Microsoft Visual FoxPro 9.0

Visual FoxPro 9.0
Microsoft Visual FoxPro 9.0

Welcome to Microsoft Visual FoxPro. Visual FoxPro is the object-oriented relational database management system that makes it possible for you to create database solutions for the desktop to the Web. Visual FoxPro provides powerful data handling capabilities, rapid application development tools for maximum productivity, and the flexibility needed to build all types of database solutions.

In the Visual FoxPro Documentation

What's New in Visual FoxPro

Describes the new features and enhancements included in this version of Visual FoxPro.
Getting Started with Visual FoxPro

Provides information about where to find the Readme file, installing and upgrading from previous versions, configuring Visual FoxPro, and customizing the development environment.
Using Visual FoxPro

Provides an overview of Visual FoxPro features, describes concepts and productivity tools for developing, programming, and managing high-performance database applications and components.
Samples and Walkthroughs

Contains Visual FoxPro code samples and step-by-step walkthroughs that you can use for experimenting with and learning Visual FoxPro features.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.
Product Support

Provides information about Microsoft product support services for Visual FoxPro.

Additional Information

Microsoft Visual FoxPro Web Site

Provides a link to the Microsoft Visual FoxPro Web site for additional information and resources for Visual FoxPro.
Microsoft Visual FoxPro Community

Provides a link to Microsoft Visual FoxPro Online Community Web site for third-party community resources and newsgroups.
Microsoft Visual FoxPro Training and Resources

Provides a link to the Visual FoxPro training Web site to find information about training, books, and events for Visual FoxPro.
Accessibility for People with Disabilities

Provides information about features that make Visual FoxPro more accessible for people with disabilities.
Send comments about this topic to Microsoft. © Microsoft Corporation. All rights reserved.


What's New in Visual FoxPro

Visual FoxPro 9.0
What's New in Visual FoxPro

This release of Visual FoxPro contains many new features and enhancements. The following sections describe these new features and enhancements.

In This Section

Guide to Reporting Improvements

A roadmap to all new Reporting enhancements.
Data Features Enhancements

Describes additions and improvements to Visual FoxPro data features.
SQL Language Improvements

Describes enhancements to SQL language such as SELECT - SQL Command.
Class Enhancements

Describes additions and improvements to Visual FoxPro classes, forms, controls and object-oriented related features.
Language Enhancements

Describes additions and improvements to the Visual FoxPro programming language.
Interactive Development Environment (IDE) Enhancements

Describes additions and improvements made to the Visual FoxPro IDE.
Enhancements to Visual FoxPro Designers

Describes improvements made to designers available in Visual FoxPro.
Miscellaneous Enhancements

Describes other improvements made in this version of Visual FoxPro.
Changes in Functionality for the Current Release

Describes changes in the behavior of existing language and functionality.
Visual FoxPro New Reserved Words

Lists new reserved words added to Visual FoxPro.
Submitting Feedback about Help to Microsoft

Describes how you can send feedback about the Visual FoxPro Help documentation to Microsoft.

Related Sections

Getting Started with Visual FoxPro

Provides information about where to find the ReadMe file and how to install and upgrade from previous versions, configure Visual FoxPro, and customize the development environment.
Using Visual FoxPro

Provides an overview of Visual FoxPro features, describes concepts and productivity tools for developing, programming, and managing high-performance database applications and components, and provides walkthroughs that help get you started. With the robust tools and data-centric object-oriented language that Visual FoxPro offers, you can build modern, scalable, multi-tier applications that integrate client/server computing and the Internet.
Samples and Walkthroughs

Contains Visual FoxPro code samples and step-by-step walkthroughs that you can use for experimenting with and learning Visual FoxPro features.
Reference

Describes Visual FoxPro general, programming language, user interface, and error message reference topics.
Product Support

Provides information about Microsoft product support services for Visual FoxPro.


Guide to Reporting Improvements

Visual FoxPro 9.0
Guide to Reporting Improvements
See Also

Visual FoxPro 9's Report System has undergone a thorough revision. This topic sketches the broad outlines of the changes, and provides you with information about where to look for details.

The following main areas of enhancements to the Report System are covered in sections of this topic.

Design-time enhancements.

Multiple features and changes make designing reports in Visual FoxPro better for you and your end-users. The Report Builder Application re-organizes your design experience out-of-the-box. If you want to customize the design process, Report Builder dialog boxes and Report Designer events are fully exposed for you to do so.
Multiple detail bands.

You can handle multiple child tables and data relationships more flexibly in the revised Report Designer. When you run multiple-detail-band reports, you can leverage the new bands, with associated detail headers and footers, both for appropriate presentation of these relationships and for more capable calculations.
Object-assisted run-time report processing.

An entirely re-built output system, including a new base class, changes the way Visual FoxPro provides output report and label files at run time. Object-assisted reporting provides better-quality output, new types of output, and an open-architecture based on a new Visual FoxPro base class, the ReportListener. A programmable Report Preview interface interacts with ReportListeners to give you full control over report preview experience. The Report Preview Application provides improved out-of-the-box previewing facilities.
Printing, rendering, and character-set-handling improvements.

Visual FoxPro 9 makes better use of the operating system's printing features and GDI+ rendering subsystem. It also handles multiple locales and character sets better than previous versions. These changes are showcased in the Report System, and are accessible for use in custom code during report design and run-time processing.
Extensible use of report and label definition files (.frx and .lbx tables).

Visual FoxPro 9 handles your existing reports and labels without modification, while allowing you to add new features and behavior to these reports easily. This backward-compatible, yet forward-thinking, migration strategy is made possible by the Report System's newly-flexible handling of the .frx and .lbx table structure.

Design-time Enhancements

Numerous changes in the Report System help you enhance the design-time experience for developers and end-users. This section directs you to information about design-time improvements.

Report Designer Event Hooks and the Report Builder Application

The Report Designer now offers Report Builder Hooks, which enable you to intercept events occurring during a report or label design session to override and extend designer activity. The default Report Builder Application replaces many of the standard reporting dialog boxes with new ones written in Visual FoxPro code. Components of the Report Builder Application are exposed as Visual FoxPro Foundation Classes for your use.

To learn about: | Read:
Report Builder Hooks | Understanding Report Builder Events
How the Report Builder Application uses Report Builder Hooks | How to: Configure the Report Builder's Event Handling
How to specify and distribute a Report Builder with your applications | _REPORTBUILDER System Variable How to: Specify and Distribute ReportBuilder.App Including Report Files for Distribution
Using Report Builder algorithms in your code | FRX Cursor Foundation Class FRX Device Helper Foundation Class

Protection for End-User Design Sessions, and other Design-time Customization Opportunities

You can allow end-users to MODIFY and CREATE reports and labels, while setting limitations on what they can do in the Report Designer interface, using the new PROTECTED keyword. Protection is available individually by object and globally for the report. You can change what end-users see on the designer layout surface, from complex expressions to simple labels or sample data, while working in PROTECTED design mode, using Design-Time Captions. You can also provide helpful instructions, for both PROTECTED and standard design mode, by specifying Tooltips for report controls.

To learn about: | Read:
Using the PROTECTED keyword | MODIFY REPORT Command MODIFY LABEL Command
Setting Protection in the Report or Label Designer, and what Protection settings do | Setting Protection for Reports
Protection settings exposed in Report or Label Dialog dialog boxes when you use the default Report Builder Application | Protection Tab, Report Control Properties Dialog Box (Report Builder) Protection Tab, Report Properties Dialog Box (Report Builder) Protection Tab, Report Band Properties Dialog Box (Report Builder)
Design-Time Captions | How to: Add Design-time Captions to Field Controls
ToolTips for Report Controls | How to: Add Tooltips to Report Controls

Enhanced Data Environment Use in Reports

You can save the Data Environment you designed for a Report or Label as a visual class. You can load a Data Environment into a Report or Label design from either a visual class or a previously-saved report or label.

To learn about: | Read:
Saving a Report Data Environment | How to: Save Report Data Environments as Classes
Loading a Report Data Environment | Data Environment Tab, Report Properties Dialog Box (Report Builder) How to: Load Data Environments for Reports

Miscellaneous Design Improvements

There have been numerous enhancements to the Report and Label Designers. Some features are subtle changes to make design sessions more efficient and more enjoyable, and others improve your choices for resulting output.

To learn about: Read:

Improvements to the Report and Label Interactive Development Environment (IDE), such as:

  • Enhanced Report Designer toolbar, and easier access to the Report Designer Toolbar from the View menu

  • New global Report Properties context menu

  • Improvements and additions to existing context menus

  • Revised and extended Report menu

Report Layout and Design

Changes to global report and label design options

Reports Tab, Options Dialog Box

Using the new PictureVal property of the Image control to specify images in reports

How to: Add Pictures to Reports

PictureVal Property

New picture template characters (U and W) and updated format instructions (Z, now supported for date and datetime data), useful in reports and labels

Format Expressions for Field Controls

InputMask Property

Format Property

Receiving improved HTML output, which leverages run-time reporting enhancements, when you choose Save As HTML… while designing a report or label

How to: Generate Output for Reports

Tip:
Other Visual FoxPro components that invoke Genhtml.prg, the default _GENHTML implementation, automatically share the improved HTML output, although these components have not changed. These include the FRX to HTML Foundation Class and the Output Object Foundation Class.

Multiple Detail Bands

The Report Engine can now move through a scope of records multiple times. The records can represent related sets of detail lines in child tables, or they can be multiple passes through a single table. These multiple passes through a scope of records are represented as multiple detail bands.

Detail bands can have their own headers and footers, their own associated onEntry and onExit code, and their own associated report variables. Each detail band can be explicitly associated with a separate target alias, allowing you to control the number of entries in each detail band separately for related tables.

Multiple detail band reports provide many new ways you can represent data in reports and labels, and new ways you can calculate or summarize data, as you move through a record scope.

To learn about: | Read:
Designing reports and labels with multiple detail bands and their associated headers and footers | Optional Bands Dialog Box Report Band Properties Dialog Box Band Tab, Report Band Properties Dialog Box (Report Builder)
Handling multiple, related tables in report and label data | Controlling Data in Reports Working with Related Tables using Multiple Detail Bands in Reports
Associating report variables with detail bands | How to: Reset Report Variables
Comparing multiple groups and multiple detail bands | Report Bands

Object-assisted Run-time Report Processing

Visual FoxPro 9 has a new, object-assisted method of generating output from reports and labels. You can use your existing report and label layouts in object-assisted mode, to:

  • Generate multiple types of output during one report run.

  • Connect multiple reports together as part of one output result.

  • Improve the quality of traditional report output.

  • Dynamically adjust the contents of a report while you process it.

  • Provide new types of output not available from earlier versions of Visual FoxPro.

This section covers the array of run-time enhancements that work together to support object-assisted reporting mode.

Object-Assisted Architecture and ReportListener Base Class

The new ReportListener base class and supporting language enhancements are the heart of run-time reporting enhancements.

To learn about: | Read:
Fundamentals of the architecture, how its components work together, and what happens during an object-assisted report run | Understanding Visual FoxPro Object-Assisted Reporting
The ReportListener base class and its members | ReportListener Object ReportListener Object Properties, Methods, and Events
Invoking object-assisted reporting mode automatically | SET REPORTBEHAVIOR Command _REPORTOUTPUT System Variable Reports Tab, Options Dialog Box
Invoking object-assisted reporting mode explicitly with Visual FoxPro commands | REPORT FORM Command LABEL Command
Debugging and error-handling object-assisted report runs | Handling Errors During Report Runs

Report Preview API and the Report Preview Application

Visual FoxPro 9's object-assisted reporting mode gives you complete control over report and label previews.

To learn about: | Read:
How object-assisted preview works | The Preview Container API Creating a Custom Preview Container
The default Report Preview Application | Leveraging the Default Preview Container
How to specify and distribute Report Preview components with your applications | _REPORTPREVIEW System Variable How to: Specify and Distribute ReportPreview.App Including Report Files for Distribution

New Types of Output and the Report Output Component Set

Because you can subclass ReportListener, you can create new types of output. Visual FoxPro 9 supplies a Report Output Application to connect ReportListener subclasses with output types, as well as ReportListener-derived classes with enhanced output capabilities.

To learn about: | Read:
Requirements for Report Output Application, and how Visual FoxPro uses Report Output Applications | _REPORTOUTPUT System Variable
Features of the default Report Output Application | Understanding the Report Output Application
Specifying custom output handlers using the default Report Output Application | How to: Specify an Alternate Report Output Registry Table How to: Register Custom ReportListeners and Custom OutputTypes in the Report Output Registry Table Considerations for Creating New Report Output Types
Understanding and configuring the Visual FoxPro Foundation Classes providing default ReportListener behavior for object-assisted preview and printing | ReportListener User Feedback Foundation Class
Understanding and configuring the Visual FoxPro Foundation Classes responsible for default XML and HTML output | ReportListener XML Foundation Class ReportListener HTML Foundation Class
Leveraging the full set of supported Report Output Foundation Classes and VFP Report Output XML format | ReportListener Foundation Classes Using VFP Report Output XML
How to specify and distribute Report Output components with your applications | How to: Specify and Distribute Report Output Application Components Including Report Files for Distribution

Migration Strategies and Changes in Output Rendering

You can use the design-time changes to improve all reports and labels, whether you choose backward-compatible or object-assisted reporting mode at run time.

When evaluating whether to switch to object-assisted reporting mode at run time, first consider items on the Reporting list of Important Changes in the Changes in Functionality for the Current Release topic, some of which are specific to this new method of creating output. .The topic includes a table of minor differences between backward-compatible and object-assisted reporting output. You can examine what effects these changes might have on individual existing reports, and use the recommendations in the table to address them. You will find additional details in the topic Using GDI+ in Reports.

Once you have experimented with your current reports, you can decide on a migration strategy for output:

  • You can switch applications over to use object-assisted reporting mode completely, by using the command SET REPORTBEHAVIOR 90.

  • You can use SET REPORTBEHAVIOR 90 but preface specific REPORT FORM commands for reports with formatting issues with SET REPORTBEHAVIOR 80, returning your application to object-assisted mode afterwards.

  • You can use object-assisted mode all the time, but adjust your ReportListener-derived classes' behavior to suit specific needs. For example, you could change the default setting of the ReportListener's DynamicLineHeight Property to False (.F.).

  • You can leave SET REPORTBEHAVIOR at its default setting of 80, and add an explicit OBJECT clause to specific reports at your leisure, as you have the opportunity to evaluate and adjust individual report and label layouts.

Printing, Rendering, and Character-set-handling Improvements

General changes to Visual FoxPro's use of Windows' printing, rendering and font-handling support the improvements in the Report System's output. These changes enhance your ability to support multiple printers and multiple languages in reports.

To learn about: | Read:
GDI+ features and their impact on native Visual FoxPro output | Using GDI+ in Reports
Visual FoxPro reporting enhancements that allow your code to use GDI+ in object-assisted reporting mode, and Visual FoxPro Foundation Classes to get you started | GDIPlusGraphics Property Render Method GDI Plus API Wrapper Foundation Classes
Making full use of multiple character sets, or language scripts, in reports, for single report layout elements, for report defaults, or globally in Visual FoxPro | GETFONT( ) Function Style Tab, Report Control Properties Dialog Box (Report Builder) How to: Change Page Settings for Reports Reports Tab, Options Dialog Box Reporting Features for International Applications
Changes to page setup dialog boxes in Visual FoxPro, improvements in your programmatic access to them, and providing overrides to Printer Environment settings in report and label files | SYS(1037) - Page Setup Dialog Box
Receiving improved information about the user's installed printers | APRINTERS( ) Function
Limiting a list of fonts to those appropriate for printer user | GETFONT( ) Function

Extensible Use of Report and Label Definition Files

Underneath all the changes to the Visual FoxPro Report System, the Report Designer and Report Engine handle your report and label definitions using the same .frx and .lbx file structures as they did in previous versions. They change the way they use certain fields, without making these reports and labels invalid in previous versions, and they also allow you to extend your use of existing fields or add custom fields.

Tip:
This change is critical to your ability to create extensions of the new reporting features. For example, you might store two sets of ToolTips in two report extension fields, one set for use by developers and one for use by end-users. In a Report Builder extension, you could evaluate whether the Designer was working in protected or standard mode, and replace the actual set of ToolTips from the appropriate extension field. In previous versions, you could not add fields to report or label structure; the Designer and Engine would consider the table invalid. You also could not add custom content to unused, standard fields in various report and label records safely, because the Report Designer removed such content.

Visual FoxPro 9 provides a revised FILESPEC table for report and label files, with extensive information on the use of each column in earlier versions as well as current enhancements.

Visual FoxPro 9 also establishes a new, structured metadata format for use with reports. This format is an XML document schema shared with the Class Designer's XML MemberData.

The XML document format allows you to pack custom reporting information into a single report or label field. The default Report Builder Application makes it easy to add Report XML MemberData to report and label records.

To learn about: | Read:
How Visual FoxPro uses .frx and .lbx tables, and how to extend these structures | Understanding and Extending Report Structure
How to find and display the contents of the revised FILESPEC table, 60FRX.dbf | Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
How you can edit the XML data using the Report Builder Application | How to: Assign Structured Metadata to Report Controls
How you can use Report XML MemberData | Report XML MemberData Extensions
The shared MemberData document schema | MemberData Extensibility

See Also

Reference

Data and XML Feature Enhancements
SQL Language Improvements
Class Enhancements
Language Enhancements
Enhancements to Visual FoxPro Designers

Other Resources

What's New in Visual FoxPro
Interactive Development Environment (IDE) Enhancements
Miscellaneous Enhancements
Changes in Functionality for the Current Release


Data and XML Feature Enhancements

Visual FoxPro 9.0
Data and XML Feature Enhancements
See Also

Visual FoxPro contains the following additions and improvements to its data features:

Extended SQL Capabilities

Visual FoxPro contains many enhancements for SQL capabilities. For more information, see SQL Language Improvements.

New Data Types

Visual FoxPro includes the following new field and data types:

  • Varchar

    To store alphanumeric text without including padding by additional spaces at the end of the field or truncating trailing spaces, use the new Varchar field type.

    If you do not want Varchar fields translated across code pages, use the Varchar (Binary) field type. For more information, see Varchar Field Type.

    You can specify Varchar type mapping between ODBC, ADO, and XML data source types and CursorAdapter and XMLAdapter objects using the MapVarchar Property. You can also specify Varchar mapping for SQL pass-through technology and remote views using the MapVarchar setting in the CURSORSETPROP( ) function. For more information, see CURSORSETPROP( ) Function and CURSORGETPROP( ) Function.

  • Varbinary

    To store binary values and literals of fixed length in fields and variables without padding the field with additional zero (0) bytes or truncating any trailing zero bytes that are entered by the user, use the Varbinary data type. Internally, Visual FoxPro binary literals contain a prefix, 0h, followed by a string of hexadecimal numbers and are not enclosed with quotation marks (""), unlike character strings. For more information, see Varbinary Data Type.

    You can specify binary type mapping between ODBC, ADO, and XML data source types and CursorAdapter and XMLAdapter objects using the MapBinary Property. You can also specify binary mapping for SQL pass-through technology and remote views using the MapBinary setting in the CURSORSETPROP( ) function. For more information, see CURSORSETPROP( ) Function and CURSORGETPROP( ) Function.

  • Blob

    To store binary data with indeterminate length, use the Blob data type. For more information, see Blob Data Type.

Many of the Visual FoxPro language elements affected by these new data types are listed in the topics for the new data types.

Binary Index Tag Based on Logical Expressions

Visual FoxPro includes a new binary, or bitmap, index for creating indexes based on logical expressions, for example, indexes based on deleted records. A binary index can be significantly smaller than a non-binary index and can improve the speed of maintaining indexes. You can create binary indexes using the Table Designer or INDEX command. Visual FoxPro also includes Rushmore optimization enhancements in the SQL engine for deleted records.

For more information, see Visual FoxPro Index Types, INDEX Command, ALTER TABLE - SQL Command, and Indexes Based on Deleted Records.

Converting Data Types with the CAST( ) Function

You can convert expressions from one data type to another by using the new CAST( ) function. Using CAST( ) makes it possible for you to create SQL statements more compatible with SQL Server.

For more information, see CAST( ) Function.

Get Cursor and Count Records Affected by SQL Pass-Thru Execution

By using the aCountInfo parameter of the SQLEXEC( ) and SQLMORERESULTS( ) functions, you can get the name of the cursor created and a count of the records affected by the execution of a SQL pass-through statement.

For more information, see SQLEXEC( ) Function) and SQLMORERESULTS( ) Function.

Roll-Back Functionality Supported when a SQL Pass-Through Connection Disconnects

Visual FoxPro now supports the DisconnectRollback property for use with the SQLSETPROP( ), SQLGETPROP( ), DBSETPROP( ), and DBGETPROP( ) functions. DisconnectRollback is a connection-level property that causes a transaction to be either rolled back or committed when the SQLDISCONNECT( ) function is called for the last connection handle associated with the connection.

The DisconnectRollback property accepts a logical value.

  • False (.F.) - (Default) The transaction will be committed when the SQLDISCONNECT( ) function is called for the last statement handle associated with the connection.

  • True (.T.) - The transaction is rolled back when the SQLDISCONNECT( ) function is called for the last statement handle associated with the connection.

The following example shows the DisconnectRollback property set in the DBSETPROP( ) and SQLSETPROP( ) functions.

Copy Code
DBSETPROP("testConnection","CONNECTION","DisconnectRollback",.T.)
SQLSETPROP(con,"DisconnectRollback",.T.)

For more information, see DisconnectRollback property in SQLSETPROP( ) Function.

SQLIDLEDISCONNECT( ) Temporarily Disconnects SQL Pass-Through Connections

You can use the new SQLIDLEDISCONNECT( ) function to allow a SQL Pass-Through connection to be temporarily disconnected. Use the following syntax.

Copy Code
SQLIDLEDISCONNECT( nStatementHandle )

The nStatementHandle parameter is set to the statement handle to be disconnected or 0 if all statement handles should be disconnected.

The SQLIDLEDISCONNECT( ) function returns the value 1 if it is successful; otherwise, it returns -1.

The function fails if the specified statement handle is busy or the connection is in manual commit mode. The AERROR( ) function can be used to obtain error information.

The disconnected connection handle is automatically restored if it is needed for an operation. The original connection data source name is used.

If a statement handle is temporarily released, the OBDChstmt property returns 0; the OBDChdbc returns 0 if the connection is temporarily disconnected. A shared connection is temporarily disconnected as soon as all of its statement handles are temporarily released.

For more information, see SQLIDLEDISCONNECT( ) Function.

Retrieving Active SQL Connection Statement Handles

You can retrieve information for all active SQL connection statement handles using the new ASQLHANDLES( ) function. ASQLHANDLES( ) creates and uses the specified array to store numeric statement handle references that you can use in other Visual FoxPro SQL functions, such as SQLEXEC( ) and SQLDISCONNECT( ). ASQLHANDLES( ) returns the number of active statement handles in use or zero (0) if none are available. For more information, see ASQLHANDLES( ) Function.

Obtain the ADO Bookmark for the Current Record in an ADO-Based Cursor

The ADOBookmark property is now supported by the CURSORGETPROP( ) function. Use this property to obtain the ActiveX® Data Objects (ADO) bookmark for the current record in an ADO-based cursor.

For more information, see ADOBookmark Property in CURSORGETPROP( ) Function.

If a table is not selected and an alias is not specified, Error 52, "No table is open in the current work area," is generated. If the cursor selected is not valid, Error 1467, "Property is invalid for local cursors," is generated.

Obtain the Number of Fetched Records

You can obtain the number of fetched records during SQL Pass-Through execution by using the new RecordsFetched cursor property with the CURSORGETPROP( ) function.

Specifying the RecordsFetched cursor property will return the number of fetched records from an OBDC/ADO-based cursor.

If records have been deleted or appended locally, the RecordsFetched cursor property may not return the current number of records in the OBDC/ADO-based cursor. In addition, filter conditions are ignored.

For more information, see RecordsFetched Property in CURSORGETPROP( ) Function.

Determine if a Fetch is Complete

You can determine if a fetch process is complete for an OBDC/ADO-based cursor by using the new FetchIsComplete cursor property with the CURSORGETPROP( ) function. Read-only at design time and run time.

This property is not supported on environment level (work area 0) cursors, tables, and local views.

The FetchIsComplete cursor property returns a logical expression True (.T.) if the fetch process is complete; otherwise False (.F.) is returned.

For more information, see FetchIsComplete Property in CURSORGETPROP( ) Function.

ISMEMOFETCHED( ) Determines Whether a Memo is Fetched

You can use the ISMEMOFETCHED( ) function to determine whether a Memo field or General field is fetched when you are using delayed memo fetching. For more information about delayed memo fetching, see Speeding Up Data Retrieval.

The syntax for this function is:

ISMEMOFETCHED(cFieldName | nFieldNumber [, nWorkArea | cTableAlias ])

The ISMEMOFETCHED( ) function returns True (.T.) when the Memo field is fetched or if local data is used. ISMEMOFETCHED() returns NULL if the record pointer is positioned at the beginning of the cursor or past the last record.

For more information, see ISMEMOFETCHED( ) Function.

Cancel ADO Fetch

In Visual FoxPro, you can now cancel a lengthy ADO fetch by pressing the ESC key.

Long Type Name Support

Visual FoxPro supports using long type names with the following functions, commands, and properties.

  • CAST( ) Function

  • ALTER TABLE - SQL Command

  • CREATE CURSOR - SQL Command

  • CREATE TABLE - SQL Command

  • CREATE FROM Command

  • CursorSchema Property

  • DataType Property

The following table lists the data types along with their long type names and short type names.

Data Type | Long Type Name | Short Type Name
Character | Char, Character | C
Date | Date | D
DateTime | Datetime | T
Numeric | Num, Numeric | N
Floating | Float | F
Integer | Int, Integer | I
Double | Double | B
Currency | Currency | Y
Logical | Logical | L
Memo | Memo | M
General | General | G
Picture | Picture | P
Varchar | Varchar | V
Varbinary | Varbinary | Q
Blob | Blob | W

Visual FoxPro allows ambiguous long type names to be used with the ALTER TABLE, CREATE CURSOR, CREATE TABLE, and CREATE FROM commands. If the specified long type name is not a recognized long type name, Visual FoxPro will truncate the specified name to the first character.

Transaction Support for Free Tables and Cursors

In prior versions of Visual FoxPro, transactions using the BEGIN TRANSACTION Command were only supported for local and remote data from databases. Transactions involving free tables and cursors are now supported through use of the MAKETRANSACTABLE( ) and ISTRANSACTABLE( ) functions. For more information, see MAKETRANSACTABLE( ) Function and ISTRANSACTABLE( ) Function.

Specify a Code Page When Using the CREATE TABLE or CREATE CURSOR Commands

You can specify a code page by including the CODEPAGE clause with the CREATE CURSOR or CREATE TABLE commands.

When the CODEPAGE clause is specified, the new table or cursor has a code page specified by nCodePage. An error, 1914, "Code page number is invalid", is generated if an invalid code page is specified.

The following example creates a table and displays its code page:

Copy Code
CREATE TABLE Sales CODEPAGE=1251 (OrderID I, CustID I, OrderAmt Y(4))

? CPDBF( )

For more information, see CREATE CURSOR - SQL Command, CREATE TABLE - SQL Command and Code Pages Supported by Visual FoxPro.

Convert Character and Memo Data Types Using the ALTER TABLE Command

Visual FoxPro now supports automatic conversion from character data type to memo data type without loss of data when using the ALTER TABLE command along with the ALTER COLUMN clause. This conversion is also supported when making structural changes using the Table Designer. For more information, see ALTER TABLE - SQL Command.

BLANK Command Can Initialize Records to Default Value

You can initialize fields in the current record to their default values as stored in the table's database container (DBC) by using the DEFAULT [AUTOINC] option when clearing the record with the BLANK command. For more information, see BLANK Command.

FLUSH Command Writes Data Explicitly to Disk

Visual FoxPro now includes options and parameters for the FLUSH command and FFLUSH function so you can explicitly save all changes you make to all open tables and indexes. You can also save changes to a specific table by specifying a work area, table alias, or a path and file name. For more information, see FLUSH Command and FFLUSH( ) Function.

Populate an Array with Aliases Used by a Specified Table

The new cTableName parameter for the AUSED( ) function makes it possible to filter the created array to contain only the aliases being used for a specified table.

AUSED(ArrayName [, nDataSessionNumber [, cTableName ]])

The cTableName parameter accepts the following formats to specify a table, from highest to lowest in priority.

  • DatabaseName!TableName or DatabaseName!ViewName

  • Path\DatabaseName!TableName or Path\DatabaseName!ViewName

  • DBC-defined table name or view in the current DBC in the current data session

  • Simple or full file name

For more information, see AUSED( ) Function.

Obtain Last Auto-Increment Value with GETAUTOINCVALUE( )

You can use the new GETAUTOINCVALUE( ) function to return the last value generated for an autoincremented field within a data session. For more information, see GETAUTOINCVALUE( ) Function.

SET TABLEPROMPT Controls Prompt to Select Table

The new SET TABLEPROMPT command controls whether Visual FoxPro prompts the user with the Open Dialog Box (Visual FoxPro) to select a table when one specified cannot be found, such as in SELECT - SQL Command. For more information, see SET TABLEPROMPT Command.

Use SET VARCHARMAPPING to Control Query Result Set Mappings

For queries such as SELECT - SQL Command, character data is often manipulated using Visual FoxPro functions and expressions. Since the length of the resulting field value may be important for certain application uses, it is valuable to have this Character data mapped to Varchar data in the result set. The SET VARCHARMAPPING command controls whether Character data is mapped to a Character or Varchar data type. For more information, see SET VARCHARMAPPING Command.

SET TABLEVALIDATE Expanded

When a table header is locked during validation, attempts to open the table, for example, with the USE command, generate the message "File is in use (Error 3)." If the table header cannot be locked for a table open operation, you can suppress this message by setting the third bit for the SET TABLEVALIDATE command. You must also set the first bit to validate the record count when the table opens. Therefore, you need to set the SET TABLEVALIDATE command to a value of 5. Also, a fourth bit option (value of 8) is available for Insert operations which checks the table header before the appended record is saved to disk and the table header is modified.

For more information, see SET TABLEVALIDATE Command.

SET REFRESH Can Specify Faster Refresh Rates

You can specify fractions of a second for the nSeconds2 parameter to a minimum of 0.001 seconds. You can also specify the following values for the optional second parameter:

  • -1 - Always read data from a disk.

  • 0 - Always use data in memory buffer but do not refresh buffer.

The Table refresh interval check box on the Data tab of the Options dialog box now also accepts fractional values.

For more information, see SET REFRESH Command and Data Tab, Options Dialog Box.

SET REFRESH Can Differentiate Values for Each Cursor

You can use the new Refresh property with the CURSORGETPROP( ) function to differentiate the SET REFRESH values for individual cursors. The default setting is -2, which is a global value. This value is not available with the SET REFRESH command.

The Refresh property is available at the Data Session and Cursor level. The default setting for a Data Session level is -2 and the default value for a Cursor level is the current session's level setting. If the global level setting is set to 0, the Cursor level setting is ignored.

If a table is not currently selected and an alias is not specified, Error 52, "No table is open in the current work area," is generated.

For more information, see Refresh Property in CURSORGETPROP( ) Function.

SET( ) Determines SET REPROCESS Command Settings

You can now use the following syntax with the SET( ) function to determine how the SET REPROCESS command was declared.

SET Command | Value Returned
REPROCESS, 2 | Current session setting type (0 - attempts, 1 - seconds)
REPROCESS, 3 | System session setting type (0 - attempts, 1 - seconds)

For more information, see SET( ) Function and SET REPROCESS Command.

Log Output from SYS(3054) Using SYS(3092)

You can use the new SYS(3092) function in conjunction with SYS(3054) to record the resulting output to a file.

SYS( 3092 [, cFileName [, lAdditive ]])

The cFileName parameter specifies the file to echo the SYS(3054) output to. Sending an empty string to cFileName will deactivate output recording to the file.

The default value for lAdditive is False (.F.). This specifies that new output will overwrite the previous contents of the specified file. To append new output to the specified file, set lAdditive to True (.T.).

SYS(3092) returns the name of the current echo file if it is active; otherwise, it returns an empty string.

SYS(3054) and SYS(3092) are global settings — in a multithreaded runtime they are scoped to a thread. Each function can be changed independently from each other.

These functions are not available in the Visual FoxPro OLE DB Provider.

For more information, see SYS(3054) - Rushmore Query Optimization Level and SYS(3092) - Output Rushmore Query Optimization Level.

Purge Cached Memory for Specific Work Area Using SYS(1104)

You can optionally specify the alias or work area of a specified table or cursor for which cached memory is purged. For more information, see SYS(1104) - Purge Memory Cache.

New Table Types for SYS(2029)

The SYS(2029) function returns new values for tables that contain Autoinc, Varchar, Varbinary or Blob fields. For more information, see SYS(2029) - Table Type.

Map Remote Unicode Data to ANSI Using SYS(987)

Use SYS(987) to map remote Unicode data retrieved through SQL pass-through or remote views to ANSI. This function can be used to retrieve remote Varchar data as ANSI for use with Memo fields. This setting is a global setting across all data sessions so should be used with care. For more information, see SYS(987) - Map Remote Data to ANSI.

Memo and Field tips in a BROWSE or Grid

When the mouse pointer is positioned over a Memo field cell in a Browse window or Grid control, a Memo Tip window displays the contents of the Memo field.

For other field types, positioning the mouse pointer over the field displays the field contents in a Field Tip window when the field is sized smaller than its contents.

Memo Tip windows display no more than 4 kilobytes of text, and are not displayed for binary data. A Memo Tip window is displayed until the mouse pointer is moved from the Memo field. The _TOOLTIPTIMEOUT System Variable determines how long a Field Tip window is displayed.

You can disable Memo Tips by setting the _SCREEN ShowTips Property to False (.F.).

Memo and Field Tips will also be displayed for Grid controls if both _SCREEN and the form's ShowTips property are set to True (.T.). Additionally, the ToolTipText Property for the field's grid column Textbox control must contain an empty string.

Specify Code Pages

You can specify the code page used to decode data when XML is being parsed and to encode data when UTF-8 encoded XML is generated. The following language changes are available:

  • nCodePage Parameter

    To specify code pages, you can use the nCodePage parameter for the following XMLToTable methods:

    • ToCursor Method

    • ChangesToCursor Method

    • ApplyDiffgram Method

    Copy Code
    XMLTable.ToCursor ( [ lAppend [, cAlias [, nCodePage ]]] )
XMLTable.ChangesToCursor( [ cAlias [, lIncludeUnchangedData [, nCodePage ]]] )
XMLTable.ApplyDiffgram( [ cAlias [, oCursorAdapter [, lPreserveChanges [, nCodePage ]]]] )
  • CodePage and UseCodePage Properties

    Use the CodePage Property and UseCodePage Property to specify code pages when you use the following classes:

    • XMLAdapter Class

    • XMLTable Class

    • XMLField Class

    Copy Code
    XMLAdapter.CodePage = nValue
XMLTable.CodePage = nValue
XMLField.CodePage = nValue
  • Flag 32768

    The flag 32768 is available for the following functions and class:

    • CursorAdapter Class

    • XMLTOCURSOR( ) Function

    • CURSORTOXML( ) Function

    • XMLUPDATEGRAM( ) Function

    Copy Code
    CursorAdaptor.Flags = nCodePage
XMLTOCURSOR( eExpression | cXMLFile [, cCursorName [, nFlags ]])
CURSORTOXML(nWorkArea | cTableAlias, cOutput [, nOutputFormat [, nFlags [, nRecords [, cSchemaName [, cSchemaLocation [, cNameSpace ]]]]]])
XMLUPDATEGRAM( [ cAliasList [, nFlags [, cSchemaLocation]]])
    The nCodePage parameter must match a recognized Visual FoxPro code page.

For more information, see Code Pages Supported by Visual FoxPro.

MapVarchar Property Maps to Varchar, Varbinary, and Blob Data Types

For CursorAdapter and XMLAdapter classes, you can use the MapVarchar property to map to Varchar data types. To map to Varbinary and Blob data types, you can use the MapBinary property.

The XMLTOCURSOR( ) Function contains several new flags to support mapping of Char and base64Binary XML field types to new Fox data types.

For more information, see the MapVarchar Property and MapBinary Property.

Handling Conflict Checks with Properties for CursorAdapter Class

You can better handle conflicts when performing update and delete operations using the commands specified by the UpdateCmd and DeleteCmd properties for CursorAdapter objects by using the new ConflictCheckType and ConflictCheckCmd properties for CursorAdapter objects.

You can use ConflictCheckType to specify how to handle a conflict check during an update or delete operation. When ConflictCheckType is set to 4, you can use ConflictCheckCmd to specify a custom command to append to the end of the commands in the UpdateCmd and DeleteCmd properties.

Note:
Visual FoxPro 8.0 Service Pack 1 includes the ConflictCheckType and ConflictCheckCmd properties.

For more information, see ConflictCheckType Property and ConflictCheckCmd Property.

Improved DataEnvironment Handling with UseCursorSchema and NoData Properties

You can specify default settings for CursorFill Method calls made without the first two parameters by setting these properties. For more information, see UseCursorSchema Property and NoData Property.

Timestamp Field Support

The new TimestampFieldList property lets you specify a list of timestamp fields for the cursor created by the CursorAdapter. For more information see TimestampFieldList Property.

Auto-Refresh Support

There are a number of scenarios where you might want to have cursor data refreshed from a remote data source after an Insert/Update operation has occurred. These include following scenarios:

  • A table has an auto-increment field that also acts as a primary key.

  • A table has a timestamp field, and that field must be refreshed from the database after each Insert/Update in order to allow successful subsequent updates to the record when WhereType=4 (key and timestamp).

  • A table contains some fields which have DEFAULT values or triggers defined that will cause changes to occur.

The following new properties have been added to the CursorAdapter class for Auto-Refresh support:

Property | Description
InsertCmdRefreshFieldList | List of fields to refresh after Insert command executes.
InsertCmdRefreshCmd | Specifies the command to refresh the record after Insert command executes.
InsertCmdRefreshKeyFieldList | List of key fields to refresh in record after Insert command executes.
UpdateCmdRefreshFieldList | List of fields to refresh after Update command executes.
UpdateCmdRefreshCmd | Specifies the command to refresh the record after Update command executes.
UpdateCmdRefreshKeyFieldList | List of key fields to refresh the record after Update command executes.
RefreshTimestamp | Enables automatic refresh for fields in TimestampFieldList during Insert/Update.

For more information about how Visual FoxPro updates remote data using a CursorAdapter, see Data Access Management Using CursorAdapters. Also, see InsertCmdRefreshCmd Property, InsertCmdRefreshFieldList Property, InsertCmdRefreshKeyFieldList Property, UpdateCmdRefreshCmd Property, UpdateCmdRefreshFieldList Property, UpdateCmdRefreshKeyFieldList Property and RefreshTimeStamp Property.

On Demand Record Refresh

In Visual FoxPro 8.0, the REFRESH( ) Function provides on demand record refresh functionality for local and remote views, however, it does not support this for the CursorAdapter. Visual FoxPro 9.0 extends REFRESH( ) support to the CursorAdapter and provides some additional capabilities:

Member | Description
RecordRefresh method | Refreshes the current field values for the target records. Use the CURVAL( ) Function to determine current field values.
BeforeRecordRefresh event | Occurs immediately before the RecordRefresh method is executed.
AfterRecordRefresh event | Occurs after the RecordRefresh method is executed.
RefreshCmdDataSourceType property | Specifies the data source type to be used for the RecordRefresh method.
RefreshCmdDataSource property | Specifies the data source to be used for the RecordRefresh method.
RefreshIgnoreFieldList property | List of fields to ignore during RecordRefresh operation
RefreshCmd property | Specifies the command to refresh rows when RecordRefresh is executed.
RefreshAlias property | Specifies the alias of read-only cursor used as a target for the refresh operation.

For more information, see RecordRefresh Method, BeforeRecordRefresh Event, AfterRecordRefresh Event, RefreshCmdDataSourceType Property, RefreshCmdDataSource Property, RefreshIgnoreFieldList Property, RefreshCmd Property and RefreshAlias Property.

Delayed Memo Fetch

The CursorAdapter class has a FetchMemo Property, which when set to False (.F.) in Visual FoxPro 9.0 places the cursor in Delayed Memo Fetch mode similar to Remote Views. Delayed Memo Fetch Mode prevents the contents of Memo fields from being fetched using CursorFill Method or CursorRefresh Method. An attempt to fetch content for a Memo field is done when the application attempts to access the value. The following CursorAdapter enhancements provide support for Delayed Memo Fetch:

Member | Description
DelayedMemoFetch method | Performs a delayed Memo field fetch for a target record in a cursor in a CursorAdapter object.
FetchMemoDataSourceType property | Specifies the data source type used for the DelayedMemoFetch method.
FetchMemoDataSource property | Specifies the data source used for the DelayedMemoFetch method.
FetchMemoCmdList property | Specifies a list of Memo field names and their associated fetch commands.

For more information, see DelayedMemoFetch Method, FetchMemoDataSourceType Property, FetchMemoDataSource Property and FetchMemoCmdList Property.

UseTransactions Property

The new UseTransactions property specifies whether the CursorAdapter should use transactions when sending Insert, Update or Delete commands through ADO or ODBC. For more information, see UseTransactions Property.

DEFAULT and CHECK Constraints Respected

In Visual FoxPro 9.0, DEFAULT values and table and field level CHECK constraints are supported for XML, Native, ADO and ODBC data sources. In Visual FoxPro 8.0, DEFAULT values and table and field level CHECK constraints are only supported for an XML data source. For the DEFAULT values and CHECK constraints to be applied to a cursor, call the CursorFill Method with the lUseSchema parameter set to True (.T.). For more information, see CursorSchema Property.

Remote Data Type Conversion for Logical Data

When you move data between a remote server and Visual FoxPro, Visual FoxPro uses ODBC or ADO data types to map remote data types to local Visual FoxPro data types. In Visual FoxPro 9.0, certain ODBC and ADO data types can now be mapped to a logical data type in remote views and the CursorAdapter object. For more information, see Data Type Conversion Control.

ADOCodePage Property

When working with an ADO data source for your CursorAdapter, you may want to specify a code page to use for character data translation. The new ADOCodePage property allows you to specify this code page. For more information, see ADOCodePage Property.

Read and Write Nested XML Documents

You can read to and write from your relational database into XML documents using nesting to handle the relationships between tables. You accomplish this using the RespectNesting Property of the XMLAdapter class. The XMLTable class has the Nest Method, Unnest Method and the following properties to handle nesting.

  • FirstNestedTable Property

  • NestedInto Property

  • NextSiblingTable Property

For more information, see the XMLAdapter Class and the XMLTable Class.

LoadXML Method Can Accept Any XML Document

The LoadXML method accepts any XML document with a valid schema. Previously, the method required that the schema follow the format of a Visual Studio generated dataset. When you use the LoadXML method to read an XML document with a schema different from a Visual Studio generated dataset, the properties for the XMLAdapter, XMLName, and XMLPrefix properties are set to empty (""). The XMLAdapterXMLNamespace property becomes equal to the target Namespace attribute value for the schema node and each XML element becomes a complexType and is mapped to an XMLTable object. The XMLNamespace property is set to namespaceURI for the element.

If you set the XMLAdapterRespectNesting property to True (.T.), the top level element declaration is ignored if it is referenced from some other complex element. For that case, the XMLTable object for the referenced element is nested into the XMLTable for the element that references it.

For more information, see LoadXML Method.

XPath Expressions Can Access Complex XML Documents

You can use XPath expressions to access complex XML documents and the new properties for reading the nodes within the document. For example, you might want to filter record nodes, restore relationships based on foreign key fields, use an element's text as data for a field, or access XML that uses multiple XML namespaces. The following properties provide you with the ability to read the XML at the XMLAdapter level, XMLTable level, or the XMLField level.

  • DeclareXMLPrefix Property

  • SelectionNamespaces Property

  • XMLNameIsXPath Property

You can use the following table to determine the node within the XML document that you want to start reading.

For example, if you use an XPath expression in the XMLName property for an XMLAdapter, reading begins at the first node

To read | Class | Context node
From the first found XML node: | XMLAdapter | IXMLDOMElement property
All found XML nodes and use each node as a single record: | XMLTable | XMLAdapter object
The first found XML node and use its text as a field value: | XMLField | XMLTable object

The following methods do not support the use of XPath expressions in the XMLName property:

  • The ApplyDiffgram and ChangesToCursor methods do not support XPath expressions for XMLAdapter and XMLTable objects.

  • The ToCursor method does not support an XPath expression for XMLAdapter when the IsDiffgram property is set to True (.T.).

  • The ToXML method does not support XPath expressions for XMLAdapter and XMLTable objects and ignores XMLField objects that use XPath expressions.

For more information about XPath expressions, see the XPath Reference in the Microsoft Core XML Services (MSXML) 4.0 SDK in the MSDN library at http://msdn.microsoft.com/library.

Cursor to XML Functions

Support for the following functions has been added to the OLE DB Provider for Visual FoxPro:

  • CURSORTOXML( ) Function

  • XMLTOCURSOR( ) Function

  • XMLUPDATEGRAM( ) Function

When used in the OLE DB Provider for Visual FoxPro, the _VFP VFPXMLProg property is not supported for the CURSORTOXML( ), XMLTOCURSOR( ) and XMLUPDATEGRAM( ) functions because the _VFP system variable is not supported in the OLE DB Provider.

EXECSCRIPT Supported in the Visual FoxPro OLE DB Provider

You can use the EXECSCRIPT( ) function with the Visual FoxPro OLE DB Provider. For more information, see EXECSCRIPT( ) Function.

Returning a Rowset from a Cursor in the Visual FoxPro OLE DB Provider

You can use the new SETRESULTSET( ), GETRESULTSET( ), and CLEARRESULTSET( ) functions to mark a cursor or table that has been opened by the Visual FoxPro OLE DB Provider, retrieve the work area of the marked cursor, and clear the marker flag from a marked cursor. By marking a cursor or table, you can retrieve a rowset that is created from the marked cursor or table from a database container (DBC) stored procedure when the OLE DB Provider completes command execution.

For more information, see SETRESULTSET( ) Function, GETRESULTSET( ) Function, and CLEARRESULTSET( ) Function.

See Also

Reference

Guide to Reporting Improvements
SQL Language Improvements
Class Enhancements
Language Enhancements
Enhancements to Visual FoxPro Designers

Other Resources

What's New in Visual FoxPro
Interactive Development Environment (IDE) Enhancements
Miscellaneous Enhancements
Changes in Functionality for the Current Release


SQL Language Improvements

Visual FoxPro 9.0
SQL Language Improvements
See Also

The SELECT - SQL command and other SQL commands have been substantially enhanced in Visual FoxPro 9.0. This topic describes the enhancements made to these commands, and new commands that affect SQL performance.

Expanded Capacities

Several SELECT - SQL command limitations have been removed or increased in Visual FoxPro 9.0. The following table lists the areas where limitations have been removed or increased.

Capacity | Description
Number of Joins and Subqueries in a SELECT - SQL command | Visual FoxPro 9.0 removes the limit on the total number of join clauses and subqueries in a SELECT - SQL command. The previous limit was nine.
Number of UNION clauses in a SELECT - SQL command | Visual FoxPro 9.0 removes the limit on number of UNION clauses in a SQL SELECT statement. The previous limit was nine.
Number of tables referenced a SELECT - SQL command | Visual FoxPro 9.0 removes the limit on the number of tables and aliases referenced in a SQL SELECT statement. The previous limit was 30.
Number of arguments in an IN( ) clause | Visual FoxPro 9.0 removes the limit of 24 values in the IN (Value_Set) clause for the WHERE clause. However, the number of values remains subject to the setting of SYS(3055) – FOR and WHERE Clause Complexity. For functionality changes concerning the IN clause, see Changes in Functionality for the Current Release.

Subquery Enhancements

Visual FoxPro 9.0 provides more flexibility in subqueries. For example, multiple subqueries are now supported. The following describes the enhancements to subqueries in Visual FoxPro 9.0.

Multiple Subqueries

Visual FoxPro 9.0 supports multiple subquery nesting, with correlation allowed to the immediate parent. There is no limit to the nesting depth. In Visual FoxPro 8.0, error 1842 (SQL: Subquery nesting is too deep) was generated when more than one level of subquery nesting occurred.

The following is the general syntax for multiple subqueries.

SELECT … WHERE … (SELECT … WHERE … (SELECT …) …) …

Examples

The following example queries, which will generate an error in Visual FoxPro 8.0, are now supported in Visual FoxPro 9.0.

Copy Code
CREATE CURSOR MyCursor (field1 I)
INSERT INTO MyCursor VALUES (0)

CREATE CURSOR MyCursor1 (field1 I)
INSERT INTO MyCursor1 VALUES (1)

CREATE CURSOR MyCursor2 (field1 I)
INSERT INTO MyCursor2 VALUES (2)

SELECT * FROM MyCursor T1 WHERE EXISTS ;
   (SELECT * from MyCursor1 T2 WHERE NOT EXISTS ;
   (SELECT * FROM MyCursor2 T3))

*** Another multiple subquery nesting example ***
SELECT * FROM table1 WHERE table1.iid IN ;
   (SELECT table2.itable1id FROM table2 WHERE table2.iID IN ;
   (SELECT table3.itable2id FROM table3 WHERE table3.cValue = "value"))

GROUP BY in a Correlated Subquery

Many queries can be evaluated by executing a subquery once and substituting the resulting value or values into the WHERE clause of the outer query. In queries that include a correlated subquery (also known as a repeating subquery), the subquery depends on the outer query for its values. This means that the subquery is executed repeatedly, once for each row that might be selected by the outer query.

Visual FoxPro 8.0 does not allow using GROUP BY in correlated subquery, and generates error 1828 (SQL: Illegal GROUP BY in subquery). Visual FoxPro 9.0 removes this limitation and supports GROUP BY for correlated subqueries allowed to return more than one record.

The following is the general syntax for the GROUP BY clause in a correlated subquery.

SELECT … WHERE … (SELECT … WHERE … GROUP BY …) …

Examples

The following example, which will generate an error in Visual FoxPro 8.0, is now supported in Visual FoxPro 9.0.

Copy Code
CLOSE DATABASES ALL
CREATE CURSOR MyCursor1 (field1 I, field2 I, field3 I)
INSERT INTO MyCursor1 VALUES(1,2,3)
CREATE CURSOR MyCursor2 (field1 I, field2 I, field3 I)
INSERT INTO MyCursor2 VALUES(1,2,3)

SELECT * from MyCursor1 T1 WHERE field1;
   IN (SELECT MAX(field1) FROM MyCursor2 T2 ;
   WHERE T2.field2=T1.FIELD2 GROUP BY field3)

TOP N in a Non-Correlated Subquery

Visual FoxPro 9.0 supports the TOP N clause in a non-correlated subquery. The ORDER BY clause should be present if the TOP N clause is used, and this is the only case where it is allowed in subquery.

The following is the general syntax for the TOP N clause in a non-correlated subquery.

SELECT … WHERE … (SELECT TOP nExpr [PERCENT] … FROM … ORDER BY …) …

Examples

The following example, which will generate an error in Visual FoxPro 8.0, is now supported in Visual FoxPro 9.0.

Copy Code
CLOSE DATABASES ALL
CREATE CURSOR MyCursor1 (field1 I, field2 I, field3 I)
INSERT INTO MyCursor1 VALUES(1,2,3)
CREATE CURSOR MyCursor2 (field1 I, field2 I, field3 I)
INSERT INTO MyCursor2 VALUES(1,2,3)

SELECT * FROM MyCursor1 WHERE field1 ;
   IN (SELECT TOP 5 field2 FROM MyCursor2 order by field2)

Subqueries in a SELECT List

Visual FoxPro 9.0 allows a subquery as a column or a part of expression in a projection. A subquery in a projection has exactly the same requirements as a subquery used in a comparison operation. If a subquery does not return any records, NULL value is returned.

In Visual FoxPro 8.0, an attempt to use a subquery as a column or a part of expression in a projection would generate error 1810 (SQL: Invalid use of subquery).

The following is the general syntax for a subquery in a SELECT list.

SELECT … (SELECT …) … FROM …

Example

The following example, which will generate an error in Visual FoxPro 8.0, is now supported in Visual FoxPro 9.0.

Copy Code
SELECT T1.field1, (SELECT field2 FROM MyCursor2 T2;
   WHERE T2.field1=T1.field1) FROM MyCursor1 T1

Aggregate functions in a SELECT List of a Subquery

In Visual FoxPro 9.0, aggregate functions are now supported in a SELECT list of a subquery compared using the comparison operators <, <=, >, >= followed by ALL, ANY, or SOME. See Considerations for SQL SELECT Statements for more information about aggregate functions.

Example

The following example demonstrates the use of an aggregate function (the COUNT( ) function) in a SELECT list of a subquery.

Copy Code
CLOSE DATABASES ALL

CREATE CURSOR MyCursor (FIELD1 i)
INSERT INTO MyCursor VALUES (6)
INSERT INTO MyCursor VALUES (0)
INSERT INTO MyCursor VALUES (1)
INSERT INTO MyCursor VALUES (2)
INSERT INTO MyCursor VALUES (3)
INSERT INTO MyCursor VALUES (4)
INSERT INTO MyCursor VALUES (5)
INSERT INTO MyCursor VALUES (-1)

CREATE CURSOR MyCursor2 (FIELD2 i)
INSERT INTO MyCursor2  VALUES (1)
INSERT INTO MyCursor2  VALUES (2)
INSERT INTO MyCursor2  VALUES (2)
INSERT INTO MyCursor2  VALUES (3)
INSERT INTO MyCursor2  VALUES (3)
INSERT INTO MyCursor2  VALUES (3)
INSERT INTO MyCursor2  VALUES (4)
INSERT INTO MyCursor2  VALUES (4)
INSERT INTO MyCursor2  VALUES (4)
INSERT INTO MyCursor2  VALUES (4)

SELECT * FROM MYCURSOR WHERE field1;
   < ALL (SELECT count(*) FROM MyCursor2 GROUP BY field2) ;
   INTO CURSOR MyCursor3
BROWSE

Correlated Subqueries Allow Complex Expressions to be Compared with Correlated Field

In Visual FoxPro 8.0, correlated fields can only be referenced in the following forms:

correlated field <comparison> local field

-or-

local field <comparison> correlated field

In Visual FoxPro 9.0. correlated fields support comparison to local expressions, as shown in the following forms:

correlated field <comparison> local expression

-or-

local expression <comparison> correlated field

A local expression must use at least one local field and cannot reference any outer (correlated) field.

Example

In the following example, a local expression (MyCursor2.field2 / 2) is compared to a correlated field (MyCursor.field1).

Copy Code
SELECT * FROM MyCursor ;
   WHERE EXISTS(SELECT * FROM MyCursor2  ;
   WHERE MyCursor2.field2 / 2 > MyCursor.field1)

Changes for Expressions Compared with Subqueries.

In Visual FoxPro 8.0, the left part of a comparison using the comparison operators [NOT] IN, <, <=, =, ==, <>, !=, >=, >, ALL, ANY, or SOME with a subquery must reference one and only one table from the FROM clause. In case of a comparison with correlated subquery, the table must also be the correlated table.

In Visual FoxPro 9.0, comparisons work in the following ways:

  • The expression on the left side of an IN comparison must reference at least one table from the FROM clause.

  • The left part for the conditions =, ==, <>, != followed by ALL, SOME, or ANY must reference at least one table from the FROM clause.

  • The left part for the condition >, >=, <, <= followed by ALL, SOME, or ANY (SELECT TOP…) must reference at least one table from the FROM clause.

  • The left part for the condition >, >=, <, <= followed by ALL, SOME, or ANY (SELECT <aggregate function>…) must reference at least one table from the FROM clause.

  • The left part for the condition >, >=, <, <= followed by ALL, SOME, or ANY (subquery with GROUP BY and/or HAVING) must reference at least one table from the FROM clause.

In Visual FoxPro 9.0, the left part of a comparison that does not come from the list (for example, ALL, SOME, or ANY are not included) doesn't have to reference any table from the FROM clause.

In all cases, the left part of the comparison is allowed to reference more than one table from the FROM clause. For a correlated subquery, the left part of the comparison does not have to reference the correlated table.

Subquery in an UPDATE - SQL Command SET List

In Visual FoxPro 9.0, the UPDATE - SQL Command now supports a subquery in the SET clause.

A subquery in a SET clause has exactly the same requirements as a subquery used in a comparison operation. If the subquery does not return any records, the NULL value is returned.

Only one subquery is allowed in a SET clause. If there is a subquery in the SET clause, subqueries in the WHERE clause are not allowed.

The following is the general syntax for a subquery in the SET clause.

UPDATE … SET … (SELECT …) …

Example

The following example demonstrates the use of a subquery in the SET clause.

Copy Code
CLOSE DATA
CREATE CURSOR MyCursor1 (field1 I , field2 I NULL)

INSERT INTO MyCursor1 VALUES (1,1)
INSERT INTO MyCursor1 VALUES (2,2)
INSERT INTO MyCursor1 VALUES (5,5)
INSERT INTO MyCursor1 VALUES (6,6)
INSERT INTO MyCursor1 VALUES (7,7)
INSERT INTO MyCursor1 VALUES (8,8)
INSERT INTO MyCursor1 VALUES (9,9)

CREATE CURSOR MyCursor2 (field1 I , field2 I)

INSERT INTO MyCursor2 VALUES (1,10)
INSERT INTO MyCursor2 VALUES (2,20)
INSERT INTO MyCursor2 VALUES (3,30)
INSERT INTO MyCursor2 VALUES (4,40)
INSERT INTO MyCursor2 VALUES (5,50)
INSERT INTO MyCursor2 VALUES (6,60)
INSERT INTO MyCursor2 VALUES (7,70)
INSERT INTO MyCursor2 VALUES (8,80)

UPDATE MyCursor1 SET field2=100+(SELECT field2 FROM MyCursor2 ;
  WHERE MyCursor2.field1=MyCursor1.field1) WHERE field1>5

SELECT MyCursor1
LIST

Sub-SELECT in the FROM Clause

A sub-SELECT is often referred to as a derived table. Derived tables are SELECT statements in the FROM clause referred to by an alias or a user-specified name. The result set of the SELECT in the FROM clause creates a table used by the outer SELECT statement. Visual FoxPro 9.0 permits the use of a subquery in the FROM clause.

A sub-SELECT should be enclosed in parentheses and an alias is required. Correlation is not supported. A sub-SELECT has the same syntax limitations as the SELECT command, but not the subquery syntax limitations. All sub-SELECTs are executed before the top most SELECT is evaluated.

The following is the general syntax for a subquery in the FROM clause.

SELECT … FROM (SELECT …) [AS] Alias…

Example

The following example demonstrates the use of a subquery in the FROM clause.

Copy Code
SELECT * FROM (SELECT * FROM MyCursor T1;
   WHERE field1 = (SELECT T2.field2 FROM MyCursor1 T2;
   WHERE T2.field1=T1.field2);
   UNION SELECT * FROM MyCursor2;
   ORDER BY 2 desc) AS subquery

*** Note that the following code will generate an error ***
SELECT * FROM (SELECT TOP 5 field1 FROM MyCursor) ORDER BY field1

ORDER BY with Field Names in the UNION clause

When using a UNION clause in Visual FoxPro 8.0, you are forced to use numeric references in the ORDER BY clause. In Visual FoxPro 9.0, this restriction has been removed and you can use field names.

The referenced fields must be present in the SELECT list (projection) for the last SELECT in the UNION; that projection is used for ORDER BY operation.

Example

The following example demonstrates the use of a field names in the ORDER BY clause.

Copy Code
CLOSE DATABASES all
CREATE CURSOR MyCursor(field1 I,field2 I)
INSERT INTO MyCursor values(1,6)
INSERT INTO MyCursor values(2,5)
INSERT INTO MyCursor values(3,4)

SELECT field1, field2, .T. AS FLAG,1 FROM MyCursor;
   WHERE field1=1;
   UNION ;
   SELECT field1, field2, .T. AS FLAG,1 FROM MyCursor;
   WHERE field1=3;
   ORDER BY field2 ;
   INTO CURSOR TEMP READWRITE

BROWSE NOWAIT

Optimized TOP N Performance

In Visual FoxPro 8.0 and earlier versions, when using the TOP N [PERCENT] clause all records are sorted and then the TOP N are extracted. In Visual FoxPro 9.0, performance has been improved by eliminating records that do not qualify for the TOP N from the sort process as early as possible.

The TOP N optimization is done only if the SET ENGINEBEHAVIOR Command is set to 90.

Optimization requires that TOP N return no more than N records (this is not the case for Visual FoxPro 8.0 and earlier versions) which is enforced if SET ENGINEBEHAVIOR is set to 90.

TOP N PERCENT cannot be optimized unless the whole result set can be read into memory at once.

Improved Optimization for Multiple Table OR Conditions

Visual FoxPro 9.0 provides for improved Rushmore optimization involving multi-table OR conditions. Visual FoxPro uses multi-table OR conditions to Rushmore optimize filter conditions for a table as long as both sides of the condition can be optimized. The following example shows this:

Copy Code
CLEAR
CREATE CURSOR Test1 (f1 I)
FOR i=1 TO 20
  INSERT INTO Test1 VALUES (I)
NEXT
INDEX ON f1 TAG f1
CREATE CURSOR Test2 (f2 I)
FOR i=1 TO 20
  INSERT INTO Test2 VALUES (I)
NEXT
INDEX ON f2 TAG f2
SYS(3054,12)
SELECT * from Test1, Test2 WHERE (f1 IN (1,2,3) AND f2 IN (17,18,19)) OR ;
  (f2 IN (1,2,3) AND f1 IN (17,18,19)) INTO CURSOR Result
SYS(3054,0)

In this scenario, table Test1 can be Rushmore optimized using the following condition:

(f1 IN (1,2,3)  OR f1 IN (17,18,19))and table Test2 with the following:

(f2 IN (17,18,19) OR f2 IN (1,2,3))

Support for Local Buffered Data

At times it can be beneficial to use SELECT - SQL to select records from a local buffered cursor in which the table has not been updated. Many times when creating controls like grids, list boxes, and combo boxes it is necessary to consider newly added records which have not yet been committed to disk. Currently, SQL statements are based on content that is already committed to disk.

Visual FoxPro 9.0 provides language enhancements that allow you to specify if the data returned by a SELECT - SQL command is based on buffered data or data written directly to disk.

The SELECT - SQL command now supports a WITH … BUFFERING clause that lets you specify if retrieved data is based on buffered data or data written directly to disk. For more information, see SELECT - SQL Command - WITH Clause.

If you do not include the BUFFERING clause, the retrieved data is then determined by the setting for SET SQLBUFFERING command. For more information, see the SET SQLBUFFERING Command.

Enhancements to other SQL Commands

The following sections describe enhancements made to the INSERT - SQL Command, UPDATE - SQL Command, and DELETE - SQL Command commands in Visual FoxPro 9.0.

UNION Clause in the INSERT - SQL Command

In Visual FoxPro 9.0, a UNION clause is now supported in the INSERT - SQL Command.

The following is the general syntax for the UNION clause.

INSERT INTO … SELECT … FROM … [UNION SELECT … [UNION …]]

Example

The following example demonstrates the use of a UNION clause in INSERT-SQL.

Copy Code
CLOSE DATABASES ALL
CREATE CURSOR MyCursor (field1 I,field2 I)
CREATE CURSOR MyCursor1 (field1 I,field2 I)
CREATE CURSOR MyCursor2 (field1 I,field2 I)

INSERT INTO MyCursor1 VALUES (1,1)
INSERT INTO MyCursor2 VALUES (2,2)

INSERT INTO MyCursor SELECT * FROM MyCursor1 UNION SELECT * FROM MyCursor2

SELECT MyCursor
LIST

Correlated UPDATE - SQL Commands

Visual FoxPro 9.0 now supports correlated updates with the UPDATE - SQL Command.

If a FROM clause is included in the UPDATE -SQL command, then the name after UPDATE keyword defines the target for the update operation. This name can be a table name, an alias, or a file name. The following logic is used to select the target table:

  • If the name matches an implicit or explicit alias for a table in the FROM clause, then the table is used as a target for the update operation.

  • If the name matches the alias for the cursor in the current data session, then the cursor is used as a target.

  • A table or file with the same name is used as a target.

The UPDATE -SQL command FROM clause has the same syntax as the FROM clause in the SELECT - SQL command with the following limitations:

  • The target table or cursor cannot be involved in an OUTER JOIN as a secondary table.

  • The target cursor cannot be a subquery result.

  • All other JOINs can be evaluated before joining the target table.

The following is the general syntax for a correlated UPDATE command.

UPDATE … SET … FROM … WHERE …

Example

The following example demonstrates a correlated update using the UPDATE -SQL command.

Copy Code
CLOSE DATABASES ALL

CREATE CURSOR MyCursor1 (field1 I , field2 I NULL,field3 I NULL)
INSERT INTO MyCursor1 VALUES (1,1,0)
INSERT INTO MyCursor1 VALUES (2,2,0)
INSERT INTO MyCursor1 VALUES (5,5,0)
INSERT INTO MyCursor1 VALUES (6,6,0)
INSERT INTO MyCursor1 VALUES (7,7,0)
INSERT INTO MyCursor1 VALUES (8,8,0)
INSERT INTO MyCursor1 VALUES (9,9,0)

CREATE CURSOR MyCursor2 (field1 I , field2 I)
INSERT INTO MyCursor2 VALUES (1,10)
INSERT INTO MyCursor2 VALUES (2,20)
INSERT INTO MyCursor2 VALUES (3,30)
INSERT INTO MyCursor2 VALUES (4,40)
INSERT INTO MyCursor2 VALUES (5,50)
INSERT INTO MyCursor2 VALUES (6,60)
INSERT INTO MyCursor2 VALUES (7,70)
INSERT INTO MyCursor2 VALUES (8,80)

CREATE CURSOR MyCursor3 (field1 I , field2 I)
INSERT INTO MyCursor3 VALUES (6,600)
INSERT INTO MyCursor3 VALUES (7,700)

UPDATE MyCursor1 SET MyCursor1.field2=MyCursor2.field2, field3=MyCursor2.field2*10 FROM MyCursor2 ;
  WHERE MyCursor1.field1>5 AND MyCursor2.field1=MyCursor1.field1

SELECT MyCursor1
LIST

UPDATE MyCursor1 SET MyCursor1.field2=MyCursor3.field2 FROM MyCursor2, MyCursor3  ;
  WHERE MyCursor1.field1>5 AND MyCursor2.field1=MyCursor1.field1 AND MyCursor2.field1=MyCursor3.field1

SELECT MyCursor1
LIST

Correlated DELETE - SQL Commands

Visual FoxPro 9.0 now supports correlated deletions with the DELETE - SQL Command.

If a FROM clause has more than one table, the name after the DELETE keyword is required and it defines the target for the delete operation. This name can be a table name, an alias or a file name. The following logic is used to select the target table:

  • If the name matches an implicit or explicit alias for a table in the FROM clause, then the table is used as a target for the update operation.

  • If the name matches the alias for the cursor in the current data session, then the cursor is used as a target.

  • A table or file with the same name is used as a target.

The DELETE -SQL command FROM clause has the same syntax as the FROM clause in the SELECT - SQL command with the following limitations:

  • The target table or cursor cannot be involved in an OUTER JOIN as a secondary table.

  • The target cursor cannot be a subquery result.

  • It should be possible to evaluate all other JOINs before joining the target table.

The following is the general syntax for a correlated DELETE command.

DELETE [alias] FROM alias1 [, alias2 … ] … WHERE …

Example

The following example demonstrates a correlated deletion using the DELETE -SQL command.

Copy Code
CLOSE DATABASES ALL

CREATE CURSOR MyCursor1 (field1 I , field2 I NULL,field3 I NULL)
INSERT INTO MyCursor1 VALUES (1,1,0)
INSERT INTO MyCursor1 VALUES (2,2,0)
INSERT INTO MyCursor1 VALUES (5,5,0)
INSERT INTO MyCursor1 VALUES (6,6,0)
INSERT INTO MyCursor1 VALUES (7,7,0)
INSERT INTO MyCursor1 VALUES (8,8,0)
INSERT INTO MyCursor1 VALUES (9,9,0)

CREATE CURSOR MyCursor2 (field1 I , field2 I)
INSERT INTO MyCursor2 VALUES (1,10)
INSERT INTO MyCursor2 VALUES (2,20)
INSERT INTO MyCursor2 VALUES (3,30)
INSERT INTO MyCursor2 VALUES (4,40)
INSERT INTO MyCursor2 VALUES (5,50)
INSERT INTO MyCursor2 VALUES (6,60)
INSERT INTO MyCursor2 VALUES (7,70)
INSERT INTO MyCursor2 VALUES (8,80)

CREATE CURSOR MyCursor3 (field1 I , field2 I)
INSERT INTO MyCursor3 VALUES (6,600)
INSERT INTO MyCursor3 VALUES (7,700)

DELETE MyCursor1 FROM MyCursor2  ;
  WHERE MyCursor1.field1>5 AND MyCursor2.field1=MyCursor1.field1

SELECT MyCursor1
LIST
RECALL ALL

DELETE MyCursor1 FROM MyCursor2, MyCursor3  ;
  WHERE MyCursor1.field1>5 AND MyCursor2.field1=MyCursor1.field1 AND MyCursor2.field1=MyCursor3.field1

SELECT MyCursor1
LIST
RECALL ALL

DELETE FROM MyCursor1 WHERE MyCursor1.field1>5

SELECT MyCursor1
list
RECALL ALL

DELETE MyCursor1 from MyCursor1 WHERE MyCursor1.field1>5

RECALL ALL IN MyCursor1

DELETE T1 ;
  FROM MyCursor1 T1 JOIN MyCursor2 ON T1.field1>5 AND MyCursor2.field1=T1.field1, MyCursor3  ;
  WHERE MyCursor2.field1=MyCursor3.field1

RECALL ALL IN MyCursor1

Updatable Fields in UPDATE - SQL Command

The number of fields that can be updated with the UPDATE - SQL Command is no longer limited to 128 as in prior versions of Visual FoxPro. You are now limited to 255, which is the number of fields available in a table.

SET ENGINEBEHAVIOR

The SET ENGINEBEHAVIOR Command has a new Visual FoxPro 9.0 option, 90, that affects SELECT - SQL command behavior for the TOP N clause and aggregate functions. For additional information, see the SET ENGINEBEHAVIOR Command.

Data Type Conversion

Conversion between data types (for example, conversion between memo and character fields) has been improved in Visual FoxPro 9.0. This conversion improvement applies to the ALTER TABLE - SQL Command with the COLUMN option as well as structural changes made with the Table Designer.

See Also

Reference

Guide to Reporting Improvements
Data and XML Feature Enhancements
Class Enhancements
Language Enhancements
Enhancements to Visual FoxPro Designers
ALTER TABLE - SQL Command
SET SQLBUFFERING Command
SET ENGINEBEHAVIOR Command

Other Resources

What's New in Visual FoxPro
Interactive Development Environment (IDE) Enhancements
Miscellaneous Enhancements
Changes in Functionality for the Current Release


Class Enhancements

Visual FoxPro 9.0
Class Enhancements
See Also

Visual FoxPro contains the following enhancements to classes, forms, controls and object-oriented related syntax.

Anchoring Visual Controls

You can anchor a visual control to one or more edges of its parent container using the control's Anchor property. When you anchor a visual control to the parent container, the edges of the control remain in the same position relative to the edges of the container when you resize the container. For more information, see Anchor Property.

Docking Forms

Visual FoxPro extends docking support to user-defined forms. Docking forms works similarly to docking toolbars except that you can dock forms to Visual FoxPro Interactive Development Environment (IDE) windows and other forms, and controls on the form can still obtain focus when the form is docked.

Visual FoxPro includes the following new and updated properties, methods, and events to support docking forms.

  • Dockable Property

  • GetDockState Method

  • ADOCKSTATE( ) Function

  • AfterDock Event

  • BeforeDock Event

  • Dock Method

  • Docked Property

  • DockPosition Property

  • UnDock Event

  • DOCK Command

For more information, see How to: Dock Forms.

CheckBox and OptionButton Controls Support Wordwrapping

The WordWrap property is now supported for CheckBox and OptionButton controls. The text portions of these controls now use wordwrapping. For more information, see WordWrap Property.

CommandButton Controls Can Align Text with Pictures

The Alignment property now applies to CommandButton controls when specifying an image for the Picture property and setting the PicturePosition property to a value other than the default. The Alignment property also contains new and revised settings for CommandButton, CheckBox, and OptionButton controls. For more information, see Alignment Property.

CommandButton, OptionButton, and CheckBox Controls Can Hide Captions

The PicturePostion property contains a new setting of 14 (No text) for CommandButton, OptionButton, and CheckBox controls. You can use this setting to hide the text portions of these controls without needing to set the Caption property to an empty string. This setting is particularly useful when you want to include a hotkey for a button with a graphic without displaying the Caption text. You must set the Style property to 1 (Graphical) for this new setting to apply.

In addition, the PicturePosition property now applies to CheckBox and OptionButton controls when Style is set to 1 (Graphical).

For more information, see PicturePosition Property.

PictureMargin and PictureSpacing Properties Control Spacing and Margins on CommandButton, OptionButton, and CheckBox Controls

You can better control positioning of images on CommandButton, OptionButton, and CheckBox controls with the new PictureMargin and PictureSpacing properties. The PictureMargin property specifies margin spacing in pixels between an image and the control's border as determined by the PicturePosition property. The PictureSpacing property specifies margin spacing in pixels between an image and text on the control.

For more information, see PictureMargin Property and PictureSpacing Property.

Collection Objects Support in ComboBox and ListBox Controls

You can now specify Collection objects as the row source and row source type for the RowSource and RowSourceType properties of ComboBox and ListBox controls. For more information, see RowSource Property and RowSourceType Property.

Setting Ascending or Descending Indexes on Cursors in the DataEnvironment

You can specify ascending or descending order for a cursor index by using the new OrderDirection property for Cursor objects.

Note:
OrderDirection is disregarded when the cursor's Order property is empty.

For more information, see OrderDirection Property.

Grid Supports Rushmore Optimization

The Grid Control can be set to support Rushmore optimization if the underlying data source contains indexes that support this.

For more information, see Optimize Property.

Mouse Pointer Control for Grid Columns and Column Headers

The MousePointer and MouseIcon properties now apply to Column objects in a grid and Header objects in a column. For the MousePointer property, you can specify the new setting of 16 (Down Arrow) to reset the mouse pointer for a column header to the default down arrow.

For more information, see MousePointer Property and MouseIcon Property.

Rotating Label, Line, and Shape Controls

You can use the new Rotation property to rotate Label controls. The Rotation property applies to Line and Shape controls when used with the new PolyPoints property. For more information, see Rotation Property, PolyPoints Property, and Creating More Complex Shapes using the PolyPoints Property.

Label Controls Can Display Themed Background

For Label controls, you can set the Style property to Themed Background Only to show only themed background colors when Windows themes are turned on. The label background color is the same as the parent container for the label. For more information, see Style Property.

ListBox Controls Can Hide Scroll Bars

You can use the new AutoHideScrollBar property for ListBox controls to hide scroll bars when the list contains less than the number of items that can be visible in the list box. For more information, see AutoHideScrollBar Property.

Toolbar Controls Can Display Horizontal Separator Objects

For Separator objects, set the Style property to 1 to display a horizontal line or a vertical line, depending on how the toolbar appears. If the toolbar appears horizontally, the line displays vertically. If the toolbar appears vertically, the line displays horizontally. In versions prior to this release, setting Style to 1 displayed a vertical line only.

Note:
In versions prior to this release, undocked vertical system and user-defined toolbars did not display horizontal separators. In the current release, horizontal separators now display for vertical undocked toolbars.

For more information, see Style Property.

Toolbar Controls Can Hide Separator Objects

The Visible property now applies to Separator objects so you can control whether a Separator object displays in Toolbar controls. When used in combination with the Style property, the separator's Visible property determines whether a space or line displays as the separator when its Style property is set to 0 (Normal - do not display a line) or 1 (display a horizontal or vertical line), respectively.

For more information, see Visible Property.

Creating More Complex Shapes

You can use the new PolyPoints property for Line and Shape controls to create polygon lines and shapes. PolyPoints specifies an array of any dimension containing coordinates with the format of X1, Y1, X2, Y2, ..., organized in the order in which the polygon line or shape is drawn.

For Line controls, when you create a polygon line using the PolyPoints property, you can specify the new setting of "S" or "s" for the LineSlant property to create a Bezier curve.

For more information, see PolyPoints Property and LineSlant Property.

ComboBox Controls Can Hide Drop-Down Lists

You can now use the NODEFAULT command in the DropDown event for a ComboBox control. This will prevent the drop-down list portion of a ComboBox control from appearing. For more information, see NODEFAULT Command.

NEWOBJECT( ) Creates Objects without Raising Initialization Code

To mimic the behavior of a class opened in Class Designer or Form Designer, pass 0 to the cInApplication parameter. This feature allows you to create design-time tools that view the structure of a class.

By passing 0 to the cInApplication parameter for the NEWOBJECT( ) function, Visual FoxPro allows you to create an instance of a class without raising initialization code (such as code in the Init, Load, Activate, and BeforeOpenTables events). Furthermore, when the object is released, it does not raise its destructor code (such as code in the Destroy and Unload events). Only initialization and destructor code is suppressed; code in other events and methods is still called.

If you use the cInApplication parameter to suppress initialization and destructor code in an object, you also suppress it in the object's child objects.

This behavior is not supported for the NewObject Method.

For more information, see NEWOBJECT( ) Function.

Specify Where Focus is Assigned in the Valid Event

To direct where focus is assigned, you can use the optional ObjectName parameter in the RETURN command of the Valid event. The object specified must be a valid Visual FoxPro object. If the specified object is disabled or cannot receive focus, then focus is assigned to the next object in the tab order. If an invalid object is specified, Visual FoxPro keeps the focus at the current object.

You can now set focus to objects in the following scenarios:

  • Set focus to an object on another visible form.

  • Set focus to an object on a non-visible Page or Pageframe control.

For more information, see Valid Event and RETURN Command.

TextBox Controls Have Auto-Completion Functionality

You can add auto-completion functionality to your text box controls to make data entry more efficient. Auto-completion is the automatic display of a drop-down list of entries that match the string as it is typed into the text box. The entries come from a special table that tracks unique values entered into the text box, the control name that is the source of the value, and usage information.

The following properties support auto-completion:

  • AutoComplete Property

  • AutoCompSource Property

  • AutoCompTable Property

By the setting the AutoComplete property, you determine the sort order for the entries. If you want more control over the list and where it is stored, you can use the AutoCompSource property to specify the table used to populate the automatic list. By default, the table is AUTOCOMP.DBF. You can use one table for each text box control or a single table can populate automatic lists for several text boxes.

If you use a single table, which is the default, the table uses values in the Source field for each entry to identify the text box control associated with the entry. By default, the Source field value is the name of the text box control. You can specify the Source field value using the AutoCompSource property of the text box. For example, you might want to make the same set of entries available to multiple Text box controls within the application such as address information. You can explicitly set the AutoCompTable and AutoCompSource properties for each of the controls to the same table and source field value. The same automatic list appears for each of them.

The text box control handles updating the auto-completion table for you based on the values actually entered in the text box. If you want to remove a value from the list, enter a string in a text box that matches the string you want to delete to filter the list for it. Select the entry in the list and press the DELETE key. The string remains in the table but no longer appears in the automatic list.

Note:
You can control the number of items that appear in the drop-down list using SYS(2910) - List Display Count.

For more information, see AutoComplete Property, AutoCompSource Property, and AutoCompTable Property.

New InputMask and Format Property Settings

The following new InputMask and Format settings are available:

InputMask Property

cMask | Description
U | Permits alphabetic characters only and converts them to uppercase (A - Z).
W | Permits alphabetic characters only and converts them to lowercase (a - z).

Format Property

cFunction | Description
Z | Displays the value as blank if it is 0, except when the control has focus. Dates are also supported in these controls. The / / date delimiters are not displayed unless the control has focus.

For more information, see InputMask Property and Format Property.

Use PictureVal Property to Pass Images as Strings

The Image control's new PictureVal property can be used instead of the Picture Property (Visual FoxPro) to specify a character string expression or object of an image. For an object, the format must be of an IPicture interface format compatible with LOADPICTURE( ) Function.

For more information, see PictureVal Property.

CLEAR CLASSLIB Updated

The CLEAR CLASSLIB command now automatically executes a CLEAR CLASS command on each class in the specified class library. Any errors that might occur during release of individual classes (e.g., class in use) are ignored.

Note:
Classes in other class libraries that are used or referenced by a class in the specified class library are not cleared.

For more information, see CLEAR Commands.

Screen Resolution Limit Increased

In prior versions of Visual FoxPro, the definable maximum area for a form is limited to twice the Screen Resolution for both X and Y dimensions. For example, if your monitor resolution is 1280x1024, then the max dimensions would be:

Copy Code
Form.Width = 2552
Form.Height = 2014

Additionally, if you attempted to set Width and Height properties to these limits in design-time and then ran the form, you would see that the values have reverted to screen resolution limits (being that they were saved this way):

Copy Code
Form.Width = 1280
Form.Height = 998

In Visual FoxPro 9.0, this limitation has been increased to approximately 32,000 pixels for each dimension and now allows for more flexibility with certain forms such as scrollable ones:

Copy Code
Form.Width = 32759
Form.Height = 32733

For more information, see Width Property and Height Property.

ProjectHook Source Code Control Events

New events have been added to the ProjectHook class, which allow you to perform source code control operations such as check-in and check-out of multiple files at once.

For more information, see SCCInit Event and SCCDestroy Event.

AddProperty Method Supports Design Time Settings

You can specify the visibility (Protected, Hidden or Public) and description of a property using the AddProperty method with new available parameters. These settings can also be controlled from the New Property Dialog Box and Edit Property/Method Dialog Box. For more information, see AddProperty Method.

WriteMethod Method Supports Design Time Settings

You can specify the visibility (Protected, Hidden or Public) and description of a method using the WriteMethod method with new available parameters. These settings can also be controlled from the New Property Dialog Box and Edit Property/Method Dialog Box. For more information, see WriteMethod Method.

See Also

Reference

Guide to Reporting Improvements
Data and XML Feature Enhancements
SQL Language Improvements
Language Enhancements
Enhancements to Visual FoxPro Designers

Other Resources

What's New in Visual FoxPro
Interactive Development Environment (IDE) Enhancements
Miscellaneous Enhancements
Changes in Functionality for the Current Release


Language Enhancements

Visual FoxPro 9.0
Language Enhancements
See Also

In the current release of Visual FoxPro, you will find enhanced functionality via new and enhanced commands and functions. Expand and collapse this topic to see information about miscellaneous language additions and improvements.

Class Enhancements

Visual FoxPro contains significant language enhancements for classes, forms, controls, and object-oriented related features. For more information, see Class Enhancements.

Data and XML Enhancements

Visual FoxPro contains significant language enhancements for Data, SQL and XML features. For more information, see SQL Language Improvements and Data and XML Feature Enhancements.

IDE Enhancements

Visual FoxPro contains a number of language enhancements for features related to the IDE (Interactive Development Environment). For more information, see Interactive Development Environment (IDE) Enhancements and Enhancements to Visual FoxPro Designers.

Printing and Reporting Enhancements

Visual FoxPro contains a number of language enhancements to support new Reporting functionality:

  • REPORT FORM Command

    Displays or prints out a report specified by a report definitions file. This command has been enhanced to support Report Listener objects.

  • SET REPORTBEHAVIOR Command

    Controls use of Report Preview and Report Output applications with the Visual FoxPro Report System.

  • SYS(2024) - Detect Report Cancellation

    Determines if user canceled out of a running report.

Additionally, there are improvements to the following related Printing language elements:

  • SYS(1037) - Page Setup Dialog Box

    Displays 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. In this version, a new nValue parameter is available.

  • APRINTERS( ) Function

    Returns a five-column array with the name of the printer, connected port, driver, comment, and location. The last three columns are available if the new optional parameter is passed.

  • GETFONT( ) Function

    Contains an additional setting to display only those fonts available on the current default printer and clarified values for the language script.

New Reporting functionality is described in more detail in separate Reporting topics. For more information, see Guide to Reporting Improvements.

Specifying Arrays with More Than 65K Elements

You can now specify arrays containing more than 65,000 elements, for example, when using the DIMENSION command. Normal arrays and member arrays have a new limit of 2GB. Arrays containing member objects retain a limit of 65,000 elements.

Note:
Array sizes can also be limited by available memory, which affects performance, especially for very large arrays. Make sure your computer has enough memory to accommodate the upper limits of your arrays.

The Library Construction Kit, which contains the files Pro_Ext.h, WinAPIMS.lib, and OcxAPI.lib, still has a limit of 65,000 elements. For more information about these files, see Accessing the Visual FoxPro API, Adding Visual FoxPro API Calls, and Building and Debugging Libraries and ActiveX Controls. The SAVE TO command does not support saving arrays larger than 65,000 elements.

For more information, see Visual FoxPro System Capacities and DIMENSION Command.

STACKSIZE Setting Increases Nesting Levels to 64k

For operations such as the DO command, you can change the default number of nesting levels from 128 levels to 32 and up to 64,000 levels of nesting by including the new STACKSIZE setting in a Visual FoxPro configuration file.

Note:
You can change the nesting level only during Visual FoxPro startup.

For more information, see Special Terms for Configuration Files and Visual FoxPro System Capacities.

Program and Procedure File Size Is Unrestricted

In previous versions of Visual FoxPro, the size of a procedure or program could not exceed 65K. Visual FoxPro now removes this restriction for programs and procedures. For more information, see Visual FoxPro System Capacities.

PROGCACHE Configuration File Setting

In previous versions of Visual FoxPro, you could not specify the program cache size or amount of memory reserved to run programs. This configuration file setting allows you to control this. It is especially useful for MTDLL scenarios. For more information, see Special Terms for Configuration Files.

ICASE( ) Function

The new ICASE( ) function makes it possible for you to evaluate a list of conditions and return results depending on the result of evaluating those conditions. For more information, see ICASE( ) Function.

TTOC( ) Converts DateTime Expressions to XML DateTime Format

You can convert a DateTime expression into a character string in XML DateTime format by passing a new optional value of 3 to the TTOC( ) function. For more information, see TTOC( ) Function.

SET COVERAGE Command Available at Run Time

The SET COVERAGE command is now available at run time so that you can debug errors that occur at run time but not at design time. For more information, see SET COVERAGE Command.

CLEAR ERROR Command

The new ERROR clause for the CLEAR command makes it possible to reset the error structures as if no error occurred. This affects the following functions:

  • The AERROR( ) function will return 0.

  • The ERROR( ) function will return 0.

  • The output from MESSAGE( ), MESSAGE(1) and SYS(2018) will return a blank string.

The CLEAR command should not be used with the ERROR clause within a TRY...CATCH...FINALLY structure. For more information, see CLEAR Commands.

Write Options Dialog Settings to Registry Using SYS(3056)

The SYS(3056) function can now be used to write out settings from the Options dialog box to the registry.

SYS(3056 [, nValue ])

The following table lists values for nValue.

nValue | Description
1 | Update only from registry settings, with the exception of SET commands and file locations.
2 | Write out settings to the registry.

For more information, see SYS(3056) - Read Registry Settings.

FOR EACH ... ENDFOR Command Preserves Object Types

Visual FoxPro now includes the FOXOBJECT keyword for the FOR EACH ... ENDFOR command to support preservation of native Visual FoxPro object types.

FOR EACH objectVar [AS Type [OF ClassLibrary ]] IN Group FOXOBJECT

Commands

[EXIT]

[LOOP]

ENDFOR | NEXT [Var]

The FOXOBJECT keyword specifies that the objectVar parameter created will be a Visual FoxPro object. The FOXOBJECT keyword only applies to collections where the collection is based on a native Visual FoxPro Collection class. Collections that are COM-based will not support the FOXOBJECT keyword.

For more information, see FOR EACH ... ENDFOR Command.

SET PATH Command Enhancements

The SET PATH command now supports the ADDITIVE keyword. The ADDITIVE keyword appends the specified path to the end of the current SET PATH list. If the path already exists in the SET PATH list, Visual FoxPro does not add it or change the order of the list. Paths specified with the ADDITIVE keyword must be strings in quotes or valid expressions.

In addition, the length of the SET PATH list has been increased to 4095 characters.

For more information, see SET PATH Command.

Trim Functions Control Which Characters Are Trimmed

It is now possible to specify which characters are trimmed from an expression when using the TRIM( ), LTRIM( ), RTRIM( ), and ALLTRIM( ) functions.

TRIM(cExpression[, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

LTRIM(cExpression[, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

RTRIM(cExpression[, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

ALLTRIM(cExpression[, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

You can specify that the trim is case-insensitive using the nFlag value of 0 bit and 1.

The cParseChar parameter specifies one or more character strings to be trimmed from cExpression. A maximum of 23 strings can be specified in cParseChar.

By default, if cParseChar is not specified, then leading and trailing spaces are trimmed from character strings or 0 bytes are removed for Varbinary data types.

The cParseChar parameters are applied in the order they are entered. When a match is found, cExpression is truncated and the process repeats from the first cParseChar parameter.

For more information, see the TRIM( ) Function, LTRIM( ) Function, RTRIM( ) Function, and ALLTRIM( ) Function topics.

ALINES( ) Offers More Flexible Parsing Options

The ALINES( ) function has been enhanced to provide several additional options such as case-insensitive parsing and improved handling of empty array elements. These options are available using the new nFlags parameter that replaces the older lTrim 3rd parameter. For more information, see ALINES( ) Function.

Improvements in TEXT…ENDTEXT Statement

You can use the TEXT…ENDTEXT command to eliminate line feeds using the new PRETEXT setting. A new FLAGS parameter controls additional output settings. For more information, see TEXT ... ENDTEXT Command.

Include Delimiters in STREXTRACT( ) Results

The STREXTRACT( ) function has a new nFlags setting that allows you to include the specified delimiters with the returned expression. For more information, see STREXTRACT( ) Function.

STRCONV( ) Enhanced to Allow for Code Page and FontCharSet

For certain conversion settings, you can specify an optional Code Page or Fontcharset setting for use in the conversion. For more information, see STRCONV( ) Function.

TYPE( ) Determines if an Expression is an Array

The TYPE( ) function accepts the parameter, 1, to evaluate an expression to determine if it is an array.

Type(cExpression, 1)

The following character values are returned if the 1 parameter is specified.

Return Value | Description
A | cExpression is an array.
U | cExpression is not an array.
C | cExpression is a collection.

cExpression must be passed as a character string.

For more information, see TYPE( ) Function.

BINTOC( ) and CTOBIN( ) Have Additional Conversion Capabilities

The BINTOC( ) and CTOBIN( ) functions have update or new parameters that provide you with more control over the output of these functions. Additionally, these enhancements offer some improvements for working with Win32 API routines. For more information, see BINTOC( ) Function and CTOBIN( ) Function.

MROW( ) and MCOL( ) Can Detect the Position of the Mouse Pointer

The MROW( ) and MCOL( ) functions now have a zero (0) parameter for detecting the position of the mouse pointer based on the currently active form instead of the form returned by the WOUTPUT( ) function. Although they are typically reference the same form, if the AllowOutput property of the form is set to False (.F.), WOUTPUT( ) does not return the current active form. The mismatch of references and can lead to unexpected results. By using the zero (0) parameter, you can avoid misplacing items, such as Shortcut menus, as the currently active form is always used.

For more information, see MROW( ) Function and MCOL( ) Function.

INPUTBOX( ) Returns A Cancel Operation

The INPUTBOX( ) function contains an additional parameter that allows you to determine if the user canceled out of the dialog. For more information, see INPUTBOX( ) Function.

AGETCLASS( ) Supported for Runtime Applications

The AGETCLASS( ) fiunction is now supported for runtime applications. For more information, see AGETCLASS( ) Function.

SYS(2019) Extends Handling of Configuration Files

You can use SYS(2019) to obtain the name and location of both internal and external configuration files. For more information, see SYS(2019) - Configuration File Name and Location.

SYS(2910) Controls List Display Count

You can control the number of items that appear in a drop-down list such as the one used by AutoComplete Property. This is the setting that is available on the View Tab, Options Dialog Box of the Options Dialog Box (Visual FoxPro).

For more information, see SYS(2910) - List Display Count.

SYS(3008) Turns Off Hyperlink Tip

Visual FoxPro will display a tip such as "CTRL+Click to follow the link" when you hover over a hyperlink in the editor. If you desire to not have this tip show, you can use SYS(3008) to turn it off. This function is also useful for international applications where you do not want to display the English text for this tip. For more information, see SYS(3008) - Hyperlink Tooltips.

SYS(3065) Internal Program Cache

You can obtain the internal program cache (PROGCACHE configuration file setting). For more information, see SYS(3065) - Internal Program Cache.

SYS(3101) COM Code Page Translation

You can now specify a code page to use for character data translation involving COM interoperability. For more information, see SYS(3101) - COM Code Page Translation.

Bidirectional Support for Tooltips and Popups

For international applications that display text from right to left, you can use the following new enhancements to control text justification:

  • SYS(3009) - right justifies text in ToolTips.

  • DEFINE POPUP…RTLJUSTIFY - right justifies items in a popup, such as a shortcut menu.

  • SET SYSMENU TO RTLJUSTIFY - right justifies an entire menu system.

The SYS(3009) function is a global setting. For more information, see SYS(3009) - Bidirectional Text Justification for ToolTips, DEFINE POPUP Command and SET SYSMENU Command.

Enhanced Font Script Support

Visual FoxPro 9.0 contains a number of enhancements that extend ability to specify a Font Language Script (or FontCharSet) along with existing Font settings:

  • SYS(3007) - specifies a FontCharSet for ToolTips. This is a global setting.

  • FONT Clause - the following table lists commands that support an optional FONT clause that allows for specification of a FontCharSet in the following format:

    FONT cFontName [, nFontSize [, nFontCharSet]]

    Command

    DEFINE MENU

    DEFINE POPUP

    DEFINE BAR

    DEFINE PAD

    DEFINE WINDOW

    MODIFY WINDOW

    BROWSE/EDIT/CHANGE

    ?/??
  • Browse - the Font Dialog Box that you can invoke by selecting the Font menu item from the Table menu with a Browse Window active now allows for selection of a font language script. You can specify a global default font script from the IDE Tab, Options Dialog Box in the Options Dialog Box (Visual FoxPro). To do this, you must first check the Use font script checkbox.

  • Editors - the Font Dialog Box that you can invoke with an editor window active by selecting the Font menu item from the Format menu or right-click shortcut menu Edit Properties Dialog Box now allows for selection of a font language script. You can specify a global default font script from the IDE Tab, Options Dialog Box in the Options Dialog Box (Visual FoxPro). To do this, you must first check the Use font script checkbox.

For more information, see SYS(3007) - ToolTipText Property Font Language Script, IDE Tab, Options Dialog Box, and FontCharSet Property.

ToolTip Timeout Control

You can specify how long a ToolTip is displayed if the mouse pointer is left stationary. For more information, see _TOOLTIPTIMEOUT System Variable.

Tablet PC Features

The following features are available to assist with applications designed to run on a Tablet PC computer.

  • ISPEN( ) - determines if the last Visual FoxPro application mouse event on a Tablet PC was a pen tap.

  • _SCREEN.DisplayOrientation - this read-write property specifies the screen display orientation for a Tablet PC. The value returned is the current orientation.

  • _TOOLTIPTIMEOUT - specifies how long a ToolTip is displayed if the mouse pointer is left stationary.

For more information, see ISPEN( ) Function, DisplayOrientation Property, and _TOOLTIPTIMEOUT System Variable.

Windows Message Event Handling

Visual FoxPro allows you to trap and handle window messages from the Microsoft® Windows® operating system using existing BINDEVENT functions. Some examples of common events you might wish to trap for include:

  • A power broadcast message used to intercept standby or power-down activities.

  • Media insertion and removal events, such as the insertion of a CD into a drive.

  • The insertion and/or removal of a Plug and Play hard disk (e.g., USB Drive).

  • Interception of screen saver queries to stop the screen saver from activating.

  • Operating system level font changes and Windows XP Theme changes.

  • New network connections/shares added or removed from system.

  • Switching between applications.

You can use the Visual FoxPro BINDEVENT functions to register (and unregister) event handlers used to intercept messages (i.e., Win32 API window messages that get processed by the Win32 WindowProc function). See MSDN for more details.

The new BINDEVENT( ) syntax requires the hWnd (integer) of the window receiving the message you desire to intercept, and the specific message itself (integer). For example, power-management events such as standby and power-down use the Win32 WM_POWERBROADCAST message (value of 536).

BINDEVENT(hWnd, nMessage, oEventHandler, cDelegate)

The following example illustrates detection of a Windows XP Theme change:

Copy Code
#DEFINE WM_THEMECHANGED    0x031A
#DEFINE GWL_WNDPROC    (-4)
PUBLIC oHandler
oHandler=CREATEOBJECT("AppState")
BINDEVENT(_SCREEN.hWnd, WM_THEMECHANGED, oHandler, "HandleEvent")
MESSAGEBOX("Test by changing Themes.")
DEFINE CLASS AppState AS Custom
nOldProc=0
PROCEDURE Destroy
    UNBINDEVENT(_SCREEN.hWnd, WM_THEMECHANGED)
ENDPROC
PROCEDURE Init
    DECLARE integer GetWindowLong IN WIN32API ;
        integer hWnd, ;
        integer nIndex
    DECLARE integer CallWindowProc IN WIN32API ;
        integer lpPrevWndFunc, ;
        integer hWnd,integer Msg,;
        integer wParam,;
        integer lParam
    THIS.nOldProc=GetWindowLong(_VFP.HWnd,GWL_WNDPROC)
ENDPROC
PROCEDURE HandleEvent(hWnd as Integer, Msg as Integer, ;
    wParam as Integer, lParam as Integer)
    lResult=0
    IF msg=WM_THEMECHANGED
        MESSAGEBOX("Theme changed...")
    ENDIF
    lResult=CallWindowProc(this.nOldProc,hWnd,msg,wParam,lParam)
    RETURN lResult
ENDPROC
ENDDEFINE

The following SYS( ) functions are also available to assist with handing these events:

  • SYS(2325) - returns the hWnd of a client window from the parent window's WHANDLE.

  • SYS(2326) - returns a Visual FoxPro WHANDLE from a window’s hWnd.

  • SYS(2327) - returns a window's hWnd from a Visual FoxPro window’s WHANDLE.

For more information, see BINDEVENT( ) Function, UNBINDEVENTS( ) Function, and AEVENTS( ) Function. Also, see SYS(2325) - WCLIENTWINDOW from Visual FoxPro WHANDLE, SYS(2326) - WHANDLE from a Window's hWnd, and SYS(2327) - Window's hWnd from Visual FoxPro WHANDLE for related topics. Refer to MSDN as reference source for details on specific window messages.

See Also

Reference

Guide to Reporting Improvements
Data and XML Feature Enhancements
SQL Language Improvements
Class Enhancements
Enhancements to Visual FoxPro Designers

Other Resources

What's New in Visual FoxPro
Interactive Development Environment (IDE) Enhancements
Miscellaneous Enhancements
Changes in Functionality for the Current Release


Interactive Development Environment (IDE) Enhancements

Visual FoxPro 9.0
Interactive Development Environment (IDE) Enhancements
See Also

To provide a more integrated development environment for your projects and applications, Visual FoxPro contains the following improved functionality for the IDE.

Additional Project Manager Shortcut Menu Commands

When docked, the Project Manager window contains the following additional shortcut menu commands that are available on the Project menu:

  • Close

    Closes the Project Manager.

  • Add Project to Source Control

    Creates a new source control project based on the current project. Available only when a source code control provider is installed and specified on the Projects tab in the Options dialog box.

  • Errors

    Displays the error (.err) file after running a build.

  • Refresh

    Refreshes the contents of the Project Manager.

  • Clean Up Project

    Removes deleted records from the Project Manager (.PJX) file.

Modifying a Class Library from the Project Manager

When you select a class library (.vcx) file in the Project Manager, you can now open and browse class libraries by clicking the Modify button. The class library opens in the Class Browser. For more information, see How to: Open Class Libraries.

Set Font of Project Manager

You can change the text font settings for the Project Manager window. Right-click the Project Manager window (outside of the tree hierarchy window) and choose Font.

Generating Message Logs During Project Build and Compile

When you build a project, application, or dynamic-link library, Visual FoxPro automatically generates an error (.err) file that includes any error messages, if they exist, when the build process completes. When you select the Display Errors check box in the Build Options dialog box, Visual FoxPro displays the .err file when the build completes. Selecting the Recompile All Files check box includes compile errors in the .err file. Build status messages usually appear in the status bar. However, in previous versions, if the build process is interrupted, Visual FoxPro did not write the .err file to disk.

In the current release, Visual FoxPro writes build status and error messages to the .err file as they occur during the build process. If the build process is interrupted, you can open the .err file opens to review the errors.

Note:
If no errors occur during the build, the .err file is deleted.

If the Debug Output window is open, build status and error messages appear in the window. You can save messages from the Debug Output window to a file.

For more information, see How to: View and Save Build Messages.

Properties Window Enhancements

  • Design time support for entering property values greater than 255 characters and extended characters, such as CHR(13) (carriage return) and CHR(10) (linefeed), has been added to visual class library (.vcx) and form (.scx) files. You can now enter up to 8k characters in length.

    Note:
    Extended property value support is only available through the Properties Window (Zoom dialog box) for custom user-specified properties as well as certain native ones such as CursorSchema and Value. For properties not supported, you can still specify values which are longer than 255 characters, or contain carriage returns and linefeeds by assigning them in code such as during the object's Init Event.

    The Zoom dialog box and Expression Builder dialog box have been updated to support this. The Properties window includes a Zoom (Z) button that appears next to the property settings box for appropriate properties.

    Caution:
    Property values that exceed 255 characters or include carriage return and/or linefeed characters are stored in a new format inside the .vcx or .scx file. If you attempt to modify these classes in a prior version, an error occurs.

    This feature is particularly useful for setting the CursorAdapter CursorSchema property to any schema expression when schemas might exceed 255 characters.

  • The Properties window font can now be specified by the new Font shortcut menu option. This new menu replaces the Small, Medium and Large font menu items used in prior versions. This font is also used in the description pane, and object and property value dropdowns.

    Note:
    Bold and italic font styles are reserved for non-default property values and read-only properties, respectively. If a bold or italic font style is chosen, then the Properties window inverts the displayed behavior. For example, if one chooses an italic font style, read-only properties appear in normal font style and all others in italic.

  • Colors can be specified for certain types of properties by right clicking on the Properties Window and selecting following menu items:

    • Non-Default Properties Color

      Sets color for properties whose values have changed from default setting (same properties that are displayed when the Non-Default Properties Only menu item is selected).

    • Custom Properties Color

      Sets color for custom properties.

    • Instance Properties Color

      Sets color for custom properties that have been added to the current class instance (same properties that appear in bold in the Edit Property/Method Dialog Box).

    Note:
    If a conflict exists between color settings, the Instance setting takes priority followed by the Non-Default one.

For more information, see Zoom <property> Dialog Box, Expression Builder Dialog Box, CursorSchema Property, and Properties Window.

MemberData Extensibility

The MemberData extensibility architecture lets you provide metadata for class members (properties, methods and events). With MemberData, you can specify a custom property editor, display a property on the Favorites tab, or change the capitalization in the Properties Window (Visual FoxPro).

For more information, see MemberData Extensibility.

Setting Default Values for New Properties

When adding a new property to a class, you can specify an initial value other than the default in the New Property dialog box. Subclasses inherit these default values unless you reset the default values to the parent class. In previous versions, you had to set the default value for the new property by selecting the property in the Properties window and setting the default value.

For more information, see How to: Add Properties to Classes.

Document View Sort Options

You can now sort items in the Document View window by name for forms and visual class libraries.

See Document View Window for more information on sorting items in the Document View Window.

Compiling Code in the Background

Visual FoxPro performs background compilation when syntax coloring is turned on in the Command window and Visual FoxPro editors for program (.prg) files, methods, stored procedures, and memos. The Expression box in the Expression Builder dialog box also includes support for background compilation and syntax coloring when turned on.

When the single and current line of code that you are typing contains invalid syntax, Visual FoxPro displays the line of code with the formatting style selected in the Editor tab of the Options dialog box.

Note:
Syntax coloring must be turned on for background compilation to function. Background compilation does not detect invalid syntax in multiple lines of code, including those containing continuation characters.

For more information, see How to: Display and Print Source Code in Color.

Rich Text Format (RTF) Clipboard Support

Visual FoxPro now supports copying in RTF (Rich Text Format) to the clipboard. Visual FoxPro preserves the style (bold, italic, and underline) and color attributes.

RTF is supported only in the FoxPro editors that allow for syntax coloring, such as the Command window and editing windows opened with MODIFY COMMAND Command. The RTF clipboard format is only supported when syntax coloring is enabled such as from Edit Properties Dialog Box. You can disable RTF clipboard format with the _VFP EditorOptions Property.

The _CLIPTEXT System Variable does not support RTF.

Find Dialog Box Improvements

The following improvements were made to Find support:

  • If a word is selected in a Visual FoxPro editor, the Find Dialog Box (Visual FoxPro) when opened now displays the word in the Look For drop-down box. If Find has not yet been used for a running instance of Visual FoxPro, a word positioned under the insertion pointer will appear in the Look For drop-down. If multiple words are selected, only the first word appears in the drop-down (use copy and paste to enter multiple words).

  • When a Browse window is open and you search for a word with the Find dialog box, you can search for the word again (Find Again) after the Find dialog box is closed by pressing the F3 key.

  • You can now use Find to search for content in Name column of the Watch and Locals debug windows (see Debugger Window). When searching object members, Find searches in these debug windows are limited to nodes that have been expanded and one level below.

View Constants in Trace Window

Constants (#DEFINE values) can be viewed in the Trace Window when you hover over it with the mouse.

Note:
Visual FoxPro evaluates constants as expressions in the Trace Window and may have difficulty interpreting a specific #DEFINE when you hover over it with the mouse. Consequently, if there are multiple expressions on a line, they are all displayed in the value tip.

Printing Selected Text in Editor Windows

You can print selected text from Visual FoxPro editor windows. When you have text selected in the editor window, the Selection option in the Print dialog box is available and selected.

Note:
If a partial line is selected, the entire line is printed.

For more information, see Print Dialog Box.

System Font Improvements

To improve legibility on high-resolution monitors, Error dialog boxes and the Zoom <property> Dialog Box in the Properties window now use the Windows Message Box text font.

In Windows XP, the Windows Message Box text font is set by opening Display in the Control Panel, and then clicking Advanced on the Appearance tab.

IntelliSense Saves Settings Between User Sessions

Visual FoxPro now saves IntelliSense settings, such as turning IntelliSense on, between user sessions. These settings are controlled by the _VFP EditorOptions property. In addition, the settings in the _VFP EditorOptions property are saved in the FoxUser.dbf resource file. For more information, see EditorOptions Property.

IntelliSense in Memo Field Editor Window

Visual FoxPro includes IntelliSense support in Memo field editor windows when syntax coloring is turned on.

IntelliSense Available for Runtime Applications

Selected IntelliSense features are available at run time in distributed Visual FoxPro 9.0 applications. In order to use IntelliSense at run time, you need to set the _FOXCODE and _CODESENSE variables, and EditorOptions Property.

Note:
With runtime applications, syntax coloring does not need to be turned on for an editor to support IntelliSense.

For more information, see IntelliSense Support in Visual FoxPro, _FOXCODE System Variable, _CODESENSE System Variable and EditorOptions Property.

IntelliSense Support in WITH ... ENDWITH and FOR EACH ... ENDFOR Commands

Visual FoxPro now supports IntelliSense within the WITH ... ENDWITH Command and FOR EACH ... ENDFOR Command.

WITH ObjectName [AS Type [OF ClassLibrary]]

  Commands

ENDWITH

FOR EACH ObjectName [AS Type [OF ClassLibrary]] IN Group

  Commands

  [EXIT]

  [LOOP]

ENDFOR

The Type parameter can be any valid type, including data types, class types, or ProgID. If the class name cannot be found, Visual FoxPro disregards Type and does not display IntelliSense for it.

Note:
The type reference does not affect the functionality of the application at run time. The type reference is only used for IntelliSense.

The ObjectName expression can refer to a memory variable or an array.

The ClassLibrary parameter must be in a path list that is visible to Visual FoxPro. You must specify a valid class library; references to existing objects are not valid. If Visual FoxPro cannot find the specified class library, IntelliSense does not display.

Types expressed as ProgIDs and class libraries do not require quotation marks ("") to enclose them unless their names contain spaces.

When a user types the AS keyword, IntelliSense displays a list of types registered in the FoxCode.dbf table with Type "T". If you have specified a valid type, typing a period within a WITH ... ENDWITH or a FOR EACH ... ENDFOR command displays IntelliSense for that object reference.

Visual FoxPro supports IntelliSense for nested WITH ... ENDWITH and FOR EACH ... ENDFOR commands. The following is an example of nested WITH ... ENDWITH commands in a class defined in a program (.prg) file named Program1.prg. To use, paste this code into a new program named Program1.prg, save it and then type a period (.) inside the WITH ... ENDWITH block.

Copy Code
DEFINE CLASS f1 AS form
MyVar1 = 123
ADD OBJECT t1 AS mytext
PROCEDURE Init
  WITH THIS AS f1 OF program1.prg
    WITH .t1 AS mytext OF program1.prg
    ENDWITH
  ENDWITH
ENDPROC
ENDDEFINE

DEFINE CLASS mytext as textbox
MyVar2 = 123
ENDDEFINE

IntelliSense provides limited List Values functionality for selected properties that begin with a "T" or "F" within a WITH ... ENDWITH or FOR EACH ... ENDFOR command. This is done to avoid possible conflicts with the common property values True (.T.) and False (.F.). If you just type ".T" or ".F" and press Enter, the word selected in the List Value drop-down does not expand. You need to type at least two letters for IntelliSense to insert the selected word.

See Also

Reference

Guide to Reporting Improvements
Data and XML Feature Enhancements
SQL Language Improvements
Class Enhancements
Language Enhancements
Enhancements to Visual FoxPro Designers

Other Resources

What's New in Visual FoxPro
Miscellaneous Enhancements
Changes in Functionality for the Current Release


Enhancements to Visual FoxPro Designers

Visual FoxPro 9.0
Enhancements to Visual FoxPro Designers
See Also

You might want to open the following designers and find the enhancements.

Report and Label Designers

You can use the Report Builder available in the Report Designer and Label Designer to perform reporting tasks, configure settings, and set properties for reporting features such as report layout, report bands, data groups, report controls, and report variables. For example, you can perform the following tasks:

  • Prevent users from modifying reports, report controls, and report bands when editing the report in protected mode.

  • Display captions instead of expressions for Field controls at design time.

  • Display user-defined ToolTips for report controls.

  • Set the language script for reports.

  • Save the report data environment as a class.

By default, the Report Builder activates when you interact with the Report and Label designers. However, you can use the _REPORTBUILDER system variable to specify ReportBuilder.app. The Report Builder consolidates, replaces, and adds to the functionality found in previous Report Designer user interface elements, which remain in the product and are available by setting _REPORTBUILDER. You can write custom report builders to extend reporting functionality and output or run reports with report objects. For more information, see Working with Reports and _REPORTBUILDER System Variable.

Menu Designer

You can set the _MENUDESIGNER system variable to call your own custom designer for creating menus.

Copy Code
_MENUDESIGNER = cProgramName

For more information, see _MENUDESIGNER System Variable.

Table Designer

The Table Designer accommodates the following data enhancements:

  • New Data Types: Varchar, Varbinary and Blob

  • Binary Indexes

  • For more information, see Data and XML Feature Enhancements.

Query and View Designers

You can use spaces in table names specified in SQL statements in the Query and View designers if you provide an alias. For example, editing the following statement is valid in the View and Query designers:

Copy Code
SELECT * from dbo."Order Details" Order_Details

For more information, see SELECT - SQL Command.

Data Environment Designer

The full path to the database (DBC) appears in the status bar when you select a database in the Add Table or View Dialog Box.

Class and Form Designers

The name of the class you are modifying appears in the title bar for the following dialog boxes:

  • Edit Property/Method Dialog Box

  • New Property Dialog Box

  • New Method Dialog Box

  • Class Info Dialog Box

The View menu for the Form Designer offers both options for specifying the tab order on forms: Assign Interactively or Assign by List.

In the Class, Form, and Report designers, you can use the following keyboard shortcut commands to adjust spacing between selected items.

Shortcut | Description
ALT+Arrow Key | Adjusts the spacing between the selected objects by one pixel in the direction of the arrow key.
ALT+CTRL+Arrow Key | Adjusts the spacing between the selected objects by one grid scale in the direction of the arrow key.

For more information, see Interactive Development Environment (IDE) Enhancements.

See Also

Reference

Guide to Reporting Improvements
Data and XML Feature Enhancements
SQL Language Improvements
Class Enhancements
Language Enhancements

Other Resources

What's New in Visual FoxPro
Interactive Development Environment (IDE) Enhancements
Miscellaneous Enhancements
Changes in Functionality for the Current Release


Miscellaneous Enhancements

Visual FoxPro 9.0
Miscellaneous Enhancements
See Also

Visual FoxPro contains the following miscellaneous enhancements. You can click Collapse All to view a list of enhancments.

Printing Dialog Boxes and Printing Language Enhancements

Visual FoxPro includes various enhancements for its printing dialog boxes and printing language.

Visual FoxPro uses the latest operating system dialogs for Printer Setup and other related printing operations. If the user is running on Windows XP, the dialogs will appear Themed.

The following language functions contain new enhancements that impact general printing operations:

  • SYS(1037) - Page Setup Dialog Box

  • APRINTERS( ) Function

  • GETFONT( ) Function

    Contains an additional setting to display only those fonts available on the current default printer and clarified values for the language script.

For more information, see Language Enhancements.

Improved Support for Applications Detecting Terminal Servers

Visual FoxPro now automatically includes support for applications that are generated by the build process to detect whether they are running on a Terminal Server and prevent loading of unnecessary dynamic-link library (.dll) files that can impact performance. For more information, see BUILD EXE Command.

Updated Dr. Watson Error Reporting to 2.0

Visual FoxPro includes and updates its product error reporting to support Dr. Watson 2.0. This version includes new and improved error reporting, logging, and auditing features. For example, errors are logged while offline and are posted when you reconnect.

Anchor Editor Application

Visual FoxPro 9.0 allows you to create a custom property editor through extended metadata attributes for class members. Through this new extensibility model, you now have the ability to extend the functionality of class properties and methods, allowing you to create design-time enhancements such as a custom property editor. For more information about creating custom property editors, see MemberData Extensibility.

A sample custom property editor, Anchoreditor.app, is included in Visual FoxPro 9.0 and is located in the Wizards directory. This application is run when the Anchor property is double-clicked in the Properties window, or by choosing the Anchor property in the Properties window and clicking the ellipsis button (…).

Term | Definition
Anchor but do not resize vertically | Specifies that the center of the control is anchored to the top and bottom edges of its container but the control does not resize.
Anchor but do not resize horizontally | Specifies that the center of the control is anchored to the left and right edges of its container but the control does not resize.
Border values | Displays the current settings for the border values.
Common settings | Selects commonly used settings for the Anchor property.
Sample | Click the Sample button to test the current anchor value on a sample form.
Anchor value | The Anchor property value that is the combination of the current settings for the border values.

Class Browser

You can open and view class definitions that are specified within a program (.prg) similarly to class libraries (.vcx). You can select a program (.prg) from the File Open/Add dialog box. See Class Browser Window for more information.

CursorAdapter Builder

The CursorAdapter Builder contains a number of enhancements that correspond to improvements added to the CursorAdapter class. See CursorAdapter Builder for more information.

Toolbox

The Toolbox (Visual FoxPro) is now dockable and can be docked to the desktop or other IDE windows.

Code References

The Code References Window has been updated with the following minor enhancements:

  • For the results grid, the Options dialog provides a new setting to show separate columns for class, method, and line, rather than concatenating them all in a single column.

  • You can now sort by method name by right-clicking on the method header or selecting the Sort By menu item from the right-click menu.

  • With the results tree list, the following new right-click menu options are available:

    • Expand All - expands all nodes

    • Collapse All - collapses all nodes

    • Sort by Most Recent First - puts the most recent result sets at the top of the list rather than at the bottom

Note:
The results beneath a tree node are not filled until the node is expanded. This is done to increase performance if you have a large result sets.

GENDBC.PRG

The Gendbc.prg program which generates program used to recreate a database has been updated with following minor enhancements:

  • Support for new Varchar, Varbinary and Blob field types

  • Support for AllowSimultaneousFetch, RuleExpression, and RuleText properties for views

Environment Manager Task Pane

The Environment Manager Task Pane has been enhanced with the following features:

  • Form and Formset Template Classes - you can now specify template classes for new forms and formsets with each environment set. This is setting specified in the Forms Tab, Options Dialog Box.

  • Field Mapping - you can set classes to use for when you drag and drop a field onto a form with each environment set. This is setting specified in the Field Mapping Tab, Options Dialog Box.

  • Resource File - the Environment Manager now supports setting of a Resource File. If one does not exist, the Environment Manager will optionally create it when the environment is set.

  • The Environment Manager now contains a new <default field mapping> environment set. This set is created the first time the Environment Manager is run so that the original default Options dialog settings for Field Mapping and Form Template Classes can be saved and restored later if desired.

  • For more information, see Environment Manager Task Pane.

Data Explorer Task Pane

The Task Pane Manager includes the new Data Explorer Task Pane which allows you to view and work with remote data sources such as SQL Server databases.

For more information, see Data Explorer Task Pane.

MemberData Editor

The new MemberData Editor lets you edit MemberData for your classes. The MemberData Editor is available from the Class menu when the Class Designer is active. The MemberData Editor is also invoked silently when you right-click on an item in the Properties Window and select the Add to Favorites menu item. The MemberData Editor application is specified as a builder and can be changed in the Builder.dbf table located in your Wizards directory.

For more information, see MemberData Editor and MemberData Extensibility.

New Foundation Classes (FFC)

The following are new FoxPro Foundation classes added to this version of Visual FoxPro:

  • _REPORTLISTENER.VCX - a set of core classes you can use when creating custom report listeners.

  • _FRXCURSOR.VCX - a class library used for working with report (FRX) files.

  • _GDIPLUS.VCX - a set of classes you can use for GDI+ handling. This is intended primarily for use when creating custom report listener classes.

New Solution Samples

Visual FoxPro 9.0 contains many new samples that show off new features in the product. To see a list of these samples, select the Solution Samples task pane in the Task Pane Manager and expand the New in Visual FoxPro 9.0 node.

See Also

Reference

Guide to Reporting Improvements
Data and XML Feature Enhancements
SQL Language Improvements
Class Enhancements
Language Enhancements
Enhancements to Visual FoxPro Designers

Other Resources

What's New in Visual FoxPro
Interactive Development Environment (IDE) Enhancements
Changes in Functionality for the Current Release


Changes in Functionality for the Current Release

Visual FoxPro 9.0
Changes in Functionality for the Current Release
See Also

Visual FoxPro includes functionality that differs from previous versions and might affect existing code. These behavior changes are organized according to the following categories:

  • Critical Changes Functionality changes most likely to affect existing code when running under this version of Visual FoxPro. It is extremely important that you read this section.

  • Important Changes Functionality changes that might affect existing code when running under this version of Visual FoxPro.

  • Miscellaneous Changes Functionality changes you should know about but are not likely to impact existing code.

  • Removed Items Features or files that existed in prior versions of Visual FoxPro but are no longer included.

Critical Changes

Critical behavior changes will most likely to affect existing code when running under this version of Visual FoxPro.

SQL SELECT IN (Value_Set) Clause

In previous versions of Visual FoxPro, the IN (Value_Set) clause for the WHERE clause in the SQL SELECT command is mapped to INLIST( ) function. In the current release, Visual FoxPro might stop evaluating values and expressions in the Value_Set list when the first match is found. Therefore, if the IN clause is not Rushmore-optimized, you can improve performance by placing values most likely to match in the beginning of the Value_Set list. For more information, see the description for the IN clause in the SELECT - SQL Command topic and the INLIST( ) Function.

Conversion of INLIST( ) Function in the Query Designer and View Designer

In previous versions of Visual FoxPro, the Query Designer and View Designer convert INLIST( ) function calls in the WHERE clause of the SQL SELECT command into IN (Value_Set) clauses. In the current release, this conversion no longer occurs due to the differences between INLIST( ) and the SQL IN clause. INLIST( ) remains restricted to 24 arguments. For more information, see the description for the IN clause in the SELECT - SQL Command topic and the INLIST( ) Function.

Grids and RecordSource and ControlSource Properties

In Visual FoxPro 9.0 there is a change in Grid control behavior. When the RecordSource property for a Grid control is set, Visual FoxPro 9.0 resets all ControlSource properties to the empty string ("") for all columns. In earlier versions of Visual FoxPro, the ControlSource properties were not properly reset, so problems could occur when a RecordSource with a different structure was later bound. This change may impact scenarios involving Access and Assign methods or BINDEVENT( ) function calls made against a Grid column's ControlSource property.

Important Changes

Important changes might affect existing code when running under Visual FoxPro 9.0.

Reporting

Visual FoxPro contains many improvements for reporting. The following are behavior changes that could impact existing reports:

  • The Report Designer and Engine now make use of extensible components. You can control or eliminate use of design-time extensions by altering the value of _REPORTBUILDER System Variable. You control run-time extension use with the SET REPORTBEHAVIOR Command.

  • In Visual FoxPro 9's new object-assisted reporting mode, report fields may need to be adjusted (widened) slightly. This is especially important for numeric data where a field that is not wide enough to display the entire number will show it instead as asterisks (*****). For more information about the changes to the Report System that required this change, and features of the GDI+ rendering engine and other changes related to it, see Using GDI+ in Reports. For migration strategy and recommendations, see Guide to Reporting Improvements.

  • For a table of additional, minor rendering differences between backward-compatible reporting mode and object-assisted reporting mode, see the table below.

    Rendering feature Behavior in backward-compatible mode Behavior in object-assisted mode Recommendations

    Tab stops (CHR(9) values included in report data)

    The width of a tab stop is determined by a number of characters in the font used.

    Tab stops are set at fixed-width positions, regardless of font.

    If you concatenated tabs with data in a stretching report layout element to create a table format within the element, you can often fulfill the same requirements using a second detail band in Visual FoxPro 9. Alternatively, change the number of tabs you concatenate with your data.

    Special characters and word-wrapping

    Non-breaking spaces are not respected; they are treated as normal space characters.

    Special characters such as non-breaking spaces (CHR(160)) and soft hyphens (CHR(173)) are correctly interpreted. As a result, words may wrap differently in output.

    Evaluate the results. In most cases, users will appreciate the change, because it more faithfully representing their original intentions in the text. If necessary, use the CHRTRAN( ) Function or STRTRAN( ) Function to replace these special characters with standard spaces and hyphens.

    Line spacing of multi-line objects

    Line spacing is determined by a formula that does not take font properties into consideration. Lines in a multi-line object are individually rendered, so background colors for each line may appear to have a different width.

    GDI+ line spacing is dynamically determined using font characteristics. A multi-line object is rendered as a single block of text.

    Evaluate the results. In most cases, the change in line spaces will provide a more polished appearance, and in all cases this method of handling multi-line text provides better performance. If a report depends on the old style of spacing lines, you can adjust the ReportListener's DynamicLineHeight Property to revert to the old behavior.

    Cursor images (.CUR files)

    .CUR files can be used as image sources in reports.

    .CUR files are not supported as image sources.

    Convert the cursor file to another, supported image format.

    Shape (Rounded Rectangle) curvature

    Limited choices for curvature.

    More choices are available through the Report Builder Application dialog box interface, but some will not look the same way in backward-compatible mode and object-assisted mode.

    If reports have to run in both backward-compatible mode and object-assisted mode, or if they are designed in version 9.0 but must run in earlier versions, limit your choices of values of shape curvature to those allowed in the native Round Rectangle Dialog Box. If you are using the Style Tab, Report Control Properties Dialog Box (Report Builder) to design such reports, use the values 12, 16, 24, 32, and 99, to represent the native buttons, selecting the buttons from left to right. The default value in the Round Rectangle dialog box (second button) is 16.
  • When you create a Quick Report, by using the CREATE REPORT - Quick Report Command or by invoking the Quick Report… option on the Report menu, and if you have SET REPORTBEHAVIOR 90, the layout elements created by the Report Designer are sized differently from ones created for the same fields in previous versions. This change handles the additional width required by the new rendering mechanism of the report engine.

  • If you use the KEYBOARD Command or PLAY MACRO Command statements to address options on the Report menu, you may need to revise the keystrokes in these statements, as the menu has been reorganized.

  • Reports may take longer to open in the Report Designer if the report was previously saved with the Printer Environment setting enabled. You can improve performance by unchecking the Printer Environment menu item from the Report menu and re-saving the report. The saved Printer Environment is not critical for functioning of a report and is typically not recommended. Object-assisted report mode also respects different printers' resolution settings, so saving resolution information for one printer in your report may have adverse effects in an environment with printers that have different resolutions. A saved Printer Environment may also have more adverse affects on REPORT FORM or LABEL commands invoked with the TO FILE option than they did in previous versions, if the associated printer setup is not available in the environment at runtime. In Visual FoxPro 9, the global default for this setting in the Reports Tab, Options Dialog Box, and for reports created in executable applications (.exe files), has been changed to unchecked.

  • Because of changes to the way Visual FoxPro 9 uses current printer settings to determine items such as print resolution and page height dynamically, a REPORT FORM or LABEL command will not run in object-assisted mode if there are no available printer setups in the environment or if the print spooler has been stopped. You will receive Error loading printer driver (Error 1958). If you need to run reports in an environment with no printer information, perhaps creating custom types of output that do not require printers, you can supply Visual FoxPro with the minimal set of information it needs to run your report by supplying a page height and page width from the appropriate Report Listener methods. For more information, see GetPageHeight Method and GetPageWidth Method.

  • By default, and by design, the Report Builder Application does not automatically show tables in the report's Data Environment when you build report expressions. To better protect end-user design sessions, only tables you have explicitly opened, not all tables from the DataEnvironment, are available in the Expression Builder. With this change, you have the opportunity to set up the design session's data exactly the way you want the end-user to see it, before you issue a MODIFY REPORT Command in your application. If you prefer the Report Designer's old behavior, you can change the Report Builder Application to emulate it. For more information, see How to: Replace the Report Builder's Expression Builder Dialog Box.

  • The ASCII keyword on the REPORT FORM Command is documented as following the <filename> parameter of the TO FILE<filename> clause. In earlier versions of Visual FoxPro, you could safely use the incorrect and unsupported syntax TO FILE ASCII<filename> instead. This incorrect syntax triggers an error in Visual FoxPro 9. Note that the ASCII keyword has no effect on object-assisted mode output provided by the Report Engine, although a ReportListener Object can be written to implement it.

  • The keyword NOCONSOLE has no default meaning in object-assisted reporting mode, because ReportListeners do not echo their rendering output to the current output window by default. However, a ReportListener can mimic backward-compatible mode in this respect, if desired. Refer to OutputPage Method for a complete example.

  • To facilitate development of run-time reporting extensions, the Report Engine now allows normal debugging procedures during a report run. If your error handling routine assumes it is impossible for a report to be suspended, this assumption will now be challenged. Refer to Handling Errors During Report Runs for a detailed look at the associated changes, and some suggestions for strategy.

  • REPORT FORM and LABEL commands are no longer automatically prohibited as user-interface-related commands in COM objects compiled into DLLs, when you run the commands in object-assisted mode. The restriction still applies to these commands when they are run in backward-compatible mode. (The topic Selecting Process Types explains why user-interface-related commands are prohibited in DLLs.) This change is not applicable to multi-threaded DLLs. A number of user-interface-related facilities also are not available in DLLs (whether single- or multi-threaded). For example, the TXTWIDTH( ) Function and TextWidth Method depend on a window handle to function, so they are not available in a DLL. The CREATE REPORT - Quick Report Command relies on the same facilities as TXTWIDTH(), and therefore is not available in a DLL. However, in many instances, creating custom output using a ReportListener does not require any user-interface activity, so a REPORT FORM or LABEL command can now be used productively in a DLL. Using the SYS(2335) - Unattended Server Mode function to trap for potential modal states, as well as the new SET TABLEPROMPT Command, is recommended. Refer to Server Design Considerations and Limitations for more information.

  • Changes have occurred to the handling of group headers and footers in multi-column reports, when the columns flow from left to right (label-style layout). The revised behavior is more useful and behaves consistently with the new detail header and footer bands as well. For a description of the change, see How to: Define Columns in Reports.

  • In previous versions, the NOWAIT keyword on the REPORT FORM and LABEL commands was not significant when the commands were issued in the Command window rather than in a program. In Visual FoxPro 9's object-assisted mode, when previewing instructions are interpreted by the Report Preview Application, this keyword is significant no matter where you issue the command. The Report Preview Application uses the NOWAIT keyword, consistently, as an instruction to provide a modeless preview form. For more information about the Report Preview Application, see Extending Report Preview Functionality.

  • Visual FoxPro 8 introduced the NOPAGEEJECT keyword on the REPORT FORM and LABEL commands, but applied the keyword only to printed output. In Visual FoxPro 9, NOPAGEEJECT has significance for all output targets, including PREVIEW. This keyword provides chained or continued report runs for multiple REPORT FORM and LABEL commands. To facilitate this behavior in preview mode, and to allow you to apply customization instructions to multiple previews, the Report Output Application caches a single ReportListener object instance for preview output, causing a change in behavior for multiple modeless report commands (REPORT FORM … PREVIEW NOWAIT). In the past, you used multiple REPORT FORM… PREVIEW NOWAIT statements in a sequence, your commands resulted in multiple report preview windows. In Visual FoxPro 9, when SET REPORTBEHAVIOR 90, these commands will result in successive report previews being directed to a single report preview window.

    Tip:
    You can easily invoke the old behavior by creating multiple ReportListener object references and associating one with each separate REPORT FORM or LABEL command, using the OBJECT keyword. For more information about using the OBJECT syntax, see REPORT FORM Command. For information about receiving multiple object references of the appropriate type from the Report Output Application, see Understanding the Report Output Application.

  • In the process of reviewing and overhauling the native Report Engine, a number of outstanding issues regarding band and layout element positioning were addressed. For example, a field element marked to stretch and sized to take up more than one text line's height in the report layout might have inappropriately pushed its band's exit events to the next page in Visual FoxPro 8. In Visual FoxPro 9, the band's exit events occur on the same page. Additional revisions improve record-pointer-handling in footer bands, when bands stretch across pages. These changes are not specific to object-assisted output rendering. If you have relied on undocumented behavior providing exact band or layout control placement in a particular report, you should review that report's behavior in Visual FoxPro 9.

SQL SELECT Statements

  • A SELECT - SQL Command containing DISTINCT and ORDER BY clauses in which the ORDER BY field is not in the SELECT field list will generate an error in Visual FoxPro 9.0 with SET ENGINEBEHAVIOR 90 (Error 1808: SQL: ORDER BY clause is invalid.). The following example shows this:

    Copy Code
    SET ENGINEBEHAVIOR 90
CREATE CURSOR foo (f1 int, f2 int)
SELECT DISTINCT f1 FROM foo ORDER BY f2 INTO CURSOR res
  • A SELECT - SQL Command containing DISTINCT and HAVING clauses in which the HAVING field is not in the SELECT field list will now generate an error in Visual FoxPro 9.0 with SET ENGINEBEHAVIOR 90 (Error 1803: SQL: HAVING clause is invalid.). An error is reported because the HAVING field is not in projection and DISTINCT is used. The following example shows this:

    Copy Code
    SET ENGINEBEHAVIOR 90
CREATE CURSOR foo (f1 int, f2 int)
SELECT DISTINCT f1 FROM foo HAVING f2>1 INTO CURSOR res
  • The number of UNION statements that can be used in a SELECT - SQL Command is no longer limited to 9. Parentheses are not completely supported with UNION statements and unlike previous versions may generate an error. If two or more SELECT statements are enclosed in parenthesis, an error is generated during compile (Error 2196: Only a single SQL SELECT statement can be enclosed in parentheses.). This behavior is not tied to any SET ENGINEBEHAVIOR Command level. The following example shows this error:

    Copy Code
    SELECT * FROM Table1 ;
  UNION ;
  (SELECT * FROM Table2 ;
  UNION ;
  SELECT * FROM Table3)
    The following example compiles without an error:

    Copy Code
    SELECT * FROM Table1 ;
  UNION ;
  (SELECT * FROM Table2) ;
  UNION ;
  (SELECT * FROM Table3)

For more information, see SET ENGINEBEHAVIOR Command.

Disabling TABLEREVERT( ) Operations During TABLEUPDATE( ) Operations

For CursorAdapters, Visual FoxPro does not permit TABLEREVERT( ) operations during operations.

For more information, see TABLEREVERT( ) Function and TABLEUPDATE( ) Function.

Index Key Truncation during Index Updates

An error (Error 2199) is now generated when index key truncation is about to occur, typically during index creation or modification. This can happen with use of a key that contains an expression involving a Memo field, whose length in not fixed, such as in the following example:

INDEX ON charfld1 + memofld1 TAG mytag

Similar issues can also occur with the SQL engine (such as during a SQL SELECT command or View creation) where it might fail to build a temporary index to optimize a join evaluation if it is unable to accurately determine the maximum size of the key.

For more information, see Error building key for index "name". (Error 2199).

Memo Field Corruption

Visual FoxPro will now detect if a Memo field in a class library (.vcx) or form (.scx) is corrupt when you try to open up that file in the designer. If the file contains a corrupt Memo field, an Error 41 such as following will occur:

Memo file <path>\myclass.VCT is missing or is invalid.

Additionally, similar Memo errors may occur if you have a Visual FoxPro table open and try to access contents of a corrupt Memo. The following sample code shows how you can detect the Error 41 memo file corruption:

Copy Code
TRY
  USE myTable EXCLUSIVE NOUPDATE
  SCAN
    SCATTER MEMO MEMVAR
  ENDSCAN
CATCH TO loError
  IF loError.ErrorNo=41
    * handle error here
  ENDIF
ENDTRY
USE IN myTable

While it is possible that loss of data may occur, the following sample code may assist in repairing some or the entire file:

Copy Code
ON ERROR *
USE myclass.vcx
COPY TO myclass_bkup.vcx&&backup
COPY TO myclass2.vcx
USE
DELETE FILE myclass.vc*
RENAME myclass2.vcx TO myclass.vcx
RENAME myclass2.vct TO myclass.vct
COMPILE CLASSLIB myclass.vcx
ON ERROR

Visual Form and Class Extended Property Support

Visual FoxPro 9 allows you to create custom properties in your visual class (SCX or VCX file) whose values can contain carriage returns and/or be of length greater than 255 characters. If you specify a property with a value like this through the Properties Window (i.e., the Zoom dialog box), Visual FoxPro will store it in a format such that you will no longer be able to edit that class in older versions of Visual FoxPro.

Class Definitions

The ability to have a property assignment set to instantiated object is no longer supported in a class definition and will generate an error. The following example shows this.

Copy Code
LOCAL oCustom
oCustom = CREATEOBJECT('cusTest')
DEFINE CLASS cusTest AS CUSTOM
    oRef = CREATEOBJECT('myclass')
ENDDEFINE
DEFINE CLASS myclass AS CUSTOM
ENDDEFINE

You can instead assign a property to an instantiated object reference in the Init event of your class.

Merge Modules for Redistributable Components

Visual FoxPro includes merge modules (MSM files) for use in redistributing shared components with your runtime applications. Merge modules are used by applications that can create Windows Installer based setups. For example, Visual FoxPro ships with merge modules that contain the Visual FoxPro runtime libraries as well as some common components including a number of Activex controls.

For Visual FoxPro 9, the VFP9RUNTIME.MSM merge module contains the runtime libraries that you will need for your custom redistributable application. The VFP9RUNTIME.MSM merge module also has dependencies on the merge modules containing the Microsoft VC 7.1 runtime library (MSVCR71.DLL) and the GDI+ graphics library (GDIPLUS.DLL). Because of these dependencies, if you select the VFP9RUNTIME.MSM merge module in a Windows Installer tool such as InstallShield, the other dependent merge modules will automatically be selected as well.

Note For Windows XP and higher operating systems, Visual FoxPro uses the GDI+ graphics library that is installed in your Windows System folder.

For Visual FoxPro 9, the merge module containing the VC runtime library no longer installs to the Windows System directory. Instead, this file is installed to your application's directory. This is done in compliance with recommended component versioning strategies for Windows operating systems. The GDI+ library is installed into the same directory as your Visual FoxPro runtime libraries and is only installed on operating systems later than Windows XP (XP already includes the GDI+ library in its Windows System directory).

Tip There may be circumstances where you will want to install the VC or GDI+ library to another location such as the Windows System directory. You can do this with your Windows Installer application (e.g., InstallShield) by first selecting the merge module before selecting the VFP9RUNTIME.MSM one. Once you have selected a merge module, you can change its installation path.

There are new merge modules for MSXML3 and MSXML4 XML parser components. The MSXML 3.0 component consists of the following merge modules:

  • MSXML 3.0 (msxml3_wim32.msm)

  • Msxml3 Exception INF Merge Module (msxml3inf_wim32.msm)

  • WebData std library (wdstddll_wim32.msm)

There are two MSXML 4.0 modules that should be included with any custom setup:

  • MSXML 4.0 (msxml4sxs32.msm)

  • MSXML 4.0 (msxml4sys32.msm)

MTDLL Memory Allocation

Visual FoxPro contains a new PROGCACHE configuration file setting which specifies the amount of memory Visual FoxPro allocates at startup for running programs (program cache). This setting also determines memory allocated per thread for Visual FoxPro MTDLL COM Servers. In prior versions, this setting was not configurable and memory was allocated as a fixed program cache of a little over 9MB (144 * 64K). The new PROGCACHE setting allows you to set the exact size of the program cache or specify that dynamic memory allocation be used.

Since MTDLL COM Servers can use up a great amount of memory if many threads are created, it is important that memory be allocated more efficiently for these scenarios. In Visual FoxPro 9, the new default setting for MTDLL COM Servers is -2 (dynamic memory allocation). For more information, see Special Terms for Configuration Files.

Miscellaneous Changes

The following are miscellaneous changes that you should know about but are not likely to impact existing code.

CursorAdapter Changes

In the current version of Visual FoxPro, the following behavior changes apply to the CursorAdapter object:

  • You can no longer call TABLEREVERT( ) Function while a TABLEUPDATE( ) Function operation is in progress.

  • The ConversionFunc Property setting is now respected during ADODB.Recordset based updates.

  • The target record is now kept current in the ADODB.Recordset during CursorAdapter.After… events.

Grid SetFocus Supported for AllowCellSelection

You can now call a Grid control's SetFocus Method and have the Grid receive focus when the AllowCellSelection Property is set to False (.F.) and the grid contains no records.

EXECSCRIPT Function

The EXECSCRIPT( ) Function now allows you to pass parameters by reference.

Additionally, Visual FoxPro 9.0 tightens syntax validation of calls made from concatenation of parameters. The following code, which worked in prior versions of Visual FoxPro, now properly causes an error because the CHR(13) character breaks the call into two lines whereas it is supposed to be part of the parameter for the EXECSCRIPT call.

Copy Code
  cRecPauseScript = "EXECSCRIPT('" + ;
    "?123" + CHR(13) + ;
    "?456" + ;
    "')"
  _VFP.DoCmd(cRecPauseScript)

To make a valid call that does not cause a syntax error, you can use the following code:

Copy Code
  cRecPauseScript = "EXECSCRIPT('?123'+CHR(13)+ '?456')"
  _VFP.DoCmd(cRecPauseScript)

Listbox Control Click Event

In the current version of Visual FoxPro, the PageUp, PageDown, Home and End keyboard keys now cause a Listbox control's Click event to fire. In previous versions, these keys did not trigger the Click event to fire, unlike the arrow keys.

PEMSTATUS( ) Function Returns False for Hidden Native Properties

In previous versions of Visual FoxPro, the PEMSTATUS( ) function returned True (.T.) for hidden native properties of Visual FoxPro base classes when specifying a value of 5 for nAttribute. In the current release, PEMSTATUS( ) returns False (.F.) for these hidden native properties. For more information, see PEMSTATUS( ) Function.

Changes to Options Dialog Box

  • In the Options dialog box, the List display count option has been moved from the Editor tab to the View tab. For more information, see View Tab, Options Dialog Box.

  • In previous versions of Visual FoxPro, you could output all the settings in the Options Dialog Box (Visual FoxPro) to the Command Window by pressing the SHIFT key when choosing the OK button to close the dialog. In the current release, these settings are now sent to the Debug Output Window. The Debug Output window must be opened in order for the settings to be directed there.

FOXRUN.PIF

The FOXRUN.PIF file that is used by the RUN | ! Command is no longer installed in the Visual FoxPro root directory. If Visual FoxPro detects the presence of a FOXRUN.PIF file during a RUN command, it will use COMMAND.COM to execute the specified RUN command. This may not be the desired SHELL program to use for a particular operating system, especially newer ones like Windows XP in which CMD.EXE is preferable.

The current behavior for a RUN command without the existence of a FOXRUN.PIF file is that the RUN command will use the SHELL program specified by the operating system COMSPEC environment variable. With Windows XP, you can view and edit this variable by right-clicking your computer desktop's My Computer icon and selecting the Properties dialog box (Advanced tab).

The FOXRUN.PIF file is still available in the Tools directory if you need it for a particular reason.

For more information, see RUN | ! Command.

SCATTER Command

The SCATTER command no longer allows for ambiguous use of both MEMVAR and NAME clauses in the same command. You can only include one of these clauses. In prior versions, the following code would not generate an error:

Copy Code
USE HOME()+"SAMPLES\Data\customer.dbf"
SCATTER MEMVAR NAME oCust

For more information, see SCATTER Command.

SET DOHISTORY

The SET DOHISTORY command, which is included for backward compatibility, was updated to send output to the Debug Output Window instead of the Command Window as in prior versions.

SCREEN ShowTips Property

The default value for _SCREEN ShowTips Property has been changed from False (.F.) to True (.T.). This change was made because new Memo and Field Tips support is now dependent on this setting.

AllowCellSelection Does Not Permit Deleting Grid Rows When Set to False

When the AllowCellSelection Property is set to False (.F.) for a Grid control, you cannot select a row for deletion by clicking the deletion column. For more information, see AllowCellSelection Property.

Northwind Database

The sample Northwind database has been updated. Five of the stored procedures now include calls to the SETRESULTSET( ) Function so that the Visual FoxPro OLE DB Provider will return a cursor when they are executed.

Foundation Classes

The _ShellExecute class contained in the _Environ.vcx FFC class library has been updated to include an additional parameter in the ShellExecute method.

Wizards and Builders

The Wizard/Builder selection dialog box now properly hides deleted entries in the Wizard and Builder registration tables.

Specifying Western Language Script Values for GETFONT( ) Function

In versions prior to this release, passing 0 as the nFontCharSet value for GETFONT( ) opened the Font Picker dialog box and displayed the Script list as unavailable. You could not specify 0 (Western) as the language script value, and setting it to 1 (Default) sets nFontCharSet to the default font setting only, which is determined by the operating system.

In this release, passing 0 to GETFONT( ) opens the Font Picker dialog box with the Script list available and Western selected. The return value for GETFONT( ) also includes the return value for nFontCharSet.

Removed Items

HTML Help SDK

The HTML Help 1.3 SDK no longer ships with Visual FoxPro.

See Also

Reference

Guide to Reporting Improvements
Data and XML Feature Enhancements
SQL Language Improvements
Class Enhancements
Language Enhancements
Enhancements to Visual FoxPro Designers

Other Resources

What's New in Visual FoxPro
Interactive Development Environment (IDE) Enhancements
Miscellaneous Enhancements


Visual FoxPro New Reserved Words

Visual FoxPro 9.0
Visual FoxPro New Reserved Words
See Also

The following tables list new words added to the Visual FoxPro language which are now reserved:

_

_MEMBERDATA | _MENUDESIGNER | _REPORTBUILDER
_REPORTOUTPUT | _ REPORTPREVIEW | _TOOLTIPTIMEOUT

A

ADJUSTOBJECTSIZE | ADOCODEPAGE | AFTERBAND
AFTERRECORDREFRESH | AFTERREPORT | ALLOWMODALMESSAGES
ANCHOR | ASQLHANDLES | AUTOCOMPLETE
AUTOCOMPSOURCE | AUTOCOMPTABLE | AUTOHIDESCROLLBAR

B

BEFOREBAND | BEFORERECORDREFRESH | BEFOREREPORT
BLOB |  |

C

CANCELREPORT | CAST | CLEARRESULTSET
CLEARSTATUS | COMMANDCLAUSES | CONFLICTCHECKCMD
CONFLICTCHECKTYPE | CURRENTDATASESSION | CURRENTPASS

D

DECLAREXMLPREFIX | DELAYEDMEMOFETCH | DISPLAYORIENTATION
DOCKABLE | DOMESSAGE | DOSTATUS
DYNAMICLINEHEIGHT |  |

E

EVALUATECONTENTS

F

FETCHMEMOCMDLIST | FETCHMEMODATASOURCE | FETCHMEMODATASOURCETYPE
FIRSTNESTEDTABLE | FRXDATASESSION | FOXOBJECT

G

GDIPLUSGRAPHICS | GETAUTOINCVALUE | GETDOCKSTATE
GETPAGEHEIGHT | GETPAGEWIDTH | GETRESULTSET

H

I

ICASE | INCLUDEPAGEINOUTPUT | INSERTCMDREFRESHCMD
INSERTCMDREFRESHFIELDLIST | INSERTCMDREFRESHKEYFIELDLIST | ISMEMOFETCHED
ISPEN | ISTRANSACTABLE |

J

K

L

LISTENERTYPE

LOADREPORT

M

MAKETRANSACTABLE

MAPBINARY

MAPVARCHAR

N

NEST

NESTEDINTO

NEXTSIBLINGTABLE

O

ONPREVIEWCLOSE | OPTIMIZE | ORDERDIRECTION
OUTPUTPAGE | OUTPUTPAGECOUNT | OUTPUTTYPE

P

PAGENO | PAGETOTAL | PICTUREMARGIN
PICTURESPACING | PICTUREVAL | POLYPOINTS
PREVIEWCONTAINER | PRINTJOBNAME | PROGCACHE

Q

QUIETMODE

R

RECORDREFRESH | REFRESHALIAS | REFRESHCMD
REFRESHCMDDATASOURCE | REFRESHCMDDATASOURCETYPE | REFRESHIGNOREFIELDLIST
REFRESHTIMESTAMP | RENDER | REPORTBEHAVIOR
REPORTLISTENER | RESPECTNESTING | ROTATION

S

SCCDESTROY | SCCINIT | SELECTIONNAMESPACES
SENDGDIPLUSIMAGE | SETRESULTSET | SQLIDLEDISCONNECT
SUPPORTSLISTENERTYPE |  |

T

TABLEPROMPT

TIMESTAMPFIELDLIST

TWOPASSPROCESS

U

UNLOADREPORT | UNNEST | UPDATECMDREFRESHCMD
UPDATECMDREFRESHFIELDLIST | UPDATECMDREFRESHKEYFIELDLIST | UPDATESTATUS
USECODEPAGE | USECURSORSCHEMA | USETRANSACTIONS

V

VARBINARY

VARCHAR

VARCHARMAPPING

W

X

XMLNAMEISXPATH

Y

Z

See Also

Other Resources

What's New in Visual FoxPro
Reserved Words


How to: Submit Feedback about Help to Microsoft

Visual FoxPro 9.0
How to: Submit Feedback about Help to Microsoft
See Also

This version of the Visual FoxPro Help documentation contains many improvements and suggestions we have gathered from our customers. We value your feedback and welcome any additional suggestions about the documentation that can help make it easier to use.

Each topic in Visual FoxPro Help contains a "Send feedback on this topic to Microsoft" hyperlink on every topic page that you can use to submit your comments about the Help topic. Clicking the link opens a message template. The message template contains the necessary information about the topic so you do not have to type it in.

Note:
For product and technical support issues, please contact Microsoft product support services so they can be addressed appropriately. For more information, see Microsoft Visual FoxPro Technical Support.

To submit feedback about the documentation

  1. Locate the Help topic that you want to submit feedback for.

  2. Near the bottom of the topic, click Send feedback on this topic to Microsoft.

  3. Type your comments about how the topic can be improved or needs correction. Do not change the subject line of the message.

  4. When you are finished, click Send.

See Also

Other Resources

What's New in Visual FoxPro
Interactive Development Environment (IDE) Enhancements
Language Enhancements
Data Features Enhancements
Miscellaneous Enhancements
Changes in Functionality for the Current Release


Getting Started with Visual FoxPro

Visual FoxPro 9.0
Getting Started with Visual FoxPro

Microsoft Visual FoxPro is the object-oriented relational database management system that makes it possible for you to create state-of-the-art enterprise database solutions. Visual FoxPro includes professional productivity tools, documentation, and sample code for quickly building, managing, and deploying solutions.

In This Section

Locating Readme Files

Describes how to find the location of the Visual FoxPro Readme file.
Installing Visual FoxPro

Describes system requirements and how to install and add applications to Visual FoxPro.
Upgrading from Earlier Versions

Describes how Visual FoxPro protects your investment in applications built in previous versions of FoxPro.
How to: Convert Earlier Visual FoxPro Files

Describes how to convert files from earlier versions of FoxPro and Visual FoxPro.
Customizing the Visual FoxPro Environment

Explains how you can optimize your computer system, configure Visual FoxPro and development environment settings, restore your desktop, and how people with disabilities can improve accessibility to Visual FoxPro and Microsoft Windows.

Related Sections

What's New in Visual FoxPro

Describes the new features and enhancements included in this version of Visual FoxPro.
Using Visual FoxPro

Gives an overview of Visual FoxPro features, describes concepts and productivity tools for developing, programming, and managing high-performance database applications and components, and provides walkthroughs that help get you started. With the robust tools and data-centric object-oriented language that Visual FoxPro offers, you can build modern, scalable, multi-tier applications that integrate client/server computing and the Internet.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.
Samples and Walkthroughs

Contains Visual FoxPro samples and walkthroughs that you can use for experimenting with and learning Visual FoxPro features.


Locating Readme Files (Visual FoxPro)

Visual FoxPro 9.0
Locating Readme Files (Visual FoxPro)
See Also

The Readme.htm file is stored at the root of the Microsoft Visual FoxPro CD-ROM. Use your Internet browser to open and view the files.

To locate Readme files for additional products included in the Visual FoxPro package, see the root of each product CD-ROM.

See Also

Other Resources

Getting Started with Visual FoxPro


Installing Visual FoxPro

Visual FoxPro 9.0
Installing Visual FoxPro

The following sections describe information about installing Visual FoxPro.

In This Section

Requirements for Installing Visual FoxPro

Describes system requirements for installing Visual FoxPro.
How to: Install Visual FoxPro

Describes how to install Visual FoxPro.
How to: Install Additional Applications

Describes how to install other applications included with Visual FoxPro.
How to: Reinstall Visual FoxPro

Describes how to reinstall Visual FoxPro or install Visual FoxPro to another location.
Troubleshooting Installation

Describes potential issues you might encounter when installing Visual FoxPro.

Related Sections

Customizing the Visual FoxPro Environment

Explains how you can optimize your computer system, configure Visual FoxPro and development environment settings, restore your desktop, and how people with disabilities can improve accessibility to Visual FoxPro and Microsoft Windows.
Upgrading from Earlier Versions

Describes how Visual FoxPro protects your investment in applications built in previous versions of FoxPro.
Getting Started with Visual FoxPro

Provides information about where to find the Readme file, installing and upgrading from previous versions, configuring Visual FoxPro, and customizing the development environment.


Requirements for Installing Visual FoxPro

Visual FoxPro 9.0
Requirements for Installing Visual FoxPro
See Also

Visual FoxPro has the following minimum system requirements:

  • Computer: PC with a Pentium class processor.

  • Peripherals: Mouse or pointing device

  • Memory: 64 MB RAM (128 MB or higher recommended)

  • Hard disk space:

    • Visual FoxPro Prerequisites: 20 MB

    • Visual FoxPro Typical Install: 165 MB

    • Visual FoxPro Maximum Install: 165 MB

  • Video: 800 x 600 resolution, 256 colors (High color 16-bit recommended)

  • Operating system: Developing applications with Visual FoxPro is supported only on Microsoft Windows 2000 Service Pack 3 or later, Windows XP and Windows Server 2003. You can create and distribute run-time applications for Windows 98, Windows Me, Windows 2000 Service Pack 3 or later, Windows XP and Windows Server 2003.

    Note:
    Installation on Windows NT 4.0 Terminal Server Edition is not supported.

See Also

Other Resources

How to: Install Visual FoxPro
Installing Visual FoxPro


How to: Install Visual FoxPro

Visual FoxPro 9.0
How to: Install Visual FoxPro
See Also

You can install this version of Visual FoxPro from a CD-ROM or a network to a local hard drive. You must install Visual FoxPro on a local drive, not a mapped drive. There is no other preparation required before installing Visual FoxPro. You must have administrator privileges to install Visual FoxPro. It is recommended that you run with power-user privileges to use all the provided tools effectively.

You can safely install or uninstall using Visual FoxPro Setup. If you are upgrading Visual FoxPro, you must first uninstall the previous version of of the program. Though both versions of Visual FoxPro can exist on the same computer, you cannot install the current version of Visual FoxPro in the same directory as the previous version.

If you plan to publish XML Web services using Visual FoxPro, you might want to set up Internet Information Services (IIS) on a Windows 2000, Windows XP or Windows Server 2003 computer. Refer to your operating system documentation for instructions on how to set up and configure IIS.

Note:
Visual FoxPro setup no longer installs any Windows operating system Service Packs or versions of Internet Explorer. It is highly recommended that you install the latest versions of these components before installing Visual FoxPro. Additionally, Visual FoxPro 9.0 is supported only on Windows 2000 Service Pack 3 or later. For details about installing the latest Service Pack, visit the following Microsoft Web page at http://www.microsoft.com/windows2000/.

Full installation includes all Visual FoxPro program files, online help, and samples files.

To install Visual FoxPro

  1. Quit all open applications.

    Note:
    If you use a virus protection program on your computer, override it or turn it off before running the Installation wizard. The Installation wizard might not run properly with virus protection turned on. After installation, be sure to restart your virus protection program.

  2. Insert the Visual FoxPro CD.

    The Visual FoxPro Setup start page appears automatically.

  3. Click Install Visual FoxPro to launch Visual FoxPro Setup.

  4. To determine if you need additional components, click Prerequisites to display any necessary components.

  5. Click Install Now! to install any new components. If Visual FoxPro Prerequisites needs to only update components, click Update Now!

  6. You might need to restart your computer. When finished, click Done.

    Visual FoxPro Setup reappears.

  7. To continue installation, click Visual FoxPro.

  8. After accepting the End User License Agreement and entering the Product Key and your name, click Continue.

    Note:
    Visual FoxPro cannot be installed on a mapped drive. You must install Visual FoxPro on a local drive. Do not attempt to use the Map Network Drive functionality in Setup.

  9. On the Options page, select the features you want to install and click Install Now! to continue.

  10. When finished, click Done to return to Visual FoxPro Setup. Click Exit to return to the Visual FoxPro Setup start page.

If you uninstall Visual FoxPro while the previous version of Visual FoxPro exists on your computer, certain shared registry keys used by the previous version of Visual FoxPro are removed. You must reinstall these critical shared registry keys.

If you run Visual FoxPro from the Start menu, Visual FoxPro Setup automatically reinstalls these keys. If you start Visual FoxPro using other means, such as running the application executable directly, the setup program does not start automatically. You should use Add/Remove Programs in the Control Panel and the following steps to reinstall the registry keys manually:

To manually reinstall Visual FoxPro 9.0 registry keys

  1. From the Start menu, click Control Panel.

  2. Click Add/Remove Programs.

  3. Click Change/Remove for Microsoft Visual FoxPro 9.0.

  4. Click Visual FoxPro and Repair/Reinstall.

See Also

Other Resources

Requirements for Installing Visual FoxPro
How to: Install Additional Applications
How to: Reinstall Visual FoxPro
Troubleshooting Installation
Installing Visual FoxPro


How to: Install Additional Applications

Visual FoxPro 9.0
How to: Install Additional Applications
See Also

This release includes copies of additional software that you can install and use with Visual FoxPro. These include:

  • InstallShield Express Limited Edition

    Provides the capability to package and deploy the applications that you create using Visual FoxPro. Visual FoxPro includes the InstallShield Express 5.0 Visual FoxPro Limited Edition.

    Note:
    The limited and full editions of InstallShield Express 5.0 are considered two versions of the same product and cannot coexist. If you install one version on a computer where another already exists, the original is uninstalled automatically. Because the limited edition contains fewer features than the full edition, you should keep the full edition on your computer.

  • Microsoft SOAP Toolkit 3.0 Samples

    Provides samples for demonstrating how to consume and publish XML Web services. Visual FoxPro Prerequisites installs the core SOAP Toolkit 3.0 components needed to access and publish XML Web services in Visual FoxPro.

  • Microsoft SQL Server 2000 Desktop Engine (MSDE)

    Provides a personal version of SQL Server.

To install InstallShield Express Limited Edition

  1. Insert the Visual FoxPro CD.

    The Visual FoxPro Setup start page opens automatically.

  2. Click Install InstallShield Express.

  3. Follow the instructions in the InstallShield Express installation wizard.

You can also locate the Setup.exe file for InstallShield Express in the InstallShield folder on the Visual FoxPro CD.

Note:
Visual FoxPro 9.0 installs its redistributable merge modules in the same location as Visual FoxPro 8.0.

The version of InstallShield Express included with Visual FoxPro 9.0 automatically uses the Visual FoxPro 9.0 merge module location.

Note:
Visual FoxPro 9.0 requires certain merge modules when creating a Visual FoxPro 9.0 redistributable custom application setup program using InstallShield Express.

You need to include the following merge modules when creating your custom setup program:

  • Microsoft Visual FoxPro 9 Runtime Libraries

  • Microsoft Visual C Runtime Library 7.1

  • GDI Plus Redist

  • MSXML 4.0

  • MSXML 3.0 (needed only for CURSORTOXML functions)

  • Microsoft Visual FoxPro 9 Runtime Language Libraries (specific language library files that may be needed for international applications)

  • Reporting Applications (needed for Visual FoxPro 9.0 reporting engine)

Note:
MSXML 4.0 consists of two merge modules (msxml4sxs32.msm and msxml4sys32.msm). MSXML 3.0 consists of three merge modules (msxml3_wim32.msm, msxml3inf_wim32.msm and wdstddll_wim32.msm).

To install SOAP Toolkit 3.0 Samples

  1. Insert the Visual FoxPro CD.

    The Visual FoxPro Setup start page opens automatically.

  2. Click Install SOAP Toolkit 3.0 Samples.

  3. Follow the instructions in the SOAP Toolkit 3.0 Samples Setup Wizard.

You can also locate the Soapsdk.msi and Soapsamp.msi files for the SOAP Toolkit in the SOAPToolkit folder on the Visual FoxPro CD.

To install MSDE

  1. Insert the Visual FoxPro CD.

    The Visual FoxPro Setup start page opens automatically.

  2. Click Install Microsoft SQL Server Desktop Engine (MSDE) and follow the installation instructions that appear in the Readme file.

You can locate the Setup.exe file for MSDE in the SQLMSDE folder on the Visual FoxPro CD.

Note:
Visual FoxPro includes Microsoft SQL Server 2000 Desktop Engine Service Pack 3.0a. To make sure you have the most recent version and Service Pack installed, visit the Microsoft SQL Server Web page at . In addition, if you are distributing custom Visual FoxPro applications that require MSDE, you can obtain the redistributable merge modules from the Microsoft SQL Server Web page for use with Windows Installer-based setup programs.

See Also

Other Resources

How to: Install Visual FoxPro
Installing Visual FoxPro


How to: Reinstall Visual FoxPro

Visual FoxPro 9.0
How to: Reinstall Visual FoxPro
See Also

You can reinstall Visual FoxPro by uninstalling it and then installing it again. You can uninstall Visual FoxPro from the Start menu or from the original installation disk.

To uninstall Visual FoxPro

  1. On the Start menu, click Control Panel.

  2. In the Control Panel window, double-click Add or Remove Programs.

    The Add or Remove Programs window opens.

  3. In the Currently installed programs list, click the version of Microsoft Visual FoxPro you want to uninstall, and then Change/Remove.

If you reinstall Visual FoxPro or reinstall to another location, you might want to clean your user settings and other files installed by Visual FoxPro before reinstalling.

You can remove these files by deleting the contents of the ...\Application Data\Microsoft\Visual FoxPro folder inside your user settings folder. To determine the location of the Application Data folder, type ? HOME(7) in the Command window. These files include your FoxUser.* resource files, which contain user settings, and folders for the Toolbox and Task Pane.

However, it is possible that your resource files are in another location. You can determine their location by typing the following in the Command window:

Copy Code
? SYS(2005)

You should delete old Code Reference files that might be associated with projects in the project directories. These are labeled as projectname_ref.* files. You might also need to restore the default Visual FoxPro registry settings.

Visual FoxPro includes the VFPClean.app tool so you can make sure all core Xbase and other files are set appropriately.

To run VFPClean.app

  • Type the following line of code in the Command window:

    Copy Code
    DO HOME()+"VFPCLEAN.APP"

See Also

Other Resources

How to: Install Visual FoxPro
Installing Visual FoxPro


Troubleshooting Installation

Visual FoxPro 9.0
Troubleshooting Installation
See Also

You might encounter the following issues when installing Visual FoxPro:

  • If you cannot run Visual FoxPro and do not see error messages telling you what is wrong, the problem might be in your computer's ROM BIOS or the video driver you are using.

  • If you are using an extended keyboard, be sure it is compatible with the ROM BIOS. In addition, make sure that you are using a standard VGA or Super VGA Windows video driver.

  • If you get a "stack overflow" error message, your video driver is out of date or not designed for your video card. To correct this problem, update the video driver.

  • For additional information, see the Visual FoxPro Readme at the root of the Visual FoxPro installation CD.

See Also

Other Resources

Installing Visual FoxPro


Upgrading from Earlier Versions

Visual FoxPro 9.0
Upgrading from Earlier Versions
See Also

Microsoft Visual FoxPro protects your investment in applications built with previous versions of FoxPro. In Visual FoxPro, you can run many applications that were written in earlier versions with little or no conversion. You can modify and enhance applications using the Visual FoxPro language, knowing that most extensions to the language do not affect backward compatibility. In addition, you can convert FoxPro screens, projects, and reports to Visual FoxPro format.

However, it is possible that some behavior or feature changes in the current version of Visual FoxPro might affect existing Visual FoxPro source code. Therefore, you should review the new features, enhancements, and most recent behavior changes for this version. For more information, see What's New in Visual FoxPro and Changes in Functionality for the Current Release.

Conversion to Visual FoxPro Format

If you choose to convert your dBASE or FoxPro files to the Visual FoxPro format, you can take advantage of the unique features of Visual FoxPro. You can run many files from some previous versions of FoxPro directly; others require varying levels of conversion.

You can convert most projects or components created using previous versions of Visual FoxPro simply by opening or recompiling them in this version of Visual FoxPro. When you recompile components, such as forms, screens, or reports, some modifications may be necessary. You can make modifications to these components in the same way you modify the components of this version of Visual FoxPro.

You can find additional information about upgrading from previous versions of Visual FoxPro on the Microsoft Developer Network (MSDN) Web site at http://msdn.microsoft.com. You can search the MSDN Archive for documentation of previous versions of Visual FoxPro.

See Also

Other Resources

Getting Started with Visual FoxPro
Overview of Visual FoxPro Features
Installing Visual FoxPro
Customizing the Visual FoxPro Environment
Optimizing Your System


How to: Convert Earlier Visual FoxPro Files

Visual FoxPro 9.0
How to: Convert Earlier Visual FoxPro Files
See Also

You can explicitly convert FoxPro 2.6 and Visual FoxPro 3.0 files to the current Visual FoxPro format, which is necessary when you want to use these files with later versions of Visual FoxPro. Files that are created from later versions are converted automatically.

To convert FoxPro 2.6 and Visual FoxPro 3.0 files

  1. On the File menu, click Open.

  2. In the Open dialog box, browse for and select the file.

    The Visual FoxPro Converter dialog box opens. For more information, see Visual FoxPro Converter Dialog Box.

  3. In the Visual FoxPro Converter dialog box, select the options you want.

  4. To complete the file conversion, click Continue.

    Note:
    If you are converting Macintosh or MS-DOS files that have never contained Windows records, the Visual FoxPro Transporter dialog box appears. For more information, see Visual FoxPro Transporter Dialog Box.

You can also convert FoxPro 2.6 and Visual FoxPro 3.0 files by typing one of the following commands with the file name in the Command window:

  • MODIFY PROJECT Command

  • MODIFY FORM Command

  • MODIFY REPORT Command

  • MODIFY LABEL Command

See Also

Other Resources

Getting Started with Visual FoxPro
Upgrading from Earlier Versions


Customizing the Visual FoxPro Environment

Visual FoxPro 9.0
Customizing the Visual FoxPro Environment

After you install Visual FoxPro, you might want to customize your development environment. You can also specify configuration settings that load when you start Visual FoxPro.

For information on optimizing your Visual FoxPro applications, see Optimizing Applications.

In This Section

Optimizing Your System

Explains how to get maximum performance by optimizing your operating system, Visual FoxPro, and your application.
Visual FoxPro Configuration

Explains how changing the configuration of your copy of Visual FoxPro affects the way it looks and behaves, such as establishing default locations for files used with Visual FoxPro, altering how your source code looks in an edit window, and displaying the format of dates and times.
Visual FoxPro Environment Settings

Describes different ways to change Visual FoxPro environment settings such as using the Options dialog box, setting configuration options at program startup, and using command-line options. You can configure Visual FoxPro toolbars, dock windows, set editor options, and customize the appearance of your applications without altering code.
Restoring the Visual FoxPro Interactive Environment

Describes how to close down all program operations and clear the Visual FoxPro desktop to return to its interactive state.
Accessibility for People with Disabilities

Provides information about features, products, and services that make Microsoft Visual FoxPro and the Windows operating system more accessible for people with disabilities.

Related Sections

Getting Started with Visual FoxPro

Provides information about installing, upgrading, and customizing Visual FoxPro.
Using Visual FoxPro

Explains how Visual FoxPro provides the tools you need to create and to manage high-performance database applications and components.
Samples and Walkthroughs

Describes how to create different types of applications and components with step-by-step guides.
Overview of Visual FoxPro Features

Describes how Visual FoxPro gives you more of everything you have come to expect in a database management system (DBMS) — speed, power, and flexibility.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.
Development Productivity Tools

Explains that Visual FoxPro provides developer tools for application development within the FoxPro application and the FoxPro language.


Optimizing Your System

Visual FoxPro 9.0
Optimizing Your System

Visual FoxPro is designed to be a fast relational database development system. However, applications you create with Visual FoxPro can have varying requirements and purposes. Therefore, you might want to optimize the operating system, Visual FoxPro, or your application for maximum performance.

In This Section

Optimizing the Operating Environment

Describes how to optimize computer hardware and and operating environment for running Visual FoxPro.
Optimizing Visual FoxPro Startup Speed

Describes how to optimize startup and operating speed in Visual FoxPro.
Optimizing Visual FoxPro in a Multiuser Environment

Describes how to improve performance when running Visual FoxPro in a multiuser environment.

Related Sections

Customizing the Visual FoxPro Environment

Provides information about setting environment options, accessibility features, and configuration.
Getting Started with Visual FoxPro

Discusses how to get started, including information about installing, upgrading, and customizing Visual FoxPro to create state-of-the-art enterprise database solutions.
What's New in Visual FoxPro

Lists the new features and enhancements made to this version of Microsoft Visual FoxPro.
Using Visual FoxPro

Provides links to information on Visual FoxPro programming features that are designed to improve developer productivity, including Access and Assign methods, support for more graphic file formats, and language to simplify programming tasks.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Discusses how to access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Optimizing the Operating Environment

Visual FoxPro 9.0
Optimizing the Operating Environment
See Also

You can optimize Visual FoxPro performance by maximizing your computer's hardware and operating environment. The following sections describe how you can optimize these areas:

  • Maximizing Memory and Virtual Memory

  • Managing Your Hard Disk

Maximizing Memory and Virtual Memory

Providing your computer with as much memory as possible is the most effective way to optimize your system for Visual FoxPro. You can also use memory more effectively by closing all other running applications on your computer. To maximize the use of your computer's memory while running Visual FoxPro, follow these guidelines:

  • Do not run other Windows applications while running Visual FoxPro.

  • Use only those memory-resident programs needed for operation.

  • Simplify the screen display.

You can free memory by simplifying the way windows and screen backgrounds display on your computer monitor.

  • Use a color or a pattern for the desktop background instead of wallpaper.

  • Use the lowest-resolution display that is practical for you. The higher resolution of the display, the more memory your computer requires and the slower your graphics and user-interface elements appear. For VGA-compatible displays that use an extended mode driver, such as Video 7 or 8514, using the standard VGA driver ensures faster display performance but provides lower resolution and less color support.

To increase the number of applications that you can run simultaneously, Microsoft Windows supports virtual memory by swapping segments of code that is the least recently used from memory to the hard disk in the form of a paging file. As a rule, the default settings in the Windows operating system for managing virtual memory meet the requirements of most users and are the recommended settings.

Note:
The paging file does not improve Visual FoxPro performance and is not a substitute for more memory.

Managing Your Hard Disk

Managing your hard disk can improve overall product speed. To get the best performance from your hard disk, provide a generous amount of disk space. If your hard disk has little free space, you can increase Visual FoxPro performance by removing unnecessary data or by purchasing a hard disk with greater capacity.

Disk input/output performance degrades significantly when a hard disk is nearly full. The more free hard disk space that is available, the more likely it is that contiguous blocks of disk space are available. Visual FoxPro uses this space for changes and additions to database, table, index, memo, and temporary files. Increasing free hard disk space improves performance of any commands that change or add to your files. More disk space also decreases the time required to read those files in response to your queries.

The way that Windows and Visual FoxPro manage files on disk can greatly affect the performance of your application. The following sections discuss managing files in directories and temporary files:

  • Managing Files in Directories

  • Managing Temporary Files

Managing Files in Directories

As a directory becomes increasingly congested with files, the operating system takes longer to find files. The speed of your system when searching directories is a factor that Visual FoxPro does not control. To improve the speed of directory searches, reduce the number of files in your directories by performing the following actions:

  • Use the Visual FoxPro Project Manager to create and manage your files, segregate program files into separate directories, and avoid creating numerous generated files.

  • When you want to distribute your application, create an application or an executable (.exe) file instead of numerous individually generated files.

    This process decreases the number of files in your application's subdirectories and increases performance.

  • If you delete a large number of files in one directory, copy the remaining files into a new directory or optimize the directory using a defragmenting utility program.

    Note:
    Deleting files from a directory does not automatically speed directory searching. When a file is deleted, the file is only marked for deletion and is still included in directory searches.

  • When saving files, use short file paths to increase performance.

    For example, suppose you have a file path "C:\Program Files\Microsoft Visual FoxPro\...", which is a very long file path. Try to use shorter file paths.

Managing Temporary Files

Visual FoxPro creates temporary files for a variety of operations. For example, Visual FoxPro creates temporary files during editing, indexing, and sorting. Text editing sessions can also create a temporary or backup (.bak) copy of the edited file. By default, Visual FoxPro creates its temporary files in the same directory that Windows stores its temporary files unless you specifically designate an alternate location.

Tip:
In most cases, you should specify one location for all Visual FoxPro temporary files. Make sure that the location you specify contains enough space for all possible temporary files.

For more information, see How to: Specify the Location of Temporary Files.

Searching for Temporary Files

When Visual FoxPro searches for temporary files, for example, when you use the SYS(2023) - Temporary Path function to retrieve the temporary files path or when the TMPFILES, EDITWORK, PROGWORK, and SORTWORK settings in a Visual FoxPro configuration file do not specify a different location, the Windows API GetTempPath is used to search for the path containing the temporary files. GetTempPath searches a sequence of variables that differ depending on the operating system. Microsoft Windows 2000 and later include user variables that store the location of temporary files, while Microsoft Windows 95, 98, and Me include only global system environment variables for this purpose.

On Windows 2000 and later, GetTempPath, and therefore, SYS(2023), TMPFILES, EDITWORK, PROGWORK, and SORTWORK, searches the TMP user variable for the location of temporary files by default. If the TMP user variable does not specify a location, Visual FoxPro searches the following variables in a specific order:

  • TMP system variable.

  • TEMP user variable.

  • TEMP system variable.

If these variables do not specify a location, the location for storing temporary files defaults to the home drive and path, or the Temp folder in the user's Documents and Settings directory.

Note:
If more than one value is specified for TMP or TEMP, then the first value is used.

On Windows 95, 98, and Me, GetTempPath searches the TMP and TEMP global system variables in that order and then searches the current directory.

For more information, see SYS(2023) - Temporary Path and Special Terms for Configuration Files.

See Also

Other Resources

Optimizing Visual FoxPro in a Multiuser Environment
Optimizing Visual FoxPro Startup Speed
Optimizing Your System


Optimizing Visual FoxPro Startup Speed

Visual FoxPro 9.0
Optimizing Visual FoxPro Startup Speed
See Also

Though Visual FoxPro is always fast, you can optimize the startup and operating speed. This section describes enhancing Visual FoxPro performance by managing startup speed and optimizing SET commands.

Managing Startup Speed

The time required to load and start Visual FoxPro relates to the physical size of Visual FoxPro, the length of the PATH statement in effect, the number of items to be found at startup, and other factors. You can control the load size, the search path, component file locations, and the startup SET command values of Visual FoxPro.

Managing File Locations

Visual FoxPro stores the FoxUser.dbf file, which contains user settings, in the user's Application Data directory by default. You can display this location by typing ? HOME(7) in the Command window. Visual FoxPro searches for the FoxUser.dbf and Config.fpw files in the following places:

  • In the startup application or executable file, if any.

    For example, you can start a Visual FoxPro application by typing the following code on the command line:

    Copy Code
                      VFPversionNumber.exe MyApp.app
    – or –

    Copy Code
    VFPversionNumber.exe MyApp.exe
    If the startup application or executable file contains a Config.fpw file, the configuration file is always used. You can override settings in a Config.fpw file that are bound inside an application by specifying an external Config.fpw file, using the -C command-line switch when starting an application or Visual FoxPro.

  • In the working directory.

  • Along the path established with the PATH environment variable.

  • In the directory containing Visual FoxPro.

Controlling File Loading

You can also speed startup by preventing Visual FoxPro from loading files you don't plan to use. If your application does not use the FoxUser or FoxHelp file, disable them in the Config.fpw file by using the following commands:

Copy Code
RESOURCE = OFF
HELP = OFF

Visual FoxPro seeks all other Visual FoxPro components (GENXTAB, CONVERT, and so on) only in the Visual FoxPro directory. If you place components elsewhere, you must explicitly identify the path to those components in your Config.fpw file. For example, you might specify these locations:

Copy Code
_TRANSPORT = c:\migrate\transport.prg
_GENXTAB = c:\crosstab\genxtab.prg
_FOXREF = c:\coderefs\foxref.app

You can use the environment variable FOXPROWCFG to explicitly specify the location of Config.fpw. For details about the FOXPROWCFG variable, see Customizing the Visual FoxPro Environment.

Optimizing the Load Size of Visual FoxPro

If you don't plan on using any of the Visual FoxPro components listed previously, set them to an empty string to speed startup.

To optimize the load size of Visual FoxPro, use the following syntax:

Copy Code
          cFileVariable
          = ""

Replace cFileVariable with _TRANSPORT, _CONVERT, or other variables as appropriate.

Optimizing Key SET Commands

You can optimize the operation of Visual FoxPro by tuning the values of certain SET commands.

The following table shows SET commands that have the greatest effect on performance, and their settings for maximum performance. You can specify SET command values by including them in the Config.fpw file, by typing them in the Command window, or by setting them in the Options dialog box.

Command Settings for Maximum Performance

SET Command | Performance Setting
SET ESCAPE Command | ON
SET OPTIMIZE Command | ON
SET REFRESH Command | 0,0
SET SYSMENU Command | DEFAULT
SET TALK Command | OFF
SET VIEW Command | OFF

See Also

Other Resources

Optimizing Your System
Optimizing Visual FoxPro in a Multiuser Environment
Optimizing the Operating Environment
Customizing the Visual FoxPro Environment
SET ESCAPE Command
SET REFRESH Command
SET SYSMENU Command
Command Window


Optimizing Visual FoxPro in a Multiuser Environment

Visual FoxPro 9.0
Optimizing Visual FoxPro in a Multiuser Environment
See Also

When you run Visual FoxPro or Visual FoxPro applications in a multiuser environment, you can improve performance by managing storage of temporary files and controlling the way tables are shared.

Managing Temporary Files

In most multiuser environments, it is recommended that you save temporary files to local disks or memory when networked computers contain large amounts of free disk space. Redirecting storage of temporary files can improve performance by reducing frequent access to the network drive.

On small networks with older networked computers and slow hard disks, you might experience better performance by leaving Visual FoxPro temporary files on the file server; however, when in doubt, direct temporary files to the local disk. When working on large, heavily used networks, always redirect temporary files to the local disk.

By saving all temporary files to a single directory on a local hard drive, you can safely erase the contents of the temporary file directory on the file server prior to each Visual FoxPro session. This action purges the system of any temporary files that were created but not erased by Visual FoxPro due to a system reboot or power loss.

For more information about temporary files, see Optimizing the Operating Environment and How to: Specify the Location of Temporary Files.

Sharing Tables

If users share tables on a network, the way you manage access to them can affect performance.

  • Avoid opening and closing tables repeatedly.

  • Buffer write operations to tables that are not shared.

  • Provide exclusive access to tables.

  • Limit the time on locking tables.

Providing Exclusive Access

You can enhance performance for the APPEND, REPLACE, and DELETE commands and operations that run at times when no other users require access to the data, for example, overnight updates, by opening data files for exclusive use. When tables are open for exclusive use, performance improves because Visual FoxPro does not need to test the status of record or file locks.

To open data files for exclusive use, use the EXCLUSIVE clause in the USE and OPEN DATABASE commands. For more information, see USE Command and OPEN DATABASE Command.

Limiting the Time on Locking Tables

You can reduce contention between users for write access to a table or record by shortening the amount of time for locking a record or table. Instead of locking a record while the user edits it, lock the record only after it has been edited. Using optimistic row buffering provides the shortest amount of time that records are locked. For more information, see Buffering Data.

See Also

Other Resources

Optimizing Applications in Multiuser Environments
Optimizing Your System


Visual FoxPro Configuration

Visual FoxPro 9.0
Visual FoxPro Configuration
See Also

The configuration of Visual FoxPro determines how your copy of Visual FoxPro looks and behaves. For example, you can establish the default locations for files used with Visual FoxPro, how your source code looks in an edit window, and the format of dates and times.

You can make changes to the Visual FoxPro configuration that exist for the current session only (temporary), or specify them as the default settings for the next time you start Visual FoxPro (permanent). If the settings are temporary, they are stored in memory and are discarded when you quit Visual FoxPro.

If you make permanent settings, they are stored in the Microsoft Windows registry or Visual FoxPro resource file. The Windows registry is a database that stores configuration information about the operating system, all Windows applications, OLE, and optional components such as ODBC. For example, the registry is where Windows stores the associations between file name extensions and applications so that when you click a file name, Windows can launch or activate the appropriate application.

For an example of how to change the registry, you can examine Registry.prg in the \Samples\Classes directory, which contains numerous methods based on Windows API calls and makes it possible for you to manipulate the Windows registry.

Similarly, Visual FoxPro stores its application-specific configuration information in the registry. When you start Visual FoxPro, the program reads the configuration information in the registry and sets the configuration according to those settings. After reading the registry, Visual FoxPro also checks for a configuration file, which is a text file in which you can store configuration settings to override the defaults stored in the registry. After Visual FoxPro has started, you can make additional configuration settings using the Options Dialog Box or SET commands. For more information, see How to: View and Change Environment Settings.

Note:
The run-time version of Visual FoxPro does not read the Windows registry when starting up, as registry settings are designed primarily to configure the development environment. If you intend to distribute your Visual FoxPro applications using a run-time library, you can establish configuration settings in two ways: with a configuration file, or with a program that manipulates the Windows registry on the user's computer.

Visual FoxPro also maintains a resource file, Foxuser.dbf, that stores information about the current state of the program when you quit. For example, the resource file contains information about the location and size of the Command window, current keyboard macros, the toolbars that are displayed, and so on. The Foxuser.dbf file is an ordinary Visual FoxPro table, which you can read and change as required by your application.

Tip:
If the data in the Foxuser.dbf file becomes corrupted or invalid, it can cause Visual FoxPro to behave in an erratic manner. If you do not manually store anything in the table, for example keyboard macros, deleting the table might help.

See Also

Other Resources

Customizing the Visual FoxPro Environment
How to: View and Change Environment Settings
Options Dialog Box
ODBC Registry Foundation Class
Command Window
How to: Change Configuration Settings in the Windows Registry
SET RESOURCE Command


Visual FoxPro Environment Settings

Visual FoxPro 9.0
Visual FoxPro Environment Settings

You can make changes to the Visual FoxPro environment by using the Options dialog box, editing the Windows registry, overriding default configuration settings, customizing the Project Manager, and configuring Visual FoxPro toolbars.

In This Section

How to: View and Change Environment Settings

Describes how to view and change environment settings.
How to: Specify the Location of Temporary Files

Describes how to change the default location for saving temporary files in Visual FoxPro.
How to: Change Configuration Settings in the Windows Registry

Describes how configure Visual FoxPro by making changes to the Windows registry using the Registry Editor.
Setting Configuration Options at Startup

Describes how to set or override default configuration opens when starting Visual FoxPro.
How to: Specify the Configuration File

Describes how to specify or suppress configuration files when starting Visual FoxPro.
How to: Create a Configuration File

Describes how to create configuration files to use when starting Visual FoxPro.
Special Terms for Configuration Files

Provides a list of special terms you can use in configuration files.
How to: Use Command-Line Options When Starting Visual FoxPro

Explains how to specify startup options by using a command-line switch.
How to: Configure Visual FoxPro Toolbars

Describes how to customize, display, and hide toolbars.
How to: Dock Windows

Describes how to dock Visual FoxPro windows to the main Visual FoxPro window or to each other.
How to: Set Editor Options

Explains how to configure Visual FoxPro editors.
How to: Display and Print Source Code in Color

Describes how to configure settings for displaying and printing program files, methods, stored procedures, and memos in color.
Automating Keystroke Tasks with Macros

Describes how to record and save keystrokes using macros.

Related Sections

Customizing the Visual FoxPro Environment

Explains customizing development environment settings.
Visual FoxPro Configuration

Explains configuring Visual FoxPro.
Restoring the Visual FoxPro Interactive Environment

Describes closing operations and clearing the Visual FoxPro desktop to return to its interactive state.


How to: View and Change Environment Settings

Visual FoxPro 9.0
How to: View and Change Environment Settings
See Also

To view and change environment settings, use the Options dialog box. The Options dialog box contains a series of tabs representing different categories of environment options.

To display the Options dialog box

  • From the Tools menu, choose Options.

The Options dialog box appears and displays tabs from which you can choose desired settings. For details about options you can set using each tab, see the Options Dialog Box.

Displaying Environment Settings

When Visual FoxPro is running, you can verify environment settings by using the Options dialog box or the DISPLAY STATUS Command, or by displaying the values of individual SET Commands.

To display multiple environment settings

  • From the Tools menu, choose Options to display the Options dialog box and view the current settings.

    – OR –

  • Type DISPLAY STATUS in the Command window.

To display individual environment settings

  • Use the SET( ) Function in the Command window to display the current value of any SET commands.

For example, to view the current status of SET TALK, type:

Copy Code
? SET("TALK")
Note:
Because settings are valid only for the current data session, you must capture your settings and place them in a program or a form's Init event code for every private data session.

For more information, see SET Command Overview.

To echo Options dialog box settings to the Command window

  1. In the Options dialog box, make setting choices.

  2. Hold down the SHIFT key and choose OK.

    The settings are echoed to the Command window.

  3. Copy the setting commands from the Command window.

Saving Environment Settings

You can save the settings you make in the Options dialog box for the current data session or as default (permanent) settings for your copy of Visual FoxPro.

To save settings for the current session only

  1. In the Options dialog box, make setting choices.

  2. Choose OK.

When you save settings for the current session only, they remain in effect until you quit Visual FoxPro (or until you change them again). To save changes permanently, save them as default settings; this stores them in the Windows registry.

To save current settings as default settings

  1. In the Options dialog box, make setting changes.

  2. Choose Set As Default.

    Note:
    The Set as Default button is disabled until you make a change to the current settings.

You can override default settings by issuing SET commands or by specifying a configuration file when you start Visual FoxPro. For details, see Setting Configuration Options at Startup.

Setting the Environment Using the SET Command

You can programmatically modify most options displayed on the tabs in the Options dialog box using SET commands or by assigning a value to a system variable.

Note:
When you configure the environment using SET commands, the settings take effect only for the current session of Visual FoxPro. When you quit the program, your settings are discarded, and you must reissue the SET commands. However, you can automate this process by issuing SET commands at startup or using a configuration file. For details, see Setting Configuration Options at Startup.

Tip:
To save a configuration made with SET commands, display the Options dialog box and save your settings there.

To set the environment programmatically

  • Use the SET commands that you want.

For example, the following lines of code set a default path, add a clock to the status bar and use a year-month-date (yy.mm.dd) format for dates:

Copy Code
SET DEFAULT TO HOME()+"\VFP"
SET CLOCK ON
SET DATE TO ANSI

For more information, see SET Command Overview.

See Also

Other Resources

Visual FoxPro Environment Settings
Get Application Information from the Windows Registry
How to: Change Configuration Settings in the Windows Registry
DISPLAY STATUS Command


How to: Specify the Location of Temporary Files

Visual FoxPro 9.0
How to: Specify the Location of Temporary Files
See Also

You can specify a different location for temporary files using the Visual FoxPro interface or by using the TMPFILES, EDITWORK, PROGWORK, and SORTWORK settings in a Visual FoxPro configuration file.

To specify the location of temporary files

  1. On the Tools menu, click Options.

  2. In the Options dialog box, click the File Locations tab.

  3. In the File Type list, click Temporary Files, then Modify.

  4. In the Change File Location dialog box, type a new location or click the ellipsis (...) button to browse and select a location for temporary files.

For more information, see Options Dialog Box and File Locations Tab, Options Dialog Box.

See Also

Other Resources

Optimizing the Operating Environment
Special Terms for Configuration Files
Setting Configuration Options at Startup
Visual FoxPro Environment Settings


How to: Change Configuration Settings in the Windows Registry

Visual FoxPro 9.0
How to: Change Configuration Settings in the Windows Registry
See Also

You can set the Visual FoxPro configuration by making changes directly in the Windows registry. To change the Windows registry, use the Registry Editor, a utility provided with Windows.

Note:
Use caution when changing the Windows registry. Changing the wrong registry entry or making an incorrect entry for a setting can introduce an error that prevents Visual FoxPro, or even Windows itself, from starting or working properly.

To change configuration settings in the registry

  1. In Windows, start the Registry Editor.

  2. In HKEY_CURRENT_USER node, browse to the Software\Microsoft\Visual FoxPro directory and open the folder for the current version of Visual FoxPro.

  3. In the Options folder, double-click the name of the setting to change, and then enter a new value.

  4. Close the Registry Editor.

    Your change will take effect the next time you start Visual FoxPro.

You can also make changes to the registry by calling Windows APIs from a Visual FoxPro program.

See Also

Other Resources

Visual FoxPro Environment Settings
Get Application Information from the Windows Registry
Accessing APIs
SYS(3056) - Read Registry Settings


Setting Configuration Options at Startup

Visual FoxPro 9.0
Setting Configuration Options at Startup
See Also

You can establish configuration settings when you first start the program, which allows you to override default settings.

Using SET Commands in Applications

One way to establish configuration settings is to issue one or more SET commands when your application starts. For example, to configure your system to display a clock in the status bar when the application starts, you can issue this SET command:

Copy Code
SET CLOCK ON

The exact point at which you issue the SET command depends on your application. In general, you issue SET commands from your application's main program file, which is the program or form that controls access to the rest of your application. You can also issue SET commands from the Load or Init events of the form. If you are using private data sessions, it may be necessary to make these settings in the BeforeOpenTables Event of your DataEnvironment object. For details about specifying a main file for an application, see Compiling an Application .

If your application has a form set as main in the project manager, and it then launches a menu, you can add SETUP commands by entering them in the menu's Setup option. For details see How to: Add Setup Code to a Menu System in Designing Menus and Toolbars .

Tip:
An efficient way to manage SET commands for startup is to create a procedure that contains all the commands that you want to issue. You can then call the procedure from the appropriate point in your application. Keeping all the SETUP commands in a single procedure makes it easier to debug and maintain your configuration settings. You can also put the code in the class on which your application object is based, or the class on which your forms are based.

Using a Configuration File

In addition to setting the Visual FoxPro environment using the Options dialog box or SET commands, you can establish preferred settings and save them in one or more configuration files. A Visual FoxPro configuration file is a text file in which you can specify values for SET commands, set system variables, and execute commands or call functions. Visual FoxPro reads the configuration file when starting up, establishing the settings and executing the commands in the file. Settings made in the configuration file override default settings made in the Options dialog box (and stored in the Windows registry).

Using a configuration file provides several advantages. You can:

  • Override the default settings established in the Options dialog box.

  • Maintain several different configuration files, each with different settings, so that Visual FoxPro can load a configuration suitable to a particular user or project.

  • Make changes more easily than if you establish settings with the SET commands in the program initialization sequence.

  • Start a program or call a function automatically when Visual FoxPro starts.

For instructions about working with configuration files, see How to: Create a Configuration File and How to: Specify the Configuration File.

See Also

Other Resources

How to: Use Command-Line Options When Starting Visual FoxPro
Compiling an Application
How to: Add Setup Code to a Menu System
Designing Menus and Toolbars
_STARTUP System Variable
Visual FoxPro Environment Settings


How to: Specify the Configuration File

Visual FoxPro 9.0
How to: Specify the Configuration File
See Also

When Visual FoxPro starts, you can specify a configuration file or bypass all configuration files, allowing Visual FoxPro to use its default settings.

When Visual FoxPro loads a configuration file, the settings in that file take precedence over corresponding default settings made in the Options dialog box.

To specify a configuration file

  • In the command line that starts Visual FoxPro, specify the -C switch and the name of the configuration file that you want to use (including a path if necessary). Do not put a space between the switch and the file name.

    -or-

  • In Windows, double-click the name of the configuration file to use. Visual FoxPro will start using the configuration file you have selected.

If you want to avoid using any configuration file, including the default file Config.fpw, you can suppress all configuration files. This causes Visual FoxPro to use only the default settings established in the Options dialog box.

To suppress a configuration file

  • In the command line that starts Visual FoxPro, add the -C switch with nothing after it.

    For example, to avoid any configuration file found in the startup directory or the system path, use this command line:

    Copy Code
    VFPVersionNumber.exe -C

Specifying an External Configuration File

You can use an external configuration file in addition to an internal configuration file in circumstances where you need to configure settings separately. For example, setting SCREEN=OFF should be performed in an internal configuration file.

You can set Visual FoxPro to read an external configuration file following an internal configuration file by using the new ALLOWEXTERNAL directive in the internal configuration file. When you include the setting ALLOWEXTERNAL=ON in the internal configuration file, Visual FoxPro searches for an external configuration file, usually Config.fpw, and reads its settings. You can also specify a different configuration file using the -C command-line switch when starting Visual FoxPro.

Note:
For .exe and .dll file servers, Visual FoxPro supports only those configuration files bound inside the server. Therefore, Visual FoxPro disregards the ALLOWEXTERNAL setting.

To read an external configuration file after an internal one

  1. In the internal configuration file, set the special term ALLOWEXTERNAL to on.

    Copy Code
    ALLOWEXTERNAL = ON

  2. When you start your program, either specify a second configuration file using the -C command-line switch or have a second configuration file in the default program path.

For more information about command-line switches, see How to: Use Command-Line Options When Starting Visual FoxPro.

The settings in an external configuration file take precedence over those in the internal configuration file, if duplicate settings exist, because the external configuration file is read after the internal file. Visual FoxPro does not begin initialization until it reads both files.

If you want to specify the configuration file as read-only, place the file in your project and mark it as Included. If you want to specify that the file can be modified, place the file in your project and mark it as Excluded. You can then distribute the file separately with your application or executable file. By convention, configuration files use the .fpw extension.

See Also

Other Resources

Setting Configuration Options at Startup
How to: Use Command-Line Options When Starting Visual FoxPro
Compiling an Application
How to: Add Setup Code to a Menu System
Designing Menus and Toolbars
_STARTUP System Variable
Visual FoxPro Environment Settings


How to: Create a Configuration File

Visual FoxPro 9.0
How to: Create a Configuration File
See Also

To create a configuration file, use the Visual FoxPro editor, or any editor that can create text files, to create a text file in the directory where Visual FoxPro is installed. Earlier versions of Visual FoxPro created the file Config.fpw in the startup directory. Config.fpw became the default configuration file. You can create any program file and use it to establish default settings and behaviors by starting Visual FoxPro using that file either by double clicking the file or using a command line reference.

If you are creating a new configuration file, you can save it using any name you want. By convention, configuration files have the extension .fpw.

When you start Visual FoxPro, you can use a default configuration file from the following locations in order:

  • Current working directory

  • Directory where Visual FoxPro is installed

  • Directories listed in the DOS path

If Visual FoxPro does not find a configuration file in these locations, Visual FoxPro uses only the default settings established in the Options dialog box.

Note:
For details about specifying an alternative to the default file name or location for the configuration file, see How to: Specify the Configuration File.

Enter configuration settings using one of these methods:

  • Make settings with the SET command.

  • Set system variables.

  • Call programs or functions.

  • Include special terms used only in configuration files.

To enter SET commands in a configuration file

  • Enter SET commands without the SET keyword and with an equal sign.

    For example, to set a default path type, use this format:

    Copy Code
    DEFAULT = HOME()+"\VFP"

    To add a clock to the status bar, use this command:

    Copy Code
    CLOCK = ON

To enter a setting for a system variable, use the same syntax you would use in the Command window or in a program.

To set system variables in a configuration file

  • Enter the name of the system variable, an equal sign (=), and the value to set the variable to.

    For example, the following command specifies an alternative spell-checking program:

    Copy Code
    _SPELLCHK = "SPLLCHK.EXE"

You can also call functions or execute programs from within a configuration file by using the COMMAND command. For example, you can start an initialization program as part of the startup process.

To call functions or execute commands in a configuration file

  • Enter COMMAND, an equal sign (=), and the command to execute or function to call.

    For example, to include the Visual FoxPro version number in the caption of the main Visual FoxPro window, use this command:

    Copy Code
    COMMAND =_SCREEN.Caption="Visual FoxPro " + VERS(4)

    The following command launches a specific application when Visual FoxPro starts:

    Copy Code
    COMMAND = DO MYAPP.APP

You can also use special terms in a configuration file that do not correspond to SET value, system variables, or commands.

To use special terms in a configuration file

  • Enter the special term, an equal sign (=), and the setting.

    For example, to set the maximum number of variables available in Visual FoxPro, use this command:

    Copy Code
    MVCOUNT = 2048

For a complete list of special terms for configuration files, see Special Terms for Configuration Files.

Starting Applications or Programs Automatically

You can insert commands into a configuration file that automatically launches programs when Visual FoxPro starts. You can use these commands either to start an entire application or to start just a program, such as one that initializes system variables.

To start applications from a configuration file

  1. Assign the name of your application to the _STARTUP System Variable anywhere in the configuration file:

    Copy Code
    _STARTUP = MYAPP.APP

    -or-

  2. Use the COMMAND command, which must be the last line in your configuration file:

    Copy Code
    COMMAND = DO MYAPP.APP

See Also

Other Resources

Setting Configuration Options at Startup
How to: Use Command-Line Options When Starting Visual FoxPro
Compiling an Application
How to: Add Setup Code to a Menu System
Designing Menus and Toolbars
_STARTUP System Variable
Visual FoxPro Environment Settings


Special Terms for Configuration Files

Visual FoxPro 9.0
Special Terms for Configuration Files
See Also

The following table lists special terms you can use in configuration files. You can also SET commands, system variables, and the _STARTUP setting in configuration files to customize the Visual FoxPro environment.

Remarks

Term and syntax Description

ALLOWEXTERNAL ON | OFF

Specifies whether settings from an external configuration file as specified by the -C command-line switch (or located in path) are read in after those from an internal one. The ALLOWEXTERNAL term is ignored unless it is bound inside of an application.

Default: OFF

BITMAP ON | OFF

Specifies whether Visual FoxPro first writes screen or form updates to an off-screen bitmap, and then performs a bit block transfer (bitblt) to the screen. BITMAP = OFF can improve performance when application are accessed using Windows Terminal Server clients.

Default: ON

CODEPAGE = nValue | AUTO

Specifies a number that identifies the character set used for files. Setting CODEPAGE to AUTO selects the current operating system code page.

For the possible values you can use, see Code Pages Supported by Visual FoxPro.

COMMAND = cVisualFoxProCommand

Specifies a Visual FoxPro command to execute when Visual FoxPro is started. The cVisualFoxProCommand specifies the command to execute.

EDITWORK path

Specifies where the text editor should place its work files. Because work files can become large, specify a location with plenty of free space.

Default: Operating system dependent. For more information, see Optimizing the Operating Environment.

INDEX extension

Specifies the extension for Visual FoxPro index files.

Default: .idx

LABEL extension

Specifies the extension for Visual FoxPro label definition files.

Default: .lbx

_MENUDESIGNER = cProgramName

Specifies an external menu design application.

Default: The empty string "".

MVCOUNT

Sets the maximum number of variables that Visual FoxPro can maintain. This value can range from 128 to 65,000.

Default: 16,384

OUTSHOW = ON | OFF

Disables the ability to hide all windows in front of the current output by pressing SHIFT+CTRL+ALT.

Default: ON

PROGCACHE = nMemoryPages

Specifies the amount of memory (address space) in pages that Visual FoxPro allocates at startup or a Visual FoxPro MTDLL COM Server allocates per thread for the internal program cache (memory used to run programs). Each page of memory is equal to 64K so the default setting equates to an allocation a little over 9MB. As the cache is filled, Visual FoxPro will try to flush it to remove unused items. It is possible that Visual FoxPro cannot free enough memory in which case an Error 1202 is generated (Program is too large). Adjusting the PROGCACHE setting can prevent this error from occurring.

Note:
While this setting can be used for the Visual FoxPro development product or normal runtime applications, it is primarily intended for MTDLL COM Servers where many threads are often created for a single server. In Visual FoxPro 9.0, the default value for MTDLL COM Servers is -2.

When the value of nMemoryPages is greater than 0, Visual FoxPro allocates a fixed program cache. You can specify between 1 and 65000.

If you specify 0 for nMemoryPages, no program cache is used. Instead, Visual FoxPro uses dynamic memory allocation based on determinations made by the operating system.

If you pass a value for nMemoryPages that is less than 0, Visual FoxPro uses dynamic memory allocation but is limited to the specified memory (nMemoryPages * 64K). When the limit is reach, Visual FoxPro will flush allocated programs to free memory.

You can call SYS(3065) to determine the current PROGCACHE setting. CLEAR PROGRAM will attempt to clear unreferenced code regardless of this setting.

Note:
The Visual FoxPro OLE DB Provider ignores this setting since it uses dynamic memory allocation (PROGCACHE=0).

Default: 144 (-2 for MTDLL)

PROGWORK path

Specifies where Visual FoxPro stores the program cache file.

For faster performance, especially in a multiuser environment, specify a fast disk, such as a local disk or memory, if available. Provide at least 256K for the cache, though the file can grow larger.

Default: Operating system dependent. For more information, see Optimizing the Operating Environment.

REPORT extension

Specifies the extension for Visual FoxPro report definition files.

Default: .frx

RESOURCE path[\file] | OFF

Specifies the location of the FoxUser.dbf resource file or prevents Visual FoxPro from using a resource file. The file argument is optional. If file is omitted, Visual FoxPro searches for the FoxUser.dbf file. If the specified file does not exist, it is created.

Default: Startup directory as path and FoxUser.dbf as file.

SCREEN = ON | OFF

Specifies whether the main Visual FoxPro window appears when opening Visual FoxPro.

When an application consists of one or more top-level forms that are displayed in the Windows desktop, setting SCREEN to OFF can be useful, making the main Visual FoxPro window not required. For further information on top-level forms, see Controlling Form Behavior.

Default: ON

SORTWORK path

Specifies where commands such as SORT and INDEX should place work files.

Because work files can be up to twice as large as the tables being sorted, specify a location with plenty of free space. For faster performance, especially in a multiuser environment, specify a fast disk such as a local disk.

Default: Operating system dependent. For more information, see Optimizing the Operating Environment.

STACKSIZE = nValue

Specifies the number of nesting levels from 32 to 64,000 for operations such as the DO command.

Note:
You can change the nesting level only during Visual FoxPro startup.

Default: 128

TEDIT [/N] editor

Specifies the name of the text editor used when you edit program files with MODIFY COMMAND or MODIFY FILE.

Include the optional clause /N with TEDIT to specify a Windows text editor.

Default: Visual FoxPro editor

TITLE title

Specifies the title that appears in the caption bar of the main Visual FoxPro window.

Default: "Microsoft Visual FoxPro"

TMPFILES path

Specifies where temporary work files specified by EDITWORK, SORTWORK, and PROGWORK configuration file settings are stored if they are not specified.

Because work files can become very large, specify a location with plenty of free space. For faster performance, especially in a multiuser environment, specify a fast disk such as a local disk.

Default: Operating system dependent. For more information, see Optimizing the Operating Environment.

See Also

Other Resources

Setting Configuration Options at Startup
SET Command
Optimizing Applications
Visual FoxPro Environment Settings


How to: Use Command-Line Options When Starting Visual FoxPro

Visual FoxPro 9.0
How to: Use Command-Line Options When Starting Visual FoxPro
See Also

In addition to using the SET command and a configuration file, you can specify startup options by including a command-line switch. For example, using command-line options, you can suppress the display of the Visual FoxPro splash screen, which displays at the startup of Visual FoxPro, or specify a nondefault configuration file.

To use a command-line switch

  • On the command line or in a shortcut, add the switch after the name of the Visual FoxPro executable file, VFPVersionNumber.exe where VersionNumber represents the version number of this release or any Visual FoxPro-created .exe file.

    Note:
    If the command-line switch requires arguments, such as a file name, do not put a space between the switch and the argument. For example, to specify a configuration file, use a command such as:

    Copy Code
    C:\Program Files\Microsoft Visual FoxPro VersionNumber\VFPVersionNumber.exe -CC:\MYAPP.FPW

    Separate multiple options with single spaces.

The following table lists the command-line switches available in Visual FoxPro.

Switch Description

-A

Ignore the default configuration file and Windows registry settings.

-BFileName,Duration

Display a custom bitmap (.bmp), .gif, or .jpg graphic file and specify its display duration in milliseconds when Visual FoxPro starts. You can also include the -B command-line switch in a Visual FoxPro shortcut.

Note:
If the bitmap you specify cannot be located, the bitmap does not display when Visual FoxPro starts.

-CFileName

Specify a configuration file, including a path if necessary, other than the default file, Config.fpw.

-LFileName

Specify a resource file, including a path if necessary, other than the default, vfp*ENU.dll, so you can use Visual FoxPro in a language other than the current language specified by Windows.

-R

In earlier versions, refresh the Windows registry with information about Visual FoxPro, such as associations for Visual FoxPro files. In later versions, use /regserver.

-T

Suppress the display of the Visual FoxPro splash screen. By default, when Visual FoxPro starts, it displays a splash screen that shows the Visual FoxPro logo, version number, and other information. If you prefer that users of your application not see this splash screen, you can prevent Visual FoxPro from displaying it using the -T command-line switch.

/?

List the available command-line arguments. Available in Visual FoxPro 7.0 and later.

/regserver

Register Visual FoxPro default registry keys.

REGSVR32 server.dll

Register a .dll component.

/unregserver

Remove Visual FoxPro default registry keys.

/u server.dll

Remove a .dll component.

See Also

Other Resources

Visual FoxPro Environment Settings
Setting Configuration Options at Startup
Customizing the Visual FoxPro Environment
How to: Configure Visual FoxPro Toolbars


How to: Configure Visual FoxPro Toolbars

Visual FoxPro 9.0
How to: Configure Visual FoxPro Toolbars
See Also

Visual FoxPro includes the following customizable toolbars.

Tool | Associated Toolbars | Command
Database Designer | Database | CREATE DATABASE
Form Designer | Form Controls Form Designer Color Palette Layout | CREATE FORM
Print Preview | Print Preview |
Query Designer | Query Designer | CREATE QUERY
Report Designer | Report Controls Report Designer Color Palette Layout | CREATE REPORT

You can place as many toolbars on your screen as you need while working. You can dock toolbars to the top, bottom, or sides of your screen to customize your working environment. Visual FoxPro saves the positions of the toolbars so they remain where you last placed them.

To dock a toolbar

  • Drag the toolbar to the top, bottom, or side of your screen.

    -OR-

  • Use the DOCK Command to dock the toolbar.

Activating and Deactivating Toolbars

By default, only the Standard toolbar is visible. When you use a Visual FoxPro designer tool (for example, the Form Designer), the designer displays the toolbars that you commonly need when working with that designer tool. However, you can activate a toolbar any time you require it.

To activate a toolbar

  • Run the associated tool.

    –OR–

To deactivate a toolbar

  • Close the associated tool.

    –OR–

You can also programmatically activate and deactivate toolbars that have been previously activated by using the DEACTIVATE WINDOW or ACTIVATE WINDOW commands as in the following example.

Copy Code
IF WVISIBLE ("Color Palette")
DEACTIVATE WINDOW("Color Palette")
ENDIF

Customizing Existing Toolbars

The easiest way to create custom toolbars is by modifying the toolbars already provided with Visual FoxPro. You can:

  • Modify an existing toolbar by adding or removing buttons.

  • Create a new toolbar that contains buttons from existing toolbars.

You can also define custom toolbars by creating a custom toolbar class using code. For details, see Designing Menus and Toolbars.

You can modify any of the toolbars provided with Visual FoxPro. For example, you might want to remove a button from an existing toolbar, or copy buttons from one toolbar to another.

To modify an existing Visual FoxPro toolbar

  1. From the View menu, choose Toolbars.

  2. Select the toolbar you want to customize and choose Customize.

  3. Remove buttons from the toolbar by dragging them off of the toolbar.

  4. Add buttons to the toolbar by selecting an appropriate category in the Customize Toolbar dialog box and then dragging the appropriate buttons onto the toolbar.

  5. Complete the toolbar by choosing Close in the Customize Toolbar dialog box and then closing the toolbar window.

    Tip:
    If you change a Visual FoxPro toolbar, you can restore it to its original configuration of buttons by selecting the toolbar in the Toolbar dialog box and then choosing Reset.

You can create your own toolbars comprised of buttons from other toolbars.

To create your own toolbar

  1. From the View menu, choose Toolbars.

  2. Choose New.

  3. In the New Toolbar dialog box, name the toolbar.

  4. Add buttons to the toolbar by selecting a category in the Customize Toolbar dialog box and then dragging the appropriate buttons onto the toolbar.

  5. You can rearrange buttons on the toolbar by dragging them to the desired position.

  6. Complete the toolbar by choosing Close in the Customize Toolbar dialog box and then closing the toolbar window.

    Note:
    You cannot reset buttons on a toolbar you create.

To delete a toolbar you created

  1. From the View menu, choose Toolbars.

  2. Select the toolbar you want to delete.

  3. Choose Delete.

  4. Choose OK to confirm the deletion.

    Note:
    You cannot delete toolbars provided by Visual FoxPro.

See Also

Other Resources

Visual FoxPro Environment Settings
How to: Use Command-Line Options When Starting Visual FoxPro
How to: Set Editor Options
Customizing the Visual FoxPro Environment
Designing Menus and Toolbars


How to: Dock Windows

Visual FoxPro 9.0
How to: Dock Windows
See Also

You can dock certain Visual FoxPro Integrated Development Environment (IDE) windows to the Visual FoxPro desktop window, each other, or user-defined forms. The following windows are dockable:

  • Call Stack

  • Command

  • Data Session (View)

  • Debugger

  • Document View

  • Locals

  • Output

  • Properties

  • Trace

  • Watch

Note:
Historically in prior versions of Visual FoxPro, the Data Session window has always been referred to as the View window. Additionally, language used to control this window, such as HIDE WINDOW, ACTIVATE WINDOW, WONTOP( ), also refers to this window as the View window.

When you drag a dockable window to a Visual FoxPro desktop window boundary, the dockable window repositions itself against the chosen boundary. The state and location of docked windows persist from the last user session.

To dock windows programmatically and retrieve their dock states, see DOCK Command and ADOCKSTATE( ) Function.

You can change the dockable status of a dockable window.

To enable or disable dockable status

  1. Right-click the title bar of an open and dockable window.

  2. Click Dockable to enable or disable the dockable status of the window. A check mark appears when the window is dockable.

    -OR-

  3. Click the desired window to make the window active.

  4. On the Window menu, click Dockable to enable or disable the dockable status of the window. A check mark appears when the window is dockable.

For more information about retrieving the dockable status for a window programmatically, see WDOCKABLE( ) Function.

Docking Modes

You can dock windows in three different modes:

  • Normal docking

    Windows dock to a boundary of the Visual FoxPro desktop window.

  • Linked docking

    Windows dock to each other and share a dockable window container.

  • Tabbed docking

    Windows dock to each other and share the full window through the use of tabs.

You can use tabbed docking and linked docking together.

To create normal docking

  1. Make sure the docking status of the window or windows is set to Dockable.

  2. Drag the window title bar to a boundary of the Visual FoxPro desktop window.

To create linked docking

  1. Make sure the docking status of the window or windows is set to Dockable.

  2. Drag the title bar of the desired window to a boundary or docking zone of the target window.

The docking zone is indicated when the window you are dragging changes shape to fit the target window. Visual FoxPro creates an additional title bar for link-docked windows.

To create tabbed docking

  1. Make sure the docking status of the window or windows is set to Dockable.

  2. Drag the title bar of the desired window to the title bar of the target window.

Visual FoxPro adds tabs to the bottom boundary of the docked windows.

To undock windows

  • To undock normal-docked windows, drag the title bar of the desired window away from the shared window boundary.

    -or-

  • To undock link-docked windows, drag the title bar of the desired window away from the shared window.

    -or-

  • To undock tab-docked windows, drag the tab of the desired window away from the shared window.

You can disable docking behavior by holding the CTRL key while dragging a window.

Deleting or editing the FoxUser.dbf resource file, which contains your settings, restores or changes your default window settings. For more information about altering your settings, see FoxUser Resource File Structure.

See Also

Tasks

How to: Dock Forms
How to: Dock Toolbars

Other Resources

Visual FoxPro Environment Settings
Visual FoxPro System Windows
Document View Window


How to: Set Editor Options

Visual FoxPro 9.0
How to: Set Editor Options
See Also

You can configure the window of the Visual FoxPro editor to display text the way you want such as setting the font, text alignment, or syntax coloring. You can also make the editor easier to use by setting preferences for indentation, wordwrap, automatic backup copies, and other features.

To configure the editing window, set your preferences in the Edit Properties dialog box that appears after you open a program or text file open and select Properties from the Edit menu. For details about settings you can configure, see Edit Properties Dialog Box.

To display the Edit Properties dialog box

  1. Open the editing window for a program, text file, or control.

  2. From the Edit menu that becomes active, select Properties.

    Tip:
    You can display the Font dialog box directly by right-clicking the editing window and choosing Font from the shortcut menu.

For more information about opening a program or text file, see How to: Create Programs.

By default, the settings that you make in the Edit Properties dialog box persist for that file. For example, if you change the font, the font for all text in the current window changes. If you open another editing window, the default settings apply.

You can choose to save your settings so that they apply to all files of the same type, or not to save the new settings at all. If you apply your settings to similar file types, Visual FoxPro uses the settings you make when you edit files with the same extension, for example, all .prg files, or all method code in the Form Designer.

To avoid persisting changes to editor settings

  • In the Edit Properties window, clear the Save Preferences option and then click OK.

To apply editor options to similar files

  • In the Edit Properties dialog box, select Use These Preferences As Default and then click OK.

You can also set the color and font that the editor uses to identify keywords, comments, and other elements of programs. For details, see Editor Tab, Options Dialog Box.

See Also

Other Resources

Visual FoxPro Environment Settings
Editing Window
Restoring the Visual FoxPro Interactive Environment
Editor Tab, Options Dialog Box
How to: Change Configuration Settings in the Windows Registry
How to: Display and Print Source Code in Color


How to: Display and Print Source Code in Color

Visual FoxPro 9.0
How to: Display and Print Source Code in Color
See Also

You can display and print code with color syntax in the Command window and Visual FoxPro editors for program (.prg) files, methods, stored procedures, and memos.

The following sections contain more information about displaying and printing code in color:

  • Displaying Source Code in Color

  • Printing Source Code in Color

Displaying Source Code in Color

You can turn on syntax coloring separately for each editing window; however; the color syntax settings that you choose in the Editor tab of the Options dialog box apply to the Command window and most other editing windows. For more information, see Editor Tab, Options Dialog Box and Editing Window.

Note:
To display color syntax in run-time applications, Visual FoxPro must be configured to display color syntax. Run-time applications display only the default color settings because run-time applications do not check the Windows registry for settings that you change in the Options dialog box, which specifies the default settings for color syntax.

When color syntax is turned on, Visual FoxPro performs background compilation for the current and single line of code that you are typing. When a line of code contains invalid syntax, Visual FoxPro displays the line of code with the selected formatting style.

To display color syntax in an editing window

  1. Open the editing window that you want to display color syntax.

  2. On the Edit menu, choose Properties.

  3. In the Edit Properties dialog box, select the Syntax coloring check box.

  4. Click OK.

Syntax coloring is activated for the editing window you selected. For more information, see Edit Properties Dialog Box.

You can also display source code files to the screen in color using the TYPE command. For more information, see TYPE Command.

To customize color syntax settings

  1. On the Tools menu, choose Options.

  2. In the Options dialog box, choose the Editor tab.

  3. Under Syntax color settings, choose the color settings that you want.

  4. When you are finished choosing settings, click OK.

The color settings you chose take effect.

To set formatting for invalid color syntax

  1. Turn on syntax coloring for the editing window.

  2. On the Tools menu, choose Options.

  3. In the Options dialog box, choose the Editor tab.

  4. In the Background Compile box, choose the formatting style you want.

Invalid syntax displays in the editing window with the formatting style you chose.

Printing Source Code in Color

You can print source code in color wherever color syntax appears, such as program files, methods, stored procedures, and memos.

Note:
To print your code files in color, you must be connected to a color printer to select the color printing options available for your printer. Background colors set in the Editor tab of the Options dialog box are not printed. If you select color printing for source code files, hyperlinks appear underlined.

To print source code in color

  1. Open the program file or code you want to print.

  2. On the File menu, choose Print.

  3. In the Print dialog box, choose your color printer, and then click Preferences.

  4. Select the color printing options available for your printer.

  5. When you are finished, click Print.

When connected to a color printer, you can also print source code in color using the TYPE command with the TO PRINTER clause.

For more information, see Print Dialog Box and TYPE Command.

See Also

Other Resources

How to: Set Editor Options
How to: View and Change Environment Settings
Visual FoxPro Environment Settings


Automating Keystroke Tasks with Macros

Visual FoxPro 9.0
Automating Keystroke Tasks with Macros

If you find yourself repeating the same keystrokes, or if you want to automate some keystroke tasks for your users, you can record and save these keystrokes in macros by using the Macros dialog box.

Note:
To use macros, any keyboard you use must have function keys F1 to F9, and a CTRL key or an ALT key.

In This Section

How to: Clear Macro Definitions

Provides instructions on how to use the Macros dialog box to clear macro key definitions.
How to: Create, Save, and Restore Macro Sets

Describes how you can create macro sets through the Macros dialog box.
How to: Edit Macros

Explains how the Macros dialog box makes it possible to edit existing macros.
How to: Record Macros

Describes the steps to record keystroke macros in Visual FoxPro.
How to: Set a Default Macro Set

Explains how you can create and set your own default macro set in Visual FoxPro.

Related Sections

Visual FoxPro Environment Settings

Describes different ways to change Visual FoxPro environment settings such as using the Options dialog box, setting configuration options at program startup, using command-line options. You can configure Visual FoxPro toolbars, dock windows, set editor options, and customize the appearance of your applications without altering code.
Optimizing Your System

Provides information about optimizing your operating environment.
Development Productivity Tools

Discusses the different tools available to help make creating Visual FoxPro applications easier and faster.


How to: Clear Macro Definitions

Visual FoxPro 9.0
How to: Clear Macro Definitions
See Also

You can clear macro key definitions through the Macros Dialog Box.

To clear a macro definition

  1. From the Macros dialog box, select a macro from the Individual Macro list.

  2. Choose Clear.

See Also

Other Resources

Automating Keystroke Tasks with Macros
Macros Dialog Box


How to: Create, Save, and Restore Macro Sets

Visual FoxPro 9.0
How to: Create, Save, and Restore Macro Sets
See Also

A macro set is a defined set of keys and their associated macros stored in a file with the extension .FKY. You can create macro sets through the Macros Dialog Box.

To create a macro set

  1. From the Macros dialog box, create individual key macros.

  2. Choose Save.

  3. In the Save Current Macros To box, enter a name for the macro set and choose Save.

To restore a macro set

  1. From the Macros dialog box, choose Restore.

  2. Select a macro set file and then choose OK.

See Also

Other Resources

Automating Keystroke Tasks with Macros
CLEAR Commands
Macros Dialog Box
RESTORE MACROS Command
SAVE MACROS Command


How to: Edit Macros (Visual FoxPro)

Visual FoxPro 9.0
How to: Edit Macros (Visual FoxPro)
See Also

You can edit existing macros through the Macros Dialog Box.

To edit a macro

  1. From the Macros dialog box, select a macro from the Individual Macro list and then choose Edit.

  2. Modify the macro contents.

  3. Choose OK.

See Also

Other Resources

Automating Keystroke Tasks with Macros
CLEAR Commands
Macros Dialog Box
SET FUNCTION Command


How to: Record Macros (Visual FoxPro)

Visual FoxPro 9.0
How to: Record Macros (Visual FoxPro)
See Also

You can record keystroke macros in Visual FoxPro through the Macros Dialog Box.

To record a macro

  1. From the Tools menu, choose Macros.

  2. In the Macros dialog box, choose Record.

  3. Press the key or type the key combination you want to define.

  4. Enter a name for the macro or accept the default and then choose OK.

Visual FoxPro begins recording every keystroke.

Note:
Macro names cannot contain spaces.

To stop recording a macro

  1. From the Tools menu, choose Macros.

  2. In the Stop Recording Macro Dialog Box, choose from the following:

    • To save the macro as is, choose OK.

    • To continue recording, choose Continue.

    • To discard the macro, choose Discard.

    • To insert a literal keystroke (the literal meaning of a key instead of any meaning currently assigned to it), choose Insert Literal.

    • To insert a pause, select Seconds, add the amount of time, and choose Insert Pause.

See Also

Other Resources

Automating Keystroke Tasks with Macros
Macros Dialog Box
ON KEY LABEL Command
SET FUNCTION Command
Stop Recording Macro Dialog Box


How to: Set a Default Macro Set

Visual FoxPro 9.0
How to: Set a Default Macro Set
See Also

A default macro set exists when Visual FoxPro starts. You can create and set your own default macro set through the Macros Dialog Box.

To set a default macro set

  1. From the Macros dialog box, create or restore a macro set.

  2. Choose Set Default.

See Also

Other Resources

Automating Keystroke Tasks with Macros
Macros Dialog Box
RESTORE MACROS Command


Restoring the Visual FoxPro Interactive Environment

Visual FoxPro 9.0
Restoring the Visual FoxPro Interactive Environment
See Also

If you want to close down all program operations and return Visual FoxPro to its interactive state, issue the following commands in order inside the Command window or in the program called just before you quit Visual FoxPro.

Copy Code
CLEAR ALL
CLOSE ALL
CLEAR PROGRAM

CLEAR ALL removes all objects from memory, which, in turn, closes all private data sessions and cursors.

CLOSE ALL, after CLEAR ALL has completed successfully, closes all databases, tables, and cursors in data session 1, the default Visual FoxPro data session.

CLEAR PROGRAM clears the compiled program buffer of the most recently executed programs. CLEAR PROGRAM forces Visual FoxPro to read the programs from disk, rather than from the program buffer.

Cleaning Up during Transactions If transactions are in progress, use the END TRANSACTION Command for each level of transaction before issuing CLEAR ALL, CLOSE ALL, and CLEAR PROGRAM.

Cleaning Up during Buffered Updates If buffered updates are in progress, use either the TABLEUPDATE( ) Function or TABLEREVERT( ) Function for each cursor with buffered updates before issuing CLEAR ALL, CLOSE ALL, and CLEAR PROGRAM.

See Also

Other Resources

Visual FoxPro Environment Settings
Customizing the Visual FoxPro Environment
How to: Set Editor Options
CLEAR Commands
CLOSE Commands
END TRANSACTION Command
TABLEUPDATE( ) Function
TABLEREVERT( ) Function
Command Window
How to: Operate the Command Window


Accessibility for People with Disabilities (Visual FoxPro)

Visual FoxPro 9.0
Accessibility for People with Disabilities (Visual FoxPro)

Microsoft is committed to making its products and services easier for everyone to use. This Help file provides information about how to make Microsoft Windows and Visual FoxPro more accessible as well as other features, products, and services that can help improve accessibility for people with disabilities.

Note:
The information in this section about Microsoft Windows applies only to users who purchased Microsoft Windows in the United States. If you purchased Microsoft Windows outside the United States, your Windows package contains a subsidiary information card listing Microsoft Support Services telephone numbers and addresses. You can contact your subsidiary to find out whether the type of products and services described in this Help file are available in your area.

For information about technical support services for people who are deaf or hard-of-hearing, see Microsoft Visual FoxPro Technical Support.

You can learn more about the accessibility features in Microsoft products and services by visiting the Accessibility Web site at http://www.microsoft.com/enable/.

In This Section

Customizing Microsoft Windows for Accessibility

Provides information about customizing the Microsoft Windows environment to make your computer more accessible.
How to: Customize Visual FoxPro for Accessibility

Provides information about how to customize Visual FoxPro for accessibility.
Utilities and Resources for Enhancing Accessibility

Provides information about accessibility products, services, and resources available from Microsoft and other organizations.
Microsoft Documentation in Alternative Formats

Provides information about how to obtain alternative and more accessible documentation formats.

Related Sections

Customizing the Visual FoxPro Environment

Includes information about system configuration and envirnment settings, and optimization.
Product Support

Provides information about Microsoft product support services for Visual FoxPro and copyright information.
How to: Use the Accessibility Browser

Provides information about using the Accessibility Browser to help make your Visual FoxPro applications more accessible for other users.


Customizing Microsoft Windows for Accessibility

Visual FoxPro 9.0
Customizing Microsoft Windows for Accessibility
See Also

There are many ways you can customize Microsoft Windows to make your computer more accessible.

  • Windows includes accessibility features that are useful for individuals who have difficulty typing or using a mouse, have moderately impaired vision, or who are deaf or hard-of-hearing. You can install these features during the setup process, or you can add them later from your Windows installation disks. Look up "accessibility" in the Windows Help index for information about installing and using these features.

  • You can add many of the features that make current versions of Windows more accessible to earlier versions of Windows and to MS-DOS via Access Packs. You can download these files by modem, or you can order them on disks from Microsoft.

  • You can use Control Panel and other built-in features to adjust the appearance and behavior of Windows to suit varying vision and motor abilities. These include adjusting colors and sizes, sound volume, and the behavior of the mouse and keyboard.

  • If you have difficulty using the standard QWERTY keyboard layout, Dvorak keyboard layouts make the most frequently typed characters on a keyboard more accessible. You can choose from three Dvorak layouts: two-handed, left-handed only, and right-handed only. You do not have to purchase any special equipment to use these features.

The specific features available, and whether they are built in or must be obtained separately, depend on which operating system you are using.

To Download the Access Packs, Application Notes, and Alternative Keyboard Layouts by Modem

If you have a modem, you can download these files from the following network services:

  • Microsoft Web site. Go to the Microsoft Windows XP Accessibility Resources at http://www.microsoft.com/enable/products/windowsxp/default.aspx.

  • Microsoft FTP server, ftp://ftp.microsoft.com/Softlib/MSLFILES/.

  • MSN, the Microsoft Network online service.

  • CompuServe. Type GO MSL.

  • Various user-group bulletin boards.

To Order the Access Packs, Application Notes, and Alternative Keyboard Layouts on Disks by Phone

If you do not have a modem, you can order the Access Packs, Application Notes, and Alternative Layouts on disks within the United States by calling Microsoft Sales Information Center at (800) 426-9400 (voice) or (800) 892-5234 (TTY).

In Canada, you can call (905) 568-3503 or (905) 568-9641 (text telephone).

See Also

Other Resources

Accessibility for People with Disabilities
How to: Customize Visual FoxPro for Accessibility
Utilities and Resources for Enhancing Accessibility
Microsoft Documentation in Alternative Formats


How to: Customize Visual FoxPro for Accessibility

Visual FoxPro 9.0
How to: Customize Visual FoxPro for Accessibility
See Also

You can use the following steps to enhance accessibility in Visual FoxPro:

Enlarging Toolbar Buttons

To view enlarged toolbar buttons

  1. From the View menu, click Toolbars.

  2. Select the Large buttons check box.

Enlarging Text in the Code Window

To view enlarged text in the Code Window

  • From the Format menu, click Font, and choose the font size you want.

Enlarging Text in the Debugger

To view enlarged text in the Debugger

  1. On the Tools menu, click Options.

  2. In the Options dialog box, click the Debug tab, and then click Font.

  3. Select the font and font size you want.

See Also

Other Resources

Accessibility for People with Disabilities
Customizing Microsoft Windows for Accessibility
Utilities and Resources for Enhancing Accessibility
Microsoft Documentation in Alternative Formats


Utilities and Resources for Enhancing Accessibility

Visual FoxPro 9.0
Utilities and Resources for Enhancing Accessibility
See Also

Microsoft and other organizations provide products, services, and resources that make it easier to use personal computers. The following list includes some of the different types of available products:

  • Programs that enlarge or alter the color of information on the screen

  • Programs that describe information on the screen in Braille or synthesized speech

  • Hardware and software utilities that modify the behavior of the mouse and keyboard

  • Programs that make it possible for people to "type" using a mouse or their voice

  • Word or phrase prediction software that makes it possible for people to type more quickly and with fewer keystrokes

  • Alternate input devices, such as single switch or puff-and-sip devices

Microsoft Active Accessibility

Visual FoxPro supports Microsoft Active Accessibility, which is a COM-based Windows developer technology that allows programs and the operating system to work more compatibly with accessibility aids, for example, screen readers such as Microsoft Magnifier. For more information about Microsoft Active Accessibility, visit MSDN at http://msdn.microsoft.com.

Additional Microsoft Products and Services for People with Disabilities

For more information, contact:

Microsoft Sales Information Center One Microsoft Way Redmond, WA 98052-6393

World Wide Web: Voice telephone: Teletypewriter (TTY):

http://www.microsoft.com

(800) 426-9400 (800) 892-5234

Directories of Computer Products That Help People with Disabilities

The Trace R&D Center at the University of Wisconsin–Madison produces a book and a compact disc describing products that help people with disabilities use computers. The book, titled Trace ResourceBook, provides descriptions and photographs of about 2,000 products. The compact disc, titled CO-NET CD, provides a database of more than 18,000 products and other information for people with disabilities. It is issued twice a year.

To obtain these directories, contact:

Trace R&D Center University of Wisconsin S-151 Waisman Center 1500 Highland Avenue Madison, WI 53705-2280

World Wide Web: Fax:

http://trace.wisc.edu

(608) 262-8848

Referrals to Assistive Technology Programs and Trained Evaluators

For general information and recommendations on how computers can help specific requirements, you should consult a trained evaluator. An assistive technology program in your area will provide referrals to programs and services that are available to you.

To locate the assistive technology program nearest you, contact:

National Information System University of South Carolina Center for Developmental Disabilities Columbia, SC 29208

Voice/text telephone: Fax:

(803) 935-5231

(803) 935-5059

See Also

Other Resources

Accessibility for People with Disabilities
Customizing Microsoft Windows for Accessibility
How to: Customize Visual FoxPro for Accessibility
Microsoft Documentation in Alternative Formats


Microsoft Documentation in Alternative Formats (Visual FoxPro)

Visual FoxPro 9.0
Microsoft Documentation in Alternative Formats (Visual FoxPro)
See Also

If you have difficulty reading or handling printed documentation, you can obtain many Microsoft publications and documents for Microsoft products in more accessible formats. Microsoft provides a number of documents for Microsoft products in more accessible formats. For more information, visit the Microsoft Accessiblity Web site at http://www.microsoft.com/enable/.

You can also obtain Microsoft publications from Recording for the Blind & Dyslexic, Inc. Recording for the Blind & Dyslexic distributes these documents to registered eligible members of their distribution service, either on audio cassettes or on disks. The Recording for the Blind & Dyslexic collection contains more than 80,000 titles, including Microsoft product documentation and books from Microsoft Press.

You can contact Recording for the Blind & Dyslexic at the following address or phone numbers for information about eligibility and availability of Microsoft product documentation and books from Microsoft Press:

Recording for the Blind & Dyslexic, Inc. 20 Roszel RoadPrinceton, NJ 08540

Phone: Fax: World Wide Web:

(609) 452-0606 or (800) 221-4792 (609) 987-8116http://www.rfbd.org

See Also

Other Resources

Accessibility for People with Disabilities
Customizing Microsoft Windows for Accessibility
How to: Customize Visual FoxPro for Accessibility
Utilities and Resources for Enhancing Accessibility


Using Visual FoxPro

Visual FoxPro 9.0
Using Visual FoxPro

Visual FoxPro provides the environment and tools you need to create and manage high-performance database applications and components. With its robust tools and data-centric, object-oriented language, you can build modern, scalable, multi-tier applications that integrate client/server computing and the Internet.

In This Section

Overview of Visual FoxPro Features

Describes the major features of Visual FoxPro that you expect in a database management system (DBMS) and as a front end for developing client/server applications, such as rapid application and interface creation, powerful object-oriented programming, event handling, testing and debugging capabilities, flexibility in interacting with other applications.
Developing Visual FoxPro Applications

Explains concepts about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.
Development Productivity Tools

Explains that Visual FoxPro provides developer tools for application development within the FoxPro application and the FoxPro language.

Related Sections

Getting Started with Visual FoxPro

Provides information about where to find the Readme file, installing and upgrading from previous versions, configuring Visual FoxPro, and customizing the development environment.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.
Samples

Contains Visual FoxPro class library, server, solutions, and foundation class code samples that you can use for experimenting with and learning Visual FoxPro features.
Walkthroughs

Provides a list of common scenarios in Visual FoxPro and gives step-by-step instructions for each, making it a good place to start learning about features.


Overview of Visual FoxPro Features

Visual FoxPro 9.0
Overview of Visual FoxPro Features

Microsoft Visual FoxPro gives you more of everything you have come to expect in a database management system (DBMS) — speed, power, and flexibility. In addition, Visual FoxPro leads you into the next generation by providing object and event models that help you create and modify applications faster than ever before.

The following topics walk you through some of the major features in Visual FoxPro. For information on the newest enhancements in this version of Visual FoxPro, see What's New in Visual FoxPro.

In This Section

Rapid Application Creation

Discusses how you can develop applications rapidly with help from Visual FoxPro wizards, builders, toolbars, and designers, and implement them quickly using the Visual FoxPro object and event models.
Advantages of More Power

Describes how you can take advantage of Visual FoxPro's object-oriented programming capabilities as well as features such as Rushmore Query Optimization technology to improve performance and speed up application development.
User Interface Creation without Programming

Discusses the powerful controls provided by Visual FoxPro that give you interfaces that require little or no coding.
Application Development with Several Developers

Discusses using Visual FoxPro to enable simultaneous access to database components and using source control programs with the Project Manager to track and protect changes to your source code.
Interaction with Other Applications

Provides information about sharing data with other applications, such as Microsoft Excel and Microsoft Word, using objects from other applications, and controlling other applications using automation.
Client/Server Solution Development

Discusses how you can use Visual FoxPro as a front end for developing robust client/server applications. It combines the higher-level support of updatable views of server data with direct access to native server syntax using SQL pass-through.

Related Sections

Getting Started with Visual FoxPro

Provides links to information about installing, upgrading, and customizing Visual FoxPro, as well as accessing the latest readme files.
Using Visual FoxPro

Provides information on Visual FoxPro programming features and productivity tools, as well as sections on development of Visual FoxPro applications.
Samples and Walkthroughs

Provides examples of common scenarios and step-by-step guides that enable you to learn how to create different types of applications and components in Visual FoxPro.
Customizing the Visual FoxPro Environment

Discusses settings that enable you to customize your development environment, including the main window title, default directory, project, editor, debugger and form tool options, temporary file storage, field mappings for drag-and-drop operations, and many other options.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.
Development Productivity Tools

Provides information on developer tools for application development within the Visual FoxPro application and the language.


Rapid Application Creation

Visual FoxPro 9.0
Rapid Application Creation
See Also

You can develop applications rapidly with help from Visual FoxPro wizards, builders, toolbars, and designers. In addition, with the Visual FoxPro object and event models, you can create prototypes and implement applications quickly.

Getting Quick Results with Wizards and Builders

Using wizards and builders, you can have any or all of the components of your application completed in a matter of minutes. In addition, if any component you create with a wizard or builder does not fully meet your needs, you can alter the component using a designer.

For quick results, wizards are the answer. They provide step-by-step prompts for common tasks you perform in Visual FoxPro. For example, the Table Wizard guides you through the process of creating a table, the Form Wizard creates a form, and the Web Publishing Wizard helps you create a Web page that searches your tables.

Take a look at what you can do:

  • Develop Instant Applications Using the Application Wizard, you can quickly create an application by using your tables and forms, or by using a sample set of application components.

  • Create an Internet Web Page You can create a Web page that provides Web surfers with search and retrieval access to your tables.

  • Add Page Frames to Forms If you choose more fields than can fit on the form, you can add a page frame to display the additional fields on additional pages.

  • Populate Pivot Tables through ODBC or OLE DB The PivotTable Wizard uses the Visual FoxPro ODBC or OLE DB driver.

  • Show Nulls in a Cross-Tab Report The Cross-Tab Wizard now supports displaying null values.

  • Move Your Data to a Back-End Server You can move Visual FoxPro databases, tables, and views from your system to a back-end server with the SQL Server Upsizing Wizard.

If you are in a hurry, use the table in Wizards Overview to select a wizard, and begin creating your application or component.

If you do not want to experiment with your own data and application components, use the samples provided with Visual FoxPro, located in the ...\Samples\Data directory.

Taking Shortcuts with Toolbars

Like other Microsoft applications, Visual FoxPro includes toolbars containing buttons that represent common tasks you perform or objects you use frequently. To perform a specific task or use a particular object, choose the appropriate button.

You can customize the toolbars that come with Visual FoxPro. You can also define custom toolbars for the applications you write. For more information about toolbars, see Customizing the Visual FoxPro Environment or Designing Menus and Toolbars.

Building Controls Quickly

Just as wizards can help to create reports and forms, builders are visual tools that help you design controls to your specifications. Builders can save you time when you are setting up many forms or prototyping applications. All you do is start the builder and answer a series of questions. Using your answers, the builder sets properties for the control you are adding.

Add a Combo Box to Your Form Suppose you want to enhance a simple form you created by adding the ability to select field values from a list, rather than moving through all the records with VCR buttons and viewing the values in a text box. Just replace the current text box with a combo box and use a builder to set the properties.

Modify Existing Controls with a Builder If you want to change an existing control, you can select the control and use a builder to help you set the control's properties.

For example, the Combo Box Builder is a tabbed dialog box that helps you design a combo box on a form. A combo box gives you the same view of a value as a text box control, but allows you to choose from a list like a list box control. With this builder you can set properties of a combo box. As you set each property, the control on the form changes to match the settings.

Build a Grid Control To display a small spreadsheet-like view of your data, you can use a grid control. Even if you aren't familiar with all the properties of a grid control, you can still take advantage of their functionality using a builder. The builder helps you choose the fields for your grid, select a style and layout, and establish relationships between tables bound to the grid control. As you make changes in the builder, they are reflected in the Form Designer.

For more information, see Builders.

See Also

Other Resources

Overview of Visual FoxPro Features
User Interface Creation without Programming
Wizards Overview
Customizing the Visual FoxPro Environment


Advantages of More Power

Visual FoxPro 9.0
Advantages of More Power
See Also

Visual FoxPro is much more powerful than its predecessors. Object-oriented programming speeds up application development through features such as subclassing. The Visual FoxPro event model eliminates the need to use a Foundation READ, or to write event handlers. Optimizing your system settings and taking advantage of Rushmore Query Optimization technology improves the performance of Visual FoxPro.

Harnessing the Power of Object-Oriented Programming

Using the Visual FoxPro object model, you can employ all the features of object-oriented programming including inheritance, encapsulation, polymorphism, and subclassing. For details about object-oriented programming with Visual FoxPro, see Object-Oriented Programming.

You can speed up application development by using classes. For example, you can create a basic form, toolbar, or page frame by using the form, toolbar, or page frame base class provided with Visual FoxPro.

Then you can reuse your code and forms by subclassing the classes you defined. For example, you can subclass the Form base class to create a custom class that automatically gives all the forms in your application the look and feel you want.

The Visual FoxPro class model gives you extensive control over the objects in your application. You have as much control of the appearance and behavior of objects on forms at run time as you do in the Form Designer at design time.

With Visual FoxPro, you can create classes visually with the Class Designer or programmatically with the DEFINE CLASS Command. For more information, see Object-Oriented Programming.

Handling Events with Ease

With Visual FoxPro you can create fully event-driven applications. You can access all standard Windows events such as mouse movements that permit dragging or dropping objects. You can control events visually through the Properties window or programmatically through the Visual FoxPro language. For more information about the event model, see Understanding the Event Model.

Testing and Debugging Immediately

Using the debug environment you can test and debug your code at the same time you design each component of your application and write the code. The Visual FoxPro language has been enhanced to include support for debugging capabilities, collection properties, checking the lock status of files and the current record, Value tips, and more. Also, the debugging tools work independently from the main application and do not interfere with the interface you are trying to test.

Test as You Design The enhanced Visual FoxPro development environment gives you more power to test your component design and code. For example, if you are designing a form, you can click the Run button to run the code. If you want to change something, just click the Design button and make your changes.

Catch Syntax Errors Early The editor now features color-coded editing: you can specify colors for syntax, normal text, variables, comments, and more in the Edit Properties Dialog Box. If you mistype a command or keyword, you'll know right away because it's the wrong color.

Debug with Power

You can debug and monitor your application components more easily in this version of Visual FoxPro using the Debugger Window.

  • View Properties of an Object In the debugger you can view the elements within a collection or array using the Watch Window to show a hierarchical display of an object's properties.

  • Trace the Execution Process of Your Code In the Trace Window you can see each line of code as it executes and check the values of all variables, properties, and environment settings.

  • Control Execution with Breakpoints Using breakpoints you can control when execution stops using one of four types of breakpoints. You can stop at a particular line, when a certain value changes, if a condition evaluates to true, or if a condition for a certain line is true.

  • Set Asserts and Display Assert Messages You can use the ASSERT Command to specify conditions that verify that the code is running properly. When an error occurs, the Debug Output Window records the message.

  • Check the Current Value of a Variable To quickly check values you can place the cursor over a variable in the Trace Window to display a Value Tip.

  • Watch and Change Values In the Watch Window and Locals Window you can change values for properties or variables while you run the code.

  • Display Output from Message Requests In the Debug Output Window you can conveniently display interactive or coded information requests in a separate window from the active window or screen.

  • Use a Coverage Log File In the Debugger Window you can use the coverage option to log the execution information about your code such as how long the line took to execute, the line number, and more.

  • Use the Call Stack In the Call Stack Window you can view the program calling path. Reading the Call Stack is one of the most effective techniques for debugging.

For more information about testing and debugging your application, see Testing and Debugging Applications.

Optimizing Your System

Visual FoxPro brings you improved performance across all these product areas:

  • Engine

  • Form/Object

  • OLE

  • Client/Server

  • Wizards/Builders

  • Language

You can also improve performance by enhancing startup speed and optimizing SET commands. For more information about optimizing your system, see Optimizing Your System.

Optimizing Applications with Rushmore Query Optimization Technology

You can dramatically improve the performance of queries by using Rushmore technology. Rushmore Query Optimization is a technology for rapidly selecting sets of records from tables. It can reduce query response times from minutes or hours to seconds. For more information about using the Rushmore technology, see Optimizing Applications.

See Also

Other Resources

Overview of Visual FoxPro Features
Application Development with Several Developers
Object-Oriented Programming
Rapid Application Creation
Debugger Window


User Interface Creation without Programming

Visual FoxPro 9.0
User Interface Creation without Programming
See Also

Visual FoxPro provides powerful data and user interface controls that you can add to forms using the Form Designer, which makes it possible for you to create a user interface with little or no coding. For example, you can develop one-to-many forms easily by linking a grid control to a table, which you can do by dragging a table onto a form to create the grid control. For consistency with other applications you can also create tabbed dialog boxes or your own builder interfaces with the page frame control.

Creating a One-to-Many Form

Visual FoxPro makes it easy to set up forms to display records from related tables. Using the Project Manager Window and the Form Designer you can just "drag and drop" the fields you need to set up a form.

Try setting up a one-to-many form using two related tables, such as the Customers and Orders tables from Testdata.dbc.

ExclamationPointButton screenshot FoxPro

Specify Tables and Views for Your Form in the Data Environment You can use the data environment for your form or a report to specify the tables or views used by your form. After you have added the tables and views that have the records you want to display in your form, you can drag the fields to the Form Designer.

Create Grids by Selecting Multiple Fields You can select multiple fields and drag them to a form to create a grid object. If you select multiple fields and drag them with the right mouse button, you can choose between a grid and multiple controls. You can also click the Fields item in a table and drag it onto a form to create a grid incorporating all fields in the table. If you right-click a single field and drag it onto a form, you can create a different object class than the one that is assigned as the default object class.

Giving Forms a Professional Look

You can be creative and customize the layout of forms and add colors, shapes, and graphics.

Align controls exactly Use the Layout toolbar to quickly line up controls and space them evenly on the form.

Change the background color Use the Color Palette toolbar.

Add graphics and pictures Use the Line, Shape, and Image buttons on the Form Controls toolbar.

Control Display and Data Entry in a Combo Box You can set the Format Property and InputMask Property for a Combo Box control.

Remove a Border on a Combo Box or Spinner You can use the BorderStyle Property to remove a border from the control. For example, if you are using combo box or spinner controls in a grid, you can clean up the display by removing the extra lines the border adds to the grid.

Use Current Windows Colors for Form Colors You can set an additional option on the ColorSource Property that lets you set the form colors based on the current Windows color scheme.

Setting the Properties on Controls

You can enhance your user interface with the control properties in Visual FoxPro. Using the Properties Window you can see and set the properties associated with each object in your form to determine how a form control looks and behaves.

Use Data Binding with ActiveX Controls To bind data to ActiveX controls you can use the ControlSource Property (if the control supports it) in the Properties window to specify a field or variable to which the control is bound.

Control Navigation in Page Frames By setting the tab order on your page frame you can control the order that pages are displayed. This also adds the ability to navigate to the different pages in a page frame with the right and left arrow keys.

Control Item Selection in List Box and Combo Box Controls When a list box or combo box is bound to a numeric ControlSource, the list index number of the item is collected, rather than the value. To collect the actual value of the selected item in the control, set the BoundTo Property to True.

Select More Than 60 Items in a List Box You can select an unlimited number of multiple items in a ListBox Control.

Create Hidden Properties and Methods You can set accessibility properties on the properties and methods you create to Public, Protected, or Hidden. To change the accessibility of properties and methods, use the Members Tab, Class Info Dialog Box.

For more information about | See
Creating forms | Creating Forms
Using form wizards | Help by pressing F1 from the wizard.
Using builders | Help by pressing F1 from the builder.
Using controls | Help by searching on the control name or Using Controls
Using forms in applications | Creating Forms

Customizing Your Form Designer

To make your work easier, you can customize the Form Designer to match your work style and needs.

Save Changes Automatically You can set options so Visual FoxPro saves your forms automatically when you quit the Form Designer. In the Forms Tab, Options Dialog Box you can choose the option to Save Changes Before Running Form. If you select this option, you skip the confirmation dialog box, and the changes you made to the current form are saved automatically.

Change the Font in the Properties Window You can choose one of three font settings from the Properties window shortcut menu.

Use the Keyboard in the Properties Window The Properties window supports keyboard navigation for scrolling through the hierarchy of objects, controls, and tab orders. Use CTRL+PGUP and CTRL+PGDN to move up and down through the list.

For more information about | See
The Form Designer and form controls | Form Designer
Creating forms | Creating Forms

Add Controls from a Class Library

When you need to add controls to a form so you can navigate through the records in it, you can choose from a library of controls, drag in the controls you need, and run the form. It's that simple.

Adding VCR Controls to a One-to-Many Form

You can use the following example to see how easy it is to streamline your work using controls from class libraries.

Add VCR Controls to a Form By opening the sample button class library (Buttons.vcx) supplied with Visual FoxPro, you can easily add a set of VCR-style navigation control buttons to your form. The sample libraries are in the Visual FoxPro ...\Samples\Classes directory.

Set the SkipTable Property Because this is a one-to-many form, you need to specify that the next record in the main table is selected when you choose the Next button. To do this, open the Properties Window and set the SkipTable property so that it refers to the main table.

Expanding Your Class Libraries

You don't have to wait for someone else to sell you control classes and libraries; you can make your own.

Create Your Own Classes You can create your own controls and save them in class libraries. You can start with standard Visual FoxPro classes and customize them to create your own version, or you can create your own classes.

Point to Classes in Compiled Applications You can use the SET CLASSLIB Command to point to a class included in a compiled application.

Add and Keep Classes on the Forms Control Toolbar When you add a class to the Forms Control toolbar, the class remains on the toolbar until you click the View Classes button again and select Standard.

View Detailed Information about Your Classes Using the Class Browser Window, you can view the entire hierarchy of classes and objects in a class library or form.

Create Your Own Subclasses of ActiveX Controls You can create subclasses of all the ActiveX controls shipped with Visual FoxPro.

For more information about | See
Using the Class Designer | Help by pressing F1 from the Class Designer.
Setting properties | Creating Forms
Creating classes and using class libraries | Object-Oriented Programming

Creating a Menu Bar and Shortcut Menus

You can use the Menu and Shortcut Designers to add a menu bar and menus to forms in your application. With the Menu and Shortcut Designers you can create shortcut menus and menus for SDI forms.

When you create a menu, you have the option of adding a menu to the menu bar or creating a shortcut menu. The Shortcut Designer presents the familiar Menu Designer interface, but allows you to design shortcut menus rather than menu bars and menus.

After you have generated your shortcut menu, you can attach it to any control by running the menu in the control's RightClick Event.

Creating Reports

When it's time to print out important data, you don't want to spend a lot of time formatting reports. That's why Visual FoxPro provides report wizards to streamline the reporting process. With report wizards you can select the data you want from your tables and views, and present it in your choice of professional looking formats.

Using the Visual FoxPro report design features, you can:

Use the Preview Button The last screen of a report wizard has a Preview button so you can quickly see if your report is the way you like it. If not, use the Back button in the wizard and make the necessary adjustments.

Use Quick Report for Fast Results If you're setting up your own report in the Report Designer, choose Quick Report from the Report menu to add selected fields from a table to a report.

Use Query or View Results in a Report Want to print out the results of a query? Choose the Report option in the Query Destination Dialog Box. You can send the query results to a pre-formatted report or send the query to a report wizard.

Create a One-To-Many Report The One-To-Many Report Wizard makes it easy to set up a report that shows fields from two tables joined in a one-to-many relationship. For example, try using the wizard to create a report from two related tables in Testdata.dbc.

Use Other Report Wizards Try using the other report wizards. For simple one-table reports or summary reports with totals, choose Report Wizard.

Use the Report Designer If you want to customize your wizard-generated report further, just open it in the Report Designer and add the enhancements you need.

For more information about | See
Report Wizard | Help by pressing F1 from the wizard.
Report Designer | How to: Create Reports

See Also

Other Resources

Overview of Visual FoxPro Features
Rapid Application Creation
Form Designer
Creating Forms


Application Development with Several Developers

Visual FoxPro 9.0
Application Development with Several Developers
See Also

If you have several developers working on your applications, you can use Visual FoxPro's ability to allow simultaneous access to database components. Also, for tracking and protecting changes to your source code, you can use source control programs with the Project Manager.

Let Several People Work on Database Objects You can now modify tables and view definitions, without exclusive access to the database. Use the Refresh option on the Database menu – this reloads the database object definition to reflect any changes made by other users.

Use Source Code Control You can use a source code control program such as Microsoft Visual SourceSafe to coordinate and manage changes to applications you develop in Visual FoxPro. The Project Manager provides access to source code control on the Project menu.

For more information about working with several developers, see Planning for Team Development Projects .

See Also

Other Resources

Overview of Visual FoxPro Features
Interaction with Other Applications
Planning for Team Development Projects
Advantages of More Power


Interaction with Other Applications

Visual FoxPro 9.0
Interaction with Other Applications
See Also

With Visual FoxPro you can share data with other applications such as Microsoft Excel and Word, use objects from other applications, and control other applications using Automation.

Sharing Data with Other Applications

You can take advantage of all the software tools on your desktop with Visual FoxPro.

Use Your FoxPro Data in Other Applications Sharing data with other applications is easy – for example, you can share Visual FoxPro data with Microsoft Excel by using the PivotTable Wizard, or with Microsoft Word by using the Mail Merge Wizard.

Display or Store Objects from Other Applications You can include objects from another application by linking or embedding them in tables or in forms. Then you can edit the objects directly, without leaving Visual FoxPro.

Importing and Exporting Data

You can import and export data between Visual FoxPro and many other applications using a variety of file formats: text, spreadsheets, and tables, to name a few. The data can be appended to or copied from existing tables easily. The Import Wizard helps you make decisions about the structure you want the data to take in Visual FoxPro.

For more information, see Importing and Exporting Data.

Integrating with Automation

With Visual FoxPro you have the power to fully integrate your application with other applications.

Control Other Applications You can extend the power of your application by controlling other applications programmatically. For example, you can direct Microsoft Excel to perform some calculations, instruct Microsoft Graph to chart the results, and then store the chart in a General field of a Visual FoxPro table, all from Visual FoxPro code. Or, you can add ActiveX controls that you or someone else developed.

Optimize Automation Requests You can determine how much time your system uses for requests and how long it takes for messages to appear for your user. For example, you can control how much time your system spends retrying Automation requests before displaying a "server busy" message.

You can also control the number of milliseconds that pass during user input, such as using the mouse or keyboard while an Automation request is pending, and a "busy" message appearing.

Control Visual FoxPro from Other Applications Using Visual FoxPro as an Automation server, you can create references to Visual FoxPro objects, execute Visual FoxPro commands, and run Visual FoxPro programs from other applications.

For more information on Automation, see Sharing Information and Adding OLE.

See Also

Other Resources

Overview of Visual FoxPro Features
Client/Server Solution Development
Importing and Exporting Data
Application Development with Several Developers


Client/Server Solution Development

Visual FoxPro 9.0
Client/Server Solution Development
See Also

You can use Visual FoxPro as a front end for developing robust client/server applications. Visual FoxPro combines the higher-level support of updatable views of server data with direct access to native server syntax using SQL pass-through. This gives you a solid foundation on which to build versatile client/server solutions. A full-featured data dictionary, local and remote views, null support, transactions, international application support, and access to ODBC data sources all contribute to the features you need for client/server development.

Increasing Client/Server Performance

You can increase the performance of your client/server application using the properties and ODBC driver provided in Visual FoxPro.

Controlling Performance with Properties

You can increase performance by using the following cursor and remote view properties:

  • CompareMemo

  • FetchAsNeeded

  • Prepared

You can display these properties using the DBGETPROP( ) Function and CURSORGETPROP( ) Function functions, or set the properties with the DBSETPROP( ) Function and CURSORSETPROP( ) Function functions.

Include or Exclude Memo Fields in Update Detection You can use the CompareMemo property to control when memo fields are used to detect update conflicts. This view and cursor property determines whether memo fields (types M or G) are included in the update WHERE clause. The default setting, True (.T.), means that memo fields are included in the WHERE clause. If you set this property to False (.F.), memo fields don't participate in the update WHERE clause, regardless of the settings of UpdateType.

Optimistic conflict detection on Memo fields is disabled when CompareMemo is set to False (.F.). For conflict detection on memo values, CompareMemo should be set to True (.T.).

Fine Tune Record Fetching Use the FetchAsNeeded property to specify if all rows are fetched progressively, or only those within the row set determined by the FetchSize property. If you want to fetch all of the rows in the result set using the Visual FoxPro idle loop, use the default setting, False (.F.). If you want to fetch only when the user scrolls beyond the row set determined by the FetchSize property, set FetchAsNeeded to True (.T.) to fetch the next row set.

Speed Up Re-query Operations on Parameterized Views Using the Prepared property, you can set whether the query for the view is prepared before it is executed. If you set this property to True (.T.), Visual FoxPro sends a request to the ODBC driver to prepare or compile the SQL query that defines the view. If the ODBC driver for your back-end data source supports the use of prepared statements, subsequent re-queries on the open view are executed faster.

Defining Rules with the Data Dictionary

Visual FoxPro databases (.dbc files) provide a data dictionary that allows you to add rules, views, triggers, persistent relationships, and connections to every table in a database.

Within a database you can define:

  • Field-level or record-level rules that Visual FoxPro enforces wherever the table is used in an application.

  • Primary and candidate index keys.

  • Local and remote views.

  • Triggers.

  • Persistent relationships between database tables.

  • Connections to remote data sources.

  • Stored procedures.

  • Default values on fields.

  • Long table and field names.

In addition, you can enforce referential integrity for every persistent relationship by using the Referential Integrity Builder to define rules for inserts, updates, and deletes.

Visual FoxPro also supports null values in tables, greatly improving compatibility and connectivity with other data sources such as Microsoft Access, Visual Basic, and SQL-based servers. For details about null values, search for "null" and "null values".

Each Visual FoxPro database is completely user-extensible, with access through language enhancements and the visual designers. For more information about databases and data dictionaries, see Developing Databases.

View Local, Remote, and Offline Data You can design and test a client/server application on your local computer using data from remote, local, or multiple-table heterogeneous views. Local views use tables on your local computer rather than tables on a remote server, and multiple table views use related data from separate tables. You can create parameterized views to minimize the amount of data you download from the server, take the data on the road, or update remote data from your Visual FoxPro application. For more information about views, see Working with Views.

Manage Shared Access with Transactions You can design your application to provide shared access to data. Shared access involves sharing data among users and restricting access when necessary. Transactions and buffering — pessimistic or optimistic, record-level or table-level — mean less programming for you. Built-in batch processing and detailed control over handling update conflicts simplifies updating data in a multiuser environment. For details about designing your application for shared access, see Programming for Shared Access.

Develop International Applications Visual FoxPro provides several areas of support for developing international applications. For example, Visual FoxPro supports several code pages. The code pages for Greek and Russian are supported on MS-DOS, Microsoft Windows, and Macintosh platforms. Visual FoxPro also supports double-byte character sets for languages such as Japanese, Korean, Traditional Chinese, and Simplified Chinese; however, Unicode is not supported. Visual FoxPro supports collation sequences for languages such as Japanese, German, Traditional Chinese, and Icelandic. For more information about international applications, see Developing International Applications.

Implement a Client/Server Application In addition to using views for client/server development, you can send any native server syntax you want directly to a server with Visual FoxPro SQL pass-through functions. These functions permit additional server access and control beyond the capability of views. For details about SQL pass-through see Enhancing Applications using SQL Pass-Through Technology.

After designing your application locally, you can upsize and implement it against a back-end data source. Upsizing applies the benefits of client/server architecture to the local application and allows you to create a remote server database with the same table structure and data as the original Visual FoxPro tables. When you upsize, you choose which tables move to the server and which remain locally for more immediate access. For details about upsizing see Upsizing Visual FoxPro Databases.

See Also

Other Resources

Overview of Visual FoxPro Features
Upgrading from Earlier Versions
Developing Databases
Creating Views
Programming for Shared Access
Interaction with Other Applications


Developing Visual FoxPro Applications

Visual FoxPro 9.0
Developing Visual FoxPro Applications

Visual FoxPro provides an extensive set of tools and technologies so you can rapidly build flexible solutions with powerful data handling capabilities. The Visual FoxPro application development environment helps you with all aspects of application development.

In This Section

Application Planning

Provides information and considerations, such as topics about design, architecture, and security, to help you plan your applications carefully.
Creating Applications

Provides an overview and phases involved with creating an application.
Working with Data

Provides an overview and information about using data in your applications, for example, analyzing data requirements and designing your application components to meet those requirements.
Enhancing Applications using SQL Pass-Through Technology

Describes techniques for implementing client/server technology in a working application that uses remote views.
Web Services and Components

Describes ways to extend applications to make them work for multiple users.
Optimizing Applications

Describes ways to optimize performance by making your application.
Testing and Debugging Applications

Discusses testing and debugging as necessary stages in the development cycle. The best results come from writing understandable and maintainable code and using the available debugging tools.
Compiling an Application

Describes building your application by compiling code and provides information about referencing modifiable files and building an application file from your project.
Configuring Help Files for Applications

Describes how to configure access to Help files that you create for your application.
Distributing Applications

Provides information about preparing your application for distribution.

Related Sections

Using Visual FoxPro

Discusses the Visual FoxPro programming environment and tools that help you create and manage high-performance database applications and components.
Programming in Visual FoxPro

Describes how understanding object-oriented programming and the event-driven model can maximize your productivity and enable you to access the full power of Visual FoxPro.
Optimizing Applications

Provides information on how to get the best performance from your operating system, Visual FoxPro, and your application.


Application Planning

Visual FoxPro 9.0
Application Planning

Careful planning saves time, effort, money, and sanity. The more you involve your end users in the planning process, the better. No matter how carefully you plan, though, you'll probably end up refining the specifications as you progress through the project and your end users provide feedback.

In This Section

Design Considerations

Discusses how the design decision you make will impact how you create your application.
Application Architecture

Describes how Visual FoxPro application architecture varies with the type of application you decide to create.
Security Considerations

Shows how you should be aware of security requirements from a business perspective and the implications that a chosen security model can have on performance, scalability, and deployment.
Planning for Team Development Projects

Discusses how using source control software, such as Microsoft Visual SourceSafe, to manage the files in a project makes it possible to create complex applications quickly by combining the skills of a team of developers.
Developing International Applications

Shows how to design Visual FoxPro applications so they are as effective internationally as domestically using the international features of Visual FoxPro.

Related Sections

Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Creating Applications

Discusses how to create Visual FoxPro application, which may include one or more databases, a main program that sets up the application's system environment, and a user interface comprised of forms, toolbars, and menus.
Working with Data

Discusses how to create effective applications with indexes, tables, and databases based on your data requirements.
Working with Projects

Defines a project a configuration and a group of files that produce a program or final binary file or files.


Design Considerations

Visual FoxPro 9.0
Design Considerations
See Also

Some of the design decisions you make impact how you create parts of the application. Some of the considerations you need to take into account include:

  • Central or common tasks users perform.

  • Size of the data set needed.

  • Single or multiple users.

  • People that the application users include.

  • Local or remote data.

Common User Activities

Even if your end users are working with customers, orders, and parts, how they are working with this information will determine how your application should deal with the data. An order entry form might be necessary for some applications, but would not be a good tool for managing inventory or tracking sales, for example.

Database Size

If you are working with large sets of data, you need to consider performance issues. You might want to change the way users navigate data. For example, if you have a small number of records in a table, you can let users navigate records in the table one record at a time. However, if you have a large number of records, consider providing other ways for users to access the data, for example, using lists, dialog boxes, filters, custom queries, and so on. For more information, see Optimizing Applications, Using Controls, and Displaying Data in Views.

Single User vs. Multiple Users

It's a good idea to create your application with the assumption that multiple users will be accessing the database at the same time. Visual FoxPro makes it easy to program for shared access. Programming for Shared Access describes techniques for allowing multiple users to simultaneously access your database.

International Considerations

If you know your application will be used only in a single-language environment, you don't have to worry about internationalization. If, on the other hand, you want to expand your market, or if your users could be dealing with international data or environment settings, you'll want to take these factors into account as you create the application. Developing International Applications discusses the issues you'll need to deal with as you develop applications for international use.

Local vs. Remote Data

If your application deals with remote data, you'll manage it differently than you would manage native Visual FoxPro data. How to: Create Views explains how to create views to local or remote data.

Backing up Your Source Code

In all application development, it's a good practice to make complete backup copies of your original program files before you build an application. Store the backup copies separately from your compiled applications.

Note:
Be sure to maintain separate copies of your original source programs for future use. You cannot re-create your source programs from their compiled code.

See Also

Other Resources

Application Planning
Developing International Applications
Programming for Shared Access
Optimizing Applications


Visual FoxPro as an Application Front End

Visual FoxPro 9.0
Visual FoxPro as an Application Front End
See Also

As a Visual FoxPro developer, you probably find it natural to design your applications around the program's visual design tools. For example, you probably think of your application's user interface in terms of Visual FoxPro forms, menus, and reports. In addition, when you develop applications in Visual FoxPro, you most likely think of storing the application's data in Visual FoxPro tables.

One way to integrate Visual FoxPro into an enterprise-wide application is to use the visual design tools in Visual FoxPro, but enhance them with the capabilities of other products. Another way is to create your application's look and feel using Visual FoxPro, but to extend the data storage capabilities of your application by taking advantage of the capabilities of other programs or of non-Visual FoxPro data storage options. You can also upsize your Visual FoxPro data by moving it to a database server.

Extending the Visual Design Tools in Visual FoxPro

The base classes of Visual FoxPro controls were designed to accommodate the vast majority of application interface needs. Visual FoxPro provides all the basic controls and interface elements that are required to create a standard Windows application. However, you will often find that your application requires objects or controls beyond those provided in the base Visual FoxPro classes. If so, you can extend the visual design tools by creating subclasses and by using ActiveX controls.

Creating Subclasses

An extremely powerful feature of Visual FoxPro is the ability to create subclasses of the base controls. By creating one or more subclasses, you can customize the basic Visual FoxPro controls in almost any way that's required for your application. This ability extends to being able to create new objects or controls that combine the features of other controls. For example, the grid control in Visual FoxPro contains not only its own container, properties, and methods, but those of the objects that appear in the grid such as buttons, text boxes, and so on.

Similarly, by subclassing base controls, you can extend the capabilities of Visual FoxPro by creating objects that add new features to existing base classes, or that combine the capabilities of several objects. For example, you can add visual features such as frames or three-dimensional effects to a text box. Or you could combine an image control, buttons, and a text box to create a bitmap-viewing control in which users can move through a series of .bmp files. Creating custom classes in this way can help you manage company-wide development by allowing you to create standardized controls that appear in all your applications. For more information, see Object-Oriented Programming.

Using ActiveX Controls

An alternative to creating a new control using subclasses in Visual FoxPro is to use an ActiveX control (.ocx file). These controls are created independently from Visual FoxPro, and can be integrated not only into Visual FoxPro, but into many other Windows applications as well.

In effect, ActiveX controls are off-the-shelf components that you can integrate seamlessly into your application. Using ActiveX controls provides several benefits:

  • It saves you the time and effort required to create, test, and maintain a Visual FoxPro-specific control to accomplish the same tasks. The more capable the ActiveX control, the more time you save.

  • Many ActiveX controls are already available from third-party suppliers to answer common application requirements. For example, if your application calls for you to display a calendar and allow users to choose dates on it, you can probably find an ActiveX control (perhaps several) that already manages this task.

  • The same control can be used in multiple programs. For example, if it makes sense to do so, you can use the same ActiveX control in Visual FoxPro and Visual Basic. The same properties and methods are used in each case to manage the control, and the control will have the same appearance in all programs, making it easier for users to work with.

  • ActiveX controls often provide access to Windows functionality that can otherwise be awkward or time-consuming to include using only Visual FoxPro tools. For example, you can find ActiveX controls that provide access to electronic mail (using Windows MAPI functions), to low-level Windows graphics functions, and so on. By including an ActiveX control, you can add these types of features to your application in a way that's easy to control using the ActiveX control's properties, methods, and events.

In short, using ActiveX controls enables you to extend your applications not only by integrating Windows-wide functionality, but by adding a common look-and-feel between your application and others in the same enterprise. For more information about using ActiveX controls, see Sharing Information and Adding OLE. For information about creating your own ActiveX controls, see Accessing the Visual FoxPro API.

Integrating Functionality from Other Programs

You might find when developing an application that other programs are uniquely suited to accomplishing certain tasks. For example, Microsoft Word has unsurpassed merge letter capabilities, while Microsoft Excel is optimized to calculate complex formulas and easily create charts and graphs from them.

Rather than emulating these capabilities in Visual FoxPro, you can make your application an enterprise-wide solution by integrating them into your application. This way you can match the requirement of your application to the best possible tool to address it.

You can integrate the functionality of other applications into Visual FoxPro in these ways:

  • Run a Visual FoxPro wizard that makes Visual FoxPro data available for use by another application.

  • Write Visual FoxPro programs that use Automation to communicate with, control, and share data with other Windows programs.

The following sections provide details about these methods of extending the capabilities of Visual FoxPro.

Using Wizards

A number of Visual FoxPro wizards allow you to integrate Visual FoxPro data with the functionality of other Windows programs. For example, you can send form letters to your customers by using the Mail Merge Wizard. When you run the wizard, you can specify a table or view that contains the Visual FoxPro data to use, and then either export the data to a suitable file format (such as comma-delimited) or specify that your word processing program use the Visual FoxPro OLE DB provider to access the data. If you use Microsoft Word, the wizard will even start the word processing program, create the blank merge document, and display the Mail Merge toolbar for you to link fields to your Visual FoxPro data.

Similarly, using Microsoft Excel and Microsoft Query, you can analyze your data using a pivot table, which summarizes data in columns and allows you to rearrange it to view it in different ways. By using the PivotTable Wizard in Visual FoxPro, you can use your application data as the source data for Microsoft Excel, and generate the pivot table in Microsoft Excel.

Using Automation

A more powerful way to interact with other applications is to use Automation. Using Visual FoxPro programs, you can access the objects exposed by other applications, and then control them by setting their properties and calling their methods. For example, Microsoft Excel exposes an application object as well as worksheets, columns, rows, and cells within the application object. You can directly manipulate any of these objects, including getting or setting data in them. In addition, you can usually control the application object using the full range of commands available in the program itself. For example, by managing the application object in Microsoft Excel, you can open, save, or print worksheets, invoke the Microsoft Excel chart wizard, and so on.

Automation is a particularly attractive and powerful way to work with Windows programs using Visual FoxPro for several reasons:

  • You have direct access to the other program, including all its objects and commands.

  • You can share data directly with the other program without having to export it or convert it to another format.

  • You can control the other program using the familiar properties and methods model.

  • The other program doesn't necessarily need to be visible to the user when you invoke it. For example, you can invoke Microsoft Excel, place some data into cells, run a complex calculation on the data, read the result, and then display it in Visual FoxPro, all without ever displaying Microsoft Excel. Your user would continue to see only Visual FoxPro, unless you explicitly wanted to display Microsoft Excel.

  • The commands (methods and properties) to control the other program are embedded within familiar Visual FoxPro programs. You don't need to learn a different programming language in order to be able to control the other program.

Automation is particularly powerful because it's an open-ended method for working with other programs. In essence, Automation simply makes available to you the data and commands from other applications for you to use in the way best suited to your application.

A sample scenario illustrates how you can integrate several Windows programs. Imagine that you store your customer and sales data in Visual FoxPro. You'd like to create a sales report that summarizes quarterly sales.

One solution would be to use Automation to copy the Visual FoxPro sales data to cells in a Microsoft Excel worksheet. You can then invoke the Microsoft Excel chart wizard to create a chart of the data and copy it to the Windows Clipboard. Still using Automation, you can invoke Microsoft Word and create or open a sales report document (if you create it as a new document, you can insert standard text that you store in Visual FoxPro), and then paste in the chart you created in Microsoft Excel.

This is just one way you can use Automation to make Visual FoxPro part of an enterprise-wide solution. By becoming familiar with the objects and methods available in programs that you typically use, you can imagine many more ways to make each program enhance the capabilities of the other. For details about Automation, see "Manipulating Objects with Automation" Sharing Information and Adding OLE.

Extending Data Storage Capabilities in Visual FoxPro

The data table and indexing capabilities of Visual FoxPro are usually more than adequate to the requirements of an application, whether you're concerned about speed or database size. However, there are times when you might want to extend Visual FoxPro by using data that's stored in some other format. This might be true if:

  • Your application needs access to legacy data that's created and maintained by an existing application. For example, suppose that, as part of your sales application, you need access to data being maintained by an accounting application that was written using a different program, perhaps even on a different platform.

  • You want to optimize data access by using a database server, which can greatly speed data access, particularly in very large databases.

  • You want to share data with other programs, and therefore want to store the data in a format that's accessible to all the programs.

  • The data is best suited to the format of a particular program (such as a spreadsheet). This might be true, for example, if your application required only occasional access to data that was otherwise being maintained by the other program.

If the data you need is in the format of a spreadsheet, word processing document, or other Windows program, you can access it using Automation. For example, you might do this if your application required a collection of form letters. In that case, the letters might be stored as Microsoft Word documents, and your application would use Automation to invoke Word, open the appropriate letter, and insert or substitute text as necessary.

A more common approach to using non-Visual FoxPro data is to use an OLE DB provider to access it. OLE DB providers allow you to connect to data in the format of other programs — typically other database programs — and query or edit the data using standard SQL commands.

For example, you might decide that security and transaction processing capabilities are a vital part of your application, so you decide to store the data using Microsoft SQL Server. To access the data, you define a connection to SQL Server, using the SQL Server OLE DB provider. You can then run queries and other SQL commands using ADO, and retrieve the results into an ADO recordset or a CursorAdapter for further processing in Visual FoxPro.

Other applications can access the same data and take advantage of the same features. For example, a Microsoft Excel worksheet can get its data from the same SQL Server database. Not only will the worksheet enjoy the same performance advantages that your application does, it can also take advantage of the security and transaction processing features of the server, which aren't otherwise available in a Microsoft Excel worksheet.

In some instances, you might want to go further and use SQL commands that are specific to the data source you're accessing with the OLE DB provider. For example, Microsoft SQL Server allows you to create and run stored procedures, which can manipulate data at the server (rather than in your application). To take advantage of stored procedures, you can send "native" SQL statements to the database server. Pass-through SQL commands also allow you to perform system administration tasks on the server, and in some instances they will execute faster than similar SQL statements executed in Visual FoxPro.

For more information about extending data storage capabilities in Visual FoxPro, see Manipulating Objects with Automation, Accessing Remote Data Using Views, and Planning Client/Server Applications.

Upsizing Visual FoxPro Data

You can choose to keep your data in Visual FoxPro tables or on another platform such as a database server. Or you can do both: keep your data in Visual FoxPro tables while you're developing, or until your database grows large, and then move (or upsize) the data to another platform.

For example, you can prototype your application by keeping all the data in local Visual FoxPro tables. This gives you the flexibility to modify your tables, views, and indexes as you develop the application without the complexities of managing tables on a database server. You can keep sample data in the local tables so you can test your forms, reports, and other programs. When the database structure is complete, you can upsize your data to a database server and put the application into production.

Another way to work is to keep your data in Visual FoxPro tables only as long as is practical. When the database grows large, you can upsize it and take advantage of the optimized performance provided by a database server. The exact point at which it makes sense to upsize your database depends on many factors, including the complexity of the database, the performance of your local computer or network, and the demands of your application.

Finally, you can prototype your database in Visual FoxPro, and then upsize it in order to share the data with other applications that can also access a database server. Similarly, you can upsize the database in order to take advantage of the security and server-side transaction processing capabilities of the database server.

For details on upsizing databases, see Upsizing Visual FoxPro Databases.

See Also

Other Resources

Design Considerations
Planning Enterprise Applications
Visual FoxPro as an Application Back End
Object-Oriented Programming
Sharing Information and Adding OLE
Creating Views
Accessing the Visual FoxPro API
Mail Merge Wizard
PivotTable Wizard


Visual FoxPro as an Application Back End

Visual FoxPro 9.0
Visual FoxPro as an Application Back End
See Also

A different way to integrate Visual FoxPro into an enterprise solution is to use it as one component, but not necessarily as the primary application. In effect, you'd be treating it as a back end for an application written using another product. In this case, the user wouldn't directly see Visual FoxPro. Instead, the application's user interface would be written using tools in the other application, and would communicate with Visual FoxPro in the background to get or manipulate data.

Visual FoxPro works well in this role because it can make available its database engine, which provides rapid data access to other applications. In addition, Visual FoxPro can make its objects and command sets available to other programs, including custom objects that you create.

Making Visual FoxPro Data Available to Other Programs

One way for an enterprise-wide application to take advantage of Visual FoxPro is to use the Visual FoxPro database engine for storing and managing data. This provides high-performance storage and query capability to other programs.

Programs can connect to Visual FoxPro data using the Visual FoxPro OLE DB provider. This provider exposes the Visual FoxPro database engine to standard Visual FoxPro SQL commands.

For example, an application might use Microsoft Excel as a calculation tool for complex data analysis. If the data to be manipulated is highly fluid, it might make sense not to store it in a worksheet, but in a database. The worksheet could then be written to use the Visual FoxPro OLE DB provider to connect to the database, extract the relevant information, and display it in a worksheet for further processing.

Another example might be a kiosk application, such as an information stand at an airport or convention center. You could create the information display using a multimedia authoring program. But if some of the data in the application changed often, it would be cumbersome to change pages in the presentation. Instead, the presentation program could connect to a Visual FoxPro database using the OLE DB provider, and then extract data at run time.

For more information, see the Visual FoxPro OLE DB provider help topics.

Making Visual FoxPro Objects and Commands Available to Other Programs

In addition to making Visual FoxPro data available to other programs as part of an enterprise solution, you can expose Visual FoxPro objects and commands. Other applications can call the methods and set properties of objects in Visual FoxPro, including not only the base objects, but objects defined in custom classes.

For example, you can create an application in Microsoft Excel that stores data in a Visual FoxPro database. In addition to simply reading and writing the data, Microsoft Excel can call Visual FoxPro commands to display a form as a dialog box. One use might be to gather data for a parameterized view.

Another way to expose Visual FoxPro objects is to create an Automation server. This allows you to create application-specific objects that can perform almost any function that you can program Visual FoxPro to accomplish, with the further advantage that you can distribute the server.

One use for a custom server is to create an object that includes a set of business rules that ensure the integrity of data that another application passes to it. For example, you can create an object in Visual FoxPro for storing employee information that not only validates that the application has passed valid employee information, but checks the user's access level to ensure that the user has security access to make the employee changes.

A custom server can also expose an object that incorporates complex logic for updating or reading information. For example, an order entry object might not only be able to store the order, but could also maintain a transaction log of orders, update inventory, calculate a sales commission, and so on.

This type of Automation server is ideal for creating the middle layer of a three-tiered enterprise application. In this model, the data forms the lowest level and the application forms the highest. The functionality is in the middle, and provides a specific, application-independent view of the data that incorporates business rules (or other data processing capabilities) that don't properly belong with the data or with the application alone.

For information about creating custom Automation servers, see How to: Create Automation Servers in Sharing Information and Adding OLE.

Creating a Data Warehouse Using Visual FoxPro

In addition to creating your application in Visual FoxPro, you can use the program to create and maintain a data warehouse, or version of your data that is optimized for reporting. To create a data warehouse, you make a copy of the data required for reporting, and then make it available to users who need it. By maintaining this data separately from your live data, you can:

  • Structure it to make reporting easier or faster than if users created reports from the live data.

  • Place data for reports in a location separate from the live data, which reduces contention for data, improves performance, and can make data available to users who shouldn't see live data for security purposes.

A data warehouse is a snapshot of the data at the time you create it. You refresh the data in the warehouse periodically, scheduling the update according to the reporting needs for your application.

For example, imagine that you're creating an application to manage a library, including an inventory of materials. During the day, the system is in constant use as patrons check materials in and out, and query the system to locate or reserve books. In addition to managing these individual transactions, librarians want to be able to analyze their library, to determine facts such as what materials are the most popular, what books are overdue, and so on.

To help with the analysis, the application can create a data warehouse out of the transaction information. The application can warehouse the data periodically, perhaps every night, and the librarians can create queries without affecting the performance of the system during the day. In addition, the data warehouse can exclude details about the patrons using the library, because this information isn't required for the analysis and might be considered confidential information.

To get the most benefit from a data warehouse, you create it on a server separate from the live data. If the live data and data warehouse are on the same server, you can still get the benefit of having optimized data in the warehouse. However, as users make queries against the warehouse, they can generate a large amount of network traffic, which might affect performance of the live system.

When you create the data warehouse, you can simply copy the live files over to parallel files in the data warehouse. Alternatively, you can restructure the data in the warehouse to optimize it for reporting. For example, you might create indexes for the warehouse data that reduce reporting overheard.

As another example, data in the live application should be normalized in order to avoid data duplication. However, in the data warehouse it might be useful to combine tables that would otherwise be separate; this can eliminate the need to join tables, making it easier for less experienced users to create reports.

You can also match the level of detail in the data warehouse to the reporting requirements of your application. For the most flexibility, you should store the same level of detail in the data warehouse as you have in the live data. However, if users wanted to create only summary reports (such as spreadsheets or charts), you could roll up detail data from the application and store only summary data in the data warehouse.

Using Visual FoxPro as a World Wide Web Search Engine

If your enterprise solution involves creating a World Wide Web server for the Internet, you can incorporate Visual FoxPro into the application as a search engine. This allows you to make the power of your Visual FoxPro database available to anyone who can access your Web server, whether on the Internet or via a company intranet.

For example, imagine that as part of your company-wide intranet you want to make available an employee directory. Employees could point their browsers to a "Search for Employee" page, which would display a page that looks like a Visual FoxPro form, containing text boxes to enter criteria. To perform a search, users would enter the employee's name, phone extension, department, position, or any other information they had available, and then choose a Search Now button. In a moment or two they would see a listing of the employees who met the search criteria. They could then save this listing as a text file that could then be imported into another program, such as a word processor.

Understanding Visual FoxPro as a Web Search Engine

In general, in order to use Visual FoxPro as an information server for the Web, you need these components:

  • An existing Web server with HTTP service, running on Microsoft Windows NT or Windows 2000 operating system.

  • A Visual FoxPro application that can be called as an Automation server. This application can run on any server accessible to the Web server.

  • A means for displaying search results, which usually consists of a Web page template into which you can insert data.

The usual sequence of events that involve a Visual FoxPro search on the Web are these:

  1. The user displays your application's search page by pointing a Web browser to it. The search page includes any text and graphics that you want, plus text boxes in which users can enter search text.

  2. The user chooses a "Search Now" button. The data from the completed form is sent to the Web server for processing, along with the name of your Web page search application.

  3. The Web server calls your application using ISAPI (Internet Server API) protocol, passing to it a parameter containing the search information.

  4. Your application searches the database. When it gets results, it inserts them into a Web page template, and then sends the Web page back to the server as a stream of characters.

  5. The Web server sends the results page to the browser that initiated the search.

  6. The browser displays the results page for the user.

If you've created Web pages, most of the steps in this process are probably familiar. For example, you might already know how to create Web pages. Even if you aren't already familiar with Web page design, you'd probably find the process of creating these pages relatively easy.

For an example of how to use Visual FoxPro as a Web search engine, see the sample Foxisapi.dll in the Visual FoxPro ...\Samples\Servers\Foxisapi directory. Refer to the Readme.txt file in that directory for details about how to run the example.

See Also

Other Resources

Design Considerations
Visual FoxPro as an Application Front End
Planning Enterprise Applications
How to: Create Automation Servers
Sharing Information and Adding OLE


Application Architecture

Visual FoxPro 9.0
Application Architecture

Visual FoxPro application architecture varies with the type of application you decide to create. When designing the structure of your application, consider the function each component provides and its relationship to other components.

For example, a typical database application consists of data structures, a user interface, query options, and reporting capabilities. A typical assembled Visual FoxPro application provides the user with a menu and one or more forms for entering or displaying data. You can provide functionality and maintain data integrity and security by attaching code to certain events. Queries and reports make it possible for your users to extract information from the database.

In This Section

Planning Client/Server Applications

Discusses the importance of planning in building a successful client/server application. Proper planning will help you build the fastest, most productive application for your users.
Rapid Application Development

Describes the fundamental steps in application development, prototyping, upsizing, implementing, and optimizing.
Application Creation with Accuracy and Data Integrity

Describes how to use Visual FoxPro data validation rules and stored procedures with the data source's data validation rules and stored procedures to build client/server applications that protect data integrity.
Planning Enterprise Applications

Explains how you can use Visual FoxPro as part of a larger-scale application that involves two or more development tools, which makes is possible for you to take advantage of the unique capabilities of each product.

Related Sections

Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Application Planning

Describes how careful planning saves time, effort, and money. Many of the decisions you make during the planning phase will impact how you create elements of the application.
Design Considerations

Discusses how the design decision you make will impact how you create your application.
Security Considerations

Shows how you should be aware of security requirements from a business perspective and the implications that a chosen security model can have on performance, scalability, and deployment.
Planning for Team Development Projects

Discusses how using source control software, such as Microsoft Visual SourceSafe, to manage the files in a project makes it possible to create complex applications quickly by combining the skills of a team of developers.
Developing International Applications

Shows how to design Visual FoxPro applications so they are as effective internationally as domestically using the international features of Visual FoxPro.


Planning Client/Server Applications

Visual FoxPro 9.0
Planning Client/Server Applications

Microsoft® Visual FoxPro® provides you with the tools to create powerful client/server applications. A Visual FoxPro client/server application combines the power, speed, graphical user interface and sophisticated querying, reporting, and processing of Visual FoxPro with the seamless multiuser access, massive data storage, built-in security, robust transaction processing, logging, and native server syntax of an ODBC data source or server. The synergy of Visual FoxPro and server strengths provides a powerful client/server solution for your users.

The most important step in building a successful client/server application is creating a good design. When you design a client/server application, you're balancing several sets of requirements. You want to build the fastest, most productive application for your users. You also want to ensure the integrity of application data, make the most of existing hardware investments, and build in scalability for the future. In addition, as a Visual FoxPro developer, you want to make the development process as streamlined and cost-efficient as possible.

In This Section

Optimizing Client/Server Performance

Building a fast, high-performance client/server application with Microsoft® Visual FoxPro® involves taking advantage of the tremendous speed of the Visual FoxPro engine.
Performance Enhancement through Set-Based Data Access

Explains how you can build a fast, efficient client/server application by minimizing the amount of data you pull down from the server.
Data Location on the Optimal Platform

Learn how to get maximum performance by storing data and other attributes of your database on the optimal platform.

Related Sections

Developing Visual FoxPro Applications

This section includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Application Architecture

Learn how Visual FoxPro application architecture varies with the type of application you decide to create.
Structure of Visual FoxPro Applications

Describes how a typical database application consists of data structures, a user interface, query options, and reporting capabilities.
Rapid Application Development

Describes the fundamental steps in application development, prototyping, upsizing, implementing, and optimizing.
Application Creation with Accuracy and Data Integrity

Learn how to use Visual FoxPro data validation rules and stored procedures with the data source's data validation rules and stored procedures to build client/server applications that protect data integrity.
Planning Enterprise Applications

Explains how you can use Visual FoxPro as part of a larger-scale application that involves two or more development tools, which makes is possible for you to take advantage of the unique capabilities of each product.


Optimizing Client/Server Performance

Visual FoxPro 9.0
Optimizing Client/Server Performance

When you have implemented your client/server application, you might find areas where you'd like to improve performance. For example, you can fine-tune your application to gain maximum performance by speeding up forms and queries and increasing data throughput.

This section discusses optimization strategies for application performance on the client, network, and server.

In This Section

Client/Server Design for High Performance

Building a fast, high-performance client/server application with Microsoft® Visual FoxPro® involves taking advantage of the tremendous speed of the Visual FoxPro engine.
Optimizing Connections

Establishing a connection uses time and memory on both the client and the server. When you optimize connections, you balance your need for high performance against the resource requirements of your application.
Speeding Up Data Retrieval

You can speed up data retrieval by managing the number of rows fetched during progressive fetching, controlling fetch size, and using delayed Memo fetching.
Query and View Acceleration

You can improve query and view performance by adding indexes, optimizing local and remote processing, and optimizing parameter expressions.
Form Acceleration

When you design a form based primarily on server data, take a minimalist approach for the best performance.
Performance Improvement on Updates and Deletes

You can speed up Update and Delete statements by, adding timestamps to your remote tables, using the CompareMemo property, using manual transaction mode, using stored procedures on a remote server, and batching updates.

Related Sections

Creating Applications

Discusses how to create Visual FoxPro application, which may include one or more databases, a main program that sets up the application's system environment, and a user interface comprised of forms, toolbars, and menus.
How to: Set the Starting Point

Describes how the main file is the starting point for your application, and can consist of a program or form. When your application is run, Visual FoxPro launches the main file for your application, which in turn runs all other components as needed.
How to: Initialize the Environment

Setting up the application environment is the first task that a main file or application object must accomplish.
How to: Control the Event Loop

Learn how to establish an event loop to, which causes Visual FoxPro to begin processing user events such as mouse clicks and keystrokes. This occurs after the environment is set up and you've displayed the initial user interface.
Creating Applications with the Application Framework

Explains how to create applications with the Application Framework using the Application Wizard and the Application builder.
Creating the User Interface

Learn how creating forms, classes, controls, and toolbars can provide a rich set of tools for your user interface.
Upsizing Visual FoxPro Databases

Explains how to use the upsizing wizards to move databases, tables, and views from your system to a remote Microsoft SQL Server.
Creating International Applications

Describes how you can design and develop your Visual FoxPro applications so they are as effective internationally as domestically.


Client/Server Design for High Performance

Visual FoxPro 9.0
Client/Server Design for High Performance
See Also

Building a fast, high-performance client/server application with Visual FoxPro involves taking advantage of the tremendous speed of the Visual FoxPro engine. You accomplish this with new techniques such as using set-based data access rather than traditional local navigation, building parameterized queries to download just the data you need, locating tables on the optimal platform, and leveraging both Visual FoxPro and remote stored procedures.

When you design a local or file-server application, you determine the queries, forms, menus, and reports your application will use or create. When you design a client/server application, you perform all the normal system analysis plus additional analysis that relates specifically to client/server applications. You need to think about where the data used by queries, forms, menus and reports will be located, and how you'll access that information. For example, you might ask yourself questions such as:

  • Which tables will be stored on the remote server once the application is implemented?

  • Which tables would be more efficiently stored as local lookup tables?

  • What views will you need to access remote data?

  • What business rules does the server enforce, and how will your application interact with these rules?

Once you've determined the basic components of your client/server application, you can begin to design how your application will access and update data.

See Also

Other Resources

Performance Enhancement through Set-Based Data Access
Planning Client/Server Applications
Data Location on the Optimal Platform
Selecting the Right Methods
Optimizing Client/Server Performance
Enhancing Applications Using SQL Pass-Through Technology


Optimizing Connections

Visual FoxPro 9.0
Optimizing Connections
See Also

Establishing a connection uses time and memory on both the client and the server. When you optimize connections, you balance your need for high performance against the resource requirements of your application.

The number of connections used by Visual FoxPro depends on whether you force the closing of unused connections, and how you set the length of the connection idle timeout.

Using Shared Connections

You can use connections exclusively or share a connection. Each method has its benefits. When you use a connection exclusively, your application experiences no contentions for connection resources once a connection is established. If each result set uses an exclusive connection, you can also intermingle asynchronous processing on multiple result sets.

When you use a shared connection, you have one connection for multiple result sets. You must serialize data manipulation operations on the result sets sharing the same connection, and design the application to test the connection for busyness any time conflicts might occur. For information on sharing a connection, see How to: Share Connections for Multiple Remote Views.

Controlling Connection Timeouts

If your application doesn't take any action for a long time, you can reduce connection use by setting the IdleTimeout property on the connection. The IdleTimeout property controls the interval of time connections are allowed to idle before they're closed by Visual FoxPro. By default, connections wait indefinitely and are not deactivated until specifically closed by the user.

You set the idle time for a connection definition with the IdleTimeout property of the DBSETPROP( ) function; you can set the IdleTimeout property for an active connection with the SQLSETPROP( ) function.

Visual FoxPro closes connections even if Browse windows and forms displaying remote data are still open, and then automatically reconnects when the connection is needed again. However, Visual FoxPro cannot close a connection if:

  • Results of a query from the server are pending.

  • The connection is in manual transaction mode. You must commit or roll back the transaction and switch to automatic transaction mode before the connection can be closed.

You set the transaction mode for a connection definition with the Transactions property of the DBSETPROP( ) function; you can set the transaction mode for an active connection with the SQLSETPROP( ) function.

Releasing Connections

You can improve performance by closing connections that your application is no longer using. Connections are closed automatically for you when you close a view. If the connection is shared by multiple views, Visual FoxPro closes the connection when the last view using the connection is closed.

You can control the connection for a query manually if you don't want to update the data in a cursor. Use a SQL pass-through query to select the data you need into a local cursor and then close the connection.

See Also

Other Resources

Optimizing Client/Server Performance
Speeding Up Data Retrieval
Query and View Acceleration
Performance Improvement on Updates and Deletes
Form Acceleration
Enhancing Applications Using SQL Pass-Through Technology
Creating Views


Speeding Up Data Retrieval

Visual FoxPro 9.0
Speeding Up Data Retrieval
See Also

You can speed up data retrieval by managing the number of rows fetched during progressive fetching, controlling fetch size, and by using delayed Memo fetching.

You can also use the UseMemoSize view property to return character fields as memo fields and then turn FetchMemo off to enable your application to selectively fetch those character fields converted to memo fields.

Using Progressive Fetching

When you query a remote data source, Visual FoxPro retrieves complete rows of data and builds a Visual FoxPro cursor. To speed retrieval of remote data, Visual FoxPro employs progressive fetching of view cursors and cursors created asynchronously with SQL pass-through. Rather than requiring you or your application to wait while an entire data set is retrieved, Visual FoxPro executes a query and fetches only a small subset of the result set rows into the local cursor. The size of this subset is 100 rows by default.

Note:
Synchronous SQL pass-through statements don't employ progressive fetching. The entire result set requested by a SQLEXEC( ) statement is retrieved before control is returned to your application.

As Visual FoxPro retrieves additional rows of data, the local cursor contains increasingly more of the queried data. Since rows are retrieved at different times from the data source, the information in the rows isn't automatically current. If your connection is operating in asynchronous mode, Visual FoxPro returns control to you or your program as soon as it fetches the first subset of data. During idle time, Visual FoxPro performs a background fetch of the remaining rows in the queried data, one subset at a time, into the local cursor. This scenario allows you to use the already fetched data in the cursor without having to wait for the rest of the data.

Note:
Increasing the number of rows fetched improves performance, but decreases the responsiveness of the user interface. Decreasing the number of rows fetched has the inverse effect.

Fetching Data On Demand

You can disable progressive fetching and fetch rows only on an as-needed basis by using the FetchAsNeeded database and view cursor property. This can result in more efficient data retrieval for remote views or views retrieving extremely large results sets.

The FetchAsNeeded property is set by default to false (.F.), which means that progressive fetching is employed by default. When you set the FetchAsNeeded property to true (.T.), rows are fetched only when needed. When the FetchAsNeeded property is set to true, you cannot perform an update until you either complete the fetch, call the SQLCANCEL( ) function on the current connection handle, or close the view.

If you want to see the impact of using the FetchAsNeeded property, set the FetchAsNeeded property on a view retrieving a large result set to .T. and then open a browse window on the view and scroll down. The status bar is updated to show the number of rows retrieved as you move through the browse window.

Controlling Cursor Fetching

If you want to fetch the entire cursor, you can issue the GOTO BOTTOM command, or any command requiring access to the entire data set.

Tip:
While you can use the GOTO BOTTOM command to fetch the entire cursor, it's often more efficient to build a parameterized view that fetches only a single row at a time and requeries as the user changes records. For more information on building high-performance views, see How to: Optimize View Performance.

Programs don't provide idle loop processing. To fetch view cursors programmatically, use the GO nRecordNumber or GOTO BOTTOM commands. To fetch cursors created with SQL pass-through in asynchronous mode, call the SQL pass-through asynchronous function once for each row subset.

Canceling a SQLEXEC( ) Statement

You can use the SQLCANCEL( ) function to cancel a SQLEXEC( ) statement or a view at any time. However, if the server has completed building the remote result set and Visual FoxPro has begun fetching the remote result set into a local cursor, the SQLCANCEL( ) function cancels the SQLEXEC( ) statement and leaves the local cursor. If you want to delete the local cursor you can issue the USE command, which closes the cursor and cancels the fetch.

The USE command will not cancel a SQLEXEC( )statement if the statement hasn't yet created a local cursor. To determine whether Visual FoxPro has created a local cursor, you can call the USED( ) function.

Controlling Fetch Size

You control the number of rows fetched at one time by your application from a remote server by setting the FetchSize property on your view. The FetchSize property specifies how many records are fetched into the local cursor from the remote server at one time, through progressive fetching or asynchronous SQL pass-through calls. The default value is 100 rows.

To control the number of records fetched at one time into a view

  1. In the View Designer, choose Advanced Options from the Query menu. In the Data Fetching area of the Advanced Options dialog box, use the spinner to set a value for Number of Records to Fetch at a time.

    -or-

  2. Set the FetchSize property with the DBSETPROP( ) function to set the view definition's fetch size.

    -or-

  3. Set the FetchSize property with the CURSORSETPROP( ) function to set the active view cursor's fetch size.

    For example, the following code sets the view definition to progressively fetch 50 rows at a time into Customer_remote_view:

    Copy Code
    ? DBSETPROP('Customer_remote_view', 'View', 'FetchSize', 50)

Using Delayed Memo Fetching

A well-designed application frequently uses delayed Memo fetching to speed downloading of result sets that contain Memo or General fields. Delayed Memo fetching means that Memo and General field contents are not automatically downloaded when you download a result set. Instead, the rest of the fields in the row are quickly downloaded, and Memo and General field contents aren't fetched until you request them by opening the Memo or General field. Delayed Memo fetching provides the fastest downloading of rows, and allows Memo or General field contents, which can be quite large, to be fetched only if needed by the user.

For example, your form might include a General field that displays a picture. To speed performance, you can use delayed Memo fetching to prevent downloading of the picture until the user chooses a "Preview" button on your form. The code behind the "Preview" button then fetches the General field and displays it on the form.

To control delayed Memo fetching, you use the FetchMemo property on your view or cursor. The FetchMemo property specifies whether to fetch the contents of the Memo or General fields when the row is downloaded. The default value is true (.T.), which means that Memo and General fields are downloaded automatically. If your data contains large amounts of Memo or General field data, you might notice increased performance when you set the FetchMemo property to false (.F.).

Note:
The view must be updatable to allow delayed Memo fetching to work, because Visual FoxPro uses the key field values established by the update properties to locate the source row on the server when it retrieves the Memo or General field. For information on making a view updatable, see How to: Update Data in a View.

Use DBSETPROP( ) to set the FetchMemo property on a view, and CURSORSETPROP( ) to set the FetchMemo property on a cursor.

Optimizing Data Fetching Performance

You can use the following recommendations for setting connection and view properties to optimize data fetching. The PacketSize property on your connection has the greatest influence on performance. Also, you can optimize fetch performance using synchronous connections.

Object | Property | Setting
Connection | PacketSize | 4K to 12K1
Connection | Asynchronous2 | .F.
View | FetchSize3 | maximum

1. Set a higher value for rows containing more data; you should experiment to find the best value. 2. Use synchronous connections to increase performance up to 50%, unless you want to be able to cancel SQL statements while executing on the server. 3. The effect of FetchSize is highly dependent on the record size of the fetched result set. In synchronous mode, it does not significantly impact performance, so set it as needed for SQL pass-through asynchronous processing view progressive fetching. FetchSize, if reduced, provides significantly better responsiveness while progressively fetching a view, but slows down the fetch speed. If increased, it increases view fetch performance.

Actual performance depends greatly on your system configuration and application requirements.

See Also

Other Resources

Optimizing Connections
Query and View Acceleration
Optimizing Client/Server Performance
Form Acceleration
Performance Improvement on Updates and Deletes
Enhancing Applications Using SQL Pass-Through Technology


Query and View Acceleration

Visual FoxPro 9.0
Query and View Acceleration
See Also

You can improve query and view performance by adding indexes, optimizing local and remote processing, and optimizing parameter expressions.

Adding Indexes to Remote Tables

Remote indexes can make queries significantly faster. Multiple-table queries are faster if the tables are indexed on the joining fields. Having indexes on fields that are included in a query's WHERE clause can also improve performance.

Clustered indexes provide the best performance. On SQL Server, each table can have one clustered index. The SQL Server Upsizing Wizard automatically creates clustered indexes on tables that had a primary key in Visual FoxPro.

Tip:
While indexes on table fields used in queries can speed processing, indexes on result sets can slow performance. Use indexes on result sets with care.

Optimizing Local and Remote Processing

If you need to process a combination of local and remote data, create a remote view that combines all remote data in a single view. You can then join the remote view with the local data in a local view. Because Visual FoxPro fetches both views completely before joining and filtering the combined view, it's important to limit the size of the view result set.

You gain speed in remote processing by limiting the remote view result set to the minimum amount of data needed by your application. When you retrieve less data into a remote result set, you minimize the time required to download remote data into your local query or view cursor.

Optimizing Parameterized Views

You can speed data retrieval during REQUERY( ) operations on an open, parameterized view by compiling the view before it's executed. To precompile or "prepare" a view, set the Prepared property on the view to true (.T.).

Optimizing Parameter Expressions

View and SQL pass-through parameters are Visual FoxPro expressions and are evaluated in Visual FoxPro before being sent to the remote server. Evaluation time for the expression is important, because it lengthens the query execution time.

See Also

Other Resources

Speeding Up Data Retrieval
Form Acceleration
Optimizing Client/Server Performance
Performance Improvement on Updates and Deletes
Enhancing Applications Using SQL Pass-Through Technology


Form Acceleration

Visual FoxPro 9.0
Form Acceleration
See Also

When you design a form based primarily on server data, take a minimalist approach for the best performance. Determine the data and functionality needed, and delay asking the server for this data and functionality until requested by the user. Requesting data from the server uses processing time and creates network traffic. To request less data in your forms:

  • Request as few records as possible. For example, use a filter or query to limit the size of the record set. Make sure that the server can process any restrictions you use.

  • Use as few remote fields as possible in views underlying your forms.

  • Use as few forms that access remote views as possible in your form set. When you open a form set, all the forms in the form set are opened and populated with data as applicable. By limiting the number of forms in your form set, especially those that must connect to a server and retrieve remote data, you shorten the time the form set takes to load.

  • Use fewer bound controls that access remote data. Each combo box, list box, and grid that's bound to a remote table or query requires a separate query to the server when the form is opened. Avoid controls containing totals, or list boxes and combo boxes that have large row sources.

  • If users need to compare multiple sets of data, consider storing the data returned by the server in temporary local tables. Provide a form in which the user can use the previously stored data, or execute a new query.

Storing Lookup Tables Locally

Often, an application contains several forms that use the same remote table. If the data in the table doesn't change frequently, you can speed up form loading and reduce server load using one of the following techniques:

  • Store tables that never change and aren't too large (such as the names and abbreviations of the regions or states in your country) in the local Visual FoxPro application database. If the table is joined in queries or views with remote tables, you should also keep a copy of it on the server to avoid joining local and remote data.

  • Store tables that rarely change (such as a list of company buildings) both on the server and in the local application database. Provide a way for the user to download the table when the data does change.

  • Store tables that change occasionally but not daily (such as a list of employees in a small company or department) both on the server and in the local application database. Your application should automatically refresh the local version each time it starts. This method uses extra time when the application starts, but speeds up queries when the application is running.

Displaying Fields Only On Request

Display fields that take a long time to retrieve data from the server, such as Memo or General fields, only when requested. You can use the following techniques:

  • If your form is based on a view, place Memo or General fields off screen on another form page. Add a label to the form, such as "Page down to see notes and pictures," that informs the user how to display the information. Set the FetchMemo property on the view or cursor to false (.F.), so that Visual FoxPro doesn't retrieve Memo or General fields until they're displayed on screen.

  • Set the Visible property to false (.F.) for controls bound to Memo or General fields. Add a toggle button or command button that sets the property to true (.T.), so that the user can choose to view the contents of these controls.

  • Display the most important fields on a main form, and provide a button labeled "More Information" that opens another form containing other fields. Base the second form on a view that's parameterized by the primary key field on the main form. For example, suppose you have a main form based on a view whose SQL SELECT statement includes the following code:

    Copy Code
    SELECT customer_id, company_name, address, city, region, country
FROM customers
    In the preceding form, cust_id is bound to thisform.txtCust_id. You could base the second form on the following view, which is used only when the user chooses the "More Information" button:

    Copy Code
    SELECT orders.order_id, orders.order_date, orders.shipper_id, ;
   employee.emp_id, employee.last_name, employee.first_name ;
FROM orders, employee ;
WHERE orders.cust_id = ?THISFORM.txtCust_id ;
AND orders.employee_id = employees.emp_id

See Also

Other Resources

Query and View Acceleration
Performance Improvement on Updates and Deletes
Optimizing Client/Server Performance
Enhancing Applications Using SQL Pass-Through Technology


Performance Improvement on Updates and Deletes

Visual FoxPro 9.0
Performance Improvement on Updates and Deletes
See Also

You can speed up Update and Delete statements by:

  • Adding timestamps to your remote tables.

  • Using the CompareMemo property.

  • Using manual transaction mode.

  • Using stored procedures on a remote server.

  • Batching updates.

Adding Timestamps

You can improve performance when you update, insert, or delete data in a remote table that contains many fields by adding a timestamp field to the remote table, if your server provides the Timestamp field type.

The presence of a timestamp field in a remote table allows you to use the Visual FoxPro SQL WhereType update option DB_KEYANDTIMESTAMP. This option saves processing time because Visual FoxPro compares only two fields in your view, the key field and the timestamp field, against a remote table to detect update conflicts. By comparing only two fields, rather than all the updatable fields (with the DB_KEYANDUPDATABLE option) or all the modified fields (with the DB_KEYANDMODIFIED option), the DB_KEYANDTIMESTAMP option reduces the time it takes to update remote data. For more information on WhereType options, see Managing Updates by Using Views.

Note:
The DB_KEYANDTIMESTAMP option compares the key and timestamp fields only when your remote table contains a timestamp field. If you use the DB_KEYANDTIMESTAMP option against a remote table that doesn't contain a timestamp field, Visual FoxPro compares the key fields only.

The Upsizing Wizard can automatically add timestamp fields as appropriate to tables you export. For more information, see "Timestamp Columns" in Upsizing Visual FoxPro Databases.

Tip:
If you do something that alters the structure of a view's base table, such as adding a timestamp field, you might need to re-create the view. The fields in a view definition are stored in the database, and any changes to the base tables for a view after the view is used aren't reflected in the view definition until you re-create the view.

Excluding Memo Fields from the Update WHERE Clause

Whenever appropriate, you can speed updates by preventing view memo fields (fields of type Memo, General, or Picture) from being compared against their base table counterparts. By default, the CompareMemo property is set to true (.T.), which automatically includes memo fields in the SQL WHERE clause generated when you create an updatable view. You can set the CompareMemo property to false (.F.) to exclude memos from the SQL WHERE clause.

Using Transactions

For optimum performance, use manual transaction mode and manage transactions yourself. Manual transaction mode allows you to control when you commit a group of transactions, which enables the server to process more statements quickly.

Automatic transaction mode is more time-consuming, because by default every single update statement is wrapped in a separate transaction. This method provides maximum control over each individual update statement, but also increases overhead.

You can improve performance in automatic transaction mode by increasing the setting of the BatchUpdateCount property on the view or cursor. When you use a large BatchUpdateCount setting, many update statements are batched in a single update statement, which is then wrapped in a single transaction. However, if any statement in the batch fails, the entire batch is rolled back.

Tip:
The BatchUpdateCount property isn't supported by some servers; you should test this property against each remote server before deploying it in your application.

Using Server-Stored Procedures

You can create stored procedures on the server, which are precompiled and therefore run very quickly. You can execute stored procedures, send parameters with SQL pass-through, and move additional processing to the server as appropriate for your application.

For example, you might want to collect user input locally and then execute a SQL pass-through query to send the data to the server, calling the appropriate stored procedure. To do this, you might want to create a form on a local cursor or array to collect data and then write code that constructs a SQLEXEC( ) statement by using the name of the stored procedure and the parameters to be supplied. You could then add this code to the Click event of a command button titled "OK" or "Commit." When the user chooses the button, the SQLEXEC( ) statement runs. Using stored procedures on a remote server to update remote data can be more efficient, because the stored procedures are compiled on the server.

Batching Updates

If your application updates a number of records, you might want to batch updates so they're handled more efficiently by the network and server. Update or Insert statements are batched before being sent to the server, according to the setting of the BatchUpdateCount property of the view. The default value is 1, which means that each record is sent to the server with an update statement. You can reduce network traffic by increasing the value to package multiple updates in a statement.

Tip:
The BatchUpdateCount property isn't supported by some servers; you should test this property against each remote server before deploying it in your application.

To use this feature efficiently, the view connection should be set to Buffering mode 5, for optimistic table buffering, and changes ideally should be confined to the same fields in each row of the cursor. You can use DBSETPROP( ) to set the BatchUpdateCount property for the view definition; to change the value for an active view cursor, use CURSORSETPROP( ).

Optimizing Performance of Updates and Deletes

You can use the following guidelines for setting view and connection properties to optimize performance of updates and deletes. The BatchSize property on your view has the greatest influence on performance.

Object | Property | Setting | Notes
View | BatchUpdateCount | 10 – 30 rows | Set a higher value for smaller-sized updates.1 Set to increase performance by up to 50%. The default is 1.
Connection | Asynchronous | (.F.) | Use synchronous connections to increase performance up to 50%, unless you want to be able to cancel SQL statements while executing on the server. The default is synchronous.
Connection | WaitTime | N/A | To increase performance in asynchronous mode, use a shorter wait time; to reduce network traffic, increase the wait time.
Connection | PacketSize | 4K to 12K | Has little effect on performance.

1 Your best value also depends on the speed of your server.

Actual performance depends greatly on your system configuration and application requirements.

See Also

Other Resources

Form Acceleration
How to: Optimize View Performance
Query and View Acceleration
Optimizing Client/Server Performance
Optimizing Connections
Speeding Up Data Retrieval
Enhancing Applications Using SQL Pass-Through Technology


Performance Enhancement through Set-Based Data Access

Visual FoxPro 9.0
Performance Enhancement through Set-Based Data Access
See Also

One of the most important factors in building a fast, efficient client/server application is minimizing the amount of data you pull down from the server. Because client/server applications can access potentially huge amounts of data on a remote server, using traditional local navigation techniques could result in a slow client/server application. To speed performance, you use set-based data access techniques to filter the amount of data you download.

Accessing Set-Based Data Efficiently

Remote data is set-based; you access remote data by selecting a set of data from a large data store using SELECT - SQL statements. The most important difference between building a traditional local application and building a client/server application is the contrast between traditional Visual FoxPro navigational techniques and set-based server data access techniques.

Using Traditional Navigational Techniques

In traditional local database programming, you can access discrete and often large amounts of data by using the GOTO BOTTOM command, which you then query against. You can navigate through data by issuing a SET RELATION command to create a temporary relationship between two tables and then issuing a SKIP command to move through the related records.

While this method of navigating records could be used against remote data, it can be inefficient against large remote data stores. For example, if you create a remote view that accesses a large table on a remote data source and then issue the GOTO BOTTOM command, you must wait while all the data in the view is retrieved from the data source, sent across the network, and loaded into your local system's view cursor.

Using Parameterized Queries

A more efficient approach for accessing remote data is to download just the data you need and then requery to obtain specific additional or new records. Use a SELECT statement based on parameters to download a specific small set of data and then access new records by using the REQUERY( ) function to request a new set of data.

You don't issue the GOTO BOTTOM command against remote server data because this would:

  • Unnecessarily burden network resources by downloading huge amounts of data.

  • Slow performance of your application by handling unneeded data.

  • Potentially reduce accuracy of the data in the local cursor because changes to remote data aren't reflected in the local cursor until you requery.

For example, if you want to create a client/server application that accesses the orders for a particular customer, create a remote view that accesses the Customer table. Create another remote view that accesses the Orders table, but parameterize the view based on the cust_id field. Then use the current customer record as the parameter for the view of the Orders table.

You can use the parameter to scope the downloaded data set to just the right amount of data. If you request too little data, you can lose performance because you'll have to requery the remote server more frequently. If you request too much data, you can waste time downloading data you won't use.

Choosing the Best Client/Server Design

The following examples describe how to gain the benefits of client/server technology and avoid the pitfalls of poor programming techniques. The first method uses traditional programming practices to retrieve all the data from a remote data source into local cursors that are then related with the SET RELATION command. The second, third, and fourth methods adopt progressively smarter data-fetching techniques, effectively limiting the amount of data downloaded with a just-in-time methodology that provides the freshest data and fastest response time over a network.

Using an Unoptimized Client/Server Strategy

A straightforward, unoptimized client/server application uses local data navigation techniques with remote data. For example, if you have 10-million customer records and 100-million order records on a remote data source, you can create an inefficient application that downloads all the Customer and Order records into local cursors. You could then index on 100-million order records, create a temporary relationship between the Customer and Orders tables in your local cursors, and use the SKIP command to navigate through the records.

This method is not optimized for performance, but might, however, be useful if the one side is local and the many side is remote.

Filtering the Many Side

A slightly improved client/server application limits the many side of the relationship, but retrieves all of the one side so you can skip through the records. In this scenario, you create a remote view of the many side of the relationship, the Orders table, parameterized on the customer ID. You then download the entire Customer table.

While creating a parameterized view on the Orders table is an improvement over downloading all of the orders, you still retrieve unnecessary information by continuing to download the entire Customer table. The Customer table is also increasingly out-of-date as changes are made by other users on your system. This method might be beneficial if the one side of the relationship contains a small data set.

Filtering the One Side

A better client/server programming technique creates remote views for all remote data. You limit the number of Customer records downloaded into the remote view of the Customer table by using the SELECT statement in the view to select just the customers for one region. You then create a remote view of the many side of the relationship, the Orders table, parameterized on the customer ID.

This scenario retrieves a smaller set of records. You use the SKIP command to skip on the one side of the relation (the Customer view). You use the REQUERY( ) function to access new data on the many (Orders) side.

In this example, you limit, or filter, both the one side and the many side of the relationship, and can still use the SKIP command to navigate through the filtered data. This method is recommended if the one side of the relationship, even after being filtered, is still sufficient to provide information for a successive set of queries before you requery the remote server.

Using the Primary Key to Access the One-to-Many Relationship

The most efficient client/server programming paradigm gives up the luxury of using the SKIP command, and creates a form that requests input or selection of the customer ID, which is then used as a parameter for a remote view of the Customer table. This parameter is also used as a parameter for a remote view of the Orders table.

For example, you could create a one-to-many form in which the customer information forms the one side, and a Grid control displays the many side of the relationship. The Grid control can be bound to the customer ID chosen in the one side of the form. You can then set the MaxRecords property of CURSORSETPROP( ) to 1, and use the following code to populate the one side of the form:

Copy Code
SELECT * FROM customer WHERE customer.cust_id = ?cCust_id

When users want to view a different customer's record, they input or select a new customer ID. The form requeries the data source for the orders for the new customer ID and refreshes the Grid control with the new order data.

Using these techniques, your application downloads just the data you need, at the time it's needed. You speed response over the network by limiting the amount of data downloaded, and you provide fresher information to the user by requerying the data source just before you display requested information.

This method is recommended when you want to access the one-to-many relationship randomly using any primary key value. You might want to download the primary keys into a control, such as a drop-down list, when you open the form and then provide a control that the user can choose to refresh the list of primary key values on demand.

Using the Data Environment in Client/Server Applications

When you use remote data in a form, include the views in the form's data environment. You can set the AutoOpenTables property for the data environment to false (.F.) so that you can specify when the application refreshes the views with the remote data. Set the ControlSource property for text boxes or other data-bound controls after you call the data environment's OpenTables method, typically in the code associated with the Init event of the form. For more information, see Creating Forms.

See Also

Other Resources

Client/Server Design for High Performance
Data Location on the Optimal Platform
Planning Client/Server Applications
Selecting the Right Methods
Optimizing Client/Server Performance
Enhancing Applications Using SQL Pass-Through Technology


Data Location on the Optimal Platform

Visual FoxPro 9.0
Data Location on the Optimal Platform
See Also

You get maximum performance when you store data and other attributes of your database on the optimal platform. The best platform for a particular element depends on how the element is accessed and updated. For example, you might want to store a local copy of a server table, such as a postal code directory that is used as a lookup table, and refresh the local copy only when the back-end table changes.

The following table lists some common application elements and examples of where to locate them for optimal performance.

Locating Elements by Platform

Element | Location | Type | Notes
Tables | Local | Local copies of server lookup tables; small, infrequently changed tables | Use a time stamp, if supported by your remote server, to compare and optionally refresh the local table to match any changes to the back-end source table.
 | Remote | Large or frequently changing tables |
Rules | Local | Rules on remote views | You can use DBSETPROP( ) to store field- and record-level rules on a remote view. Your application can use these local rules to check the validity of data before sending the data to the back-end as an update to remote tables.
 | Remote | Row-level and column-level rules on remote base tables |
Stored procedures | Local | Visual FoxPro stored procedures |
 | Remote | Stored procedures on a remote server | Use the SQL pass-through SQLEXEC( ) function to call stored procedures on a remote server.
Transactions | Local | Visual FoxPro transactions |
 | Remote | Server transactions |
Triggers | Local views | No triggers on views |
 | Remote | Server triggers |

To reduce network traffic during lookups, you can choose to store not only infrequently changing but also frequently changing lookup tables locally. For example, you can download your company's customer list and refresh it only when customer information changes.

To accomplish this, you can program your application to compare the time stamp on the local copy of the table with the time stamp on back-end data (if your remote server supports time stamps) and update the local copy only if the server table has changed. You can also add a command button to your form that forces an immediate download of the table, allowing users to refresh their copy of the local table on demand.

See Also

Other Resources

Performance Enhancement through Set-Based Data Access
Selecting the Right Methods
Planning Client/Server Applications
Rapid Application Development
Client/Server Design for High Performance
Optimizing Client/Server Performance
Enhancing Applications Using SQL Pass-Through Technology


Rapid Application Development

Visual FoxPro 9.0
Rapid Application Development
See Also

Regardless of the programming method you choose, you need a good strategy to make developing client/server applications quick and efficient. Because Visual FoxPro makes it easy to quickly prototype and build applications, you can choose to design and build a local prototype of your application and then upsize and implement it in stages against a remote data source. If you have access to a remote data source during the development process, you might choose to prototype your application against the remote data source, using remote views.

Building a Prototype with Views

The first step in developing a Visual FoxPro client/server application can be to build a prototype. By prototyping your application, perhaps module by module, you discover changes and enhancements to your application's design early in the development process. You can then fine-tune your design efficiently against small sample data stores before adding the additional layer of complexity inherent in working with large sets of remote, heterogeneous data. For more information, see Upsizing Visual FoxPro Databases.

Creating a Local Prototype with Local Views

A local prototype for a client/server application is a functioning Visual FoxPro application that uses local views to access local tables. You use views in your client/server prototype because the final client/server application will use remote views to access remote data. By prototyping your application with local views, you're one step closer to the final application.

Building a local prototype is especially practical if you don't have constant access to a remote data source during development, or if you don't want to use remote data to prototype your application. Local views access local Visual FoxPro tables, rather than remote data source tables. You create the local data, however, to mimic the structure of the data on the server. Using local data to represent remote data is one method of quickly developing and testing your application's basic design. You can also speed development by limiting the amount of data selected into the views. For more information, see Working with Views.

Planning for Upsizing

Upsizing is the process that creates a database on the remote server with the same table structure, data, and potentially many other attributes of the original Visual FoxPro database. With upsizing, you take an existing Visual FoxPro application and migrate it to a client/server application. For more information, see Upsizing Visual FoxPro Databases.

When you build an application that you'll eventually upsize, you make choices about the design of your application's architecture and the programming model based on eliciting maximum performance against a remote data source. For more information, see Client/Server Design for High Performance.

Prototyping with Remote Views

If you have access to a remote data source and you want to use remote data directly as you develop your client/server application, you can build your prototype using remote views. When you prototype using remote views, you skip the upsizing step because your data is already located on a remote server and you already have remote views to access that data.

Implementing your Client/Server Application

You can simplify testing and debugging your application by implementing your prototyped application in stages. When you implement a prototyped application in stages, you add multiuser enhancements, move the data to the remote data source, and test and debug the application, module by module, in a systematic manner.

As you implement your application, you can use native server syntax and access server-specific functionality, such as stored procedures on a remote server, with SQL pass-through technology. For more information, see Enhancing Applications Using SQL Pass-Through Technology.

Optimizing your Application

Once your application is fully implemented against remote data and you've completed the testing and debugging phase, you can fine-tune the speed and performance of the entire application. For more information, see Optimizing Client/Server Performance.

See Also

Other Resources

Application Architecture
Selecting the Right Methods
Application Creation with Accuracy and Data Integrity
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Data Location on the Optimal Platform


Application Creation with Accuracy and Data Integrity

Visual FoxPro 9.0
Application Creation with Accuracy and Data Integrity
See Also

You can combine the power of Visual FoxPro data validation rules and stored procedures with the data source's data validation rules and stored procedures to build client/server applications that protect data integrity.

Maintaining Data Integrity

You can create local versions of remote server validation rules to provide friendly messages to the user; for example, provide messages about updates that would not be allowed when sent to the remote server because the data entered had violated some server relational integrity or data validation rule.

Using Visual FoxPro Rules on a Remote or Offline View

You can create field- and record-level rules on remote and offline views to validate data entered locally before the data is sent to the remote data source. Because the purpose of these view rules is to prevent sending data to the data source that will be rejected by the server's data integrity rules, you want to replicate the data source's rules in the rules you create for your remote view. You use the DBSETPROP( ) function to create rules for views.

Tip:
You can create a local validation rule on a remote view that calls a stored procedure on a remote server and sends the value you want to validate to the server as a parameter. However, using a stored procedure on a remote adds to processing time during data entry.

Using Server Rules

You can choose to rely on the rules established on the server for data validation. If an error occurs, your error handling routine can call the AERROR( ) function to obtain information, including the error message number, the text of the remote error message, and the connection handle associated with the error.

Using Server Triggers

Though you can create Visual FoxPro triggers on local tables, you can't create them on views. You can, however, use triggers on the remote data source. Server triggers can be used to process secondary data updates, such as cascading updates or deletes. Using server triggers to process secondary updates is more efficient than sending multiple commands to the remote server from your Visual FoxPro application.

Protecting Against Data Loss

Both Visual FoxPro and most remote data sources provide transaction-logging capabilities to protect against data loss. For more information, see Programming for Shared Access.

You can use Visual FoxPro transactions for local prototypes and for processing local data. Use server transactions for remote data updates, inserts, and deletes. For more information, see Optimizing Client/Server Performance.

See Also

Other Resources

Application Architecture
Rapid Application Development
Planning Client/Server Applications
Selecting the Right Methods
Data Location on the Optimal Platform
Enhancing Applications Using SQL Pass-Through Technology


Planning Enterprise Applications

Visual FoxPro 9.0
Planning Enterprise Applications
See Also

Many applications that you create with Visual FoxPro are self-contained solutions to a specific business requirement. For example, you might create a Visual FoxPro application to track your customers, which can include not only database information about the customers, but tools for taking orders, invoicing, and so on. You can create all the features your application needs using the facilities already available in Visual FoxPro, including its database engine, visual design tools, and reporting capabilities.

You can also use Visual FoxPro as part of a larger-scale application that involves two or more development tools. Using Visual FoxPro this way — referred to as "enterprise development" — allows you to take advantage of the unique capabilities of each product. Enterprise development can be as simple as maintaining a customer database in Visual FoxPro and creating a mail merge letter in Microsoft Word, or it can involve creating a complex application using client/server databases, Automation servers, electronic mail, and more.

Visual FoxPro is an ideal tool for creating enterprise-wide business solutions because it features:

  • Powerful, easy-to-use application development tools, including a Form Designer and wizards.

  • A fast database engine.

  • Excellent connectivity with other products, including both other Windows programs such as Microsoft Excel and Word, and client/server systems such as Microsoft SQL Server.

  • Integrated source control and other team development tools.

These features allow you to develop with Visual FoxPro in several roles in an enterprise-wide application. You can use Visual FoxPro:

  • As a front end for other applications. In this scenario, you work primarily with Visual FoxPro; for example, you create the user interface for the application in Visual FoxPro. You then access other applications that contain data needed for the application or that can provide services that enhance those already available in Visual FoxPro. You can also upsize your Visual FoxPro data or move it to another platform.

  • As a data source for other applications. To do so, you would create the user interface for the application using another program, and then access Visual FoxPro data as needed.

The strategy you choose depends on what your application goals are and what programs you want to use.

See Also

Other Resources

Application Architecture
Visual FoxPro as an Application Front End
Visual FoxPro as an Application Back End
Object-Oriented Programming
Accessing the Visual FoxPro API
How to: Create Automation Servers


Security Planning

Visual FoxPro 9.0
Security Planning

Security is a major concern for both application architects and developers. Applications that store sensitive information need to be protected from malicious attacks and from competitors attempting to steal information or intellectual property. When designing a security model for your application, you must be aware of security requirements from a business perspective and the implications that a chosen security model can have on performance, scalability, and deployment.

For general information about security planning for software development, visit the Microsoft Web site about security at http://www.microsoft.com/security/.

In This Section

Security Considerations

Describes general security issues you should be aware of when designing a server application.
Security Risks for Visual FoxPro Developers

Describes specific security issues in Visual FoxPro and how you can avoid them.

Related Sections

Application Planning

Discusses the benefits of careful application planning and provides links to information on application design, team projects, and international considerations.
Programming in Visual FoxPro

Provides links to information on object-oriented programming techniques and the event-driven model to maximize your programming productivity.


Security Considerations (Visual FoxPro)

Visual FoxPro 9.0
Security Considerations (Visual FoxPro)
See Also

When designing a server application, your design specification should address security issues. You should consider and can address the following items in the application's functional specification:

  • Security goals Define what you need to protect.

  • Security risks Understand the vulnerabilities of your application. You must also understand the significance of potential threats as they relate to your business.

  • Authentication Describes the process of accepting credentials from a user and validating those credentials against a designated authority. The identity of the user, or possibly an application or computer, is referred to as a security principal. The client must provide credentials to allow the server to verify the identity of the principal. After the identity is known, the application can authorize the principal to access resources on the system.

  • Authorization Describes the process of determining whether the proven identity is allowed to access a specific resource.

  • Securing data transmission Ensure that data cannot be viewed or tampered with while in transit by using encrypting when it crosses the network. You must consider the level of security that you data needs while in transit.

  • Impersonation Enables a server process to run using the security credentials of the client. When the server is impersonates the client, any operations performed by the server use the client's credentials. Impersonation does not allow the server to access remote resources on behalf of the client and requires delegation.

  • Delegation Enables a server process to run using the security credentials of the client, similar to impersonation. However, delegation is more powerful and enables the server process to make calls to other computers while acting as the client.

  • Operating system security Refers to the establishment of appropriate Access Control Lists (ACLs) and network security to prevent intruders from accessing secured resources. You must set the appropriate ACLs on the appropriate resources to allow access by only the relevant principals.

  • Securing physical access Refers to storing the server computer in a secure room. You should not overlook this fundamental issue.

  • Code access security Enables code to be trusted to varying degrees depending on where it originates and other aspects of the code's identity. You should be aware of how to create your own access permissions.

See Also

Other Resources

Security Planning
Security Risks for Visual FoxPro Developers


Security Risks for Visual FoxPro Developers

Visual FoxPro 9.0
Security Risks for Visual FoxPro Developers
See Also

It is important to understand security issues when developing and deploying applications. For general information about developing secure applications, see the Microsoft Web site at http://msdn.microsoft.com/security.

Developers need to be aware of the following specific security issues and best practices when developing Visual FoxPro applications:

  • Validate parameter input values before evaluating them.

    When passing user input values for parameters to commands such as SQL statements, you should include code to check that those values do not contain harmful expressions, such as those that can cause access violations.

    Avoid using simple text boxes for parameter input when possible and choose user interface elements you can more easily control, such as a list boxes, grids as list boxes, or OptionGroup controls. If you must rely on typed user input as parameter input, for example, to execute commands, you should always parse the input for parentheses (()) characters. This ensures that users do not enter input that might be interpreted by Visual FoxPro as an expression. You should also check input for the ampersand (&), which is used as a macro substitution character.

    Caution:
    Use extreme caution when accepting typed user input as parameters and passing it to the following language elements: RUN or ! command, EVALUATE( ) function, EXECSCRIPT( ) function, _VFP.DoCmd method, _VFP.Eval method, and the ampersand (&) character. This practice is recommended only for advanced developers who use strong parameter validation routines for parsing values that might cause harm to the application, the user's computer, or network.

  • Provide less flexibility to users when providing values for SQL SELECT statements.

    When using COM server or SQL Server methods that accept user input values from a SQL SELECT statement, write code that avoids giving the user access to information that should be secured, such as the computer name, or to perform undesirable actions, such as allowing the user to copy over tables and databases.

  • Set database container (DBC) file system attributes to read-only access.

    If a DBC is set to read/write access, users can modify code for DBC Events, such as the DBC_BeforeOpenTables event, to include damaging code, for example, to format a user's hard drive when opening a table in the DBC.

    If the DBC needs to be modified as part of maintenance, a network administrator can temporarily set the DBC with read/write access and then reset it to read-only access when maintenance is finished.

  • Prevent users from viewing source code in your application by encrypting your application and remove debugging information.

    To protect source code and remove debugging information, open your application project in the Project Manager. To encrypt your application project and not include debugging information, select the Encrypted check box and clear the Debug info check box in the Project Information dialog box. You should then select the Recompile All Files check box in the Build Options dialog box and rebuild your project by clicking Build in the Project Manager window. In the setup section of your application, include the SET DEBUG command.

    The _cryptapi class located in the ...\Ffc\_Crypt.vcx foundation class library provides access to the Windows Crypto API routines so you can encrypt strings, data, or files in your Visual FoxPro Applications.

    For more information, see Project Information Dialog Box, Project Manager Window, Build Options Dialog Box, and SET DEBUG Command.

  • It is recommended that you develop applications that use least privilege user settings. It is not necessary for the user to log in as a power user or administrator.

  • Avoid writing to the registry keys, HKEY_LOCAL_MACHINE and HKEY_CLASSES_ROOT. Instead, write only to the HKEY_CURRENT_USER hive.

  • Do not create or update files in the C:\Program Files (%PROGRAMFILES%) or C:\Windows (%SYSDIR%) directories. Instead, you should write user data to the user application folder. You can use the _commonfolder class located in the ...\Ffc\_System.vcx foundation class library to obtain the location of the user application folder.

  • When creating COM Servers in Visual FoxPro, it is recommended that you create COM+ applications to deploy them so you can enforce COM+ role-based security.

See Also

Other Resources

Security Planning
Security Considerations
Developing Visual FoxPro Applications


Planning for Team Development Projects

Visual FoxPro 9.0
Planning for Team Development Projects

You can create complex applications quickly by combining the skills of a team of developers. However, team development requires some extra coordination to keep the development effort working smoothly. One strategy is to use source control software, such as Microsoft Visual SourceSafe, to manage the files in a project.

The following topics provide strategies that you can follow to make team development successful. They assume that you're already familiar with creating a Visual FoxPro application, as discussed in other sections.

In This Section

Team Development Concepts

Describes how you can create applications faster and develop more complex applications by working with a team of developers.
Source Control Features

Explains that Visual FoxPro provides a number of features that support team development, a significant feature of which is the use of a source code control system to coordinate access to files in a project.
Managing Visual FoxPro Projects Under Source Control

Explains the process for using source control software in Visual FoxPro, including that you put projects under source control, add files to your source-controlled projects, and update the project list for each project.
Managing Files in a Source-Controlled Project

Says that after you have put a Visual FoxPro project under source control, you can work with individual files or manage the project as a whole.
Developing and Modifying Databases in Teams

Suggests that in addition to working together with projects and project files, your team must be able to share information in databases.
Developing Class Libraries in Teams

Describes how, because class libraries (.vcx files) are a crucial part of most Visual FoxPro applications, teams must be able to coordinate development efforts when creating them.

Related Sections

Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Application Planning

Explains how careful planning saves time, effort, and money and many of the decisions you make during the planning phase will impact how you create elements of the application.
Design Considerations

Discusses how the design decisions you make will impact how you create your application.
Application Architecture

Describes how Visual FoxPro application architecture varies with the type of application you decide to create.
Security Considerations

Explains how you need to be aware of security requirements from a business perspective and the implications that a chosen security model can have on performance, scalability, and deployment.
Security Considerations

Shows how you should be aware of security requirements from a business perspective and the implications that a chosen security model can have on performance, scalability, and deployment.
Developing International Applications

Shows how to design Visual FoxPro applications so they are as effective internationally as domestically using the international features of Visual FoxPro.


Team Development Concepts (Visual FoxPro)

Visual FoxPro 9.0
Team Development Concepts (Visual FoxPro)
See Also

By working with a team of developers, you can create applications faster, and can develop more complex applications. You can blend the skills of different developers to create applications that would be difficult or impossible for a single developer to create.

However, team development requires extra effort in the development process. Successful team development depends on:

  • Allowing several developers to work with the same projects and databases at the same time.

  • Coordinating the changes that are made to the same programs, forms, or other application elements, so that one developer's changes don't overwrite those of another developer.

  • Allowing developers to enhance existing application elements (for example, programs or class libraries) without affecting the work of other developers who are currently using these elements.

For example, imagine that your team is developing a complex application. Because the application is large, Visual FoxPro must allow several developers to be working at once on different components of the application. However, you want to be sure that only one developer at a time works on an individual element, such as a form, so that one developer doesn't overwrite the changes made by another developer.

Furthermore, you want that developer to be able to code, test, and debug a form without affecting the other developers (and users) who continue working with an earlier version of the form. When the first developer is finished with the new form, the enhancements can then be integrated into the application.

You can follow the methods recommended in this section for coordinating the work of multiple developers. For example, this section provides information on how you can work with projects and class libraries in a multi-developer environment.

See Also

Other Resources

Planning for Team Development Projects
Source Control Features
Managing Visual FoxPro Projects Under Source Control
Managing Files in a Source-Controlled Project
Developing and Modifying Databases in Teams


Source Control Features

Visual FoxPro 9.0
Source Control Features
See Also

Visual FoxPro provides a number of features that support team development. A significant feature of team development is the use of a source code control system to coordinate who can access and modify files in a project.

Source control is the generic term for tools that manage files in a multi-developer environment. Most source control tools work something like a traditional public library, maintaining a central repository of files — documents, programs, or any other files — in a location accessible to all developers. In addition, source control tools include the ability to track the changes that developers make to files and revert to earlier versions if necessary.

Generally speaking, source control tools provide some or all of these features:

  • Check out, check in Developers check out a file by downloading a copy from the central repository to their local computer before modifying it. As a rule, while a file is checked out, other developers cannot check it out or modify it, but they can usually view it by synchronizing, or getting a read-only copy of it. (If the file is a text file, such as program source code, it's possible for several developers to check out the same file, and then merge others' changes with their local copy.) When developers are done with a file, they can check in their changes by checking in, or uploading, their local copy to the central repository. As part of the file check-in process, most source control tools prompt the developer to enter any comments about changes made to the file.

  • Merging To allow several developers to work concurrently on the same file, source control software allows multiple developers to check out the file at the same time. (This can usually be done only with text files such as program source code.) If another developer has changed the file, the source control system can integrate those changes into your version of the file.

  • Project control Developers can organize files into projects or other work-specific categories. Files can often be shared between projects if necessary.

  • Change tracking Most source control systems keep track of the changes made in a file when it's checked in. This allows developers to reconstruct earlier versions of the file, which is useful for recovering earlier work.

  • Difference checking Source control software allows developers to compare versions of a file and review the differences between them.

  • History Developers can examine the check-in history for each file, including the comments made by each developer when checking in the file.

    Tip:
    If your source control software supports comments, take advantage of it. Comments can greatly aid in the process of tracking changes and provide a useful history of application development.

To use source code control, users must join a source-controlled project (sometimes referred to as "enlisting" in a project). When users have joined a project, they can check out and check in the files that belong to that project.

Note:
You must enable your source control system's option to check out the same file multiple times in order for several developers to work in a project concurrently. For details, refer to the documentation for your source code control software.

See Also

Other Resources

Team Development Concepts
Source Control Software in Visual FoxPro
How to: Enable Source Control
Managing Visual FoxPro Projects Under Source Control
Planning for Team Development Projects


Source Control Software in Visual FoxPro

Visual FoxPro 9.0
Source Control Software in Visual FoxPro
See Also

One of the most critical aspects of developing in teams is the ability to control who is allowed to change files. For example, if there are no controls on files, and if more than one developer is changing a program at the same time, there is a strong likelihood that one set of changes will end up being overwritten or discarded, wasting time and effort.

Visual FoxPro helps your team manage files in your projects by allowing you to integrate a source code control system into the Visual FoxPro Project Manager. By doing so, you can manage project files in a team development environment and ensure that development efforts proceed smoothly.

Integrating Source Control with Visual FoxPro Projects

Visual FoxPro supports source code control tools by allowing you to integrate commercially-available source control software directly into your projects. You can use many of the version control systems currently available. (Contact the software vendor to find out if the software can be integrated with Microsoft development tools.) For example, if your development team already uses Microsoft Visual SourceSafe, you can specify that as the source control software to use with Visual FoxPro.

Note:
If you add a project to Visual SourceSafe, for proper mapping to the project, all files contained in the project must be in the project directory or path.

All source control in Visual FoxPro is managed through the Project Manager. When you set up a project in Visual FoxPro, you have the option of creating a corresponding source code control project, which is referred to as "putting the project under source control." After you've put a project under source control, Visual FoxPro helps you manage the files in the source-controlled project. When you want to modify a file — for example, if you edit a program or modify a form — Visual FoxPro prompts you to check out that file.

In Visual FoxPro, source control is used to manage files of all types, not just .prg files, but .scx, .frx, .lbx, .mnx, and .vcx files, and others as well. Although individual files can be shared between different Visual FoxPro projects, all source control operations are conducted on files within the context of a particular project.

Note:
Visual FoxPro doesn't prompt you to put data tables such as .dbf and .dbc files under source control when you create them, but you can add them manually to your source-controlled project.

When you work in the Project Manager with a project that's under source control, Visual FoxPro displays icons next to files that are under source control to indicate their status.

The following table summarizes the icons used in the Project Manager to indicate source control status.

Icon | Meaning
FoxProRedCheck screenshot | The file is checked out to you.
FoxProDoubleChecks screenshot | The file is checked out to you and to one or more other developers.
FoxProUserSymbol screenshot | The file is checked out to another developer.
FoxProLockSymbol screenshot | The file is not checked out; you cannot change the file until you check it out.
FoxProMergeSymbol screenshot | The file has been merged. After examining the changes, you can check the file in.
FoxProNoMergeSymbol screenshot | The file has been merged and there are conflicts that need to be resolved.
FoxProQuestionMarkSymbol screenshot | Visual FoxPro cannot determine the source control status of the file.

If a file isn't under source control, no icon appears next to it.

See Also

Other Resources

Source Control Features
How to: Enable Source Control
Planning for Team Development Projects
Managing Visual FoxPro Projects Under Source Control
Team Development Concepts


How to: Enable Source Control

Visual FoxPro 9.0
How to: Enable Source Control
See Also

To enable source control, first install your source control program according to the documentation provided with it. Typically, you install an administrator version on a server where the source code will be maintained, and then install the client version of the product on local machines.

Note:
All developers on a project must use the same source code control software.

After installing the source control software, you can set options so that Visual FoxPro will recognize it, and to specify defaults for your projects.

To enable source control in Visual FoxPro

  1. From the Tools menu, choose Options.

  2. In the Options dialog box, choose the Projects tab.

  3. In the Source control options area, select the name of your source control program in the Active source control provider list.

  4. To have Visual FoxPro prompt you to add new projects to source control, select Automatically add new projects to source control.

Each time you start Visual FoxPro, it checks for a source control provider. If one is found, you can put or manage projects under source control.

See Also

Other Resources

Source Control Software in Visual FoxPro
Managing Visual FoxPro Projects Under Source Control
Planning for Team Development Projects
Source Control Features


Managing Visual FoxPro Projects Under Source Control

Visual FoxPro 9.0
Managing Visual FoxPro Projects Under Source Control

To use source control software in Visual FoxPro, you put projects under source control, add files to your source-controlled projects, and update the project list for each project.

In This Section

Working with the Project File and Project List File

Discusses how Visual FoxPro maintains a project file list to coordinate changes to a project under source control.
How to: Put Projects Under Source Control

Describes how to create a new project under source control or to put an existing project under source control.
How to: Add Files to a Source-Controlled Project

Explains how to add files to a project under source control.
How to: Join an Existing Source-Controlled Project

Describes how to join an existing project that is under source control.
How to: Update the Project List

Explains how to update the project list so that newly added files are available to other developers in the project list.
How to: Detach a Project from Source Control

Describes how to detach a project from source control.
How to: Remove Files from a Source-Controlled Project

Describes how to remove individual files from source control, so they will no longer be part of the project.
How to: Share Files Between Source-Controlled Projects

Explains how to set a file to be a member of two or more source controlled projects at the same time.

Related Sections

How to: Enable Source Control

Describes how to enable source control in Visual FoxPro.
Planning for Team Development Projects

Discusses how using source control software, such as Microsoft Visual SourceSafe, to manage the files in a project makes it possible to create complex applications quickly by combining the skills of a team of developers.


Working with the Project File and Project List File

Visual FoxPro 9.0
Working with the Project File and Project List File
See Also

In Visual FoxPro, project information is maintained in a set of table and memo files with the extensions .pjx and .pjt. For example, if you've created a project called "MyProj," the information about the project, including the list of files, their location, and whether they're compiled into the application file (.app or .exe file), is stored in the files called Myproj.pjx and Myproj.pjt.

When working in a team development environment, developers don't share the same project files (.pjx and .pjt files). Instead, developers maintain their own local copies of the .pjx and .pjt files.

To coordinate changes that individual developers make to a project under source control, Visual FoxPro maintains a project file list (or .pjm file, short for "project metafile"). The file containing the project file list is a text file that stores the same information as the .pjx and .pjt files, such as which files are currently included in the project.

The source code control software maintains a central project file list file stored with the other files in the central repository. In addition, each developer has a local copy of the project file list checked out that reflects his or her current version of the project.

Imagine you're working with a project, and that you're adding a new program (.prg file). When you add the new file (and assuming that you put this file under source control), Visual FoxPro updates your local copy of the project and shows the file when you use the Project Manager on your computer. Other developers aren't initially aware of your change, and their local copies of the project don't show the file you have added. Even though you haven't updated the project file list, you can still check in the new file for safekeeping and check it back out again as needed.

When you're finished with the new file — for example, when you've finished testing your new program — you can update the project file list. When you do, Visual FoxPro merges the information in your local project file list with that in the central project file list.

Visual FoxPro in turn updates your local project file list with changes it finds in the central project file list. If other developers have added files to the project, your local project file list is updated, local copies of the new files are placed on your computer, Visual FoxPro rebuilds your project (.pjx and .pjt files), and the Project Manager displays the added files for you to work with.

Note:
The project file list tracks only the project files that are explicitly under source control. If your project includes files that aren't under source control, they will not appear in the project file list, and Visual FoxPro will not add these files to other developers' projects when they update their own project lists.

See Also

Other Resources

How to: Add Files to a Source-Controlled Project
Managing Visual FoxPro Projects Under Source Control
How to: Update the Project List
How to: Join an Existing Source-Controlled Project
Planning for Team Development Projects


How to: Put Projects Under Source Control

Visual FoxPro 9.0
How to: Put Projects Under Source Control
See Also

You must specify that a Visual FoxPro project will be source-controlled before you can take advantage of your source control software. You do this by adding a project to your source control system.

If source control software is enabled, you can specify that any new projects you create be automatically put under source control.

To create a new source-controlled project

  1. In the Options dialog box, choose the Projects tab, and then select a source code control provider if you haven't already done so.

  2. Make sure Automatically add new projects to source control is selected, and then choose OK. To make this setting the default, choose Set as Default, and then choose OK.

  3. From the File menu, choose New, and then start a new Visual FoxPro project.

    After you've named the new project, Visual FoxPro will prompt you to create the new source-controlled project. The default name for the new project will be the same as the name of the Visual FoxPro project.

After you create the new source-controlled project, Visual FoxPro finishes creating the Visual FoxPro project. Before other developers can use the file, they must enlist in the project.

If you're working with an existing project that isn't already under source control, you can create a new source-controlled project for it, and then put its files under source control.

To put an existing project under source control

  1. Open your Visual FoxPro project in the Project Manager Window.

  2. From the Project menu, choose Add Project to Source Control.

    Visual FoxPro displays the dialog box for your source control system that allows you to create a new project. By default, the name of the source-controlled project is the same as that of the Visual FoxPro project.

  3. Create the source-controlled project as you normally do with your source control software.

When you add an existing project to source control, Visual FoxPro prompts you to add the project's files to the source-controlled project.

See Also

Other Resources

How to: Add Files to a Source-Controlled Project
Managing Visual FoxPro Projects Under Source Control
How to: Update the Project List
How to: Join an Existing Source-Controlled Project
Planning for Team Development Projects


How to: Add Files to a Source-Controlled Project

Visual FoxPro 9.0
How to: Add Files to a Source-Controlled Project
See Also

After you put a Visual FoxPro project under source control, you can add individual files to the source-controlled project. If the Visual FoxPro project already contains files when you put it under source control, you can add them to the source-controlled project.

Note:
If the source control software supports it, Visual FoxPro allows you to keep the file checked out when you add it to the source-controlled project. If not, the file is checked in and you must check it out again in order to work with it. For details about checking files out and in after they're added to a project, see Managing Files in a Source-Controlled Project.

To add existing files to a controlled project

  1. From the Project menu, choose Source Control and then choose Add Files to Source Control.

  2. In the Add Files to Source Control Dialog Box, select the files you want to add.

    Note:
    Keep checked out and Comment appear only if your source code control software supports these options.

  3. Choose OK.

    Visual FoxPro generates the control files necessary for the source control software, and then adds the files to the project. If you've selected many files, this process can take some time.

You can set it up so that when you add a file to a project, Visual FoxPro will prompt you to put it under source control.

To specify that Visual FoxPro prompts you to put new files under source control

  • In the Projects tab of the Options dialog box, make sure Automatically add new projects to source control is selected, and then choose OK.

    To make this setting the default, choose Set as Default, and then choose OK.

After you've added files to a project, you must update the project list before other developers can work with the new files.

See Also

Other Resources

How to: Update the Project List
Planning for Team Development Projects
Managing Visual FoxPro Projects Under Source Control
How to: Detach a Project from Source Control
How to: Join an Existing Source-Controlled Project


How to: Join an Existing Source-Controlled Project

Visual FoxPro 9.0
How to: Join an Existing Source-Controlled Project
See Also

If you are a new developer on a project that's already under source control, you must join the project before you can check files out and in. When you join a project, Visual FoxPro creates a local project list file and generates a current project file (.pjx file) for you.

To join an existing project

  1. From the File menu, choose Join Source Control Project.

  2. In the Open Project dialog box, select the server and directory that contains the Visual FoxPro project file you want to join.

  3. Set the working directory on your local machine; this specifies where the source control system will place files when you check them out and where it will look when you check them back in. For example, if you're using Visual SourceSafe as your source control provider, choose Browse from the Directory area and select an existing directory, or type the name of a new directory.

    Tip:
    All developers on a project must use the same directory structure for the files in a project, although the names of individual subdirectories can differ.

See Also

Other Resources

Planning for Team Development Projects
Managing Visual FoxPro Projects Under Source Control
How to: Detach a Project from Source Control
How to: Update the Project List


How to: Update the Project List

Visual FoxPro 9.0
How to: Update the Project List
See Also

Even after files have been added to the source-controlled project, other developers will not be able to work with them. Developers will be able to manually use their source control system to check files out and in if they need to, but the added files will not be displayed in the Project Manager for any developer except the developer who added the files. To make the files available to other developers, update the project list.

When you update the project list, Visual FoxPro:

  • Generates a new local project file list (.pjm file).

  • Checks in the new project file list (with the option set to keep the file checked out).

  • Merges the local and central project file lists if there are differences. If a merge conflict occurs, Visual FoxPro displays a dialog box to help you resolve the merge conflicts.

  • Rebuilds the local project (.pjx) file based on the merged project file list.

  • Gets local copies of files added to the project by other developers.

  • Prompts you to get the latest versions of the project files.

  • Refreshes the display in the Project Manager to reflect changes.

To update the project list

  • From the Project menu, choose Source Control, and then choose Update Project List.

As part of the update procedures, Visual FoxPro prompts you to get the latest versions of files. If you have a file already checked out, as a general rule you shouldn't get the latest version, because your version is almost certainly more current than the one on the network.

If you're getting the latest version of a text file (such as a program), the source control software can attempt to merge the latest changes with your version. For more information about merging text files, see How to: Check In Files.

When you're finished, other developers should also then update their project list (using the same procedure) in order to be able to work with the files you've added.

See Also

Other Resources

Planning for Team Development Projects
Managing Visual FoxPro Projects Under Source Control
How to: Detach a Project from Source Control
How to: Join an Existing Source-Controlled Project


How to: Detach a Project from Source Control

Visual FoxPro 9.0
How to: Detach a Project from Source Control
See Also

If you no longer want to control the files in a project, you can detach the project from source control. When you do so, files remain in the source control project so that other developers can continue to use them and so you can examine their history or use them with other projects.

If you have project files on your computer that are tagged as read-only — that is, you have copies of files, but they're not checked out — you can remove their read-only attribute when the project is detached from source control.

Note:
When you detach a project from source control, you break the link between your local project files and the source-controlled project, and your local files become read/write. Be sure to institute manual version control procedures after detaching the project, or you run the risks inherent in working with files that are not under source control.

To detach a project from source control

  1. Check in all the files under source control.

  2. From the Project menu, choose Detach Project from Source Control.

See Also

Other Resources

How to: Update the Project List
How to: Remove Files from a Source-Controlled Project
Planning for Team Development Projects
Managing Visual FoxPro Projects Under Source Control


How to: Remove Files from a Source-Controlled Project

Visual FoxPro 9.0
How to: Remove Files from a Source-Controlled Project
See Also

You can remove individual files from source control if you no longer want them to be part of your source-controlled project. You might do this, for example, if a program or form becomes obsolete and is no longer part of your project

To remove a file from source control

  1. In the Project Manager Window, select the file to remove.

  2. From the Project menu, choose Source Control, and then choose Remove Files from Source Control.

  3. In the Remove Files from Source Control Dialog Box, select the files to remove, and then click OK.

If you remove a file from a Visual FoxPro project that's under source control, Visual FoxPro prompts you whether you want only to remove the file from the project or to delete it from disk. A setting in the Options dialog box determines whether Visual FoxPro also prompts you to remove the file from the source-controlled project.

  • If Remove files from source control upon removal from project is checked, Visual FoxPro also prompts you to remove the file from the source-controlled project.

  • If Remove files from source control upon removal from project isn't checked, you're not prompted, and the file is left under source control.

After a file has been removed from source code control, copies of it might still exist on other developers' computers. If so, the file is treated as a local file only for those developers.

See Also

Other Resources

How to: Detach a Project from Source Control
How to: Share Files Between Source-Controlled Projects
Planning for Team Development Projects
Managing Visual FoxPro Projects Under Source Control


How to: Share Files Between Source-Controlled Projects

Visual FoxPro 9.0
How to: Share Files Between Source-Controlled Projects
See Also

You can set up a file so that it's a member of two or more source-controlled projects at the same time. This is useful if you use common files, such as standard programs, libraries, or dialog boxes, in more than one project. When you share files between projects, changes you check in to a file are reflected in all the projects that share the file.

The specific method for sharing files between source-controlled projects depends on your source control software. If file sharing options aren't supported by your source control provider, file sharing commands will not be available on the menu.

The first step of the following procedure applies to all source control systems that support file sharing. The subsequent steps might differ, depending on your source control software.

To share files between controlled projects

  1. From the Project menu, choose Source Control and then choose Share Files.

  2. In the dialog box that appears, indicate what files you want to share with your current project, and what project they currently belong to.

    The specific options available from this menu command depend on your source control system. For details, choose Help in the Share dialog box or refer to the documentation for your source control system.

    Tip:
    In Microsoft Visual SourceSafe, you can see what projects a file is a member of by using the Project Properties command and choosing the Links tab. If you add a project to Visual SourceSafe, for proper mapping to the project, all files contained in the project must be in the project directory or path.

See Also

Other Resources

How to: Remove Files from a Source-Controlled Project
Managing Files in a Source-Controlled Project
Planning for Team Development Projects
Managing Visual FoxPro Projects Under Source Control


Managing Files in a Source-Controlled Project

Visual FoxPro 9.0
Managing Files in a Source-Controlled Project

After you have put a Visual FoxPro project under source control, you can work with individual files or manage the project as a whole.

In This Section

Working with Multi-File Components

Covers how some project files consist of multiple components and how Visual FoxPro will manage the implicit file or files automatically.
How to: Check Out Files

Describes how to check out a file in a source-controlled project.
How to: Check In Files

Describes how to check in a file in a source-controlled project.
How to: Discard Changes

Describes how to undo a check out so that any changes to the file will be discarded.
How to: Get the Latest Versions of Files

Describes how to get the latest version of a file that is already checked out.
How to: Compare Files or Projects

Explains how to compare files or projects in a source controlled environment to determine whether another user has changed it, or to pinpoint where changes have been made since the last time it was checked out.
How to: Check for Differences in Forms, Reports, and Other Table Files

Describes how to compare files that represent form, report, and table files, to determine where changes have been made.
How to: Display File and Project Information

Discusses how to view the check out history or source control information of a file or project list.

Related Sections

Planning for Team Development Projects

Discusses how using source control software, such as Microsoft Visual SourceSafe, to manage the files in a project makes it possible to create complex applications quickly by combining the skills of a team of developers.


Working with Multi-File Components

Visual FoxPro 9.0
Working with Multi-File Components
See Also

Some project components in Visual FoxPro actually consist of multiple files: a primary file and one or more implicit files. For example, when you create a form, Visual FoxPro creates an .scx file (the primary file) and an .sct file (the implicit file). The following components have multiple files:

Component | Primary file type | Implicit file type(s)
Form | .scx | .sct
Report | .frx | .frt
Label | .lbx | .lbt
Class Library | .vcx | .vct
Menu | .mnx | .mnt
Table | .dbf | .fpt, .cdx, .idx
Database | .dbc | .dct, .dcx

When a developer checks out a component file, such as a form, Visual FoxPro also manages the corresponding implicit file or files. Likewise, when a file is checked back in, or a new file added, Visual FoxPro manages the implicit file or files automatically.

Note:
If you generate and compile a menu, you create local .mpr and .mpx files as well. These aren't initially under source control, but you can add them as files to your project, and then put them under source control as you would other files.

Checking In Text Files

When you check in a text file such as a .prg file, and if multiple versions of the file are checked out, the source control software doesn't simply overwrite the central version. Instead, it checks whether there have been changes to the file since you last checked it out. If so, it attempts to merge those changes with your file. To do so, it adds, deletes, and changes lines in your copy of the file.

When it's finished merging, the source control software might also give you the opportunity to check in your file. Don't check in your file right away. Instead, test your application using the new version of the file that incorporates both your changes and those of other developers. Only when you're satisfied that the application works correctly, check in your file. If other developers have made further changes to the same file, you might have to merge, test, and check in again.

In some instances, the source control software might report a merge conflict, which indicates that it cannot resolve changes between your changes and those of other developers. This can occur, for example, if you and another developer have been updating the same lines of the same program. If the source control software cannot merge successfully, it creates a version of the file that contains the original text plus your changes, marks the conflicts, and writes that file to your computer. (The exact means by which the conflicts are marked depends on the source control software you're using.) The file then appears in the Project Manager with a merge conflict icon:

To resolve the merge conflict, you must edit the file again, make your changes, and remove the merge conflict markers. When you're finished editing, Visual FoxPro prompts you to confirm that you've resolved all conflicts. The file is then marked with the merge icon:

Test your application to be sure that the changes are working properly. You can then attempt to check the file in again. If no more merge conflicts occur, your file becomes the current version.

See Also

Other Resources

Managing Files in a Source-Controlled Project
How to: Check In Files
Planning for Team Development Projects
Options Dialog Box


How to: Check Out Files

Visual FoxPro 9.0
How to: Check Out Files
See Also

When you're working in a source-controlled project, Visual FoxPro can prompt you to check files out when you modify them by opening the appropriate editor. For example, if you select a form and choose Modify to open the Form Designer, Visual FoxPro can first prompt you to check out the files for the form. (If you don't check out the files, the form is displayed in the Form Designer, but is read-only.)

However, you can also check out files manually, which is useful if you want exclusive access to the file, but don't want to open the editor for the file just at the moment. You might do this, for example, if you intend to work with a file offsite.

To specify Visual FoxPro to prompt you to check out files being modified

  • In the Projects tab of the Options dialog box, make sure the option Check out files upon modify is checked, then choose OK.

    To make this setting the default, choose Set as Default, and then choose OK.

To check out a file manually

  1. In the Project Manager, select the file to work with.

  2. From the Project menu, choose Source Control, and then choose Check Out.

  3. In the Check Out Files Dialog Box, select the file or files you want to work with, and then click OK.

See Also

Other Resources

Managing Files in a Source-Controlled Project
How to: Check In Files
Planning for Team Development Projects
Options Dialog Box


How to: Check In Files

Visual FoxPro 9.0
How to: Check In Files
See Also

You must always check in files manually. Visual FoxPro doesn't automatically check in a file; for example, it doesn't check in a form when you close the Form Designer. Instead, it leaves the file checked out so you can continue to edit it, take it offsite, or work with it in some other fashion.

The exact result of the check-in process depends on the file you're checking in and on your source control software. For forms, menus, labels, class libraries, and other types of files, the file is treated as a binary file, and the source control software makes your new version of the file into the current one for other developers to check out.

Tip:
Always remember to check in files when you're done editing them. If you keep them checked out for long periods, you might prevent other developers from working with them, and you'll prevent the latest version of the file from being backed up during the course of your network backup.

To check in a file

  1. In the Project Manager, select the file to work with.

  2. From the Project menu, choose Source Control, and then choose Check In.

  3. Enter a comment describing the changes you've made.

  4. In the Check In Files Dialog Box, select the file, and then click OK.

For more information about checking in files, see Working with Multi-File Components.

See Also

Other Resources

How to: Check Out Files
How to: Discard Changes
Planning for Team Development Projects
Managing Files in a Source-Controlled Project


How to: Discard Changes

Visual FoxPro 9.0
How to: Discard Changes
See Also

If you've checked out a file, but decide to discard any changes you've made, you can undo the checkout. This has the effect of checking the file back in (that is, other users can then check the file out), but doesn't update it with changes. For example, if you mistakenly checked out a file instead of simply getting the latest version, undo the checkout instead of checking the file back in. This prevents the source code control system from having to create another version of the file, thus saving time and space.

Tip:
If you want to view a file but don't need to check it out, you can get the latest version of it.

To undo a checkout

  1. In the Project Manager Window, select the file to work with.

  2. From the Project menu, choose Source Control, and then choose Undo Check Out.

  3. In the Undo Check Out of Files Dialog Box, make sure the file you want is selected, and then click OK.

See Also

Other Resources

How to: Check In Files
How to: Get the Latest Versions of Files
Planning for Team Development Projects
Managing Files in a Source-Controlled Project


How to: Get the Latest Versions of Files

Visual FoxPro 9.0
How to: Get the Latest Versions of Files
See Also

If you want to view the latest version of a file, you can check it out. However, if the file is already checked out, or if you only want to view the file (not modify it), you can get the latest version of a file. When you do, Visual FoxPro copies the most current checked-in version of a file to your computer, but leaves it as a read-only file. You can get the latest version of a file even if it's currently checked out.

If the file you're getting is a text file, the source control software will merge the most current one with your vesrsion instead of simply overwriting it.

Note:
To merge files when getting the latest version, you might need to enable this as an option in your source control software. For details, see the documentation for your source control software.

To get the latest version of a file

  1. In the Project Manager Window, select the file for which you want the latest version.

  2. From the Project menu, choose Source Control, and then choose Get Latest Version. If the file is currently checked out, you're prompted to replace or merge your checked-out version with the current version from the source control project.

    Note:
    If you already have the file checked out, Visual FoxPro prompts you to overwrite it. If you've made changes to the file since last checking it out, choose No when prompted to replace the file.

See Also

Other Resources

How to: Discard Changes
How to: Compare Files or Projects
Planning for Team Development Projects
Managing Files in a Source-Controlled Project


How to: Compare Files or Projects

Visual FoxPro 9.0
How to: Compare Files or Projects
See Also

When working with files and with a project, you might need to compare the current local copy in your working directory with the current master copy in the source-controlled project. This can help you determine whether another user has changed a file, or it can help you pinpoint where you've made changes since you checked out the file.

Most source control systems can only compare and display differences between files if they're in text format. When Visual FoxPro compares forms, reports, menus, labels, and class libraries, it uses the text representations of those files.

Note:
If your source control provider doesn't support file comparison options, they aren't available on the menu.

To see differences between projects

  • From the Project menu, choose Source Control, and then choose Show Project Differences.

    The resulting report is produced by your source control software, so the specific information provided can vary. In general, however, the source control system will display a window with two panes, and will highlight or otherwise mark the differences between the local and master copies of the file.

To see differences between files or the project list

  1. If you're viewing differences for a single file, in the Project Manager, select the file for which you want to see differences.

  2. For a single file, from the Project menu, choose Source Control, and then choose Show Differences. For the project list, from the Project menu, choose Source Control, and then choose Show Project List Differences.

    The resulting report is produced by your source control software, so the specific information provided can vary. In general, however, the source control system will display the two versions side-by-side, and will highlight or otherwise mark new, deleted, and changed lines.

See Also

Other Resources

How to: Get the Latest Versions of Files
How to: Check for Differences in Forms, Reports, and Other Table Files
Planning for Team Development Projects
Managing Files in a Source-Controlled Project


How to: Check for Differences in Forms, Reports, and Other Table Files

Visual FoxPro 9.0
How to: Check for Differences in Forms, Reports, and Other Table Files
See Also

In Visual FoxPro, only a few types of files are treated as text files by the source control software. These include program source code (.prg) files and the project file list (.pjm file). Forms, reports, and other types of files are actually stored as tables of information about their components. For example, a form's .scx file is a table of the controls in that form, plus information about the form itself. Table-type files are used to store information about forms (.scx files), reports (.frx files), menus (.mnx files), labels (.lbx files), and class libraries (.vcx files).

Because these files are stored as Visual FoxPro tables, source control systems cannot treat them as text files (the source control system treats them as "binary" files). As a result, tools for viewing differences between versions of these files cannot pinpoint the differences, nor can you see a history of changes.

In order to allow you to use source control to view differences in forms, reports, and similar files, Visual FoxPro creates text representations of them. Then, when you put one of these files under source control, Visual FoxPro creates a text version of the file, which it maintains automatically as you make changes.

To support the capability to generate text representations of table-type files, Visual FoxPro includes the utility program Scctext.prg, or you can use a different program that you obtain from another source or write yourself.

To specify a text conversion utility

  1. In the Options dialog box, choose the Projects file.

  2. In the Text generation box, enter the name of the conversion program.

  3. Choose Set as Default, and then choose OK

Visual FoxPro automatically calls the text conversion program whenever you add a form, report, menu, label, or visual class file to a source-controlled project. The utility generates a text file that has the same name as the primary file, but uses "A" as the last letter of the extension. For example, for a form called Myform.scx, the utility generates a text file called Myform.sca. When you check in the form (or other file) after changing it, the source control software automatically creates and checks in the text file.

If you specify a text conversion utility when you already have forms, reports, and similar files in your source-controlled project, you must temporarily remove them from the project, and then re-add them with text generation enabled.

To generate text representations for existing files in a project

  1. Back up all the files that will be affected: forms, reports, menus, labels, and class libraries.

  2. Verify that the files aren't already checked out.

  3. From the Project menu, choose Source Control, and then choose Remove Files from Source Control.

  4. Select the files to remove from the project, and then choose OK.

  5. Enable text generation, following the steps described earlier.

  6. From the Project menu, choose Source Control, and then choose Add Files to Source Control.

  7. Select the files to add, and then choose OK.

As it puts the each file under source control, Visual FoxPro also creates the corresponding text representation for the file.

See Also

Other Resources

How to: Compare Files or Projects
How to: Display File and Project Information
Planning for Team Development Projects
Managing Files in a Source-Controlled Project


How to: Display File and Project Information

Visual FoxPro 9.0
How to: Display File and Project Information
See Also

You can display information about individual files and about the project as a whole. For example, you can display the checkout history for an individual file or for the project list file. Information typically available includes:

  • The version number, which indicates how many times a new version of the file or project list has been checked in.

  • Who checked in the file or project file each time.

  • The date and time it was checked in.

  • What comments the developer added when checking in the file or project list.

To view checkout history for a file or the project list

  1. If you're viewing the history of a single file, in the Project Manager, select the file for which you want to see the history.

  2. For an individual file, from the Project menu, choose Source Control, then choose Show History. For the project list, from the Project menu, choose Source Control, and then choose Show Project List History.

    The specific options available from this menu command depend on your source control system. For details, choose Help in the dialog box that's displayed or refer to the documentation for your source control system.

You can also view the information about an individual or about the project that's being maintained by the source control system. This usually includes information such as the checkout status of the file or project list, whether the file is a text or binary file (which determines if you can merge your changes with the centrally-stored file), and so on.

To view source control information for a file or the project list

  1. If you're viewing the history of a single file, in the Project Manager, select the file for which you want to see the history.

  2. For an individual file, from the Project menu, choose Source Control, and then choose Source Control Properties. For the project list, from the Project menu, choose Source Control, and then choose Project Properties.

    The specific options available from this menu command depend on your source control system. For details, choose Help in the dialog box that's displayed or refer to the documentation for your source control system.

See Also

Other Resources

How to: Check for Differences in Forms, Reports, and Other Table Files
Developing and Modifying Databases in Teams
Planning for Team Development Projects
Managing Files in a Source-Controlled Project


Developing and Modifying Databases in Teams

Visual FoxPro 9.0
Developing and Modifying Databases in Teams
See Also

In addition to working together with projects and project files, your team must be able to share information in databases. Working with databases as a team involves not only the issues of ordinary concurrency control for data in tables, but the need to be able to share database control information as well.

For several developers to work with a database at the same time, they must be able to share the database (.dbc) file. In Visual FoxPro, the .dbc file can be shared between developers as an ordinary data table. The .dbc file must therefore be stored centrally with the tables making up the database. Developers shouldn't keep local copies of a .dbc file because changes that they make to the database will not be reflected in other developers' versions of the file.

If you do need to change the .dbc file, note the following restrictions:

  • Developers cannot modify the same database element (such as a table structure, view, or connection) at the same time. When a developer modifies a database element, Visual FoxPro locks its entry in the .dbc file; other users can read the entry (that is, they can issue a USE command), but they cannot modify it (MODIFY STRUCTURE).

  • If a database element is in use, you cannot modify its structure. For example, if one developer has a table open, no other developer can modify its structure.

  • If you call the DBSETPROP( ) function to change the properties of a database, the function puts a write lock on the object being updated. If there's a lock conflict, DBSETPROP( ) follows the rules established with SET REPROCESS.

Working with Views and Connections

Views and connections work somewhat differently than tables. When you're first defining the view, Visual FoxPro uses the tables in a database, but doesn't lock them. However, because the tables are in use, other developers cannot modify their structures.

From the time you first save a new view or connection definition, Visual FoxPro locks it exclusively until you close the View or Connection Designer. In other words, as long as you have the view or connection open in a designer, it's locked exclusively. While the view is locked, no one else can modify it.

When you use a view, its structure is cached locally. This ensures that if the view is modified while you're using it — for example, if you call REFRESH( ) or REQUERY( ) — your form or report continues to run correctly.

See Also

Other Resources

How to: Display File and Project Information
Developing Class Libraries in Teams
Planning for Team Development Projects
Managing Files in a Source-Controlled Project


Developing Class Libraries in Teams

Visual FoxPro 9.0
Developing Class Libraries in Teams
See Also

Because class libraries (.vcx files) are a crucial part of most Visual FoxPro applications, teams must be able to coordinate development efforts when creating them. Working with class libraries in a team involves many of the same coordination issues that any set of application components does, but adds some issues unique to classes:

  • Changes to classes are propagated not just to applications that use those classes, but to all subclasses derived from them.

  • Multiple classes are often stored in a single library file, the minimum unit that can be managed by a source control system.

As with complex forms and programs, it's good practice to isolate development in a class library, so that one developer can make changes to the library without affecting the work of other developers. Ideally, the team of developers can work with a class library while it's being enhanced by another developer, without having to worry about whether changes to the libraries will cause problems in the application.

When a class is used, Visual FoxPro caches it on the user's computer, even after a form that uses the class has been released. You must explicitly release the class before Visual FoxPro will recognize it as no longer in use. If you've used a class during the current session (and it's therefore cached), but want to load a new version of the class, be sure to release the class to force Visual FoxPro to reload it from the changed library.

Putting Class Libraries Under Source Control

When you put a class library under source control, only one developer can check the library out at a time. The library becomes read-only for other developers. As a rule, this doesn't interfere with application development, because developers can use and subclass a library even if it's read-only. While the application developers work with the read-only version of the library, the class library developer can modify all the classes in the library.

If you use this approach, the developer who is updating the library shouldn't check in the file until it has been finished and tested. Otherwise, other developers will get the incomplete version of the file when they update their project file lists or get the latest versions of files.

If the library is very complex, you can also consider breaking it into smaller libraries for development. Another advantage of this approach is that smaller library files load faster. However, this means that different classes might be finished and available at different times.

Because each approach has its advantages, you should examine the requirements of your development team and choose the strategy that best fits how you work.

See Also

Other Resources

Developing and Modifying Databases in Teams
Planning for Team Development Projects
Managing Files in a Source-Controlled Project
How to: Display File and Project Information


Developing International Applications

Visual FoxPro 9.0
Developing International Applications

This section describes how to use the international features of Visual FoxPro to develop and plan applications that are compatible and effective in international markets.

In This Section

Planning an International Application

Describes steps for preparing an international application.
Designing for Localization

Describes best practices to use when designing user interface components for localization.
Managing Files in an International Application

Explains how the Project Manager can help you organize an international application. In a project you can integrate the parts of an application, such as forms, menus, programs, and reports.

Related Sections

Creating International Applications

Describes how to create Visual FoxPro applications that are compatible and effective in international markets.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.


Planning an International Application

Visual FoxPro 9.0
Planning an International Application
See Also

By designing an application for international use, you can reduce the cost and time to market instead of modifying it later for international use. When you prepare to design an international application, make sure you consider the following:

  • Acceptable data for an international application.

  • Writing code for an international application.

  • Design considerations for the user interface.

Preparing an international application usually involves the following steps: creating data, writing code, and designing a user interface. The following sections contain more information about these considerations.

Determining Acceptable Data for International Applications

To determine acceptable data for an international application, consider the following:

  • Locales of the application users.

  • Languages that affect the code page used to prepare data.

The locales of your users determine the cultural content of the data as well as the languages that affect the code page. A code page is a character set that a computer uses to display data properly, often to handle international characters. International characters include characters that have diacritical marks. Diacritical marks are placed over, under, or through letters to indicate sound changes from the unmarked form. For example, the most common diacritical marks are the grave accent (` as in à), acute accent (' as in á), circumflex (^ as in â), tilde (~ as in ã), umlaut (¨ as in ä), and slash (/ as in ø), all used in conjunction with vowels.

Ordinarily, data is automatically marked with the appropriate code page when you work with it. However, if you manually assign a code page to a table, or if you otherwise cause the code page to change, users might not recognize some or all of the data displayed. For more information, see Code Pages in Visual FoxPro.

Some languages, such as Chinese, Korean, and Japanese, use double-byte character sets (DBCS) to represent their data. If your application might run in these environments, you might need to use special string-handling functions and collation sequences for the application to work properly. For more information, see Application Creation with Double-Byte Character Sets.

Writing Code for International Applications

An application consists of an application component and a user interface component. The application component contains the code that runs for all locales, including code that processes the strings and graphics used in the user interface. The user interface component contains graphics, text strings, and settings related to various locales, such as dates, currencies, numeric values, and separators.

When designing your application, keep the application and user interface components separate because independent components make the application easier to localize and maintain.

For example, you do not have to browse the source code to localize interface elements when they are separate components. For more information, see Modifying International Applications.

Designing the User Interface for International Applications

The menus, forms, controls, toolbars, and bitmaps used in the user interface must be appropriate for the locales for the application you design. For example, if you design the application for users in Germany and France, dialog boxes must be large enough to display instructions that are localized in German and French. In addition, the images used in icons and bitmaps must be culturally appropriate and correct so that users in target locales can understand them. For more information, see Designing for Localization.

Testing International Applications

When testing international applications, remember to check the following:

  • Country and language dependencies for the application.

  • Application data and user interface for conformity to the locale's standards for date and time, numeric values, currency, list separators, and measurements.

See Also

Other Resources

Developing International Applications


Designing for Localization

Visual FoxPro 9.0
Designing for Localization
See Also

Because text tends to increase when you localize an application, be careful when designing the following user interface components:

  • Application messages

  • Menus and forms

  • Icons and bitmaps

Creating Application Messages

When you create messages in your application, English text strings are usually shorter than equivalent text strings in other languages. The following table shows the additional average growth for strings, based on their initial length.

English length (in characters) | Additional growth for localized strings
1 to 4 | 100%
5 to 10 | 80%
11 to 20 | 60%
21 to 30 | 40%
31 to 50 | 20%
over 50 | 10%

Designing Menus and Forms

As with messages, menus and forms can grow when the application is localized. For instance, consider the following forms, which are part of an Automated Teller Machine sample application. The first figure shows the English form, and the second figure shows the Spanish equivalent. You can see that extra space was allocated for text to increase in the form.

Tip:
If you allow room for text to increase in an interface, localizers need less time to resize controls and to redesign the interface.

In menus and forms, avoid crowding status bars. Also, avoid abbreviations, because they might not exist in other languages.

Using Icons and Bitmaps

Used properly, icons and bitmaps can be an important part of a user interface. However, the meaning of icons and bitmaps can be more ambiguous than the meaning of words. Therefore, consider the following guidelines when using icons and bitmaps:

  • Use images that are universally recognized. For example, use an envelope to represent mail, but don't use a mailbox because it's not a universal symbol.

  • Use culturally sensitive images. For example, avoid using images of religious symbols and animals.

  • Avoid using text in bitmaps, because text growth can become a problem, just as it can in other parts of the interface.

  • Avoid jargon, slang, humor, extravagant language, and ethnic stereotypes.

  • Use ToolTips to help explain icons, which have the added advantage of expanding automatically to the size of the text they display.

  • If you portray men and women, ensure that their gender roles are suitable, and that gestures and images of the human body are appropriate in the target culture.

  • Use color appropriately. For example, avoid using color combinations associated with national flags or political movements.

If you're not sure whether an icon or bitmap is appropriate, consult someone in the locale for which you're designing the application.

See Also

Other Resources

Planning an International Application
How to: Enter International Data
Developing International Applications
Code Pages in Visual FoxPro
Code Pages Supported by Visual FoxPro


Managing Files in an International Application

Visual FoxPro 9.0
Managing Files in an International Application
See Also

The Project Manager can help you organize an international application. In a project you can integrate the parts of an application, such as forms, menus, programs, and reports. The project ensures that the parts are current when you build the application for its target market.

Unlike .dbf files, text files such as query and program files don't have code page marks. This means that you must keep track of the code pages used by text files so that you can use the files properly. With the Project Manager, you can track the code pages used by text files.

Distributing Locale-Specific Run-Time Files

If you're distributing your application along with the run-time version of Visual FoxPro, you might need to include a locale-specific resource file. This file contains the dialog boxes and other user-interface elements that Visual FoxPro uses to interact with the user. There is a different run-time resource file for each language in which Visual FoxPro is available.

You would normally need to concern yourself about a locale-specific run-time resource only if all of the following are true:

  • You are including the run-time version of Visual FoxPro with your application.

  • You are distributing your application to users who use a language different from the one in which you developed it. For example, if you develop in English for an English-speaking user base, you don't need to worry about including a locale-specific resource file. However, if you use the English version of Visual FoxPro to develop but are distributing your run-time application in a French-speaking country, you should consider including the run-time resource file.

  • Your application displays Visual FoxPro dialog boxes, menus, or error messages. Typically, if you've designed and localized your own versions of these interface elements, you don't need to include the locate-specific resource file.

Run-time resource files are named using the format VFPVersionNumber***.dll, where VersionNumber is the version number of Visual FoxPro and "***" is a three-letter code representing the language. For example, the code ENU stands for United States English, the code DEU stands for German, and the code FRA for French.

You must always include at least one run-time resource file, even if you don't intend to use any of the user interface elements in Visual FoxPro as part of your application. By default, Visual FoxPro includes the resource file that's provided with your copy of the program. For example, if you're developing an application using the United States version of Visual FoxPro, Visual FoxPro automatically includes VFPVersionNumberRENU.dll if you include run-time files with your application. If you have no reason to use a locale-specific resource file, you can simply distribute the default resource file as part of your application.

When the application is installed, users can specify the run-time resource file to use by making an entry in the Windows system registry or by using a command-line switch.

To specify a run-time resource file:

  • In the command line that starts your application, include the L switch and the name of the resource file that you want to use (including a path if necessary). Do not put a space between the switch and the file name.

    For example, the following command specifies the file VFPVersionNumberRDEU.dll as the resource file:

    Copy Code
    C:\Program Files\Microsoft Visual ;
FoxPro\MYAPP.EXE -LC:\MyApp\VFPVersionNumberRDEU.dll
    -or-

  • Set the Windows registry on the user's machine (using code or an application such as Regedit.exe) to point to the resource file to use. The registry entry containing the name of the run-time resource file is:

    HKEY_CLASSES_ROOT\VisualFoxProRuntime.VersionNumber\Resources

    For example, the following registry entry points to the run-time resource file VFPRDEU.dll:

    HKEY_CLASSES_ROOT\VisualFoxproRuntime.VersionNumber\Resources C:\Program Files\Common Files\Microsoft Shared\VFP\VFPRDEU.dll

    If you want to control the resource file used by the full development version of Visual FoxPro, use a similar registry key without the run-time reference:

    HKEY_CLASSES_ROOT\VisualFoxpro.VersionNumber\Resources

    For example, the following registry entry points to the resource file on a computer with the full version of Visual FoxPro installed:

    HKEY_CLASSES_ROOT\VisualFoxpro.VersionNumber\Resources C:\Program Files\Visual FoxPro VersionNumber \VFPDEU.dll

When the run-time application starts, Visual FoxPro searches for a resource file, first according to the L switch and then according to the Registry setting. If neither of these settings specifies a locale-specific resource file, Visual FoxPro uses the current system (Windows) locale to dynamically construct a DLL file name. Therefore, if the locale-specific resource file for your application matches the system locale on the user's version of Windows, you don't need to explicitly specify the resource file name. However, it's always safest not to rely on the system default if you want to be sure that the proper file is loaded.

See Also

Other Resources

Creating International Applications
Modifying International Applications
How to: Specify the Code Page of a Text File
Application Distribution Process
Developing International Applications
Application Creation with Double-Byte Character Sets
Sorting Data in International Applications


Creating Applications

Visual FoxPro 9.0
Creating Applications

When you create a Microsoft Visual FoxPro application, it typically includes one or more databases, a main program that sets up the application's system environment, and a user interface comprised of forms, toolbars, reports, and menus.

To create an application, follow these steps:

  1. Create a project.

  2. Configure your application by setting a starting point, initializing the environment, and starting the event loop.

  3. Create a user interface for your application.

  4. Create reports and labels for your application.

The Application Framework can create applications automatically that include all required, and many optional, elements that make an application effective and easy to use. For more information, see Creating Applications with the Application Framework.

In This Section

Working with Projects

Describes using projects as a way to develop large applications.
Configuring an Application

Explains the steps involved in configuring a Visual FoxPro application.
Creating Applications with the Application Framework

Explains how to create applications with the Application Framework using the Application Wizard and the Application builder.
Creating the User Interface

Discusses how creating forms, classes, controls, and toolbars can provide a rich set of tools for your user interface.
Working with Reports

Introduces Visual FoxPro reports and labels and how to include them in your applications.
Creating International Applications

Describes how you can design and develop your Visual FoxPro applications so they are as effective internationally as domestically.

Reference

Database Wizard

Makes it possible for you to use predefined templates to help you create a database containing appropriate tables.
Database Designer

Displays and allows you to create and modify tables, views, and relationships that are contained in a database.
Project Manager

Makes it possible for you to organize and manage your files in projects.

Related Sections

Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.


Working with Projects

Visual FoxPro 9.0
Working with Projects

Visual FoxPro projects make it easier and faster to develop large applications. When you want create an application and manage files associated with that application, you can use projects to organize and work those files. Projects are actually tables that keep track of all files required by an application as well as dependencies, references, and connections among the files. For example, a simple project might consist of forms, programs, reports, databases, tables, queries and other files.

In This Section

How to: Create Projects

Explains how to create projects.
How to: Create Files in Projects

Explains to how to create new files in projects for application components, such as databases, tables, programs, queries, text files, and so on.
How to: Add Files to a Project

Explains how to add existing files to projects.
How to: Edit Files in Projects

Explains how to edit project files and add descriptions for them.
How to: Search For Code References

Describes how to search for references and text in projects and text files.
How to: Replace Code References

Describes how to replace code references and text that you search for in projects and text files.
How to: View Code Definitions

Describes how to view the definition of a code element found in a code reference search in the current program file.
How to: Remove Files from Projects

Explains how to remove or delete files from projects.
Extending Projects in Visual FoxPro

Introduces and describes how to use Project Manager hooks to extend working with projects programmatically.

Related Sections

Working with Programs

Introduces using program files to store code for executing series of instructions that you do not want to run immediately.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Application Planning

Describes how careful planning saves time, effort, and money and how many of the decisions you make during the planning phase will impact how you create elements of the application.
Creating Applications

Discusses how to create a Visual FoxPro application, which may include one or more databases, a main program that sets up the application's system environment, and a user interface comprised of forms, toolbars, and menus.
Working with Data

Describes how to create effective applications with indexes, tables, and databases based on your data requirements.


How to: Create Projects

Visual FoxPro 9.0
How to: Create Projects
See Also

You can create a project for your application using the Application wizard or as an empty project. After you create a project, Visual FoxPro generates the associated folders and files for the new project, including the main project (.pjx) file and project memo (.pjt) file.

A wizard helps you create and set options for your application project using your answers to a series of questions. The Application Wizard helps you create a project, add files using the Application Builder, and create an application framework that includes required and optional elements for applications.

To create a project using a wizard

  1. On the File menu, click New.

  2. In the New dialog box, click Project, and then Wizard.

    The Application Wizard dialog box opens.

  3. In the Project name box of the Application Wizard dialog box, type the name for your project. To choose another location for your project, change the location in the Project file box or click Browse to select a different location.

    The Project file box displays the location and name of your project as you type it.

  4. When you are finished, click OK.

Visual FoxPro displays the Application Builder dialog box so you can set additional options and add files to your application.

For more information, see Application Wizard, Application Builder, and Creating Applications with the Application Framework.

To create an empty project

  1. On the File menu, click New.

  2. In the New dialog box, click Project, and then New File.

  3. In the Create dialog box, choose a location to save the project and type the name for the new project.

  4. Click Save.

Visual FoxPro opens the Project Manager window for your project. For more information, see Project Manager Window.

To create a project programmatically

  • Use the CREATE PROJECT command to open the Project Manager.

For more information, see CREATE PROJECT Command.

After you create your project, Visual FoxPro opens the Project Manager so you can add and work with files in your project. Files must be added to a project to be included in an application. For more information, see How to: Add Files to a Project.

If you have data, such as spreadsheets, text files, or tables from other applications, you can import it into Visual FoxPro and add it to the project. For more information, see Importing and Exporting Data.

See Also

Other Resources

How to: Create Files in Projects
How to: Add Files to a Project
Working with Projects


How to: Create Files in Projects

Visual FoxPro 9.0
How to: Create Files in Projects
See Also

After creating a project for your application, you can create files for new application components, such as tables, queries, programs, or text files, in your project.

To create a file for a new project component

  1. Open the project for your application.

  2. In the Project Manager, expand the node in the project hierarchy containing the component type that you want to create a file for.

  3. Click the component type you want to create a file for.

  4. On the Project menu, click New File.

    Tip:
    You can also click New in the Project Manager.

  5. Perform one of the following:

    • To begin a wizard for the component, click the wizard button.

    • To create a blank file for the component, click the new component button.

For more information, see Project Manager Window.

See Also

Other Resources

How to: Add Files to a Project
How to: Edit Files in Projects
Working with Projects


How to: Add Files to a Project

Visual FoxPro 9.0
How to: Add Files to a Project
See Also

If you want to include files in an application, you must add them to the project for the application. You can add existing files to a project using the Application Builder or Project Manager. New files that you create using the Project Manager are added automatically to the project. When you compile your application, Visual FoxPro includes the files for the components that are part of your the application.

Note:
When you build your application from a project, files included in the project are marked as read-only. If your application includes files that are modified by the user, you must exclude these files from the build process. For more information, see Excluding Modifiable Files from Builds.

To add a file to a project

  1. Open the project for your application.

  2. In the Project Manager, expand the node in the project hierarchy containing the component type that you want to add.

  3. Click the component type you want.

  4. On the Project menu, click Add File.

    Tip:
    You can also click Add in the Project Manager.

    The Select dialog box for that component type opens.

  5. In the Select dialog box, browse for and select the file you want to add, and then click OK.

For more information, see Project Manager Window.

When you reference files in a program or form, Visual FoxPro adds those files automatically to your project when you build the project, not when you reference them. For example, if a program in your project includes the following line of code, Visual FoxPro adds the file Orders.scx to your project:

Copy Code
DO FORM ORDERS.SCX

When you build the project, Visual FoxPro resolves references to all files and automatically includes implicit files in the project. In addition, if the files contain references to other files, building the project also resolves those references and includes those files. The referenced files appear in the Project Manager the next time you view the project.

Caution:
Visual FoxPro might not be able to resolve references to picture files, such as .bmp and .msk files, depending on how they are used in code. Therefore, add pictures to your files manually. In addition, Visual FoxPro cannot automatically include files that are referenced using macro substitution because the name of the file is not known until the application runs. If your application references files using macro substitution, include the referenced files manually.

See Also

Other Resources

How to: Remove Files from Projects
How to: Edit Files in Projects
Working with Projects


How to: Edit Files in Projects

Visual FoxPro 9.0
How to: Edit Files in Projects
See Also

You can edit files that you add to a project. When you create or add a new file, you can add a description to the file. This description is shown at the bottom of the Project Manager when the file is selected.

To edit a project file

  1. Open the project for your application.

  2. In the Project Manager, expand the nodes in the project hierarchy containing the file you want to edit.

  3. Click the file you want to edit.

  4. On the Project menu, click Modify File.

    Tip:
    You can also click Modify in the Project Manager.

The appropriate window or designer opens so you can modify the file. For more information, see Project Manager Window.

To edit a project programmatically

  • Use the MODIFY PROJECT command to open the Project Manager.

For more information, see MODIFY PROJECT Command.

To add a description to a file

  1. Open the project for your application.

  2. In the Project Manager, select the file.

  3. On the Project menu, click Edit Description.

  4. In the Description dialog box, type a description for the file.

  5. When you are finished, click OK.

For more information, see Project Manager Window.

See Also

Other Resources

How to: Remove Files from Projects
Working with Projects


How to: Search For Code References

Visual FoxPro 9.0
How to: Search For Code References
See Also

You can search for specific code references and text in your projects and folders in Visual FoxPro.

To search for a code reference

  1. If you are searching a project, open the project or projects that you want to search.

  2. On the Tools menu, select Code References.

    If you did not perform a previous search in the project, the Look Up Reference dialog box appears. Otherwise, the Code References window appears and displays the previous search results.

  3. In the Look for box of the Look Up Reference dialog box, type the code or text you want to search for.

  4. Choose one of the following:

    • To search projects, make sure the Scope box is set to Entire project and the name of the project you want to search. To select a different open project, click the Scope arrow to display a list of open projects.

      Tip:
      To restrict your search to the project home directory and subfolders, select the Limit search to project home directory and subfolders check box.

    • To search a folder, make sure the Scope box is set to Folder and that the Look in box is set to the folder you want to search.

      Tip:
      To expand your search to the folder's subfolders, select the Search subfolders check box.

  5. Choose any of the following options:

    • To specify file types other than the default types in your search, click the File Types arrow to display a list of file types.

    • To specify additional options for your search, select settings from the Options group or click the Options button to open the Options dialog box.

  6. Click Search to begin the search.

For more information, see Look Up Reference Dialog Box and Look Up Reference Dialog Box, Options Dialog Box.

If the search is successful, the Code References window displays the search string as a node in the search pane and any results from your search in the results pane. You can view all the results by selecting the code reference node in the search pane, or you can filter your results for each file by selecting a file name in the search pane. You can open the file and go to a code reference directly by double-clicking a result in the results pane. For more information, see Code References Window.

After locating the code or text you want, you can replace it. For more information, see How to: Replace Code References. You can also view code definitions. For more information, see How to: View Code Definitions.

See Also

Other Resources

Working with Projects


How to: Replace Code References

Visual FoxPro 9.0
How to: Replace Code References
See Also

After performing a code reference search, you can replace code or text in your projects or folders. For more information, see How to: Search for Code References.

To replace a code reference in a project or folder

  1. Perform a code reference search to locate the code or text you want to replace.

    If your search is successful, the Code References window displays the search results in the results pane.

  2. In the Code References window, choose the lines of code in which you want to replace the code reference or text by performing one of the following:

    • To select particular lines of code, click the check box for each line of code you want that appears in the results pane.

    • To select all lines of code, right-click in the results pane to display a shortcut menu and choose Select All.

  3. In the Code References window, click Replace on the toolbar to open the Replace dialog box.

    Caution:
    If you select lines of code for replacement in which data files might be affected or where changes to data structures, property values, or property and method names in forms (.scx) or visual class libraries (.vcx) might occur, Visual FoxPro prompts you to confirm or decline the replacement operation. If you confirm replacement, Visual FoxPro performs only those replacements that do not affect data files and provides code in the search string node under the Replacement Logs node for you to manually perform the desired changes. If you decline replacement, no changes are made.

  4. In the Replace with box of the Replace dialog box, type the replacement code or text.

  5. Select options that you want from the Options group.

  6. Click Replace to begin replacement.

    Note:
    If you selected Confirm replacements from the Options group, you must confirm the replacement operation for each line of code you selected. The Code References window displays a record of the replacement operation as a log node below the Replacement Logs node in the search pane and the results of the replacement in the results pane.

For more information, see Code References Window and Replace Dialog Box.

After the Code References tool finishes replacing the code or text, you must confirm whether you want to refresh the results in the Code References window.

See Also

Other Resources

How to: View Code Definitions
Working with Programs


How to: View Code Definitions

Visual FoxPro 9.0
How to: View Code Definitions
See Also

When performing a code reference search, you can locate the definition of a code element that you found in the current program file, if the definition exists. For more information, see How to: Search for Code References.

To view the definition of a code element

  1. Open the program file to the location of the code element.

  2. Double-click the text of the code element to select it.

  3. Right-click to display the shortcut menu, and select View Definition.

You can also call View Definition using the DO (_FOXREF) WITH... command. For more information, see _FOXREF System Variable.

View Definition first searches for other external file references that are in the source file, followed by files in the active project. If multiple code element definitions exist, the Go To Definition window appears so you can select a defintion.

If the definition cannot be found in a file for the active project, View Definition searches other open projects or folders. If the definition is found in one of these locations, the Go To Definition window opens for you to select the correct location. For more information, see Go To Definition Window.

If the code element is user-defined, and the definition is found, Visual FoxPro opens an editing window to the location of the definition. If the item you select is a native Visual FoxPro command or function, the Visual FoxPro Help opens the Help topic for that item. If the item you select is a file name, such as for a #INCLUDE statement or SET PROCEDURE command, Visual FoxPro opens the file.

See Also

Other Resources

Working with Programs
Working with Projects


How to: Remove Files from Projects

Visual FoxPro 9.0
How to: Remove Files from Projects
See Also

You can remove files from your project or delete them.

To remove a file from a project

  1. Open the project for your application.

  2. In the Project Manager, expand the node in the project hierarchy containing the component type that you want to remove.

  3. Click the file you want to remove.

  4. On the Project menu, click Add File.

    Tip:
    You can also click Remove in the Project Manager.

  5. When Visual FoxPro prompts you to confirm removing the file, perform one of the following:

    • To remove the file only from your project, click Remove.

    • To delete the file from disk, click Delete.

For more information, see Project Manager Window.

See Also

Other Resources

Working with Projects


Extending Projects in Visual FoxPro

Visual FoxPro 9.0
Extending Projects in Visual FoxPro

You can access and manipulate projects programmatically as objects using Project Manager hooks.

In This Section

Project Manager Hooks

Introduces Project Manager hooks and tasks you can perform with projects programmatically.
Project Object Hierarchy

Describes the hierarchy for a project object and its associated ProjectHook object.
Project Object Architecture

Describes language elements, such as clauses and project events, that are part of the project object architecture.

Related Sections

Working with Projects

Defines a project a configuration and a group of files that produce a program or final binary file or files.
Development Productivity Tools

Provides information on developer tools provided for application development within the Visual FoxPro application and the language.


Project Manager Hooks

Visual FoxPro 9.0
Project Manager Hooks
See Also

In Visual FoxPro, you can access a project programmatically and manipulate a project as an object. You can manipulate a project while the project is open in the Project Manager at design time or while the Project Manager is not visible at design time and run time.

Tip:
To open or modify a project so you can manipulate it programmatically without displaying the Project Manager, use the NOSHOW clause in the CREATE PROJECT and MODIFY PROJECT commands. You can use the project's Visible property to display the Project Manager later. For more information, see CREATE PROJECT Command and MODIFY PROJECT Command.

The following lists describes some of the actions you can perform programmatically with a project:

  • Open and modify files in the project.

  • Add or delete files from a project.

  • Determine the number of files in a project and their types.

  • Change properties of the project.

  • Change properties of files in the project.

  • Change properties of Automation servers, which are dynamic-link library (.dll) files or executable (.exe) built from the project.

  • Execute code when events occur in the project.

  • Rebuild the project or build .app, .exe, or .dll files from the project.

  • Add files in the project to source code control applications, such as Microsoft Visual SourceSafe, and check files in and out of source code control.

    Note:
    If you add a project to Visual SourceSafe, all files contained in the project must be in the project directory or path for proper mapping to the project.

As an advanced developer, you can also create customized project managers.

See Also

Other Resources

Project Object Hierarchy
Project Object Architecture
Extending Projects in Visual FoxPro


Project Object Hierarchy

Visual FoxPro 9.0
Project Object Hierarchy
See Also

The project hierarchy consists of the Projects collection, Project objects in the collection, and a ProjectHook object associated with each project object. A Project object contains a Files collection consisting of project files and a Servers collection consisting of Automation servers created from the project.

The following diagram illustrates the project hierarchy within the Visual FoxPro object model.

A Project object is instantiated when a project is created, opened, or rebuilt, or when an application (.app) file, dynamic-link library (.dll) file, or executable (.exe) file is built from the project. When a project associated with a ProjectHook class opens, a ProjectHook object is instantiated by default.

When an event occurs in a project, the Project object passes the event to the ProjectHook object. User code in the event of the ProjectHook object executes and passes control back to the Project object. The value returned to the Project object from the ProjectHook object determines whether the Project object finishes the operation.

Tip:
Placing NODEFAULT in the event code prevents the default action from being performed. For example, placing NODEFAULT in the QueryAddFile event of a ProjectHook object prevents a file from being added to a project.

The following sections contain more information about the project hierarchy:

  • Projects Collection in the Project Hierarchy

  • Project Object in the Project Hierarchy

  • ProjectHook Object in the Project Hierarchy

Projects Collection in the Project Hierarchy

The Projects collection provides direct access to Project objects, making it possible for you to manipulate a project and the files and servers that the project contains. When a project is created or opened or when an application (.app) file, dynamic-link library (.dll) file, or executable (.exe) file is built from the project, a project object is added to the projects collection.

You can obtain information about a project in the Projects collection using its properties and methods. For example, the following lines of code show two ways to display the names of all projects in a Projects collection. The first example uses the Count property and Item method of a Projects collection. The second example uses the FOR EACH command.

Copy Code
nProjectCount = Application.Projects.Count
FOR nCount = 1 TO nProjectCount
   ? Application.Projects.Item(nCount).Name
NEXT
FOR EACH oProj IN Application.Projects
   ? oProj.Name
ENDFOR

For more information, see Projects Collection.

Project Object in the Project Hierarchy

A Project object is instantiated when a project is created, opened, or rebuilt, or when an application (.app) file, dynamic-link library (.dll) file, or executable (.exe) file is built from the project. A Project object contains a Files collection consisting of project files and a Servers collection consisting of Automation servers created from the project.

The Project object makes it possible for you manipulate a project programmatically and to access it through an Application object. The Application object has an ActiveProject property that provides an object reference to an open project in the currently active Project Manager.

You can manipulate a Project object through its properties and methods. For more information, see Project Object and Application Object.

Files Collection

The Files collection provides direct access to a File object, which makes it possible for you to manipulate File objects in a project while the project is open. You can manipulate a File object using its properties and methods. For more information, see File Object.

You can add files to a project programmatically. For example, the following line of code uses the ActiveProject property of an Application object to add a program, Main.prg, to the currently active project:

Copy Code
Application.ActiveProject.Files.Add('Main.prg')

The following line of code adds Main.prg to the first project in the Projects collection:

Copy Code
Application.Projects[1].Files.Add('Main.prg')

You can obtain information about a file in a Files collection using its properties and methods. For example, the following lines of code show two ways to display the names of all files in a Files collection. The first example uses the Count property and Item method of a Files collection. The second example uses the FOR EACH command.

Copy Code
nFileCount = Application.ActiveProject.Files.Count
FOR nCount = 1 TO nFileCount
   ? Application.ActiveProject.Files.Item(nCount).Name
NEXT
FOR EACH oProj IN Application.ActiveProject.Files
   ? oProj.Name
ENDFOR

For more information, see Files Collection.

Servers Collection

The Servers collection provides direct access to a Server object, which makes it possible for you to manipulate Server objects that a project contains. You can manipulate a Servers collection through its properties and methods. For more information, see Servers Collection.

When you build a dynamic-link library (.dll) file or executable (.exe) file containing an Automation server from the project, a Server object is added to the Servers collection. For more information about creating Automation servers, see How to: Create Automation Servers in Sharing Information and Adding OLE.

Note:
A Server object is not instantiated until the project containing the OLEPUBLIC class, specified in the DEFINE CLASS command, is built. For more information, see DEFINE CLASS Command.

A Server object makes it possible for you to obtain information about Automation servers contained in a project, for example, type library information. This information is also available on the Servers tab in the Project Information dialog box. For more information, see Servers Tab, Options Dialog Box.

You can manipulate a Server object in a Servers collection using its properties. For more information, see Server Object.

ProjectHook Object in the Project Hierarchy

When a project associated with a ProjectHook class opens, a ProjectHook object is instantiated by default.

Tip:
To prevent a ProjectHook object from instantiating for the project, include the NOPROJECTHOOK clause in CREATE PROJECT and MODIFY PROJECT commands. For more, see CREATE PROJECT Command and MODIFY PROJECT Command.

The ProjectHook object and allows programmatic access to events that occur in a project. For example, you can execute code when adding a file to a project. The ProjectHook object differs from a Project object, which contains all the properties and methods available in the Project Information dialog box. For more information, see Project Information Dialog Box.

The default ProjectHook class is specified for new projects in the Projects tab of the Options dialog box. You can override the default ProjectHook class by specifying a different project hook class for an individual project in the Project Information dialog box. However, if no default ProjectHook class is specified in the Projects tab, new projects are not associated with a ProjectHook object. For more information, see Projects Tab, Options Dialog Box.

At run time, you can use the ProjectHook property to specify a project hook class for a project. If you change the ProjectHook class for a project, the new ProjectHook class does not take effect until the project closes and opens again.

You can manipulate a ProjectHook object through properties, methods, and events. For more information, see ProjectHook Object.

See Also

Other Resources

Project Manager Hooks
Project Object Architecture
Extending Projects in Visual FoxPro
Working with Projects


Project Object Architecture

Visual FoxPro 9.0
Project Object Architecture
See Also

A Visual FoxPro Project object exposes the IDispatch interface so that Automation clients, ActiveX controls, and other COM objects can access the project object through standard OLE interfaces. When manipulating projects, errors that might occur are OLE errors because a Project object exposes the IDispatch interface.

Project Events

The following sections describe events and the order in which they occur when projects are created, modified, closed, built, and so on.

Creating a New Project

The following events occur when you execute CREATE PROJECT, create a new project from the File menu, or click the New button on the standard toolbar to create a new project:

  1. The Project object is created.

  2. The ProjectHook object instantiates.

  3. The Init event for the ProjectHook object occurs. If the Init event returns true (.T.), the default, the project is created and the project is displayed in the Project Manager.

    If the Init event returns false (.F.), the project isn't created, the project and ProjectHook objects are released, and the Project Manager isn't displayed.

Modifying an Existing Project

The following events occur when you execute MODIFY PROJECT, modify an existing project from the File menu, or click the Open button on the standard toolbar to open an existing or create a new project:

  1. The project object is created. The project object obtains its values from the project's .pjx file.

  2. The ProjectHook object is instantiated.

  3. The Init event for the ProjectHook object occurs. If the Init event returns true (.T.) (the default), the project is opened for modification in the Project Manager.

    If the Init event returns false (.F.), the project isn't opened for modification, the project and ProjectHook objects are released, and the Project Manager isn't displayed.

Closing a Project

The following events occur when an open project is closed:

  1. The ProjectHook Destroy event occurs and the ProjectHook object is released.

  2. The Project object is released.

Issuing BUILD APP, BUILD DLL, or BUILD EXE

The following events occur when BUILD APP, BUILD DLL, or BUILD EXE is issued:

  1. The project object is created. The project object obtains its values from the project's .pjx file.

  2. The ProjectHook object is instantiated.

  3. The Init event for the ProjectHook object occurs. If the Init event returns true (.T.), the default, the ProjectHook BeforeBuild event occurs. If NODEFAULT is included in the BeforeBuild event, the .app, .dll, or .exe isn't built. Otherwise, the build process continues.

    If any files are added to the project during the build process, the ProjectHook QueryAddFile event occurs before each file is added. If NODEFAULT is included in the QueryAddFile event, a file isn't added to the project. Otherwise, the file is added to the project. When the .app, .dll, or .exe is successfully built, the ProjectHook AfterBuild event occurs, and then the ProjectHook Destroy event occurs.

    If the Init event returns false (.F.), the app, .dll, or .exe isn't built, and the project and ProjectHook objects are released.

Issuing BUILD PROJECT

The following events occur when BUILD PROJECT with the FROM clause is issued. If the FROM clause is omitted, the events occur in the order described above when BUILD APP, BUILD DLL, or BUILD EXE is issued.

  1. The project object is created. The project object obtains its values from the project's .pjx file.

  2. The ProjectHook object is instantiated.

  3. The Init event for the ProjectHook object occurs. If the Init event returns true (.T.), the default, the files specified in the FROM clause are added individually to the project. The ProjectHook QueryAddFile event occurs before each file is added to the project. If NODEFAULT is included in the QueryAddFile event, the file isn't added to the project. Otherwise, the file is added to the project.

    The ProjectHook BeforeBuild event then occurs. If NODEFAULT is included in the BeforeBuild event, the project isn't built. Otherwise, the project is built.

  4. When the project build is complete, the ProjectHook AfterBuild event occurs, and then the ProjectHook Destroy event occurs.

    If the ProjectHook Init event returns false (.F.), the project isn't built. The project and ProjectHook objects are released and a new .pjx file isn't created.

Using a Drag and Drop Operation

The following events occur when you drag a file or a set of files over the outline section (treeview) of the Project Manager:

  1. When the mouse pointer is positioned over the outline section of the Project Manager, the ProjectHook OLEDragOver event occurs with the nState parameter set to 0 (DRAG_ENTER in Foxpro.h). The OLEDragOver event then occurs repeatedly with the nState parameter set to 2 (DRAG_OVER in Foxpro.h). If the mouse pointer moves outside of the outline section of the Project Manager, the OLEDragOver event occurs with the nState parameter set to 1 (DRAG_LEAVE in Foxpro.h).

  2. The ProjectHook OLEDragDrop event occurs if you release the mouse button while the mouse pointer is positioned over the outline section of the Project Manager. By default, Visual FoxPro adds each file dropped on the Project Manager to the project. The ProjectHook QueryAddFile event occurs before each file is added to the project.

Adding a File with the Add Button

The following events occur when you add a file to a project by clicking the Add button in the Project Manager:

  1. The Open dialog box appears.

  2. If you select a file and choose OK, a file object is created for the file you select.

  3. The ProjectHook QueryAddFile event occurs and the name of the file object is passed to the event. If NODEFAULT is included in the QueryAddFile event, the file isn't added to the project. Otherwise, the file is added to the project.

Adding a File with the New Button

The following events occur when you add a new file to a project by clicking the New button in the Project Manager:

  1. The appropriate designer or editor for the file is displayed.

  2. When the new file is saved, the Save As dialog box is displayed. Clicking Save creates a file object for the new file.

  3. The ProjectHook QueryAddFile event occurs and the name of the file object is passed to the event. If NODEFAULT is included in the QueryAddFile event, the file isn't added to the project. Otherwise, the file is added to the project.

Modifying a File with the Modify Button

The following events occur when you modify a file in a project by clicking the Modify button in the Project Manager:

  1. The ProjectHook QueryModifyFile event occurs before the appropriate designer or editor for the file is displayed.

  2. The file object for the file to modify is passed as a parameter to the QueryModifyFile event. If NODEFAULT is included in the QueryModifyFile event, the appropriate designer or editor for the file isn't displayed and the file isn't modified. Otherwise, the file is opened in the appropriate designer or editor for modification.

Removing a File with the Remove Button

The following events occur when you remove a file in a project by clicking the Remove button in the Project Manager:

  1. The ProjectHook QueryRemoveFile event occurs.

  2. The file object for the file to be removed is passed as a parameter to the QueryRemoveFile event. If NODEFAULT is included in the QueryRemoveFile event, the file isn't removed from the project. Otherwise, the file is removed from the project.

Executing a File with the Run Button

The following events occur when you execute a file in a project by clicking the Run button in the Project Manager:

  1. The ProjectHook QueryRunFile event occurs.

  2. The file object for the file to be executed is passed as a parameter to the QueryRunFile event. If NODEFAULT is included in the QueryRunFile event, the file isn't executed. Otherwise, the file is executed.

Rebuilding a Project or Building a File with the Build Button

The following events occur when you rebuild the project or build an .app, .dll, or .exe from a project by clicking the Build button in the Project Manager:

  1. The Build Options dialog box is displayed.

  2. You can choose Rebuild Project, Build Application, Build Executable, or Build COM DLL, and specify additional build options. If you click Cancel, the build doesn't occur.

  3. The ProjectHook BeforeBuild event occurs if you click OK, and the build process begins.

  4. When the build is completed, the ProjectHook AfterBuild event occurs.

See Also

Other Resources

Project Manager Hooks
Project Object Hierarchy
Extending Projects in Visual FoxPro
Working with Projects


Configuring an Application

Visual FoxPro 9.0
Configuring an Application

You need to configure your Visual FoxPro application properly so that it performs according to the specifications set during application planning. Typically, you might create an application object to perform these tasks. You can also use a main file to handle these tasks.

In This Section

How to: Set the Starting Point

Explains how to designate a file as the main file and starting point of your application.
Main Files in Applications

Introduces using main files in applications.
How to: Initialize the Environment

Describes how to configure the application environment.
How to: Control the Event Loop

Describes how to start and stop the event loop for an application.
How to: Customize the Appearance of Applications

Describes how you can change the appearance of your application, for example, the application icon or title, without changing code.

Related Sections

Creating Applications

Explains concepts about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed for Visual FoxPro applications.
Application Architecture

Describes how Visual FoxPro application architecture varies with the type of application you decide to create.


How to: Set the Starting Point

Visual FoxPro 9.0
How to: Set the Starting Point
See Also

All applications must have a main file, which is a file that sets the starting point for your application, performs the major tasks in your application, and links components in the application together.

Note:
You can set only one file in a project as the main file.

When you use the Application Wizard to create the project for your application, the wizard creates a main program file automatically. However, you can modify the main file created by the wizard or designate a different file in the project as the main file.

The Application Wizard also creates an application object you can use to manipulate your application. The main program created by the Application Wizard includes sections for instantiating and configuring the application object.

To set a main file for an application

  1. Open the project for your application.

  2. In the Project Manager, expand the nodes containing the file you want.

  3. Click the file to select it.

  4. On the Project menu, click Set Main.

The name of the main file appears in bold in the Project Manager.

Note:
The file that you set as the main file is included in the build process automatically and is marked as read-only when you compile the application.

See Also

Other Resources

Main Files in Applications
Configuring an Application


Main Files in Applications

Visual FoxPro 9.0
Main Files in Applications
See Also

The main file in an application can be a program or a form. Though the best choice for a main file is a program (.prg) file, you can combine the functionality of a main program and the user interface that the user initially sees by using a form. When users run your application, Visual FoxPro launches the main file in your application and runs all other components as needed.

If you use a program file as the main file in your application, make sure that it contains commands to handle the major tasks in your application. However, the main file does not need to issue commands directly to accomplish all the tasks. For example, the main file can call procedures or functions to handle tasks such as initializing the environment and cleaning up memory.

The following list contains and describes major tasks and the order to perform them in a main program file:

  1. Initialize the environment for the application by opening databases, declaring variables, and so on. For more information, see How to: Initialize the Environment.

  2. Establish and display the initial user interface by calling a menu or form.

    The initial user interface can be a menu, form, or any other user component. Sometimes, an application displays login box to request user credentials before displaying the opening menu or form.

    You can initiate the user interface in the main program by using the DO command to run a menu or the DO FORM command to run a form. For example, the following line of code runs a form called Startup:

    Copy Code
    DO FORM BeginApp.scx
    For more information, see DO Command and DO FORM Command.

  3. Detect and respond to user actions by establishing and control the event loop using the READ EVENTS command. For more information, see How to: Control the Event Loop.

  4. End event processing when the user quits the application using a menu command, such as an Exit command, or an Exit button. For more information, see How to: Control the Event Loop.

  5. Restore the environment when the user quits the application.

    Typically, it is recommended that you save default settings of the environment in public variables, a custom class, or as properties of an application object so that you can restore these values when quitting the application.

    Tip:
    If you initialize the environment using a different program than the one you use to restore it, make sure you can access the values you stored. For example, suppose you initialize the environment by calling one procedure but restore the environment by calling another. Make sure to store the values you want to restore in public variables, custom classes, or as properties of an application object.

    Note:
    Variable names used with macro substitution should not contain the m. prefix because the period assumes variable concatenation and produces a syntax error.

For example, a main program file might contain the following lines of code:

Copy Code
DO SETUP.PRG
DO MAINMENU.MPR
READ EVENTS
DO CLEANUP.PRG

These lines of code perform the following tasks:

  • Run a setup program to initialize the environment

  • Run a menu file to display an application menu.

  • Call READ EVENTS to establish the event loop.

  • Run a cleanup program to restore the environment.

See Also

Other Resources

How to: Set the Starting Point
Working with Programs
Working with Forms
Configuring an Application


How to: Initialize the Environment

Visual FoxPro 9.0
How to: Initialize the Environment
See Also

When Visual FoxPro starts, the default Visual FoxPro development environment establishes certain values for SET commands and system variables. However, these settings might not be the best environment for your application. Therefore, the first task that the main file or application object must perform is setting up the environment for the application.

Tip:
It is recommended that you save the initial environment settings and modify them to set up a specific environment for your application. To see the default values of the Visual FoxPro development environment, start Visual FoxPro without a configuration file by typing VFP -C and then call the DISPLAY STATUS command. For more information, see DISPLAY STATUS Command.

To view and save settings for the current environment

  1. On the Tools menu, click Options.

  2. In the Options dialog box, press and hold the SHIFT key while you click OK.

    The SET commands and other environment settings display in the Command window.

  3. In the Command window, copy and paste the SET commands and environment settings into a setup program file.

You can now edit the SET commands and environment settings as appropriate for your application. In the environment for your application, you might want to include code to perform the following:

  • Initialize variables.

  • Establish a default path.

  • Open needed databases, free tables, and indexes. If your application requires access to remote data, the initialization routine can also prompt the user for the necessary login information.

  • Reference external library and procedure files.

For example, suppose you wanted to test the default value of the SET TALK command, store the value, and set TALK to OFF for your application. You might place the following code in your setup procedure:

Copy Code
IF SET('TALK') = "ON"
   SET TALK OFF
   cTalkVal = "ON"
ELSE
   cTalkVal = "OFF"
ENDIF

For more information, see SET Command Overview.

See Also

Other Resources

Configuring an Application
How to: Set the Starting Point
How to: Control the Event Loop


How to: Control the Event Loop

Visual FoxPro 9.0
How to: Control the Event Loop
See Also

After setting up the environment and displaying the initial user interface, your application needs to establish an event loop so it can detect and respond to user interaction. When the user quits the application, your application must provide a way to end the event loop.

Note:
You need to establish a way to exit the event loop before you start it. Make sure the application user interface has a mechanism, for example, a Quit button or Exit menu command, to end the event loop.

To establish the event loop

  • In the main file for your application, include the READ EVENTS command.

The READ EVENTS command causes Visual FoxPro to begin processing user events such as mouse clicks and keystrokes. For more information, see READ EVENTS Command.

Note:
If you do not include the READ EVENTS command, your application returns to the operating system after running. It is important to place the READ EVENTS command correctly in your main file because all processing in the main file is suspended from the time it executes the READ EVENTS command until it executes a subsequent CLEAR EVENTS command. For example, you might call the READ EVENTS command as the last command in an initialization procedure and after initializing the environment and displaying the user interface.

After the event loop begins, the application runs under the control of the user interface element that last displayed. For example, suppose you include only the following command in the main file:

Copy Code
DO FORM STARTUP.SCX

The application displays the form Startup.scx. Within the development environment, your application might run properly in the Command window. However, if you run the application from a menu or screen, the application appears briefly, then quits.

To end the event loop

  • Call the CLEAR EVENTS command using a menu command or button on a form.

The CLEAR EVENTS command suspends the event processing and returns control to the program that called the READ EVENTS command.

Note:
Typically, you call the CLEAR EVENTS command from a menu or a button in a form. The main program file should not call CLEAR EVENTS directly.

For more information, see CLEAR Commands.

See Also

Other Resources

Configuring an Application


How to: Customize the Appearance of Applications

Visual FoxPro 9.0
How to: Customize the Appearance of Applications
See Also

You can change the appearance of your application in the following ways without changing application code:

  • Change the default menu system.

    You can create and add custom menus and menu options using the Menu Designer. Otherwise, the run-time environment displays the default Visual FoxPro menu. For more information, see How to: Create Menus and Submenus.

  • Change the default application title.

    When you run your application, it runs in the main Visual FoxPro window and displays the text "Microsoft Visual FoxPro" in the title bar by default. You can change the default application title to a more appropriate title.

  • Change the default application icon.

    When you compile your application, the default Visual FoxPro icon appears in the Windows Explorer or Start Menu as the application icon. You can use the generic icon supplied by Visual FoxPro or supply your own. For more information, see Graphics Support in Visual FoxPro.

To change the application title

  • In a configuration file for your application, include the following statement and replace MyProgramTitle with the appropriate title of your application:

    Copy Code
    TITLE = MyProgramTitle
    Tip:
    To include a Visual FoxPro function, for example, to display a version number, as part of the title, include the following line in the configuration file to set the Caption property of the main window with the appropriate application title and function name as shown: COMMAND=_SCREEN.Caption="MyProgramTitle " + FunctionName()

For more information, see Special Terms for Configuration Files.

To change the default application icon

  1. Open the project for your application.

  2. In the Project Manager, select the main file for your project.

  3. On the Project menu, click Project Info.

    The Project Information dialog box appears for your project.

  4. In the Project Information dialog box, click the Project tab.

  5. On the Project tab, click Attach icon.

  6. In the Open dialog box, browse for and select an icon (.ico) file to assign to your project.

  7. Click OK.

For more information, see Project Manager Window and Project Information Dialog Box.

See Also

Other Resources

Preparation for Distributing Applications
Configuring an Application


Creating Applications with the Application Framework

Visual FoxPro 9.0
Creating Applications with the Application Framework

The Application Framework is designed to include all required, and many optional, elements that make an application effective and pleasurable to use. Though the framework itself provides a great deal of flexibility and power to create applications the way that works best for you, this section discusses the ways using the Application Wizard and the Application builder ease your application development.

In This Section

How to: Create a Framework

Learn how to create an Application Framework by using the Application Wizard or by using the New Application item in the Component Gallery.
Application Framework Files

Provides a list and description of files that are included in the Application Framework.
Data Selection with Application Builder

Describes how to select the data sources you want in developing your application after you plan your application.
How to: Manage Documents with Application Builder

Discusses how to plan and choose the documents that you want to add to your application once you have selected data sources.
How to: Generate Forms and Reports with Application Builder

Explains how to generate forms or reports without writing any code.
How to: Specify a Builder Application with Builder.dbf

Provides the Builder.dbf table, which you can use to specify a builder application. The table contains fields that represent the name of a builder, a description of the builder, and a field called Type that identifies the Class or Base Class property that invokes the custom builder.

Reference

Related Sections

Creating Applications

Discusses how to create Visual FoxPro applications, which may include one or more databases, a main program that sets up the application's system environment, and a user interface comprised of forms, toolbars, and menus.
Configuring an Application

Explains the steps involved in configuring a Visual FoxPro application.
Optimizing Client/Server Performance

Discusses how you can fine-tune your application to gain maximum performance by increasing data throughput.
Creating the User Interface

Covers how creating forms, classes, controls, and toolbars can provide a rich set of tools for your user interface.
Upsizing Visual FoxPro Databases

Explains how to use the upsizing wizards to move databases, tables, and views from your system to a remote Microsoft SQL Server.
Creating International Applications

Describes how you can design and develop your Visual FoxPro applications so they are as effective internationally as domestically.


How to: Create a Framework

Visual FoxPro 9.0
How to: Create a Framework
See Also

You can create an Application Framework by using the Application Wizard or by using the New Application item in the Component Gallery. When you use the Component Gallery, a new project folder item is added to your Favorites folder.

Whichever method you use, Visual FoxPro displays an Application Builder so you can add information to be stored in a meta table.

To create an application

  1. From the Tools menu, point to Wizards, and then click Application.

    -or-

    In the Catalogs folder of the Component Gallery, double-click the New Application item.

  2. In the Application Wizard dialog box:

    • Specify the project name.

    • Accept or locate the project file.

    • Choose your options to Create project directory structure (default) and Add to Favorites catalog (default).

For more information, see Creating Applications with the Application Framework in Help.

You can also use the Component Gallery to add forms, reports, data, and service objects to your new application framework and controls to forms. When you use the Component Gallery to add a form to an application, you can create a new form or subclass from an existing class.

See Also

Other Resources

Application Framework Files
Creating Applications with the Application Framework
Development Productivity Tools


Application Framework Files

Visual FoxPro 9.0
Application Framework Files
See Also

An application framework includes the project file and a starter class library subclassed from the Visual FoxPro base classes, ready for you to populate with new or existing tables and documents.

Master Include File

This common #INCLUDE file is used by components with settings and strings. The file also includes the APP_GLOBAL value, the name used by components for referencing.
Configuration File

An optional Config.fpw used for applications such as top-level forms in order to implement settings such as SCREEN=OFF.
Project Hook Class

Controls events related to the project such as adding new files. It also can access Application Builder for setting actions and properties of file interaction within the application.
Application Meta Table

Contains information such as project settings made or used by the Application Builder and Project Hooks.
Application Builder

Facilitates adding components to the project and setting properties such as navigation options.

The framework allows you to specify whether to create a complete application or just an application framework. If you choose to create a complete application, you can either include in the application a database and forms or reports you have already created, or you can create a new application from scratch using a database template. If you choose to create a framework, you can go back later and add components to the framework.

See Also

Other Resources

Creating Applications with the Application Framework
Development Productivity Tools


Data Selection with Application Builder

Visual FoxPro 9.0
Data Selection with Application Builder
See Also

After you plan your application, you need to select the data sources you need in developing your application. You can use the Application Builder Data Tab, Application Builder to add databases and tables to your application and project.

Adding Data Using the Data Tab

If you already have existing data, you can use the Data tab to create a data environment for your application by adding free tables or tables from a database to the application. As soon as you specify a table, the Application Builder displays it in the grid and prepares to create both a form and a report for the table. At this point, you have selected only which data sources to include. They are not actually added to the framework until you select the Generate button. If you want to add only the data source and not have new forms or reports, uncheck the options next to the table entry. If you have a form or report check box marked when you click the Generate button, the appropriate wizard creates a new document for that datasource. You can select a visual style for these documents from the Style drop-down lists.

You can later edit these documents in the Form tab or Report tab of the Application Builder. If you have datasources listed in the Data tab grid and you click the OK button to exit the Application Builder, Visual FoxPro prompts you to add the tables, forms and reports to your project and application. Clicking the Generate button performs the same function.

The documents generated by the Application Builder contain all the fields for the selected datasource. If you want more control over the layout of your document, run the Form Wizard or Report Wizard directly from the Wizards menu and add the newly created document in the Form tab or Report tab. You can also add or edit forms or reports from the Application Builder.

When you use the Application Builder to add data, it is marked in the project as Excluded, meaning that it is not bound into the built application. This enables you to edit the added table. A table built into an application is read-only and cannot be edited. If you want to include a table in the project and thereby make it read-only (for example, a special lookup table where data will not change), right-click on the table in the Project Manager, and select the Include menu item.

Creating Data Using the Data Tab

You can also use the Database Wizard or the Database Wizard buttons on the Data tab to create new tables to add to the project and application. These wizards create new data structures for your application in the appropriate data folder and allow you to generate new documents in the same manner discussed previously.

The basic documents that the Application Builder creates contain all fields in the tables on which they are based. These documents are excellent for basic data input and reporting, but you might want to create documents for other unique purposes in your application. The Form Wizard and Report Wizard offer more flexibility and the foundation classes included with the Component Gallery offer added functionality to forms and reports.

Locating Data

If you use the Application Builder to add data and documents to your application, data-binding is handled automatically. The Application Builder does, however, offer a Default Data Directory option on the Advanced Tab, Application Builder if you are manually coding documents to bind to data and need the application framework to handle data path resolution. Use this setting to specify a folder that contains your datasources to provide appropriate path information for this data.

Importing Data

With many applications, you may already have data that you wish to use, but it's not necessarily in the proper format. It might be in plain text or spreadsheet format. In these cases, you can use the Import Wizard to migrate your data into FoxPro tables. You can then easily add these tables to your application.

Upsizing Data

Visual FoxPro includes an upsizing wizard that allows you to move your FoxPro data to a SQL Server database. If the demands of your application require use of one of these databases, you can easily migrate your existing data and still keep the application intact.

The SQL Server Upsizing Wizard allows you to Create remote views on tables. If you select this option, the tables in your database will be changed to remote views. Since the documents (forms or reports) in your application are bound solely to the datasource name, you can still run your application, but the data being used will be SQL Server data instead of FoxPro tables.

If you have existing SQL Server data that you want to use in your application, you can easily set up a Visual FoxPro database containing remote views pointing to these datasources. The application framework will handle these just like they were native FoxPro tables.

See Also

Other Resources

Creating Applications with the Application Framework
How to: Manage Documents with Application Builder


How to: Manage Documents with Application Builder

Visual FoxPro 9.0
How to: Manage Documents with Application Builder
See Also

Once you have selected data sources, you need to plan and choose the documents that you want to add to your application. The Application Builder is particularly effective for this task since it not only adds the document to your project, but also integrates it with the framework. Because the framework uses extended document information stored in a meta-table, the Application Builder automatically handles this integration. The meta-table is stored in the same folder as the application project and is given the same name as the project plus an "_app.dbf" suffix. The extended document information that is stored in the framework meta-table specifies the following:

  • A friendly name to display in the Open or New dialog box.

  • Whether a form appears in the New dialog box.

  • Whether a form appears in the Open dialog box.

  • Whether a form uses a navigation toolbar.

  • Whether a form uses a navigation menu.

  • Whether a form allows for opening of multiple instances.

You can have the builder automatically create new forms and reports when you add data to the application. These documents are generated from the associated wizards.

Once a document has been added to the application framework, it will automatically appear in the Forms tab or Reports tab.

When you open the Forms tab you will find a list that contains the forms you have already added to your application manually or from entries in the Data tab.

Note:
It's possible that a form in your project does not appear in the Forms tab. This is because that form is not registered in the application meta-table. You can register it by choosing the form using the Add button on the Forms Tab page. In addition, the Cleanup button on the Advanced Tab, Application Builder will synchronize the documents in your project with those registered in the meta-table. You can also edit or remove any of these documents from the appropriate tab.

To add documents in the Application Builder

  1. Click the Add button on the appropriate document tab (Form or Report) and select a document. The application framework automatically handles a variety of document types. With forms, you can select a form (.scx) file, a form class from a class library, (.vcx), or a program (.prg) file that contains code that runs a form. With reports, you can choose a report (.frx) file, label (.lbx) file, or program (.prg) file that has code to run a report.

  2. Once you add the file to the document list, you can choose various settings in terms of how that document functions in the application.

The Forms tab enables you to manage the following options:

To edit documents in the Application Builder

  1. Open any listed form or report by highlighting the document and then clicking the Edit button. In the case of a form, you may be prompted with the following message:

    "Would you like to add a mediator object to this form to fully enable it for use with the application framework?"

    If you answer "Yes", the Application Builder adds to your form an object that automatically communicates directly with the application object used by the framework. This object provides additional functionality to forms in your application. For example, when you close a form, the object can detect if there is buffered data that has not been saved and prompt you to save changes. Also, the object will differentiate between a form launched using the New dialog box versus the Open dialog box.

  2. In the designer, edit your document to your liking. You might want to use the Component Gallery to add a background or foundation class. You can use the Component Gallery to add special characteristics and functionality to your document.

To remove documents in the Application Builder

  • You can remove any document from the meta-table by highlighting the document and then clicking the Remove button. After the document is removed from your application, it remains in the project file.

    Note:
    Your application will run regardless of whether a form or report is stored in the meta-table. As long as you provide code that specifies how to run this document, the application will handle it just fine. The advantage of using the Application Builder is that you would not need to worry about the application handling running forms and reports. This is done automatically.

See Also

Other Resources

Creating Applications with the Application Framework
Creating Applications with the Application Framework
Data Selection with Application Builder


How to: Generate Forms and Reports with Application Builder

Visual FoxPro 9.0
How to: Generate Forms and Reports with Application Builder
See Also

You can use the Application Builder to generate forms and reports without having to write code.

To generate forms or reports

  1. Use the Database Wizard button, the Table Wizard button, or the Select button to locate and choose a data source.

    If you select the Database Wizard or Table Wizard buttons, Visual FoxPro opens the selected wizard for you. After you have used the wizard you will be returned to the Data tab of the Application Wizard.

    When you specify the data source, the grid displays the table name and selected Form and Report controls. The wizard automatically selects standard forms and presentation style for all forms and reports. If you accept the default form style and report style choices, go to Step 4; otherwise, go to Step 2.

  2. If you want to only change the form style, clear the Report check box. If you want to only change the report style, clear the Form check box. If you want to change both, leave them both selected.

  3. Choose the styles you want from the Style controls.

  4. Click the Generate button to create the forms and or reports you have specified.

    Note:
    Because the data grid is cleared after you generate forms or reports, you should choose reports and forms with differing styles in separate 'generate' sessions.

See Also

Other Resources

Data Tab, Application Builder
Working with Data


How to: Specify a Builder Application with Builder.dbf

Visual FoxPro 9.0
How to: Specify a Builder Application with Builder.dbf
See Also

You can use the Builder.dbf table to specify a builder application. Each record contains fields that represent the name of a builder, optionally, a description of the builder, and a field called Type that identifies the Class or Base Class property that invokes the custom builder. For instance, the Type entry for a Command Button is Commandbutton and the Type entry for the Autoformat builder is Multiselect because it runs against multiple selected controls.

The following table describes a BUILDER table record.

Field Name | Field Type | Width (comment)
NAME | Character | 45 (Builder name)
DESCRIPT | Memo | 4
BITMAP (unused) | Memo | 4
TYPE | Character | 20
PROGRAM | Memo | 4 (Builder application)
CLASSLIB | Memo | 4 (Class Library name)
CLASSNAME | Memo | 4 (Builder Class)
PARMS | Memo | 4 (passed parameter list)

The named builder application compares the value in the Type field and the Class of the object and starts if there is a match. If more than one match is found, a selection dialog displays.

By default, the Builder.app application passes three parameters, listed in the PARMS field of Builder.dbf, to a builder program:

PARMS Entry | Description
wbReturnValue | Variable containing a value to be returned to the Builder.app.
<character string> | A literal string to pass to Register table.
<optional value> | A keyword or other value to pass to Builder.app

To create a custom builder

  1. Write an application that provides an interface and modifies the selected control or controls.

  2. Save the application in the Wizards folder.

  3. Open the Builders.dbf table and append a new record.

  4. Enter values for the Name, Descript, Type, and Program fields.

    If your custom builder uses additional values, you can also enter values for the remaining fields.

After you complete all entries and close the Browse, the new builder is registered. For example, if you create a program that changes the fonts of selected controls, then save the program in a file called Chgfont.prg, the following table shows the entries for Builder.dbf.

Field Name | Value
NAME | The Builder That Changes Fonts
DESCRIPT | This builder modifies the font of all selected controls
TYPE | MULTISELECT
PROGRAM | Chgfont.prg

When you use the builder, Visual FoxPro displays the Builder Selection dialog box because there are now two builders of the Multiselect type. When you choose The Builder that Changes Fonts , Builder.app runs the program you saved as Chgfont.prg.

See Also

Other Resources

_BUILDER System Variable
Application Builder
AutoFormat Builder
Combo Box Builder
Command Group Builder
Creating Applications with the Application Framework
Edit Box Builder
Form Builder
Grid Builder
How to: Use Builders
List Box Builder
Option Group Builder


Creating the User Interface

Visual FoxPro 9.0
Creating the User Interface

A well-designed interface can guide users through your application. Forms, classes, controls, menus, and toolbars provide a rich set of tools for designing a great user interface.

In This Section

Working with Forms

After creating your form, you can run, hide, or alter it in different ways.
Using Controls

Controls manage the interactions between users and your application. Microsoft Visual FoxPro offers a variety of controls to enhance your application interface.
Designing Menus and Toolbars

A good menu system tells your users a lot about the design and structure of your application. Planning menus and toolbars carefully can improve the usability of your application and provide immediate access to common tasks.

Related Sections

Developing Visual FoxPro Applications

This section includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Creating Applications

Discusses how to create Visual FoxPro application, which may include one or more databases, a main program that sets up the application's system environment, and a user interface comprised of forms, toolbars, and menus.
How to: Set the Starting Point

Describes how the main file is the starting point for your application, and can consist of a program or form. When your application is run, Visual FoxPro launches the main file for your application, which in turn runs all other components as needed.
How to: Initialize the Environment

Setting up the application environment is the first task that a main file or application object must accomplish.
How to: Control the Event Loop

Learn how to establish an event loop to, which causes Visual FoxPro to begin processing user events such as mouse clicks and keystrokes. This occurs after the environment is set up and you've displayed the initial user interface.
Creating Applications with the Application Framework

Explains how to create applications with the Application Framework using the Application Wizard and the Application builder.
Optimizing Client/Server Performance

Learn how you can fine-tune your application to gain maximum performance by increasing data throughput.
Upsizing Visual FoxPro Databases

Explains how to use the upsizing wizards to move databases, tables, and views from your system to a remote Microsoft SQL Server.
Creating International Applications

Describes how you can design and develop your Visual FoxPro applications so they are as effective internationally as domestically.


Working with Forms

Visual FoxPro 9.0
Working with Forms

Visual FoxPro provides true modeless operation so you can work with and run multiple forms. Your application needs forms so that users can view and enter data. You can modify standard forms using the Visual FoxPro user interface and programmatically to create a customized environment for application users.

After you create a form, you can manipulate it in various ways. You can run or hide it using the interface or programmatically. You can alter your form through its objects, by passing data to parameters, or setting the design area and templates. Local and remote data can be incorporated into your form, and you can manage multiple instances of your form.

In This Section

Creating Forms

Describes how to design and build forms, how to use form sets and form types, how to use objects on forms, how to customize forms using properties and methods, and how to set the data environment.
How to: Run a Form

Provides instructions on how to run a form, name a form object, and make it possible for a user to close the active form.
How to: Set Properties at Run Time

Provides instructions on how to set properties to expressions at run time and set multiple properties at the same time.
How to: Hide a Form

Explains how to hide and release a form. When you hide a form, it is invisible to the user, and the user cannot manipulate it. However, you still have complete programmatic control of the form.
How to: Pass Parameters to a Form

Details the steps required to pass a parameter to a form created in the Form designer and to return a value from a form.
How to: Return a Value from a Form

Provides steps for using forms throughout your application to allow users to specify a value.
How to: Manage Multiple Instances of a Form

Outlines the important issues to consider when you have multiple instances of a form and provides examples of multiple instances of a form.
Docking Forms

Describes docking user-defined forms certain Visual FoxPro IDE windows or other forms.
How to: Dock Forms

Describes how to dock user-defined forms.
How to: Create Forms with Local and Remote Data

Describes the creation of forms that can be switched easily between using local and remote data.
How to: Set the Design Area for a Form

Explains how to set the maximum design area for the Form designer in the Options dialog box.
Using Form Templates

Introduces using form templates and their advantages.
How to: Set Form Templates

Describes how to specify a form class from a registered class library for your form template and presents the various ways you can specify form set templates.
How to: Save Forms

Contains directions on how to save a form in the Form designer and save a form or selected controls as a class definition.
How to: Save a Form as HTML

Describes how to save forms as HTML.

Related Sections

Creating the User Interface

Discusses how creating forms, classes, controls, and toolbars can provide a rich set of tools for your user interface.
Using Controls

Controls manage the interactions between users and your application. Microsoft® Visual FoxPro® offers a variety of controls to enhance your application interface.
Designing Menus and Toolbars

A good menu system tells your users a lot about the design and structure of your application. Planning menus and toolbars carefully can improve the usability of your application and provide immediate access to common tasks.


Creating Forms

Visual FoxPro 9.0
Creating Forms

You can use forms to give your users a familiar interface for viewing and entering data into a database, but forms provide far more than just an interface. Forms provide a rich set of objects that can respond to user (or system) events, so you can make it possible for your users to accomplish their information management tasks as easily and as intuitively as possible.

In This Section

Designing Forms

Provides background on the capabilities of the Form designer, with links to topics on creating forms, setting the data environment, and manipulating objects.
Creation of Single- and Multiple-Document Interfaces

Describes the two types of applications possible in Visual FoxPro and the types of forms that support both types of interfaces. Includes links to topics dealing with the various form types.
How to: Extend Forms with Form Sets

Explains the benefits of including multiple forms as a group in a form set and describes how to create and work with form sets.
Adding Objects to Forms

Lists the types of objects you can add to a form and offers background on the two categories of objects in Visual FoxPro: containers and controls. Provides links to topics on adding containers and controls to forms.
Customizing Forms

Provides instructions on how to change text fonts and sizes, add shapes and lines to a form, add graphics to a form, and set the foreground and background colors of a form.
How to: Add Properties and Methods to a Form

Includes instructions on how to add a new property to a form, create an array property, create a new method for a form, and include a file in a form. Provides links to topics on manipulating objects, defining form behavior, and editing event and method code.

Related Sections

Creating the User Interface

Using Visual FoxPro forms, classes, controls, menus, and toolbars, you can build interfaces that help users gain access to the full potential of your programs.
Working with Forms

After creating your form, you can run, hide, or alter it in different ways.
Using Controls

Controls manage the interactions between users and your application. Visual FoxPro offers a variety of controls to enhance your application interface.
Designing Menus and Toolbars

A good menu system tells your users a lot about the design and structure of your application. Planning menus and toolbars carefully can improve the usability of your application and provide immediate access to common tasks.


Designing Forms

Visual FoxPro 9.0
Designing Forms

Visual FoxPro provides you with a powerful Form Designer to make form design fast and easy. You can have:

  • Various types of objects on the forms.

  • Data bound to objects on the form.

  • Top-level or child forms.

  • Multiple forms that can be manipulated together.

  • Forms based on your own custom templates.

Forms and form sets are objects with their own properties, events, and methods that you can set in the Form Designer. A form set consists of one or more forms that can be manipulated as a unit. If you have four forms in your form set, for example, you can display or hide them as a unit with a single command at run time.

In This Section

How to: Create a New Form

Describes the three ways to create forms in Visual FoxPro. Additionally, it explains ways to modify a form once it has been created.
How to: Set the Data Environment

Explains how to set the data environment for a form and how to perform common tasks such as adding a table or view or setting an index using the Data Environment designer.

Reference

Form Designer

Describes the Visual FoxPro Form designer.

Related Sections

Creating Forms

Describes creating forms.
Creation of Single- and Multiple-Document Interfaces

Describes the two types of applications possible in Visual FoxPro and the types of forms that support both types of interfaces. Includes links to topics dealing with the various form types.
Manipulating Objects

Provides links on how to manipulate objects in the Form designer.
How to: Specify a Form Type

Describes how to specify the a form to one of the three form types: child form, floating form, or top-level form.


How to: Create a New Form

Visual FoxPro 9.0
How to: Create a New Form
See Also

Forms display the fields and records in your tables and views, and usually include navigation controls to help you move from record to record.

You can create forms in Visual FoxPro in any of these ways:

  • Use form wizards to create ready-to-use forms.

  • Choose Quick Form on the Form menu to create a simple form that you can customize by adding your own controls.

  • Use the Form Designer to modify existing forms or create your own forms.

Using a Form Wizard

Whenever you want to create a new form, you can use a form wizard to help you set it up. The wizard will ask you a series of questions and build a form for you based on your answers. You can choose from several different style options and preview your form before creating it.

To create a new form with a wizard

  1. In the Project Manager Window, select the Documents tab and select Forms.

  2. Choose New.

  3. Choose Form Wizard.

  4. Select the type of form you want to create.

  5. Follow the instructions on the wizard screens.

You can also access the form wizards from the menu by choosing the Wizards command from the Tools menu, and selecting Form.

Visual FoxPro provides two different form wizards to help you create forms:

  • To create a basic form based on one table, choose the Form Wizard.

  • To create a form that incorporates data from two tables linked in a one-to-many relationship, choose the One-to-Many Form Wizard.

Forms you create with the form wizards have a standard set of navigation buttons so you can display different records in the form, edit records, search for records, and so on. If you create a form within a database, the Form wizard can use input mask and format settings stored in the database.

Starting the Form Designer

If you want to create your own form without using a wizard, use the Form Designer. With the Form Designer, you can add fields and controls to your form, and customize it by adjusting and aligning the controls.

The Quick Form command makes it easier to get started creating a form. The Quick Form command displays the Form Builder, which adds selected fields from tables or views to your form.

To create a new form

  1. In the Project Manager Window, choose the Documents tab.

  2. Select the Forms icon.

  3. Choose New.

  4. Select New Form. The Form Designer window appears so you can begin creating your form.

    - OR -

    From the File menu, choose New, select Form, and choose New File.

    - OR -

    Use the CREATE FORM Command.

Modifying a Form

If the wizard- or builder-generated forms don't quite fit your needs, you can modify them with the Form Designer. Using the Form Designer, it's easy to move and resize controls, copy or delete controls, align controls, and modify the tab order.

To modify a generated form

  1. In the Project Manager, select the Documents tab.

  2. Choose the Forms icon and select the name of the form.

  3. Choose Modify.

Adding Fields Quickly

When you want to quickly place the fields from a table or view into a form, choose Quick Form on the Form menu. Quick Form starts the Form Builder, which adds selected fields from a table or view to your form, using the field style you choose. The Form Builder creates a form without navigation controls, so you can add your own. You can use a control builder to add navigation controls to your form, or choose from the predefined library of navigation controls provided with Visual FoxPro.

To add fields to a form

  1. In the Project Manager, open the form.

  2. In the Form Designer, go to the Form menu and choose Quick Form. The Form Builder appears.

  3. In the Style tab, select the style you want for the new control.

  4. In the Field Selection tab, select the source of the fields, and the fields you want to add.

  5. Choose OK to generate the form.

    - OR -

  6. In the Form Controls toolbar, choose a data control and drag in the Form Designer window to create the control.

  7. In the Properties window, choose the Data tab and select the ControlSource property.

  8. Enter a field name.

    - OR -

    Select a field from the list of available fields.

See Also

Other Resources

How to: Set the Data Environment
Creating Forms
Creation of Single- and Multiple-Document Interfaces
Designing Forms
How to: Add Visual FoxPro Controls to a Form


How to: Set the Data Environment

Visual FoxPro 9.0
How to: Set the Data Environment
See Also

Each form or set of forms includes a data environment. The data environment is an object that includes the tables or views that the form interacts with and the relationships between tables that the form expects. You can use the data environment to automate opening and closing tables and views when the form is run. In addition, you can use the data environment to set the ControlSource property for controls by populating the ControlSource property in the Properties window with all the fields in your data environment.

Adding Tables to the Data Environment

You can visually design the data environment and save it with the form. When you add tables or views to the Data Environment designer, you can see the fields and indexes that belong to the table or view.

To add tables to the data environment

  1. Open the form in the Form Designer.

  2. On the View menu, click Data Environment.

    The Data Environment designer opens for the form's data environment.

  3. On the DataEnvironment menu, click Add.

  4. In the Add Table or View dialog box, click the database you want in the Database list.

  5. In the Select area, click Tables or Views.

  6. In the Tables in database list, click the table or view you want to add to the data environment.

  7. Click Add.

    Tip:
    If no database or project is open, click Other to browse for and select a table.

You can also drag a table or view from an open project or the Database Designer to the Data Environment designer.

The following list includes commonly set data environment properties:

  • AutoCloseTables Property

  • AutoOpenTables Property

  • InitialSelectedAlias Property

Setting Indexes for the Data Environment

You can set the order your records appear in your report by setting an index for the data environment.

To set an index for the Data Environment Designer

  1. From the View menu, choose Data Environment.

  2. From the shortcut menu, choose Properties.

  3. In the Properties Window, choose Cursor1 in the Object box.

  4. Choose the Data tab and select the Order property.

  5. Enter an index name.

    - OR -

    Select an index from the list of available indexes.

When the Data Environment Designer is active, the Properties window displays objects and properties associated with the data environment. Each table or view in the data environment, each relationship between tables, and the data environment itself is a separate object in the Object box of the Properties window.

Removing Tables from the Data Environment Designer

When you remove a table from the data environment, any relationships that the table is involved in are also removed.

To remove a table or view from the Data Environment Designer

  1. In the Data Environment Designer, select the table or view.

  2. From the DataEnvironment menu, choose Remove.

Setting Relationships in the Data Environment

If you add tables to the Data Environment Designer that have persistent relationships set in a database, the relationships are automatically added in the data environment. If the tables don't have persistent relationships, you can still relate them in the Data Environment Designer.

To set relationships in the Data Environment Designer

  • Drag a field from the primary table onto the matching index tag in the related table.

You can also drag a field from the primary table to a field in the related table. If there is no index tag in the related table corresponding to the field in the primary table, you're prompted to create the index tag.

Editing Relationships in the Data Environment

When you set a relation in the Data Environment Designer, a line between the tables indicates the relationship.

To edit the properties of the relationship

  • In the Properties window, select the relationship from the Object box.

The properties of the relationship correspond to clauses and keywords in the SET RELATION and SET SKIP commands.

The RelationalExpr property is set by default to the name of the primary key field in the primary table. If the related table is indexed on an expression, you need to set the RelationalExpr property to this expression. For example, if the related table is indexed on UPPER(cust_id), you need to set RelationalExpr to UPPER(cust_id).

If the relation is not a one-to-many relationship, set the OneToMany property to false (.F.). This corresponds to using the SET RELATION command without issuing SET SKIP.

Setting the OneToMany property of a relation to true (.T.) corresponds to issuing the SET SKIP command. When you skip through the parent table, the record pointer remains on the same parent record until the record pointer moves through all related records in the child table.

Note:
If you want a one-to-many relationship in the form, set the OneToMany property to true (.T.), even if a persistent one-to-many relationship has been established in a database.

See Also

Other Resources

Manipulating Objects
How to: Create a New Form
Creation of Single- and Multiple-Document Interfaces
Creating Forms
How to: Specify a Form Type
How to: Display a Child Form Inside a Top-Level Form
Add Table or View Dialog Box
Properties Window
Designing Forms


Creation of Single- and Multiple-Document Interfaces

Visual FoxPro 9.0
Creation of Single- and Multiple-Document Interfaces
See Also

Visual FoxPro allows to you to create two types of applications:

  • Multiple-document interface (MDI) applications consist of a single main window, and the application's windows are contained within or float on top of the main window. Visual FoxPro is primarily an MDI application, with the command window, edit windows, and designer windows contained within the main Visual FoxPro window.

  • Single-document interface (SDI) applications consist of one or more independent windows, each of which appears separately on the Windows desktop. Microsoft Exchange is an example of an SDI application, in which each message you open appears in its own independent window.

An application consisting of single window is usually an SDI application, but some applications mix SDI and MDI elements. For example, Visual FoxPro displays its debugger as an SDI application, which in turn contains MDI windows of its own.

To support both types of interfaces, Visual FoxPro allows you to create several types of forms:

  • Child form. A form contained within another window, used in creating MDI applications. Child forms cannot be moved outside the bounds of their parent form (the main form), and when minimized appear at the bottom of their parent form. If their parent form is minimized, they are minimized along with it.

  • Floating form. A form that belongs to a parent (main) form, but is not contained within it. Instead, floating forms can be moved anywhere on the screen. They cannot be moved behind their parent window. If minimized, a floating form appears at the bottom of the desktop. If their parent form is minimized, floating forms are minimized along with it. Floating forms are also used in creating MDI applications.

  • Top-level form. An independent form without parent form, used to create an SDI application, or to serve as the parent for other child forms in an MDI application. Top-level forms work at the same level as other Windows applications, and can appear in front of or behind them. They appear on the Windows taskbar.

See Also

Other Resources

How to: Set the Data Environment
Creating Forms
How to: Specify a Form Type
How to: Display a Child Form Inside a Top-Level Form
How to: Add a Menu to a Top-Level Form
How to: Hide the Main Visual FoxPro Window


How to: Specify a Form Type

Visual FoxPro 9.0
How to: Specify a Form Type
See Also

You create all types of forms in much the same way, but you set specific properties to indicate how the form should behave.

If you're creating a child form, you specify not only that it should appear inside another form, but also whether it is an MDI-compliant child form, which indicates how the form behaves when maximized. If the child form is MDI-compliant, it combines with the parent form, sharing the parent form's title bar and caption, menus, and toolbars. A child form that is not MDI-compliant maximizes into the full client area of the parent, but retains its own caption and title bar.

To specify a child form

  1. Create or edit the form using the Form Designer.

  2. Set the form's ShowWindow property to one of the following values:

    • 0 — In Screen. The child form's parent will be the main Visual FoxPro window.

    • 1 — In Top-Level Form. The child form's parent will be the top-level form that is active when the child window is displayed. Use this setting if you want the child window to appear inside any top-level window other than the main Visual FoxPro window.

  3. Set the form's MDIForm property to .T. (true) if you want the child form to be combined with the parent when maximized, or to .F. (false) if the child window should be retained as a separate window when maximized.

A floating form is a variation of a child form.

To specify a floating form

  1. Create or edit the form using the Form Designer.

  2. Set the form's ShowWindow property to one of the following values:

    • 0 — In Screen. The floating form's parent will be the main Visual FoxPro window.

    • 1 — In Top-Level Form. The floating form's parent will be the top-level form that is active when the floating window is displayed.

  3. Set the form's Desktop property to .T. (true).

To specify a top-level form

  1. Create or edit the form using the Form Designer.

  2. Set the form's ShowWindow property to 2 — As Top-Level Form.

See Also

Other Resources

Creation of Single- and Multiple-Document Interfaces
How to: Display a Child Form Inside a Top-Level Form
Creating Forms
How to: Hide the Main Visual FoxPro Window
How to: Add a Menu to a Top-Level Form


How to: Display a Child Form Inside a Top-Level Form

Visual FoxPro 9.0
How to: Display a Child Form Inside a Top-Level Form
See Also

If you've created a child form in which the ShowWindow Property is set to 1 — In Top-Level Form, you don't directly specify the top-level form that acts as the child form's parent. Instead, Visual FoxPro assigns the child form to a parent at the time the child window is displayed.

To display a child form inside a top-level form

  1. Create a top-level form.

  2. In the event code of the top-level form, include the DO FORM Command, specifying the name of the child form to display.

    For example, create a button in the top-level form, and then in the Click Event code for the button, include a command such as this one:

    Copy Code
    DO FORM MyChild
    Note:
    The top-level form must be visible and active when the child form is displayed. Therefore, you cannot use the Init Event of the top-level form to display a child form, because the top-level form will not yet be active.

  3. Activate the top-level form, and then if necessary, trigger the event that displays the child form.

See Also

Other Resources

Creation of Single- and Multiple-Document Interfaces
How to: Specify a Form Type
How to: Hide the Main Visual FoxPro Window
Creating Forms
How to: Add a Menu to a Top-Level Form
How to: Extend Forms with Form Sets


How to: Hide the Main Visual FoxPro Window

Visual FoxPro 9.0
How to: Hide the Main Visual FoxPro Window
See Also

If you're running a top-level form, you might not want the main Visual FoxPro window to be visible. You can use the Visible property of the Application object to hide and show the main Visual FoxPro window as needed.

To hide the main Visual FoxPro window

  1. In the Init Event of the form, include the following line of code:

    Copy Code
    Application.Visible = .F.

  2. In the Destroy Event of the form, include the following line of code:

    Copy Code
    Application.Visible = .T.

Make sure that you also provide a way to close the form by using THISFORM.Release in some method or event.

Note:
You can also include the following line in a configuration file to hide the main Visual FoxPro window: SCREEN = OFF

See Also

Other Resources

Creation of Single- and Multiple-Document Interfaces
Customizing the Visual FoxPro Environment
How to: Display a Child Form Inside a Top-Level Form
How to: Add a Menu to a Top-Level Form
Creating Forms
How to: Extend Forms with Form Sets
Adding Objects to Forms


How to: Add a Menu to a Top-Level Form

Visual FoxPro 9.0
How to: Add a Menu to a Top-Level Form
See Also

Menus on top-level forms not only provide form navigation, they can provide initial clues about the design of your application.

To add a menu to a top-level form

  1. Create a top-level form menu. For more information about creating menus for top-level forms, see Designing Menus and Toolbars.

  2. Set the form's ShowWindow Property to 2 – As Top-Level Form.

  3. In the Init Event of the form, run the menu program and pass it two parameters:

    DO menuname.mpr WITH oForm, lAutoRename

    oForm is an object reference to the form. In the Init event of the form, pass THIS as the first parameter.

    lAutoRename specifies whether or not a new unique name is generated for the menu. If you plan to run multiple instances of the form, pass .T. for lAutoRename.

    For example, you can call a menu called mySDImenu with this code:

    Copy Code
    DO mySDImenu.mpr WITH THIS, .T.

See Also

Other Resources

Creation of Single- and Multiple-Document Interfaces
How to: Hide the Main Visual FoxPro Window
How to: Extend Forms with Form Sets
Creating Forms
Adding Objects to Forms
How to: Add Visual FoxPro Containers


How to: Extend Forms with Form Sets

Visual FoxPro 9.0
How to: Extend Forms with Form Sets
See Also

You can manipulate multiple forms as a group by including them in a form set. A form set has these benefits:

  • You can show or hide all the forms in a form set at one time.

  • You can visually arrange multiple forms at once to control their relative positions.

  • Because all the forms in a form set are defined in a single .scx file with a single data environment, you can automatically synchronize record pointers in multiple forms. If you change the record pointer in a parent table in one form, the child records in another form are updated and displayed.

    Note:
    All the forms and all the objects on the forms are loaded when you run the form set. Loading many forms with a number of controls might take several seconds.

Creating a New Form Set

A form set is a parent container for one or more forms. When you are in the Form Designer, you can create a form set.

To create a form set

  • From the Form menu, choose Create Formset.

If you don't want to work with multiple forms as a group of forms, you don't need to create a form set. Once you've created a form set, you can add forms to it.

Adding and Removing Forms

Once you've created a form set, you can add new forms and remove forms.

To add additional forms to a form set

  • From the Form menu, choose Add New Form.

To remove a form from a form set

  1. In the Form box at the bottom of the Form Designer, select the form.

  2. From the Form menu, choose Remove Form.

If you have a single form in a form set, you can remove the form set so that you have only the form.

To remove a form set

  • From the Form menu, choose Remove Formset.

Forms are saved in table format to a file with an .scx extension. When you create a form, the .scx table contains a record for the form, a record for the data environment, and two records for internal use. A record is added for each object you add to the form or to the data environment. If you create a form set, an additional record is added for the form set and for each new form. The parent container of each form is the form set. The parent container of each control is the form that it is placed on.

Tip:
When you run a form set, you may not want all forms in the form set initially visible. Set the Visible property to false (.F.) for forms you don't want displayed when the form set runs. Set the Visible property to true (.T.) when you want the forms displayed.

See Also

Other Resources

How to: Add a Menu to a Top-Level Form
Adding Objects to Forms
Creating Forms
How to: Add Visual FoxPro Containers
Form Designer


Adding Objects to Forms

Visual FoxPro 9.0
Adding Objects to Forms

To design the functionality you want in a form, you add the appropriate controls, set form and control properties, and write event code.

In This Section

Understanding Container and Control Objects

Introduces containers and controls in Visual FoxPro.
How to: Add Visual FoxPro Containers

Explains how to add the various base container classes to a form.
How to: Add Visual FoxPro Controls to a Form

Describes various methods to add controls to a Visual FoxPro form.
How to: Add Controls to a Form with the Component Gallery

Explains how to quickly add custom controls and objects to a form using the Component Gallery.
How to: Add Controls to a Wizard-Generated Form

Explains how to add controls from the wizard control gallery to a form so that they match the style of controls on a form created by one of the form wizards.
How to: Select, Move, and Resize Form Controls

Describes how to select a control to adjust its placement or size.
How to: Copy and Delete Form Controls

Describes how to make a copy of a control already on a form and how to delete existing controls.
Aligning Controls in Forms

Discusses ways to align controls on a form.
How to: Set Tab Order for Controls

Describes how to set the tab order for controls on a form interactively or by list.
How to: Add User-Defined Objects to a Form

Explains how to add user-defined custom classes to a form.

Related Sections

How to: Extend Forms with Form Sets

Explains how to manipulate multiple forms as a group by including them in a form set.
Creating Forms

Provides links that describe how to create forms.


Understanding Container and Control Objects

Visual FoxPro 9.0
Understanding Container and Control Objects
See Also

You can add the following types of objects to a form:

  • Controls

  • Containers

  • User-defined classes

  • Sharing Information and Adding OLE

Objects in Visual FoxPro belong in one of two categories, depending on the nature of the class they are based on:

  • Containers can hold other containers or controls. They can act as the parent object for other objects. For example, a form, as a container, is the parent object of a check box on that form.

  • Controls can be placed in containers, but cannot be the parent for other objects. For example, a check box cannot contain any other object.

The Form Designer allows you to design both containers and controls.

Container | Can contain
Column | Headers, and any objects except form sets, forms, toolbars, timers, and other columns
Command button group | Command buttons
Form set | Forms, toolbars
Form | Page frames, grids, any controls
Grid | Columns
Option button group | Option buttons
Page frame | Pages
Page | Grids, any controls

Collection and Count Properties

All container objects in Visual FoxPro have a count property and a collection property associated with them. The collection property is an array referencing each contained object. The count property is a numeric property indicating the number of contained objects.

The collection and count properties for each container are named according to the type of object that can be contained in the container. The following table lists the containers and the corresponding collection and count properties.

Container | Collection Property | Count Property
Application | Objects Forms | Count FormCount
FormSet | Forms | FormCount
Form | Objects Controls | Count ControlCount
PageFrame | Pages | PageCount
Page | Controls | ControlCount
Grid | Columns | ColumnCount
CommandGroup | Buttons | ButtonCount
OptionGroup | Buttons | ButtonCount
Column | Controls | ControlCount
ToolBar | Controls | ControlCount
Container | Controls | ControlCount
Control | Controls | ControlCount

These properties allow you to use a loop to programmatically manipulate all or specific contained objects. For example, the following lines of code set the BackColor property of columns in a grid to alternating green and red:

Copy Code
o = THISFORM.grd1
FOR i = 1 to o.ColumnCount
   IF i % 2 = 0 && Even-numbered column
      o.Columns(i).BackColor = RGB(0,255,0) && Green
   ELSE
      o.Columns(i).BackColor = RGB(255,0,0) && Red
   ENDIF
ENDFOR

See Also

Other Resources

How to: Add Visual FoxPro Containers
How to: Add Visual FoxPro Controls to a Form
Adding Objects to Forms


How to: Add Visual FoxPro Containers

Visual FoxPro 9.0
How to: Add Visual FoxPro Containers
See Also

In addition to form sets and forms, Visual FoxPro provides four base container classes:

  • CommandGroup Control

  • Grid Control

  • OptionGroup Control

  • PageFrame Control

To add container objects to a form

  • In the Form Controls toolbar, select the desired container object (button group, grid, option button group, or page frame) button and drag it to size in the form.

When you add a command button group or an option button group to a form in the Form Designer, the group contains two buttons by default. When you add a page frame to a form, the page frame contains two pages by default. You can add more buttons or pages by setting the ButtonCount Property or the PageCount Property to the number you want.

When you add a grid to a form, the ColumnCount property is set to – 1 by default, which indicates AutoFill. At run time, the grid will display as many columns as there are fields in the RowSource table. If you don't want AutoFill, you can specify the number of columns by setting the grid's ColumnCount property.

For more information about these container objects, see Understanding Container and Control Objects and Using Controls.

See Also

Other Resources

Adding Objects to Forms
How to: Add Visual FoxPro Controls to a Form
Creating Forms
How to: Add User-Defined Objects to a Form
How to: Extend Forms with Form Sets
How to: Add Controls to a Form with the Component Gallery
How to: Add Controls to a Wizard-Generated Form
How to: Select, Move, and Resize Form Controls
Aligning Controls in Forms
How to: Set Tab Order for Controls


How to: Add Visual FoxPro Controls to a Form

Visual FoxPro 9.0
How to: Add Visual FoxPro Controls to a Form
See Also

You can add any of the standard Visual FoxPro controls to your form. For example, you can add labels for fields on the form, add controls such as buttons, edit boxes, or list boxes, or add pictures or lines and shapes to enhance the appearance of your form.

To add a control to a form

  1. Open the form in the Form Designer.

  2. On the Form Controls toolbar, click the control you want to add.

  3. In the Form Designer, click the form at the location you want to place the control at its default size.

    The new control appears where you placed it. You can then move it to its final location on the form, and resize it as needed.

You can also click and drag the cursor to draw the control with the dimensions that you want. For more information, see Form Designer.

You can now set properties for the control by clicking Properties on the View menu to open the Properties window. The Properties window displays all the properties for the controls you add to a form. For more information, see Properties Window (Visual FoxPro).

You can add multiple controls of the same type without choosing the control each time you want to add a control.

To add multiple controls to a form

  1. Open the form in the Form Designer.

  2. On the Form Controls toolbar, click the control you want to add.

  3. On the Form Controls toolbar, click Button Lock.

    Tip:
    You can also double-click the control you want to add.

You can now add multiple controls of the same type without clicking the control on the Form Controls toolbar multiple times..

Adding Controls with a Builder

Just as you can use wizards can be used to create forms quickly, you can use a builder to add certain controls to a form. The builder sets the appropriate properties on the control using your answers to a series of questions.

To add a control with a builder

  1. Open the form in the Form Designer.

  2. On the Form Controls toolbar, click Builder Lock.

  3. Add the control you want to the form.

    If available, a builder opens for the control.

  4. Follow the instructions on the builder tabs.

    Note:
    To set control properties in the Properties window, turn off the Builder Lock.

For more information choosing controls, see Using Controls. For details on valid image control sources, see Graphics Support in Visual FoxPro.

Adding Data-Bound Controls to a Form

You can bind controls to data in a table, view, table field, or view field.

To bind a control to data in a table, view, or table or view field

  • Set the ControlSource property for a control to a field or the RecordSource property of a grid to a table or view.

For more information, see ControlSource Property or RecordSource Property.

You can also create data-bound controls by dragging fields or tables to the form from the following locations:

  • Project Manager

  • Database Designer

  • Data Environment Designer

The type of the control created by dragging a field or table depends on the Field Mappings settings in the Properties tab of the Table Designer or the Field Mapping tab of the Options dialog box.

Tip:
You can make it easier to bind new controls to fields in tables or views by placing the tables or views associated with your form in the form's data environment. The ControlSource property in the Properties window displays a list of the fields available in the Data Environment designer so you can select the one you want to bind to a control.

See Also

Other Resources

Creating Forms
Adding Objects to Forms
How to: Add Controls to a Form with the Component Gallery
How to: Add Controls to a Wizard-Generated Form
How to: Add User-Defined Objects to a Form
How to: Select, Move, and Resize Form Controls
Aligning Controls in Forms
How to: Set Tab Order for Controls


How to: Add Controls to a Form with the Component Gallery

Visual FoxPro 9.0
How to: Add Controls to a Form with the Component Gallery
See Also

You can use the Component Gallery to quickly add custom controls and objects to a form. The Component Gallery contains dozens of custom controls and objects that greatly reduce the amount of coding required to create specialized forms.

To open the Component Gallery

  • From the Tools menu, choose Component Gallery.

When the Component Gallery is open, you can drag custom controls and objects from the Component Gallery and drop them on a form.

See Also

Other Resources

Using the Component Gallery
How to: Add Visual FoxPro Containers
How to: Add User-Defined Objects to a Form
Creating Forms
Adding Objects to Forms
How to: Add Properties and Methods to a Form
Table Designer
Field Mapping
How to: Add Visual FoxPro Controls to a Form
How to: Add Controls to a Wizard-Generated Form
How to: Select, Move, and Resize Form Controls
Aligning Controls in Forms
How to: Set Tab Order for Controls


How to: Add Controls to a Wizard-Generated Form

Visual FoxPro 9.0
How to: Add Controls to a Wizard-Generated Form
See Also

If you create a form with one of the form wizards and then want to add controls to it, you can match the style of the existing controls by using the controls in the wizard controls library, Wizstyle.vcx.

When you open the wizards control library, wizard-style controls (such as chiselfield, embossedmemo, and so on) are available in the Form Controls toolbar. To find out which control to use, select an existing control and note its class and class library. For example, a standard wizard field would be in the Standardfield class, found in Wizstyle.vcx.

Tip:
Use ToolTips on the Form Controls toolbar to help you identify class names.

To match controls in a wizard-generated form

  1. In the Form Designer, open the form.

  2. From the Form Controls toolbar, choose the View Classes button and choose Add.

  3. In the Open dialog box, locate Wizstyle.vcx in the Wizards subdirectory and choose OK.

  4. In the Form Controls toolbar, select the control that corresponds to an existing control in the form and drag in the form to add it.

    Note:
    If you move a form to a new directory or another system, you should move the control library associated with the form along with it.

See Also

Other Resources

Adding Objects to Forms
How to: Add Controls to a Form with the Component Gallery
How to: Create a New Form
How to: Create Forms with Local and Remote Data
How to: Add Visual FoxPro Controls to a Form
Creating Forms
How to: Add User-Defined Objects to a Form
How to: Select, Move, and Resize Form Controls
Aligning Controls in Forms
How to: Set Tab Order for Controls


How to: Select, Move, and Resize Form Controls

Visual FoxPro 9.0
How to: Select, Move, and Resize Form Controls
See Also

After creating a form, you may need to adjust the placement or size of the controls on the form. For example, you might want to move a memo field, or make a text box longer.

To select a control

  • Using the pointer, click anywhere on the control.

To select adjacent controls

  1. Choose the select arrow in the Form Controls toolbar.

  2. By dragging the pointer, draw a box around the controls you want to select.

To move a control

  1. Select the control by clicking it.

  2. Drag the control to the new position in the form window.

    -or-

    Select the control and use the arrow keys to reposition it.

To resize a control

  1. Select the control.

  2. Drag one of the sizing handles to increase the length, width, or overall size of the control.

See Also

Other Resources

Adding Objects to Forms
How to: Add Controls to a Form with the Component Gallery
How to: Create Controls by Dragging and Dropping Fields or Tables
How to: Create a New Form
How to: Create Forms with Local and Remote Data
How to: Add Visual FoxPro Controls to a Form
Creating Forms
How to: Add Controls to a Wizard-Generated Form
How to: Add User-Defined Objects to a Form
Aligning Controls in Forms
How to: Set Tab Order for Controls


How to: Copy and Delete Form Controls

Visual FoxPro 9.0
How to: Copy and Delete Form Controls
See Also

When designing or modifying a form, you may want to make a copy of a control that is already on the form. You can copy an existing control and paste the copy onto your form.

To copy a control

  1. Using the pointer, select a control.

  2. From the Edit menu, choose Copy.

  3. From the Edit menu, choose Paste.

  4. Use the pointer to reposition the control as needed.

If you create a control and then decide you don't need it, or don't want a control created by a wizard, you can remove the control.

To delete a control

  • Select the control and choose Cut from the Edit menu.

See Also

Other Resources

Adding Objects to Forms
How to: Add Controls to a Form with the Component Gallery
How to: Create Controls by Dragging and Dropping Fields or Tables
How to: Create a New Form
How to: Create Forms with Local and Remote Data
How to: Add Visual FoxPro Controls to a Form
Creating Forms
How to: Add Controls to a Wizard-Generated Form
How to: Add User-Defined Objects to a Form
How to: Select, Move, and Resize Form Controls
Aligning Controls in Forms
How to: Set Tab Order for Controls


Aligning Controls in Forms

Visual FoxPro 9.0
Aligning Controls in Forms
See Also

The buttons on the Layout toolbar make it easy to accurately line up controls in relation to each other in your forms. For example, you might want to align controls horizontally or vertically or make sure that a related set of controls has the same width or height. To align controls, select a group of controls, and then choose one of the layout buttons on the Layout toolbar.

Adjusting Control Placement

If you need to place controls precisely on the screen, you can use Show Position on the View menu. When checked, Show Position displays the coordinates and dimensions of a selected control in the status bar at the bottom of the Form Designer window.

Controlling the Grid Display

The grid display helps you align controls on your forms. You can adjust the size of the grid with Set Grid Scale on the Format menu. You can turn display of the grid on and off by using the Grid Lines command on the View menu, or setting the Grid Lines option on the Forms tab of the Options dialog box.

You can also adjust the size or position of controls in relation to the grid with Snap to Grid on the Format menu. When Snap to Grid is checked on the Form menu, controls placed on a Form are automatically aligned to the guidelines on the grid. You can override the grid by:

  • Clearing Snap to Grid on the Format menu. By default, this option is checked.

  • Using the arrow keys to align controls.

  • Pressing CTRL before clicking on a control and holding the CTRL key down while dragging the object to another position.

  • Choosing alignment options from the Layout toolbar or the Format menu.

See Also

Reference

Aligning Controls in Forms

Other Resources

How to: Add Visual FoxPro Containers
How to: Add User-Defined Objects to a Form
Creating Forms
Adding Objects to Forms
How to: Add Properties and Methods to a Form
How to: Add Visual FoxPro Controls to a Form
How to: Add Controls to a Wizard-Generated Form
How to: Add User-Defined Objects to a Form
How to: Select, Move, and Resize Form Controls
How to: Set Tab Order for Controls


How to: Set Tab Order for Controls

Visual FoxPro 9.0
How to: Set Tab Order for Controls
See Also

The tab order of a form determines the sequence in which the controls are selected when a user presses the TAB key to move through the form.

You can choose two different methods for setting tab order: interactively, by clicking the controls in the order you want them to be selected when the form is used; or by arranging a list of controls in a dialog box.

To choose a tab-ordering method

  1. From the Tools menu, choose Options.

  2. In the Options dialog box choose the Forms tab.

  3. Under the Tab Ordering option, select Interactive or By List.

This procedure describes how to choose a tab-ordering method for the Set Tab Order button in the Form Designer Toolbar. You can also choose a tab-ordering method from the Tab Order option in the View menu.

Setting Tab Order Interactively

In interactive mode, you set tab order by double-clicking the control you want to be first in the tab order, and then single-clicking on the rest of the controls in the order in which you want them to be selected in the form. The last control selected is indicated with a highlighted tab order number.

To change the tab order interactively

  1. From the View menu, choose Tab Order.

  2. Choose Assign Interactively.

  3. Double-click the tab order box beside the control you want to be the first control in the tab order.

  4. Click the tab order box for each of the other controls.

  5. Click anywhere on the form to save your changes and exit Tab Order mode, or press ESC to exit Tab Order mode without saving your changes.

Setting Tab Order by List

In list mode, you set tab order by rearranging the control names in the Tab Order dialog box. You can set order by row (down the form) or by column (across the form).

To set the tab order using a list

  1. From the View menu, choose Tab Order.

  2. Choose Assign by List.

  3. Choose By Row or By Column.

  4. In the Tab Order dialog box, use the pointer to rearrange the list.

  5. Choose OK.

See Also

Other Resources

Adding Objects to Forms
Tab Order dialog box
How to: Add Visual FoxPro Containers
How to: Add User-Defined Objects to a Form
Creating Forms
Adding Objects to Forms
How to: Add Properties and Methods to a Form
How to: Add Visual FoxPro Controls to a Form
How to: Add Controls to a Wizard-Generated Form
How to: Select, Move, and Resize Form Controls


How to: Add User-Defined Objects to a Form

Visual FoxPro 9.0
How to: Add User-Defined Objects to a Form
See Also

One of the most powerful features of Visual FoxPro is the ability to create classes that can easily be used and reused in various pieces of your applications. Once you've created classes, you can add them to your forms.

To add an object based on a custom class

  • In the Project Manager Window, drag the class onto the container.

You can also add your classes directly from the Form Controls toolbar when you add them to your toolbar.

Adding Class Libraries to the Controls Toolbar

You need to register your class libraries before they can be displayed in the Form Controls toolbar.

To register a class library

  1. From the Tools menu, choose Options.

  2. In the Options dialog box, choose the Controls tab.

  3. Choose Add.

  4. In the Open dialog box, choose a class library to add to the Selected list and choose Open.

  5. Repeat steps 3 and 4 until you've added all the libraries you want to register.

Classes in the class libraries in the Selected list can be used in the Form Designer as easily as Visual FoxPro base classes can be used.

Tip:
If you want the class libraries to be available from the Form Controls toolbar every time you run Visual FoxPro, choose Set as Default in the Options dialog box.

You can also register libraries directly in the Form Designer.

To register a class library in the Form Designer

  1. In the Form Controls toolbar, choose the View Classes button.

  2. From the submenu, choose Add.

  3. In the Open dialog box, choose a class library to add to the Form Controls toolbar and choose Open.

Adding Objects to a Form from a Class Library

Once you've added class libraries in the Classes tab of the Options dialog box or from the View Classes submenu, you can access them in the Form Designer.

To add a custom object from the Controls toolbar

  1. In the Form Controls toolbar, choose the View Classes button.

  2. From the list of registered class libraries, select the library that contains the control you want to add to the form.

    The toolbar is populated with the controls in the library you selected.

  3. Click the control you want and drag it to size in the form.

    Note:
    You can remove a visual class library from the View Classes toolbar menu by selecting the library in the Selected list in the Controls tab of the Options dialog box, and choosing Remove.

When you add objects to a form based on anything other than the Visual FoxPro base classes, a relative path to the class library (.vcx file) is stored in the form's .scx file. If you move either the form or the class library to a different location, Visual FoxPro displays a dialog box when you try to run the form so that you can manually locate the class library.

To determine how many controls are on a form

  • Use the ControlCount Property.

The Controls property of the form allows you to reference each control on the form. The following program prints the Name property of all the controls on the currently active form.

Copy Code
ACTIVATE SCREEN  && to print to the main Visual FoxPro window
FOR nCnt = 1 TO Application.ActiveForm.ControlCount
   ? Application.ActiveForm.Controls[nCnt].Name
ENDFOR

See Also

Reference

How to: Add User-Defined Objects to a Form

Other Resources

How to: Add Properties and Methods to a Form
Creating Forms
Adding Objects to Forms
Project Manager
How to: Add Controls to a Form with the Component Gallery
How to: Add Controls to a Wizard-Generated Form
How to: Select, Move, and Resize Form Controls
Aligning Controls in Forms
How to: Set Tab Order for Controls


Manipulating Objects

Visual FoxPro 9.0
Manipulating Objects

You can manipulate and work with objects on a form at design time.

The following list describes some of the tasks you can perform with objects on the form:

  • Set the size and position of objects in the Form Designer by expanding, shrinking, or dragging them.

  • Align controls by choosing options on the Format menu or using the alignment tools on the Layout toolbar. For more information about the Layout toolbar, see Aligning Controls in Forms.

  • Set colors using the Palette toolbar. For more information about using the Palette toolbar, see Customizing Forms.

  • View object property settings, display inherited code for objects, events, and methods, set values for properties, and restrict your view to only modified properties using the Properties window.

The Properties window is the primary location for controlling all objects on the form. The Properties window displays the properties, events, and methods and their settings for a selected form, data environment, cursor, relation, or control. For more information about the Properties window, see Properties Window.

In This Section

How to: View Properties for Objects

Discusses how to view an object's properties, methods, and events in the Properties window.
How to: Set Properties for Objects

Describes how to set or edit the value of an object's property at design time or programmatically.
How to: Display Inherited Code for Objects, Events, and Methods

Explains how to display code inherited from parent classes for objects, events, and methods.
How to: Show Properties with Modified Settings

Explains how to display only those properties with modified settings in the Properties window.
Example of Manipulating Objects

Contains an example with two forms in a formSet. The example illustrates how to set properties and call event code from a number of objects inside a formset.

Related Sections

Designing Forms

Provides links to topics that explain how to use the Visual FoxPro designers to create forms.
Adding Objects to Forms

Provides links to topics that explain the various ways to add objects to forms.
Working with Forms

Provides links to topics that explain how to work with forms, such as how to run a form or how to dock forms.


How to: View Properties for Objects

Visual FoxPro 9.0
How to: View Properties for Objects
See Also

You can view properties, methods, and events for certain objects, for example, for a form or an object on a form, by displaying them in the Properties window. For more information, see Properties Window.

To view properties for an object

  1. Select the object that you want to view properties for.

  2. On the Window menu, click Properties Window.

You can also view properties for an object by right-clicking the object and choosing Properties, when available, from the shortcut menu. When the Properties window is open, you can view properties by selecting objects in the object list of the Properties window. The Properties window refreshes to display the properties, events, and methods for the selected object.

Tip:
To view properties that multiple objects have in common, press and hold SHIFT while you select several objects on the form. The properties list shows common properties for the objects you select.

Viewing Truncated Values in the Properties Window

Sometimes values for properties, events, and methods can appear truncated in the properties list if the values extend beyond the right edge of the Properties window. However, you can still view these truncated values.

To view a truncated value in the properties list

  • Expand the Properties window.

-OR-

  • Moving the mouse over the property, event, or method in the properties list to display the value tip.

Value tips show the visual class libraries, if they exist, from which methods and events are inherited and settings for read-only properties.

Viewing Values for Read-Only Properties

You can view the value for a read-only property that appears truncated in the Properties window without expanding the Properties window.

To view the value for a read-only property

  1. In the Properties window, right-click the property you want to view.

  2. On the shortcut menu, select Zoom.

For more information, see Zoom <property> Dialog Box.

See Also

Other Resources

Manipulating Objects
How to: Add Properties and Methods to a Form
Controlling Form Behavior
Creating Forms
How to: Edit Event and Method Code
Form Designer


How to: Set Properties for Objects

Visual FoxPro 9.0
How to: Set Properties for Objects
See Also

You can set or change properties at design time or programmatically.

Note:
Some properties are evaluated at design time, so any memory variables or arrays used in expressions for these properties must be in scope at design time. Properties that are read-only at design time, such as the Class property of an object, are displayed in italics in the properties list of the Properties window.

To set or edit the value for a property

  1. Click an object on the form.

  2. From the properties list in the Properties window, select a property.

  3. In the property settings box, type or choose the desired setting for the selected property.

You can also select an object from the object box in the Properties window.

If the property requires a character value, you do not have to include the value in quotation marks. For example, if you want the caption of a form to display as Customer, type Customer in the property settings box. However, if you want the caption to display as "Customer" with quotation marks (""), type "Customer" in the property settings box.

Setting Properties to Expressions

You can set certain properties to the results of expressions or functions in the Properties window. Visual FoxPro evaluates the expression for a property when you enter it in the Properties window and when the object is initialized at design or run time. Once the object is created, the property setting does not change until you or the user explicitly changes it.

Caution:
If you set a property to the result of a user-defined function, Visual FoxPro evaluates the function when you set the property, or when you modify or run the form. If an error exists in the user-defined function, you might not be able to open your form.

To set a property to an expression

  1. From the properties list, select the property for which you want to enter an expression.

  2. In the property settings box, type an equal sign (=) followed by the expression.

For example, you can indicate the currently active table when the form runs by selecting the Caption property of the form and typing =ALIAS( ) in the property settings box.

You can also specify expressions for properties by using the Expression Builder. To open the Expression Builder, select the desired property and click the Function button in the Properties window.

You can also set the property to the user-defined function in the Init event of the object as in the following example:

THIS.Caption = myfunction( )

However, if an error exists in the user-defined function, you will still be unable to run the form, but you can modify it.

See Also

Other Resources

Manipulating Objects
How to: Add Properties and Methods to a Form
Controlling Form Behavior
Creating Forms
How to: Edit Event and Method Code
Form Designer


How to: Display Inherited Code for Objects, Events, and Methods

Visual FoxPro 9.0
How to: Display Inherited Code for Objects, Events, and Methods
See Also

You can view code inherited from parent classes if it exists for objects, events, and methods, making it easier to decide whether you want to use or override the inherited code.

Note:
The View Parent and View Inherited Code features support only the viewing of parent code, not editing. To edit parent class code for a subclass, use the Class Browser. For more information, see How to: View Class Definition Code and Operating the Class Browser.

To view inherited code using the code window

  1. Perform one of the following:

    • On the form, double-click the object you want.

    - OR -

    • In the properties list of the Properties window, double-click an event or method.

    A code window opens for the object, event, or method.

  2. In the code window, click View Parent Code to display the list of all parent classes.

    Note:
    View Parent Code is available in the code window only when there is at least one parent class that contains code. When source code exists, parent classes appear in bold.

    Tip:
    You can also click View Parent Code in the code window by pressing ALT+I.

  3. Select the parent class.

    An editing window opens and displays the parent code.

If inherited code exists for a method or event, the parent class name and class libraries from which the method or event inherits code appear in the properties list of the Properties window as follows:

Copy Code
          Inherited
          cClassname
          ClassLibrary

Visual FoxPro displays only those parent classes for the selected control. If a list of parent classes is available, the parent classes appear in order from the most immediate or top parent class to the one closest to the base class, traversing the parent tree. The base class does not appear.

If code inherited from the immediate parent class exists, and the parent class is a member of a container class, Visual FoxPro displays the container class followed by a separator and then the classes in the parent tree. Other classes that traverse the container hierarchy might contain code but are not displayed in the list.

Viewing inherited code using the properties list in the Properties window traverses the parent or container tree to reach the inherited parent class.

See Also

Other Resources

Manipulating Objects
How to: Add Properties and Methods to a Form
Controlling Form Behavior
Creating Forms
How to: Edit Event and Method Code
Form Designer


How to: Show Properties with Modified Settings

Visual FoxPro 9.0
How to: Show Properties with Modified Settings
See Also

In the Properties window, you can choose to list only those properties for which the default settings have been changed.

To view properties with modified settings

  1. Right-click the Properties window outside the properties list.

  2. From the shortcut menu, select Non-Default Properties Only.

The properties list shows only those properties, events, and methods whose settings have been changed.

See Also

Other Resources

Manipulating Objects
How to: Add Properties and Methods to a Form
Controlling Form Behavior
Creating Forms
How to: Edit Event and Method Code
Form Designer


Example of Manipulating Objects

Visual FoxPro 9.0
Example of Manipulating Objects
See Also

The following example sets properties and calls event code from various objects within a form set. The example includes two forms, frmLeft and frmRight, in a formset.

The two check boxes and the command button on frmLeft have event code associated with them. The name of the text box on frmLeft is txtInput.

Event Code for Objects in LeftForm

Object | Event | Code
chkItalic | Click | THISFORM.txtInput.FontItalic = ; THIS.Value
chkBold | Click | THIS.txtInput.FontBold = THIS.Value
cmdClear | Click | THISFORM.txtInput.Value = "" THISFORM.txtInput.FontBold = .F. THISFORM.txtInput.FontItalic = .F. THISFORM.chkItalic.Value = .F. THISFORM.chkBold.Value = .F.

Setting a Property of Another Control on the Same Form

You can set the properties of one control from within the event code of another by using the THISFORM keyword or the Parent property. The following two commands are executed when a user initially clicks on the Italic and the Bold check boxes, setting the appropriate text box properties:

Copy Code
THISFORM.txtInput.FontItalic = .T.
THIS.Parent.txtInput.FontBold = .T.

In this case, THISFORM and THIS.Parent can be used interchangeably.

The code in the click event for cmdClear uses THISFORM to reset the values of the other controls on the form.

Setting Another Form's Properties

You can also set properties of one form from another. Form2 contains five command buttons. The first button on the form has this code in its Click event:

Copy Code
THISFORMSET.frmLeft.Caption = ;
 ALLTRIM(ThisFormSet.frmLeft.txtInput.Value)

Notice that the form set and the form need to be referenced when setting properties from within a different form.

The click event code of the second command button on frmRight demonstrates setting a property of a form from within an object on the form:

Copy Code
THISFORM.Caption = ;
 ALLTRIM(ThisFormSet.frmLeft.txtInput.Value)

If the user chooses this button, the caption of frmRight changes to the value in the text box on frmLeft.

Accessing Objects on Different Forms

The following code in the Click event of the Change Bold Setting command button changes the value of the Bold check box on frmLeft and calls the event code associated with this control.

Copy Code
THISFORMSET.frmLeft.chkBold.Value = ;
   NOT THISFORMSET.frmLeft.chkBold.Value
THISFORMSET.frmLeft.chkBold.InteractiveChange

The last line of the example calls the InteractiveChange event of chkBold. You could also call this procedure with the following command:

Copy Code
THISFORMSET.frmForm1.chkBold.InteractiveChange( )

If this procedure call is omitted, the value of the check box changes, but the FontBold property of the text box is never changed.

Checking Properties and Calling Method Code of Another Form

The following code in the Click event of the Hide Left Form command button hides or shows frmLeft, depending on the value of the Visible property, and changes the button caption as appropriate:

Copy Code
IF ThisFormSet.frmLeft.Visible
   ThisFormSet.frmLeft.Hide
   THIS.Caption = "Show Left Form"
ELSE
   ThisFormSet.frmLeft.Show
   THIS.Caption = "Hide Left Form"
ENDIF

Notice that the THIS keyword is used within event code of a control to reference properties of the control.

The following command in the Click event of the Quit command button releases the form set, causing both forms to close:

Copy Code
RELEASE ThisFormSet

See Also

Other Resources

Working with Forms
Manipulating Objects
How to: Set Properties at Run Time
How to: Hide a Form
Creating Forms
How to: Pass Parameters to a Form
How to: Save a Form as HTML


Customizing Forms

Visual FoxPro 9.0
Customizing Forms

You can add enhancements to your forms to make them more interesting visually and easier to use. For example, you might want to group similar controls together visually by drawing a box around them, or use images to give the forms a more professional appearance.

Using the Form Designer, you can customize your forms by:

  • Changing text fonts and sizes.

  • Adding shapes and lines to a form.

  • Adding graphics to a form.

  • Setting the foreground and background colors of a form.

In This Section

How to: Change Text Properties

Describes how to change the text in a forms.
How to: Add Shapes and Lines to Forms

Describes how to place lines and shapes objects on a form.
How to: Add Graphics to Forms

Explains how to use the Image control to add graphics to a form.
How to: Set Form Colors

Describes how to control a forms color by using the forms ColorSource property.
How to: Assign an Icon to a Form

Describes how to assign an icon to a form.

Related Sections

Working with Forms

Provides links to topics that explain how to work with forms, such as how to run a form or how to doc forms.
Creating Forms

Describes how to design and build forms, how to use form sets and form types, how to use objects on forms, how to customize forms using properties and methods, and how to set the data environment.


How to: Change Text Properties

Visual FoxPro 9.0
How to: Change Text Properties
See Also

Using the font properties in the Properties window, you can modify the style and size of the text that appears in controls you have added to your forms. You can choose from the available font styles and sizes supported by your system. To change the text in your form, change the font properties, such as FontName, FontSize, and FontBold, shown in the Properties window.

To change the text in your forms

  1. In the Form Designer, select the control you want to change.

  2. In the Properties window, drop down the Object list, and select the object you want to change.

  3. Locate the font property you want to change, and set its value.

See Also

Other Resources

Customizing Forms
Form Designer
Properties window
DynamicFontBold, DynamicFontItalic, DynamicFontStrikethru, DynamicFontUnderline Properties
ColorSource property
How to: Set the Design Area for a Form


How to: Add Shapes and Lines to Forms

Visual FoxPro 9.0
How to: Add Shapes and Lines to Forms
See Also

You can add shapes and lines to forms to customize them. For example, you may want to separate groups of controls with a dividing line, or enclose related controls within a box to set them apart.

To add a line to a form

  1. In the Form Controls toolbar, choose the Line button.

  2. Drag in the form to create a line.

You can size and move the line like other controls, or change the slant of the line with the LineSlant Property in the Properties window.

To add a shape to a form

  1. In the Form Controls toolbar, choose the Shape button.

  2. Drag in the form to create a shape.

You can change the type of shape drawn with the Curvature property in the Properties window.

See Also

Other Resources

Customizing Forms
Working with Forms
Creating Forms
Form Designer
Properties window
ColorSource property
How to: Set the Design Area for a Form


How to: Add Graphics to Forms

Visual FoxPro 9.0
How to: Add Graphics to Forms
See Also

You can add an image to the background of your form, or add an image to a box inside the form.

To add a graphic to your form

  1. Choose one of the following:

    • To change the background of the form, select the form.

      - OR -

    • To add a picture to your form, select an Image control from the Form Controls toolbar and place it on the form.

  2. In the Properties window, select the Picture property.

  3. Choose the dialog button to display the Open dialog box.

  4. Locate the image or other file you want to use.

  5. Choose OK.

See Also

Other Resources

Image Control
Picture Property
BackStyle Property
BackColor, ForeColor Properties
Customizing Forms
Form Designer
Properties window
ColorSource property
How to: Set the Design Area for a Form


How to: Set Form Colors

Visual FoxPro 9.0
How to: Set Form Colors
See Also

You can control a form's colors by using the ColorSource Property to base the colors on an existing color scheme, or you can use the Color Palette toolbar to change the foreground or background color of your forms and the controls within them.

To set form colors using the ColorSource property

  • On the Layout tab in the Properties window, choose ColorSource and select a value.

To set the foreground or background color of a form or control

  1. From the View menu, select Color Palette toolbar.

  2. Choose Foreground Color or Background Color.

  3. Select the control or form you want to change.

  4. In the Color Palette toolbar, select the color you want to use.

  5. To see more color choices, choose Other Colors on the toolbar.

To create a custom color

  1. In the Color Palette toolbar, choose Other Colors.

  2. In the Color dialog box, choose Define Custom Colors to display the Custom Color Selector.

  3. Select one of the Custom Colors boxes, and then click in the Custom Color Selector to select the custom color you want.

  4. Choose Add to Custom Colors to add the new color to your palette.

  5. Choose OK.

    Visual FoxPro applies the custom color to the current selection.

See Also

Other Resources

BackStyle Property
BackColor, ForeColor Properties
Customizing Forms
Working with Forms
Creating Forms
Form Designer
Properties window
How to: Set the Design Area for a Form


How to: Assign an Icon to a Form

Visual FoxPro 9.0
How to: Assign an Icon to a Form
See Also

In Visual FoxPro, you can assign an icon to the form; the icon is displayed on a forms taskbar button and in the title bar of the form. To assign an icon to a form, set the form's Icon property to the name of an .ico file.

To assign an icon to a form

  1. Open the form.

  2. Open the Properties window.

  3. Set the Icon property to the .ico file that you want to display.

See Also

Other Resources

How to: Add Properties and Methods to a Form
Manipulating Objects
How to: Edit Event and Method Code
Creating Forms
Form Designer
Visible Property
How to: Save Forms


How to: Add Properties and Methods to a Form

Visual FoxPro 9.0
How to: Add Properties and Methods to a Form
See Also

You can add as many new properties and methods as you want to a form set or to a form that isn't part of a form set. Properties hold a value; methods hold procedural code to be run when you call the method. The new properties and methods are scoped to the form and you reference them the same way you reference other properties or methods of the form.

Creating New Properties

If you have a form set, properties and methods that you add in the Form Designer are scoped to the form set. If you don't have a form set, the properties and methods are scoped to the form.

To add a new property to a form

  1. From the Form menu, choose New Property.

  2. In the New Property Dialog Box, type the name of the property. You can also include a description of the property that can be displayed at the bottom of the Properties window.

Creating an Array Property

An array property is scoped to the form like any other property, but can be manipulated with the Visual FoxPro array commands and functions.

To create an array property

  1. Add a new property to the form.

  2. In the Name box of the New Property Dialog Box, type the name of the array property and include the size and dimensions of the array.

    For example, to create a two-dimensional array with 10 rows, you could type arrayprop[10,2] in the Name box of the New Property dialog box.

Array properties are read-only in design mode, but you can manage, redimension, and assign values to the elements of the array property at run time. For an example of using an array property, see How to: Manage Multiple Instances of a Form.

Creating New Methods

You can add methods to the form that can be called the same way the form class methods can be called.

To create a new method for a form

  1. From the Form menu, choose New Method.

  2. In the New Method Dialog Box, type the name of the method. You can optionally include a description of the method.

You call a user-defined method the same way you call base class methods, using the following syntax:

Copy Code
          ObjectName.MethodName

Your method can also accept parameters and return values. In this case, you call the method in an assignment statement:

Copy Code
          cVariable = ObjectName.MethodName(cParameter, nParameter)

Including Predefined Constants

To use predefined constants in your methods or events (not to properties), you can include a header file in a form or a form set using #INCLUDE. A header file typically contains compile-time constants defined with the #DEFINE preprocessor directive.

To include a file in a form

  1. From the Form menu, choose Include File.

  2. In the Include File Dialog Box, specify the file in the Include File text box.

    -or-

    Choose the dialog button to open the Include dialog box and choose the file.

  3. Choose OK.

See Also

Other Resources

Adding Objects to Forms
How to: Add User-Defined Objects to a Form
Manipulating Objects
Creating Forms
Controlling Form Behavior
How to: Edit Event and Method Code


Controlling Form Behavior

Visual FoxPro 9.0
Controlling Form Behavior
See Also

When you are designing a form in the Form Designer, the form is live: except for setting the Visible property to false (.F.), visual and behavioral changes you make are immediately reflected in the form. If you set the WindowState property to 1 – Minimized or 2 – Maximized, the form in the Form Designer immediately reflects this setting. If you set the Movable property to false (.F.), a user will not be able to move the form at run time and you won't be able to move the form at design time either. You might want to design the functionality of your form and add all the appropriate controls before you set some of the properties that determine form behavior.

The following form properties are commonly set at design time to define the appearance and behavior of the form.

Property | Description | Default
AlwaysOnTop | Controls whether a form is always on top of other open windows. | False (.F.)
AutoCenter | Controls whether the form is automatically centered in the main Visual FoxPro window or on the desktop when the form is initialized. | False (.F.)
BackColor | Determines the color of the form window. | 255,255,255
BorderStyle | Controls whether the form has no border, a single-line border, a double-wide border, or a system border. If the BorderStyle is 3 - System, the user will be able to resize the form. | 3
Caption | Determines the text displayed in the title bar of the form. | Form1
Closable | Controls whether the user can close the form by double-clicking the close box. | True (.T.)
DataSession | Controls whether the tables in the form are opened in work areas that are globally accessible or private to the form. | 1
MaxButton | Controls whether or not the form has a maximize button. | True (.T.)
MinButton | Controls whether or not the form has a minimize button. | True (.T.)
Movable | Controls whether or not the form can be moved to a new location on the screen. | True (.T.)
ScaleMode | Controls whether the unit of measurement in object size and position properties is foxels or pixels. | Determined by settings in the Options dialog box.
Scrollbars | Controls the type of scroll bars a form has. | 0 - None
TitleBar | Controls whether a title bar appears at the top of the form. | 1 - On
ShowWindow | Controls whether the window is a child (in screen), floating, or top-level window. | 0 - In Screen
WindowState | Controls whether the form is minimized (in Windows only), maximized, or normal. | 0 - Normal
WindowType | Controls whether the form is modeless (the default) or modal. If the form is modal, the user must close the form before accessing any other elements of your application's user interface. | 0 – Modeless

You can use the LockScreen property to make run-time adjustment of control layout properties appear cleaner.

See Also

Other Resources

How to: Add Properties and Methods to a Form
How to: Assign an Icon to a Form
Manipulating Objects
How to: Edit Event and Method Code
Creating Forms
Form Designer
Visible Property
How to: Save Forms


How to: Edit Event and Method Code

Visual FoxPro 9.0
How to: Edit Event and Method Code
See Also

Events are user actions, such as clicks and mouse movements, or system actions, such as the progression of the system clock. Methods are procedures that are associated with the object and that are specifically invoked programmatically. For a discussion of events and methods, see Object-Oriented Programming. You can specify the code to be processed when an event is triggered or a method is invoked.

To edit event or method code

  1. From the View menu, choose Code.

  2. Select the event or method in the Procedure box.

  3. In the Edit window, write the code you want to be processed when the event is triggered or the method is invoked.

    For example, you could have a command button on a form with the caption "Quit." In the Click event for the button, include the line:

    Copy Code
    THISFORM.Release
    Tip:
    To move between procedures in the Code Editing window, press PAGE DOWN or PAGE UP.

When the user clicks the command button, the form is removed from the screen and from memory. If you don't want to release the form from memory, you could instead include the following line in the click event:

Copy Code
THISFORM.Hide
Note:
If code associated with the Init event of a form set, a form, or any object on any form in a form set returns false (.F.), the form will not be created.

See Also

Other Resources

How to: Add Properties and Methods to a Form
Controlling Form Behavior
How to: Save Forms
Creating Forms
How to: Run a Form
How to: Set Properties at Run Time


How to: Run a Form

Visual FoxPro 9.0
How to: Run a Form
See Also

You can run a form directly from the interface or in program code.

Running a Form Interactively

There are several ways to run the form you've designed.

If you're working in the Form Designer, you can test the form by clicking the Run button on the Form Designer toolbar. To reopen the form in the Form Designer, close the form or choose the Modify Form button on the toolbar.

You can also run a form from a project or programmatically.

To run a form

  1. In the Project Manager Window, select the select the name of the form under the Documents tab and choose Run.

    -or-

  2. Type "DO FORM" in the Command window.

    -or-

  3. From the Form menu, choose Run Form. You can also choose the Run button on the Standard toolbar.

You can also run the form by choosing Do from the Program menu, choosing Form in the List Files of Type box, selecting the form, and choosing Do.

Tip:
When running a form, you can quickly switch to Design mode by clicking the Modify Form button on the Standard toolbar.

To run a form from a program, include the DO FORM Command in the code associated with an event, in method code, or in a program or procedure.

Naming the Form Object

By default, when you use the DO FORM command, the name of the form object is the same as the name of the .scx file. For example, the following line of code runs Customer.scx. Visual FoxPro automatically creates an object variable for the form named customer:

Copy Code
DO FORM Customer

To name a form object

  • Use the NAME clause of the DO FORM command.

For example, the following commands run a form, creating two form object variable names:

Copy Code
DO FORM Customer NAME frmCust1
DO FORM Customer NAME frmCust2

Manipulating the Form Object

You can associate a form object with a public variable so that you can access the form object through the variable name.

To associate a form object with a public variable

  • Use the DO FORM command in the Command window.

For example, the following commands, issued in the Command window, open a form named Customer and change its caption.

Copy Code
DO FORM Customer
Customer.Caption = "Hello"

If you then issue the following command in the Command window, O is displayed in the active output window, indicating that Customer is an object:

Copy Code
? TYPE("Customer")

If you issue the DO FORM command in a program, the form object is scoped to the program. If the program or procedure completes, the object is gone, but the form remains visible. For example, you could run the following program:

Copy Code
*formtest.prg
DO FORM Customer

After you run the program, the form remains visible and all of the controls on the form are active, but TYPE("Customer") returns U indicating that Customer is an undefined variable. The following command, issued in the Command window, would generate an error:

Copy Code
Customer.Caption = "Hello"

You can, however, access the form by using the ActiveForm, Forms, and FormCount properties of the application object.

Scoping the Form to the Form Object Variable

You can link a form to a form object.

To link a form to a form object

  • Use the DO FORM command with the LINKED keyword.

If you include the LINKED keyword, when the variable associated with the form object goes out of scope, the form is released.

For example, the following command creates a form linked to the object variable frmCust2:

Copy Code
DO FORM Customer NAME frmCust2 LINKED

When frmCust2 is released, the form is closed.

Closing an Active Form

To allow users to close the active form by clicking the close button or by choosing Close from the form's Control menu, set the Closable property of the form.

To allow a user to close the active form

  1. In the Properties window, set the Closable Property to true (.T.).

    -or-

  2. Use the RELEASE Command.

For example, you can close and release the frmCustomer form by issuing the following command in a program or in the Command window:

Copy Code
RELEASE frmCustomer

You can also allow a user to close and release a form by including the following command in the Click Event code for a control, such as a command button with a caption of "Quit":

Copy Code
THISFORM.Release

You can also use the RELEASE command in the code associated with an object on the form, but any code you've included in the Release Method will not be executed.

Caution:
When you release a form, you release from memory the object variable created for the form. There is a single variable for a form set, so you can't release forms in a form set without releasing the form set. If you want to release the form set, you can use RELEASE THISFORMSET. If you want to remove a form from the screen so that a user can no longer see it or interact with it, you can use THISFORM.Hide.

See Also

Other Resources

Working with Forms
How to: Save Forms
How to: Set Properties at Run Time
Creating Forms
Example of Manipulating Objects
How to: Hide a Form


How to: Set Properties at Run Time

Visual FoxPro 9.0
How to: Set Properties at Run Time
See Also

The object model in Visual FoxPro makes it possible for you to control form properties at run time.

Referencing Objects in the Object Hierarchy

To manipulate an object in code, you need to identify it in relation to the container hierarchy. At the highest level of the container hierarchy, that is, the form or form set, you need to reference the object variable. Unless you use the NAME clause of the DO FORM Command, the object variable has the same name as the form (.scx) file.

To manipulate properties

  • In code, reference the object variable, the control, and then the property with the dot (.) operator as a separator and using the following format:

    ObjectVariable.[Form.]Control.Property = Setting

The following table lists properties or keywords that make it easier to reference an object in the object hierarchy.

Property or keyword | References
ActiveControl | The control on the currently active form that has the focus.
ActiveForm | The currently active form.
ActivePage | The active page on the currently active form.
Parent | The immediate container of the object
THIS | The object or a procedure or event of the object.
THISFORM | The form that contains the object.
THISFORMSET | The form set that contains the object.

For example, to change the caption of a command button on the form frmCust in a form set stored in Custview.scx, use the following command in a program or in the Command window:

Copy Code
CustView.frmCust.cmdButton1.Caption = "Edit"

Use the THIS, THISFORM, and THISFORMSET keywords to reference objects from within a form. For example, to change the Caption of a command button when the command button is clicked, include the following command in the Click event code for the command button:

Copy Code
THIS.Caption = "Edit"

The following table gives examples of using THISFORMSET, THISFORM, THIS, and Parent to set object properties:

Command | Where to include the command
THISFORMSET.frm1.cmd1.Caption = 'OK' | In the event or method code of any control on any form in the form set except for frm1.
THISFORM.cmd1.Caption = 'OK' | In the event or method code of any control except for cmd1 on the same form that cmd1 is on.
THIS.Caption = 'OK' | In the event or method code of the control whose caption you want to change.
THIS.Parent.BackColor = RGB(192,0,0) | In the event or method code of a control on a form. The command changes the background color of the form to dark red.

Setting Properties at Run Time with Expressions

You can also set properties at run time using expressions or functions.

To set properties to expressions at run time

  1. Assign an expression to the property.

    -or-

  2. Assign the result of a user-defined function to the property.

    For example, you could set the caption of a button to be Edit or Save, depending on the value of a variable. Declare the variable in the calling program for your form:

    Copy Code
    PUBLIC glEditing
glEditing = .F.

    Then use an IIF expression in the Caption setting:

    Copy Code
    frsSet1.frmForm1.cmdButton1.Caption = ;
   IIF(glEditing = .F., "Edit", "Save")

You could determine the size of a button and set the caption using expressions with fields in a table:

Copy Code
* set button width to length of 'Call ' + first and last names
frmForm1.cmdButton1.Width = 5 + ;
   LEN(ALLTRIM(employee.first_name    + " " + employee.last_name))
* set button caption to 'Call ' + first and last names
frmForm1.cmdButton1.Caption = "Call " + ;
   ALLTRIM(employee.first_name + " " + employee.last_name)

You could also set the caption using a user-defined function:

Copy Code
frsSet1.frmForm1.cmdButton1.Caption = setcaption()

Setting Multiple Properties

You can set multiple properties at once.

To set multiple properties

  • Use the WITH ... ENDWITH Command structure.

    For example, to set multiple properties of a column in a grid in a form, you could include the following statement in any event or method code in the form:

    Copy Code
    WITH THISFORM.grdGrid1.grcColumn1
   .Width = 5
   .Resizable = .F.
   .ForeColor = RGB(0,0,0)
   .BackColor = RGB(255,255,255)
   .SelectOnEntry = .T.
ENDWITH

Calling Methods at Run Time

After an object is created, you can call the methods of that object from anywhere in your application.

To call a method for an object

  • Use the following syntax:

    Parent.Object.Method

For example, the following code calls methods to display a form and set the focus to a command button:

Copy Code
* form set saved in MYF_SET.SCX
myf_set.frmForm1.Show
myf_set.frmForm1.cmdButton1.SetFocus

To hide the form, issue this command:

Copy Code
myf_set.frmForm1.Hide

See Also

Other Resources

Working with Forms
How to: Run a Form
Creating Forms
How to: Hide a Form
How to: Pass Parameters to a Form
How to: Save a Form as HTML


How to: Hide a Form

Visual FoxPro 9.0
How to: Hide a Form
See Also

You can hide a form so that it is not visible to a user. When the form is hidden, the user cannot interact with the form, but you still have full programmatic control of them.

To hide a form

  • Use the Hide Method.

    For example, in the code associated with the Click Event of a command button, you could include the following line of code:

    Copy Code
    THISFORM.Hide

When the user clicks the command button, the form remains in memory, but is not visible.

Releasing Forms

You can allow a user to release a form when he or she is finished interacting with it. When you release a form, you can no longer access properties and methods of the form.

To release a form

  • Call the Release Method.

For example, in the code associated with the Click Event of a command button, you could include the following line of code:

Copy Code
THISFORM.Release

When the user clicks the command button, the form closes.

See Also

Other Resources

Working with Forms
Example of Manipulating Objects
Creating Forms
How to: Pass Parameters to a Form
How to: Save a Form as HTML
How to: Manage Multiple Instances of a Form


How to: Pass Parameters to a Form

Visual FoxPro 9.0
How to: Pass Parameters to a Form
See Also

Sometimes you want to pass parameters to forms when you run them to set property values or specify operational defaults.

To pass a parameter to a form created in the Form Designer

  1. Create properties on the form to hold the parameters, such as ItemName and ItemQuantity.

  2. In the Init Event code for the form, include a PARAMETERS statement such as:

    Copy Code
    PARAMETERS cString, nNumber

  3. In the Init event code for the form, assign the parameters to the properties, as in this example:

    Copy Code
    THIS.ItemName = cString
THIS.ItemQuantity = nNumber

  4. When running the form, include a WITH clause in the DO FORM Command:

    Copy Code
    DO FORM myform WITH "Bagel", 24

See Also

Other Resources

Working with Forms
How to: Hide a Form
How to: Save a Form as HTML
Creating Forms
How to: Manage Multiple Instances of a Form
How to: Set the Design Area for a Form
How to: Return a Value from a Form


How to: Return a Value from a Form

Visual FoxPro 9.0
How to: Return a Value from a Form
See Also

You can use forms throughout your application to allow users to specify a value.

To return a value from a form

  1. Set the WindowType Property of the form to 1 to make the form modal.

  2. In the code associated with the Unload event of the form, include a RETURN Command with the return value.

  3. In the program or method that runs the form, include the TO keyword in the DO FORM Command.

    For example, if FindCustID is a modal form that returns a character value, the following line of code stores the return value to a variable named cCustID:

    Copy Code
    DO FORM FindCustID TO cCustID

For more information, see RETURN Command and DO FORM Command.

Note:
If you get an error, make sure the WindowType is set to 1 (Modal).

See Also

Other Resources

Working with Forms
Unload Event
How to: Pass Parameters to a Form
RETURN Command
DO FORM Command


How to: Manage Multiple Instances of a Form

Visual FoxPro 9.0
How to: Manage Multiple Instances of a Form
See Also Example

You can have multiple instances of a class definition active at a time. For example, you can design one order form but have several open orders in your application. Each uses the same form definition but is displayed and manipulated individually.

When you have multiple instances of a form, the key points to remember are:

  • Create an array property in the launching form to hold the object variables associated with each instance of the multiple instance form. The easiest way to keep track of instance variables when you don't know ahead of time how many there will be is to use an array.

  • For the form that is to have multiple instances, set the DataSession Property to 2 – Private Data Session. A private data session provides a separate set of work areas for each instance of the form so that selected tables and record pointer positions are all independent.

Example

The following example provides code that demonstrates creating multiple instances of a form. For the sake of brevity, this code is not optimized; it is intended only to present the concepts.

The following form launches multiple instances:

Property Setting for Launch.scx

Object | Property | Setting
frmLaunch | aForms[1] | " "

Event Code for Launch.scx

Object | Event | Code
cmdQuit | Click | RELEASE THISFORM
cmdLaunch | Click | nInstance = ALEN(THISFORM.aForms) DO FORM Multi ; NAME THISFORM.aForms[nInstance] ; LINKED DIMENSION ; THISFORM.aForms[nInstance + 1]

In refining the code in this example, you could manage the array of form objects so that empty array elements reused as forms are closed and new forms are opened, rather than always redimensioning the array and increasing the number of elements by one.

The form that can have multiple instances is Multi.scx. The data environment for this form contains the Employee table.

Property Setting for Multi.scx

Object | Property | Setting
txtFirstname | ControlSource | Employee.first_name
txtLastName | ControlSource | Employee.last_name
frmMulti | DataSession | 2 - Private Data Session

When you choose Launch Form in the Launcher form, an instance of the Multi form is created. When you close the Launcher form, the property array aForms is released and all instances of Multi are destroyed.

Visual FoxPro provides some functions and properties to help you manage multiple instances of objects. For more information, see AINSTANCE( ) Function, AUSED( ) Function, and DataSessionID Property.

See Also

Other Resources

Working with Forms
How to: Save a Form as HTML
How to: Set the Design Area for a Form
Creating Forms
How to: Create Forms with Local and Remote Data
DataSession


Docking Forms

Visual FoxPro 9.0
Docking Forms
See Also

You can dock forms the same way you can dock toolbars. However, unlike docked toolbars, docked forms resize to fill the dock area of the item they are docked with, but only affected dimensions are changed. For example, if you dock a form to the right edge of the target object, the width of the form does not change.

You can link-dock or tab-dock user-defined forms inside Visual FoxPro IDE windows. A form is link-docked to another form when they share a container. A form is tab-docked to another form when they display tabs that you can click to display each form. While the form is docked, controls on the form can still receive focus. When a form is docked along the border of the main Visual FoxPro window, its title bar is displayed at half its height.

Note:
Unlike Visual FoxPro windows, Visual FoxPro does not save the dock settings when closing a user-defined form. You need to provide code for handling this task.

When docking a form, Visual FoxPro calls the form's Resize event. For more information, see Resize Event.

When a form's Visible property is set to .F. (False), Visual FoxPro automatically undocks the form and hides it. When the form's Visible property is set to .T. (True), Visual FoxPro attempts to dock the form in the original location if possible. For more information, see Visible Property.

You can use the following functions, properties, methods, and events to retrieve the form's dock state or write code for docking events:

  • ADOCKSTATE( ) Function

  • AfterDock Event

  • BeforeDock Event

  • Dock Method

  • Dockable Property

  • Docked Property

  • GetDockState Method

  • UnDock Event

See Also

Tasks

How to: Dock Forms
How to: Dock Toolbars
How to: Set Properties at Run Time

Other Resources

Working with Forms
Creating Forms
Customizing Forms


How to: Dock Forms

Visual FoxPro 9.0
How to: Dock Forms
See Also

You can dock user-defined forms to certain Visual FoxPro IDE windows or other forms.

To dock a form

  1. Open the form in the Form Designer.

  2. In the Properties window, set the form's Dockable property to 1.

  3. Save and run the form.

  4. Drag the form to the dock area of the target window or form.

    An outline of the form appears and changes shape when the form is moved over an eligible docking area.

For more information, see Form Designer and Dockable Property.

To dock a form programmatically

  1. In code, set the form's Dockable property to 1.

  2. Set the form's Visible property to .T. (True).

  3. Call the form's Dock method with the appropriate values.

For more information, see Visible Property (Visual FoxPro) and Dock Method.

To undock a form

  • Choose one of the following:

    • Drag the form from the window or form it is docked to.

    -OR-

    • Call the form's Dock method with the appropriate values.

    -OR-

    • Set the form's Dockable property to 2 or 0.

See Also

Tasks

How to: Set Properties at Run Time

Other Resources

Working with Forms
Creating Forms
Customizing Forms


How to: Create Forms with Local and Remote Data

Visual FoxPro 9.0
How to: Create Forms with Local and Remote Data
See Also

You can create forms that can be easily switched between using local data and data that is stored remotely (for example, on a database server). This allows you to create a prototype application using local or test data, then switch to remote or live data without substantial changes to your forms.

For example, if your Visual FoxPro application is a front end for a large customer table stored on a database server, you can create a local .dbf file that contains a small but representative sampling of the data. You can then create, test, and debug your forms based on this small set of data. When you're ready to distribute your application, you can link your form to the large data set.

The key to being able to switch between local and remote data is to make sure that you use views instead of directly linking your form (and its controls) to a table. To access remote data, you must use a view in any event. Therefore, to facilitate switching between local and remote data, create a view for the local data as well. When you create the form, you can add both views to its data environment, then switch between them as needed.

To create a form that can switch between local and remote data

  1. Create two views of the data, one that points to the remote data, and another that points to the local data.

  2. Create a new form.

  3. Open the Data Environment Designer for the form, and then add both views.

  4. Right-click the Data Environment Designer, and then choose Properties.

  5. In the Properties window, set the Alias Property for both cursors to the same name.

  6. Set the data environment's OpenViews Property to either 1 — Local Only or 2 — Remote Only, depending on which view you wanted to use when running the form.

    Note:
    Because you are using the same alias for both views, do not choose 0 — Local and Remote (the default).

  7. On the form, add the controls you need and set their ControlSource properties to the appropriate fields in the view. Because both views have the same alias, the controls will respond automatically to whichever view is active when the form is run.

After the form is created, you can switch the views alias by changing the data environment's OpenViews property. You can do this in the Data Environment while using the Form Designer. Alternatively, you can write code and attach it to an event, which is useful if you want to switch views at run time. For example, you could put this code in the form's Activate event:

Copy Code
THISFORM.DataEnvironment.OpenViews = 2 && Use remote view

If you create a form that can be switched between local and remote data, you must also design your navigation code to accommodate both views, particularly if you are designing forms with one-to-many relationships. For example, if your form only accesses a local table or view, you might use code such as the following in a Next command button to move to the next record in a cursor:

Copy Code
SKIP 1
THISFORM.Refresh()

However, this code is inefficient when you're navigating in a remote view, because it assumes that the cursor contains all the data required by the form. As a rule, you want to minimize the amount of data that you download from the remote data source.

The solution is to use a parameterized view. For example, the definition for a view used to edit customer information could be:

Copy Code
SELECT * FROM CUSTOMERS WHERE ;
 CUSTOMERS.COMPANY_NAME = ?pCompanyName

When the form runs, it can prompt the user for a customer name using a dialog box or by allowing the user to enter a name in a text box. The code for a Display button would then be similar to the following:

Copy Code
pCompanyName = THISFORM.txtCompanyName.Value
REQUERY("customer")
THISFORM.Refresh()

For more information, see How to: Create Parameterized Views.

See Also

Other Resources

Working with Forms
How to: Set the Design Area for a Form
How to: Set Form Templates
Creating Forms
Data Environment Designer


How to: Set the Design Area for a Form

Visual FoxPro 9.0
How to: Set the Design Area for a Form
See Also

You can set the maximum design area for the Form Designer in the Options dialog box.

To set the maximum design area for a form

  1. From the Tools menu, choose Options.

  2. In the Options dialog box, choose the Forms tab.

  3. In the Maximum design area box, choose the pixel coordinates for the maximum design area.

    Tip:
    If you select None, the Form Designer does not impose a limit on the size of form you design.

For more information, see Forms Tab, Options Dialog Box.

When you set the maximum design area, the background of the Form Designer is white within the design area boundaries and gray in areas beyond the maximum design area. If you develop applications on a monitor with a resolution of 1024 x 768, for example, you can set your design resolution to 640 x 480 and know that the forms you design will always fit on 640 x 480 screens.

Within the design area, be sure to account for standard window attributes such as toolbars. For example, in a 640 x 480 screen, a form with a status bar and one toolbar docked at the top or the bottom of the screen can have a maximum height of 390 pixels.

Main Visual FoxPro window attribute | Required pixels (Non-Themed Windows)
Title and menu | 38
Status bar | 23
Docked toolbar | 29

Note The required pixel amounts above will vary if themed windows are used.

See Also

Other Resources

Working with Forms
How to: Manage Multiple Instances of a Form
How to: Create Forms with Local and Remote Data
Creating Forms
How to: Set Form Templates


Using Form Templates

Visual FoxPro 9.0
Using Form Templates
See Also

Form templates allow you to set default properties for your forms so that you can easily give all the forms in your application a consistent look and feel. You could include a company logo, for instance, and use a consistent color scheme in all your forms by designing a template form class with these attributes. If the company logo changes, you could change the picture in the template form class and all the forms you created based on the template would automatically inherit the new logo.

You can add custom properties and methods to the Visual FoxPro form class so that these properties and methods are available to each form in your application. If you are used to creating variables and user-defined procedures that are scoped to a form, using custom properties and methods provides this functionality, and also allows you to have a cleaner encapsulation model.

You can specify form set templates the same way you set form templates. The following combinations are possible:

  • Both form set and form templates are specified.

    Choosing Form in the New dialog box (and all the other ways to create a new form) will automatically create a form set based on the template form set class. When you choose Add New Form from the Form menu in the Form Designer, a form based on your form template is added to the form set.

  • Only the form set template is specified.

    Choosing Form in the New dialog box (and all the other ways to create a new form) will automatically create a form set based on the template FormSet class. When you choose Add New Form from the Form menu in the Form Designer, a form based on the Visual FoxPro Form base class is added to the form set.

  • Only the form template is specified.

    Choosing Form in the New dialog box (and all the other ways to create a new form) will automatically create a form based on the template Form class.

  • No templates are specified.

    Choosing Form in the New dialog box (and all the other ways to create a new form) will automatically create a form based on the Visual FoxPro Form base class.

For more information, see How to: Set Form Templates.

See Also

Other Resources

Working with Forms
How to: Create Forms with Local and Remote Data
Creating Forms
Options Dialog Box
How to: Save a Form as HTML
How to: Set the Design Area for a Form
How to: Manage Multiple Instances of a Form


How to: Set Form Templates

Visual FoxPro 9.0
How to: Set Form Templates
See Also

You can create your own form class to use a template for all your new forms, or you can use one of the sample classes that ship with Visual FoxPro. For more information, see Using Form Templates.

When you create a new form, it is based on the template form that is set in the Options dialog box. If no template is specified, the new form is based on the Visual FoxPro Form base class. For more information about Visual FoxPro classes, see Object-Oriented Programming.

You can specify a form class from a registered class library for your form template.

To specify a default form template

  1. From the Tools menu, choose Options.

  2. In the Options dialog box, choose the Forms tab.

  3. In the Template classes area, select the Form check box.

    If no form template has been selected, the Open dialog box opens so that you can choose a form class. If a form template has been selected, you can change it by choosing the dialog button and selecting another class.

  4. Choose Set as Default if you want the template to be used in subsequent sessions of Visual FoxPro.

  5. Choose OK.

See Also

Other Resources

Working with Forms
How to: Create Forms with Local and Remote Data
Creating Forms
Options Dialog Box
How to: Save a Form as HTML
How to: Set the Design Area for a Form
How to: Manage Multiple Instances of a Form


How to: Save Forms

Visual FoxPro 9.0
How to: Save Forms
See Also

You need to save your form before you can run it. If you try to close the Form Designer when the form has not been saved, Visual FoxPro prompts you to save or discard the changes you've made.

To save a form

  • In the Form Designer, choose Save from the File menu. Forms are saved as files with an .scx extension.

Saving Forms and Controls as Classes

You can also save a form, or a subset of the controls on a form, as a class definition. If you intend to create subclasses based on the form or reuse the controls in other forms, save the form as a class definition.

To save a form or selected controls as a class definition

  1. From the File menu, choose Save As Class.

  2. In the Save As Class Dialog Box, choose Current form or Selected controls.

  3. In the Name box, enter a name for the class.

  4. In the File box, enter a filename for the class to be stored to.

  5. Choose OK.

If you don't give the filename an extension, the default extension of .vcx is added when the file is saved. Once a form has been saved as a class definition, you can modify it with the MODIFY CLASS command. For more information about creating classes, see Object-Oriented Programming.

See Also

Other Resources

How to: Save a Form as HTML
How to: Edit Event and Method Code
Creating Forms
Working with Forms
How to: Run a Form
How to: Set Properties at Run Time
Example of Manipulating Objects


How to: Save a Form as HTML

Visual FoxPro 9.0
How to: Save a Form as HTML
See Also

You can use the Save As HTML option on the File menu when you're creating a form to save the contents of a form as an HTML (Hypertext Markup Language) file.

To save a form as HTML

  1. Open the form.

  2. Choose Save As HTML on the File menu. (You will be asked to save the form if it has been modified.)

  3. Enter the name of the HTML file to create and choose Save.

See Also

Other Resources

How to: Save Forms
How to: Pass Parameters to a Form
How to: Manage Multiple Instances of a Form
Creating Forms
Working with Forms
How to: Set the Design Area for a Form
How to: Create Forms with Local and Remote Data


Using Controls

Visual FoxPro 9.0
Using Controls

Users interact with applications primarily using controls on forms. For example, by clicking, typing into, and navigating controls on forms in your application, users can manipulate data and accomplish the tasks they need to perform. Visual FoxPro provides a variety of controls that you can include on forms to help users perform tasks. The following list describes main categories of application tasks you can perform using controls:

  • Provide users with a set of predetermined choices.

  • Accept user input that cannot be predetermined.

  • Accept user input in a given range.

  • Allow users to perform specific actions.

  • Perform specific actions at given intervals.

  • Display information.

For example, you can make sure that only valid data is stored in a database by providing users a specified set of options or values. To provide these predetermined choices, you can use the following controls:

  • Option buttons or option button groups.

  • List boxes and drop-down list boxes.

  • Check boxes.

Though you can use a variety of controls to perform any particular task, you should select and use controls consistently so that users can easily understand or know what to expect when they interact with your application's interface. For example, a label might contain the same Click event as a command button; however, users who are familiar with graphical interfaces expect to click command buttons, not labels, to perform actions.

In This Section

Controls for Displaying Lists

Describes the common uses, methods, and properties of list boxes and drop-down list boxes.
Controls for Accepting Input

Describes the common uses, methods, and properties of Visual FoxPro controls that accept user input that cannot be predetermined.
Controls for Displaying Information

Explains various Visual FoxPro controls and objects that can display and order information.
Controls for Manipulating Rows of Data

Describes the common uses, methods, and properties of the Visual FoxPro grid control.
Controls for Allowing Specific Actions

Describes the Visual FoxPro controls that allow users to take specific preprogrammed actions either by user interaction or by timed delay.
Controls for Extending Forms

Describes how the Page Frame object and the use of ActiveX controls can expand the workable area and use of Visual FoxPro forms.
Controls and Data Concepts

Explains the difference between the two kinds of controls you can have on your forms and lists the effects of a ControlSource property setting on different controls.
Creating Drag-and-Drop Controls

Describes the two types of drag-and-drop functionality that can be included in your Visual FoxPro application, OLE drag-and-drop and control drag-and-drop.
How to: Make Controls Easier to Use

Offers instructions on how to use access keys, tab order, ToolTip text, and selective disabling to create a more design that is easier to use.

Related Sections

Creating the User Interface

Using Visual FoxPro forms, classes, controls, menus, and toolbars, you can build interfaces that help users gain access to the full potential of your programs.
Creating Forms

Your application must have forms to make it possible for users to view and enter data. However, you can customize standard forms visually and programmatically to create a specialized environment for your users.
Working with Forms

After creating your form, you can run, hide, or alter it in different ways.
Designing Menus and Toolbars

A good menu system tells your users a lot about the design and structure of your application. Planning menus and toolbars carefully can improve the usability of your application and provide immediate access to common tasks.


Controls for Displaying Lists

Visual FoxPro 9.0
Controls for Displaying Lists

The ListBox and ComboBox controls provide list boxes and drop-down list boxes that the user can scroll through to see options or pieces of information. List boxes can display multiple items, while drop-down list boxes can display one item at a time. However, the user can click the scroll arrow to display and scroll through a list of all the items in the list box.

Tip:
If you have space on the form and want to emphasize the choices the user can make, use a list. To conserve space and emphasize the currently selected item, use a drop-down list box.

You can fill a list box or combo box with items from a variety of sources by setting the RowSourceType and RowSource properties. For more information, see How to: Choose the Type of Data for a List or Combo Box.

To see several examples demonstrating list boxes and drop-down list boxes, run Solution.app in the Visual FoxPro directory, ...\Samples\Solution.

In This Section

How to: Choose the Type of Data for a List or Combo Box

Describes the various source types that can be used to populate a ListBox or ComboBox control.
How to: Create Multicolumn List Boxes

Describes how to create a list with multiple columns displayed.
How to: Allow Users to Select Multiple Items in a List Box

Explains how to allow multiple items in a list to be selected.
How to: Allow Users to Add Items to a List Box

Describes how to add items to a list interactively using the AddItem method.
How to: Refresh a One-to-Many Display Based on a List Value

Describes how to design a one-to-many list based on local or remote views.
How to: Display Child Records in a List

Explains how to display child records in a list.
How to: Add Pictures to Items in a List

Provides information on how to display pictures in a list.

Related Sections

Using Controls

Controls manage the interactions between users and your application. Visual FoxPro offers a variety of controls to enhance your application interface.
Controls and Objects Created in Earlier Versions

Describes support for controls and objects created in earlier FoxPro versions and new controls added to Visual FoxPro.


How to: Choose the Type of Data for a List or Combo Box

Visual FoxPro 9.0
How to: Choose the Type of Data for a List or Combo Box
See Also

When you want to populate a ListBox or ComboBox control with items or values, set the control's RowSource property to specify the source of items or values to fill the control and set the RowSourceType property to identify the source type, such as an array or table.

Tip:
It is recommended that you set the RowSourceType property before setting RowSource to determine the source that can be used. To ensure that the control displays the most recent items or values, use the Requery method in the Init method, for example, This.Requery().

Note:
When you set the RowSource property in code, you must enclose the value with quotation marks ("").

When the ColumnCount property is set to 0 or 1, the control displays the first item or value only in a single column. Otherwise, the control displays each item or value in a column up to the number of columns specified by ColumnCount. You might also need to set the ColumnWidths property to expand the width of the control so the items or values within display properly.

This topic contains examples that illustrate ways you can set RowSourceType and RowSource depending on the source of values you choose. The following is a list displaying the source types available:

  • No Source Type

  • Value Source Type

  • Alias Source Type

  • SQL Statement Source Type

  • Query Source Type

  • Array Source Type

  • Fields Source Type

  • Files Source Type

  • Field Structure Source Type

  • Pop-Up Source Type

  • Collection Source Type

  • Different Source Types

For details about source types, the sources you can specify, and how ColumnCount affects population of the control for each source type, see RowSourceType Property and RowSource Property.

For more information, Visual FoxPro provides the following samples that use the RowSourceType and RowSource properties:

  • Add New Items to a Combo Box Sample

  • Allow Users to Choose List Values Sample

  • Move Items Between List Boxes Sample

  • Open Multiple Files Interactively Sample

No Source Type

You can populate a list box or combo box without specifying a source or source type.

To populate the control without specifying a source

  1. Set RowSourceType to 0 (None).

    None is the default setting and does not populate the control automatically.

  2. Use the AddItem method, AddListItem method, List property, or ListItem property to add values or items to the control.

For example, the following lines of code set RowSourceType to 0 to indicate no source type and uses the AddItem method to add three items to the list box lstMyListBox on the form frmForm1:

Copy Code
frmForm1.lstMyListBox.RowSourceType = 0
frmForm1.lstMyListBox.AddItem("First Item")
frmForm1.lstMyListBox.AddItem("Second Item")
frmForm1.lstMyListBox.AddItem("Third Item")

The list box displays the items, "First Item", "Second Item", and "Third Item". For more information, see AddItem Method, AddListItem Method, List Property, and ListItem Property.

To remove items from the list, use the RemoveItem method. For example, the following line of code removes the second item, "Second Item", from the list box:

Copy Code
frmForm1.lstMyListBox.RemoveItem(2)

For more information, see RemoveItem Method.

Value Source Type

You can populate a list box or combo box with a list of individual values.

To populate the control with a list of individual values

  1. Set RowSourceType to 1 (Value).

  2. Set RowSource by specifying the values in a comma-delimited list, using no spaces between the values and the commas.

For example, the following lines of code set RowSourceType to 1 to indicate that the source is a comma-delimited list of values and specifies a comma-delimited list in quotation marks ("") for RowSource:

Copy Code
Form1.lstMyList.RowSourceType = 1
Form1.lstMyList.RowSource = "one,two,three,four"

Alias Source Type

You can populate a list box or combo box with values from one or more fields in an open table by specifying the table's alias.

To populate the control with values from one or more fields using a table alias

  1. Set RowSourceType to 2 (Table alias).

  2. Set RowSource by specifying a table alias.

For example, the following lines of code set RowSourcetype to 2 to indicate that the source is a table identified by the table alias, Customers, and specifies "Customers" as the table alias for RowSource:

Tip:
Make sure the table is opened first before the code executes.

Copy Code
OPEN DATABASE (HOME(2)+"Northwind\Northwind")
Form1.lstMyList.RowSourceType = 2
Form1.lstMyList.RowSource = "Customers"

The ColumnCount property determines the number of fields from which values are used to populate the control. When ColumnCount set to 0 or 1, the control displays values from the first field in the table. When ColumnCount set to a value greater than 1, the control displays values from fields in the table up to the number specified by ColumnCount. For example, if ColumnCount is set to 3, the control displays values from the first three fields in the table.

Note:
When RowSourceType is 2 (Table alias) or 6 (Fields), the table record pointer moves to the record containing the value that the user chooses in the list.

SQL Statement Source Type

You can populate a list box or combo box with values a cursor or table created by a SQL statement, such as SQL SELECT.

To populate the control with values from a SQL statement

  1. Set RowSourceType to 3 (SQL statement).

  2. Set RowSource by specifying a SQL SELECT statement.
Tip:
By default in Visual FoxPro, SQL SELECT statements without INTO clauses display the resulting cursor immediately in a browse window. For more information, see Browse Window. It is suggested that you include an INTO CURSOR clause in your SQL SELECT statement to avoid displaying the browse window.

For example, the following lines of code set RowSourceType to 3 to indicate that the source is a cursor or table created from a SQL statement and specifies a SQL SELECT statement for RowSource that selects all fields and all records from the Customers table, located in the sample Northwind database in the directory, ..\Samples\Northwind, into a cursor named myCursor:

Copy Code
OPEN DATABASE (HOME(2)+"Northwind\Northwind")
Form1.lstMyList.RowSourceType = 3
Form1.lstMyList.RowSource = "SELECT * FROM Customers INTO CURSOR myCursor"

For more information about SQL SELECT statements, see SELECT - SQL Command.

Query Source Type

You can populate a list box or combo box with results from a query that you created using the Query Designer and saved in a query (.qpr) file. For more information about queries, see Query and View Designers and How to: Create Queries.

To populate the control with values from a query

  1. Set RowSourceType to 4 (Query file).

  2. Set RowSource by specifying the name of a .qpr file, including a path if needed.

    Note:
    Make sure to include the .qpr file name extension. However, if you do not specify a file extension, Visual FoxPro assumes the file extension is .qpr.

For example, the following lines of code set RowSourceType to 4 to indicate that the source is a .qpr file and specifies the name of a .qpr file for RowSource:

Copy Code
Form1.lstMyList.RowSourceType = 4
Form1.lstMyList.RowSource = "MyQuery.qpr"

Array Source Type

You can populate a list box or combo box with items or values stored in an array. You use an array created elsewhere in your application or create an array property of the form or form set to specify for RowSource. For more information about arrays, see Arrays. For more information about creating array properties, see Creating Forms.

To populate the control from an array

  1. Set RowSourceType to 5 (Array).

  2. Set RowSource by specifying the name of the array.

For example, the following lines of code create an array with 10 elements, store values in the array, set RowSourceType to 5 to indicate the source is an array, and specifies the name of the array for RowSource:

Copy Code
DIMENSION gaMyArray(10)
FOR gnCount = 1 to 10
   STORE gnCount TO gaMyArray(gnCount)
NEXT
Form1.lstMyList.RowSourceType = 5
Form1.lstMyList.RowSource = "gaMyArray"
Note:
The RowSource setting is evaluated by Visual FoxPro as needed in your application and is not confined only to the method in which you set RowSource. You need to keep this scope in mind.

For example, if you create a local array in a method, that array is scoped to the method and will not be available in all cases when Visual FoxPro needs to evaluate the property setting. If you set the RowSource to an array property of a form or form set, you need to reference the property relative to the control, not relative to the method in which you set the property. As an example, suppose you have a form array property named arrayProp and the following lines of code in the form's Init event. The first line of code produces an error while the second line does not:

Copy Code
THIS.lst1.RowSource = "THIS.arrayprop"
THIS.lst1.RowSource = "THISFORM.arrayprop"

Fields Source Type

You can populate a list box or combo box with values from fields from a single table. Unlike when RowSourceType is set to 2 (Table alias), setting RowSourceType to 6 (Fields) makes it possible to display fields independent of their actual positions in the table.

Tip:
If you want to populate the control with fields from multiple tables, set RowSourceType to 3 and specify a SQL SELECT statement for RowSource.

To populate the control from fields from a single table

  1. Set RowSourceType to 6 (Fields).

  2. Set RowSource by specifying a field or a comma-delimited list of fields.

    If the table is open, you can specify RowSource in the following ways:

    Copy Code
    Form1.lstMyList.RowSource = field1
Form1.lstMyList.RowSource = field2, field3, ...

    If the table is not open, precede the field or list of fields with a table alias and a period (.), for example:

    Copy Code
    Form1.lstMyList.RowSource = TableAlias.field1
Form1.lstMyList.RowSource = TableAlias.field1, field3, field2, ...

For example, the following lines of code open a table, set RowSourceType to 6 to indicate that the source type is fields, and specify fields from the Products table in the Northwind database, located in the directory ..\Samples\Northwind, for RowSource:

Copy Code
OPEN DATABASE (HOME(2)+"Northwind\Northwind")
USE Products
Form1.lstMyList.RowSourceType = 6
Form1.lstMyList.RowSource = "productname, productid"

The following lines of code specify fields from the Customers table, which is not open, for RowSource:

Copy Code
OPEN DATABASE (HOME(2)+"Northwind\Northwind")
Form1.lstMyList.RowSourceType = 6
Form1.lstMyList.RowSource = "Customers.companyname, customerid"

Files Source Type

You can populate a list box or combo box with the names of files from the current directory. The list also contains options for you to choose a different drive and directory to display file names from.

To populate the control with file names from a directory

  1. Set RowSourceType to 7 (Files).

  2. Set RowSource by specifying a file skeleton or mask, such as *.* or *.fileExt.

For example, the following lines of code set RowSourceType to 7 to indicate that the source type is files and specifies a file skeleton for RowSource:

Copy Code
Form1.lstMyList.RowSourceType = 7
Form1.lstMyList.RowSource = "*.*"

Field Structure Source Type

You can populate a list box or combo box with the names of fields in a table. Displaying a list of field names is useful when the user wants to search a particular field for values or to organize those fields in the table.

To populate the control with field names from a table

  1. Set RowSourceType to 8 (Field structure).

  2. Set RowSource by specifying a table name or table alias.

For example, the following lines of code set RowSourceType to 8 to indicate that the source type is a field structure of a table and specifies a table name for RowSource:

Copy Code
Form1.lstMyList.RowSourceType = 8
Form1.lstMyList.RowSource = "Customers"

Pop-Up Source Type

Included for backward compatibility, RowSourceType set to 9 (Pop-up) made it possible to populate a list box or combo box from a previously defined pop-up or menu.

To populate the control with a pop-up menu

  • Set RowSourceType to 9 (Pop-up).

Collection Source Type

You can populate a list box or combo box with members and property values of objects in a collection, or Collection object.

To populate the control with collection members

  1. Set RowSourceType to 10 (Collection).

  2. Set RowSource by specifying the name of a collection.

For example, the following lines of code create a collection and two forms, adds the forms and three strings to the collection, sets RowSourceType to 10 to indicate that source type is a Collection object, and specifies the collection name and properties of objects in the collection for RowSource:

Copy Code
colMyCollection=CREATEOBJECT("Collection")
frm1=CREATEOBJECT("Form")
frm2=CREATEOBJECT("Form")
colMyCollection.Add(frm1)
colMyCollection.Add(frm2)
colMyCollection.Add("Item 1")
colMyCollection.Add("Item 2")
colMyCollection.Add("Item 3")
Form1.lstMyList.RowSourceType = 10
Form1.lstMyList.RowSource = "colMyCollection, Caption, Name"

Different Source Types

You can populate a list box or combo box with items and values from different sources.

To populate a control from different sources

  • See Fill a List with Values from Different Sources Sample.

See Also

Other Resources

Controls for Displaying Lists
Controls and Objects Created in Earlier Versions


How to: Create Multicolumn List Boxes

Visual FoxPro 9.0
How to: Create Multicolumn List Boxes
See Also

Although the default number of columns in a list box is one, a list box in Visual FoxPro can contain as many columns as you want. A multicolumn list box differs from a grid in that you select a row at a time in a multicolumn list box while you can select individual cells in a grid, and data in the list cannot be directly edited.

To display multiple columns in a list box

  1. Set the ColumnCount property to the number of desired columns.

  2. Set the ColumnWidths Property. For example, if there are three columns in the list box, the following command would set the column widths to 10, 15, and 30, respectively:

    Copy Code
    THISFORM.listbox.ColumnWidths = "10, 15, 30"

  3. Set the RowSourceType Property to 6 - Fields.

  4. Set the RowSource Property to the fields to be displayed in the columns.

    Note:
    For the columns to align correctly, you need to either set the ColumnWidths property or change the FontName Property to a monospaced font. The FirstElement Property of ListBoxes and ComboBoxes is not effective in multi-column lists.

When the RowSourceType of the list is set to 0 - None, you can use the AddListItem method to add items to a multicolumn list box. For example, the following code adds text to specific columns in a list box:

Copy Code
THISFORM.lst1.ColumnCount = 3
THISFORM.lst1.Columnwidths = "100,100,100"
THISFORM.lst1.AddListItem("row1 col1", 1,1)
THISFORM.lst1.AddListItem("row1 col2", 1,2)
THISFORM.lst1.AddListItem("row1 col3", 1,3)
THISFORM.lst1.AddListItem("row2 col2", 2,2)

See Also

Other Resources

Controls for Displaying Lists
Using Controls
Controls and Objects Created in Earlier Versions


How to: Allow Users to Select Multiple Items in a List Box

Visual FoxPro 9.0
How to: Allow Users to Select Multiple Items in a List Box
See Also

The default behavior of a list allows one item at a time to be selected. You can, however, make it possible for a user to select multiple items in a list.

To allow multiple selected items in a list

  • Set the MultiSelect property of the list to true (.T.).

To process the selected items — to copy them to an array or incorporate them elsewhere in your application — loop through the list items and process those for which the Selected Property is true (.T.). The following code could be included in the InteractiveChange event of a list box to display the selected items in a combo box, cboSelected, and the number of selected items in a text box, txtNoSelected:

Copy Code
nNumberSelected = 0  && a variable to track the number
THISFORM.cboSelected.Clear && clear the combo box
FOR nCnt = 1 TO THIS.ListCount
   IF THIS.Selected(nCnt)
      nNumberSelected = nNumberSelected + 1
      THISFORM.cboSelected.Additem (THIS.List(nCnt))
   ENDIF
ENDFOR
THISFORM.txtNoSelected.Value = nNumberSelected

See Also

Other Resources

Controls for Displaying Lists
Using Controls
Controls and Objects Created in Earlier Versions


How to: Allow Users to Add Items to a List Box

Visual FoxPro 9.0
How to: Allow Users to Add Items to a List Box
See Also

You can make it possible for users to add items to a list interactively.

To make it possible for users to add items to a list interactively

  • Use the AddItem method.

In the following example, when the user presses ENTER, the code in the KeyPress event of a text box adds the text in the text box to the list box and clears the text in the text box:

Copy Code
LPARAMETERS nKeyCode, nShiftAltCtrl
IF nKeyCode = 13   && Enter Key
   THISFORM.lstAdd.AddItem(This.Value)
   THIS.Value = ""
ENDIF

You can make it possible for users to enter data in a table from a list. If the ControlSource Property is set to a field, whatever the user selects in the list is written to the table. This is an easy way to help ensure the integrity of the data in your table. While the user can still enter the wrong data, an illegal value cannot be entered.

For example, if you have a list of states or counties for a user to choose from, the user cannot enter an invalid state or county abbreviation.

You can make it possible for users to navigate to a record by picking a value from a list. Often, you want to let users select the record they want to view or edit. For example, you could provide users with a list of customer names. When the user selects a customer from the list, you select that customer's record in the table and display customer information in text boxes on the form. You can do this several ways, depending on the source of data in your form.

RowSourceType Selecting the appropriate record

2 - Alias 6 - Fields

When the user chooses a value in the list, the record pointer is set automatically to the desired record. Issue THISFORM.Refresh in the InteractiveChange event of the list to show the new values in other controls on the form.

0 - None 1 - Value 3 - SQL Statement 4 - QPR 5 - Array

In the InteractiveChange event, select the table that has the record with the desired values, and then search for the desired value. For example, if the RowSource holds customer identification numbers from the customer table, use this code:

Copy Code
SELECT customer
LOCATE FOR THIS.Value = cust_id
THISFORM.Refresh

See Also

Other Resources

Controls for Displaying Lists
Using Controls
Controls and Objects Created in Earlier Versions


How to: Refresh a One-to-Many Display Based on a List Value

Visual FoxPro 9.0
How to: Refresh a One-to-Many Display Based on a List Value
See Also

When the user chooses to go to a record by picking a value in a list, you might have a one-to-many relationship that needs to reflect the changed record pointer in the parent table. You can implement this functionality with both local tables and local or remote views.

For local tables, if the RowSourceType of the list is 2 - Alias or 6 - Fields and the RowSource is a local table with a relationship set in the form's data environment, issue THISFORM.Refresh in the InteractiveChange event when the user chooses a new value. The many sides of the one-to-many relationship automatically displays only the records that match the expression of the parent table involved in the relation.

For views, refreshing a one-to-many display is a little different if the RowSource of the list box is a local or remote view. The following example describes creating a form with a list box and a grid. The list box displays the values from the cust_id field in the TESTDATA!Customer table. The grid displays the orders associated with the cust_id field selected in the list box.

First, in the View Designer create a parameterized view for the orders. When you create the view in the View Designer, set the selection criterion for the foreign key to a variable. In the following example, the variable is called m.cCust_id.

Then, when you design the form, follow the steps in the following procedure. Note that the view requires a value for the parameter that is not available when the form is loaded. By setting the NoDataOnLoad Property of the view cursor object to true (.T.), you prevent the view from being run until the REQUERY( ) Function is called, at which time the user would have selected a value for the variable used in the parameterized view.

To design a one-to-many list based on local or remote views

  1. Add the table and the parameterized view to the data environment.

  2. In the Properties window for the view cursor object in the Data Environment, set the NoDataOnLoad property to true (.T.).

  3. Set the RowSourceType property of the list box to 6 — Fields, and set its RowSource property to the field referenced as the foreign key in the view's parameter.

    In the example, you would set the RowSource property to customer.cust_id.

  4. Set the RecordSource property of the grid to the name of the view you created earlier.

  5. In the InteractiveChange event code of the list box, store the value of the list box to the variable, and then requery the view, as in this example:

    Copy Code
       m.cCust_id = THIS.Value
   *assuming the name of the view is orders_view
   =REQUERY("orders_view")

For more information about local and remote views, see Creating Views.

See Also

Other Resources

Controls for Displaying Lists
Using Controls
Controls and Objects Created in Earlier Versions


How to: Display Child Records in a List

Visual FoxPro 9.0
How to: Display Child Records in a List
See Also

You can display records from a one-to-many relationship in a list so that the list displays the child records in the relationship as the record pointer moves through the parent table.

To display child records in a list

  1. Add a list to the form.

  2. Set the ColumnCount property of the list to the number of columns you want to display.

    For example, if you want to display the Order_id, Order_net, and Shipped_on fields in the list, set the ColumnCount property to 3.

  3. Set the ColumnWidths property to the appropriate widths for displaying your selected fields.

  4. Set the RowSourceType of the list to 3SQL Statement.

  5. Set the RowSource to the SELECT statement. For example, the following statement selects three fields from the orders table for the current record in the customer table:

    Copy Code
    SELECT order_id, order_net, shipped_on from orders ;
   WHERE order.cust_id = customer.cust_id ;
   INTO CURSOR temp

  6. In the Init event of the form and in the code that moves the record pointer through the table, requery the list:

    Copy Code
    THISFORM.lstChild.Requery

See Also

Other Resources

Controls for Displaying Lists
How to: Use Check Boxes to Specify States
Using Controls
Controls and Objects Created in Earlier Versions


How to: Add Pictures to Items in a List

Visual FoxPro 9.0
How to: Add Pictures to Items in a List
See Also

You can display pictures next to items in lists.

To display pictures next to items in a list

  • Set the Picture property to a graphic file for the list box.

For more information, see Picture Property and Graphics Support in Visual FoxPro.

For example, suppose you populate a list box with files and want to display a different graphics file next to each file depending on whether the file is table, a program, or some other file type.

The following code uses the FOR ... ENDFOR command to

displays a different graphics file for each item in the list and appears in the Click event of this list box:

Copy Code
FOR iItem = 5 TO THIS.ListCount      && files start at the 5th item
   cExtension = UPPER(RIGHT(THIS.List(iItem),3))
   DO CASE
      CASE cExtension = "DBF"
         THIS.Picture(iItem) = "tables.bmp"
      CASE cExtension = "BMP"
         THIS.Picture(iItem) = "other.bmp"
      CASE cExtension = "PRG"
         THIS.Picture(iItem) = "programs.bmp"
      CASE cExtension = "SCX"
         THIS.Picture(iItem) = "form.bmp"
      OTHERWISE
         THIS.Picture(iItem) = IIF("]" $ cExtension, ;
            "", "textfile.bmp")
   ENDCASE
ENDFOR

For more information, see Click Event.

See Also

Other Resources

Controls for Displaying Lists
How to: Use Check Boxes to Specify States
Controls for Accepting Input
Using Controls
Controls and Objects Created in Earlier Versions


Controls for Accepting Input

Visual FoxPro 9.0
Controls for Accepting Input

It is difficult to anticipate all the values that a user might need to enter into a control. The following controls make it possible for you to accept user input that cannot be predetermined:

  • Text boxes

  • Edit boxes

  • Combo boxes

In This Section

User Input in Text Boxes

Describes how text boxes make it possible for users to enter or edit data stored in non-memo fields.
User Input in Edit Boxes

Describes how edit boxes make it possible for users to edit text from character fields or memo fields.
User Input in Combo Boxes

Describes how combo boxes make it possible for users to select items from a list or enter new items.
How to: Use Check Boxes to Specify States

Describes how check boxes make it possible for users to specify a Boolean state.
How to: Define User Input Characteristics

Describes how to control the type of input the user enters.
Accepting Numeric Input in a Given Range

Describes how to ensure that users enter values within a specific range.
How to: Set the Number of Option Buttons in an Option Button Group

Describes how to set the number of option buttons that the user can choose from.
Setting Option Button Properties

Describes how to set properties for option buttons.
How to: Store User Choices to a Table Using Option Buttons

Describes how to use option buttons obtain information and store it in a table.

Related Sections

Using Controls

Describes controls you can use to manage interactions between users and your application.
Controls for Displaying Lists

Describes the common uses, methods, and properties of list boxes and drop-down list boxes.
Controls for Displaying Information

Explains various Visual FoxPro controls and objects that can display and order information.
Controls for Manipulating Rows of Data

Describes the common uses, methods, and properties of the Visual FoxPro grid control.
Controls for Allowing Specific Actions

Describes the Visual FoxPro controls that allow users to take specific preprogrammed actions either by user interaction or by timed delay.
Controls for Extending Forms

Describes how the Page Frame object and the use of ActiveX controls can expand the workable area and use of Visual FoxPro forms.


User Input in Text Boxes

Visual FoxPro 9.0
User Input in Text Boxes
See Also

The text box is a basic control that makes it possible for users to add or edit data stored in a non-memo field in a table.

The following table describes some of the tasks you can perform with text boxes by setting the appropriate properties.

Property | Action
SelectOnEntry Property | Select all text when user enters the text box using the keyboard.
InputMask Property | Determine values that can be typed in the text box.
Format Property | Determine how values are displayed in the text box.
Value Property | Reference or change the text displayed in the text box in code.
ControlSource Property | Store the value displayed in the text box in the Value property and in the variable or field specified by the ControlSource property.
AutoComplete Property | Display a dynamic list of previously entered values to chose.
AutoCompTable Property | Specify the table that populates the dynamic list for the text box.
AutoCompSource Property | Specify a field in the auto-completion table to associate with the text box.

The Solution.app file in the Visual FoxPro ...\Samples\Solution directory contains examples of how to use text boxes. After you open Solution.app, in the tree view, click Controls, then Text boxes.

Date Values in Text Boxes

Text boxes have several properties that make it easy for users to enter date values. The following table lists properties you can set to control how dates can be entered in text boxes.

Property | Description
Century | Sets whether the first two digits of the year are displayed or not.
DateFormat | Formats the date in the text box to one of fifteen predetermined formats, such as German or Japanese.
StrictDateEntry | Sets StrictDateEntry to 0 - Loose. This makes it possible for a user to enter dates in more flexible formats than the default 99/99/99.

Validating Data in Text Boxes

You can check or verify values in text boxes by including code inside the Valid event for the text box. If the value in the text box is invalid, return False (.F.) or 0 from the code you use to evaluate the text box value in the Valid event. If the Valid event returns False (.F.), Visual FoxPro displays the message "Invalid input".

Note:
The control does not lose focus if the Valid event returns False (.F.) or 0.

For example, suppose you have a text box in which a user can type an appointment date. You can check that the date has not already passed by including the following example code in the Valid event for the text box:

Copy Code
IF CTOD(THIS.Value) < DATE( )
   = MESSAGEBOX("You need to enter a future date",1)
   RETURN 0
ENDIF

If you want to display your own message, include the WAIT WINDOW command or the MESSAGEBOX( ) function in the Valid event code and return 0. For more information, see WAIT Command and MESSAGEBOX( ) Function.

See Also

Other Resources

Controls for Accepting Input
Controls for Displaying Lists
Controls for Displaying Information
Controls for Manipulating Rows of Data
Controls for Allowing Specific Actions
Controls for Extending Forms


User Input in Edit Boxes

Visual FoxPro 9.0
User Input in Edit Boxes
See Also

You can make it possible for users to edit text from long character fields or memo fields in edit boxes. Edit boxes allow automatic wordwrapping and the ability to move through the text using the arrow keys, page up and page down keys, and scrollbars.

To see examples of using edit boxes, run Solution.app in the Visual FoxPro ...\Samples\Solution directory. In the tree view, click Controls, and then click Edit boxes.

Allowing Users to Edit a Memo Field in an Edit Box

All you have to do to make it possible for a user to edit a memo field in an edit box is set the ControlSource property of the edit box to the memo field. For example, if you have a memo field named comments in a table named log, you can set the ControlSource property of an edit box to log.comments to make it possible for a user to edit the memo field in the edit box.

Allowing Users to Edit a Text File in an Edit Box

You also can make it possible for a user to edit a text file in an edit box. The following form demonstrates this.

An OK button on the form closes the form with the following command in the Click event code:

Copy Code
RELEASE THISFORM

The other two buttons in this example, cmdOpenFile and cmdSave, make it possible for a user to open a text file and save the file after edits.

Code Associated with the Click Event of cmdOpenFile

Code | Comments
CREATE CURSOR textfile ; (filename c(35), mem m) APPEND BLANK | Create a cursor with a character field to hold the name of the text file and a memo field to hold the contents of the text file. Add a blank record to the cursor.
REPLACE textfile.FileName WITH ; GETFILE("TXT") | Use the GETFILE( ) function to return the name of the file to open. Store the name in the FileName field of the cursor.
IF EMPTY(textfile.FileName) RETURN ENDIF | If the user chooses Cancel in the Get File dialog box, the FileName field will be empty and there will be no file to open.
APPEND MEMO mem FROM ; (textfile.FileName) OVERWRITE | Fill the memo field with the text in the file.
THISFORM.edtText.ControlSource = ; "textfile.mem" THISFORM.Refresh | Set the ControlSource of the edit box on the form.
THISFORM.cmdSave.Enabled = .T. | Enable the Save button.

When the file has been opened and edited, the Save button makes it possible for a user to write changes back out to the file.

Code Associated with the Click Event of cmdSave

Code | Comments
COPY MEMO textfile.mem TO ; (textfile.filename) | Overwrites the old value in the file with the text in the memo field.

Manipulating Selected Text in an Edit Box

Edit boxes and text boxes have three properties that make it possible for you to work with selected text: SelLength, SelStart, and SelText.

You can select text programmatically using the SelStart and SelLength properties. For example, the following lines of code select the first word in an edit box.

Copy Code
Form1.edtText.SelStart = 0
Form1.edtText.SelLength = AT(" ", Form1.edtText.Text) - 1
Tip:
When you change the SelStart property, the edit box scrolls to display the new SelStart. If you change the SelStart in a loop, for example when searching for text, your code will execute faster if you include THISFORM.LockScreen = .T. before processing and THISFORM.LockScreen = .F. after processing.

You can access selected text in an edit box or text box with the SelText property. For example, the following line of code makes the selected text all uppercase:

Copy Code
Form1.edtText.SelText = UPPER(Form1.edtText.SelText)

Common Edit Box Properties

The following edit box properties are commonly set at design time.

Property | Description
AllowTabs | Whether the user can insert tabs in the edit box instead of moving to the next control. If you allow tabs, be sure to indicate that users can move to the next control by pressing CTRL+TAB.
HideSelection | Whether selected text in the edit box is visibly selected when the edit box does not have the focus.
ReadOnly | Whether the user can change the text in the edit box.
ScrollBars | Whether there are vertical scrollbars.

See Also

Other Resources

Controls for Accepting Input
Using Controls
EditBox Control


User Input in Combo Boxes

Visual FoxPro 9.0
User Input in Combo Boxes
See Also

The combo box control has the functionality of a list box and a text box. There are two styles for a combo box: Drop-down combo and Drop-down list. Specify which one you want by changing the Style property of the control. Drop-down lists are discussed in Controls for Displaying Lists.

Drop-Down Combo Box

A user can click the button on a drop-down combo box to see a list of choices or enter a new item directly in the box beside the button. The default Style property of a combo box is 0 — Dropdown Combo.

Adding User Items to Drop-Down Combo Box Lists

To add the new user value to the drop-down combo box, you can use the following line of code in the method associated with the Valid event of the combo box:

Copy Code
THIS.AddItem(THIS.Text)

Before adding an item, however, it would be a good idea to check to make sure that the value is not already in the combo box drop-down:

Copy Code
lItemExists = .F. && assume the value isn't in the list.
FOR i = 1 to THIS.ListCount
   IF THIS.List(i) = THIS.Text
      lItemExists = .T.
      EXIT
   ENDIF
ENDFOR

IF !lItemExists
   THIS.AddItem(THIS.Text)
ENDIF

Common Combo Box Properties

The following combo box properties are commonly set at design time.

Property | Description
ControlSource | Specifies the table field where the value that the user chooses or enters is stored.
DisplayCount | Specifies the maximum number of items displayed in the list.
InputMask | For drop-down combo boxes, specifies the type of values that can be typed in.
IncrementalSearch | Specifies whether the control tries to match an item in the list as the user types each letter.
RowSource | Specifies the source of the items in the combo box.
RowSourceType | Specifies the type of the source for the combo box. The RowSourceType values for a combo box are the same as for a List.
Style | Specifies whether the combo box is a drop-down combo or a drop-down list.

See Also

Other Resources

Controls for Accepting Input
ComboBox Control
Using Controls


How to: Use Check Boxes to Specify States

Visual FoxPro 9.0
How to: Use Check Boxes to Specify States
See Also

You can use check boxes to make it possible for a user to specify a Boolean state: True or False, On or Off, Open or Closed. However, there are times when it is not accurate to evaluate something as True or False, such as unanswered questions on a True/False questionnaire.

To see examples of using check boxes

  1. Run Solution.app in the Visual FoxPro ...\Samples\Solution directory.

  2. In the tree view, click Controls, and then click Check boxes.

See Also

Other Resources

Controls for Accepting Input
How to: Add Pictures to Items in a List
CheckBox Control
How to: Define User Input Characteristics
Using Controls
Controls and Objects Created in Earlier Versions


How to: Define User Input Characteristics

Visual FoxPro 9.0
How to: Define User Input Characteristics
See Also

You can define the characteristics of the input that users can type in a control using the InputMask property.

For example, suppose you want to limit user input in a text box to numeric values less than 1,000,000 with two decimal places. You can set the InputMask property of the text box to 999,999.99. The comma (,) and the period (.) display in the text box prior to the user entering any values. If the user presses a character key, the character does not display in the text box. As another example, suppose you have a field in a table that accepts Logical data types and you want the user to type "Y" or "N" but not "T" or "F". You can set the InputMask property of the column to "Y".

Hiding User Input Values

When you want to obtain sensitive information from a user, for example, when the user types a password in a text box, you can prevent the information the user types from displaying on the screen.

To hide user input in a text box

  • Set the TextBox PasswordChar property to the asterisk (*) or another generic character.

If you set the PasswordChar property to anything other than an empty string, the Value and Text properties of the text box contain the actual value that the user typed in the text box, but the text box displays a generic character for every key the user pressed.

See Also

Other Resources

Controls for Accepting Input
Accepting Numeric Input in a Given Range
Using Controls
Controls for Allowing Specific Actions
Controls and Objects Created in Earlier Versions


Accepting Numeric Input in a Given Range

Visual FoxPro 9.0
Accepting Numeric Input in a Given Range
See Also

Although you can set the InputMask property and include code in the Valid event to make sure that numeric values entered into text boxes fall within a given range, the easiest way to check the range of values is to use a spinner.

Using Spinners

You can use spinners to make it possible for users to make choices by "spinning" through values or directly typing the values in the spinner box.

Setting the Range of Values that Users Can Choose

Set the KeyboardHighValue and the SpinnerHighValue properties to the highest number you want users to be able to enter in the spinner.

Set the KeyboardLowValue and the SpinnerLowValue properties to the lowest number you want users to be able to enter in the spinner.

Decrementing a Spinner When the User Clicks the Up Button

Sometimes, if your spinner reflects a value like "priority," you want the user to be able to increase the priority from 2 to 1 by clicking the Up button. To cause the spinner number to decrement when the user clicks the Up button, set the Increment property to -1.

Spinning Through Non-Numeric Values

While the value of a spinner is numeric, you can use the Spinner control and a text box to make it possible for users to spin through multiple types of data. For instance, if you want a user to be able to spin through a range of dates, you could size the spinner so that only the buttons are visible and position a text box beside the spinner buttons. Set the Value property of the text box to a date and in the UpClick and DownClick events of the spinner, increment or decrement the date.

Tip:
You can use the Windows API function GetSystemMetrics to set the width of your spinner so that only the buttons are visible and the buttons are the best width for the up and down arrow bitmap display.

  • Set the spinner's BorderStyle property to 0.

  • Include the following code in the Init of the spinner:

    Copy Code
    DECLARE INTEGER GetSystemMetrics IN Win32api INTEGER
THIS.Width = GetSystemMetrics(2) && SM_CXVSCROLL

Common Spinner Properties

The following spinner properties are commonly set at design time.

Property | Description
Increment | How much to increment or decrement the value each time the user clicks the Up or Down buttons.
KeyboardHighValue | The highest value that can be entered into the spinner text box.
KeyboardLowValue | The lowest value that can be entered into the spinner text box.
SpinnerHighValue | The highest value that the spinner will display when the user clicks the Up button.
SpinnerLowValue | The lowest value that the spinner will display when the user clicks the Down button.

See Also

Other Resources

Controls for Accepting Input
How to: Define User Input Characteristics
Controls for Allowing Specific Actions
Using Controls
Performing Specific Actions at Given Intervals
Controls and Objects Created in Earlier Versions


How to: Set the Number of Option Buttons in an Option Button Group

Visual FoxPro 9.0
How to: Set the Number of Option Buttons in an Option Button Group
See Also

When you create an option button group on a form, two option buttons are included by default. You can determine how many option buttons are in a group by changing the ButtonCount property.

To set the number of option buttons in a group

  • Set the ButtonCount Property to the desired number of option buttons.

    For example, to have a group of six option buttons, set the ButtonCount property of the option button group to 6.

The Value Property of the group indicates which of the buttons has been chosen. For example, if you choos the fourth option button in a group of six option buttons, the value of the option button group is 4.

If the group's ControlSource Property is a character field, or if the Value property is set to a character value before the form is run, the group's Value property is the caption of the selected option button.

See Also

Other Resources

Controls for Accepting Input
Using Controls
Setting Option Button Properties
Controls and Objects Created in Earlier Versions
Controls and Data Concepts
How to: Store User Choices to a Table Using Option Buttons


Setting Option Button Properties

Visual FoxPro 9.0
Setting Option Button Properties
See Also

To manually adjust individual elements of an option button or command button group in the Form Designer, choose Edit from the group's shortcut menu.

You can set properties on individual buttons in the Properties window. You also can set these properties at run time by specifying the name of the option button and the desired property setting. For example, the following line of code, included in the method or event code of some object on the same form as the option button group, sets the caption of optCust in the option button group opgChoices:

Copy Code
THISFORM.opgChoices.optCust.Caption = "Sort by Customer"

You also can set these properties at run time by using the Buttons property and specifying the index number of the option button in the group. For example, if optCust is the third button in the group, the following line of code also sets the caption of optCust:

Copy Code
THISFORM.opgChoices.Buttons(3).Caption = "Sort by Customer"

To set properties on all buttons in a group, use the SetAll method of the group.

For example, the following line of code disables all the buttons in an option button group named opgMyGroup on a form:

Copy Code
THISFORM.opgMyGroup.SetAll("Enabled",.F., "OptionButton")

Enabling and Disabling Buttons in a Group

The previous example shows how to programmatically disable all option buttons in a group. When the buttons are disabled, they are displayed in the colors specified in the DisabledForeColor and DisabledBackColor properties of the option buttons. You could also set the Enabled property of the option button group to false (.F.) to disable the group; however, there would be no visual clue for the user.

Determining Which Option Button Is Currently Selected

You can use the Value property of the option button group to determine which option button in the group is selected. If the control source for the button is numeric, you have five option buttons in a group. If the third button is selected, the Value property of the option button group is 3; if no option buttons are selected, the Value property of the option button group is 0.

You also can determine the caption of the selected option button by using the Value and Buttons properties of the group. For example, the following line of code stores the Caption property of the selected option button to a variable cSelected.

Copy Code
oGroup = THISFORM.opg1
cSelected = oGroup.Buttons(oGroup.Value).Caption

Filtering Lists with Option Buttons

If you have a small set of predetermined table filters, you could use option buttons to make it possible for users to switch between the filters.

The following example assumes a form with a list box (lstCustomers) and an option button group that contains three option buttons.

Property Settings for the List Box

Object | Property | Setting
lstCustomers | RowSourceType | 2 - Alias
lstCustomers | RowSource | Customer

The filters are set in the Click event code of the option buttons.

Event Code for Filtering a List when Users Choose an Option Button

Object Event Code

optAll

Click
Copy Code
SET FILTER TO
GO TOP
THISFORM.lstCustomers.Requery

optCanada

Click
Copy Code
SET FILTER TO customer.country = "Canada"
GO TOP
THISFORM.lstCustomers.Requery

optUK

Click
Copy Code
SET FILTER TO customer.country = "UK"
GO TOP
THISFORM.lstCustomers.Requery

When the user closes the form, do not forget to reset the filter by including SET FILTER TO in the Click event of the closing button or in the Destroy event.

Tip:
To refresh a list when the list source might have changed, use the Requery method.

See Also

Other Resources

Controls for Accepting Input
Using Controls
How to: Set the Number of Option Buttons in an Option Button Group
How to: Store User Choices to a Table Using Option Buttons
Controls and Objects Created in Earlier Versions
Form Designer


How to: Store User Choices to a Table Using Option Buttons

Visual FoxPro 9.0
How to: Store User Choices to a Table Using Option Buttons
See Also

While it is not as common, you can use option buttons to get information from a user to be stored in a table by saving the Caption property. If you have a standardized testing application, for example, you could use option buttons to make it possible for a user to choose among multiple choice options A, B, C, or D. You could also use option buttons to indicate gender in an employee table.

To store the Caption property of an option button to a table

  1. Set the Value property of the option button group to an empty string.

  2. Set the Control property of the option button group to a character field in a table.

For example, if the captions of the option buttons in a group are "A", "B", "C", and "D", and the ControlSource of the option button group is a character field, when a user chooses the button with the caption "B", "B" is stored in the field.

To see an example of a multiple-choice test using option buttons

  1. Run Solution.app in the Visual FoxPro ...\Samples\Solution directory.

  2. In the tree view, click Controls, and then click Options buttons.

  3. Click Present a user with multiple choices.

See Also

Other Resources

Controls for Accepting Input
Setting Option Button Properties
Controls for Displaying Lists
Using Controls
Controls and Objects Created in Earlier Versions
How to: Choose the Type of Data for a List or Combo Box


Controls for Displaying Information

Visual FoxPro 9.0
Controls for Displaying Information
See Also

One of the principles of good design is to make relevant information visible. You can use the following controls to display information to your users:

  • Images

  • Labels

  • Text Boxes

  • Edit Boxes

  • Shapes

Using Images

The Image control makes it possible for you to add pictures (.bmp and other graphics files) to your form. An Image control has the full range of properties, events, and methods that other controls have, so an Image control can be changed dynamically at run time, Users can interact with images by clicking, double-clicking, and so on. For details on valid graphic file types, see Graphics Support in Visual FoxPro.

The following table lists some of the key properties of an Image control.

Property | Description
Picture | The picture (.bmp file) to display.
BorderStyle | Whether there is a visible border for the image.
Stretch | If Stretch is set to 0 – Clip, portions of the picture that extend beyond the dimensions of the Image control are not displayed. If Stretch is set to 1 - Isometric, the Image control preserves the original dimensions of the picture and displays as much of the picture as the dimensions of the Image control will allow. If Stretch is set to 2 - Stretch, the picture is adjusted to exactly match the height and width of the Image control.

Using Labels

Labels differ from text boxes in that they:

  • Cannot have a data source.

  • Cannot be directly edited.

  • Cannot be tabbed to.

You can programmatically change the Caption and Visible properties of labels to tailor the label display to the situation at hand.

Common Label Properties

The following label properties are commonly set at design time.

Property | Description
Caption | The text displayed by the label.
AutoSize | Whether the size of the label is adjusted to the length of the Caption.
BackStyle | Whether the label is Opaque or Transparent.
WordWrap | Whether the text displayed on the label can wrap to additional lines.

Using Text and Edit Boxes to Display Information

Set the ReadOnly property of text and edit boxes to display information that the user can view but not edit. If you only disable an edit box, the user will not be able to scroll through the text.

Using Shapes and Lines

Shapes and lines help you visually group elements of your form together. Research has shown that associating related items helps users to learn and understand an interface, which makes it easier for them to use your application.

The following Shape properties are commonly set at design time.

Property | Description
Curvature | A value between 0 (90 degree angles) and 99 (circle or oval).
FillStyle | Whether the shape is transparent or has a specified background fill pattern.
SpecialEffect | Whether the shape is plain or 3D. This only has an effect when the Curvature property is set to 0.

The following Line properties are commonly set at design time.

Property | Description
BorderWidth | How many pixels wide the line is.
LineSlant | When the line is not horizontal or vertical, the direction of the slant. Valid values for this property are a slash ( / ) and a backslash ( \ ).

Using Form Graphics to Display Information

You can graphically display information on a form by using the following form methods.

Method | Description
Circle | Draws a circular figure or arc on a form.
Cls | Clears graphics and text from a form.
Line | Draws a line on a form.
Pset | Sets a point on a form to a specific color.
Print | Prints a character string on a form.

To see examples that demonstrate form graphics, run Solution.app in the Visual FoxPro ...\Samples\Solution directory. In the tree view, click Forms, and then click Form graphics.

See Also

Other Resources

Performing Specific Actions at Given Intervals
How to: Enhance Control Display
Using Controls
Caption
Controls and Objects Created in Earlier Versions


How to: Enhance Control Display

Visual FoxPro 9.0
How to: Enhance Control Display
See Also

Command buttons, check boxes, and option buttons can display pictures in addition to captions. These controls all have properties that make it possible for you to specify pictures to be displayed on the controls.

Property | Description
DisabledPicture | Display picture on button when button is disabled. If you do not specify a value, Visual FoxPro displays a dimmed picture when the control is disabled.
DownPicture | Display picture on button when button is pressed. If you do not specify value, Visual FoxPro displays the picture with the background colors changed so that the button appears pressed when the button is pressed.
Picture | Display picture displayed on button when button is enabled and not pressed.
PicturePosition | Display picture relative to its caption.
PictureSelectionDisplay | Display picture in the text box of a combo box.

If you do not want a caption displayed with the picture, set the Caption Property to an empty string by deleting the default caption in the property settings box of the Properties Window.

Using Picture Masks

Often, a .bmp picture contains white space you do not want to appear on your controls. A white border around an irregularly shaped image could make your control look bad. To avoid this problem, Visual FoxPro creates a temporary default mask for your picture. White areas are given a transparent attribute so that the underlying color of the button or background shows through. To keep certain white areas of your .bmp white, create a mask for it that will override the default.

To create a mask for a .bmp

  1. Open the .bmp file in Paint or another bitmap utility.

  2. Blacken all areas of the picture that you want to be displayed exactly as they are in the .bmp file. Leave the areas you want to be transparent as white.

  3. Save the file in the same directory and with the same name as the .bmp file but with an .msk extension.

When Visual FoxPro loads a .bmp file specified by the Picture property for a command button, option button, or check box, it looks in the same directory for a matching .msk file. If an .msk file with the same name as the .bmp is in the directory, Visual FoxPro uses it as a mask for the picture. All white areas in the .msk picture are made transparent in the .bmp. All black areas in the .msk picture are displayed exactly as they are in the .bmp.

Note:
The .bmp picture and the .msk picture must have the same dimensions for the mask to be able to represent the area of the .bmp.

See Also

Other Resources

Controls for Displaying Information
Controls for Manipulating Rows of Data
Using Controls
How to: Manually Adjust Grid Display at Design Time
Controls and Objects Created in Earlier Versions


Controls for Manipulating Rows of Data

Visual FoxPro 9.0
Controls for Manipulating Rows of Data

Visual FoxPro provides a very powerful tool — the grid object — for displaying and manipulating multiple rows of data.

In This Section

How to: Use Grid Objects

Describes how to create a Grid control.
How to: Manually Adjust Grid Display at Design Time

Describes how to manually adjust the width and height of rows in a grid.
How to: Set the Source of the Data Displayed in the Grid

Explains how to specify the data source for a Grid control.
How to: Set Up a One-to-Many Form Using the Grid Control

Describes how to display a one-to-many relationship between two tables on a form using Grid controls.
How to: Display Controls in Grid Columns

Describes how to display Visual FoxPro controls, such as text boxes, check boxes, drop-down list boxes, and spinners, in grid columns.
Formatting Grids

Discusses various ways to customize the format for Grid controls.

Related Sections

Using Controls

Describes how controls manage the interactions between users and your application. Visual FoxPro offers a variety of controls to enhance your application interface.
Controls and Data Concepts

Explains the difference between the two kinds of controls you can have on your forms and lists the effects of a ControlSource property setting on different controls.


How to: Use Grid Objects

Visual FoxPro 9.0
How to: Use Grid Objects
See Also

The grid is a container object. Just as a form set can contain forms, a grid can contain columns. In addition, the columns contain headers and controls, each with their own sets of properties, events, and methods, giving you a great deal of control over the elements of the grid.

Container | Can contain
Grid | Columns
Column | Headers, controls

The Grid object makes it possible for you to present and manipulate rows and columns of data in a form or page. A particularly useful application of the Grid control is creating one-to-many forms, such as an invoice form.

To add a Grid control to a form

  • In the Form Controls toolbar, choose the Grid button and drag to size in the Form window.

If you do not specify a RecordSource value for the grid and there is a table open in the current work area, the grid will display all the fields in that table.

By default, a grid control is created when you drag a table onto a form.

To create a grid control

  • Choose any table in the Data Environment, Database Designer, or Project Manager Window and drag it onto a form.

You can override the default and create multiple controls corresponding to the default field type mappings specified for each field in the table. For more information, see How to: Create Controls by Dragging and Dropping Fields or Tables.

Setting the Number of Columns in a Grid

One of the first properties you might want to set for the Grid control is the number of columns.

To set the number of columns in a grid

  1. Select the ColumnCount property in the Property and Methods list.

  2. In the Property box, type the number of columns you want.

If the ColumnCount property is set to - 1 (the default), the grid will contain, at run time, as many columns as there are fields in the table associated with the grid.

Adding Records to a Grid

You can make it possible for users to add new records to a table displayed in a grid by setting the AllowAddNew property of the grid to true (.T.). When the AllowAddNew property is set to true, new records are added to the table when the last record is selected and the user presses the DOWN ARROW key.

If you want more control over when a user adds new records to a table, you can set the AllowAddNew property to false (.F.), the default, and use the APPEND BLANK or INSERT commands to add new records.

To see examples of using grids

  1. Run Solution.app in the Visual FoxPro ...\Samples\Solution directory.

  2. In the tree view, click Controls, and then click Grid.

See Also

Other Resources

Formatting Grids
Controls for Manipulating Rows of Data
How to: Enhance Control Display
How to: Manually Adjust Grid Display at Design Time
Using Controls
How to: Set the Source of the Data Displayed in the Grid
Controls and Objects Created in Earlier Versions


How to: Manually Adjust Grid Display at Design Time

Visual FoxPro 9.0
How to: Manually Adjust Grid Display at Design Time
See Also

When you have added columns to the grid, you can change the width of the columns and the height of the rows. You can manually set the height and width properties of the column and row objects in the Properties window or visually set these properties in grid design mode.

To switch to grid design mode

  1. Choose Edit from the grid's shortcut menu.

    -or-

  2. In the Object box of the Properties window, select a column of the grid.

When you are in grid design mode, a thick border is displayed around the grid. To switch out of grid design mode, select the form or another control.

To adjust the width of the columns in a grid

  1. In grid design mode, position the mouse pointer between grid column headers so that the pointer changes to a bar with arrows pointing left and right.

  2. Select the column and drag until the column is the desired width

    -or-

    Set the column's Width property in the Properties window.

To adjust the height of the rows in a grid

  1. In grid design mode, position the mouse pointer between the first and second buttons on the left side of the Grid control so that the pointer changes to a bar with arrows pointing up and down.

  2. Select the row and drag until the row is the desired height.

    -or-

    Set the column's Height property in the Properties window.

    Tip:
    You can prevent a user from changing the height of the grid rows at run time by setting the AllowRowSizing Property to false (.F.).

See Also

Other Resources

Formatting Grids
Controls for Manipulating Rows of Data
How to: Set the Source of the Data Displayed in the Grid
Using Controls
How to: Set Up a One-to-Many Form Using the Grid Control
Controls and Objects Created in Earlier Versions


How to: Set the Source of the Data Displayed in the Grid

Visual FoxPro 9.0
How to: Set the Source of the Data Displayed in the Grid
See Also

You can set the data source for the grid and for each column individually.

To set the data source for a grid

  1. Select the grid, and then click the RecordSourceType property in the Properties window.

  2. Set the RecordSourceType property to 0 - Table, if you want Visual FoxPro to open the table for you, or 1 - Alias if you want the grid to be populated with the fields in a table that is already open.

  3. Click the RecordSource property in the Properties window.

  4. Type the name of the alias or table to serve as the data source for the grid.

If you want to specify particular fields to be displayed in particular columns, you also can set the data source for a column.

To set the data source for a column

  1. Select the column, and then click the ControlSource property in the Properties window.

  2. Type the name of the alias or table and the field to serve as the source for the values displayed in the column. For example, you can type:

    Copy Code
    Orders.order_id

See Also

Other Resources

Formatting Grids
Controls for Manipulating Rows of Data
How to: Manually Adjust Grid Display at Design Time
How to: Set Up a One-to-Many Form Using the Grid Control
How to: Display Controls in Grid Columns
Using Controls
Controls and Objects Created in Earlier Versions


How to: Set Up a One-to-Many Form Using the Grid Control

Visual FoxPro 9.0
How to: Set Up a One-to-Many Form Using the Grid Control
See Also

One of the most common uses for a grid is to display the child records for a table while text boxes display the data for the parent records. When the user moves through the records in the parent table, the grid displays the appropriate child records.

If you have a data environment for your form that includes a one-to-many relationship between two tables, displaying the one-to-many relationship in the form is very easy.

To set up a one-to-many form with a data environment

  1. Drag desired fields from the parent table in the Data Environment Designer to your form.

  2. Drag the related table from the Data Environment Designer to the form.

In almost all cases, you will want to create a data environment for your form or form set. However, it is not much more complicated to create a one-to-many form without using the Data Environment Designer.

To set up a one-to-many form without creating a data environment

  1. Add text boxes to your form to display the desired fields from the primary table.

  2. Set the ControlSource Property of the text boxes to the primary table.

  3. Add a grid to the form.

  4. Set the RecordSource Property of the grid to the name of the related table.

  5. Set the LinkMaster Property of the grid to the name of the primary table.

  6. Set the ChildOrder Property of the grid to the name of the index tag in the related table that corresponds to the relational expression of the primary table.

  7. Set the RelationalExpr Property of the grid to the expression that joins the related table to the primary table. For example, if the ChildOrder tag is indexed on "lastname + firstname", set RelationalExpr to the same expression.

Either way you set up the one-to-many form, you can add navigation controls to move through the parent table and refresh the form objects. For example, the following code could be included in the Click event of a command button:

Copy Code
SELECT orders && if orders is the parent table
SKIP
IF EOF( )
   GO BOTTOM
ENDIF
THISFORM.Refresh

See Also

Other Resources

Formatting Grids
Controls for Manipulating Rows of Data
How to: Set the Source of the Data Displayed in the Grid
How to: Display Controls in Grid Columns
Using Controls
How to: Make Controls Easier to Use
Controls and Objects Created in Earlier Versions


How to: Display Controls in Grid Columns

Visual FoxPro 9.0
How to: Display Controls in Grid Columns
See Also

In addition to displaying field data in a grid, you can have controls in the columns of a grid so that you can present a user with embedded text boxes, check boxes, drop-down list boxes, spinners, and other controls. For example, if you have a logical field in a table, when you run the form, a user can tell which record values are true (.T.) and which record values are false (.F.) by seeing whether the check box is set. Changing the value is as easy as setting or clearing the check box.

You can add controls to grid columns interactively in the Form Designer or write code to add the controls to the columns at run time.

To interactively add controls to a grid column

  1. Add a grid to a form.

  2. In the Properties window, set the ColumnCount property of the grid to the number of desired columns.

    For example, type 2 for a two-column grid.

  3. In the Properties window, select the parent column for the control from the Object box.

    For example, select Column1 to add a control to Column1. The border of the grid changes to indicate that you are editing a contained object when you select the column.

  4. Select the desired control on the Form Controls toolbar and click in the parent column.

    The new control will not be displayed in the grid column in the Form Designer, but it will be visible at run time.

  5. In the Properties window, make sure the control is displayed indented under the parent column in the Object box.

    If the new control is a check box, set the Caption property of the check box to " " and the Sparse property of the column to false (.F.).

  6. Set the ControlSource property of the parent column to the desired table field.

    For example, the ControlSource of the column in the following illustration is products.discontinu from Testdata.dbc in the Visual FoxPro ...\Samples\Data directory.

  7. Set the CurrentControl property of the parent column to the new control.

When you run the form, the control is displayed in the grid column.

Tip:
If you want to be able to center a check box in a grid column, create a container class, add a check box to the container class, and adjust the position of the check box in the container class. Add the container class to the grid column and set the ControlSource of the check box to the desired field.

To remove controls from grid columns in the Form Designer

  1. In the Object box of the Properties window, select the control.

  2. Activate the Form Designer.

    If the Properties window is visible, the control name is displayed in the Object box.

  3. Press the DELETE key.

You also can add controls to a grid column using the AddObject method in code.

To programmatically add controls to a grid column

  • In the Init event of the grid, use the AddObject method to add the control to the grid column and set the CurrentControl property of the column.

For example, the following lines of code in the Init event of a grid add two controls to a grid column and specify one of them as the current control:

Copy Code
THIS.grcColumn1.AddObject("spnQuantity", "SPINNER")
THIS.grcColumn1.AddObject("cboQuantity", "COMBOBOX")
THIS.grcColumn1.CurrentControl = "spnQuantity"
* The following lines of code make sure the control is visible
* and is diplayed in every row in the grid
THIS.grcColumn1.spnQuantity.Visible = .T.
THIS.grcColumn1.Sparse = .F.

In this example, Column1 has three possible current control values:

  • spnQuantity

  • cboQuantity

  • Text1 (the default control)

    Note:
    Properties set on the Grid level are not passed on to the columns or headers. In the same way, you must set properties of the headers and contained controls directly; they do not inherit their properties from settings at the Column level.

    Tip:
    For the best display of combo boxes in grid columns, set the following combo box properties:

    Copy Code
    BackStyle = 0      && Transparent
Margin = 0
SpecialEffect = 1 && Plain
BorderStyle = 0      && None

See Also

Other Resources

Formatting Grids
Controls for Manipulating Rows of Data
How to: Set Up a One-to-Many Form Using the Grid Control
How to: Make Controls Easier to Use
Using Controls
Controls for Extending Forms
Form Designer
Controls and Objects Created in Earlier Versions


Formatting Grids

Visual FoxPro 9.0
Formatting Grids
See Also

You can customize the format for grids in various ways.

Using Conditional Formatting in Grids

Special formatting in a grid can make it easier for a user to scan through the records in the grid and locate certain information. To provide conditional formatting, use the dynamic font and color properties of a column.

For example, you can add a grid to a form and set the ColumnCount property to 2. Set the ControlSource property of the first column to orders.to_name and the ControlSource property of the second column to orders.order_net. To display order totals less than 500.00 with a forecolor of black and order totals greater than or equal to 500.00 with a foreground color of red, include the following line in the grid's Init event code:

Copy Code
THIS.Column2.DynamicForeColor = ;
   "IIF(orders.order_net >= 500, RGB(255,0,0), RGB(0,0,0))"

Common Grid Properties

The following grid properties are commonly set at design time.

Property | Description
ChildOrder | The foreign key of the child table that is joined with the primary key of the parent table.
ColumnCount | Number of columns. If ColumnCount is set to - 1, the grid has as many columns as there are fields in the grid's RecordSource.
LinkMaster | The parent table for child records displayed in the grid.
RecordSource | The data to be displayed in the grid.
RecordSourceType | Where the data displayed in the grid comes from: a table, an alias, a query, or a table selected by the user in response to a prompt.

Common Column Properties

The following column properties are commonly set at design time.

Property | Description
ControlSource | The data to be displayed in the column. This is often a field in a table.
Sparse | If Sparse is set to true (.T.), controls in a grid are displayed as controls only when the cell in the column is selected. Other cells in the column display the underlying data value in a text box. Setting Sparse to true (.T.) allows faster repainting if a user is scrolling through a grid with a lot of displayed rows.
CurrentControl | Which control in the grid is active. The default is Text1, but if you add a control to the column, you can specify it as the CurrentControl.
Note:
The ReadOnly property of a control inside the column is overridden by the ReadOnly property of the Column. If you set the ReadOnly property of the control in a column in the code associated with the AfterRowColChange event, the new setting will be valid while you are in that cell.

See Also

Other Resources

Controls for Manipulating Rows of Data
How to: Set Up a One-to-Many Form Using the Grid Control
How to: Make Controls Easier to Use
Using Controls
Controls for Extending Forms
Form Designer
Controls and Objects Created in Earlier Versions


Controls for Allowing Specific Actions

Visual FoxPro 9.0
Controls for Allowing Specific Actions
See Also

Frequently, you want to make it possible for users to take specific actions that have nothing to do with manipulating values. For example, you can make it possible for a user to close a form, open another form, move through a table, save or cancel edits, run a report or query, jump to an address of a destination on the Internet or an intranet, or any number of other actions.

Using Command Buttons and Command Button Groups

One of the most common places to put the code for specific actions is the Click event of a command button.

Making a Command Button the Default Choice

Set the Default property to true (.T.) to make the command button the default choice. The default choice has a thicker border than other command buttons. If a command button is the default choice, when the user presses ENTER, the Click event of the command button executes.

Note:
If the selected object on a form is an edit box or a grid, the code associated with the Click event of the default choice is not executed when the user presses ENTER. Pressing ENTER in an edit box adds a carriage return and line feed to the value in the edit box. Pressing ENTER in a grid selects an adjacent field. To execute the Click event of the default button, press CTRL+ENTER.

Common Command Button Properties

The following command button properties are commonly set at design time.

Property | Description
Cancel | Specifies that the code associated with the Click event of the command button executes when a user presses ESC.
Caption | Text displayed on the button.
DisabledPicture | The .bmp file displayed when the button is disabled.
DownPicture | The .bmp file displayed when the button is pressed.
Enabled | Whether the button can be chosen.
Picture | The .bmp file displayed on the button.

You also can include command buttons in a group so that you can manipulate them individually or as a group.

Managing Command Button Choices at the Group Level

If you want to work with a single method procedure for all the code for the Click events of command buttons in a group, you can attach the code to the Click event of the command button group. The Value property of the command button group indicates which of the buttons was clicked, as demonstrated in the following code example:

Copy Code
DO CASE
   CASE THIS.Value = 1
      WAIT WINDOW "You clicked " + THIS.cmdCommand1.Caption NOWAIT
      * do some action
   CASE THIS.Value = 2
      WAIT WINDOW "You clicked " + THIS.cmdCommand2.Caption NOWAIT
      * do some other action
   CASE THIS.Value = 3
      WAIT WINDOW "You clicked " + THIS.cmdCommand3.Caption NOWAIT
      * do a third action
ENDCASE
Note:
If the user clicks in the command button group but not on a particular button, the Value property still reflects the last command button that was selected. If you have written code for the Click event of a particular button in the group, that code is executed rather than the group Click event code when the user chooses that button.

Common Command Button Group Properties

The following command button group properties are commonly set at design time.

Property | Description
ButtonCount | Number of command buttons in the group.
BackStyle | Whether the command button group has a transparent or opaque background. A transparent background appears to be the same color that the underlying object, usually the form or a page, is.

Using the Hyperlink Object

You can use the Hyperlink object to jump to an address of a destination on the Internet or an intranet. The Hyperlink object can be used to start a hyperlink aware application, typically an Internet browser such as the Microsoft Internet Explorer, and open the page specified in the address. The Hyperlink NavigateTo( ) method makes it possible for you to specify the address of the destination that you jump to.

For example, to navigate to the Microsoft Internet site on the World Wide Web from a form, first add the Hyperlink control to the form. Add a command button to the form, and then add the following code to the Click event for the command button:

Copy Code
THISFORM.Hyperlink1.NavigateTo('www.microsoft.com')

When the form is run, you can click the command button to jump to the Microsoft Web site.

See Also

Other Resources

Accepting Numeric Input in a Given Range
Performing Specific Actions at Given Intervals
Using Controls
Controls and Objects Created in Earlier Versions
Controls for Displaying Information


Performing Specific Actions at Given Intervals

Visual FoxPro 9.0
Performing Specific Actions at Given Intervals
See Also

The Timer control makes it possible for you to perform actions or check values at specific intervals.

Using the Timer Control

Timer controls respond to the passage of time independent of user interaction, so you can program them to take actions at regular intervals. A typical use is checking the system clock to see if it is time to do a particular task. Timers are also useful for other kinds of background processing.

To see examples of using timers, run Solution.app in the Visual FoxPro ...\Samples\Solution directory. In the tree view, click Controls, and then click Timer.

Each timer has an Interval property, which specifies the number of milliseconds that pass between one timer event and the next. Unless disabled, a timer continues to receive an event (appropriately named the Timer event) at roughly equal intervals of time. The Interval property has a few limitations to consider when you are programming a timer:

  • The interval can be between 0 and 2,147,483,647, inclusive, which means that the longest interval is about 596.5 hours (over 24 days).

  • The interval is not guaranteed to elapse exactly on time. To ensure accuracy, the timer should check the system clock when it needs to, rather than try to keep track of accumulated time internally.

  • Although the Interval property is measured in milliseconds, the actual interval is dependent on the system timer. For example, on Windows XP or later, a one millisecond interval can trigger 1000 events per second. On operating systems prior to Windows XP, the system generates 18 clock ticks per second so even though the Interval property is measured in milliseconds, the true precision of an interval is no more than one-eighteenth of a second. For more information on system timers and timer tick, refer to the online MSDN reference.

  • If your application or another application is making heavy demands on the system — such as long loops, intensive calculations, or disk, network, or port access — your application might not get timer events as often as the Interval property specifies.

Placing a Timer Control on a Form

Placing a Timer control on a form is like drawing any other control: you choose the Timer control on the Form Controls toolbar and click and drag on the form.

The timer appears on the form at design time so you can select it, view its properties, and write an event procedure for it. At run time, a timer is invisible and its position and size are irrelevant.

Initializing a Timer Control

A Timer control has two key properties.

Property | Setting
Enabled | If you want the timer to start working as soon as the form loads, set to true (.T.). Otherwise, leave this property set to false (.F.). You can choose to have an outside event (such as a click of a command button) start operation of the timer.
Interval | Number of milliseconds between timer events.

The Enabled property for the timer is different than for other objects. With most objects, the Enabled property determines whether the object can respond to an event caused by the user. With the Timer control, setting Enabled to false (.F.) suspends timer operation.

Remember that the Timer event is periodic. The Interval property does not determine "how long" as much as it determines "how often." The length of the interval should depend on how much precision you want. Because there is some built-in potential for error, make the interval one-half the desired amount of precision.

Note:
The more often a timer event is generated, the more processor time is consumed in responding to the event. This can slow down overall performance. Do not set a particularly small interval unless you need it.

Responding to the Timer Event

When a Timer control's interval elapses, Visual FoxPro generates the Timer event. Typically, you respond to this event by checking some general condition, such as the system clock.

A digital clock is a very simple but highly useful application involving a Timer control. When you understand how the application works, you can enhance it to work as an alarm clock, stopwatch, or other timing device.

The digital clock application includes a timer and a label with a border. At design time, the application looks like this:

At run time, the timer is invisible.

Control | Property | Setting
lblTime | Caption |
Timer1 | Interval | 500 (half a second)
Timer1 | Enabled | True

The sole procedure in the application is the Timer event procedure:

Copy Code
IF THISFORM.lblTime.Caption != Time()
   THISFORM.lblTime.Caption = Time()
ENDIF

The Interval property for the timer is set to 500, following the rule of setting the Interval to half of the shortest period you want to distinguish (one second in this case). This might cause the timer code to update the label with the same time twice in one second. This could cause some visible flicker, so the code tests to see if the time is different from what is displayed in the label before it changes the caption.

See Also

Other Resources

Controls for Allowing Specific Actions
Controls for Displaying Information
Using Controls
How to: Enhance Control Display
Controls and Objects Created in Earlier Versions


Controls for Extending Forms

Visual FoxPro 9.0
Controls for Extending Forms
See Also

Page frames make it possible for you to extend the surface area of your forms, and ActiveX controls make it possible for you to extend the functionality of your forms.

Using Page Frames

A page frame is a container object that contains pages. Pages in turn contain controls. Properties can be set at the page frame, page, or control level.

To see examples of using page frames

  1. Run Solution.app in the Visual FoxPro ...\Samples\Solution directory.

  2. In the tree view, click Controls, and then click Page frame.

You can think of the page frame as a three-dimensional container that presents layered pages. Only controls on the top page (or on top of the page frame) can be visible and active.

The page frame defines the location of the pages and the amount of the page that is visible. The upper-left corner of a page is anchored to the upper-left corner of the page frame. Controls can be placed on pages that are beyond the dimensions of the page frame. These controls are active, but are not visible unless you programmatically change the Height and Width properties of the page frame to make the controls visible.

Using Pages in an Application

With page frames and pages, you can create tabbed forms or dialog boxes with the same kind of interface capabilities that you see in the Project Manager.

In addition, page frames make it possible for you to define a region of the form where you can easily swap controls in and out. For example, in Wizards, most of the form remains constant, but an area of the form changes with each step. Instead of creating five forms for the wizard steps, you could create one form with a page frame and five pages.

Solution.app, in the Visual FoxPro ...\Samples\Solution directory, contains two page frame examples that demonstrate using frames with and without tabs.

Adding Page Frames to a Form

You can include one or more page frames on any form.

To add a page frame to a form

  1. In the Form Controls toolbar, choose the Page Frame button and drag to size in the Form window.

  2. Set the PageCount property to indicate the number of pages to include in the frame.

  3. From the frame's shortcut menu, choose Edit to activate the frame as a container. The page frame border widens to indicate that it is active.

  4. Add controls the same way you would add them to a form.

    Note:
    Like other container controls, you must select the page frame and choose Edit from the right mouse menu, or select the container in the Object drop-down list in the Properties window, so that the container is selected (has a wider border) before you add controls to the page you are designing. If you do not activate the page as a container before adding controls, the controls will be added to the form instead of the page, even though they might appear to be on the page.
To select a different page in the page frame

  1. Activate the page frame as a container by right-clicking it and choosing Edit.

  2. Select the tab of the page you want to use.

    -or-

  • Select the page in the Object box in the Properties window.

    -or-

  • Select the page in the Page box at the bottom of the Form Designer.

Adding Controls to a Page

When you add controls to a page, they are visible and active only when their page is active.

To add controls to a page

  1. In the Object box of the Properties window, select the page. A border appears around the page frame indicating that you can manipulate contained objects.

  2. In the Form Controls toolbar, choose the control button you want and drag to size in the page.

Managing Long Captions on Page Tabs

If the captions on your tabs are longer than can be displayed on the tab given the width of the page frame and the number of pages, you have two options:

  • Set the TabStretch property to 1 - Single Row to show only the characters of the captions that will fit on the tabs. Single Row is the default.

  • Set the TabStretch property to 0 - Multiple Rows to stack the tabs so that the entire caption on all the tabs is visible.

Changing Pages Programmatically

Whether a page frame is displayed with tabs or not, you can programmatically make a page active by using the ActivePage property. For example, the following code in the Click event procedure of a command button on a form changes the active page of a frame page on the form to the third page:

Copy Code
THISFORM.pgfOptions.ActivePage = 3

Common Page Frame Properties

The following page frame properties are commonly set at design time.

Property | Description
Tabs | Whether tabs are visible for the pages.
TabStyle | Whether or not the tabs are all the same size and together the same width as the page frame.
PageCount | The number of pages in the page frame.

See Also

Reference

ActiveX Controls Overview

Other Resources

How to: Make Controls Easier to Use
How to: Manipulate Objects with OLE Container Control and OLE Bound Control
Using Controls
Controls and Objects Created in Earlier Versions


ActiveX Controls Overview

Visual FoxPro 9.0
ActiveX Controls Overview
See Also

ActiveX controls (.ocx files) are installed by default when you install Visual FoxPro. You can distribute ActiveX controls with your applications. ActiveX controls are added to a form in an application by using the Visual FoxPro OLE container control.

The following table lists the .ocx files that are installed with Visual FoxPro and the ActiveX controls contained in each file.

Note:
Help files for these ActiveX controls are available when MSDN is installed.

File | Controls
MSCOMCt2.ocx | Animation control DateTimePicker control FlatScrollBar control MonthView control UpDown control
MCI32.ocx | Multimedia MCI control
MSChrt20.ocx | MsChart control
MSCOMCtl.ocx | ImageCombo control ImageList control ListView control ProgressBar control Slider control StatusBar control TabStrip control Toolbar control TreeView control
MSCOMM32.ocx | MSComm control
MSInet.ocx | Microsoft Internet Transfer control
MSMapi32.ocx | MAPIMessages control MAPISession control
MSMask32.ocx | Masked Edit control
MSWinsck.ocx | Winsock control
Picclp32.ocx | PictureClip control
Richtx32.ocx | RichTextBox control
Sysinfo.ocx | SysInfo control
Note:
In earlier versions of Visual FoxPro, the file containing the ActiveX controls was renamed from Comctl32.ocx to MSCOMCtl.ocx. Even though Visual FoxPro upgraded to the MSCOMCtl.ocx file, older forms with these controls still reference the older file because the ActiveX control is bound by its OleClass property. ActiveX controls from the older COMCtl32.ocx file have a version of 1. For example, the OleClass property for a ListView control on an earlier form would say:

Copy Code
COMCTL.ListViewCtrl.1

Newer ActiveX controls in the Mscomctl.ocx file have a version 2 (or higher). For example:

Copy Code
COMCTL.TreeViewCtrl.2

Visual FoxPro does not automatically upgrade your control, so it is important to know which version of an ActiveX control a form uses when distributing your applications.

See Also

Other Resources

Controls for Extending Forms
Sharing Information and Adding OLE
Controls Tab, Options Dialog Box
OLE Container Control


How to: Manipulate Objects with OLE Container Control and OLE Bound Control

Visual FoxPro 9.0
How to: Manipulate Objects with OLE Container Control and OLE Bound Control
See Also

You add an OLE object to a form by clicking the OLE Container Control tool and dragging it to size in the Form window. This tool can represent a server object such as Microsoft Excel or Word, or it can represent an ActiveX control if your Windows SYSTEM directory contains ActiveX controls (files with an .ocx extension). For general information about ActiveX controls, see Sharing Information and Adding OLE.

OLE Bound Control

You can create a bound OLE object on a form by clicking this tool and dragging it to size in the Form window. After creating the object, you connect it to a General field in a table. Then, you use the object to display the contents of the field. For example, if you store Word documents in a General field, you can display the contents of these documents by using a bound OLE object on a form.

To create a bound OLE object

  1. Create or open a form.

  2. In the Form Controls toolbar, choose the OLE Bound Control button and drag it to size on the form.

  3. Bind the OLE object to a General field by setting the object's ControlSource property.

For an example of using the OLE Bound control, see Sharing Information and Adding OLE.

See Also

Other Resources

Controls for Extending Forms
How to: Make Controls Easier to Use
How to: Display Controls in Grid Columns
Using Controls
Controls and Objects Created in Earlier Versions


Controls and Data Concepts

Visual FoxPro 9.0
Controls and Data Concepts
See Also

You can have two types of controls on your forms: controls that are bound to data and controls that are not. When users interact with bound controls, the values that they enter or choose are stored in the data source, which can be a table field, a cursor field, or a variable. You bind a control to data by setting its ControlSource property, or, in the case of grids, its RecordSource property.

If you do not set the ControlSource property of a control, the value that the user enters or chooses in the control is only stored as a property setting. The value is not written to disk or stored in memory beyond the lifetime of the control.

Effect of ControlSource Property Setting on Controls

Control Effect

Check box

If ControlSource is a field in a table, then NULL values, logical values true (.T.) or false (.F.), or numeric values 0, 1, or 2 in the ControlSource field cause the check box to be selected, cleared, or grayed as the record pointer moves through the table.

Column

If ControlSource is a table field, the user is directly editing the field when editing values in the column. To bind an entire grid to data, set the RecordSource property of the grid.

List box or Combo box

If ControlSource is a variable, the value the user chooses in the list is stored in the variable. If the ControlSource is a field in a table, the value is stored in the field at the record pointer. If an item in the list matches the value of the field in the table, the item is selected in the list when the record pointer moves through the table.

Option button

If ControlSource is a numeric field, 0 or 1 is written to the field, depending on whether or not the button is chosen.

If ControlSource is logical, .T. or .F. is written to the field, depending on whether the button is chosen. If the record pointer moves in the table, the value of the option button is updated to reflect the new value in the field.

If ControlSource of the option button's OptionGroup control (not the option button itself) is a character field, the caption of the option button is stored to the field if the option button is chosen. Note that the control source for an option button (as distinct from an OptionGroup control) cannot be a character field, or Visual FoxPro will report a data type mismatch when the form is run.

Spinner

The spinner reflects and writes numeric values to the underlying field or variable.

Text box or Edit box

The value in the table field is displayed in the text box. Changes the user makes to this value are written back to the table. Moving the record pointer affects the Value property of the text box.

See Also

Other Resources

Using Controls
How to: Create Controls by Dragging and Dropping Fields or Tables
How to: Set the Number of Option Buttons in an Option Button Group
Setting Option Button Properties


How to: Create Controls by Dragging and Dropping Fields or Tables

Visual FoxPro 9.0
How to: Create Controls by Dragging and Dropping Fields or Tables
See Also

You can specify the type of control that is created when you drag a field or table onto a form. For example, you can create a text box control any time a Character field is dragged onto a form.

To map field types to classes

  1. From the Tools menu, choose Options.

  2. Select the Field Mapping tab.

  3. To change a field type mapping, select a line in the Map fields to classes for drag and drop area and choose Modify.

  4. In the Modify Field Mapping dialog box, select a field type from the Type list.

    To set the class that is created whenever you drag a table or multiple fields, select Multiple from the Type list.

  5. To select the class library (.vcx file) that contains the control you want to associate with the selected field type, choose Browse.

  6. Select a class name from the Name list. The class you specify here will be created any time a field of the selected type is dragged onto a form.

  7. Choose OK to accept the mapping.

  8. Set options in the Database options area:

    To... Select...

    Create a label in addition to the bound control when you drag a field or table to a form or container

    Drag and drop field caption

    Set the Comment property of the bound control to the text specified in the Field Comment box in the Fields tab of the Table Designer

    Copy field comment

    Set the InputMask property of the bound control to the input mask specified in the Fields tab of the Table Designer

    Copy field input mask

    Set the Format property of the bound control to the format specified in the Fields tab of the Table Designer

    Copy field format
Note:
You also can specify classes for dragging and dropping in the Display Class box in the Fields tab of the Table Designer. The settings in the Table Designer override the settings you specify here.

Quickly Creating a Single Control

You can quickly create a single control based on the field type mapping you specified on the Field Mapping tab in the Options dialog box. You also can override the default mapping and create a different class type.

To create a single control

  • Click on any field in the Data Environment and drag it onto a form.

    Note:
    The ControlSource property of the newly created control is set to the Name property of the field.

To create a single control and override the current field mapping

  1. Right-click on any field in the Data Environment and drag it onto a form.

  2. From the shortcut menu, select Create Other Control Here.

  3. In the Open dialog box, choose a Visual Class Library (.vcx) file.

  4. Select the type of control you want to create from the Class Name box and choose Open.

Quickly Creating Multiple Controls

You can drag an entire table onto a form. By default, a grid control is created when you drag a table onto a form. You can override the default and create multiple controls corresponding to the default field type mappings specified for each field in the table.

To create a grid control

  • Choose any table in the Data Environment, Database Designer, or Project Manager and drag it onto a form.

To create multiple controls

  1. Right-click any table, or two or more highlighted fields in a table, in the Data Environment, Database Designer, or Project Manager, and drag it onto a form.

  2. From the shortcut menu, select Create Multiple Controls Here.

See Also

Other Resources

Controls and Data Concepts
How to: Add Controls to a Wizard-Generated Form
How to: Create a New Form
How to: Create Forms with Local and Remote Data
How to: Add Visual FoxPro Controls to a Form
Data Environment Designer
Creating Forms


Creating Drag-and-Drop Controls

Visual FoxPro 9.0
Creating Drag-and-Drop Controls
See Also

When you design Visual FoxPro applications, you can drag text, files, and objects from the Component Gallery, Project Manager, the Database Designer, and the Data Environment Designer to desired locations on forms and reports. The drag-and-drop features in Visual FoxPro make it possible for you to extend this ability to the user at run time.

This drag-and-drop capability extends to multiple-form operations. The user can drag text, files, and controls anywhere on the screen, including other forms.

Two types of drag-and-drop functionality are supported in Visual FoxPro: OLE drag-and-drop and control drag-and-drop. OLE drag-and-drop makes it possible for you to move data between other applications that support OLE drag-and-drop (such as Visual FoxPro, Visual Basic, the Windows Explorer, Microsoft Word and Excel, and so on). In a distributed Visual FoxPro application, you can move data between controls in the application, or between controls and other Window applications that support OLE drag-and-drop.

Control drag-and-drop makes it possible for you to drag Visual FoxPro controls within your Visual FoxPro applications. Control drag-and-drop is also supported in earlier versions of Visual FoxPro. As the user drags a control, Visual FoxPro provides a gray outline that is the same size as the object and moves with the mouse pointer. You can override this default behavior by specifying a cursor file (.cur) for the DragIcon property of a control.

This section describes control drag-and-drop. For more information about OLE drag-and-drop, see OLE Drag-and-Drop.

To see examples of control drag-and-drop, run Solution.app in the Visual FoxPro ...\Samples\Solution directory. In the tree view, click Controls, and then click General.

Note:
Dragging a control at run time does not change its location automatically. You can do this, but you must program the relocation yourself, as described in the section, "Causing Control Movement in a Drag-and-Drop Operation." Often, dragging is used only to indicate that some action should be performed; the control retains its original position after the user releases the mouse button.

You can specify both the meaning of a drag operation and how to initiate dragging (if at all) for any given control by using the following drag-and-drop properties, events, and method.

To | Use this feature
Enable automatic or manual dragging of a control. | DragMode property
Specify what icon is displayed when the control is dragged. | DragIcon property
Recognize when a control is dropped onto the object. | DragDrop event
Recognize when a control is dragged over the object. | DragOver event
Start or stop manual dragging. | Drag method

All visual controls can be dragged at run time and all controls share the properties listed in the preceding table. Forms recognize the DragDrop and DragOver events, but they do not have DragMode and DragIcon properties.

Enabling Automatic Drag Mode

To make it possible for the user to drag a control whenever the user clicks the control, set its DragMode property to 1. This enables automatic dragging of the control. When you set dragging to Automatic, dragging is always on.

Note:
While an automatic drag operation is taking place, the control being dragged does not recognize other mouse events.

Responding When the User Drops the Object

When the user releases the mouse button after dragging a control, Visual FoxPro generates a DragDrop event. You can respond to this event in many ways. You can relocate the control at the new location (indicated by the last position of the gray outline). Remember that the control does not move automatically to the new location.

Two terms are important when discussing drag-and-drop operations — source and target.

Term | Meaning
Source | The control being dragged.
Target | The object onto which the user drops the control. This object, which can be a form or control, recognizes the DragDrop event.

A control becomes the target if the mouse position is within its borders when the button is released. A form is the target if the pointer is in a blank portion of the form.

The DragDrop event receives three parameters: oSource, nXCoord, and nYCoord. The parameter oSource is a reference to the control that was dropped onto the target. The parameters nXCoord and nYCoord contain the horizontal and vertical coordinates, respectively, of the mouse pointer within the target.

Because oSource is an object, you use it just as you would a control — you can refer to its properties or call one of its methods. For example, the following statements in the code associated with the DragDrop event checks to see whether the user has dropped a control on itself:

Copy Code
LPARAMETERS oSource, nXCoord, nYCoord
IF oSource.Name != THIS.Name
   * Take some action.
ELSE
   * Control was dropped on itself.
   * Take some other action.
ENDIF

All possible control types for oSource have a Visible property. Therefore, you can make a control invisible when it is dropped on a certain part of a form or on another control. The following line in the code associated with the DragDrop event of an Image control causes a dragged control to disappear when it is dropped on the image:

Copy Code
LPARAMETERS oSource, nXCoord, nYCoord
oSource.Visible = .F.

Indicating Valid Drop Zones

When you enable drag-and-drop functionality, you can help your users by including visual clues about where a user can and cannot drop a control. The best way to do this is to change the DragIcon of the source in the code associated with the DragOver event.

The following code in the DragOver event of a control indicates to a user that the control is not a valid drop target. In this example, cOldIcon is a user-defined property of the form.

Copy Code
LPARAMETERS oSource, nXCoord, nYCoord, nState
DO CASE
   CASE nState = 0 && Enter
      THISFORM.cOldIcon = oSource.DragIcon
      oSource.DragIcon = "NODROP01.CUR"
   CASE nState = 1 && Leave
      oSource.DragIcon = THISFORM.cOldIcon
ENDCASE

Controlling When Dragging Starts or Stops

Visual FoxPro has a setting of Manual for the DragMode property that gives you more control than the Automatic setting. The Manual setting makes it possible for you to specify when a control can and cannot be dragged. (When DragMode is set to Automatic, the control can always be dragged as long as the setting is n'ot changed.)

For instance, you might want to enable dragging in response to MouseDown and MouseUp events, or in response to a keyboard or menu command. The Manual setting also makes it possible for you to recognize a MouseDown event before dragging starts, so that you can record the mouse position.

To enable dragging from code, leave DragMode in its default setting (0 - Manual). Then use the Drag method whenever you want to begin or stop dragging an object.

If nAction is 1, the Drag method initiates dragging of the control. If nAction is 2, the control is dropped, causing a DragDrop event. The value 0 for nAction cancels the drag. The effect is similar to giving the value 2, except that no DragDrop event occurs.

Note:
To enable a drag and drop operation from a list box, the best place to call the Drag method is in the code associated with the MouseMove event of the source list box, after determining that the mouse button is down. For an example, see Lmover.scx in the Visual FoxPro ...\Samples\Solution\Controls\Lists directory.

Causing Control Movement in a Drag-and-Drop Operation

You might want the source control to change position after the user releases the mouse button. To make a control move to the new mouse location, use the Move method. For example, the following code in the DragDrop event of a form moves the control that is dragged to the location of the drop:

Copy Code
LPARAMETERS oSource, nXCoord, nYCoord
oSource.Move(nXCoord, nYCoord)

This code might not produce precisely the effects you want, because the upper-left corner of the control is positioned at the mouse location. The following code positions the center of the control at the mouse location:

Copy Code
LPARAMETERS oSource, nXCoord, nYCoord
oSource.Move ((nXCoord – oSource.Width / 2), ;
   (nYCoord – oSource.Height / 2))

The code works best when the DragIcon property is set to a value other than the default (the gray rectangle). When the gray rectangle is being used, the user normally wants the control to move precisely into the final position of the gray rectangle. To do this, record the initial mouse position within the source control. Then use this position as an offset when the control is moved. For an example, see Ddrop.scx in the Visual FoxPro...\Samples\Solution\Forms directory.

To record the initial mouse position

  1. Specify manual dragging of the control.

  2. Declare two form-level variables, nDragX and nDragY.

  3. Turn on dragging when a MouseDown event occurs. Also, store the value of nXCoord and nYCoord in the form-level variables in this event.

  4. Turn dragging off when the MouseUp event occurs.

See Also

Other Resources

OLE Drag-and-Drop
How to: Implement Intrinsic and Manual OLE Drag-and-Drop Modes
Design-Time OLE Drag-and-Drop Support
Allow Users to Drag-and-Drop Controls
Using Controls


How to: Make Controls Easier to Use

Visual FoxPro 9.0
How to: Make Controls Easier to Use
See Also

You can make the application user interface easier to understand and use by creating access keys, setting tab order, displaying ToolTip text and deactivating selected controls.

Creating Access Keys

You can create access keys so that users can choose a control from anywhere in the form by pressing ALT and the key.

To specify an access key for a control

  • In the Caption property for the control, precede the desired letter with a backslash (\) followed immediately by a left angle bracket (<).

For more information, see Caption Property (Visual FoxPro).

For example, the following setting for the Caption property of a command button creates an access key using the letter "O":

Copy Code
Caption = "\<Open"

The user can choose the command button anywhere in the form by pressing ALT+O.

To specify an access key for a text box or edit box

  1. Create a label containing a backslash (\) and a left angle bracket (<) preceding the desired letter, for example, C\<ustomer.

  2. Make sure the label is the control in the tab order immediately preceding the text box or edit box you want to receive the focus.

Setting Tab Order for Controls

The default tab order of controls on your form is set to the order in which you added the controls to the form. You can reset the tab order so that the user can traverse controls in a more logical order.

To change tab order for controls

  1. Open the form in the Form Designer.

  2. On the View menu, point to Tab Order, and click Assign Interactively.

    Tip:
    You can also click Set Tab Order on the Form Designer toolbar. To set the tab order using a list, click Assign by List.

  3. Double-click the numbered box next to the control you want to have the initial focus when the form opens.

  4. Click the numbered box next to the other controls in the order you want them to be tabbed to.

  5. When you are finished, click anywhere outside the numbered boxes..

You also can set the default method to assign tab order using a list by setting the Tab ordering option on the Forms tab in the Options dialog box.

You can set the selection order for the option and command buttons within a control group. To move to a control group with the keyboard, a user tabs to the first button in the control group and then uses the arrow keys to select other buttons in the group.

To change the selection order of buttons within a control group

  1. In the Properties window, select the group in the Object list. A thick border indicates that the group is in edit mode.

  2. Select the Form Designer window.

  3. From the View menu, choose Tab Order.

  4. Set the selection order as you would the tab order for controls.

Setting ToolTip Text

Each control has a ToolTipText Property that makes it possible for you to specify the text displayed when the user pauses the mouse pointer over the control. Tips are especially useful for buttons with icons instead of text.

To specify ToolTip text

  • In the Properties window, select the ToolTipText property and type the desired text.

The form's ShowTips property determines whether ToolTip text is displayed.

Changing the Mouse Pointer Display

You can provide visual clues about the different states your application might be in by changing how the mouse pointer displays.

To change the mouse pointer display

  • Create a method that changes the mouse pointer to a different state.

For example, in the tsBaseForm class of the Tasmanian Traders sample application, a WaitMode method changes the mouse pointer to the default wait state cursor. Before running any code that might take a while to process, the Tasmanian Traders application passes a value of true (.T.) to the WaitMode method to change the pointer and let the user know that processing is going on. After the processing is completed, a call to WaitMode with false (.F.) restores the default mouse pointer.

Copy Code
* WaitMode Method of tsBaseForm class
LPARAMETERS tlWaitMode

lnMousePointer = IIF(tlWaitMode, MOUSE_HOURGLASS, MOUSE_DEFAULT)
THISFORM.MousePointer = lnMousePointer
THISFORM.SetAll('MousePointer', lnMousePointer)
  • If you want to change the mouse pointer to something other than one of the default pointers, set the MousePointer property to 99 - Custom and set the MouseIcon property to your own cursor (.cur) or icon (.ico) file. For more information, see MousePointer Property and MouseIcon Property.

Activating and Disabling Controls

You can activate or disable controls if they are not available under certain conditions.

To activate or disable a control

  • Set the Enabled property for the control to False (.F.).

For more information, see Enabled Property.

You can activate or disable individual option buttons or command buttons in a group by setting the Enabled property for each button to True (.T.) or False (.F.). You also can disable or enable all the buttons in a group by setting the Enabled property of the group, as in the following line of code:

Copy Code
frmForm1.cmgCommandGroup1.Enabled = .T.

When you set the Enabled property of an option button group or a command button group to false (.F.), all the buttons in the group are disabled, but will not be displayed with the disabled ForeColor and BackColor. Setting the Enabled property of the group does not change the Enabled property of the individual buttons in the group. This makes it possible for you to disable a group of buttons with some of the buttons already disabled. When you enable the group, buttons that were originally disabled remain disabled.

If you want to disable all the buttons in a group so that they appear disabled, and if you do not want to preserve information about which buttons were originally disabled or enabled, you can use the SetAll Method of the group, like this:

Copy Code
frmForm1.opgOptionGroup1.SetAll("Enabled", .F.)

See Also

Other Resources

How to: Display Controls in Grid Columns
Controls for Extending Forms
Using Controls
Caption property
Properties window
Controls and Objects Created in Earlier Versions


Designing Menus and Toolbars

Visual FoxPro 9.0
Designing Menus and Toolbars

Menus and toolbars provide a structured and accessible route for users to leverage the commands and tools contained in your applications. Proper planning and design of menus and toolbars will make sure the key functionality of your applications is exposed, and users will not become frustrated as they try to use your applications. For information about customizing Visual FoxPro toolbars, see Customizing the Visual FoxPro Environment.

Users often browse menus before looking elsewhere for information about your application. If your menus are well designed, users can organize their understanding of the application by developing a mental model based on the menu organization and content alone. With the Visual FoxPro Menu designer, you can create menus that enhance the quality of your applications.

Each part of a Visual FoxPro application can have its own menu system or set of menus. The following topics describe how to create a menu system. For details about adding menus to an application, see Compiling an Application.

In This Section

Menu System Creation

Describes the Menu designer, where you create the menus, submenus, and menu options.
Creating Menus, Shortcut Menus, Menu Items, and Submenus

Discusses how to create menus, shortcut menus, menu items, and submenus to navigate and access features in your application.
How to: Add Cleanup Code to a Menu System

Describes how to customize menu systems by adding cleanup code to it.
How to: Add Setup Code to a Menu System

Explains how to customize a menu system by adding setup code to it.
How to: Assign Access Keys and Keyboard Shortcuts

Explains how to assign access keys and keyboard shortcuts to your menus for better functionality.
How to: Control Menus at Run Time

Describes how to control menus during run time.
How to: Enable and Disable Menu Items

Explains how to enable or disable a menu or menu item based on a logical condition.
How to: Include Menus in an Application

Explains how to include a menu system in your application.
How to: Perform Tasks with Commands

Explains how to perform at task by assigning a command to a menu or menu item.
How to: Perform Tasks with Procedures

Describes how to assign a procedure to a menu or menu item.
Creating Custom Toolbars

Discusses how to add custom toolbars to simplify or speed up tasks in your application.
How to: Test and Debug a Menu System

Explains how to preview a menu system as you design it, or test and debug it after generating the menu program.
How to: Customize a Menu System

Explains that after creating a basic menu system, you can customize it. For example, you can create status bar messages, define menu locations, or define default procedures.

Related Sections

Creating the User Interface

Provides links to topics on using Visual FoxPro forms, classes, controls, menus, and toolbars, to build interfaces that help users gain access to the full potential of your programs.
Creating Forms

Provides a links to topics on how to design forms in Visual FoxPro.
Working with Forms

Provides link to topics that explain how to work with forms you can run, hide, or alter forms in different ways.
Using Controls

Provides link to topics that explain how to use controls to manage the interactions between users and your application. Visual FoxPro offers a variety of controls to enhance your application interface.


Menu System Creation

Visual FoxPro 9.0
Menu System Creation

Much of the work involved in creating a menu system is done in the Menu Designer, where you create the actual menus, submenus, and menu options.

Creating a menu system involves several steps. Regardless of the size of your application and the complexities of the menus you plan to use, you should:

  • Plan and design the system.

    Decide what menus you need, where they appear in the interface, which ones need submenus, and so on.

  • Create the menus and submenus.

    Define the menu titles, menu items, and submenus using the Menu Designer.

  • Assign tasks to the system so that it does what you want.

    Specify tasks for the menus to perform, such as displaying forms and dialog boxes. Additionally, include setup code and cleanup code if appropriate. Setup code executes before the menu system is defined and can include code for opening files, declaring variables, or placing the menu system on a stack so that it can be retrieved later. Cleanup code contains code to be executed after the menu definition code, and makes menus and menu items available or unavailable for selection.

  • Generate the menu program.

  • Run the program to test the system.

In This Section

Menu System Design Guidelines

Discusses how the usefulness of your application can depend on the quality of its menu systems. Investing time in your menus will create a user interface that is easily accepted and quickly learned.
How to: Group Menu Items

Describes how to group menu items to increase readability of your menus.
How to: Save a Menu as HTML

Describes how to save your menu as an HTML file.

Related Sections

Designing Menus and Toolbars

Provides links to topics that describe how to create menus and toolbars for your Visual FoxPro applications.
Creating Menus, Shortcut Menus, Menu Items, and Submenus

Provides links to topic that describe how to create menus, menu items, and submenus for your Visual FoxPro applications.
Compiling an Application

Provides links to topics that describe how to build an application and assemble the executable components in the application project, into a single file that you can distribute.


Menu System Design Guidelines

Visual FoxPro 9.0
Menu System Design Guidelines
See Also

The usefulness of an application can depend on the quality of its menu systems. If you invest planning time in your menus, users will accept them readily and learn them quickly.

While designing your menu system, consider the following guidelines:

  • Organize the system according to the tasks users will perform, not according to the hierarchy of programs in the application.

    Users can form a mental model of how the application is organized by looking at the menus and menu items. To design these menus and menu items effectively, you should know how your users will think about and accomplish their work.

  • Give each menu a meaningful title.

  • Organize menu items according to their expected frequency of use, their logical sequence, or their alphabetical order.

    If you can't predict the frequency and can't determine a logical order, then organize menu items alphabetically. Alphabetical ordering is particularly effective when a menu contains more than eight items. With so many items, the user spends time scanning them; alphabetical ordering facilitates scanning.

  • Put separator lines between logical groups of menu items.

  • Limit the number of items on a menu to one screen.

  • If the number exceeds the length of a screen, create submenus for appropriate menu items.

  • Choose access keys and keyboard shortcuts for menus and menu items.

    For example, ALT+F could be an access key for a File menu.

  • Use words that clearly describe the menu items.

    Use common words rather than computer jargon, and use simple, active verbs to indicate what actions will result from choosing each menu item. Don't use nouns as verbs. Additionally, describe the menu items using parallel construction. For example, if you use single words for all the items, then use the same part of speech for all of them.

  • Use mixed upper and lowercase letters in menu items.

See Also

Other Resources

Menu System Creation
Creating Menus, Shortcut Menus, Menu Items, and Submenus
Designing Menus and Toolbars
How to: Group Menu Items
Compiling an Application


How to: Group Menu Items

Visual FoxPro 9.0
How to: Group Menu Items
See Also

For readability, separate groups of similar menu items with dividing lines. For example, in Visual FoxPro, the Edit menu has a line separating the Undo and Redo commands from the Cut, Copy, Paste, Paste Special, and Clear commands.

To group menu items

  1. In the Prompt column, type \-. This creates a dividing line.

  2. Drag the button to the left of the \- prompt to move the dividing line until it appears where you want it.

See Also

Other Resources

Menu System Creation
Creating Menus, Shortcut Menus, Menu Items, and Submenus
How to: Save a Menu as HTML
Designing Menus and Toolbars
Compiling an Application


How to: Save a Menu as HTML

Visual FoxPro 9.0
How to: Save a Menu as HTML
See Also

You can use the Save As HTML option on the File menu when you're creating a menu to save the contents of a menu as an HTML (Hypertext Markup Language) file.

To save a form as HTML

  1. Open the menu.

  2. Choose Save As HTML on the File menu. (You will be asked to save the menu if it has been modified.)

  3. Enter the name of the HTML file to create and choose Save.

See Also

Other Resources

Menu System Creation
How to: Group Menu Items
How to: Include Menus in an Application
Designing Menus and Toolbars
Creating Menus, Shortcut Menus, Menu Items, and Submenus
Compiling an Application


Creating Menus, Shortcut Menus, Menu Items, and Submenus

Visual FoxPro 9.0
Creating Menus, Shortcut Menus, Menu Items, and Submenus

After planning your menu system, you can create it with the Menu Designer. You can create menus, shortcut menus, menu items, submenus of menu items, lines that separate groups of related menu items, and so on. The following sections provide the details.

In This Section

How to: Create Menus and Submenus

Describes how to create menus and submenus to navigate your application.
How to: Create Menu Items

Describes how to create menus you can place menu items on the menus. Menu items can represent Visual FoxPro commands or procedures or submenus that offer additional options.
How to: Create Shortcut Menus

Describes how to create shortcut menus that appear when you click the right mouse button on a control or object.

Related Sections

Designing Menus and Toolbars

Provides links to topics that explain how to design custom menus and toolbars for your Visual FoxPro application.
Menu System Design Guidelines

Discusses how the usefulness of your application can depend on the quality of its menu systems. Investing time in your menus will create a user interface that is easily accepted and quickly learned.


How to: Create Menus and Submenus

Visual FoxPro 9.0
How to: Create Menus and Submenus
See Also

You can create menus by customizing the existing Visual FoxPro menu system or by developing your own menu system. To start with the existing Visual FoxPro menu system, use the Quick Menu feature.

To create a menu system with Quick Menu

  1. From the Project Manager Window, select the Other tab, select Menus, and then select New.

  2. Select Menu.

    The Menu Designer appears.

  3. From the Menu menu, choose Quick Menu.

    The Menu Designer now contains information about the main Visual FoxPro menus.

  4. Customize the menu system by adding or changing menu items.

    For example, insert a Customer menu before the Help menu by choosing the mover button associated with the Help menu, choosing the Insert button, and then typing Customer in the Prompt column. The result looks like this:

    CustomizeMenu screenshot foxpro
    Tip:
    Drag mover buttons to change the location of menus on the menu bar. If you need a Help menu, make it the last menu on the menu bar so that users can find it quickly.

  5. From the Menu menu, choose Generate.

    Visual FoxPro prompts you to save the menu system in a file with an .mnx extension. This file is a table that will store all the information about the menu system. After you save the menu system, Visual FoxPro prompts for an output file with an .mpr extension. This file will contain the generated menu program.

Creating SDI Menus

SDI menus are menus that appear in single-document interface (SDI) windows. To create an SDI menu you must indicate that the menu will be used on an SDI form while you're designing the menu. Other than that, the process of creating an SDI menu is the same as that for creating a normal menu.

To create an SDI menu

  • While the Menu Designer is open, choose General Options from the View menu, and select Top-Level Form.
Note:
Menus on SDI forms (ShowWindow = 2) are not supported if the HalfHeightCaption property of the form is set to True (.T.).

Creating Submenus

For each menu item, you can create a submenu containing additional menu items.

To create a submenu

  1. In the Prompt column, select the menu item to which you want to add a submenu.

  2. In the Result box, select Submenu.

    A Create button appears to the right of the list. If a submenu already exists, an Edit button appears instead.

  3. Select Create or Edit.

  4. In the Prompt column, type the names of the new menu items.

To add menus programmatically

  • Use the DEFINE PAD, DEFINE POPUP, or DEFINE BAR commands.

Though you typically create menus and menu items using the Menu Designer, you can also create them using Visual FoxPro commands. For example, you can create a menu using DEFINE PAD, a submenu using DEFINE POPUP, and items on the submenu using a series of DEFINE BAR commands. You can also use DEFINE BAR Command to customize menus in such ways as adding pictures, assigning fonts, and displaying messages to the user.

See Also

Other Resources

Menu System Creation
Creating Menus, Shortcut Menus, Menu Items, and Submenus
Designing Menus and Toolbars
How to: Group Menu Items
Compiling an Application


How to: Create Menu Items

Visual FoxPro 9.0
How to: Create Menu Items
See Also

After creating menus, you can place menu items on the menus. Menu items can represent Visual FoxPro commands or procedures that you want the user to execute, or menu items can contain submenus that offer additional menu items.

To add menu items to a menu

  1. In the Prompt column, select the menu title to which you want to add menu items.

  2. In the Result box, select Submenu.

    A Create button appears to the right of the list.

  3. Choose the Create button.

    An empty design window appears. In this window, you enter the menu items.

  4. In the Prompt column, type the names of the new menu items.

See Also

Other Resources

Menu System Creation
Creating Menus, Shortcut Menus, Menu Items, and Submenus
Designing Menus and Toolbars
How to: Group Menu Items
Compiling an Application


How to: Create Shortcut Menus

Visual FoxPro 9.0
How to: Create Shortcut Menus
See Also

Shortcut menus appear when you click the right mouse button on a control or object, and provide a quick way to expose all of the functions that apply to just that object. You can use Visual FoxPro to create shortcut menus, then attach these menus to controls. For example, you can create a shortcut menu containing the commands Cut, Copy, and Paste that will appear when a user right-clicks on data contained in a Grid control.

To create a shortcut menu

  1. From the Project Manager Window, select the Other tab, select Menus, and then choose New.

  2. Choose Shortcut.

    The Shortcut Designer appears.

When you are in the Shortcut Menu designer, the process for adding menu items is the same as it is for creating menus.

For an example of shortcut menus, run Solution.app in the Visual FoxPro ...\Samples\Solution\Solution directory.

See Also

Other Resources

Menu System Creation
Creating Menus, Shortcut Menus, Menu Items, and Submenus
Designing Menus and Toolbars
How to: Group Menu Items
Compiling an Application


How to: Add Cleanup Code to a Menu System

Visual FoxPro 9.0
How to: Add Cleanup Code to a Menu System
See Also

You can tailor your menu system by adding cleanup code to it. Cleanup code typically contains code that initially enables or disables menus and menu items. When you generate and run the menu program, setup code and menu definition code is processed before cleanup code.

To add cleanup code to a menu system

  1. From the View menu, choose General Options.

  2. In the Menu Code area, select Cleanup and then choose OK.

  3. In the code window, type the appropriate cleanup code.

    Your changes are saved when you close the Menu Designer.

    Tip:
    If your menu is the main program in an application, include a READ EVENTS Command in the cleanup code and assign a CLEAR EVENTS command to the menu command used to exit the menu system. This prevents your run-time applications from terminating prematurely.

See Also

Other Resources

How to: Add Setup Code to a Menu System
How to: Control Menus at Run Time
Creating Custom Toolbars
Designing Menus and Toolbars
Compiling an Application


How to: Add Setup Code to a Menu System

Visual FoxPro 9.0
How to: Add Setup Code to a Menu System
See Also

You can customize a menu system by adding setup code to it. Setup code can include code for creating the environment, defining variables, opening necessary files, and saving or restoring menu systems with the PUSH MENU and POP MENU commands.

To add setup code to a menu system

  1. From the View menu, choose General Options.

  2. In the Menu Code area, select Setup and then choose OK.

  3. In the setup code window, type the appropriate setup code.

    Your changes are saved when you close the Menu Designer.

See Also

Other Resources

How to: Perform Tasks with Commands
How to: Add Cleanup Code to a Menu System
How to: Control Menus at Run Time
Designing Menus and Toolbars
Compiling an Application


How to: Assign Access Keys and Keyboard Shortcuts

Visual FoxPro 9.0
How to: Assign Access Keys and Keyboard Shortcuts
See Also

As you create a menu system, you should consider ease of access to the system, and you must assign tasks to the system. You must give menus and menu items tasks to perform, such as displaying forms, toolbars, and other menu systems. You should define access keys to permit entry to the menu system. You can also add keyboard shortcuts and enable or disable menu items for more control.

Assigning Access Keys

Well-designed menus have access keys for quick keyboard access to the menu functionality. The access key is represented by the underlined letter in the menu title or menu item. For instance, the Visual FoxPro File menu uses "F" as its access key.

If you don't assign an access key to a menu title or menu item, Visual FoxPro automatically assigns the first letter as the access key. For example, the Customer menu created previously didn't have a defined access key. Accordingly, Visual FoxPro assigned the first letter (C) as the access key.

To specify the access key for a menu or menu item

  • Type \< to the left of the letter you want as the access key.

    For example, to set the access key to "u" in the Customer menu title, replace Customer with C\<ustomer in the Prompt column.

    Note:
    If an access key for your menu system doesn't work, look for duplicate access keys.

Assigning Keyboard Shortcuts

In addition to assigning access keys, you can specify keyboard shortcuts for menus or menu items. As with access keys, keyboard shortcuts let you choose a menu or menu item by holding down one key while pressing another. The difference between access keys and keyboard shortcuts is that you can use a keyboard shortcut to choose a menu item without first displaying its menu.

Keyboard shortcuts for Visual FoxPro menu items are combinations of the CTRL or ALT key and another key. For instance, you can create a new file in Visual FoxPro by pressing CTRL+N.

To specify a keyboard shortcut for a menu or menu item

  1. In the Prompt column, select the appropriate menu title or menu item.

  2. Choose the button in the Options column to display the Prompt Options dialog box.

  3. In the Key Label box, press a key combination to create a keyboard shortcut.

    If a menu item doesn't have a keyboard shortcut, Visual FoxPro displays "(press the key)" in the Key Label box.

  4. In the Key Text box, add the text you want to appear beside the menu item.

    By default, Visual FoxPro repeats the keyboard shortcut from the Key Label box in the Key Text box. However, you can change the text in the Key Text box if you want your application to display different text. For example, if both the Key Label and Key Text were CTRL+R, you could change the Key Text value to ^R.

    Note:
    CTRL+J is an invalid keyboard shortcut because it is used to close certain dialog boxes in Visual FoxPro.

See Also

Other Resources

How to: Include Menus in an Application
How to: Enable and Disable Menu Items
Creating Menus, Shortcut Menus, Menu Items, and Submenus
Designing Menus and Toolbars
Compiling an Application


How to: Control Menus at Run Time

Visual FoxPro 9.0
How to: Control Menus at Run Time
See Also

Each Visual FoxPro menu has two names, and each menu item has a name and a number. Visual FoxPro uses one name in the user interface and the other name or number in the generated menu program (.mpr). You can use these names or numbers to reference and control menus and menu items at run time. If you don't provide a name or number when creating menus and menu items, Visual FoxPro creates one when you generate the menu program.

For an example of adding and removing menu items at run time, see Solution.app in the Visual FoxPro ...\Samples\Solution directory.

Caution:
Avoid using Visual FoxPro-generated names and numbers in code, because they change each time you generate the menu program. If you refer to a generated name or number, your code might fail.

In the Menu Designer, the Prompt column shows what appears in the user interface, and the column to the right of the Result box shows what appears in the generated program.

To specify a name for a menu pad

  1. In the Prompt column, select the appropriate menu title.

    Note:
    The Result column must show Command, Submenu, or Procedure — not Pad Name.

  2. Choose the button in the Options column to display the Prompt Options dialog box.

  3. In the Pad Name box, type the name of your choice.

  4. Choose OK to return to the Menu Designer.

To specify a number for a menu item

  1. In the Prompt column, select the appropriate menu item.

    Note:
    The Result column must show Command, Submenu, or Procedure — not Bar #.

  2. Choose the button in the Options column to display the Prompt Options dialog box.

  3. In the Bar # box, type the number of your choice.

  4. Choose OK to return to the Menu Designer.

    Tip:
    If you use the Quick Menu feature, don't change the names or numbers that Visual FoxPro provides for system menus or menu items; otherwise, you might get unpredictable results when you run the generated menu program.

See Also

Other Resources

How to: Add Cleanup Code to a Menu System
Designing Menus and Toolbars
Creating Custom Toolbars
Creating Menus, Shortcut Menus, Menu Items, and Submenus
Compiling an Application


How to: Enable and Disable Menu Items

Visual FoxPro 9.0
How to: Enable and Disable Menu Items
See Also

You can enable or disable a menu or menu item based on a logical condition.

To enable or disable a menu or menu item

  1. In the Prompt column, select the appropriate menu title or menu item.

  2. Choose the button in the Options column to display the Prompt Options dialog box.

  3. Select Skip For.

    The Expression Builder appears.

  4. In the Skip For box, type the expression that determines whether the menu or menu item is enabled or disabled.

    If the expression evaluates to false (.F.), the menu or menu item is enabled. If the expression evaluates to true (.T.), the menu or menu item is disabled and cannot be selected or chosen. For details, see DEFINE BAR and DEFINE PAD.

    Note:
    After the menu system has been displayed, you can enable and disable menus and menu items by using the SET SKIP OF Command.

On a menu, a check mark next to a menu item indicates that it is in effect. For example, if you put a check mark next to the Credit item on the Customer menu created earlier, Credit is in effect.

To mark the state of a menu item

  • At run time, place a check mark next to a menu item by using the SET MARK OF Command.

For an example of disabling and marking the state of menu items, run Solution.app in the Visual FoxPro ...\Samples\Solution directory.

See Also

Other Resources

How to: Assign Access Keys and Keyboard Shortcuts
How to: Perform Tasks with Commands
How to: Perform Tasks with Procedures
Designing Menus and Toolbars
Compiling an Application


How to: Include Menus in an Application

Visual FoxPro 9.0
How to: Include Menus in an Application
See Also

When you create a menu system, you can include it in your application.

To include a menu system in your application

  • Add the .mnx file to your project, and then build the application from the project. For more information about building your application, see Compiling an Application.

When you create and generate a shortcut menu, you can attach it to a control. Shortcut menus typically appear when a user right-clicks on a control. You can attach a shortcut menu to a particular control by entering a small amount of code in the right-click event of the control.

To attach shortcut menus to controls

  1. Select the control to which you want to attach the shortcut menu.

  2. In the Properties window, choose the Methods tab and select Right Click Event.

  3. In the code window, type DO menu.MPR, where menu is the name of the shortcut menu.

    Note:
    Be sure to use the .mpr extension when referencing shortcut menus.

Attaching SDI Menus to Forms

When you create an SDI menu, you can attach it to an SDI form. In addition, you must:

  • Set the form's ShowWindow property.

  • Add a DO statement to the form's Init event.

To attach an SDI menu to a form

  1. In the Form Designer, set the form's ShowWindow property to 2 – As Top Level Form.

  2. In the Init event of the form, call the menu.

    For example, if your menu is called SDIMENU.MPR, add this code:

    Copy Code
    DO SDIMENU.MPR WITH THIS,.T.

See Also

Other Resources

How to: Save a Menu as HTML
How to: Assign Access Keys and Keyboard Shortcuts
Designing Menus and Toolbars
Creating Menus, Shortcut Menus, Menu Items, and Submenus
Compiling an Application


How to: Perform Tasks with Commands

Visual FoxPro 9.0
How to: Perform Tasks with Commands
See Also

When a menu or menu item is selected, it performs a task, such as displaying a form, a toolbar, or another menu system. To perform a task, a menu or menu item must execute a Visual FoxPro command. The command can be contained in one line, or it can be a procedure call.

Tip:
If you expect to use a set of commands in several places, write a procedure. The procedure should be explicitly named and written in the menu cleanup code, or somewhere where it can be referenced by any menu or object. For more information, see How to: Perform Tasks with Procedures.

A command can be any valid Visual FoxPro command, including a call to a program that exists on your path or a procedure defined in the Cleanup option of the General Options dialog box. For more information, see How to: Customize a Menu System.

To assign a command to a menu or menu item

  1. In the Prompt column, select the appropriate menu title or menu item.

  2. In the Result box, select Command.

  3. In the box to the right of the Result box, type the appropriate command:

If the command calls a procedure in the menu's cleanup code, use the DO command with the following syntax:

Copy Code
DO procname IN menuname

In this syntax, menuname specifies the location of the procedure. This is the name of the menu file and must have the .mpr extension. If you don't specify the location in menuname, you must specify it with SET PROCEDURE TO menuname.mpr, if the procedure is in the menu cleanup code.

Displaying Forms and Dialog Boxes

From a menu or menu item, you can display a compiled form or dialog box by calling it with a command or procedure.

To display a form or dialog box

  • Use the DO FORM command with the form's name.

For example, to display a form named "Orders," use the following command:

Copy Code
DO FORM Orders
Tip:
When you create a menu or menu item that displays a form or dialog box, put three dots at the end of the prompt to indicate that more user input is required.

If you create a custom toolbar for an application, you can display it by calling it from a menu or menu item. For details, see Creating Custom Toolbars.

See Also

Other Resources

How to: Enable and Disable Menu Items
How to: Perform Tasks with Procedures
How to: Add Setup Code to a Menu System
Designing Menus and Toolbars
Compiling an Application


How to: Perform Tasks with Procedures

Visual FoxPro 9.0
How to: Perform Tasks with Procedures
See Also

You can assign a procedure to a menu or menu item. The way you assign a procedure depends on whether the menu or menu item has submenus.

To assign a procedure to a menu or menu item without submenus

  1. In the Prompt column, select the appropriate menu title or menu item.

  2. In the Result box, select Procedure.

    A Create button appears to the right of the list. If a procedure has been defined previously, an Edit button appears instead.

  3. Select Create or Edit.

  4. Type the appropriate code in the window.

    Note:
    You don't need to type the PROCEDURE Command in the procedure editing window because Visual FoxPro generates this statement for you. The only place you need the PROCEDURE statement is in the cleanup code.

To assign a procedure to a menu or menu item with submenus

  1. In the Menu level box, select the level that includes the appropriate menu or menu item. For example, suppose your menu system includes the Customer menu created earlier. To assign a procedure to the Customer menu, select the "Menu Bar" level in the Menu Level box. Similarly, to assign a procedure to an item on the Customer menu, select the "Customer" level in the list.

  2. From the View menu, choose Menu Options.

    Visual FoxPro displays the Menu Options dialog box.

  3. Assign the procedure by doing one of the following:

    • Write or call a procedure in the Procedure box.

      -or-

    • Choose Edit and then OK to open a separate editing window and write or call a procedure.

See Also

Other Resources

How to: Perform Tasks with Commands
How to: Add Setup Code to a Menu System
How to: Add Cleanup Code to a Menu System
Designing Menus and Toolbars
Compiling an Application


Creating Custom Toolbars

Visual FoxPro 9.0
Creating Custom Toolbars

If your application includes repetitive tasks that users perform frequently, you can add custom toolbars to simplify or speed up the tasks. For example, if users typically print a report by choosing a menu command, you can simplify the task by providing a toolbar with a print button.

In This Section

How to: Define a Toolbar Class

Explains how to create a custom toolbar class.
How to: Add Objects to a Custom Toolbar Class

Describes the steps involved in editing a custom toolbar class.
How to: Add Custom Toolbars to Form Sets

Provides information on how to add a custom toolbar class to your form as another form in a form set.
How to: Coordinate Toolbars and Forms Using Code

Provides information on how to programmatically add a toolbar to a form.
How to: Define Toolbar Actions

Explains how to define actions associated with the toolbar and its objects.
How to: Dock Toolbars

Describes how to dock and undock system or user-defined toolbars.
How to: Create the Coordinated Menu

Explains how to coordinate a menu with a toolbar.
How to: Add a Coordinated Toolbar and Menu to a Form Set

Explains how to add a coordinated menu and toolbar to a form.

Related Sections

Customize Toolbar Dialog Box

Explains how to customize toolbars that come with Visual FoxPro.
Designing Menus and Toolbars

Provides links to topics that explain how to design custom menus and toolbars for your Visual FoxPro application.


How to: Define a Toolbar Class

Visual FoxPro 9.0
How to: Define a Toolbar Class
See Also

If you want to create a toolbar that contains buttons not already found on existing toolbars, you can do so by defining a custom toolbar class. Visual FoxPro provides a Toolbar base class from which you can create the class you need.

After defining a toolbar class, you can add objects to the toolbar class, and then define the properties, events, and methods for the custom toolbar. Finally, you can add the toolbar to a form set.

To define a custom toolbar class

  1. From the Project Manager Window, select Classes and then choose New.

  2. In the Class Name box, type the name of your class.

  3. From the Based On box, select Toolbar to use the Toolbar base class.

    -or-

    Choose the dialog button to choose another toolbar class.

For example, you could store a printing class based on the Toolbar base class in an inventory library.

When you complete the New Class dialog box, the Class Designer appears.

You can also define a toolbar class by doing one of the following:

  • Choosing New from the File menu and then choosing Class.

  • Using the CREATE CLASS Command or MODIFY CLASS Command.

  • Defining the class programmatically with the DEFINE CLASS Command.

While designing a custom toolbar, you can set its properties. For example, you can set the Movable property to allow the user to move the toolbar.

Additionally, you can use methods and events to control custom toolbars. For example, you can use the Dock Method to dock or float a toolbar, and you can use the BeforeDock Event and AfterDock Event to control what happens before and after a toolbar is docked.

See Also

Other Resources

How to: Add Objects to a Custom Toolbar Class
Creating Custom Toolbars
Customize Toolbar Dialog Box
Designing Menus and Toolbars
Customizing the Visual FoxPro Environment


How to: Add Objects to a Custom Toolbar Class

Visual FoxPro 9.0
How to: Add Objects to a Custom Toolbar Class
See Also

After creating a custom toolbar class, you can add objects to it, including any objects supported by Visual FoxPro, except grids. For example, you can add objects from the Controls toolbar.

To add objects to your custom toolbar class

  1. Open the class library containing the custom toolbar class, and then open the class.

  2. On the Form Controls toolbar, choose an object you want to add.

  3. Place the object on the custom toolbar by selecting the custom toolbar.

  4. Repeat steps 2 and 3 until the custom toolbar is complete.

  5. Reorganize the objects on the custom toolbar, if appropriate.

    For example, you can size objects, move them by dragging them, delete them by pressing the DELETE key, or add extra space between them by inserting Separator objects from the Form Controls toolbar.

    Note:
    You can move only one object at a time.

  6. Set properties of the toolbar in the Properties window.

  7. Save the custom toolbar class.

    Tip:
    You can add a bitmap or icon to a toolbar button by setting its Picture property.

See Also

Other Resources

How to: Define a Toolbar Class
How to: Add Custom Toolbars to Form Sets
Creating Custom Toolbars
Customize Toolbar Dialog Box
Designing Menus and Toolbars
Customizing the Visual FoxPro Environment


How to: Add Custom Toolbars to Form Sets

Visual FoxPro 9.0
How to: Add Custom Toolbars to Form Sets
See Also

After defining a toolbar class, you can create a toolbar from it. You can coordinate toolbars and forms by using the Form Designer or writing code.

Coordinating Toolbars and Forms in the Form Designer

You can add a toolbar to a form set so that the toolbar opens along with the forms in the form set. You cannot add the toolbar directly to the form.

To add a toolbar to a form set using the Form Designer

  1. Register and select the library containing the toolbar class.

  2. Open the form set with which you want to use the toolbar class, click the View Classes button on the Form Controls toolbar, and then select the toolbar class from the list displayed.

  3. From the Form Controls toolbar, choose the toolbar class.

  4. Click in the Form Designer to add the toolbar, and then drag the toolbar to its appropriate location.

    Visual FoxPro adds the toolbar to the form set. If a form set isn't open, Visual FoxPro prompts you for one.

  5. Define the actions of the toolbar and its buttons.

    Tip:
    To determine an object's class, look at its ToolTip in the Form Controls toolbar.

See Also

Other Resources

How to: Add Objects to a Custom Toolbar Class
How to: Coordinate Toolbars and Forms Using Code
Creating Custom Toolbars
Customize Toolbar Dialog Box
Designing Menus and Toolbars
Customizing the Visual FoxPro Environment
How to: Define Toolbar Actions
Object-Oriented Programming


How to: Coordinate Toolbars and Forms Using Code

Visual FoxPro 9.0
How to: Coordinate Toolbars and Forms Using Code
See Also

In addition to using the Form Designer, you can add toolbars to form sets by using code.

To add a toolbar to a form set using code

  • In the form set's Init Event, use the SET CLASSLIB Command to specify the library containing the toolbar class, and then create a toolbar from that class in the form set.

For example, to add and display the toolbar tbrPrint, which is based on the printing class in the inventory class library, add the following code to the form set's Init event:

Copy Code
SET CLASSLIB TO inventory
THIS.AddObject("tbrPrint","printing")
THIS.tbrPrint.Show
Note:
If the toolbar class does not define the actions of the toolbar and its buttons, you must define the actions in the event procedures associated with the toolbar and its buttons.

You can define all aspects of a toolbar in code. For example, if you add the following code to a form set's Init event, when the form set is loaded Visual FoxPro creates and displays the toolbar defined in the code. This toolbar contains two buttons.

When chosen, these buttons change the font attributes of the form frmForm1 in the form set.

Form Set Init Event Code

Code | Comments
THIS.AddObject("tbrTool1","mytoolbar") THIS.tbrTool1.Show | Adds a toolbar of the class mytoolbar to the current form set and makes the toolbar visible. This code is in the form set's Init event.

Class definition code

Code | Comments
DEFINE CLASS myToolBar AS TOOLBAR ADD OBJECT cmdBold AS COMMANDBUTTON ADD OBJECT sep1 AS SEPARATOR ADD OBJECT cmdItalic AS COMMANDBUTTON | Start of the class definition: one toolbar with a command button, a separator, and another command button.
Left = 1 Top = 1 Width = 25 Caption = "Form Attributes" | Sets properties of the toolbar object.
cmdBold.Caption = "B" cmdBold.Height = 1.7 cmdBold.Width = 10 cmdItalic.Caption = "I" cmdItalic.Height = 1.7 cmdItalic.Width = 10 cmdItalic.FontBold = .F. | Sets properties of the controls. Notice that there are no Top or Left property settings for controls on a toolbar. Controls on a toolbar are automatically positioned in the order they are added. The FontBold property of cmdItalic is set to false (.F.) because FontBold is true (.T.) by default.
PROCEDURE Activate THIS.cmdBold.FontBold = ; THISFORMSET.frmForm1.FontBold THIS.cmdItalic.FontItalic = ; THISFORMSET.frmForm1.FontItalic ENDPROC | When the toolbar is activated, the font attributes of the two command buttons are set to reflect the Bold and Italic font settings of frmForm1.
PROCEDURE cmdBold.CLICK THISFORMSET.frmForm1.FontBold = ; !THISFORMSET.frmForm1.FontBold THIS.FontBold = ; THISFORMSET.frmForm1.FontBold ENDPROC | When the user clicks cmdBold, the FontBold setting of frmForm1 is reversed, and the FontBold setting of cmdBold is set to match it.
PROCEDURE cmdItalic.CLICK THISFORMSET.frmForm1.FontItalic = ; !THISFORMSET.frmForm1.FontItalic THIS.FontItalic = ; THISFORMSET.frmForm1.FontItalic ENDPROC | When the user clicks cmdItalic, the FontItalic setting of frmForm1 is reversed, and the FontItalic setting of cmdItalic is set to match it.
ENDDEFINE | End of the class definition.

See Also

Other Resources

How to: Add Custom Toolbars to Form Sets
How to: Define Toolbar Actions
Creating Custom Toolbars
Customize Toolbar Dialog Box
Designing Menus and Toolbars
Customizing the Visual FoxPro Environment
How to: Define Toolbar Actions


How to: Define Toolbar Actions

Visual FoxPro 9.0
How to: Define Toolbar Actions
See Also

After creating a toolbar, you must define the actions associated with the toolbar and its objects. For example, you must define what happens when the user clicks the toolbar or one of its buttons.

To define a toolbar action

  1. Select the object for which you want to define an action: the toolbar or one of its buttons.

  2. In the Properties window, choose the Methods tab.

  3. Edit the appropriate event.

  4. Add the code that specifies the action.

Additionally, you can set properties and methods of the toolbar and its objects.

Coordinating Menus and Custom Toolbars

If you create a toolbar, you should synchronize menu commands with their corresponding toolbar buttons. For example, if you enable a toolbar button, you should enable its corresponding menu command.

You should design and create your application to:

  • Perform the same actions when the user chooses associated toolbar buttons and menu items.

  • Coordinate the enabling and disabling of associated toolbar buttons and menu items.

To coordinate menu items and toolbar buttons

  1. Create a toolbar by defining a toolbar class, add command buttons, and include the operational code in the methods associated with the Click Event of the command buttons.

  2. Create the coordinated menu.

  3. Add the coordinated toolbar and menu to a form set.

See Also

Other Resources

How to: Coordinate Toolbars and Forms Using Code
How to: Create the Coordinated Menu
Creating Custom Toolbars
Customize Toolbar Dialog Box
Designing Menus and Toolbars
Customizing the Visual FoxPro Environment


How to: Dock Toolbars

Visual FoxPro 9.0
How to: Dock Toolbars
See Also

In Visual FoxPro, you can dock system or user-defined toolbars only to the main Visual FoxPro window. As with Visual FoxPro IDE windows, toolbars always take precedence when being docked closer to a border.

Toolbars do not support linked or tabbed docking. You cannot dock other windows to toolbars. Toolbars can never be docked inside a window and never share the same docking area with a form.

To dock a toolbar

  • Drag the toolbar to the top of the main Visual FoxPro window.

    The toolbar repositions itself against the chosen boundary.

    -OR-

  • Call the DOCK command with the appropriate values.

    -OR-

  • Use the toolbar's Dock method.

For more information, see DOCK Command and Dock Method.

To undock a toolbar

  1. Move the mouse pointer over the left side of the toolbar until the pointer changes into a mover arrow.

  2. Drag the toolbar away from the main Visual FoxPro window.

  3. -OR-

  4. Call the DOCK command with the appropriate values.

    You can also use the toolbar's Dock method or Move method. When using the Move method, the coordinates you specify must be outside the dock area.

For more information, see Move Method.

When a toolbar is docked along the border of the main Visual FoxPro window, its title bar is hidden, and its border changes to a single line. The toolbar also resizes to a single row of buttons. The window resizes so that the toolbar does not obscure any information on the screen. For example, if the toolbar is docked at the top, the screen moves down by the height of the toolbar.

For more information about docking state and writing code for docking events, see Docking State and Events.

See Also

Other Resources

Creating Custom Toolbars
Visual FoxPro Environment Settings
How to: Define Toolbar Actions


How to: Create the Coordinated Menu

Visual FoxPro 9.0
How to: Create the Coordinated Menu
See Also

When you coordinate a menu with a toolbar, the menu items accomplish the same tasks as the associated toolbar buttons, and the menu items are automatically disabled when the associated toolbar button is disabled.

To create a menu that is coordinated with a toolbar

  1. In the Menu Designer, create a submenu with a descriptive prompt for every button on the toolbar.

  2. In the result column for each submenu item, choose Command.

  3. For each submenu item, call the code associated with the Click Event of the appropriate toolbar command button.

    For example, if the name of the button on the toolbar is cmdA, add the following line of code in the edit box for the submenu item command:

    Copy Code
    Formset.toolbar.cmdA.Click

  4. Choose the button in the Options column to open the Prompt Options dialog box and choose Skip For.

  5. In the Expression Builder, enter an expression that indicates that the menu option should be skipped when the toolbar command button is not enabled.

    For example, if the name of the button on the toolbar is cmdA, enter the following expression in the Skip For box:

    Copy Code
    NOT formset.toolbar.cmdA.Enabled

  6. Generate the menu.

  7. Add the menu to the form set with the toolbar and run the form set.

When the user opens the menu, Visual FoxPro evaluates the Skip For condition, disabling the menu item if the associated toolbar command button is disabled. When the user chooses an item on the menu, the code in the Click event of the associated toolbar command button is executed.

See Also

Other Resources

How to: Define Toolbar Actions
How to: Add a Coordinated Toolbar and Menu to a Form Set
Creating Custom Toolbars
Customize Toolbar Dialog Box
Designing Menus and Toolbars
Customizing the Visual FoxPro Environment


How to: Add a Coordinated Toolbar and Menu to a Form Set

Visual FoxPro 9.0
How to: Add a Coordinated Toolbar and Menu to a Form Set
See Also

When you have created a toolbar class and a menu that are designed to work together, it is easy to incorporate them in a form set.

To incorporate a coordinated toolbar and menu in a form set

  1. Add the toolbar to the form set in one of three ways:

    • Drag the toolbar class from the Project Manager Window into the Form Designer.

    • Register the toolbar class library and add the toolbar to the form set from the Form Controls toolbar.

    • In the Init Event of the form set, include code with the AddObject Method to add the toolbar.

  2. In the Load Event of the form set, save the existing menu and run your menu program.

    For example, if your menu name is mymenu, include the following lines of code using the PUSH MENU Command and DO Command:

    Copy Code
    PUSH MENU _MSYSMENU
DO mymenu.mpr

  3. In the Unload event of the form set, restore the original menu with the POP MENU Command:

    Copy Code
    POP MENU _MSYSMENU

If some menu commands are used more than others, you can create custom toolbars containing buttons for those commands. Then, users can simply press the buttons whenever they need the commands. However, if you create a toolbar, you should synchronize the menu commands with their corresponding buttons. For example, if you enable a button, you should enable its corresponding menu command.

See Also

Other Resources

How to: Create the Coordinated Menu
How to: Test and Debug a Menu System
Creating Custom Toolbars
Customize Toolbar Dialog Box
Designing Menus and Toolbars
Customizing the Visual FoxPro Environment


How to: Test and Debug a Menu System

Visual FoxPro 9.0
How to: Test and Debug a Menu System
See Also

You can preview a menu system as you design it or you can test and debug it after generating the menu program.

To preview a menu system as you design it

  • In the Menu Designer, choose Preview.

When you choose Preview, the menu system you've defined appears at the top of the screen. Additionally, the Preview dialog box displays the file name (or a temporary file name) of the menu system.

If you select a menu title or menu item, it also appears in the Preview dialog box, along with the command assigned to it, if there is one.

To test a menu system

  1. From the Menu menu, choose Generate.

    If you've changed the menu, Visual FoxPro prompts you to save the changes.

  2. In the Generate Menu dialog box, enter a name for the generated menu program by typing the name in the Output File box or by choosing the dialog button.

  3. Choose Generate to produce a menu program file with an .mpr extension.

  4. From the Program menu, choose Do to run the program.

    Caution:
    If you modify the generated menu program (the .mpr file), you'll lose the changes when you modify the menu using the Menu Designer and then regenerate the menu program.

If the menu program doesn't work as intended, use the diagnostic tools provided with Visual FoxPro. For more information, see Testing and Debugging Applications.

Tip:
If you run an application (.exe file) in which the main program is a menu and the application terminates as soon as the menu is displayed, include the READ EVENTS Command in the cleanup code. You must also assign a CLEAR EVENTS command to the menu command that allows the user to exit the menu system.

See Also

Other Resources

How to: Add a Coordinated Toolbar and Menu to a Form Set
How to: Customize a Menu System
Creating Custom Toolbars
Customize Toolbar Dialog Box
Designing Menus and Toolbars
Customizing the Visual FoxPro Environment


How to: Customize a Menu System

Visual FoxPro 9.0
How to: Customize a Menu System
See Also

After creating a basic menu system, you can customize it. For example, you can create status bar messages, define menu locations, or define default procedures.

Displaying Status Bar Messages

When a menu or menu item is selected, you can display a status bar message describing the choice. Such a message helps the user by adding information about the menu choice.

To display a message when a menu or menu item is selected

  1. In the Prompt column, select the appropriate menu title or menu item.

  2. Choose the button in the Options column to display the Prompt Options dialog box.

  3. Select Message.

    The Expression Builder dialog box appears.

  4. In the Message box, type the appropriate message.

    Tip:
    Enclose character strings in quotation marks.

Defining the Location of Menu Titles

You can customize the location of user-defined menu titles in your applications. You can customize the location relative to the active menu system by choosing options in the General Options dialog box. Additionally, you can specify the location of menu titles when the user edits an object visually.

To specify a relative location for user — defined menu titles

  1. From the View menu, choose General Options.

  2. Choose the appropriate Location option: Replace, Append, Before, or After.

Visual FoxPro relocates all of the menu titles you've defined. If you want to relocate some but not all of them, drag the mover buttons next to the appropriate menu titles in the Menu Designer.

Additionally, you can specify the location of menu titles when the user edits an object in your application. If you include an object and the user activates it, your menu titles will not appear on the resulting menu bar unless you indicate that you want them there.

To control menu title location during object visual editing

  1. In the Prompt column, select the appropriate menu title.

  2. Choose the button in the Options column to display the Prompt Options dialog box.

  3. Set the Negotiate check box.

  4. Choose one of the following option buttons:

    • None does not place the menu title on the menu bar. Choosing None is the same as not choosing any option.

    • Left places the menu title in the left group of menu titles on the menu bar.

    • Middle places the menu title in the middle group of menu titles on the menu bar.

    • Right places the menu title in the right group of menu titles on the menu bar.

If you don't choose Left, Middle, or Right, the menu title will not appear on the menu bar when the user edits an object. For more information about editing objects visually, see Sharing Information and Adding OLE.

Saving and Restoring Menus

You can save and restore menus on the stack by pushing and popping them, which can be useful when you want to remove a menu temporarily, replace it with another, and then restore the original later on. The number of menus you save in memory is limited only by the amount of available memory.

Tip:
Check the available memory with the SYS(1016) function. For example, to check how much memory your menu system uses, call SYS(1016), push the menu on the stack, and then call SYS(1016) again.

To save or restore menus

  • Use the PUSH MENU or POP MENU commands.

Creating a Default Procedure for a Menu System

You can create a global procedure that applies to your entire menu system. Such a procedure runs whenever a menu without an assigned procedure is chosen.

For example, suppose you're developing an application for which some menus do not yet have submenus, procedures, and so on. For these menus, you can create a code stub that executes when the menus are chosen. For instance, you could create a general procedure that includes this function:

Copy Code
MESSAGEBOX("Feature not available")

To create a default procedure

  1. Open the menu system you're designing.

  2. From the View menu, choose General Options.

  3. Assign the procedure by doing one of the following:

    • Write or call a procedure in the Procedure box.

      -OR-

    • Select Edit and then OK to open a separate editing window and write or call a procedure.

Setting the System Menu

You can manipulate menus that use the Visual FoxPro menu system. You can disable your menus, add and remove items from your menus, restore the default Visual FoxPro menus, and control access to your menus during program execution.

To manipulate menus

  • Use the SET SYSMENU Command.

See Also

Other Resources

How to: Test and Debug a Menu System
General Options dialog box
Creating Custom Toolbars
Customize Toolbar Dialog Box
Designing Menus and Toolbars
Customizing the Visual FoxPro Environment


Working with Reports

Visual FoxPro 9.0
Working with Reports

After collecting and organizing data in your application, you can design, create, and add reports to your application project. To create a report, follow these general steps:

  1. Determine the type of report you want to create.

  2. Create the report page layout.

  3. Modify and customize the page layout file.

  4. Include and manage data for your report.

  5. Set output options for your report.

  6. Run the report.

In This Section

Reports in Visual FoxPro

Introduces reports and labels in Visual FoxPro.
Considerations for Creating Reports

Offers some best practices when creating reports and labels.
Working with Data in Reports

Describes how to provide and manage data for reports and labels.
How to: Create Reports

Explains how to create reports.
How to: Create Labels

Explains how to create labels.
How to: Open Reports and Labels

Explains how to open existing reports and labels.
Report Layout and Design

Describes aspects of setting up and organizing page layouts for reports and labels.
Running Reports

Describes how to generate output from reports and labels.
Distributing Reports with Applications

Discusses considerations for distributing reports in your application.
Extending Report Functionality in Visual FoxPro

Discusses ways you can leverage Visual FoxPro reporting extensibility features.

Reference

Report Wizard

Makes it possible for you to create reports quickly using a single free table or database table or view.
One-To-Many Report Wizard

Makes it possible for you to create a report quickly using tables with a parent-child relationship.
Label Wizard

Makes it possible for you to create labels quickly.
Report Designer

Describes the user interface of the Report Designer.
Label Designer

Describes the user interface of the Label Designer.
Language Reference

Provides a list of language reference topics in alphabetical order.

Related Sections

Working with Data

Describes how to create effective applications with indexes, tables, and databases.
Creating Applications

Discusses how to create a Visual FoxPro application, which may include one or more databases, a main program that sets up the application's system environment, and a user interface comprised of forms, toolbars, and menus.
Working with Projects

Defines a project configuration and a group of files that produce a program or final binary file or files.
Application Planning

Provides useful information about how the decisions you make during the planning phase impact how you create elements of the application.


Reports in Visual FoxPro

Visual FoxPro 9.0
Reports in Visual FoxPro
See Also

You can use reports to arrange and display data from tables in a database or application in a separate file. For example, you can create simple reports, such as a list of customer addresses, or more complex and specific reports, such as an invoice. Simple reports might be based on a single table whereas more complex reports might be based on multiple tables. You can also create special types of reports, such as labels. Labels are multicolumn reports that have particular column settings designed to fit label paper.

The following sections contain more information about reports in Visual FoxPro:

  • Report Layout Files

  • Report Layout Types

Report Layout Files

A report layout (.frx) file is a Visual FoxPro table storing the specifications for displaying data in a report. Each report file has an associated report memo (.frt) file. The .frx file specifies fields from data sources, text, and the arrangement of data that you want to display on the report page. A label layout (.lbx) file stores the specifications for displaying data in label format. Each label layout file also has an associated label memo (.lbt) file. Report and Label layout files have identical table structures.

The layout file does not store values from the data fields, only the arrangement and format of the data for a particular report or label. Therefore, depending on changes that might have occurred in the fields of the data source, values in the report can change each time you run the report or label.

Report Layout Types

Before creating a report, consider the general layout you want for the report. The following table lists descriptions of general layouts, common uses, and examples.

Layout type | Description | Examples
Form | Displays each record with fields placed vertically down the side. | Lists Form letters
Column | Displays each record in a row, with fields arranged horizontally across the page. | Group/Total report* Financial reports Inventory Sales summary
Multiple column | Contains more than one column of records. Records repeat vertically down the rows of the leftmost column and then continue to the next column. | Telephone directory Newspaper-style text
One-to-many* | Contains one record or a one-to-many relationship. | Invoices Account statements
Label* | Contains more than one column of records. Records repeat horizontally across the columns and then continue down to the next row. | Mailing labels* Name tags Business cards

* Layouts that have an associated report wizard.

See Also

Reference

Considerations for Creating Reports

Other Resources

How to: Create Reports
How to: Create Labels
Working with Reports


Considerations for Creating Reports

Visual FoxPro 9.0
Considerations for Creating Reports
See Also

There are a few guidelines you can use when designing and creating reports:

  • Use label controls to identify, attract, and focus attention on specific information and areas of the report.

  • Use appropriate spacing and positioning of information for enhancing organization, improving clarity and reducing clutter in the report, and leading the reader's eye to parts of the report. In general, the reader's eye travels through the top, center, right, and then the left parts of the screen or page.

  • Consider the type of output you intend to create when planning your basic design.

    For example, if you plan to provide on-screen display, do not make your readers scroll through information. If you cannot display the information in your report in the length of a single screen, consider reorganizing the information in a different way.

    If your users will print the report, consider whether they all have color printers before using color to display significant distinctions between records or fields, such as using red to distinguish negative numbers.

  • Test your reports with widely varied sample records, just as you would test forms and other parts of your application. Ensure that missing data elements have appropriate defaults or placeholders, and that unusually long values in data fields are not cut off.

See Also

Tasks

How to: Create Reports (Visual FoxPro)
How to: Create Labels

Concepts

Reports in Visual FoxPro

Other Resources

Working with Reports


Working with Data in Reports

Visual FoxPro 9.0
Working with Data in Reports
See Also

When you create reports or labels, you can specify the data to include in the report or label and control the environment in which the report accesses the data.

In This Section

Controlling Data in Reports

Discusses providing data for reports and labels, controlling selected records, and sorting and ordering those records.
How to: Specify a Report's Data Session

Explains how to set a private data session for a report.
How to: Load Data Environments for Reports

Describes how to use a DataEnvironment class definition you created for use with forms, or the data environment records saved with another report or label, to provide data for a report.
How to: Save Report Data Environments as Classes

Describes how to save the data environment definition you created for a report or label as a visual class, so you can re-use this definition for other reports in other areas of your application, such as form design.
Working with Related Tables using Multiple Detail Bands in Reports

Discusses different ways you can display data from different tables and how the report engine handles multiple tables at run time.

Related Sections

How to: Use Data Sessions

Provides information about using private and shared data sessions in an application.

See Also

Reference

DataEnvironment Object
Session Object

Other Resources

Controlling Access to Data


Controlling Data in Reports

Visual FoxPro 9.0
Controlling Data in Reports
See Also

Before running a report or label, you set up the data needed by your report or label layout. You provide data for reports and labels by choosing and making data sources available, controlling the records selected or filtered in those data sources, and sorting, ordering, and relating those records.

You can also manipulate data within reports by using report variables and calculated fields. Report variables and calculated fields store values that are dynamically calculated during the report run. Your report layouts can display the results of these calculations as well as the data derived directly from your data sources.

Controlling Data Sources for Reports

You can provide data for reports and labels in a variety of ways, depending on which is best for your situation.

If you always run a report with the same data sources, you can define a data environment that is stored with the report, pointing to specific tables. Saving the data environment places additional records in the report or label definition table for all open tables and index files, index order, and any relationships between tables. The steps you use to define the data environment objects for a report or labels are the same as the process you use to define the data environment for a form. For more information, see How to: Set the Data Environment.

You can also make data available for a report by specifying the data sources using code every time you run a report, which is useful when running the same report with different data sources.

The following table describes methods of making data available during a report run. Choose the method that suits the way you want to use data sources.

To | Add
Always use the same data sources. | Tables or views to the report's data environment. -OR- A DO <query> or SQL SELECT statement to the Init event of the report's data environment. For more information, see DO Command, SELECT - SQL Command, and Init Event.
Use separate sets of data sources. | One or more USE <table>,USE <view>, DO <query>, or SQL SELECT statements to Click event or other code that precedes a REPORT or LABEL command. For more information, see USE Command and Click Event.
Note:
Use aliases with the fields from the selected or driving table in the report only if you do not plan to use the report with data sources other than the original table. If you use a view or query as the data source and aliases are included in the report controls, sometimes the alias with which you designed the report might not be available at runtime. An error such as "Alias 'X' not found" occurs when the report engine evaluates expressions including the alias. At other times, if the original table is actually open, the alias might be available but not selected for this report run. In this case no error occurs, but the report displays the same record repeatedly on the report page.

Controlling Data Sessions for Reports

As part of deciding when and how to open data sources for a report, you determine whether to share these data sources with the report's environment.

Data sources for a report may be manipulated by your application before you run the report. For example, you can create a form that allows the user to navigate through a customer table. When the user clicks a Print button on your form, you run a report printing a current statement for the customer selected in the form. In this scenario, you run the report in the same data session as the form.

You can also choose to manipulate data for the report just before running the report, and completely independently of the report's surrounding environment. For example, the same customer form might have a button or menu option to Print a Sales Territory Summary, requiring you to summarize data from a number of tables not used directly in this form. In this scenario, you might choose to open the report data in a private data session. When the report finishes printing, the form's data environment and the selected customer record are undisturbed.

For more information, see How to: Specify a Report's Data Session.

Controlling Record Selection

By default, when you run a report against a table, each record in the table is processed. The report evaluates expressions in the report layout for each record, displaying appropriate results.

You can control selection of the records that appear in the report through the data source, report print options, or both.

The following table describes how to control record selection in the report based on whether you use a data source or report print options.

When using for record selection | Use
View or query | Conditions in the Filter tab of the View Designer or Query Designer. For more information, see Filter Tab, Query and View Designers.
SQL SELECT statement | WHERE or HAVING clause. For more information, see SELECT - SQL Command.
Report Designer | Setting in the Print Options dialog box. For more information, see Report and Label Print Options Dialog Box.
REPORT FORM command | Scope, FOR, or WHILE expressions. For more information, see REPORT Command and Field and Record Manipulation.
Table | Filtered index. For more information, see INDEX Command.

Controlling Record Relationships

Reports and labels process your selected records by moving the record pointer in the current work area. By setting up relationships between the table or view opened in the current work areas and other data sources, you can access other fields for use in report expressions. You can set the relationships in code, using SET RELATION and SET SKIP commands, or by using Relation objects in the DataEnvironment.

When you refer to fields not in the current work area in report expressions, you prefix the field names with the alias under which the additional tables or views are open. Refer to How to: Create and Use Table Aliases for more information.

Note:
The table or view in the current work area drives the REPORT FORM or LABEL FORM and is often termed its driving alias. Tables or view in the related work areas are known as target aliases because these work areas are the targets of SET RELATION command. When you establish relationships between tables, you can change the way reports and labels move through your data, to account for multiple records in the target aliases that may be related to each record in the driving alias. For example, a report on a table of invoice summary information may be related to multiple detail lines for each invoice. See Working with Related Tables using Multiple Detail Bands in Reports for information on coordinating multiple tables and relationships in reports.

Controlling Record Order

The page layout for reports and labels does not actually sort and order data. It processes records in the same order that they exist in the data source. You must perform sorting with a view, index, or other form of data manipulation outside the layout.

For example, if the data source is a table, you can sort and order the data by setting an appropriate index for the table, using an ordered view in the data environment, or using a query as the data source to display the records in groups. You can create a table index using code, for example, using the INDEX command, or as part of the report's data environment. If the data source is a query, view, or SQL SELECT statement, you can use the ORDER BY clause.

If you do not use the report's data sources to control the record order, the only way to control record order through the report is through the Order property of a cursor in the data environment.

See Also

Concepts

Reports in Visual FoxPro

Other Resources

Working with Data in Reports


How to: Specify a Report's Data Session

Visual FoxPro 9.0
How to: Specify a Report's Data Session
See Also

You can specify that the data session for the report is private to prevent changes to the global data session from affecting the data session for your report. Other designers or application code can affect the global data session, and these changes would otherwise affect the data available for your report. For example, external code could SET DELETED ON when your report expected the setting to be OFF, or it could close tables your report expected to be open.

To set a private data session

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Private Data Session.

You can also set the data session as private for the report or label by clicking Properties on the Report menu. When the Report Properties dialog box opens, click the Data Environment tab if it is not selected.

Note:
If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Page Setup dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Page Setup Dialog Box.

For more information, see Data Environment Tab, Report Properties Dialog Box (Report Builder).

See Also

Other Resources

How to: Use Data Sessions
Setting Protection for Reports


How to: Save Report Data Environments as Classes

Visual FoxPro 9.0
How to: Save Report Data Environments as Classes
See Also

You can save the data environments that you use for reports and labels as classes. You can then specify these data environment classes for other reports and labels or use them with forms or other parts of your application requiring the same data set-up.

To save the data environment for a report as a class

  1. Open the report or label in the appropriate designer.

  2. On the View menu, click Data Environment.

    The Data Environment designer opens.

  3. On the File menu, click Save As Class.

  4. In the Name box, type the name of the class.

  5. In the File box, type the visual class library (.vcx) file to store the class or click the ellipsis (…) button to browse for and select a file.

  6. In the Description box, type an optional description for the class.

For more information, see Save As Class Dialog Box.

See Also

Tasks

How to: Load Data Environments for Reports

Other Resources

Working with Data in Reports


How to: Load Data Environments for Reports

Visual FoxPro 9.0
How to: Load Data Environments for Reports
See Also

You can load a data environment for your report or label from another report (.frx) or label (.lbx) file, or from a visual DataEnvironment class definition.

You load the data environment from the Data Environment tab of the Report Properties dialog box.

Important
The ability to load a Data Environment is a feature provided by the ReportBuilder application. If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Properties dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Page Setup Dialog Box.

To load a data environment from another report

  1. Open the report or label to which you wish to add the data environment in the Report or Label Designer.

  2. On the Report menu, click Load Data Environment. Alternatively, choose Properties from the menu and click the Data Environment tab of the Report Properties dialog box.

  3. Select the option button to Copy from another report file.

  4. Click the Select button. The Open Dialog Box (Visual FoxPro) appears. Choose the report (.frx) or label (.lbx) file from which you wish to copy the Data Environment, and click OK.

  5. A message appears in a dialog box informing you that you are about to overwrite the current contents of your Data Environment for this report. If you are ready to do so, confirm by clicking Yes; otherwise, click No to cancel.

  6. The ReportBuilder confirms that it has updated the report or label's Data Environment, with a second dialog box.

  7. Open the report's Data Environment and verify that the tables and views from the original report or label's Data Environment are now loaded into this one. Any code from the original Data Environment should be repeated in the appropriate Data Environment methods.

To load a data environment from a DataEnvironment-based class definition

  1. Open the report or label and navigate to the Load Data Environment tab of the Report Properties dialog box, as above.

  2. Select the option button to Link to a DataEnvironment class.

  3. Click the Select button and choose an appropriate class library (vcx) or program file (prg) and DataEnvironment-based class from the list.

  4. As above, confirm that you wish to overwrite your existing Data Environment information. The ReportBuilder will provide an error message if the class you chose does not descend from DataEnvironment, or it will confirm that it has successfully updated the Data Environment in the current report or label.

  5. Open the report's Data Environment and verify that the tables and views from the visual class are now loaded into this report or label's Data Environment. You will find code, written by the ReportBuilder, binding the events and methods of the visual class included in the report or label's Data Environment code snippets. You can edit this code if needed.

See Also

Tasks

How to: Save Report Data Environments as Classes


Working with Related Tables using Multiple Detail Bands in Reports

Visual FoxPro 9.0
Working with Related Tables using Multiple Detail Bands in Reports
See Also

REPORT FORM and LABEL FORM are scoped commands. When you use any command with a scope clause, you can specify a record range and/or filtering conditions for records on which the command should act. If you do not specify a scope explicitly, each scoped command has a default scope. For reports and labels, the default scope is ALL.

Scope conditions and ranges are ordinarily evaluated with respect to, or driven by, the records in a single work area. In reports and labels, this means the Report Engine processes your report or label layout's detail band once for each record in your report scope. If your report includes group expressions, the detail band scope is the set of records belonging inside the innermost group break. When a group break occurs, the Report Engine pauses in its processing of the report scope, takes some other actions you specify, and then continues on through the scope. Otherwise, the detail band scope is equivalent to the report scope.

When you set up data for your report or label, you can relate other tables and cursors to the selected work area, or driving alias for the report. Along with standard Visual FoxPro scoping behavior, the Report Engine also provides the ability to make multiple passes through each detail band scope based on these relationships.

The Report Designer represents these multiple passes through the detail band scope by showing you multiple detail bands. You use different bands to display information for tables or cursors that are targets of different relationships.

Refer to the section on Working with Report Bands for information on how to adjust your report layout to indicate what related work areas are significant to report scope processing. This topic discusses how the Report Engine handles the multiple tables when you include these features in the report layout.

Using Target Aliases to represent Data Relationships

The target alias of a detail band refers to an open table or view in the current data session. In the Report Designer, target alias information may look like group break expressions, but it is quite different. When a group breaks, the record pointer moves forward. When the Report Engine moves to another detail band and re-evaluates the target alias, the record pointer moves back to the beginning of the detail band scope.

How the Report Engine validates Target Aliases at Run time

The Report Engine considers the driving alias of the report plus the Target alias attribute of each detail band to determine how to process each band. Before beginning the report run, it validates any target alias expressions contained in the report. To be valid, a target alias expression must evaluate to one of the following:

  • An empty string.

  • The alias of a table or view in relation to the driving alias for the report.

  • The driving alias for the report.

The Report Engine evaluates any expressions you have used as target aliases in your report layout, before it begins processing your report. If these expressions do not evaluate to aliases currently in use, the error "<alias> not found" occurs. If an alias is in use, it must either be the same as the driving alias or related to the report's driving alias. Otherwise, the error "<alias> is not related to the current work area" occurs.

Detail Bands with Target Aliases

The driving alias for a report with related tables is typically the parent in one or more data relationships. For example, a Customer table is related to an Orders table and a Payments table.

A report layout driven by this Customer table indicates these relationships by including one detail band with the target alias expression "Orders" and second detail band with the target alias expression "Payments".

Important
Include the quotation marks in each target alias expression, unless Orders or Payments is a variable holding the name of the actual alias.

For each detail band with a target alias, the Report Engine remains on the parent record and processes all the children in the appropriate target alias related to the current parent record. Then it moves to the next band, and processes the set of children in the next related table.

Detail Bands without Target Aliases

In reports with multiple tables and target aliases, you can use an empty target alias when you want a band to be processed only once for each driving alias record. This technique gives you a handy way to provide some summary information, similar to group headers and footers, but positioned more flexibly in your report output.

For example, in your Customer report, you might provide a data group on Customer ID, which enables you to provide information about the Customer in the group header or footer. By using a detail band with no alias, placed between the detail bands for Orders and Payments, you can provide additional information about the Customer, such as a string displaying current account status. Because this band has no target alias, its contents will appear only once before the Report Engine goes on to display Payments details.

Detail Bands with Target Aliases matching the Driving Alias

In most cases, setting a target alias to an expression matching the driving alias for a report results in the same behavior as an empty Target alias (the band is processed once for each record in the scope).

However, the Report Engine makes an important exception if you use this technique in the first detail band of the report: if the first band has a target alias exactly equal to the driving alias, it processes all the records in the detail scope, resets the record pointer in the driving alias, and then moves to the next detail band.

Using the driving alias as the target alias for the first band provides a way to process all the records in a current group or report scope multiple times. It also provides the ability to calculate some values for the current group before going on to display any content for the individual records. This technique is discussed further in the next section, Variables and Calculated Fields for Related Tables.

Automatic One-to-Many Behavior

Having validated any target alias expressions you have used for your detail bands, the Report Engine checks to see if you have explicitly set any OneToMany properties in your DataEnvironment or, if you are opening the tables yourself, whether the driving alias has any SET SKIP relationships set. If there are any already set, the Report Engine will not change your environment. However, if you have not set any one-to-many relationships explicitly, the Report Engine sets it up for your target aliases, and removes it at the conclusion of the report run. This automatic one-to-many behavior occurs only when you use at least one target alias in the report.

Variables and Calculated Fields for Related Tables

You can scope calculated fields and report variables to each of the various detail bands in a report layout, associating their dynamically-calculated results with the target aliases in each band.

Calculated fields in reports and report variables in Visual FoxPro versions previous to 9 could be Reset at the end of group(s), end of page, or end of report. The Reset at value indicated at what point in the report the Report Engine set these items back to their initial values, or on what basis their calculations were performed.

Another way of expressing this idea is to say that calculated fields and report variables are data-scoped based on their Reset values. In Visual FoxPro 9, the Reset at labels in Report Designer dialog boxes have been changed to Reset based on, to clarify this behavior.

In a report with multiple detail bands, you can scope report variables and calculated fields based on detail bands and their associated target aliases. For example, in your Customer report, you could scope a variable set to Count based on the detail band with the target alias Orders. This variable would provide a count of orders for each Customer. Because it is scoped to a band with correct target alias, this variable will provide a correct count. Without target alias expressions, the count would not be correct in cases where the Customer had more Payments than Orders.

Preprocessing report calculations

Because you can set up multiple detail bands with the same target alias, you can use one band to handle report calculations before displaying any content. In the Customer report example, you could have two bands with the target alias Orders. You could reset two report variables, OrderTotal and OrderCount, based on the first band but place all your report expressions displaying content from the Order table in the second band. The resulting calculations would allow you to provide a count and total of all orders in the detail header of the second band.

Using preprocessed report variables

When report variables are reset based on a detail band, their values remain correct after the Report Engine stops processing that band. Their values are not reset until the next time the Report Engine begins processing the same detail band (or its associated detail band header, if there is one) again. Any calculated results in these variables can be used in further calculations as you display information in additional report bands.

For example, you could use the OrderTotal variable to display a percent of total calculation, for each order in the second Orders band. After the Orders bands, you could also use the OrderTotal to calculate a running balance in the Payments band.

Preprocessing report variables based on the driving alias

Many people use a SQL-SELECT statement to produce a single driving cursor with fields sourced from multiple tables. Even with one cursor, you can still find it useful to set up multiple detail bands to process the same cursor multiple times. By using the driving alias as the target alias for the first detail band in a report, you have the opportunity to calculate values as if the values in the driving alias were repeated in a separate table.

See Also

Tasks

How to: Specify Target Aliases for Detail Bands

Reference

Scope Clauses
SET RELATION Command
TARGET( ) Function
SET SKIP Command
Relation Object
ChildAlias Property
OneToMany Property


How to: Create Reports (Visual FoxPro)

Visual FoxPro 9.0
How to: Create Reports (Visual FoxPro)
See Also

Depending on the complexity of the report or level of customization you want, you can create reports in several ways:

  • Create a simple report from a single or multiple tables using a report wizard.

    A wizard is the easiest way to start creating a report. For more information, see Creating Reports Using Wizards.

  • Create a simple report from a single table using Quick Report in the Report Designer.

    Quick Report is the fastest way to create a simple report and offers customization features of the Report Designer. For more information, see Creating Reports Using Quick Report.

  • Create a custom report or modify an existing report using the Report Designer.

    Report Designer begins the report design process with a blank report layout. The Report Designer and Label Designer are similar in functionality but differ in the default page and paper they use. For more information, see Creating Reports Using the Report Designer.

You can modify any report layout file you create with the Report Designer.

Creating Reports Using Wizards

You can create reports easily by using a report wizard. The report wizards help you set up and create a report layout using your answers to a series of questions. You can use the Report Wizard to create reports with single tables, for example, to create a list of names and addresses from a customer table. You can use the One-To-Many Report Wizard to create reports with tables that have a parent-child relationship, for example, to create a list of orders for a customer from a customer table and an orders table.

To start a report wizard

  1. Open the project for your application.

  2. In the Project Manager, expand the Documents node.

  3. In the Documents node, click Reports and then New.

  4. In the New Report dialog box, click Report Wizard.

  5. Select the type of report you want to create.

  6. Follow the instructions on the wizard screens.

For more information, see Report Wizard and One-To-Many Report Wizard.

You can also start wizards from the Tools menu by clicking Wizards and selecting a wizard. After you create a layout using a wizard, you customize the layout using the Report Designer.

Creating Reports Using Quick Report

You can create reports quickly by using Quick Report, which creates a simple report from a single table.

Tip:
You can use Quick Report in existing report files if the Detail band is empty. If the Page Header band contains controls, Quick Report saves them.

Note:
Quick Report does not add General fields to the report layout.

To create a quick report

  1. Open the project for your application.

  2. In the Project Manager, expand the Documents node.

  3. In the Documents node, click Reports and then New.

  4. In the New Report dialog box, click New Report.

    The Report Designer opens.

  5. On the Report menu, click Quick Report.

  6. In the Open dialog box, browse to the directory containing the table you want and select the table.

  7. In the Quick Report dialog box, click the field layout you want.

  8. To select specific fields to include, click Fields. When you are finished selecting fields, click OK.

    Note:
    By default, all fields except General fields in the table are included.

  9. Select or clear the Title, Add alias, or Add table to data environment settings.

  10. When you are finished in the Quick Report dialog box, click OK.

For more information, see Quick Report Dialog Box.

You can also start a quick report from the File menu by clicking New and in the New dialog box, click Report and then New File. The Report Designer appears. To continue, follow the remaining steps described for creating a quick report.

You can create a quick report programmatically without opening the Report Designer by using the Quick Report version of the CREATE REPORT command. For more information, see CREATE REPORT – Quick Report Command.

Creating Reports Using the Report Designer

You can create custom reports by starting with a blank report layout in the Report Designer.

Note:
The Report Designer and Label Designer are similar in functionality but differ in the default page and paper they use.

To start the Report Designer

  1. Open the project for your application.

  2. In the Project Manager, expand the Documents node.

  3. In the Documents node, click Reports and then New.

  4. In the New Report dialog box, click New Report.

    The Report Designer opens.

For more information, see Report Designer.

You can also start a new blank report from the File menu by clicking New and in the New dialog box, click Report and then New File.

You can open the Report Designer programmatically using the CREATE REPORT and MODIFY REPORT commands. For more information, see CREATE REPORT Command and MODIFY REPORT Command.

See Also

Reference

Considerations for Creating Reports

Other Resources

Reports in Visual FoxPro
How to: Create Labels
How to: Open Reports and Labels
Working with Reports


How to: Create Labels

Visual FoxPro 9.0
How to: Create Labels
See Also

You can create labels in several ways:

  • Create a simple label using the Label Wizard.

    A wizard is the easiest way to start creating a label. You can also install default label definitions, or templates, using the Label Wizard.

  • Create a custom label or modify an existing label using the Label Designer.

    Label Designer begins the label design process with a blank label layout. The Label Designer and Report Designer are similar in functionality but differ in the default page and paper they use.

You can modify any label layout file you create with the Label Designer.

Creating Labels Using the Label Wizard

You can create labels easily by using the Label Wizard. The Label Wizard helps you set up and create a label layout using your answers to a series of questions.

Note:
The first time you run the Label Wizard, it prompts you to install default label templates. This operation is performed only when you run the wizard for the first time.

To start the Label Wizard

  1. Open the project for your application.

  2. In the Project Manager, expand the Documents node.

  3. In the Documents node, click Labels and then New.

  4. In the New Label dialog box, click Label Wizard.

  5. Follow the instructions on the wizard screens.

For more information, see Label Wizard.

You can also start wizards by clicking Wizards on the Tools menu and selecting a wizard. After you create a layout using a wizard, you customize the layout using the Label Designer.

Creating Labels Using the Label Designer

You can create custom labels by starting with a blank label layout in the Label Designer.

Note:
The Label Designer and Report Designer are similar in functionality but differ in the default page layout definition use. The Label Designer also provides the ability to associate label templates with the Designer, so you can subdivide a page layout into predefined label sections. If the Label Designer does not provide you with a choice of label templates when you create a new label, run the Label Wizard to install them.

To start the Label Designer

  1. Open the project for your application.

  2. In the Project Manager, expand the Documents node.

  3. In the Documents node, click Labels and then New.

  4. In the New Label dialog box, click New Label.

    The Label Designer opens.

For more information, see Label Designer.

You can also start a new blank label from the File menu by clicking New and in the New dialog box, click Label and then New File.

You can open the Label Designer programmatically using the CREATE LABEL and MODIFY LABEL commands. For more information, see CREATE LABEL Command and MODIFY LABEL Command.

See Also

Other Resources

How to: Create Reports
How to: Open Reports and Labels
Working with Reports


How to: Open Reports and Labels

Visual FoxPro 9.0
How to: Open Reports and Labels
See Also

You can open an existing report or label to modify it. You can also open a report in protected mode to prevent users from changing part of the report or label that you specify.

To open a report or label

  1. On the File menu, click Open.

  2. In the Open dialog box, browse to the folder containing the report or label you want to open.

    Tip:
    To show only report files or label files, select Report (*.frx) or Label (*.lbx) in the Files of type box of the Open dialog box.

  3. Click the report or label file you want to open.

    The name of the file appears in the File name box.

  4. Click OK.

    The corresponding designer opens for the report or label.

To open a report or label in a project

  1. Open the project for your application.

  2. In the Project Manager, expand the Documents node.

  3. In the Documents node, expand the Reports or Labels node.

  4. In the Reports or Labels node, select the report or label you want to edit.

  5. In the Project Manager, click Modify.

    The corresponding designer opens for the report or label.

To open a report or label programmatically

  • Use the MODIFY REPORT or MODIFY LABEL command.

    The appropriate designer opens for the report or label.

For more information, see MODIFY REPORT Command and MODIFY LABEL Command.

To open a report or label in protected mode

  • Use the MODIFY REPORT or MODIFY LABEL command with the PROTECTED keyword.

    The appropriate designer opens for the report or label.

See Also

Other Resources

How to: Create Reports
How to: Create Labels
Report Layout and Design
Working with Reports


Report Layout and Design

Visual FoxPro 9.0
Report Layout and Design

When you create a report or label, you can customize the appearance of the report or label by making the following changes to the page layout in the Report Designer or Label Designer:

  • Change settings and properties for page.

  • Arrange data and information by specifying where and when they appear using report bands.

  • Group records using data groups.

Many of the topics in this section apply to organizing data in labels as well as reports.

In This Section

Working with Page Layouts

Introduces how to specify a range of settings for a page layout.
Working with Report Bands

Introduces how to specify where, when, and how to display data and information in reports.
Working with Report Data Groups

Introduces how to use data groups to group records in reports.
Working with Report Controls

Introduces how to add data and information to reports using controls.
Working with Report Variables

Describes how to use report variables to store, manipulate, and display calculated values.

Related Sections

Working with Data in Reports

Introduces how to include and manage data in reports.
Working with Reports

Introduces Visual FoxPro reports and labels and how to include them in your applications.


Working with Page Layouts

Visual FoxPro 9.0
Working with Page Layouts

You can change a wide range of settings for your report or label page.

In This Section

How to: Change Page Settings for Reports

Describes how to change the default report or label page settings, such as the left margin, paper size and type, and page orientation.
How to: Define Columns in Reports

Describes how to define columns for a report or label page.
How to: Configure the Page Layout Grid for Reports

Describes how to set options for the designer grid to so you can position and align objects along grid lines in reports and labels.

Related Sections

Report Layout and Design

Describes aspects of setting up and organizing page layouts for reports and labels.


How to: Change Page Settings for Reports

Visual FoxPro 9.0
How to: Change Page Settings for Reports
See Also

You can change the default page settings for a report or label. For example, you can change the left margin, the default font for the page layout, the paper size and source, and the page orientation.

Note:
When you change the paper size and page orientation, make sure the page orientation matches the paper size. For example, if you select an envelope, you should set the page orientation to Landscape.

Note:
When you set the default font for the page layout, the setting applies only to new report controls that you add to the report. For more information, see How to: Change Font Settings in Report Controls.

To set the left margin for the page

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Properties.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder, the Report Page Setup dialog box opens instead. If _REPORTBUILDER is set to a third-party builder, a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Page Setup Dialog Box.

  3. In the Report Properties dialog box, click the Page Layout tab if it is not selected.

  4. In Left margin box, type or select a value for the left margin.

  5. Click OK.

    Note:
    When you change the left margin for a page with columns, the width for the column changes automatically to accommodate the new margin.

For more information, see Page Layout Tab, Report Properties Dialog Box (Report Builder).

To change the default font for the page layout

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Default Font.

  3. In the Font dialog box, select the font style and size you want, and then click OK.

For more information, see Font Dialog Box.

You can also change the default font from the Report menu by clicking Properties to open the Report Properties dialog box. Click the Page Layout tab, and in the Default font area, click the ellipsis (…) button to open the Font dialog box.

Note:
When you use this method to adjust the default font for a report, the Report Builder notes the Script you selected for the font in the dialog box and adds this information to the report layout. You see the Use font script checkbox checked when you return to the Page Layout tab of the Report Properties dialog, and the label showing your selected font, font size, and style, also shows the numeric value representing this script. If you don't want to save this information, uncheck the checkbox. For more information, see Page Layout Tab, Report Properties Dialog Box (Report Builder).

Note:
If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Page Setup dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Page Setup Dialog Box.

To change the paper size or source

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Properties.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder, the Report Page Setup dialog box opens instead. If _REPORTBUILDER is set to a third-party builder, a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Page Setup Dialog Box.

  3. In the Report Properties dialog box, click the Page Layout tab.

  4. On the Page Layout tab, click Page setup.

    The Page Setup dialog box opens.

  5. In the Size box, select the paper size you want.

  6. In the Source box, select the paper source you want.

  7. When you are finished, click OK.

For more information, see Page Layout Tab, Report Properties Dialog Box (Report Builder).

To change the page orientation

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Properties.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder, the Report Page Setup dialog box opens instead. If _REPORTBUILDER is set to a third-party builder, a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Page Setup Dialog Box.

  3. In the Report Properties dialog box, click the Page Layout tab.

  4. Click Page setup.

    The Page Setup dialog box opens.

  5. In the Orientation area, click Portrait or Landscape, and then OK.

For more information, see Page Layout Tab, Report Properties Dialog Box (Report Builder).

See Also

Other Resources

How to: Open Reports and Labels
Working with Page Layouts
Working with Reports


How to: Define Columns in Reports

Visual FoxPro 9.0
How to: Define Columns in Reports
See Also

You can define multiple columns for the report or label page layout. Multiple columns divide a page layout into vertical sections. The Report Designer and Label Designer display one column, allowing you to place report controls only in a portion of the page layout. At runtime, the Report Engine repeats the column layout two or more times to fill the page.

Note:
If you increase the number of columns in your page layout after arranging report controls in the layout, you might need to move or resize the controls to fit within the new boundaries of column.

Columns have an associated pair of header and footer bands, which are nested inside the report's page header and page footer bands. Column header bands appear above any group header bands, and column footer bands appear below any group footer bands, in the Report Designer layout. The behavior of these bands and the options you can set for them is similar to those available for group header and footer bands. For more information, see How to: Add Bands to Reports.

However, the addition of multiple columns to a report layout can have an impact on the behavior of column, group, and detail header and footer bands in the report. This impact depends on how you set Column print order, as described in the procedures below.

To define columns for a report or label page layout

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Properties.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder, the Report Page Setup dialog box opens instead. If _REPORTBUILDER is set to a third-party builder, a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Page Setup Dialog Box.

  3. In the Report Properties dialog box, click the Page Setup tab.

  4. In the Number box, type or select the number of columns you want to appear across the page.

  5. In the Width box, type or select a value for the column width.

  6. In the Spacing box, type a value for the amount of space you want between each column.

    Note:
    The Spacing box is available only when specifying more than one column in the Number box. Use the Column print order option group to determine the print order appropriate to the data in this report or label. By default, the Report Designer selects the Top to bottom option button. In this print order, Report Engine prints records consecutively in a single column until reaching the end of the available height for the detail band on the current page. If you select the Left to right option button, the Report Engine prints records across the multiple columns, before continuing to print an additional record in the first column. This print order is the default for the Label Designer, and is often referred to as label style.

    Note:
    In Visual FoxPro 9.0, setting label-style print order has some additional impact on reports. When you use this option to make columns flow from left to right, group and detail header and footer bands extend across the page, so they can provide true header information for the entire row. The detail band starts one row down from any header bands you design in the layout. In earlier versions, Column print order did not change the behavior of group header and footer bands, so the first detail item printed adjacent to the innermost group header on the same row.

  7. Click OK.

For more information, see Page Layout Tab, Report Properties Dialog Box (Report Builder).

See Also

Concepts

Report Bands

Other Resources

How to: Open Reports and Labels
Working with Page Layouts
Working with Reports


How to: Configure the Page Layout Grid for Reports

Visual FoxPro 9.0
How to: Configure the Page Layout Grid for Reports
See Also

You can use the page layout grid to help you position and align report and label objects. You can set the following options for the grid:

  • Display grid lines, which do not appear in the resulting output.

  • Activate snap-to-grid functionality, which makes it possible for you to align objects to grid lines automatically.

  • Change measurement units for the ruler.

  • Set grid spacing.

  • Show the position of objects in the grid.

To show or hide grid lines

  1. Open the report or label in the appropriate designer.

  2. On the View menu, click Grid Lines so that it is selected.

    The designer shows grid lines for positioning and aligning report and label objects.

To activate snap-to-grid

  1. Open the report or label in the appropriate designer.

  2. On the Format menu, click Snap to Grid so that it is selected.

    When you drag objects in the designer, they position themselves along grid lines.

    Note:
    The visible grid lines provide guidance when you align controls in the layout. These lines do not determine the grid coordinates to which your controls snap when Snap to Grid is on. See Ruler/Grid Tab, Report Properties Dialog Box (Report Builder) for more information.

    Tip:
    You can enable Snap to Grid for general guidance even for reports requiring more exact placement. To override the automatic alignment feature and position controls exactly, select them in the layout and use the arrow keys to move them. You can also use the default Report Builder's options to adjust Size and position in layout for individual report controls. See General Tab, Report Control Properties Dialog Box (Report Builder) for more information.

To change the measurement unit for the ruler

  1. Open the report or label in the appropriate designer.

  2. On the Format menu, click Set Grid Scale.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Set Grid Scale dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Set Grid Scale Dialog Box.

  3. In the Report Properties dialog box, click the Ruler/Grid tab.

  4. In the Ruler list, select the measurement unit you want.

  5. When you are finished, click OK.

For more information, see Ruler/Grid Tab, Report Properties Dialog Box (Report Builder).

To set grid spacing

  1. Open the report or label in the appropriate designer.

  2. On the Format menu, click Set Grid Scale.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Set Grid Scale dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Set Grid Scale Dialog Box.

  3. In the Report Properties dialog box, click the Ruler/Grid tab.

  4. In the Horizontal spacing and Vertical spacing boxes, type or select the spacing you want.

  5. When you are finished, click OK.

For more information, see Ruler/Grid Tab, Report Properties Dialog Box (Report Builder).

To show object position in the grid

  1. Open the report or label in the appropriate designer.

  2. On the View menu, click Show Position so that it is selected.

    When you move the mouse or drag an object across the grid, the position displays in the status bar.

See Also

Other Resources

Working with Page Layouts
Report Layout and Design


Working with Report Bands

Visual FoxPro 9.0
Working with Report Bands

You can specify where, when, and how data and information display in reports and labels, by adding items that control their appearance and that perform user-defined operations to report bands.

In This Section

Report Bands

Describes and compares different types of report bands.
How to: Add Bands to Reports

Explains how to add report bands to a report layout.
How to: Change Report Band Height

Describes how to change report band height in a report layout.
How to: Change Detail Band Order

Describes how to use the Report Builder to change the order of multiple detail bands in a report layout.
How to: Specify Target Aliases for Detail Bands

Describes how to vary the order of records processed in a report run by specifying target aliases for one or more detail bands.
How to: Specify Expressions to Evaluate When Processing Bands

Explains how to create expressions that fire before and after the Report Engine processes a band during a report run.
How to: Add Comments to Report Bands

Describes how to add comments to indicate your design goals and other notes relevant to your use of a specific band in the report layout.
How to: Add User Data to Report Bands

Describes how to add user-defined data to the attributes stored in a report layout relevant to a specific band.
How to: Configure Output for Report Bands

Explains how to adjust report bands to account for lengthy or missing data, and how to configure optional bands.
How to: Delete Bands from Reports

Explains how to remove optional bands from a report layout.

Reference

Related Sections

Report Layout and Design

Describes aspects of setting up and organizing page layouts for reports and labels.
Working with Data in Reports

Describes how to provide and manage data for reports and labels.
Working with Report Data Groups

Discusses the use of data groups in reports and labels.
How to: Define Columns in Reports

Describes how to define columns for a report or label page.


Report Bands

Visual FoxPro 9.0
Report Bands
See Also

Report bands make it possible for you to specify where and when data displays on the report or label page. For example, suppose you create a contact list ordered by contact last names. You can use report bands to organize the information in this report. The following list contains some possible types of information for which you might want to designate different bands:

  • The name of the list using a title band, which appears once at the beginning of a report.

  • The total number of entries in the list using a summary band, which appears at the end of a report.

  • The report name, page number, and date using page header or page footer bands, which appear at the beginning or end of each page, respectively.

  • A separator between the last names of contacts beginning with each letter of the alphabet, to make it easier to find entries, using group header and footer bands, which appear each time the report moves to a record in which the first letter of the contact last name changes.

You can include the same types of report controls in all types of report bands, such as Field controls and calculated expressions for displaying data. For more information about report controls, see Working with Report Controls.

You choose different types of report bands, and place different types of report controls in each band, to present your data effectively. The following sections contain more information about types of report bands and their structure:

  • Types of Report Bands

  • Choosing Different Band Types for Report Content

  • Comparing Group and Detail Bands in Report Layouts

  • Functional Differences between Group and Detail Bands

Types of Report Bands

Reports contain several bands by default; however, you can add other bands to the report or label. The following table summarizes the types of report bands available and their approximate order in the page layout. Because bands can stretch in side, the table also tells you which bands allows you to continue their contents in multiple pages if their contents overflow a single page.

Band type Description Availability in layout Typically displays Can span more than a page

Title

Displays information or data that displays once at the beginning of the report.

Optional band, can be placed on separate page at the beginning of the report or immediately before the Page Header band on the first page.

Report title or title page, report date, page number, company logo, title border.

No

Page Header

Displays information or data that displays once per page at the beginning of the page.

Available by default.

Required band on all pages, except when Title and Summary bands are on separate pages. Optionally available on Summary page.

Report name, page number, report date.

No

Column Header

Displays information or data that displays once per set of columns preceding the column set.

Added automatically for each column created by the user. Does not appear when the report has only one column.

Preface to column set.

No

Group Header

Displays information or data that displays once per group preceding the group.

Added automatically for each data group created by the user.

Preface to a data group.

Yes

Detail Header

Displays information or data that displays once per record preceding the record.

Added by the user.

Optional band, available for every Detail Band in the layout.

Preface to a record.

Yes

Detail

Displays information or data that displays once per record in the underlying table.

Available by default.

One Detail Band is required in the report layout. The user can optionally include additional Detail Bands.

Data for each record.

Yes

Detail Footer

Displays information or data that displays once per record following the record.

Optional band, available for every Detail Band in the layout.

Summary for the record.

Yes

Group Footer

Displays information or data that displays once per group following the group.

Added automatically for each data group created by the user.

Calculated values for a data group.

Yes

Column Footer

Displays information or data that displays once per set of columns following the column set.

Added automatically for each column created by the user. Does not appear when the report has only one column.

Summary, column totals.

No

Page Footer

Displays information or data that displays once per page at the end of a page.

Required band on all pages, except when Title and Summary bands are on separate pages. Optionally available on Summary page.

Report name, page number, report date.

No

Summary

Displays information or data that displays once at the end of the report.

Optional band, can be placed on a separate page at the end of the report or immediately before the Page Footer band on the last page.

Report totals, summary page.

Note:
You can create grand totals by placing calculated expressions in the Summary band.

Yes

For more information, see Report Designer and Label Designer.

Choosing Different Band Types for Report Content

The use of Title and Summary bands is easily understood by comparing these sections of the report to a book's structure.

The Title band contains information that only appears once at the beginning of the report, similar to the book's front matter, such as a preface, acknowledgements, or table of contents. The Summary contains information only found at the end of the book, such as its index or colophon.

Page Headers and Page Footers are also similar to a book's. The book's title might appear in the top margin of every page, and the page number might appear in the bottom margin. Although books do not often have Column Headers and Column Footers, the use of these bands is also clear from their physical position in the page layout.

However, when a report contains multiple Detail bands and data groups, these bands look similar in the report layout. Their difference in structure in the report might not be clear initially. Also, at runtime, these bands do not always appear in the same physical locations in which they appeared during report or label design.

You can think of Group Headers and Group Footers as having a similar role to the introductory paragraphs and summaries you might find in each chapter of a book. The detail bands are analogous to the paragraphs that appear between these preparatory and concluding chapter sections; they can appear any number of times before the chapter ends.

The following section explains the differences between Detail bands and Group bands in more detail.

Comparing Group and Detail Bands in Report Layouts

When you add Detail bands, they appear consecutively in the page layout. Appearing consecutively means each new Detail band is added after the last Detail band, and each set of Detail Header and Detail Footer bands appear with the corresponding Detail band. A Detail band and its corresponding Detail Header and Detail Footer bands comprise a detail band set; no other bands can separate them. The consecutive structure of multiple Detail band sets makes it possible for you to include data from multiple child tables of a single parent. A Detail band's Target alias tells the Report Engine which set of related child records you want to process in this band. See How to: Specify Target Aliases for Detail Bands for more information.

When you add data groups, they and their corresponding Group Header and Group Footer bands appear nested in the page layout. Appearing nested means the first data group that is created appears at the most outer level in the page layout while the last data group created appears at the most inner level. The nested structure of data groups makes it possible for you to group records in reports based on a grandparent-parent-child relationship. A data group's Group on expression tells the Report Engine when to start a new group. For more information, see How to: Add Data Groups to Reports.

Functional Differences between Group and Detail Bands

The different ways the Report Designer displays Detail band sets and data groups mirror their different functions at run time. The two types of bands help you display different types of data relationships in reports.

For example, suppose you had a customer table with two child tables, orders and payments. Using multiple Detail bands, you can create a report containing the orders and payments for each customer. The orders and payments are not related to each other, because the entries in the orders and payments tables do not necessarily correspond to one another in any way.

In the same example report, suppose you have a SalesPeople table, with each salesperson being responsible for one or more customers. Using a data group, you can nest each salesperson's customers' details within a header or footer showing the name of the sales person. In another table, you store the names of sales territories, with each territory being served by one or more customers. You can nest the SalesPeople group inside an outer group displaying information about each territory.

Group bands occur when their Group on expression changes during the report. In the example report described above, the group expression might be territory or salesperson. A report data group requires a Group on expression. Detail bands have an optional Target alias expression, which may look like a Group on expression, but is quite different. In the example report, the Target alias expressions are "orders" and "payments" or variables referring to the aliases under which each child table is open.

For more information, see Working with Report Data Groups and Working with Related Tables using Multiple Detail Bands in Reports.

Detail band sets and group bands have some additional functional differences in reports:

  • It is impossible to have the Report Engine evaluate on a data group without a Group Header and Group Footer in the layout, representing the corresponding Group on expression. Detail Header and Group Footer bands are optional bands; a Detail band can constitute a detail band set without them.

  • If you include the optional Detail Header and Detail Footer bands for a detail band, these bands can appear in your report even if the child table specified by band’s target alias has no records matching the current parent record. This condition is impossible for Group Headers and Group Footers, since a group cannot exist without at least one detail row satisfying the group's Group on expression.

    Tip:
    If you do not want report controls in the Detail Header and Detail Footer to display when the Detail band has no contents, you can use Print when expressions to suppress them. Usually the correct expression to use in this scenario is EOF(<target alias>), where <target alias> is the Target alias expression you used for this Detail band. The EOF() function indicates when the record pointer is placed at end of file for this child table during the report run because there is no valid child record. You can close up the empty space in the Detail Header and Detail Footer bands, when these report controls do not print, using each control's option to Remove line if blank. Refer to How to: Suppress Blank Lines in Report Controls and Print When Tab, Report Control Properties Dialog Box (Report Builder) for more information.

  • The SUMMARY keyword on the REPORT FORM and LABEL FORM commands suppresses detail band sets, including Detail Header and Detail Footer bands. If you have specified expressions to evaluate on entry or on exit for these bands, they do not fire during a SUMMARY report run. SUMMARY does not suppress Group Headers and Group Footers, and their on entry or on exit expressions are evaluated. For more information, see How to: Specify Expressions to Evaluate When Processing Bands.

  • Reports have a limit of 74 nested data groups and a separate limit of 20 Detail band sets. Creating detail band sets does not subtract from the available number of data groups, and creating data groups does not limit the number of detail band sets you can add to your report.

See Also

Other Resources

How to: Add Bands to Reports
Working with Report Bands


How to: Add Bands to Reports

Visual FoxPro 9.0
How to: Add Bands to Reports
See Also

You can add bands to your reports and labels so you can specify additional areas and when to display certain data on the report or label page. You can add the following bands to reports and labels:

  • Title band.

  • Summary band.

  • Detail bands.

  • Page Header band, Page Footer band, or both, for a Summary band.

  • Detail Header and Detail Footer bands for a Detail band.

For more information, see Report Bands.

To add a Title, Summary, or Detail band

  1. Open the report or label for editing in the appropriate designer.

  2. On the Report menu, click Optional Bands.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder, the Optional Bands dialog box opens instead. If _REPORTBUILDER is set to a third-party builder, a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Optional Bands Dialog Box.

  3. In the Report Properties dialog box, click the Optional Bands tab.

  4. To select the bands you want to add, perform the following:

    • To add a Title band, in the Title area, click Report has title band.

      Tip:
      To specify that contents from the Title band displays on a separate page, click New page after title has printed.

    • To add a Summary band, in the Summary area, click Report has summary band.

      Tip:
      To specify that contents from the Summary band displays on a separate page, click Summary prints as new page. To add a Page Header or Page Footer band for the Summary Band, click Include page header with summary or Include page footer with summary, or both.

    • To add Detail bands, in the Detail bands area, click Add for every Detail band you want to add.

      Each Detail band that you add is numbered in the order you add them from lowest to highest.

  5. When you are finished, click OK.

For more information, see Optional Bands Tab, Report Properties Dialog Box (Report Builder).

To add Detail Header and Detail Footer bands for a Detail band

  1. In the appropriate designer, add a Detail band to the page layout.

  2. On the Report menu, click Edit Bands.

  3. In the Edit Bands dialog box, select the Detail band you want and click OK.

    The Detail Band Properties dialog box opens.

    Tip:
    You can also double-click the Detail band separator to open the properties dialog box for the Detail band.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Detail dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Detail Dialog Box.

  4. In the Detail Band Properties dialog box, click the Band tab.

  5. In the Detail properties area, click Associated header and footer bands, and then OK.

For more information, see Band Tab, Report Band Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Configure Output for Report Bands

Other Resources

How to: Open Reports and Labels
Working with Report Controls
How to: Delete Bands from Reports
Working with Report Bands


How to: Change Report Band Height

Visual FoxPro 9.0
How to: Change Report Band Height
See Also

You can change the height of report bands in the report or label page layout. For information about adjusting the report band height when generating output for reports, see How to: Configure Output for Report Bands.

To change the height of a report band

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Edit Bands.

    The Edit Bands dialog box opens.

  3. In the Edit Bands dialog box, select the band you want, and click OK.

    The properties dialog box for the report band opens.

    Tip:
    You can also double-click the band separator in the Report Designer or Label Designer to open the report band properties dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report band dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Band Properties Dialog Box.

  4. In the report band properties dialog box, click the General tab if it is not selected.

  5. In the Height box, type or select the height you want.

  6. Check the Constant band height checkbox if you want the band to have this height every time it appears. If you want the band to stretch when its contents need more room, uncheck this checkbox. All bands share this feature, although some bands can stretch only on a single page while others can span multiple pages if their contents require more space. Refer to Report Bands for more information.

  7. When you are finished, click OK.

For more information, see General Tab, Report Band Properties Dialog Box (Report Builder).

Tip:
You can also change the height of the report band by dragging the band separator to the height you want.

Note:
When a report band contains objects, you cannot drag the band separator past the lowest object in the band. However, you can reduce the height of the report band in the Height box of the General tab regardless of the height of the objects in the band. Any objects that no longer fit in the report band might appear partially or entirely in the report band below it. Make sure to reposition report band objects so they appear in the location you want.

See Also

Tasks

How to: Configure Output for Report Bands

Other Resources

Working with Report Bands


How to: Change Detail Band Order

Visual FoxPro 9.0
How to: Change Detail Band Order
See Also

You can change the order in which Detail bands appear in the report or label page layout.

Note:
If the _REPORTBUILDER system variable is not set to the default Report Builder, you might not be able to change the order of the Detail bands after you add them. For more information, see _REPORTBUILDER System Variable.

To change the order of Detail bands

  1. Open the report or label for editing in the appropriate designer.

  2. On the Report menu, click Optional Bands.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder, the Optional Bands dialog box opens instead. If _REPORTBUILDER is set to a third-party builder, a different dialog box might display. For more information, see Optional Bands Dialog Box.

  3. In the Report Properties dialog box, click the Optional Bands tab.

  4. In the Detail bands area, drag the mover button next to the Detail band you want to the position you want in the list.

For more information, see Optional Bands Tab, Report Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Add Bands to Reports

Other Resources

Working with Report Bands


How to: Specify Target Aliases for Detail Bands

Visual FoxPro 9.0
How to: Specify Target Aliases for Detail Bands
See Also

You can specify a target alias for each Detail band to vary the order of record processing.

To specify a target alias for a Detail band

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Edit Bands.

  3. In the Edit Bands dialog box, click the Detail band you want, and then OK.

    The Detail Band Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Detail dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Band Properties Dialog Box.

  4. In the Detail Band Properties dialog box, click the Band tab.

  5. In the Target alias expression box, type the target alias expression. To build an expression, click the ellipsis (…) button to open the Expression Builder.

    Note:
    Enclosing the target expression in quotation marks ("") evaluates the expression as a literal, while omitting quotation marks evaluates the expression as a variable containing the target alias.

  6. When you are finished, click OK.

For more information, see Band Tab, Report Band Properties Dialog Box (Report Builder).

See Also

Other Resources

Working with Report Bands
Working with Data in Reports


How to: Specify Expressions to Evaluate When Processing Bands

Visual FoxPro 9.0
How to: Specify Expressions to Evaluate When Processing Bands
See Also

You can specify expressions to evaluate before or after processing a band in the report or label page layout.

To specify expressions to evaluate when processing a report band

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Edit Bands.

    The Edit Bands dialog box opens.

  3. In the Edit Bands dialog box, select the band you want, and click OK.

    The properties dialog box for the report band opens.

    Tip:
    You can also double-click the band separator in the Report Designer or Label Designer to open the report band properties dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report band dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Band Properties Dialog Box.

  4. In the report band properties dialog box, click the General tab if it is not selected.

  5. In the Run expression area, perform the following:

    • To specify an expression to evaluate before processing the report band, type an expression in the On entry box.

    • To specify an expression to evaluate after processing the report band, type an expression in the On exit box.

    To build an expression, click the ellipsis (…) button next to the On entry or On exit box to open the Expression Builder. For more information, see Expression Builder Dialog Box.

For more information, see General Tab, Report Band Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Configure Output for Report Bands

Other Resources

Working with Report Bands


How to: Add Comments to Report Bands

Visual FoxPro 9.0
How to: Add Comments to Report Bands
See Also

You can add comments to report bands to help you identify and describe their purpose. Comments appear in the Comments field of the report structure table and do not appear in the report or label.

Procedures

To add comments to a report band

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Edit Bands.

    The Edit Bands dialog box opens.

  3. In the Edit Bands dialog box, select the band you want, and click OK.

    The properties dialog box for the report band opens.

    Tip:
    You can also double-click the band separator in the Report Designer or Label Designer to open the report band properties dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report band dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Band Properties Dialog Box.

  4. In the report band properties dialog box, click the Other tab if it is not selected.

  5. On the Other tab, click Edit comment.

    The comment dialog box for the report band opens.

  6. In the comment dialog box, type the comments you want, and click OK.

For more information, see Other Tab, Report Band Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Add Comments to Report Controls

Other Resources

Working with Report Bands


How to: Add User Data to Report Bands

Visual FoxPro 9.0
How to: Add User Data to Report Bands
See Also

You can add user-defined data to a report band. User-defined data appears in the User field of the report structure table and does not appear in the report or label.

To add user-defined data to a report band

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Edit Bands.

    The Edit Bands dialog box opens.

  3. In the Edit Bands dialog box, select the band you want, and click OK.

    The properties dialog box for the report band opens.

    Tip:
    You can also double-click the band separator in the Report Designer or Label Designer to open the report band properties dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report band dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Band Properties Dialog Box.

  4. In the report band properties dialog box, click the Other tab if it is not selected.

  5. On the Other tab, click Edit user data.

    The user data dialog box for the report band opens.

  6. In the user data dialog box, type the user-defined data you want, and click OK.

  7. For more information, see Other Tab, Report Band Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Add Comments to Report Bands

Other Resources

Working with Report Bands


How to: Configure Output for Report Bands

Visual FoxPro 9.0
How to: Configure Output for Report Bands
See Also

You can configure output for report bands in the following ways:

  • Control whether report bands maintain a constant height or adjust for lengthy data and suppressed blank lines.

  • Specify that the output from Title and Summary bands display on individual pages.

  • Specify that output from Detail bands start with a new column or page.

  • Reset the page number to 1 for each detail set.

  • Repeat the output from the Detail Header on each page.

  • Specify a minimum distance from the bottom of the page that determines when to begin detail sets on the next page.

To prevent report bands from adjusting their size to fit lengthy data or suppressed blank lines

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Edit Bands.

    The Edit Bands dialog box opens.

  3. In the Edit Bands dialog box, select the band you want, and click OK.

    The properties dialog box for the report band opens.

    Tip:
    You can also double-click the band separator in the Report Designer or Label Designer to open the report band properties dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report band dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Band Properties Dialog Box.

  4. In the report band properties dialog box, click the General tab if it is not selected.

  5. Click Constant band height, and then OK.

For more information, see General Tab, Report Band Properties Dialog Box (Report Builder).

To display Title or Summary band output on individual pages

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Optional Bands.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder, the Optional Bands dialog box opens instead. If _REPORTBUILDER is set to a third-party builder, a different dialog box might display. For more information, see Optional Bands Dialog Box.

  3. In the Report Properties dialog box, click the Optional Bands tab.

  4. Perform the following:

    • To specify that Title band output appear on a separate page, in the Title area, click New page after title has printed.

    • To specify that Summary band output appear on a separate page, in the Summary area, click Summary prints as new page.

  5. When you are finished, click OK.

For more information, see Optional Bands Tab, Report Properties Dialog Box (Report Builder).

To configure output for Detail bands

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Edit Bands.

  3. In the Edit Bands dialog box, click the Detail band you want, and then OK.

    The Detail Band Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Detail dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Band Properties Dialog Box.

  4. In the Detail Band Properties dialog box, click the Band tab.

  5. In the Detail properties area, select the output settings you want.

  6. When you are finished, click OK.

For more information, see Band Tab, Report Band Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Specify Expressions to Evaluate When Processing Bands

Other Resources

Working with Report Bands


How to: Delete Bands from Reports

Visual FoxPro 9.0
How to: Delete Bands from Reports
See Also

You can delete the Title, Summary, and Detail bands from your report or label. For information about deleting data groups, see How to: Delete Data Groups in Reports.

Note:
You cannot reduce the number of Detail bands to zero. The page layout must always contain one Detail band. When you reduce the number of Detail bands, the highest-numbered band, which is the band added last and appears at the lowest level of the layout, is deleted.

Caution:
If a Detail band contains items, the designer prompts you to confirm deleting the band. However, the designer does not prompt you for confirmation when clearing the Title band or Summary band check box, which deletes the band and any controls it contains.

To delete a Title, Summary, or Detail band

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Optional Bands.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Optional Bands dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Optional Bands Dialog Box.

  3. In the Report Properties dialog box, click the Optional Bands tab if it is not selected.

  4. On the Optional Bands tab, select the bands you want to remove:

    • To delete the Title band, clear the Report has title band check box.

    • To delete the Summary band, clear the Report has summary band check box.

    • To delete Detail bands, in the Detail bands list, select the Detail band you want, and click Remove. When the designer prompts you to confirm deletion, click Yes to confirm deletion.

  5. When you are finished, click OK.

For more information, see Optional Bands Tab, Report Properties Dialog Box (Report Builder).

See Also

Other Resources

How to: Open Reports and Labels
Working with Report Bands


Working with Report Data Groups

Visual FoxPro 9.0
Working with Report Data Groups

In a report or label layout, grouping records by certain fields or other criteria can make the report easier to read. Adding data groups to reports makes it possible for you to group records visually and display introductory and summary data for each group.

In This Section

Data Groups in Reports

Introduces data groups and describes their use.
How to: Add Data Groups to Reports

Describes how to add data groups.
How to: Edit Data Groups in Reports

Discusses editing data groups.
How to: Configure Output for Data Groups

Describes how to set output options for data groups.
How to: Delete Data Groups in Reports

Describes how to delete data groups.

Related Sections

Report Layout and Design

Describes aspects of setting up and organizing page layouts for reports and labels.
Working with Report Bands

Introduces how to specify where, when, and how to display data and information in reports and labels.


Data Groups in Reports

Visual FoxPro 9.0
Data Groups in Reports
See Also

You often want to examine data grouped on the basis of one or more criteria. These criteria are usually expressions based on one or more table fields, but can be much more complex. You designate a data group in a report by associating a Group on expression, your criterion for grouping the records, with the report.

For each set of records in which the expression evaluates to one value, you can designate certain actions you want the Report Engine to perform. These actions include providing summary content in the report output, and triggering program code.

Using Multiple Data Groups

Data groups are nested, which can be useful for organizing data and totaling expressions at different levels. For example, you can group records in a report by country by creating data groups based on the country name field. You can then group records by region within each country as a nested group.

To determine the nesting level for a data group, consider how often the value of the expression for the data group might change, then define the group that changes most often first. In the example report described in this section, the value of a country field changes more often than the value of a region field. Therefore, the country should be the outer two group, and the region should be the inner group.

Putting Data in Order for Groups

To group records effectively, you must sort the records appropriately before running the report. If the records with the same group value don't appear consecutively in the output, the Report Engine can't display the summary information or calculate your group-related values.

The report layout does not actually sort and order your data. It processes records in the same order that they exist in the data source. Sorting and ordering must be performed with a view, index, or other form of data manipulation outside the layout. For example, if the data source is a table, its records are probably not in the appropriate order for grouping. You can sort and order the data by setting an appropriate index on the table, using an ordered view in the data environment, or using a query as the data source to display the records in groups.

In the sample report described above, which contains two group levels, the records in the data source must be sorted country name and also by state or region within country, to appear properly in the output. If the report's data source is a table, you index the table on a key expression such as Country + Region.

Note:
Your index can contain additional elements not needed by the data groups in your report. In this example, your index expression could read Country + Region +City. This order would provide a sorted list of cities in the details you display for each region.

Report Display Options relevant to Data Groups

When you add data groups, you can preface and follow each group with a group header and group footer, which appear on the report layout as a Group Header band and a Group Footer band. Typically, the Group Header band contains a Field control for the field used by the group. You can also add other controls such as shapes or labels that display before the first record in a group. The Group Footer band often contains group totals and other summary information for the group.

You can also specify other options for data groups:

  • Printing text in headers and footers to identify specific groups.

  • Printing each group on a new page.

  • Resetting page numbers when groups are printed on a new page.

Triggering Code for a Data Group

You can perform actions programmatically for each data group. For example, each time a new region starts, you could insert a record into a cursor, with fields for the region name and the system variable _PAGENO. After running the report, you could use this cursor to provide a second report with an index or table of contents.

To perform this task during the run of the report, write a user-defined function and specify its name as the code to run during the On entry or On exit event for the Group Header band.

For more information, see How to: Specify Expressions to Evaluate When Processing Bands.

See Also

Concepts

User-Defined Procedures and Functions

Other Resources

How to: Add Data Groups to Reports
Working with Report Data Groups


How to: Add Data Groups to Reports

Visual FoxPro 9.0
How to: Add Data Groups to Reports
See Also

You can add one or more data groups to a report or label and nest groups to a maximum of 74 levels. Group Header and Group Footer bands accompany data groups automatically.

Note:
Records in the data source must be sorted and ordered according to the order that you want records to appear in each data group.

Tip:
Field controls that are used for grouping in the Detail band are usually moved to the Group Header band.

To add a data group

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Data Grouping.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Data Grouping dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Data Grouping Dialog Box.

  3. In the Report Properties dialog box, click the Data Grouping tab if it is not selected.

  4. On the Data Grouping tab, click Add.

    A data group expression appears in the Grouping nesting order list.

  5. In the Group on box, type the expression you want. To build an expression, click the ellipsis (…) button to open the Expression Builder.

  6. In the Group starts on area, select the output settings you want for the data group.

  7. To add another data group, click Add and repeat steps 4 through 5 for each data group expression. To remove a data group, click Remove.

    Tip:
    Expressions appear in the Group nesting order list in the order they are added initially. However, you can change the order of the group expressions. To change the expression order, drag the mover button to the left of the expression you want to move to the position you want.

  8. When you are finished, click OK.

    Group Header and Group Footer bands appear for each data group and surround all Detail bands in the layout. Each Group Header and Group Footer band displays the number of the data group and the data group expression. The Group Header and Group Footer bands with the highest number appear closest to the Detail band.

For more information, see Data Grouping Tab, Report Properties Dialog Box (Report Builder) and Expression Builder.

See Also

Other Resources

Data Groups in Reports
How to: Edit Data Groups in Reports
How to: Delete Data Groups in Reports
Working with Report Data Groups


How to: Edit Data Groups in Reports

Visual FoxPro 9.0
How to: Edit Data Groups in Reports
See Also

You can edit the expression for a data group and its output options. You can also change the order in which data groups appear.

Note:
When you change the order of a data group, all controls in a group band move to the new location. Changing the order of data groups does not change any previously defined controls. For example, if controls are positioned relative to the top or bottom of a group band, they remain anchored in that position in the band.

To edit a data group expression

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Data Grouping.

  3. The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Data Grouping dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Data Grouping Dialog Box.

  4. In the Report Properties dialog box, click the Data Grouping tab if it is not selected.

  5. In the Grouping nesting order list, select the expression you want.

  6. In the Group on box, type the new expression or change the expression in the Expression Builder by clicking the ellipsis (…) button.

  7. When you are finished, click OK.

For more information, see Data Grouping Tab, Report Properties Dialog Box (Report Builder) and Expression Builder.

To change output settings for a data group

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Data Grouping.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Data Grouping dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Data Grouping Dialog Box.

  3. In the Report Properties dialog box, click the Data Grouping tab if it is not selected.

  4. On the Data Grouping tab, change the output settings you want.

  5. When you are finished, click OK.

For more information, see Data Grouping Tab, Report Properties Dialog Box (Report Builder).

To change data group expression order

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Data Grouping.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Data Grouping dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Data Grouping Dialog Box.

  3. In the Report Properties dialog box, click the Data Grouping tab if it is not selected.

  4. In the Group nesting order list, drag the mover button to the left of the group expression you want to its new position.

  5. When you are finished, click OK.

For more information, see Data Grouping Tab, Report Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Configure Output for Data Groups

Other Resources

How to: Delete Data Groups in Reports
Working with Report Data Groups


How to: Configure Output for Data Groups

Visual FoxPro 9.0
How to: Configure Output for Data Groups
See Also

You can control the way output from data groups appears in your report or label. The following sections describe ways to configure output for data groups:

  • Specifying Page or Column Breaks for Data Groups

  • Preventing Orphaned Group Headers

  • Repeating Group Headers

Specifying Page or Column Breaks for Data Groups

You can use page or column breaks to specify that records for each group start on a new page or column.

To specify page or column breaks for a data group

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Data Grouping.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Data Grouping dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Data Grouping Dialog Box.

  3. In the Report Properties dialog box, click the Data Grouping tab if it is not selected.

  4. In the Group nesting order list, select the data group expression you want.

  5. In the Group starts on area, select New page or New column.

    Tip:
    To start the data group on a new page and reset page numbering to 1, click New page number 1.

For more information, see Data Grouping Tab, Report Properties Dialog Box (Report Builder).

Preventing Orphaned Group Headers

Sometimes the output from a data group might appear partially on one page and then finish on the next. In this scenario, the group header might appear near the bottom of the page with most of the records appearing on the next.

To avoid this scenario, set the minimum distance that a group header will display from the bottom of the page. If the group header will appear closer to the bottom than the distance you specify, the header appears on a new page.

To prevent orphaned group headers

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Data Grouping.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Data Grouping dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Data Grouping Dialog Box.

  3. In the Report Properties dialog box, click the Data Grouping tab if it is not selected.

  4. In the Group nesting order list, select the data group expression you want.

  5. In the Start group on a new page when less than box, select or type the minimum distance you want.

    Tip:
    A recommended value is one to three times the height of the Detail band plus the Group Header height.

For more information, see Data Grouping Tab, Report Properties Dialog Box (Report Builder).

Repeating Group Headers

When records from a group continue on the next page, you can repeat the group header for those records.

Tip:
You can mark multiple group bands to repeat their contents when a group continues to a new page. If you want controls in a group header band to repeat when the group continues on the next page, make sure you mark the group header band containing those controls to repeat their contents. Marking only one group header band only repeats the controls for that band.

To repeat the group header on the next page

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Data Grouping.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Data Grouping dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Data Grouping Dialog Box.

  3. In the Report Properties dialog box, click the Data Grouping tab if it is not selected.

  4. In the Group nesting order list, select the data group expression you want.

  5. Click Reprint group header on each page.

    Tip:
    Clearing the Reprint group header on each page box prevents the group header from repeating.

For more information, see Data Grouping Tab, Report Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Edit Data Groups in Reports

Other Resources

Working with Report Data Groups


How to: Delete Data Groups in Reports

Visual FoxPro 9.0
How to: Delete Data Groups in Reports
See Also

You can delete data groups, which deletes the Group Header and Group Footer bands, from reports and labels.

Note:
If a data group contains items, the designer prompts you to confirm deleting the band.

To delete a data group

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Data Grouping.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Data Grouping dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Data Grouping Dialog Box.

  3. In the Report Properties dialog box, click the Data Grouping tab if it is not selected.

  4. In the Group nesting order list, select the data group expression you want, and click Remove. When the designer prompts you to confirm deletion, click Yes to confirm deletion.

    The Group Header and Group Footer bands are deleted from the page layout.

For more information, see Data Grouping Tab, Report Properties Dialog Box (Report Builder).

See Also

Other Resources

Working with Report Data Groups


Working with Report Controls

Visual FoxPro 9.0
Working with Report Controls

Report controls and their settings provide a way for you to display data and information and customize its appearance in reports and labels.

In This Section

Adding Report Controls

Introduces adding different controls that display data or information to reports and labels.
Managing Report Controls

Describes manipulating report controls, for example, how to select multiple controls as a group, resize them, and change their alignment and relative position to each other.
Configuring Report Controls

Describes setting format options for report controls.

Reference

CREATE REPORT – Quick Report Command

Describes how to create a simple report quickly without opening the Report Designer.
CREATE REPORT Command

Describes how to programmatically open the Report Designer to create a report.

Related Sections

Working with Report Bands

Introduces how to display data and information in reports and labels.
Working with Data in Reports

Describes how to provide and manage data for reports and labels.
Report Layout and Design

Describes aspects of setting up and organizing page layouts for reports and labels.
Working with Reports

Introduces Visual FoxPro reports and labels and how to include them in your applications.


Adding Report Controls

Visual FoxPro 9.0
Adding Report Controls

You can add a variety of controls to reports and labels. The following table describes the report controls you can add and use.

Report control | Displays
Field | Values evaluated from variables, expressions, or fields in tables and views. These values can differ every time you generate output for the report or label.
Label | Text that appears the same every time you generate output for the report or label.
Line | Straight horizontal or vertical lines.
Rectangle | Boxes and borders.
Rounded Rectangle | Boxes with rounded corners, borders, circles, and ovals.
Picture/OLE Bound | Picture files or contents of General fields.

In This Section

How to: Add Field Controls to Reports

Describes how to add Field controls to reports and labels.
How to: Specify Expressions in Field Controls

Describes how to use expressions in Field controls to display values and data from fields.
How to: Specify Data Types for Field Controls

Describes how to specify the type of data in Field controls and appropriate formatting settings for the data type.
Format Expressions for Field Controls

Explains format expressions that you can specify for formatting output from Field controls.
How to: Perform Calculations in Field Controls

Describes how to specify that a type of cumulative calculation be applied to a Field control to determine the rendered value.
How to: Add Label Controls to Reports

Describes how to add Label controls to reports and labels.
How to: Add Shapes to Reports

Describes how to add shape controls, such as Line and Rectangle controls, to reports and labels.
How to: Add Pictures to Reports

Describes how to add pictures to reports and labels.
How to: Add General Fields to Reports

Describes how to add the contents of General fields to reports and labels.

Related Sections

Managing Report Controls

Describes manipulating report controls, for example, to select multiple controls as a group, resize them, and change their alignment and relative position to each other.
Configuring Report Controls

Describes setting format options for report controls.
Working with Reports

Introduces Visual FoxPro reports and labels and how to include them in your applications.


How to: Add Field Controls to Reports

Visual FoxPro 9.0
How to: Add Field Controls to Reports
See Also

Field controls are how you render data from variables, expressions, and fields in tables and views on a report or label. These values can change for each record traversed by the report engine as it processes the report.

If your report layout has an accompanying data environment, you can add fields from tables and views directly from the report's data environment.

To add a Field control to the page

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, point to Insert Control, and click Field.

    The Field Properties dialog box opens.

    Tip:
    You can also double-click the report control in the Report Designer or Label Designer to open the report control properties dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Expression dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Expression Dialog Box.

  3. In the Field Properties dialog box, click the General tab if it is not selected.

  4. In the Expression box, type the expression, variable, or table field you want. To build an expression, click the ellipsis (…) button to open the Expression Builder.

  5. When you are finished in the Expression Builder, click OK.

  6. In the Field Properties dialog box, specify the formatting settings that you want, and click OK.

    Tip:
    To specify that the bottom of the Field report control expands to fit the results of the expression when the control is populated, click Stretch with overflow.

    A Field control for the variable, expression, or field appears in the Page Header report band by default.

    Tip:
    You can add Field report controls at the position you want by selecting them on the Report Controls toolbar and drawing them. When you specify an expression in a Field report control, resize the Field report control to the minimum amount of space the expression requires. If more space is needed, you can set the control to stretch for larger values, but you cannot set it to reduce in size if less space is needed.

For more information, see How to: Specify Expressions in Field Controls, General Tab, Report Control Properties Dialog Box (Report Builder), and Expression Builder Dialog Box.

You can also specify the data types and output format options for the values stored in the Field control. For more information, see How to: Specify Data Types for Field Controls.

To add a Field control from the data environment directly

  1. Open the report or label in the appropriate designer.

  2. On the View menu, click Data Environment to open the data environment for the report.

  3. Drag the field you want from the table or view to the position you want in the designer.

    A Field report control for the field appears in the Page Header band by default. After you add the control, you can move it by dragging it to the position you want.

See Also

Other Resources

Managing Report Controls
Configuring Report Controls
Adding Report Controls
Working with Report Controls


How to: Specify Expressions in Field Controls

Visual FoxPro 9.0
How to: Specify Expressions in Field Controls
See Also

You can display the results of expressions on reports and labels by specifying expressions in Field controls. For example, you can include commonly used expressions and functions to display values such as the following:

  • Displaying the Current Date

  • Displaying Page Numbers

After you add Field controls with expressions that contain fields to the page, they might not display the way you want because of unwanted spacing. To remove unwanted spacing, you can trim and concatenate expressions that contain fields into a single expression. For more information, see Trimming and Concatenating Expressions.

Displaying the Current Date

You can display the current date on the page using a Field control.

To display the current date on the page

  1. Open the report or label in the appropriate designer.

  2. In the designer, add a Field control to the page layout.

    The Field Properties dialog box opens.

    Tip:
    You can also double-click the report control in the Report Designer or Label Designer to open the report control properties dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Expression dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Expression Dialog Box.

  3. In the Field Properties dialog box, click the General tab if it is not selected.

  4. In the Expression box on the General tab, type DATE(), and click OK.

For more information, see DATE( ) Function and General Tab, Report Control Properties Dialog Box (Report Builder).

You can view the date by previewing the report. For more information, see How to: Preview Reports.

Displaying Page Numbers

The Page Header or Page Footer band typically contains a page number. You can display page numbers using a Field control.

Note:
If you use a wizard or the Quick Report functionality, a page number is inserted automatically in the Page Footer band.

To display page numbers on the page

  1. Open the report or label in the appropriate designer.

  2. In the designer, add a Field control to the page layout.

    The Field Properties dialog box opens.

    Tip:
    You can also double-click the report control in the Report Designer or Label Designer to open the report control properties dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Expression dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Expression Dialog Box.

  3. In the Field Properties dialog box, click the General tab if it is not selected.

  4. In the Expression box on the General tab, type _pageno, and click OK.

For more information, see _PAGENO System Variable.

You can view the page numbers by previewing the report. For more information, see How to: Preview Reports.

See Also

Other Resources

How to: Add Field Controls to Reports
How to: Specify Data Types for Field Controls
Managing Report Controls
Configuring Report Controls
Adding Report Controls
Working with Report Controls


How to: Specify Data Types for Field Controls

Visual FoxPro 9.0
How to: Specify Data Types for Field Controls
See Also

You can specify the data type for the output generated by Field controls in reports or labels. The data type you choose determines the format options that are available for output generated from the Field control; however, your selection does not change the data type of the field in the source table.

You can specify formatting for output from a Field control depending on the data type of the output by building a format expression. For example, you might specify uppercase formatting for character output, insert commas or decimal points in numeric output, display numeric output in currency format, or convert one date format to another. For more information, see Format Expressions for Field Controls.

To specify data type and its format settings in a Field control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the Field control you want.

    The Field Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Expression dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable, Report Expression Dialog Box, and Format (Field) Dialog Box.

  3. In the Field Properties dialog box, click the Format tab if it is not selected.

  4. In the Format expression box, type the format expression you want, which can include format codes and template characters.

  5. On the Format tab, click the data type you want for the Field control.

  6. In the Format options area, select the format codes you want from those available for the selected data type.

    Tip:
    When using a combination of format codes and format template characters, precede the list of format template characters with the list of format codes.

  7. When you are finished, click OK.

For more information, see Format Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Other Resources

How to: Add Field Controls to Reports
Managing Report Controls
Configuring Report Controls
Adding Report Controls
Working with Report Controls


Format Expressions for Field Controls

Visual FoxPro 9.0
Format Expressions for Field Controls
See Also

You can create a variety of formats for output generated from Field controls by creating a format string expression. A format string contains format codes and format templates.

Format Codes

Format codes apply to all the characters in the Field control expression and must be preceded by the at sign (@) in the format string. For example, you can pad a numeric value with leading zeros instead of spaces by using the format string "@L 999999".

Format Code: | Description: | Applies to data of type:
! | Force text to uppercase. | Character only
B | Left justify . | All types
J | Right justify. | All types
I | Center justify. | All types
L | Leading zeros. | Numeric only
Z | Blank if zero. | Numeric, Date, and DateTime
( | Surround negative numbers with (). | Numeric only
C | Appends " CR" to positive, non-zero numbers. | Numeric only
X | Appends " DB" to negative, non-zero numbers. | Numeric only
$ | Uses currency notation. | Numeric only
D | Use current SET DATE setting. | All types
E | Display as if SET DATE BRITISH was in effect. | All types
YL | Display using system Long Date format. | Date
YS | Display using system Short Date format. | Date
R | Prevents non-formatting characters in the template string from replacing the corresponding character of the field expression value. When @R is used, the template string interleaves instead of overlaying. (See example below.) | Character and Numeric

Notes

  • Numeric data is right-justified by default.

  • Character and Date data are left-justified by default.

  • You can use combinations of format codes. For example "@CX" will display both credits and debits on numeric data, where appropriate.

For more information about how format codes are used in form controls, see Format Property.

Template Characters

Format template characters apply to individual characters in the Field control expression. You can create a pattern with format template characters with each character in the template representing a character you want to display. For example, some characters in a format template alter the display of specific character types. For example, including the character "Y" in a format template for a logical expression displays the letters "Y" instead of ".T." for True and "N" instead of ".F." for False. The character "9" in a format template is a placeholder for any digit in character or numeric data. Other format template characters, such as parentheses, spaces, and hyphens, display as themselves.

For more information about format template characters, see InputMask Property.

Examples

The following examples show how format codes and format template characters work together to create the output:

Field Expression Value | Format String | Rendered Output
-43.05 | @(CX 999.999 | ( 43.050 DB)
65.43 | (999) 999-9999 | ( ) - -43
"4505551023" | (999) 999-9999 | (505) 102-
"4505551023" | @R (999) 999-9999 | (450) 555-1023
ca90210 | @R !! 99999 | CA 90210

See Also

Reference

TRANSFORM( ) Function

Other Resources

How to: Specify Data Types for Field Controls
Managing Report Controls
Configuring Report Controls
Adding Report Controls
Working with Report Controls


How to: Perform Calculations in Field Controls

Visual FoxPro 9.0
How to: Perform Calculations in Field Controls
See Also

You can change the rendered value of a field control by specifying that a cumulative calculation be performed and the results displayed in place of the field expression value.

To specify that a cumulative calculation be applied to a Field control

  1. Open the report or label in the appropriate designer.

  2. In the designer, right-click on the Field control and select Properties… from the context menu.

  3. In the Field Properties dialog box, select the Calculate tab.

  4. Select a Calculation type.

  5. Select a Reset based on option.

For detailed information on the behavior of each calculation type, see Calculate Field Dialog Box.

Note:
If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Expression Dialog Box.

See Also

Tasks

How to: Add Field Controls to Reports

Reference

Calculate Field Dialog Box


How to: Add Label Controls to Reports

Visual FoxPro 9.0
How to: Add Label Controls to Reports
See Also

You can display text that appears the same every time you generate reports or labels by adding Label controls to the page layout.

For example, suppose you have a Field control that contains an expression for calculating a total. You can display the text "Grand Total" in a Label control to identify the contents of a Field control as a total.

To add a Label control to a report layout

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, point to Insert Control, and click Label.

    An editing cursor flashes in the report layout.

    Type in the characters for the label.

    Tip:
    You can also add Label controls at the position you want by selecting them on the Report Controls toolbar and drawing them. After you add the control, you can move it by dragging it to the position you want.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

To edit a label control caption

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the Label report control you want.

    The Label Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Text dialog box appears or a different dialog box might display. If the Text dialog box appears, edit text in the Label report control by clicking Label on the Report Controls toolbar, and then the Label control you want to edit in the designer. When you finish typing, click outside the Label control. For more information, see _REPORTBUILDER System Variable.

  3. In the Label Properties dialog box, click the General tab if it is not selected.

  4. In the Caption box on the General tab, type the changes to the text. To view and edit the entire text for the Label report control, click the ellipsis (…) button to open an editor dialog box.

  5. When you are finished, click OK.

    The updated text appears in the control.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Other Resources

Managing Report Controls
Configuring Report Controls
Adding Report Controls
Working with Report Controls


How to: Add Shapes to Reports

Visual FoxPro 9.0
How to: Add Shapes to Reports
See Also

You can separate or emphasize parts of a report by adding shapes, such as lines, rectangles, and circles, to the page layout. For example, you can use lines to separate report details and information in the header and the footer. You can use rectangles as borders around report controls, report bands, or the entire page. You can add shapes to reports using the Line and Rectangle report controls.

To add a shape to the report page layout

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, point to Insert Control, and click Line, Rectangle, or Rounded Rectangle.

    The shape report control you chose appears in the Page Header band by default. To move the shape to another location, drag the shape to the location you want.

You can also add shape report controls at the position you want by selecting them on the Report Controls toolbar and drawing them. After you add the control, you can move it by dragging it to the position you want.

See Also

Other Resources

Managing Report Controls
Configuring Report Controls
Adding Report Controls
Working with Report Controls


How to: Add Pictures to Reports

Visual FoxPro 9.0
How to: Add Pictures to Reports
See Also

You can add pictures to the report or label page layout. For example, you can add a company logo to the page header of an invoice. You can add pictures from image files or contents from General fields to reports using the Picture/OLE Bound control.

Tip:
When you want to add a picture that can vary depending on the record or a group of records, store the picture in a General field instead of a file. When you add the picture to the layout, add the picture by specifying the General field instead of a file. For more information, see General Field Type and How to: Add General Fields to Reports.

To add a picture to the page layout

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, point to Insert Control, and click Picture/OLE Bound.

    The Picture/OLE Bound Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Picture dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Picture Dialog Box.

  3. In the Picture/OLE Bound Properties dialog box, click the General tab if it is not selected.

  4. In the Control source area, perform one of the following:

    • To use an image file on disk (or in your project) on a report layout, click Image file name. In the Control source box, type the name of the file and include the path if needed.

      Tip:
      To browse for and select a file, click the ellipsis (…) button to display the Open Picture dialog box.

    • To use an image stored in a General field of a table, click General field name. In the Control source box, type the name of the General field containing the image.

      Tip:
      To browse for and select a field, click the ellipsis (…) button to open the Expression Builder dialog box. The Expression Builder dialog box displays available fields when the report's data environment contains a table or view.

    • To use an expression (such as a string variable, a non-General character field, or a string literal) that resolves to the name of an image file, click Expression or variable name.

      Tip:
      To build an expression or select a variable, click the ellipsis (…) button to opens the Expression Builder so that you can build an expression or select a variable. For more information, see Expression Builder Dialog Box.

    • To use an instance of a Visual FoxPro Image class as the source of an image on a report layout, click Expression or variable name., and enter a variable name containing an object reference to a form's Image control that has its PictureVal Property set appropriately.

      Tip:
      The use of an Image object's PictureVal property as a image source in a report is only supported in object-assisted output mode. It will work in backward-compatible mode, in some cases, but results are not guaranteed. For example, in backward-compatible mode, Picture/OLE Bound controls with this source may not respect the Clip sizing option. For more information, see SET REPORTBEHAVIOR Command.

  5. When you are finished in the Picture/OLE Bound Properties dialog box, click OK.

    The Picture/OLE Bound report control appears in the Page Header band by default. After you add the control, you can move it by dragging it to the position you want.

    Tip:
    You can add Picture/OLE Bound controls at the position you want by selecting them on the Report Controls toolbar and drawing them.

    If you specified an image file, the Picture/OLE Bound report control displays an image. If you specified a General field, the Picture/OLE Bound report control displays a generic frame. When you specify images, they retain their original size by default. For more information, see How to: Resize Report Controls.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

For an example of a report containing pictures, see the sample report Wrapping.frx in the Visual FoxPro directory, ...\Samples\Solution\Reports.

See Also

Other Resources

Graphics Support in Visual FoxPro
Managing Report Controls
Configuring Report Controls
Adding Report Controls
Working with Report Controls


How to: Add General Fields to Reports

Visual FoxPro 9.0
How to: Add General Fields to Reports
See Also

You can add contents in General fields to the report or label page layout. For example, you can add a Microsoft Excel document that is stored in a General field to a sales report. You can add General fields to reports using the Picture/OLE Bound control.

Tip:
Storing images in General fields make it possible for you to display a different picture depending on the record or a group of records. When you add the image to the layout, specify the name of the General field that contains the image instead of the file name. For more information, see General Field Type and How to: Add Pictures to Reports.

To add a General field to the page layout

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, point to Insert Control, and click Picture/OLE Bound.

    The Picture/OLE Bound Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Picture dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Picture Dialog Box.

  3. In the Picture/OLE Bound Properties dialog box, click the General tab if it is not selected.

  4. In the Control source area on the General tab, click General field name. In the Control source box, type the name of the General field.

    Tip:
    To browse for and select a field, click the ellipsis (…) button to open the Expression Builder dialog box. The Expression Builder dialog box displays available fields when the report's data environment contains a table or view.

  5. When you are finished in the Picture/OLE Bound Properties dialog box, click OK.

    The Picture/OLE Bound report control appears in the Page Header band by default. After you add the control, you can move it by dragging it to the position you want.

    Tip:
    You can add Picture/OLE Bound controls at the position you want by selecting them on the Report Controls toolbar and drawing them.

    If the General field in the table contains data other than an image file, such as a Microsoft Excel or Microsoft Word document, an icon representing that data appears on the report or label when you generate output for it. When you add General fields, their contents retain their original size by default. For more information, see How to: Resize Report Controls.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Other Resources

Managing Report Controls
Configuring Report Controls
Adding Report Controls
Working with Report Controls


Managing Report Controls

Visual FoxPro 9.0
Managing Report Controls

You can manage existing report controls by grouping them, moving them, and aligning them. You can manage each control inidividually, or group controls together to manage as a single unit. When you select a report control in the Report Designer or Label Designer, Visual FoxPro displays many report control management options that you can choose on the Format menu.

In This Section

How to: Select Multiple Report Controls

Describes how to select multiple report controls in order to set properties on them collectively.
How to: Group Report Controls

Describes how to group report controls so you can preserve their positions with respect to each other.
How to: Resize Report Controls

Describes how to adjust the size of report controls.
How to: Align Report Controls

Describes how to align report controls with each other to layout bands.
How to: Adjust Report Control Position

Describes how to adjust the position of report controls automatically when other controls or the report band change in height.

Reference

Keyboard Shortcuts

Lists keyboard shortcuts you can use in the Report and Label designers.

Related Sections

Adding Report Controls

Introduces adding different controls that display data or information to reports and labels.
Configuring Report Controls

Describes setting format options for report controls.
Working with Report Controls

Introduces topics about working with report controls in reports and labels.


How to: Select Multiple Report Controls

Visual FoxPro 9.0
How to: Select Multiple Report Controls
See Also

You can select multiple report controls in the Report Designer or Label Designer to manipulate them as a group temporarily. You can also clear selection of particular controls when you no longer want them as part of the group of selected controls in the designer.

To select multiple report controls

  1. Open the report or label in the appropriate designer.

  2. In the designer, choose one of the following:

    • To select multiple report controls, press and hold the SHIFT key while you select each control; or drag a selection box around the controls you want to select.

      -OR-

    • To select all report controls in a report band, press and hold the SHIFT key and double-click the report band containing the controls you want to select.

      -OR-

    • To select all report controls in the designer, on the Edit menu, click Select All.

      Tip:
      Sometimes report controls might be positioned off the screen. You can select these controls along with all other report controls in the designer by choosing Select All.

    As controls are selected, selection handles appear on the edges of each control.

You can now manipulate the selected report controls as a group temporarily.

To clear selection for a report control from a group of selected controls using the mouse

  1. In the designer, press and hold the SHIFT key while you use the mouse to click the report control that you wish to remove from the current selection.

To clear selection for a report control from a group of selected controls using the Report Builder's Multiple Selection dialog

  1. Right-click one of the selected controls, and select Properties from the context menu.

    The Multiple Selection dialog box opens.

    Tip:
    You can also double-click the group of selected report controls in the designer to open the Multiple Selection dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, a report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

  2. In the Multiple Selection dialog box, click the Selection tab if it is not selected.

  3. In the Object list on the Selection tab, click the report control that you want, then Clear selection.

    Tip:
    To select multiple controls in the Object list, press and hold the CTRL key while you click the name of each report control.

  4. When you are finished, click OK.

For more information, see Selection Tab, Multiple Selection Dialog Box (Report Builder).

See Also

Other Resources

Configuring Report Controls
Managing Report Controls
Working with Report Controls


How to: Group Report Controls

Visual FoxPro 9.0
How to: Group Report Controls
See Also

You can associate multiple controls with each other and save this preference in the layout by grouping them. After you format and align controls, grouping them is useful for preserving their positions with respect to one another. After you group controls, you can move them them as a single unit.

Note:
Properties are not available for grouped items. You must un-group them before you can invoke their properties dialog boxes.

To group controls

  1. Open the report or label in the appropriate designer.

  2. In the designer, select the controls you want to group.

  3. On the Format menu, click Group.

    The selection handles move from each control to surround the group of controls.

To remove grouping from grouped controls

  1. Open the report or label in the appropriate designer.

  2. In the designer, click the group of controls.

  3. On the Format menu, click Ungroup.

    The selection handles move from surrounding the group of controls to the edges of each of the controls that were in the group.

See Also

Other Resources

Configuring Report Controls
Managing Report Controls
Working with Report Controls


How to: Resize Report Controls

Visual FoxPro 9.0
How to: Resize Report Controls
See Also

You can resize any report control except Label controls. You can resize each report control manually or change their dimensions to match the size of a selected other report control.

To resize picture files and General fields in reports, first set them to scale. For more information, see Resizing Picture/OLE Bound Controls futher down in this topic.

You can also specify that the report control expands and contracts, or stretches, depending on its contents. For more information, see How to: Set Stretching Report Controls.

Note:
The size of a Label control depends on the length, font style, and font size of the contents in the control.

To resize a report control manually

  1. Open the report or label in the appropriate designer.

  2. In the designer, select the control.

    Selection handles appear on the edges of the control.

  3. Drag a selection handle to increase or decrease the size of the control.

    Tip:
    For more precise sizing, you can press and hold the SHIFT key while you press the arrow keys to change the size of a selected control.

To specify a size for a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control you want to resize.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

  3. In the report control properties dialog box, click the General tab if it is not selected.

  4. In the Height and Width boxes in the Size and position in layout area, type or select the height and width you want.

  5. When you are finished, click OK.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

To match the size of another report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, select the report controls you want using the multiple selection method.

    Note:
    If you group report controls using the Group command on the Format menu, only the To Grid sizing option is available. For more information, see How to: Group Report Controls.

  3. On the Format menu, select Size and choose the appropriate option from the submenu:

    • To Grid

    • To Tallest

    • To Shortest

    • To Widest

    • To Narrowest

    The selected controls resize according to the option you selected.

For example, selecting To Tallest as the sizing option resizes all selected controls to the tallest control.

Resizing Picture/OLE Bound Controls

Image files and General fields added to the report page layout retain their original size by default. When added to the layout, an image file or the contents of the General field might not fit the frame that contains the image or the General field. If the image or General field is larger than the frame, only a portion of the image or General field contents appear visible in the upper left corner of the frame. The remaining lower right portion extends beyond the frame and view.

However, you can resize image files and adjust the contents of General fields to fit their frames.

To resize a picture file or adjust a General field to fit its frame

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the Picture/OLE Bound control you want to resize, or right-click on it and select Properties from the context menu.

    The Picture/OLE Bound Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Picture dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Picture Dialog Box.

  3. In the Picture/OLE Bound Properties dialog box, click the General tab if it is not selected.

  4. On the General tab, choose one of the following options from the If source and frame are different sizes drop-down list:

    • To fill the frame with the image or contents of the General field but retain its relative proportions, click Scale contents, retain shape.

    • To fill the frame with the image or contents of the General field and stretch it vertically or horizontally as needed, click Scale contents, fill the frame.

      Note:
      Choosing Scale contents, fill the frame may distort the proportions of the image or General field.

  5. When you are finished, click OK.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Other Resources

Configuring Report Controls
Managing Report Controls
Working with Report Controls


How to: Align Report Controls Within the Layout

Visual FoxPro 9.0
How to: Align Report Controls Within the Layout
See Also

You can align report controls in different ways. The following list describes some of the ways you can align report controls:

  • Relative to each other.

  • Relative to the grid in the designer.

  • Relative to the center of the band.

To align controls with each other

  1. Open the report or label in the appropriate designer.

  2. In the designer, select the report controls you want to align.

  3. On the Format menu, point to Align, and click the alignment that you want.

    Note:
    The Center Vertically and Center Horizontally options apply to aligning report controls relative to the band they are in. If multiple controls are selected in multiple bands, then the alignment applies to the overall layout.

When aligning report controls relative to each other, Visual FoxPro uses the report control whose edge is the closest to alignment you select as the anchor.

Tip:
Aligning horizontally placed report controls with their right side or left side cause them to overlap each other. Likewise, aligning vertically placed report controls with their top or bottom edge cause them to overlap each other. Therefore, align report controls with an edge that is open for all selected controls and away from each other.

To align controls with the designer grid

  1. Open the report or label in the appropriate designer.

  2. On the Format menu, ensure that Snap to Grid. is selected.

    Any control movement you now make in the report layout will be constrained by the designer grid.

To allow future control movement to be unconstrained by the designer grid, clear the Snap to Grid setting on the Format menu.

To center controls within a band

  1. Open the report or label in the appropriate designer.

  2. In the designer, select the report controls you want to align.

  3. On the Format menu, point to Align, and click Center Vertically or Center Horizontally.

    The report controls move to the vertical or horizontal center of the band that contains them.

See Also

Tasks

How to: Adjust Report Control Position

Other Resources

Configuring Report Controls
Managing Report Controls
Working with Report Controls


How to: Adjust Report Control Position

Visual FoxPro 9.0
How to: Adjust Report Control Position
See Also

You can move or specify a position for report controls in the Report Designer. You can also specify that report controls adjust position automatically in output when the bottom of report controls positioned above them expands vertically or when the report band changes in height.

For example, the bottom of report controls such as Field and Picture/OLE Bound controls can expand vertically when they display, which affects the placement of other controls that appear beneath them in the layout. You can specify that the affected controls to adjust position automatically.

To adjust report control position manually

  1. Open the report or label in the appropriate designer.

  2. In the designer, drag the report control to the position you want.

To specify a position for a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control you want to reposition.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

  3. In the report control properties dialog box, click the General tab if it is not selected.

  4. In the From page top and From left boxes in the Size and position in layout area, type or select the position values you want.

  5. When you are finished, click OK.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

To adjust report control position automatically

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control you want to reposition automatically.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

  3. In the report control properties dialog box, click the General tab if it is not selected.

  4. In the Object position area, choose one of the following:

    • To specify that the report control move relative to the height of controls above it, click Float.

    • To specify that the report control remain in position relative to the top of the band, click Fix relative to top of band.

    • To specify that the report control remain in position relative to the bottom of the band, click Fix relative to bottom of band.

  5. When you are finished, click OK.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Other Resources

Configuring Report Controls
Managing Report Controls
Working with Report Controls


Configuring Report Controls

Visual FoxPro 9.0
Configuring Report Controls

When adding or editing report controls, you can add comments and change format settings. When a report control is selected in the Report Designer or Label Designer, Visual FoxPro displays many report control formatting options that you can choose on the Format menu.

In This Section

How to: Add Comments to Report Controls

Describes how to add comments for report controls.
How to: Add User Data to Report Controls

Describes how to add user-defined data for report controls.
How to: Add Tooltips to Report Controls

Describes how to add tooltips to report controls.
How to: Assign Structured Metadata to Report Controls

Describes how to add additional custom metadata to individual report controls.
How to: Change Styles of Report Controls

Describes how to the change report control styles.
How to: Change Alignment in Report Controls

Describes how to change the alignment in report controls.
How to: Change Colors in Report Controls

Describes how to change foreground and background colors, where available, for report controls.
How to: Change Font Settings in Report Controls

Describes how to change the font settings, such as style and size, in report controls.
How to: Change Opacity of Report Controls

Describes how to make report controls opaque or transparent.
How to: Set Stretching Report Controls

Describes how to set stretching for report controls.
How to: Suppress Repeated Values for Report Controls

Describes how to prevent repeated values from displaying in output from report controls.
How to: Suppress Blank Lines in Report Controls

Describes how to prevent blank lines from displaying in output from report controls.
How to: Specify Conditional Output for Report Controls

Describes how to specify output expressions that determine whether to display output from report controls.
How to: Add Design-time Captions to Field Controls

Describes how to configure a control so that it shows in the designer with alternative text, rather than the actual field expression.

Related Sections

Adding Report Controls

Introduces adding different controls that display data or information to reports and labels.
Managing Report Controls

Describes manipulating report controls, for example, to select multiple controls as a group, resize them, and change their alignment and relative position to each other.
Working with Report Controls

Introduces topics about working with report controls in reports and labels.


How to: Add Comments to Report Controls

Visual FoxPro 9.0
How to: Add Comments to Report Controls
See Also

When adding or editing a report control, you can add comment text that is saved as part of the layout file (.frx or .lbx) but do not appear in the rendered output. Comment text is useful for control-specific developer notes, or for whatever purpose you wish.

To add a comment for a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control to which you want to add comments.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

  3. In the report control properties dialog box, click the Other tab if it is not selected.

  4. In the Comment area, click Edit comment.

    The comment dialog box for the report control opens.

  5. In the comment dialog box, type the comment you want for the report control.

  6. When you are finished, click OK.

For more information, see Other Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Add User Data to Report Controls

Other Resources

Managing Report Controls
Configuring Report Controls
Working with Report Controls


How to: Add User Data to Report Controls

Visual FoxPro 9.0
How to: Add User Data to Report Controls
See Also

You can add user-defined data to a report control. User-defined data appears in the USER field of the report structure table (.frx or .lbx) and does not appear in the rendered output.

You can make use of the contents of the USER field in methods of a Reportlistener object when running a report or label in object-assisted mode. For more information, see Understanding Visual FoxPro Object-Assisted Reporting.

To add user-defined data to a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control to which you want to add user data.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

    Note:
    The dialog box that appears when there is no report builder set does not include the ability to edit the user-defined data.

  3. In the report control properties dialog box, click the Other tab if it is not selected.

  4. In the User data area, click Edit user data.

    The user data dialog box for the report band opens.

  5. In the user data dialog box, type the user-defined data you want for the report control.

  6. When you are finished, click OK.

For more information, see Other Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Add Comments to Report Controls

Other Resources

Managing Report Controls
Configuring Report Controls
Working with Report Controls


How to: Add Tooltips to Report Controls

Visual FoxPro 9.0
How to: Add Tooltips to Report Controls
See Also

When adding or editing a report control, you can assign text that will appear as a ToolTip as you hover the mouse pointer over the control. ToolTip text only appears in the Designer, and does not appear in the rendered output. ToolTip text is stored in the TAG2 field of the report structure table (.frx or .lbx).

To assign ToolTip text to a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control to which you want to add comments.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

    Note:
    The dialog box that appears when there is no report builder set does not include the ability to edit the ToolTip text for report controls.

  3. In the report control properties dialog box, click the Other tab if it is not selected.

  4. In the ToolTip area, click Edit ToolTip.

    The ToolTip dialog box for the report control opens.

  5. In the ToolTip dialog box, type the ToolTip text you want for the report control.

  6. When you are finished, click OK.

For more information, see Other Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Add User Data to Report Controls

Other Resources

Managing Report Controls
Configuring Report Controls
Working with Report Controls


How to: Assign Structured Metadata to Report Controls

Visual FoxPro 9.0
How to: Assign Structured Metadata to Report Controls
See Also

The default Report Builder application allows you to assign structured metadata to individual report controls and layout bands.

Metadata XML for report elements is stored in the STYLE field of the report structure table (.frx or .lbx). For more information about report and label tables, see Understanding and Extending Report Structure.

Note:
Reporting metadata XML documents are instances of Visual FoxPro's Memberdata XML Schema (.xsd), which also specifies metadata document format for Visual FoxPro Class and Property extensibility. For the full Memberdata Schema, see MemberData Extensibility.

The ReportBuilder.App permits direct text editing of the full XML memberdata element for a report control. It also exposes two supported attributes of Reporting metadata for convenient editing:

  • The Run-time extensions attribute can be used to store executable script.

  • The Execute When attribute can be used to specify an expression that ReportListener method code can evaluate in order to conditionally execute.

Just as it does not directly use the contents of the User Data field, the Report Engine does not reference report XML metadata directly. You can make use of the metadata in custom methods of a ReportListener object when running a report or label layout in object-assisted mode. For more information, see Understanding Visual FoxPro Object-Assisted Reporting. You can also write Report Builder extensions that use the metadata during report design sessions. For more information, see Report XML MemberData Extensions.

To assign Run-time extensions and Execute When metadata attributes to a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control to which you want to add user data.

    The Properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

    Note:
    The dialog box that appears when there is no report builder set does not include the ability to edit the report metadata.

  3. In the Report Control Properties dialog box, click the Other tab if it is not selected.

  4. In the Run-time extensions area, click Edit settings.

    The Run-time extensions dialog box for the report band opens.

  5. In the Run-time extensions edit box, type your script or run-time extension data. In the Execute When expression box, you can enter a value or expression that can be used by custom ReportListener classes at run-time.

  6. When you are finished, click OK.

For more information, see Other Tab, Report Control Properties Dialog Box (Report Builder).

To edit the metadata XML directly

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control to which you want to add user data.

    The Properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable. The default Report Builder also allows you to specify a different dialog box for metadata XML editing. For more information, see Report Builder Event Handler Registry Table

    Note:
    The dialog box that appears when there is no report builder set does not include the ability to edit the report metadata.

  3. In the report control properties dialog box, click the Other tab if it is not selected.

  4. In the Run-time extensions area, click Edit settings.

    The Run-time extensions dialog box for the report band opens.

  5. In the Run-time extensions dialog box, click Edit XML.

    The Metadata XML dialog box opens. If previously there was no metadata assigned to the selected control, the ReportBuilder places an empty XML template into the edit box.

  6. Enter values against the metadata attributes.

  7. When you are finished, click OK.

  8. For more information about the supported Reporting metadata XML document format, see the XML schema in MemberData Extensibility.

See Also

Tasks

How to: Add User Data to Report Controls

Other Resources

Managing Report Controls
Configuring Report Controls
Working with Report Controls


How to: Change Line Styles of Report Controls

Visual FoxPro 9.0
How to: Change Line Styles of Report Controls
See Also

You can change the line style in Line, Rectangle, and Rounded Rectangle controls. For example, you can change the line thickness or appearance for these controls. You can change the fill pattern in Rectangle and Rounded Rectangle controls. You can change the shape of Rectangle and Rounded Rectangle controls to display rounded corners or as circles.

Note:
Fill styles might not display if the control is set to transparent. For more information, see How to: Change Opacity of Report Controls.

To change the line style of report controls

  1. Open the report or label in the appropriate designer.

  2. In the designer, select the report control you want to change.

  3. On the Format menu, point to Pen, and click the line thickness or style you want.

    Tip:
    You can also double-click the report control to open the report control properties dialog box. In the report control properties dialog box, click the Style tab if it is not selected. In the Style list, select the line style you want. In the Weight list, select the line thickness you want. For more information, see Style Tab, Report Control Properties Dialog Box (Report Builder).

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

To change the fill pattern of report controls

  1. Open the report or label in the appropriate designer.

  2. In the designer, select the report control you want to change.

  3. On the Format menu, point to Fill, and click the fill pattern you want.
Note:
A shape that uses Fill style 0 ("empty" or "no fill") will always render and appear in the designer as transparent, regardless of the Backstyle mode. Conversely, a shape that uses Fill style 1 ("solid") will always render and appear in the designer as opaque, regardless of the Backstyle mode. For more information, see How to: Change Opacity of Report Controls.

To change the shape of report controls

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control you want to change.

    The report control properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

  3. In the report control properties dialog box, click the Style tab if it is not selected.

  4. In the Curvature list, type or select the curvature value for the report control.

  5. When you are finished, click OK.

For more information, see Style Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Other Resources

Managing Report Controls
Configuring Report Controls
Working with Report Controls


How to: Set Alignment of Report Control Contents

Visual FoxPro 9.0
How to: Set Alignment of Report Control Contents
See Also

You can change the alignment of text in Field and Label controls. Changing alignment in these controls affects only their contents and does not affect the alignment of the control on the page layout. You can also center the contents from General fields, specified by Picture/OLE Bound report controls, within their frames.

To change output alignment in a Field or Label control

  1. Open the report or label in the appropriate designer.

  2. In the designer, click the Field or Label report control you want to change.

  3. On the Format menu, point to Text Alignment, and click the alignment you want.

You can also change the alignment in a Field control depending on the data type you specify for the control on the Format tab in the Field Properties dialog box. For more information, see Format Tab, Report Control Properties Dialog Box (Report Builder).

Note:
If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Expression Dialog Box.

Centering Contents from General Fields in Frames

When specifying General fields in Picture/OLE Bound report controls, contents in General fields might vary in shape and size from the frames that contain them. When the frame is larger than its contents, the contents in the General field appear anchored in the upper left corner of the frame. You can center the contents from General fields horizontally within their frames.

To center a General field in its frame

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the Picture/OLE Bound report control.

    The Picture/OLE Bound Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Picture Dialog Box.

  3. In the Picture/OLE Bound Properties dialog box, click the General tab if it is not selected.

  4. On the General tab, click Center general field horizontally in frame.

  5. When you are finished, click OK.

    When generating output for the report, the contents from the General field appear centered within the frame.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Other Resources

Managing Report Controls
Configuring Report Controls
Working with Report Controls


How to: Change Colors in Report Controls

Visual FoxPro 9.0
How to: Change Colors in Report Controls
See Also

You can change the colors in Field, Label, Line, Rectangle, and Rounded Rectangle controls. Foreground and background colors are available depending on the report control.

Note:
Background colors might not display if the control is set to transparent. For more information, see How to: Change Opacity of Report Controls.

To change colors in report controls

  1. Open the report or label in the appropriate designer.

  2. In the designer, click the control you want to change.

  3. On the Format menu, click Foreground Color or Background Color depending on its availability for the control.

  4. In the Color dialog box, select the color you want, and then click OK.

You can also change foreground and background colors by double-clicking the report control to open the report control properties dialog box. Click the Style tab, clear the Use default foreground color or Use default background color check boxes, and then click the ellipsis (…) buttons to select different colors. For more information, see Style Tab, Report Control Properties Dialog Box (Report Builder).

Note:
If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

See Also

Other Resources

Managing Report Controls
Configuring Report Controls
Working with Report Controls


How to: Change Font Settings in Report Controls

Visual FoxPro 9.0
How to: Change Font Settings in Report Controls
See Also

You can change font settings in Field and Label controls. You can change the font setting in an existing control or the default font setting for new controls.

Note:
When you set the default font, the setting applies only to new Field and Label controls that you add to the page layout. To change the font and size for existing Field and Label controls, select the controls you want, and then change the font from the Format menu.

For more information about setting the default font for the page layout and new report controls, see How to: Change Page Settings for Reports.

To change the font for an existing Field or Label report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, click the Field or Label report control you want to change.

  3. On the Format menu, click Font.

  4. In the Font dialog box, select the font style and size you want, and then click OK.

    Important
    Field expression and text label controls are initially created without a specific font script. Selecting a non-default font using the Format menu as described above will store the selected Font Script setting in the report layout. The report engine will refer to this setting when rendering the report control. See below for how to reset the font script setting back to "use system default".

For more information, see Font Dialog Box.

You can also change font settings by double-clicking the report control to open the report control properties dialog box. Click the Style tab, and in the Font area, click the ellipsis (…) button to open the Font dialog box. For more information, see Style Tab, Report Control Properties Dialog Box (Report Builder).

Note:
If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

To set the Font Script specification for a Field or Label report control back to use system default

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the Field or Label report control you want to change, or right-click and select Properties.

    The report control properties dialog box opens.

  3. Select the Style tab.

  4. Clear the Use Font Script checkbox.

  5. Click OK.

For more information, see Style Tab, Report Control Properties Dialog Box (Report Builder).

Note:
If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

See Also

Other Resources

Managing Report Controls
Configuring Report Controls
Working with Report Controls


How to: Change Opacity of Report Controls

Visual FoxPro 9.0
How to: Change Opacity of Report Controls
See Also

You can change the opacity of Field, Label, Rectangle, Rounded Rectangle, and Picture/OLE Bound report controls. When a report control is opaque, objects appearing behind the report control are not visible. When a report control is transparent, objects appearing behind the report control are visible.

To change the opacity of a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, click the report control you want to change.

  3. On the Format menu, point to Backstyle, and click the opacity setting you want.

You can also change opacity settings by double-clicking the report control to open the report control properties dialog box. Click the Style tab, and in the Backstyle area, click the opacity setting you want. For more information, see Style Tab, Report Control Properties Dialog Box (Report Builder).

Note:
A shape that uses Fill style 0 ("empty" or "no fill") will always render and appear in the designer as transparent, regardless of the Backstyle mode. Conversely, a shape that uses Fill style 1 ("solid") will always render and appear in the designer as opaque, regardless of the Backstyle mode. For more information, see How to: Change Line Styles of Report Controls.

Note:
If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

See Also

Other Resources

Managing Report Controls
Configuring Report Controls
Working with Report Controls


How to: Set Stretching Report Controls

Visual FoxPro 9.0
How to: Set Stretching Report Controls
See Also

You can specify that controls on reports and labels stretch, or automatically expand and contract to accommodate the output they generate. For example, a Field control that contains a memo field expression may evaluate to varying amounts of text from record to record. Therefore, you can set the control to stretch according to the amount of information it contains. If you are using a shape as a border around one or more field expression controls, you can also specify that the shape stretches to accommodate the varying size of the controls it encompasses.

Controls that can stretch might affect the position of other controls that appear below them in the layout. You can set the other controls to float, or adjust position automatically according to changes in size of the controls above them. For more information about adjusting report control position automatically, see How to: Adjust Report Control Position.

The following illustration shows how stretching and floating report controls function.

The following sections contain information about working with stretching controls:

  • Specifying Stretching for Report Controls

  • Displaying Borders for Stretchable Controls

Specifying Stretching for Report Controls

The following control types can be set to stretch:

  • Field/Expression

  • Vertical line

  • Rectangle / Rounded rectangle

For Line, Rectangle, and Rounded Rectangle controls, you can specify that they stretch relative to the height of the band that contains them or, if grouped, relative to the largest control in the group.

Caution:
You must set floating for controls that are placed underneath controls that stretch; otherwise, the output generated from controls that stretch might overlap output in controls appearing underneath them. Output from controls might also be overwritten on the page layout when any of the following conditions occur:

To specify stretching for a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control you want.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

  3. In the report control properties dialog box, click the General tab if it is not selected.

  4. On the General tab, choose one of the following:

    • For Field controls, click Stretch with overflow.

    • For Rectangle, Rounded Rectangle, or vertical Line controls, in the Stretch downwards area, click the stretch setting you want.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

For examples, see the sample report Wrapping.frx in the Visual FoxPro ...\Samples\Solution\Reports directory.

To position a stretching report control below another

  1. Open the report or label in the appropriate designer.

  2. In the designer, position one report control below the other.

  3. Double-click the report control that appears above the other control.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

  4. In the report control properties dialog box, click the General tab if it is not selected.

  5. In the Object position area, click Fix relative to top of band, and then OK.

  6. Double-click the report control that appears below the other control.

    The properties dialog box for the report control opens.

  7. In the report control properties dialog box, click the General tab if it is not selected.

  8. In the Object position area on the General tab, click Float, and then OK.

For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).

Displaying Borders for Stretchable Controls

You can use a shape control as a border around a report control, and specify that it stretches with the control.

To display a border for a stretching control

  1. Open the report or label in the appropriate designer.

  2. In the designer, draw a border by dragging a Rectangle or Rounded Rectangle report control around the report control that stretches.

  3. Double-click the Rectangle or Rounded Rectangle report control.

    The Rectangle Properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Rectangle/Line or Round Rectangle dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable, Rectangle/Line Dialog Box, and Round Rectangle Dialog Box.

  4. In the Rectangle Properties dialog box, click the General tab if it is not selected.

  5. In the Stretch downwards area, click Stretch relative to tallest object in group, and then OK.

  6. Drag a selection box around the Rectangle or Rounded Rectangle control.

  7. On the Format menu, click Group.

You can now manipulate both controls permanently as a single unit. The Rectangle or Rounded Rectangle control stretches when the report control within its boundaries stretches.

For more information, see How to: Add Shapes to Reports and How to: Group Report Controls.

See Also

Tasks

How to: Resize Report Controls

Other Resources

Configuring Report Controls


How to: Suppress Repeated Values for Report Controls

Visual FoxPro 9.0
How to: Suppress Repeated Values for Report Controls
See Also

You can suppress the display of repeated values in consecutive records so that the value appears once for the first record but not for subsequent records until the value changes. You can also suppress the repeat display of report controls.

For example, suppose you have an invoice with underlying table fields that contain the date of the transaction. You can specify that the date appears only once for transactions that occurred on the same date.

You can also choose to repeat values only when a new page or column begins, when the data group changes, or when a Detail band continues with the next page or column.

To suppress repeated values or report controls

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control you want.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. In the report control dialog box, click Print When to open the Print When dialog box. For more information, see _REPORTBUILDER System Variable and Print When Dialog Box.

  3. In the report control properties dialog box, click the Print when tab if it is not selected.

  4. In the Print repeated values area, click No, and then OK.

For more information, see Print When Tab, Report Control Properties Dialog Box (Report Builder).

To repeat values or report controls under specific conditions

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control you want.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. In the report control dialog box, click Print When to open the Print When dialog box. For more information, see _REPORTBUILDER System Variable and Print When Dialog Box.

  3. In the report control properties dialog box, click the Print when tab if it is not selected.

  4. In the Print repeated values area on the Print when tab, click No.

  5. In the Also print area, choose one of the following:

    • To repeat values or the report control only for a new page or column, click In first whole band of new page/column.

    • To repeat values or the report control only when the data group changes, click When this data group expression changes. Select the appropriate data group from the drop-down list.

    • To repeat values or the report control only when the band continues with the next page or column, click When band content overflows to new page/column and In first whole band of new page/column.

  6. When you are finished, click OK.

For more information, see Print When Tab, Report Control Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Suppress Blank Lines in Report Controls

Other Resources

Configuring Report Controls


How to: Suppress Blank Lines in Report Controls

Visual FoxPro 9.0
How to: Suppress Blank Lines in Report Controls
See Also

Your report might include records that do not contain values for every field on the report. By default, Visual FoxPro leaves the area for that field blank. To reduce the "white space" in the rendered report output, you can specify that the report engine vertically contracts the report output in cases where all controls in a horizontal line across the layout render as empty.

To suppress blank lines in a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control you want.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Print When Dialog Box.

  3. In the report control properties dialog box, click the Print when tab if it is not selected.

  4. On the Print when tab, click Remove line if blank, and then OK.

For more information, see Print When Tab, Report Control Properties Dialog Box (Report Builder).

Note:
When a field in a report band is blank or the field in the underlying table is empty, Visual FoxPro checks the report band for other report controls. If no other controls exist in the report band, Visual FoxPro removes the entire line. You can choose whether the report band adjusts for suppressed blank lines. For more information, see How to: Configure Output for Report Bands.

See Also

Tasks

How to: Suppress Repeated Values for Report Controls

Other Resources

Configuring Report Controls


How to: Specify Conditional Output for Report Controls

Visual FoxPro 9.0
How to: Specify Conditional Output for Report Controls
See Also

You can specify a logical condition that is evaluated by the report engine to determine whether to render output for a control. If the expression evaluates to False (.F.), output from the control does not display.

For examples of output expressions, see the sample reports Colors.frx and Ledger.frx in the Visual FoxPro ...\Samples\Solution\Reports directory.

To add an output expression to a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the control you want.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. In the report control dialog box, click Print When to open the Print When dialog box. For more information, see _REPORTBUILDER System Variable and Print When Dialog Box.

  3. In the report control properties dialog box, click the Print when tab if it is not selected.

  4. In the Print only when expression is true box, type an expression or build one by clicking the ellipsis (…) button to open the Expression Builder.

  5. When you are finished, click OK.

For more information, see Print When Tab, Report Control Properties Dialog Box (Report Builder) and Expression Builder Dialog Box.

See Also

Other Resources

Configuring Report Controls


How to: Add Design-time Captions to Field Controls

Visual FoxPro 9.0
How to: Add Design-time Captions to Field Controls
See Also

For Field report controls, you are able to assign a design-time caption that shows up in the Report Designer layout in place of the regular field expression.

Design-time captions are only visible in the designer when the design session was launched using the PROTECTED keyword. For normal design sessions, the field expression is shown in the field control.

This design-time caption is a literal string, stored in the NAME column of the report layout source file (.frx or .lbx). The default report builder application, ReportBuilder.app, exposes this property for Fields on the Protection tab. For more information, see Protection Tab, Report Control Properties Dialog Box (Report Builder).

To set a design-time caption on a Field report control

  1. Open the report or label layout in the appropriate designer.

  2. In the designer, double-click the control you want or right-click it and select Properties from the context menu.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. There is no way to set a design-time caption using the native report control dialog box. For more information, see _REPORTBUILDER System Variable.

  3. In the report control properties dialog box, click the Protection tab.

  4. Enter a character string in the Design-time caption text box. For example, for a field control with an expression of DATETIME(), you might enter a sample of the output like "13 July 1996 14:25."

    Note:
    Design-time captions are not expressions. You must enter a literal series of characters. Do not surround them with quote marks unless you want the quote marks to appear in the designer as part of the visible caption.

  5. When you are finished, click OK.

See Also

Other Resources

Configuring Report Controls
Setting Protection for Reports


Working with Report Variables

Visual FoxPro 9.0
Working with Report Variables

You can use report variables to store values that you want to manipulate, calculate, or display in a report when generating output for the report.

In This Section

How to: Define Report Variables

Explains how to declare and define report variables.
How to: Change Report Variable Order

Explains how to change the order in which report variables are evaluated in reports.
How to: Reset Report Variables

Explains how to reset the values of report variables to their initial value at specific points during the report processing.

Related Sections

Working with Data in Reports

Describes how to provide and manage data for reports and labels.
Report Layout and Design

Describes aspects of setting up and organizing page layouts for reports and labels.


How to: Define Report Variables

Visual FoxPro 9.0
How to: Define Report Variables
See Also

You can define variables in the report or label layout for storing, manipulating, and displaying values.

Report variables are PUBLIC in scope, and remain available after a report run (unless you explicitly specify that they should be released).

Defining report variables

To define a report variable

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Variables.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Variables dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Variables Dialog Box.

  3. In the Report Properties dialog box, click the Variables tab if it is not selected.

  4. On the Variables tab, click Add.

  5. In the Report Variable dialog box, type the name for the variable.

  6. In the Value to store box, type an expression. At any given time during the report run, the variable will contain the evaluated results of the expression.

  7. To specify an initial value for the variable, in the Initial value box, type an type an expression. The evaluated result of this expression will be assigned to the variable at the beginning of the report run..

    Note:
    If you use the report variable in calculations, make sure to initialize the variable with a nonzero value to avoid a division-by-zero error. If you do not specify an initial value, Visual FoxPro assigns a default value of 0.

  8. To specify additional calculations to perform on the evaluated expression results prior to assigning a value to the variable, in the Calculation type list, select the calculation operation you want.

  9. For cumulative calculation types, you can also specify the point at which the variable value is reset, by changing the setting of Reset value based on. For detailed information on calculation types, see Calculate Tab, Report Control Properties Dialog Box (Report Builder).

  10. When you are finished, click OK.

    You can now use the variable in your report or label.

For more information, see Variables Tab, Report Properties Dialog Box (Report Builder).

For example, consider a table of timesheet information with fields for punch-in and punch-out times stored in hour_in, min_in, hour_out, and min_out fields. The following table shows three example variables used in a report:

To store this value | Create this variable | Using this expression
Time employee arrived | tArrive | hour_in + (min_in / 60)
Time employee left | tLeave | hour_out + (min_out / 60)
Total time employee was present | tDayTotal | tLeave - tArrive

You can use the tDayTotal variable in a variety of other calculations, such as the number of hours worked in a week, a month, or a year; the average number of hours worked each day; and so on.

For examples of report variables, see the sample reports Percent.frx and Invoice.frx in the Visual FoxPro ...\Samples\Solution\Reports directory.

See Also

Tasks

How to: Open Reports and Labels
How to: Change Report Variable Order
How to: Reset Report Variables

Other Resources

Working with Report Variables


How to: Change Report Variable Order

Visual FoxPro 9.0
How to: Change Report Variable Order
See Also

Visual FoxPro evaluates report variables in the order they appear in the Report Variables dialog box, which can affect the value of expressions that reference them. For example, suppose a report variable tTotal is specified as containing the results of the sum of two other report variables, tDelivered and tOutstanding. These two variables must appear in the report variable list before tTotal, otherwise the value of tTotal may be incorrect.

Caution:
If you change the ordering of data groups in your report, report variables might not reset on the correct field. For example, if your report has two data groups and you change the order of the two groups, the variables remain set on the original positions of those groups.

To change report variable order

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Variables.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Variables dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Variables Dialog Box.

  3. In the Report Properties dialog box, click the Variables tab if it is not selected.

  4. In the Variables list, drag the mover button on the left of the variable to the position you want.

  5. When you are finished, click OK.

For more information, see Variables Tab, Report Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Open Reports and Labels
How to: Define Report Variables
How to: Reset Report Variables

Other Resources

Working with Report Variables


How to: Reset Report Variables

Visual FoxPro 9.0
How to: Reset Report Variables
See Also

You can specify that a report variable be reset to its initial value on entry to a specific report band. By default, Visual FoxPro resets the value of a report variable once at the beginning of a report run, leaving it with the last evaluated value when the report run is complete.

You can also use a Band's On Entry and On Exit expressions to set the value of a report variable.

To reset a report variable

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Variables.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the Report Variables dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Variables Dialog Box.

  3. In the Report Properties dialog box, click the Variables tab if it is not selected.

  4. Set the value of Reset value based on:

    • Report to set the variable to its initial value before the report starts processing (default)

    • Page to reset the report variable to its initial value when the Page Header band begins processing.

    • Column to reset the variable to its initial value when the Column Header band begins processing (only available in multi-column layouts).

    • Group: <expr> to reset the variable to its initial value when the Group Header band begins processing (only available when a data grouping has been created).

    • Detail <n> to reset the variable to its initial value when a detail band set begins processing (only available in layouts with multiple detail bands).

      For more information on multiple detail band layouts, see Working with Related Tables using Multiple Detail Bands in Reports.

  5. When you are finished, click OK.

For more information, see Variables Tab, Report Properties Dialog Box (Report Builder).

To reset a variable when entering or exiting a band

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Edit Bands.

  3. In the Edit Bands dialog box, click the report band you want, and then OK.

    The properties dialog box for the report band opens.

    Tip:
    You can also double-click the band separator in the Report Designer or Label Designer to open the report band properties dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report band dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable and Report Band Properties Dialog Box.

  4. In the report band properties dialog box, click the General tab if it is not selected.

  5. In the Run expression area, type an expression in the On entry or On exit box that resets the variable when entering or exiting the band. An example of such an expression would be EXECSCRIPT("tVariable = 10") to assign the report variable tVariable the numeric value 10. To build an expression, click the ellipsis (…) button to open the Expression Builder.

  6. When you are finished, click OK.

For more information, see General Tab, Report Band Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Open Reports and Labels
How to: Define Report Variables
How to: Change Report Variable Order

Other Resources

Working with Report Variables


Running Reports

Visual FoxPro 9.0
Running Reports

When you are finished creating a report or label, you can run reports by generating and controlling output from the report or label in different ways.

In This Section

How to: Preview Reports

Explains how to view a report before sending it to an output destination.
How to: Generate Output for Reports

Explains how to generate output reports and labels, for example, by printing them or sending them to a file.
How to: Control Record Selection in Report Output

Explains how to control the records to include when printing a report.
How to: Save the Printer Environment for Reports

Explains how to save the current printer environment settings with a report.

Related Sections

Working with Reports

Introduces Visual FoxPro reports and labels and how to include them in your applications.
Walkthrough: Creating Reports with Visual FoxPro

Provides steps for creating reports using the Report wizard and the Report designer, and discusses issues to consider when planning and creating reports.


How to: Preview Reports

Visual FoxPro 9.0
How to: Preview Reports
See Also

You can view a report in a preview window before sending it to an output destination.

Note:
The actions discussed in this topic have different results, depending on the setting of REPORTBEHAVIOR. When you use the command SET REPORTBEHAVIOR 90, Visual FoxPro uses a ReportListener object to generate your results through GDI+ instead of GDI. The results of the generation process are sent through a different previewing interface. For more information, see SET REPORTBEHAVIOR Command and _REPORTPREVIEW System Variable.

To preview a report

  1. Open the report or label in the appropriate designer.

  2. On the View menu, click Preview.

    The preview window and Print Preview toolbar open so you can navigate the report.

  3. To navigate the preview window, you can perform the following using the Print Preview toolbar:

    • To browse the report, click First Page, Previous Page, Go to Page, Next Page, or Last Page.

    • To change the size of view, choose a zoom level.

    • To print the report, click Print.

    • To return to design mode, click Close Preview.

      Caution:
      When you close the preview window, you might be prompted to save your changes to a file. If you receive this prompt, the selection you made not only closes the preview window but also the report layout file. To return to preview mode, click Cancel. To save your changes, and close the preview window and report layout file, click Save. To leave the changes to the layout unsaved, click No.

To preview a report programmatically

  • Use the REPORT FORM or LABEL FORM command with the PREVIEW clause.

For more information, see REPORT FORM Command and LABEL Command.

For example, the following code displays the report in a modal preview window:

Copy Code
REPORT FORM MyReport.FRX PREVIEW
  • Use the REPORT FORM or LABEL FORM command with the OBJECT TYPE 1 clause to explicitly request object-assisted preview. You can also use an OBJECT reference on the command with a reference to a ReportListener object, and set the object's ListenerType property value to 1:

Copy Code
REPORT FORM MyReport.FRX OBJECT TYPE 1 && preview
* - OR -
LOCAL loReportListener
loReportListener = CREATEOBJECT("ReportListener")
loReportListener.ListenerType = 1
REPORT FORM MyReport.FRX OBJECT loReportListener

For more information, see ListenerType Property.

See Also

Reference

ReportListener Object

Other Resources

How to: Generate Output for Reports
How to: Control Record Selection in Report Output
Running Reports


How to: Generate Output for Reports

Visual FoxPro 9.0
How to: Generate Output for Reports
See Also

You can generate output reports and labels by performing the following:

  • Printing Reports

  • Sending Reports to the Screen

  • Sending Reports to a File

  • Saving Reports as HTML

Note:
Some of the actions discussed in this topic have different results, depending on the setting of REPORTBEHAVIOR. When you use the command SET REPORTBEHAVIOR 90, Visual FoxPro uses a ReportListener object to generate your results through GDI+ instead of GDI. For more information, see SET REPORTBEHAVIOR Command.

Printing Reports

You can change printer settings before you print the report or print the report programmatically.

To print a report or label

  1. Choose the Print… option on the File menu, and select Report or Label as the Type of output to print in the Print dialog box. Click the ellipsis (...) button to choose the report or label file (.frx or .lbx) to print. Alternatively, open the report or label in the appropriate designer and click Run Report on the Report menu.

  2. The Print dialog box opens so you can make changes to printer settings.

  3. In the Print dialog box, click Print.

To print reports and labels programmatically

  • Option 1: Use the REPORT FORM or LABEL command with the TO PRINTER clause.

  • Option 2: Use REPORT FORM or LABEL command with the clause OBJECT TYPE 0.

  • Option 3: Use REPORT FORM or LABEL command with the clause OBJECT<oReference>, where <oReference> is an instance of a ReportListener-derived class with its ListenerType property value set to 0. For more information, see ListenerType Property.

When using these commands, you can also display or suppress display of the Print dialog box and print status message. You can set many other options, such as which records to print.

For more information, see REPORT FORM Command or LABEL Command.

Sending Reports to the Screen

You can send report or label output to the main Visual FoxPro screen or currently active window.

To send report or label output to the screen or currently active window

  • When using the REPORT FORM and LABEL commands, omit all clauses that direct output other than to the screen or currently active window.
Tip:
Visual FoxPro 9's GDI+ reporting rendering mechanism does not echo the contents of the report or label directly to the current output window, so ensure that SET REPORTBEHAVIOR is set to 80 when you want this result. Alternatively, you can use a ReportListener object to draw the report contents to a shape or container on _SCREEN, or in any Visual FoxPro form. Creating a Custom Preview Container for an example performing this task with minimal code.

Sending Reports to a File

Sending reports to a file makes it possible for you to create an electronic version of the report and print them as a batch file on your printer at a later time.

To send a report to a file

  • Use the REPORT FORM or LABEL command and include the TO FILE clause.

For more information, see REPORT FORM Command or LABEL Command.

Saving Reports as HTML

You can save a report in Hypertext Markup Language (HTML) format.

Tip:
You must first save the report and any changes to disk before saving it as HTML.

To save a report as HTML

  1. Open the report or label in the appropriate designer.

  2. On the File menu, click Save As HTML.

  3. In the Save As HTML dialog box, select the options you want.

  4. To save the HTML (.htm) file with a different name, click the ellipsis (...) button to open the Save As dialog box so you can specify a different name. When you are finished in the Save As dialog box, click Save.

  5. In the Save As HTML dialog box, click OK.

For more information, see Save As HTML Dialog Box.

Tip:
Without opening the Report or Label Designer, you can also generate HTML from your report form by using the command REPORT FORM <your filename> OBJECT TYPE 5. This command uses an instance of the ReportListener HTML Foundation Class to generate your HTML file; the Save As HTML dialog box invokes the same object to perform its task.

See Also

Reference

ReportListener Object

Other Resources

How to: Preview Reports
How to: Control Record Selection in Report Output
Running Reports


How to: Control Record Selection in Report Output

Visual FoxPro 9.0
How to: Control Record Selection in Report Output
See Also

When printing a report, you can control the records included by specifying any combination of the following:

  • Quantity of records to include in the report.

  • Range of sequential records to process.

  • Selection criteria that records must meet.

  • Conditions required to continue processing sequential records for the report.

This topic shows you how to control record selection when printing through the user interface. When you use the REPORT FORM or LABEL command to print, you can specify these criteria using scope clauses on the command. For more information, see REPORT FORM Command or LABEL Command.

To control record selection in a report

  1. Choose the Print… option on the File menu, and select Report or Label as the Type of output to print in the Print dialog box. Click the ellipsis (...) button to choose the report or label file (.frx or .lbx) to print. Alternatively, open the report or label in the appropriate designer and click Run Report on the Report menu.

  2. In the Print dialog box, click Options.

  3. In the Print Options dialog box, click Options.

  4. In the Report and Label Print Options dialog box, specify the settings you want:

    • To specify a record quantity or range, in the Scope box, choose the scope setting you want. The default scope, All, processes all records. When choosing Next or Record, you type or choose a number in the box to the right of the Scope box to specify a sequential number of records, or a single record number. When you choose the Rest scope, Visual FoxPro processes all records from the current position of the record pointer through the rest of the records in the file.

    Note:
    The results for All, Next, and Rest are influenced by the current index order for the table. The results for Record are not influenced by the current index order because the record pointer does not move. The results for all four choices can be further limited by the other types of record criteria in this dialog box.

    • To specify record selection criteria for non-sequential records, use the For box. Type an expression with which records should be compared. To build an expression, make sure data sources used by the report are open and click the ellipsis (...) button to open the Expression Builder.

    • To specify conditions to meet to continue processing records sequentially, use the While box. Visual FoxPro processes records while the condition you type in the While box evaluates to True (.T.). To build an expression, click the ellipsis (...) button to open the Expression Builder.

    Tip:
    If you specify a While condition for a file that is not indexed, the selection process might end before evaluating all the appropriate records. Before printing the report, make sure the source table contains an active and appropriate index for the condition you want to use. Set the record pointer to a record satisfying your While condition.

  5. When you are finished, click OK.

    Tip:
    Both While conditions and For selection criteria can include variables as well as data from tables. You can change the contents of the variables dynamically during the report or label run.

For more information, see Report and Label Print Options Dialog Box and Expression Builder Dialog Box.

See Also

Other Resources

How to: Open Reports and Labels
How to: Generate Output for Reports
Running Reports


How to: Save the Printer Environment for Reports

Visual FoxPro 9.0
How to: Save the Printer Environment for Reports
See Also

You can save the current printer environment settings with a report. The printer settings are saved to the appropriate memo fields in the report header record. Your selection is saved between Visual FoxPro sessions.

Note:
In Visual FoxPro 9, unlike earlier versions, the printer environment is not saved with reports by default, even for reports created in a distributed application. Saving the printer environment with reports make opening a report for design sessions much slower, especially if the printer may be on another machine on a large network, and this setting is less important than it was to earlier versions of the Visual FoxPro Report System.

Note:
Sometimes you design a report always to be printed in a single environment, requiring settings specific to a single printer. In this case, you can opt to save the Printer Environment with your report. Even in such a case, however, it is often better practice to omit the printer environment settings from the report or label definition file (frx or lbx).

For run-time processing, the printer settings can be specified for report or label processing using a SET PRINTER TO NAME command before the REPORT FORM or LABEL command. This approach keeps the printer environment settings external to the report or label definition file, while allowing you to specify them exactly as needed for the individual report. For more information, see SET PRINTER Command.

To save the printer environment settings

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Printer Environment if it is not selected.

You can also choose this setting from the Tools menu by clicking Options, then the Reports tab in the Options dialog box, or from the Report menu by clicking Properties, then the Page Setup tab in the Report Properties dialog box. For more information, see Options Dialog Box (Visual FoxPro) and Report Properties Dialog Box (Report Builder).

You can use the SYS(1037) function to initialize printer environment settings for the default printer or your report printer environment settings. For more information, see SYS(1037) - Page Setup Dialog Box.

See Also

Tasks

How to: Open Reports and Labels

Other Resources

Running Reports


Distributing Reports with Applications

Visual FoxPro 9.0
Distributing Reports with Applications

When you are finished designing, creating, and running reports in Visual FoxPro, you can include them for distribution with your applications.

In This Section

Integrating Reports with Applications

Discusses reporting functions and report design in the context of developing applications.
Setting Protection for Reports

Contains topics about how to configure protection for reports so that users cannot alter certain parts when modifying them in protected mode.
Including Report Files for Distribution

Provides information about distributing report and label definition tables (.frx and .lbx tables) as well as Visual FoxPro Report System external components (such as ReportBuilder.app) with your applications.

Related Sections

Working with Reports

Introduces Visual FoxPro reports and labels.
Reporting Features for International Applications

Covers features of interest to developers distributing their applications internationally.
Distributing Applications

Provides information about preparing your application for distribution.


Integrating Reports with Applications

Visual FoxPro 9.0
Integrating Reports with Applications
See Also

After you finish developing reports for your application, you can integrate them with your application. The following illustration shows some ways you can add reports to your application.

Options for Integrating Reports

You have several options for integrating reports into your application:

  • Add code that can run and display reports to the following objects:

    • Form controls. For more information about forms and buttons, see Creating Forms.

    • Toolbar buttons or menu commands. For more information, see Designing Menus and Toolbars.

    For example, if you want to make it possible for the user to run the report and produce a printout only, you can add the REPORT FORM command to a control on a form, menu command, or toolbar button. For more information, see How to: Generate Output for Reports.

  • If you want to make it possible for the user to enter some variables used in the report, you can collect those values from the user just as you can for queries.

    For example, the user can enter a specified date range for the report, which you use to run the report. For more information, see Working with Report Variables.

  • If you want to make it possible for the user to create custom reports, you can offer the user the capability to create new reports or modify existing reports with the Report Designer. For more information, see How to: Open Reports and Labels.

See Also

Other Resources

Developing Visual FoxPro Applications


Setting Protection for Reports

Visual FoxPro 9.0
Setting Protection for Reports
See Also

Report protection allows you to distribute report layouts with your application, enable your users to customize or extend the layouts within constraints that you set at design time.

Protection settings include:

  • Restricting access to certain menu options.

  • Restricting access to the property dialog boxes of specific report elements.

  • Restricting the ability to resize bands.

  • Restricting the ability to move, edit, or delete report controls.

In This Section

Report Protection Flags

Provides an overview of report protection flags.
How to: Protect Report Layouts

Describes how to configure protection settings that affect the entire report or label layout, when modifying the layout in protected mode.
How to: Protect Report Bands

Describes how to configure protection settings on individual report bands, when modifying the layout in protected mode.
How to: Protect Report Controls

Describes how to configure protection settings on individual report controls, when modifying the layout in protected mode.

Related Sections

Running Reports

Describes how to generate output from reports and labels.
How to: Add Design-time Captions to Field Controls

Describes how to configure a control so that it shows in the designer with alternative text, rather than the actual field expression.

See Also

Reference

Protection Tab, Report Properties Dialog Box (Report Builder)
Protection Tab, Report Band Properties Dialog Box (Report Builder)
Protection Tab, Report Control Properties Dialog Box (Report Builder)


Report Protection Flags

Visual FoxPro 9.0
Report Protection Flags
See Also

Visual FoxPro 9.0 introduces a new keyword to the MODIFY REPORT | LABEL command: PROTECTED. When a report or label layout is opened in protected mode, various capabilities of the designer are disabled or restricted depending on the protection settings set by the developer.

There are two types of protection settings: Those that apply to the entire report layout; and those that apply to specific report elements (a control or band).

In Visual FoxPro 9.0, you adjust protection settings for a layout in the user interface provided by the default Report Builder application. The native dialog boxes of the Report Designer do not expose a way to edit protection flags.

Protection Flags

Types of Protection flags

The following constants are defined in the file foxpro_reporting.h, located in the ..\FFC\ directory.

Note that these constant values represent the bit position of each flag, not the actual integer value of the flag.

Protection flags for report controls

Constant in foxpro_reporting.h Value Description

FRX_PROTECT_OBJECT_LOCK

0

A report control with this flag set can not be moved (relative to its band) or resized using the mouse or keyboard. It can be selected, double-clicked, and edited through the native Report Designer dialog boxes. Resizing a band above the one in which the object is located will still result in the object being moved relative to the top of the report, as expected.

FRX_PROTECT_OBJECT_HIDE

1

A report control with this flag set is not visible in the designer.

FRX_PROTECT_OBJECT_NO_DELETE

2

A report control with this flag set may not be deleted or cut. You can select it, copy it to the edit clipboard with Ctrl-C, and paste a new control into the report layout.

Important
With no report builder active, the protection flags will be retained along with the other report control attributes. This means that you will not be able to remove the newly pasted report control. For this reason, the default report builder, ReportBuilder.App, automatically removes protection flags from the newly created report control during the paste operation. This behavior is implemented in the PasteUnprotectFilter class, registered by default in the Report Builder's handler table. See Report Builder Event Handler Registry Table for more information.

FRX_PROTECT_OBJECT_NO_EDIT

3

For report controls with this flag set, double-clicking has no effect, and you can not display the object's context menu with a right-click. Basically there is no access to the object's Properties dialog.

FRX_PROTECT_OBJECT_NO_SELECT

6

A report control with this flag set may not be selected with the mouse or TAB key. The resize handles do not appear. This flag implicitly has the same effect as OBJECT_NO_EDIT + OBJECT_LOCK.

Generally speaking, for most practical purposes:

  • NO_SELECT protection effectively includes the behavior of LOCK + NO_EDIT + NO_DELETE protection, even if those flags are not explicitly set.

  • HIDDEN protection effectively includes the behavior of LOCK + NO_EDIT + NO_DELETE + NO_SELECT protection, even if those flags are not explicitly set.

Protection flags for report bands

Constant in foxpro_reporting.h | Value | Description
FRX_PROTECT_BAND_NO_EDIT | 4 | The Band Properties dialog box is not available. Double-clicking on the band has no effect.
FRX_PROTECT_BAND_NO_RESIZE | 14 | The vertical size of the band is locked. The band cannot be resized in the designer.

Protection flags for report controls

Constant in foxpro_reporting.h | Value | Description
FRX_PROTECT_REPORT_NO_PREVIEW | 7 | Report layout may not be previewed.
FRX_PROTECT_REPORT_NO_OPTBAND | 8 | Optional Bands dialog box is not available.
FRX_PROTECT_REPORT_NO_GROUP | 9 | Data Grouping dialog box is not available.
FRX_PROTECT_REPORT_NO_VARIABLES | 10 | Report Variables dialog box is not available.
FRX_PROTECT_REPORT_NO_PAGESETUP | 11 | Page Setup dialog box is not available.
FRX_PROTECT_REPORT_NO_DATAENV | 13 | The Data Environment of the layout can not be modified.
FRX_PROTECT_REPORT_NO_PRINT | 15 | The report can not be printed from within the designer. The Run Report and Print… options of the menu are disabled.

How Protection Flags are stored with the layout

Protection flags are stored in the ORDER memo field of the FRX structure, in the header record and separately in each control and band record.

If you are not using the default report builder, you can adjust the flags by opening the .frx or .lbx file and replacing the value stored in the ORDER field with an alternative value determined by the following method:

Protection flag values are summed and stored as binary character data in the ORDER field. For example: FRX_PROTECT_OBJECT_LOCK + FRX_PROTECT_OBJECT_NO_DELETE + FRX_PROTECT_NO_EDIT = 2^0 + 2^2 + 2^3 = 1+4+8 = 13. Therefore, the ORDER field will contain CHR(13).

The FRX Cursor foundation class includes a couple of methods that are useful in extracting and replacing protection flags, as shown in the example below.

Example

Copy Code
#INCLUDE foxpro_reporting.h
LOCAL oFrxHelper, cReport, iFlags

* Create the helper object:
oFrxHelper = NEWOBJECT( "frxCursor", HOME()+ "\FFC\_frxcursor.vcx")

* Select a report file:
cReport = GETFILE("FRX")

* Open a report layout as a table:
USE (m.cReport) ALIAS frx

* Go to the report header record:
LOCATE FOR frx.objtype = FRX_OBJTYP_REPORTHEADER and ;
           frx.objcode = FRX_OBJCOD_REPORTHEADER and ;
           frx.platform = FRX_PLATFORM_WINDOWS

* Extract the current protection setting:
iFlags = oFrxHelper.BinStringToInt( frx.ORDER )

* Prevent access to the Report Variables dialog box:
iFlags = BITSET( iFlags, FRX_PROTECT_REPORT_NO_VARIABLES )

* Save back to the frx record:
REPLACE frx.order WITH oFrxHelper.IntToBinString( iFlags )
USE IN frx

* Edit the report in protected mode:
MODIFY REPORT FORM (cReport) PROTECTED

See Also

Reference

FRX Cursor Foundation Class
Protection Tab, Report Properties Dialog Box (Report Builder)
Protection Tab, Report Band Properties Dialog Box (Report Builder)
Protection Tab, Report Control Properties Dialog Box (Report Builder)


How to: Protect Report Layouts

Visual FoxPro 9.0
How to: Protect Report Layouts
See Also

You can protect a report or label layout from being modified by end users in undesirable ways by setting editing restrictions with report protection flags, and letting your users edit report layouts via the MODIFY REPORT … PROTECTED command.

To set protection for reports

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Properties, or right-click on the layout and select Properties from the context menu.

    The Report Properties dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder, the Report Page Setup dialog box opens instead. If _REPORTBUILDER is set to a third-party builder, a different dialog box might display. . There is no way to set protection flags using the native report dialog boxes. For more information, see _REPORTBUILDER System Variable and Report Page Setup Dialog Box.

  3. In the Report Properties dialog box, click the Protection tab.

  4. On the Protection tab, select a combination of the following protection options:

    • The user will not be able to run the report from within the designer, or use the Print… option on the File menu.

    • The user will not be able to preview the report from within the designer.

    • The user will not be able to modify the report's Data Environment.

    • The user will not be able to access the page layout dialog box.

    • The user will not be able to configure the layout's optional bands (in other words, they will not be optional for the user).

    • The user will not be able to access the data grouping dialog box.

    • The user will not be able to change the settings of the report variables.

  5. When you are finished, click OK.

For more information, see Protection Tab, Report Properties Dialog Box (Report Builder) and Report Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Protect Report Bands
How to: Protect Report Controls

Reference

MODIFY REPORT Command

Concepts

Report Protection Flags

Other Resources

Setting Protection for Reports


How to: Protect Report Bands

Visual FoxPro 9.0
How to: Protect Report Bands
See Also

You can set protection options for a report band to prevent the user from changing the band when modifying the report or label in protected mode.

To set protection for a report band

  1. Open the report or label in the appropriate designer.

  2. On the Report menu, click Edit Bands.

    The Edit Bands dialog box opens.

  3. In the Edit Bands dialog box, select the band you want, and click OK.

    The properties dialog box for the report band opens.

    Tip:
    You can also double-click the band separator in the Report Designer or Label Designer to open the report band properties dialog box.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report band dialog box displays or a different dialog box might display. There is no way to set a design-time caption using the native report control dialog box. For more information, see _REPORTBUILDER System Variable.

  4. In the report band properties dialog box, click the Protection tab.

  5. On the Protection tab, select a combination of the following protection options:

    • The user will not be able to resize the band in protected mode.

    • The user will not be able to access the Band Properties dialog box.

  6. When you are finished, click OK.

For more information, see Protection Tab, Report Band Properties Dialog Box (Report Builder).

See Also

Tasks

How to: Protect Report Layouts
How to: Protect Report Controls

Reference

MODIFY REPORT Command

Concepts

Report Protection Flags

Other Resources

Setting Protection for Reports


How to: Protect Report Controls

Visual FoxPro 9.0
How to: Protect Report Controls
See Also

You can set protection options for a report control to prevent the user from changing the control or to hide the control from the user when modifying the report or label in protected mode. You can also set protection options for multiple selected report controls.

To set protection for a report control

  1. Open the report or label in the appropriate designer.

  2. In the designer, double-click the report control you want.

    The properties dialog box for the report control opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, the report control dialog box displays or a different dialog box might display. There is no way to set a design-time caption using the native report control dialog box. For more information, see _REPORTBUILDER System Variable.

  3. In the report control properties dialog box, click the Protection tab.

  4. On the Protection tab, select a combination of the following protection options:

    • The user will not be able to resize or move the report control.

    • The user will not be able to access the Report Control Properties dialog box.

    • The user will not be able to delete the report control from the layout.

    • The user will not be able to select the report control with the mouse or keyboard.

    • The user will not be able to see the report control.

  5. When you are finished, click OK.

  6. For more information, see Protection Tab, Report Control Properties Dialog Box (Report Builder).

To set protection for multiple selected report controls

  1. In the designer, select the report controls that you want using the multiple-selection method. For more information, see How to: Select Multiple Report Controls.

  2. Double-click one of the selected controls, or right-click and select Properties.

    The Multiple Selection dialog box opens.

    Note:
    If the _REPORTBUILDER system variable is not set to the default Report Builder or is set to a third-party builder, a report control dialog box displays or a different dialog box might display. For more information, see _REPORTBUILDER System Variable.

  3. In the Multiple Selection dialog box, click the Protection tab if it is not selected.

  4. On the Protection tab, select the protection options you want.

  5. When you are finished, click OK.

For more information, see How to: Select Multiple Report Controls.

See Also

Tasks

How to: Protect Report Layouts
How to: Protect Report Bands

Reference

MODIFY REPORT Command

Concepts

Report Protection Flags

Other Resources

Setting Protection for Reports


Including Report Files for Distribution

Visual FoxPro 9.0
Including Report Files for Distribution
See Also

When you distribute an application, you have a number of decisions to make about how you deploy the reports you have designed to provide application output. This topic describes options for inclusion of report and label definition tables (.frx and .lbx files) and the distributable Visual FoxPro Report System components.

Distributing Report and Label Files

Reports and labels can be included in your project and built into your application (.exe or .app file), or they can be delivered separately on disk.

Tip:
You can reference reports and labels in your application project, for easy reference while designing the application, without building the report and label files into the compiled application file. For more information, see How to: Exclude Files from Builds.

Which strategy you decide to use usually depends on whether you want end-users to have the ability to adjust the reports and labels. If the reports and labels are on disk as separate files, your application can provide facilities for end-users to customize them, using the MODIFY REPORT and MODIFY LABEL commands.

Tip:
In Visual FoxPro 9, you can offer end-users a customized and safe design experience, by leveraging custom Report Builder dialogs and such features as Report Protection and Report Designer ToolTips, and Design-time Captions. For more information, see Setting Protection for Reports, How to: Add Tooltips to Report Controls, and How to: Add Design-time Captions to Field Controls.

You can use a combination approach, building the reports and labels into your application to serve as read-only output templates, but copying them to disk for end-users' modifications. This approach has the advantage of ensuring that you can revert to a "clean" copy of the original report or label definition file when necessary.

Tip:
Using a built-in template also allows you to make some last-minute adjustments to the report or label before an end-user design session. For example, you could adjust protection flags in the editable copy using an application lookup table for user permissions. You might also replace the ToolTips for report controls you use for development purposes, with developer notes, for another set containing end-user instructions. Because you can add extension fields to report and label tables, this programmatic run-time adjustment would be as simple as opening the report or label table with the USE command, followed by a command such as REPLACE ALL ORDER WITH <your extension field>. For more information, see Understanding and Extending Report Structure.

Under some circumstances, Visual FoxPro permits the commands MODIFY REPORT and MODIFY LABEL to be used with the names of read-only report and label files built into the application. When the application's end-user saves the report or label from the designer, Visual FoxPro saves the copy to disk. For this strategy to work, the report and label files must either be in the same folder as the project (.pjx) file or in a folder whose name Visual FoxPro can resolve at run time, relative to the application file (.exe or .app).

For example, suppose your project is in a folder named d:\app and the report form you wish to include is d:\app\reports\my.frx on your development computer. At run time, you install the application file (.exe) to c:\programs\myapp. If you create a reports subfolder, c:\programs\myapp\reports, you can use the command MODIFY REPORT my.frx. When the user chooses to save the report, Visual FoxPro saves the report as c:\programs\myapp\reports\my.frx by default. However, if c:\programs\myapp does not have the subfolder, an error occurs on the MODIFY REPORT command.

You can verify the availability of the subfolder at run time, and use the MD | MKDIR Command if necessary. Alternatively, use the following commands, where lcDir holds the name of a target folder you have previously verified with the user.

Copy Code
SELECT * FROM my.frx INTO TABLE (lcDir + "my.frx")
MODIFY REPORT(lcDir + "my.frx")

This approach puts the process completely under your control. It allows you to configure the target folder to meet the user's needs rather than the project's design-time structure.

Note:
When distributing reports, whether built-in or as external files, ensure that all additional required files are available to your application at run time. For example, if your report references an image file, include the image file in your application or distribute the file as a separate file on disk. Ensure that the image file is in the same location in your project's build structure, or in the folder structure of your distributed application on disk, relative to the report file, as it was when you designed the report. Otherwise, Visual FoxPro cannot find the image file when it generates the report. If you choose to build reports into your application, other compiled modules, such as ReportOutput.app or ReportBuilder.app, may not be able to locate the files within your compiled module. You can ensure that the report system components find your files by building in their source files to your application, rather than distributing them as separate applications. The next section discusses your options for distributing these components.

Distributing Report System Components

If you provide end-users with the opportunity to modify reports and labels, you should distribute the Report Builder Application, or your customized version of the Report Builder Application, to ensure that your users have all the advantages of its Report Designer enhancements.

By default, Visual FoxPro looks for a file with the name ReportBuilder.app in the HOME() or startup location. For an executable application (.exe), this location is always the folder where Visual FoxPro's run-time support libraries are installed, such as C:\Program Files\Common Files\Microsoft Shared\VFP. For more information, see HOME( ) Function. If you include the Microsoft Visual FoxPro 9 Report Applications merge module with your application installation Setup programs, as described in the next section, the default ReportBuilder.app installs to the appropriate location on the user's disk.

Caution:
Installing any other applications with the names ReportBuilder.app, ReportPreview.app, and ReportOutput.app to the default location of the run-time support libraries is not recommended, since you might install over the default applications required by other Visual FoxPro applications. If you wish to install customized versions of these applications to the default location, use different application names and designate your preferred reporting components by name, in your application, as described in this section.

You can use the _REPORTBUILDER System Variable in your application, or in the configuration file (CONFIG.FPW) for your application, to specify a different location and a different file name for your distributed Report Builder Application. For more information, see Setting Configuration Options at Startup.

When you deploy applications, you have the option to build Report Builder component files into your executable application (.exe) rather than distributing Report Builder Application as a standalone file. For more information, see How to: Specify and Distribute ReportBuilder.App.

To provide Visual FoxPro 9's enhanced output capabilities in your applications, using ReportListener and PreviewContainer objects, you should also distribute the Report Output Application (ReportOutput.app) and Report Preview Application (ReportPreview.app) or suitable replacements. The techniques for specifying the names and locations of these components are the same for all three report applications. For more information, see How to: Specify and Distribute ReportPreview.App and How to: Specify and Distribute Report Output Application Components.

Tip:
You can leverage the default ReportListener-derived classes used by the Report Output Application and many of the capabilities of the Report Builder Application separately from the two applications, by using Foundation Class libraries containing identical visual classes. For more information, see ReportListener Foundation Classes, FRX Cursor Foundation Class, and FRX Device Helper Foundation Class.

Distributing additional files for reports and Visual FoxPro's Report System

Visual FoxPro supplies merge modules (.msm files) so you can build distributable Setup programs for your applications and include all the necessary support files. For more information, see Walkthrough: Creating a Visual FoxPro Application Setup Program Using InstallShield. The following table lists the modules of special significance to applications using Visual FoxPro's reporting features.

Merge module file name | Merge module title | Remarks
vfp9rptapps.msm | Visual FoxPro 9 Report Applications | Installs ReportBuilder.app, ReportOutput.app, and ReportPreview.app to their default locations for executable applications.
msxml4sxs32.msm msxml4sys32.msm | MSXML 4.0 | These module are required for all Visual FoxPro application installations, and are used extensively by the default Report Applications.
GDIPlus.msm | Microsoft GDI+ | This module is required for all Visual FoxPro application installations, and is used extensively by the Report System in object-assisted reporting mode.

See Also

Reference

EXTERNAL Command
MODIFY REPORT Command
MODIFY LABEL Command

Other Resources

Distributing Applications
Extending Report Functionality in Visual FoxPro


Extending Report Functionality in Visual FoxPro

Visual FoxPro 9.0
Extending Report Functionality in Visual FoxPro
See Also

You can extend both the design-time and run-time elements of the Visual FoxPro Report System. The topics in this section show you how to customize the Report and Label designers and the output you receive from the REPORT FORM and LABEL commands.

Visual FoxPro ships with a number of applications that take advantage of the new extension features. This section includes information you can use to customize the shipping applications and add your own components to them.

In This Section

Extending Reports at Design Time

Describes the event hooks in the Report and Label designers and how to leverage the default Report Builder application or replace it with your own custom application.
Extending Reports at Run Time

Discusses how to take advantage of the Report Preview and Report Output run-time features.
Understanding and Extending Report Structure

Shows you how to explore and extend report and layout definition tables (.frx and .lbx files).
Report XML MemberData Extensions

Discusses the supported XML Memberdata format, shared by the Report System with Visual FoxPro Property Sheet extensions, and ways you can leverage its contents in reports.
Using GDI+ in Reports

Provides information about how Visual FoxPro 9's use of GDI+ impacts native reporting behavior, as well as additional uses you can make of GDI+ in your code.

Related Sections

Working with Reports

Introduces Visual FoxPro reports and labels and how to include them in your applications.
ReportListener Object

Provides information about the Visual FoxPro baseclass used to support run-time Report System extensions.

See Also

Reference

SET REPORTBEHAVIOR Command
REPORT FORM Command
LABEL Command
_REPORTBUILDER System Variable
_REPORTPREVIEW System Variable
_REPORTOUTPUT System Variable


Extending Reports at Design Time

Visual FoxPro 9.0
Extending Reports at Design Time

Describes the event hooks in the Report and Label designers and how to leverage the default Report Builder application or replace it with your own custom application.

In This Section

Understanding Report Builder Events

Describes the builder events exposed by the Report and Label Designers.
Report Builder Event Handler Registry Table

Describes the structure of the lookup table used by the default Report Builder application to assign handler classes to builder events.
The Report Builder Event Class

Describes the properties and methods of the class used to encapsulate the builder event in the Report Builder framework.
How to: Display the Report Builder Options Dialog Box

Explains how to display reportbuilder.app's Options dialog box.
How to: Configure the Report Builder's Event Handling

Explains how to configure how the default report builder responds to build events.
How to: Add Your Own Handler to the Report Builder's Registry

Explains how to plug in your own event handler classes into the default report builder framework.
How to: Specify an Alternate Report Event Handler Table

Explains how to configure reportbuilder.app to use a different lookup table for event handler classes when it responds to events in the Report Designer.
How to: Extend or Replace the Report Builder

Explains how to replace the default report builder application in Visual FoxPro with your own application.
How to: Specify and Distribute ReportBuilder.App

Explains how to distribute ReportBuilder.App, either as a separate App file with your application, or by integrating the source code into your application's project.

Related Sections

Extending Reports at Run Time

Describes how to use and take best advantage of the preview and output run-time hooks in Visual FoxPro.
_REPORTBUILDER System Variable

Describes how to register an application to handle report builder events.


Understanding Report Builder Events

Visual FoxPro 9.0
Understanding Report Builder Events
See Also

Visual FoxPro's Report and Label Designers expose selected user interface (UI) operations as builder events that can be intercepted and handled by a report builder application.

The builder application invoked by the designer is specified by the _REPORTBUILDER System Variable, which by default references reportbuilder.app, located in the Visual FoxPro install directory. This application is invoked both from the Report Designer and the Label Designer - there is no corresponding "_LABELBUILDER" variable. In this topic and the ones that follow, you may assume that any discussion involving the Report Designer applies equally to the Label Designer.

The report builder application has the opportunity to augment or replace the native designer dialog boxes, and the entire underlying source file of the layout currently open in the Report Designer is available to the report builder as a cursor in a private data session.

If _REPORTBUILDER is empty or refers to a non-existent file, no error is raised. The designers will respond to user actions normally, as in previous versions of Visual FoxPro.

When a report builder event occurs, the Report Designer does the following:

  • Creates a private data session.

  • Opens a copy of the source (.frx or lbx) file currently being edited in the designer, with the alias "FRX."

  • Invokes the application specified by _REPORTBUILDER, passing it four parameters.

A report builder application must comply with the following API:

  • It must accept at least four parameters (passed by reference) in the main program.

  • It must return a value to the Report Designer by changing the value of the first parameter.

  • It must be modal, because the designer will be waiting for the return value to indicate what action it should take next.

Parameters passed from the Designer

The Designer passes four parameters, by reference, to the builder application:

Index | Parameter | DataType | Description
1 | ReturnFlags | I | Passed by reference so that the builder application can return values to the Report or Label Designer.
2 | EventType | I | An integer representing the type of event that occurred.
3 | CommandClauses | O | An object (of Empty class) with properties indicating what clauses were used on the command that launched the designer.
4 | DesignerSessionId | I | The DataSession Id that the Report Designer is in.

ReturnFlags

This passed-by-reference parameter is -1 when passed to the report builder, but the designer expects to receive a different value back. Possible return values consist of summed binary flags:

#define constant | Bit number | Bits | Value | Description
FRX_REPBLDR_HANDLE_EVENT | 0 | 01 | 1 | If set, this flag tells the Report Designer that the event has been handled by the report builder, and to suppress the default action the designer would normally do in response to the event. This flag is similar to the operation of NODEFAULT in Visual FoxPro method code.
FRX_REPBLDR_RELOAD_CHANGES | 1 | 10 | 2 | If set, this flag tells the Report Designer that the builder made changes to the FRX cursor, and that the changes should be reloaded into the designer, and reflected in the layout.
Note:
The #define constants shown in the tables are defined in foxpro_reporting.h in the FFC\ directory under the Visual FoxPro home directory.

EventType

This parameter is an enumerated type, representing the event that caused the Report Designer to invoke the report builder application.

#define constant | Value | Event Description
FRX_BLDR_EVENT_PROPERTIES | 1 | A Properties dialog box is being invoked, by double-clicking or a menu action.
FRX_BLDR_EVENT_OBJECTCREATE | 2 | A control is being created in the layout.
n/a | 3 | (Reserved for future use.)
FRX_BLDR_EVENT_OBJECTREMOVE | 4 | A control is being removed from the layout by deletion or by CTRL-X/Cut.
FRX_BLDR_EVENT_OBJECTPASTE | 5 | A control is being pasted into the layout from the clipboard.
FRX_BLDR_EVENT_REPORTSAVE | 6 | The layout is being saved to disk.
FRX_BLDR_EVENT_REPORTOPEN | 7 | The layout is being opened.
FRX_BLDR_EVENT_REPORTCLOSE | 8 | The layout is being closed.
FRX_BLDR_EVENT_DATAENV | 9 | The Data Environment window is being opened.
FRX_BLDR_EVENT_PREVIEWMODE | 10 | The print preview mode is being invoked.
FRX_BLDR_EVENT_OPTIONALBANDS | 11 | The Optional Bands dialog box is being invoked.
FRX_BLDR_EVENT_DATAGROUPING | 12 | The Data Grouping dialog box is being invoked.
FRX_BLDR_EVENT_VARIABLES | 13 | The Variables dialog box is being invoked.
FRX_BLDR_EVENT_EDITINPLACE | 14 | CTRL-E was pressed on a selected Label control.
FRX_BLDR_EVENT_SETGRIDSCALE | 15 | The Set grid scale dialog box is being invoked.
FRX_BLDR_EVENT_OBJECTDROP | 16 | Object(s) are being created from a drag-and-drop operation from the Data Environment window, a Database Container, or a Project window.
FRX_BLDR_EVENT_IMPORTDE | 17 | Import data environment was selected from the Report menu.
FRX_BLDR_EVENT_PRINT | 18 | Print was selected from the File menu or Run Report was selected from the designer's context menu.
FRX_BLDR_EVENT_QUICKREPORT | 19 | Quick Report was selected from the Report menu.

CommandClauses

This parameter is an object reference to an instance of an Empty class with a number of additional properties indicating the various possible clauses on the Visual FoxPro command that launched the Report or Label Designer:

Property Data Type Description

AddTableToDE

L

Indicates that the Add table to data environment check box is selected in the Quick Report dialog box.

Alias

L

Indicates that the ALIAS keyword was specified in the CREATE REPORT | LABEL FROM.. command, or that Add alias was checked in the Quick Report dialog box.

FieldList

O

Contains a collection of numeric field numbers, representing the field list of the quick report command.

File

C

Contains the filename of the source (.frx or .lbx) file open in the Designer. This file may not actually exist if CREATE REPORT was used.

Form

L

Indicates the layout of the quick report:

  • .T. if FORM layout was specified.

  • .F. if COLUMN layout was specified.

From

C

Contains the table name specified in the CREATE REPORT FROM <filename> clause.

InScreen

L

Indicates that the IN SCREEN clause was used in the command.

InWindow

C

Specifies the window name of the IN <windowname> clause, if used.

IsCreate

L

Indicates the layout is newly created:

  • .T. if CREATE REPORT | LABEL.

  • .F. if MODIFY REPORT | LABEL.

IsReport

L

Indicates the type of layout open in the Designer:

  • .T. if CREATE | MODIFY REPORT.

  • .F. if CREATE | MODIFY LABEL.

IsQuickReportFromMenu

L

Indicates that the Quick Report option on the Report menu was invoked.

NoEnvironment

L

Specifies that the NOENVIRONMENT keyword was included in the command.

NoOverwrite

L

Specifies that the NOOVERWRITE keyword was included in the command.

NoWait

L

Specifies that the NOWAIT keyword was included in the command.

Protected

L

Specifies that the PROTECTED keyword was included in the command.

Save

L

Specifies that the SAVE keyword was included in the command.

Titles

L

Indicates that label controls should be added to the quick report layout.

Width

N

Specifies the number of columns specified on the quick report command.

Window

C

Contains the window name specified in the WINDOW <windowname> clause of the command.

DesignerSessionId

Because the report builder is invoked from inside a private data session, the Report or Label Designer also passes in the data session id of the data session that the designer is open in. This allows the report builder to switch to the designer's data session whenever it needs to access tables that might be open in the layout's data environment.

The FRX Cursor

A working copy of the report file being edited will be open with the alias "FRX" in a private data session when the report builder application is called. Additionally:

  • The record pointer will be located on the FRX record that represents the report layout object on which the event occurred. In some cases this might be the report header record itself, representing a report-specific event rather than a control-specific event.

  • Any records in the FRX cursor representing layout objects that are currently selected (highlighted with the mouse and showing object "handles") will have the CURPOS field set to .T..

Note:
The report header (record 1) may also have CURPOS=.T. because that is used to store the value of "Show Position" from the View menu option. If the builder application is required to identify how many objects are currently selected, it should use code similar to COUNT FOR CURPOS AND RECNO() > 1.

See Also

Tasks

How to: Configure the Report Builder's Event Handling

Reference

Report Builder Event Handler Registry Table
Report Properties Dialog Box (Report Builder)
Multiple Selection Dialog Box (Report Builder)
_REPORTBUILDER System Variable

Other Resources

Extending Reports at Design Time


Report Builder Event Handler Registry Table

Visual FoxPro 9.0
Report Builder Event Handler Registry Table
See Also

The default report builder application, ReportBuilder.App, contains an internal lookup table that assigns specific behavior to builder events. The table defines whether certain object-event combinations are ignored or directed to specific classes for handling.

For more information on the event handling classes, see the source code to reportbuilder.app contained in the XSource Folder under the Visual FoxPro HOME() directory.

Because it is built-in to the application, this lookup table cannot be modified directly. ReportBuilder.App has a mechanism that allows you to copy the table out to disk so that you can adjust the default settings and even add your own handler classes to augment or replace the default ones.

See How to: Configure the Report Builder's Event Handling for more information.

In this topic:

  • The Event Handler Registry Table Structure

  • Handler Class Types

  • How the Report Builder processes events

Table Structure

ReportBuilder.App uses an internal lookup table to determine which handler class to instantiate for a given combination of EventType and report object (as specified by the currently selected record in the FRX cursor, which could be a report control, a report band, or the report header record itself). The structure of this table is shown below:

Field Name Type (size) Description

REC_TYPE

C (1)

Specifies the type of handler class the record defines.

HNDL_CLASS

C (35)

Specifies the class name.

The class will be instantiated using a NEWOBJECT() call that assumes the class library will be found in the Visual FoxPro SET CLASSLIB or SET PATH.

HNDL_LIB

C (50)

Specifies the class library.

This can be a visual (.vcx) or non-visual (.prg) class library.

EVENTTYPE

I

Specifies the event type. Use a value of -1 for a "wild card" match.

See Understanding Report Builder Events for a list of possible event types.

OBJTYPE,

OBJCODE

I,

I

Specifies the report control type. These fields are equivalent to the OBJTYPE and OBJCODE fields in the report layout source (.frx) tables.

Use a value of -1 for a "wild card" match.

See Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx) for links to where the structure of report layout source (.frx) files are documented.

NATIVE

L

Indicates "native behavior override". For this record's event type/report object combination, the native Designer behavior should be allowed to take place.

DEBUG

L

Indicates "debug handler override". For this record's event type/report object combination, a special "debug" user interface will be displayed instead of the handler class specified by HNDL_CLASS.

FLTR_ORDR

C (1)

Defines the order in which Filter handlers are processed. For records of REC_TYPE="F" only.

NOTES

C (35)

This field is not used by ReportBuilder.App, but it is displayed in the report builder's event handler registry table browser. (For more information, see Event Handler Registry Dialog Box (Report Builder).)

Any additional fields in this table are ignored by the report builder.

Handler Class Types

Classes defined in the registry table can be one of several types:

Value | Type | Description
H | Event Handler | Indicates a handler class for a specific builder event / report object combination.
F | Filter Handler | Indicates a handler class that will be invoked for every report builder event, and can prevent the event from being handled by the report builder.
X | Exit Handler | Indicates a handler class that will be invoked after the event processing, but before the report builder returns control to the Designer, as a "clean up" process.
G | GetExpression Wrapper | Indicates a class that will be invoked in place of the native GETEXPR dialog box in any report builder dialog box.
E | Run-time Extension Editor | Indicates a class that will be invoked when the Edit settings command button is selected from the Other tab of the Report Control Properties Dialog.
M | Multi-select dialog tab | Indicates a Page Object class that will be automatically added to the pageframe in the Multiple Selection Dialog Box (Report Builder).

Event Handler API

Event Handler classes can be of any Visual FoxPro base class but must implement the Event Handler API. The Event Handler API has the following attributes:

  • A method named Execute that accepts a single object reference parameter.

What the class actually does in the Execute( oEvent ) method is not specified, although for Event Handler classes they probably will need to set the return flags:

Copy Code
DEFINE CLASS MyHandler AS Custom
    PROCEDURE Execute( oEvent )
        * You can alter oEvent.returnFlags to suit
        oEvent.SetHandledByBuilder(.T. | .F. )
        oEvent.SetReloadChanges( .T. | .F. )
    ENDPROC
ENDDEFINE

This method is passed a reference to an object representing the event that occurred. The handler should assign the appropriate ReturnFlags value to indicate what action the designer should take next when the builder terminates and returns control.

Event Handlers:

  • Are identified by a REC_TYPE value of "H".

  • Are generally only instantiated for a specific designer builder event type and report object type combination.

For more information on the properties and methods of the object reference passed to the handler class in the Execute() method, see The Report Builder Event Class.

Filter Handler API

Filter classes can be of any Visual FoxPro base class but must implement the Event Handler API (see above) plus one additional public property, allowToContinue:

Copy Code
DEFINE CLASS MyFilter AS Custom
    allowToContinue = .T.
    PROCEDURE Execute( oEvent )
        * decide whether or not to process the event
        THIS.allowToContinue = .T.
        * You can optionally alter oEvent.returnFlags to suit
        oEvent.SetHandledByBuilder(.T. | .F. )
        oEvent.SetReloadChanges( .T. | .F. )
    ENDPROC
ENDDEFINE

Filter Handler classes:

  • Are identified by a REC_TYPE value of "F".

  • Are instantiated for every report builder event.

  • Are processed in the order indicated by the FLTR_ORDR field.

  • Can prevent further processing of the event by setting their AllowToContinue property to false (.F.)

  • Can apply pre-processing to the FRX cursor prior to the event being processed by an Event Handler class.

Exit Handlers

Exit Handler classes must support the Event Handler API.

Exit Handler classes:

  • Are identified by a REC_TYPE value of "X".

  • In general are a way of getting some code to run at clean-up time.

  • Are only processed if an Event Handler class was previously located and executed. If a Filter handler prevented further processing, then Exit handlers will not be processed.

  • Like all handler classes, they have the opportunity to alter the oEvent.ReturnFlags value but it is very bad practice to do so.

GetExpression Wrapper API

You can replace the implementation of the GETEXPR dialog box used in the report builder by registering a class of REC_TYPE="G" in the handler registry. The class must support the GetExpression() method as shown in this example:

Copy Code
DEFINE CLASS MyGetExpr AS Custom
    PROCEDURE GetExpression( cDefExpr, cDataType, cCalledFrom, oEvent )
        LOCAL cExpression
        GETEXPR TO cExpression DEFAULT cDefExpr
        RETURN cExpression
    ENDPROC
ENDDEFINE

Only one class may be registered as the default GetExpressionWrapper. If there are more than one record of REC_TYPE="G," only the first one located will be used by the report builder.

The cCalledFrom parameter

The report builder passes the GetExpressionWrapper class a parameter indicating what type of expression is being edited. Possible values are:

  • "PrintWhenExpression"

  • "FieldExpression"

  • "OleBoundField"

  • "OleBoundExpression"

  • "BandGroupOnExpression"

  • "VariableValueToStore"

  • "VariableInitialValue"

Run-time Extension Editor API

You can replace the implementation of the dialog box that appears when you click the Edit settings command button in the Run-time extensions group on the Other tab of the Report Builder by registering a class in the handler registry with a REC_TYPE of "E". The class must support the Event Handler API. If implementing a form class, then the form must be issued as a MODAL window.

A run-time extension editor classes should do the following in the Execute() method:

  • Read the metadata XML from the STYLE field.

  • Present a user interface to allow the user to edit the metadata.

  • Save a valid XML fragment back into the STYLE field.

  • Unlike the other handler types shown above, it should not attempt to set the return flags.

Only one class may be registered as the default RuntimeExtensionEditor. If there is more than one "E" record in the handler registry table, the first one found will be used.

Adding tabs to the Multiple-selection dialog box

You can add pages to the pageframe in the Multiple Selection Dialog Box (Report Builder) by registering a class in the handler registry with a REC_TYPE of "M".

The class must be derived from the Page Object. If the page contains a Container Object that implements .LoadFromFrx() and .SaveToFrx(), then these methods will be called automatically by the multiple-selection dialog at appropriate points:

Copy Code
DEFINE CLASS pagAlign AS page
    Caption = "Alignment"
    Name    = "pagAlign"
    ADD OBJECT Panel1 AS panelAlign
ENDDEFINE

DEFINE CLASS panelAlign as Container
    BorderWidth = 0
    Width = 300
    Height = 300
    Event = null
    frxCursor = null

    ADD OBJECT Check1 AS Checkbox WITH ;
        Caption = "Align to leftmost object", ;
        Top = 100, Left = 50, Width = 150, Value=.F.

    PROCEDURE LoadFromFrx()
        * No initialization required
        RETURN .T.
    ENDPROC

    PROCEDURE SaveToFrx()
        IF THIS.Check1.Value
            LOCAL curSel
            curSel = SELECT()
            SELECT MIN(hpos) AS hpos FROM frx ;
                WHERE curpos AND objcode<>53 ;
                INTO CURSOR query
            newHpos = query.hpos
            USE IN query
            SELECT frx
            SCAN FOR curpos AND RECNO()>1
                REPLACE hpos WITH m.newHpos
            ENDSCAN
            SELECT (m.curSel)
        ENDIF
        RETURN .T.
    ENDPROC
ENDDEFINE

This example adds a tab to the multiple-selection dialog with a single checkbox that, if checked, will set the horizontal position all selected objects to that of the left-most positioned object in the selection.

The container object may implement any of the following PEMs:

  • The LoadFromFrx() method is called during the initialization of the form, and is a good place to read values from the frx cursor in order to initialize values of the controls in the container.

  • The SaveToFrx() method is called when the user clicks OK. Return FALSE if you wish to prevent the dialog from closing.

  • If defined, the Event property will be assigned a reference to the report builder's Event object. (See The Report Builder Event Class for more information.)

  • If defined, the frxCursor property will be assigned a reference to the Event object's frxCursor member object, for convenience. (See FRX Cursor Foundation Class for more information.)

There can be more than one record in the handler registry defined with REC_TYPE="M,". Each page class will be loaded into the dialog box as a separate tab.

How the report builder processes events

When the report builder is invoked, the Report Designer passes it an event type ID, with a copy of the FRX file open in a private data session. The report object that the event applies to is usually identified by the location of the record pointer in the FRX cursor. The report builder takes note of the OBJTYPE and OBJCODE values on the selected record, and then refers to the handler registry table.

1. All Filter Handlers are processed

The builder selects all records from the handler registry table with REC_TYPE="F", sorted by FLTR_ORDR, and instantiates each filter class in turn, invoking the Execute() method.

If the value of its allowToContinue property is true (.T.), then the next filter handler class is instantiated.

If the value of its allowToContinue property is false (.F.), then no further processing takes place - ReportBuilder.App sets Bit 0 on the ReturnFlags parameter to indicate to the designer that the builder event had been handled successfully.

Important:

  • The value specified in the FLTR_ORDR field is important, because a filter with a lower value (higher priority) can prevent futher processing, both by the next filter in line and also by an appropriate Event Handler class.

  • Each Filter Handler gets an opportunity to set the event's return flags, but these will only be respected if the Filter sets its allowToContinue to false (.F.), because if processing continues, the successive Event Handler will assume it can set these flags as it wishes, possibly overriding any setting made by the Filter Handler.

2. An appropriate Event Handler class is instantiated

The report builder next looks for a specific Event Handler class to instantiate and handle the event.

The Registry table allows for "wild card" matches, so that not every unique combination of builder event + report object needs to have a separate record. The builder uses selectively more general searches in the handler registry table for non-deleted records.

The builder will progressively generalize the searches, applying wild-card values until it finds a match:

Sequence | REC_TYPE | EVENTTYPE | OBJTYPE | OBJCODE
1 | "H" | (Exact) | (Exact) | (Exact)
2 | "H" | (Exact) | (Exact) | -1
3 | "H" | (Exact) | -1 | -1
4 | "H" | -1 | -1 | -1

If still no matching record is found, then the builder event will be ignored (both bits of the ReturnFlags parameter will be cleared) and control returned to the designer for the native Visual FoxPro behavior.

If a match is found, the class is instantiated and its Execute() method invoked.

3. All Exit Handlers are processed

Once the matching Event Handler has been executed, the report builder selects all records from the lookup table with REC_TYPE="X," sorted by FLTR_ORDR, and instantiates each class in turn, invoking the Execute() method.

Concerning multiple selected objects

The default event handler registry table includes a record for a MultiSelectHandler registered to an OBJTYPE of 99. See Multiple Selection Dialog Box (Report Builder) for an example of a handler of multiple selections.

The builder detects when multiple report controls are selected in the layout and treats this case as a unique OBJTYPE:

Copy Code
COUNT FOR curpos AND RECNO() > 1 TO oEvent.SelectedObjectCount
IF oEvent.SelectedObjectCount > 1
    oEvent.OBJTYPE = 99
    oEvent.OBJCODE = 0
ELSE
    oEvent.OBJTYPE = frx.OBJTYPE
    oEvent.OBJCODE = frx.OBJCODE
ENDIF

In this way, a specific Event Handler class can be registered to handle multiple-selections.

See Also

Tasks

How to: Add Your Own Handler to the Report Builder's Registry
How to: Configure the Report Builder's Event Handling

Reference

Event Handler Registry Dialog Box (Report Builder)
Report Band Properties Dialog Box (Report Builder)
Report Control Properties Dialog Box (Report Builder)

Concepts

Understanding Report Builder Events

Other Resources

Extending Reports at Design Time


The Report Builder Event Class

Visual FoxPro 9.0
The Report Builder Event Class
See Also

Encapsulates attributes of the report builder event in the reportbuilder.app framework. Also exposes some useful framework methods.

If you decide to create your own handler classes, your code will need to interact with the oEvent parameter object that the builder framework passes to the filter and handler class methods.

oEvent.PropertyName [= eValue]
oEvent.Method( ... )

Properties

PropertyName | Type | eValue
BuilderPath | C | Contains the path of reportbuilder.app, with a trailing backslash.
CommandClauses | O | Contains a reference to the third parameter passed to the report builder. See Understanding Report Builder Events for more information on report builder parameters.
DefaultRecno | I | Specifies the initial position of the record pointer in the FRX cursor.
DefaultSessionId | I | Contains the Data Session Id of the Report Designer, the fourth parameter passed in from the Report Designer.
EventType | I | Contains the second parameter passed in from the Report Designer.
FrxCursor | O | An instance of the FRX Cursor Foundation Class containing some useful functions for interacting with the FRX cursor.
FrxSessionId | I | Data Session of the Report Builder, in which the FRX cursor is open.
ObjCode | I | The value of the frx.OBJCODE field of the initially selected record in the FRX cursor.
ObjType | I | The value of the frx.OBJTYPE field of the initially selected record in the FRX cursor.
Protected | L | Indicates if the Report Designer was launched with the PROTECTED keyword. (Same value as CommandClauses.Protected.)
ReturnFlags | I | The value of this property will be returned to the Report Designer in the first parameter passed in from the Report Designer. Initially set to 0 (no interception, no change). Use .setHandledByBuilder(.T.) and .setReloadChanges(.T.) to configure the return flag appropriately.
SelectedObjectCount | I | Specifies the number of selected report objects in the layout, determined by counting CURPOS=.T. in the FRX cursor (not counting the header record).
SessionData | O | A reference to a name-value pair manager object used to store data between Report Builder invocations
UniqueId | C | Contains the value of the UNIQUEID field of the initially selected record in the FRX cursor.

Methods

Method | Description
GetEventTypeText( [ iEvent ] ) | Returns a character string containing the name of a given event type.
GetTargetTypeText( [ iObjType, iObjCode ] ) | Returns a character string containing the name of a given report object.
GetExpression( cDefExpr, cDataType, cCalledFrom ) | Displays a GETEXPR dialog box and returns a string containing the resultant expression. Ensures that the getExpression dialog box is displayed in the data session of the Report Designer.
Handle( [ iObjType, iObjCode ] ) | Locates a handler class, instantiates it, and calls the Execute() method.
GetExtensionEditor() | Locates an Extension Editor class in the handler registry table, instantiates it, and returns the object reference. For more information, see Report Builder Event Handler Registry Table.
ToString() | Returns a character string "dump" of all the object's property values, suitable for displaying in a MESSAGEBOX call.
SetHandledByBuilder( .T. | .F. ) | Sets the "Event handled By" bit on the ReturnFlags property to suppress (or enable) default Report Designer behavior.
SetReloadChanges( .T. | .F. ) | Sets the "Reload FRX changes" bit on the ReturnFlags property so that changes made to the FRX cursor are reflected (or not reflected) in the report layout.
Note:
If your class makes changes to the FRX cursor that need to be reloaded into the layout, it should call the .SetReloadChanges(.T.) method.

See Also

Reference

Report Builder Event Handler Registry Table

Concepts

Understanding Report Builder Events

Other Resources

Extending Reports at Design Time


How to: Display the Report Builder Options Dialog Box

Visual FoxPro 9.0
How to: Display the Report Builder Options Dialog Box
See Also

The report builder application, reportbuilder.app, features an Options dialog box where various configuration settings can be adjusted.

Important
Unlike the settings in the Visual FoxPro Options Dialog Box (Visual FoxPro), adjustments to report builder settings in this dialog box do not persist between Visual FoxPro sessions.

Tip:
You can remove access to this dialog box for end-users modifying reports, by issuing the MODIFY REPORT | LABEL command with the PROTECTED keyword in your application.

To open the Builder Options dialog box from the Report or Label Designer

  1. Right-click the report layout background, and select Properties… from the context menu.

    - OR -

    Open the Properties dialog box of any report control or report band.

  2. Right-click the surface of the dialog box to display the dialog boxes context menu.

  3. Select Options…

    The Builder Options dialog box appears.

To open the Builder Options dialog box from the Command Window

  1. DO (_REPORTBUILDER)

See Also

Reference

Report Builder Options Dialog Box (Report Builder)

Other Resources

Extending Reports at Design Time


How to: Configure the Report Builder's Event Handling

Visual FoxPro 9.0
How to: Configure the Report Builder's Event Handling
See Also

The Report Builder can be set to respond to events in the Report Designer in a number of different ways. It can:

  • Use a lookup table mapping Report Designer events with specific handler classes. This is the default handle mode.

  • Use a "debug" handler class for all events.

  • Notify you of each event as it occurs with a MESSAGEBOX() alert containing information about the parameters that would be passed to the builder. The Report Designer then processes the event as if the builder were not active.

  • Ignore the events completely.

This setting is adjusted from the Report Builder's Options dialog box, or by using the Report Builder's command-line parameters.

Important
Unlike the settings in the Visual FoxPro Options Dialog Box (Visual FoxPro), this preference setting does not persist between Visual FoxPro sessions.

Setting the builder's Event Handling mode using the Options dialog

See How to: Display the Report Builder Options Dialog Box for detailed steps describing how to display this dialog box.

To use the event handler lookup table (default)

  1. Open the Report Builder Options dialog box.

  2. Set the Report Designer event handling option to Search for a handler class in the handler registry table.

  3. Select Close to dismiss the dialog box.

For more information, see How to: Specify an Alternate Report Event Handler Table.

To use the Debug Event handler class

  1. Open the Report Builder Options dialog box.

  2. Set the Report Designer event handling option to Use the debug handler for all events.

  3. Select Close to dismiss the dialog box.

See Report Builder Debug Event Dialog Box (Report Builder) for more information.

To signify each event with a MESSAGEBOX() alert

  1. Open the Report Builder Options dialog box.

  2. Set the Report Designer event handling option to Use the event inspector for all events.

  3. Select Close to dismiss the dialog box.

In this mode, the report builder alerts you to the event occurring, but does not handle the event, passing it back to the Report Designer for normal handling.

To ignore all report builder events

  1. Open the Report Builder Options dialog box.

  2. Set the Report Designer event handling option to Ignore builder events completely.

  3. Select Close to dismiss the dialog box.

The Report or Label Designer will respond to the event normally as though _REPORTBUILDER were empty. See _REPORTBUILDER System Variable for more information.

Setting the builder's Event Handling mode using the command-line

The Report Builder also exposes this setting via a command-line parameter:

To set the event handle mode from the Command Window

  1. Type the following command:

    DO (_REPORTBUILDER) WITH 4, iHandleMode

    - OR -

    DO (HOME()+"reportbuilder.app") WITH 4, iHandleMode

The iHandleMode must be an integer from 1 to 4, representing the four possible event handling modes described above.

See Also

Reference

Report Builder Options Dialog Box (Report Builder)
Report Builder Event Handler Registry Table

Other Resources

Extending Reports at Design Time


How to: Specify an Alternate Report Event Handler Table

Visual FoxPro 9.0
How to: Specify an Alternate Report Event Handler Table
See Also

Reportbuilder.app contains an internal lookup table that defines whether certain report object / builder event combinations are ignored or directed to specific classes for handling.

See Report Builder Event Handler Registry Table for detailed information on the required structure of the lookup table.

Reportbuilder.app has a mechanism that allows you to specify alternate event handler lookup tables so that you can completely customize how the report builder responds to events in the Report or Label Designer.

Important
Unlike the settings in the Visual FoxPro Options Dialog Box (Visual FoxPro), this preference setting does not persist between Visual FoxPro sessions.

Setting the Event Registry Table using the Options Dialog

The Report Builder Options Dialog Box (Report Builder) includes the ability to specify which event handler lookup table the report builder uses.

The Current registry table text box displays the filename of the lookup table that the report builder is using. If the builder is using the table built-in to the application, this will read "internal lookup table."

To specify an alternate lookup table

  1. Open the Report Builder Options dialog box. See How to: Display the Report Builder Options Dialog Box for detailed steps describing how to display the dialog box.

  2. Select Use alternate lookup table.

  3. Click the ellipsis (…) to display the File Open dialog box.

  4. Select the desired table, and click OK.

  5. Select Close to dismiss the options dialog box.

To revert to using the internal lookup table

  1. Open the Report Builder Options dialog box. See How to: Display the Report Builder Options Dialog Box for detailed steps describing how to display the dialog box.

  2. Select Use internal lookup table.

  3. Select Close to dismiss the options dialog box.

Setting the Event Registry Table using Command-line parameters

You can use the report builder's command-line parameters to set the lookup table that it uses to locate builder event handler classes.

To select an alternate lookup table

  1. Open the Command window.

  2. Type one of the following commands:

    • DO (HOME() + "reportbuilder.app") WITH 3, cFilename

    • * OR:

    • DO (_REPORTBUILDER) WITH 3, cFilename

The cFilename parameter must be a fully pathed file specification of a table (.dbf) file that contains the required fields. For more information on the required table structure, see Report Builder Event Handler Registry Table .

You can use an asterisk to force the report builder to use its internal lookup table:

To force the use of the internal lookup table

  1. Open the Command window.

  2. Type one of the following commands:

    • DO (HOME() + "reportbuilder.app") WITH 3, "*"

    • * OR:

    • DO (_REPORTBUILDER) WITH 3, "*"

If you pass the report builder an empty string, the report builder will revert to default behavior, which is to look for a table named "reportbuilder.dbf" in the current PATH, and use it if found. If it isn't found, the report builder will use the internal lookup table.

To revert to default behavior

  1. Open the Command window.

  2. Type one of the following commands:

    • DO (HOME() + "reportbuilder.app") WITH 3, ""

    • * OR:

    • DO (_REPORTBUILDER) WITH 3, ""

See Also

Tasks

How to: Configure the Report Builder's Event Handling

Reference

Report Builder Options Dialog Box (Report Builder)

Other Resources

Extending Reports at Design Time


How to: Add Your Own Handler to the Report Builder's Registry

Visual FoxPro 9.0
How to: Add Your Own Handler to the Report Builder's Registry
See Also

The Report Builder uses an internal lookup table mapping event types in the Report or Label Designer to specific event handler classes. Because this table is built into reportbuilder.app, it is read-only and cannot be modified.

By default, the Report Builder will use an external table with the filename reportbuilder.dbf in preference to its internal handler table, if it meets one of the following requirements:

  • It is in Visual FoxPro's SET PATH

  • It is in the same folder as reportbuilder.app.

The Report Builder has a mechanism to create an external copy of the lookup table, available from its Options dialog box.

Once the file exists on disk, you can make changes to the table, either by browsing it in the Visual FoxPro directory, or by using the Report Builder's Handler Registry Table Explorer.

In this topic, you will learn how to:

  • Copy the read-only event lookup table so that you can make changes.

  • Explore the Report Builder's event lookup table.

  • Add and configure your own event handler class to the lookup table.

See Report Builder Event Handler Registry Table for more information on the lookup table.

Creating an editable copy of the internal lookup table

To copy the internal lookup table out to disk using the options dialog

  1. Open the Report Builder Options dialog box. For more information, see How to: Display the Report Builder Options Dialog Box.

  2. Click Create copy… to open the Save as dialog box.

  3. Change the file name and location if you wish, and click Save to create the copy.

  4. Click Close to dismiss the Options dialog box.

The default location in the Save as dialog box will be the directory in which reportbuilder.app is located, and the default file name will be reportbuilder.dbf. This is the table that the Report Builder will use in preference to its internal one.

Tip:
After you create and edit your event lookup table, you can add it to your applications and give it a different name. To specify this table for the Report Builder's use in your applications, you invoke reportbuilder.app in a special configuration mode while performing setup tasks for your application. For more information, see How to: Specify an Alternate Report Event Handler Table.

To copy the internal lookup table out to disk using command-line parameters

  1. Open the Command window.

  2. Type one of the following commands:

    • DO (HOME() + "reportbuilder.app") WITH 5, cFilename

    • * OR:

    • DO (_REPORTBUILDER) WITH 5

The cFilename parameter must be a fully pathed file specification of a table (.dbf) file. If the file exists, it will be over-written. If you omit the cFilename parameter, the Save As dialog box will appear.

Browsing the Event Handler Registry table

To explore the lookup table using the Builder's Event Handler Registry browser

  1. Open the Report Builder Options dialog box. For more information, see How to: Display the Report Builder Options Dialog Box.

  2. Click Explore registry… to open the Event Handler Registry dialog box.

For more information on adjusting the contents of the lookup table, see Event Handler Registry Dialog Box (Report Builder).

Adding a custom handler class to the Event Handler Registry table

In this example, you will create a class that handles the event that occurs when you press CTRL-E on a label report control.

To create a CTRL-E label edit handler

  1. Create or edit a programmatic class library:

    MODIFY COMMAND c:\temp\mylibrary.prg

  2. Create your handler class by typing the following code, then save your changes:
Copy Code
DEFINE CLASS MyLabelEditor AS Custom
    PROCEDURE Execute( oEvent )
        LOCAL cCaption
        cCaption = INPUTBOX("Label caption:",;
                        "Label Properties", TRIM(frx.expr))
        IF NOT EMPTY( m.cCaption )
            REPLACE frx.expr WITH m.cCaption
            oEvent.SetHandledByBuilder(.T.)
            oEvent.SetReloadChanges(.T.)
        ENDIF
    ENDPROC
ENDDEFINE

To register your handler for the Ctrl-E builder event

  1. Open the Report Builder Options dialog box. For more information, see How to: Display the Report Builder Options Dialog Box.

  2. If the Current registry table text box contains "Internal lookup table," follow the steps above to copy the read-only event lookup table so that you can make changes.

  3. Click Explore registry… to open the Event Handler Registry dialog box.

  4. Locate a record with Type="H", Event=14, ObjType=5, ObjCode=0.

  5. If such a record does not exist in the table, add a new record to the table by clicking on Add Record.

  6. Set the field values as shown in the table below.

  7. Click Close to dismiss the Event Handler Registry dialog box.

  8. Click Close to dismiss the Report Builder Options dialog box.

Type | H
Class | MyLabelEditor
Library | c:\temp\mylibrary.prg
Description | Sample Ctrl-E on Label handler
Event | 14
ObjType | 5
ObjCode | 0
Native | False
Debug | False

To test your event handler registry changes

  1. Open a report or label layout in the designer.

  2. Select a label control

  3. Press CTRL-E.

    You should see an INPUTBOX() dialog as your class is invoked to handle the event.

See Also

Tasks

How to: Configure the Report Builder's Event Handling
How to: Specify an Alternate Report Event Handler Table

Reference

Event Handler Registry Dialog Box (Report Builder)
Report Builder Options Dialog Box (Report Builder)
Report Builder Event Handler Registry Table

Concepts

Understanding Report Builder Events

Other Resources

Extending Reports at Design Time


How to: Replace the Report Builder's Expression Builder Dialog Box

Visual FoxPro 9.0
How to: Replace the Report Builder's Expression Builder Dialog Box
See Also Example

The Report Builder architecture defines a framework into which you can plug your own classes to handle specific builder actions, such as responding to report designer events. Additionally, the report builder also allows you to replace the Expression Builder dialog box with your own implementation, by registering a class in the report builder's event handler registry table.

This topic describes the process of plugging in your own class to replace the expression builder dialog box, and also gives a more comprehensive example class that demonstrates how to create a Data Environment-aware expression builder.

Note:
If you have not already done so, create an editable copy of the report builder's internal event handler registry table, as described in How to: Add Your Own Handler to the Report Builder's Registry.

Note:
This topic assumes that the _REPORTBUILDER system variable is set to the default Report Builder application. If it is empty, or has been set to a third-party report builder, then the procedures described below probably will not apply. For more information, see _REPORTBUILDER System Variable .

To create a GetExpression wrapper class

  1. Create or edit a programmatic class library:

    MODIFY COMMAND c:\temp\mylibrary.prg

  2. Define a class that implements the GetExpression wrapper API, as documented in Report Builder Event Handler Registry Table. You can use the simple example shown here as a template. This example replaces the label caption editor with a simple input box.

  3. Save your changes.
Copy Code
DEFINE CLASS MyGetExpressionWrapper AS Custom
   PROCEDURE GetExpression( cDefaultExpr, cDataType, ;
                            cCalledFrom,  oEvent )
      LOCAL cNewValue
      * Switch to the designer datasession, where tables
      * may be open:
      SET DATASESSION TO (oEvent.DefaultSessionID)
      DO CASE
      CASE m.cCalledFrom = "LabelCaption"
         * Specify special handling for label captions:
         cNewValue = INPUTBOX("Enter the label caption")
      OTHERWISE
         * All other expression builders will use the default:
         GETEXPR "Enter the label caption" TO cNewValue ;
            TYPE cDataType DEFAULT cDefaultExpr
      ENDCASE
      * Restore to the private builder datasession:
      SET DATASESSION TO (oEvent.FrxSessionID)
      RETURN cNewValue
   ENDPROC
ENDDEFINE

To register your class as in the handler registry table

  1. Open the Report Builder Options dialog box:

    DO (_REPORTBUILDER)

  2. Click Explore Registry.

  3. Locate the record with Type = "G".

  4. Edit the record so that Class = "MyGetExpressionWrapper" and Library= "c:\temp\mylibrary.prg"

  5. Click OK to save your changes.

To test your changes

  1. Open a report or label layout in the designer.

  2. Double-click on a label control to display the Properties dialog box.

  3. Click on the ellipsis (…) next to the label caption text box to invoke the custom expression builder provided by your class.

Example

By design and by default, the Expression Builder dialog box invoked by ReportBuilder.App does not show tables that are not open in the designer's data session. Tables and cursors included in the report layout's data environment are not available. This is a change from how the designer's Expression Builder behaved in earlier versions (and still does when _REPORTBUILDER = "").

This example shows how you can define an alternative wrapper class that inspects the data environment, opens the tables in a private data session and then invokes the standard GETEXPR dialog box, to duplicate the original behavior of the report designer's Expression Builder.

You can save this class to a procedure file, and register it for use in the report builder, as described above.
Copy Code
DEFINE CLASS GetExpressionWithDE AS Session

  DataSession = 2   && private

  PROCEDURE GetExpression
     LPARAMETERS lcDefaultExpr, lcDataType, lcCalledFrom, loEvent

     LOCAL lCurSel, lcNewExpr, liPrivateSession
     LOCAL liLines, i, iTableCount, lcAlias, lcSource

     *----------------------------------------------
     * Save this before it changes:
     *----------------------------------------------
     liPrivateSession = THIS.DataSessionId

     *----------------------------------------------
     * Scan the data environment and open tables:
     *----------------------------------------------
     SET DATASESSION TO (loEvent.FrxSessionId)
     lCurSel     = SELECT()
     iTableCount = 0
     SELECT expr FROM frx WHERE objtype = 26 ;
        INTO CURSOR environCursors
     SELECT environCursors
     SCAN
        liLines = ALINES(laValuePairs, environCursors.expr )
        FOR i = 1 TO liLines
           DO CASE
           CASE LEFT(UPPER(laValuePairs[i]),5) == "ALIAS"
              lcAlias = THIS.GetValue( laValuePairs[i])
           CASE LEFT(UPPER(laValuePairs[i]),7) == "CURSORS"
              lcSource = THIS.GetValue( laValuePairs[i])
           ENDCASE
        ENDFOR

        lcSource = EVL(lcSource,"")

        DO CASE
        CASE FILE(lcSource)
        CASE FILE(FORCEEXT(lcSource,"DBF"))
           lcSource = FORCEEXT(lcSource,"DBF")
        CASE FILE(JUSTFNAME(lcSource))
           lcSource = JUSTFNAME(lcSource)
        CASE FILE(FORCEEXT(JUSTFNAME(lcSource),"DBF"))
           lcSource = FORCEEXT(JUSTFNAME(lcSource),"DBF")
        ENDCASE

        IF FILE(lcSource)
           lcAlias = EVL( lcAlias, "Cursor"+TRANSFORM(i))
           SET DATASESSION TO (liPrivateSession)
           IF NOT USED(lcAlias)
              TRY
                 IF EMPTY(ALIAS())
                    USE (lcSource) ALIAS (lcAlias) ;
                       NOUPDATE SHARED
                 ELSE
                    USE (lcSource) ALIAS (lcAlias) ;
                       IN 0 NOUPDATE SHARED
                 ENDIF
                 iTableCount = iTableCount+1
              CATCH WHEN .T.
              ENDTRY
           ENDIF
           SET DATASESSION TO (loEvent.FrxSessionID)
        ENDIF
     ENDSCAN
     USE IN environCursors
     SELECT (lCurSel)
     IF iTableCount > 0
        SET DATASESSION TO (liPrivateSession)
     ELSE
        SET DATASESSION TO (loEvent.DefaultSessionID)
     ENDIF

     *-----------------------------------
     * Display the GETEXPR dialog:
     *-----------------------------------
     GETEXPR TO lcNewExpr TYPE lcDataType DEFAULT lcDefaultExpr

     *-----------------------------------
     * Clean up and exit:
     *-----------------------------------
     SET DATASESSION TO (liPrivateSession)
     CLOSE DATA
     SET DATASESSION TO (loEvent.FrxSessionID)
     RETURN lcNewExpr
  ENDPROC

  PROTECTED PROCEDURE GetValue
     LPARAMETER lcValuePair
     LOCAL liPos, lcReturn
     lcReturn = ""
     IF NOT EMPTY(lcValuePair)
        liPos = AT("=",lcValuePair)
        IF EMPTY(liPos)
           RETURN ""
        ENDIF
        lcReturn =CHRTRAN(ALLTRIM(SUBSTR(lcValuePair,liPos+1)),["'],[])
     ENDIF
     RETURN lcReturn
  ENDPROC

ENDDEFINE

See Also

Tasks

How to: Configure the Report Builder's Event Handling
How to: Specify an Alternate Report Event Handler Table

Reference

Event Handler Registry Dialog Box (Report Builder)
Report Builder Options Dialog Box (Report Builder)
Report Builder Event Handler Registry Table

Concepts

Understanding Report Builder Events


How to: Extend or Replace the Report Builder

Visual FoxPro 9.0
How to: Extend or Replace the Report Builder
See Also Example

Although Visual FoxPro ships with a default Report Builder application, complete with a framework of Report Designer event handlers, you may choose to replace or augment this application with your own implementation.

See Understanding Report Builder Events for more information on how to write a program that complies with the report builder API.

Using an alternate builder application by default

To set the default report builder application

  1. Add a line to CONFIG.FPW that sets the _REPORTBUILDER system variable:

    _REPORTBUILDER = mybuilder.prg

Replacing reportbuilder.app "on the fly"

To change report builders in code

  1. Use code like this to switch to an alternate report builder application:

    cOriginalBuilderApp = _REPORTBUILDER

    _REPORTBUILDER = "mybuilder.prg"

  2. To restore the default:

    _REPORTBUILDER = m.cOriginalBuilderApp

Calling back to ReportBuilder.App

To call back to Reportbuilder.app

  1. Use code like this to switch to an alternate report builder application:

    parameters returnFlags, eventType, cmdClauses, sessionID

    :

    do (HOME(1)+"ReportBuilder.App") with returnFlags, eventType,

    cmdClauses, sessionID

See the example below for a builder application that calls back to Reportbuilder.app to augment the default behavior.

Example

This example program wraps ReportBuilder.App to provide custom behavior for the CREATE REPORT - Quick Report Command.

The functionality includes:

  • Adding a "Company letterhead" to the layout.

  • Updating the header and footer controls.

To use, set _REPORTBUILDER = FULLPATH("quickreportbuilder.prg").
Copy Code
*-----------------------------
* QUICKREPORTBUILDER.PRG
*-----------------------------
#DEFINE QUERY_TITLE_LOC "Creating a Quick Report"
#DEFINE HEADER_QUERY_LOC "Company-standard name will be included. "+ ;
                         "Would you like to add something?"
#DEFINE FINISH_QUERY_LOC "Finished! "+CHR(13)+ ;
                         "Would you like to adjust the contents?"
#DEFINE COMPANY_HEADER_LOC  "ABC Company"

* Return value flags:---------
#DEFINE EVENT_PASSED_TO_VFP       0
#DEFINE EVENT_HANDLED_BY_BUILDER  1
#DEFINE FRX_DISCARD_CHANGES       0
#DEFINE FRX_RELOAD_CHANGES        2

* Hook event types:-----------
#DEFINE EVENTTYPE_REPORTOPEN      7
#DEFINE EVENTTYPE_OBJECTCREATE    2
#DEFINE EVENTTYPE_REPORTSAVE      6
#DEFINE EVENTTYPE_REPORTCLOSE     8
#DEFINE EVENTTYPE_PROPERTIES      1

* ReportBuilder.App Handle Modes:
#DEFINE MODE_HANDLE_CLASS         1
#DEFINE MODE_FORCE_DEBUG          2
#DEFINE MODE_FORCE_NATIVE         3

* standard FRX stuff
#DEFINE OBJTYPE_TEXT              5
#DEFINE OBJTYPE_FIELD             8
#DEFINE OBJTYPE_FONTRES          23
* ----------------------------

#DEFINE MB_YESNO                  4
#DEFINE MB_ICONQUESTION          32
#DEFINE IDYES                     6
#DEFINE IDNO                      7
* ----------------------------

LPARAMETERS returnFlags, eventType, commandClauses, designerSessionId

* This builder only takes action on a quick report.
* Criteria:  - Must be a REPORT and not a LABEL layout
*            - Must be a CREATE REPORT FROM... command

LOCAL BuilderModule
BuilderModule = HOME()+"ReportBuilder.App"

IF commandClauses.IsReport AND NOT EMPTY(commandClauses.FROM)

    LOCAL oFrxHelper
    oFrxHelper = NEWOBJECT("frxCursor", HOME()+"FFC\_frxcursor.vcx")

    DO CASE
    CASE m.eventType = EVENTTYPE_REPORTOPEN
        * This is the first event in a quick report.
        * First, replace default font resource and font
        * info in header to match our requirements, because
        * there are some hardcoded metrics for heights in this
        * simple example.
        * The FRX cursor is in the current workarea:
        REPLACE frx.fontface WITH "Courier New" ;
            FOR RECNO() = 1 OR frx.objtype = OBJTYPE_FONTRES
        LOCATE FOR frx.objtype = OBJTYPE_FONTRES

        * Now, add a font resource record for our
        * "designed" expression:
        SCATTER MEMVAR MEMO
        m.penred = 255
        m.fontface = "Tahoma"
        m.fontstyle = 1
        INSERT INTO frx FROM MEMVAR

        * Now, reuse the memvars, changing their values, to set up
        * the designed expression's record:
        m.uniqueid   = SYS(2015)
        m.objtype    = OBJTYPE_TEXT
        m.objcode    = 0
        m.timestamp  = oFrxHelper.getFrxTimeStamp()
        m.vpos       = 20
        m.hpos       = 20
        m.height     = 3000
        m.width      =  50000
        m.fillchar   = "C"
        m.penred     = 255
        STORE -1 TO m.fillred, m.fillgreen, m.fillblue
        m.mode       = 1
        m.stretch    = .T.
        m.top        = .T.
        m.spacing    = 2
        m.offset     = 2
        m.resettotal = 1
        m.supalways  = .T.
        m.suprpcol   = 3
        m.supgroup   = 0
        m.totaltype  = 0
        m.expr       = INPUTBOX(HEADER_QUERY_LOC, ;
                                QUERY_TITLE_LOC, ;
                                COMPANY_HEADER_LOC)

        DO CASE
        CASE EMPTY(m.expr)
            m.expr = COMPANY_HEADER_LOC

        CASE ATC(COMPANY_HEADER_LOC,m.expr) = 0
            m.expr = COMPANY_HEADER_LOC + " " + ALLTR(m.expr)

        ENDCASE
        m.expr = ["]+m.expr+["]

        INSERT INTO frx FROM MEMVAR

        * Finally, tell the Designer to consume our edit:
        returnFlags = FRX_RELOAD_CHANGES

    CASE  m.eventType = EVENTTYPE_REPORTSAVE
        * This is the last event in a quick report.

        IF NOT EMPTY(m.BuilderModule) AND ;
            MESSAGEBOX(FINISH_QUERY_LOC,;
                       MB_YESNO +MB_ICONQUESTION,;
                       QUERY_TITLE_LOC) = IDYES

            * Give the user a chance to adjust or eliminate
            * objects of certain types:
            SCAN ALL FOR INLIST(frx.objtype, ;
                       OBJTYPE_FIELD, OBJTYPE_TEXT)
                * Mark the object as "selected" so that the
                * builder will act on it:
                REPLACE frx.curpos WITH .T.
                * Call the builder application, ;
                * faking a regular Report Designer event:
                do (BuilderModule) with ;
                        -1, EVENTTYPE_PROPERTIES, ;
                        m.commandClauses, ;
                        m.designerSessionId
                REPLACE frx.curpos WITH .F.
            ENDSCAN
            m.returnFlags = FRX_RELOAD_CHANGES
        ENDIF

        * Find the DATE() expression control created by the
        * Quick Report process and convert it into a DATETIME():
        LOCATE FOR frx.objtype = OBJTYPE_FIELD AND ;
                        UPPER(ALLTRIM(frx.expr)) == "DATE()"
        LOCAL liWidth
        liWidth = oFrxHelper.GetFruTextWidth( ;
                                TRANSFORM(DATETIME()),;
                                frx.fontface, frx.fontsize )
        REPLACE frx.expr  WITH "DATETIME()", ;
                                frx.width WITH m.liWidth

        * Find the _pageno controls and spiff them up a bit:
        LOCATE FOR frx.objtype = OBJTYPE_TEXT ;
            AND ATC(["PAGE],frx.expr) > 0
        IF FOUND()
            REPLACE frx.expr WITH ["Page "+TRANSFORM(_PAGENO)],;
                    frx.objtype WITH OBJTYPE_FIELD, ;
                    frx.hpos WITH (frx.hpos - (frx.width*2)), ;
                    frx.width WITH frx.width*3
            SKIP
            * Remove the other _pageno object that
            * follows the "Page" one in a normal quick report:
            DELETE
        ENDIF

        * We need to instruct the Designer to respect our changes:
        returnFlags = FRX_RELOAD_CHANGES

    OTHERWISE
        returnFlags = EVENT_PASSED_TO_VFP

    ENDCASE

ELSE
    * Parameters are passed by reference:
    do (BuilderModule) with m.returnFlags, ;
                            m.eventType, ;
                            m.commandClauses, ;
                            m.designerSessionId
ENDIF
RETURN

See Also

Tasks

How to: Add Your Own Handler to the Report Builder's Registry

Reference

Report Builder Event Handler Registry Table

Concepts

Understanding Report Builder Events

Other Resources

Extending Reports at Design Time


How to: Specify and Distribute ReportBuilder.App

Visual FoxPro 9.0
How to: Specify and Distribute ReportBuilder.App
See Also

When you write and distribute Visual FoxPro applications, you may choose to give your users the ability to customize some or all of your application's report layouts. The report builder and report protection features in Visual FoxPro 9.0 makes this a safer and controlled solution for your application.

In this topic, you will learn how to redistribute the default Report Builder application in two ways:

  • Distribute the Report Builder as a separate file alongside your own application, and ensure that Visual FoxPro is directed to the location of the reportbuilder.app file at run time.

  • Build the Report Builder source files directly into your own application.

Redistributing ReportBuilder.App with Your Application

By default, if ReportBuilder.App exists in the same directory as the Visual FoxPro run-time files, then _REPORTBUILDER will contain the fully-qualified path and filename. One solution is to ensure that the setup program used to distribute your application places ReportBuilder.App in the same directory as the run-time files. Alternatively, you can distribute ReportBuilder.App in the same directory as your application, providing you explicitly set _REPORTBUILDER to point to your copy of the ReportBuilder.App file.

To make sure the Visual FoxPro run-time environment can find your distributed copy of ReportBuilder.App

  1. In the main program of your application, use code similar to the following:

    Copy Code
    * Get the application's home directory:
cHomeDir = CURDIR()  && use whatever method you prefer
* Set the system variable to use the fully-qualified path:
_REPORTBUILDER = m.cHomeDir+"ReportBuilder.App"
:

You could also use a line in CONFIG.FPW:

_REPORTBUILDER=<path>\ReportBuilder.App

Considerations

If you distribute ReportBuilder.App in this way, you will not be able to specify an alternative report event handler registry table that is built-in to your application's APP file. This is because the code running inside ReportBuilder.App cannot use any files built in to other applications (.app or .exe files).

Integrating the Report Builder Source into Your Project

Instead of distributing the compiled application, you may choose to incorporate the source code of the report builder directly into your application's project.

To integrate the report builder source into your application

  1. Unpack the xsource.zip file found in the Tools\xsource\ folder under the Visual FoxPro home directory.

  2. In the main program of your application, use code similar to the following:

    Copy Code
    * Ensure the report builder source is pulled into the project:
EXTERNAL PROCEDURE frxbuilder.prg
* Set the system variable to use the local source version:
_REPORTBUILDER = "frxbuilder.prg"
:

  3. Rebuild your project.

    The report builder source code and event handler lookup table will be added to your project and compiled in to your application.

Rather than use the original version of the event handler lookup table, frxbuilder.dbf, you may wish to customize it. Be careful - your project is referencing your master copy of the report builder source. You may prefer to remove the frxbuilder.dbf file from your project, and replace it with a customized copy local to your application's source tree.

You do not have to keep the default name for this table. If you wish, you can tell the report builder to use an alternatively named table instead:

To specify an alternate event handler registry table

  1. In the setup portion of the main program of your application, use code similar to the following:

    do frxBuilder with 3, "mylookup.dbf"

Shared Source Files

ReportBuilder.App and ReportPreview.App have the following source files in common:

  • frxControls.vcx

  • frxCommon.prg

  • grabber.gif

  • wwrite.ico

  • foxpro_reporting.h

The Project Manager creates only one reference to each of these files in your application's project, depending on the order of the EXTERNAL statements in your main program.

Considerations for Report Builder Help

Report Builder Application dialog boxes are supplied with help information in the Visual FoxPro help file, associated with the HelpContextID Property (Visual FoxPro) of various interface elements. The Visual FoxPro help file cannot be redistributed with your application. For information, see Distributable and Restricted Visual FoxPro Features and Files.

When you distribute Report Builder Application or its components, and if you provide help files for your applications, you can choose one of the following strategies:

  • Create help topics using the appropriate context IDs in your help file, matching the context IDs the Report Builder uses. Check the help ID constants defined in FRXBUILDER.H for the correct context IDs to use.

  • Do not create help topics with these context IDs. When the user presses the F1 key or uses a Help button, your help file will appear with your top-level topic showing.

  • Change the constants defined in FRXBUILDER.H in the Report Builder source to use one or more different context IDs, and create a topic or multiple topics in your help file to match the context IDs you use. You will need to recompile ReportBuilder.App from the source code in order for this change to take effect.

To specify different help context ID values for Report Builder Application components

  1. Modify the help context id constants defined in FRXBUILDER.H and save your changes.

  2. Recompile the Report Builder Application, or recompile your application if you are building in the Report Builder components to your application.

When you distribute Report Builder Application or its components, and if you do not provide a help file for your application, you have the following options:

  • Distribute ReportBuilder.app or its components as-is. When they determine that SET("HELP") = "OFF", ReportBuilder components disable the Help button.

  • Adjust an associated constant in the frxbuilder.h file to remove the Help button.

To remove the Help button from Report Builder Application interface elements

  1. Locate the frxbuilder.h file in the Report Builder Application source.

  2. Change the value of the SHOW_HELP_BUTTON_ON_HANDLER_FORMS constant to False (.F.).

  3. Recompile the Report Builder Application, or recompile your application if you are building in the Report Builder components to your application.

For more information about using the Visual FoxPro help system in applications, see SET TOPIC ID Command and SET HELP Command.

See Also

Tasks

How to: Specify an Alternate Report Event Handler Table

Reference

_REPORTBUILDER System Variable
Including Report Files for Distribution

Concepts

Application Distribution Process

Other Resources

Configuring Help Files for Applications


Extending Reports at Run Time

Visual FoxPro 9.0
Extending Reports at Run Time

The Visual FoxPro Report System provides many ways to attach your code to the report rendering process. The following topics discuss how to use and take best advantage of the preview and output run-time hooks.

In This Section

Understanding Visual FoxPro Object-Assisted Reporting

Describes the object-assisted output architecture which enables you to extend run-time report processing.
Extending Report Preview Functionality

Describes the Visual FoxPro report preview architecture and how to replace the default preview implementation with your own.
Extending Report Output Functionality

Describes how the Visual FoxPro ReportListener class enables you to control the generation of various output types from report and label layouts.
Handling Errors During Report Runs

Describes the special features of the ReportListener class designed to help you trap and manage errors during reports, and considers the role of other Visual FoxPro commands and functions in error-handling during report runs.

Related Sections

Extending Reports at Design Time

Describes how the Visual FoxPro report builder architecture works, introduces the functionality of the default report builder application, how to customize it or replace it with your own application.


Understanding Visual FoxPro Object-Assisted Reporting

Visual FoxPro 9.0
Understanding Visual FoxPro Object-Assisted Reporting
See Also

Visual FoxPro 9 introduces an object-assisted architecture for reporting. Using this architecture and your existing report forms you can enhance the reporting process in many ways, such as:

  • Generating multiple output results during a single report run.

  • Improving printed and preview quality.

  • Connecting multiple report runs together to achieve one output result.

  • Adjusting the report content dynamically while processing data.

  • Generating new types of output not available previously.

This topic discusses the objects that work together to provide these enhancements, and describes what happens during an object-assisted report run.

Visual FoxPro 9's Report System is best described as object-assisted rather than object-oriented. The Report Engine is not an object. However, when you use the new architecture, the Engine delegates much of its work to objects.

Note:
The Report Designer also does not incorporate references to Visual FoxPro classes defined in visual class libraries (.vcx files) or programs (.prg files) as layout elements. However, using the new design-time architecture, you can use instances of Visual FoxPro classes to define attributes of report layout elements. These template classes can be attached to the report definition, and dynamically provide formatting changes and method code at run time. For more information, see Report XML MemberData Extensions.

Run-time Output Architecture

In earlier versions of Visual FoxPro the Report Engine was monolithic. It handled all processing as a single unit. When you designed a report you had the ability to attach some code at various points, primarily when the Report Engine began to process, or finished processing, a report layout band.

In Visual FoxPro 9, the Report Engine handles the movement of the record pointer through your report's data scope, and evaluates expressions. It delegates the process of rendering the results to a new Visual FoxPro baseclass, ReportListener. Because you can derive classes from ReportListener, you can affect the rendering of each individual object in a report on a much more granular level than before. For more information, see ReportListener Object.

Visual FoxPro Reporting Engine Overview graphic

How to Invoke Object-Assisted Reporting

You can use the OBJECT [TYPE<N>] clause on the REPORT FORM or LABEL command to tell the Report Engine what ReportListener-derived object or object type to use. You can also tell the Report Engine to use an application whose name is stored to a system variable, _REPORTOUTPUT, to nominate an appropriate object for you. If you have SET REPORTBEHAVIOR to the value 90, the Report Engine automatically requests the application whose name is stored in _REPORTOUTPUT for an object, each time you issue a REPORT FORM or LABEL command.

Visual FoxPro Reporting Engine Print Path I graphi

If you have invoked a REPORT FORM or LABEL command with the intention of providing an on-screen preview, the Report System invokes another object, the PreviewContainer, to display the preview, after they finish their jobs of evaluating and rendering the report contents. Because the PreviewContainer is a Visual FoxPro object instance, you can create previews to match a wide variety of specifications and customize them for your applications. For more information about how to create an object matching the requirements of a PreviewContainer, see The Preview Container API.

Visual FoxPro Reporting Engine Preview Path I grap

Report System Processing Modes

The ReportListener processes a report or label in two different modes, depending on the value of its ListenerType Property. You can think of these two modes as print-appropriate and preview-appropriate, or page-at-a-time and all-pages-at-once.

In both modes, your ReportListener-derived class has an opportunity to affect the rendering of each layout element, as each element in each band is processed. The modes differ in how, and when, your derived class gets access to the rendered results, or output pages, prepared by the ReportListener baseclass.

In page-at-a-time mode, the ReportListener triggers an OutputPage event as it prepares each page, at the same time as it sends each page to the printer or print queue. Your derived class has access only to the page that has just been prepared, and only at that time. This mode is efficient if you only need access to each page once. For example, you might be saving each page to disk as an image. For full information on the capabilities and options available, see OutputPage Method.

Visual FoxPro Reporting Engine Print Path II graph

In the second, all-pages-at-once mode, the ReportListener prepares all pages for rendering and caches them. It does not trigger OutputPage events while it prepares the pages. When the report run concludes, you can invoke the OutputPage method to access any page included in the output, by page number. You can request pages in any order, multiple times.

Visual FoxPro Reporting Engine Preview Path II gra

The report is now completely prepared and ready for previewing. At this point, if you have specified a value of 1 for ReportListener's Listenertype property, the ReportListener invokes the object referenced in its PreviewContainer property to display the preview.

You can store a reference to any object fulfilling the requirements of the PreviewContainer API in this property. If it does not already have an object reference, the Reportlistener requests an appropriate object reference from an application whose name is stored in another system variable, _REPORTPREVIEW.

Visual FoxPro Reporting Engine Preview Path III gr

When the entire report is prepared, the ReportListener uses the PreviewContainer's SetReport method. This action gives the PreviewContainer a reference to the ReportListener, and indicates that the ReportListener's readiness for preview. The PreviewContainer takes control of the reporting process at this point. It uses the ReportListener's OutputPage method to request the pages required for display, as the user navigates through the report.

For more information about how to leverage the default Report Preview Application or write a replacement, see Extending Report Preview Functionality.

If the user decides to print from the preview interface, the PreviewContainer calls the ReportListener's OnPreviewClose method with appropriate instructions. The ReportListener resumes control, and prints the cache of pages it previously prepared. For more information, see OnPreviewClose Method.

This section has given you a tour of the objects that cooperate in Visual FoxPro object-assisted mode reporting. The next section discusses the events that occur during a report run, while the Report Engine and ReportListener prepare and render the report contents. It gives you the information you need to assess the report status, and write appropriate code, during different stages of preparation.

Run-time Output Processing

The following processing narrative describes the full report run. As described in the previous section, there are several ways you can ensure that a REPORT FORM or LABEL command is processed with an object reference. The different ways of invoking object-assisted reporting do not change the event sequence described in this section.

The Report Engine and ReportListener baseclass process the report in a series of events that begins just before the BeforeReport event and finishes just after the AfterReport event. The ReportListener baseclass also provides two external, or framing, events, LoadReport and UnloadReport that allow your code to pre- and post- process the report.

Note:
For full information about ReportListener member events, refer to the various entries ReportListener Object Properties, Methods, and Events.

Beginning the report run

When a REPORT FORM or LABEL command is processed, the Report Engine first checks to see if a previous command included the NOPAGEEJECT keyword. This keyword indicates that multiple reports are being processed together and that some output is already in the queue for eventual display or printing.

If there was no previous NOPAGEJECT, the ReportListener's OutputPageCount property value is reset to 0.

The Report Engine next creates the ReportListener's special data session and provides its DataSessionID value to the ReportListener, using the ReportListener's FRXDataSession property. It also assigns the ReportListener's CommandClauses property; although not all CommandClauses properties are immediately available. For more information, see CommandClauses Property.

The Engine now invokes the ReportListener's LoadReport event and evaluates the return value of any user code you provide in this event. If LoadReport returns a value of False (.F.), report processing does not continue.

Tip:
If you want to make changes to the report or label table or to the current printer driver, LoadReport is your opportunity to do so. You can also dynamically change the value of the ReportListener.CommandClauses.Prompt member and other output-target-related ReportListener.CommandClauses members.

After LoadReport, the Engine is ready to investigate the contents of the report or label table. If specified in the table, the Engine prepares a private data session to hold the report data. It stores the DataSessionID value for the data to be processed during the report in the ReportListener's CurrentDataSession property.

The Report Engine now switches to the FRXDataSession and provides a read-only copy of the report or label table, using the alias FRX, in this session.

Tip:
The Report Engine and ReportListener do not use this copy of the report or label definition table; in fact, they never switch to this session again during the course of the report run. The Report Engine reads the contents of the table into a separate structure for its own use.

The Report Engine switches the data session back to the CurrentDataSession containing the data to be processed during the report run. It is now ready to begin its internal processing.

Note:
In this section, you have learned about two data sessions used during a report run (the CurrentDataSession and FRXDataSession). These two data sessions are most critical to understand as you begin to write ReportListener code. However, other data sessions may be involved in the report run. A later section of this topic describes the relevant types of data sessions in more detail.

Beginning the report run's internal processing

If the ReportListener is set to a ListenerType value of 1 (printing), and if you have used the PROMPT clause on the report or label processing command, or if you have set the ReportListener.CommandClauses.Prompt value to .T. in the LoadReport event, the Print Setup dialog box is displayed at this time. The initial values in this dialog box reflect any RANGE instructions you used on the processing command; however the effective print RANGE for the report, and the values of related ReportListener.CommandClauses members, may be altered by user choices in the dialog box.

When the user closes the dialog box, the Report Engine opens the print queue, if required, unless the user canceled the print run. It also checks the current printer settings (even if no printing is requested) to determine the current page dimensions. If you used the NODIALOG keyword on the processing command but did not set the ReportListener.QuietMode property to True (.T.), the property is automatically set to True (.T.) for the balance of the report run. The Report Engine next calls the BeforeReport event.

Tip:
We have now reached the sequence of events that comprises the Visual FoxPro native report run. The ReportListener GetPageHeight and GetPageWidth methods have valid return values. All CommandClauses members are prepared. You can use the ReportListener's CancelReport method from now until the end of AfterReport, if you need to interrupt and prematurely end the report run.

After BeforeReport, the Report Engine and ReportListener do their initial evaluation of various aspects of the report or label table. For example, they check to see whether you have used the system variable _PAGETOTAL in report expressions. If so, the ReportListener's TwoPassProcess property value is set to True (.T.). The ReportListener's CurrentPass property value is also set to 0 at this time. For more information, see CurrentPass Property and TwoPassProcess Property.

Note:
You can set the TwoPassProcess property's value to True (.T.) manually if you want to force two passes to occur. The ReportListener will respect this manual assignment if you set it before calling the REPORT FORM or LABEL command, in the LoadReport event, or the BeforeReport event.

Handling report content

The Report Engine and ReportListener have finished their setup phase. They now process all the band events relevant to the report. Between each band's BeforeBand and AfterBand Events, they process each layout element belonging to the band. Each layout element has the following potential events:

  • An EvaluateContents event, if it is a Field or Expression element.

  • An AdjustObjectSize event, if it is a Shape or Image element. If the Shape or Image does not fit on the page, it is possible for this event to be repeated in additional attempts on subsequent pages.

  • Zero to many Render events, for all types of layout elements. An element does not trigger a Render event if its Print When expression evaluates to True (.T.). Otherwise, it triggers at least one Render event and potentially more, if it spans bands and pages.

If the ReportListener.TwoPassProcess property is True (.T.), the Report Engine and ReportListener run through all the band and element events twice. The first time, they evaluate expressions and placement on output pages without actually rendering anything. This is a pre-processing, or calculation pass. It allows the Report Engine to calculate a _PAGETOTAL value for use in rendering output on the second, or rendering, pass. The pre-processing pass also provides an opportunity for your code to calculate other values.

Tip:
You can use the ReportListener Debug Foundation Class to examine the report run event processing closely. Use the class's Verbose property to examine the contents of the ReportListener's CommandClauses member at different points in the result, and receive extended information about various methods' object parameters.

Ending the report run

The final report band processed is either a Page Footer band or a Summary band; even if you use the ReportListener's CancelReport method, the Report System finishes processing a full page before interrupting the report.

After the final report band processes, the ReportListener and Report Engine begin clean-up procedures.

The report's private data session, if any, is closed before the AfterReport event occurs. To ensure that the ReportListener always has a valid data session to which it can return, if the report used a private data session, the ReportListener's CurrentDataSession is reset to 1, the default value, at this time. If the report did not have a private data session, the CurrentDataSession is outside the Report System's control, and does not change.

The ReportListener's AfterReport event is invoked next. Following AfterReport, natively-provided output is finalized. If a print stream was opened for this output, it is closed now. At this time, the CancelReport method ceases to have any effect on internal processing; there is no more "report run" from the Report Engine's point of view.

The ReportListener.QuietMode property value is restored to False (.F.), if it was turned out temporarily as a result of the NODIALOG keyword.

If the ReportListener.ListenerType property value is 1, the ReportListener invokes the PreviewContainer to display the report output at this point, followed by UnloadReport after the PreviewContainer returns control to the ReportListener. If the ListenerType property value is not 1, the ReportListener's UnloadReport method occurs immediately.

After the UnloadReport event, the Engine closes the special data session in which it opened a copy of the report or label table. It resets the ReportListener.FRXDataSession property to its default value, -1, at this time, signifying that there is no valid session fulfilling this purpose between report runs.

The ReportListener.TwoPassProcess is reset to its default value of .F.. By putting this property back into its default state, the ReportListener makes it possible for you to explicitly re-assign this value before the next time you use the ReportListener instance. The ReportListener.CurrentPass property value is not reset; its current value gives you a way to assess what happened on the previous report run.

Unless you used the NOPAGEEJECT keyword on this report run, the ReportListener GetPageWidth and GetPageHeight methods stop proving useful values at this point.

Data Sessions Associated with Object-Assisted Report Runs

When each ReportListener event begins, the data session is the one in which the ReportListener object was originally created. This data session is not always the same data session in which you issued the REPORT FORM or LABEL command. The ReportListener Base Foundation Class uses the term ListenerDataSession, with an associated protected member property, to describe and manipulate the data session in which it originated.

In the framing events of the report run (LoadReport and UnloadReport), you should return to the ListenerDataSession upon completing any code sequence that switches data session. The Report Engine will expect to find the ReportListener object in this state at the conclusion of these events. Refer to SET DATASESSION Command for more information about switching between data sessions.

As events progress through the other report events and the Report Engine's internal processing, your ReportListener code normally switches between the data sessions indicated by the ReportListener's CurrentDataSession Property and FRXDataSession Property. Switching between these two data sessions allows you to reference the report's data files as well as the copy of the report or label table as you generate output, as needed.

The Report Engine also provides you with information about a fourth data session: the data session in which you issued the REPORT FORM or LABEL command. You find this DataSessionID value as a StartDataSession member property of the CommandClauses Property object. You do not normally need to reference this fourth data session in ReportListener code. It is provided in case you need to reference the environment in which the command occurred. For example, you might want to check the setting of a session-scoped environmental setting such as SET("DELETED"). For more information, see Customizing the Environment of a Data Session.

The REPORT FORM or LABEL command's StartDataSession may be the same data session as the one referenced by the ReportListener's CurrentDataSession property. However, if the report table specifies a private data session for the report run, the CurrentDataSession and StartDataSession are not the same. The StartDataSession may also be the session in which the ReportListener was created, if your ReportListener object is scoped to a form or session object. However, a ReportListener is often global in scope, for example created by the Report Output Application or by a manager object belonging to your application. In this case, the StartDataSession and ListenerDataSession are unrelated.

See Also

Tasks

How to: Use Data Sessions

Reference

_REPORTOUTPUT System Variable
_REPORTPREVIEW System Variable
_PAGETOTAL System Variable
_PAGENO System Variable
Session Object

Concepts

Handling Errors During Report Runs


Extending Report Preview Functionality

Visual FoxPro 9.0
Extending Report Preview Functionality

In addition to the Report Designer's builder events, which are hooks into the report design process, Visual FoxPro also provides hooks into the process of running reports. These hooks are exposed through the ReportListener, an instance of which is used in object-assisted reporting.

There are two ways to enable object-assisted reporting:

  • SET REPORTBEHAVIOR 90

  • Write code that explicitly uses the OBJECT clause on the REPORT FORM Command.

The topics in this section introduce the preview container component used by the ReportListener class when rendering previews in object-assisted reporting, and how to leverage it in your applications.

In This Section

The Preview Container API

Describes the properties and methods that a class must implement to be used as a Preview Container.
Creating a Custom Preview Container

Describes how to replace the default preview container with your own custom component that can provide report preview functionality thoughout your application automatically when you SET REPORTBEHAVIOR 90.
Leveraging the Default Preview Container

Describes the additional capabilities of the Preview Container component provided by the Preview Container Object Factory application shipped with Visual FoxPro and referenced by the _REPORTPREVIEW system variable, by default.
How to: Specify and Distribute ReportPreview.App

Explains how to distribute ReportPreview.App, either as a separate App file with your application, or by integrating the source code into your application's project.

Related Sections

Understanding Report Builder Events

ReportListener Object

SET REPORTBEHAVIOR Command

REPORT FORM Command

_REPORTPREVIEW System Variable

Extending Report Output Functionality

Extending Reports at Design Time


The Preview Container API
See Also

When previewing a report or label layout in object-assisted mode, a ReportListener requires an additional component to supply the preview user interface. This component is called a preview container and is written in Visual FoxPro code, and it is therefore completely customizable.

There are two ways a ReportListener instance gets a preview container when it needs one:

  1. Your code explicitly assigns an object reference to the ReportListener's PreviewContainer property.

  2. The ReportListener object asks for an object reference from the Preview Container Object Factory application referenced by the _REPORTPREVIEW System Variable.

The Preview Container API

An object of ReportListener class expects the following methods to be implemented by the object assigned to its PreviewContainer property:

PreviewContainer Method Parameter Description

SetReport()

oListenerRef

The ReportListener object will invoke this method, passing it a reference to itself so that the preview container code can call back to listener methods.

  • SetReport() may be called before the report has completed processing, so this method should store the parameter value for later reference.

  • SetReport() may be called with a .NULL. value, in which case the preview container should clear any internal references to a previously passed report listener object, and reset itself.

Show()

[ iModality ]

The ReportListener object will call this method when the report engine is ready to display the preview interface and allow the user to navigate through the report or label output. The iModal parameter is the same as that passed to a form's Show Method (Visual FoxPro).

Although not referenced by any external program, an object implementing the Preview Container API should have an internal reference to the report listener object passed to the object via the .SetReport() method.

PreviewContainer Property | Type | Description
oReport | Object | The .SetReport() and .Show() methods are called at different times. In order for the preview container to have access to various report listener properties at the time the Show() method is called, it should save the report listener reference passed in SetReport() to an internal property.

An object of ReportListener class also expects to receive messages from an object assigned to its PreviewContainer property:

ReportListener Method Parameter Description

OnPreviewClose()

lPrint

The ReportListener expects that its OnPreviewClose() method will be called when the preview user interface is closed or otherwise dismissed by the user. The PreviewContainer object can send the lPrint parameter to indicate whether the user chose to print from the preview.

Exactly which PreviewContainer method makes the call is not important. If the PreviewContainer object is a form, or has an interface similar to a form's, some candidate methods would be Hide(), Release(), QueryUnload(), and Destroy().

It takes a few lines of code to put it all together:

Copy Code
* Instantiate your preview container implmentation
oMyPreview = NEWOBJECT("MyPreviewContainer","MyClassLib")
* Instantiate a ReportListener (or your own derived class)
oListener  = CREATEOBJECT("ReportListener")
* Tell the listener to render all pages and use a preview container:
oListener.ListenerType = 1
* Give the listener a reference to your preview container:
oListener.PreviewContainer = m.oMyPreview
* Run the report:
REPORT FORM myreport OBJECT m.oListener

For an example of a simple preview container implementation, see Creating a Custom Preview Container.

The _REPORTPREVIEW Object Factory

The code shown above covers the case where a ReportListener is explicitly assigned a preview container reference prior to running the report. If the ReportListener does not have a preview container reference, and requires one, it obtains one by calling out to the application or program referenced by the _REPORTPREVIEW system variable.

The program referenced by _REPORTPREVIEW must do the following:

  • Accept a parameter, passed by reference from the report engine.

  • Assign to the parameter an object reference to an instance of a class which implements the preview container API.

  • Return.

Example:

Copy Code
* Program suitable for _REPORTPREVIEW:
LPARAMETER loRef
loRef = NEWOBJECT("MyPreviewContainer","MyClassLib")
return

The program in _REPORTPREVIEW is invoked when you issue the following types of Visual FoxPro commands:

  • REPORT FORM or LABEL … PREVIEW when SET("REPORTBEHAVIOR") has the value 90.

  • REPORT FORM or LABEL … OBJECT <oRef> when oRef.ListenerType has the value 1 and you have not assigned a value to oRef.PreviewContainer.

  • REPORT FORM or LABEL … OBJECT TYPE 1 when the ReportListener assigned by the listener factory in specified by _REPORTOUTPUT does not already have a value assigned to its PreviewContainer member.

See Also

Reference

REPORT FORM Command
SET REPORTBEHAVIOR Command
_REPORTPREVIEW System Variable

Other Resources

Extending Report Preview Functionality


Creating a Custom Preview Container

Visual FoxPro 9.0
Creating a Custom Preview Container
See Also

Describes how to replace the default preview container with your own custom component that can provide report preview functionality thoughout your application automatically when you SET REPORTBEHAVIOR 90.

Prerequisites

ReportListener Object

The Preview Container API

The simplest preview

The simplest possible preview example does not use the Preview Container API at all, but uses methods of the ReportListener object to demonstrate the essential mechanism behind the API.

The following commands set up a target Shape object, runs a report in object-assisted mode, and uses the methods of the ReportListener object to display the first page of the report on the target shape:

Copy Code
* Set up a target for the preview rendering:
_SCREEN.AddObject("canvas","Shape")
_SCREEN.canvas.Width  = 250
_SCREEN.canvas.Height = 300

* Create a base ReportListener and buffer the entire report:
rl = NEWOBJECT("ReportListener")
rl.ListenerType = 3  && Buffer all pages, do not preview automatically

* Process the report:
REPORT FORM (_SAMPLES+"\solution\reports\colors.frx") OBJECT rl

* Render page 1 to the target:
rl.OutputPage( 1, _SCREEN.canvas, 2 )

After executing these statements in the Command Window, you will see a thumbnail-size image of the report rendered on the surface of the screen.

Things to note:

  • The third parameter passed to the ReportListener's OutputPage() method is 2, which indicates that the target handle passed in the second parameter is a Visual FoxPro object reference - the Shape control.

  • The Shape object did not have to be visible in order for the report to display.

  • Either a Container or a Shape control can be used as the target.

  • Dragging the command window over the preview erases it from the screen, because when the screen receives a paint message, it repaints itself with no knowledge of the preview rendering.

Implementing a simple Preview Container

The next step is to encapsulate the process described above into a class that implements the preview container API, allowing you to re-use the previewing logic.

The following example program, simplepreview.prg, contains a class definition which also uses a Shape object as the render target, this time on a form class that implements the preview container API:

Copy Code
*-----------------------------------------
* simplepreview.prg
*-----------------------------------------
DEFINE CLASS SimplePreview AS Form
    Caption     = "Click for next page"
    ListenerRef = .NULL.
    PageNo      = 1
    AllowOutput = .F.

    ADD OBJECT Canvas AS Shape WITH ;
        Top = 12, Left = 8, ;
        Height = 252, Width = 209, ;
        Name = "Canvas"

    PROCEDURE Canvas.Click
        WITH THISFORM
            IF .PageNo < .ListenerRef.OutputPageCount
                .PageNo = .PageNo + 1
                .Refresh()
            ENDIF
        ENDWITH
    ENDPROC

    PROCEDURE SetReport
        LPARAMETER oListenerRef
        THIS.ListenerRef = oListenerRef
    ENDPROC

    PROCEDURE QueryUnload
        IF NOT ISNULL( THIS.ListenerRef )
            THIS.ListenerRef.OnPreviewClose(.F.)
            THIS.ListenerRef = .NULL.
        ENDIF
        THIS.Hide()
        NODEFAULT
    ENDPROC

    PROCEDURE Paint
        IF NOT ISNULL( THIS.ListenerRef )
            THIS.ListenerRef.OutputPage( THIS.PageNo, THIS.Canvas, 2 )
        ENDIF
    ENDPROC

ENDDEFINE

This class implements the two methods of the preview container API by explicitly defining a SetReport() method; and by being derived from the Form base class, which already has an appropriate Show() method.

Things to note:

  • This class resolves the repainting issues of the previous example by adding code to the form's Paint() event to ensure that the preview image is redrawn when required.

  • The Reportlistener object will call SetReport(), passing a reference to itself when it requires the preview container to perform basic non-report-specific initialization. SetReport() will also be called with null (.NULL.) when its OnPreviewClose() method is invoked.

  • The code in the QueryUnload() event informs the report listener that you have finished viewing the report, and then nulls out the reference to the report listener object to avoid a dead-lock condition that would prevent the form from closing.

  • The code in the Shape.Click() method uses the report listener's OutputPageCount property to ensure that the preview does not request a page that does not exist.

The following code demonstrates how to re-use a preview container component, by instantiating the SimplePreview class and assigning it to the PreviewContainer property of a ReportListener object. Try in the Command Window:

Copy Code
pc = NEWOBJECT("SimplePreview", "simplepreview.prg")
rl = NEWOBJECT("ReportListener")
rl.ListenerType     = 1 && Buffer all pages, use preview container
rl.PreviewContainer = pc
REPORT FORM (_SAMPLES+"\solution\reports\colors.frx") OBJECT rl
REPORT FORM (HOME()+"Tools\Filespec\60frx3.frx") OBJECT rl

After running this code, you will observe that the SimplePreview form is displayed automatically. This is because the report listener object invoked the PreviewContainer.Show() method after the report has completed processing.

If you change the last line of the example above to include the NOWAIT clause, you will observe that the preview form is no longer modal when it is displayed. The report listener object recognizes the NOWAIT clause and invokes Show(0) instead of Show(1).

Hide or Release?

  • In SimplePreview.prg above, the QueryUnload() event suppresses default behavior with NODEFAULT and manually hides the form by calling Hide().

This is for two reasons:

  • There is an outstanding reference to the form held by the report listener PreviewContainer property which means that, without additional code, the form won't close and release when you click the close box. The close box will disable and the form will stay visible.

  • The Hide() allows the preview container to be re-used in successive report previews, as the previous example code shows.

If you do not wish your custom preview container to stay available for further report previews with the report listener, you can modify the QueryUnload method as shown below:

Copy Code
    PROCEDURE QueryUnload
        IF NOT ISNULL( THIS.ListenerRef )
            THIS.ListenerRef.PreviewContainer = .NULL.
            THIS.ListenerRef.OnPreviewClose(.F.)
            THIS.ListenerRef = .NULL.
        ENDIF
    ENDPROC

This alternative implementation results in the preview container being discarded after one report preview. Try the steps above again in the Command Window with the revised preview container class, and you will see that only the first preview uses SimplePreview. The second report run reverts to the default preview container because the ReportListener object detects that it no longer has a reference in its PreviewContainer property and requests a new one via _REPORTPREVIEW.

Scaling and Printing

Scaling

In the previous example, the dimensions of the rendered preview page are dictated solely by the size of the Shape control. If you change the Width of the Shape to be twice its current size, then you will observe that the preview images is similarly distorted.

You can obtain additional information about the report layout from the ReportListener reference in order to scale the page representation appropriately. Add the following method code to the class definition above:

Copy Code
    PROCEDURE Show
        LPARAMETER iMode
        IF NOT ISNULL( THIS.ListenerRef )
            LOCAL nWidthInches, nHeightInches
            nWidthInches  = THIS.ListenerRef.GetPageWidth()/960
            nHeightInches = THIS.ListenerRef.GetPageHeight()/960
            * Assume: Scale by 50% on a 96 DPI screen:
            THIS.Canvas.Height = INT( nHeightInches * 96 * 0.5 )
            THIS.Canvas.Width  = INT( nWidthInches * 96 * 0.5 )
        ENDIF
        DODEFAULT( iMode )
    ENDPROC

This is the appropriate place for this code because the ReportListener instance is guaranteed to invoke the preview container's Show() method at a point where the GetPageHeight() and GetPageWidth() methods will return correct values for the report being previewed. The SetReport() method will be called before accurate information is available.

Printing

You can specify that the report be printed by passing a parameter of .T. to the report listener's OnPreviewClose() method as the form is closed.

Setting as default

You can replace the default preview container used by object-assisted reporting preview in Visual FoxPro by added a few lines to the top of the program containing the SimplePreview class definition:

Copy Code
*-----------------------------------------
* simplepreview.prg
*-----------------------------------------
LPARAMETER loPreviewContainerRef
* parameter is passed by reference
loPreviewContainerRef = CREATEOBJECT("SimplePreview")
RETURN

DEFINE CLASS SimplePreview AS Form
:

This program is now suitable for assigning to _REPORTPREVIEW, specifying the preview container to be returned to Visual FoxPro whenever one is requested by a ReportListener object performing a REPORT… PREVIEW in object-assisted mode.

You can test it out in the Command Window:

Copy Code
_REPORTPREVIEW = "simplepreview.prg"
SET REPORTBEHAVIOR 90
report form (HOME()+"Tools\Filespec\60frx3.frx") preview

Next Steps

See Leveraging the Default Preview Container

See Also

Reference

ReportListener Object
_REPORTOUTPUT System Variable
_REPORTPREVIEW System Variable
OutputPage Method
Container Object
Shape Control


Leveraging the Default Preview Container

Visual FoxPro 9.0
Leveraging the Default Preview Container
See Also

To facilitate the SET REPORTBEHAVIOR 90 setting, Visual FoxPro ships with a default preview container factory application, ReportPreview.App. It is located in the HOME() directory along with the other tools, and is referenced by default in the _REPORTPREVIEW system variable.

This topic describes the capabilities of the Preview Container component delivered by ReportPreview.App, additional to the standard Preview Container API.

Prerequisites

  • The Preview Container API

  • _REPORTPREVIEW System Variable

Object Diagram

The following illustration shows the object diagram of the default preview container as it exists after the report engine has called the Show() method. Prior to that point, the oForm and oForm.Toolbar member objects may not have been instantiated:

Visual FoxPro Preview Object Diagram graphic

A proxy object is used because in order to support numerous clauses of the REPORT FORM… PREVIEW command in object-assisted mode, the preview may instantiate one of a number of specific form classes derived from the parent class frxPreviewForm as its oForm reference:

Class Name | Derived From | Notes
Form | n/a | Visual FoxPro base form class
frxBaseForm | Form | Implements error handling and large font support.
frxPreviewForm | frxBaseForm | Implements the Preview Container API. .ShowWindow = 1 - in top-level form
frxPreviewAsTopForm | frxPreviewForm | .ShowWindow = 2 - As top-level form
frxPreviewInScreen | frxPreviewForm | .ShowWindow = 0 - In Screen
frxPreviewInDesktop | frxPreviewForm | .Desktop = .T.

The properties and methods described below are members of the frxPreviewProxy object.

Additional Properties and Methods

In addition to the standard preview container API, the default component returned by ReportPreview.App exposes other properties and methods that can be used to control the appearance of the Preview window when object-assisted reporting mode is used.

Properties

These properties control the initial state of the preview window only. If set to non-default values, these properties take precedence over any preferences restored from the resource file.

Property Name | Type | Description
Top | I | Specifies the vertical offset from the top of the main Visual FoxPro window of the of the preview form, in pixels.
Left | I | Specifies the left horizontal offset from the left side of the main Visual FoxPro window of the of the preview form, in pixels.
Width | I | Specifies the horizontal size of the preview form in pixels.
Height | I | Specifies the vertical size of the of the preview form, in pixels.
ToolbarIsVisible | L | Specifies that the preview window toolbar should be initially visible.
Caption | C | Specifies the caption of the preview window.
CanvasCount | I | Specifies the initial number of pages rendered on the preview form. Valid values are 1, 2, or 4.
ZoomLevel | I | Specifies the initial zoom level of the preview window. Possible values are: 1 - 10% 2 - 25% 3 -50% 4 - 75% 5 - 100% (default) 6 - 150% 7 - 200% 8 - 300% 9 - 500% 10 - whole page
CurrentPage | I | Specifies the initial page to render on the preview form. The default is 1. If it is greater than the number of pages available the last page will be displayed.
TopForm | L | Specfies whether the preview form should be a standalone top form. This will force a modeless (NOWAIT) preview session, and the toolbar is automatically docked at the top of the form. Default value is false (.F.).
TextOnToolbar | L | Specifies that the toolbar buttons should show text captions. Default value is false (.F.).

Methods

In addition to the methods specified by The Preview Container API , the default preview container also exposes all public methods of the base Form class.

The following additional methods can be called after the preview container is visible:

Method | Description
SetCurrentPage( iPageNo ) | Moves to a specific page number.
SetCanvasCount( iCount ) | Adjusts the number of pages rendered on the preview form.
SetZoomLevel( iLevel ) | Adjusts the scale of the rendered pages.
SetExtensionHandler( oRef ) | Assigns an extension handler (See below)

The Extension Handler Interface

The default preview container has a specific mechanism that allows you to modify or extend the functionality of the preview user interface without subclassing or recompiling the source code.

You use SetExtensionHandler() to pass the default preview container a reference to an object that implements a specific set of "hook" methods that are invoked at specific points. See below for the API and sample usage.

Preview Extension Handler Properties

Property Description

PreviewForm

This is a back-reference to the preview form. If this property does not exist, it will be created by the default preview container via an ADDPROPERTY() call, and assigned a reference to the preview form. The preview container nulls out the back reference automatically before releasing to avoid an object reference loop that might prevent it from doing so.

Useful properties of .PreviewForm:

  • .PreviewForm.oReport references the active report listener

  • .PreviewForm.Toolbar references the preview form's toolbar object.

Preview Extension Handler Methods

These methods must be implemented by a candidate Extension Handler.

Method Description

AddBarsToMenu( cPopupName, iNextBarNum )

This method is called from the preview form's RightClick() event, directly prior to the ACTIVATE POPUP (m.cPopupName) statement, so you can potentially remove menu bars or redefine them.

cPopupName is the name of the popup.

iNextBarNum is the next available bar number.

Because you cannot use the THIS keyword in a popup ON SELECTION.. command, the preview form makes a reference to itself available in a variable oRef.

HandledKeyPress( nKey, nModifier )

This method is called from the preview form's Keypress() event. Return true (.T.) if you wish to replace the default response to a specific key press. This method is called before the preview form's native keypress handling, so you may override selected keypress events.

Show( iStyle )

This method is called from the preview form's Show() method. You will be able to manipulate the preview toolbar through the THIS.PreviewForm.Toolbar reference. The toolbar actually gets created in the preview form's Init() event but as the extension handled has not been assigned at that point, the Show() is the best place for configuration and decoration code.

Note that the toolbar itself also has a PreviewForm back-reference to the preview form, so you could add command buttons with Click() code like THIS.Parent.PreviewForm.ExtensionHandler.MyCustomMethod().

Paint()

Called from the preview form's Paint() event, after the preview has finished rendering the pages.

Release()

Called from the preview form's Release() event. Returning false (.F.) from this method will prevent the preview form from closing.

Example: Customizing the preview container using an Extension Handler

The following example customizes the appearance of the preview window and also implements an extension handler that removes the ability to change the number of pages rendered simultaneously on the preview form.

Copy Code
* Obtain an instance of the default preview container:
pc = .NULL.
DO (_REPORTPREVIEW) WITH pc

* Set some initial properties:
WITH pc
    .Caption = "My Custom Preview Window"
    .ZoomLevel = 4   && 75%
    .CanvasCount = 1
ENDWITH

* Create an instance of an Extension Handler:
xh = NEWOBJECT("MyRetroPreview")

* Assign it to the preview container:
pc.SetExtensionHandler( m.xh )

* Set up a report listener and give it our preview:
rl = NEWOBJECT("Reportlistener")
rl.ListenerType = 1
rl.PreviewContainer = pc

* Run a report:
REPORT FORM (_SAMPLES+"\solution\reports\colors.frx") OBJECT rl
RETURN

*---------------------------------------------
* Extension Handler Class:
*---------------------------------------------
DEFINE CLASS MyRetroPreview AS Custom

    PROCEDURE AddBarsToMenu( cPopup, iNextBar )
        * Remove the option to change page count:
        RELEASE BAR 8 OF (m.cPopup)
    ENDPROC

    PROCEDURE Show( iStyle )
        * Remove the option to change page count:
        THIS.PreviewForm.Toolbar.opgPageCount.Visible = .F.
        THIS.PreviewForm.CanvasCount = 1
    ENDPROC

    PROCEDURE HandledKeyPress( nKeyCode, nShiftAltCtrl )
        RETURN .F.
    ENDPROC

    PROCEDURE Paint()
    ENDPROC

    PROCEDURE Release()
        RETURN .T.
    ENDPROC

ENDDEFINE

Use of the Resource File

The default preview container uses the current resource file (as returned by SET("RESOURCE",1) ) to remember the size, position, number of pages visible, zoom level, etc., for each report file.

The window and toolbar preferences are stored in the FOXUSER table with an ID of "9REPPREVIEW". Window and Toolbar position and size preferences are saved independently for each individual report file. The position and state of the preview toolbar is common to all report previews. If the resource file is not available, or read-only, then the window preferences are not saved.

See Also

Tasks

Creating a Custom Preview Container

Reference

SET REPORTBEHAVIOR Command
ReportListener Object

Concepts

Understanding Visual FoxPro Object-Assisted Reporting


How to: Specify and Distribute ReportPreview.App

Visual FoxPro 9.0
How to: Specify and Distribute ReportPreview.App
See Also

When you write and distribute Visual FoxPro applications, you will probably want to allow your users to preview reports on screen. If you wish to leverage the new object-assisted report engine to preview reports in your application, then you must choose whether to:

  • Write your own custom preview container, as described in Creating a Custom Preview Container.

  • Distribute ReportPreview.App with your application.

In this topic, you will learn how to redistribute the ReportPreview.App, the default Preview Container factory application, in two ways:

  • A separate App file alongside your own application.

  • An integrated source directly into your own application.

Redistributing ReportPreview.App with Your Application

By default, if ReportPreview.App exists in the same directory as the Visual FoxPro run time files, then _REPORTPREVIEW will contain the fully-qualified path and file name. One solution is to ensure that the setup program used to distribute your application places ReportPreview.App in the same directory as the run time files. Alternatively, you can distribute ReportPreview.App in the same directory as your application, providing you explicitly set _REPORTPREVIEW to that copy of the file.

To distribute ReportPreview.App with your application

  1. In the main program of your application, use code similar to the following:

    Copy Code
    * Get the application's home directory:
cHomeDir = CURDIR()  && use whatever method you prefer
* Set the system variable to use the fully-qualified path:
_REPORTPREVIEW = m.cHomeDir+"ReportPreview.App"
:

You could also use a line in CONFIG.FPW:

_REPORTPREVIEW=<path>\ReportPreview.App

Integrating the Preview Container Factory Source into Your Project

Instead of distributing the compiled application, you may choose to incorporate the source code of the report preview factory directly into your application's project.

To integrate the preview container factory source into your application

  1. Unpack the xsource.zip file found in the Tools\xsource\ folder under the Visual FoxPro home directory.

  2. In the main program of your application, use code similar to the following:

    Copy Code
    * Ensure the report builder source is pulled into the project:
EXTERNAL PROCEDURE frxpreview.prg
* Set the system variable to use the local source version:
_REPORTPREVIEW = "frxpreview.prg"
:

  3. Rebuild your project.

    The preview factory source code files will be added to your project and compiled in to your application.

Shared Source Files

ReportBuilder.App and ReportPreview.App have the following source files in common:

  • frxControls.vcx

  • frxCommon.prg

  • grabber.gif

  • wwrite.ico

  • foxpro_reporting.h

The Project Manager builds only one copy of each of these files into your application's project, depending on the order of the EXTERNAL statements in your main program.

See Also

Tasks

How to: Specify and Distribute Report Output Application Components
How to: Specify and Distribute ReportBuilder.App

Reference

_REPORTPREVIEW System Variable
Including Report Files for Distribution

Concepts

Application Distribution Process


Extending Report Output Functionality

Visual FoxPro 9.0
Extending Report Output Functionality

In Visual FoxPro 9's Report System, Report Output Application provides instances of ReportListener-derived classes for use in object-assisted report runs. The topics in this section discuss the default Report Output Application and related features.

In This Section

Report Output Application

Discusses how to leverage the features of the default Report Output Application and how to customize it for your applications.
Using VFP Report Output XML

Specifies the base Visual FoxPro Reporting XML schema and its many optional elements. You can use the default Report Output Application to generate VFP Report Output XML. In your application or in external tools, the XML can provide many additional forms of output results.
Considerations for Creating New Report Output Types

Lists some design criteria for developing new output-generating components to be registered with Report Output Application.

Related Sections

Understanding Visual FoxPro Object-Assisted Reporting

Extending Report Preview Functionality

Distributing Reports with Applications

_REPORTOUTPUT System Variable

SET REPORTBEHAVIOR Command


Report Output Application

Visual FoxPro 9.0
Report Output Application

The Report Output Application provides ReportListener object references to the Visual FoxPro Report System at run time. You designate an application or program for this purpose by supplying its filename in the _REPORTOUTPUT system variable. The ReportOutput.app file, located in the main Visual FoxPro directory, provides Visual FoxPro 9's default implementation of the Report Output Application.

The requirements a Report Output Application must fulfill are simple. For a full listing of these requirements, and for further recommendations, see _REPORTOUTPUT System Variable.

ReportOutput.app fulfills this responsibility and showcases Visual FoxPro's ability to provide enhanced output, in the following ways:

  • Managing a cache of Listener object references.

  • Providing new output results, by supplying references to ReportListener XML Foundation Class and ReportListener HTML Foundation Class. For more information, see ReportListener Foundation Classes.

  • Providing enhanced run-time feedback for “traditional” print and preview output types, by supplying references to ReportListener User Feedback Foundation Class.

  • Managing a registry of output types for user-added extensions and new output results.

This section covers the features of the default Report Output Application (ReportOutput.app).

In This Section

Understanding the Report Output Application

Discusses the features of the default Report Output Application.
How to: Specify an Alternate Report Output Registry Table

Describes how to create the Report Output Application's registry table and how to indicate the registry table you want the Report Output Application to use.
How to: Register Custom ReportListeners and Custom OutputTypes in the Report Output Registry Table

Describes how to add your own entries to the Report Output Application's registry table.
How to: Use the Report Output Application's Reference Collection

Describes how to use the Report Output Application's collection of references to ReportListener objects.
How to: Specify and Distribute Report Output Application Components

Provides instructions for distributing the Report Output Application's registry table and other components with your applications.

Related Sections

_REPORTOUTPUT System Variable

Understanding Visual FoxPro Object-Assisted Reporting

Considerations for Creating New Report Output Types


Understanding the Report Output Application

Visual FoxPro 9.0
Understanding the Report Output Application
See Also

The default Report Output Application (ReportOutput.app) fulfills the standard responsibilities of an application designated in the _REPORTOUTPUT variable.

  • It accepts two parameters, expecting a numeric value as the first parameter.

  • It stores an object reference to an instance of a ReportListener-derived class to the variable it received as the second parameter.

  • The class for which it supplies an instance is determined by the value in the first parameter.

  • If successful in obtaining an object reference to an appropriate class, it assigns the value of the first parameter to the object's OutputType property.

Note:
For full information on the requirements for a Report Output Application, refer to _REPORTOUTPUT System Variable.

This topic covers details of the default Report Output Application's implementation of these requirements. It also describes some additional functionality supplied by the default Report Output Application.

ReportOutput.app ReportListener Reference Collection

You can explicitly assign a ReportListener object reference to a variable, if you call the Report Output Application using the following syntax:

Copy Code
LOCAL loRef
do (_REPORTOUTPUT) with <N>, loRef
IF ISNULL(loRef)
   * the Report Output Application did
   * not recognize the value <N>
ELSE
   ? loref.outputtype
   ? loref.class
ENDIF

However, in many cases, ReportOutput.app provides a ReportListener object reference without your explicitly assigning the reference to a variable. This situation occurs if you have set the value of SET REPORTBEHAVIOR to 90, or if you use the OBJECT TYPE<N> clause on your REPORT FORM or LABEL command.

ReportOutput.app maintains a public variable, _oReportOutput, derived from the Collection class. It stores references to the ReportListener-derived objects, for which it has provided references, in this collection. The collection scopes ReportListener references globally, so that they can be successfully re-used for multiple reports, regardless of how or where you ask for the reference.

Providing consistent ReportListener scope, using ReportOutput.app's reference collection or a similar strategy, is required to support chaining multiple reports in one output result. The reference collection also provides a convenient mechanism for retrieval of these object references, before and after the report run.

You can retrieve the object reference from the collection by using the string value of the appropriate OutputType as the collection key:

Copy Code
#DEFINE PRINT_MODE 0
REPORT FORM ? OBJECT TYPE PRINT_MODE
LOCAL loRef
loRef = _oReportOutput[TRANSFORM(PRINT_MODE)]
? loRef.OutputType  && will be 0
? loRef.PageTotal && will be the total of pages
                  && from the last print run

For more information, see How to: Use the Report Output Application's Reference Collection.

Important
ReportOutput.app reserves the right to use additional key values in this collection for other uses besides ReportListener object references. For example, if you designate a custom Report Output registry table, it stores the name of this table in the reference collection. For more information, see How to: Specify an Alternate Report Output Registry Table.

ReportOutput.app Extended Parameters

ReportOutput.app extends the use of the two required _REPORTOUTPUT parameters, provides default behavior if the second parameter is not included, and adds an optional third parameter. The following represents appropriate syntax for ReportOutput.app

Copy Code
DO ReportOutput.app WITH ;
   nListenerType [,eListenerReference [,eUnload]]

This section describes ReportOutput.app's treatment of each parameter.

First Parameter: nListenerType

When evaluating its nListenerType parameter, ReportOutput.App accepts all numbers greater than or equal to -1, the default value of ReportListener's ListenerType property, as instructions to provide a ReportListener reference of appropriate type.

Note:
If nListenerType is a number but is not an integer value, ReportOutput.app accepts the value but uses the integer portion of the received value as the type requested.

If nListenerType is -1, it provides a reference to an object instanced from the ReportListener baseclass. If it is greater than -1, ReportOutput.app begins an evaluation process to determine what ReportListener-derived class should provide the reference, as follows:

  • ReportOutput.app first checks to see if it has a cached reference to an object previously provided for this value. If it finds one, it re-uses this reference.

  • If no cached reference is available, ReportOutput.app checks its registry table for any user instructions that match this value. The registry table is described in a later section of this topic.

  • If there are no user instructions available, it uses built-in defaults listed in the following table.

nListenerType value | Default class providing ReportListener reference
0 | ReportListener User Feedback Foundation Class
1 | ReportListener User Feedback Foundation Class
2 | ReportListener Baseclass
3 | ReportListener Baseclass
4 | ReportListener XML Foundation Class
5 | ReportListener HTML Foundation Class
999 | ReportListener Debug Foundation Class
Note:
In the table, notice that a single ReportListener class may handle multiple nListenerType values. ReportOutput.app assigns the nListenerType value it receives to the object's OutputType property. This property value assignment is part of the specified requirements for any Report Output Application. If the object is an instance of a ReportListener-derived class, ReportOutput.app expects the object to decide whether to re-assign its own ListenerType property based on OutputType, or maintain the values separately. If the object is an instance of the ReportListener baseclass, ReportOutput.app also assigns the nListenerType value to the object's ListenerType property. For more information, see OutputType Property (Visual FoxPro) and ListenerType Property.

ReportOutput.app reserves all nListenerType values less than -1 to expose additional functionality beyond its specified responsibility to provide ReportListener references. Two such values, -100 and -200, are covered in a later section of this topic.

Second Parameter: eListenerReference

ReportOutput.app treats its second parameter, eListenerReference as optional. If it is not received, ReportOutput.app simply caches a reference to an instance of the appropriate ReportListener class in its reference collection. This behavior gives you the opportunity to set up various ReportListener references before you need them for reporting.

If it receives its eListenerReference parameter, ReportOutput.app accepts either a declared variable, as shown in the example in the last section, or as a string representing the variable. If you provide a string to represent the variable, and if the variable represented by the string does not already exist, ReportOutput.app initializes the variable as PUBLIC.

You can also use a string to ReportOutput.app in the eListenerReference parameter if you want to assign a ReportListener to an object member. For example:

Copy Code
#DEFINE PREVIEW_MODE 1
Ox = CREATEOBJECT("custom")
Ox.addProperty("myReportListener")
DO (_REPORTOUTPUT) WITH PREVIEW_MODE, "ox.myReportListener"
REPORT FORM ? OBJECT ox.MyReportListener
? ox.myReportListener.Name

If the object member does not exist but ReportOutput.app can verify that the object exists, the member is created. It is capable of drilling down into object containership hierarchies for this purpose. For example:

Copy Code
#DEFINE PREVIEW_MODE 1
Ox = CREATEOBJECT("form")
Ox.addobject("myChildObject","custom")
DO (_REPORTOUTPUT) WITH PREVIEW_MODE, "ox.myChildObject.RL"
REPORT FORM ? OBJECT ox.myChildObject.RL
? ox.myChildObject.RL.PageTotal

Third Parameter: eUnload

You can release a ReportListener reference from ReportOutput.app's reference collection explicitly, as follows:

Copy Code
#DEFINE PRINT_MODE 0
_oReportOutput.Remove[TRANSFORM(PRINT_MODE))

However, ReportOutput.app provides a third parameter so you can ask the application to manage this reference for you, without addressing the collection directly. The parameter allows you to explicitly release the reference or to release and immediately receive a new instance, as shown in the following example.

Copy Code
#DEFINE PRINT_MODE 0
#DEFINE OUTPUTAPP_LOADTYPE_RELOAD 2
   DO (_reportoutput) WITH ;
      PRINT_MODE , ox, OUTPUTAPP_LOADTYPE_RELOAD

The following are the recognized values for the eUnload parameter.

eUnload Parameter Value | Usage
Not passed, logical False (.F.), or passed but not logical or numeric type. | Ignored. ReportOutput.app provides standard behavior: it loads a ReportListener or performs other activity as determined by nListenerType value.
Logical True (.T.) or numeric value 1. | ReportOutput.app does not provide a ReportListener object reference. It checks for a ReportListener object using a key determined by nListenerType, and removes this ReportListener from its collection if found.
All numeric values greater than 1. | ReportOutput.app removes a reference for a ReportListener object from its collection, if found, and then re-loads the appropriate reference. It stores this reference to the variable indicated in the eListenerReference parameter.

ReportOutput.app ReportListener Registry Table

ReportOutput.app provides default ReportListener object references according to the table listing nListenerType values and class names in the previous section. You can use a registry table to override these settings.

ReportOutput.app leverages the same configuration or registry table structure as the ReportListener Foundation Classes use to store their configuration information. The following code shows you the base structure of this table. You can add fields to this table of any type, and the order of the fields is not significant to Report Output Application components or the Foundation Classes.

Copy Code
CREATE TABLE (CONFIG_TABLE_NAME) ;
   (objtype i, ;
    objcode i, ;
    objname v(60), ;
    objvalue v(60), ;
    objinfo m)

Both ReportOutput.app and the ReportListener Foundation Classes provide facilities to create the table for you. For more information on creating the table and designating it as your Report Output Application registry table, see How to: Specify an Alternate Report Output Registry Table.

Note:
ReportOutput.app and the ReportListener Foundation Classes use this table structure differently, and require different indexes. However, it does not matter which component creates the table, or if you create it as a blank table, as shown in the sample code above. Each component will create any records and indexes it needs, if pointed to that table.

ReportOutput.app reserves the range 100-999 for Objtype field values in the configuration table. It uses an Objtype field value of 100 to represent ReportListener class registry records. The following table shows you ReportOutput.app's use of records in the table for ReportListener registry purposes.

Field | Usage | Remarks
OBJTYPE | 100 | A value of 100 in this field identifies a ReportListener registry record.
OBJCODE | nListenerType | The values in this field are matched against the first parameter you supply to ReportOutput.app.
OBJNAME | Class to instantiate | This class name may be ReportListener (the base class).
OBJVALUE | Class library (.vcx) or procedure file (.prg) holding the class definition. | This value may be blank, if the class name is ReportListener.
OBJINFO | Module/Application containing library. | This value may be blank, if the class library or procedure file is bound into your application.

ReportOutput.app specifies an Objtype field value of 110 to store other configuration information for its own use. It uses records with an Objtype value of 110 and an Objcode value of 1 for filtering the ReportListener registry records based on user-specified criteria. Records with an Objtype value of 110 and any other Objcode values are reserved for other configuration uses by ReportOutput.app, but are not currently used.

The following table describes ReportOutput.app's usage of registry table fields for filter records.

Field Usage Remarks

OBJTYPE

110

A value of 110 in this field identifies a ReportOutput.app configuration record.

OBJCODE

1

A value of 1 in this field, for records with an Objtype value of 110, is a filter record.

OBJNAME

not used

Filter records ignore this field.

OBJVALUE

not used

Filter records ignore this field.

OBJINFO

Filter expression

The expression you put in this field is included in a LOCATE expression when searching the registry table for an appropriate class to provide for a given nListenerType value. The LOCATE command is constructed as follows:

Copy Code
#DEFINE OUTPUTAPP_OBJTYPE_LISTENER    100
   LOCATE FOR ObjType = ;
   OUTPUTAPP_OBJTYPE_LISTENER AND ;
   (ObjCode = iType)  ;
   &cFilter ;
   AND (NOT DELETED())

For more information, see How to: Register Custom ReportListeners and Custom OutputTypes in the Report Output Registry Table.

ReportOutput.app Return Values

A Report Output Application must be modal, because it is required to return a value to Visual FoxPro's Report Engine as part of the Engine's processing of a REPORT FORM or LABEL command. Visual FoxPro receives this return value using the parameter eListenerReference, which is passed by reference; the native engine does not recognize a return value from ReportOutput.app.

However, ReportOutput.app does provide a return value if you call it as a function, representing success or failure in the task indicated by your nListenerType parameter:

Copy Code
? ReportOutput(5, "oRL")
* returns .T.
DISPLAY MEMO LIKE oRL
* Shows that the call above
* declares the variable oRL PUBLIC if
* it is not already in scope,
* because it was passed as a string
* stores a reference to the HTMLListener
* Foundation class in this variable.
? ReportOutput(25,"oRlx")
* returns .F.
DISPLAY MEMO LIKE oRLx
* Shows that the call above does
* not declare the variable oRLx

ReportOutput.app Compile-time Adjustments

ReportOutput.app's source code is available in a zip file in the XSource folder in your Visual FoxPro \Tools directory. For more information, see XSource Folder.

You can include the source code for ReportOutput.app in your applications. For more information, see Including Report Files for Distribution. When you follow this practice, you can edit the Report Output defined constants, found in the ReportOutput.h header file, to tune your application's reporting behavior.

The table below provides a sample of the kinds of items available in the header file for adjustment.

#DEFINEd constant | Default value | Edit this setting to change:
OUTPUTAPP_INTERNALDBF | "_ReportOutputConfig" | Name of built-in registry table.
OUTPUTAPP_EXTERNALDBF | "OutputConfig" | Default name of registry table on disk.
OUTPUTAPP_REFVAR | _oReportOutput | Name of public variable for the reference collection.
OUTPUTAPP_BASELISTENER_CLASSLIB | "Listener.VCX" | Class library holding default ReportListener classes.
OUTPUTAPP_CLASS_PRINTLISTENER | "UpdateListener" | Class name used by default to handle eListenerType value 0 (print).

See Also

Concepts

Considerations for Creating New Report Output Types

Other Resources

ReportListener Foundation Classes


How to: Specify an Alternate Report Output Registry Table

Visual FoxPro 9.0
How to: Specify an Alternate Report Output Registry Table

The default Report Output Application supports a registry table in which you can specify the ReportListener-derived classes for different types of output results. This topic describes mechanisms available to:

  • Create a new registry table.

  • Tell the Report Output Application to use this table at run time.

  • Find out what registry table the Report Output Application is currently using.

Note:
Some of the code in this topic uses the _REPORTOUTPUT System variable to invoke ReportOutput.app. _REPORTOUTPUT may contain the name of a different Report Output Application in your environment. In this case, substitute HOME() + ReportOutput.app, or similar code, to invoke the default Report Output Application. Where the instructions designate the name and position of a custom registry table, substitute your preferred name and location.

For more information about using the registry table with your own classes and output extensions, see How to: Register Custom ReportListeners and Custom OutputTypes in the Report Output Registry Table.

For more information about the format of the registry table, see Understanding the Report Output Application.

Creating a Report Output Registry Table

You can use either ReportOutput.app or a ReportListener Foundation Class to create the table, because they use the same configuration table format.

Note:
These two methods may generate different sample and configuration records in the table, and they can potentially include different sets of indexes. If you share a registry table between different reporting components, each component using the table verifies the contents of the table against its own requirements. If necessary, each component is capable of adding its own records and indexes on-the-fly.

To create a new Report Output registry table using ReportOutput.app

  1. In the Command Window or in a program (.prg), use the following line of code:

    Copy Code
    * #DEFINE OUTPUTAPP_CONFIG_WRITE -100
DO (_REPORTOUTPUT) WITH -100

  2. The Report Output Application creates a table named OutputConfig.DBF, and associated memo (.fpt) and structure index (.cdx) files, in the same location as ReportOutput.App (normally, Visual FoxPro's main or HOME() directory).

  3. The Report Output Application presents a BROWSE of this new table, so you can check the contents. The contents will include the records required by the ReportListener XML Foundation Class, plus some deleted records which serve as examples of different types of registry records

  4. You see a deleted record for debugListener, the ReportListener Debug Foundation Class. This record shows you what a ReportListener registry record looks like, according to the requirements of the Report Output Application.

  5. You also see deleted records for two records with ObjType values of 1000. This value is in the range reserved for use by utilityReportListener, the ReportListener Utility and File-handling Foundation Class. One record shows you how to create a configuration record to set a class property and the other shows you how to create a configuration record to invoke a class method. For more information about how this class and its descendents use configuration records, see ReportListener Utility and File-handling Foundation Class.

  6. You can rename the three OutputConfig.* files and place them somewhere else on your disk for later use.

To create a new Report Output registry table using a ReportListener Foundation class

  1. Create an instance of the ReportListener Utility and File-handling Foundation Class, or any of the ReportListener Foundation Classes derived from it. You can create an instance of this class using the class library (vcx) built into ReportOutput.app, or you can create an instance of the class using the copy of the class library available in Visual FoxPro's FFC folder.

    Copy Code
    * "borrow" a copy directly from ReportOutput.App:
#DEFINE CONFIG_REPORTLISTENER_CLASS "utilityReportListener"
oRL = NEWOBJECT(CONFIG_REPORTLISTENER_CLASS, ;
                "listener.vcx", ;
                _REPORTOUTPUT)
* - OR -
* access the Foundation Class library directly:
#DEFINE FFC_HOME HOME()+"FFC\"
oRL = NEWOBJECT(CONFIG_REPORTLISTENER_CLASS, ;
                FFC_HOME + "_reportListener.vcx")
    Tip:
    All the ReportListener Foundation Classes providing file-based output, such as the ReportListener HTML Foundation Class, derive from ReportListener Utility and File-handling Foundation Class. Some of these classes require a registry table. Any class that requires a table checks for the availability of the table when you initialize it. If the table is not available, it creates a copy of the table, in its default location, during initialization procedures. For more information, see ReportListener Utility and File-handling Foundation Class.

  2. Request a new configuration table from the ReportListener instance. You can specify its name and location:

    Copy Code
    * if SAFETY is ON, prompt for overwrite if the file exists:
oRL.createConfigTable("c:\temp\myconfig.dbf")
*- OR -
* use the second parameter to explicitly overwrite:
oRL.createConfigTable("c:\temp\myconfig.dbf", .T.)
    Tip:
    The classes respect the setting of SAFETY in your environment, in that they will prompt you to confirm an overwrite of the table if SET SAFETY is ON and if you do not specify the second parameter of the createConfigTable method as True (.T.). For more information, see SET SAFETY Command. If you decline to overwrite the table when prompted, the classes still take some actions; they investigate the table to ensure that required indexes are available and add any records they need to the table.

Assigning your own Registry Table to the Report Output Application

In the last section, you saw that, to create a registry table, you can invoke ReportOutput.app using a negative number (-100) as the first parameter you send to the program. ReportOutput.app understands negative values in this parameter as special instructions to perform maintenance chores, rather than instructions to perform its normal task of supplying ReportListener references.

ReportOutput.app reserves a second value, -200, to allow you to designate the name and location of your registry table, as shown below.

To designate your custom registry table for ReportOutput.app's use

  1. Execute the following line of code, substituting the name and path of your custom registry table:

    Copy Code
    * #DEFINE OUTPUTAPP_CONFIG_READ -200
DO (_REPORTOUTPUT) WITH -200,"c:\temp\myconfig.dbf"

Verifying the Report Output Application's current Registry Table

At run time, ReportOutput.app maintains a reference collection of ReportListener object references. For more information, see How to: Use the Report Output Application's Reference Collection. ReportOutput.app uses a special member of this collection to hold the name of its registry table. You can use the reference collection to find out what registry table is currently in use by the Report Output Application. You can also verify the name of the current registry table by calling Report Output Application directly.

To verify the name of the current Report Output Application registry table using the reference collection

  1. If you have issued a CLEAR ALL statement or RELEASEd the reference collection public variable after the last time you successfully invoked the Report Output Application, or if you have not yet invoked it in this session of Visual FoxPro, the collection may not yet exist. Verify that the collection exists and then check the value of the appropriate collection member

    Copy Code
    #DEFINE OUTPUTAPP_CONFIG_READ -200
IF VARTYPE(_oReportOutput) = "O"
  lcFile = _oReportOutput[TRANSFORM(OUTPUTAPP_CONFIG_READ)]
ENDIF

  2. Examine the results you received in the variable lcFile. If it is a fully-qualified (pathed) filename, the Report Output Application is using a registry table on disk. If lcfile does not include a path, Report Output Application is using a registry table built into an application (.app or .exe).

To verify the name of the current Report Output Application registry table by calling Report Output Application

  1. Initialize a variable to hold the name of the registry file

    Copy Code
    LOCAL lcFile

  2. Call the Report Output Application with the special configuration value you used earlier, using the variable you initialized as its second parameter. This is similar to how you call the Report Output Application to receive a reference to a ReportListener:

    Copy Code
    #DEFINE OUTPUTAPP_CONFIG_READ -200
DO (_REPORTOUTPUT) WITH OUTPUTAPP_CONFIG_READ, lcFile

  3. Examine the results you received in the variable lcFile. If it is a fully-qualified (pathed) filename, the Report Output Application is using a registry table on disk. If lcfile does not include a path, Report Output Application is using a registry table built into an application (.app or .exe).

    Note:
    The reference collection is created automatically when you use this syntax.


How to: Register Custom ReportListeners and Custom OutputTypes in the Report Output Registry Table

Visual FoxPro 9.0
How to: Register Custom ReportListeners and Custom OutputTypes in the Report Output Registry Table

When it looks for a registered ReportListener, ReportOutput.app checks the records in its registry table with the value of 100 in the Objtype field and a value in the ObjCode field matching the first parameter it received. It ignores deleted records in the table, and uses registry records with a value of 110 in the ObjType field to apply additional filters limiting the records to be considered.

When it has identified the correct record, ReportOutput.app uses the other fields in the record to instantiate a reference to your designated ReportListener-derived class.

In this topic you learn how to create records in the registry table so ReportOutput.app can use them in this process.

Note:
For more information about registry table structure and use, see Understanding the Report Output Application. For information about creating and specifying a registry table, see How to: Specify an Alternate Report Output Registry Table.

To add a new OBJECT TYPE value to the registry table

  1. Issue the following command to create ReportOutput.app's default registry table on disk:

    Copy Code
    DO (_REPORTOUTPUT) WITH -100  && Write registry file
    Note:
    If the system variable _REPORTOUTPUT contains the name of a Report Output Application other than the default ReportOutput.app in your environment, substitute HOME() + ReportOutput.app, or similar code, to invoke the default Report Output Application.

  2. A BROWSE window appears with registry records for different components using this table.

  3. Examine the current record in the table. This record is a deleted entry showing you how to create a registry record for new ReportListener entries. Notice that its Objtype value is 100, indicating that it provides ReportListener-derived class information, and that its Objcode value is 999, meaning that ReportOutput.app should use this record when asked for a ReportListener of type 999. Also, observe the name of the class in the Objname field (DebugListener).

  4. From the Table menu popup, choose the Recall Records… option. On the dialog that appears, click the Recall button. The DebugListener record is now active.

  5. Change the Objcode value to a different number, such as 55.

  6. Close the BROWSE window.

  7. Issue the following command:

    Copy Code
    REPORT FORM ? OBJECT TYPE 55
* substitute the number you used in the table if it was not 55

  8. The REPORT FORM command generates debugging output.

  9. Save the name of the current registry table for later use, using the following command. For more information, see How to: Use the Report Output Application's Reference Collection.

    Copy Code
    lcOutputRegistry = _oReportOutput["-200"] && current registry

To add a new class definition to the registry table

  1. Open the registry table you created earlier, and open a BROWSE window.

    Copy Code
    USE (lcOutputRegistry) SHARED ALIAS MyRegistry
BROWSE

  2. From the Table menu popup, choose Append New Record. The new record appears at the bottom of the Browse window.

  3. Change the new record's Objtype value to 100, indicating its use. Change its Objcode value to a different value from the one you used earlier, for example 77.

  4. In the Objname field, use the name of a different ReportListener-derived class. For example, you could use "XMLDisplayListener", a class delivered in the Foundation Class (FFC) folder.

  5. In the Objvalue field, use the name of the class's class library. The file extension is optional if the class library is a visual class library (.vcx) but required if the class library is a program (.prg). If you used "XMLDisplayListener" above, you should use "_ReportListener" here.

    Note:
    For this example, you can use the full path of the library in this field, or you can SET PATH TO (HOME() + "FFC") when you are ready to invoke ReportOutput.app. However, when you distribute applications, you can build _ReportListener.VCX into your application file and it will be found without a path.

  6. Leave the Objinfo field blank unless the class library you used in the last step is built into an application (.app or .exe) outside your own code. For example, in the DebugListener record, the Objinfo name holds the fully-pathed name of the Report Output Application, because the Objvalue field holds the name of the library built into ReportOutput.app. If you used "_ReportListener" or "_ReportListener.vcx" from the FFC folder in Objvalue, this value should be blank.

  7. Close the registry table. (Although you opened it SHARED, in certain cases ReportOutput.app will require exclusive use of the table.) From the Command window:

    Copy Code
    USE IN MyRegistry

  8. Ensure that the class library you specified is available on your path, if you did not use its full path in the Objvalue field ealier. Then use your designated class with ReportOutput.app:

    Copy Code
    REPORT FORM ? OBJECT TYPE 77

  9. The REPORT FORM command generates output using the class you specified.

To filter records in the registry table

  1. Open the registry table you created earlier, and open a BROWSE window.

    Copy Code
    USE (lcOutputRegistry) SHARED ALIAS MyRegistry
BROWSE

  2. Change the Objcode value for the class you specified in the last section to match the value you used for DebugListener earlier. For example:

    Copy Code
    GO BOTTOM
REPLACE Objcode WITH 55
    Note:
    You now have two classes registered with the same Output type value (55). By default, ReportOutput.app will use the first one it finds (in this case, DebugListener).. In this procedure, you use a filter to take control of which record ReportOutput.app uses.

  3. From the Table menu popup, choose Append New Record. The new record appears at the bottom of the Browse window.

  4. Change the new record's Objtype value to 110, the value specific to Report Output Application configuration records, and its Objcode value to 1, the value specific to filter records.

  5. Filter records do not use the Objname and Objvalue fields. Use the following expression in the Objinfo field. This expression indicates that you do not want to use any classes built in to the ReportOutput.app file, you only want to use external classes:

    Copy Code
    ATC("ReportOutput.APP",Objinfo) = 0

  6. Close the registry table.

  7. Ask the Report Output Application for a reference to ReportListener using this type. The third parameter below ensures that any cached reference of this type from earlier attempts will be released and you will get a new evaluation of the appropriate class:

    Copy Code
    oRL = NULL
DO (_REPORTOUTPUT) WITH 55, oRL, 2 && reload

  8. Verify that the class reference is the second class you added to the table (in the example, XMLDisplayListener):

    Copy Code
    ? oRL.Class

  9. Open the registry table again, and change the Objcode value or make some other change so the record no longer qualifies as a filter:

    Copy Code
    USE (lcOutputRegistry) SHARED ALIAS MyRegistry
GO BOTTOM
REPLACE Objcode WITH 2
USE && close the table again

  10. Issue the same commands you used earlier, and observe that you receive a reference to DebugListener this time:

    Copy Code
    DO (_REPORTOUTPUT) WITH 55, oRL, 2 && reload
? oRL.Class
    Tip:
    Filters can be based on values in additional registry table fields, because user-defined fields are permitted in the table. For example, you could have a logical field named CustPref, and filter on the value CustPref, signifying which class your application's end-user prefers to use. To work as a filter, an expression has to be something appropriate to a LOCATE statement applied to the registry table. The Report Output Application uses the filter in a LOCATE statement when it searches the registry table for a record for a ReportListener of appropriate output type. For more information about how the Report Output Application uses the Objinfo field to apply a filter, and about how it uses the rest of the registry table columns, see Understanding the Report Output Application.


How to: Use the Report Output Application's Reference Collection

Visual FoxPro 9.0
How to: Use the Report Output Application's Reference Collection
See Also

At run time, the default Report Output Application (ReportOutput.app) maintains a reference collection of ReportListener object references. ReportOutput.app scopes the collection globally, by declaring the reference variable with the PUBLIC keyword. The collection allows the Report Engine to use a single ReportListener-derived object on multiple REPORT FORM or LABEL commands. For more information, see Understanding the Report Output Application.

You can use this collection to set properties on ReportListener object instances before REPORT FORM and LABEL commands, or to check the results of a report run afterwards, without assigning a variable to hold the reference explicitly.

ReportOutput.app uses a consistent collection key-naming scheme so you can easily find the appropriate reference.

Note:
Some of the code in this topic uses the _REPORTOUTPUT System variable to invoke ReportOutput.app. _REPORTOUTPUT may contain the name of a different Report Output Application in your environment. In this case, substitute HOME() + ReportOutput.app, or similar code, to invoke the default Report Output Application. Where the instructions designate the name and position of a custom registry table, substitute your preferred name and location.

Initializing the Reference Collection and Creating Reference Collection members

To create a Reference Collection member

  1. You can create a Reference Collection member while running a report, and without using an explicit variable reference. Issue the following command, where <N> is the type of output you want from the REPORT FORM command. For example, use the value 1 as <N> to preview the report.

    Copy Code
    REPORT FORM ? OBJECT TYPE <N>

  2. You can also create a Reference Collection member without running a report. Issue the following command, where <N> is a type of output you want for subsequent REPORT FORM commands. For example, use the value 0 as <N> to print the report:

    Copy Code
    DO (_REPORTOUTPUT) WITH <N>

  3. You can also create a Reference Collection member representing the Report Output Application's current registry table, initializing the collection at the same time. This method does not create any ReportListener object references immediately. Initializing the collection in this manner, and specifying a configuration table as the collection's single member, is the default behavior of the Report Listener Application when you call the application with no parameters:

    Copy Code
    #DEFINE OUTPUTAPP_CONFIG_READ -200
DO (_REPORTOUTPUT) WITH OUTPUTAPP_CONFIG_READ
* or pass a variable by reference in the second
* parameter, as you normally do for ReportListener
* references, to receive the name of the current
* registry table:
LOCAL lcFile
DO (_REPORTOUTPUT) WITH OUTPUTAPP_CONFIG_READ, lcFile
* or simply initialize the collection with no parameters:
DO (_REPORTOUTPUT)
? _oReportOutput[TRANSFORM(OUTPUTAPP_CONFIG_READ)]

Examining Reference Collection members

To retrieve a ReportListener object reference from ReportOutput's collection

  1. Use the string value of the numeric value representing the type of output for a ReportListener reference as the collection key value. In the command below, <N> represents the type of output provided by this ReportListener object reference.

    Copy Code
    ? _oReportOutput[TRANSFORM(<N>)].Class

  2. Use the Reference Collection member after running a report. For example, check the total number of pages in the report run:

    Copy Code
    REPORT FORM ? OBJECT TYPE 0
? _oReportOutput["0"].PageTotal

  3. Use the Reference Collection member, before running a report to customize its behavior. For example, prevent user feedback before generating XML output:

    Copy Code
    DO (_REPORTOUTPUT) WITH 4
_oReportOutput["4"].QuietMode = .T.
    Tip:
    As shown above, special negative values used by ReportOutput.app for configuration purposes may also be used as keys in this collection, although they do not provide ReportListener-derived object references. For additional examples, see "Verifying the Report Output Application's current Registry Table" in How to: Specify an Alternate Report Output Registry Table.

Changing the Default Reference Collection Variable Name

In the instructions above, you used the variable name _oReportOutput when addressing the reference collection. To change this variable name in your applications, recompile ReportOutput.app with instructions to use the variable name that you prefer.

To recompile ReportOutput.app with a different reference collection variable name

  1. Expand the ReportOutput subfolder in the zip file located in Visual FoxPro's Tools\Xsource folder. For more information about Xsource, see XSource Folder.

  2. Navigate to the folder in which you expanded the ReportOutput component source files. Modify the ReportOutput.H (header) file.

    Copy Code
    CD <your source folder>
MODIFY COMMAND ReportOutput.H

  3. Locate the following two lines of code in the header file:

    Copy Code
    #DEFINE OUTPUTAPP_REFVAR        _oReportOutput
#DEFINE OUTPUTAPP_REFVARCLASS  "Collection"

  4. Edit the value _oReportOutput, replacing it with the variable name you want your application to use. You can also edit the value "Collection", replacing it with the Collection-derived class name you want ReportOutput.app to use when creating an instance of the collection.

    Note:
    If you change the value of OUTPUTAPP_REFVARCLASS, the class definition you designate in this constant must be in scope before you invoke ReportOutput.App. For more information, see SET CLASSLIB Command and SET PROCEDURE Command.

  5. Save your changes.

  6. Rebuild the ReportOutput.App file, being sure to use the RECOMPILE switch:

    Copy Code
    BUILD APPLICATION ReportOutput FROM ReportOutput RECOMPILE

  7. Store the name and location of your new ReportOutput.app to the _REPORTOUTPUT System variable, either in the CONFIG.FPW file for your application or in your setup code. For more information, see Setting Configuration Options at Startup.

    Copy Code
    _ReportOutput = <your ReportOutput.app filename and location>

  8. Distribute the new ReportOutput.App file with your applications.

See Also

Tasks

How to: Build Applications

Reference

PUBLIC Command
Collection Class
ReportListener Object
_REPORTOUTPUT System Variable
REPORT FORM Command


How to: Specify and Distribute Report Output Application Components

Visual FoxPro 9.0
How to: Specify and Distribute Report Output Application Components
See Also

When you write and distribute Visual FoxPro applications, you can distribute ReportOutput.app or its component files as part of your applications. In this topic, you learn how to:

  • Distribute the default ReportOutput.app with your applications with appropriate instructions to use the application and an accompanying registry table.

  • Adjust the registry table defaults in ReportOutput.app.

  • Integrate the Report Output Application registry table and other Report Output Application components into your applications without distributing ReportOutput.app.

Using a non-default registry table in an application

If you distribute ReportOutput.App as a separate file from your application, and if you plan to distribute the registry table externally, the table can have any name.

To include code designating a registry table with a non-default name for the default ReportOutput.app

  1. Create a new registry table on disk. For more information about creating the table, see How to: Specify an Alternate Report Output Registry Table.

  2. Edit the table with records suitable for your application. For more information, see How to: Register Custom ReportListeners and Custom OutputTypes in the Report Output Registry Table.

  3. Store the name and location in which you are distributing ReportOutput.app to the _REPORTOUTPUT System variable, either in the CONFIG.FPW file for your application or in your setup code. For more information, see Setting Configuration Options at Startup.

    Copy Code
    _ReportOutput = <your ReportOutput.app file name and location>

  4. Include code similar to the following during setup code in your application:

    Copy Code
    #DEFINE OUTPUTAPP_CONFIG_READ -200
DO (_REPORTOUTPUT) with OUTPUTAPP_CONFIG_READ, ;
   <your registry table file name and location>

Changing ReportOutput.app's default registry table information

You can distribute a recompiled copy of ReportOutput.app with different default registry table names to suit your application.

To recompile ReportOutput.app with different default registry filenames

  1. Expand the ReportOutput subfolder in the zip file located in Visual FoxPro's Tools\Xsource folder. For more information about Xsource, see XSource Folder.

  2. Navigate to the folder in which you expanded the ReportOutput component source files. Modify the ReportOutput.H (header) file.

    Copy Code
    CD <your source folder>
MODIFY COMMAND ReportOutput.H

  3. Locate the following two lines of code in the header file:

    Copy Code
    #DEFINE OUTPUTAPP_INTERNALDBF   "_ReportOutputConfig"
#DEFINE OUTPUTAPP_EXTERNALDBF   "OutputConfig"

  4. Edit the value "OutputConfig", replacing it with the name of the table (.dbf) you want your application to use as a default value for finding the table on disk. Edit the value "_ReportOutputConfig", replacing it with the name of the table you want your application to use as a default value for finding the table built into your application, if it does not first locate a table with the default name on disk.

  5. Save your changes.

  6. Rebuild the ReportOutput.App file, being sure to use the RECOMPILE switch:

    Copy Code
    BUILD APPLICATION ReportOutput FROM ReportOutput RECOMPILE

  7. If you have changed the value in OUTPUTAPP_INTERNALDBF, the build process should automatically build in the table you specified and create the appropriate reference in your project. Locate the table for the Project Manager, during the build process, if it asks you to find the table.

  8. Store the name and location of your new ReportOutput.app to the _REPORTOUTPUT System variable, either in the CONFIG.FPW file for your application or in your setup code. For more information, see Setting Configuration Options at Startup.

    Copy Code
    _ReportOutput = <your ReportOutput.app filename and location>

  9. Distribute the new ReportOutput.App file with your applications. Include an appropriate registry table to match the file name you chose, either built into the application or on-disk.

Building Report Output Application components directly into your application

If you distribute Report Output Application components into your application file (.app or .exe), the registry table can have any name, whether you distribute the table internally or externally. This section shows you how to build the components into your project and application files.

Tip:
You do not need to distribute the ReportOutput.App file externally with your application if you follow this procedure.

To include a registry table and Report Output Application components in your application (.app or .exe) file

  1. Include code similar to the following during setup code in your application to build the Report Output Application components into your application:

    Copy Code
    * make sure that the main program of the
* Report Output Application is included
* in your project:
EXTERNAL proc frxoutput.prg

* make sure that the registry table is
* also included, if you plan to build it in
* to the application file:
EXTERNAL TABLE MyConfig

  2. In your application setup code, designate the main program of the default Report Output Application

    Copy Code
    * set the value of the _REPORTOUTPUT
* system variable to the main program of
* the default Report Output Application:
_REPORTOUTPUT = FULLPATH("frxoutput.prg")

  3. In the application setup code, designate the appropriate registry table as described in the last section. You do not need to include a path if you build the registry table into the application:

    Copy Code
    * designate the appropriate registry table:
#DEFINE OUTPUTAPP_CONFIG_READ -200
DO (_REPORTOUTPUT) with OUTPUTAPP_CONFIG_READ, "myconfig"

  4. Rebuild your application. Because you have included the main program of Report Output Application, the other required components should be automatically built into your application by the build process. During the build process, locate any files requested by the Project Manager.

  5. Your application is now ready to use the built-in Report Output Application files and your custom registry table:

    Copy Code
    * the following line will look for an class
* to instantiate using your registry table.
* It will throw an error if no appropriate
* record exists in the registry table:
REPORT FORM <your report> OBJECT TYPE 993

* the following line will look for a class
* to instantiate using your registry table.
* It will use Report Output Application's
* built-in default values if no appropriate
* record exists in the registry table:
REPORT FORM <your report> OBJECT TYPE 5

* the following lines of code causes Visual FoxPro
* to automatically ask Report Output Application
* for a ReportListener-derived object of
* TYPE 1 (print).  Your registry table
* will be used to find a class of the appropriate
* type, and Report Output Application's defaults
* will be used if the table has no records
* designating a class for this type:
SET REPORTBEHAVIOR 90
REPORT FORM <your report> TO PRINT

See Also

Reference

_REPORTOUTPUT System Variable
Including Report Files for Distribution


Using VFP Report Output XML

Visual FoxPro 9.0
Using VFP Report Output XML
See Also

As delivered by the default ReportOutput Application, Visual FoxPro's base Report XML is transformed by the ReportListener HTML Foundation Class, to provide an HTML facsimile of the original printed report output.

The underlying XML created by the ReportListener XML Foundation Class includes the full data results of the report run, plus additional information from the report table (.frx) required to describe the layout of the report and environmental conditions in place when you ran the report.

The VFP Report XML schema specifies the format of this XML. Because the schema expresses the full details of a report run, your applications can leverage the XML to provide many different results.

This topic discusses the VFP Report XML schema, and provides the full schema document (.xsd).

Note:
As you explore the details of this schema, you will notice many optional elements. The inclusion or exclusion of these elements tunes the schema to different uses. For example, the ReportListener HTML Foundation Class requires formatting information to determine the placement of layout elements on an output page, but a report run generating a searchable cache of XML content does not require formatting information. If you use the Report Listener XML Foundation Class to provide a VFP Report XML document, you use various properties of the class to set these options. For more information see ReportListener XML Foundation Class.

VFP Report XML Schema Description

VFP Report XML document design can be broadly described as follows:

A document contains one or multiple representations of VFP Report runs.

Each VFP Report node contains one or both of two possible child nodes:

  • A Layout or report definition (RDL) node, containing the report formatting instructions stored in the report table (.frx) by report design tools, and/or

  • A Data node, with the elements that were generated as the Report Engine moved through the data scope for the report at run time.

When you use ReportListener XML Foundation Class to generate your XML, the class determines which type of information is contained in the VFP Report node using its XMLMode property, as specified in the following table.

0 | OUTPUTXML_DATA_ONLY | The generated data will be used in a presentation not based on the original report layout, such as a Web page using independent design criteria, or for a data-centric (unformatted) translation, such as a generated cache of accounting calculations.
1 | OUTPUTXML_RDL_ONLY | The generated report definition will eventually reside on a reporting server. The data will come from a query on the server at run time. The XML RDL serves to define that query as well as the desired output expressions and layout of the result. The original run-time report data, in this scenario, provides a sample set against which the VFP-designed report layout is run to generate the XMl, but it is not used by the server.
2 | OUTPUTXML_DATA_RDL | The generated data will be matched against report layout instructions using an external mechanism, such as XSLT, to provide additional output forms.

If the VFP Report node includes the data processed at run time along with its RDL node, you can choose whether you wish to include formatting band data, and, if so, whether you want this data to be integrated with the standard data bands or included as separate collections.

Note:
The schema defines Page and Column header and footer bands as formatting bands because they occur at arbitrary, data-independent points during run-time processing. The output of these bands, as well as the exact points at which they occur, change depending on page layout and the page size for the current printer. For some reports and some XML scenarios, the information in these bands is not relevant.

The following diagram provides a high-level view of VFP Report XML and its major components.

Visual FoxPro Reporting XML Overview graphic

VFP-RDL Node

The report definition component of VFP Report XML provides full details of the layout information contained in the report table plus environment conditions during the report run, as detailed in the table below.

Visual FoxPro Reporting XML VFP-RDL graphic

VFP-RDL Element | Contents
VFPFRXLayoutObject | A join between report table (.frx) columns, FRXCursor-calculated columns, and some specialized calculated columns for different types of report table records. For more information about the report details provided by FRXCursor, see FRX Cursor Foundation Class.
VFPFRXLayoutNode | A set of elements indicating what element node names are used for different report object types in the data portion of the document, since this is configurable by the user.
VFPDataSource | A description of all open tables in the data session providing data for the report, including their indexes, relationships, filters, and columns. This section is optional.
VFPFRXCommand | A list of the REPORT FORM execution clauses and existing environment conditions, derived from the Listener’s CommandClauses member and other environmental settings. For more information, see CommandClauses Property.
VFPFRXPrintJob | A set of attributes providing printer setup and page layout information used for this report run, such as the page height.

Data Node

The Data node provides a sequence of bands containing the generated results of output processing that were rendered during the report run. As indicated above, reports contain two basic types of bands:

  • Data- and scope- dependent bands. Group and detail bands appear in an order and in numbers wholly dependent on the data scope chosen by the user for this report. Title and Summary bands, if used, appear exactly once at the beginning and end of the chosen scope.

  • Format dependent bands. Page and Column headers and footers are triggered by the Report Engine according to the requirements of the original report’s page dimensions and their interactions with the length of other data in the report.

The contents of data and scope dependent bands will always be contained in the Data node. Instances of these bands will appear in the same order that they do in the actual report output.

Depending on your specifications for formatting bands, this sequence can include formatting bands, omit formatting bands entirely, or include separate collections of formatting bands, as shown in the following diagram.

Visual FoxPro Reporting XML Data Node graphic
Note:
You can associate formatting bands with their data- and scope- dependent bands using an id:idref relationship, familiar to Visual FoxPro users as primary and foreign keys. Data- and scope- dependent bands have an idref attribute specifying their original page number, and formatting bands have an id attribute specifying their original page number.

Band Contents

All types of bands represent their rendered content the same way: there is a child element for each rendered layout element in each band instance. Although the following diagram drills down into a detail band, the same element contents could be expanded for the header and footer bands.

Visual FoxPro Reporting XML Detail graphic

Layout element nodes include optional attributes to describe their formatting, such as top and left position on the page.

Note:
The schema asserts that attribute processing is lax for layout elements and several other types, to allow custom extensions to the schema to remain valid without explicit declaration. For example, you could add attributes representing dynamic color adjustment on layout elements at run time, and these attributes would not invalid your XML output according to the VFP Report XML schema.

Associating Data and VFP-RDL Elements

All data- and scope- dependent bands as well as layout elements can be cross-referenced with their report-table-based layout descriptions using their id attribute, which contains the RECNO() value from their original record in the report table. For example, the following XML fragment provides a run-time instance of a page footer band containing two Field or Expression elements and one Text or Label element.

Copy Code
   <PF id="1" idref="4">
    <E id="7" c="0" l="0" t="9920" w="650" h="170">8/13/2004</E>
    <T id="8" c="0" l="6980" t="9910" w="400" h="160">Page </T>
    <E id="9" c="0" l="7380" t="9920" w="490" h="170">    1</E>
   </PF>

Below is the VFPLayoutObject node that describes the layout and design of the first Expression element in this page footer band. The frxrecno child element in the VFPLayoutObject below matches the id attribute in the E (expression) node above.

Copy Code
    <VFPFRXLayoutObject>
     <frxrecno>7</frxrecno>
     <platform>WINDOWS</platform>
     <name/>
     <expr>DATE()</expr>
     <offset>0</offset>
     <vpos>7708.333</vpos>
     <hpos>0.000</hpos>
     <height>1875.000</height>
     <objtype>8</objtype>
     <!-- … -->
     <start_band_id>_1AI121WEG</start_band_id>
     <band_offset>2</band_offset>
     <end_band_id>_1AI121WEG</end_band_id>
     <bandstretch>false</bandstretch>
    </VFPFRXLayoutObject>
Tip:
Layout elements continued to subsequent pages concatenate a "+" sign to their record-number-based id attribute values. This convention signifies that the node is not a new instance of the layout element. It allows your XML-parsing to consider this information, to concatenate text that was rendered on separate pages in the original printed output.

Formatting bands have a similar relationship with their VFPLayoutObject records, but they use their idref attribute to match the frxrecno value in the appropriate VFPLayoutObject record. As explained in the last section, these bands use their id attribute to represent the original page number on which they appeared. In the XML fragment above, the page footer has an id value of 1, indicating that it occurred on the first page, and you can see that the data elements in this page footer indeed indicate that the footer occurred on page 1 of the report. The page footer has an idref of 4, which indicates that its associated VFPFRXLayoutObject element has an frxrecno value of 4.

Bands' and objects' node names can be configured in the ReportListener XML Foundation Class, to use non-default node names. The VFP-RDL uses VFPFRXLayoutNode elements to associate node names with report table object types dynamically in the XML output result. In the following fragment, the node name E is associated with the object type 8, indicating that report expressions use this element name in the Data portion of the document.

Copy Code
    <VFPFRXLayoutNode>
     <name>E</name>
     <type>8</type>
     <code>0</code>
     <info>Expression object nodename</info>
    </VFPFRXLayoutNode>
Tip:
ReportListener XML Foundation Class includes VFPFRXLayoutNode elements for formatting attributes, so you can dynamically assign these attribute names as well. If your derived class adds more formatting attributes into your version of VFP Report Output XML, add these attributes as properties of your class with the string "attr" as part of the property name. ReportListener XML Foundation Class includes any properties following this naming convention and their values in the list of VFPFRXLayoutNodes and assigns a distinguishing object type.

VFP Report XML Schema Document

The following is the full VFP Report XML schema (.xsd). The XSD document includes annotation elements describing significant aspects of this schema and its use, and directs you to various ReportListener XML Foundation Class properties to specify its optional components.

Note:
The VFP Report XML schema uses brief XML node names to describe various reporting elements, such as <PH> for "Page Header." ReportListener XML Foundation Class provides a mechanism to change the default node names, if you prefer longer names for legibility or want to change to other node names that are more consistent with a description of each element in your language. Although the VFP Report XML uses the default node names, the schema also provides a mechanism to describe the names in use for each report table record type and other aspects of a report run.

Copy Code
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="Reports">
    <xs:annotation>
      <xs:documentation>
This schema describes the Visual FoxPro 9.0  XMLListener base delivery
format.  As noted in various places, actual element and attribute
NCNames are user-configurable at runtime, and the schema uses default
names.
As also noted, many elements of the schema are minOccurs=0.  In some
cases these elements do not appear at all depending on the
configuration of the report run or the XMLListener-specific properties
for that report run. Examples: a SUMMARY report does not have detail
bands, and if XMLListener.IncludeFormattingInLayoutObjects is .F. no
formatting attributes appear.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="VFP-Report" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="VFP-Report">
    <xs:annotation>
      <xs:documentation>
Contents of VFP-Report element are determined by XMLListener.XMLMode
property.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="VFP-RDL" minOccurs="0"/>
        <xs:element ref="Data" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="Data">
    <xs:annotation>
      <xs:documentation>
Contents and structure of Data element are determined by
XMLListener.includeBreaksInData property.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:choice>
        <xs:group ref="IntegratedFormattingBands"/>
        <xs:group ref="SeparateFormattingBands"/>
      </xs:choice>
    </xs:complexType>
  </xs:element>
  <xs:group name="SeparateFormattingBands">
    <xs:sequence>
      <xs:element name="Title" type="Band" minOccurs="0"/>
      <xs:group ref="GroupedBands" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="Summary" type="Band" minOccurs="0"/>
      <xs:element name="Pages">
        <xs:complexType>
          <xs:sequence minOccurs="0" maxOccurs="unbounded">
            <xs:element name="PH" type="FormattingBand" minOccurs="0"/>
            <xs:element name="PF" type="FormattingBand" minOccurs="0"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="Columns">
        <xs:complexType>
          <xs:sequence minOccurs="0" maxOccurs="unbounded">
            <xs:element name="CH" type="FormattingBand" minOccurs="0"/>
            <xs:element name="CF" type="FormattingBand" minOccurs="0"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:group>
  <xs:group name="GroupedBands">
    <xs:sequence minOccurs="0" maxOccurs="unbounded">
      <xs:element name="GH" type="Band" minOccurs="0" maxOccurs="unbounded"/>
      <xs:group ref="DetailBandSet" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="GF" type="Band" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:group>
  <xs:group name="DetailBandSet">
    <xs:sequence>
      <xs:element name="DH" type="Band" minOccurs="0"/>
      <xs:element name="D" type="Band" minOccurs="0"/>
      <xs:element name="DF" type="Band" minOccurs="0"/>
    </xs:sequence>
  </xs:group>
  <xs:group name="IntegratedFormattingBands">
    <xs:sequence>
      <xs:element name="Title" type="Band" minOccurs="0"/>
      <xs:group ref="FormattedPageBandSeries" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="Summary" type="Band" minOccurs="0"/>
    </xs:sequence>
  </xs:group>
  <xs:group name="FormattedPageBandSeries">
    <xs:sequence>
      <xs:element name="PH" type="FormattingBand" minOccurs="0"/>
      <xs:element name="CH" type="FormattingBand" minOccurs="0" maxOccurs="unbounded"/>
      <xs:group ref="GroupedBands" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="CF" type="FormattingBand" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="PF" type="FormattingBand" minOccurs="0"/>
    </xs:sequence>
  </xs:group>
  <xs:complexType name="Band">
    <xs:annotation>
      <xs:documentation>
All bands are inherently minOccurs="0" unless
XMLListener.includeBandsWithNoObjects is .T.
Band id and idref attributes are configurable via associated
XMLListener properties.  Throughout schema, default attribute
names are shown.
      </xs:documentation>
      <xs:documentation>
All band nodenames are configurable, with defaults shown in the schema;
see annotation for VFPFRXLayoutNode name attribute.
      </xs:documentation>
    </xs:annotation>
    <xs:group ref="LayoutObjects"/>
    <xs:attribute name="id" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>
Indicates FRXRecno for associated FRX metadata in VFP-RDL, with
concatenated "+" if this band has been continued.
      </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="idref" type="xs:positiveInteger" use="required">
      <xs:annotation>
        <xs:documentation>
Indicates the associated page number, for non-formatting bands.
      </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <!-- restriction by pattern here? -->
  </xs:complexType>
  <xs:group name="LayoutObjects">
    <xs:choice minOccurs="0" maxOccurs="unbounded">
      <xs:element name="T" type="LayoutObjectNoContinuation"/>
      <xs:element name="P" type="LayoutObjectNoContinuation"/>
      <xs:element name="S" type="LayoutObject"/>
      <xs:element name="E" type="LayoutObject"/>
      <xs:element name="L" type="LayoutObject"/>
    </xs:choice>
  </xs:group>
  <xs:complexType name="FormattingBand">
    <xs:group ref="LayoutObjects"/>
    <xs:attribute name="idref" type="xs:positiveInteger" use="required">
      <xs:annotation>
        <xs:documentation>
Indicates the FRXRecno for associated metadata, for formatting bands.
      </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="id" type="xs:positiveInteger" use="required">
      <xs:annotation>
        <xs:documentation>
Indicates the associated page number, for formatting bands.
      </xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
  <xs:complexType name="LayoutObject">
    <xs:annotation>
      <xs:documentation>
All layout objects' nodenames are configurable, with defaults shown in
the schema; see annotation for VFPFRXLayoutNode name attribute.
Availability of layout objects' formatting attributes is determined by
XMLListener.IncludeFormattingInLayoutObjects property.  All attribute
names, both formatting and non-formatting, are also configurable via
XMLListener associated properties.
      </xs:documentation>
    </xs:annotation>
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute name="id" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>
Indicates FRXRecno for associated FRX metadata in VFP-RDL, with
concatenated "+" if this object has been continued from a previous
page.
            </xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="c" type="xs:byte" default="0"/>
        <xs:attribute name="l" type="xs:integer"/>
        <xs:attribute name="t" type="xs:integer"/>
        <xs:attribute name="w" type="xs:positiveInteger"/>
        <xs:attribute name="h" type="xs:positiveInteger"/>
        <xs:attribute name="img" type="xs:string">
          <xs:annotation>
            <xs:documentation>
Supplies generated filename if this XML is generated by HTMLListener
subclass and the image comes from a non-filebased image type (general
field or image control).
            </xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:anyAttribute processContents="lax"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
  <xs:complexType name="LayoutObjectNoContinuation">
    <xs:simpleContent>
      <xs:restriction base="LayoutObject">
        <xs:attribute name="c" fixed="0"/>
      </xs:restriction>
    </xs:simpleContent>
  </xs:complexType>
  <xs:element name="VFP-RDL">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="VFPDataSet"/>
      </xs:sequence>
      <xs:attribute name="id" type="xs:string" use="required"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="VFPDataSet">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="VFPFRXLayoutObject" maxOccurs="unbounded"/>
        <xs:element ref="VFPFRXLayoutNode" maxOccurs="unbounded"/>
        <xs:element ref="VFPDataSource" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="VFPFRXCommand"/>
        <xs:element ref="VFPFRXPrintJob"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="VFPDataSource">
    <xs:annotation>
      <xs:documentation>
The set of VFPDataSource elements represents a snapshot of the  FRX's
CurrentDataSession, similar to a FoxPro View file in XML
format.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="the_alias"/>
        <xs:element name="rpt_driver"/>
        <xs:element name="the_dbf"/>
        <xs:element name="the_order"/>
        <xs:element name="order_desc"/>
        <xs:element name="the_filter"/>
        <xs:element name="the_skip"/>
        <xs:element ref="flds" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="VFPFRXCommand">
    <xs:annotation>
      <xs:documentation>
Base attributes are determined by the member properties of the
XMLListener.CommandClauses object.  Additional user-defined attributes
are permitted.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:attribute name="ASCII" type="xs:boolean" use="required"/>
      <xs:attribute name="DE_NAME" type="xs:string" use="required"/>
      <xs:attribute name="ENVIRONMENT" type="xs:boolean" use="required"/>
      <xs:attribute name="FILE" type="xs:string" use="required"/>
      <xs:attribute name="HEADING" type="xs:string" use="required"/>
      <xs:attribute name="INSCREEN" type="xs:boolean" use="required"/>
      <xs:attribute name="INWINDOW" type="xs:string" use="required"/>
      <xs:attribute name="ISDESIGNERLOADED" type="xs:boolean" use="required"/>
      <xs:attribute name="ISREPORT" type="xs:boolean" use="required"/>
      <xs:attribute name="NOCONSOLE" type="xs:boolean" use="required"/>
      <xs:attribute name="NODIALOG" type="xs:boolean" use="required"/>
      <xs:attribute name="NOEJECT" type="xs:boolean" use="required"/>
      <xs:attribute name="NOPAGEEJECT" type="xs:boolean" use="required"/>
      <xs:attribute name="NORESET" type="xs:boolean" use="required"/>
      <xs:attribute name="NOWAIT" type="xs:boolean" use="required"/>
      <xs:attribute name="OFF" type="xs:boolean" use="required"/>
      <xs:attribute name="OUTPUTTO" type="xs:byte" use="required"/>
      <xs:attribute name="PDSETUP" type="xs:boolean" use="required"/>
      <xs:attribute name="PLAIN" type="xs:boolean" use="required"/>
      <xs:attribute name="PREVIEW" type="xs:boolean" use="required"/>
      <xs:attribute name="PROMPT" type="xs:boolean" use="required"/>
      <xs:attribute name="RANGEFROM" type="xs:boolean" use="required"/>
      <xs:attribute name="RANGETO" type="xs:byte" use="required"/>
      <xs:attribute name="RECORDTOTAL" type="xs:byte" use="required"/>
      <xs:attribute name="SAMPLE" type="xs:boolean" use="required"/>
      <xs:attribute name="SUMMARY" type="xs:boolean" use="required"/>
      <xs:attribute name="TOFILE" type="xs:string" use="required"/>
      <xs:attribute name="TOFILEADDITIVE" type="xs:boolean" use="required"/>
      <xs:attribute name="WINDOW" type="xs:string" use="required"/>
      <xs:anyAttribute processContents="lax"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="VFPFRXLayoutNode">
    <xs:annotation>
      <xs:documentation>
Provides metadata specific to XMLListener's base XML
format.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="name">
          <xs:annotation>
            <xs:documentation>
Indicates the current nodename as defined in the XMLListener's
configuration table, for elements, or as an XMLListener property, for
attributes.  Names used for layout objects and band types in the Data
portion of this schema represent only the default values for these
nodenames; for readability and localization purposes these nodenames
are configurable and should be looked up from the VFPFRXLayoutNode
portion of the VFP-RDL at runtime.
            </xs:documentation>
          </xs:annotation>
        </xs:element>
        <xs:element name="type">
          <xs:annotation>
            <xs:documentation>
Matches FRX.objtype for this nodename
            </xs:documentation>
          </xs:annotation>
        </xs:element>
        <xs:element name="code">
          <xs:annotation>
            <xs:documentation>
Matches FRX.objcode for this nodename
      </xs:documentation>
          </xs:annotation>
        </xs:element>
        <xs:element name="info">
          <xs:annotation>
            <xs:documentation>
      Description of this type of node from XMLListener's configuration
table (for elements) or a matching XMLListener member property (for
attributes).
            </xs:documentation>
          </xs:annotation>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="VFPFRXLayoutObject">
    <xs:annotation>
      <xs:documentation>
Provides metadata specific to the FRX format, using FRX columns
directly as well as derived columns from FRXCursor helper object and
other sources.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
    <xs:element name="frxrecno"/>
    <xs:element name="platform"/>
    <xs:element name="name"/>
    <xs:element name="expr"/>
    <xs:element name="offset"/>
    <xs:element name="vpos"/>
    <xs:element name="hpos"/>
    <xs:element name="height"/>
    <xs:element name="objtype"/>
    <xs:element name="tag"/>
    <xs:element name="tag2"/>
    <xs:element name="pensize"/>
    <xs:element name="penpat"/>
    <xs:element name="fillpat"/>
    <xs:element name="width"/>
    <xs:element name="style"/>
    <xs:element name="picture"/>
    <xs:element name="order"/>
    <xs:element name="comment"/>
    <xs:element name="fillchar"/>
    <xs:element name="penred"/>
    <xs:element name="pengreen"/>
    <xs:element name="penblue"/>
    <xs:element name="fillred"/>
    <xs:element name="fillgreen"/>
    <xs:element name="fillblue"/>
    <xs:element name="fontface"/>
    <xs:element name="fontstyle"/>
    <xs:element name="fontsize"/>
    <xs:element name="mode"/>
    <xs:element name="float"/>
    <xs:element name="stretch"/>
    <xs:element name="stretchtop"/>
    <xs:element name="fontbold"/>
    <xs:element name="fontitalic"/>
    <xs:element name="fontunderline"/>
    <xs:element name="fontstrikethrough"/>
    <xs:element name="unpathedimg"/>
    <xs:element name="pathedimg"/>
    <xs:element name="top"/>
    <xs:element name="bottom"/>
    <xs:element name="norepeat"/>
    <xs:element name="pagebreak"/>
    <xs:element name="colbreak"/>
    <xs:element name="resetpage"/>
    <xs:element name="general"/>
    <xs:element name="spacing"/>
    <xs:element name="swapheader"/>
    <xs:element name="swapfooter"/>
    <xs:element name="ejectbefor"/>
    <xs:element name="ejectafter"/>
    <xs:element name="totaltype"/>
    <xs:element name="resettotal"/>
    <xs:element name="fontcharset"/>
    <xs:element name="supalways"/>
    <xs:element name="supovflow"/>
    <xs:element name="suprpcol"/>
    <xs:element name="supgroup"/>
    <xs:element name="supvalchng"/>
    <xs:element name="supexpr"/>
    <xs:element name="user"/>
    <xs:element name="bandid" minOccurs="0"/>
    <xs:element name="bandtype" minOccurs="0"/>
    <xs:element name="bandlabel" minOccurs="0"/>
    <xs:element name="start" minOccurs="0"/>
    <xs:element name="stop" minOccurs="0"/>
    <xs:element name="band_seq" minOccurs="0"/>
    <xs:element name="rel_band_id" minOccurs="0"/>
    <xs:element name="objid" minOccurs="0"/>
    <xs:element name="objname" minOccurs="0"/>
    <xs:element name="locale_id" minOccurs="0"/>
    <xs:element name="start_band_id" minOccurs="0"/>
    <xs:element name="band_offset" minOccurs="0"/>
    <xs:element name="end_band_id" minOccurs="0"/>
    <xs:element name="bandstretch" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="VFPFRXPrintJob">
    <xs:annotation>
      <xs:documentation>
Provides information specific to this report execution run as available
in the VFP environment.  These elements determine formatting
coordinates for instances of the layout objects as the Report Engine
calculates their placement during the report run.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:attribute name="pagewidth" type="xs:short" use="required"/>
      <xs:attribute name="pageheight" type="xs:short" use="required"/>
      <xs:attribute name="name" type="xs:string" use="required">
        <xs:annotation>
          <xs:documentation>
Provided by XMLListener.PrintJobName.
          </xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name="pagedesign" type="xs:string" use="required"/>
      <xs:attribute name="printresolution" type="xs:short" use="required"/>
    <xs:anyAttribute processContents="lax"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="flds">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="the_alias">
          <xs:annotation>
            <xs:documentation>
            Repeated on the field level for use with SET FIELDS GLOBAL.
            </xs:documentation>
          </xs:annotation>
        </xs:element>
        <xs:element name="the_field"/>
        <xs:element ref="the_type"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="the_type">
    <xs:annotation>
      <xs:documentation>
      Derived from AFIELDS(), matches VFP codes for various table-based
datatypes.
      </xs:documentation>
    </xs:annotation>
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:enumeration value="C"/>
        <xs:enumeration value="Y"/>
        <xs:enumeration value="D"/>
        <xs:enumeration value="T"/>
        <xs:enumeration value="B"/>
        <xs:enumeration value="F"/>
        <xs:enumeration value="G"/>
        <xs:enumeration value="I"/>
        <xs:enumeration value="L"/>
        <xs:enumeration value="M"/>
        <xs:enumeration value="N"/>
        <xs:enumeration value="Q"/>
        <xs:enumeration value="V"/>
        <xs:enumeration value="W"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>
</xs:schema>

See Also

Reference

ReportListener Object
ListenerType Property

Other Resources

ReportListener Foundation Classes
Extending Report Output Functionality


Considerations for Creating New Report Output Types

Visual FoxPro 9.0
Considerations for Creating New Report Output Types
See Also

Visual FoxPro 9's object-assisted reporting mode offers almost unlimited potential for expanding your output horizons using ReportListeners. The Report Output Application offers a convenient mechanism to help you to share your reporting extensions with other users.

This topic provides some guidelines to consider when developing and distributing Report System extension objects.

Design Decisions for Reporting Extensions

Determine whether your goal is to provide a new type of output result not available from baseclass behavior, such as Rich Text, or to enhance multiple output formats, in an output-result-independent manner.

If your goal is to enhance existing output results, your object probably does not need to be a ReportListener, and it is not an Output Type. Design this object to be supportable, as a member or helper object, by multiple ReportListeners. It needs to be single-purpose and small, for efficiency. Design a ReportListener to accept enhancements by iterating through a collection of these objects. By contrast, if your goal is a new type of output result, it must be a ReportListener-derived object, so it can partner successfully with the Report Engine. It is a good candidate for a chain of responsibility mechanism, as implemented by the ReportListener Base Foundation Class. This mechanism allows you to generate multiple types of output during the same report run.
Note:
You can use both techniques together. Register your enhancement objects to a single ReportListener, and apply their effects to the output before sending events to Successors. Each Successor can decide which enhancements are applicable to its type of output. An example is included in this topic.

Determine your error handling strategy, and publish your object's requirements in this respect.

ReportListeners partner with the Report Engine in a unique way, because of the way they process user code during a single Visual FoxPro command. They are also potentially partnered with other user code in DataEnvironment methods and user-defined functions (UDFs) embedded in the report or label file. There are different ways to handle REPORT FORM commands that do not complete properly. Review Handling Errors During Report Runs for information and suggestions. When you decide on a strategy, make sure the users of your ReportListener class have proper information to provide proper cleanup when errors occur.
Place ReportListener-required temporary tables in the special session provided for this purpose.

The ReportListener object's FRXDataSession Property provides you with the information you need to access the special copy of the report definition file (.frx) during the report run. If your ReportListener needs to do work with additional cursors, use this protected session, rather than the data session containing the data on which the report is based, represented by the ReportListener object's CurrentDataSession Property. This strategy ensures that you leave the user's "real" data session undisturbed, and also ensures cleanup of these temporary files at the conclusion of a report run.
Caution:
Be sure to switch appropriately between data sessions during the report run, when you want to use the report copy or your other workfiles. For more information, see SET DATASESSION Command.

Tip:
For an example of objected-assisted reporting that uses additional cursors in FRXDataSession, see Report XML MemberData Extensions.

Make a distinction between the ReportListener's OutputType Property (Visual FoxPro) and ListenerType Property in your design.

OutputType gives you the value with which the Report Output Application was invoked, while ListenerType represents the native output-generation mode provided by the baseclass ReportListener. A ReportListener-derived class can be registered to handle many different OutputType values in the Report Output Application's registry table, just as the baseclass ReportListener supports different ListenerType values. However, one OutputType can also support different baseclass behavior and native output, by supporting multiple ListenerType values.

Example: Applying Multiple Effects to Multiple Output Types

This example creates a ReportListener-derived class, FXListener, that leverages the ReportListener Base Foundation Class's ability to handle a Successor chain. This class pre-processes all ReportListener events with effects-handling before invoking the Successor chain. All Successors in the chain receive the benefits of the effects collection, and process the results of all applied effects to whatever extent they are capable of using the changes.

FXListener supports a collection of effect objects. FXListener requires that all effect objects are instances of classes derived from any Visual FoxPro base class, and implementing the following simple interface:

Copy Code
DEFINE CLASS FX As Custom  && any base class
   * required interface:
   PROCEDURE ApplyFX(toListener, tcProgram,;
                     tP1, tP2, tP3, tP4, tP5, tP6,;
                     tP7, tP8, tP9, tP10, tP11, tP12)
    * FXListener passes a reference to itself as toListener,
    * PROGRAM() as tcProgram, and
    * all ReportListener parameters as tP1 through tP12,
    * for each ReportListener event during the run.
    * Parameters tP1 through tP12 are passed by reference,
    * so that changes made by effect objects are visible
    * to FXListener and its successors upon return from
    * this method.
   ENDPROC
ENDDEFINE

You register one or more effects for a report run by adding an instance of one or more effect-handling classes to a FXListener-derived object's effects collection. You then invoke REPORT FORM commands with the OBJECT clause referencing your FXListener object, to receive the results of your effects.

The example below includes the full code for the FXListener class and a simple effect class. The effect class applies the UPPER() function to all text output. The example adds an instance of this effect class to FXListener's collection. It also designates two Successors to FXListener (an instance of the ReportListener User Feedback Foundation Class and an instance of the ReportListener HTML Foundation Class) before it proceeds to run a report.

The effect object's change to report output is reflected in the preview output displayed by the primary ReportListener (the instance of FXListener) as well as the HTML output generated by the HTMListener Successor object in its chain. Running at the same time, the user feedback provided by the ReportListener User Feedback Class incorporates the contents of the primary ReportListener's customized PrintJobName Property.

Tip:
The text output is changed to upper case in Render rather than the EvaluateContents event, for better performance. Using Render also provides the ability to change the output of Label layout elements as well as Field or Expression layout elements in the report; EvaluateContents events do not occur for Label layout elements.

If you add an effect object that generates changes to font attributes, rather than text contents, using the EvaluateContents event, you see results of these changes in the preview. However, you do not see the same results in the HTML; the ReportListener HTML Foundation Class takes its font attributes from the layout elements' definitions in the FRX, and does not incorporate dynamic changes made at run time. Well-designed effect classes are unaware of the capabilities, requirements, and limitations of various ReportListener-generated types of output.

For other examples of effect classes, see Report XML MemberData Extensions.

Copy Code
#DEFINE FFC_HOME HOME() + "FFC\"

LOCAL loPrimaryRL, loSuccessorRL, loSuccessorRL2
loPrimaryRL = CREATEOBJECT("FXListener")
loSuccessorRL = NEWOBJECT("UpdateListener", ;
                FFC_HOME + "_ReportListener.vcx")
loSuccessorRL2 = NEWOBJECT("HTMLListener", ;
                FFC_HOME + "_ReportListener.vcx")

WITH loPrimaryRL
   .PrintJobName = "FX Listener Test"
   .QuietMode = .T.
   .ListenerType = 1
   .FXs.Add(CREATEOBJECT("FXSimple"))
   .Successor = loSuccessorRL
ENDWITH
loSuccessorRL.Successor = loSuccessorRL2
loSuccessorRL2.QuietMode = .T.

REPORT FORM ? OBJECT loPrimaryRL

* FXListener,
* Effects-applying ReportListener-derived class:
DEFINE CLASS FXListener AS _ReportListener OF ;
                 (FFC_HOME + "_reportListener.vcx")
   FXs = NULL
   PROCEDURE Init()
      THIS.FXs = CREATEOBJECT("Collection")
   ENDPROC
   PROCEDURE SendFX(tcProgram, ;
     tP1, tP2, tP3, tP4, tP5, tP6, tP7, tP8, tP9, tP10, tP11,tP12)
      IF (NOT THIS.IsSuccessor) AND THIS.FXs.Count > 0
         * Only the lead does this work.
         * The order of the
         * invocation of this method,
         * which precedes the DODEFAULT()
         * in each event,
         * makes the results available
         * for all Successors.
          LOCAL loFX
          FOR EACH loFX IN THIS.FXs FOXOBJECT
              loFX.ApplyFX(THIS,tcProgram, ;
                           @tP1, @tP2, @tP3, @tP4, @tP5, @tP6, ;
                           @tP7, @tP8, @tP9, @tP10, @tP11, @tP12)
          NEXT
      ENDIF
   ENDPROC
   PROCEDURE BeforeReport()
      THIS.SendFX(PROGRAM())
      NODEFAULT
      RETURN DODEFAULT()
   ENDPROC
   PROCEDURE AfterReport()
      THIS.SendFX(PROGRAM())
      NODEFAULT
      RETURN DODEFAULT()
   ENDPROC
   PROCEDURE BeforeBand(nBandObjCode, nFRXRecNo)
      THIS.SendFX(PROGRAM(),nBandObjCode, nFRXRecNo)
      NODEFAULT
      RETURN DODEFAULT(nBandObjCode, nFRXRecNo)
   ENDPROC
   PROCEDURE AfterBand(nBandObjCode, nFRXRecNo)
      THIS.SendFX(PROGRAM(),nBandObjCode, nFRXRecNo)
      NODEFAULT
      RETURN DODEFAULT(nBandObjCode, nFRXRecNo)
   ENDPROC
   PROCEDURE EvaluateContents(nFRXRecno, oObjProperties)
       THIS.SendFX(PROGRAM(),nFRXRecno, oObjProperties)
       NODEFAULT
       IF (NOT ISNULL(THIS.Successor))
          THIS.SetSuccessorDynamicProperties()
          THIS.Successor.EvaluateContents(nFRXRecno, oObjProperties)
       ENDIF
       DODEFAULT(nFRXRecno, oObjProperties)
   ENDPROC
   PROCEDURE AdjustObjectSize(nFRXRecno, oObjProperties)
       THIS.SendFX(PROGRAM(),nFRXRecno, oObjProperties)
       NODEFAULT
       IF (NOT ISNULL(THIS.Successor))
          THIS.SetSuccessorDynamicProperties()
          THIS.Successor.AdjustObjectSize(nFRXRecno, oObjProperties)
       ENDIF
       DODEFAULT(nFRXRecno, oObjProperties)
   ENDPROC
   PROCEDURE Render(nFRXRecNo,;
                    nLeft,nTop,nWidth,nHeight,;
                    nObjectContinuationType, ;
                    cContentsToBeRendered, GDIPlusImage)
       THIS.SendFX(PROGRAM(),nFRXRecNo,;
                   @nLeft,@nTop,@nWidth,@nHeight,;
                   @nObjectContinuationType, ;
                   @cContentsToBeRendered, @GDIPlusImage)
       NODEFAULT
       RETURN DODEFAULT(nFRXRecNo,;
                        nLeft,nTop,nWidth,nHeight,;
                        nObjectContinuationType, ;
                        cContentsToBeRendered, GDIPlusImage)
   ENDPROC
ENDDEFINE

* example FX class fulfilling FX design contract
* by implementing required interface:
DEFINE CLASS FXSimple AS Custom
   PROCEDURE ApplyFX(toListener, tcProgram,;
                     tP1, tP2, tP3, tP4, tP5, tP6, ;
                     tP7, tP8, tP9, tP10, tP11, tP12)
      IF ATC("Render",tcProgram) > 0
          tP7 = UPPER(tP7)
          * cContentsToBeRendered
          * is Render's 7th parameter
          * Note that many changes to
          * cContentsToBeRendered in the Render method
          * will require use of STRCONV() to
          * provide a Unicode result, although this
          * simple change does not require it.
      ENDIF
   ENDPROC
ENDDEFINE

See Also

Reference

Considerations for Creating Reports


Handling Errors During Report Runs

Visual FoxPro 9.0
Handling Errors During Report Runs
See Also

Visual FoxPro 9.0 provides significant enhancements to the process of creating output, including new opportunities to invoke application code during the native Report System's internal data-handling and output-rendering procedures. To adequately provide users with the ability to develop such programs, Visual FoxPro 9.0 also enhances error-reporting and debugging during a report run.

This topic covers error-handling features with special significance for reporting, and examines different strategies for handling abnormal conclusions of report runs.

Note:
Application components such as the Report Output Application and Report Preview Application partner with the Visual FoxPro Report System during output processing. They function as factories to provide appropriate object references to the Report Engine. Although these components may trigger errors and require debugging, they are not active during the internal report run, which spans processing events from the BeforeReport Event to the AfterReport Event. You can debug any issues with these components similarly to any other Visual FoxPro application; they are not covered by this topic. For more information about the sequence of events in a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

Tip:
You can use all standard Visual FoxPro debugging tools, such as the Trace Window, when examining your reporting code. You will also find the ReportListener Debug Foundation Class useful as you investigate report event sequences.

Strategies for error-handling during a report run

Because Visual FoxPro's output processing sequence can include extensive user code, you may need to end a report run before it finishes due to a code error. You may also want to end a report run prematurely because an end-user wants to interrupt the report. Additionally, an external error handler may detect a reason to end your application, while a report run is in process.

In all these situations, you can call the ReportListener CancelReport method to make sure Visual FoxPro does any special cleanup, such as closing a print queue, necessary to end the report, and your application, safely. See CancelReport Method for more information.

The ReportListener User Feedback Foundation Class provides a good model for canceling a report in response to an end-user request. See the DoMessage Method topic for the code in this class' CancelReport Method. Notice that the method issues a NODEFAULT if the end-user opts to resume running the report in response to a dialog box. Your code can follow a similar strategy in response to recoverable errors. For critical errors, you may prefer to end the report unilaterally, and end the application following report clean-up.

You can check to see whether the report ended normally using the SYS(2024) function. This function will return "Y" during a report run, through the conclusion of the Unload Event, if the report did not complete its run normally. At this point, the internal Visual FoxPro Report System processing has concluded. If you determine that the abnormal end to the report run did not occur as a response to an end-user's request, you can safely CANCEL or QUIT or request similar handling from an external application object. For more information, see Microsoft Visual FoxPro Technical Support.

Example 1: Cancelling a report

In the following example, an error occurs in a ReportListener's BeforeReport event, and its Error event responds by calling the class' CancelReport method. The UnLoadReport event code reports the value of SYS(2024) as "Y," as a result of the Error event's action.

Note:
If the error occurred during the LoadReport event, SYS(2024) would not return "Y." No internal processing has occurred as yet, so there would be nothing for the Report Engine to clean up.

Copy Code
DEFINE CLASS errorListener as ReportListener
  PROCEDURE BeforeReport()
    REPORT FORM ?
  ENDPROC
  PROCEDURE Error(nError, cMethod, nLine)
     WAIT WINDOW MESSAGE()
     * MESSAGE() will report:
     * Report contains a nesting error.
     THIS.CancelReport()
  ENDPROC
  PROCEDURE UnloadReport()
     WAIT WINDOW SYS(2024)
     * SYS(2024) will report: "Y"
  ENDPROC
ENDDEFINE

Example 2: Ending an application as a result of report error

In the example above, the ReportListener-derived class handles the error. You may prefer to bubble the error event to an external application handler for determination of appropriate action. In this case, the external application needs to know that a report run was in progress when the error occurred, so it can cancel the report properly before ending the application.

To determine that a report run is in progress in external code, use the SYS(2040) function. For more information, see SYS(2040) - Detect Report Status.

The following example checks the return value of SYS(2040) in an ON ERROR Command handler.

Copy Code
PUBLIC oApp
oApp = CREATEOBJECT("MyApp")
ON ERROR oApp.ErrorHandler()
WAIT WINDOW "Some processing here..."
REPORT FORM ? OBJECT oApp.oE
WAIT WINDOW ;
  "Some more processing here, " + ;
  "will not occur because of error..."

DEFINE CLASS MyApp AS Custom
   oE = NULL
   PROCEDURE Init
      THIS.oE = CREATEOBJECT("errorListener")
   ENDPROC
   PROCEDURE ErrorHandler
     MESSAGEBOX("Error! " + MESSAGE())
     IF SYS(2040) # "0"
       THIS.oE.cancelReport()
     ENDIF
    IF _VFP.StartMode = 0
       CANCEL
    ELSE
       QUIT
    ENDIF
  ENDPROC
ENDDEFINE

DEFINE CLASS errorListener as ReportListener
  PROCEDURE BeforeBand()
    * parameters are missing
  ENDPROC
  PROCEDURE CancelReport()
    DODEFAULT()
    MESSAGEBOX("Cancelling Report!")
  ENDPROC
ENDDEFINE

Example 3: Canceling a report during application shutdown

You can use a similar strategy in an ON SHUTDOWN handler if it is possible for this handler to be called during a report run. The ON SHUTDOWN handler needs a reference to the appropriate ReportListener object, just as the application object in the example above does. For more information, see ON SHUTDOWN Command.

Tip:
Timers do not fire during a report or label run. However, it is often possible for end-users to decide to close your application while Visual FoxPro is generating output. Therefore, do not assume that the need to cancel a report is always associated with an error.

You can use the following simple example to verify this capability.

Copy Code
PUBLIC rl
ON SHUTDOWN DO MyShutdown

rl = CREATEOBJECT("reportListener")
REPORT FORM ? OBJECT rl  && use a long report!
* use the close box on the main Visual FoxPro
* window while the report runs.

PROCEDURE MyShutDown
  IF SYS(2040) # "0"
     MESSAGEBOX("Now Cancelling Report!")
     rl.CancelReport()
  ENDIF
  ON SHUTDOWN
  IF _VFP.StartMode = 0
     CANCEL
  ELSE
     QUIT
  ENDIF
ENDPROC

Example 4: Using a ReportListener's Error event

In two of the three examples above, the ReportListener class does not have Error event code. If you include Error event-handling in a ReportListener class, as shown in the first example, this code can decide to handle, or bubble, any error it receives.

If the Error event handles an error, it can safely use CANCEL or QUIT. You can use these commands in other ReportListener events or methods as well. Be sure to invoke the ReportListener's CancelReport() method before issuing the CANCEL or QUIT statement, however.

In the next example, the ReportListener class uses its Error event to handle the error, and then ends the report immediately.

Tip:
The ReportListener's Error event will not handle errors that occur during a report run but outside the ReportListener's own code, such as an error in a user-defined function (UDF) within the report or an error in a report expression. For this reason, having ReportListener Error event code does not free your external error handler of the responsibility to be aware of reporting errors. A combination of approaches is necessary to handle all types of errors that may occur in the course of a report run.

Copy Code
LOCAL oE
oE = CREATEOBJECT("errorListener")
WAIT WINDOW "Some processing here..."
REPORT FORM ? OBJECT oE
WAIT WINDOW ;
  "Some more processing here, " + ;
  "will not occur because of error..."

DEFINE CLASS errorListener as ReportListener
  PROCEDURE BeforeBand()
    * parameters are missing
  ENDPROC
  PROCEDURE Error(nError, cMethod, nLine)
   WAIT WINDOW "Error occured! " + CHR(13) + ;
               "SYS(2024) before CancelReport: " + SYS(2024)
   THIS.CancelReport()
   CANCEL
  ENDPROC
  PROCEDURE CancelReport()
    IF SYS(2040) # "0"
       MESSAGEBOX("Cancelling Report!")
       DODEFAULT()
       WAIT WINDOW "SYS(2024) is now: " + SYS(2024)
    ENDIF
  ENDPROC
ENDDEFINE

Example 5: Using structured error handling with reports

As a final strategy, you can use structured error handling with reports. When you run the sample code below, however, notice that your code does not get to the CATCH construct until after the report run has ended, from the Report System's perspective. Although you can use the CancelReport method, the user code you run in this method should be designed to run safely whether or not a report is actually in progress.

Copy Code
LOCAL oE

TRY
  oE = CREATEOBJECT("errorListener")
  WAIT WINDOW "Some processing here..."
  REPORT FORM ? OBJECT oE
  WAIT WINDOW ;
  "Some more processing here, " + ;
  "will not occur because of error..."
CATCH WHEN .T.
   WAIT WINDOW "An error occured! " + CHR(13) + ;
               "SYS(2024)=" + SYS(2024) + CHR(13) + ;
               "SYS(2040)=" + SYS(2040)
   * SYS(2024) will report "N"
   * SYS(2040) will report "0"
   oE.CancelReport()
ENDTRY

DEFINE CLASS errorListener as ReportListener
  PROCEDURE BeforeBand()
    * parameters are missing
  ENDPROC
  PROCEDURE CancelReport()
    IF SYS(2040) = "0"
       MESSAGEBOX("No report in progress, " + CHR(13) + ;
                  "but this method can still do user cleanup!")
       NODEFAULT
    ELSE
       MESSAGEBOX("Cancelling Report!")
       DODEFAULT()
    ENDIF
  ENDPROC
ENDDEFINE

Errors during a report run that do not occur in lines of code

In Visual FoxPro 9.0 and all earlier versions, it is possible for errors to occur during report runs that are not specifically associated with a traceable line of user code. Such errors include report expressions or report variables that the Report Engine cannot resolve, as well as difficulties initializing the report's Data Environment.

Visual FoxPro 9.0 maintains backward-compatibility with its handling of such errors, as described in this section.

When an error occurs outside user code, Visual FoxPro's internal error handling does not offer you an opportunity to suspend the report, because there is no line of code on which to suspend.

If you do not have an ON ERROR handler or a TRY… ENDTRY construct in place, Visual FoxPro does not invoke your error handling until after it does its internal cleanup and ends the report run.

As demonstrated in the examples in this topic, the value of the MESSAGE() function is available if it occurs in ReportListener code or other user code you invoke during a report run. However, if the error is not associated with a line of code, MESSAGE() is not assigned until after the Report Engine concludes its cleanup.

If an error is not associated with a line of code, the value of MESSAGE() is not assigned at all unless you have some form of error-handling in place at the time the REPORT FORM or LABEL command occurs. If you do not have an error handler, and if you have used the CLEAR ERROR command before the report run, MESSAGE() is still empty after the report run. If you have not used CLEAR ERROR, MESSAGE() retains its previous value.

Commands not supported during a report run

To error-handle well, you should start by planning to use only commands that are safe to use during a report run.

The Visual FoxPro commands in the table below are all unsupported during internal output processing, between the BeforeReport event and AfterReport event (inclusive).

Not all the errors in this table will generate an immediate error, but use of these commands during output processing leads to unpredictable results.

These commands are unsupported whether they occur:

  • Directly in ReportListener event code.

  • In additional code invoked by a ReportListener, such as code in a procedure library.

  • In the command window while execution is suspended.

  • Using code invoked directly in report or label expressions, such as user-defined functions (UDFs).

In some cases, as indicated in the table, the commands are also not supported in the ReportListener's LoadReport Event and UnloadReport Event. These two framing events provide user hooks at each end of the internal processing run.

As a final, exceptional case, while the OutputPage Method may be running after the report run concludes, if called by a PreviewContainer object, this method may need access to resources built into the application, such as image files, to perform its task. For this reason, using commands such as CLEAR ALL that might unload the calling application from memory are not supported until the preview concludes. When the REPORT FORM or LABEL command includes the NOWAIT keyword, the preview concludes at the time the preview window closes, unless the user chooses to print from preview. If the user chooses to print, the preview concludes at the time Visual FoxPro finishes sending the report output to the printer.

Note:
In addition to the commands listed below, all commands that change sessions, work areas, record pointers, or other attributes of the data on which the REPORT FORM and LABEL commands act, should be used with caution. As in previous versions of Visual FoxPro, it is the responsibility of the user to restore the state of the data appropriately when using these commands, with the understanding that other ReportListeners and additional user code, as well as the internal Report Engine, may be affected by their changes. For example, although the BROWSE command does not appear in this table, it has potential to change the record pointer, trigger additional code attached through user-defined functions (UDFs), and affect data relationships, so it should be used with caution.

Command(s) | Supported in LoadReport and UnloadReport events? | Remarks
CLEAR ALL RELEASE ALL CLOSE ALL | No | This restriction is primarily to preserve the ReportListener reference and data tables as expected by the Report Engine during its processing of the report scope.
RETRY RETURN TO MASTER RETURN TO <Procedure Name> | No |
?, ??, ??? \, \ @... SAY EJECT, EJECT PAGE PRINTJOB… ENDPRINTJOB LIST, DISPLAY, TYPE SET DEVICE,PRINTER | Yes | These output commands are supported during the output run if the target device for the output run is different from the target device for the output command. For example, if your REPORT FORM command has a PREVIEW clause, you can LIST MEMO TO<filename> during the report run.
BEGIN TRANSACTION and additional transaction-related commands | Yes | Transaction commands are supported if the transaction is concluded within one invoked procedure or one ReportListener event.
MODIFY/CREATE CLASS, FORM, LABEL, REPORT […] | Yes | All commands that invoke interactive Visual FoxPro Designers are unsupported, whether modal or invoked with the NOWAIT keyword. You can invoke a text editor (MODIFY FILE or COMMAND).
REPORT FORM LABEL | No | REPORT FORM and LABEL commands cannot be nested.

Errors associated with the Visual FoxPro Report System

The following table provides a list of errors that can occur for reasons specific to the run-time processing of reports and labels.

Error message and number | Cause or scenario
"name" is not an object (Error 1924) | The Engine received a REPORT FORM Command or LABEL Command with an OBJECT <ref> clause and <ref> was not an object.
Class definition "name" is not found (Error 1733) | The Engine received a NULL reference as the result of an OBJECT TYPE<N> clause on a REPORT FORM or LABEL command, indicating that the application specified in the _REPORTOUTPUT system variable could not resolve this value to a ReportListener Object object reference.
Data type is invalid for this property (Error 1732) | The Engine an OBJECT TYPE<N> clause on a REPORT FORM or LABEL command, and the <N> parameter was not of numeric type. This error may also occur in connection with use of the OutputPage method, discussed below.
Report contains a nesting error (Error 1645) | A REPORT FORM or LABEL command was invoked during another report or label run. Note that this error still occurs if the nested command uses backward-compatible report mode, if a different report is requested, or if the nested command includes a reference to a different ReportListener object.
Syntax error (Error 10) | SET REPORTBEHAVIOR Command was issued with an incorrect parameter.
The current object does not inherit from class "name" (Error 1935) | The Engine received an object reference that does not inherit from the Visual FoxPro ReportListener base class.
Variable "variable" is not found (Error 12) | The Engine received an OBJECT TYPE<N> clause on a REPORT FORM or LABEL command, and the application specified in the _REPORTOUTPUT system variable could not be found or the variable was empty.
Must specify additional parameters (Error 94) Function argument value, type, or count is invalid (Error 11) Data type is invalid for this property (Error 1732) Error writing to file "file" (Error 1105) Output page "page" is not available (Error 2194) | The errors in this group all indicate that the ReportListener's OutputPage method was invoked incorrectly. For more information, see OutputPage Method.

See Also

Reference

TRY...CATCH...FINALLY Command
Debugging and Error-Handling Language
Error Event (Visual FoxPro)
CANCEL Command
QUIT Command
MESSAGE( ) Function
CLEAR Commands

Concepts

Structured Error Handling
Class and Object Error Handling
Handling Run-Time Errors
Error Handler Priority


Understanding and Extending Report Structure

Visual FoxPro 9.0
Understanding and Extending Report Structure
See Also

In Visual FoxPro 9.0, both design-time and run-time Report System extensions are more feasible and varied than ever before. To ensure you create extensions successfully, you must understand the report (.frx) and label (.lbx) table structures.

Note:
Report and label file structures are identical in Visual FoxPro. For more information about the contents of the FILESPEC directory, see Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx).

This topic discusses how you explore and extend the tables' use of various columns to describe different aspects of report layout and behavior. It also provides you with specified limitations for extensions to these tables.

This information allows you to:

  • Manipulate existing report and label table data successfully.

  • Describe new types of report elements and behavior in the tables.

Understanding the Changes to Report and Label Tables

Visual FoxPro 9 adds no required fields to the native report table structure. Because no new fields are added to migrate report and label forms, you can use Visual FoxPro 9's enhanced design facilities to edit existing reports. These reports will still run when distributed to end-users of your existing applications.

To support various design-time and run-time enhancements, Visual FoxPro 9 overloads some fields in report and label tables, using them in new ways for report elements that did not use these fields in earlier versions. Some of the new values are not used directly by the product, instead providing information to ReportBuilder applications or other user-code.

Visual FoxPro 9's new content, supporting design and processing enhancements, can also be added into existing reports without disturbing backward- compatibility. The additional content in report and label fields will be ignored at runtime by Visual FoxPro 8 and earlier versions.

Visual FoxPro provides information about the system tables for various elements, including reports, in the FILESPEC directory. Visual FoxPro 9.0 supplies an updated copy of 60FRX.DBF, the table that specifies usage of the various fields in the report and label tables.

Changes to 60FRX.DBF

The 60FRX.Descriptio column has been updated in almost every record, to better explain usage of fields by reports and labels. The updated information you see in this field applies to all versions of Visual FoxPro, and adds a separate section indicating any new usage in Visual FoxPro 9.0.

The following example is the 60FRX.Descriptio entry for the 60FRX.Fields value RULERLINES.

Copy Code
RULERLINES is used only in the header record.
0 = Show Ruler Lines: No
1 = Show Ruler Lines: Yes
==============================
Visual FoxPro 9-only Information Below
==============================
RULERLINES is reserved in VFP9 for OBJTYPE=8 (Field) for StringTrimming.
Default is StringTrimmingEllipsisWord.
0 or not entered = Default
1 = StringTrimmingCharacter
2 = StringTrimmingWord
3 = StringTrimmingEllipsisCharacter
4 = StringTrimmingEllipsisWord
5 = StringTrimmingEllipsisPath (for filenames).

To help you find how each type of report and label field is used for different types of layout elements, the Visual FoxPro 9.0 version of 60FRX.DBF contains a new field, 60FRX.Usedby_obj. The 60FRX.Usedby_obj field contains a list of keywords for all report elements that uses a given field.

For example, if you wanted to find out all fields used in the header record of a report or label file, and a description for how these fields are used, you could issue this command:

Copy Code
SELECT Fields, Descriptio FROM 60FRX WHERE ATC("Header",Usedby_obj) > 0

The Fields column in the resulting cursor gives you the name of each field in an FRX or LBX table used in the Header record. The Descriptio column tells you how each field is used.

Tip:
If a report field has new uses in Visual FoxPro 9.0, the keywords for elements newly using the field follow a symbol, "|", in the 60FRX.Usedby_obj list. For example, for the 60FRX.Fields value RULERLINES, the 60FRX.Usedby_obj value reads HEADER | EXPR. As indicated in the 60FRX.Descriptio entry for RULERLINES above, previous versions of Visual FoxPro used this field in the header record only. Visual FoxPro 9.0 also uses this field for Field (or Expression) layout elements. As a result, the two keywords appear separated by the "|" symbol in the 60FRX.Usedby_obj column.

The following table gives you the 60FRX.Usedby_obj keywords for each type of report object.

Report table Objtype field value | Report object description | 60FRX.Usedby_obj value
0 | Comment | N/A
1 | Report Header | HEADER
2 | Workarea (FoxPro 2.x reports) | 20TABLE
3 | Index (FoxPro 2.x reports) | 20INDEX
4 | Relation (FoxPro 2.x reports) | 20RELATION
5 | Label | TEXT
6 | Line | LINE
7 | Rectangle / Shape | SHAPE
8 | Field | EXPR
9 | Bandinfo | BAND
10 | Group | GROUP
17 | Picture / OLE Bound | PICT
18 | Variable | VAR
21 | Printer Driver Setup (FoxPro 2.x reports) | 20PDRIVER
23 | Font resource | FONTRES
25 | Data Environment | DATAENV
26 | Cursor, Relation, or CursorAdapter (See Name field to determine which) | CURSOR-RELATION

Creating Valid Report and Label Content

Visual FoxPro 9 supplies reference code to show you how to locate and size the various objects used in reports and labels in Foundation Classes. For more information, see FRX Cursor Foundation Class and FRX Device Helper Foundation Class. These classes are part of the default ReportBuilder Application. They give you the ReportBuilder Application's tools to use, when you want to determine appropriate placement and metrics for new report and label elements.

Formatting and Reviewing 60FRX.DBF Information

A new report in the FILESPEC directory, 90FRX.FRX, provides consolidated information on full report and label table usage in all versions, while highlighting new-to-Visual FoxPro 9 usage. The earlier reports available for 60FRX.DBF, 60FRX1.FRX and 60FRX2.FRX, are still included in FILESPEC.

Extending Report and Label Tables Safely

Visual FoxPro 9 provides reliable persistence of user-defined content in reports and labels. You can add your own content to these tables in the following ways:

  • Add new columns to report and label tables.

  • Add new report and label object types as rows to the tables.

  • Add records with new Platform values (records that with platform values other than "Windows").

  • Add private data into columns, such as the User column, not used natively by reports or labels.

  • Add private attributes into the Reporting memberdata XML data schema. Reporting memberdata is stored in the Style column. For more information, see How to: Assign Structured Metadata to Report Controls.

Visual FoxPro 9 preserves all these types of user-defined content, whether they occur in records used natively, or in additional records. It makes this content available to user code in Report Designer sessions, through Report Builder hooks. When you process reports and labels, it makes the full content of the report or label table available to ReportListener events and methods.

Caution:
Earlier versions of Visual FoxPro did not preserve user content in design sessions and did not allow user-defined records or columns in report and label tables. As a result, you should not add new types of content into reports and tables using Visual FoxPro 9 if you expect to edit these files in earlier versions later, because the new content can be lost. You can add new content into existing records of reports and labels and distribute them successfully to users of earlier versions. However, do not add new columns into these tables, to ensure that the earlier versions can recognize the tables as reports and labels.

The following limitations must be observed when you extend reports and labels with new types of content.

Differentiating Between Native and User-defined Record Types

There are 100 total possible Objtype values (0 through 99). Visual FoxPro 9 explicitly reserves Objtype values 49 and below for internal or native Report Designer use. Only records with recognized and documented Objtype values, and only records containing Objcode field values natively associated with these Objtype values, are manipulated in the native Report Designer.

Users and add-ons such as ReportBuilder Applications can alter the contents of records with natively-recognized values in the Objtype field of the report or label. They can also add new records with native Objtypes, taking care to follow standard usage of columns for all native types.

Users and add-ons should not add unknown or undocumented Objcode values to records with native Objtype values (49 and below). They may be removed by the native Report Designer without warning.

You can add records with user-defined Objtype values of 50 and above. These records can have any Objcode values. The native Report Designer preserves and ignores all content of such records, but ReportBuilder Applications and other add-ons can be used to add and modify them.

Note:
Although user-added records with Objtype values of 50 and above are preserved, the position of such records within the report or label table is not guaranteed. A Report Designer session may change the order of records in the report table. User-defined records will usually appear at the end of the table after the report is saved by the Report Designer. If record order is significant to your application, store information relevant to record order in an additional column.

Ensuring Unique ID Values for Records With User-defined Content

Extra content in any records without UniqueID values,including content in native fields such as the User field, will not be preserved. The restriction holds for records with native Objtype values as well as user-defined Objtype values.

Tip:
Use the SYS(2015) function to create values for the UniqueID field of new records. Use the FRXCursor Foundation Class's getFrxTimeStamp method to create appropriate Timestamp values.

Reports and labels have a few native Objtype values without UniqueIDs, notably font (objtype 23) and data environment-related resources (objtypes 25 and 26), used in specific ways by the Report Engine at runtime. It is also possible to have a “comment” record (objtype 0 or blank). The Report Designer and ReportBuilder Application are not guaranteed to preserve user-defined content in these records. You can add new records of the appropriate objtypes for these resources, giving them standard contents. You can also extend these resources by associating user-defined object types with them. For example, a record of objtype 53 could represent an "extended font resource record.

Locating User-added Content in Report and Label Table Structures

User-added columns must be at the end of the Report or Label table structure. If native columns are re-ordered, deleted, edited for size, type or name, etc., Visual FoxPro will consider the report or label to be invalid.

The header record of the table, describing global report or label attributes, must remain in its standard position (first record in the table).

The Expr, Tag, and Tag2 columns in the header record (used for printer setup attributes) are reserved for internal use.

In some limited cases, users may edit the values in the Expr column and, if these values are reasonable for the associated attributes, they will be recognized by the Designer, remain stable and be available during design sessions, and used by the Report Engine at run time. However, this behavior is not supported and not extensible. In particular, user-defined value-pairs in the Expr field will not be saved back to the report table after design sessions, even if no explicit changes to Page Setup are made during these sessions. You can use the Picture field of the header record to store user-override information for printer instructions, instead. For more information, see SYS(1037) - Page Setup Dialog Box.

See Also

Reference

ReportListener Object
SYS(2015) - Unique Procedure Name

Concepts

MemberData Extensibility
Report XML MemberData Extensions

Other Resources

Extending Reports at Design Time


Report XML MemberData Extensions

Visual FoxPro 9.0
Report XML MemberData Extensions
See Also

Visual FoxPro 9.0 provides extended metadata attributes for class members in the Class Designer using XML in a document format specified by the VFP MemberData Schema. While the Visual FoxPro Report System does not share the Class Designer, it shares the MemberData schema for similar extensibility purposes. Using MemberData extensions with reports, you can:

  • Specify custom design-time instructions for individual report layout elements, for use by through event hooks exposed by the Report and Label Designers.

  • Provide dynamic instructions for individual report layout elements that can be carried out by a ReportListener-derived object at run time.

This topic describes the MemberData schema components used for reporting, and provides examples using MemberData XML documents when you design and run reports.

Report XML MemberData Document Design

Report MemberData, like Class Design MemberData, contains a sequence of elements under a VFPData root node. For a complete listing of the shared MemberData schema (.xsd), see MemberData Extensibility. The following table describes the attributes specified for reporting use.

Note:
The schema permits users to add attributes not explicitly specified. Any tools you create to parse or create the XML should allow for the possibility that additional, unknown attributes are present for one or more elements in the sequence. Tools should also handle the possibility that attributes not marked as required by the schema might be missing for one or more elements. The run-time example in this topic provides a model for this behavior.

The Style column of report and label definition files (.frx and .lbx tables) is reserved for storage of Report MemberData. For more information on the structure of reports and labels, see Understanding and Extending Report Structure.

You can use the default Report Builder Application to insert XML documents of the required structure into report and label records for individual layout elements. You can examine the results, to see Report XML MemberData example documents. For more information, see How to: Assign Structured Metadata to Report Controls.

Node name Node type Parent node Remarks and recommended usage

VFPData

Element

(required)

None

Root node for the MemberData document.

reportdata

Element

(required)

VFPData

An element containing metadata for a specific report or label definition table record.

name

Attribute

(required)

reportdata

Shared with Class Designer MemberData. Can be used, with the type attribute, to filter and manage reporting MemberData Records in a common global store, such as FoxCode.dbf. For more information, see _FOXCODE System Variable.

Note:
Although this attribute is required, an empty value is permitted.

type

attribute

reportdata

Shared with Class Designer MemberData. Can be used, with the name attribute, to filter and manage records in a global store.

Note:
When the default Report Builder Application creates Report MemberData, it places the value "R" in the type attribute, to distinguish these records from other types of MemberData.

script

attribute

reportdata

Shared with Class Designer MemberData, and specified, similarly to its use in class design, for use in reporting design-time extensions.

class

attribute

reportdata

Specified to hold the name of a class to be used for any and all of the following:

  • A template at design time, from which Report Builder extensions may apply attributes. Report Builder extensions which take this approach should document the attributes they transfer from the template class to the report or label element.

  • A helper class for designing the report or label element. Report Builder extensions taking this approach should specify a required interface for such classes and invoke the specified methods during design events. The helper class has access to the Report Builder's private data session and copy of the report or label table.

  • A helper class associated with the design-time script element. Report Builder extensions taking this approach can send the script to the helper class for processing, or they can run the script directly, sending a reference to the helper object as a parameter to the script.

  • A template class instantiated at run time by a ReportListener. The ReportListener can transfer attributes dynamically from the template class, documenting the set of attributes to be transferred. This approach allows all layout elements, in all reports, to share in changes you make to the template class, emulating class inheritance.

  • A helper class instantiated by a ReportListener to aid run-time processing of a specific report layout element and associated with run-time script processing.

classlib

attribute

reportdata

Specified to hold the name of the class library or procedure file (.vcx or .prg) from which the helper or template class will be instantiated. Reporting extensions should assume a file extension of vcx if none is included. Note that the class library or procedure file must be accessible to the extension. For a summary of how Visual FoxPro finds class definition, refer to the Remarks section of SET CLASSLIB Command.

declass

attribute

reportdata

Specified to hold the name of a DataEnvironment class in a visual class library (.vcx) to be used as a template for Cursor and Relation records in this report or label in the default Report Builder Application's implementation of the Load DataEnvironment event. The Report Builder Application also writes code binding an instance of this class to the report's run-time DataEnvironment events. For more information, see How to: Load Data Environments for Reports.

Note:
The Report Builder Application uses the header record (first record) in the report or label definition table to store DataEnvironment class information, because this information is global to the report. It is good practice to follow this convention, storing global data in the first record's XML MemberData document. In the run-time example included in this topic, a run-time reporting extension opts to check this record for script appropriate to the BeforeReport and AfterReport events. These events are global in nature and not associated with any specific report or label layout element or record.

declasslib

attribute

reportdata

Specified to hold the filename of the visual class library or procedure file from which the DataEnvironment class should be instantiated, when the declass attribute holds the name of a DataEnvironment class, as described above. As an alternative, the default Report Builder Application offers users the ability to associate DataEnvironment records from another report or label (.frx or .lbx file) with the report. When users make this choice, the Report Builder Application stores the name of the report or label used as the DataEnvironment template in this attribute.

execute

attribute

reportdata

Specified for script used in run-time reporting extensions.

execwhen

attribute

reportdata

Specified for conditions to be evaluated by run-time reporting extensions to determine if, and when, the script contents of the execute attribute should run.

Tip:
As shown in the example code in this topic, execwhen conditions can be evaluated flexibly; unlike the Print When conditions in a report they do not have to evaluate directly to a logical result.

Report XML MemberData at Design Time

As described in the table above, the Report Builder Application uses the declass and declasslib attributes of the Report XML MemberData stored in the header record of the report or label definition file. By default, it does not use any other MemberData you store in the report or label. However, you can easily leverage the Report Builder Application's extension architecture to read and use the XML.

The following class implements the Report Builder Application's exit handler mechanism. When registered with the Report Builder Application, this class receives information about the Report Designer event that occurred and whether the Report Builder Application made any changes to the current report layout element. If the layout element contains text, and if changes occurred, the handler object checks for a template class in the XML MemberData. If one exists, and if it has a property with the name Fontname, the handler asks the user whether the template class's font should be applied to the report layout element.

Note:
For more information on registering custom handlers and filters in the Report Builder Application's registry table and implementing the required API, see Report Builder Event Handler Registry Table. Use of the exit handler mechanism is convenient, but illustrates only a fraction of the potential you have for design-time interactions using Report Designer event hooks and Report XML MemberData.

Copy Code
DEFINE CLASS TemplateObjectHandler AS Custom
* register this as an exit handler
PROCEDURE Execute( oEvent )
  IF BITTEST(oEvent.ReturnFlags,1) AND ;
    INLIST(FRX.ObjType,5,8) AND NOT EMPTY(FRX.STYLE)
    LOCAL lcAlias, loX
    lcAlias = "T"+SYS(2015)
    TRY
      XMLTOCURSOR(FRX.Style,lcAlias)
      SELECT (lcAlias)
      IF NOT EMPTY(Class) AND ;
        MESSAGEBOX("(Re)apply Font from Template Object?",4) = 6
        IF EMPTY(ClassLib)
          loX = CREATEOBJECT(ALLTRIM(Class))
        ELSE
          loX = NEWOBJECT(ALLTRIM(Class),ALLTRIM(Classlib))
        ENDIF
        IF VARTYPE(loX) = "O" AND ;
          PEMSTATUS(loX,"Fontname",5)
          REPLACE Fontface WITH loX.Fontname IN FRX
        ELSE
          MESSAGEBOX("Could not apply template.")
        ENDIF
      ENDIF
    CATCH WHEN .T.
      * not valid XML
      * or other error occurred
    FINALLY
      IF USED(lcAlias)
        USE IN (lcAlias)
      ENDIF
      SELECT FRX
    ENDTRY
  ENDIF
  RETURN .T.
ENDPROC
ENDDEFINE

Report XML MemberData at Run Time

The following example leverages the run-time effects processing architecture suggested in Considerations for Creating New Report Output Types.

The superclass in the example, FXMemberData is a custom-derived class implementing the simple FX API, and suitable for being called from an instance of the FXListener class, as described in that topic. FXMemberData is an effect object with the ability to read and parse Report XML MemberData, placing the results in a cursor indexed on a column, FRXRecno, associating each record with the elements of the original report or label definition table.

FXMemberData performs its service at the beginning of the report run. For the rest of the report run, if the value of its ApplyMemberData member is set to True (.T.), FXMemberData positions the record pointer of its cursor appropriately for the current report event, but does not take any other action.

Having this type of object avoids the necessity of having each ReportListener or effect object requiring access to the structured metadata parse the XML document separately. With the metadata easily accessible to them in this common cursor, each object using the data can SELECT the columns of interest to it into a separate, private cursor, with additional columns for dynamic changes they might want to make at run time for their own purposes.

Note:
To find the relevant cursor created by FXMemberData or a similar provider, other objects can investigate the FRXDataSession to find a cursor of the correct structure, parsing the XML themselves if they cannot find one. Alternatively, they can observe a simple convention, shown here as MemberDataAlias, of a ReportListener property holding the appropriate alias. Notice that FXMemberData uses the AddProperty Method to attach this property to any ReportListener.

A second class derived from FXMemberData, FXProcessMemberDataScript, shows you some strategies for using the Execute and ExecWhen attributes of Report XML MemberData. This class evaluates ExecWhen to determine when to invoke the script in Execute. If it determines that it should process the script, it checks to see if a PARAMETERS or LPARAMETERS line is the first line in the script. If not, it prepends a LPARAMETERS statement to the script, to allow it to pass all the parameters received by the ApplyFX method of the effect class API, which effectively allow effect objects to handle and adjust all report events' parameters. The LPARAMETERS statement it creates also includes a reference to the FX object as the first parameter, before all the parameters received in the ApplyFx method. Having made these adjustments, it uses the EXECSCRIPT( ) Function to process the script, passing these parameters to the script.

Copy Code
* to use this class, follow the pattern
* illustrated for use of the FXListener class,
* as follows :
LOCAL loPrimaryRL
* the following line assumes availability of
* the class definition for FXListener listed in
* code example in the topic
* Considerations for Creating New Report Output Types:
loPrimaryRL = CREATEOBJECT("FXListener")
* add successor ReportListeners if desired
loPrimaryRL.FXs.Add("FXProcessMemberDataScript")
* or use its superclass if you don't
* need script processing but want to
* parse the XML MemberData:
* loPrimaryRL.FXs.Add("FXMemberData")
* add other effect objects to the collection
* as required

* Effect class suitable for calling
* by FXListener example class

* Because it works with unknown attributes
* and unknown memberdata requirements,
* FXMemberData requires that the values you use
* for all custom attributes be evaluated by
* XMLTOCURSOR() as a string.  Values
* that do not evaluate as a string will error.
* This behavior makes it possible
* for you or other users to use multiple data types
* for the same custom attributes on different FRX
* records.
* When you use a non-string value, you should
* re-datatype it as appropriate for use in your code.
* (Use EVAL() or otherwise translate the data
* type as needed.)

DEFINE CLASS FXMemberData AS Custom
   MemberDataAlias = ""
   ApplyMemberData = .F.
   PROCEDURE ApplyFX(toListener, tcProgram,;
                     tP1, tP2, tP3, tP4, tP5, tP6, ;
                     tP7, tP8, tP9, tP10, tP11, tP12)
      LOCAL liSession, liSelect, llInBeforeReport
      llInBeforeReport = (ATC("BeforeReport", tcProgram) > 0)
      IF (llInBeforeReport OR THIS.ApplyMemberData) AND ;
         (TYPE("toListener.FRXDataSession") = "N" AND ;
              toListener.FRXDataSession > -1)
         liSession = SET("DATASESSION")
         SET DATASESSION TO (toListener.FRXDataSession)
         liSelect = SELECT()
         IF llInBeforeReport
             * pull the memberdata out of the FRX for later use
             THIS.PullMemberData(toListener)
         ENDIF
         IF THIS.ApplyMemberData
            * this FX object
            * might apply the results of
            * the memberdata pull
            * or it might just make them
            * available to other FX objects
            * after the initial read
            SELECT (THIS.MemberDataAlias)
            THIS.UseMemberData(;
                 toListener, tcProgram,;
                 @tP1, @tP2, @tP3, @tP4, @tP5, @tP6, ;
                 @tP7, @tP8, @tP9, @tP10, @tP11, @tP12)
         ENDIF
         SELECT (liSelect)
         SET DATASESSION TO (liSession)
      ENDIF
   ENDPROC
   PROTECTED PROCEDURE UseMemberData(toListener, tcProgram,;
                        tP1, tP2, tP3, tP4, tP5, tP6, ;
                        tP7, tP8, tP9, tP10, tP11, tP12)
       LOCAL lnFRXRecno
       lnFRXRecno = -1
       DO CASE
       CASE ATC(".Before",tcProgram) > 0 OR ATC(".After",tcProgram) > 0
          DO CASE
          CASE RAT("REPORT",UPPER(tcProgram)) = (LEN(tcProgram)-5)
             lnFRXRecNo = 1
             * pull global data
          CASE VARTYPE(tP2) = "N" && Band events
             lnFRXRecNo = tP2
          OTHERWISE
             * called inappropriately
          ENDCASE
       CASE VARTYPE(tP1) = "N"  && Render, other events
          lnFRXRecno = tP1
       OTHERWISE
          * called inappropriately
       ENDCASE
       IF NOT SEEK(lnFRXRecno,THIS.MemberDataAlias,"FRXRecno")
          lnFRXRecno = -1
       ENDIF
       RETURN (lnFRXRecno # -1)
   ENDPROC
   PROTECTED PROCEDURE PullMemberData(toListener)
      LOCAL lcAlias, lcTempAlias, lcAttributes, liIndex, loAttr
      IF TYPE("toListener.MemberDataAlias") = "C" AND ;
         NOT EMPTY(toListener.MemberDataAlias)
         lcAlias = toListener.MemberDataAlias
      ELSE
         lcAlias = "M"+SYS(2015)
         toListener.AddProperty("MemberDataAlias", lcAlias)
         * "publish" this for others in case they want it
      ENDIF
      THIS.MemberDataAlias = lcAlias
      lcTempAlias = "T" + SYS(2015)
      CREATE CURSOR (lcAlias)  ;
                    (FRXRecno I, Name M, Type M, ;
                     ExecWhen M, Execute M, Class M, ;
                     ClassLib M, DEClass M, DEClassLib M)
      * we're going to take every attribute, whether
      * we understand the column or not,
      * but we'll start off with the
      * core set minus script since script attribute is
      * officially reserved for design-time use
      lcAttributes = ;
          "|FRXRecno|ExecWhen|Execute|Class|" + ;
          "Classlib|Name|Type|DEClass|DEClassLib|"
      SELECT FRX
      SCAN FOR NOT EMPTY(Style)
          TRY
             XMLTOCURSOR(Style,lcTempAlias)
          CATCH WHEN .T.
             * not valid XML
          FINALLY
             IF USED(lcTempAlias)
                IF RECCOUNT(lcTempAlias) > 0
                   SELECT (lcTempAlias)
                   FOR liIndex = 1 TO FCOUNT()
                       IF ATC("|"+FIELD(liIndex)+"|",lcAttributes) = 0
                          ALTER TABLE (lcAlias) ;
                           ADD COLUMN (FIELD(liIndex)) M
                          lcAttributes = lcAttributes + ;
                           FIELD(liIndex) + "|"
                       ENDIF
                   ENDFOR
                   SCATTER MEMO NAME loAttr
                   INSERT INTO (lcAlias) FROM NAME loAttr
                   REPLACE FRXRecno WITH RECNO("FRX") IN (lcAlias)
                ENDIF
                USE IN (lcTempAlias)
             ENDIF
          ENDTRY
          loAttr = NULL
       ENDSCAN
       SELECT (lcAlias)
       INDEX ON FRXRecno TAG FRXRecno
   ENDPROC
ENDDEFINE

DEFINE CLASS FXProcessMemberDataScript AS FXMemberData
   ApplyMemberData = .T.
   PROTECTED PROCEDURE UseMemberData(toListener, tcProgram,;
                        tP1, tP2, tP3, tP4, tP5, tP6, ;
                        tP7, tP8, tP9, tP10, tP11, tP12)
       IF DODEFAULT(toListener, tcProgram,;
                    @tP1, @tP2, @tP3, @tP4, @tP5, @tP6, ;
                    @tP7, @tP8, @tP9, @tP10, @tP11, @tP12)

          * We are now positioned on the correct
          * record by the parent class,
          * and can take action based on the memberdata contents.
          * For example, if we're in BeforeReport,
          * we could instantiate a collection of the appropriate
          * template objects for each label or text record that has a
          * class and classlib available.
          * For each EvaluateContents or Render
          * event we can call methods of the class or
          * apply font attributes to the runtime result.
          LOCAL loMemberdata, llExecute
          SCATTER MEMO NAME loMemberdata
          IF NOT EMPTY(loMemberdata.Execute)
             IF EMPTY(loMemberdata.ExecWhen)
                llExecute = .T.
             ELSE
                DO CASE
                CASE ATC(loMemberData.ExecWhen,tcProgram) > 0
                   * simple event evaluation
                   * ExecWhen contains an event name
                   * Note that each event, via script,
                   * could potentially change the contents of
                   * ExecWhen to hold another value (the next
                   * event during which this script
                   * should be evaluated)
                   llExecute = .T.
                CASE (TYPE(loMemberdata.ExecWhen) = "L") AND ;
                   EVALUATE(loMemberdata.ExecWhen)
                   * ExecWhen contains a logical expression
                   * to be evaluated
                   llExecute = .T.
                CASE ATC(SUBSTR(tcProgram,RAT(".",tcProgram) + 1),;
                         loMemberData.ExecWhen) > 0
                   * ExecWhen contains a delimited string of events
                   llExecute = .T.
                ENDCASE
             ENDIF
             IF llExecute
                IF NOT (BETWEEN(ATC("PARAM", ;
                        ALLTRIM(CHRTRAN(loMemberData.Execute,;
                        CHR(10)+CHR(13), ;
                        SPACE(2)))),1,2))
                   * add a parameters statement; this adjustment
                   * should just happen the first time
                   * any FRX record is processed.
                   loMemberData.Execute = ;
                   "LPARAMETERS toFX, toListener, tcProgram,;"+ ;
                    CHR(13) + CHR(10) + ;
                   "tP1, tP2, tP3, tP4, tP5, tP6,"+;
                   "tP7, tP8, tP9, tP10, tP11, tP12" + ;
                    CHR(13) + CHR(10) + ;
                   loMemberData.Execute
                   REPLACE Execute WITH loMemberData.Execute
                ENDIF
                ExecScript(loMemberData.Execute,;
                    THIS, toListener, tcProgram,;
                    @tP1, @tP2, @tP3, @tP4, @tP5, @tP6, ;
                    @tP7, @tP8, @tP9, @tP10, @tP11, @tP12)
             ENDIF
          ENDIF
       ENDIF
   ENDPROC

ENDDEFINE

To use a script-processing effect of this nature, you could add the following XML MemberData document to a Field or Expression control in the report layout holding a numeric value. This example provides automatic color changes for numeric values below 0, using the EvaluateContents event, and formats the negative numbers with parentheses, using the Render method.

Tip:
Notice that the ExecWhen attribute indicates the script should be processed at these two points by specifying a delimited string ("|EvaluateContents|Render|"). This is one of several alternative means of evaluating ExecWhen provided by the FXProcessMemberDataScript class.

Copy Code
<VFPData>
<reportdata name="" type="R" script=""
execwhen="|EvaluateContents|Render|"
execute=
"DO CASE
 CASE ATC(&quot;Render&quot;,tcProgram) &gt; 0
  * Render's 7th parameter is
  * cContentstoBeRendered
  * notice the conversion from Unicode to DBCS
  tP7 = VAL(STRCONV(tp7,6))
  IF tp7 &lt; 0
     tP7 =  &quot;(&quot;+TRANS(ABS(tp7)) + &quot;)&quot;
  ELSE
     tP7 = TRANS(tP7)
  ENDIF
  * convert back to Unicode for use by the native ReportListener:
  tP7 = STRCONV(tp7,5)
OTHERWISE
  * EvaluateContents' second parameter
  * is objProperties
   IF VARTYPE(tP2.value) = "N" AND ;
      tP2.value &lt; 0
      tP2.penred = 255
      tP2.penblue = 0
      tP2.pengreen = 0
      tP2.reload = .T.
   ENDIF
ENDCASE"
class="" classlib="" declass="" declasslib=""/>
</VFPData>
Tip:
The well-formed XML document above shows a number of escaped character references within the script; for example, a character such as < must be stored as the entity reference &lt; when it is part of the value of an attribute or element node in XML. When you create the script using the Report Builder Application's Run-time Extensions text box interface, you can type these characters as you normally do, without using the entity references. The Report Builder Application stores the document properly, escaping the characters as necessary, when you save the XML.

The following class is another class definition following the FX API. Unlike FXMemberData and its derived classes, FXMemberDataAware does not understand XML and does not read the MemberData directly. Instead, it reads the cursor produced by FXMemberData and understands its structure. If it finds the cursor in its environment, it uses the cursor, adding columns if desired. If the cursor is not available, it provides a temporary instance of FXMemberData during the BeforeReport method, so this temporary object can create the cursor.

FXMemberDataAware is an abstract class, performing no service during the report run. However, you can derive many FX classes from FXMemberDataAware, each with a specialized purpose. If you add instances of each FX to an FXListener's collection, they all share the same MemberData cursor during the report run. They can also create private MemberData extension cursors related to the shared cursor, as needed.

Copy Code
DEFINE CLASS FXMemberDataAware AS Custom

   MemberDataAlias = ""
   HasMemberData = .F.

   PROCEDURE ApplyFX(toListener, tcProgram,;
                     tP1, tP2, tP3, tP4, tP5, tP6, ;
                     tP7, tP8, tP9, tP10, tP11, tP12)

      IF ATC("BeforeReport",tcProgram) > 0
         THIS.VerifyMemberData(toListener)
      ENDIF

      IF ATC("AfterReport",tcProgram) > 0
         THIS.DetachMemberData(toListener, .T.)
      ENDIF

    ENDPROC

   PROCEDURE VerifyMemberData(toListener)
      IF toListener.FRXDataSession = -1
         RETURN .F.
      ENDIF
      LOCAL loMemberData, liSelect, liSession
      liSession = SET("DATASESSION")
      SET DATASESSION TO (toListener.FRXDataSession)
      liSelect = SELECT()
      IF (EMPTY(THIS.MemberDataAlias) OR ;
         (NOT USED(THIS.MemberDataAlias)))
         * can be supplied by the Listener
         * by leveraging a different FX object,
         * but might not be, so in this case
         * let's scarf it up with a temporary object
         IF (NOT PEMSTATUS(toListener,"MemberDataAlias",5)) OR ;
            EMPTY(toListener.MemberDataAlias)
            THIS.MemberDataAlias = "M" + SYS(2015)
            toListener.AddProperty("MemberDataAlias", ;
                        THIS.MemberDataAlias)
         ELSE
            THIS.MemberDataAlias = toListener.MemberDataAlias
         ENDIF
         IF NOT USED(THIS.MemberDataAlias)
            * could be sharing
            loMemberData = NEWOBJECT("FXMemberData")
            loMemberData.MemberDataAlias = THIS.MemberDataAlias
            loMemberData.ApplyMemberData = .F.
            loMemberData.ApplyFX(toListener, "BeforeReport")
            SET DATASESSION TO (toListener.FRXDataSession)
            IF USED(THIS.MemberDataAlias)
               * we can proceed...
               THIS.AlterMemberDataInfo()
            ENDIF
          ENDIF
       ENDIF
       THIS.HasMemberData = USED(THIS.MemberDataAlias)
       SELECT (liSelect)
       loMemberData = NULL
       SET DATASESSION TO (liSession)
       RETURN THIS.HasMemberData
    ENDPROC

    PROTECTED PROCEDURE AlterMemberDataInfo()
      * Hook for derived classes
      * to add their own columns,
      * or even to create private cursors
      * in the FRX Data session that
      * function in relation to the MemberData
      * shared cursor.
    ENDPROC

    PROCEDURE DetachMemberData(toListener, tlCloseMemberDataTable)
       IF tlCloseMemberDataTable AND toListener.FRXDataSession > -1
          LOCAL liSession
          liSession = SET("DATASESSION")
          SET DATASESSION TO (toListener.FRXDataSession)
          IF USED(THIS.MemberDataAlias)
             USE IN (THIS.MemberDataAlias)
             IF PEMSTATUS(toListener,"MemberDataAlias",5)
                toListener.MemberDataAlias = ""
             ENDIF
          ENDIF
          SET DATASESSION TO (liSession)
       ENDIF
       THIS.MemberDataAlias = ""
       THIS.HasMemberData = .F.

    ENDPROC

ENDDEFINE

See Also

Reference

ReportListener Object
BeforeReport Event
AfterReport Event
Render Method
EvaluateContents Event

Other Resources

Extending Reports at Design Time
Extending Reports at Run Time


Using GDI+ in Reports

Visual FoxPro 9.0
Using GDI+ in Reports
See Also

Visual FoxPro 9's object-assisted reporting mode leverages Microsoft Windows GDI+ to render to output devices. GDI+ offers new opportunities for high-quality, extensible output, and also mandates some changes in native output behavior. This topic describes some aspects of creating output associated with use of GDI+.

GDI+ Features in Visual FoxPro Object-Assisted Output

When you use Visual FoxPro's object-assisted reporting mode, output is rendered by a ReportListener-derived object. The following table lists ways in which ReportListener's features and native behavior are affected by GDI+.

Device-independent and resolution-independent rendering

GDI+ provides a graphics object, an extra layer of abstraction beyond the device context of GDI. The graphics object is capable of rendering output identically to disparate devices such as screens and printers. You can expect a high degree of consistency between preview and print output in Visual FoxPro's object-assisted reporting mode. The graphics object's methods for laying out text and graphics are resolution-independent, so Visual FoxPro can render pages to printers at different resolutions, according to the capabilities of each printer.
Note:
Because Visual FoxPro respects the print resolutions available on each printer, you may see some changed behavior in reports with saved printer environments. If the printer setup with which the report was saved during report design had a different resolution than the printer you specify when running the report, the page may not scale properly on the page. In Visual FoxPro 9, you can override printer setup instructions with explicit instructions in a separate field, including explicit instructions to use a particular print resolution regardless of printer (assuming the printer supports the resolution you set). However, in most cases, you have no need to do so; simply removing the printer environment from the report provides better results.

Tip:
In Visual FoxPro 9, unlike previous versions, the printer environment is not saved to the report or label definition by default. For more information about using override settings for printer environments, see Understanding and Extending Report Structure. For more information about printer environments in reports, see How to: Save the Printer Environment for Reports.

Differences in kerning and text widths from output in earlier versions

GDI+'s device- and resolution- independent methods of drawing text ensure that a specific string will fit into the same rectangular space in a layout when it is rendered on different devices. However, the algorithms in GDI+ that measure strings, handle kerning (or spacing) of individual letters in strings, and align strings in the layout rectangle are significantly different from the Report Engine's original algorithms used for this purpose. If you have defined the width for expressions very exactly in an existing report, in some cases the same data will no longer fit. You may be able to widen the expressions appropriately by adding just a few pixels. You can use the Report Builder's Size and position in layout options convenient for this purpose. For more information, see General Tab, Report Control Properties Dialog Box (Report Builder).
Tip:
As in earlier versions of Visual FoxPro, numeric expressions that do not fit in their assigned layout rectangle are represented by asterisks in report output, to avoid providing a number that looks correct but is actually truncated. If you see asterisks in an expression when you switch a report to object-assisted mode, and if you think that the number should fit into the space, check to see if it has a picture template assigned. All versions of Visual FoxPro use the picture template to determine how much space the number needs for display. If you used a template such as 99,999.99, for example, your output may display as asterisks even if the actual number has fewer digits. To ensure that the output displays properly in object-assisted mode, you can widen the layout element enough to display 99,999.99 with the element's designated font attributes. However, if the picture template has more digits than your anticipated data results, you may only need to remove a digit from the template. For more information, see Format Expressions for Field Controls.

When strings do not fit in their assigned layout rectangle, GDI+ provides a way to let the user know that the entire output is not displayed. The ReportListener class takes advantage of this GDI+ feature for output that does not represent numbers, with its StringTrimming options, described in the next section.
Note:
Visual FoxPro's Report System, in all versions, ignores the layout rectangle when displaying calculated fields that have picture templates. As a result, the differences between object-assisted output and backward-compatible output described here do not apply to calculated fields. For example, a field set to Sum and given a picture template of 999,999,999 in a layout rectangle that is too small to fit all the characters in the template will display its full text; it will not be truncated. For more information, see How to: Perform Calculations in Field Controls and Format Expressions for Field Controls.

StringTrimming Options

GDI+ provides multiple ways for you to handle text that does not fit in its assigned layout rectangle. The ReportListener class exposes its various options as described in the table below. When you are designing a report or label, the Report Builder allows you to pick from these options in the Report Control Properties dialog box. For additional information about selecting one of the available options while designing a report, see Format Tab, Report Control Properties Dialog Box (Report Builder).

Value StringTrimming Type

0

Not specified, default will be used.

1

StringTrimmingCharacter

Trims strings that do not fit at the nearest character.

2

StringTrimmingWord

Trims strings that do not fit at the nearest word.

3

StringTrimmingEllipsisCharacter

Trims strings that do not fit at the nearest character and adds an ellipsis (…).

4

StringTrimmingEllipsisWord (Visual FoxPro default)

Trims strings that do not fit at the nearest word and adds an ellipsis (…).

Note:
Trimming the string based on the word rather than character level most closely emulates the trimming behavior of Visual FoxPro when it runs reports and is not in object-assisted mode. Adding the ellipsis allows users to see when some content is missing. Because GDI+ requires slightly more space for text expressions than GDI did, this setting allows you to check older reports for expressions that require widening for GDI+ rendering to handle their contents.

5

StringTrimmingEllipsisPath

Replaces an inner portion of strings that do not fit with an ellipsis (…).

Note:
This value is useful for path- and file- names. For example, the string C:\PROGRAM FILES\MICROSOFT VISUAL FOXPRO 9\REPORTOUTPUT.APP can render as C:\PROGRAM FILES\…\REPORTOUTPUT.APP.
DynamicLineHeight feature

GDI+ line spacing is the default method of handling line spacing for ReportListener objects that render multi-line text. GDI+ line spacing allows for a more polished appearance, faster performance, and fewer pages for the same report content than the Report Engine's original line-spacing algorithms. However, GDI+ line spacing changes the amount of space your text takes up in the layout when you compare the rendered results to previous versions of Visual FoxPro. ReportListener's rendering strategy for text spanning multiple lines changes according to the value of its DynamicLineHeight property. This value determines whether the ReportListener uses GDI+ standard (dynamic) line spacing according to font characteristics, or the backward-compatible fixed line spacing used by Visual FoxPro when it runs reports and labels but is not in object-assisted mode. For more information, see DynamicLineHeight Property.
Availability of output page images

When an application renders to a particular drawing surface using GDI+, GDI+ provides methods to save the contents of the drawing surface to various image file types. Visual FoxPro exposes this capability in the ReportListener's OutputPage method. For more information, see OutputPage Method.
Availability of transparency values in color settings

GDI+ specifies colors using ARGB (alpha or transparency, red, green, and blue) components. Visual FoxPro report and label definition files do not have a way of storing the transparency value, so colors stored in .frx and .lbx tables are always completely opaque or transparent. However, Visual FoxPro exposes the transparency values to ReportListener code at run time, in the EvaluateContents event. You can use this event dynamically set text and text background colors to different degrees of transparency, and cause blends to occur in overlaid, semi-transparent layout elements. For more information, see EvaluateContents Event.

Using GDI+ in User Code during Report Runs

Your code can take advantage of GDI+ capabilities in reports. Visual FoxPro 9 ships with a suite of wrapper classes for the GDI+ API to facilitate your use of these features. For more information, see GDI Plus API Wrapper Foundation Classes.

Your use of GDI+ during a report run takes one of two forms:

  • You use GDI+ to render to the drawing surface the ReportListener uses for native output. In this scenario, you can dynamically place new output elements or alter existing ones directly into the running report. The ReportListener class exposes a handle to its own graphics object, during a report run, for this purpose. For more information, see GDIPlusGraphics Property. As explained in that topic, and as shown in the topic's sample code, to use the native ReportListener's graphics object, you must use functions based in the same file copy of GDIPLUS.DLL that the product uses in native code. To ensure that you use the correct copy of GDIPLUS.DLL, use the syntax IN GDIPLUS.DLL with no explicit path in your DECLARE DLL statements. For more information, see DECLARE - DLL Command.

  • You supply the ReportListener object with a handle to a separate graphics object, and ask it to draw an output page to this additional graphics object. In this scenario, you do not accomplish your goal by temporarily assigning a different handle to the ReportListener's GDIPlusGraphics property; for safety reasons, that handle is read-only. Instead, you supply the ReportListener with the additional handle as one of the parameters to the OutputPage method. The ReportListener's GDIPlusGraphics handle, and the native output stream, remain undisturbed by this process. For more information, see OutputPage Method.

See Also

Reference

SET REPORTBEHAVIOR Command

Concepts

Understanding Visual FoxPro Object-Assisted Reporting


Creating International Applications

Visual FoxPro 9.0
Creating International Applications

This section describes how to create applications that are compatible and effective in international markets.

In This Section

How to: Enter International Data

Discusses understanding how to enter data for international applications.
How to: Set Date, Time, and Currency Formats

Describes the various methods for localizing date, time, and currency formats.
Code Pages in Visual FoxPro

Explains how data stored in Visual FoxPro often is tagged with a code page, which is a table of characters and corresponding numbers in memory that Microsoft Windows uses to display data properly.
Sorting Data in International Applications

Discusses sort orders and presents methods for implementing and validating sort processes.
Modifying International Applications

Describes how you can prevent localization problems with code by observing certain guidelines.
Reporting Features for International Applications

Discusses features of the Visual FoxPro Report System of special interest to developers of international applications.

Related Sections

Developing International Applications

Describes planning and developing applications for international distribution.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Creating Applications

Discusses how to create Visual FoxPro applications, which may include one or more databases, a main program that sets up the application's system environment, and a user interface comprised of forms, toolbars, and menus.


How to: Enter International Data

Visual FoxPro 9.0
How to: Enter International Data
See Also

An important aspect of developing international applications is knowing how to enter data into your application. Data can come into your application in two ways:

  • Users enter the data.

  • You or your users import the data from existing files.

The following sections discuss these two methods.

Entering International Characters

You can enter international characters into Visual FoxPro using your keyboard. The exact method you use depends on the language you're working with. In single-byte character environments, you can enter the characters directly, or by pressing a combination of keys on the keyboard. On the other hand, double-byte character set (DBCS) environments often provide an Input Method Editor (IME), which is an application you can use to enter characters.

Entering Characters Using the Keyboard

With an international keyboard you can display international characters by simply pressing the keys dedicated to those characters. If your keyboard doesn't have keys for international characters, you can enter such characters by using the character map provided with Windows (available from the Accessories menu) or by pressing the ALT key in conjunction with keys on the numeric keypad.

For instance, to type (ANSI code 246), press NUM LOCK on the numeric keypad, and then press ALT+0246. Be sure to use a standard Windows font — not FoxFont or FoxPrint.

Tip:
The status bar on the character map shows the key combination that corresponds to each character selected on the map.

Note:
You cannot enter international characters in FoxFont. For example, if you open the Command window, switch to FoxFont, and then press a dedicated key, the result isn't the character on the key. For best results, avoid FoxFont in international applications.

Troubleshooting

If characters don't transport correctly, see if you're using FoxFont. For example, FoxFont is the default for user-defined windows created with the DEFINE WINDOW Command (if the FONT clause is omitted). Be sure to use the FONT clause to specify a font other than the standard Windows font when creating user-defined windows so that international characters display correctly.

Entering Characters Using an IME

If you're working in an IME environment, you can use an Input Method Editor to enter characters into Visual FoxPro. The IME is an application provided with your environment that makes it possible for you to type characters on the keyboard to display a selection of international characters and then choose the specific character you want. For example, an IME for Chinese might make it possible for you to enter a Pinyin representation of a Chinese word and then display a list of characters that match the representation. When you select the character you want, the IME pastes it into Visual FoxPro.

You can control when Visual FoxPro displays an IME by setting the IMEMode Property or calling the IMESTATUS( ) Function. If you turn the IME window on, Visual FoxPro automatically displays the IME when you're editing in a system window such as the Browse or Edit windows. If you turn the IME window off, you can invoke the IME by pressing the appropriate keys on your keyboard.

Appending and Copying International Data

If you're importing or copying data from delimited files using the APPEND FROM Command or COPY TO Command, you can specify what character is being used in the file to separate fields. For example, it's common in many European countries to use a semicolon (;) as a field delimiter, whereas the common delimiters in the United States are comma (,), tab, or space.

To import or copy files and specify a delimiter, add the DELIMITED WITH CHARACTER clause to the APPEND FROM or COPY TO commands:

Copy Code
COPY TO mytxt.txt DELIMITED WITH _ WITH CHARACTER ";"

See Also

Other Resources

Code Pages in Visual FoxPro
How to: Set Date, Time, and Currency Formats
Sorting Data in International Applications
Modifying International Applications
Developing International Applications
Creating International Applications


How to: Set Date, Time, and Currency Formats

Visual FoxPro 9.0
How to: Set Date, Time, and Currency Formats
See Also

To format dates, times, and currency, you can use a variety of formatting techniques. You can:

  • Allow Visual FoxPro to use the settings established in the Control Panel.

  • Specify a language or a specific format in the Visual FoxPro Options dialog box that you want to use.

  • Format dates, times, and currency information in code.

To set a format for dates, times, and currency

  1. From the Tools menu, choose Options, and then click the Regional tab.

  2. To use the settings made with the Windows Control Panel, choose Use system settings.

    -or-

    Choose a language or format for dates and times and then choose options for formatting currency and numbers.

    Note If you choose the format Short or Long for the date format, you cannot specify any further options for the date format, and the settings are read from the Windows Control Panel.

  3. Choose OK to use the options for this session, or Set As Default to make the changes the default settings for this copy of Visual FoxPro.

You can also use the SET SYSFORMATS Command and SET DATE Command. As a rule, you would issue this command during the initialization of your application (for example, in the configuration file). The default for SET SYSFORMATS is OFF, so you must explicitly set it to ON when starting your application.

You can establish data validation in individual text boxes by setting the Format Property of the text box. Note that text box formatting takes precedence over system-wide formatting.

See Also

Other Resources

How to: Enter International Data
Code Pages in Visual FoxPro
Sorting Data in International Applications
Modifying International Applications
Developing International Applications
Creating International Applications


Code Pages in Visual FoxPro

Visual FoxPro 9.0
Code Pages in Visual FoxPro

Data stored in Visual FoxPro is often tagged with a code page, which is a table of characters and corresponding numbers in memory that Windows uses to display data properly. For example, if you enter the letter C in a table (.dbf) file, the letter is stored on your hard disk as the number 67. When you open the file, Visual FoxPro determines its code page, inspects the code page to find the character corresponding to the number 67, and then displays the character (C) on your monitor.

Code pages correspond roughly to different alphabets. For example, Windows supplies code pages for English, German, Scandinavian languages, and so on. By using different code pages, applications can properly display characters from these different alphabets.

In This Section

Understanding Code Pages in Visual FoxPro

Describes how Visual FoxPro makes use of code pages to display data. Code pages provide a set of characters specific to a language or hardware platform.
Code Pages Supported by Visual FoxPro

Provides a list of code pages that are supported by Visual FoxPro.
How to: Specify the Code Page of a .dbf File

Explains how to add, remove, and change code page marks for a .dbf file.
How to: Specify the Code Page of a Text File

Explains how to specify a code page for use with a text file.
How to: Determine the Code Page of a Project File

Describes how to determine what code page a file in a project uses.
Specification of Code Pages for Variables

Explains how to use data stored with one code page and translate it to another code page.
How to: Prevent Translation of Data in Character or Memo Fields

Describes how to stop automatic code page translation. Stopping automatic translation is ideal when you may not want data to be translated into another code page, because doing so would alter the data.

Related Sections

Developing International Applications

Describes how to develop and plan Visual FoxPro applications that are compatible and effective in international markets.
Creating International Applications

Describes how to create Visual FoxPro applications that are compatible and effective in international markets.


Understanding Code Pages in Visual FoxPro

Visual FoxPro 9.0
Understanding Code Pages in Visual FoxPro
See Also

Visual FoxPro displays data using one code page. By default, this is the current code page used by Windows. However, you can override the Windows code page by specifying an alternative code page in your configuration file (you must specify a valid code page).

Tables in Visual FoxPro are tagged with the code page that was in use when the table was created. When you use the table, Visual FoxPro checks the code page for the table against the current code page. If they match, Visual FoxPro displays the data as is. If there is no code page for the table (for example, the table was created in an earlier version of FoxPro), Visual FoxPro prompts you for a code page and then marks the file with it.

When reading data from a table tagged with a code page that does not match the system code page, Visual FoxPro attempts to translate characters from the table code page into the current one. For example, if you're using Visual FoxPro and the current system code page is the English code page, the character is represented by ANSI value 252. If the code page for the table represents the character as ANSI value 219, Visual FoxPro translates all instances of ANSI value 219 into ANSI 252 so that they display properly.

Code page translation doesn't work perfectly in all instances, because code pages usually contain characters that are not represented one-for-one in other code pages. For example, you cannot map data that contains the MS-DOS line-drawing characters into Windows because the Windows code pages don't contain line-drawing characters. Similarly, you cannot translate data created in the Russian code page into an English code page because there isn't a one-to-one correspondence between the alphabets for these languages. Finally, Visual FoxPro might not contain a character translation map for a particular code page. In that case the data is displayed with no code page translation. (Visual FoxPro does not display an error to indicate that no code page translation is occurring.) Any of these situations can cause some characters to display improperly.

When writing data to a table tagged with a code page does not match the system code page and character data is modified, Visual FoxPro attempts to translate characters from the current code page into the table one. For example, if you're using Visual FoxPro and the current system code page is the English code page, the character is represented by ANSI value 252. If the code page for the table represents the character as ANSI value 219, Visual FoxPro translates all instances of ANSI value 252 into ANSI 219 so that they are saved properly.

If you want to create an application for a specific locale, you can avoid code page translation problems by creating the application's components using the code page designed for that locale and environment. For example, to create an application for use in Russia, you should use code page 1251. For a complete list, see Code Pages Supported By Visual FoxPro.

If you need to enter some characters not represented by keys on your keyboard, you can enter these characters using ALT in conjunction with keys on the numeric keypad. However, remember that the same key combination in different environments often displays different results. For example, if you enter ALT+0182 with code page 1252 in Visual FoxPro, you see a paragraph symbol. In contrast, if you enter ALT+0182 with code page 437 in FoxPro for MS-DOS, you see a graphic character with a double vertical line meeting a single horizontal line.

Although Visual FoxPro supports many code pages, only a few are used often. Typically, English-speaking users use code page 1252.

When working with code pages, be sure to test that the user interface and data display correctly by using the code page designed for a particular locale. If you see unexpected characters on the screen, check the underlying code page.

See Also

Other Resources

Code Pages in Visual FoxPro
How to: Specify the Code Page of a Text File
Developing International Applications
How to: Determine the Code Page of a Project File
Specification of Code Pages for Variables


Code Pages Supported by Visual FoxPro

Visual FoxPro 9.0
Code Pages Supported by Visual FoxPro
See Also

A code page is a set of characters specific to a language or hardware platform. Accented characters are not represented by the same values across platforms and code pages. In addition, some characters available in one code page are not available in another.

Code page | Platform | Code page identifier
437 | U.S. MS-DOS | x01
620 * | Mazovia (Polish) MS-DOS | x69
737 * | Greek MS-DOS (437G) | x6A
850 | International MS-DOS | x02
852 | Eastern European MS-DOS | x64
857 | Turkish MS-DOS | x6B
861 | Icelandic MS-DOS | x67
865 | Nordic MS-DOS | x66
866 | Russian MS-DOS | x65
874 | Thai Windows | x7C
895 * | Kamenicky (Czech) MS-DOS | x68
932 | Japanese Windows | x7B
936 | Chinese Simplified (PRC, Singapore) Windows | x7A
949 | Korean Windows | x79
950 | Traditional Chinese (Hong Kong SAR, Taiwan) Windows | x78
1250 | Eastern European Windows | xC8
1251 | Russian Windows | xC9
1252 | Windows ANSI | x03
1253 | Greek Windows | xCB
1254 | Turkish Windows | xCA
1255 | Hebrew Windows | x7D
1256 | Arabic Windows | x7E
10000 | Standard Macintosh | x04
10006 | Greek Macintosh | x98
10007 * | Russian Macintosh | x96
10029 | Macintosh EE | x97

* Not detected when you include CODEPAGE=AUTO in your configuration file.

See Also

Other Resources

Code Pages in Visual FoxPro
How to: Prevent Translation of Data in Character or Memo Fields
Sorting Data in International Applications
Developing International Applications
Code Pages in Visual FoxPro
Specification of Code Pages for Variables
Special Terms for Configuration Files
SET COLLATE Command


How to: Specify the Code Page of a .dbf File

Visual FoxPro 9.0
How to: Specify the Code Page of a .dbf File
See Also

When you create .dbf files, Visual FoxPro automatically gives them code page marks so that you can tell which code pages they use. However, if you use .dbf files from previous versions of FoxPro, they might not have code page marks.

You can determine whether a .dbf file has a code page mark by using the CPDBF( ) function after opening the file or by having Visual FoxPro check when you open the file.

To check for code page marks automatically

  1. From the Tools menu, choose Options.

  2. Select the Data tab.

  3. Set the Prompt for code page check box, if it's not already set.

    To save this setting for future sessions of Visual FoxPro, choose Set as Default.

    Tip:
    Instead of setting the Prompt for code page check box, you can use the SET CPDIALOG command to check for code pages.

If a file doesn't have a code page mark, you must add a mark, as described in the following section.

Adding Code Page Marks

If you use a .dbf file from a previous version of FoxPro, the file might not have a code page mark; without such a mark, the file might not display properly. If automatic code page checking is enabled, when you open the file you can tell if it has a code page mark. If it doesn't have one, you can add one.

To manually add a code page mark to a .dbf file

  1. Ensure automatic code page checking is in effect (see the previous procedure).

  2. Open the file.

    If the file doesn't have a code page mark, the Code Page dialog box appears.

  3. Choose the appropriate code page.

  4. View the file to see if you assigned the proper code page.

    If you can't see some of the data, or if you can't recognize some of it, the code page is not correct.

  5. If the code page is incorrect, remove the code page mark by using the CPZERO program in the Visual FoxPro Tools\Cpzero directory.

  6. Repeat this procedure until the code page is correct.

    Note:
    Text files such as program (.prg) and query (.qpr) files don't have code page marks. This means that you can't tell which code pages the files use. However, if you include such files in a project, the project can keep a record of the code pages used. For more information, see How to: Specify the Code Page of a Text File.

Removing Code Page Marks

If a .dbf file doesn't display properly, it might have the wrong code page mark. You can remove the code page mark with the CPZERO program located in Tools\Cpzero. Running CPZERO sets the code page to 0, meaning none.

To remove a code page mark

  • Run CPZERO using the following syntax:

    DO CPZERO WITH "filename", 0

    Note:
    When you remove the code page mark of a .dbf file, the data in the file doesn't change. To change the code page of the data, you must mark the file with the proper code page.

Changing Code Page Marks

You can change the code page of a .dbf file by removing its code page mark and then adding a new one, by copying the file to another file, or by using the CPZERO program.

To change the code page of a .dbf file by copying the file

  • Use the COPY TO command, specifying the target code page with the AS clause. (To set the code page to the current system code page, omit the AS clause.)

    For example, to copy Test.dbf to Test866.dbf, while changing the code page to 866, use the following commands:

    Copy Code
    USE TEST.DBF
COPY TO TEST866.DBF AS 866

When the COPY TO completes, the data in the resulting file will have the new code page.

To change a code page mark using CPZERO

  • Run CPZERO using the following syntax:

    DO CPZERO WITH "filename", newCodePage

    Note:
    Some characters cannot be translated between code pages successfully. In addition, Visual FoxPro doesn't support some code page translations. Always check the results of a code page change to be sure that your data has been translated successfully.

See Also

Other Resources

Code Pages in Visual FoxPro
How to: Specify the Code Page of a Text File
Developing International Applications
How to: Determine the Code Page of a Project File
Specification of Code Pages for Variables


How to: Specify the Code Page of a Text File

Visual FoxPro 9.0
How to: Specify the Code Page of a Text File
See Also

If you forget the code page of a text file that's not part of a project, you cannot determine the code page, because a text file doesn't have a code page mark as .dbf files have. The best way to remember the code page of a text file is to add the file to a project.

To specify the code page of a text file

  1. Open the Project Manager Window.

  2. Select the text file whose code page you want to specify.

  3. From the Project menu, choose Project Info.

  4. In the Project Information Dialog Box, click the Files tab.

  5. Right-click the selected file.

  6. From the submenu, choose Code Page.

    Visual FoxPro displays the Code Page Dialog Box.

  7. Choose the appropriate code page.

    Visual FoxPro displays the available code pages.

If you know the code page of a text file, you can specify it by using the AS clause of the appropriate Visual FoxPro command. For files you want to import or append, you can specify the code page in the IMPORT Command or APPEND Command. For query, program, and other text files already on your computer, you can change the code page using the MODIFY QUERY Command, MODIFY COMMAND Command, and MODIFY FILE Command.

If you're not sure which code page to apply, substitute the GETCP( ) Function for the code page number in the command. GETCP( ) displays the Code Page dialog box, making it possible for you to select the appropriate code page.

Note:
Some characters cannot be translated between code pages successfully. In addition, Visual FoxPro doesn't support some code page translations. Always check the results of a code page change to be sure that your data has been translated successfully.

See Also

Other Resources

Code Pages in Visual FoxPro
How to: Specify the Code Page of a .dbf File
How to: Determine the Code Page of a Project File
Developing International Applications
Specification of Code Pages for Variables
How to: Prevent Translation of Data in Character or Memo Fields


How to: Determine the Code Page of a Project File

Visual FoxPro 9.0
How to: Determine the Code Page of a Project File
See Also

After adding a file to a project, you can determine its code page. The method you use depends on whether the file is a table (.dbf file) or a text file.

To determine the code page of a text file

  1. Open the Project Manager Window.

  2. Under Other, select the text file whose code page you want to know.

  3. From the Project menu, choose Project Info.

To determine the code page of a table

  • Use the CPDBF( ) Function.

When you build an application from a project, the Project Manager automatically integrates the files in the project no matter how many different code pages they have. The resulting application has the current code page.

Note:
When you add a .dbf file to a project, you don't have to specify a code page for the file because Visual FoxPro automatically determines the code page from the file's code page mark. However, when you add a text file to a project, you must specify a code page for the file because Visual FoxPro cannot determine the code page automatically.

To prepare a program for use with another code page, specify the original code page when you save or compile the program on the new platform. For example, to prepare a program created with Visual FoxPro for Macintosh for use with Visual FoxPro, specify the appropriate MS-DOS code page when you save or compile the program with Visual FoxPro. If you use the COMPILE Command, specify the code page using the AS clause. Alternatively, specify the code page with SET CPCOMPILE Command before compiling the program.

See Also

Other Resources

Code Pages in Visual FoxPro
How to: Specify the Code Page of a Text File
Specification of Code Pages for Variables
Developing International Applications
How to: Prevent Translation of Data in Character or Memo Fields
Code Pages Supported by Visual FoxPro


Specification of Code Pages for Variables

Visual FoxPro 9.0
Specification of Code Pages for Variables
See Also

You might want to manipulate international data in certain ways. For example, you might want to translate the data in a variable to another code page, or you might want to prevent translation of data in a character or memo field.

Translating Data in Variables

If the code in your application includes a variable containing data from another code page, you can translate the data to the proper code page using the CPCONVERT( ) function. For example, suppose the variable x contains data created with the Macintosh code page (10000). To translate the data to the Windows code page (1252), issue the following command:

Copy Code
cConvert=CPCONVERT(10000,1252,x)

In Windows, the converted data looks just as you see it on the Macintosh. For example, a character that looks like "" on the Macintosh looks identical in Windows.

See Also

Other Resources

Code Pages in Visual FoxPro
How to: Determine the Code Page of a Project File
How to: Prevent Translation of Data in Character or Memo Fields
Developing International Applications
Code Pages Supported by Visual FoxPro
Code Pages in Visual FoxPro


How to: Prevent Translation of Data in Character or Memo Fields

Visual FoxPro 9.0
How to: Prevent Translation of Data in Character or Memo Fields
See Also

In some cases you don't want automatic code page translation. For instance, if a character field contains an encrypted password, you don't want Visual FoxPro to automatically translate the password because doing so would alter it.

To prevent translation of data in a character or memo field

  1. Open the project containing the table.

  2. Select the table.

  3. Choose the Modify button.

    The Table Designer appears.

  4. Select the field whose data you want to protect.

  5. From the Type list select Character (Binary) for a Character field, or Memo (Binary) for a memo field.

  6. Choose OK, and then choose Yes to make the changes permanent.

  7. Verify the changes by displaying the structure of the table with the DISPLAY STRUCTURE Command.

    Alternatively, use the MODIFY STRUCTURE Command to protect the appropriate fields.

You can also prevent translation of selected characters in text files by using the CHR( ) Function.

See Also

Other Resources

Code Pages in Visual FoxPro
Specification of Code Pages for Variables
Developing International Applications
Code Pages Supported by Visual FoxPro
Code Pages in Visual FoxPro
How to: Determine the Code Page of a Project File


Sorting Data in International Applications

Visual FoxPro 9.0
Sorting Data in International Applications

After creating a table of international data, check to see if your application sorts the data correctly. The code page associated with the table determines the sort order, because the code page specifies the available sort orders or collation sequences.

In This Section

Understanding Sort Orders

Describes how to use sort orders, to make it possible to sort data properly for various languages.
How to: Specify a Sort Order

Explains how to specify a sort order in your application, for subsequent indexing and sorting operations.
Application Creation with Double-Byte Character Sets

Discusses how to use Double-Byte Character Sets, for languages that require more than one byte to represent characters, in your application.

Related Sections

Code Pages in Visual FoxPro

Provides links to topics that explain how data stored in Visual FoxPro often is tagged with a code page, which is a table of characters and corresponding numbers in memory that Microsoft Windows uses to display data properly.
Creating International Applications

Provides links to subjects on how you can design and develop your Visual FoxPro applications so they are as effective internationally as domestically.
Developing International Applications

Provides links to topics that describe how to develop and plan Visual FoxPro applications that are compatible and effective in international markets.


Understanding Sort Orders

Visual FoxPro 9.0
Understanding Sort Orders
See Also

Sort orders incorporate the sorting rules of different locales, making it possible for you to sort data in those languages correctly. In Visual FoxPro, the current sort order determines the results of character expression comparisons and the order in which records appear in indexed or sorted tables.

Note:
Sorting works differently in double-byte character sets (DBCS) environments.

Use the appropriate sort order, because different sort orders produce different results, as shown in the following table.

Unsorted | Machine | General | Spanish
!@#$ | Space | space | Space
1234 | !@#$ | !@#$ | !@#$
space | 1234 | 1234 | 1234
Caesar | Caesar | a | a
csar | Car | ab | Ab
Strasse | Char | b | b
strae | Czech | Caesar | Caesar
Car | Strasse | csar | Csar
Char | Ab | Car | Car
Czech | Csar | ar | ar
ab | Strae | Char | Czech
ar | ar | Czech | Char
a | a | Strasse | Strasse
b | b | strae | Strae

Sort Order Guidelines

Consider the following guidelines when choosing a sort order:

  • Avoid the Machine sort order if you want to sort international characters properly, because Machine sorts international characters in ASCII order. For example, notice that ar follows strae.

  • Characters with diacritical marks sort differently than characters without diacritical marks. For example, in the General and Spanish sort orders, notice that a sorts before ab but ab sorts before b.

  • Ligatures such as sort the same as their equivalent character expansions. For example, strae sorts the same as Strasse, and csar sorts the same as Caesar.

  • In some languages, two characters sort as a single character. For example, in Spanish the Ch in Char sorts as a character between C and D.

The following sections describe how to specify sort orders, check the current sort order, and recognize the effects of sort orders.

Checking Sort Orders

You can determine the current sort order by using the SET ('COLLATE') function. For example, you can save the current sort order, set the current sort order to Machine, perform whatever work is necessary, and then restore the original sort order by using the following code:

Copy Code
cCurrentOrder=SET('COLLATE')
SET COLLATE TO 'MACHINE'
*
* code that requires the Machine sort order
*
SET COLLATE TO cCurrentOrder  && return to the previous sort order

You can also determine the sort order of an index or index tag by using the IDXCOLLATE( ) function.

Recognizing the Effects of Sort Orders

The sort order affects the results of string comparisons, SEEK, and SELECT - SQL, as described in the following sections.

Comparing Strings

All sort orders except for Machine and Unique Weight ignore case. This means that you don't have to use UPPER( ) in your index expressions.

The current sort order affects string comparisons. For example, when you set the sort order to General, the following statements return True (.T.):

Copy Code
?"A" = "a"
?"Strae"="Strasse"
?"" = "ae"

However, when you use the Machine sort order, all of these statements return False (.F.). because the strings are matched for an exact comparison, byte by byte.

The character string comparison operator (= =) gives you the same result as when you compare by value or when you compare using the Machine sort order; that is, it compares strings byte by byte. For example, the following statement returns False (.F.):

Copy Code
? "Strae" == "Strasse"
Note:
Visual FoxPro ignores SET EXACT when you use the character string comparison operator (= =).

Using SEEK

Visual FoxPro ignores diacritical marks when you perform a partial seek. A partial seek occurs when you make the length of the expression less than the length of the key. If diacritics are important, consider using the SCAN ... ENDSCAN or LOCATE commands instead of SEEK.

The advantages of using SCAN and LOCATE instead of SEEK include the following:

  • SCAN and LOCATE are sensitive to diacritics.

  • Visual FoxPro fully optimizes the results of SCAN or LOCATE if the current sort order is Machine or Unique Weight, whereas Visual FoxPro only partly optimizes the results of SEEK.

  • SCAN and LOCATE remember the condition that invoked them, making it possible for you to use them for looping on a condition. In contrast, SEEK positions you somewhere in the index, and SKIP continues down the index from that point. Accordingly, SEEK might not produce the results you want with international data.

Using SELECT - SQL

The SELECT - SQL command uses the current sort order. For example, if you have an index tag based on the General sort order and the current sort order (returned by SET ('COLLATE')) is Machine, the result of SELECT SQL is based on Machine.

To employ the current sort order, use the ORDER BY clause of SELECT - SQL.

Using Indexes

Sort orders determine the order of records in indexed tables. Consider the following guidelines for using indexes with sort orders:

  • Rebuild indexes created in earlier versions of FoxPro if you want the indexes to use a sort order other than Machine.

  • Rebuild dBASE indexes to take advantage of Visual FoxPro sort orders.

  • Use the REINDEX command to rebuild an index, because REINDEX leaves the sort order unchanged.

See Also

Other Resources

Sorting Data in International Applications
Code Pages Supported by Visual FoxPro
Application Creation with Double-Byte Character Sets
Developing International Applications
Data
Modifying International Applications


How to: Specify a Sort Order

Visual FoxPro 9.0
How to: Specify a Sort Order
See Also

You can specify a sort order for character fields used in subsequent indexing and sorting operations.

To specify a sort order

  1. From the Tools menu, choose Options.

  2. Select the Data tab.

  3. In the Collating sequence box, select the appropriate sort order.

    To save this setting for future sessions of Visual FoxPro, choose Set as Default.

    Tip:
    You can also specify a sort order with the SET COLLATE TO command or the COLLATE statement in your Config.fpw file. For details about Config.fpw, see Customizing the Visual FoxPro Environment.

The current sort order doesn't affect previously created indexes; however, it does affect the results of comparisons and commands such as SEEK and SELECT - SQL.

You can change the sort order at any time. For instance, after opening a customer table you can create index tags representing different sort orders, as shown in the following code. Then you can change the sort order by simply using a different tag:

Copy Code
USE customer
SET COLLATE TO "GENERAL"
INDEX ON fname TAG mygeneral ADDITIVE
SET COLLATE TO "MACHINE"
INDEX ON custid TAG mymachine ADDITIVE
SET COLLATE TO "DUTCH"
INDEX ON lname TAG mydutch ADDITIVE
Note:
The sort order for an index overrides the current sort order.

The current code page determines which sort orders are available. If you use the SET COLLATE Command to specify a sort order not supported by the current code page, Visual FoxPro generates an error. Also, if you specify a sort order in Config.fpw that isn't supported by the current code page, the sort order defaults to Machine.

See Also

Other Resources

Code Pages Supported by Visual FoxPro
Application Creation with Double-Byte Character Sets
Developing International Applications
Data
Sorting Data in International Applications


Application Creation with Double-Byte Character Sets

Visual FoxPro 9.0
Application Creation with Double-Byte Character Sets
See Also

Visual FoxPro supports double-byte character sets (DBCS) — character sets that require more than one byte to represent a character. Some examples of languages that require a double-byte character set are Simplified Chinese, Traditional Chinese, and Korean.

Visual FoxPro DBCS support makes it possible for you to create international applications. For example, you can create a Korean application with a U.S. version of Visual FoxPro if you're running the Korean version of Windows. The Visual FoxPro DBCS functions operate properly on the Korean character set, and the Korean collation sequence is supported.

Note:
Visual FoxPro provides special programming functions for use with string in DBCS environments.

Using DBCS Characters When Naming Objects

Visual FoxPro makes it possible for you to use DBCS characters when naming elements of your applications. As with Visual FoxPro generally, elements can:

  • Be up to 254 bytes in length with the combination of double-byte characters and single characters. For example, if you use all double-byte characters, then the name you are creating can be only 127 characters long.

  • Begin with a letter, number, underscore or leading-trailing byte combination.

  • Contain only letters, numbers, underscores, or DBCS characters.

These rules apply to variables, objects (windows, menus, and so on), function and procedure names, class and subclass names, aliases, and constants. You can also use double-byte characters for file names. To avoid the possibility that characters in the file name are inadvertently treated as delimiters, it's safest to always enclose the file name in quotation marks.

Note:
Visual FoxPro length limits are expressed using single-byte characters. Using double-byte characters in field names, index expressions, variable names, window names, and so on, effectively shortens the length of the name. For example, a field name can be up to 10 bytes long in a free table, so a field name can consist of 10 single-byte characters, but only 5 double-byte characters. For more information about Visual FoxPro system capacities, see System Capacities.

Sorting DBCS Data

To help you order information in DBCS environments, Visual FoxPro supports collation sequences for Simplified Chinese, Traditional Chinese, Japanese, and Korean. Collation sequences make it possible for you to properly order character fields in tables for each language.

The following table lists the Visual FoxPro collation sequence options and the corresponding language.

Options | Language
JAPANESE | Japanese
KOREAN | Korean
PINYIN | Simplified Chinese
STROKE | Simplified and Traditional Chinese

For more information, see How to: Specify a Sort Order.

See Also

Other Resources

Sorting Data in International Applications
Modifying International Applications
Developing International Applications
Code Pages Supported by Visual FoxPro
Code Pages in Visual FoxPro


Modifying International Applications

Visual FoxPro 9.0
Modifying International Applications
See Also

You can prevent localization problems with code by observing the following guidelines.

Testing for International Versions

If it's important for your application to be able to determine what language Visual FoxPro is running in, you can call VERSION( ). Knowing the language environment can help you determine what text to display, how to format data, and so on. For example, the following code determines what language environment Visual FoxPro is running in and then runs a language-specific form:

Copy Code
IF VERSION(3) = 34 THEN
   * Running in Spanish--display Spanish form
   DO FORM CST_SPN.SCX
ELSE
   * Display English form
   DO FORM CST_ENU.SCX
ENDIF
Note:
Support for double-byte characters strings has been available in Visual FoxPro only since version 3.0b. If your application is relying on the availability of double-byte character set (DBCS) functions, you should also call the VERSION(1) function to test the Visual FoxPro version number.

Using Strings

Avoid including strings directly in code because they make localization difficult. For instance, don't include dates and currencies as strings in code. If possible, write your code so that it retrieves strings from files or tables separate from the program.

Note:
The performance of your program might suffer if you remove all strings from it. For example, performance might suffer if the program searches for strings while inside a loop.

One way to work with strings in an application that will be translated is to use string constants throughout the application. You can then define the text for these constants in a separate text file that is referenced from your programs using the #INCLUDE preprocessor directive. For example, instead of embedding the error message "file not found," you can use the constant ERR_FILE_NOT_FOUND. The text for this constant could be in a file called ERR_TEXT.H. A program that uses this technique might look like this:

Copy Code
#INCLUDE ERR_TEXT.H

* processing here

IF ERR THEN
   MESSAGEBOX( ERR_FILE_NOT_FOUND )
ENDIF

When your application is localized, the translator can create a locale-specific version of the error text file and then recompile the application.

Working With Strings in DBCS Environments

Visual FoxPro includes functions for manipulating character expressions containing any combination of single-byte or double-byte characters. By using DBCS string functions you can develop applications without having to write extra code that tests for double-byte characters when counting, locating, inserting, or removing characters in a string.

Most DBCS functions are equivalent to their single-byte counterparts except that they're named with a C suffix to distinguish them. You can use these functions with both single-byte and double-byte data; the DBCS functions return exactly the same value as their single-byte counterparts when single-byte data is passed to them. A few other functions help you work with strings specifically in double-byte environments.

DBCS string functions | Description
AT_C( ) | Returns the position of one string within another (case-sensitive), starting at the left.
ATCC( ) | Returns the position of one string within another (case-insensitive).
CHRTRANC( ) | Replaces characters in a string.
IMESTATUS( ) | Toggles double-byte editing in the Browse window.
ISLEADBYTE( ) | Tests whether a character is a DBCS character.
LEFTC( ) | Returns leftmost characters from a string.
LENC( ) | Returns the number of characters in a string.
LIKEC( ) | Determines whether two strings match.
RATC( ) | Returns the position of one string within another (case-sensitive), starting at the right.
RIGHTC( ) | Returns rightmost characters from a string.
STRCONV( ) | Converts characters between single-byte and double-byte representations.
STUFFC( ) | Replaces characters in a string with another string.
SUBSTRC( ) | Returns a substring.

When working with double-byte string functions, remember that the maximum-length limit for variables, names, and so on is effectively cut in half. For more information, see System Capacities.

Note:
The Visual FoxPro DBCS functions are not supported in earlier versions of Visual FoxPro, and calling them might cause unpredictable results. If you use any DBCS functions in your application, use VERSION(1) to verify that the Visual FoxPro version is later than version 3.0.

Working with Date, Time, and Currency Formats

To help you format dates, times, and currency to match what your users are accustomed to, you can use a variety of formatting techniques. You can:

  • Allow Visual FoxPro to use the settings established in the Control Panel.

  • Specify a language or a specific format in the Visual FoxPro Options dialog box that you want to use.

Format dates, times, and currency information in code using the SET SYSFORMATS and SET DATE commands. As a rule, you would issue this command during the initialization of your application (for example, in the configuration file). The default for SET SYSFORMATS is OFF, so you must explicitly set it to ON when starting your application.

You can establish data validation in individual text boxes by setting the Format property of the text box. However, because text box formatting takes precedence over system-wide formatting, this can make it more difficult to localize your application to an environment that uses a different format for dates, currency, and so on.

For more information about setting local formats, see How to: Set Date, Time, and Currency Formats.

Using Preprocessor Directives

You can create application variants for different locales by using preprocessor directives. These control compilation of code in the application and include the #INCLUDE, #DEFINE, #UNDEF, and #IF...#ENDIF constructs.

Using preprocessor directives can produce variants quickly; however, such directives have the following drawbacks:

  • To use preprocessor directives, you bracket code, and extensive bracketing can increase the code's complexity.

  • Compile-time constants are available only in the program that creates them.

See Also

Other Resources

Application Creation with Double-Byte Character Sets
Managing Files in an International Application
Developing International Applications
Creating International Applications
VERSION( )
#INCLUDE


Reporting Features for International Applications

Visual FoxPro 9.0
Reporting Features for International Applications
See Also

This topic discusses features in Visual FoxPro 9's Report System that facilitate developing reports for use in international applications.

Note:
Some of the features discussed here are available only in Visual FoxPro's object assisted reporting mode. If you find that you do not see some of the improvements described in this topic, use the command SET REPORTBEHAVIOR 90, or include the OBJECT clause on the REPORT FORM or LABEL command. For more information, see SET REPORTBEHAVIOR Command.

Using Language Script in Reports

Just as you can choose fonts individually for report layout elements, you can choose a language script for each element individually. For more information, see How to: Change Font Settings in Report Controls.

If you do not choose a language script for a particular element, it receives its language script information, like its font information, from the report's default. You use the Default Font… option on the Report menu for this purpose. You can also set the font and language script defaults for a report using the Page Layout tab of the Report Properties dialog. For more information, see How to: Change Page Settings for Reports.

When you design a new report, the default font and language script for the report is determined by your global preference, as set in the Tools Options dialog box. For more information, see Reports Tab, Options Dialog Box.

Tip:
The Options Dialog Box global choice, the Report Builder Page Layout tab, and the Report Builder's options for setting fonts for individual layout elements all offer you an option to omit the language script from your font settings. When you choose this option, the language script for your report elements matches your computer's regional default settings. This behavior is backward-compatible with earlier versions of Visual FoxPro.

The language script with which the Visual FoxPro Report System generates output for report layout elements is automatically available to additional forms of report output you can create with ReportListener-derived classes. The source text provided in the ReportListener's Render method's eContentsToBeRendered parameter is Unicode, and the native Report System has already converted the data to the appropriate character set. For more information, see Render Method.

The ReportListener XML Foundation Class provides an example of an alternative output type leveraging this feature. The class uses its Render method's Unicode value to account for mixed language scripts in report output automatically. It converts the Unicode values to construct UTF-8 encoded documents. For more information about the class's XML output, see Using VFP Report Output XML.

Caution:
This capability may appear to work in reports when you do not use object-assisted mode, when you preview the reports. However, it will not print as you expect, and is only supported in object-assisted mode.

Localizing Report Builder, Report Preview, and Report Output Components

The distributable source components of the Visual FoxPro Report System each provides a header (.h) file you can change to localize all user feedback strings. You can recompile the applications, and redistribute them separately, to provide a shared, external reporting component. You can also bind your adjusted version of each component directly into your application's .exe or .app file.

The following table lists the appropriate header file for each component, and provides a help topic you can read to learn more about specifying your adjusted reporting component file for application use.

Component file name | Use in applications | Localization header file name | Help topic with additional information
ReportBuilder.app | Augments the user experience of creating and modifying report and label layouts. | frxbuilder_loc.h | How to: Specify and Distribute ReportBuilder.App
ReportPreview.app | Provides a flexible user interface for GDI+-rendered report previews. | frxpreview_loc.h | How to: Specify and Distribute ReportPreview.App
ReportOutput.app, _reportlistener.vcx | Provides ReportListener classes for object-assisted reporting. | reportoutput_locs.h, reportlisteners_locs.h | How to: Specify and Distribute Report Output Application Components ReportListener Foundation Classes
_frxcursor.vcx | Provides algorithms useful for programmatically creating and adjusting reports. | _frxcursor.h | FRX Cursor Foundation Class

For more information, see Including Report Files for Distribution.

Each component also includes application programming interfaces (APIs) appropriate to changing user feedback messages at run time, to customize for regional purposes as well as other, application-specific needs. For example, the ReportListener User Feedback Foundation Class, the default ReportListener-derived class for print and preview output, provides public members you use to set its various text status messages and captions. The Report Preview Application exposes a Caption property and an extensive API for adjusting its context menu. For more information, see Leveraging the Default Preview Container.

Handing Reading Order (Right-to-Left and Left-to-Right) of Multiple Languages

The Report Designer supports right-to-left languages with Text Alignment and Reading Order properties. You can design labels and text (expression) layout elements to match the desired right-to-left results, by setting both these properties for selected elements, using the following options on the Format menu:

  • Set the Text Alignment of the layout element to Right

  • Set the Reading Order property to Right to Left.

Note:
The Reading Order option on the Format menu is disabled unless you have set Windows' regional settings to display a right-to-left language, such as Arabic or Hebrew, for non-Unicode applications. Once you have enabled the setting, you can set individual report items to different Reading Order values as required for a mixed-language report.

At run time, Visual FoxPro 9's new GDI+ rendering system provides more flexible and accurate handling of alignment for right-to-left languages. It also renders the alignment more consistently between preview and print output.

ReportListener-derived classes have access to the alignment and reading order settings stored in your report or label, and can take action based on these settings. For example, the ReportListener HTML Foundation Class uses these options to determine text-align and direction components of style attributes for individual HTML text elements.

See Also

Concepts

Understanding Visual FoxPro Object-Assisted Reporting
Using GDI+ in Reports

Other Resources

Distributing Reports with Applications


Working with Data

Visual FoxPro 9.0
Working with Data

You can create more effective applications by analyzing your data requirements and then designing your databases, tables, and indexes to meet these needs.

In This Section

Developing Databases

Describes how to use databases in Visual FoxPro to establish relationships between tables, enforce referential integrity, and manage local and remote data.
Working with Tables

Introduces creating and working with tables.
Enforcing Business Rules

Provides an overview about how to enforce business rules by using validation rules, preventing duplicate values in fields, and maintaining relationships between tables.
Working with Queries

Describes how to use queries to select and display data from tables or views.
Working with Views

Explains how to use views to create a customized updatable data set for your application.
Importing and Exporting Data

Explains how information is copied between Visual FoxPro and other applications by importing to and exporting from Visual FoxPro.
Upsizing Visual FoxPro Databases

Discusses building and upsizing a local prototype of your application using Visual FoxPro tables, views, and databases to represent data accessed on a remote server.
Programming for Shared Access

Explains how programming for shared access makes it possible for you to create an application that will run on several machines in a network environment.
Visual FoxPro Data Access Using the OLE DB Provider

Describes the Visual FoxPro OLE DB Provider and how to access Visual FoxPro data from other languages and applications.

Reference

Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.

Related Sections

Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Application Planning

Stresses that careful planning saves time, effort, and money and that many of the decisions you make during the planning phase will impact how you create elements of the application.
Enhancing Applications using SQL Pass-through Technology

Describes how you can use SQL pass-through (SPT) technology to create objects on the server, run stored procedures on a remote server, and execute commands using native server syntax.


Developing Databases

Visual FoxPro 9.0
Developing Databases

In Visual FoxPro, you can design, create, and manage databases so you can associate, organize, and work with tables and views as a group. Before you begin creating and working with databases, it is important to understand the design considerations regarding database creation.

In This Section

Databases in Visual FoxPro

Introduces databases in Visual FoxPro and provides information about their aspects.
Designing Databases

Describes design considerations for creating well-planned databases.
Creating Databases

Describes creating databases and working with tables associated with databases.
Managing Databases

Describes various tasks for managing databases.

Reference

Database Wizard

Makes it possible for you to create databases using a wizard.
Database Designer

Makes it possible for you to create databases starting with an empty database container or modify existing databases.
Project Manager

Makes it possible for you to organize files in an application project.

Related Sections

Working with Data

Provides an overview and information about using data in your applications, for example, analyzing data requirements and designing your application components to meet those requirements.
Importing and Exporting Data

Explains how information is copied between Visual FoxPro and other applications by importing to and exporting from Visual FoxPro.
Developing Visual FoxPro Applications

Explains concepts about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.


Databases in Visual FoxPro

Visual FoxPro 9.0
Databases in Visual FoxPro
See Also

Databases provide an architecture and working environment for associating, organizing, and working with tables and views. You can use databases independently or include them in an application project. When you create a database, Visual FoxPro creates and opens a database (.dbc) file exclusively. The database file, which is a table, stores all the information about the database including the names of files and items associated with it. The database file does not physically contain top-level items such as tables or fields. Instead, the database file stores file path pointers to tables associated with the database.

Databases provide additional benefits such as the following:

  • Associate tables with a database.

  • Create persistent relationships between tables.

  • Make it possible for you to create field and record-level validation rules without writing code.

  • Create rules to preserve the relationships between database tables when adding, updating, or deleting records.

  • Create stored procedures.

  • Create views from local and remote tables.

  • Access connections to remote data sources.

To view the structure of a sample database, open the NorthWind.dbc file located in the Visual FoxPro ...\Samples\Northwind directory. For more information, see How to: Open Databases.

Data Dictionary Features of Databases

Creating a database by associating tables as a group provides the benefits of the data dictionary features in Visual FoxPro. A data dictionary provides greater flexibility in designing and modifying the database and frees you from writing code to create field and row-level validation or to ensure the uniqueness of values in primary key fields. More specifically, the Visual FoxPro data dictionary makes it possible for you to create or specify the following items:

  • Primary and candidate keys.

  • Persistent relationships between database tables.

  • Long names for tables and fields.

  • Captions on fields that display in browse windows and grid columns as headers.

  • Default values in fields.

  • The default control class used in forms.

  • Input masks and display formats for fields.

  • Field-level rules and record-level rules.

  • Triggers.

  • Stored procedures.

  • Connections to remote data sources.

  • Local and remote views.

  • Comments for each field, table, and database.

Some data dictionary features, such as long field names, primary and candidate keys, default values, field-level and record-level rules, and triggers, are stored with the database (.dbc) file but can also be created by creating a table or view. For more information, see Working with Tables and How to: Create Views.

Tables in Databases

You can associate tables with a database by creating them or adding them to a database. Tables in Visual FoxPro can exist as a free table or as a database table. A free table is a table (.dbf) file that is not associated with any database. A database table is a table file that is associated with a database. Database tables can have properties that free tables do not have, such as field-level and record-level rules, triggers, and persistent relationships. For more information, see Working with Tables and How to: Associate Tables with a Database.

Links Between Tables and the Database

Adding a table to the database creates links between the table file and the database. Information for these links is stored in the database (.dbc) file and the table (.dbf) file. The link information stored in the database file about a table it contains is called a forward link. Forward link information consists of the relative path and file name for each associated table file and is stored in the database file.

The link information stored in the table file about the database that contains it is called a back link. Back link information consists of the relative path and file name for the database associated with the table and is stored in the header of the table file. For more information, see How to: Update Table and Database Links.

Persistent Relationships Between Database Tables

Creating persistent relationships between database tables in a database make it possible for you to relate tables based on a simple or complex index expression or their indexes so you can access the exact records you want.

Unlike temporary relationships created with the SET RELATION command, you do not need to recreate persistent relationships each time you use the tables. However, persistent relationships do not control the relationship between record pointers in tables, so you need to set temporary relationships using the SET RELATION command relationships as well as persistent relationships when developing Visual FoxPro applications. For more information, see SET RELATION Command.

Persistent relationships are stored in the database (.dbc) file. The following also apply to persistent relationships:

  • They are used automatically as the default join conditions in the Query and View designers. For more information, see Query and View Designers.

  • They appear in the Database Designer as lines joining table indexes. For more information, see Database Designer.

  • They are used to store referential integrity information.

  • They are used as the default relationships for forms and reports in a data environment and appear in the Data Environment Designer. For more information, see Data Environment Designer.

For more information, see How to: Create Persistent Relationships Between Tables.

Referential Integrity Between Database Tables

You can create a set of rules to preserve relationship definitions between database tables when adding, updating, or deleting records. The process of creating these rules is called building referential integrity. When you create rules to enforce referential integrity, Visual FoxPro prevents the following actions:

  • Adding records to a related table when no associated record exists in the primary table.

  • Changing values in a primary table that result in orphan records in a related table.

  • Deleting records from a primary table when there are matching related records.

You can write triggers and stored procedure code to enforce referential integrity. A trigger is an expression that is bound to a table and is invoked when any of the table's records are modified using a one of the specified data manipulating commands. However, you can use the Visual FoxPro Referential Integrity (RI) Builder to build referential integrity rules.

The RI Builder makes it easier for you to determine the types of rules you want to enforce, the tables to enforce the rules with, and the system events that cause Visual FoxPro to check referential integrity rules. The RI Builder can also handle multiple levels of cascading for cascaded deletes and updates. When you use the RI Builder, Visual FoxPro generates the code for enforcing relational integrity rules and saves it as triggers that reference stored procedures. For more information, see How to: Build Referential Integrity Between Tables.

Stored Procedures in Databases

A stored procedure is Visual FoxPro procedure code that operates specifically on the data in a database and is stored in the database (.dbc) file. Stored procedures can improve performance because they are loaded into memory when a database opens. Stored procedures also make your application more portable because you do not have to manage code files separate from the database file.

For example, you can use stored procedures for creating user-defined functions that you reference in validation rules at the field and record level. When you save a user-defined function as a stored procedure in a database, the function code is saved in the database file and moves with the database automatically if you relocate the database. For more information, see How to: Create and Manage Stored Procedures.

Multiple Databases for Multiple User Environments

To meet organizational needs in a multiple user environment, you might need more than one database on your system. Multiple databases offer the following advantages:

  • Controlling user access to a subset of tables in the overall system.

  • Organizing data to meet diverse informational needs efficiently for various user groups.

  • Making it possible to use a subset of tables exclusively for creating local and remote views at run time.

For example, suppose you have a database with sales information that is used primarily by a sales force working with customers and another database that maintains inventory information that is used primarily by buyers working with suppliers. Sometimes, the informational needs for these groups overlap. Multiple databases can be opened and accessed at the same time; yet they contain different information.

See Also

Other Resources

Designing Databases
Creating Databases


Designing Databases

Visual FoxPro 9.0
Designing Databases

Before you begin creating and working with databases, make sure you understand the design considerations involved with database creation.

In This Section

Database Design Process

Provides an introduction on how to create a well-designed database and lists the important steps in the design process.
Analyzing Data Requirements

Focuses on the first step in designing a Microsoft Visual FoxPro database, which involves finding out the reason for the database and how it will be used.
Organizing Requirements into Tables

Describes how to select the tables in your database, which can be the most difficult step in the database design process.
Determining the Fields You Need

Explains the importance of determining what you must know about the people, things, or events recorded in the table.
Identifying Relationships

Contains information and examples on how the Microsoft Visual FoxPro relational database management system can be used to link information in meaningful ways.
Refining the Design

After the tables, fields, and relationships have been established, details the important step of reviewing your database design to locate remaining flaws.
Sample Database Diagrams

Offers database diagrams as a way to spark ideas for creating your own database.

Related Sections

Working with Data

Discusses how to create effective applications with indexes, tables, and databases based on your data requirements.
Developing Databases

Shows how to use databases in Microsoft Visual FoxPro to establish relationships between tables, enforce referential integrity, and manage local and remote data.
Working with Tables

Describes how to make sure your tables have the structure that your application requires. Data type and index choices are essential to the success of your application.
Importing and Exporting Data

Describes how information is copied between Microsoft Visual FoxPro and other applications by importing to and exporting from Visual FoxPro.


Database Design Process

Visual FoxPro 9.0
Database Design Process
See Also

If you use an established database design process, you can quickly and effectively create a well-designed database that provides you with convenient access to the information you want. With a solid design, you'll spend less time constructing the database and you'll end up with faster, more accurate results.

Note:
The terms "database" and "table" are not synonymous in Visual FoxPro. The term database (.dbc file) refers to a relational database that is a container of information about one or more tables (.dbf files) or views.

The key to effective database design lies in understanding exactly what information you want to store and the way a relational database management system, such as Visual FoxPro, stores data. To efficiently and accurately provide you with information, Visual FoxPro needs to have the facts about different subjects organized into separate tables. For example, you might have one table that stores facts only about employees and another that stores facts only about sales.

When you organize your data appropriately, you design flexibility into your database and gain the capability to combine and present facts in many different ways.

When you design a database, you first break down the information you want to keep as separate subjects, and then you tell Visual FoxPro how the subjects are related to each other so that Visual FoxPro can bring the right information together when you need it. By maintaining information in separate tables, you make it easier to organize and maintain your data, as well as to build a high-performance application.

Here are the steps in the database design process. Each step is discussed in greater detail in related topics.

  1. Determine the purpose of your database Knowing the purpose will help you decide which facts you want Visual FoxPro to store. For more information, see Analyzing Data Requirements.

  2. Determine the tables you need When you have a clear purpose for your database, you can divide your information into separate subjects, such as "Employees" or "Orders." Each subject will be a table in your database. For more information, see Organizing Requirements into Tables

  3. Determine the fields you need Decide what information you want to keep in each table. Each category of information in a table is called a field and is displayed as a column when you browse the table. For example, one field in an Employee table could be Last_name; another could be Hire_date. For more information, see Determining the Fields You Need

  4. Determine the relationships Look at each table and decide how the data in one table is related to the data in other tables. Add fields to tables or create new tables to clarify the relationships, as necessary. For more information, see Identifying Relationships

  5. Refine your design Analyze your design for errors. Create the tables and add a few records of sample data. See if you can get the results you want from your tables. Make adjustments to the design as needed. For more information, see Refining the Design

Don't worry if you make mistakes or leave things out of your initial design. Think of it as a rough draft that you can refine later. Experiment with sample data and prototypes of your forms and reports. With Visual FoxPro, it's easy to change the design of your database as you're creating it. However, it becomes much more difficult to make changes to tables after they're filled with data and after you've built forms and reports. For this reason, make sure that you have a solid design before you proceed too far into building your application.

You can use the Database Designer to define a set of tables and link them with relationships that persist whenever you use the tables.

Take a look at the sample database. To open the database in the Database Designer, choose Open from the File menu, and locate Testdata.dbc in the Visual FoxPro ...\Samples\Data directory.

DatabaseDesignerInterface screenshot foxpro

See Also

Other Resources

Designing Databases
Database Designer
Analyzing Data Requirements
Developing Databases
Working with Tables
Organizing Requirements into Tables


Analyzing Data Requirements

Visual FoxPro 9.0
Analyzing Data Requirements
See Also

Your first step in designing a Visual FoxPro database is to analyze your data requirements by determining the purpose of the database and how it is to be used. This tells you what information you want from the database. From that, you can determine what subjects you need to store facts about (the tables) and what facts you need to store about each subject (the fields in the tables).

Talk to the people who will use the database. Brainstorm about the questions you'd like the database to answer. Sketch out the reports you'd like it to produce. Gather the forms you currently use to record your data. You'll use all this information in the remaining steps of the design process.

Example

Suppose that Tasmanian Traders, an import/export company that sells specialty foods from around the world, wants a database that can track information about the company's sales and inventory.

Start by writing down a list of questions the database should be able to answer. How many sales of our featured product did we make last month? Where do our best customers live? Who's the supplier for our best-selling product?

Next, gather all the forms and reports that contain information the database should be able to produce. The company currently uses a printed report to keep track of products being ordered and an order form to take new orders. The following illustration shows these two documents.

Tasmanian Traders also needs to print mailing labels for customers, employees, and suppliers.

After gathering this information, you're ready for the next step.

See Also

Other Resources

Database Design Process
Organizing Requirements into Tables
Designing Databases
Developing Databases
Working with Tables


Organizing Requirements into Tables

Visual FoxPro 9.0
Organizing Requirements into Tables
See Also

Determining the tables in your database can be the trickiest step in the database design process. That's because the results you want from your database — the reports you want to print, the forms you want to use, and the questions you want answered — don't necessarily provide clues about the structure of the tables that produce them. They tell you what you want to know but not how to categorize the information into tables.

See the order form in Analyzing Data Requirements as an example. It includes facts about the customer — the customer's address and phone number — along with facts about the order. This form provides you with a number of facts that you know you want to store in your database. Although the facts are all on the same form, you can easily prevent common data integrity problems by storing them in separate tables.

Storing information once reduces the chance of error

For example, if you only use one table to store the information for an order form, suppose that one customer places three different orders. You could add the customer's address and phone number to your database three times, once for each order. But this multiplies the chance of data entry errors.

The Customer table stores address information once

Also, if the customer moves, you'd have to either accept contradictory information or find and change each of that customer's sales records in the table. It's much better to create a Customer table that stores the customer's address in your database once. Then, if you need to change the data, you change it only once.

Preventing the deletion of valuable information

Suppose a new customer places an order and then cancels it. When you delete the order from the table containing information on both customers and their orders, you would delete the customer's name and address as well. But you want to keep this new customer in your database so you can send the customer your next catalog. Again, it's better to put the information about the customer in a separate Customer table. That way you can delete the order without deleting customer information.

Look at the information you want to get out of your database and divide it into fundamental subjects you want to track, such as customers, employees, products you sell, services you provide, and so on. Each of these subjects is a candidate for a separate table.

Tip:
One strategy for dividing information into tables is to look at individual facts and determine what each fact is actually about. For example, on the Tasmanian Traders order form, the customer address isn't about the sale; it's about the customer. This suggests that you need a separate table for customers. In the Products On Order report, the supplier's phone number isn't about the product in stock; it's about the supplier. This suggests that you need a separate table for suppliers.

See Also

Other Resources

Designing Databases
Developing Databases
Working with Tables


Determining the Fields You Need

Visual FoxPro 9.0
Determining the Fields You Need

To determine the fields in a table, decide what you need to know about the people, things, or events recorded in the table. You can think of fields as attributes of the table. Each record (or row) in the table contains the same set of fields or attributes. For example, an address field in a customer table contains customers' addresses. Each record in the table contains data about one customer, and the address field contains the address for that customer.

In This Section

Identifying Fields

Provides tips for determining the fields you might need in your database.
Using Primary Key Fields

Explains how each table in your database should include a field or set of fields that uniquely identifies each individual record stored in the table, for Visual FoxPro to work most efficiently.

Related Sections

Designing Databases

Take advantage of relational database technology in Visual FoxPro with well-planned databases.
Working with Tables

Describes how to make sure your tables have the structure that your application requires. Data type and index choices are essential to the success of your application.
Working with Fields

Introduces creating and working with fields in tables.


Identifying Fields

Visual FoxPro 9.0
Identifying Fields
See Also

Here are a few tips for determining your fields:

Relate each field directly to the subject of the table

A field that describes the subject of a different table belongs in that other table. Later, when you define relationships between your tables, you'll see how you can combine the data from fields in multiple tables. For now, make sure that each field in a table directly describes the subject of the table. If you find yourself repeating the same information in several tables, it's a clue that you have unnecessary fields in some of the tables.

Don't include derived or calculated data

In most cases, you don't want to store the result of calculations in tables. Instead, you can have Visual FoxPro perform the calculations when you want to see the result. For example, the Tasmanian Traders order form displays the extended price for each line of the order in the Tasmanian Traders database. However, there's no Extended Price subtotal field in any Tasmanian Traders table. Instead, the Order_Line_Items table includes a quantity field that stores the units on order for each individual product, as well as the unit price for each item ordered. Using that data, Visual FoxPro calculates the subtotal each time you print an order form. The subtotal itself doesn't need to be stored in a table. For more information, see Analyzing Data Requirements.

Include all the information you need

It's easy to overlook important information. Return to the information you gathered in the first step of the design process. Look at your paper forms and reports to make sure all the information you have required in the past is included in your Visual FoxPro tables or can be derived from them. Think of the questions you will ask Visual FoxPro. Can Visual FoxPro find all the answers using the information in your tables? Have you identified fields that will store unique data, such as the customer ID? Which tables include information that you'll combine into one report or form? For more information, see Using Primary Key Fields and Identifying Relationships.

Store information in its smallest logical parts

You might be tempted to have a single field for full names, or for product names, along with product descriptions. If you combine more than one kind of information in a field, it's difficult to retrieve individual facts later. Try to break down information into logical parts; for example, create separate fields for first and last name, or for product name, category, and description.

Example

Tasmanian Traders sells imported specialty foods from around the world. The employees use a Products On Order report to keep track of products being ordered.

The report indicates that the Products table, which contains facts about products sold, needs to include fields for the product name, units in stock, and units on order, among others. But what about fields for the supplier name and phone number? To produce the report, Visual FoxPro needs to know which supplier goes with each product.

You can solve this without storing redundant data in your tables by creating a Supplier table with separate fields for the supplier's name and phone number. For more information, see Using Primary Key Fields.

See Also

Other Resources

Determining the Fields You Need
Using Primary Key Fields


Using Primary Key Fields

Visual FoxPro 9.0
Using Primary Key Fields
See Also

The power in a relational database management system such as Visual FoxPro comes from its ability to quickly find and bring together information stored in separate tables. In order for Visual FoxPro to work most efficiently, each table in your database should include a field or set of fields that uniquely identifies each individual record stored in the table. This is often a unique identification number, such as an employee ID number or a serial number. In database terminology, this information is called the primary key of the table. Visual FoxPro uses primary key fields to quickly associate data from multiple tables and bring the data together for you.

If you already have a unique identifier for a table, such as a set of product numbers you've developed to identify the items in your stock, you can use that identifier as the table's primary key. But make sure the values in this field will always be different for each record — Visual FoxPro doesn't allow duplicate values in a primary key field. For example, don't use someone's name as a primary key, because names aren't unique. You could easily have two people with the same name in the same table.

When choosing primary key fields, keep these points in mind:

  • Visual FoxPro doesn't allow duplicate or null values in a primary key field. For this reason, you shouldn't choose a primary key that could contain such values.

  • You can use the value in the primary key field to look up records, so it shouldn't be too long to remember or type. You might want it to have a certain number of letters or digits, or be within a certain range of values.

  • The size of the primary key affects the speed of operations in your database. When you create primary key fields, use the smallest size that will accommodate the values you need to store in the field.

Example

The primary key of the Tasmanian Traders Products table contains product ID numbers. Because each product number identifies a different product, you don't want two products with the same number.

In some cases, you might want to use two or more fields that together provide the primary key of a table. For example, the Order_Line_Items table in the Tasmanian Traders database uses two fields as its primary key: Order_id and Product_id. For more information, see Identifying Relationships.

See Also

Other Resources

Determining the Fields You Need


Identifying Relationships

Visual FoxPro 9.0
Identifying Relationships
See Also

Once you've divided your information into tables, you need a way to tell Visual FoxPro how to bring it back together again in meaningful ways. For example, the following form includes information from several tables.

Visual FoxPro is a relational database management system. That means you store related data in separate tables. Then you define relationships between the tables and Visual FoxPro uses the relationships to find associated information stored in your database.

For example, suppose that you want to phone an employee with questions about a sale the employee made. Employee phone numbers are recorded in the Employee table; sales are recorded in the Orders table. When you tell Visual FoxPro which sale you're interested in, Visual FoxPro can look up the phone number based on the relationship between the two tables. It works because Employee_id, the primary key for the Employee table, is also a field in the Orders table. In database terminology, the Employee_id field in the Orders table is called a foreign key, because it refers to a primary key from a different, or foreign, table.

So, to set up a relationship between two tables — Table A and Table B — you add one table's primary key to the other table, so that it appears in both tables. But how do you decide which table's primary key to use? To set up the relationship correctly, you must first determine the nature of the relationship. There are three types of relationships between tables:

  • One-to-many relationships

  • Many-to-many relationships

  • One-to-one relationships

The following examples present each type of relationship and explain how to design your tables so that Visual FoxPro can associate the data correctly. The purpose of each example is to explain how you determine the relationships between your tables and how you decide which fields belong in the tables to support those relationships — it doesn't describe how to use the Visual FoxPro interface to relate tables.

Example

A one-to-many relationship is the most common type of relationship in a relational database. In a one-to-many relationship, a record in Table A can have more than one matching record in Table B, but a record in Table B has, at most, one matching record in Table A.

For example, the Category and Products tables in the Tasmanian Traders database have a one-to-many relationship.

To set up the relationship, you add the field or fields that make up the primary key on the "one" side of the relationship to the table on the "many" side of the relationship. You use a primary or candidate index key for the "one" side of the relationship, and a regular index key for the "many" side. In this case, you would add the Category_id field from the Category table to the Products table, because one category includes many products. Visual FoxPro uses the category ID number to locate the correct category for each product.

For more information, see Working with Tables.

Example

In a many-to-many relationship, a record in Table A can have more than one matching record in Table B, and a record in Table B can have more than one matching record in Table A. This type of relationship requires changes in your database design before you can correctly specify the relationship to Visual FoxPro.

To detect many-to-many relationships between your tables, it's important that you look at both directions of the relationship. For example, consider the relationship between orders and products in the Tasmanian Traders business. One order can include more than one product. So for each record in the Orders table, there can be many records in the Products table. But that's not the whole story. Each product can appear on many orders. So for each record in the Products table, there can be many records in the Orders table.

The subjects of the two tables — orders and products — have a many-to-many relationship. This presents a challenge in database design. To understand the problem, imagine what would happen if you tried to set up the relationship between the two tables by adding the Product_id field to the Orders table. To have more than one product per order, you need more than one record in the Orders table per order. You'd be repeating order information over and over for each record that relates to a single order — an inefficient design that could lead to inaccurate data. You run into the same problem if you put the Order_id field in the Products table — you'd have more than one record in the Products table for each product. To solve this problem, create a third table that breaks down the many-to-many relationship into two one-to-many relationships. This third table is called a junction table, because it acts as the junction between two tables. You put the primary key from each of the two tables into the junction table.

A junction table might hold only the two primary keys from the tables it links together or, as in the Order_Line_Items table, the junction table might hold additional information.

Each record in the Order_Line_Items table represents one line item on an order. The Order_Line_Items table's primary key consists of two fields — the foreign keys from the Orders and Products tables. The Order_id field alone doesn't work as the primary key for this table, because one order can have many line items. The order ID is repeated for each line item on an order, so the field doesn't contain unique values. The Product_id field alone doesn't work either, because one product can appear on many different orders. But together the two fields in the junction table always produce a unique value for each record. The junction table does not require its own primary key.

In the Tasmanian Traders database, the Orders table and the Products table aren't related to each other directly. Instead, they are related indirectly through the Order_Line_Items table. The many-to-many relationship between orders and products is represented in the database using two one-to-many relationships:

  • The Orders and Order_Line_Items tables have a one-to-many relationship. Each order can have more than one line item, but each line item is connected to only one order.

  • The Products and Order_Line_Items tables have a one-to-many relationship. Each product can have many line items associated with it, but each line item refers to only one product.

Example

In a one-to-one relationship, a record in Table A can have no more than one matching record in Table B, and a record in Table B can have no more than one matching record in Table A. This type of relationship is unusual and might call for some changes in your database design.

One-to-one relationships between tables are unusual because in many cases, the information in the two tables can simply be combined into one table. For example, suppose you created a table, called Ping-Pong Players, to track information about a Tasmanian Traders Ping-Pong fundraising event. Because the ping-pong players are all employees of Tasmanian Traders, this table has a one-to-one relationship with the Employee table in the Tasmanian Traders database.

You could add all the fields from the Ping-Pong Players table to the Employee table. But the Ping-Pong Players table tracks a one-time event, and you won't need the information after the event is over. Additionally, not all employees play Ping-Pong, so if these fields were in the Employee table, they would be empty for many records. For these reasons, it makes sense to create a separate table.

When you detect the need for a one-to-one relationship in your database, consider whether you can put the information together in one table. For example, in the Employee table, one employee can have one manager, who is also an employee. You can add a field for the manager's id number. To pull the information together later, you can use a self-join in your query or view. You don't need a separate table to resolve the one-to-one relationship. If you don't want to do that for some reason, here's how to set up the one-to-one relationship between two tables:

  • If the two tables have the same subject, you can probably set up the relationship by using the same primary key field in both tables.

  • If the two tables have different subjects with different primary keys, choose one of the tables (either one) and put its primary key field in the other table as a foreign key.

See Also

Other Resources

Designing Databases
Developing Databases
Working with Tables


Refining the Design

Visual FoxPro 9.0
Refining the Design
See Also

When you have the tables, fields, and relationships you need, it's time to study the design and detect any flaws that might remain.

You might encounter several pitfalls while you are designing your database. These common problems can cause your data to be harder to use and maintain:

  • Do you have one table with a large number of fields that don't all relate to the same subject? For example, one table might contain fields pertaining to your customers as well as fields that contain sales information. Try to make sure each table contains data about only one subject.

  • Do you have fields that are intentionally left blank in many records because they aren't applicable to those records? This usually means that the fields belong in another table.

  • Do you have a large number of tables, many of which contain the same fields? For example, you have separate tables for January sales and February sales, or for local customers and remote customers, in which you store the same type of information. Try consolidating all the information pertaining to a single subject in one table. You might also need to add an extra field, for example, to identify the sales date.

Create your tables, specify relationships between the tables, and enter a few records of data in each table. See if you can use the database to get the answers you want. Create rough drafts of your forms and reports and see if they show the data you expect. Look for unnecessary duplications of data and eliminate them.

As you try out your initial database, you will probably discover room for improvement. Here are a few things to check for:

  • Did you forget any fields? Is there information that you need that isn't included? If so, does it belong in the existing tables? If it's information about something else, you might need to create another table.

  • Did you choose a good primary key for each table? If you use it to search for specific records, is it easy to remember and type? Make sure that you won't need to enter a value in a primary key field that duplicates another value in the field.

  • Are you repeatedly entering duplicate information in one of your tables? If so, you probably need to divide the table into two tables with a one-to-many relationship.

  • Do you have tables with many fields, a limited number of records, and many empty fields in individual records? If so, think about redesigning the table so it has fewer fields and more records.

As you identify the changes you want to make, you can alter your tables and fields to reflect the improved design. For information about modifying tables, see Working with Tables.

Example

Each product in the Tasmanian Traders stock falls under a general category, such as Beverages, Condiments, or Seafood. The Products table could include a field that shows the category of each product.

Suppose that in examining and refining the database, Tasmanian Traders decides to store a description of the category along with its name. If you add a Category Description field to the Products table, you have to repeat each category description for each product that falls under the category — not a good solution.

A better solution is to make Category a new subject for the database to track, with its own table and its own primary key. Then you can add the primary key from the Category table to the Products table as a foreign key.

The Category and Products tables have a one-to-many relationship: one category can have more than one product in it, but any individual product can belong to only one category.

See Also

Other Resources

Sample Database Diagrams
Designing Databases
Developing Databases
Working with Tables


Sample Database Diagrams

Visual FoxPro 9.0
Sample Database Diagrams
See Also

The following database diagrams might give you ideas for designing your own database. These databases aren't included with Visual FoxPro; they're included here as examples of the types of databases and tables you can create.

Appointments Database

This database structure stores appointments for a professional office, and could easily be modified for use in an office of doctors, dentists, lawyers, or accountants. The Appointments table has a multiple-field primary key to uniquely identify each appointment. This primary key, the "client_sta" index, is created by indexing on an expression that combines the client_id and date_start time fields.

Personnel Database

This database structure stores human resources information. The Job History table stores information on each hire or promotion, so it can contain many records for each employee.

Library Database

This database stores information about library books and loans to patrons. Notice the many-to-many relationships between the Books and Authors tables and between the Books and Subjects tables.

See Also

Other Resources

Designing Databases


Creating Databases

Visual FoxPro 9.0
Creating Databases

After you have designed your database and determined the fields you might need, you are ready to create your database.

In This Section

How to: Create Databases

Describes how to create databases.
How to: View and Set Database Properties

Describes how you can view and set properties for databases.
Working with Items in Databases

Introduces and describes how to perform tasks with items in databases, such as displaying them, arranging them, adding items, defining relationships, updating links between a database and its tables, creating rules governing adding, updating, and deleting records, and so on.
How to: Create and Manage Stored Procedures

Describes how to store code written to operate on a specific database and that can move with the database.
Working with Database Container Events

Introduces database container events that you can use to run procedure code when database events occur.

Reference

Database Wizard

Makes it possible for you to create databases using a wizard.
Database Designer

Makes it possible for you to create databases starting with an empty database container or modify existing databases.
Project Manager

Makes it possible for you to organize files in an application project.

Related Sections

Designing Databases

Describes design considerations for creating well-planned databases.
Managing Databases

Describes various tasks for managing databases.
Developing Databases

Introduces and describes using databases to store, organize, and work with tables and views as a collection.


How to: Create Databases

Visual FoxPro 9.0
How to: Create Databases
See Also

You can use a wizard to create a database and add tables, or you can create an empty database container. A wizard helps you create a database using your answers to a series of questions. The wizard also provides templates for tables and views, indexes, primary keys, and relationships you can choose or edit.

When you create a database, a database (.dbc) file is created with an associated database memo (.dct) file and database index (.dcx) file.

To create a database using a wizard

  1. On the File menu, click New.

  2. In the New dialog box, click Database, and then Wizard.

  3. Follow the instructions on the wizard screens.

For more information, see Database Wizard.

You can also begin the wizard from a project in the Project Manager by expanding the Data node, selecting the Databases node, clicking New, and then Database Wizard. For more information, see Project Manager Window.

To create an empty database container

  1. On the File menu, click New.

  2. In the New dialog box, click Database, then New file.

  3. In the Create dialog box, browse to the location you want to save the database, type a name for the database, and click Save.

    The Database Designer opens and displays an empty database.

For more information, see Database Designer.

To create a database in a project

  1. Open the project in the Project Manager.

  2. In the Project Manager, expand the Data node, and click the Databases node.

  3. Click New, and then New Database.

For more information, see Project Manager Window.

To create a database programmatically

  • Use the CREATE DATABASE command.

    The following example creates and exclusively opens a database named Sample:

    Copy Code
    CREATE DATABASE Sample

For more information, see CREATE DATABASE Command.

Note:
Using the CREATE DATABASE command does not add the database automatically to a project even when the Project Manager is open. For more information, see How to: Add Databases to Projects.

See Also

Other Resources

Databases in Visual FoxPro
Working with Items in Databases
Creating Databases


How to: View and Set Database Properties

Visual FoxPro 9.0
How to: View and Set Database Properties
See Also

Databases and database objects, such as connections and views, have properties you can view and some you can set. You can view and set these properties using the DBGETPROP( ) and DBSETPROP( ) functions. For more information, see DBGETPROP( ) Function and DBSETPROP( ) Function.

However, you can set the Comment property for a database using the Visual FoxPro interface.

To add comments to the current database

  1. Open the database in the Database Designer.

  2. On the Database menu, click Properties to open the Database Properties dialog box.

  3. In the Comment box, type a comment for the database.

  4. When you are finished, click OK.

See Also

Other Resources

How to: Create Databases
Creating Databases


Working with Items in Databases

Visual FoxPro 9.0
Working with Items in Databases

After you create a database, you can perform various tasks, for example:

  • Configure how to display items in the database.

  • Add tables or create new tables and views to the database.

  • Find tables in the database.

  • Update links between databases and the tables they contain when database or table files are moved.

  • Define relationships between database tables.

  • Create rules governing adding, updating, and deleting records in database tables.

In This Section

How to: Display Items in Databases

Describes how to choose items and how they display in the Database Designer.
How to: Associate Tables with a Database

Describes how to create or add tables to a database.
How to: Find Tables or Views in Databases

Describes how to quickly locate tables and views in the Database Designer.
How to: Arrange Tables and Views in Databases

Describes how to arrange the layout of tables in the Database Designer.
How to: Use Tables from Other Databases

Describes how to include data from tables not associated with the current database.
How to: Update Table and Database Links

Describes how to update links between tables and the database when moving database files or database tables.
How to: Remove a Table from a Database

Describes how to remove or delete tables from a database.
How to: Create Persistent Relationships Between Tables

Describes how to create persistent relationships between database tables so you can access records easier.
How to: Manage Persistent Relationships Between Tables

Describes how to edit or delete persistent relationships between tables.
How to: Build Referential Integrity Between Tables

Describes how to create a set of rules to preserve relationships between database tables when adding, updating, or deleting records.

Related Sections

Databases in Visual FoxPro

Introduces databases in Visual FoxPro and provides information about their aspects.
Creating Databases

Describes how to create databases and work with tables in databases.
Designing Databases

Describes design considerations for creating well-planned databases.
Working with Tables

Describes using tables to store data and managing them.


How to: Display Items in Databases

Visual FoxPro 9.0
How to: Display Items in Databases
See Also

You can choose to which database items to display or how to display them in the Database Designer. For example, you can expand tables to see the fields and indexes they contain or collapse tables to show only table names.

To display items in a database

  1. Open the database in the Database Designer.

  2. On the Database menu, click Properties to open the Database Properties dialog box.

  3. In the Display area, select those items you want to display.

To expand or collapse a table in a database

  • In the Database Designer, right-click a table and click Expand or Collapse.

To expand or collapse all tables

  • Right-click the Database Designer and click Expand All or Collapse All.

See Also

Other Resources

How to: Open Databases
How to: Arrange Tables and Views in Databases
How to: Find Tables or Views in Databases
Creating Databases
Working with Items in Databases


How to: Associate Tables with a Database

Visual FoxPro 9.0
How to: Associate Tables with a Database
See Also

After you create a database, you can associate tables with a database by creating them in the database or adding existing ones. Tables can belong only to one database at a time; therefore you can associate any table that is not currently part of another database. If you want to associate a table that belongs to another database, you must remove that table before you can add it to a different database. You can also use data from another database table without removing it. For more information, see How to: Use Tables from Other Databases.

Note:
To associate free tables with a database, you must explicitly add them. Modifying their structure does not associate free tables with a database, even if a database is open when you modify the structure.

When you add a table to a database, Visual FoxPro modifies the header record in the table file to document the path and file name for the database that now contains the table. This path and file name information is called a back link because it links the table back to the owning database.

To create database tables, see How to: Create Database Tables.

To associate a table with a database

  1. Open the database in the Database Designer.

    The Database menu appears.

  2. On the Database menu, click Add Table.

  3. In the Open dialog box, browse for and select a table, and click OK.

    The table you selected appears in the Database Designer.

To associate a table with a database in a project

  1. Open the project in the Project Manager.

  2. In the Project Manager, expand the Data node, and then the Databases node.

  3. Click the Tables node, and then Add.

  4. In the Select table name dialog box, browse for and select the table (.dbf) file you want to add, and click OK.

    The table you selected appears in the Tables node of the Project Manager.

For more information, see Project Manager Window.

To associate a table with the current database programmatically

  1. Open the database.

  2. Use the ADD TABLE command.

    For example, the following code opens a database named MyDatabase and adds a table called MyTable:

    Copy Code
    OPEN DATABASE MyDatabase
ADD TABLE MyTable

For more information, see ADD TABLE Command.

See Also

Other Resources

How to: Open Tables
How to: Open Databases
Databases in Visual FoxPro
Creating Databases
Working with Items in Databases


How to: Find Tables or Views in Databases

Visual FoxPro 9.0
How to: Find Tables or Views in Databases
See Also

When your database is associated with many tables and views in the Database Designer, you can quickly locate a specific table or view. When locating an item, such as a table or view, associated with an open database, Visual FoxPro searches the current database first. If the item is not found, Visual FoxPro searches in the default search path.

To find a table or view in a database

  1. Open the database in the Database Designer.

  2. On the Database menu, click Find Object.

  3. In the Find Table or View dialog box, select the table or view you want to locate.

  4. Click Find.

    The table or view you selected appears active in the Database Designer.

See Also

Other Resources

How to: Open Databases
How to: Display Items in Databases
How to: Arrange Tables and Views in Databases
Creating Databases
Working with Items in Databases


How to: Arrange Tables and Views in Databases

Visual FoxPro 9.0
How to: Arrange Tables and Views in Databases
See Also

You can change the layout of tables or views in the Database Designer. For example, after working in the database, you might want to return tables to the default height and width or you might want align the tables.

To arrange tables or views in a database

  1. Open the database in the Database Designer.

  2. On the Database menu, click Arrange.

  3. In the Arrange Tables and Views dialog box, choose the options that you want, and click OK.

For more information, see Arrange Tables and Views Dialog Box.

See Also

Other Resources

How to: Open Databases
How to: Display Items in Databases
How to: Find Tables or Views in Databases
Creating Databases
Working with Items in Databases


How to: Use Tables from Other Databases

Visual FoxPro 9.0
How to: Use Tables from Other Databases
See Also

You can use data from a table not associated with the current database.

Tip:
To access a table associated with or not associated with a database, specify the full path. However, you can increase performance by using only the table name.

To use data from another database table

  • Perform one of the following:

    • Use the USE command with a question mark (?) to display the Use dialog box, and click Other.

    -OR-

    • Use the USE command and precede the table name with the database name followed immediately by an exclamation point (!).

      Tip:
      The exclamation point is used to refer to a table in a database other than the current database.

    -OR-

    • Create a view in your database that references the table.

For more information, see USE Command and Working with Views.

For example, the following code demonstrates how you can open a table named MyTable in another database called MyDatabase2 and browse the table:

Copy Code
USE MyDatabase2!MyTable
BROWSE

See Also

Other Resources

How to: Open Tables
Working with Tables
Creating Databases
Working with Items in Databases


How to: Update Table and Database Links

Visual FoxPro 9.0
How to: Update Table and Database Links
See Also

When you move database (.dbc, .dct, and .dcx) files or a database table, the relative paths change and might break forward links and back links that Visual FoxPro uses to associate database and table files. You can reestablish links and update the relative path information to reflect the new file location.

Tip:
If you want to open a table without reestablishing links for all tables in the database, use the USE command. Visual FoxPro displays the Open dialog box so you can locate the database that owns the table or delete the links. For more information, see USE Command.

You can also remove the database reference, or back link, from a table.

To update links between a database and its tables

  • Use the VALIDATE DATABASE command with the RECOVER clause

For more information, see VALIDATE DATABASE Command.

For example, the following code opens a database named MyDatabase and displays dialog boxes to help you locate those tables that are not in the locations stored by the database:

Copy Code
OPEN DATABASE MyDatabase
VALIDATE DATABASE RECOVER

To remove the back link from a table

  • Use the FREE TABLE command.

    Caution:
    Do not use FREE TABLE to remove a table from a database if the database exists on disk; use REMOVE TABLE instead. If the database exists on disk, FREE TABLE might render the database unusable.

For more information, see FREE TABLE Command.

See Also

Other Resources

Databases in Visual FoxPro
How to: Remove a Table from a Database
Creating Databases
Working with Items in Databases


How to: Remove a Table from a Database

Visual FoxPro 9.0
How to: Remove a Table from a Database
See Also

You can remove a table from the database or delete the table from disk permanently. Removing a table from a database does not delete the table automatically. However, it removes the table and associated data dictionary information from the database file and also updates the back link information to reflect the new status of the table as a free table.

Note:
You must first close a table before removing or deleting it. If a database table has a long name, removing the table from the database also removes the long name. For more information, see How to: Name Tables.

To remove or delete a table in a database

  1. Open the database in the Database Designer.

  2. In the Database Designer, click the table you want to remove.

  3. On the Database menu, click Remove.

    Visual FoxPro prompts you to remove the table from the database or delete it from disk.

  4. In the confirmation dialog box, perform one of the following:

    • To remove the table, click Remove.

    -OR

    • To delete the table from disk, click Delete.

To remove or delete a table from a database in a project

  1. Open the project in the Project Manager.

  2. In the Project Manager, expand the Data node, the Databases node, then the Tables node.

  3. Click the table you want to remove, and then Remove.

    Visual FoxPro prompts you to remove the table from the database or delete it from disk.

  4. In the confirmation dialog box, perform one of the following:

    • To remove the table, click Remove.

    -OR

    • To delete the table from disk, click Delete.

To remove or delete a table from the current database programmatically

  • Perform one of the following:

    • To remove the table from the database, use the REMOVE TABLE command.

      -OR-

    • To delete the table from disk, use the DROP TABLE command or use the REMOVE TABLE command with the DELETE clause.

For more information, see REMOVE TABLE Command and DROP TABLE Command.

For example, the following code opens a database named MyDatabase without opening the Database Designer and removes a table named MyTable:

Copy Code
OPEN DATABASE MyDatabase
REMOVE TABLE MyTable

The following code opens a database named MyDatabase without opening the Database Designer and deletes a table named MyTable from disk:

Copy Code
OPEN DATABASE MyDatabase
REMOVE TABLE MyTable DELETE

The following code opens a database named MyDatabase without opening the Database Designer and deletes a table named MyTable from disk without moving the file to the Windows Recycle Bin:

Copy Code
OPEN DATABASE MyDatabase
DROP TABLE MyTable NORECYCLE
Caution:
Do not use the ERASE command with tables associated with a database. ERASE does not update the back link to the database and can cause table access errors.

See Also

Other Resources

How to: Open Databases
How to: Update Table and Database Links
Creating Databases
Working with Items in Databases


How to: Create Persistent Relationships Between Tables

Visual FoxPro 9.0
How to: Create Persistent Relationships Between Tables
See Also

You can create persistent relationships between database tables based on a simple or complex expression or their indexes. These relationships are stored in the database (.dbc) file. The type of index tag or key determines the type of persistent relationship you can create. For example, in a one-to-many relationship between two tables, you must use a primary or candidate index tag or key in a table for the "one" side in the relationship and a regular index tag or key in the other table for the "many" side in the relationship.

Before you can create a persistent relationship, you need to perform the following steps:

  1. Determine which table contains the primary records and which table contains the related records.

  2. In the table with the primary records, add an integer field, and then add a primary index on the new field.

  3. In the table with the related records, add a field that matches the primary index key in the primary record table, and then add a regular index on that new field.

    Note:
    Use the same expression for both indexes. For example, if you use a function in the expression on the primary key field, you need to use the same function in the expression on the foreign key field.

For more information, see Identifying Relationships and Working with Table Indexes.

To create a persistent relationship between tables

  1. Open the database in the Database Designer.

  2. In the Database Designer, drag the index name from the table you want to relate to the index name in the related table.

A line representing the persistent relationship between the two tables appears in the Database Designer.

For more information, see Database Designer.

To create a persistent relationship between tables programmatically

  • Use the CREATE TABLE or ALTER TABLE commands with the FOREIGN KEY clause.

For more information, see CREATE TABLE - SQL Command and ALTER TABLE - SQL Command.

For example, the following code uses the SQL ALTER TABLE command and the tables Customer and Orders to create a one-to-many persistent relationship, where one customer has many orders, based on the primary index key, Cust_ID, in the Customer table and a new foreign key, cust_id, in the Orders table:

Copy Code
ALTER TABLE Orders;
   ADD FOREIGN KEY Cust_ID TAG ;
      Cust_Id REFERENCES Customer

See Also

Other Resources

How to: Open Databases
How to: Manage Persistent Relationships Between Tables
Databases in Visual FoxPro
Creating Databases
Working with Items in Databases


How to: Manage Persistent Relationships Between Tables

Visual FoxPro 9.0
How to: Manage Persistent Relationships Between Tables
See Also

You can edit and delete persistent relationships between database tables.

To edit a persistent relationship between tables

  1. Open the database in the Database Designer.

  2. In the Database Designer, click the relationship line between the two tables.

  3. On the Database menu, click Edit Relationship.

    Tip:
    You can also double-click the relationship line between the two tables.

  4. In the Edit Relationship dialog box, change the settings you want.

For more information, see Edit Relationship Dialog Box.

To delete a persistent relationship between tables

  1. Open the database in the Database Designer.

  2. In the Database Designer, click the relationship line between the two tables.

  3. Press the DELETE key.

For more information, see Database Designer.

To delete a persistent relationship between tables programmatically

  • Use the ALTER TABLE command and include the DROP FOREIGN KEY clause.

For more information, see ALTER TABLE - SQL Command.

For example, the following code deletes a persistent relationship between two tables, Customer and Orders, based on the primary index key, Cust_ID, in the Customer table and a foreign key, Cust_ID, in the Orders table:

Copy Code
ALTER TABLE Orders DROP FOREIGN KEY TAG Cust_ID SAVE

See Also

Other Resources

How to: Open Databases
How to: Build Referential Integrity
Creating Databases
Working with Items in Databases


How to: Build Referential Integrity Between Tables

Visual FoxPro 9.0
How to: Build Referential Integrity Between Tables
See Also

You can create a set of rules to preserve the relationships defined between database tables when adding, updating, or deleting records. The process of creating these rules is called building referential integrity.

To build referential integrity between tables

  1. Open the database in the Database Designer.

  2. In the Database Designer, create a new persistent relationship between two tables or choose an existing relationship by clicking the relationship line.

  3. On the Database menu, click Edit Referential Integrity.

  4. In the Referential Integrity Builder, select the rules you want to enforce for updating, deleting, or inserting records.

  5. To save your changes, generate RI code, and exit the builder, click OK, and then Yes.

For more information, see Referential Integrity Builder.

When you use the RI Builder, Visual FoxPro generates code for enforcing referential integrity rules and saves it as triggers that reference stored procedures. A trigger is an expression that is bound to a table and is invoked when table records are modified by specified data manipulating commands. You can view this code by opening the stored procedure text editor for your database. For more information, see Trigger Usage and How to: Create and Manage Stored Procedures.

Caution:
Run the RI Builder again when you make changes to a database such as modifying database tables or altering indexes used in a persistent relationship before you use the database. Rerunning the RI Builder updates stored procedure code and table triggers used to enforce referential integrity. If you do not rerun the RI Builder, you might receive unexpected results because the stored procedures and triggers were not updated.

See Also

Other Resources

How to: Open Databases
Databases in Visual FoxPro
How to: Create Persistent Relationships
How to: Create Stored Procedures
Creating Databases
Working with Items in Databases


How to: Create and Manage Stored Procedures

Visual FoxPro 9.0
How to: Create and Manage Stored Procedures
See Also

You can create, edit, copy, and delete stored procedures in your database. A stored procedure is Visual FoxPro code that is stored in the database (.dbc) file and operates specifically on data in the database.

To create a stored procedure

  1. Open the database in the Database Designer.

  2. On the Database menu, click Edit Stored Procedures.

An editing window opens so you can write code for the stored procedure.

To create a stored procedure for a database in a project

  1. Open the project in the Project Manager.

  2. In the Project Manager, expand the Data node, the Databases node, and then the database node in which you want to add a stored procedure.

  3. Click the Stored Procedures node and then New.

An editing window opens so you can write code for the stored procedure.

To create a stored procedure programmatically

  • Use the MODIFY PROCEDURE command.

For more information, see MODIFY PROCEDURE Command.

To edit a stored procedure

  • Perform one of the following:

    • To edit a stored procedure from the Database Designer, on the Database menu, click Edit Stored Procedures.

    -OR-

    • To edit a stored procedure from the Project Manager, click the Stored Procedures node, and then Modify.

    • -OR-

    • Use the MODIFY PROCEDURE command.

An editing window opens so you can edit code for the stored procedure.

To copy and append stored procedures to a text file

  • Use the COPY PROCEDURES and APPEND PROCEDURES commands.

For more information, see COPY PROCEDURES Command and APPEND PROCEDURES Command.

To delete a stored procedure

  1. Open the editing window for the stored procedure.

  2. In the editing window, select the code you want to delete.

  3. Press the DELETE key.

See Also

Other Resources

How to: Open Databases
Handling Database Errors
Databases in Visual FoxPro
Creating Databases


Working with Database Container Events

Visual FoxPro 9.0
Working with Database Container Events

You can use database container (DBC) events to execute procedure code when those events occur.

Note:
DBC events are not available in versions prior to Visual FoxPro 7.0. Attempting to access a DBC events-enabled database using a version prior to Visual FoxPro 7.0 generates an error.

In This Section

Database Container Events

Introduces and describes database container (DBC) events.
How to: Enable or Disable DBC Events

Describes how to activate or deactivate DBC events.
How to: Add Code to a DBC Event

Describes how to add code to DBC events.

Related Sections

Understanding the Event Model

Introduces events and how you can use them to perform operations when the system or user performs an action.
Designing Databases

Describes design considerations for creating well-planned databases.
Creating Databases

Describes creating databases and working with tables associated with databases.


Database Container Events

Visual FoxPro 9.0
Database Container Events
See Also

Database container (DBC) events occur when actions occur in a database. You can add procedure code to these events that executes when those events occur.

The following table describes available DBC events.

DBC events | Description
DBC_Activate | Occurs when an open database becomes the current database.
DBC_Deactivate | Occurs when a database is no longer the current database.
DBC_BeforeAddRelation | Occurs before adding a relation to the database.
DBC_AfterAddRelation | Occurs after adding a relation to the database successfully.
DBC_BeforeAddTable | Occurs before adding a table to an open database.
DBC_AfterAddTable | Occurs after adding a table to an open database.
DBC_BeforeAppendProc | Occurs before completing the APPEND PROCEDURES operation in the current DBC stored procedue. Use to prevent the append operation. Also, use to discover the name of the DBC involved.
DBC_AfterAppendProc | Occurs after completing the APPEND PROCEDURES operation.
DBC_BeforeCloseTable | Occurs before closing a table or view.
DBC_AfterCloseTable | Occurs after closing a table or view.
DBC_BeforeCopyProc | Occurs before beginning the copy procedure operation in the current DBC. Use to prevent the operation. Also, use to discover the name of the DBC involved.
DBC_AfterCopyProc | Occurs after completing the copy procedure operation in the current DBC. Use to discover the name of the DBC involved.
DBC_BeforeCreateConnection | Occurs before creating a connection. Use to prevent creating the connection or opening the connection designer.
DBC_AfterCreateConnection | Occurs after creating a connection.
DBC_BeforeCreateOffline | Occurs before taking a view offline. Use to prevent offline view.
DBC_AfterCreateOffline | Occurs after completing the CREATEOFFLINE( ) fuction.
DBC_BeforeCreateTable | Occurs before creating a table in an open database.
DBC_AfterCreateTable | Occurs after creating a table in an open database.
DBC_BeforeCreateView | Occurs before creating a view. Use to prevent view from being created or view designer from being opened.
DBC_AfterCreateView | Occurs after creating a view.
DBC_BeforeDBGetProp | Occurs before running DBGETPROP( ).
DBC_AfterDBGetProp | Occurs after completing DBGETPROP( ).
DBC_BeforeDBSetProp | Occurs before running DBSETPROP( ) or when the "Event" property is changed.
DBC_AfterDBSetProp | Occurs after completing DBSETPROP( ) or when the "Event" property is changed.
DBC_BeforeDeleteConnection | Occurs before dropping a connection.
DBC_AfterDeleteConnection | Occurs after dropping a connection.
DBC_BeforeDropOffline | Occurs before returning a view to online. Use to prevent bringing offline view back online.
DBC_AfterDropOffline | Occurs after completing DROPOFFLINE( ).
DBC_BeforeDropRelation | Occurs before dropping a relation from a database.
DBC_AfterDropRelation | Occurs after dropping a relation from a database successfully.
DBC_BeforeDropTable | Occurs before removing a table from the DBC and deleting from disk.
DBC_AfterDropTable | Occurs after removing a table from the DBC and deleting from disk.
DBC_BeforeDropView | Occurs before removing a view from the DBC. Use to prevent view from being dropped.
DBC_AfterDropView | Occurs after removing a view from the DBC.
DBC_BeforeModifyConnection | Occurs before modifying a connection.
DBC_AfterModifyConnection | Occurs after modifying a connection.
DBC_BeforeModifyProc | Occurs before modifying a DBC-stored procedure in an open DBC. Use to prevent modification. Also, use to discover the name of the current DBC.
DBC_AfterModifyProc | Occurs after modifying and closing the stored procedure file for the DBC.
DBC_BeforeModifyTable | Occurs before modifying a table.
DBC_AfterModifyTable | Occurs after modifying a table.
DBC_BeforeModifyView | Occurs before modifying a view.
DBC_AfterModifyView | Occurs after modifying a view.
DBC_BeforeOpenTable | Occurs before opening a table or view.
DBC_AfterOpenTable | Occurs after opening a table or view.
DBC_BeforeRemoveTable | Occurs before removing a table from the DBC.
DBC_AfterRemoveTable | Occurs after removing a table from the DBC.
DBC_BeforeRenameConnection | Occurs before renaming a connection.
DBC_AfterRenameConnection | Occurs after renaming a connection.
DBC_BeforeRenameTable | Occurs before renaming a table.
DBC_AfterRenameTable | Occurs after renaming a table.
DBC_BeforeRenameView | Occurs before renaming a view.
DBC_AfterRenameView | Occurs after renaming a view.
DBC_BeforeValidateData | Occurs before executing VALIDATE DATABASE. Return .F. to prevent the DBC from being validated.
DBC_AfterValidateData | Occurs after completing VALIDATE DATABASE.
DBC_ModifyData | Occurs immediately after Modify Data is issued. Use to prevent opening of Schema window. Also, can open a closed database.
DBC_OpenData | Occurs when a database opens or when a MODIFY DATABASE command is issued against a closed database. Use to close an open database.
DBC_CloseData | Closes an open database.
DBC_PackData | Occurs before executing PACK DATABASE. Use to prevent the DBC from being packed.

See Also

Other Resources

How to: Enable or Disable DBC Events
How to: Add Code to a DBC Event
Developing Databases
Working with Database Container Events


How to: Enable or Disable DBC Events

Visual FoxPro 9.0
How to: Enable or Disable DBC Events
See Also

Before you can add procedure code to Database Container (DBC) events, you need to activate them. When you do not want to execute code in DBC events, you can deactivate them.

Caution:
DBC events are not available in versions prior to Visual FoxPro 7.0. Therefore, activating DBC events makes the database incompatible with versions prior to Visual FoxPro 7.0. Attempting to access a DBC events-enabled database using a version prior to Visual FoxPro 7.0 generates an error.

To activate DBC events

  1. Open database in the Database Designer.

  2. On the Database menu, click Properties.

  3. In the Database Properties dialog box, click Set Events On.

  4. Click OK.

For more information, see Database Properties Dialog Box.

To activate DBC events programmatically

  1. Make sure the database is open as the current database.

  2. Use the DBSETPROP( ) function.

For example, the following code activates DBC events:

Copy Code
DBSETPROP(cDBCName,'Database','DBCEvents',.T.)

For more information, see DBSETPROP( ) Function.

To deactivate DBC events

  1. Open database in the Database Designer.

  2. On the Database menu, click Properties.

  3. In the Database Properties dialog box, clear Set Events On.

  4. Click OK.

For more information, see Database Properties Dialog Box.

To deactivate DBC events programmatically

  • Use the DBSETPROP( ) function.

For example, the following code deactivates DBC events:

Copy Code
DBSETPROP(cDBCName,'Database','DBCEvents',.F.)

See Also

Other Resources

Database Container Events
How to: Add Code to a DBC Event
Working with Database Container Events


How to: Add Code to a DBC Event

Visual FoxPro 9.0
How to: Add Code to a DBC Event
See Also

You can add procedure code to a DBC event by storing it in the stored procedures file for the database or in a separate program (.prg) file. When DBC events are are activated for a database, the procedure code runs.

To add code to a DBC event

  1. Open database in the Database Designer.

  2. On the Database menu, click Properties.

    The Database Properties dialog box opens. If you activated DBC events for the database, the Events File check box appears available.

  3. In the Events list, click an event.

    Tip:
    To select multiple events, press and hold the SHIFT key while you click each event.

  4. Choose one of the following:

    • To add code to the stored procedure file for the current database, click Edit Code.

    -OR-

    • To add code to an external file, click the Events File check box.

      If no file is specified, the Open dialog displays so you can specify a file. If a file is already been specified, click the ellipsis (...) button to display the Open dialog box.

      Caution:
      Selecting the Events File check box changes the structure of the database and makes the database no longer compatible with versions prior to Visual FoxPro 7.0 or the Visual FoxPro ODBC Driver. Clearing the Events File check box makes the database compatible.

An editing window for the stored procedures or external file opens with procedure template codes for the DBC event.

See Also

Other Resources

Database Container Events
How to: Enable or Disable DBC Events
Working with Database Container Events


Managing Databases

Visual FoxPro 9.0
Managing Databases

You can perform different tasks to manage databases.

In This Section

How to: Add Databases to Projects

Describes how to add databases to an application project.
How to: Open Databases

Describes how to open existing databases and work with a visual representation of them.
How to: Set the Current Database

Describes how to set a database as the current one.
How to: Validate a Database

Describes how to validate the integrity of the database (.dbc) file.
Handling Database Errors

Describes how to provide custom error messages instead of generic database errors by using triggers.
How to: Close Databases

Describes how to close databases.
How to: Remove Databases from Projects

Describes how to remove databases from an application project.
How to: View Database Structure

Describes how to view the structure of the database (.dbc) file, which contains information about the database.
How to: Extend Database Files

Describes how to add user-defined fields to a database (.dbc) file.

Reference

Database Designer

Makes it possible for you to create databases starting with an empty database container or modify existing databases.
Project Manager

Makes it possible for you to organize files in an application project.
Databases

Lists programming language you can use to work with databases.

Related Sections

Working with Items in Databases

Introduces and describes how to perform tasks with items in databases, such as displaying them, arranging them, adding items, defining relationships, updating links between a database and its tables, creating rules governing adding, updating, and deleting records, and so on.
Designing Databases

Describes design considerations for creating well-planned databases.
Developing Databases

Introduces and describes using databases to store, organize, and work with tables and views as a collection.


How to: Add Databases to Projects

Visual FoxPro 9.0
How to: Add Databases to Projects
See Also

You can add databases to a project for an application.

To add a database to a project

  1. Open the project in the Project Manager Window.

  2. In the Project Manager, expand the Data node.

  3. Click the Databases node, and then Add.

  4. In the Select database name dialog box, browse to and select the database (.dbc) file for the database you want to add, and click OK.

    The database you select appears in the Databases node of the Project Manager.

See Also

Other Resources

Creating Databases
Managing Databases


How to: Open Databases

Visual FoxPro 9.0
How to: Open Databases
See Also

To add, access, and edit items in a database, open the database. When you open a database, Visual FoxPro sets it as the current database and adds the database name to the database list on the Visual FoxPro standard toolbar. By default, items that you create or add to the database are associated with the current database, and commands or functions that manipulate open databases operate on the current database. You can also set another open database as the current database. For more information, see How to: Set the Current Database.

Note:
Opening a new database does not close any currently open databases. However, the most recently opened database becomes the current database.

You can have multiple open databases at the same time. For example, you might open and use multiple databases when you run multiple applications with each using a different database. You might also want to open multiple databases to use information, such as custom controls, in a database that is separate from your application's database.

Note:
Visual FoxPro might open one or more databases automatically when you execute a query or a form that requires opening databases. To make sure you are working with the correct database, set the current database explicitly before using any commands that operate on the current database. For more information, see How to: Set the Current Database.

Opening the database in the Database Designer makes it possible for you to view the database schema, a visual representation of the database, and work with the tables associated with it, the relationships between those tables, and other items in the database. To view the structure of the database (.dbc) file itself, see How to: View Database Structure.

To open a database in the Database Designer

  1. On the File menu, click Open.

  2. In the Open dialog box, browse for and select the database (.dbc) file you want to open.

  3. Click OK.

    The database you selected opens in the Database Designer, which displays any items it contains and any relationships between them.

For more information, see Database Designer.

To open a database in a project

  1. Open the project in the Project Manager.

  2. In the Project Manager, expand the Data node, then the Databases node.

  3. Click the name of the database you want to open.

  4. Perform one of the following:

    • To open the database without opening the Database Designer, click Open or expand the node for the database.

    -OR-

    • To open the database in the Database Designer, click Modify.

      The database you selected opens in the Database Designer, which displays any items it contains and any relationships between them.

For more information, see Project Manager Window.

To open a database programmatically

  • Perform one of the following:

    • To open the database without opening the Database Designer, use the OPEN DATABASE command.

      -OR-

    • To open the database in the Database Designer, use the MODIFY DATABASE command.

For more information, see OPEN DATABASE Command and MODIFY DATABASE Command.

See Also

Other Resources

Working with Items in Databases
Creating Databases
Managing Databases
Developing Databases


How to: Set the Current Database

Visual FoxPro 9.0
How to: Set the Current Database
See Also

You can a set a different database as the current database when more than one database is open. However, you can set only one open database as the current database.

To set the current database

  • Perform one of the following:

    • In the database list on the standard toolbar, select a database.

      -OR-

    • Use the SET DATABASE command.

The database you select is set as the current database.

For more information, see SET DATABASE Command.

See Also

Other Resources

How to: Open Databases
Managing Databases
Developing Databases


How to: Validate a Database

Visual FoxPro 9.0
How to: Validate a Database
See Also

You can make sure that information about database tables, such as their location, indexes, and index tags, are correctly stored in the database by validating the database.

To validate a database

  • Use the VALIDATE DATABASE command.

For more information, see VALIDATE DATABASE Command.

See Also

Other Resources

Handling Database Errors
Managing Databases
Developing Databases


Handling Database Errors

Visual FoxPro 9.0
Handling Database Errors
See Also

Database errors or "engine errors" occur when errors occur at run time in record-level event code. For example, a database error occurs when a user attempts to store a null value in a field that does not accept null values.

Typically, when a database error occurs, the underlying database engine that detects the error generates an error message. However, the exact nature of the error message depends on the database that is accessed. For example, error messages generated by a remote database server might be different than those generated by a local Visual FoxPro database table. In addition, engine-level errors can be generic because the database engine has no information about the context for updating a record. As a result, error messages generated by a database engine are not as useful to a Visual FoxPro application user.

To handle database errors in a more application-specific way, you can create triggers. A trigger is an expression that is bound to a table and is invoked when any of the table's records are modified using a one of the specified data manipulating commands. You can write trigger code in the form of user-defined functions or stored procedures using the CREATE TRIGGER command to trap application-specific error conditions and generate appropriate messages.

Tip:
If you handle database errors using triggers, two error messages can occur: one from your trigger and another from the underlying database engine. You can avoid this possibility by turning buffering on. Buffering makes it possible to delay record updates to the underlying database but to still call your trigger when the record is updated. You can turn on buffering and display custom error messages using the CURSORSETPROP( ) function. For more information, see CURSORSETPROP( ) Function.

For more information, see CREATE TRIGGER Command and How to: Create and Manage Stored Procedures.

See Also

Other Resources

How to: Validate a Database
Managing Databases
Developing Databases


How to: Close Databases

Visual FoxPro 9.0
How to: Close Databases
See Also

You can close an open database interactively or programmatically.

To close a database

  • Perform one of the following:

    • In the Project Manager, if the node for the database is expanded, collapse the node.

    -OR-

    • In the Project Manager, click the name of the open database, and then Close.

    -OR-

    • In the Database Designer, close the designer window.

    The database closes.

To close a database programmatically

  • Use the CLOSE DATABASES command.

For more information, see CLOSE DATABASES Command.

Note:
Using CLOSE DATABASES in the Command window does not close a database if the database was opened in the Project Manager by expanding its node or when a form is running in its own data session. Under these circumstances, the database remains open until it is closed in Project Manager or until the form using the database closes.

See Also

Other Resources

Managing Databases
Developing Databases


How to: Remove Databases from Projects

Visual FoxPro 9.0
How to: Remove Databases from Projects
See Also

You can remove a database from a project or delete it from disk permanently. Removing a database does not automatically delete the database. Deleting the database using the steps described makes it possible for Visual FoxPro to remove the back link information in the database tables.

Note:
Using other methods such as searching for the database files and deleting them using Windows Explorer does not remove back link information.

To remove or delete a database from a project

  1. Open the project in the Project Manager Window.

  2. In the Project Manager, expand the Data node, then the Databases node.

  3. Click the database you want to remove, and then Remove.

    Visual FoxPro prompts you to remove the database from the project or delete it from disk.

  4. In the confirmation dialog box, perform one of the following:

    • To remove the database from the project, click Remove.

    -OR-

    • To delete the database from disk, click Delete.

To delete a database programmatically

  • Use the DELETE DATABASE command.

    Note:
    DELETE DATABASE does not delete database tables from disk. Instead, database tables become free tables.

    Tip:
    To delete a database and its associated tables from disk, use the DELETE DATABASE command with the DELETETABLES clause.

For more information, see DELETE DATABASE Command.

For example, the following code deletes a database named MyDatabase from disk:

Copy Code
DELETE DATABASE MyDatabase

See Also

Other Resources

Creating Databases
Managing Databases


How to: View Database Structure

Visual FoxPro 9.0
How to: View Database Structure
See Also

While the Database Designer displays a visual and conceptual representation of the database, you might want to examine the structure of the database (.dbc) file, which is a table. The database file contains a record for each table, view, index, index tag, persistent relationship, and connection associated with the database as well as a record for each table field or view field that has extended properties. It also includes a single record that contains all the stored procedures for the database. For more information, see Table File Structure.

You can examine the contents of a database file by browsing the file.

To browse a database file

  1. Close the database.

  2. Use the USE command with the name of the database file, including the .dbc file name extension, and the EXCLUSIVE keyword.

  3. On the next line, follow the USE command with the BROWSE command.

    Caution:
    Do not use BROWSE to modify the contents of the database file unless you understand database file structure. If an error occurs while attempting to change the database file, the database might become invalid and potentially lose data. Instead, use MODIFY STRUCTURE to add fields. For more information, see How to: Extend Database Files.

For example, the following code opens a browse window and displays the contents of a database named MyDatabase as a table:

Copy Code
CLOSE MyDatabase
USE MyDatabase.dbc EXCLUSIVE
BROWSE

See Also

Other Resources

Managing Databases
Developing Databases


How to: Extend Database Files

Visual FoxPro 9.0
How to: Extend Database Files
See Also

Each record in the database (.dbc) file has a Memo field named User. You can use this field to store additional information about each record in the database file. You can also add user-defined fields to the end of a database file.

Note:
To modify the structure of a database file, you must open the database file exclusively.

Caution:
Do not change any existing Visual FoxPro- defined fields in a database file. Any changes you make to a database file might affect the validity of your database.

To add a field to a database file

  1. Close the database.

  2. Use the USE command with the name of the database file, including the .dbc file name extension, and the EXCLUSIVE keyword.

  3. On the following line, use the MODIFY STRUCTURE command.

    The Table Designer opens for the database file.

You can now add fields to the database file.

Tip:
When you add a new field to a database file, begin the field name with the letter "U" to designate it as a user-defined field. This designation prevents your field from conflicting with any future extensions to the database file.

For example, the following code first closes the database MyDatabase, opens the database file MyDatabase.dbc exclusively, and then opens the Table Designer for the database file so you can add fields:

Copy Code
CLOSE MyDatabase
USE MyDatabase.dbc EXCLUSIVE
MODIFY STRUCTURE

See Also

Other Resources

How to: View Database Structure
Managing Databases
Developing Databases


Working with Tables (Visual FoxPro)

Visual FoxPro 9.0
Working with Tables (Visual FoxPro)

Visual FoxPro uses tables to store data in row and column format. These rows and columns are known as records and fields, respectively. Building databases also includes creating tables. When designing your database, you determined the items you needed in databases, such as tables, fields, and relationships, for your application. When you create tables, you make more specific choices concerning the details of those items, for example, data types, captions, and possible default values for each field, triggers for each table, and table indexes needed to establish relationships between tables.

In This Section

Creating Tables

Introduces tables and considerations for creating tables.
Managing Tables

Describes tasks for managing and working with tables.
Working with Fields

Introduces creating and working with fields in tables.
Working with Records

Introduces records, how to view them, and how to use them to store data in tables.
Working with Table Indexes

Explains how to control the order and increase the speed for processing records in tables by creating indexes.
Working with Validation Rules

Introduces validation rules for controlling data entered in database tables.
Trigger Usage

Gives a description of triggers and how they are used and points to topics on creating, modifying, removing, and deleting triggers.

Related Sections

Working with Data

Find out how to create effective applications with indexes, tables, and databases based on your data requirements.
Developing Databases

Describes how to use databases in Visual FoxPro to establish relationships between tables, enforce referential integrity, and manage local and remote data.
Importing and Exporting Data

Information is copied between Visual FoxPro and other applications by importing to and exporting from Visual FoxPro.


Creating Tables

Visual FoxPro 9.0
Creating Tables

You can create tables to store data in row and column format. You can create free tables or database tables depending on your needs. Considerations also exist when you create tables. The following topics contain information for creating tables and defining the fields and their attributes that make up the structure of a table.

In This Section

Table Creation

Introduces tables and the benefits of using tables to store data.
How to: Create Free Tables

Describes how to create standalone tables.
How to: Create Database Tables

Describes how to create tables associated with a database.
How to: Name Tables

Describes how to specify names for tables or long names for database tables.
How to: Edit Table Structure

Describes how to edit the structure of a table, which defines fields and their attributes, indexes, and other table information.

Reference

Table Wizard

Makes it possible for you to create tables using a wizard.
Table Designer

Makes it possible for you to create the field structure for tables starting with an empty table or modify the structure of existing tables.
Table Manipulation Language

Lists programming language you can use to work with tables.

Related Sections

Managing Tables

Discusses tasks you can perform to manage tables.
Working with Tables

Introduces creating and working with tables.
Enforcing Business Rules

Describes how to enforce business rules by creating validation rules at the field-level and record-level.
Trigger Usage

Introduces using triggers that are invoked when table records are modified using data manipulating commands.


Table Creation

Visual FoxPro 9.0
Table Creation
See Also

Tables store data in a row and column format, similar to a spreadsheet. Each row represents a record, and each column represents the fields in each record. Tables in Visual FoxPro can exist as a free table or as a database table.

A free table is a table (.dbf) file that is not associated with any database. A database table is a table file that is associated with a database. Database tables can have properties that free tables do not have, such as field-level and record-level rules, triggers, and persistent relationships. The following list includes some of the benefits database tables offer:

  • Long names for the table and for each field in the table.

  • Captions and comments for each table field.

  • Default values, input masks, and format for table fields.

  • Default control class for table fields.

  • Field-level and record-level rules.

  • Primary key indexes and table relationships to support referential integrity rules.

  • One trigger for each INSERT, UPDATE, or DELETE event.

However, free tables are useful for storing information outside of a database. For example, for example, you can use free tables to store lookup information that multiple databases share. For more information about the benefits of associating tables with a database, see Databases in Visual FoxPro.

To view a sample table, open one of the table (.dbf) files for the Northwind database located in the Visual FoxPro ...\Samples\Northwind directory. For more information, see How to: View Records in Tables.

Considerations for Table Creation

When creating tables, remember the following considerations:

  • Make sure field's data type matches the type of information you want to store.

  • Make sure the field is wide enough to accommodate the information it stores and displays.

  • Set an appropriate number of decimal places for Numeric or Float fields.

  • Make sure that fields that can accept null values are configured to accept them.

See Also

Other Resources

Creating Tables
How to: Create Free Tables
How to: Create Database Tables
Working with Tables


How to: Create Database Tables

Visual FoxPro 9.0
How to: Create Database Tables
See Also

You can use a wizard to help you create a database table, or you can create an empty database table. A wizard helps you create a table using your answers to a series of questions.

Note:
When you create a database table with an open database, the database table is associated automatically with the open database. If multiple databases are open, the table is associated with the open database set as the current database. The table's association with the database is stored as a back link in the table's header record. For more information, see Databases in Visual FoxPro and How to: Open Databases.

When you create a table, a table (.dbf) file is created to store the table file. For information about naming tables, see How to: Name Tables.

To create a database table using a wizard

  1. Open the database you want to create a table in.

  2. On the Database menu, click Create Table.

  3. In the New Table dialog box, click Table Wizard.

  4. Follow the instructions on the wizard screens.

For more information, see Table Wizard.

You can also begin the wizard from a project in the Project Manager by expanding the Data node, the Databases node, and then node for your database. Click the Tables node, and then New. In the New Table dialog box, click Table Wizard. For more information, see Project Manager Window.

To create an empty database table

  1. Open the database you want to create a table in.

  2. On the Database menu, click Create Table.

  3. In the New Table dialog box, click New Table.

  4. In the Create dialog box, select the location you want to save the database table, and type a name for the table.

  5. Click Save.

    The Table Designer opens so you can specify table fields, items, and other attributes.

For more information, see Table Designer.

To create a database table in a project

  1. Open the project with the database in the Project Manager.

  2. In the Project Manager, expand the Data node, the Databases node, and then node for your database.

  3. Click the Tables node, New, and then New Table.

  4. In the Create dialog box, select the location you want to save the database table, and type a name for the table.

  5. Click Save.

    The Table Designer opens so you can specify table fields, items, and other attributes.

For more information, see Project Manager Window and Table Designer.

To create a database table programmatically

  1. Open the database you want to create a table for.

  2. Perform one of the following:

    • To create a table by opening the Table Designer, use the CREATE command.

      -OR-

    • To create a table without opening the Table Designer, use the SQL CREATE TABLE command.

For more information, see CREATE Command and CREATE TABLE - SQL Command.

See Also

Other Resources

How to: Edit Table Structure
Working with Tables
Creating Tables


How to: Create Free Tables

Visual FoxPro 9.0
How to: Create Free Tables
See Also

You can create free tables using a wizard or as an empty table. A wizard helps you create a table using your answers to a series of questions.

When you create a table, a table (.dbf) file is created to store the table file. For information about naming tables, see How to: Name Tables.

To create a free table using a wizard

  1. On the File menu, click New.

  2. In the New dialog box, click Table, then Wizard.

  3. Follow the instructions on the wizard screens.

For more information, see Table Wizard.

You can also begin the wizard from a project in the Project Manager by expanding the Data node, click the Free Tables node, and then New. In the New Table dialog box, click Table Wizard. For more information, see Project Manager Window.

To create an empty free table

  1. On the File menu, click New.

  2. In the New dialog box, click Table, and then New file.

  3. In the Create dialog box, select the location you want to save the database table, and type a name for the table.

  4. Click Save.

    The Table Designer opens so you can specify table fields, items, and other attributes.

For more information, see Table Designer.

To create a free table in a project

  1. Open the project in the Project Manager.

  2. In the Project Manager, expand the Data node.

  3. Click the Free Tables node, and then New.

  4. In the New Table dialog box, click New Table.

  5. In the Create dialog box, select the location you want to save the database table, and type a name for the table.

  6. Click Save.

    The Table Designer opens so you can specify table fields, items, and other attributes.

For more information, see Project Manager Window and Table Designer.

To create a free table programmatically

  • Perform one of the following:

    • To create a table by opening the Table Designer, close any open databases and use the CREATE command.

    -OR-

    • To create a table without opening the Table Designer, use the SQL CREATE TABLE command. If a database is open, include the FREE keyword.

For more information, see CREATE Command and CREATE TABLE - SQL Command.

See Also

Other Resources

Table Creation
How to: Edit Table Structure
Creating Tables
Working with Tables


How to: Name Tables

Visual FoxPro 9.0
How to: Name Tables
See Also

When you create a table, you need to specify a name for the table (.dbf) file created to store the table. Both database tables and free tables require table file names. Table names must begin with a letter or underscore and can consist of letters, digits, or underscores.

If your table is in a database, you can specify a long table name, which can contain up to 128 characters, in addition to the table file name. You can use long table names instead of conventional file names to identify the table in a database more easily. Visual FoxPro displays long table names when the table appears in the Visual FoxPro interface, for example in the Project Manager, the Database Designer, the Query Designer, and the View Designer as well as in the title bar of a browse window.

Note:
If you remove a table from a database, the table retains its file name but not its long name.

To assign a long table name to a database table

  1. Open the database table in the Table Designer.

  2. In the Table Designer, click the Table tab.

  3. In the Name box, type a long name for the table.

To assign a long table name to a database table programmatically

  • Include the NAME clause when creating a database table with the SQL CREATE TABLE command.

For more information, see Table Designer and CREATE TABLE - SQL Command.

Renaming Tables

You can rename the long names for database tables and the file names of database and free tables. You can rename the long names of database tables using the Table Designer because you are changing the long name, not the table file name. You can rename free tables only programmatically because free tables do not have long names.

To change the long name of a database table

  1. Open the database in the Database Designer.

  2. Find and make the table you want to rename active.

  3. On the Database menu, click Modify.

  4. In the Table Designer, click the Table tab.

  5. In the Name box, type a new name for the table.

For more information, see Database Designer and Table Designer.

To rename a database table programmatically

  1. Set the database containing the table you want to rename as the current database.

  2. Use the RENAME TABLE command.

For more information, see RENAME TABLE Command.

To rename a free table programmatically

  • Use the RENAME command.

    Caution:
    Do not use the RENAME command on database tables. RENAME does not update the table's back link to the database and might cause errors when accessing the table. Use the RENAME TABLE command instead.

For more information, see RENAME Command.

See Also

Other Resources

How to: Create Database Tables
How to: Create Free Tables
Creating Tables
Working with Tables


How to: Edit Table Structure

Visual FoxPro 9.0
How to: Edit Table Structure
See Also

You can edit the structure of a table, which defines the fields and their attributes as well as indexes for the table.

To edit the structure of a free table

  1. On the File menu, click Open.

  2. In the Open dialog box, browse to and select the table (.dbf) file you want to open, and click OK.

  3. On the View menu, click Table Designer.

    The Table Designer opens so you can change attributes for fields, indexes, and the table.

For more information, see Table Designer.

To edit the structure of a database table

  1. Open the database in the Database Designer.

  2. In the Database Designer, click the table you want to edit.

  3. On the Database menu, click Modify.

The Table Designer opens so you can change attributes for fields, indexes, and the table.

To edit the structure of a table in a project

  1. Open the project in the Project Manager.

  2. In the Project Manager, expand the Data node.

  3. Choose one of the following:

    • Expand the Databases node, the database node containing the table, then the Tables node, and click the table whose structure you want to edit.

    -OR-

    • Expand the Free Tables node, and click the table whose structure you want to edit.

  4. In the Project Manager, click Modify.

    The Table Designer opens so you can change attributes for fields, indexes, and the table.

For more information, see Table Designer.

To edit the structure of a table programmatically

  1. Open the table with the USE command.

  2. Choose one of the following:

    • To edit the structure by opening the Table Designer, use the MODIFY STRUCTURE command.

      -OR-

    • To edit the structure without opening the Table Designer, use the SQL ALTER TABLE command.

For more information, see USE Command, MODIFY STRUCTURE Command, and ALTER TABLE - SQL Command.

See Also

Other Resources

How to: View Records in Tables
Working with Tables
Creating Tables


Managing Tables

Visual FoxPro 9.0
Managing Tables

You can perform different tasks to manage tables.

In This Section

How to: Open Tables

Describes how to open free tables, database tables, and tables in projects.
How to: Copy Tables

Describes how to copy the structure and contents of a table to a new table.
How to: Save a Table as HTML

Describes how to save the contents of a table as HTML.
How to: Close Tables

Describes how to close tables.
How to: Delete Tables

Describes how to delete tables.
Managing Tables in Data Sessions

Describes how to manage tables in data sessions, which are separate working environments for a form, form set, or report.

Related Sections

Creating Tables

Introduces creating tables and considerations for creating tables.
Creating Databases

Describes creating databases and working with tables associated with databases.
Working with Tables

Discusses how to structure your tables to meet your application requirements. Data type and index choices are essential to the success of your application.


How to: Open Tables (Visual FoxPro)

Visual FoxPro 9.0
How to: Open Tables (Visual FoxPro)
See Also

To work with tables and add data to tables, you must first open them.

To open a free table

  1. On the File menu, click Open.

  2. In the Open dialog box, browse to and select the table (.dbf) file you want to open, and click OK.

    The table opens even though the table does not appear.

To display the records in the table, open a browse window. To display the table structure, open the Table Designer. For more information, see How to: View Records in Tables and How to: Edit Table Structure.

To open a database table

  1. Open the database in the Database Designer.

  2. Click the table you want to open.

  3. To open the table, perform one of the following:

    • Open a browse window for the table.

    -OR-

    1. On the Window menu, click Data Session.

    2. In the Data Session window, click Open.

      The Open dialog box appears.

    3. In the Tables in database list, click the table you want to open, and then OK.

      The table you selected opens and appears in the Data Session window.

For more information, see How to: View Records in Tables and Managing Tables in Data Sessions.

To open a table in a project

  1. Open the project in the Project Manager.

  2. In the Project Manager, expand the Data node.

  3. Select a database table or a free table:

    • To open a database table, expand the Databases node, then the database node containing the table, then the Tables node, and click the table you want to open.

      Note:
      Double-clicking the table opens the Table Designer. For more information, see Creating Tables.

      -OR-

    • To open a free table, expand the Free Tables node, and click the table you want to open.

  4. To browse the table, on the View menu, click Browse. To open the table in a data session, perform the following:

    1. On the Window menu, click Data Session.

    2. In the Data Session window, click Open.

      The Open dialog box appears.

    3. In the Tables in database list, click the table you want to open, and then OK.

      The table you selected opens and appears in the Data Session window.

For more information, see How to: View Records in Tables and Managing Tables in Data Sessions.

To open a table programmatically

  • Use the USE command.

For more information, see USE Command.

See Also

Other Resources

Working with Tables
Managing Tables


How to: Copy Tables

Visual FoxPro 9.0
How to: Copy Tables
See Also

You can copy tables in two steps:

  1. Copy the table structure.

  2. Copy the data from the source table to the destination table.

To copy the structure of a table

  1. Open the source table with the USE command.

  2. Copy the source table structure and create the destination table by choosing one of the following:

    • To copy only the table structure not including information such as default values, triggers, and validation rules, use the COPY STRUCTURE command.

    -OR-

    • To copy the table structure including information such as default values, triggers, and validation rules, use the COPY STRUCTURE EXTENDED command.

For more information, see USE Command, COPY STRUCTURE Command, and COPY STRUCTURE EXTENDED Command.

To copy data between tables

  1. Open the source table and destination table with the USE command.

  2. Copy the data from the source table to the destination table with the APPEND FROM command.

For more information, see USE Command and APPEND FROM Command.

See Also

Other Resources

How to: Edit Table Structure
Working with Tables
Managing Tables


How to: Save a Table as HTML

Visual FoxPro 9.0
How to: Save a Table as HTML
See Also

When you browse a table, you can save the contents of a table as an HTML file.

To save a table as HTML

  1. Open the table in a browse window.

  2. On the File menu, click Save As HTML.

  3. In the Save As HTML dialog box, click the option you want.

  4. To specify a different location to save the file, click the ellipsis (...) button. Otherwise, click OK.

For more information, see How to: View Records in Tables.

See Also

Other Resources

How to: Copy Tables
Working with Tables
Managing Tables


How to: Close Tables

Visual FoxPro 9.0
How to: Close Tables
See Also

When you are finished working with tables, close them.

To close a table

  1. On the Window menu, click Data Session.

  2. In the Data Session window, click the alias for the table you want to close, then Close.

    The table closes.

To close a table programmatically

  • Use the CLOSE command with the TABLES keyword.

    Note:
    CLOSE TABLES closes all tables in the currently selected database or all free tables in all work areas if no database is open.

For more information, see CLOSE Commands.

See Also

Other Resources

How to: Delete Tables
Working with Tables
Managing Tables


How to: Delete Tables

Visual FoxPro 9.0
How to: Delete Tables
See Also

You can remove tables or delete them permanently from disk when you no longer need them. For information about removing and deleting database tables, see How to: Remove a Table from a Database.

Note:
If you delete a table that has files associated with it, such as a memo file (.fpt) or index files (.cdx or .idx), make sure to delete those files.

To remove or delete a free table

  1. Open the project in the Project Manager.

  2. In the Project Manager, expand the Data node, then the Free Tables node.

  3. In the Free Tables node, click the table you want, and then Remove.

    A confirmation dialog displays so you can choose to remove or delete the table.

  4. In the confirmation dialog box, choose one of the following

    • To remove the table from the project, click Remove.

      -OR-

    • To delete the table permanently from disk, click Delete.

For more information, see Project Manager Window.

To delete a free table programmatically

  1. Close the table with the CLOSE command and the TABLES keyword.

  2. Delete the file by using the DELETE FILE command or the ERASE command.

For more information, see DELETE FILE Command and ERASE Command.

See Also

Other Resources

Working with Tables
Managing Tables


Managing Tables in Data Sessions

Visual FoxPro 9.0
Managing Tables in Data Sessions

When you have multiple tables, you can use data sessions to control the tables that forms can access and work areas to determine which tables are open in data sessions.

In This Section

Work Areas in Data Sessions

Introduces using work areas in data sessions and table aliases to identify open tables.
Temporary Relationships Between Tables

Introduces how to move the record pointer in a table when it moves in another table by setting temporary relationships between tables.
How to: Open Tables in Work Areas

Describes how to open tables in work areas.
How to: Create and Use Table Aliases

Describes how to create use-defined aliases and reference tables in other work areas using aliases.
How to: Set Temporary Relationships Between Tables

Describes how to set temporary relationships between tables or in a single table.
How to: Close Tables in Work Areas

Describes how to close tables in work areas.

Related Sections

Creating Databases

Describes creating databases and working with tables associated with databases.
Creating Tables

Introduces creating tables and considerations for creating tables.
Managing Tables

Discusses tasks you can perform to manage tables.


Work Areas in Data Sessions

Visual FoxPro 9.0
Work Areas in Data Sessions
See Also

A work area is a numbered region that identifies an open table, its index, and its relationships to other tables in a data session. A data session is a representation of the current dynamic work environment used by a form, form set, or report. When you use data sessions, Visual FoxPro provides a separate environment automatically for each instance of a form or form set. Each data session contains a set of work areas. For more information about data sessions, see How to: Use Data Sessions and How to: View Open Tables in Data Sessions.

In Visual FoxPro, you can open and manipulate tables in 32,767 work areas. Work areas are typically identified in your application using a number or the table alias for the table that is open in the work area. For more information, see How to: Open Tables in Work Areas and How to: Close Tables in Work Areas.

A table alias is a name that refers to a table open in a work area. Using a table alias or name alone specifically identifies the table you want independently from the work area in which the table is open. You can use table aliases in the Visual FoxPro programming language.

When you open a table, Visual FoxPro uses the file name of the table automatically as the default alias. Visual FoxPro also assigns its own default alias to a table automatically under the following circumstances:

  • When you open a table simultaneously in multiple work areas by calling the USE command with the AGAIN clause without specifying an alias when opening the table in each work area.

  • When a conflict exists between aliases.

The default aliases that Visual FoxPro assigns in the first 10 work areas are the work area letters "A" through "J". The aliases assigned in work areas 11 through 32,767 are W11 through W32767. You can use these default aliases to refer to a table open in a work area in the same way as any other default or user-defined alias. For more information, see How to: Create and Use Table Aliases.

See Also

Other Resources

Temporary Relationships Between Tables
Managing Tables in Data Sessions
Working with Tables


Temporary Relationships Between Tables

Visual FoxPro 9.0
Temporary Relationships Between Tables
See Also

You can use work areas and table aliases to create temporary relationships between tables. Temporary relationships cause the record pointer in one table, known as the child table, to follow the movements of the record pointer in another table, known as the parent table. For example, suppose you want establish a relationship between a customer table and an orders table so that when you move the record pointer in the customer table to a particular customer, the record pointer in the orders table moves to the record with the same customer number.

You can create different relationships between tables. For example, in a one-to-many relationship, you can select a record in the parent table or "one" side of the relationship and access multiple related records in the child table or "many" side of the relationship. For more information about relationships you can create, see Identifying Relationships.

Typically, you set a temporary relationship between tables that have a common field using a relational expression. The relational expression is typically the index expression of the controlling index in the child table. Therefore, when you create a relationship between the parent table and the index of the child table, selecting a record in the parent table selects only those records in the child table whose index key matches the index key for the parent record you select.

After you open tables and create relationships, you can view the aliases and relationships for those tables in the Data Session window.

Relationships in Single Tables

You can also create a relationship between records in a single table, or a self-referential relation. This type of relationship can be useful when you have all the information you need in a single table. For example, suppose you have an employee table. By creating a self-referential relationship in the table, you can select employee records for those employees who report to each manager as you navigate to each manager record in the table.

Relationships Between Tables in a Data Environment

If you are using a form to work with tables, you can use the data environment of the form to create and store these relationships with the form. Relationships you create in the data environment open automatically when you run the form. For information on creating a data environment, see Creating Forms.

See Also

Other Resources

How to: Set Temporary Relationships Between Tables
Work Areas in Data Sessions
Managing Tables in Data Sessions
Working with Tables


How to: View Open Tables in Data Sessions

Visual FoxPro 9.0
How to: View Open Tables in Data Sessions
See Also

You can see the tables that are currently open in a data session. For more information about data sessions, see How to: Use Data Sessions.

To see open tables in a data session

  • On the Window menu, choose Data Session.

    -OR-

  • Use the SET command without any arguments.

The Data Session window opens and displays name of the current data session, the table aliases for all open tables, and other options.

For more information, see SET Command and Data Session Window.

See Also

Other Resources

How to: Open Tables in Work Areas
How to: Create and Use Table Aliases
How to: Set Temporary Relationships Between Tables
Managing Tables in Data Sessions
Working with Tables


How to: Open Tables in Work Areas

Visual FoxPro 9.0
How to: Open Tables in Work Areas
See Also

You can open tables in work areas within data sessions. You can also reference or move to the next available work area before opening a table. For more information, see Work Areas in Data Sessions and How to: Use Data Sessions.

Note:
More than one table cannot be open in the same work area. When you open another table in the same work area, the currently open table closes automatically.

To open a table in a work area

  1. Open the tables you want to work with in the data session.

  2. On the Window menu, choose Data Session.

    The Data Session window opens.

  3. In the Alias list, click the alias for the table you want to open, and then Open.

    The table whose alias you selected is now open.

To open a table in multiple work areas

  • In the Alias list of the Data Session window, click the alias for the same table, and then Open.

    Visual FoxPro assigns a different alias to the same table.

To open a table in a work area programmatically

  • Use the USE command with the table name and work area number.

    Tip:
    To open the same table in another work area, repeat the USE command with the same table name and include the AGAIN keyword.

For more information, see USE Command.

When you open a table from the File menu, the table also opens in a work area.

To reference the next work area

  • Use the SELECT command and include the work area number or table alias.

For more information, see SELECT Command.

See Also

Other Resources

How to: Close Tables in Work Areas
How to: Create and Use Table Aliases
How to: Set Temporary Relationships Between Tables
Managing Tables in Data Sessions
Working with Tables


How to: Create and Use Table Aliases

Visual FoxPro 9.0
How to: Create and Use Table Aliases
See Also

When you open a table, Visual FoxPro uses the file name of the table automatically as the default alias. Under certain conditions, Visual FoxPro assigns its own default alias. However, you can also create your own alias.

Note:
After assigning a user-defined alias, you must use the alias to refer to the table thereafter.

To assign a user-defined alias to a table

  • Open the table with the USE command, the table name, and the ALIAS clause with the table alias you want.

For more information, see USE Command.

To reference a field in an open table from another work area

  • Preface the field name with table name or alias and a period (.) or the -> operator.

For example, suppose you want to access a field named Contact in a table named Customer that is open in a different work area. The following example illustrates how you can reference the field:

Customer.Contact

If the table you want to reference is opened with an alias, you can use the alias name. For example, if the Customer table is opened with an alias People, the following example illustrates how you can reference the Contact field with the alias:

People.Contact

See Also

Other Resources

Work Areas in Data Sessions
How to: Set Temporary Relationships Between Tables
Managing Tables in Data Sessions
Working with Tables


How to: Set Temporary Relationships Between Tables

Visual FoxPro 9.0
How to: Set Temporary Relationships Between Tables
See Also

You can set temporary relationships between open tables in so that when the record pointer in one table moves, the record pointer in the other table follows. You can also create a temporary relationship in a single table.

Tip:
Typically, you set a temporary relationship between tables that have a common field using a relational expression. The relational expression is typically the index expression of the controlling index in the child table.

For more information, see Temporary Relationships Between Tables.

To create a relationship between tables

  1. Open the tables you want to create relationships between.

  2. On the Window menu, choose Data Session.

    The Data Session window opens.

  3. In the Aliases list, click the alias for the parent table you want, and then Relations.

    The table you selected appears in the Relations list followed by a line indicating the relationship to a child table that you select in the next step.

  4. In the Aliases list, click the alias for the child table you want, and then the Relations.

    Note:
    If an index order has not been set in the table you selected, the Set Index Order dialog box appears. To select an index order, click the index order you want to set in the child table, and then OK.

    The Expression Builder opens.

  5. In the Expression Builder, type or build a relational expression between the parent table and the child table. When you are finished, click OK.

For more information, see How to: Open Tables in Work Areas.

To create a one-to-many relationship between tables

  1. After you select the child table in the Data Session window, click 1 to many.

  2. In the Create One-to-Many Relationships dialog box, click the alias for the child table you want, and then Move.

  3. When you are finished, click OK.

To create a relationship in a single table

  1. Open the table you want in two separate work areas.

  2. On the Window menu, choose Data Session.

    The Data Session window opens.

  3. In the Aliases list, click the alias for the parent table you want, and then Relations.

  4. In the Aliases list, click the alias for the child table you want, and then Relations.

    Note:
    If an index order has not been set in the table you selected, the Set Index Order dialog box appears. To select an index order, click the index order you want to set in the child table, and then OK.

    The Expression Builder opens.

  5. In the Expression Builder, type or build a relational expression between the parent table and the child table. When you are finished, click OK.

For more information, see How to: Open Tables in Work Areas.

To set a temporary relationship between tables programmatically

  • Use the SET RELATION command.

You can also use SET RELATION to establish a relationship between a single parent table and various child tables. You can also set a relationship between a table open in the currently selected work area and another table open in another work area by using the SET RELATION command. For more information, see SET RELATION Command.

See Also

Other Resources

Temporary Relationships Between Tables
Managing Tables in Data Sessions
Working with Tables


How to: Close Tables in Work Areas

Visual FoxPro 9.0
How to: Close Tables in Work Areas
See Also

You can close tables in work areas within data sessions.

Tip:
You can also close the currently open table in a work area automatically by opening another table in the same work area.

To close a table in a work area

  1. On the Window menu, choose Data Session.

    The Data Session window opens.

  2. In the Alias list, click the alias for the table you want to open, and then Close.

To close a table in a work area programmatically

  • Use the USE command without arguments or with only the IN clause and the work area number of the table you want to close.

See Also

Other Resources

How to: Open Tables in Work Areas
Managing Tables in Data Sessions
Working with Tables


Working with Fields

Visual FoxPro 9.0
Working with Fields

After you create a table, you need to identify and create fields to store data in the table.

In This Section

Field Creation

Introduces fields and considerations for creating them.
How to: Add Fields to Tables

Describes how to add new fields to tables.
How to: Name Fields

Describes how to specify names for fields.
How to: Choose Data Types

Describes how to specify data types for fields.
How to: Add Indexes to Fields

Describes how to specify indexes for fields.
How to: Permit Null Values in Fields

Describes how to specify that fields can accept null values.
How to: Create Default Field Values

Describes how to specify default values for fields.
How to: Specify Input Masks for Fields

Describes how to specify input formats for entering and storing values uniformly in fields.
How to: Format Output for Fields

Describes how to specify the format for field output.
How to: Specify Captions for Fields

Describes how to change the column header text for fields in browse windows and grids.
How to: Set Default Classes for Fields

Describes how to set the default class to use when creating objects or controls by adding fields to forms.
How to: Set Autoincrementing Field Values

Describes how to set field values to increment automatically.
How to: Add Comments to Fields

Describes how to add descriptions for fields.
How to: Restrict Access to Fields

Describes how to display only certain fields in browse windows.
How to: Delete Fields

Describes how to delete fields from tables.
Preventing Duplicate Values in Fields

Discusses preventing duplicate values in fields.
Autoincrementing Field Values in Tables

Discusss considerations for incrementing field values automatically.

Related Sections

Working with Tables

Introduces creating and working with tables.
Working with Data

Provides an overview and information about using data in your applications, for example, analyzing data requirements and designing your application components to meet those requirements.


Field Creation

Visual FoxPro 9.0
Field Creation
See Also

You can define fields by specifying a field name, a data type, and a field width. When you create a table, you need to define the fields that the table contains. Visual FoxPro tables can contain up to 255 fields.

Note:
If one or more fields can store null values, the maximum number of fields is reduced from 255 to 254.

The following list describes the general attributes you specify when creating a field:

  • Name of the field.

  • Type of data that the field contains.

  • Width of the field.

  • Number of decimal places if the field contains numeric or float values.

  • An index on the field.

  • Whether the field accepts null values.

You can also perform the following tasks when working with fields:

  • Specify default values for the field.

  • Add comments for the field.

  • Specify input masks for entering and storing data in the field.

  • Set automatically incrementing values in fields.

The following sections describes considerations when creating fields:

  • Considerations for Choosing Field Names

  • Considerations for Choosing Data Types

  • Considerations for Default Values in Fields

Considerations for Choosing Field Names

For database fields, Visual FoxPro stores the first 10 characters of the field name in the table (.dbf) file and the long name for the field in the database (.dbc) file. The rules for creating long field names are the same as those for creating any Visual FoxPro identifier except that database field names can contain up to 128 characters. For more information, see Creating Visual FoxPro Names.

However, as long as a table is associated with a database, you must use the long field names to refer to table fields, not the 10-character field names. If you remove a table from a database, the long names for the fields are lost, and you must use the 10-character field names stored in the table (.dbf) file as the field names.

If the first 10 characters in the long name are not unique in the table, Visual FoxPro generates a field name consisting of the first n characters in the long name appended by a sequential number for a total of 10 characters. The following table lists examples of generated names.

Long name | Short name
customer_contact_name | customer_c
customer_contact_address | customer_2
customer_contact_city | customer_3
... | ...
customer_contact_fax | customer11

In indexes, long field names can consist of characters, but not numbers. However, if you create an index using long field names and then remove the referenced table from the database, the index no longer functions correctly. In this case, you can shorten the field names in the index and then rebuild the index, or you can delete the index and recreate it using short field names. For more information, see Working with Table Indexes.

For more information about choosing field names, see How to: Name Fields.

Considerations for Choosing Data Types

When you choose the data type for a field, remember the following considerations:

  • The types of values the field can store.

    For example, you cannot store text in a numeric field.

  • The amount of storage the field needs to store values.

    For example, any value with Currency type uses 8 bytes of storage.

  • The types of operations you want to perform on values in the field.

    For example, Visual FoxPro can calculate the sum of values with Numeric or Currency type but not the sum of values with Character or General type.

    Tip:
    For numbers that you do not intend to use for mathematical calculations, for example, phone numbers, use the Character, not Numeric, type.

  • The capability to index or sort values in the field.

    For example, you cannot sort or create an index for fields with Memo or General type.

For more information about Visual FoxPro data types, see Visual FoxPro Data and Field Types. For more information about choosing data types for fields, see How to: Choose Data Types.

Considerations for Default Values in Fields

Specifying default values for fields help application users enter data more quickly by making it possible to skip fields unless they want to change the default value.

Tip:
If a business rule for your application requires that a field contain an entry, providing a default value helps to comply with that rule using a field-level or record-level rule.

For example, suppose a company has primarily domestic customers. On the form used to enter data for new customers, you might want to display the country for those customers as the default value in the country or region field. If other values are required for the country or region, the user can replace the default value with the appropriate value.

You can specify default values that are scalar values, such as a number, or expressions that evaluate to a scalar quantity. You can also specify any valid FoxPro expression that returns a value consistent with the data type for the field.

Note:
When specifying the default value, Visual FoxPro evaluates the default value or expression for the correct data type when the closing the table structure or using the SQL CREATE TABLE or ALTER TABLE commands. If the data type of the expression does not match the data type of the field, Visual FoxPro generates an error. Expressions that are user-defined functions (UDF) or contain UDFs are not evaluated; and therefore, do not generate errors.

Visual FoxPro evaluates the default value or expression when using the APPEND, APPEND BLANK, or SQL INSERT commands to assign values to fields. When you assign values to fields using the APPEND FROM or SQL INSERT commands, Visual FoxPro applies default values to any fields that are not explicitly assigned. However, these two commands do not replace any existing values with default values.

You can also use default values to populate fields that do not accept null values. When you add a new record, Visual FoxPro applies the default values then checks each field in the order they are defined for missing data. This makes sure that fields that do not accept null values can be populated with default values before applying the constraint that the fields cannot be null.

If fields in your tables accept null values, you can use the null value (.NULL.) as the default value. Regardless of whether SET NULL is on or off, if you use null (.NULL.) as the default value, Visual FoxPro inserts null (.NULL.) into fields for all commands except APPEND BLANK. For more information, see SET NULL Command and How to: Permit Null Values in Fields.

If you do not specify a default value, a blank value appropriate for the data type of the field is inserted unless the SET NULL command is set to ON. This preserves backward compatibility.

Note:
When you remove or delete a table from a database, all the default values for fields in that table are deleted from the database. However, stored procedures referenced by the removed or deleted default value remain even after the default value has been removed.

For more information about setting default values for fields, see How to: Create Default Field Values.

See Also

Other Resources

How to: Add Fields to Tables
Working with Fields
Working with Tables


How to: Add Fields to Tables

Visual FoxPro 9.0
How to: Add Fields to Tables
See Also

When opening the table in the Table Designer, the Fields tab displays a row for the first field and adds a field following the field as you define it. You can add additional fields to the table in the order that you want.

To add a field to a table

  1. Open the table in the Table Designer.

  2. On the Fields tab, insert the cursor in the field that follows the one you want to add.

  3. Click Insert.

    A new field appears preceding the selected field with a default field name, type, and width.

  4. Change the attributes for the field to the ones you want.

  5. When you are finished, click OK.

    Visual FoxPro prompts you to confirm changes to table structure.

  6. To confirm the table structure changes, click Yes.

To add a field to a table programmatically

  • Use the SQL ALTER TABLE command and include the ADD COLUMN clause.

For more information, see ALTER TABLE - SQL Command.

For example, the following code adds a field named Fax with Character type and a field width of 10 characters to a customer table:

Copy Code
ALTER TABLE Customer ADD COLUMN Fax C(20)

See Also

Other Resources

Field Creation
How to: Edit Table Structure
How to: Name Fields
Working with Fields
Working with Tables


How to: Name Fields

Visual FoxPro 9.0
How to: Name Fields
See Also

You specify names for fields as you build a table. For free tables, field names can be up to 10 characters long. For database tables, field names can be up to 128 characters long.

Note:
If you remove a table from a database, the long field names in a table are truncated to 10 characters. For more information, see Field Creation.

To name a table field

  1. Open the table in the Table Designer.

  2. Click the Fields tab.

  3. In the Name box, type a name for the field.

For more information, see How to: Open Tables and Fields Tab, Table Designer.

To name a table field programmatically

  • When creating the table using the SQL CREATE TABLE command, specify the field name.

    -OR-

  • To edit an existing table, open the table with the USE command and then use the SQL ALTER TABLE command.

For more information, see CREATE TABLE - SQL Command or ALTER TABLE - SQL Command.

For example, the following code creates and opens a table named Customer with three fields, Cust_ID, Company, and Contact using the CREATE TABLE command:

Copy Code
CREATE TABLE Customer (Cust_ID C(6), Company C(40), Contact C(30))

In the example, C(6) indicates the field contains Character data and has a field width of 6 characters. For more information, see How to: Choose Data Types.

The following code adds fields to an existing table using the SQL ALTER TABLE command:

Copy Code
ALTER TABLE Customer ;
   ADD COLUMN (Company C(40), Contact C(30))

Renaming Fields

You can rename existing table fields.

To rename a table field

  1. Open the table in the Table Designer.

  2. In the Name box on the Fields tab, insert the cursor in the field you want and type the new name for the field.

For more information, see Fields Tab, Table Designer.

To rename a table field programmatically

  • Use the SQL ALTER TABLE command with the RENAME COLUMN clause.

For more information, see ALTER TABLE - SQL Command.

For example, the following code renames the Company field in the Customer table using the SQL ALTER TABLE command:

Copy Code
ALTER TABLE Customer RENAME COLUMN Company TO Company_LongName

See Also

Other Resources

Field Creation
How to: Edit Table Structure
How to: Choose Data Types
Working with Fields
Working with Tables


How to: Choose Data Types

Visual FoxPro 9.0
How to: Choose Data Types
See Also

After you specify the name for a field, you can choose the type of data that the field can store.

To chose a data type for a field

  1. Open the table in the Table Designer.

  2. On the Fields tab, select the field that you want.

  3. In the Type list, select a data type for the field.

    Tip:
    If the field has a Numeric or Float type, set the number of decimal places in the Decimal column. If an integer field contains automatically incrementing values, you need to specify next and step values. For more information, see How to: Set Autoincrementing Field Values.

For more information, see Fields Tab, Table Designer.

To choose a data type for a field programmatically

  • When creating the table using the SQL CREATE TABLE command, specify the data type for the field.

-OR-

  • To edit an existing table, open the table with the USE command and then use the SQL ALTER TABLE command.

For more information, see CREATE TABLE - SQL Command or ALTER TABLE - SQL Command.

For example, the following code creates and opens a table named Customer with three fields, Cust_ID, Company, and Contact using the CREATE TABLE command:

Copy Code
CREATE TABLE Customer (Cust_ID C(6), Company C(40), Contact C(30))

In the example, C(6) indicates the field contains Character data and has a field width of 6 characters.

See Also

Other Resources

Field Creation
How to: Edit Table Structure
How to: Add Indexes to Fields
Working with Fields
Working with Tables


How to: Add Indexes to Fields

Visual FoxPro 9.0
How to: Add Indexes to Fields
See Also

When you add a field to a table, you can specify a regular index on the field quickly.

To add an index to a field

  1. Open the table in the Table Designer.

  2. On the Fields tab, select the field that you want.

  3. In the Index list for the field, select the index sort order you want.

    The index you create appears in the Indexes tab in the Table Designer automatically and uses the field as the index expression.

  4. To continue editing the index, click the Indexes tab.

For more information, see How to: Create Indexes.

See Also

Other Resources

How to: Edit Table Structure
Field Creation
Working with Table Indexes
Working with Fields
Working with Tables


How to: Permit Null Values in Fields

Visual FoxPro 9.0
How to: Permit Null Values in Fields
See Also

When you specify fields for a table, you can decide whether one or more fields can accept null (.NULL.) values. Typically, a null value indicates that information usually stored in the field or record is not currently available.

For example, an employee's health benefits or tax status might be unknown at the time a record is populated. Instead of storing a zero or a blank, which could be interpreted to have meaning, you might store a null value in the field until more information becomes available.

Note:
Null values in fields affect the behavior of tables and indexes. For example, if you use APPEND FROM or INSERT INTO to copy records from a table containing null values to a table that does not permit null values, the appended fields containing null values are blank, empty, or zero in the destination table.

To permit null values in a field

  1. Open the table in the Table Designer.

  2. On the Fields tab, click in the NULL column for the field.

    When null values are permitted for the field, the NULL column displays a check mark for that field. To discontinue permitting null values in the field, click the button in the NULL column so that the check mark is cleared.

For more information, see Fields Tab, Table Designer.

To permit null values in a field programmatically

  • When creating the table using the SQL CREATE TABLE command, include the NULL or NOT NULL clauses.

-OR-

  • To edit an existing table, open the table with the USE command and then use the SQL ALTER TABLE command with the NULL or NOT NULL clauses.

For more information, see CREATE TABLE - SQL Command and ALTER TABLE - SQL Command.

For example, the following code creates and opens a table that permits null values in one of the fields but not the other two fields:

Copy Code
CREATE TABLE Customer (Cust_ID C(6) NOT NULL, ;
   Company C(40) NOT NULL, Contact C(30) NULL)

To permit null values in all fields of the table

  1. Open the table in the Table Designer.

  2. On the Fields tab, click the NULL column for every field.

For more information, see Fields Tab, Table Designer.

To permit null values in all fields of the table programmatically

  • Use SET NULL ON before calling the SQL CREATE TABLE command.

Using SET NULL ON also selects the NULL column automatically for each new field you add to the table using the Table Designer and makes it possible for you to not need to include the NULL or NOT NULL clauses in CREATE TABLE.

For more information, see SET NULL Command.

See Also

Other Resources

How to: Open Databases
How to: Edit Table Structure
Field Creation
How to: Create Default Field Values
Working with Fields
Working with Tables


How to: Create Default Field Values

Visual FoxPro 9.0
How to: Create Default Field Values
See Also

You can specify default values that fields in database tables contain when adding new records, regardless of how the data is entered. These default values remain until they are replaced with new values.

Note:
You can specify default values for fields of any data type except General fields.

You can also view the default value for the field.

To specify a default value for a field

  1. Open the database containing the table.

  2. Open the table in the Table Designer.

  3. On the Fields tab, select the field that you want.

  4. In the Default value box in the Field validation area, type the default value you want for the field.

    Tip:
    Enclose text in quotation marks ("") for character fields.

  5. Click OK.

For more information, see Fields Tab, Table Designer.

To specify a default value for a field programmatically

  • When creating the table using the SQL CREATE TABLE command, include the DEFAULT clause.

-OR-

  • To edit an existing table, open the table with the USE command and then use the SQL ALTER TABLE command with the DEFAULT clause.

For more information, see CREATE TABLE - SQL Command and ALTER TABLE - SQL Command.

For example, suppose you want to your application to limit the amount of merchandise a new customer can order until you can complete a credit check and determine the amount of credit you want to extend to that customer. The following code creates a customer table with a maximum order amount field with a default value of 1000:

Copy Code
CREATE TABLE Customer (Cust_ID C(6), Company C(40), Contact C(30), ;
   MaxOrdAmt Y(4) DEFAULT 1000)

If the table exists, you can add a default value for the field:

Copy Code
ALTER TABLE Customer ALTER COLUMN MaxOrdAmt SET DEFAULT 1000

To view the default value for a field in a database table

  • Use the DBGETPROP( ) function to retrieve the value of the DefaultValue field property.

For more information, see DBGETPROP( ) Function.

See Also

Other Resources

How to: Open Databases
How to: Edit Table Structure
Field Creation
How to: Set Autoincrementing Field Values
Working with Fields
Working with Tables


How to: Specify Input Masks for Fields

Visual FoxPro 9.0
How to: Specify Input Masks for Fields
See Also

You can make it possible to enter and store values in fields for database tables in a uniform manner, reducing data entry errors and making processing more efficient. You can accomplish this by defining the punctuation, spacing, and other format attributes for values entered in a field using an input mask.

For example, you can make it possible to enter and store telephone numbers in a field by adding an input mask appropriate for telephone numbers to a numeric field, for example (999) 999-9999. The input mask helps the user enter telephone numbers more quickly because the formatting is provided. For more information about input mask characters, see InputMask Property.

To specify an input mask for a field

  1. Open the database containing the table.

  2. Open the table in the Table Designer.

  3. On the Fields tab, select the field that you want.

  4. In the Input mask box of the Display area, type the input mask characters that you want.

For more information, see Fields Tab, Table Designer.

To specify an input mask for a field programmatically

  • Use the DBSETPROP( ) function to set the InputMask field property.

For more information, see DBSETPROP( ) Function.

For example, the following code specifies an input mask for a date:

Copy Code
DBSETPROP("Orders.Postalcode","Field","InputMask", "99999-9999")

See Also

Other Resources

How to: Open Databases
How to: Edit Table Structure
Working with Fields
Working with Tables


How to: Format Output for Fields

Visual FoxPro 9.0
How to: Format Output for Fields
See Also

You can specify the format used by values in fields from database tables when those values appear on forms, in browse windows, or reports. You can use format codes and characters to specify the format. For more information about format codes and characters, see Format Property.

To specify the format for field output

  1. Open the database containing the table.

  2. Open the table in the Table Designer.

  3. On the Fields tab, select the field that you want.

  4. In the Format box of the Display area, type the format characters that you want.

For more information, see Fields Tab, Table Designer.

To specify the format for field output programmatically

  • Use the DBSETPROP( ) function to set the Format field property.

For more information, see DBSETPROP( ) Function.

For example, the following code specifies the output format for a postal code:

Copy Code
DBSETPROP("Orders.Postalcode","Field","Format","@R 99999-9999")

See Also

Other Resources

How to: Open Databases
How to: Edit Table Structure
Working with Fields
Working with Tables


How to: Specify Captions for Fields

Visual FoxPro 9.0
How to: Specify Captions for Fields
See Also

For database tables, you can specify and display a caption instead of the field name in the column header of a browse window or grid. The caption can be text or an expression.

Note:
Expressions cannot exceed 254 characters. If the expression exceeds 254 characters, the caption defaults to the field name.

To specify a caption for a field

  1. Open the database containing the table.

  2. Open the table in the Table Designer.

  3. On the Fields tab, select the field that you want.

  4. In the Caption box of the Display area, type the text for the field caption.

    Tip:
    To specify an expression for a field caption, include an equal sign (=) preceding the caption string.

For more information, see Fields Tab, Table Designer.

To specify a caption for a field programmatically

  • Use the DBSETPROP( ) function with the Caption field property.

For more information, see DBSETPROP( ) Function.

For example, the following code specifies the caption "Supplier_Fax" for a field named Fax in a supplier table:

Copy Code
DBSETPROP('Supplier.Fax', 'Field', 'Caption', 'Supplier_Fax')

See Also

Other Resources

How to: Open Databases
How to: Edit Table Structure
Working with Fields
Working with Tables


How to: Set Default Classes for Fields

Visual FoxPro 9.0
How to: Set Default Classes for Fields
See Also

You can set or change the default class for a field in a database table so that when you drag or add the field to a form, an object instantiates from the default class and appears on the form.

For example, character fields appear as text box controls when you add them to a form. Suppose you wanted to add the field as a combo box control instead of a text box. You can change the default class for the field to the ComboBox base class. You can also specify class libraries that you create.

To set a default class for a field

  1. Open the database containing the table.

  2. Open the table in the Table Designer.

  3. On the Fields tab, select the field that you want.

  4. In the Display class list from the Map field type to classes area, select the default class for the field.

  5. To specify a class library, in the Display library box, type the name of the class library. To browse for and select a class library, click the ellipsis (...) button.

For more information, see Fields Tab, Table Designer.

Tip:
If you change the class and class library often for fields, you can map data types to the class and class libraries you want using the Field Mapping tab in the Options dialog box. For more information, see Field Mapping Tab, Options Dialog Box and How to: Create Controls by Dragging and Dropping Fields or Tables.

See Also

Other Resources

How to: Open Databases
How to: Edit Table Structure
Working with Fields
Working with Tables


How to: Set Autoincrementing Field Values

Visual FoxPro 9.0
How to: Set Autoincrementing Field Values
See Also

You can set values in free and database table fields with Integer type to increment automatically.

Note:
Automatically incrementing field values is not supported for local, remote, or offline views. Activating automatically incrementing values in a field sets the field as read-only, and its values cannot be changed with an insert, update, or replace operation. For more information, see Autoincrementing Field Values in Tables.

To set automatically incrementing values in a field

  1. Open the table in the Table Designer.

  2. On the Fields tab, select the field you want.

  3. In the Type list, select Integer (AutoInc).

  4. In the AutoIncrement area, type a start value for Next Value and an increment value for Step.

  5. When you are finished, click OK.

    Note:
    When you select the Integer (AutoInc) type for a field, the Default value box becomes unavailable. However, Visual FoxPro neither discards nor uses the default value. Any expressions in the Default value box remain when you change the field type to or from Integer (AutoInc). You can still use code such as DBGETPROP( ) to retrieve the default value for the field. If you want to use the value in the Default value box, you must first change the Integer (AutoInc) data type.

For more information, see Fields Tab, Table Designer.

To set automatically incrementing values in a field programmatically

  • When creating the table using the SQL CREATE TABLE command, include the AUTOINC clause.

    -OR-

  • To edit an existing table, open the table with the USE command and then use the SQL ALTER TABLE command with the AUTOINC clause.

For more information, see CREATE TABLE - SQL Command or ALTER TABLE - SQL Command.

See Also

Other Resources

How to: Edit Table Structure
Field Creation
Working with Fields
Working with Tables


How to: Add Comments to Fields

Visual FoxPro 9.0
How to: Add Comments to Fields
See Also

You can add descriptions to fields in a database table so it is easier to understand and update. When you select a field from a database table in the Project Manager, the comment text displays in the Description area of the Project Manager window.

To add a comment to a field

  1. Open the database containing the table.

  2. Open the table in the Table Designer.

  3. On the Fields tab, select the field that you want.

  4. In the Field comment box for the field, type the text for the description.

  5. Click OK.

For more information, see Table Designer.

To add a comment to a field programmatically

  • Use the DBSETPROP( ) function to set the Comment field property.

For more information, see DBSETPROP( ) Function.

For example, suppose you want to add a description to a unit price field in a table containing items in an order. The following code assigns the text, "Current retail price per unit" to the field:

Copy Code
?DBSETPROP('OrdItems.Price', 'Field', 'Comment', ;
   'Current retail price per unit')

See Also

Other Resources

How to: Open Databases
How to: Edit Table Structure
Working with Fields
Working with Tables


How to: Restrict Access to Fields

Visual FoxPro 9.0
How to: Restrict Access to Fields
See Also

You can specify to display only certain fields when viewing them in a browse window or using them on a form. By setting a field filter, you can restrict access to the fields you want by choosing only those fields you want to display, leaving the remaining fields hidden and inaccessible.

To specify access and display for certain fields

  1. Open the table in a browse window.

  2. On the Table menu, click Properties to open the Work Area Properties dialog box.

  3. In the Allow access to area, click Only fields specified by field filter, and then Field Filter.

    The Field Picker dialog box opens.

  4. In the All fields list, select the fields that you want to retain access.

    The remaining fields in the All fields list will be hidden and access to them will be restricted.

  5. When you are finished, click Move, and then OK.

  6. In the Work Area Properties dialog box, click OK.

  7. Close and reopen the browse window.

    Only the fields you chose are visible in the browse window.

See Also

Other Resources

How to: View Records in Tables
Working with Fields
Working with Tables


How to: Delete Fields

Visual FoxPro 9.0
How to: Delete Fields
See Also

You can delete a field from a table.

Caution:
Deleting a field from a table deletes information about the field, including the field's default value, rule definitions, and caption. If an index key or trigger expression references the field, the expressions become invalid when the field is deleted. The invalid index key or trigger expression does not generate an error until run time.

To delete a field from a table

  1. Open the table in the Table Designer.

  2. On the Fields tab, select the field that you want.

  3. Click Delete.

To delete a field from a table programmatically

  • Use SQL ALTER TABLE command with the DROP COLUMN clause.

For more information, see ALTER TABLE - SQL Command.

For example, the following command deletes a field named Fax from a customer table:

Copy Code
ALTER TABLE Customer DROP COLUMN Fax

See Also

Other Resources

How to: Edit Table Structure
Working with Fields
Working with Tables


Preventing Duplicate Values in Fields

Visual FoxPro 9.0
Preventing Duplicate Values in Fields
See Also

You can prevent duplicate values in one or more table fields by creating a primary or candidate index using an expression that contains those fields. When you include one or more fields in an index expression, Visual FoxPro generates an index key based on those fields for each record that uniquely identifies the record. When a new record is entered, you can compare index keys for the new record and the existing records to determine whether a duplicate record already exists and prevent the duplicate record from being added to the table.

Tip:
If your table is part of a database, use a primary or candidate index. If your table is a free table or already has a primary index, you must use a candidate index.

For example, suppose you have a table that stores the area code and phone number in two columns. The following table illustrates these two columns.

Area code | Phone number
206 | 444-nnnn
206 | 555-nnnn
313 | 444-nnnn

Both the area code column and phone number column contain values that duplicate other values in the respective columns. However, no phone numbers are duplicated because combining both fields creates a row containing the complete phone number. Likewise, if the primary or candidate index included both fields in the index expression, the rows in the example would not be considered duplicates. Therefore, if you attempted to enter a phone number that contained exactly the same area code and phone number as exists in one of the rows, Visual FoxPro would reject the entry as a duplicate.

See Also

Other Resources

Index Creation Based on Expressions
Working with Table Indexes
Working with Fields
Working with Tables


Autoincrementing Field Values in Tables

Visual FoxPro 9.0
Autoincrementing Field Values in Tables
See Also

You can specify that integer fields from database tables and free tables contain values that increment automatically. A table can contain multiple integer fields that contain automatically incrementing values. Autoincrementing is not supported for local, remote, or offline views.

When you add a field with automatically incrementing values to a table that did not contain one, the values begin incrementing automatically with the next row that is added in the table. Previous rows in the table are not updated with automatically incrementing values; therefore, make sure that no conflicts occur as a result.

For more information about how to set automatically incrementing field values, see How to: Set Autoincrementing Field Values.

The following sections contain more information about areas of Visual FoxPro affected by automatically incrementing field values:

  • Table Structure Changes for Autoincrementing Field Values

  • Considerations for Autoincrementing Field Values

  • Local Views and Autoincrementing Field Values

  • Buffered Tables and Autoincrementing Field Values

  • Record Locking and Autoincrementing Field Values

Table Structure Changes for Autoincrementing Field Values

When you activate automatically incrementing values for any field in a table, Visual FoxPro sets byte 0 to 0x31 for the file type "Visual FoxPro, Autoincrement enabled" in the table (.dbf) header record structure. Visual FoxPro sets byte 18, bytes 19 to 22, and byte 23 in the field subrecords structure to the following values, respectively:

  • 0x0C for the autoincrementing column.

  • Next value.

  • Step value.

For more information, see Table File Structure.

Considerations for Autoincrementing Field Values

A field that contains automatically incrementing values becomes read-only and cannot be changed with an insert, update, or replace operation. Attempting to update such a field generates an error message unless you set the cursor AutoIncError property using the CURSORSETPROP( ) function to False (.F.) or turn the error message off by using the SET AUTOINCERROR command. For more information, see CURSORSETPROP( ) Function and SET AUTOINCERROR Command.

Tables containing automatically incrementing field values append table-buffered records approximately 35% slower than tables without automatically incrementing field values, which might affect performance. When using table buffering, the table header is locked when the record is appended.

Visual FoxPro does not manage gaps in generated sequences. Gaps can be caused by reverting an appended or inserted record or by failing to update the base table and so on. In all cases, the unused value is lost, and the next generated value remains the same as if the append or insert operation succeeded.

Versions prior to Visual FoxPro 8.0 cannot recognize tables that use automatically incrementing field values. If you remove autoincrementing for fields, the current state containing the last incrementing and incremental values is cleared from the table (.dbf) field subrecord and discarded. The table (.dbf) type is restored to the current Visual FoxPro type value. The automatically incrementing values stored previously in each record remain.

Local Views and Autoincrementing Field Values

Views do not "inherit" autoincrementing behavior of the base table, and the fields in the view that represent autoincrementing fields in the base table are read/write. Autoincrementing field values occur in the base table when the row or rows are updated in the base table. If you want to refresh the view with the autoincrementing field value previously generated, you must use the REQUERY( ) function. For more information, REQUERY( ) Function.

Buffered Tables and Autoincrementing Field Values

Visual FoxPro does not perform any autoincrementing management relative to buffered tables. All appended and inserted records have autoincrementing field values generated regardless of whether table or row buffering is active. In the case of buffering, when the TABLEUDPATE( ) function is called, the base table is updated with the previously generated value. If the update does not occur, such as when calling the TABLEREVERT( ) function, any autoincrementing field values that are generated are discarded, thus resulting in gaps in the sequence.

Record Locking and Autoincrementing Field Values

When you turn on autoincrementing values for a field, the start and incremental values Next Value and Step are stored in the table (.dbf) header in the unused or reserved portion of the field subrecord for the specified field. Next Value is stored as a 4-byte integer. The Step value is stored as a 1-byte integer with a maximum value of 255. The value actually used to increment the field value is the sum of the value stored in the .dbf header and the incremental value. The operation sequence occurs as follows:

  • Perform an insert or append operation.

  • Lock header.

  • Increase the currently stored increment value by the Step value and apply to the field.

  • Store the new value, which is the value of the newly added record, in the .dbf file header.

  • Unlock header when insert or append operation completes. The header contains the last incremented value.

See Also

Other Resources

How to: Choose Data Types
Working with Fields
Working with Tables


Working with Records

Visual FoxPro 9.0
Working with Records

After you create a table and the fields it contains, you can store data in tables using records. Each record is a row that consists of each field in the table.

In This Section

How to: View Records in Tables

Describes how to view records, which store data, in tables.
How to: Navigate Records in Tables

Describes how to move through records in tables.
How to: Filter Records in Tables

Describes how to display only certain records or restrict access to them.
How to: Configure Browse Windows or Grids

Describes how to customize the display of browse windows or grids.
How to: Add Records to Tables

Describes how to add records to tables for storing data or appending records from other tables or files.
How to: Add Data to Records

Describes how to add data to records after creating new records or replace data in existing records.
How to: Delete Records in Tables

Describes how to mark records for deletion, which remain on disk until you remove them.
How to: Restore Deleted Records

Describes how to restore records marked for deletion.
How to: Remove Deleted Records

Describes how to remove records marked for deletion permanently from disk.

Related Sections

Working with Data

Provides an overview and information about using data in your applications, for example, analyzing data requirements and designing your application components to meet those requirements.
Working with Tables

Introduces creating and working with tables.


How to: View Records in Tables

Visual FoxPro 9.0
How to: View Records in Tables
See Also

You can view the records in a table by opening it in a browse window. A browse window displays data in a table as rows (records) and columns (fields) that you can scroll through. For more information, see Browse Window.

To browse data in a free table

  1. On the File menu, click Open.

  2. In the Open dialog box, browse to the location of the table you want to view.

  3. In the Files of type box, select the Table (*.dbf) file type to display only table files.

  4. Select the table file you want to view.

  5. On the View menu, click Browse.

    The table you selected opens in a browse window.

To browse data in a database table

  1. Open the database in the Database Designer.

  2. Select the table you want.

  3. On the Database menu, click Browse.

    The table opens in a browse window.

To browse data in a table from a project

  1. Open the project in the Project Manager.

  2. Expand the Data node and choose one of the following:

    • To browse a database table, expand the Databases node, then the Tables node.

    -OR-

    • To browse a free table, expand the Free Tables node.

  3. Click the table you want to view, and then Browse.

    The table you selected opens in a browse window.

To browse a table programmatically

  1. Open the table with the USE command.

  2. Follow USE with the BROWSE command.

    Tip:
    To prevent users from adding records to a table while browsing a table, include the NOAPPEND clause in the BROWSE command.

For more information, see USE Command and BROWSE Command.

See Also

Other Resources

How to: Navigate Records in Tables
How to: Filter Records in Tables
How to: Configure Browse Windows or Grids
Working with Records
Working with Tables


How to: Navigate Records in Tables

Visual FoxPro 9.0
How to: Navigate Records in Tables
See Also

You can navigate records when viewing them in a browse window by using scroll bars, arrow keys, or the TAB key. You can also specify a group of records to locate.

To navigate records in a browse window

  1. Open the table in a browse window.

  2. On the Table menu, point to Go to Record, and choose one of the following:

    • To move to the first record, click Top.

    • To move to the last record, click Bottom.

    • To move to the next record, click Next.

    • To move to the previous record, click Previous.

    • To specify a record number, click Record # to open the Go to Record dialog box, type a number, and click OK.

For more information, see Go To Record Dialog Box.

To specify a group of records to locate

  1. Open the table in a browse window.

  2. On the Table menu, point to Go to Record, and click Locate.

    The Locate dialog box opens.

  3. In the Scope box of the Locate dialog box, select the range of records you want to locate.

  4. In the For box, type an expression that records must meet to be located. To build an expression, click the ellipsis (...) button.

  5. In the While box, type an expression that evaluates to true in order to continue locating records.

  6. When you are finished, click Locate.

See Also

Other Resources

How to: Filter Records in Tables
How to: View Records in Tables
How to: Configure Browse Windows or Grids
Working with Tables
Working with Records


How to: Filter Records in Tables

Visual FoxPro 9.0
How to: Filter Records in Tables
See Also

You can specify that only certain records display in browse windows by setting a data filter.

Caution:
If you restrict access to all the fields in a table, you might not be able to open the table in a browse window.

To filter records in a browse window

  1. Open the table in a browse window.

  2. On the Table menu, click Properties to open the Work Area Properties dialog box.

  3. In the Data filter box, type the filter expression you want. To build an expression, click the ellipsis (...) button.

  4. Click OK.

    The browse window displays only those records that meet the filter expression.

For example, the following filter expression displays on those records in a Customer table where the Country field is set to "USA":

Copy Code
Customer.Country = "USA"

See Also

Other Resources

How to: Navigate Records in Tables
How to: View Records in Tables
How to: Configure Browse Windows or Grids
Working with Tables
Working with Records


How to: Configure Browse Windows or Grids

Visual FoxPro 9.0
How to: Configure Browse Windows or Grids
See Also

You can change the configuration of a browse window or grid in the following ways:

  • Rearranging Columns

  • Changing Column Widths

  • Fitting Columns to Data Automatically

  • Turning Grid Lines On and Off

  • Splitting a Browse window

  • Locking Columns

For more information, see Browse Window and Grid Control.

Rearranging Columns

You can rearrange columns in the order you want.

Note:
Rearranging columns does not affect the actual structure of the table.

To rearrange a column in a browse window

  1. Open the table in a browse window.

  2. Insert the cursor in the column you want to move.

  3. On the Table menu, click Move Field.

    The cursor changes shape to indicate you can move the column.

  4. To move the column, press the LEFT ARROW or RIGHT ARROW keys.

  5. When you are finished, press the ENTER key.

You can also drag the column header to the new location.

To rearrange a column in a grid

  • Drag the column header to the new location.

Changing Column Widths

You can change the width of a column.

Note:
Resizing the column width does not affect the field length or the structure of the table. To change the actual length of the fields, modify the structure of the table using the Table Designer.

To change the width of a column in a browse window

  1. Open the table in a browse window.

  2. Insert the cursor in a column you want to resize.

  3. On the Table menu, click Size Field.

    The cursor changes shape to indicate you can resize the column.

  4. To increase the size of the column, press the RIGHT ARROW key. To decrease it, press the LEFT ARROW key.

  5. When you are finished, press the ENTER key.

You can also drag between column headers to resize the column to the left of the cursor.

To change the width of a column in a grid

  • Drag between the column headers to resize the column to the left of the cursor.

Fitting Columns to Data Automatically

You can resize columns to automatically fit the data that they contain.

To resize one column to data

  • Double-click between the column headers to the right of the column you want to resize automatically.

To resize all columns to data

  • Double-click the area to the left of the first column header.

Turning Grid Lines On and Off

You can turn off the grid lines in a browse window.

To turn grid lines on or off

  1. Open the table in a browse window.

  2. On the View menu, click Grid Lines.

Splitting a Browse Window

You can split the browse window into left and right windows so you can look at two different areas in the table or look at records in browse and edit modes at the same time.

Tip:
By default, the two windows of a split browse window are linked. When you select and modify records in one window, your changes are reflected in the other window. If you want the two windows to function independently, for example, so you can scroll one pane without affecting the other, click Link Partitions on the Table menu so that it is not selected.

To split a browse window

  1. Open the table in a browse window.

  2. On the Table menu, click Resize Partitions.

    The cursor changes shape to indicate that you can split the browse window.

  3. To increase the size of the left browse window, press the RIGHT ARROW key. To decrease the size, press the LEFT ARROW key.

  4. When you are finished, press the ENTER key.

You can also position the cursor in the dark area at the bottom left corner of the browse window and drag the corner to increase the size of the left browse window.

To resize a split browse window, perform the same steps to split a browse window.

Locking Columns

You display only certain columns while you scroll through the table by locking those columns. For example, pressing the TAB key to move through columns to the right does not cause locked columns to scroll out of the browse window or grid.

To lock all columns to the left of a column

  • Right-click the area between the column headers to the right of the column you want to lock.

A vertical column separator line, which appears 1 pixel wider than the line separating the other columns, indicates the area where the locked columns end and the normal columns begin.

To unlock all columns

  • Right-click between any column headers.

All columns are unlocked.

Note:
When any of columns scroll to the left out of view and are locked, they remain hidden until locking is removed. This functionality can be useful if you want to lock the columns in the middle of the grid and do not want to display the preceding or following columns. The Column SetFocus method does not function if a column is locked and hidden from view, for example, scrolled off to the left side. For more information, see SetFocus Method.

For example, suppose a grid contains five columns, and the data source has ten columns. When you scroll two columns to the right, the first and second columns scroll to the left and out of view. When you right-click the column header the first and second visible columns, which are actually the third and fourth columns, the first two hidden columns as well as the first visible column become locked. However, you cannot scroll to the left to view all the locked columns.

See Also

Other Resources

How to: View Records in Tables
How to: Navigate Records in Tables
How to: Filter Records in Tables
Working with Tables
Working with Records


How to: Add Records to Tables

Visual FoxPro 9.0
How to: Add Records to Tables
See Also

Before you can store data in tables, you must add records to store the data. You can add one or more blank records to the end of a table by appending records. You can also copy records from other tables or files and append them to a table.

To add a blank record to a table

  1. Open the table in a browse window.

  2. On the Table menu, click Append New Record.

    In the browse window, a blank record appears at the end of any records in the table.

For more information, see How to: View Records in Tables.

To add a blank record after typing data

  1. Open the table in a browse window.

  2. On the View menu, click Append Mode.

When working in append mode, a new blank record appears on the following row after you type data in the previous record.

For more information, see How to: View Records in Tables.

To add a blank record to a table programmatically

  • Choose one of the following:

    • Use the APPEND command with the BLANK keyword.

    -OR-

    • To add records and specify the data to store in the new records, use the SQL INSERT command.

When you use the SQL INSERT command, you can store data in records directly by specifying text or from constants, variables, arrays, objects, and other data sources. For more information, see INSERT – SQL Command and APPEND Command.

To append records from another table or file

  • Use the APPEND FROM command or the IMPORT command.

For more information, see APPEND FROM Command, IMPORT Command, and Importing and Exporting Data.

See Also

Other Resources

How to: Add Data to Records
Working with Records
Working with Tables


How to: Add Data to Records

Visual FoxPro 9.0
How to: Add Data to Records
See Also

You can add data to records after creating blank records or replace data in existing records. You can also edit each field in a record on a separate line by working with the table in edit mode. For more information, see How to: Add Records to Tables.

To add or replace data in records

  1. Open the table in a browse window.

    Tip:
    To view each field on a separate line, on the View menu, click Edit.

  2. In the table, insert the cursor in the field of the record you want, and type the data appropriate for the field's data type.

For more information, see How to: View Records in Tables.

To store data in records programmatically

  • Choose one of the following:

    • If the blank record you added is the current record, follow the APPEND BLANK command with the REPLACE command and specify the record to replace values in.

      Tip:
      By default, REPLACE replaces values in fields, including empty fields for the current record. When you use REPLACE, make sure the table is open, that the record exists, that you specify the field you want to store values in, and a value for each field that is appropriate for the field's data type.

    -OR-

    • Open the table, then use the EDIT or CHANGE commands to display the table in edit mode.

    -OR-

    • Use the SQL UPDATE command to update records in a table.

For more information, see REPLACE Command, EDIT Command, CHANGE Command, and UPDATE - SQL Command.

Tip:
When you use the REPLACE or the SQL UPDATE command in a multiple user application, you can edit data without locking the record until you want to commit changes by turning on record or table buffering. For more information, see Programming for Shared Access.

Adding Null Values to Records

You can type null values for fields in records.

Note:
To specify the text displayed for null values, use the SET NULLDISPLAY command. For more information, see SET NULLDISPLAY Command.

To store a null value in a field

  1. Open the table in a browse window.

  2. In the table, insert the cursor in the field of the record you want, and press CTRL+0 (zero).

To store a null value in a field programmatically

  • Include the NULL keyword with the command you use to add or replace data.

See Also

Other Resources

How to: Delete Records in Tables
Working with Records
Working with Tables


How to: Delete Records in Tables

Visual FoxPro 9.0
How to: Delete Records in Tables
See Also

You can delete records by marking them for deletion, then removing the deleted records. Otherwise, records marked for deletion remain on disk until you remove them. You can also delete and remove all records from a table.

Tip:
When viewing records in a browse window, records marked for deletion still appear if the SET DELETED command is set to OFF. To hide records marked for deletion, set the SET DELETED command to ON. SET DELETED also determines whether commands that operate on records can access records marked for deletion. You might also create an index tag using the DELETED( ) function. For more information, see Indexes Based on Deleted Records.

You can restore records marked for deletion before you remove them. For more information, see How to: Restore Deleted Records.

To mark a record for deletion

  1. Open the table in a browse window.

  2. In the browse window, insert the cursor in a field for the record you want to delete.

  3. On the Table menu, click Toggle Deletion Mark.

    The deletion mark appears in the column to the left of the first field in the record.

    Tip:
    You can also double-click the column to mark the record for deletion.

For more information, see How to: View Records in Tables.

To mark multiple records for deletion

  1. Open the table in a browse window.

  2. On the Table menu, click Delete Records.

    The Delete dialog box opens.

  3. In the Scope box of the Delete dialog box, select the range of records you want to delete.

  4. In the For box, type an expression that records must meet to include for deletion. To build an expression, click the ellipsis (...) button.

  5. In the While box, type an expression that evaluates to true in order to continue evaluating records to include for deletion.

  6. When you are finished, click Delete.

For more information, see How to: View Records in Tables and Delete (Records) Dialog Box.

To mark records for deletion programmatically

  • Use the SQL DELETE command.

For more information, see DELETE - SQL Command.

To delete and remove all records from a table

  • Use the ZAP command.

For more information, see ZAP Command.

Note:
Before you use the ZAP command, make sure the table has been opened exclusively.

Caution:
Records deleted and removed with ZAP cannot be restored.

See Also

Other Resources

How to: Remove Deleted Records
Working with Records
Working with Tables


How to: Restore Deleted Records

Visual FoxPro 9.0
How to: Restore Deleted Records
See Also

You can restore records that are marked for deletion but have not yet been removed.

To restore a record marked for deletion

  1. Open the table in a browse window.

  2. In the browse window, insert the cursor in the record marked for deletion.

  3. On the Table menu, click Toggle Deletion Mark.

    Tip:
    You can also click the deletion column next to the record marked for deletion to remove the deletion marker.

    The deletion marker is removed from the deletion column.

To restore multiple records marked for deletion

  1. Open the table in a browse window.

  2. On the Table menu, click Recall Records

    The Recall dialog box opens.

  3. In the Scope box of the Recall dialog box, select the range of records you want to restore.

  4. In the For box, type an expression that records must meet to include for restoration. To build an expression, click the ellipsis (...) button.

  5. In the While box, type an expression that evaluates to true in order to continue evaluating records to include for restoration.

  6. When you are finished, click Recall.

For more information, see Recall (Records) Dialog Box.

To restore deleted records programmatically

  • Use the RECALL command.

For more information, see RECALL Command.

See Also

Other Resources

How to: Remove Deleted Records
Working with Records
Working with Tables


How to: Remove Deleted Records

Visual FoxPro 9.0
How to: Remove Deleted Records
See Also

After marking records for deletion, you can remove them permanently from disk.

To remove marked records from disk

  1. Open the table in a browse window.

  2. On the Table menu, click Remove Deleted Records.

  3. When prompted to confirm deletion, click Yes.

    The marked records are removed from disk, and the browse window closes.

To remove marked records from disk programmatically

  • Use the PACK command

For more information, see PACK Command.

Tip:
PACK has two clauses: MEMO and DBF. Calling PACK without the MEMO or DBF clauses removes records marked for deletion in the table (.dbf) file and the associated memo (.fpt) file. When you call the PACK command, make sure the table has been opened exclusively. To delete records in the table file only and leave the memo file untouched, use PACK DBF. To remove unused space in the memo file without removing records marked for deletion in the table file, use PACK MEMO.

See Also

Other Resources

How to: Delete Records in Tables
Working with Records
Working with Tables


Working with Table Indexes

Visual FoxPro 9.0
Working with Table Indexes

When you create a table, Visual FoxPro creates a table (.dbf) file and, if your table includes memo or general fields, the associated table memo (.fpt) file. By default, Visual FoxPro stores records in the table in the order that you enter them. When your application performs operations on the table, the records are processed in the order they were entered.

You can control the order and increase the speed of processing table records by creating an index for the table. An index does not change the physical order of the records stored in the table; rather, it provides an efficient and versatile mechanism for accessing table records. For example, suppose you want to process records in a customer table by company name in alphabetical order. You can create a table index based on the company name field so that your application can process records in the order specified by the index you created. You can also add a filter to the index so you can add only those records that meet the filter criteria to the index.

After you create the table index, you can set the order of records in the table to the index so that your application processes records in the order specified. In addition, you can create different indexes for a table so that you can change the order in which your application processes records. For example, you might want to organize a customer table by contact name to quickly find the name you want or by postal code to generate mailing labels that are presorted for efficient mailing. You can create and store different ordering scenarios for tables by creating multiple indexes for the same table. You can use different types of index files to store indexes depending on their frequency of use.

You can also use indexes to create persistent relationships between tables in a database, making it possible for you to access the exact records you want. Persistent relationships between database tables are stored in the database file and exist as the default relationships when you use the tables in the data environment.

In This Section

Visual FoxPro Index Files

Describes different types of Visual FoxPro index files for storing indexes.
Visual FoxPro Index Types

Describes different index types.
How to: Create Indexes

Describes how to create indexes.
Index Creation Based on Expressions

Describes different types of expresions you can use to create indexes.
Considerations for Creating Index Expressions

Describes considerations to remember when creating index expressions.
Indexes Based on Deleted Records

Discusses how indexes based on deleted records improve query performance and ensure use of Rushmore query optimization.
How to: Filter Data

Describes how to add filters to indexes so you can select records containing only the data that you want.
How to: Create Less Frequently Used Indexes

Describes how to create indexes you use rarely or for a special task.
How to: Set Controlling Indexes

Describes how to select a controlling, or master, index for a table.
How to: Select Indexes at Run Time

Describes how the user can change the display of records at run time.
How to: Display Records in Descending Order

Describes how to change the display of records from ascending order to descending order.
How to: Enhance the Efficiency of Indexes

Describes how to improve index performance, primarily by keeping indexes updated.
How to: Delete Indexes

Describes how to remove indexes that you no longer use.

Reference

User Interface Reference

Explains the options that appear on various dialog boxes, windows, and other user interfaces. Generally, these topics appear when you press F1 in a dialog box or window.
Language Reference

Provides a list of language reference topics in alphabetical order.

Related Sections

Working with Data

Describes how to design and build your database to create effective applications with indexes, tables, and databases based on your data requirements.
Working with Tables

Discusses how to make sure your tables have the structure that your application requires.
Working with Fields

Introduces records, how to view them, and how to use them to store data in tables.


Visual FoxPro Index Files

Visual FoxPro 9.0
Visual FoxPro Index Files
See Also

When you create an index, you supply an expression, which can contain table field names, that specifies how table records should be organized. Visual FoxPro creates an index key for each record in the table based on the index expression and stores the index keys in an index file. The index file contains and maintains pointers to records in the table (.dbf) file and is organized according to the index key values. An index file is separate from but associated with a .dbf file.

Visual FoxPro supports the following types of index files: structural compound index (.cdx), nonstructural compound index (.cdx) files, and standalone index (.idx) files. The structural and nonstructural .cdx files can contain multiple indexes, which have names, or tags, that identify them, while the standalone .idx file contains only a single index.

The following diagram shows a .cdx file with three index names, or tags. Two of the index tags, emp_id and last_name, represent indexes based on single fields. The index tag, cntry_last, organizes records using a simple two-field index expression.

cdxTagsOrderScenarios graphic foxpro

The following table summarizes the index file types in Visual FoxPro, how they are named, the number of index keys they can contain, and the character limitations for each.

Visual FoxPro Index File Types

Index file type | Description | Contains | Limits
Structural compound index (.cdx) files | Opens and closes with the table automatically. Uses same base name as the table file name. | Multiple index keys | 240-character limit on evaluated expression
Nonstructural compound index (.cdx) files | Must be opened explicitly. Uses a name different from the base table name and is defined by the user. | Multiple index keys | 240-character limit on evaluated expression
Standalone index (.idx) files | Must be opened explicitly. Uses a name different from the base table name and is defined by the user. | Single index key | 100-character limit on evaluated expression

Structural Compound Index Files

When you create an index for a table, Visual FoxPro automatically creates a structural .cdx file to store the index. The term "structural" refers to the fact that Visual FoxPro treats the structural .cdx file as an intrinsic part of the table, opens and closes the structural .cdx file automatically when you open and close the table, and maintains the structural .cdx file automatically when you add, change, or delete table records. If a Visual FoxPro table has an index file associated with it, it is typically a structural .cdx file. A structural .cdx file always has the same base name as the table (.dbf) file name.

The structural .cdx file can contain multiple indexes in the same file. It is recommended that you use the structural .cdx file for indexes you frequently use and need to maintain on a regular basis, such as those used to organize records for daily viewing, data entry, Rushmore Query Optimization, or frequently printed reports.

Note:
For a given table, Visual FoxPro stores primary and candidate indexes in the structural .cdx file associated with the table (.dbf) file. You cannot store primary and candidate indexes in other .cdx files, such as nonstructural .cdx files, nor is it possible to use standalone index (.idx) files for primary and candidate indexes because the index file should always open whenever the associated table is opened.

Nonstructural Compound Index Files

Nonstructural .cdx files store multiple indexes that are not frequently used. You can use a nonstructural .cdx file when you want to create multiple indexes for a special purpose but do not want your application to maintain these indexes on a continuing basis. A nonstructural .cdx file always has a name that is different from the table (.dbf) file name and is defined by the user.

For example, suppose your application contains a special set of reports that analyzes data based on fields not normally indexed. You can create a nonstructural .cdx file containing the appropriate indexes, run the reports, and then delete the nonstructural .cdx file.

Note:
Unlike structural .cdx files that open automatically when the associated table is opened, you must open a nonstructural .cdx file explicitly using the SET INDEX command or the USE command with the INDEX clause. For more information, see SET INDEX Command and USE Command.

Standalone Index Files

Available primarily for backward compatibility, a standalone .idx file stores a single index key that is temporary or less frequently used. You can use standalone (.idx) files as temporary indexes by creating or reindexing them immediately before you use them. A standalone .idx file always has a name that is different from the table (.dbf) file name and is defined by the user.

For example, suppose you have an index that you use only for quarterly or annual summary reports. Instead of including this index in the structural .cdx file, where it is maintained every time you use the table, you can create a standalone .idx file to store this index. You can create as many .idx files as you want for a particular table.

See Also

Other Resources

Visual FoxPro Index Types
How to: Create Indexes
File Structures
Working with Table Indexes


Visual FoxPro Index Types

Visual FoxPro offers different index types so that you can perform additional tasks with data:

  • Control whether to permit duplicate values in the fields or index expression specified for generating index keys.

  • Establish referential integrity in persistent relationships between tables.

  • Optimize indexes based on logical expressions.

  • Select and organize a subset of records based on the first occurrence of a specified value.

  • Optimize search and query operations.

You can use all Visual FoxPro index types except binary indexes to perform query, view, ordering, and SEEK operations on records. You can use all index types to optimize filter conditions and ON and WHERE conditions in SQL SELECT statements.

The following table summarizes index types available in Visual FoxPro.

Visual FoxPro Index Types

Index type | Description | Number allowed
Primary | Does not permit duplicate values in the specified fields or expression. | One per table
Candidate | Does not permit duplicate values in the specified fields or expression. | Many per table
Regular | Permits duplicate values in the specified fields or expression. | Many per table
Binary | Indexes records based on a valid and non-null logical expression. | Many per table
Unique | Selects a subset of records based on the first occurrence of a specified value. Included for backward compatibility. | Many per table

Primary Indexes

The primary index contains an index key for each record in a table and is the default index when you do not specify any other indexes as the main index for the table. The primary index prohibits duplicate values in the fields or index expression specified for generating index keys; therefore, each index key in the primary index is unique. You can create only one primary index per table.

Note:
Primary indexes are an integral part of a table within a database. If you free a table from a database, the primary index is removed. If you specify a primary index on any field that contains duplicate data, Visual FoxPro generates an error.

The primary index is also principally used in the primary or "referenced" table to establish referential integrity in a persistent relationship between tables.

Candidate Indexes

Similar to a primary index, a candidate index contains an index key for each record in a table and prohibits duplicate values in the fields or index expression specified for generating index keys. However, you can create multiple candidate indexes per table. The name "candidate" actually refers to the status of the index; that is, you can create candidate indexes as alternative selections for the primary index.

Note:
If you specify a candidate index on any field that contains duplicate data, Visual FoxPro generates an error.

Candidate indexes can be used as either the referenced or referencing index to establish referential integrity in a persistent relationship between tables. For example, in a one-to-many relationship or a one-to-one persistent relationship, you can use candidate and primary indexes to define the "one" side in these relationships.

Regular Indexes

A regular index contains an index key for each record in the table but permits duplicate values in the fields or index expression specified for generating index keys. A regular index is simply an index that is not unique, primary, or candidate. You can create more than one regular index for a table.

You cannot use regular indexes to enforce the uniqueness of the data in those records. You can use a regular index as the "many" side in a one-to-many persistent relationship.

Binary Indexes

A binary, or bitmap, index is used for creating indexes based on logical expressions, for example, indexing deleted records, and is supported for free and database tables. However, binary indexes do not support the following:

  • Using index expressions that evaluate to null.

  • Using FOR clause filter expressions.

  • Changing the order in which records are displayed and processed, for example, by using the ASCENDING, DESCENDING, UNIQUE, or CANDIDATE keywords.

  • Setting binary indexes as controlling indexes, for example, by using the SET ORDER command.

  • Performing ordering and seek operations.

A binary index can be significantly smaller than a non-binary index and can improve the speed in maintaining indexes, for example, when using indexes based on deleted records. For more information, see Indexes Based on Deleted Records. Visual FoxPro can often create the Rushmore optimization bitmap faster for a binary index if the number of records returned is more than 3% of the total number of records. However, the Rushmore bitmap might be created slower if the number of records returned is less than 3% of the total number of records. The 3% threshold can decrease as the number of the records in the table increase.

Note:
Performance improvements or degradations and binary index sizes might vary with your specific data and application architecture. The numbers used in the example are based on tests using random test data.

You can create binary indexes using the Table Designer or the INDEX command. For more information, see How to: Create Indexes and INDEX Command.

Unique Indexes

Earlier versions of Visual FoxPro included unique indexes. Unique indexes do not actually prevent duplicate values from being entered in the table. The name "unique" actually describes the entries in the index file because the file does not store a particular index key more than once and disregards later occurrences of duplicate index keys. Unique indexes make it possible to specify that only the index key for the first record matching the index expression is added to the index. After a match occurs, no other index keys are added to the index. However, the table can still contain duplicate values.

Tip:
If you want to select records in this manner, it is recommended that you create a query or view instead. For more information, see Working with Queries and Working with Views.

See Also

Other Resources

How to: Create Indexes
Working with Table Indexes


How to: Create Indexes (Visual FoxPro)

Visual FoxPro 9.0
How to: Create Indexes (Visual FoxPro)
See Also

You can create an index for a table when you define a field for a table or after you create the table. When you create an index, you supply an expression, which can contain table field names, that specifies how table records should be organized. You can also specify a filter expression so that Visual FoxPro adds only those records that meet the filter criteria to the index.

Tip:
Indexes are easy to create, but they impact performance so use restraint when creating them. You do not need to define an index for every field. Indexes that you rarely use can slow performance.

You can create an index using the Visual FoxPro Table Designer or programmatically. For information about using Visual FoxPro commands to create indexes, see Creating Indexes Programmatically.

Note:
After you create an index, you need to select the index to use it for the table. For more information, see How to: Set Controlling Indexes.

To create an index using the Table Designer

  1. Open the Table Designer to modify your table.

  2. In the Table Designer, choose the Indexes tab.

  3. In the Name box, type a name for the index tag.

  4. In the Type list, choose the index type you want.

  5. In the Expression box, type the name of the field that you want use to organize the records.

    -OR-

    Build an index expression by clicking the ellipsis (...) button to the right of the box.

    Note:
    When specifying an index expression for binary indexes, you must specify a logical expression that does not evaluate to a null value. If the index expression is changed so that it contains or evaluates to a null value, Visual FoxPro generates an error.

  6. Choose OK.

For more information about index types, see Visual FoxPro Index Types.

For considerations concerning index expressions, see Index Creation Based on Expressions and Considerations for Creating Index Expressions.

You can add a filter to the index to select only those records that match the filter expression you supply. For more information, see How to: Filter Data.

When you create an index for a table, Visual FoxPro automatically creates a structural compound index (.cdx) file to store the index. This structural .cdx file has the same name as the table and opens automatically when the table opens. For more information about index files, see Visual FoxPro Index Files.

Tip:
By default, Visual FoxPro displays records in ascending order. You can specify to display records in descending order when you create the index or after you create the index. For more information, see How to: Display Records in Descending Order.

As you work with records in tables, you might need to access records in different orders. For example, you might want to organize a customer table by contact name to quickly find the name you want or by postal code to generate mailing labels that are presorted for efficient mailing. You can create and store different ordering scenarios for tables by creating multiple indexes for the same table.

Creating Indexes Programmatically

You can create indexes in structural compound index (.cdx) files using the Visual FoxPro language. You can create an index when you create a table using the SQL CREATE TABLE command or create an index for an existing table using the SQL ALTER TABLE command or the INDEX command.

Note:
If you want to create a primary index, use the SQL CREATE TABLE or ALTER TABLE commands. You cannot use the INDEX command to create primary indexes.

To create an index in a structural .cdx file when creating a table

  1. Use the SQL CREATE TABLE command to specify a name and fields for the table.

  2. To create a primary index, include the PRIMARY KEY clause for the corresponding field that you want to use.

    -OR-

    To create a candidate index, include the UNIQUE clause.

    Note:
    Including the UNIQUE clause is not the same as specifying a unique index.

    -OR-

    For all other indexes, include the FOREIGN KEY clause.

To create an index in a structural .cdx file for an existing table

  1. Use the SQL ALTER TABLE command to specify a name and fields for the table.

  2. To create a primary index, include the PRIMARY KEY or ADD PRIMARY KEY clause for the corresponding field that you want to use.

    -OR-

    To create a candidate index, include the ADD UNIQUE clause.

    -OR-

    For all other indexes, include the ADD FOREIGN KEY clause.

For example, using the Customer table from the Visual FoxPro sample database, TestData, you can use either of the following commands to assign the Cust_ID field as the primary key for the Customer table:

Copy Code
ALTER TABLE Customer ADD PRIMARY KEY Cust_ID TAG Cust_ID
ALTER TABLE Customer ALTER COLUMN Cust_ID c(5) PRIMARY KEY

For more information, see CREATE TABLE - SQL Command, ALTER TABLE - SQL Command, and INDEX Command.

You can also create indexes in structural .cdx files by copying from one or more standalone index (.idx) files using the COPY INDEXES command and omitting the TO clause.

To create in index in a structural .cdx file from an .idx file

  1. Use the COPY INDEXES command to specify one or more names of .idx files. To include each index key from all open .idx files, use the ALL keyword.

  2. Omit the TO clause.

For more information, see COPY INDEXES Command.

See Also

Other Resources

How to: Create Less Frequently Used Indexes
Working with Table Indexes


Index Creation Based on Expressions

Visual FoxPro 9.0
Index Creation Based on Expressions
See Also

You can increase application performance by creating indexes based on expressions. Expressions can range from the simple to the complex depending upon the tasks you want to accomplish. You can perform different tasks by creating indexes with expressions as described in the following sections:

  • Indexes Based on Simple Expressions

  • Indexes Based on Complex Expressions

  • Fields with Null Values in Index Expressions

You can also increase the speed for queries, reports, or other operations using index expressions that use Rushmore optimization. For more information, see Optimizing Applications.

Indexes Based on Simple Expressions

You can create indexes using simple index expressions, which are based on a single field or the concatenation of two or more character fields. You can also create index expressions containing fields from another table.

Tip:
If you want to include fields with different data types in an index expression, convert any non-character fields to character fields by enclosing the field with the STR( ) function.

For example, suppose you want to organize records by a maximum order amount and then by company name. The following code converts the MaxOrdAmt field, which has type Currency, so it can be concatenated with the Company field, which has type Character:

Copy Code
STR(customer.maxordamt,20,4) + customer.company

For more information, see STR( ) Function.

One or More Fields in Index Expressions

When you include one or more fields in an index expression, you can perform the following tasks:

  • Sort data in the order that the fields appear in the index expression.

    Visual FoxPro evaluates fields in the order that they appear in the expression. For example, suppose you want to view records in a customer table sorted by country, region, then customer ID. The following expression creates an index for the customer table by using a plus sign (+) to include multiple fields:

    Copy Code
    customer.country + customer.region + customer.cust_id
  • Prevent duplicate values in tables by using a primary or candidate index that includes one or more fields.

    For more information about controlling duplicate values, see Duplicate Values in Fields.

  • Optimize performance and increase speed for queries and views with filters on more than one field by including more than one field in the index expression.

    By including fields that change the least at the beginning of the expression, indexing can be limited to those fields whose values change more frequently. For example, suppose you want to organize records in a customer table by country, postal code within the country, and the company name within the postal code. In the following example, the Country field appears in the beginning of the list because it changes the least:

    Copy Code
    customer.country + customer.postal_code + customer.company

Fields from Another Table in Index Expressions

You can create an index expression that refers to fields in another table, for example, one that is open in another work area. However, it is recommended that you store any index tag that refers to more than one table in a standalone index (.idx) file instead of the associated structural compound index (.cdx) file. When an index tag for one table refers to another table, Visual FoxPro does not permit opening the table associated with the .cdx file until you open the other table that the index tag references.

Indexes Based on Complex Expressions

You can create indexes using complex expressions, which can contain constants, Visual FoxPro functions, stored procedures, or user-defined functions. To take advantage of Rushmore Query Optimization, the index expression must exactly match the criteria.

Visual FoxPro Functions in Index Expressions

You can use Visual FoxPro functions in an index expression.

For example, you can use the STR( ) function to convert a numeric value into a character string. Suppose you wanted to create an index for a customer table that combines the customer ID field with the maximum order amount field. You can convert the MaxOrdAmt field from a Currency field to a Character field using the following code:

Copy Code
INDEX ON cust_id + STR(maxordamt, 8, 2) TAG custmaxord

If you want to reduce the size of indexes for fields with integer values, you can convert the integer values to a binary character representation using the BINTOC( ) function. You can also convert the binary values to integer values using the CTOBIN( ) function.

If you want to create an index to sort a table in chronological order, you can use the DTOS( ) function to convert a date field to a character string. For example, suppose you wanted to access an employee table by the hire date and employee ID. The following example code creates the index expression that performs this task:

Copy Code
INDEX ON DTOS(hire_date) + emp_id TAG id_hired

For more information, see STR( ) Function, BINTOC( ) Function, CTOBIN( ) Function, and DTOS( ) Function.

Stored Procedures or User-Defined Functions in Index Expressions

You can increase the power of an index by referencing a stored procedure or including a user-defined function (UDF) in the index expression.

Note:
Certain considerations exist when you include a UDF in an index expression. Referencing a stored procedure or using a UDF in an index expression increases the time required to create or update the index. For more information, see Considerations for Creating Index Expressions.

For example, you can use a stored procedure to extract the street name from a single field that includes both the street number and street name. If the street number is always numeric, the stored procedure can return the character portion of the field and pad the field with spaces as needed to create a constant-length index key. You can then use this index key to access records in the table in street name order.

Fields with Null Values in Index Expressions

You can create indexes on fields that contain null values. Visual FoxPro inserts index expressions that evaluate to null (.NULL.) into the compound index (.cdx) or standalone index (.idx) file preceding index expressions that do not evaluate to null. Therefore, all null values appear at the beginning of the index.

For example, the following diagrams demonstrate one effect of indexing null values. Before an index is applied, the first diagram shows the Social Security field for the third and fifth records contain null (.NULL.) values, which indicate that Social Security numbers are either unknown or unavailable.

The following example code creates an index using an index expression containing the Social Security field:

Copy Code
INDEX ON SocSec + LastName + FirstName TAG MyIndex

When the index containing the Social Security field is applied, the table first displays those records that contain null values for Social Security numbers, sorted by last name in descending order, followed by the remaining records ordered by Social Security number.

Note:
Two entries exist for Alan Carter. However, because record number 5 contains a null value, record number 5 is indexed before record number 2.

See Also

Other Resources

How to: Create Indexes
Considerations for Creating Index Expressions
Working with Table Indexes


Considerations for Creating Index Expressions

Visual FoxPro 9.0
Considerations for Creating Index Expressions
See Also

When creating index expressions, be aware of the following considerations:

  • If you specify an expression that exceeds the limits set for creating index keys, Visual FoxPro generates an error.

    The length of an index key in a compound index (.cdx) file must be between 1 and 240 characters. The length of an index key in an index (.idx) file must be between 1 and 100 characters. With some collating sequences, or when using double-byte character set (DBCS) characters, each character in the index expression uses two characters in the index key. In these cases, the length of the index expression is limited to 120 characters.

  • If you create an index expression using numeric fields, the index organizes records by the sum of the fields, not the fields themselves.

  • Visual FoxPro does not support variable length index keys. If you attempt to build an index with a key that varies in length, the key is padded with spaces.

  • Do not use a variable, an array element, or a field or field expression from a table in another work area for the index expression.

    If you access an index that contains a variable or field that no longer exists or cannot be located, Visual FoxPro generates an error message.

  • Even though Visual FoxPro generates an error, it is possible to create an index key with zero (0) length.

    When Visual FoxPro creates an index, it evaluates fields in the first record in the table. Therefore, if the index expression is a substring of an empty memo field, a zero-length index key is created.

    Tip:
    To prevent creating a zero-length index key if a field is empty, it might be necessary to enter some temporary data in the field of the first record.

  • Visual FoxPro pads index keys based on Character, Varchar, Varchar (Binary), and Varbinary fields and expressions.

    Index keys based on Varchar, Varchar (Binary), and Varbinary fields and expressions include padding even though these data types do not usually include padding. Index keys based on Varchar and Varchar (Binary) are padded with additional spaces, similar to index keys based on Character fields and expressions. Index keys based on Varbinary fields or expressions are padded with zeros from the right side of the value in the field to the maximum length of the field. For example, the values 0hAA, 0hAA00, and 0hAA000 have the same index key of 0hAA0000. For more information, see Varchar Field Type and Varbinary Data Type.

  • Memo and Blob fields must be combined with other character expressions in index file expressions; they cannot be used alone. General fields cannot be used in index expressions.

    If you include a field prefaced by a table alias or work area letter in the index expression, Visual FoxPro generates an error message.

  • Avoid using aliased fields when creating indexes even though you can optimize FOR clauses with Rushmore Query Optimization technology when aliased fields are included.

    In several cases, for example, with the USE...AGAIN command and SQL queries, a different alias is automatically assigned to a table, and the index might not be properly updated or used. For more information on Rushmore technology, see Using Rushmore Query Optimization to Speed Data Access.

  • Although an index expression can contain a user-defined function (UDF), it is not recommended that you include a UDF in an index expression.

    Though both stored procedures and user-defined functions in an index expression increase the time it takes to create or update the index, if your table is associated with a database, you might prefer to use a stored procedure rather than a UDF in your index expression.

    If you use a UDF in an index expression, Visual FoxPro must be able to locate the user-defined function. When Visual FoxPro creates an index, the index expression is saved in the index file; however, only a reference to the UDF is included in the index expression. The UDF is stored in a file that is separate from the database; therefore, it is possible to move or delete the UDF file, which invalidates the reference in the index expression to the UDF.

    In contrast, stored procedure code is stored in the table (.dbc) file and can always be located by Visual FoxPro. Also, referencing a stored procedure in an index expression guarantees that the index is based on the exact code you specify.

    Also, index updates might not occur when user-defined functions are not in the scope of applications that modify the index. If you use a UDF in your index expression, Visual FoxPro uses any UDF that is in scope when indexing the table and that has the same name as the UDF referenced in the index.

    If you use a UDF associated with a database in an index expression, Visual FoxPro handles the expression in the same way it handles rule and trigger expressions that contain UDFs. For more information, see Enforcing Business Rules and Trigger Usage.

  • Be sure to use functions invariant from the current code page setting when creating an index that should be modified under different current code pages. Results of some functions used in index expressions can vary depending on the current codepage.

    For example, the UPPER( ) function uses the current code page to transform a string and might yield unexpected results if the index is modified under different current code pages or when the index is applied to a field and the current code page is not the same as the code page tagged to the table. You can use the STRCONV( ) function instead, STRCONV(...,8,...).

    Visual FoxPro evaluates index expressions by reading character data from the table without additional code page translation even when current code page (CPCURRENT()) does not match code page tagged to the table (CPDBF()) in order to produce the same index regardless of the current code page.

See Also

Other Resources

How to: Create Indexes
INDEX Command
Working with Table Indexes


Indexes Based on Deleted Records

Visual FoxPro 9.0
Indexes Based on Deleted Records
See Also

When records are marked for deletion in Visual FoxPro, they are not physically removed until the PACK command is called. Therefore, these records remain visible and accessible while performing basic table operations unless you set the SETDELETED command to ON, which hides these records from basic operations.

To help ensure that queries use Rushmore optimization, some developers create an index tag for deleted records by using the DELETED( ) function in the index expression. The DELETED( ) function determines whether a record is marked for deletion. For example, the following code creates an index named Deleted using an index expression that includes the DELETED( ) function that selects records marked for deletion:

Copy Code
INDEX ON DELETED() TAG Deleted

However, performance issues can still exist with this method, usually when working with large data sets in a LAN/WAN networking environment where deleted records are scattered in a table and when transmitting a large index over the network.

Instead, you can create and use a binary index, which optimizes the bit that marks records for deletion, to improve performance when you set the SET DELETED command to ON. You can create a binary index by choosing the Binary index type in the Table Designer or by including the BINARY keyword in the INDEX command. For example, the following code creates a binary index named myDeleted that selects records marked for deletion:

Copy Code
INDEX ON DELETED() TAG DeletedTag BINARY

For more information, see Visual FoxPro Index Types, DELETED( ) Function, and SET DELETED Command.

Rushmore Optimization for Indexes Based on Deleted Records

For indexes based on deleted records, Visual FoxPro includes the following Rushmore optimization enhancements in the SQL engine:

  • INDEX ON NOT(DELETED()) optimizes NOT(DELETED()) and DELETED() query conditions. In versions prior to Visual FoxPro 9.0, only DELETED() was optimized.

    For example, the following queries are now optimized:

    Copy Code
    CLEAR
CLOSE DATABASE ALL
SYS(3054,1)
CREATE TABLE myTable (f1 I)
INDEX ON NOT(DELETED()) TAG NotDel

SET DELETED OFF
SELECT * FROM myTable WHERE NOT(DELETED()) INTO CURSOR tempCursor
SELECT * FROM myTable WHERE DELETED() INTO CURSOR tempCursor

SET DELETED ON
SELECT * FROM myTable INTO CURSOR tempCursor
INDEX ON DELETED() TAG Del

SET DELETED OFF
SELECT * FROM myTable WHERE NOT(DELETED()) INTO CURSOR tempCursor
SELECT * FROM myTable WHERE DELETED() INTO CURSOR tempCursor

SET DELETED ON
SELECT * FROM myTable INTO CURSOR tempCursor
CLOSE DATABASE ALL
  • INDEX ON ... FOR DELETED( ) or INDEX ON ... FOR NOT(DELETED()) optimizes DELETED() or NOT(DELETED()) query conditions respectively when INDEX ON DELETED() or INDEX ON NOT(DELETED()) is not present.

    For example, the following queries are now optimized:

    Copy Code
    CLEAR
CLOSE DATABASES ALL
SYS(3054,1)
CREATE TABLE myTable (f1 I)
INDEX ON f1 TAG f1_NotDel FOR NOT(DELETED())
INDEX ON f1 TAG f1_Del FOR DELETED()

SET DELETED OFF
SELECT * FROM myTable WHERE NOT(DELETED()) INTO CURSOR tempCursor
SELECT * FROM myTable WHERE DELETED() INTO CURSOR tempCursor

SET DELETED ON
SELECT * FROM myTable INTO CURSOR tempCursor
INDEX ON DELETED() TAG DeletedRec

SET DELETED OFF
SELECT * FROM myTable WHERE NOT(DELETED()) INTO CURSOR tempCursor
SELECT * FROM myTable WHERE DELETED() INTO CURSOR tempCursor

SET DELETED ON
SELECT * FROM myTable INTO CURSOR tempCursor
CLOSE DATABASES ALL
  • When Visual FoxPro can determine that a query should not return deleted or undeleted records, and if no unfiltered index is present, it uses INDEX ON <expression> ... FOR DELETED() or INDEX ON <expression> FOR NOT(DELETED()).

    For example, the following queries are now optimized:

    Copy Code
    CLEAR
CLOSE DATABASE ALL
SYS(3054,1)
CREATE TABLE myTable (f1 I,f2 I)
INDEX ON f1 TAG f1_NotDel FOR NOT(DELETED())
INDEX ON f1 TAG f1_Del FOR DELETED()

SET DELETED OFF
SELECT * FROM myTable WHERE ;
  (NOT(DELETED()) AND f1>3) OR ;    && Tag f1_NotDel used for optimization.
  (DELETED() AND f1<3) ;       && Tag f1_Del used for optimization.
  INTO CURSOR tempCursor
SELECT * FROM myTable WHERE ;
  (f1>3 AND NOT(DELETED())) OR ;   && Not optimized. f1>3 comes first.
  (f1<3 AND DELETED()) ;      && Not optimized. f1<3 comes first.
  INTO CURSOR tempCursor

SET DELETED ON
SELECT * FROM myTable WHERE ;
  (f1>3000) OR ;       && Tag f1_NotDel used for optimization.
  (f1<1000) ;         && Tag f1_NotDel used for optimization.
  INTO CURSOR tempCursor
INDEX ON f1 TAG f1

SET DELETED OFF
SELECT * FROM myTable WHERE ;
  (NOT(DELETED()) AND f1>3) OR ;   && Tag f1 used for optimization.
  (DELETED() AND f1<3) ;    && Tag f1 used for optimization.
  INTO CURSOR tempCursor

SET DELETED ON
SELECT * FROM myTable WHERE ;
  (f1>3000) OR ;       && Tag f1 used for optimization.
  (f1<1000) ;      && Tag f1 used for optimization.
  INTO CURSOR tempCursor
CLOSE DATABASE ALL
  • If only indexes with NOT(DELETED()) filter expressions are used for Rushmore optimization and SET DELETED is set to ON, then additional optimization using NOT(DELETED()) is not performed as it is unnecessary.

SQL Optimizations for MIN( ) and MAX( ) Aggregate Functions

When appropriate, Visual FoxPro uses FOR DELETED() and FOR NOT(DELETED()) filter expressions to optimize MIN( ) and MAX( ) aggregate functions. Visual FoxPro uses filtered indexes based on DELETED() index expressions when available.

Filtered indexes that use FOR NOT(DELETED()) can provide additional optimization with SQL queries with any SET DELETED setting. However, a filtered index tag with FOR DELETED() provides benefits only when SET DELETED is set to OFF.

Note:
These optimizations are not Rushmore-based; therefore, they do not appear in the results returned by SYS(3054) - Rushmore Query Optimization Level.

Copy Code
CLEAR
SET SAFETY OFF
CLOSE DATABASE ALL

CREATE TABLE myTable (f1 I)
INDEX ON f1 TAG f1

SET DELETED OFF
SELECT MAX(f1) FROM myTable INTO CURSOR temp1
* tag f1 is used to optimize MAX(f1)

SELECT MAX(f1) FROM myTable WHERE DELETED()INTO CURSOR temp1
* MAX(f1) is not optimized and slow

SET DELETED ON
SELECT MAX(f1) FROM myTable INTO CURSOR temp1
* MAX(f1) is not optimized and slow

SELECT myTable
INDEX ON f1 TAG f1Del FOR DELETED()
INDEX ON f1 TAG f1NotDel FOR NOT(DELETED())

SET DELETED OFF
SELECT MAX(f1) FROM myTable INTO CURSOR temp1
* tag f1 is used to optimize MAX(f1)

SELECT MAX(f1) FROM myTable WHERE DELETED()INTO CURSOR temp1
* tag f1Del is used by  MAX(f1)

SET DELETED ON
SELECT MAX(f1) FROM myTable INTO CURSOR temp1
* tag f1NotDel is used to optimize MAX(f1)

CLOSE DATABASE ALL

See Also

Other Resources

How to: Create Indexes
How to: Create Less Frequently Used Indexes
How to: Filter Data
Working with Table Indexes


How to: Filter Data

Visual FoxPro 9.0
How to: Filter Data
See Also

You can limit the records that you access to only the data you want by using a filtered index or temporary filter condition. When you create a filtered index, Visual FoxPro creates index keys in the index file for only those records that match the filter expression. Filtered indexes are useful for creating complex filter conditions.

Note:
It is not recommended that you use values other than field values, constants, and built-in functions to create filter expressions. You cannot specify filter expressions for binary indexes.

To create filtered index

  1. Open the Table Designer to modify the table and choose the Indexes tab.

  2. In the Filter box, type a filter expression.

    -OR-

    Build a filter expression by clicking the ellipsis (...) button to the right of the box.

  3. Choose OK.

For example, the following filter expression selects only those records for customers in Canada:

Copy Code
customer.country = "Canada"

To create filtered indexes programmatically

  • Use the INDEX command and include the FOR clause to specify a filter expression.

For example, suppose you want to prepare a mailing for your company's sales representatives and you want to sort the mailing by country. You might create an index that filters the employee table so that only the records for sales representatives appears, ordered by country and last name. The following code creates a filtered index and displays the filtered data in a browse window:

Copy Code
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Employee
INDEX ON country+last_name FOR title = "Sales Representative" ;
TAG reps_cntry
BROWSE

When you view the browse window, only the sales representatives are shown; the records for other employees do not appear at all in the browse window.

For more information, see INDEX Command.

Temporary Filters

You can also filter data temporarily without creating a filtered index.

To filter data temporarily

  • Use the SET FILTER command.

    SET FILTER is particularly useful when you want to specify a temporary condition that records in a table must meet to be accessed.

In the following example, SET FILTER filters the Customer table to show only the customers in Germany:

Copy Code
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer
SET FILTER TO country = "Germany"
BROWSE

SET FILTER accepts any valid Visual FoxPro logical expression as the filter condition. You can turn off the filter for the current table by using SET FILTER TO without an expression.

After you use SET FILTER, only those records that satisfy the filter condition are available in the table. All commands that access the table respect the SET FILTER condition. You can set a separate filter for every open table.

For more information, see SET FILTER Command.

See Also

Other Resources

How to: Create Indexes
How to: Display Records in Descending Order
Working with Table Indexes


How to: Create Less Frequently Used Indexes

Visual FoxPro 9.0
How to: Create Less Frequently Used Indexes
See Also

If you want to create an index that you use infrequently, for example, for a special purpose, you can store it in nonstructural compound index (.cdx) files, which can contain multiple indexes. Included for backward compatibility, you can also store a single temporary or less frequently used index in a standalone index (.idx) file. For more information about index files for storing infrequently used indexes, see Visual FoxPro Index Files.

You can create indexes in nonstructural .cdx files and standalone .idx files using the Visual FoxPro language.

Indexes in Nonstructural Compound Index Files

For an existing table, you can create an index in a nonstructural .cdx file using the INDEX command with the TAG and OF clauses or by copying from one or more standalone index (.idx) files using the COPY INDEXES command.

To create an index in a nonstructural .cdx index file

  1. Use the INDEX command to specify an index expression.

  2. Include the TAG clause to specify the name, or tag, for the index.

  3. Include the OF clause to specify the name of the nonstructural .cdx file.

For example, the following code opens the Employee table in the Visual FoxPro sample database, TestData, and creates an index based on the Title field. The INDEX command includes the TAG clause to specify a name, or tag, for the index and the OF clause to store the index in a nonstructural .cdx file named QRTLYRPT with the .cdx file name extension:

Copy Code
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Employee
INDEX ON Title TAG Title OF QRTLYRPT

For more information, see OPEN DATABASE Command, USE Command, and INDEX Command.

To create an index in a nonstructural .cdx file from an .idx file

  1. Use the COPY INDEXES command to specify one or more names of .idx files. To include each index key from all open .idx files, use the ALL keyword.

  2. Include the TO clause to specify the name of the nonstructural .cdx file.

For more information, see COPY INDEXES Command.

Indexes in Standalone Index Files

For an existing table, you can create a single-key index in a standalone .idx file using the INDEX command with the TO clause or by copying an index from a compound index (.cdx) file using the COPY TAG command.

Tip:
To create a small and quickly accessible index file, include the COMPACT clause. However, to create an .idx file that is compatible with the FoxBASE+® and FoxPro® version 1.0 index formats, omit the COMPACT clause.

Note:
By default, .cdx files are always compact.

To create a single-key index

  1. Use the INDEX command to specify the index expression.

  2. Include the TO clause to specify the name of the .idx file.

  3. Include the COMPACT clause.

For example, the following code opens the Orders table in the Visual FoxPro sample database, TestData, and creates an index based on the Order_Date field. The TO clause specifies OrdDate as the name of the .idx file. The SET ORDER command sets the order of the table to the OrdDate file, and the BROWSE command opens a browse window that displays the records organized by the Order_Date field:

Copy Code
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Orders
INDEX ON Order_Date TO OrdDate COMPACT
SET ORDER TO OrdDate
BROWSE

For more information, see OPEN DATABASE Command, USE Command, INDEX Command, SET ORDER Command, and Browse Window.

You can also create a standalone index from an index in a .cdx file using the COPY TAG command.

To create a single-key index from a .cdx file

  1. Use the COPY TAG command to specify the name of the index in the .cdx file.

  2. If needed, include the FROM clause to specify the name of the .cdx file.

  3. Include the TO clause to specify the name of the .idx file.

  4. Include the COMPACT clause.

For example, suppose that one of the indexes in a structural .cdx file is used only for quarterly or annual reports. You can transfer this index from the .cdx file to an .idx file. The following code opens the Employee table in the Visual FoxPro sample database, TestData, and creates a single-key index based on the index named Birth_Date in the structural .cdx file associated with the Employee table. The single-key index is stored in an .idx file named BirthDate.

Copy Code
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Employee
COPY TAG Birth_Date TO BirthDate COMPACT
Note:
When a table is open, any associated structural .cdx file is also open.

Tip:
After you create the .idx file from the .cdx file, you should delete the tag from the .cdx file. For more information about deleting indexes, see How to: Delete Indexes.

For more information, see OPEN DATABASE Command, USE Command, and COPY TAG Command.

See Also

Other Resources

How to: Create Indexes
Visual FoxPro Index Types
Working with Table Indexes


How to: Set Controlling Indexes

Visual FoxPro 9.0
How to: Set Controlling Indexes
See Also

A table can have many index files open simultaneously; however, only one master, or controlling, index file or tag specifies the order in which Visual FoxPro displays or accesses the table. Also, certain commands, such as the SEEK command, use the controlling index file or tag to search for records.

Note:
You cannot select binary indexes as controlling indexes. Visual FoxPro does not support the SET ORDER command when setting to a binary index tag. If you attempt to set order to a binary tag, Visual FoxPro generates an error, and the current order remains at its prior setting. Records in the table are displayed and accessed in record number order and not in an indexed order. Therefore, Visual FoxPro does not support SEEK operations for binary indexes.

After you create one or more indexes for a table, you need to assign a controlling index for organizing records in your table. You can designate an index tag in a compound index (.cdx) file or a standalone index (.idx) file as the controlling index tag or file. When changes are made to the table, all open .idx and .cdx files are updated.

You can select a controlling index using the Visual FoxPro IDE or language.

To designate a controlling index

  1. Open the browse window for your table.

  2. On the Table menu, choose Properties.

  3. In the Index order box of the Work Area Properties dialog box, select the index you want to use.

  4. Choose OK.

The browse window displays records in the order that the index specifies.

To set controlling indexes programmatically

  • Choose one of the following:

    • To set the controlling index for a table, use the SET ORDER command.

      Tip:
      When opening a table using the USE command, including the ORDER clause in performs the same function as SET ORDER.

      You do not need to use SET ORDER for running queries.

    • To set the controlling index for the currently open table, use the SET INDEX command.

      Tip:
      When opening a table using the USE command, including the INDEX clause in performs the same function as SET INDEX.

For example, suppose an index with the tag name Country is created for the Customer table in the Visual FoxPro sample database, TestData. The following code uses the SET ORDER command to specify Country as the controlling index for displaying the records in the table when you open the table. The BROWSE command opens a browse window and displays the records by country name:

Copy Code
OPEN DATABASE (HOME(2) + 'Data\TestData')
SET ORDER TO Country
BROWSE

For more information, see SET ORDER Command, SET INDEX Command, USE Command, and BROWSE Command.

See Also

Other Resources

How to: Create Indexes
How to: Select Indexes at Run Time
How to: Display Records in Descending Order
Working with Table Indexes


How to: Select Indexes at Run Time

Visual FoxPro 9.0
How to: Select Indexes at Run Time
See Also

You can provide the capability for users to organize records interactively when they click a column header in a grid on a form. For example, suppose you want to permit application users to organize records in a grid on a form by clicking the column header they want to organize records by. To provide this capability, include the SET ORDER command to change the order of records in a form at run time.

To organize records interactively on a form

  1. Create a form with a Grid control.

  2. Set the grid's ColumnCount property to the number of fields you want to display in the grid.

  3. For the header of each column in the grid, insert code that includes the SET ORDER command in the header's Click event that performs the following tasks:

    • Sets the record order to an index key based on the column.

    • Refreshes the form.

For example, suppose you created a form based on the Customer table in the Visual FoxPro sample database, TestData, with a grid containing four columns: Company, Contact, Postal_Code, and Phone. The grid appears sorted alphabetically first because the records in that table were entered alphabetically. However, you can then make it possible for the user to view the grid ordered by contact name or postal code by inserting the code that uses the SET ORDER command in the Click event of each column header.

The following table describes sample code you can include in the Click event.

Code | Comment
SET ORDER TO Company GO TOP THISFORM.Refresh | In the Company header Click event code, reorder the grid using the Company index key and refresh the form to display records in order by company name.
SET ORDER TO Contact GO TOP THISFORM.Refresh | In the Contact header Click event code, reorder the grid by the Contact index key and refresh the form to display records in order by contact name.
SET ORDER TO PostalCode GO TOP THISFORM.Refresh | In the Postal_Code header Click event code, reorder the grid by the PostalCode index key and refresh the form to display records in order by postal code.

In the example, when the form is first displayed, the grid appears in alphabetical order by company. When the user clicks the header of the Contact column, Visual FoxPro displays the records in the grid in alphabetical order by contact name. If the user clicks the Postal_Code column header, the grid is resorted and displayed in order by postal code.

See Also

Other Resources

SET ORDER Command
Grid Control
ColumnCount Property
Click Event
Working with Table Indexes


How to: Display Records in Descending Order

Visual FoxPro 9.0
How to: Display Records in Descending Order
See Also

Visual FoxPro displays records in a table in ascending order by default. However, you can create indexes that display records in descending order or you can display records in descending order when you view records in a table.

Note:
You cannot change the order for displaying or processing records when using binary indexes.

You can create descending indexes in structural compound index (.cdx) files using the Visual FoxPro IDE or the language. To create descending indexes for other index files, use the Visual FoxPro language.

To create indexes in descending order

  1. Open the Table Designer to modify your table and choose the Indexes tab.

  2. In the Order column next to the Name box for the index, click the upward-pointing arrow so that it points down.

    Note:
    An upward-pointing arrow appears in the Order column only when an index name exists in the Name box.

To display records in descending order programmatically

  • Include the DESCENDING keyword in the following Visual FoxPro commands:

    • INDEX Command

    • SET ORDER Command

    • SET INDEX Command

    • USE Command

Though Visual FoxPro displays records in ascending order by default, these commands also include the ASCENDING keyword. You can use both keywords to change orders based on the order that is most convenient.

For example, the following code opens the Products table in the Visual FoxPro sample database, TestData, using the USE command. The INDEX command creates an index based on the Unit_Price field with the index name, or tag, Unit_Price. The INDEX command includes the DESCENDING keyword to display the records in descending order in a browse window when the BROWSE command is called. The records in the Products table appear in order of highest price to lowest price:

Copy Code
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Products
INDEX ON Unit_Price TAG Unit_Price DESCENDING
BROWSE

When an index already exists, you can view records in descending order instead of creating a new descending index. For example, suppose you created an index that organizes a product table by unit price as shown in the following code:

Copy Code
USE Products
INDEX ON Unit_Price TAG Unit_Price

By default, Visual FoxPro displays records in ascending order by default. However, you can browse records in descending order using the following code:

Copy Code
USE Products
SET ORDER TO Unit_Price DESCENDING
BROWSE

See Also

Other Resources

How to: Create Indexes
How to: Set Controlling Indexes
DESCENDING( ) Function
Working with Table Indexes


How to: Enhance the Efficiency of Indexes

Visual FoxPro 9.0
How to: Enhance the Efficiency of Indexes
See Also

You can improve the performance of indexed tables by keeping indexes current and using expressions that can be optimized in your indexes. You can rebuild active index files or reindex tables at run time.

Rebuilding Active Index Files

When you open a table without opening its corresponding index files and make changes to the key fields in the table, index files become outdated. Index files can also become invalid when a system crash occurs or potentially by accessing and updating a table from a program other than Visual FoxPro. When index files become outdated, you can update them by reindexing with the REINDEX command.

To rebuild an active index file

  1. Open the table you want to reindex.

  2. On the Table menu, choose Rebuild Indexes.

To rebuild active index files programmatically

  • Use the REINDEX command to rebuild an index.

    REINDEX updates all index files open in the selected work area. Visual FoxPro recognizes and reindexes each index file type accordingly.

    For example, the following code updates the index file for the Customer table in the Visual FoxPro sample database, TestData:

    Copy Code
    OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer
REINDEX

For more information, see REINDEX Command.

Note:
Reindexing tables at run time can take time, particularly when you're reindexing large tables. You should reindex tables only when necessary. You can enhance performance by reindexing during the initialization or termination portion of your program, rather than performing indexing maintenance during the main portion of an application.

See Also

Other Resources

Working with Table Indexes


How to: Delete Indexes (Visual FoxPro)

Visual FoxPro 9.0
How to: Delete Indexes (Visual FoxPro)
See Also

By deleting indexes, or index tags, that you never use, you can improve performance by removing the need for Visual FoxPro to update those tags. To delete an index, delete the index tag in the compound index (.cdx) file or delete the entire standalone index (.idx) file.

You can delete index tags in structural .cdx files by using the Visual FoxPro IDE or language. To delete an .idx file or index tags from a nonstructural .cdx file, use the Visual FoxPro language.

Deleting Index Tags from a Structural .cdx File

You can delete an index tag from the structural .cdx file by using the Table Designer, the DELETE TAG command if you know the tag name, or the SQL ALTER TABLE command if you do not know the tag name but you know the tag is a primary or unique index.

To delete an index tag in a structural .cdx file

  1. Open the Table Designer to modify your table and choose the Indexes tab.

  2. Select the index and choose Delete.

    For more information, see Table Designer.

-OR-

  • Use the DELETE TAG command.

    For example, suppose the structural .cdx file for the Employee table in the Visual FoxPro sample database, TestData, contains an index tag named Title. The following code deletes the Title index tag:

    Copy Code
    USE Employee
DELETE TAG Title
    To delete all the tags in the .cdx file, include the ALL clause in the DELETE TAG command. For more information, see DELETE TAG Command.

-OR-

  • Use the DROP PRIMARY KEY or DROP UNIQUE TAG clause in the SQL ALTER TABLE command.

    For example, suppose the index tag you wanted to delete is the primary key for the Employee table in the sample database, TestData, but you did not have the name of the index key. You can use the DROP PRIMARY KEY clause in the SQL ALTER TABLE command:

    Copy Code
    USE employee
ALTER TABLE DROP PRIMARY KEY
    For more information, see ALTER TABLE – SQL Command.

Deleting Index Tags from a Nonstructural .cdx File

You cannot view the index tags in nonstructural .cdx files in the Table Designer. Therefore, you must know the name of the index tag and use the DELETE TAG command to delete an index tag from a nonstructural .cdx file.

To delete an index tag in a nonstructural .cdx file

  • Use the DELETE TAG command and the OF clause to specify the name of the tag and the .cdx file that you want to delete the index tag from.

    For example, suppose you have a nonstructural .cdx file named QRTLYRPT.CDX containing a tag named Title. The following line of code deletes the Title tag:

    Copy Code
    DELETE TAG Title OF QRTLYRPT

    To delete all the tags in the .cdx file, use the ALL clause in the DELETE TAG command. For more information, see DELETE TAG Command.

Deleting Standalone .idx Files

A standalone index (.idx) file contains only a single index key expression; therefore, you can delete the index by deleting the .idx file.

To delete a standalone .idx file

  • Use the DELETE FILE command.

    For example, suppose you have a standalone .idx file called OrdDate.idx. The following line of code deletes the .idx file:

    Copy Code
    DELETE FILE OrdDate.idx

    For more information, see DELETE FILE Command.

You can also use your computer operating system to delete the file.

See Also

Other Resources

Working with Table Indexes


Working with Validation Rules

Visual FoxPro 9.0
Working with Validation Rules

You can specify validation rules to control the data entered in database tables.

In This Section

Field and Record Validation Rules

Introduces aspects and considerations of working with validation rules.
How to: Create Field Validation Rules

Describes how to create validation rules for data in fields.
How to: Create Record Validation Rules

Describes how to create validation rules for data in records.
How to: Remove Validation Rules

Describes how to delete validation rules.

Related Sections

Enforcing Business Rules

Provides an overview about how to enforce business rules by using validation rules, preventing duplicate values in fields, and maintaining relationships between tables.
Working with Fields

Introduces creating and working with fields in tables.
Working with Tables

Introduces creating and working with tables.


Field and Record Validation Rules

Visual FoxPro 9.0
Field and Record Validation Rules
See Also

Field and record validation rules control how and the type of data that you can enter in database table fields and records. Validation rules provide the following advantages:

  • Provide a way to enforce business rules consistently.

  • Help you write less code.

  • Are enforced for all users of the database table, regardless of the requirements of the application.

When using validation rules, the values entered in fields and records are compared against the rule expressions that you specify. If an entered value does not meet the requirements of the rule expression, the value is rejected.

For example, you might create a rule that compares the value of a postal code field against a separate table containing the postal abbreviation codes for your country or region and rejects any value that does not exist as a valid postal code abbreviation.

Tip:
Avoid creating field or record-level rules that are application-specific. Instead, create and use field and record-level rules to enforce data integrity and business rules that always apply to the data in your database, regardless of how or who accesses the data.

Note:
Validation rules are stored in the database (.dbc) file. Removing or deleting a database table removes and deletes all field and record-level rules associated with that table. However, stored procedures referenced by the removed or deleted validation rules remain.

The following sections contain more information about working with validation rules:

  • Choosing Between Field and Record Validation Rules

  • Checking Field and Record Validation Rules

Choosing Between Field and Record Validation Rules

You can use a field-level validation rule when the following apply:

  • You want to control the type of information a user can enter in a field.

  • You can validate the data in a field independently from any other entry in the record.

  • You want to compare values entered in a field against the values in another table.

For example, you can use a field-level validation rule to make sure that a user does not enter a negative number in a field that requires a positive value.

You use record-level validation rules when the following apply:

  • You want to control the type of information a user can enter in a record.

  • You want to compare the values of two or more fields in the same record to make sure comply with business rules for the database.

For example, you can use a record-level validation rule to make sure that the value in a field is always greater than another in the same record.

Checking Field and Record Validation Rules

Field and record validation rules are active even when data is buffered. Generally, field validation rules are checked when the field's value changes; record validation rules are checked when the record value changes.

Note:
If a field or record value has not changed, validation rules are not checked. When no values have changed, you can navigate fields and fields without validating data.

The following table describes more specifically when Visual FoxPro checks field validation rules depending on the method of data entry.

Changing values using | Window or command | Field validation rule is checked
User interface | Browse window Form Other window | When moving off the field.
Commands that do not specify fields | APPEND Command APPEND GENERAL Command APPEND MEMO Command BROWSE Command CHANGE Command DELETE Command EDIT Command GATHER Command | When changing the field value. The rule is checked in the field order specified in the command.
Commands that do not specify fields | APPEND Command with BLANK clauseINSERT - SQL Command | When appending or inserting the record.
Commands that specify fields | UPDATE - SQL Command REPLACE Command | In the field order specified in the command.

In contrast, Visual FoxPro checks record validation rules whenever the record pointer moves off the record, regardless of the method you use to enter data. In addition, in a browse window, the record validation rule is checked if you modify a record but do not move the record pointer, and then close the browse window. Visual FoxPro generates any error messages that occur, and then closes the browse window.

Caution:
Do not include any commands or functions in your validation rules that attempt to move the record pointer in the current work area where validation rules are checked. For example, including commands or functions such as SEEK, LOCATE, SKIP, APPEND, APPEND BLANK, INSERT, or AVERAGE, COUNT, BROWSE, and REPLACE FOR in validation rules might check them recursively, creating an error condition.

When a record validation rule causes an error during a running application, you need to include error-handling code. Typically, this code does not permit the user to leave a form or change the active environment until the the user corrects the error or cancels changes to the record.

See Also

Other Resources

How to: Create Field Validation Rules
How to: Create Record Validation Rules
Working with Validation Rules


How to: Create Field Validation Rules

Visual FoxPro 9.0
How to: Create Field Validation Rules
See Also

You can create field validation rules to control the type of information a user can enter in database table fields. You can also specify a custom message to display for invalid values instead of the default error message.

Note:
Make sure that field validation rules do not conflict semantically with record validation rules. Visual FoxPro does not compare the field-level and record-level expressions for consistency.

To create a field validation rule

  1. Open the database containing the table.

  2. Open the table in the Table Designer.

  3. In the Table Designer, select the field you want.

  4. In the Rule box from the Field validation area, type the validation expression you want. To build an expression, click the ellipsis (...) button.

  5. When you are finished, click OK.

  6. To display a custom error message, in the Message box, type the custom error message or expression you want to display for invalid values. To build an expression, click the ellipsis (...) button.

    Note:
    Make sure to enclose message text in quotation marks ("").

  7. When you are finished, click OK.

For more information, see Fields Tab, Table Designer.

To create a field validation rule programmatically

  • When creating the table using the SQL CREATE TABLE command, include the CHECK clause. To include custom error message text, include the ERROR clause.

    -OR-

  • To edit an existing table, open the table with the USE command and then use the SQL ALTER TABLE command with the CHECK or SET CHECK clause. To include custom error message text, include the ERROR clause.

    -OR-

  • Use the DBSETPROP( ) function to set the RuleExpression and RuleText field properties.

For more information, see CREATE TABLE - SQL Command, ALTER TABLE - SQL Command, and DBSETPROP( ) Function.

For example, suppose you want the number of items entered for a record in an order items table to be equal to or greater than 1. The following code adds a field validation rule requiring that numbers entered in the Quantity field are equal to or greater than 1 using the SET CHECK clause. The ERROR clause specifies a custom error message:

Copy Code
ALTER TABLE OrdItems ALTER COLUMN Quantity SET CHECK Quantity >= 1 ;
   ERROR "Quantity must be a value greater than or equal to 1."

When the user attempts to enter a value less than 1, Visual FoxPro displays the custom error message and rejects the value.

See Also

Other Resources

Field and Record Validation Rules
How to: Create Record Validation Rules
How to: Open Databases
How to: Edit Table Structure
How to: Remove Validation Rules
Working with Fields
Working with Tables
Working with Validation Rules


How to: Create Record Validation Rules

Visual FoxPro 9.0
How to: Create Record Validation Rules
See Also

You use record-level validation rules when you want to control the type of information a user can enter in a database table record. You can also specify a custom message to display for invalid values instead of the default error message.

Note:
Make sure that field validation rules do not conflict semantically with record validation rules. Visual FoxPro does not compare the field-level and record-level expressions for consistency.

To create a record validation rule

  1. Open the database containing the table.

  2. Open the table in the Table Designer.

  3. In the Table Designer, click the Table tab.

  4. In the Rule box from the Record validation area, type the validation expression you want. To build an expression, click the ellipsis (...) button.

  5. When you are finished, click OK.

  6. To display a custom error message, in the Message box, type the custom error message or expression you want to display for invalid values. To build an expression, click the ellipsis (...) button.

    Note:
    Make sure to enclose message text in quotation marks ("").

  7. When you are finished, click OK.

For more information, see Table Tab, Table Designer.

To create a record validation rule programmatically

  • When creating the table using the SQL CREATE TABLE command, include the CHECK clause. To include custom error message text, include the ERROR clause.

    -OR-

  • To edit an existing table, open the table with the USE command and then use the SQL ALTER TABLE command with the CHECK or SET CHECK clause. To include custom error message text, include the ERROR clause.

For more information, see CREATE TABLE - SQL Command and ALTER TABLE - SQL Command.

Note:
You cannot use the DBSETPROP( ) function to set record validation rules and error text; however, you can retrieve them using the DBGETPROP( ) function and the RuleExpression and RuleText table properties. For more information, see DBSETPROP( ) Function.

For example, suppose you want to make sure that new employees in an employee table are equal to or greater than 18 years old. The following code adds a record validation rule requiring that the hire date in the Hire_Date column is equal to or greater than the birth date plus 18 years using the SET CHECK clause. The ERROR clause specifies a custom error message:

Copy Code
ALTER TABLE Employee SET CHECK Hire_Date >= birth_date + (18 * 365.25) ;
   ERROR "Employees must be 18 years or older by date of hire."

If the user enters an employee record with an invalid date, Visual FoxPro displays the custom error message you defined and does not update the record.

See Also

Other Resources

Field and Record Validation Rules
How to: Create Field Validation Rules
How to: Open Databases
How to: Edit Table Structure
How to: Remove Validation Rules
Working with Fields
Working with Tables
Working with Validation Rules


How to: Remove Validation Rules

Visual FoxPro 9.0
How to: Remove Validation Rules
See Also

If you no longer want to use a field or record validation rule, you can remove it.

Note:
Validation rules are stored in the database (.dbc) file. Removing or deleting a database table removes and deletes all field and record validation rules associated with that table. However, stored procedures referenced by the removed or deleted validation rules remain.

To remove a field validation rule

  1. Open the database containing the table.

  2. Open the table in the Table Designer.

  3. In the Table Designer, select the field you want.

  4. In the Rule box from the Field validation area, delete the validation expression.

  5. In the Message box, delete the custom error message or expression.

  6. When you are finished, click OK.

For more information, see Fields Tab, Table Designer.

To remove a record validation rule

  1. Open the database containing the table.

  2. Open the table in the Table Designer.

  3. In the Table Designer, click the Table tab.

  4. In the Rule box from the Record validation area, delete the validation expression.

  5. In the Message box, delete the custom error message or expression.

  6. When you are finished, click OK.

For more information, see Table Tab, Table Designer.

To remove a validation rule programmatically

  1. Open the table with the USE command.

  2. Use the SQL ALTER TABLE command with the DROP CHECK clause.

For more information, see ALTER TABLE - SQL Command.

See Also

Other Resources

How to: Open Databases
How to: Edit Table Structure
Working with Fields
Working with Tables
Working with Validation Rules


Trigger Usage

Visual FoxPro 9.0
Trigger Usage

A trigger is an expression that is bound to a database table and is invoked when any of the table records are modified by one of the data modification commands specified in the trigger. You can use triggers to perform operations that a database application requires when modifying data. The following list contains example tasks that you can perform with triggers:

  • Log database modifications.

  • Enforce referential integrity.

  • Create an automatic reorder for a product that is low on stock.

Triggers are created and stored as properties for a specific table. If you remove a table from a database, the triggers associated with that table are deleted. Triggers fire after all other checks, such as validation rules, primary key enforcement, and null value enforcement, are performed. However, unlike field- and record-level validation rules, triggers do not fire on buffered data.

In This Section

How to: Create Triggers

Describes how to create triggers.
How to: Modify Triggers

Describes how to edit triggers.
How to: Remove or Delete Triggers

Describes how to remove and delete triggers.

Related Sections

Enforcing Business Rules

Provides an overview about how to enforce business rules by using validation rules, preventing duplicate values in fields, and maintaining relationships between tables.
Working with Tables

Introduces creating and working with tables.


How to: Create Triggers

Visual FoxPro 9.0
How to: Create Triggers
See Also

You can create triggers using the Table Designer or the CREATE TRIGGER command. For each table, you can create one trigger for each of the three events: INSERT, UPDATE, and DELETE. A table can have a maximum of three triggers at any one time.

To create a trigger

  • In the Table tab of the Table Designer, enter the trigger expression or the name of a stored procedure containing the trigger expression in the Insert trigger, Update trigger, or Delete trigger box.

    -or-

  • Use the CREATE TRIGGER Command.

For example, perhaps each time Tasmanian Traders sells an item, they want to compare the remaining Units_in_stock against the Reorder_level and be notified if they need to reorder that item. You can create an Update trigger on the products table to accomplish this. Every time a product is sold, the Update trigger will fire and the Units_in_stock fieldwill be updated to reflect the remaining items in stock.

To create the trigger, you can specify updProductsTrigger( ) as your Update trigger for the products table. You can add a field to products, named reorder_amount, which stores the amount you want to order each time you reorder the item, and create a reorder table with the fields: product_id and reorder_amount. You can then add this code to your stored procedure:

Copy Code
PROCEDURE updProductsTrigger
   IF (units_in_stock+units_on_order) <= reorder_level
   INSERT INTO Reorder VALUES(Products.product_id, ;
    Products.reorder_amount)
   ENDIF
ENDPROC

You can create similar triggers for an insert or delete event by using the FOR INSERT or FOR DELETE clause, respectively, instead of the FOR UPDATE clause. If you attempt to create a trigger that already exists for a particular event and table while SET SAFETY Command is on, Visual FoxPro prompts you to confirm overwriting the existing trigger.

Visual FoxPro includes the Referential Integrity Builder to generate triggers and stored procedures that enforce Referential Integrity (RI) rules for your database. For more information on using the RI Builder, see Referential Integrity Builder and How to: Build Referential Integrity Between Tables.

See Also

Other Resources

How to: Edit Table Structure
Trigger Usage
Working with Tables
How to: Modify Triggers


How to: Modify Triggers (Visual FoxPro)

Visual FoxPro 9.0
How to: Modify Triggers (Visual FoxPro)
See Also

You can modify triggers through the Table Designer or through the language.

To modify a trigger

  • In the Table tab of the Table Designer, enter the new trigger expression in the Insert trigger, Update trigger, or Delete trigger box.

    -or-

  • Issue the SET SAFETY OFF command, and then use the CREATE TRIGGER Command.

When you modify a trigger by first issuing the SET SAFETY OFF command and then re-creating the trigger, the old trigger expression is automatically deleted and replaced by the re-created trigger expression.

See Also

Other Resources

How to: Remove or Delete Triggers
How to: Edit Table Structure
Working with Tables
Trigger Usage


How to: Remove or Delete Triggers

Visual FoxPro 9.0
How to: Remove or Delete Triggers
See Also

You can remove a trigger from a database table through the interface or with the DELETE TRIGGER command.

To delete a trigger

  • In the Table tab of the Table Designer, select the trigger expression in the Insert trigger, Update trigger, or Delete trigger box and delete it.

    -or-

  • Use the DELETE TRIGGER Command.

The following example removes the update trigger for the customer table:

Copy Code
DELETE TRIGGER ON customer FOR UPDATE

If you remove or delete a table from a database, all triggers bound to that table are deleted from the database. However, stored procedures referenced by the removed or deleted trigger are not deleted.

See Also

Other Resources

How to: Edit Table Structure
Working with Tables
Trigger Usage


Enforcing Business Rules

Visual FoxPro 9.0
Enforcing Business Rules
See Also

When you have or use business rules for entering data, there are several ways you can enforce those rules in your database:

  • Create and use validation rules to control data entered in database table fields and records. For more information, see Working with Validation Rules.

  • Prevent duplicate values in fields by using candidate or primary indexes. For more information, see Preventing Duplicate Values in Fields.

  • Maintain relationships between tables by establishing referential integrity rules using triggers and stored procedures that are invoked when records in database tables are modified. For more information, see How to: Build Referential Integrity Between Tables.

When developing constraints for your database, consider the level at which you want to enforce a business rule and the action that activates the constraint. Constraints activate in the order that they appear in a table. The first violation of any constraint stops the operation.

The following table summarizes the order in which Visual FoxPro enforces data validation constraints, the level at which they apply, and when those constraints are activated.

Level | Enforcement mechanism | Activated when
Form | VALID clause | Moving the record pointer off the record.
Table | Triggers | Changing values in tables with an INSERT, UPDATE, or DELETE operation.
Field or column | NULL validation | Moving out of a field or column in a browse window or changing the field value with an INSERT or REPLACE operation.
Field or column | Field-level validation rules | Moving out of a field or column in a browse window or changing the field value with an INSERT or REPLACE operation.
Record | Record-level validation rules | Updating a record.
Record | Candidate/primary index | Updating a record.

See Also

Other Resources

Working with Data


Working with Queries

Visual FoxPro 9.0
Working with Queries

When your application includes tables, you can select and display data from those tables using queries. You can use queries for various tasks:

  • Answering a question quickly. For example, you can find out information such as:

    • Customer name and address associated with a particular ID number

    • Number of outstanding orders

    • Number of customers with overdue balances

    • Region or salesperson with the best sales record

  • Viewing a relevant subset of your data

  • Organizing and generating data for a report. You can also run reports separately without using a query.

You can create queries from tables, define and organize query results, collect user input using queries, and customize queries. You can also direct queries to different destinations so that you can use them in other parts of your application.

In This Section

How to: Create Queries

Describes the different methods you can use to create queries.
How to: Query Multiple Tables and Views

Describes how to create queries from multiple tables.
How to: Control Record Selection with Joins

Describes how to use join conditions between tables to expand or narrow results.
How to: Define Query Results

Describes how you can define the data appearing in the results of a query.
How to: Organize Query Results

Describes how you can organize the data results appearing in the query output.
How to: Customize Queries

Describes ways to customize queries in the Query Designer, such as narrowing or expanding queries, eliminating duplicate queries, extracting percentage of top records, and adding expressions for filtering.
How to: Customize Queries Using SQL SELECT Statements

Describes how to customize queries by viewing and editing the SQL SELECT statement generated for views by the View Designer.
How to: Collect User Input with Queries

Describes how you can collect user input from a form to use in SQL SELECT statements for queries.
How to: Run Queries

Describes how to run queries after they are defined.
Setting Query Output Destinations

Provides procedures for sending query output to tables and arrays, reports, windows, and form controls.

Related Sections

Working with Data

Provides an overview and information about using data in your applications, for example, analyzing data requirements and designing your application components to meet those requirements.
Working with Tables

Discusses how to structure your tables to meet your application requirements. Data type and index choices are essential to the success of your application.
Working with Records

Explains how to store data in the table by adding new records and that you can change and delete existing records through the interface or by using commands.
Working with Views

Explains how to use views to create a customized updateable data set for your application.


How to: Create Queries (Visual FoxPro)

Visual FoxPro 9.0
How to: Create Queries (Visual FoxPro)
See Also

The basic process for creating a query is generally the same regardless of the method you use. The following general process describes creating a query from a single table. You can also create queries from multiple tables.

To create a query

  1. Determine the kind of information you need to find and the table or view from which you need to retrieve the data.

  2. Select the table or view and the corresponding fields that you want data from.

  3. Specify any additional criteria for extracting records from the tables or views.

  4. Generate the query and direct the results to an output source.

When you have created a query you want to keep, you can save it by giving it a name. Queries are stored as files with the .qpr extension.

You can use different methods to create queries:

  • Use the Query Wizard to guide you through the steps of creating queries.

  • Use the Query Designer to create and customize queries quickly.

  • Use SQL SELECT statements, which offer more powerful and flexible ways to generate queries using code.

Creating Queries Using the Query Wizard

If you want help with creating queries, use the Query Wizard. The wizard prompts you to select the tables or views that you want information from and creates a query based on your answers to a series of questions. For more information about the wizard, press the F1 key for Help while you are using the wizard or see Query Wizard.

To create a query using the Query Wizard

  1. Open a free table, or in Project Manager, open a database or a database table.

  2. On the Tools menu, point to Wizards, and click Query.

  3. Select Query Wizard and click OK.

  4. Follow the instructions on the wizard screens.

You can also begin creating a query in the Query Wizard, save the query, and then use the Query Designer to modify it.

Creating Queries Using the Query Designer

If you do not need help with creating your query, you can use the Query Designer. The Query Designer provides a way for you to search for records that meet specified criteria for retrieving information stored in tables and views. You can also organize and group the records as needed and create reports, tables, and graphs based on the results.

To open the Query Designer

  1. On the File menu, click New.

  2. In the New Dialog box, click Query, then New File.

    The Query Designer opens.

For more information, see Query and View Designers.

Selecting Tables for Queries

If you are creating queries from free tables or views, you can select the tables or views after starting the Query Designer. However, if you want to select tables or views from a database, open the database before starting the Query Designer. If your tables, databases, or views are in a project, open the Project Manager before starting the Query Designer. For more information about using multiple tables and views, see How to: Query Multiple Tables and Views.

When adding more than one table to your query, you can specify join conditions to modify the scope of the results returned. Visual FoxPro displays the Join Condition dialog box for you to specify the join condition for each additional table you add to your query. For more information specifying join conditions, see How to: Control Record Selection with Joins, Join Conditions for Tables, Queries, and Views, and Join Condition Dialog Box.

To select a free table for a query

  1. From the File menu, click New.

  2. In the New dialog box, click Query, and then New File.

  3. In the Add Table or View dialog box, click Other.

  4. Select a table, and click Close.

To select a database table for a query

  1. Open either a stand-alone database, or in Project Manager, select a database.

  2. On the File menu, click New.

  3. In the New dialog box, click Query, and then New File.

  4. In the Add Table or View dialog box, select a database table, and click Add.

  5. When you are finished selecting tables, choose Close.

    The tables appear on the Query Designer surface.

You can also create queries by using the CREATE QUERY command to open the Query Designer. For more information, see CREATE QUERY Command.

Instead of using the automatically generated alias when you add a table or view, you can specify an alias for each table you use by typing it in the Alias box that appears in the Add Table or View dialog box.

Removing and Adding Other Tables

You can remove tables from and add other tables to your query.

To remove a table from and add another table to a query

  1. In the Query Designer, click the table you want to remove.

  2. On the Query Designer toolbar, click Remove Table to remove the table and then Add Table to select another table or view you want.

Building Queries in the Query Designer

After selecting the tables you want to use for your query, you can begin building queries in the Query Designer. You can also select tables and create a query in the Query Wizard, save the query, and then use the Query Designer to modify the query.

To build a query using the Query Designer

  1. In the Query Designer, click the Fields tab.

  2. In the Available fields list, select a field, and click Add.

    To select multiple fields, press the SHIFT key while selecting fields, and then click Add.

  3. To specify the order in which fields appear in output, click and hold the vertical double arrow button appearing to the left of the field you want to move in the Selected fields list. Move your mouse to position the field the way you want.

You can customize or define your query further in the Query Designer by performing the following tasks:

  • Change the join condition of the selected tables in the Join tab.

  • Filter results by field in the Filter tab.

  • Organize results by field in the Order By tab.

  • Group results by field in the Group By tab.

  • Select a different type of output in the Miscellaneous tab.

For more information about defining your query, see How to: Define Query Results. For more information about customizing your query and using the tabs in the Query Designer, see How to: Customize Queries and Query and View Designers. For more information about organizing the results of your query, see How to: Organize Query Results.

Adding Comments to Queries

You can also add comments or notes about the query to describe its purpose.

To add a comment to a query

  1. Click the Query Designer surface to bring it into the foreground.

  2. On the Query menu, click Comments.

  3. In the Comment box, type comments you want to make about the query.

Comments that you add to a query are stored with the SQL SELECT statement generated by the Query Designer. You can view comments by clicking the View SQL button on the Query Designer toolbar to open the SQL window. Comments that you insert using the Comment box appear above the SQL SELECT statement and are preceded by an asterisk (*).

Note:
When you modify comments using the Comment box, changes are made only to the first comment and do not affect any other comments you might manually insert into the SQL window.

For more information about the SQL SELECT statement generated by a query, see SELECT - SQL Command. For more information about customizing queries in the Query Designer and using the SQL SELECT command in the SQL window, see How to: Customize Queries and How to: Customize Queries Using SQL SELECT Statements.

See Also

Other Resources

Working with Queries
How to: Define Query Results
How to: Query Multiple Tables and Views
How to: Organize Query Results
How to: Run Queries
Query and View Designers
How to: Update Data in a View


How to: Query Multiple Tables and Views

Visual FoxPro 9.0
How to: Query Multiple Tables and Views
See Also

When you need access to information stored in two or more tables, add all the needed tables to the query or view and join them on common fields. You can then search the records in all the tables for the information you need. You can use any combination of database tables, free tables, and local or remote views in your queries.

The term "view" can refer to either an input source or an object you create in the View Designer; therefore, the term "table" is used for both tables and views used as input sources.

Adding Views and Tables to a Query

When you add tables or views to your query, Visual FoxPro suggests a possible join between the tables or views, based on matching field names.

For example, if you add the Customer table in the Visual FoxPro ...\Samples\Data directory to the Query Designer, and then add the Orders table, Visual FoxPro suggests a join between the tables based on the matching fields Customer.cust_id and Orders.cust_id.

If you are using a database that contains persistent relationships defined between the views or tables within it, Visual FoxPro uses the existing relationships as default joins.

If you want to add database tables or views to your query, you may need to open the appropriate database to make them available.

To add a table or view to a query

  1. In the Query Designer toolbar, choose Add Table.

  2. In the Add Table or View dialog box, select the database you want to use, choose Tables or Views, select the table or view you want to add, and choose OK.

    -or-

    If you want to add a table that is not part of the database, choose Other, locate the table in the Open dialog box, and choose OK.

  3. In the Join Condition dialog box, verify the suggested join and choose OK.

    If Visual FoxPro cannot suggest a likely match between fields, select the matching fields in the Join Condition dialog box yourself.

See Also

Other Resources

Add Table or View dialog box
Join Condition dialog box
How to: Control Record Selection with Joins
How to: Customize Queries
How to: Create Queries
How to: Run Queries


How to: Control Record Selection with Joins

Visual FoxPro 9.0
How to: Control Record Selection with Joins
See Also

When you have multiple tables in a query or view, you can control which records the query or view retrieves by adding or altering join conditions between the tables. Working with joins is similar for both queries and views; therefore, the procedures use queries as examples. Although you can run a query or view without joins, the results usually have little practical value and might require large amounts of time to process.

For more information about join conditions, see Join Conditions for Tables, Queries, and Views.

Adding Join Conditions

Joins usually appear automatically when you add tables to the query or view. However, if the field names of the related fields do not match, you might need to specify the join you want to have for the table you add using the Join Condition dialog box in the Query and View designers.

The process for adding a join is similar between the Query and View designers. The following procedure describes adding a join in the Query Designer.

To create a join between tables using the Query Designer

  1. Create or open a query.

  2. Add a table to the query so that you have two or more tables.

  3. On the Query Designer toolbar, click Add Join.

  4. In the Join Condition dialog box, select the related field names in the two tables.

    Note:
    Set joins for columns only if they have the same size and data type.

  5. Select a join type and click OK.

You can also add joins for tables that already appear on the Query or View designer surface by clicking and dragging the mouse between the fields in the tables or choosing the Add Join button on the Query or View designer toolbar to display the Join Condition dialog box. You can also create a join type using the using the FROM clause in the SQL SELECT statement.

For more information about the Join Condition dialog box, see Join Condition Dialog Box. For more information about SQL SELECT statements generated by the Query and View designers, see How to: Create Queries, How to: View and Edit SQL Statements for Views, and SELECT - SQL Command.

For example, suppose you wanted to retrieve order information, including information about the customer who placed the order. The following example creates a view using two tables, Customers and Orders. Both the Customer and Orders tables have a customer ID field. The tables are related based on an inner join, which specifies that the results include only those rows from the Customer table that match one or more records from the Orders table.

The following code opens the sample database called TestData.dbc, creates a view using the CREATE SQL VIEW command as described in the example, and uses the FROM clause to specify the join condition as described:

Copy Code
OPEN DATABASE testdata
CREATE SQL VIEW cust_orders_view AS ;
   SELECT * FROM testdata!customer ;
      INNER JOIN testdata!orders ;
      ON customer.cust_id = orders.cust_id

Modifying Join Conditions

You can modify existing joins in the following ways:

  • Choose a different join type to modify the scope of the records returned.

  • Select different fields in the table for the join.

  • Change the comparison operator.

  • Change the order of joins

The process for modifying a join is similar for both the Query and View designers. The following procedure describes modifying a join in the Query Designer.

To modify a join

  1. Open a query containing the tables with joins that you want to modify.

  2. In the Join tab of the Query Designer, select the join, and change the join conditions as needed.

You can also modify join types using FROM clause in the SQL SELECT command. For more information about SQL SELECT statements generated by the Query and View Designers, see How to: Create Queries, How to: View and Edit SQL Statements for Views, and SELECT - SQL Command.

Removing Join Conditions

You can remove joins from between tables. The process for removing a join is similar for both the Query and View designers. The following procedure describes removing a join in the Query Designer.

To delete a join

  1. Open the query that contains the tables with the join you want to remove.

  2. In the Join tab of the Query Designer, select the join condition, and click Remove.

You can also select the join line that you want to remove between two tables on the Query or View Designer surface. On the Query menu, click Remove Join Condition.

See Also

Other Resources

Working with Queries
How to: Create Queries
How to: Query Multiple Tables and Views
How to: Customize Queries
How to: Run Queries
Logical Operators
Join Condition Dialog Box


How to: Define Query Results

Visual FoxPro 9.0
How to: Define Query Results
See Also

After you have opened the Query Designer and selected the table or view that contains the information you want, you can define your results. At a minimum, you need to select the fields you want. You can also define your results by setting the order the selected fields appear and setting filters to select which records appear.

Selecting Fields You Want

Before you can run a query, you must select some fields to include in the results. In some cases, you might want to use all the fields from the table or view. At other times, you might want to focus the query on a few selected fields, such as fields you want to include in a report.

Be sure to include any fields you might want to use to sort or group the results of your query. When you select the fields, you can also set the order they appear in your output.

Use the Fields tab in the lower pane of the Query Designer to select the fields you want to include in the results of your query.

To add a field to the query output

  • Select the name of the field and choose Add.

    -or-

  • Drag the field name to the Selected fields box.

Selecting All Fields for Output

You can select all of the fields by name or use the asterisk wild card. If you select the fields by name, the exact names of the fields are included in the query. If you run the query after adding fields to the table, the new fields are not included in the results.

If you use the wild card, the asterisk is included in the query and includes all fields that are in the table at the time of the query. If the table structure has changed since the query was created, the new fields also appear in the query results.

To add all available fields to a query at once

  • Choose Add All to add fields by name.

    -or-

  • Drag the asterisk at the top of the table into the Selected fields box.

Displaying an Alias for a Field

You can make your query results easier to read and understand by adding a descriptive caption to a results field. For example, you might want to display the word "SumMaxOrd" at the top of the results column instead of the field name or expression, SUM(MaxOrdAmount).

To add an alias for a field

  1. In the Functions and expressions box, type the field name, and then type AS and the alias, as in this example:

    Copy Code
    SUM(maxorderamt) AS SumMaxOrd

  2. Choose Add to place the field with the alias in the Selected fields box.

Setting the Order for Output Fields

The order that fields appear in the Fields tab determines the order of the columns of information in your query output.

To change the column order of the query output

  • Drag the mover box, located to the left of a field name, up or down.

If you want to change the order that rows of information will be sorted, use the Order By tab instead.

Selecting the Records You Want

Selecting the records you want to find is the key step that determines the results of your query. With the Filter tab in the Query Designer, you can formulate the WHERE clause of a select statement to tell Visual FoxPro which records to search for and retrieve.

You may want to find a specific subset of data to include in a report or other output: for example, all customers with outstanding balances, all customers in a specific region or postal code, and so on. To see only the records you want, enter a value or range of values to compare the records against.

In Visual FoxPro, you use the Filter tab to specify which field you want to use for selecting records, choose a comparison criterion, and enter an example of the value you want the field to be compared to.

To specify a filter

  1. From the Field Name list, choose a field you want to use as the basis for selecting records.

    Note:
    You can't use General or Memo fields in a filter.

  2. From the Criteria list, choose the type of comparison to use.

  3. Enter the comparison criterion in the Example box.

    • Use quotation marks only if the string is the same as the name of a field in a table in the query; otherwise, do not enclose character strings in quotation marks.

    • If you use dates, do not enclose them in braces.

    • Place a period before and after a logical literal (.T.).

    • If you enter a field name from a table in the query, Visual FoxPro will recognize it as a field.

  4. If you want capitalization to be ignored in searches on character data, select the Case button.

If you want to reverse the meaning of a logical operator, select the Not button. For example, if you want to find customers in all regions except Washington, use the selection expression in the following example:

Copy Code
Customer.region Not Like WA

To further tune your search, you can add more filters in the Filter tab. For more information, see "Fine-Tuning Your Search" in How to: Customize Queries.

If you are using more than one table or view in your query, you can expand the records you select by the join type you choose.

Selecting a Number or Percentage of Records

If you only need a certain number or percentage of records from the result set that your query returns, you can use the Top options on the Miscellaneous tab in the Query Designer or View Designer, or you can add a TOP clause to your SQL SELECT statement. You can provide a number from 1 to 32,767 or a percentage from 0.01 to 99.99 in a TOP clause. Visual FoxPro sorts records first and then extracts the top number or percent of records.

To limit the number of records to retrieve

  1. In the Query Designer, select the Miscellaneous tab.

  2. In the Top area, clear the All box to make other options in the Top area available.

  3. Choose one of the following:

    • In the Number of records box, type or select the maximum number of records you want to retrieve.

    -OR-

    • Click Percent to change the Number of records box to Percentage so you can type or select the maximum percentage of records you want to retrieve.

For example, if you want to select the top 10 customers with the highest order amounts, you can specify a GROUP BY on CUST_ID to show one aggregate record for each customer and sort by ORDER_AMT in the ORDER BY clause. To get a true TOP 10, you need to specify a descending sort on the ORDER_AMT so that the records with the highest order amounts appear first in the results. If you use an ascending sort, the result records are ordered from the least order amount to the most. The top records you select from the result set would actually have the lowest values.

Copy Code
SELECT TOP 10 *;
FROM testdata!customer INNER JOIN testdata!orders ;
ON Customer.cust_id = Orders.cust_id;
GROUP BY Customer.cust_id;
ORDER BY Orders.order_amt DESC

See Also

Other Resources

Working with Queries
How to: Create Queries
How to: Organize Query Results
Fields Tab, Query and View Designers
How to: Query Multiple Tables and Views
How to: Update Data in a View


How to: Organize Query Results

Visual FoxPro 9.0
How to: Organize Query Results
See Also

With the output of your query defined, you can now organize the records that appear in your results by ordering and grouping on the output fields. If you want, you can also filter the groups that appear in your results.

Ordering Query Results

Ordering determines the order in which records or rows will be sorted when they appear in the output of your query. For example, you could sort records by State and then by City, or sort them in ascending order based on the outstanding account balance.

Use the Order By tab to set the sort order for your query. The sort order determines the order in which rows or records will appear in your query output.

First select the fields you want to use from the Selected Fields box and move them to the Ordering Criteria box. Then arrange the fields in the order you want them to appear in the query results.

To set ordering criteria

  1. In the Selected fields box, select a field name.

  2. Choose Add.

To remove ordering criteria

  1. Select one or more fields that you want to remove.

  2. Choose Remove.

The order in which fields appear in the Ordering criteria box determines the order of importance when the query results are sorted. The first field determines the primary sort order.

For example, if the first field in the Ordering criteria box is Customer.region and the second field in the Ordering criteria box is Customer.city, the results will be ordered by Customer.region. If more than one record in the customer table has the same region field value, these records are additionally ordered by Customer.city.

To adjust the importance of a sort order field, use the button to the left of the field to drag the field to the desired location in the Ordering criteria box.

You can sort in ascending or descending order by setting the buttons in the Order options area. Each order field appears in the Output fields box on the Filter tab with an up arrow or down arrow next to it, indicating whether the sort on that field is to be made in ascending or descending order.

Grouping Query Results

Grouping consolidates or gathers similar records into one record so you can perform calculations based on groups of records. For example, you might want to find the sum of all orders to a specific region. Instead of looking at all the records individually, you can group all the records from the same region into one record, and get the sum of all the orders from that region. To control how records are grouped, use the Group By tab in the Query Designer.

Grouping is most useful when used in conjunction with an aggregate function, such as SUM, COUNT, AVG, and so on.

For example, suppose you want to see the total dollar amount of orders for each customer ID number in your orders table. You need to group all the order records for a given customer ID into one record, and find the sum of the order amounts.

You first use the Fields tab to add the expression SUM(Orders.order_net) to the output of your query, then use the Group By tab to group the results by customer ID number. The results show total net orders for each customer:

To set grouping options

  1. In the Fields tab, type the expression in the Functions and expressions box.

    -or-

    Choose the dialog button to use the Expression Builder to enter an expression in the Functions and expressions box.

  2. Choose the Add button to place the expression in the Selected fields box.

  3. In the Group By tab, add the expression to group results by.

You can also set a filter on the grouped results.

Selecting the Groups You Want

To set a filter on grouped or consolidated records rather than on individual records, choose Having on the Group By tab. You can use a field name, an aggregate function on a field name, or another expression in the Field Name box.

Building on the previous example, you could use the query that shows total sales by customer number, then use the Having button to restrict the output to customers having more than $50,000 in net orders:

To set a Having option on a group

  1. In the Group By tab, choose Having.

  2. In the Having dialog box, select a function and field name in the Field Name field.

  3. Choose OK.

See Also

Other Resources

Working with Queries
How to: Define Query Results
How to: Run Queries
How to: Customize Queries
Order By Tab, Query and View Designers
How to: Query Multiple Tables and Views
How to: Update Data in a View
How to: Create Queries


How to: Customize Queries

Visual FoxPro 9.0
How to: Customize Queries
See Also

You can customize your queries further in the Query Designer. You can use filters to expand or narrow the results of your query. You can also add expressions to perform calculations or functions on the data in your fields.

Filtering Records in Queries

You can use filter expressions to narrow or expand the range of records that your query retrieves. For example, suppose you want to retrieve records that meet more than one criterion, for example, you want to retrieve customers from a given state who have outstanding balances greater than $1,000. In this scenario, you want to narrow the range of records your query retrieves. In contrast, suppose you want to retrieve records that meet any criterion, for example, customers from Washington or from California. In this scenario, you want to narrow the range of records your query retrieves.

When you want to create filter expressions that include more than one criterion, use the logical AND operator. When you want to create filter expressions that use any criterion you specify, use the logical OR operator.

You can also combine AND and OR conditions to select specific sets of records. For example, you might want to retrieve records for customers from Washington or California who have maximum order amounts larger than $5,000.

To specify AND or OR conditions for filter expressions

  1. Open the query in the Query Designer.

  2. Click the Filter tab, and select the filter expression you want.

  3. In the Logical column, click AND or OR.

For more information, see Filter Tab, Query and View Designers.

Eliminating Duplicate Records in Queries

You can remove duplicate records from queries. Duplicate records contain fields where all the values in the fields match each other.

To remove duplicate records from queries

  1. Open the query in the Query Designer.

  2. Click the Miscellaneous tab, and then No duplicates.

    Note:
    Selecting No duplicates inserts the DISTINCT keyword preceding the fields in the SQL SELECT statement of the query. For more information, see SELECT - SQL Command.

Retrieving the Top Number or Percentage of Records

You can specify how many or what percentage of records with the highest or lowest values in a particular field you want the query to return. For example, the query can display those records with the 10 highest or lowest values in a specific field or the records with the highest or lowest 10 percent of values in the field.

Using the Top setting on the Miscellaneous tab, you can either set a number or a percentage of records you want to see. To set whether you are choosing the top or bottom, you set the sort order for your query to either descending to see the top or ascending to see the bottom.

To retrieve a number or percentage of top records

  1. In the Order By tab, select the field you want to retrieve top values for, then choose Descending to display the highest values or Ascending to display the lowest values. If you are sorting on additional fields, place them after the top values field in the order by list.

  2. In the Miscellaneous tab, type the number for the percentage or the number of highest or lowest values you want retrieved in the Number of records box. To display a percentage, choose Percent.

  3. If you do not want duplicate records included in the number or percentage, choose No duplicates.

Adding Expressions to Queries

You can create more flexible and powerful queries if you incorporate expressions, either in a filter or as result fields. You can include functions and expressions in the output of your query, using the box at the bottom of the Fields tab. If you want to name the field holding the expression, you can add an alias.

For example, you might want your query results to include the sum of all order amounts with the alias Total:

Copy Code
SUM(orders.order_amt) AS Total

You can type an expression directly into the box or use the Expression Builder on the Fields tab.

To add an expression to your query output

  1. In the Fields tab, type the expression in the Functions and Expressions box.

    -or-

    Choose the dialog button to use the Expression Builder and enter an expression in the Functions and expressions box.

  2. Choose the Add button to place the expression in the Selected fields box.

    Note:
    Null values are ignored in calculations. For more information on null values in expressions, search for "Null Values".

Instead of searching for records that match one or more fields, you can use an expression to combine two fields, or perform a calculation based on a field and search for records that match the combined or calculated field.

You can type expressions directly into the Example box. If you want some help, you can use the Expression Builder, which is available from the dialog button next to the Expressions and Functions box in the Fields tab.

For example, using the Orders table, you might want to check total discounts for a customer by combining order amount and order discount in an expression like the following:

Copy Code
Orders.order_amt * Orders.order_dsc

See Also

Reference

How to: Add a Filter to a Filter Table

Other Resources

Working with Queries
How to: Create Queries
How to: Customize Queries Using SQL SELECT Statements
How to: Run Queries
How to: Organize Query Results
Expression Builder Dialog Box
Fields Tab, Query and View Designers
How to: Query Multiple Tables and Views


How to: Customize Queries Using SQL SELECT Statements

Visual FoxPro 9.0
How to: Customize Queries Using SQL SELECT Statements
See Also

When you create a query in the Query Designer, Visual FoxPro actually uses a SQL SELECT statement to retrieve the information from the fields in the tables. SQL SELECT statements offer you a more powerful way to manipulate your query and provide more control over your query results and where the results are stored. To verify your query or add comments, you can display the SQL SELECT statement in the SQL window and modify it to further customize your query.

When you add queries to your application, you can use SQL SELECT statements to combine a variety of data sources, filter records more precisely, manipulate data, and sort the results. You can use SQL SELECT statements with queries created in the Query Designer, views in the View Designer, or in code for an event or procedure in a program (.prg) file. For more information about where you can use SQL SELECT statements and the SQL SELECT command, see How to: Create Queries and SELECT - SQL Command.

Viewing SQL SELECT Statements Created by Queries

You can view the SQL statement that your query builds in the SQL window at any time while you create your query. By viewing the SQL statement created by the Query Designer, you can make sure the query is properly defined.

To view the SQL SELECT statement created by a query

  1. Create your query using the Query Designer.

  2. On the Query menu, choose View SQL.

The SQL window opens to display the SQL SELECT statement your query created. The first statement is the SQL SELECT statement. For example, you can select all the records from the Customer table in the TasTrade database where the country field contains the value "Canada":

Copy Code
SELECT *;
   FROM tastrade!customer;
   WHERE Customer.country = Canada

The script for the SQL SELECT statement appearing in the SQL window is automatically generated when loading or modifying a query in the Query Designer.

To run the SQL SELECT statement immediately, enter the statement in the Command window. If you want each clause to appear on a separate line in the window, end each line except the last one with a semicolon (;) so that Visual FoxPro processes the command only after the last line.

To include the SELECT statement in code, copy the SQL SELECT statement into a .prg file.

Editing SQL SELECT Statements in the SQL Window

In the SQL window, you can edit the SQL SELECT statement for the query.

Note:
The Query Designer parses only the first SQL SELECT statement in the SQL window, the clauses directly involved with the SELECT statement, and the first comment appearing in the query. The Query Designer disregards all other text.

To edit the SQL SELECT statement in the SQL window

  1. Create or open a query.

  2. Open the SQL window, and edit the SQL SELECT statement.

You can specify an asterisk, table.*, or a comma-delimited list of fields for the SELECT statement in the SQL window. For example, you can specify the SQL statement as SELECT * FROM or SELECT field1, field2, ... FROM. Your preferences are preserved during the loading or generation of the query. You can also include the same field multiple times in the SELECT list.

For more information about using syntax for the SQL SELECT command, see SELECT - SQL Command.

Loading SQL SELECT Statement Changes into the Query Designer

After editing the SQL SELECT statement in the SQL window, you can reload the changes into the Query Designer.

To update the query in the Query Designer

  • Close the SQL window.

You can also update the query by clicking the Query Designer to bring it to the foreground.

If the Query Designer cannot reload your changes after you make changes in the View SQL window, a dialog box appears and asks the following:

"View/Query designer is unable to reload your changes. Would you like to rebuild content from the designer?"

If you select Yes, your changes are discarded in the SQL window, and Visual FoxPro returns you to the Query Designer. If you select No, Visual FoxPro returns you to the SQL window.

To save a statement that cannot be parsed such as a call to a stored procedure, select No and click the Save button on the toolbar. Visual FoxPro saves the query. You can also click the Save button after entering the command in the SQL window to save the query. You do not need to click the Query Designer window, which causes the Query Designer to try to load and parse the query.

See Also

Other Resources

Working with Queries
How to: Customize Queries
How to: Collect User Input with Queries
How to: Run Queries


How to: Collect User Input with Queries

Visual FoxPro 9.0
How to: Collect User Input with Queries
See Also

If you want to collect values that the application user enters from a form, you can create variables to store those values and then use them immediately in the SQL SELECT statement or execute the statement later. For more information about customizing queries using SQL SELECT statements, see How to: Customize Queries Using SQL SELECT Statements and SELECT - SQL COMMAND.

To collect user input values for immediate use

  • In the SQL SELECT statement, include the name of the form or a reference to the form where appropriate.

The following example illustrates how to collect user input values from a form using a shortcut reference that appears in the WHERE clause of the SQL SELECT statement. The shortcut reference, THISFORM, refers to the currently active form. You should substitute control names for ControlName1 and ControlName2.

Copy Code
SELECT * ;
   FROM tastrade!customer ;
   WHERE customer.country = ;
    THISFORM.ControlName1.Value ;
   AND customer.region =
THISFORM.ControlName2.Value ;
   GROUP BY customer.postal_code ;
   ORDER BY customer.postal_code,
customer.company_name

To store user input values from a form when you do not need to use them while the form is active, use variables in code. For example, if you do not want to use references to a control, you can define variables in the code to store the values returned by the control.

To collect user input values for later use

  1. Define the variable you want to use for storing the user input value.

  2. In the SQL SELECT statement, include the name of the variable where appropriate.

The following example illustrates how to collect user input values from a form using the variable, cValue, to store the value returned from a control on the currently active form. The shortcut reference, THISFORM, refers to the currently active form. The variable appears in the WHERE clause of the SQL SELECT statement to select the country that matches cValue.

Copy Code
cValue = THISFORM.ControlName.Value
SELECT * ;
   FROM tastrade!customer ;
   WHERE customer.country = cValue ;
   GROUP BY customer.postal_code ;
   ORDER BY customer.postal_code, ;
     customer.company_name

If you don't define the variable before you run the query, an error message appears stating that the variable couldn't be found. If the variable isn't defined in code, Visual FoxPro assumes that the variable is pre-initialized.

See Also

Other Resources

Working with Queries
How to: Customize Queries Using SQL SELECT Statements
How to: Create Queries
How to: Integrate Queries and Reports


How to: Run Queries (Visual FoxPro)

Visual FoxPro 9.0
How to: Run Queries (Visual FoxPro)
See Also

After you finish building your query, you can execute the query to obtain the results. Visual FoxPro executes the SQL SELECT statement generated by the Query Designer, and sends the results to a browse window. For more information about building queries, see How to: Create Queries.

To run a query from the Query Designer

  1. Open the query in the Query Designer before you run it.

  2. From the Query menu, select Run Query.

Visual FoxPro displays the results of the query in a browse window.

You can also run a query from the Project Manager without opening the query by selecting the name of the query from the Queries node in the file tree view and choosing Run.

See Also

Other Resources

Working with Queries
Setting Query Output Destinations
How to: Customize Queries Using SQL SELECT Statements


Setting Query Output Destinations

Visual FoxPro 9.0
Setting Query Output Destinations

The following table describes destinations for query output.

Output option | Destination
Browse | Display the results of the query in a browse window.
Cursor | Save the results of the query in a temporary read-only table with a name that you specify.
Table | Save the results of the query as a table with a name that you specify.
Screen | Display the results of the query in the main Visual FoxPro window or in the currently active output window.

In This Section

How to: Choose a Query Output Destination

Describes how to specify the destination to send query results to, such as a cursor, table, or screen.
How to: Store Query Results in a Table, Array, or Cursor

Explains how to story your query results in a table, array, or cursor.
How to: Populate Query Results in a Form Control

Describes how to use query results to populate a control on a form, such as a list box control, combo box control, or grid control.
How to: Print Query Results in a Report or Label

Explains how to send query results to an existing report or label.
How to: Display Query Results in a Window

Explains how to display query results in a window, such as the default browse window or the main Visual FoxPro window.

Reference

Browse Window

Display records in an active window.
SELECT - SQL Command

Retrieve data form one or more tables.
Query Destination Dialog Box

Make it possible for you to send the results of your query to seven different outputs. This command is available only for queries.

Related Sections

Working with Queries

Describes how to use queries to select and display data from tables or views.
How to: Organize Query Results

Describes how you can organize the data results appearing in the query output.
How to: Customize Queries

Describes ways to customize queries in the Query Designer, such as narrowing or expanding queries, eliminating duplicate queries, extracting percentage of top records, and adding expressions for filtering.
How to: Query Multiple Tables and Views

Describes how to create queries from multiple tables.
How to: Update Data in a View

Describes how to update data in views and their base tables.
How to: Create Queries

Describes the different methods you can use to create queries.


How to: Choose a Query Output Destination

Visual FoxPro 9.0
How to: Choose a Query Output Destination
See Also

You can send the results of your query to a different destination for output, such as a cursor, table, or screen. By default, Visual FoxPro displays the results of your query in a browse window.

When you choose Query Destination on the Query menu, or choose the Query Destination button on the Query toolbar, the Destination dialog box displays, so you can choose where to send your query results.

To choose a query destination

  1. From the Query menu, choose Query Destination.

  2. In the Query Destination dialog box, choose an output destination, and fill out any additional fields as required.

See Also

Other Resources

How to: Run Queries
SELECT - SQL Command
Working with Queries


How to: Store Query Results in a Table, Array, or Cursor

Visual FoxPro 9.0
How to: Store Query Results in a Table, Array, or Cursor
See Also

You can store your query results in a table, array, or cursor for other uses such as populating forms and printing reports and labels. If you want to store the results only temporarily, send the results to an array or cursor. If you want to store the results permanently, send the results to a table.

To specify a table as the destination

  • Use the INTO clause of the SELECT - SQL statement to specify a destination.

The following example shows an INTO clause for a table:

Copy Code
SELECT * ;
   FROM tastrade!customer ;
   WHERE customer.country = "Canada" ;
   INTO TABLE mytable

To specify an array as the destination

  • Use the INTO clause of the SELECT - SQL statement to specify a destination.

The following example shows an INTO clause for an array:

Copy Code
SELECT * ;
   FROM tastrade!customer ;
   WHERE customer.country = "Canada" ;
   INTO ARRAY aMyArray

To specify a cursor as the destination

  • Use the INTO clause of the SELECT - SQL statement to specify a destination.

The following example shows an INTO clause for a cursor named mycursor:

Copy Code
SELECT * ;
   FROM tastrade!customer ;
   WHERE customer.country = "Canada" ;
   INTO CURSOR mycursor

If you create a table or an array, you can use it like any other table or array in Visual FoxPro. If you create a cursor, you can browse through its contents. The cursor is opened in the lowest available work area. You can access it by using the name you gave it in the SELECT - SQL statement.

The following two procedures describe two common ways to include query results stored in tables and cursors into an application.

See Also

Other Resources

How to: Run Queries
Setting Query Output Destinations
How to: Populate Query Results in a Form Control
How to: Print Query Results in a Report or Label


How to: Populate Query Results in a Form Control

Visual FoxPro 9.0
How to: Populate Query Results in a Form Control
See Also

If you want to display your query results in a form, you can use a table, array, or cursor to populate a grid, list box, or combo box.

To populate a list box or combo box control with a table or cursor

  1. In the Form Designer, modify the form that has the control you want to populate.

  2. Set the RowSourceType property to 3 -SQL Statement.

  3. In the control's RowSource property, enter a SELECT - SQL statement that includes an INTO TABLE or INTO CURSOR clause.

To populate a grid control with a table or cursor

  1. In the Form Designer, modify the form that has the control you want to populate.

  2. In the form's Load event, enter a SELECT - SQL statement that includes an INTO TABLE or INTO CURSOR clause.

  3. Set the grid's RecordSource property to the name of the table or cursor you created in Step 2.

  4. Set the grid's RecordSourceType property to 0Table (for a table) or 1Alias (for a cursor).

See Also

Other Resources

How to: Run Queries
Setting Query Output Destinations
Working with Queries


How to: Print Query Results in a Report or Label

Visual FoxPro 9.0
How to: Print Query Results in a Report or Label
See Also

If your report or label includes groups or you otherwise need to order the data, you can use the various clauses of the SELECT - SQL statement to get the exact results you need.

To send results to an existing report or label

  1. Use the SELECT - SQL statement with a REPORT or LABEL command.

    The following example uses the GROUP BY and ORDER BY clauses as well as the REPORT FORM command:

    Copy Code
    SELECT * ;
   FROM tastrade!customer ;
   WHERE customer.country = "Canada" ;
   GROUP BY customer.region ;
   ORDER BY customer.postal_code, customer.company_name ;
   INTO CURSOR MyCursor
REPORT FORM MYREPORT.FRX

    The following example uses a LABEL FORM command:

    Copy Code
    SELECT * ;
   FROM tastrade!customer ;
   WHERE customer.country = "Canada" ;
   GROUP BY customer.region ;
   ORDER BY customer.postal_code, customer.company_name ;
   INTO CURSOR mycursor
LABEL FORM MYLABEL.LBX

While the SELECT - SQL statement is the most flexible method for populating your report or label, it is not the only method.

See Also

Concepts

Integrating Reports with Applications

Other Resources

How to: Run Queries
Setting Query Output Destinations
SELECT - SQL COMMAND


How to: Display Query Results in a Window

Visual FoxPro 9.0
How to: Display Query Results in a Window
See Also

If you want to display the results of your SELECT - SQL statement, you can send the results to a window. The Browse window is the default destination for query results and you don't need to include a destination clause. You can also send the results to the main Visual FoxPro window or another active window.

To display results in the main Visual FoxPro window

  • Use the TO SCREEN clause of a SELECT - SQL statement.

To display results in another active window

  • Define a window, show it to activate it, and then run a SQL query or other command that displays results in a window.

This code example shows the definition for a temporary window titled "Top Customers" that displays the names of companies with more than $5,000 in total orders for the year.

Displaying query results in a window

Code Comment
Copy Code
frmMyForm=createobj("form")
frmMyForm.Left = 1
frmMyForm.Top = 1
frmMyForm.Width = 130
frmMyForm.Height = 25
frmMyForm.Caption = "Top Customers"
frmMyForm.Show

Create and start a temporary window object.
Copy Code
SELECT customer.company_name,;
  SUM(orders.freight) ;
  FROM tastrade!customer,
  tastrade!orders ;
  WHERE customer.customer_id =
  orders.customer_id ;
  GROUP BY customer.company_name ;
  HAVING SUM(orders.freight) > 5000 ;
  ORDER BY 2 DESC

Enter a SELECT - SQL statement.

See Also

Other Resources

How to: Run Queries
Setting Query Output Destinations
SELECT - SQL Command


Working with Views (Visual FoxPro)

Visual FoxPro 9.0
Working with Views (Visual FoxPro)

When you want a customized and updatable data set for your application, you can create and use views. Views combine the characteristics of tables and queries by providing a way to retrieve records from one or more related tables or views. You can create views using single or multiple tables or views, use views to update data in tables and display data, update views, and move data offline for manipulation.

In This Section

Creating Views

Provides an overview of creating views and describes how to create different types of views.
Managing Views

Describes tasks you can perform to manage views.
Displaying Data in Views

Describes different ways you can display views.
Updating Data in Views

Describes how to update data in views and their base tables.
Manipulating Offline Data

Describes how to move data in views offline
How to: Optimize View Performance

Explains how to set performance and data fetching options.

Related Sections

Working with Data

Provides information to help you create effective applications by analyzing data requirements and designing your application components to meet those needs.
Working with Tables

Discusses how to make sure your tables have the structure that your application requires.
Working with Queries

Describes how to use queries to select and display data from tables or views.


Creating Views

Visual FoxPro 9.0
Creating Views

You can retrieve data from local and remote data sources by creating local and remote views, respectively. Local views use Visual FoxPro SQL syntax to select information from tables or views stored locally on your computer. Remote views use the SQL syntax of the remote data source to retrieve information from tables in the data source, which is typically an ODBC data source. For local views, you can also retrieve data from Visual FoxPro and remote ODBC data sources for local views by adding remote views to local views.

In This Section

View Creation

Describes the basic process for creating views.
How to: Create Local Views

Describes how to create views from data in locally stored tables.
Accessing Remote Data Using Views

Describes the general process for accessing remote data to create remote views.
How to: Define Connections to Remote Data Sources

Describes how to define connections to remote data sources used to create remote views.
How to: Create Remote Views

Describes how to create remote views.
How to: Add Tables to Views

Describes how to access data from other tables by adding them to views.
How to: Select Fields for Views

Describes how to select fields from tables you chose for a view.
How to: Generate Results for Views

Describes how to retrieve the records as defined by the view you created.

Related Sections

Managing Views

Describes tasks you can perform to manage views.
Working with Views

Explains how to use views to create a customized updateable data set for your application.


View Creation

Visual FoxPro 9.0
View Creation
See Also

The basic process for creating a view is generally the same regardless of the method you use and the type of view you create:

  1. Determine the type of view you need to create.

  2. Specify the tables or views you want to retrieve records from and their join conditions.

  3. Select the fields you want to retrieve data from.

  4. Specify any additional criteria for retrieving records from those tables.

  5. Specify whether to update the original tables or base tables used to build the view.

  6. Generate the view to retrieve and view the resulting records.

Similar to queries, when you create a view, Visual FoxPro builds and runs a SQL statement that defines the data set for the view using the view definition you created. You can also set properties for views.

Combining Views

You can combine views when need a subset of data from other views or if you want to combine local and remote data in a single view. A view built from other views is called a top-level view. A view built from local tables and local or remote views is called a multitiered view.

The basic process for combining local and remote data into a single view is described in the following steps:

  1. Create a remote view.

  2. Create a local view and add the remote view you created.

  3. Add any local tables that you want to the local view and join them on a common field.

  4. In the local view, set the fields and filter the records that you want.

  5. Run the view.

  6. Update the view results to update both the local table and the remote view.

  7. Close the local view and then the remote view to update the data on the remote server.

You can also combine local and remote data in a view by creating a new local view based on a local view and a remote view. You can have multiple levels of views between the top-level view and the local or remote base tables. When you use a multitiered view, the views on which the top-level view is based and any Visual FoxPro base tables used in the top-level or intermediate-level views appear in the Data Session window for the database. Remote tables do not appear in the Data Session window.

For example, the following code use the Northwind sample database and creates a local view that combines data from a local employee table and the remote orders table, you can use the following code:

Copy Code
OPEN DATABASE HOME(2) + "Northwind\Northwind"
CREATE SQL VIEW Local_Employee_View AS SELECT * FROM Employees
CREATE SQL VIEW Remote_Orders_View ;
   CONNECTION Remote_01 AS SELECT * FROM Orders
CREATE SQL VIEW Local_Employee_Remote_Orders_View ;
   AS SELECT * FROM Northwind!Local_Employee_View, ;
   Northwind!Remote_Orders_View ;
   WHERE Local_Employee_View.Emp_ID = Remote_Orders_View.Emp_ID

See Also

Other Resources

How to: Create Local Views
Accessing Remote Data Using Views
Creating Views
Working with Views


How to: Create Local Views

Visual FoxPro 9.0
How to: Create Local Views
See Also

Local views use Visual FoxPro SQL syntax to select information from tables or views that are stored locally on your computer. You can create local views in the following ways:

  • Using the Local View Wizard.

    A wizard is the easiest way to start creating a view. You can select fields from tables and views and filter and sort the records in your view. For more information, see Creating Local Views Using a Wizard.

  • Using the View Designer.

    The View Designer makes it possible to select fields from tables or views, specify criteria for retrieving data and join conditions, and filter, sort, and group records to create views or customize existing views. For more information, see Creating Local Views Using the View Designer.

  • Creating views programmatically.

    The CREATE SQL VIEW command makes it possible for you to use SQL SELECT statements so you can create views programmatically. For more information, see Creating Local Views Programmatically.

Regardless of the method you use, the basic process for creating a view is generally the same. For more information, see View Creation.

Note:
When you create or use a view from the Project Manager, the Project Manager opens the database automatically. However, if you subsequently use a view outside the project, you must open the database or make sure the database is in scope before you can use the view.

Creating Local Views Using a Wizard

You can create local views easily using a wizard. The wizard helps you select tables or views and creates a query based on your answers to a series of questions.

Note:
The tables or views you want to use must be part of a project or database before you can use the Local View Wizard to create a view. For more information, see Working with Projects and Developing Databases.

To start the Local View Wizard

  1. Perform one of the following:

    • Open a database in the Database Designer.

      -OR-

    • Open the project for your application in the Project Manager, and click a database or table.

  2. On the Tools menu, point to Wizards, and click All Wizards.

  3. In the Wizard Selection dialog box, click Local View Wizard, and then OK.

  4. Follow the instructions on the wizard screens.

For more information, see Local View Wizard.

Creating Local Views Using the View Designer

You can use the View Designer to create views and specify additional options or customize existing views.

Note:
The tables or views you want to use must be part of a project or database before you can use View Designer to create a view. For more information, see Working with Projects and Developing Databases.

To start the View Designer

  1. Perform one of the following:

    • Open a database in the Database Designer.

      -OR-

    • Open the project for your application in the Project Manager, and click a database.

  2. On the File menu, click New.

  3. In the New dialog box, click View, and then New File.

    The Add Table or View dialog box appears.

  4. In the Select area of the Add Table or View dialog box, click Tables to display available tables or Views to display available views.

  5. Click the tables or views you want to use, and then Add.

    Tip:
    When you add more than one table or view to your view, the Join Condition dialog box appears. You can modify the scope of resulting records by specifying a join condition for each additional table or view.

    Tip:
    When you select the same table or view more than once, Visual FoxPro uses an automatically generated alias for the table or view. However, you can specify an alias for each table or view that you select by typing it in the Alias box in the Add Table or View dialog box.

    The tables or views you select appear in the View Designer and Database Designer.

  6. When you are finished, click Close.

For more information specifying join conditions, see How to: Control Record Selection with Joins, Join Conditions for Tables, Queries, and Views, and Join Condition Dialog Box.

After selecting tables or views, you need to select the fields that contain the data you want to retrieve the data for your view. For more information, see How to: Select Fields for Views.

Creating Local Views Programmatically

You can create local views programmatically by opening the View Designer or specifying a SQL SELECT statement.

To create a local view programmatically

  1. Open the database or project containing the tables or views you want to select.

  2. Choose one of the following:

    • To select tables or views and open the View Designer, use the CREATE SQL VIEW command with only the name of the view you want to create.

    -OR-

    • To create a local view without opening the View Designer, use the CREATE SQL VIEW command and the AS clause to specify SQL SELECT statements.

      Note:
      To match related records between the tables, you must specify a join condition in the FROM or WHERE clause of the SQL statement used in the CREATE SQL VIEW command. If persistent relationships between the tables exist, they are automatically used as join conditions.

    The tables or views you select appear in the View Designer and Database Designer. You might need to close and reopen the designers to update them.

For more information, see CREATE SQL VIEW Command.

See Also

Other Resources

How to: Add Tables to Views
View Creation
Accessing Remote Data Using Views
Creating Views
Working with Views


Accessing Remote Data Using Views

Visual FoxPro 9.0
Accessing Remote Data Using Views
See Also

You can access and retrieve information in remote data sources by creating remote views. Remote views are similar to local views except that you specify the name or connection name for a remote data source. This remote data source is typically an Open Database Connectivity (ODBC) data source. Remote views use the SQL syntax of the remote data source.

The general process for accessing remote data using remote views appears as follows:

  1. Establish a working connection to a valid remote data source.

    A valid remote data source is typically a remote server for which you have installed an ODBC driver and set up an ODBC data source name. For more information, see How to: Set Up an ODBC Data Source.

  2. In Visual FoxPro, define the data source or a named connection to use when you create the view.

    You can define a connection to a data source and store the definition in a Visual FoxPro database so you can use the connection definition when you create a remote view. When you open the remote view, Visual FoxPro uses the named connection associated with the view to connect to the remote data source and request data from the remote data source.

  3. Create the remote view by selecting tables and fields you want to use from the remote data source.

  4. Set any properties that you want for the named connection to optimize the communication between Visual FoxPro and the remote data source.

See Also

Other Resources

How to: Define Connections to Remote Data Sources
View Creation
Creating Views
Working with Views


How to: Define Connections to Remote Data Sources

Visual FoxPro 9.0
How to: Define Connections to Remote Data Sources
See Also

You can define and store a connection to a remote data source in a Visual FoxPro database so you can use the connection name when you create and use a remote view.

Creating and storing a named connection in your database does not use any network or remote resources because Visual FoxPro does not activate the connection until you use the remote view. The named connection exists only as a connection definition stored as a row in the database (.dbc) file until the connection activates.

Note:
Before you can create a connection, you must have a database open. For more information, see How to: Open Databases.

To define a connection

  1. Perform one of the following:

    • Open the database in the Database Designer.

    -OR-

    • Open the project for your application in the Project Manager.

  2. On the File menu, click New.

  3. In the New dialog box, click Connection, then New File.

  4. In the Connection Designer, select the options that correspond to your server requirements.

  5. On the File menu, click Save to open the Save dialog box.

  6. In the Connection Name box, type a name for the connection, and click OK.

For more information, see Connection Designer.

To create a new connection programmatically

  1. Open the database or the project containing the database.

  2. Choose one of the following:

    • To create a connection using the Connection Designer, use the CREATE CONNECTION command with a question mark (?).

    -OR-

    • To create a connection without opening the Connection Designer, use the CREATE CONNECTION command with the name of the connection and the necessary parameters.

For more information, see CREATE CONNECTION Command.

For example, the following code opens a database named MyDatabase and creates a connection called Remote_01 to a remote data source named SQLRemote:

Copy Code
OPEN DATABASE MyDatabase
CREATE CONNECTION Remote_01 ;
   DATASOURCE SQLRemote USERID myUserID PASSWORD myPassword

See Also

Other Resources

How to: Create Remote Views
Accessing Remote Data Using Views
View Creation
Creating Views
Working with Views


How to: Create Remote Views

Visual FoxPro 9.0
How to: Create Remote Views
See Also

You can create remote views by specifying the name of a valid data source or a connection you have previously defined. For more information about defining connections, see How to: Define Connections to Remote Data Sources.

Note:
If you create a remote view using only the data source name, Visual FoxPro uses the Open Database Connectivity (ODBC) information about the data source to create and activate a connection to the data source. When you close the view, the connection closes.

You can create remote views in the following ways:

  • Using the Remote View Wizard.

    A wizard is the easiest way to start creating a view. You can select fields from tables and filter and sort the records in your remote view. For more information, see Creating Remote Views Using a Wizard.

  • Using the View Designer.

    The View Designer makes it possible to select fields from tables, specify criteria for retrieving data and join conditions, and filter, sort, and group records to create views or customize existing views. For more information, see Creating Remote Views Using the View Designer.

  • Creating remote views programmatically.

    The CREATE SQL VIEW command makes it possible for you to specify a remote data source or connection name so you can create remote views programmatically. For more information, see Creating Views Programmatically.

Regardless of the method you use, the basic process for creating a view is generally the same. For more information, see View Creation.

Note:
When you create or use a view from the Project Manager, the Project Manager opens the database automatically. However, if you subsequently use a view outside the project, you must open the database or make sure the database is in scope before you can use the view.

Creating Remote Views Using a Wizard

You can create remote views easily using a wizard. The wizard helps you select connections or data sources and creates a query based on your answers to a series of questions.

To create a remote view with a wizard

  1. Perform one of the following:

    • Open the database in the Database Designer.

    -OR-

    • Open the project for your application in the Project Manager.

  2. On the Tools menu, point to Wizards, and click All Wizards.

  3. In the Wizard Selection dialog box, click Remote View Wizard, and then OK.

  4. Follow the instructions on the wizard screens.

For more information, see Remote View Wizard.

Creating Remote Views Using the View Designer

You can use the View Designer to create views and specify additional options or customize existing views.

Note:
For remote views, if you join two or more tables in the View Designer, the designer uses inner joins and places the join condition in the WHERE clause of the SQL statement generated by the view. If you want to use an outer join, the View Designer provides only left outer joins using the syntax supported by ODBC. If you need right or full outer joins or want to use native syntax for a left outer join, create the view programmatically.

To create a remote view

  • Perform one of the following:

    • Open the database in the Database Designer.

    -OR-

    • Open the project for your application in the Project Manager.

For more information, see Query and View Designers and Select Connection or Data Source Dialog Box.

After selecting tables, you need to select the fields that contain the data you want to retrieve the data for your view. For more information, see How to: Select Fields for Views.

Creating Remote Views Programmatically

You can create remote views programmatically by opening the View Designer or specifying a SQL SELECT statement.

To create a remote view programmatically

  1. Open the database or project to which you want to add the remote view.

  2. Choose one of the following:

    • To select a data source or connection name, choose tables, and open the View Designer, use the CREATE SQL VIEW with only the REMOTE clause.

    -OR-

    • To create a remote view without opening the View Designer, use the CREATE SQL VIEW with a CONNECTION clause and the AS clause to specify the SQL SELECT statement you want to use.

      Note:
      To match related records between the tables, you must specify a join condition in the FROM or WHERE clause of the SQL statement used in the CREATE SQL VIEW command. If persistent relationships between the tables exist, they are automatically used as join conditions.

    The tables you select appear in the View Designer and Database Designer. You might need to close and reopen the designers to update them.

For more information, see CREATE SQL VIEW Command.

You can view available connections using the DISPLAY CONNECTIONS command. For more information, see DISPLAY CONNECTIONS Command.

For example, the following code opens a database named MyDatabase on a remote server and creates a remote view from a table named MyRemoteTable using a predefined connection named Remote_01:

Copy Code
OPEN DATABASE MyDatabase
CREATE SQL VIEW MyRemoteTable_Remote_View ;
   CONNECTION Remote_01 AS SELECT * FROM MyRemoteTable

You can also specify a data source name instead of connection name.

See Also

Other Resources

Accessing Remote Data Using Views
View Creation
Creating Views
Working with Views


How to: Add Tables to Views

Visual FoxPro 9.0
How to: Add Tables to Views
See Also

You can access data stored in other tables by adding those tables to your local or remote view and specifying join conditions for the added tables.

Specifying join conditions between the tables you add help determine which records from the two tables should be compared and returned. For more information, see How to: Control Record Selection with Joins and Join Conditions for Tables, Queries, and Views.

Note:
When you add tables to an existing view programmatically, the CREATE SQL VIEW command produces a cross product.

To add a table to a local view

  1. Open the view in the Project Manager or Database Designer.

    The View Designer opens.

  2. On the Query menu, click Add Tables.

  3. In the Add Table or View dialog box, select the table or view you want to add.

    The table or view you selected appears in the View Designer.

  4. In the Join Condition dialog box, specify the join condition you want, and click OK.

  5. If you want to specify an alias for each table that you select, type it in the Alias box.

  6. When you are finished, click Close.

For more information, see Query and View Designers and Join Condition Dialog Box.

To add a table to a remote view

  1. Open the view in the Project Manager or Database Designer.

    The View Designer opens.

  2. On the Query menu, click Add Tables.

  3. In the Open dialog box, click each table you want to add, and then Add.

    The table you selected appears in the View Designer.

  4. In the Join Condition dialog box, specify the join condition you want, and click OK.

  5. If you want to specify an alias for each table that you select, type it in the Alias box.

  6. When you are finished, click Close.

For more information, see Query and View Designers, Select Connection or Data Source Dialog Box and Join Condition Dialog Box.

To add a table to views programmatically

  1. In the SQL SELECT statements specified by the CREATE SQL VIEW command, add table names and join conditions for the tables you add using the FROM and WHERE clauses.

    Visual FoxPro displays a confirmation dialog box to overwrite the existing view.

  2. In the confirmation dialog box, click Yes.

For more information, see CREATE SQL VIEW Command.

See Also

Other Resources

How to: Edit Views
How to: Select Fields for Views
Creating Views
Working with Views


How to: Select Fields for Views

Visual FoxPro 9.0
How to: Select Fields for Views
See Also

After creating a view and selecting the tables or views you want to use, you can build the view by selecting the fields from the tables or views.

To select fields for a view

  1. Open the view in the View Designer.

  2. In the View Designer, click the Fields tab.

  3. In the Available fields list, click each field you want, and then Add.

    Tip:
    To select multiple fields, press and hold the SHIFT key while selecting fields. After you select all the fields you want, click Add.

    Each field you select appears in the Selected fields list.

    Tip:
    To change the order in which fields appear in output, in the Selected fields list, drag the double arrow button appearing to the left of the field you want to move to the position you want.

  4. When you are finished, you can perform other tasks to customize the view.

You can customize your view in the View Designer by performing the following tasks:

  • Change the join condition of the selected tables in the Join tab.

  • Filter results by field in the Filter tab.

  • Organize results by field in the Order By tab.

  • Group results by field in the Group By tab.

  • Specify update criteria in the Update Criteria tab to control how to perform updates to source tables.

  • Select a different type of output in the Miscellaneous tab.

For more information, see Query and View Designers.

See Also

Other Resources

How to: Create Local Views
How to: Create Remote Views
View Creation
Creating Views
Working with Views


How to: Generate Results for Views

Visual FoxPro 9.0
How to: Generate Results for Views
See Also

After you finish selecting fields and customizing a view, you can run it to retrieve and view the records selected by the view. When you are satisfied with the view results, you can save the results view by specifying a name for the view.

To retrieve and view the results of a view

  • On the Query menu, click Run Query.

    Visual FoxPro displays the results in a browse window.

To save the view

  1. On the File menu, click Save As.

  2. In the Save dialog box, type a name for the view.

Visual FoxPro adds a view definition containing the table names, selected fields, and property settings for the view to the current database.

See Also

Other Resources

How to: Select Fields for Views
View Creation
Creating Views
Working with Views


Managing Views

Visual FoxPro 9.0
Managing Views

You can perform a variety of tasks to manage views, similar to those that you perform to manage tables, table fields, and table records, for example:

  • Specify captions for view fields.

  • Add comments to views and view fields.

  • Specify default values for view fields.

  • Create validation rules for fields and records.

  • Create indexes on view fields using the INDEX command.

    Note:
    Unlike table indexes, indexes you create on views are not stored and are removed when you close a view. Consider the size of the view's result set before creating an index. Indexing a large result set might decrease performance of your view.

  • Create temporary relationships between views or tables and views using the SET RELATION command.

    Tip:
    To increase performance when using the SET RELATION command, make the view the parent and the table the child in the relationship.

    Note:
    Making the table the child is more efficient because the structural index of the table is constantly maintained, quickly accessed, and can be used by the data environment to order the records. In comparison, the index on the view must be rebuilt each time the view is activated and takes more time than the index on the table. An index on a view is not part of the view definition; therefore, if you use a data environment, the view cannot be the child because the index on the child must exist as part of the definition.

In This Section

Opening Views

Discusses opening views.
How to: Edit Views

Describes how to open views for editing and other management tasks.
How to: Rename Views

Describes how to change the names of views.
How to: Open Views in Work Areas

Describes how to open views in work areas.
Setting View and Connection Properties

Provides an overview about setting properties for views and connections for remote views.
How to: Set Field Properties for Views

Describes how to set various properties for fields in views.
How to: Add Comments to Views

Describes how to add descriptions for views.
How to: Create Default Values for View Fields

Describes how to specify default values for view fields.
How to: Create Rules on View Fields and Rows

Describes how to create validation rules for view fields and records.
How to: Set Timeout Intervals for Connections

Describes how to set timeout values for the connection to the remote server if you need to adjust how Visual FoxPro interacts with the server.
How to: View and Edit SQL Statements for Views

Describes how to display and edit the SQL SELECT statement and properties generated for views.
How to: Create Views with Stored SQL Statements

Describes how to store the SQL SELECT statement that Visual FoxPro builds for views and use them to create views programmatically.
How to: Delete Views

Describes how to delete views when you are finished working with them.

Related Sections

Displaying Data in Views

Describes different ways to display views.
Updating Data in Views

Describes how to update data in views and their base tables.
Working with Views

Explains how to use views to create a customized updateable data set for your application.


Opening Views

Visual FoxPro 9.0
Opening Views
See Also

You can use views in browse windows, data sessions, and programmatically in the same way you open tables. When you use a view, the view is opened as a cursor in its own work area. If the view is based on local tables, Visual FoxPro also opens the base tables in separate work areas. The base tables for a view are the tables accessed by the SQL SELECT statement that you specify in the CREATE SQL VIEW command when you create a view. In the previous example, using product_view automatically opens the products table as well.

When a view is based on remote tables, the base tables are not opened in work areas. Only the name of the remote view appears in the Data Session window.

See Also

Other Resources

How to: Edit Views
Managing Views
Working with Views


How to: Edit Views

Visual FoxPro 9.0
How to: Edit Views
See Also

You can open views for performing tasks, such as adding tables, changing join conditions, or other modifications you want to make to a view.

To open a view for editing

  1. Perform one of the following:

    • Open the application project containing the view in the Project Manager. Click the view, and then Modify.

      -OR-

    • Open the database containing the view in the Database Designer. Click the view, and on the Database menu, click Modify.

    The View Designer opens to display the view.

For more information, see How to: Open Databases and How to: Edit Files in Projects.

To open a view programmatically

  1. Open a database containing the view.

  2. Use the MODIFY VIEW command with the name of the view.

For more information, see MODIFY VIEW Command.

See Also

Other Resources

Managing Views
Working with Views


How to: Rename Views (Visual FoxPro)

Visual FoxPro 9.0
How to: Rename Views (Visual FoxPro)
See Also

You can rename views.

To rename a view

  1. Open the application project containing the view in the Project Manager.

  2. In the Project Manager, click the view.

  3. On the Project menu, click Rename File.

  4. In the Rename File dialog box, type the new name for the view.

  5. When you are finished, click OK.

For more information, see How to: Edit Files in Projects.

To rename a view programmatically

  1. Open the database containing the view.

  2. Use the RENAME VIEW command.

For more information, see How to: Open Databases and RENAME VIEW Command.

See Also

Other Resources

How to: Edit Files in Projects
Managing Views
Working with Views


How to: Open Views in Work Areas

Visual FoxPro 9.0
How to: Open Views in Work Areas
See Also

You can open a view in separate work areas similar to how you can open a table in different work areas. For more information, see How to: Open Tables in Work Areas.

However, unlike tables, views retrieve a new data set each time you use the view. When you open the view programmatically with the USE command, you can open additional instances of the view without retrieving data from the data source. This is particularly useful when you want to open a remote view in multiple work areas without waiting to download data from remote data sources.

To open another instance of a view without downloading data

  • Open the view with the USE command and include the NOREQUERY or AGAIN clause.

You can specify a data session number when using the NOREQUERY clause. If you omit a data session number, Visual FoxPro searches in all data sessions. If an opened result set is found for the view, Visual FoxPro opens the cursor again on the same result set. If no open result set is found, Visual FoxPro retrieves a new result set for the view. As is true with tables, if the view is not found, Visual FoxPro opens a new cursor for the view.

If you want Visual FoxPro to search only the current data session for an opened result set, use the AGAIN clause. Opening another instance of a view with the AGAIN clause is the equivalent using the NOREQUERY clause with the current session number.

For more information, see USE Command.

For example, the following code opens the sample Northwind database using the OPEN DATABASE command, creates a remote view named Product_View using the CREATE SQL VIEW command and selects all the records in the Products table. The USE command opens the view, and the BROWSE command displays the first instance of the view in a browse window. The SELECT command selects the work area of the view, and the USE command opens the same view with the NOREQUERY clause. This time, the BROWSE command displays the view in a browse window without retrieving the data from the data source:

Copy Code
OPEN DATABASE HOME(2) + "Northwind\Northwind"
CREATE SQL VIEW Product_View AS SELECT * FROM Products
USE Product_View
BROWSE
SELECT 0
USE Product_View NOREQUERY
BROWSE

The following code uses the USE command to open the view and the BROWSE command to display the view in a browse window. The second USE command opens the view from the current data session with the AGAIN clause using a different alias. The BROWSE command displays the view with the different alias:

Copy Code
OPEN DATABASE HOME(2) + "Northwind\Northwind"
USE Product_View
BROWSE
USE Product_View AGAIN IN 0
BROWSE

The following command deletes the view when you are finished working with it:

Copy Code
DELETE VIEW Product_View

For more information, see OPEN DATABASE Command, CREATE SQL VIEW Command, BROWSE Command, SELECT Command, and DELETE VIEW Command.

See Also

Other Resources

Managing Views
Working with Views


Setting View and Connection Properties

Visual FoxPro 9.0
Setting View and Connection Properties
See Also

When you create a view, the view inherits property settings from the environment cursor, which is the cursor 0 in the current data session. You can change the settings for these properties using the CURSORSETPROP( ) function with 0 as the cursor number. After the view has been created and is stored in a database, you can change view properties with the DBSETPROP( ) function. The changes you make to view properties in a database are stored persistently in the database.

When you use a view, the property settings stored for the view in the database are inherited by the active view cursor. You can change these properties on the active cursor using the CURSORSETPROP( ) function for the view cursor. Changes you make with the CURSORSETPROP( ) function are temporary. The temporary settings for the active view disappear when you close the view; the temporary settings for cursor 0 go away when you close the Visual FoxPro session.

Connections inherit properties in a similar fashion. Default properties for connection 0 are inherited when you create and store a named connection in a database. You can change these default property settings for connection 0 with the SQLSETPROP( ) function. After the connection has been created and is stored in a database, you can change connection properties with the DBSETPROP( ) function. When you use a connection, the property settings stored for the connection in the database are inherited by the active connection. You can change these properties on the active connection using the SQLSETPROP( ) function for the connection handle.

Both views and connections can use a named ODBC data source. If you use an ODBC data source in a view, the connection inherits properties from the session defaults.

The following diagram illustrates property inheritance for views and connections. The gray lines represent the flow of property inheritance; the black lines represent Visual FoxPro commands.

See Also

Other Resources

Managing Views
Working with Views


How to: Set Field Properties for Views

Visual FoxPro 9.0
How to: Set Field Properties for Views
See Also

You can set some of the same properties that are available for fields in tables because your view is part of a database. For example, you can assign captions, add comments, or set validation rules to control data entry. For more information, see Working with Fields.

To view and set properties for fields in views

  1. Open the view in the View Designer, and click the Fields tab.

  2. In the Selected fields list, click a field, and then Properties.

  3. In the View Field Properties dialog box, configure the settings that you want.

  4. When you are finished, click OK.

For more information, see Fields Tab, Query and View Designers and View Field Properties Dialog Box.

See Also

Other Resources

How to: Edit Views
Managing Views
Working with Views


How to: Add Comments to Views

Visual FoxPro 9.0
How to: Add Comments to Views
See Also

You can add comments to the views you create. Comments that you add to a view are stored in the database (.dbc) file that contains the view.

To add a comment to a view

  1. Open the view in the View Designer.

  2. On the Query menu, click Comments.

  3. In the Comment box, type comments you want to add to the view.

  4. When you are finished, click OK.

You can see the comments for a view by opening the SQL window. For more information, see How to: View SQL Statements for Views.

To edit comments for a view

  1. Open the view in the View Designer.

  2. Open the SQL window for the view.

  3. In the SQL window, edit the DBSETPROP( ) function call containing the Comment view property.

  4. When you are finished, close the SQL window.

For more information, see How to: View SQL Statements for Views.

To add or edit a comment to a view programmatically

  • Use the DBSETPROP( ) function with the Comment property for the view.

For more information, see DBSETPROP( ) Function.

See Also

Other Resources

How to: Edit Views
Managing Views
Working with Views


How to: Create Default Values for View Fields

Visual FoxPro 9.0
How to: Create Default Values for View Fields
See Also

As with table fields, you can specify default values for view fields. These default values are stored in the database and are available when you use the view.

Note:
Visual FoxPro does not compare the default values you create locally with any default values stored in the remote data source. You must create default values that are acceptable for the data source.

To specify a default value for a view field

  1. Open the view in the View Designer, and click the Fields tab.

  2. On the Fields tab, select a field, and click Properties.

  3. The View Field Properties dialog box opens.

  4. In the Default value box in the Field Validation area, type the default value for the field.

  5. When you are finished, click OK.

For more information, see Fields Tab, Query and View Designers and View Field Properties Dialog Box.

To specify a default value for a view field programmatically

  • Use the DBSETPROP( ) function with the DefaultValue field property for views.

For more information, see DBSETPROP( ) Function.

For example, you may want your application to limit the amount of merchandise a new customer can order until you've had time to complete a credit check and determine the amount of credit you're willing to extend to that customer. The following example creates a maxordamt field with a default value of 1000:

Copy Code
OPEN DATABASE testdata
USE VIEW customer_view
?DBSETPROP ('Customer_view.maxordamt', 'Field', 'DefaultValue', 1000)

You might also use default values to populate some rows automatically for the user. For example, you might add a Grid control to an order entry form that is based on a remote view of an order line items table. The order_id field is the key field that maps each row of the Grid to its counterpart in the remote order line items table. Because the order ID for each row in the grid will be the same for one order, you can use a default value to save keystrokes by populating the order_id field automatically.

Tip:
If one of your application's business rules requires that a field contain an entry, providing a default value helps to ensure that a particular field-level or record-level rule will not be violated.

See Also

Other Resources

How to: Edit Views
Managing Views
Working with Views


How to: Create Validation Rules for Views

Visual FoxPro 9.0
How to: Create Validation Rules for Views
See Also

You can create local versions of field and record validation rules for views. Creating local validation rules provide the following benefits:

  • Reduce response time.

  • Reduce impact on network resources.

  • Test data before sending it to the remote data source.

  • Prevent sending faulty data to the remote data source.

However, Visual FoxPro does not compare the validation rules that you create locally with the validation rules in the remote data source. Therefore, you must create rules that are appropriate and compliant with the remote data source. If remote data source rules change, the local validation rules must match.

For more information, see Working with Validation Rules.

To create a field or record validation rule for views

  1. Open the view in the View Designer, and click the Fields tab.

  2. In the Selected Fields list, click a field, and click Properties.

  3. In the Rule box from the Field validation area, type the validation expression you want. To build an expression, click the ellipsis (...) button.

  4. To display a custom error message, in the Message box, type the custom error message or expression you want to display for invalid values. To build an expression, click the ellipsis (...) button.

    Note:
    Make sure to enclose message text in quotation marks ("").

To create a field or record validation rule for views programmatically

  • Use the DBSETPROP( ) function to set the RuleExpression and RuleText field or record properties for views.

For more information, see DBSETPROP( ) Function.

For example, the following code creates a field-level rule on orditems_view that prevents entering a quantity of less than 1:

Copy Code
OPEN DATABASE testdata
USE VIEW orditems_view
DBSETPROP('Orditems_view.quantity','Field', ;
         'RuleExpression', 'quantity >= 1')
DBSETPROP('Orditems_view.quantity','Field', ;
         'RuleText', ;
'"Quantities must be greater than or equal to 1"')

See Also

Other Resources

How to: Edit Views
Managing Views
Working with Views


How to: Set Timeout Intervals for Connections

Visual FoxPro 9.0
How to: Set Timeout Intervals for Connections
See Also

You can set timeout values for the connection to the remote server if you need to adjust how Visual FoxPro interacts with the server.

To set timeout intervals

  1. Open the application project containing the view in the Project Manager.

  2. In the Project Manager, expand the Data node, the Databases node, and then the node for the database containing the remote data source connection you want.

  3. Click the connection name, and then Modify.

    The Connection Designer opens for the connection.

  4. In the Timeout intervals area, set the values you want.

  5. When you are finished, on the File menu, click Save to save the settings.

For more information, see Connection Designer.

See Also

Other Resources

How to: Edit Files in Projects
Managing Views
Working with Views


How to: View and Edit SQL Statements for Views

Visual FoxPro 9.0
How to: View and Edit SQL Statements for Views
See Also

When you create a view in the View Designer, Visual FoxPro builds a SQL SELECT statement to retrieve the information from the fields in the tables. You can see and edit the SQL SELECT statement that Visual FoxPro builds and the properties set for the view in the SQL window. Any changes that you make in the SQL window are preserved during the loading or generation of the view.

To display the view definition

  1. Open the view in the View Designer.

  2. On the Query menu, click View SQL.

The SQL window for the view opens and displays the SQL SELECT statement generated automatically for the view and properties for the view. For more information, see SELECT - SQL Command and DBSETPROP( ) Function.

For example, suppose you create a view in the View Designer using the sample Northwind database and select all records in the Customers table where the Country field contains the value "Canada". The following SQL SELECT statement appears in the SQL window when you open it:

Copy Code
SELECT *;
   FROM Northwind!Customers ;
   WHERE Customers.Country = "Canada"

You can also include the SQL SELECT statement in code by copying the SQL SELECT statement from the SQL window into a program (.prg) file. You can also run the SQL SELECT statement immediately by copying the statement and running the statement in the Command window.

Tip:
If you want to process the statement only after you type the last line, type each clause on a separate line in the window and end each line except the last one with a semicolon (;).

To edit the view definition

  1. In the SQL window, edit the SQL SELECT statement or view properties.

  2. To update the View Designer, close the SQL window or click the View Designer to make it the active window.

The View Designer is updated with the changes you made to the view definition.

Note:
If the View Designer cannot reload your changes after you make changes in the View SQL window, a dialog box appears with the following prompt:

"View/Query designer is unable to reload your changes. Would you like to rebuild content from the designer?"

Clicking Yes discards your changes in the SQL window and returns you to the View Designer. Clicking No returns you to the SQL window.

Tip:
To save a statement that cannot be parsed such as a call to a stored procedure, click No, and then Save on the standard toolbar. Visual FoxPro saves the query. You can save the query by clicking Save on the standard toolbar after typing the command in the SQL window. You do not need to click the View Designer window, which causes the View Designer to try to load and parse the query.

See Also

Other Resources

How to: Edit Views
How to: Create Views with Stored SQL Statements
Managing Views
Working with Views


How to: Create Views with Stored SQL Statements

Visual FoxPro 9.0
How to: Create Views with Stored SQL Statements
See Also

You can use macro substitution to store the SQL SELECT statement created for a view into a variable that you use with the AS clause in the CREATE SQL VIEW command.

To create a view using macro substitution

  1. Create a variable and store the SQL SELECT statement in the variable.

  2. In the AS clause of CREATE SQL VIEW command, use the ampersand (&) macro substitution character followed by the variable name.

For example, the following code stores a SQL SELECT statement into the variable MyEmpCustSQL. CREATE SQL VIEW creates a view named EmpCustView using the variable:

Copy Code
MyEmpCustSQL = "SELECT employee.emp_id, customer.cust_id, ;
   customer.emp_id, customer.contact, customer.company ;
   FROM employee, customer WHERE employee.emp_id = customer.emp_id"
CREATE SQL VIEW EmpCustView AS &MyEmpCustSQL

See Also

Other Resources

How to: View and Edit SQL Statements for Views
CREATE SQL VIEW Command
& Command
Managing Views
Working with Views


How to: Delete Views

Visual FoxPro 9.0
How to: Delete Views
See Also

You can delete a view from a database.

To delete a view

  1. Open the application project containing the view in the Project Manager.

  2. In the Project Manager, expand the Data node, and then the Databases node.

  3. In the Local Views or Remote Views node, click the view you want to delete, and then Remove.

    Visual FoxPro displays a confirmation dialog box for you to confirm deleting the view.

  4. In the confirmation dialog box, click Remove.

For more information, see Project Manager Window.

To delete a view programmatically

  1. Open the database containing the view.

  2. Use the DELETE VIEW command or DROP VIEW command.

    Note:
    These commands perform the same task. DROP VIEW uses the ANSI SQL standard syntax for deleting a SQL view.

For more information, see DELETE VIEW Command and DROP VIEW Command.

See Also

Other Resources

How to: Edit Files in Projects
How to: Open Databases
Managing Views
Working with Views


Displaying Data in Views

Visual FoxPro 9.0
Displaying Data in Views

You can display records in views in a variety of ways.

In This Section

How to: Display View Structure

Describes how to display the fields in a view without downloading data.
How to: Filter Records in Views

Describes how to retrieve only the records that you want in a view.
How to: Create Parameterized Views

Describes how to specify parameters for filtering records in views.

Related Sections

Updating Data in Views

Describes how to update data in views and their base tables.
Managing Views

Describes tasks you can perform to manage views.
Working with Views

Explains how to use views to create a customized updateable data set for your application.


How to: Display View Structure

Visual FoxPro 9.0
How to: Display View Structure
See Also

You can display the structure of a view without opening the View Designer. . This option is useful when you want to look at the structure of a remote view without waiting to download data.

To display a view without data

  1. Open the view with the USE command and the NODATA keyword.

  2. Use the DISPLAY STRUCTURE command to display the structure information for the view in the main Visual FoxPro window.

For more information, see USE Command.

Tip:
Using the NODATA keyword is the fastest way to retrieve the structure for a view because it creates the smallest cursor possible on the remote data source.

For example, the following code opens a database named MyDatabase. The USE command opens a previously created remote view called Customer_Remote_View with the NODATA keyword in the work area 0. The DISPLAY STRUCTURE command writes the structure information to a file called ViewStructure without sending it to the main Visual FoxPro window.

Copy Code
OPEN DATABASE MyDatabase
USE Customer_Remote_View NODATA IN 0
DISPLAY STRUCTURE TO FILE ViewStructure.txt NOCONSOLE

See Also

Other Resources

Displaying Data in Views
Managing Views
Working with Views


How to: Filter Records in Views

Visual FoxPro 9.0
How to: Filter Records in Views
See Also

When you access a local or remote data source, you can retrieve potentially large amounts of data. However, you can narrow the scope of the records to only those you need for the view by providing a filter. Filtering records also reduces network traffic when working with remote data and increases the performance of your view.

You can filter records in views by specifying a filter expression. When generating the view, Visual FoxPro evaluates the filter expression and compares the result with values in view fields. If the values meet the requirements of the expression, Visual FoxPro includes the records in the result set. Adding a filter expression adds a WHERE clause to the view's SQL statement.

For example, suppose you want to create a filter that includes only those customers from a certain country. In the following lines of code, the WHERE clause contains a filter expression that selects all customers in a customer table where the country field in the customer table contains the value "Sweden":

Copy Code
SELECT * FROM Customer ;
   WHERE Customer.Country = 'Sweden'

This code increases performance by retrieving only those records for a particular country rather than all customers. However, this code also requires that you create a separate view for each country because the actual value is coded into the view's SQL SELECT statement. Instead, you can create a parameterized view which uses a parameter in the filter expression to accept a value for the WHERE clause. For more information, see How to: Create Parameterized Views.

To filter records in a view

  1. Open the view in the View Designer, and click the Filter tab.

  2. In the Field Name list, select one of the following:

    • A table field that you want include in the filter expression.

    -OR-

    • <Expression> to open the Expression Builder so you can build a filter expression.

      Note:
      If you are creating a view from a remote data source, the functions available in the Expression Builder reflect the functions supported by that server. For a list of functions that your remote server supports, check your server documentation. Visual FoxPro does not attempt to parse the expressions you specify; instead, it passes them to the remote server.

  3. In the Criteria list, select the comparison operator that you want to use.

    Tip:
    To negate the condition, click the NOT column for the expression.

  4. In the Example box, type the value or expression you want to use to compare the field value with.

For more information, see Filter Tab, Query and View Designers and Expression Builder Dialog Box.

See Also

Other Resources

How to: Edit Views
Displaying Data in Views
Managing Views
Working with Views


How to: Create Parameterized Views

Visual FoxPro 9.0
How to: Create Parameterized Views
See Also

You can filter records for a view without creating separate views for each filter value by creating a parameterized view. A parameterized view uses a SQL SELECT statement containing a WHERE clause that specifies a filter expression with a parameter. The parameter accepts values that can be supplied later by prompting the user or programmatically. Parameter names can be any combination of alphabetic characters, numbers, and single quotes.

To specify a parameter for a filter

  1. Open the view in the View Designer, and click the Filter tab.

  2. On the Filter tab, create a filter or select an existing filter.

  3. In the Example box, type the parameter name.

    Tip:
    To prompt for a parameter value when opening the view, precede the parameter name immediately with a question mark (?). When you open the view, the View Parameter dialog box appears and prompts you for a parameter value.

    Note:
    The parameter name you provide is evaluated as a Visual FoxPro expression. If the evaluation fails, Visual FoxPro prompts for a parameter value. The parameter value supplied is sent to the data source as part of the SQL SELECT statement.

For more information, see How to: Edit Views and Filter Tab, Query and View Designers.

To create a parameterized view programmatically

  1. Use the CREATE SQL VIEW command with the AS clause to specify a SQL SELECT statement.

  2. In the WHERE clause of the SQL SELECT statement, include the filter expression containing the parameter name in the appropriate location.

For more information, see CREATE SQL VIEW Command and SELECT - SQL Command.

For example, the following code opens the sample Northwind database and creates a parameterized view that selects all records in the Customers table where the Country field matches the value supplied for the cCountry parameter:

Copy Code
OPEN DATABASE HOME(2) + "Northwind\Northwind"
CREATE SQL VIEW Customer_Remote_View ;
   AS SELECT * FROM Customers WHERE Customers.Country = ?cCountry

When the following code opens the view, Visual FoxPro displays the View Parameter dialog box to prompt for a parameter value. After you type a parameter value, a browse window opens to display the results:

Copy Code
USE Customer_Remote_View
BROWSE

The following code deletes the view from the Northwind database when you are finished:

Copy Code
DELETE VIEW Customer_Remote_View

You can pass the parameter value programmatically instead of prompting for a parameter value. The following code creates the same parameterized view but omits the question mark. The code later stores the value "Sweden" programmatically in cCountry as the parameter value. When you open the view, the parameter value is passed to the view, and a browse window opens to display the results:

Copy Code
OPEN DATABASE HOME(2) + "Northwind\Northwind"
CREATE SQL VIEW Customer_Remote_View ;
   AS SELECT * FROM Customers WHERE Customers.Country = cCountry
cCountry = 'Sweden'
USE Northwind!Customer_Remote_View
BROWSE

The following code deletes the view from the Northwind database when you are finished:

Copy Code
DELETE VIEW Customer_Remote_View

See Also

Other Resources

How to: Edit Views
Displaying Data in Views
Managing Views
Working with Views


Updating Data in Views

Visual FoxPro 9.0
Updating Data in Views

You can update data in a view and the base tables that the view was created from.

In This Section

Preparing to Update Views

Describes properties that need to be set so that you can update views.
How to: Update Data in a View

Describes how to enable updates for views.
How to: Update a Table in a View

Describes how to update base tables in the remote data source for a view.
How to: Update Multiple Tables in a View

Describes how to update multiple base tables for a view.

Related Sections

Displaying Data in Views

Describes different ways to display views.
Managing Views

Describes tasks you can perform to manage views.
Working with Views

Explains how to use views to create a customized updateable data set for your application.


Preparing to Update Views

Visual FoxPro 9.0
Preparing to Update Views
See Also

Before you can update data in a view, the view properties that control updates must be set so that the view can be updated. In most cases, the default view property values are set so that the view can be updated.

The following table lists the view properties that control updates and their default settings for views.

View property Default setting

Tables

Includes all tables that have updateable fields and have at least one primary key field.

KeyField

Database key fields and remote primary keys on the table.

UpdateName

Table_name.column_name for all fields.

Updateable

Update all fields except primary key fields.

SendUpdates

Defaults to the session default, which is originally set to False (.F.). If you change it to True (.T.), that becomes the default for all views created in the session.

Note:
While all the properties in the table are required for updating data, the SendUpdates view property controls whether to send updates. You must set SendUpdates to True (.T.) to send updates to the data source.

Tip:
As you develop your application, you might want to set SendUpdates to False (.F) so that you can set other view properties without updating data. When you are ready to test your application, set the SendUpdates property to True (.T.) to begin updating data.

CompareMemo

Defaults to True (.T.), means that memo fields are included in the WHERE clause and are used for detecting update conflicts.
Note:
The default view property settings might not enable updates for a view that is created programmatically. To enable updates for programmatically created views, review the default settings for the view properties and adjust them as needed. To change the settings for view properties, use the DBSETPROP( ) function. For more information, see DBSETPROP( ) Function.

Note:
By default, optimistic row buffering is used for views. However, you can change this to table buffering. For more information, see How to: Perform Updates Using Buffers.

See Also

Other Resources

How to: Update Data in a View
Updating Data in Views
Managing Views
Working with Views


How to: Update Data in a View

Visual FoxPro 9.0
How to: Update Data in a View
See Also

To update data in a view, make sure that the options and properties that control updates for views are set so that the view can be updated. For more information, see Preparing to Update Views.

Note:
The default view properties might provide all the information needed so that your view can be updated.

To view options for updating a view

  • Open the view in the View Designer, and click the Update Criteria tab.

    The Update Criteria tab displays the update settings for the view.

For more information, see How to: Edit Views and Update Criteria Tab, View Designer.

To set properties for updating a view

  1. Use the DISPLAY DATABASE command to display the current property settings for the view.

  2. Use the DBSETPROP( ) function to modify the property settings for the view.

For more information, see DBSETPROP( ) Function.

When you use DBSETPROP( ) to set properties on a view before you use the view, the settings are stored in the database and are used automatically whenever you activate the view. Once the view is active, you can use CURSORSETPROP( ) to change property settings on the active view. Property settings you set on an active view with CURSORSETPROP( ) are not saved when you close the view.

The following example lists the steps you would follow to specify the five view update properties programmatically:

  1. Set the Tables property with at least one table name.

    For example, if you have a view based on the customer table called cust_view, you could set the table name with the following function:

    Copy Code
    DBSETPROP('cust_view','View','Tables','customer')
    Tip:
    If a table appears as a qualifier in the UpdateName property but is not included in the default list for the Tables property, the table might not have a primary key field specified. Make the table updatable by adding the field you consider to be a key field to the KeyField property list, and then add the table to the Tables property list.

  2. Set the KeyField property with one or more local Visual FoxPro field names that together define a unique key for the update table.

    Using the same example, you could make cust_id the key field using the following code:

    Copy Code
    DBSETPROP('cust_view.cust_id','Field','KeyField',.T.)
    Caution:
    Be sure the key field(s) you specify define a unique key both in the base table you want to update and in the view.

  3. Map the view fields to their base table fields with the UpdateName property. This property is particularly useful when your view is based on a join of two tables with a common field name, or when the fields are aliased in the view. To update the desired base table, you map the Visual FoxPro view field name to the base table field and table name.

    Copy Code
    DBSETPROP('cust_view.cust_id','Field','UpdateName',;
         'customer.cust_id')
    Tip:
    To avoid creating synonym fields in your view, you can qualify field names in the SQL statement you use to build your view. Then use the Visual FoxPro UpdateName property of the view to map each qualified field to the correct base table and field name.

  4. Specify the scope of fields you want to update with the Updatable property. You should specify only those fields also specified with the UpdateName property.

    Copy Code
    DBSETPROP('cust_view.cust_id','Field','Updatable', .T.)
  5. Set the SendUpdates property to True (.T.). The SendUpdates property controls whether to create and send updates to the tables and fields that can be updated.

    Copy Code
    DBSETPROP('cust_view','View','SendUpdates',.T.)

See Also

Other Resources

How to: Update a Table in a View
Updating Data in Views
Managing Views
Working with Views


How to: Update a Table in a View

Visual FoxPro 9.0
How to: Update a Table in a View
See Also

You can use local or remote views to update the base tables in the remote data source. In the View Designer, the Update Criteria tab allows you to control how the changes you make to remote data (updates, deletes, and inserts) are sent back to the remote data source. You can also enable and disable updating for specific fields in the tables and set the SQL update method appropriate to your server.

Note:
The local base tables that open automatically when you use a view are not automatically closed when you close a view; you must explicitly close them. This is consistent with the SQL SELECT command.

Making a Table Updatable

If you want to have the changes you make to the local version of a table sent back to the source table, you need to set the Send SQL Updates option. You must set at least one key field to use this option. If the table you select has a primary key field defined and you have selected it in the Fields tab, the View Designer automatically uses the primary key field for the table as a key field for the view.

To enable updating of source tables

  • In the Update Criteria tab, set the Send SQL updates option.

Setting Key Fields

When you first open a table in the View Designer, the Update Criteria tab shows which fields in the table are defined as key fields. Visual FoxPro uses key fields to uniquely identify the update records in remote tables that you have modified locally.

To set a key field

  • In the Update Criteria tab, click the key column next to the name of the field.

If you have changed the key fields and want to restore them to the original setting in the source table, choose Reset Key. Visual FoxPro will check the remote tables and use the key fields from those tables.

Updating Specific Fields

You can specify that only certain fields in any given table are updatable. You must have a key field defined for a table in order to make any fields in that table updatable. If fields are not marked as updatable, users can make changes to the field in a form or Browse window, but these changes are not sent to the remote table.

To make a field updatable

  • In the Update Criteria tab, click the updatable ("pencil") column next to the name of the field.

Updating All Fields

If you want to be able to make changes to all the fields in a table, you can set all the fields in a table as updatable.

To make all fields updatable

  • In the Update Criteria tab, choose Update All.

    Note:
    You must have a key field defined in a table in order to use Update All. Update All does not affect key fields.

See Also

Other Resources

Update Criteria tab
How to: Update Data in a View
Updating Data in Views
Managing Views
Working with Views


How to: Update Multiple Tables in a View

Visual FoxPro 9.0
How to: Update Multiple Tables in a View
See Also

You can update multiple base tables from a view. When your view combines two or more tables, you set properties to ensure that only the many side of the view query is updatable.

Views are updated on a table-by-table basis. You must ensure that for each table accessed in a view, the key field set is a unique key for both the view result set and the base table.

To make a multitable view updatable

  • In the View Designer, choose the Update Criteria tab, and then select the tables and field names you want to update.

    -or-

  • Use the DBSETPROP( ) Function.

In most cases, the default values provided by Visual FoxPro prepare a multitable view to be updatable, even when you create the view programmatically. The following code example creates and explicitly sets properties to update a two-table view. You can use this example as a guide for customizing update property settings on a view.

Updating Multiple Tables in a View

Code | Comments
CREATE SQL VIEW emp_cust_view AS ; SELECT employee.emp_id, ; employee.phone, customer.cust_id, ; customer.emp_id, customer.contact, ; customer.company ; FROM employee, customer ; WHERE employee.emp_id = customer.emp_id | Create a view that accesses fields from two tables.
DBSETPROP('emp_cust_view', 'View', 'Tables', 'employee, customer') | Set the tables to be updated.
DBSETPROP('emp_cust_view.emp_id', 'Field', ; 'UpdateName', 'employee.emp_id') DBSETPROP('emp_cust_view.phone', 'Field', ; 'UpdateName', 'employee.phone') DBSETPROP('emp_cust_view.cust_id', 'Field', ; 'UpdateName', 'customer.cust_id') DBSETPROP('emp_cust_view.emp_id1', 'Field', ; 'UpdateName', 'customer.emp_id') DBSETPROP('emp_cust_view.contact', 'Field', ; 'UpdateName', 'customer.contact') DBSETPROP('emp_cust_view.company', 'Field', ; 'UpdateName', 'customer.company') | Set update names.
DBSETPROP('emp_cust_view.emp_id', 'Field', ; 'KeyField', .T.) | Set a single-field unique key for the Employee table.
DBSETPROP('emp_cust_view.cust_id', 'Field', ; 'KeyField', .T.) DBSETPROP('emp_cust_view.emp_id1', 'Field', ; 'KeyField', .T.) | Set a two-field unique key for the Customer table.
DBSETPROP('emp_cust_view.phone', 'Field', ; 'Updatable', .T.) DBSETPROP('emp_cust_view.contact', 'Field', ; 'Updatable', .T.) DBSETPROP('emp_cust_view.company', 'Field', ; 'Updatable', .T.) | Set the updatable fields. Typically, key fields are not updatable.
DBSETPROP('emp_cust_view', 'View', ; 'SendUpdates', .T.) | Activate the update functionality.
GO TOP REPLACE employee.phone WITH "(206)111-2222" REPLACE customer.contact WITH "John Doe" | Modify data in the view.
TABLEUPDATE() | Commit the changes by updating both the Employee and Customer base tables.

See Also

Other Resources

How to: Update a Table in a View
Updating Data in Views
Managing Views
Working with Views


Manipulating Offline Data

Visual FoxPro 9.0
Manipulating Offline Data
See Also

There are times when you might want to display, collect, or modify data independent of the host database. By using the offline view features in Visual FoxPro, you can use views to connect to a host database and create a subset of data for use offline. Then, working offline, you can use the view directly or through an application you create. When you are done, you can upload the changes stored in the view back to the host database.

Some scenarios where offline views are useful include:

  • A data warehousing situation, where large databases are maintained centrally on MIS servers. If you are only interested in data pertaining to, for example, the Marketing department, you can construct a view including only the data that is relevant to you. You can then take the data offline, allow multiple users in the Marketing department to update the data, and then commit the changed data to the source database.

  • A geographically remote location which requires that you take a subset of data with you on a laptop, modify the data independently of the host database, then update the host database with the changed data at a later time.

  • Time-sensitive data. For example, you might want to update data reflecting employee pay raises before the new pay rates actually take effect.

Using the offline view, you can display and update data much as you do online with the same forms, reports, or applications.

To create and use view data offline, you can use the following language features:

  • The CREATEOFFLINE( ) function.

  • The USE SQLViewName command with the ADMIN and ONLINE clauses.

    For example, the following code opens the Showproducts view:

    Copy Code
    USE Showproducts
  • The TABLEUPDATE function.

  • The DROPOFFLINE( ) function.

If you are not getting the subset of data that you expected, check the optimization settings for the remote view. If you set the MaxRecords property using the DBSETPROP( ) function, only that many records appear in your views offline. However, if you include a Memo field in the field list of your view, it is automatically included in the result set even if FetchMemo is set to false (.F.).

If you plan to use the offline view on a machine other than the one on which you created the offline view, you must prepare the offline destination by creating a copy of the host database file (.dbc); making sure the ODBC data source used by the view exists on the destination machine; and analyzing your data requirements to determine the contents of the view you need.

Note:
Use the ODBC Administrator program to install data sources on a machine. You can access the ODBC Administrator program from either the Visual FoxPro program group or from the Control Panel.

After you create the view for your offline data, you can use it as you would any view in your application: you can add, change, and delete records. Multiple users can access the offline view concurrently using the same database in shared mode. If you decide you do not want to keep any of the changes, you can revert the information to reflect the original information.

Administering Data Offline

In some cases — especially in a multiple-user environment where numerous people modify data — you might want to examine changes made to the offline view before committing the changes to the source database. With the USE command and the ADMIN clause, you can see all changes that have been committed to a view since it was taken offline. You can then selectively revert changes that have been made without being connected to the data source. For example, the following code opens the view Showproducts in administrator mode:

Copy Code
USE Showproducts ADMIN

See Also

Other Resources

Working with Views
How to: Create Offline Views
Updating Data Using Transactions


How to: Create Offline Views

Visual FoxPro 9.0
How to: Create Offline Views
See Also

As with online data, analyze your requirements before creating offline views to determine the design of the views you will need in the offline database. Once you know the subset of data you want to use offline, you can start with an existing view or create a new view. If a view already exists that returns the records you want to use offline, you can use it, or you can create one programmatically. The view you take offline is stored in a .dbf file in the offline database container.

Note:
If you plan to modify data in an offline view, be sure to make the view updatable before you take it offline. Once a view is offline, you can only set its update properties programmatically; you cannot modify an offline view in the View Designer.

To use an existing view offline

  • Use the CREATEOFFLINE( ) Function and the name of the view.

For example, if you want to go to client sites to update accounts, add customers, and record new sales, you need the customer information as well as current orders and the online product descriptions. You might have a view called customerinfo that combines information from the Customers table, Orders table, and OrderItems table. To create the view, use this code:

Copy Code
CREATEOFFLINE("customerinfo")

To programmatically create a view offline

  • Use the CREATE SQL VIEW Command, followed by the CREATEOFFLINE( ) Function.

For example, the following code creates a view that displays data from the Products table and the Inventory table from the online database. Since no update criteria are specified, this view is read-only:

Copy Code
CREATE SQL VIEW showproducts ;
   CONNECTION dsource ;
   AS SELECT * FROM Products INNER JOIN Inventory ;
   ON Products.ProductID = Inventory.ProductID ;
CREATEOFFLINE("showproducts")

See Also

Other Resources

Manipulating Offline Data
How to: Update to Online Data
How to: Optimize View Performance


Updating Data Using Transactions

Visual FoxPro 9.0
Updating Data Using Transactions
See Also

After you're finished offline, you can update the data on the server using the same table update transactions you usually use with online data. When working with remote data, keep in mind the following tips:

  • For single record updates, use automatic transactions.

  • For batch updates, use manual transactions.

  • As necessary, include code to detect update conflicts, create a log of conflicts, and resolve conflicts.

Before you can process your updates, you need to use the USE command and the ONLINE keyword to reconnect to the host database. After you issue the command, Visual FoxPro attempts to locate the host database using the data source information stored in the view. After the connection is established, you can use TABLEUPATE( ) to process the updates stored in the offline data.

To make sure the connection information is correct regardless of the location of either the host or view tables, you need to use connection string syntax rather than a named connection.

Updating Batches of Records in Local Tables

To process a batch of changes against local tables, you can use manual transactions that allow you to process the entire batch of changes within a single transaction rather a series of separate transactions.

Updating local tables with offline views

Code | Comments
USE myofflineview ONLINE EXCLUSIVE | Reconnect to the host and open the view.
BEGIN TRANSACTION IF TABLEUPDATE (2, .F., "myofflineview") END TRANSACTION ELSE MESSAGEBOX("Error Occurred: Update unsuccessful.") ROLLBACK ENDIF | Check for update conflicts and update as appropriate.

Updating Batches of Records in Remote Tables

To process a batch of changes against remote tables, use manual transactions: begin with TABLEUPDATE( ) and finish processing with either SQLCOMMIT( ) or SQLROLLBACK( ).

To set the connection to manage your transactions manually, you need to use CURSORGETPROP( ) on the view cursor to get the connection handle, then set the Transactions property to manual mode.

In the following code, the current connection identification for the view, myview, is stored into hConn1. hConn1 is used to set the Transactions property to "2" for manual transactions.

Copy Code
hConn1 = CURSORGETPROP("CONNECTHANDLE","myview") ;
SQLSETPROP(hConn1,"TRANSACTIONS",2)

After you set the connection to handle the updates, you can use TABLEUPDATE( ) to handle your transactions.

If the host tables reside on a remote server, such as SQL Server, you might use the following code as a guideline.

Updating remote tables with offline views

Code | Comment
USE myofflineview ONLINE EXCLUSIVE | Reconnect to the host and open the view.
SQLSetProp(liviewhandle,"transactions",2) SQLSetProp(custviewhandle,"transactions",2) SQLSetProp(ordviewhandle,"transactions",2) | Setting the connections on the views to handle transaction manually.
IF NOT TABLEUPDATE(.T.,.F.,"lineitemsview") =SQLROLLBACK(ordviewhandle) =MESSAGEBOX("Can't update line items table") IF NOT TableUpdate(.T.,.F.,"ordersview") =SQLROLLBACK(liviewhandle) =MESSAGEBOX("unable to update the orders table") IF NOT TABLEUPDATE(.T.,.F.,"customerview") =SQLROLLBACK(custviewhandle) =MESSAGEBOX("Can't update customer table") Else *# check out failure scenarios IF NOT SQLCOMMIT(liviewhandle) =SQLROLLBACK(liviewhandle) IF NOT SQLCOMMIT(ordviewhandle) =SQLROLLBACK(ordviewhandle) IF NOT SQLCOMMIT(custviewhandle) =SQLROLLBACK(custviewhandle) ENDIF ENDIF ENDIF ENDIF ENDIF ENDIF | Handling updates and update conflicts.

Updating One Record

If you are updating a single row, you can use automatic transactions. Because each statement to process an update, delete, or insert is handled as a separate transaction, rollbacks against prior transaction statements are not possible.

Copy Code
USE customerview ONLINE EXCLUSIVE
GO TO 3
   IF TABLEUPDATE (0, .F. workarea)
      * conflict handling code
   ENDIF
Tip:
To update a single record in a local table, use the GETNEXTMODIFIED( ) function.

Canceling Offline Updates

If you decide you want to delete the offline data and convert the view back to an online view, you can use the DROPOFFLINE( ) function.

To cancel offline updates, use DROPOFFLINE( ) with the name of the view.

Be sure to check the return values. True (.T.) indicates success and false (.F.) indicates that the view was not closed before the command was issued.

The following code drops all of the changes made to the subset of data in myview. The view remains part of the database, but its current set of data is dropped:

Copy Code
DROPOFFLINE("myview")

You can delete offline records, but you can't use the PACK, ZAP, or INSERT commands with an offline view.

See Also

Other Resources

Manipulating Offline Data
How to: Optimize View Performance
How to: Create Queries
How to: Set the Maximum Number of Records Downloaded
USE Command
TABLEUPATE( ) Function
SQLCOMMIT( ) Function


How to: Optimize View Performance

Visual FoxPro 9.0
How to: Optimize View Performance
See Also

You can optimize your views by setting data fetching and performance options. Use the Advanced Options dialog box to fine tune how records are retrieved in a view or how updates are made to the server or source tables.

To set advanced options

  1. From the Query menu, choose Advanced Options.

  2. In the Advanced Options dialog box, set the connection information and data fetching options you need.

  3. Choose OK.

You can control the number of rows Visual FoxPro progressively fetches at one time from the host database with the Fetchsize view and cursor property using the DBSETPROP( ) and CURSORSETPROP( ) functions. For more information, see DBSETPROP( ) Function and CURSORSETPROP( ) Function.

You can use the delayed memo-fetching feature to speed retrieval of view data. When you choose delayed memo fetching, Visual FoxPro does not retrieve the contents of a Memo field until you choose to open and display the field. Because Visual FoxPro needs the key field and table name to locate a row on the remote data source, you must set the following properties using the DBSETPROP( ) and CURSORSETPROP( ) functions for delayed Memo fetching to work:

  • UpdateName property or UpdatableFieldList property

  • KeyField or KeyFieldList property

  • Tables property

However, you don't have to set the SendUpdates or Updatable properties to ON in order to make delayed memo fetching work.

See Also

Other Resources

Working with Views
How to: Update to Online Data
How to: Set the Maximum Number of Records Downloaded
How to: Create Queries
How to: Optimize Filters and Joins
How to: Share Connections for Multiple Remote Views
How to: Test a Connection for Availability
Advanced Options Dialog Box


How to: Set the Maximum Number of Records Downloaded

Visual FoxPro 9.0
How to: Set the Maximum Number of Records Downloaded
See Also

You can control the amount of data downloaded when you open a view by setting the MaxRecords property. When Visual FoxPro sends a SQL statement to the data source to create a view, the data source builds and stores a result set. The MaxRecords property specifies the maximum number of rows fetched from the remote result set into your view. The default setting is –1, which downloads all rows in the result set.

To control the number of rows downloaded into a view

  1. From the Tools menu, choose Options and select the Remote Data tab; then in the Remote view defaults area, next to the Maximum records to fetch box, clear All, enter a value in the text box, and then choose OK.

    -or-

  2. Use the MaxRecords property of the DBSETPROP( ) or CURSORSETPROP( ) function.

For example, the following code alters the view definition to limit the number of rows downloaded into the view to 50, regardless of the size of the result set built on the remote data source:

Copy Code
OPEN DATABASE testdata
USE VIEW remote_customer_view
?DBSETPROP ('Remote_customer_view', ;    'View','MaxRecords', 50)

You can use the CURSORSETPROP( ) function to set the MaxRecords limit for an active view.

Tip:
You can't use the MaxRecords property to stop a runaway query, because the MaxRecords property doesn't control the building of the result set. Use the QueryTimeOut property to control the execution time on the remote data source.

See Also

Other Resources

How to: Optimize View Performance
How to: Optimize Filters and Joins
How to: Create Queries
How to: Share Connections for Multiple Remote Views
How to: Test a Connection for Availability


How to: Optimize Filters and Joins

Visual FoxPro 9.0
How to: Optimize Filters and Joins
See Also

To make optimization decisions for a view or query, you might need to know the execution plan: the order that joins and filter clauses will be evaluated. Using the SYS(3054) function, you can display one of three Rushmore Query Optimization levels. The three levels indicate the degree to which the filter conditions or join conditions were able to use Rushmore optimization. The levels are completely (Full), partially (Partial) or not at all (None).

To display the execution plan for filters

  1. In the Command window, type SYS(3054,1) to enable SQL ShowPlan.

  2. Type your SQL SELECT statement.

    For example, you might type:

    Copy Code
    SELECT * FROM customer, orders ;
AND Upper(country) = "MEXICO"

  3. On the screen, read the execution plan.

    For this example, the screen might display:

    Copy Code
    Using Index Tag Country to optimize table customer
Rushmore Optimization Level for table customer: Full
Rushmore Optimization level for table orders: none

  4. In the Command window, type SYS(3054,0) to turn off SQL ShowPlan.

You can then pass 11 to the SYS function to evaluate joins in the FROM or WHERE clauses.

To display the execution plan for joins

  1. In the Command window, type SYS(3054,11) to enable SQL ShowPlan.

  2. Enter your SQL SELECT statement.

    For example, you might type:

    Copy Code
    SELECT * ;
FROM customer INNER JOIN orders ;
   ON customer.cust_id = orders.cust_id ;
WHERE Upper(country) = "MEXICO"

  3. On the screen, read the execution plan.

    For this example, the screen might display:

    Copy Code
    Using Index Tag Country to optimize table customer
Rushmore Optimization Level for table customer: Full
Rushmore Optimization level for table orders: none
Joining table customer and table orders using Cust_id

  4. In the Command window, type SYS(3054,0) to turn off SQL ShowPlan.

Controlling Join Evaluation

If the execution plan for your joins does not match your specific needs, you can force your join order to execute exactly as written without optimization from the processor.

To force the evaluation order of the join

  • Add the FORCE keyword and place your join conditions in the FROM clause.

    Note:
    Note Join conditions placed within the WHERE clause are not included in a forced join evaluation.
Note:
You can't use the FORCE keyword in SQL pass-through statements or remote views because this keyword is a Visual FoxPro extension of the ANSI standard and is not supported in other SQL dictionaries. The FORCE clause is global and therefore applies to all tables in the JOIN clause. Be sure that the order in which the join tables appear is exactly the order in which they should be joined. You can also use parentheses to control the evaluation order of joins.

In this example, the first join specified is also the first join evaluated. The Customer table is joined with the Orders table first. The result of that join is then joined with the OrdItems table:

Copy Code
SELECT * ;
   FROM FORCE Customers ;
   INNER JOIN Orders ;
      ON Orders.Company_ID = Customers.Company_ID ;
   INNER JOIN OrItems;
      ON OrdItems.Order_NO = Orders.Order_NO

In this example, the join within the parentheses for the table Orders and OrdItems is evaluated first. The result of that join is then used in the evaluation of the join with Customers:

Copy Code
SELECT * ;
FROM FORCE Customers ;
   INNER JOIN (orders INNER JOIN OrdItems ;
      ON OrdItems.Order_No = Orders.Order_No) ;
      ON Orders.Company_ID = Customers.Company_ID

See Also

Other Resources

How to: Set the Maximum Number of Records Downloaded
How to: Optimize View Performance
How to: Create Queries
How to: Share Connections for Multiple Remote Views
How to: Test a Connection for Availability
SYS(3054)


How to: Share Connections for Multiple Remote Views

Visual FoxPro 9.0
How to: Share Connections for Multiple Remote Views
See Also

You can use one active connection as the information pipeline for multiple remote views by sharing a connection. When you share an active connection, you:

  • Reduce the number of connections on a remote server.

  • Reduce costs for connections to servers that charge on a per-connection basis.

You share connections by setting the view definition to use a shared connection upon activation. When the view is used, Visual FoxPro connects to the remote data source using the existing shared connection (if any). If a shared connection isn't in use, Visual FoxPro creates a unique connection when the view is opened, which can then be shared with other views.

Only one active instance of a named connection definition is shared during a Visual FoxPro session. If multiple instances of the same connection definition are active, the first instance to be used as a shared connection becomes the designated shared connection. All views that use that connection definition and employ connection sharing will access the remote server through the designated shared connection.

Connections other than the designated shared connection are not shared. Connection sharing is not scoped to sessions.

To share a connection

  • From the Tools menu, choose Options and select the Remote Data tab; then select Share connection in the Remote view defaults area and choose OK.

    -or-

  • Use the View Designer.

    -or-

  • Use the CREATE SQL VIEW command with the SHARE clause.

The following code creates a view that, when activated with the USE Command, shares a connection:

Copy Code
CREATE SQL VIEW product_view_remote ;
   CONNECTION remote_01 SHARE AS ;
   SELECT * FROM products
USE product_view_remote

See Also

Other Resources

How to: Optimize View Performance
How to: Optimize Filters and Joins
How to: Create Queries
How to: Test a Connection for Availability


How to: Test a Connection for Availability

Visual FoxPro 9.0
How to: Test a Connection for Availability
See Also

When a connection is busy, such as when Visual FoxPro is progressively fetching data into a cursor, you don't want to start another fetch or send updates on the same connection. You can determine whether a connection is busy with the ConnectBusy property, which returns a value of true (.T.) if the connection is busy. You can use this property in your application to test a connection before sending a request over a shared connection to a remote data source.

To determine whether a connection is busy

  • Use the ConnectBusy property of the SQLGETPROP( ) Function.

You need the connection handle to use the SQLGETPROP( ) function. You can identify the connection handle for an active view with the ConnectHandle property of the CURSORGETPROP( ) Function. The following code identifies a connection handle and then uses the connection handle to test whether the connection is busy:

Copy Code
nConnectionHandle=CURSORGETPROP('ConnectHandle')
SQLGETPROP(nConnectionHandle, "ConnectBusy")

See Also

Other Resources

How to: Optimize View Performance
How to: Optimize Filters and Joins
How to: Create Queries
How to: Share Connections for Multiple Remote Views


Importing and Exporting Data

Visual FoxPro 9.0
Importing and Exporting Data

You can copy data between Visual FoxPro and other applications by importing to and exporting from Visual FoxPro. The data can be in any one of a variety of text, spreadsheet, and table file formats. You can create a new Visual FoxPro table, add to an existing Visual FoxPro table, or copy data to a different file type.

In This Section

Importing and Exporting Concepts

When you import or append data, you bring the data from another application into Visual FoxPro. When you export data, you send data from a Visual FoxPro table to a file type used by another application.
Importing Data

If you want to import from your source file, you can either let Visual FoxPro define the structure of the new table or use the Import Wizard to specify its structure.
Appending Data

You can add your text, spreadsheet, or table data to an existing Visual FoxPro table. By default, Visual FoxPro uses the file type to map the source fields to the destination table.
Exporting Data

You can export data from your Visual FoxPro tables to text files, spreadsheets, or tables used in other applications.
Data Access Management Using CursorAdapters

Describes support for working with different data source types as native Visual FoxPro cursors using CursorAdapter objects.
Converting Between XML and Visual FoxPro Data

Introduces exchanging data more easily with other applications by converting Visual FoxPro data to XML format.
XML Functionality Using XMLAdapters

Discusses the extension of Visual FoxPro's XML features and compatibility with XML DiffGram and .NET Framework ADO.NET DataSet formats and supporting hierarchically formatted XML.

Related Sections

Working with Data

Find out how to create effective applications with indexes, tables, and databases based on your data requirements.
Using Visual FoxPro

Visual FoxPro programming features are designed to improve developer productivity, including Access and Assign methods, support for more graphic file formats, and language to simplify programming tasks.
Developing Visual FoxPro Applications

This section includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Visual FoxPro is a powerful interactive data management tool, but you also can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Importing and Exporting Concepts

Visual FoxPro 9.0
Importing and Exporting Concepts
See Also

You can choose from three ways to copy data into or out of Visual FoxPro:

  1. Importing

  2. Appending

  3. Exporting

When you import or append data, you bring the data from another application into Visual FoxPro. When you export data, you send data from a Visual FoxPro table to a file type used by another application. These methods allow you to copy and use, rather than link or share, the data.

When you import data, you copy data from a source file, create a new table, and populate the table with the file's data. For example, you can import the data from a dBASE table to create a Visual FoxPro table. After importing a file, you can use it like any other Visual FoxPro table.

When you append data, you add the source data to a Visual FoxPro table after the last record in the table. You can specify fields to import and select records that meet a condition in an expression. After appending from the file, you can view and edit the records in the Visual FoxPro table.

When you export, you copy data from a Visual FoxPro table into a new file formatted for use in another application. For example, you can export Visual FoxPro data to a Microsoft Excel worksheet file.

You select the source and destination files. You can also specify fields to export, set the scope of records to export, and select records that meet a condition.

See Also

Other Resources

Importing and Exporting Data
Importing Data
Appending Data
Exporting Data


Importing Data

Visual FoxPro 9.0
Importing Data
See Also

If you want to import from your source file, you can either let Visual FoxPro define the structure of the new table or use the Import Wizard to specify its structure. Visual FoxPro uses the field order in the source file to define the structure of the destination table. If you want to define the structure, you can modify the file in the source application or use the Import Wizard.

If you no longer have access to the application that supports the source file and you want to change the order or data type of the fields, you can import the source file, then create a query that outputs the fields in the order you want to another new table.

When you import a file, you must choose the file type you want to import and specify the source file and destination table names.

Choosing a File Type to Import

The following table lists the file types you can import into Visual FoxPro:

File Type | File Extension | Description
Microsoft Excel | xls | A Microsoft Excel (versions 2.0, 3.0, 4.0, 5.0, and 97) worksheet format. The column cells become fields, and rows become records.
Lotus 1-2-3 | wks wk1 wk3 | A Lotus 1-2-3 spreadsheet for releases 1-A, 2.x, and 3.x. The column cells become fields and rows become records.
Borland Paradox | db | A Paradox table for versions 3.5 and 4.0.

If you want to use tables from a previous version of FoxPro or use dBASE files, you can open and use them without importing. Visual FoxPro will ask if you want to convert the table to the latest version of Visual FoxPro. Once you convert a table from a previous version, this table cannot be opened in the previous version.

For more information on importing files, see the IMPORT command.

See Also

Other Resources

Importing and Exporting Data
How to: Import Data with the Import Wizard
How to: Import Data into New Tables
How to: Import from Lotus 1-2-3
How to: Translate Lotus Date Fields
How to: Import from Microsoft Excel


How to: Import Data with the Import Wizard

Visual FoxPro 9.0
How to: Import Data with the Import Wizard
See Also

The Import Wizard helps you to create a new table from your source file. The wizard asks you a series of questions, imports the file based on your answers, and allows you to control how the new table is structured.

To import a file with the Import Wizard

  1. From the File menu, choose Import.

  2. From the Import dialog box, choose Import Wizard.

  3. Follow the instructions on the wizard screens.

See Also

Other Resources

Importing Data
How to: Import Data into New Tables
How to: Import from Lotus 1-2-3
How to: Translate Lotus Date Fields
How to: Import from Microsoft Excel


How to: Import Data into New Tables

Visual FoxPro 9.0
How to: Import Data into New Tables
See Also

You can import data from a table or spreadsheet format using the source file's structure to define the new table.

To import data to a new table

  1. From the File menu, choose Import.

  2. In the Type box, enter the format of the file you want to import.

  3. In the From box, enter the name of the source file.

  4. If you selected a spreadsheet in the Type box, enter the sheet number in the Sheet box that appears.

  5. Choose OK.

    Visual FoxPro creates a new table using the source file.

If you want to import to a new table from a text file without using the Import Wizard, you need to create a new table with fields that match the order, data type, and width of the fields in the text file and then append the text to the new table.

After importing the file, you can add the new table to the database of your choice. You can also modify the new table using the Table Designer.

See Also

Other Resources

Table Creation
Table Designer
How to: Import Data with the Import Wizard
Importing Data
Appending Data
How to: Import from Lotus 1-2-3
How to: Translate Lotus Date Fields
How to: Import from Microsoft Excel


How to: Import from Lotus 1-2-3

Visual FoxPro 9.0
How to: Import from Lotus 1-2-3
See Also

When you import spreadsheet data, Visual FoxPro uses the first row in your Lotus 1-2-3 spreadsheet to determine the data types of the fields in the new table. If the first row has literal text headings for each column, all the fields in the table will be character fields, even if the rest of the rows contain numeric data.

To make sure fields have the appropriate data type

  • In Lotus 1-2-3, modify the spreadsheet so that the first row contains the first record of data you want in the table.

    Caution:
    If your worksheet is from version 2.x or 3.x (file extension .wk1 or .wk3) and has columns with more than eight or nine characters, Visual FoxPro truncates character fields to nine characters for version 2.x worksheets and eight characters for version 3.x. To prevent truncated fields in your table, you can use the Import Wizard or create a Visual FoxPro table, then append records from the worksheet.

Lotus stores dates as the non-negative number of days from January 1, 1900. If the new table does not have the correct data type, you can translate the Lotus date fields in Visual FoxPro.

See Also

Other Resources

How to: Import Data with the Import Wizard
Importing Data
Appending Data
How to: Translate Lotus Date Fields
How to: Import from Microsoft Excel


How to: Translate Lotus Date Fields

Visual FoxPro 9.0
How to: Translate Lotus Date Fields
See Also

If Lotus date fields imported incorrectly, you can translate them by adding the Julian date for January 1, 1900 (the value 2415019) to the date value in the field.

To translate Lotus date fields

  1. Import the spreadsheet to a Visual FoxPro table.

  2. Use the Table Designer to modify the table and add a new date field to the table.

  3. If the date was imported as a numeric value, use the REPLACE command and CTOD( ) function to copy the date to the new field:

    Copy Code
    REPLACE ALL NewDateField ;
   WITH CTOD(SYS(10,OldDateField+2415019))

    -or-

    If the date was imported as a character value, use the following command to copy the date to the new field:

    Copy Code
    REPLACE ALL NewField ;
   WITH CTOD(SYS(10,VAL(OldField)+2415019))

  4. From the table, delete the original, incorrect date field.

See Also

Other Resources

Importing Data
Appending Data
How to: Import Data with the Import Wizard
How to: Import from Lotus 1-2-3
How to: Import from Microsoft Excel


How to: Import from Microsoft Excel

Visual FoxPro 9.0
How to: Import from Microsoft Excel
See Also

When you import worksheet data, Visual FoxPro uses the first row in your Microsoft Excel worksheet to determine the data types of the fields in the new table. If the first row has literal text headings for each column, all the fields in the table will be character fields, even if the rest of the rows contain numeric data.

To make sure fields have the appropriate data type

  • In Microsoft Excel, modify the worksheet so that the first row contains the first record of data you want in the table.

    Caution:
    If a field in your Microsoft Excel worksheet has a field length of 255, that field is truncated to 254 when it is imported to a Visual FoxPro table.

See Also

Other Resources

Appending Data
How to: Import Data with the Import Wizard
Importing Data


Appending Data

Visual FoxPro 9.0
Appending Data
See Also

You can add your text, spreadsheet, or table data to an existing Visual FoxPro table. By default, Visual FoxPro uses the file type to map the source fields to the destination table. You can also select fields and records to append. If you want to control the field mapping, you can use theImport Wizard, but field selection and logical expression options are not available.

Choosing a File Type to Append

The following table lists the file types you can append to Visual FoxPro:

File Type | File Extension | Description
Table | dbf | A FoxPro® table from a database outside the current database or a dBASE file.
Tab delimited | txt | A text file with a tab separating each field.
Comma delimited | txt | A text file with a comma separating each field.
Space delimited | txt | A text file with one space separating each field.
System Data Format | sdf | A text file with fixed length records ending with a carriage return and line feed.
Microsoft Excel | xls | A Microsoft Excel (versions 2.0, 3.0, 4.0, 5.0, and 97) worksheet format. The column cells become fields and rows become records.
Lotus 1-2-3 | wks wk1 wk3 | A Lotus 1-2-3 spreadsheet for releases 1-A, 2.x, and 3.x. The column cells become fields and rows become records.
Borland Paradox | db | A Paradox table for versions 3.5 and 4.0.

For more information on appending files, see the APPEND FROM command.

See Also

Other Resources

How to: Append Data with the Import Wizard
Importing and Exporting Data
How to: Append Data to Existing Tables
How to: Select Fields to Append
How to: Select Records to Append
Importing Data


How to: Append Data with the Import Wizard

Visual FoxPro 9.0
How to: Append Data with the Import Wizard
See Also

The Import Wizard asks you a series of questions and appends the data from the source file based on your answers. Using the wizard, you can choose to map the source fields to the destination fields by changing the column numbers.

To append from a file with the Import Wizard

  1. From the File menu, choose Import.

  2. From the Import dialog box, choose Import Wizard.

  3. Follow the instructions on the wizard screens.

See Also

Other Resources

Appending Data
How to: Append Data to Existing Tables
How to: Select Fields to Append
How to: Select Records to Append
Exporting Data


How to: Append Data to Existing Tables

Visual FoxPro 9.0
How to: Append Data to Existing Tables
See Also

You can add records to the active table from another file. By default, Visual FoxPro adds all of the records and fields to the table. Using Append From options, you can specify fields or select records. For more information about field and record selection, see the sections How to: Select Fields to Append and How to: Select Records to Append.

To append data

  1. Browse the destination table.

  2. From the Table menu, choose Append Records.

  3. In the Type box, enter the format of the source file.

  4. In the From box, enter the name of the source file.

  5. In the To box, make sure the correct table name is showing.

    Tip:
    If the table name is not correct, choose Cancel, and then open the correct destination table. The To box shows the table active at the time you selected the Append From command.

  6. If you want to specify fields or select records to append, choose Options and complete the Options dialog box.

  7. Choose OK.

    Visual FoxPro adds the records to the table.

See Also

Other Resources

How to: Append Data with the Import Wizard
How to: Select Fields to Append
How to: Select Records to Append
Exporting Data


How to: Select Fields to Append

Visual FoxPro 9.0
How to: Select Fields to Append
See Also

You may want to append only certain fields from your source file. You can select the fields to include in the Append From process.

To select fields to append

  1. From the Table menu, choose Append Records.

  2. In the Append From dialog box, enter the source file type and name, and then choose Options.

  3. In the Append From Options dialog box, choose Fields. The Field Picker dialog box displays the fields in the destination table.

  4. Select fields that match those you want to append from the source file and choose move, then choose OK.

    The fields you select appear in the Selected Fields box.

  5. Choose OK.

See Also

Other Resources

How to: Append Data to Existing Tables
How to: Select Records to Append
Exporting Data
How to: Append Data with the Import Wizard


How to: Select Records to Append

Visual FoxPro 9.0
How to: Select Records to Append
See Also

If you only want to append certain records, you can use a FOR expression. Visual FoxPro uses the expression to search the entire file and append only records that match the expression you provide. The fields you specify in the FOR expression must exist in both the source and destination files.

To select records to append

  1. Browse the destination table, and then from the Table menu, choose Append Records.

  2. Enter the source file type and name, and then choose Options.

  3. Choose For to build an expression in the Expression Builder dialog box.

    Note:
    You do not need to enter the command FOR because it is implied. For example, type customer.country = "Canada" to append only Canadian information.

  4. Choose OK.

If you append from a text file, Visual FoxPro assumes your fields are separated by commas and that each character field is enclosed by quotation marks. If you have set the decimal point character to display as a comma, numeric and currency data might be parsed into separate fields.

For example, Visual FoxPro translates the value 100,00 into two fields because it appears to be delimited with a comma. Choose one of two methods to make sure the comma is properly translated:

  • Use tabs to separate fields in the text file.

  • Change the decimal point character back to a period.

If you want to append from a text file, change the field separators to tabs, then use the APPEND FROM command with the keywords DELIMITED WITH TAB.

If you want to change the decimal point character to a period before appending text files, you can change the character back to a comma after you append the file.

To change the decimal point character

  1. In the Command window, type the following command.

    Copy Code
    SET POINT TO

  2. Import the file using the DELIMITED keyword.

  3. In the Command window, type the following command to reset the decimal point character to a comma.

    Copy Code
    SET POINT TO ','

See Also

Other Resources

How to: Append Data with the Import Wizard
How to: Select Fields to Append
Exporting Data
Importing and Exporting Data
Appending Data


Exporting Data

Visual FoxPro 9.0
Exporting Data
See Also

You can export data from your Visual FoxPro tables to text files, spreadsheets, or tables used in other applications. The exporting process requires a source table and the destination's file type and name. If you want, you can select which fields and record to export. You can use the new file in any application that supports the file type you select.

Choosing a File Type to Export

The following table lists the file types you can export from Visual FoxPro.

File type | File extension | Description
Tabs delimited | txt | A text file with a tab separating each field.
Comma delimited | txt | A text file with a comma separating each field.
Spaces delimited | txt | A text file with one space separating each field.
System Data Format | sdf | A text file with fixed length records ending with a carriage return and line feed.
Table | dbf | A Visual FoxPro, FoxPro, FoxBASE+®, dBASE, or Paradox 3.5 or 4.0 table.
Microsoft Excel | xls | A Microsoft Excel (versions 2.0, 3.0, 4.0, 5.0, and 97) worksheet format. The column cells become fields and rows become records. You can export a maximum of 65,535 rows, which includes one row reserved for the field header.
Lotus 1-2-3 | wks wk1 | A Lotus 1-2-3 spreadsheet for releases 1-A, 2.x, and 3.x. The column cells become fields and rows become records.

For more information on exporting, see the COPY TO command.

See Also

Other Resources

How to: Export Data to New Files
Importing and Exporting Data
How to: Export a Quantity or Range of Records
How to: Export Records That Match Conditions
How to: Control the Record Export Process
How to: Export Text Files
How to: Export Numeric or Currency Values


How to: Export Data to New Files

Visual FoxPro 9.0
How to: Export Data to New Files
See Also

You can copy all of the fields and records from your Visual FoxPro table to a new file or you can copy only the fields and records you select.

To export data

  1. From the File menu, choose Export.

  2. In the Type box, enter the destination file type.

  3. In the To box, enter the destination file name.

  4. In the From box, enter the source file name.

  5. If you want to select fields or records to export, choose Options and complete the Export Options dialog box.

  6. Choose OK.

By default, Visual FoxPro exports all of the fields in the source table to the destination file. You can select which fields to export by using the Export Options dialog box.

To select fields to export

  1. From the File menu, choose Export.

  2. In the Export dialog box, enter the destination file type and name.

  3. In the From box, enter the source file name.

  4. Choose Options.

  5. Choose Fields and select the fields from the Field Picker dialog box.

  6. Choose OK.

When you export data, you might want to limit the number of records that are copied to the new file by providing selection criteria. You can:

  • Choose a scope of records by specifying a quantity or range.

  • Build a FOR expression that selects records that match a condition.

  • Build a WHILE expression that selects records until one record is found that does not match a condition.

You can use any combination of these options. The WHILE expression overrides the other criteria.

See Also

Other Resources

Exporting Data
How to: Export a Quantity or Range of Records
How to: Export Records That Match Conditions
How to: Control the Record Export Process
How to: Export Text Files
How to: Export Numeric or Currency Values


How to: Export a Quantity or Range of Records

Visual FoxPro 9.0
How to: Export a Quantity or Range of Records
See Also

One way you can limit the number of records is to specify a quantity or range of records. Using the Scope option, you can export a single record or a group of records positioned sequentially in the file.

Note:
The active index and the current record pointer affect the results of the scope options Next and Rest. For example, the next record in a table indexed by last name is probably different than one in a table indexed by state. This does not affect the Record option because the number for a record does not change when the table is indexed.

To export a limited number of records

  1. From the File menu, choose Export.

  2. Enter the source table and destination file information.

  3. Choose Options.

  4. Choose Scope.

  5. Select the appropriate Scope option and complete the Scope dialog box.

    To export Choose

    Every record from the source file

    All

    A range of records starting with current record

    Next

    A specific record by number

    Record

    The current record plus all of those after it to the end of the file

    Rest

  6. Choose OK.

    Visual FoxPro exports records within the scope you select.

See Also

Other Resources

How to: Export Data to New Files
Importing and Exporting Data
How to: Export Records That Match Conditions
How to: Control the Record Export Process
How to: Export Text Files
How to: Export Numeric or Currency Values
Exporting Data


How to: Export Records That Match Conditions

Visual FoxPro 9.0
How to: Export Records That Match Conditions
See Also

If the records you want to export are not sequential within the table, you can build a logical expression that specifies the selection criteria a record must meet to be exported. For example, you can choose to export all records with a particular value in a field.

To enter criteria for exporting records

  1. From the File menu, choose Export.

  2. Enter the source table and destination file information.

  3. Choose Options.

  4. Choose For to build an expression in the Expression Builder dialog box.

    Note:
    You do not need to include the FOR command in the expression. For example, type customer.country = "Canada" to export only Canadian data.

  5. Choose OK.

    Visual FoxPro evaluates all of the records and exports those that match the condition in the expression.

See Also

Other Resources

How to: Export Data to New Files
How to: Export a Quantity or Range of Records
How to: Control the Record Export Process
How to: Export Text Files
How to: Export Numeric or Currency Values
Exporting Data


How to: Control the Record Export Process

Visual FoxPro 9.0
How to: Control the Record Export Process
See Also

When exporting, you can specify a condition that must be met to continue evaluating and selecting records. You enter this condition as a WHILE expression.

As long as the WHILE expression remains true, Visual FoxPro processes the source table. After finding a record that does not meet the condition, Visual FoxPro ends the evaluation process and exports the selected records. This option allows you to export records based on information outside of the values contained in the fields.

Tip:
If you use a WHILE expression on a file that has not been indexed, the export process may end before evaluating all of the appropriate records. Before performing the export procedure, be sure the source table has the appropriate index active for the WHILE expression you want to use.

To enter criteria for ending record export

  1. From the File menu, choose Export.

  2. Enter the source table and destination file information.

  3. Choose While to build an expression in the Expression Builder dialog box.

    Note:
    You do not need to include the WHILE command in the statement. For example, type sales > 1000 to see only sales above one thousand dollars.

  4. Choose OK.

    Visual FoxPro exports the records it evaluates while the expression is true.

See Also

Other Resources

How to: Export Data to New Files
How to: Export a Quantity or Range of Records
How to: Export Records That Match Conditions
How to: Export Text Files
How to: Export Numeric or Currency Values
Exporting Data


How to: Export Text Files

Visual FoxPro 9.0
How to: Export Text Files
See Also

If you export to a text file, Visual FoxPro assumes that your fields are separated by commas and that each character field is enclosed by quotation marks. If you have set the decimal point character to display as a comma, numeric and currency data might be parsed into separate fields.

To export to a text file

  • Use the COPY TO Command with the appropriate DELIMITED clause as shown in the following table.

    For these separators Use this DELIMITED clause

    Commas between fields and quotation marks enclosing character fields

    DELIMITED

    Character fields enclosed by a character other than quotation marks

    DELIMITED WITH delimiter

    Tabs between fields

    DELIMITED WITH TAB

    Spaces between the fields

    DELIMITED WITH BLANK*

    * Date and times separated by a space will be parsed as two fields with these keywords

See Also

Other Resources

How to: Export Data to New Files
How to: Export a Quantity or Range of Records
How to: Export Records That Match Conditions
How to: Control the Record Export Process
How to: Export Numeric or Currency Values
Exporting Data


How to: Export Numeric or Currency Values

Visual FoxPro 9.0
How to: Export Numeric or Currency Values
See Also

If you changed the Visual FoxPro decimal point character to a comma, numeric and currency data might be parsed into separate fields when you append or export the data. For example, Visual FoxPro would translate the value 100,000 into two fields because it appears to be delimited with a comma. Choose one of two methods to make sure the comma is properly translated:

  • Use tabs to separate fields in the text file

  • Change the decimal point character back to a period

If you want to export the text, use the COPY TO Command with the keywords DELIMITED WITH TAB.

If you want to change the decimal point character to a period before exporting text files, you can change the character back to a comma after you export the file.

To change the decimal point character

  1. In the Command window, type the following command.

    Copy Code
    SET POINT TO

  2. Export the file using the DELIMITED keyword.

  3. In the Command window, type the following command to reset the decimal point character to a comma.

    Copy Code
    SET POINT TO ','

See Also

Other Resources

How to: Export Data to New Files
How to: Export a Quantity or Range of Records
How to: Export Records That Match Conditions
How to: Control the Record Export Process
How to: Export Text Files
Exporting Data


Data Access Management Using CursorAdapters

Visual FoxPro 9.0
Data Access Management Using CursorAdapters
See Also

In Visual FoxPro, you can retrieve data from local and remote data sources that have the following data source types using cursor adapters:

  • Native

  • Open Database Connectivity (ODBC)

  • ActiveX Data Object (ADO)

  • Extensible Markup Language (XML)

The CursorAdapter class expands support for working with different data source types as native Visual FoxPro cursors. CursorAdapter objects provide the following capabilities:

  • Use different data sources dynamically.

  • Use either the data source of the CursorAdapter object or the data environment.

  • Share data sources within the limits of the data source technology.

  • Optionally define the structure of the cursor associated with a CursorAdapter object.

  • Control the loading of data from the data source into a Visual FoxPro cursor associated with a CursorAdapter object.

  • Render data from different data sources into Visual FoxPro cursors based on the data source type.

  • Control how data is added, updated, and deleted with CursorAdapter properties and methods.

  • Add CursorAdapter objects to containers other than the data environment, such as forms, form sets, and other containers.

  • Use the CursorAdapter class as a standalone class without an associated data environment.

With CursorAdapter objects, the data source is only a pipe to the translation layer, which renders data from the data source into a Visual FoxPro cursor.

Note:
Visual FoxPro does not support using relations with the CursorAdapter objects. However, you can use relations with cursors associated with cursor adapters.

For more information about the CursorAdapter, DataEnvironment, and Cursor classes, see CursorAdapter Class, DataEnvironment Object, and Cursor Object.

Interaction with the TABLEUPDATE( ) and TABLEREVERT( ) Functions

The TABLEUPDATE( ) function recognizes and can work with CursorAdapter objects. TABLEUPDATE( ) delegates its operations to the cursor adapter associated with the cursor. TABLEREVERT( ) operates on CursorAdapter objects in the same way as other buffered cursors.

For more information about how CursorAdapter objects affect the way the TABLEUPDATE( ) and TABLEREVERT( ) functions behave, see TABLEUPDATE( ) Function and TABLEREVERT( ) Function.

Automatic Updating and CursorAdapters

Visual FoxPro automatically generates the SQL INSERT, UPDATE, and DELETE commands for local and remote views. When working with CursorAdapter objects, you can customize and control how Visual FoxPro generates these SQL INSERT, UPDATE, and DELETE commands.

When the CursorAdapter InsertCmd, UpdateCmd, and DeleteCmd properties are empty, Visual FoxPro generates the corresponding SQL commands automatically. You must determine whether automatic generation of these commands is appropriate for the data source you are using. To generate the SQL INSERT, UPDATE, and DELETE commands automatically, you must set the following CursorAdapter-specific properties:

  • Tables

  • KeyFieldList

  • UpdatableFieldList

  • UpdateNameList

The following general rules apply for the Tables and UpdateNameList properties:

  • Tables

    To enable automatic updating, you must provide a list of table names in the exact order you want them to appear in the SQL INSERT, UPDATE, and DELETE commands.

  • UpdateNameList

    You must specify a comma-delimited list consisting of pairs of local and full remote field names. Each pair of names consists of the local field name followed by the full remote field name. The full remote field name appears as <remote table name>.<remote field name>, where <remote table name> matches the name from the Tables property.

You must also set the appropriate key fields if you set the following CursorAdapter properties to True (.T.):

  • AllowInsert

  • AllowUpdate

  • AllowDelete

For more information about the SQL commands used for automatic updating, see INSERT - SQL Command, UPDATE - SQL Command, and DELETE - SQL Command.

Batch Updates

CursorAdapter objects use batch updating if the value of CursorAdapter BatchUpdateCount property is greater than 1, and one of the following conditions are true:

  • The CursorAdapter object is set up to use the same ODBC statement handle for all permitted operations, namely, INSERT, UDPATE, and DELETE, as defined by the AllowInsert, AllowUpdate, and AllowDelete properties.

  • The CursorAdapter object is set up to use the same ADODB Command object for all operations permitted.

  • The CursorAdapter object uses "XML" as the data source type for all permitted operations.

If batch updating is used, the following CursorAdapter events do not occur:

  • BeforeInsert

  • AfterInsert

  • BeforeUpdate

  • AfterUpdate

  • BeforeDelete

  • AfterDelete

If an update fails for a batch, Visual FoxPro attempts to send a separate update for each row in the batch; however, the listed events still do not occur.

For more information, see BatchUpdateCount Property.

Automatic Updating and ActiveX Data Objects (ADO)

When working with ADO, you can send updates using two different methods:

  • Use the CursorAdapter object to send updates with the ADO RecordSet object used by the CursorAdapter CursorFill method.

    When performing automatic updates using an ADO RecordSet, the following rules apply when setting the CursorAdapter InsertCmdDataSource, UpdateCmdDataSource, and DeleteCmdDataSource properties:

    • The ADO RecordSet must be read/write and have bookmarks available. Bookmarks are always available when using a client-side RecordSet object. Bookmarks might be available when using Keyset or Static server-side cursors when supported by the OLE DB Provider.

    • Updates are performed on a field-by-field basis. For every updated record, the CursorAdapter object locates the original record in the ADO RecordSet, changes the values for updatable fields, and calls the ADO RecordSet Update method. The CursorAdapter object does not call the ADO RecordSet UpdateBatch method; therefore, your application should explicitly call UpdateBatch when appropriate.

    When using this method, you should configure the CursorAdapter object as follows:

    Copy Code
    THIS.DataSourceType="ADO"
THIS.UpdateCmdDataSourceType=""
    You can also use the DataEnvironment and CursorAdapter builders to build an updatable form or DataEnvironment and CursorAdapter class library and use the AutoUpdate tab in the CursorAdapter Builder to specify key fields, update fields, and other required information.

  • Use the CursorAdapter object to send updates directly to the database using a custom or automatically generated update command.

    When performing automatic updates directly, the CursorAdapter object needs an ADO Command object with its ActiveConnection property set to an open ADO Connection object.

    When using this method, you should configure the CursorAdapter object as follows:

    Copy Code
    THIS.UpdateCmdDataSourceType="ADO"
THIS.UpdateCmdDataSource=NewADODBCommandObject
    Setting THIS.DataSourceType="ADO" does not apply when using this method.

Automatic Updating and XML

CursorAdapter objects do not automatically generate SQL INSERT, UPDATE, or DELETE commands as they do for other data sources when the data source is XML because of the numerous ways that exist for generating XML. However, you can use the CursorAdapter object to generate an XML UpdateGram and assign it to the CursorAdapter UpdateGram property.

Though the CursorAdapter object can generate the XML UpdateGram, you must implement the actual update operation using the appropriate protocols, such as SQL XML using HTTP, SQL XML OLE DB, or XML Web service to .NET.

The following rules apply when working with XML data sources and generating XML UpdateGrams:

  • You must specify command text for the CursorAdapter InsertCmd, UpdateCmd, and DeleteCmd properties that Visual FoxPro can execute for the appropriate insert, update, or delete operation. If using batch updating, that is CursorAdapter BatchUpdateCount property is greater than 1, UpdateCmd is executed only once per batch.

  • The following CursorAdapter properties must be set to "XML":

    • InsertCmdDataSourceType

    • UpdateCmdDataSourceType

    • DeleteCmdDataSourceType

    If these properties are not set to "XML", Visual FoxPro executes the command text in the UpdateCmd, InsertCmd, or DeleteCmd properties but does not generate an XML UpdateGram.

  • To construct the XML UpdateGram correctly, CursorAdapter requires that the Tables, UpdatableFieldList, and UpdateNameList properties contain valid values. CursorAdapter can generate a multiple table UpdateGram by specifying the tables and fields in the Tables, UpdatableFieldList, and UpdateNameList properties as appropriate. Therefore, you can update a cursor that represents a multi-table join using the XMLUPDATEGRAM( ) function. For more information, see XMLUPDATEGRAM( ) Function.

  • CursorAdapter uses the WhereType property to generate the before section for the XML UpdateGram. Therefore, when you perform an update or delete operation, the KeyFieldList and UpdatableFieldList properties must contain the appropriate key fields. For more information, see WhereType Property.

  • If row buffering is enabled, or BatchUpdateCount is 1, Visual FoxPro creates an XML UpdateGram for each update, insert, or delete operation.

    If table buffering is enabled, and if using batch updating, that is, BatchUpdateCount is greater than 1, Visual FoxPro creates an XML UpdateGram for the entire batch of changes. In this mode, you must call the TABLEUPDATE( ) function as expected to initiate the update and generation of the XML UpdateGram.

See Also

Other Resources

Importing and Exporting Data
CursorAdapter Class
CursorAdapter Object Properties, Methods, and Events


Converting Between XML and Visual FoxPro Data

Visual FoxPro 9.0
Converting Between XML and Visual FoxPro Data
See Also

You can exchange data more easily with other applications by converting Visual FoxPro data to XML format. Visual FoxPro includes the following functions so you can convert data between XML and Visual FoxPro format:

  • CURSORTOXML( ) Function

  • XMLTOCURSOR( ) Function

  • XMLUPDATEGRAM( ) Function

Note:
You must have the Microsoft XML Core Services (MSXML) parser installed before you can use the Visual FoxPro XML functions.

The following sections discuss considerations when converting between XML and Visual FoxPro data:

  • Processing XML Data in Variables or Strings Instead of Files

  • XML String Conversion

  • Importing and Exporting XML Using Schemas

You can override the internal functionality of the CURSORTOXML( ), XMLTOCURSOR( ), and XMLUPDATEGRAM( ) functions by referencing a COM component using the VFPXMLProgID property. For more information, see VFPXMLProgID Property.

Visual FoxPro supports hierarchically formatted XML for XML DiffGram and .NET Framework ADO.NET DataSet formats by providing the XMLAdapter, XMLTable, and XMLField classes. For more information, see XML Functionality Using XMLAdapters.

Processing XML Data in Variables or Strings Instead of Files

XMLTOCURSOR( ) processes data differently from a variable or string than from a file. When converting XML to a cursor, the method used to pass XML to the function affects how double-byte character sets (DBCS) characters in the XML are handled. DBCS characters are interpreted correctly when using a file for XMLSource. However, if you need to use a memory variable or string, you can force interpretation to DBCS by using the following code in XMLTOCURSOR( ):

Copy Code
STRCONV(string,11)

The following example opens the Visual FoxPro sample Customer table located in the Visual FoxPro ..\Samples\Data\ directory and converts the data in the Customer table and saves the data in the table to a memory variable, lcXML, as XML:

Copy Code
CLEAR
CLOSE DATABASES ALL
USE HOME()+'samples\data\customer'
CURSORTOXML('customer','lcXML',1,48,5,"","","")

The following line inserts incorrect characters in the resulting cursor:

Copy Code
XMLTOCURSOR(lcXML,"curCustomerList",4)

The following line uses the STRCONV( ) function and converts the XML to DBCS data correctly, opens a browse window for the table:

Copy Code
XMLTOCURSOR(STRCONV(lcXML,11),"curCustomerList",4)
BROWSE

XML String Conversion

XMLTOCURSOR( ) does not perform automatic conversions of XML strings, for example, from ANSI to UTF-8. This might occur when reading an XML string from a file. To perform a conversion, use the STRCONV( ) function.

The following example demonstrates the parse error that occurs when Visual FoxPro encounters the first ASCII character:

Copy Code
CLOSE DATABASE ALL
USE HOME(2)+"\data\customer"
CURSORTOXML("customer","lcXML",1,32)
STRTOFILE(lcXML,"customer.xml")
XMLTOCURSOR("customer.xml","curCustomer",512)
RETURN

You can prevent the parse error generated by converting the string to UTF-8 when the XML is written or when it is written to the file. The following example converts the string to UTF-8 as it is being written to the file by using the STRCONV( ) function with the STRTOFILE( ) function:

Copy Code
CLOSE DATABASE ALL
USE HOME(2)+"\data\customer"
CURSORTOXML("customer","lcXML",1,32)
STRTOFILE(STRCONV(lcXML,9),"customer.xml")
XMLTOCURSOR("customer.xml","curCustomer",512)
RETURN

In the example, you can use a value of 48 for the nFlag parameter in the STRCONV( ) function to create the XML encoded as UTF-8. However, this does not work for XML provided from an external source or with XML that is not generated with the CURSORTOXML( ) function.

For more information, see STRCONV( ) Function.

Importing and Exporting XML Using Schemas

When you import XML using the XMLTOCURSOR( ) function, Visual FoxPro uses an external or internal schema, if available, to determine the cursor or table structure before making a single pass to convert the data. When no schema is provided, Visual FoxPro makes two passes through the XML data: the first pass determines the data structure in the best possible way and the second to perform the conversion. The XML must generally conform to a format that can be interpreted as a table in addition to being well-formed. Well-formed XML that is not easily deconstructed into a table format will fail to import.

The following is an example of XSD schema generated by the Visual FoxPro CURSORTOXML( ) function:

Copy Code
<?xml version = "1.0" encoding="Windows-1252" standalone="yes"?>
<xsd:schema id="VFPSchema" targetNamespace="http://microsoft.com" xmlns="http://microsoft.com" xmlns:xsd="http://www.w3.org/2000/10/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" elementFormDefault="qualified">
   <xsd:element name="atxm">
      <xsd:complexType>
         <xsd:all>
            <xsd:element name="ikey" minOccurs="0" type="xsd:int"/>
            <xsd:element name="nc00" minOccurs="0">
               <xsd:simpleType>
                  <xsd:restriction base="xsd:decimal">
                     <xsd:precision value="10"/>
                     <xsd:scale value="4"/>
                  </xsd:restriction>
               </xsd:simpleType>
            </xsd:element>
            <xsd:element name="mc03" minOccurs="0">
               <xsd:simpleType>
                  <xsd:restriction base="xsd:string">
                     <xsd:maxLength value="2147483647"/>
                  </xsd:restriction>
               </xsd:simpleType>
            </xsd:element>
            <xsd:element name="cc04" minOccurs="0">
               <xsd:simpleType>
                  <xsd:restriction base="xsd:string">
                     <xsd:maxLength value="128"/>
                  </xsd:restriction>
               </xsd:simpleType>
            </xsd:element>
            <xsd:element name="lc05" minOccurs="0" type="xsd:boolean"/>
            <xsd:element name="fc06" minOccurs="0" type="xsd:double"/>
            <xsd:element name="yc07" minOccurs="0" type="xsd:decimal"/>
            <xsd:element name="ic08" minOccurs="0" type="xsd:int"/>
            <xsd:element name="bc09" minOccurs="0" type="xsd:double"/>
            <xsd:element name="dc10" minOccurs="0" type="xsd:date"/>
            <xsd:element name="tc11" minOccurs="0"
type="xsd:timeInstant"/>
            <xsd:element name="ts12" minOccurs="0">
               <xsd:simpleType>
                  <xsd:restriction base="xsd:binary">
                     <xsd:encoding value="base64"/>
                  </xsd:restriction>
               </xsd:simpleType>
            </xsd:element>
         </xsd:all>
      </xsd:complexType>
   </xsd:element>
   <xsd:element name="VFPData" msdata:lsDataSet="true">
      <xsd:complexType>
         <xsd:choice maxOccurs="unbounded">
            <xsd:element ref="atxm"/>
         </xsd:choice>
      </xsd:complexType>
   </xsd:element>
</xsd:schema>

Currently, Visual FoxPro exports XML in the following formats:

  • Element-centric Each field in a resulting or source cursor or table is represented by a sub-element of the top-level element.

    Copy Code
    <?xml version="1.0" encoding="Windows-1252" standalone="yes" ?>
<!-- Note targetNamespace in root (VfpData) element. If set to default (""), xmlns attrib is not written -->
<VfpData xmlns="http://www.microsoft.com">
   <alltypesxm>
      <ikey>2</ikey>
      <nc00>1.1111</nc00>
      <mc03>H1111111111111111111</mc03>
      <cc04>H111111111111111111</cc04>
      <lc05>true</lc05>
      <fc06>-1111000</fc06>
      <yc07>-111111111.1111</yc07>
      <ic08>-11111111</ic08>
      <bc09>-111111111111.1</bc09>
      <dc10>1999-03-02T08:00:00</dc10>
      <tc11>1999-03-02T09:01:01</tc11>
      <ts12>AAAAAAAAAr8=</ts12>
   </alltypesxm>
</VfpData>
  • Attribute-centric The cursor is identified by the keyword "VFPData" and each field in a resulting or source cursor or table is represented by an attribute of the VFPData element.

    Copy Code
    <?xml version="1.0" encoding="Windows-1252" ?>
<!-- Note targetNamespace in root element -->
<VFPData xmlns="http://www.microsoft.com">
   <atxm_attr ikey="2" nc00="12345.1111"
      mc03="H1111111111111111111" cc04="H111111111111111111" lc05="1"
      fc06="-1111000.0000" yc07="-111111111.1111" ic08="-11111111"
      bc09="-111111111111.100000" dc10="1999-03-02"
      tc11="1999-03-02T01:01:01" ts12="AAAAAAAAAr0=" />
   <atxm_attr ikey="3" nc00="2.1111" mc03="H2222222222222222222"
      cc04="H222222222222222222" lc05="1" fc06="22220000.0000"
      yc07="2222222222.2222" ic08="222222222"
      bc09="222222222222.2200000"
      tc11="2000-10-03T02:02:02" ts12="AAAAAAAAAr8=" />
</VFPData>
  • Raw Each row in a resulting or source cursor or table is represented by an XML element with the generic identifier "row", and each column value is mapped to an attribute of the row element where the attribute name is equal to the column name. This format is identical to Attribute-centric except for "row" as the name of the top-level element.

    Copy Code
    <?xml version="1.0"?>
<!-- Note no targetNamespace in root element -->
<VFPData>
   <row CustomerID="CACTU" CompanyName="Cactus Comidas para llevar"
      ContactName="Patricio Simpson" ContactTitle="Sales Agent"
      Address="Cerrito 333" City="Buenos Aires" PostalCode="1010"
      Country="Argentina" Phone="(1) 135-5555" Fax="(1) 135-4892"/>
</VFPData>

See Also

Other Resources

XML Data in Visual FoxPro
Visual FoxPro and XML Schema Data Type Mapping
Importing and Exporting Data


XML Functionality Using XMLAdapters

Visual FoxPro 9.0
XML Functionality Using XMLAdapters
See Also

Visual FoxPro enhances its existing XML features and its compatibility with XML DiffGram and .NET Framework ADO.NET DataSet formats by providing the XMLAdapter, XMLTable, and XMLField classes. With these classes, Visual FoxPro supports hierarchically formatted XML for the following:

  • XML files that have associated schema, either inline or external, as implemented by ADO.NET DataSets based on the .NET Framework. For more information, see ADO.NET DataSets.

  • Microsoft XML Data Reduced Schema (XDR) as used by Microsoft SQL XML

  • ADO Recordset schemas that are produced when an ADO Recordset is saved as XML to a file or stream

Visual FoxPro can factor an XML file representing a collection of different and possibly related tables, such as an ADO.NET DataSet object, into separate Visual FoxPro cursors. Usually, this file contains data from a database management system (DBMS) with the structure of Parent > Child > Child. The XML can also have a nested format such as Parent > Child, Parent > Child, or a serial format such as Parent-Parent, Child-Child.

When you have hierarchical XML that represents a single table resulting from a multiple-table SQL JOIN command, Visual FoxPro creates only one cursor.

Note:
The XMLAdapter, XMLTable, and XMLField classes require Microsoft XML Core Services (MSXML) 4.0 Service Pack 1 (SP1). For more information about these classes, see XMLAdapter Class, XMLTable Class, and XMLField Class. For more information about MSXML, see Microsoft XML Core Services 4.0 SP1 on the MSDN Library Web site at http://msdn.microsoft.com/downloads/.

Note:
XML Schema Definition (XSD) schema as generated by Visual Studio ADO.NET DataSets might contain elements not supported by Visual FoxPro. For more information, see Support for Schemas Generated by ADO.NET DataSets.

ADO.NET DataSets

In the .NET Framework, ADO.NET is a set of classes that expose data access services to the programmer. ADO.NET provides consistent access to data sources such as Microsoft SQL Server and other data sources exposed through OLE DB and XML.

The ADO.NET DataSet is used as the primary class for manipulating data and encapsulates data as XML. An ADO.NET DataSet object can produce XML in several ways:

  • By returning the entire ADO.NET DataSet to the calling application.

    This method returns all rows in the original query in XML DiffGram format with inline schema and update, insert, and delete operations as indicated. Rows that remain unchanged do not have the diffgr:hasChanges attribute.

    When a DataSet object returns to the calling application from a method in an application that uses the .NET Framework and returns ADO.NET DataSet objects, it is always serialized, or converted, into XML. Visual FoxPro can convert this XML into cursors, which you can then manipulate in a Visual FoxPro application.

  • By returning only changes to the ADO.NET DataSet to the .NET-based application.

    This method returns only those rows, in XML DiffGram format, that were modified, added, or deleted.

    If the ADO.NET DataSet object contains changes, they are marked with the attributes, DiffGram:hasChanges="modified" or DiffGram:hasChanges="inserted". For those records marked as "modified", the previous values appear in the section, diffgr:before. Records that are deleted appear only in the diffgr:before section and not in the main section of the DiffGram.

  • By using the ADO.NET DataSet GetXml and GetXMLSchema methods to return XML as a .CLR stream or string type.

  • By using the ADO.NET DataSet WriteXml and WriteXmlSchema methods to write the ADO.NET DataSet as XML to a file with inline schema, without schema, or separate schema.

For more information about XML DiffGram and ADO.NET DataSet formats, see the .NET Framework SDK on the MSDN Library Web site at http://msdn.microsoft.com/library/.

Support for Schemas Generated by ADO.NET DataSets

XML that has external or inline XML Schema Definition (XSD) schema as generated by ADO.NET DataSets might contain elements not supported by Visual FoxPro, which disregards those elements. For example, these elements might include the following:

  • xs:unique name

  • xs:annotation

  • Additional processing instructions and attributes such as the following:

    • Schema prefix support, such as msdata:Prefix, that defines the scope of a group of elements

    • XML prefix support, such as the vfpx attribute, that scopes the prefix to root elements

    • msprop attribute and other attributes that use this namespace

    • Other msdata attributes that reference items not supported by Visual FoxPro, such as msdata:Locale or msdata:Comment

See Also

Other Resources

XML Data in Visual FoxPro
Converting Between XML and Visual FoxPro Data
Visual FoxPro and XML Schema Data Type Mapping
Importing and Exporting Data


Upsizing Visual FoxPro Databases

Visual FoxPro 9.0
Upsizing Visual FoxPro Databases

When you have designed your client/server application, you are ready to build and upsize a local prototype. A local prototype is a working model of your application using Microsoft Visual FoxPro tables, views, and databases to represent data that eventually will be accessed on a remote server. Use the upsizing wizards to move databases, tables, and views from your system to a remote Microsoft SQL Server server.

In This Section

Goals for Prototyping

When you use Microsoft Visual FoxPro to build a prototype of your application, you are leveraging the power of visual forms, wizards, builders, designers, and the Project Manager to quickly develop a working application.
How to: Build a Local Prototype of an Application

When you build a local prototype of your application, you might be starting from scratch, or you might be converting an existing Microsoft Visual FoxPro application to a client/server application.
Database Creation with Upsizing Wizards

The Visual FoxPro SQL Server Upsizing Wizard creates SQL Servers that duplicate, as much as possible, the functionality of a set of tables in a Microsoft Visual FoxPro database.

Related Sections

Developing Visual FoxPro Applications

This section includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Working with Data

Describes how to develop and work with databases and database objects, how to build queries and views, how to import and export data, how to manage data in multiuser environments, and how to access data using the OLE DB Provider.
Creating Applications

Discusses how to create Visual FoxPro application, which may include one or more databases, a main program that sets up the application's system environment, and a user interface comprised of forms, toolbars, and menus.
Creating Applications with the Application Framework

Explains how to create applications with the Application Framework using the Application Wizard and the Application builder.
Optimizing Client/Server Performance

Learn how you can fine-tune your application to gain maximum performance by increasing data throughput.
Creating International Applications

Describes how you can design and develop your Visual FoxPro applications so they are as effective internationally as domestically.


Goals for Prototyping

Visual FoxPro 9.0
Goals for Prototyping
See Also

When you use Visual FoxPro to build a prototype of your application, you're leveraging the power of visual forms, wizards, builders, designers, and the Project Manager to quickly develop a working application. While your ultimate goal is to implement your application across client/server platforms, you gain a great deal by choosing to build a solid prototype.

Reducing Development Time

By building a quick prototype, you can refine your application's design and local architecture quickly and easily, without having to access the remote server to rebuild server tables and databases. You can also test and debug your application's forms against smaller data stores, allowing you to more quickly correct and enhance your application's user interface. Because you're keeping architectural overhead low, you prevent wasting development time in rebuilding, reindexing, and reconnecting remote data just to test your prototype.

Decreasing Development Costs While Increasing Customer Satisfaction

Because the local prototype is self-contained on your computer, you can easily demonstrate a working model of your application to the end user early in the development cycle. Being able to see your application as it progresses gives clients confidence in your ability to deliver a solution that meets their needs. It also provides you with the opportunity to get customer feedback about the user interface and reports before you've invested resources in implementing it against a remote server.

As users see and interact with your prototype, they can begin to identify areas they'd like to change, as well as see the potential for adding additional functionality into their application. You can implement changes and redemonstrate the application in an iterative process until both you and the customer are satisfied with the design and function of the prototyped application. Your prototype then serves as a working specification for the final, implemented client/server application.

Contributing to Successful Implementation

You can also potentially provide the prototyped application as a demonstration for your users, allowing them to experiment with the working model as you move forward in the implementation process of the actual application. As they gain experience with the prototype, their learning curve decreases and they become better partners with you in refining and fine-tuning the application. They're also positioned to be more productive and satisfied in the final implementation stage because they already understand the basic framework of the application.

Having a working model increases the lead-time the end user has to become familiar and comfortable with the application. It also provides a framework to allow staff at your company or the customer site to design and develop a training plan for the application. The prototype can even be used to train end users before the final application is delivered, thus contributing to a successful implementation of the final, implemented client/server application.

See Also

Other Resources

Upsizing Visual FoxPro Databases
How to: Build a Local Prototype of an Application
Database Creation with Upsizing Wizards
SQL Server Upsizing Wizard Preparation


How to: Build a Local Prototype of an Application

Visual FoxPro 9.0
How to: Build a Local Prototype of an Application
See Also

When you build a local prototype of your application, you might be starting from scratch, or you might be converting an existing Visual FoxPro application to a client/server application. The primary difference between building a local prototype of a client/server application and developing any other Visual FoxPro application is in using local views and tables to represent data that will eventually be upsized.

To build and upsize a local prototype

  1. Create your application using local views and local tables to represent data you want to move to a remote server.

  2. Use local views in your application's data environment for forms and reports.

  3. Upsize local views and tables using the SQL Server Upsizing Wizard:

    • In the Set Upsizing Options step, in the Changes to make locally area, select Redirect views to remote data.

      When you select this option, the Upsizing Wizard copies the local tables you select to the remote server, and redirects local views to use remote data where applicable.

For more information, see Working with Views and Creating Forms.

See Also

Other Resources

Goals for Prototyping
Database Creation with Upsizing Wizards
Upsizing Visual FoxPro Databases
SQL Server Upsizing Wizard Preparation


Database Creation with Upsizing Wizards

Visual FoxPro 9.0
Database Creation with Upsizing Wizards

The Visual FoxPro SQL Server Upsizing Wizard creates a SQL Server database that duplicates the functionality of a Visual FoxPro database as closely as possible. You can also redirect Visual FoxPro views so that they use the newly created remote data instead of local data. You can use the Upsizing wizards to:

  • Move local data to a remote server.

  • Transform local base tables and local views into remote base tables and remote views.

  • Migrate a local application to a client/server application.

    Note:
    Though the Upsizing Wizard accesses SQL Server, you can create a client/server application for any remote ODBC data source. For servers other than SQL Server, you can use SQL pass-through functions to create remote tables, then use Visual FoxPro to create remote views that access server tables. For more information on using SQL pass-through functions, see Enhancing Applications Using SQL Pass-Through Technology. For information on creating remote views, see How to: Create Remote Views.

In This Section

SQL Server Upsizing Wizard Preparation

Discusses steps you should take to prepare the client and server sides of an application before using the SQL Server Upsizing Wizard.
How to: Start the SQL Server Upsizing Wizard

Explains how to begin upsizing your application with the SQL Server Upsizing Wizard.
How the SQL Server Upsizing Wizard Works

Describes how the SQL Server Upsizing Wizard makes upsizing a Visual FoxPro database to SQL Server practically transparent.
Mapping Visual FoxPro Databases to SQL Server Databases

Describes mapping between Visual FoxPro databases and SQL Server databases.
SQL Server Upsizing Process Completion

Discusses steps you can take after using the SQL Server Upsizing wizar, to ensure your application and data are secure and functioning properly.

Related Sections

How to: Build a Local Prototype of an Application

Describes how to create a prototype application using local views and local tables to represent data you want to move to a server.
Upsizing Visual FoxPro Databases

Provides links to topics that discuss how to upsize your Visual FoxPro databases.


SQL Server Upsizing Wizard Preparation

Visual FoxPro 9.0
SQL Server Upsizing Wizard Preparation
See Also

Before you run the SQL Server Upsizing Wizard, you must prepare both the client and server sides.

Preparing the SQL Server Side

Before upsizing, you must ensure that you have necessary permissions on the server, estimate the size of your database, and check that the server has sufficient disk space. There are also special preparations for upsizing to multiple disks or devices.

Checking Free Disk Space

Make sure you have enough disk space on the server.

Caution:
If the SQL Server Upsizing Wizard runs out of disk space on the server, it halts, leaving a partial database and any devices it created on the server. You can remove devices, databases, and tables with the SQL Server Administration tool.

Setting Permissions on SQL Server Databases

In order to run the SQL Server Upsizing Wizard, you must have certain permissions on the SQL server to which you will be upsizing. The permissions you need depend on the tasks you want to accomplish.

  • To upsize to an existing database, you need CREATE TABLE and CREATE DEFAULT permissions.

  • To build a new database, you need CREATE DATABASE and SELECT permissions on the system tables in the master database.

  • To create new devices, you must be a system administrator.

For more information on granting server permissions, see your SQL Server documentation.

Estimating SQL Server Database and Device Size

When you create a new database, the SQL Server Upsizing Wizard asks you to select devices for your database and log. It also asks you to set the size of the database and your devices.

Estimating SQL Server Database Size

When SQL Server creates a database, it sets aside a fixed amount of space for that database on one or more devices. Not all this space is necessarily used by the database — the database size simply limits how large a database can grow before it runs out of space.

Note:
You can increase the size of a SQL Server database after it's created. For more information, see the ALTER DATABASE command in your SQL Server documentation.

To estimate the space needed for your database, calculate the total size of your Visual FoxPro .dbf files for the tables you want to upsize plus the rate at which your new SQL Server database will grow. In general, every megabyte of Visual FoxPro data requires at least 1.3 to 1.5 MB in the SQL Server.

If you have ample disk space on your server, multiply the size of your Visual FoxPro tables by two. This ensures that the SQL Server Upsizing Wizard has enough space to upsize your database and also leaves some room to grow. If you expect to add a lot of data to the database, increase the multiple.

Estimating SQL Server Device Sizes

All SQL Server databases and logs are placed on devices. A device is both a logical location at which to put databases and logs, and a physical file. When a device is created, SQL Server creates a file, thus reserving a set amount of disk space for its own use.

The SQL Server Upsizing Wizard displays the amount of free space available on the existing SQL Server devices. Select a device that has at least enough free space for your estimated database size.

If no existing devices have enough free space, you can use the SQL Server Upsizing Wizard to create a new device. New devices should be at least as big as your estimated database size. If possible, make the device larger than your database size, so you can expand your database later, or place other databases or logs on the same device.

Note:
Device size cannot be changed. Make sure you create sufficiently large devices.

Using Multiple SQL Server Disks or Devices

In most cases, the SQL Server Upsizing Wizard provides more than enough control over SQL Server devices. However, if your server has multiple disks or if you want to place a database or log on multiple devices, you might want to create devices before running the SQL Server Upsizing Wizard.

Servers with Multiple Physical Disks

If your server has more than one physical hard disk, you might want to place your database on one disk and the database log on a different disk. In the event of a disk failure, you'll be more likely to recover your database if the log and the database are stored on different physical disks.

The SQL Server Upsizing Wizard allows you to create new devices but only on one physical disk — the same disk as the Master database device.

To place a database and log on separate disks, make sure you have devices that are big enough on both disks, creating new devices if necessary. Then run the SQL Server Upsizing Wizard.

Placing Databases or Logs on Multiple Devices

SQL Server allows databases and logs to span several devices. However, the SQL Server Upsizing Wizard allows you to specify only one device for your database and one device for the log.

If you want to specify multiple devices for a database or log, make those devices (and no other devices) the default devices. Then run the SQL Server Upsizing Wizard and choose Default for the database or log device.

Note:
If the new SQL Server database or log sizes don't require using all the default devices, SQL Server uses only the devices necessary to accommodate the database or log.

Preparing the Client

Before upsizing, you must have access to a SQL Server through an ODBC data source or named connection. You must also have a Visual FoxPro database, which you should back up before running the SQL Server Upsizing Wizard.

Creating an ODBC Data Source or Named Connection

When you create a new remote database, you select an ODBC data source or named connection in your Visual FoxPro database that accesses the SQL Server to which you want to upsize. Because you can't proceed through the Upsizing Wizard until you select a named connection or data source, you should create the appropriate named connection or data source before you start the upsizing process.

For information on creating a named connection, see How to: Define Connections to Remote Data Sources. If you want to create an ODBC data source, run the ODBC Administrator. For information on setting up ODBC data sources, see How to: Set Up an ODBC Data Source.

Backing Up Your Database

It's a good idea to create a backup copy of your database (.dbc, .dct, and .dcx files) before upsizing. While the SQL Server Upsizing Wizard doesn't modify .dbf files, it does operate on the .dbc directly by opening the .dbc as a table at times and indirectly by renaming tables and views when creating new remote views. If you back up your database, you can revert your database to its original pre-upsizing state by overwriting the upsized .dbc, .dct, and .dcx files with the original backup copies, which reverses the renaming and creation of new views.

Closing Tables

The SQL Server Upsizing Wizard attempts to exclusively open all the tables in the database to be upsized; if any tables are already open and shared, the wizard closes them and reopens them exclusively. Opening tables exclusively before upsizing protects against other users attempting to modify records in the tables you're exporting during data export. If any tables can't be opened exclusively, the SQL Server Upsizing Wizard displays a message; those tables are not available for upsizing.

See Also

Other Resources

Database Creation with Upsizing Wizards
How to: Start the SQL Server Upsizing Wizard
Upsizing Visual FoxPro Databases
How the SQL Server Upsizing Wizard Works
SQL Server Upsizing Process Completion
Goals for Prototyping


How to: Start the SQL Server Upsizing Wizard

Visual FoxPro 9.0
How to: Start the SQL Server Upsizing Wizard
See Also

After you create an ODBC data source and complete the necessary preparations on the client and server, you're ready to begin upsizing.

To start the SQL Server Upsizing Wizard

  1. From the Tools menu, choose Wizards, and then choose Upsizing.

  2. From the Wizard Selection dialog box, choose SQL Server Upsizing Wizard.

  3. Follow the directions in the wizard screens, as described in the following sections.

    You can choose Cancel at any time to exit the wizard; the wizard performs no actions on the server until you choose Finish.

  4. When you're ready to upsize, choose Finish.

After you choose Finish, the SQL Server Upsizing Wizard begins exporting the database to the server.

The Finish button is available after you provide the basic information needed for upsizing. If you choose Finish before you complete all the wizard screens, the SQL Server Upsizing Wizard uses default values for the remaining screens.

See Also

Other Resources

Database Creation with Upsizing Wizards
SQL Server Upsizing Wizard Preparation
How the SQL Server Upsizing Wizard Works
Upsizing Visual FoxPro Databases
SQL Server Upsizing Process Completion


How the SQL Server Upsizing Wizard Works

Visual FoxPro 9.0
How the SQL Server Upsizing Wizard Works
See Also

The SQL Server Upsizing Wizard makes upsizing a Visual FoxPro database to SQL Server easy and almost transparent.

The SQL Server Upsizing Wizard exports data using one of two methods:

  • Create a stored procedure that performs multiple row inserts.

  • Create a SQL INSERT statement for each row in the table and then executes the statement.

Creating a stored procedure can be very fast because stored procedures are precompiled and execute quickly. However, stored procedures cannot accept variable length binary variables as parameters.

If you are exporting data that you want to store in SQL Server tables and uses text or image data types or tables with more than 250 fields, the SQL Server Upsizing Wizard creates a SQL INSERT statement for each row in the table and then executes the statement. If the SQL Server Upsizing Wizard encounters any errors, and the number of errors exceeds 10 percent of the number of records in the table or 100 records, whichever is larger, the wizard cancels the export for that table and saves the number of export errors for the error report. However, the exported server table is not dropped, and any records that were successfully exported are left in the server table.

Files Created by the SQL Server Upsizing Wizard

The SQL Server Upsizing Wizard creates tables for its own use during the upsizing process. These files are removed from the hard disk unless the following occur:

  • You choose to produce an upsizing report.

  • You want to save the generated SQL.

  • Errors occur during upsizing and you choose to save the error information.

If any of the conditions above are true, the SQL Server Upsizing Wizard creates a project, named Report, Report1, Report2, and so on, and a database, named Upsize, Upsize1, and so on, in a subdirectory named UPSIZE in the directory defined by the SET DEFAULT command for your Visual FoxPro session. The wizard adds the database tables used to produce the Upsizing Report, a table to store the generated SQL, and any error tables.

The following table lists the table files potentially created by the upsizing process.

Table name | Contents | Purpose
Errors_uw | Information on any error that occurred during upsizing. | Report table
Fields_uw | Information about all the tables upsized. | Report table
Indexes_uw | Information about all the indexes upsized. | Report table
Misc_uw | Miscellaneous upsizing information. | Report table
Relations_uw | Information about all the referential integrity constraints stored in the Visual FoxPro database. | Report table
Tables_uw | Information on all the tables in the database you choose to upsize. | Report table
Views_uw | Information about the local views redirected to access remote data. | Report table
SQL_uw | One memo field containing all the SQL code generated by the SQL Server Upsizing Wizard. | Script table
ExportErrors_table_name | The SQL Server Upsizing Wizard generates a table containing the records that are not successfully exported for each table that experiences a data export error during upsizing. | Data export error tables
Note:
If the wizard is canceled during processing or if the wizard halts because of an error, no tables are left on your hard disk.

Tip:
The script table stored on your hard disk contains all the SQL code generated by the SQL Server Upsizing Wizard whether it executes without error on the server or not. If you want to use this code, the best approach is to look at the generated SQL, copy the parts of it you want to use, run the extracted pieces of code, and repeat the process to obtain the results you want. You cannot run the entire SQL script as a substitute for running the SQL Server Upsizing Wizard because the wizard performs additional steps that are not reflected in the generated SQL code.

See Also

Tasks

How to: Start the SQL Server Upsizing Wizard

Concepts

SQL Server Upsizing Process Completion
Database Creation with Upsizing Wizards


Mapping Visual FoxPro Databases to SQL Server Databases

Visual FoxPro 9.0
Mapping Visual FoxPro Databases to SQL Server Databases
See Also

The following sections contain information about mapping a Visual FoxPro database to a SQL Server database:

Mapping Objects

A Visual FoxPro database maps directly to a SQL Server database. When upsizing a Visual FoxPro database to a server, the SQL Server Upsizing Wizard creates server objects with as much as the same functionality possible as the Visual FoxPro database.

Mapping some Visual FoxPro objects to server objects is very straightforward. Visual FoxPro databases, tables, fields, defaults, and indexes map on a direct one-to-one basis to SQL Server databases, tables, fields, defaults, and indexes. A Visual FoxPro table maps to a SQL Server table with the exception of part of its data dictionary.

However, not all local objects map directly to server objects. Validation rules and referential integrity in Visual FoxPro are part of the data dictionary and are enforced at the engine level. SQL Server validation rules and referential integrity are not part of the data dictionary and are enforced through code bound to a table. These differences, as well as design decisions made by the SQL Server Upsizing Wizard mean that much of the Visual FoxPro data dictionary cannot be mapped directly to SQL Server constructs.

The following table summarizes how objects are mapped from Visual FoxPro to SQL Server.

Visual FoxPro objects | SQL Server objects
Database | Database
Table | Table
Indexes | Indexes
Field | Field
Default | Default
Table validation rule | SQL Server stored procedures called from UPDATE and INSERT triggers
Field validation rule | SQL Server stored procedures called from UPDATE and INSERT triggers
Persistent relationships (where used for referential integrity constraints) | Update, Insert, and Delete triggers or table constraints

Naming Conventions for Upsized Objects

When migrating objects to a data source, the SQL Server Upsizing Wizard creates named objects on the server. The wizard uses prefixes for objects that need new names, for example, defaults and rules, because no such standalone object existed in Visual FoxPro. A table name and then a field name, if appropriate, follow the prefix. This naming convention makes it possible for all objects of the same kind to have the same prefix and sort together when viewed with data source administration tools. Objects created on the same table also group together when viewed.

Note:
If SQL Server naming conventions are violated, database, table, index, and field names might change during upsizing. SQL Server names must be 30 characters or less, and the first character must be a letter or the symbol "@". The remaining characters may be numbers, letters, or the "$", "#", and "_" symbols; no spaces are allowed. The SQL Server Upsizing Wizard replaces any illegal characters with the "_" symbol. Any names that are identical to SQL Server reserved words are given a suffix of "_". For example, FROM and GROUP become FROM_ and GROUP_. The SQL Server Upsizing Wizard also places the "_" symbol in front of object names that begin with a number.

The SQL Server Upsizing Wizard gives each upsized table the same name as the local table unless the table name contains a space or is a keyword for the data source.

Field names and data types are automatically translated into SQL Server fields when a Visual FoxPro table is exported by the SQL Server Upsizing Wizard.

The following table illustrates how Visual FoxPro data types map to SQL Server data types.

Abbreviation | Visual FoxPro data type | SQL Server data type
C | Character | char
Y | Currency | money
D | Date | datetime
T | DateTime | datetime
B | Double | float
F | Float | float
G | General | image
I | Integer | int
L | Logical | bit
M | Memo | text
M (Binary) | Memo (Binary) | image
C (Binary) | Character (Binary) | binary
N | Numeric | float

Timestamp columns are created using the Transact-SQL timestamp data type. When you select the Timestamp column checkbox for a specific table in Step 4 - Map Field Data Types, the SQL Server Upsizing Wizard creates a timestamp field for that table.

If a table contains one or more memo (M) or picture (P) fields, the SQL Server Upsizing Wizard selects the Timestamp column check box for that table by default and creates a timestamp field on the upsized version of the table.

Identity columns are created using the Transact-SQL IDENTITY property fields.

Mapping Views

If you select Create Remote Views On Tables, the SQL Server Upsizing Wizard creates remote views and gives them many of the properties of the fields in the original local table.

Mapping SQL Server Defaults

A Visual FoxPro default expression maps directly to a single SQL Server default. The SQL Server Upsizing Wizard attempts to create a SQL Server default based on the default expression for a Visual FoxPro field. If the default is successfully created, the SQL Server Upsizing Wizard binds it to the appropriate SQL Server field. The upsizing report on fields indicates if the SQL Server Upsizing Wizard was successful in translating the Visual FoxPro expression to SQL Server Transact-SQL. For more information, see Mapping Expressions.

While SQL Server and Visual FoxPro defaults are largely similar, there are some differences in the way defaults are created and behave in the two products. SQL Server defaults are stand-alone objects, independent of any particular field or table. Once a default has been created, it can be used by, or bound, to any number of different fields.

Though Visual FoxPro logical fields accept null values, SQL Server do not accept them. To manage this difference, the SQL Server Upsizing Wizard automatically creates and binds a default value called "UW ZeroDefault" to each exported logical field whether or not you chose to export defaults. This default sets the value of the server field to 0 (False (.F.) in Visual FoxPro) when you do not supply a value.

If the local Visual FoxPro table contains a default value for a logical field that sets the field equal to True (.T.), the SQL Server Upsizing Wizard does not bind the UW_ZeroDefault default to the server table. Instead, the wizard creates a default that sets the field equal to 1 and names the default according to the naming conventions outlined earlier in this topic.

Note:
SQL Server defaults behave differently than Visual FoxPro defaults.

Naming Conventions for Defaults

The SQL Server Upsizing Wizard names defaults using the prefix "Dflt_" plus the table name and field name. For example, a default value for an order amount field in a customer table might be named "Dflt_Customer_Ordamt" on the server.

Note:
If combining the prefix with the table and field names causes the default name to exceed 30 characters, Visual FoxPro truncates the excess characters.

Fields with a default expression of zero are bound to a default named "UW ZeroDefault". If two or more fields have the same non-zero default expression, the SQL Server Upsizing Wizard creates two defaults with two different names but are functionally identical.

Index Conversion

SQL Server and Visual FoxPro indexes are very similar. The following table shows how Visual FoxPro index types convert to SQL Server index types.

Visual FoxPro index type | SQL Server index type
Primary | Clustered Unique
Candidate | Unique
Unique Regular | Non-unique

The SQL Server Upsizing Wizard uses Visual FoxPro tag names as names for indexes on SQL Server. If the tag name is a reserved word on the server, the wizard alters the tag name by appending the "_" character.

Note:
SQL Server does not support ascending or descending indexes or permit expressions within server indexes. The SQL Server Upsizing Wizard removes Visual FoxPro expressions from index expressions as the index is upsized; only field names are sent to the server.

Mapping Triggers

A SQL Server trigger is a series of Transact-SQL statements associated with a particular SQL Server table. When you choose to upsize Validation rules and Relationships in Step 8, the SQL Server Upsizing Wizard converts Visual FoxPro field- and record-level validation rules and persistent table relationships into stored procedures that are called from SQL Server triggers. Each server trigger can contain code to emulate the functionality of several validation and referential integrity rules.

Note:
The SQL Server Upsizing Wizard does not upsize Visual FoxPro triggers.

A server table can have three triggers, one for each of the commands that can modify data in the table: UPDATE, INSERT, and DELETE. The trigger is automatically executed when the associated command is carried out.

The following table describes the triggers created by the SQL Server Upsizing Wizard. Any specific trigger might contain code to emulate some or all of the Visual FoxPro functionality listed.

Trigger | Visual FoxPro functionality emulated
UPDATE | Validation rules (field and record-level validation) Referential integrity
INSERT | Validation rules (field and record-level validation) Referential integrity (child table triggers only)
DELETE (Parent table only) | Referential integrity

Naming Conventions for Triggers

The SQL Server Upsizing Wizard names server triggers by combining a prefix that indicates the type of trigger being created with the table name of the SQL Server table to which the trigger belongs. The prefix ("TrigU_" for UPDATE triggers, "TrigD_" for DELETE triggers, and "TrigI_" for INSERT triggers) is placed in front of the table name. For example, the UPDATE trigger on the Customer table might be called TrigU_Customer.

Exporting Validation Rules

The SQL Server Upsizing Wizard can export Visual FoxPro field- and record-level validation rules, which it converts to stored procedures on SQL Server. The wizard names field-level rules by combining a prefix "vrf" (for "validation rule, field") with the names of the table and the field; an example might be vrf_customer_lname. Table validation rules are named with the prefix "vrt" (for "validation rule, table") plus the name of the table, to create a name such as vrt_customer.

The SQL Server Upsizing Wizard uses triggers that call stored procedures rather than SQL Server rules to enforce field level validation because SQL Server rules don't allow you to display custom error messages. For more information about SQL Server rules, see the CREATE RULE command in your SQL Server documentation.

Exporting Referential Integrity

Your Visual FoxPro application supports referential integrity through triggers on UPDATE, DELETE, and INSERT events on persistent table relationships that are enforced at the engine level. You can choose to implement referential integrity constraints on SQL Server using either of two methods:

  • Trigger-based referential integrity.

  • Declarative referential integrity.

When you choose trigger-based referential integrity, the SQL Server Upsizing Wizard creates triggers that include the Transact-SQL code required to duplicate Visual FoxPro referential integrity constraints. If you choose to implement declarative referential integrity, the SQL Server Upsizing Wizard creates SQL Server constraints using the ALTER TABLE command with the CONSTRAINT keyword.

Trigger-Based Referential Integrity

In the trigger-based method, referential integrity is enforced on SQL Server by Transact-SQL code in triggers. You can use triggers to provide restrictions on UPDATE, DELETE, and INSERT statements, and to cascade changes resulting from DELETE and INSERT statements.

The SQL Server Upsizing Wizard creates SQL Server triggers by evaluating the Visual FoxPro triggers used to enforce referential integrity on persistent relationships in your Visual FoxPro database.

A Visual FoxPro persistent relationship used in a referential integrity constraint can become up to four triggers on a SQL Server data source: two for the parent table and two for the child table.

Note:
If only one of the tables in a relationship is upsized, or if referential integrity is not enforced in Visual FoxPro, the relationship is not exported.

The following table lists the mapping between Visual FoxPro Referential Integrity constraints and the SQL Server triggers generated by the SQL Server Upsizing Wizard.

Visual FoxPro Referential Integrity constraint | SQL Server trigger | Description
UPDATE | Cascade | Cascade UPDATE trigger.
UPDATE | Restrict | Restrict UPDATE trigger.
UPDATE | Ignore | No trigger generated.
INSERT | Restrict | Restrict INSERT trigger.
INSERT | Ignore | No trigger generated.
DELETE | Cascade | Cascade DELETE trigger.
DELETE | Restrict | Restrict DELETE trigger.
DELETE | Ignore | No trigger generated.

Parent Table

The SQL Server Upsizing Wizard creates an UPDATE trigger that either prevents the user from changing the parent table's primary key or cascades that change through the child table, depending on the type of relationship that was created in Visual FoxPro.

The SQL Server Upsizing Wizard also creates a DELETE trigger that prevents the user from deleting a record with related child records, or that deletes the child records, again depending on the type of relationship between the tables in Visual FoxPro.

Child Table

The SQL Server Upsizing Wizard creates an UPDATE trigger that prevents the user from making changes to the foreign key that would orphan the record. Similarly, an INSERT trigger is created to prevent the user from adding a new record that has no parent.

Custom Error Values

At run time, if the referential integrity established by the SQL Server Upsizing Wizard-created triggers is violated, SQL Server places a custom error value into the @@ERROR variable. Potential error values are defined by the SQL Server Upsizing Wizard as a part of the trigger code. The specific error value returned at run time depends on whether the user was attempting to update, insert, or delete.

The following table lists the error numbers generated for each action.

Action | SQL Server error number
Violated validation rule | 44444
Attempted delete | 44445
Attempted update | 44446
Attempted insert | 44447
Update or Delete statement affected more than one row; statement is automatically rolled back | 44448

Declarative Referential Integrity

If you choose to implement declarative referential integrity, the SQL Server Upsizing Wizard creates SQL Server constraints using the ALTER TABLE command with the CONSTRAINT keyword. The parent table constraint uses the PRIMARY KEY keyword. The child table constraint uses the FOREIGN KEY and REFERENCES keywords. Declarative referential integrity is supported at the RESTRICT, RESTRICT updates, and RESTRICT deletes levels.

You can use SQL Server constraints to provide restrictions on UPDATE, DELETE, and INSERT statements.

Mapping Expressions

Although Visual FoxPro and Transact-SQL have some functions in common, many Visual FoxPro functions are not supported by SQL Server.

The following table lists those expressions that are the same between Visual FoxPro and SQL server.

CEILING( ) | LOG( ) | LOWER( )
LTRIM( ) | RIGHT( ) | RTRIM( )
SOUNDEX( ) | SPACE( ) | STR( )
STUFF( ) | UPPER( ) |

The following table describes the expression mapping that the SQL Server Upsizing Wizard uses to attempt converting Visual FoxPro expressions in field and record-level validation rules and default values to Transact-SQL.

Visual FoxPro expression | SQL Server expression
True (.T.) | 1
False (.F.) | 0
# | <>
.AND. | AND
.NOT. | NOT
.NULL. | NULL
.OR. | OR
=< | <=
=> | >=
ASC( ) | ASCII( )
AT( ) | CHARINDEX( )
CDOW( ) | DATENAME(dw, ...)
CHR( ) | CHAR( )
CMONTH( ) | DATENAME(mm, ...)
CTOD( ) | CONVERT(datetime, ...)
CTOT( ) | CONVERT(datetime, ...)
DATE( ) | GETDATE( )
DATETIME( ) | GETDATE( )
DAY( ) | DATEPART(dd, ...)
DOW( ) | DATEPART(dw, ...)
DTOC( ) | CONVERT(varchar, ...)
DTOR( ) | RADIANS( )
DTOT( ) | CONVERT(datetime, ...)
HOUR( ) | DATEPART(hh, ...)
LIKE( ) | PATINDEX( )
MINUTE( ) | DATEPART(mi, ...)
MONTH( ) | DATEPART(mm, ...)
MTON( ) | CONVERT(money, ...)
NTOM( ) | CONVERT(float, ...)
RTOD( ) | DEGREES( )
SUBSTR( ) | SUBSTRING( )
TTOC( ) | CONVERT(char, ...)
TTOC( ) | CONVERT(datetime, ...)
YEAR( ) | DATEPART(yy, ...)

See Also

Tasks

How to: Start the SQL Server Upsizing Wizard

Concepts

How the SQL Server Upsizing Wizard Works
SQL Server Upsizing Process Completion
Database Creation with Upsizing Wizards


SQL Server Upsizing Process Completion

Visual FoxPro 9.0
SQL Server Upsizing Process Completion
See Also

You can now take additional steps, both on your server and in your Visual FoxPro application, to ensure your application and data are secure and functioning properly.

You can also use the information in this section when you build an application from remote views rather than by upsizing. Regardless of how you created remote tables, you take certain steps to ensure the server and client are prepared to work together in your client/server application.

SQL Server Steps

You can complete the upsizing process on your server by:

  • Making sure the tables you want to edit from Visual FoxPro are updatable.

  • Setting permissions on the database so that users can access the objects they need.

  • Protecting your work by making your new database recoverable, in case it's damaged or lost.

Adding Unique Indexes for Updatability

A remote table should have a unique index to be updatable in Visual FoxPro. The SQL Server Upsizing Wizard can export an existing unique index, but it doesn't create one where none exists. Make sure that tables you want to edit from Visual FoxPro are updatable.

Setting Permissions

The new SQL Server database and its objects receive a set of default permissions from the SQL Server. Set permissions on the remote database so that your users have access to the objects they need.

Database Logon Permissions

The default permissions of a new database make it accessible only to system administrators and the database owner.

You can add new users and groups by using the SQL Server Security Manager or the system procedures sp_adduser and sp_addgroup.

For more information on adding users and groups, see SQL Server Security Manager Help and the documentation of the system procedures sp_adduser and sp_addgroup in the Microsoft SQL Server Transact-SQL Reference.

Object Permissions

All objects created by the Visual FoxPro-to-SQL Server Upsizing Wizard, including tables, triggers, and defaults, are accessible initially only to the database owner and system administrators. This is true whether you upsized to a new or existing database. If you overwrite existing objects, you also overwrite all object permissions.

Ensuring Recoverability

Protect your work by making your new database recoverable in case it's damaged or lost.

Dumping the Master Database

When a database is created on a SQL Server, new records are added to the system tables in the Master database. Dumping the Master database also provides you with a backup copy, including all the latest changes.

Scheduling Backups

Schedule regular backups of your database, so you can restore your database from this backup copy in the event of a serious problem.

Device Mirroring

Mirroring a device continuously duplicates the information from one SQL Server device to another. In the event that one device fails, the other contains an up-to-date copy of all transactions.

If you anticipate that many changes will be made to a database between backups and you can't afford to lose those changes, consider device mirroring. Device mirroring is most effective when the devices are located on separate disks, as both devices might be lost if they're on the same disk and the disk fails.

Visual FoxPro Client Steps

Once you've transferred objects from Visual FoxPro to a SQL Server, you probably need to modify code in the original Visual FoxPro database so that it functions properly with the new SQL Server database.

Optimizing Views

Views created by the SQL Server Upsizing Wizard aren't parameterized and therefore are not optimized. For most efficient processing, add parameters to views created by the SQL Server Upsizing Wizard to download just the data you need. For information on adding a parameter to a view, see How to: Create Parameterized Views.

SQL Server doesn't support some Visual FoxPro functions. If the remote view created by the SQL Server Upsizing Wizard uses functions that couldn't be mapped to Transact-SQL functions, the view will not work. For more information on mapping Visual FoxPro expressions to Transact-SQL expressions, see Mapping Visual FoxPro Databases to SQL Server Databases.

Creating Stored Procedures and Triggers

The SQL Server Upsizing Wizard doesn't upsize Visual FoxPro stored procedures and triggers. If you want to create SQL Server stored procedures or triggers, you can use Transact-SQL on the server or use SQL pass-through in Visual FoxPro. For more information on using Transact-SQL, see your SQL Server documentation. For information on using SQL pass-through, see Enhancing Applications Using SQL Pass-Through Technology.

Comparing Event Order

In Visual FoxPro, some events occur in a different order, depending on whether your application is using SQL Server data or Visual FoxPro data. These differences might require changes to your code.

Default Values

Visual FoxPro default field values appear when you begin editing a new record. Default values generated by SQL Server defaults appear only after a record has been inserted. You need to change any code that depends on having values before the record is committed, such as the code for lookups.

Validation Rules

In Visual FoxPro, field validation occurs when the focus leaves a field. When you edit SQL Server data in attached tables, triggers and rules aren't fired until you leave the record. You might need to modify any record validation rules that rely on field validation occurring when a field is exited.

Handling Unconverted Expressions

The upsizing report indicates whether each Visual FoxPro table validation rule, field validation rule, and default expression was successfully converted. If a default expression or validation rule was not translated, you should rewrite it in Transact-SQL.

You can also perform validation at the form level in Visual FoxPro. However, if server data is then modified without using a particular form, the validation will not be applied and invalid data might be entered.

For more information about expression conversion, see Expression Mapping. For more information about Transact-SQL functions, see your SQL Server documentation.

Record Locking

Visual FoxPro uses optimistic locking internally when accessing tables on a SQL server. Optimistic locking means that the row is locked only when the edited value is committed and the update process occurs — usually a very brief interval.

Optimistic locking is used rather than pessimistic locking on SQL Server because pessimistic locking on SQL Server is provided by page locking, potentially locking many records at a time. While page locking prevents other users from making changes to the same record you're editing, it can also prevent users from accessing many other records in the same (locked) page. Optimistic locking provides the best multiuser access for a Visual FoxPro client/server application.

You can optimize updates and control how update conflicts are handled with the SQL WhereType property. For more information on controlling update conflicts, see Managing Conflicts When Updating Data.

See Also

Reference

SQL Server Upsizing Process Completion

Other Resources

Database Creation with Upsizing Wizards
Upsizing Visual FoxPro Databases
Enhancing Applications Using SQL Pass-Through Technology
SQL Server Upsizing Wizard Preparation


Programming for Shared Access

Visual FoxPro 9.0
Programming for Shared Access

If you create an application that will run on several machines in a network environment or if several instances of a form will access the same data, then you must program for shared access. Shared access means providing efficient ways of using and sharing data among users, as well as restricting access when necessary.

Microsoft Visual FoxPro provides support for shared or exclusive access to data, locking options, data sessions, record and table buffering, and transactions. Although these features are useful particularly in shared environments, you can use them in single-user environments too.

In This Section

Controlling Access to Data

Discusses effective data management in a shared environment, and how you must choose how to access the data and when and where to limit that access.
Updating Data

Explains how to update data using buffers, transactions, or views.
Managing Conflicts When Updating Data

Discusses how you can anticipate and manage the inevitable conflicts that result from data update operations.
How to: Detect Updating Conflicts

Describes how you can detect changes in fields during data update operations.
Optimizing Applications in Multiuser Environments

Discusses how to improve performance when writing applications for multiuser environments.

Related Sections

Optimizing Visual FoxPro in a Multiuser Environment

Describes how to improve performance when running Visual FoxPro in a multiuser environment.
Web Services and Components

Describes how to extend a basic Visual FoxPro application so it can work for multiple users, access and distribute Web services, use Microsoft ActiveX controls and automation-enabled applications, and add international capabilities.
Sharing Information and Adding OLE

Discusses using ActiveX controls and object linking and embedding in your application to link to data and use the strengths of other applications.
Working with Data

Provides information to help you create effective applications by analyzing data requirements and designing your application components to meet those needs.


Controlling Access to Data

Visual FoxPro 9.0
Controlling Access to Data

Since you access data in files, effective data management begins with control over the environment of these files. You must choose how to access the data and how and when to limit that access.

In This Section

How to: Set Data Access

Explains how to specify the access type, exclusive or shared, when using a table.
Locking Data

Discusses methods to manually or automatically lock access to tables and records to manage access in a shared environment.
Updating Data Using Multiple Form Instances

Discusses how data is updated and how locks on records may affect other instances of a form.
How to: Use Data Sessions

Describes how to use data sessions to ensure that each user in a shared environment has a secure, exact duplicate of the working environment, and to ensure that multiple instances of a form can operate independently.
Customizing the Environment of a Data Session

Discusses how you can use private data sessions to establish custom SET command settings within a single session of Visual FoxPro.
Buffering Data

Describes data buffering, and how to use it to protect data during updates.
How to: Enable Buffering

Explains how to enable record and table buffering to protect data during updates.
How to: Append and Delete Records in Table Buffers

Explains how to append and delete records with table buffering enabled.

Reference

CURSORSETPROP( ) Function

Specify property settings for a Visual FoxPro table or cursor.
TABLEUPDATE( ) Function

Commit changes made to a buffered row, a buffered table, cursor, or cursor adapter.
TABLEREVERT( ) Function

Discard changes made to a buffered row or a buffered table or cursor and restore the OLDVAL( ) data for remote cursors and the current disk values for local tables and cursors.
LOCK( ) Function

Attempt to lock one or more records in a table.
Data Session Window

Use the Data Session window to open and display tables or views, establish temporary relationships, and set work area properties.

Related Sections

Programming for Shared Access

Explains how programming for shared access makes it possible for you to create an application that will run on several machines in a network environment.
Updating Data

Explains how to update data using buffers, transactions, or views.
Managing Conflicts when Updating

Discusses how you can anticipate and manage the inevitable conflicts that result from data update operations.
How to: Buffer Data

Explains how to buffer data to protect data during updates.


How to: Set Data Access

Visual FoxPro 9.0
How to: Set Data Access
See Also

In a shared environment, you can access data in two ways: from exclusive files or from shared files. If you open a table for shared access, other users also have access to the file. If you open a table for exclusive access, no other user can read or write to that file. Because exclusive use defeats many of the benefits of sharing data on a network, it should be used sparingly.

Using a Table with Exclusive Access

The most restrictive way to open a file is to open it exclusively. When you open a table through the interface, it opens for exclusive use by default. You can also explicitly open a table for exclusive use by using Visual FoxPro commands.

To open a table for exclusive use

  • Type the following commands in the Command window:

    Copy Code
    SET EXCLUSIVE ON
USE cMyTable

    -or-

  • Type the following command in the Command window:

    Copy Code
    USE cMyTable EXCLUSIVE

The following commands require you to open a table for exclusive use:

  • ALTER TABLE

  • INDEX when creating, adding, or deleting a compound index tag.

  • INSERT [BLANK]

  • MODIFY STRUCTURE To use this command to change a table structure, you must open the table exclusively. You can, however, use this command in read-only mode when you open the table for shared use.

  • PACK

  • REINDEX

  • ZAP

Visual FoxPro returns the error, "Exclusive open of file is required," if you try to execute one of these commands on a shared table.

You can restrict access to a table by using the FLOCK( ) Function. If you use FLOCK( ) to lock the table, other users cannot write to the table but they can read it.

Using a Table with Shared Access

When you open a table for shared use, more than one workstation can use the same table at the same time. When you open a table through the interface, you can override the default ON setting for the SET EXCLUSIVE Command. You can explicitly open a table for shared use by using Visual FoxPro commands.

To open a table for shared use

  • Type the following commands in the Command window:

    Copy Code
    SET EXCLUSIVE OFF
USE cMyTable

    -or-

  • Type the following command in the Command window:

    Copy Code
    USE cMyTable SHARED

When you add or change data in a shared table, you must first lock the affected record or the entire table. You can lock a record or a table opened for shared use in the following ways:

  • Use a command that performs an automatic record or table lock.

  • Manually lock one or more records or an entire table with the record and table locking functions.

  • Initiate buffering with the CURSORSETPROP( ) Function.

Associated memo and index files always open with the same share status as their table.

If your application uses a table for lookup purposes only and all users of the application access it, then you can improve performance by marking the table as read-only.

See Also

Other Resources

Controlling Access to Data
How to: Use Data Sessions
Programming for Shared Access
SET EXCLUSIVE Command


Locking Data

Visual FoxPro 9.0
Locking Data
See Also

If you share access to files, you must also manage access to data by locking tables and records. Locks, unlike access permissions, can provide both long- and short-term control of data. Visual FoxPro provides both automatic and manual locking.

Choosing Record or Table Locks

Record locking, whether automatic or manual, prevents one user from writing to a record that's currently being written to by another user. Table locking prevents other users from writing to, but not reading from, an entire table. Because table locking prohibits other users from updating records in a table, it should only be used sparingly.

Choosing Automatic or Manual Locks

In addition to record or table locking, you can also choose automatic or manual locking. Many Visual FoxPro commands automatically attempt to lock a record or a table before the command is executed. If the record or table is successfully locked, the command is executed and the lock is released.

Commands that Automatically Lock Records and Tables

Command | Scope of lock
ALTER TABLE | Entire table
APPEND | Table header
APPEND BLANK | Table header
APPEND FROM | Table header
APPEND FROM ARRAY | Table header
APPEND MEMO | Current record
BLANK | Current record
BROWSE, CHANGE and EDIT | Current record and all records from aliased fields in related tables once editing of a field begins
CURSORSETPROP( ) | Depends on parameters
DELETE | Current record
DELETE NEXT 1 | Current record
DELETE RECORD n | Record n
DELETE of more than one record | Entire table
DELETE – SQL | Current record
GATHER | Current record
INSERT | Entire table
INSERT - SQL | Table header
MODIFY MEMO | Current record when editing begins
READ | Current record and all records from aliased fields
RECALL | Current record
RECALL NEXT 1 | Current record
RECALL RECORD n | Record n
RECALL of more than one record | Entire table
REPLACE | Current record and all records from aliased fields
REPLACE NEXT 1 | Current record and all records from aliased fields
REPLACE RECORD n | Record n and all records from aliased fields
REPLACE of more than one record | Entire table and all files from aliased fields
SHOW GETS | Current record and all records referenced by aliased fields
TABLEUPDATE( ) | Depends on buffering
UPDATE | Entire table
UPDATE – SQL | Entire table

Record Lock Characteristics

Commands that attempt record locks are less restrictive than commands that lock tables. When you lock a record, other users can still add or delete other records. If a record or table is already locked by another user, an attempted record or table lock fails. Commands that attempt to lock the current record return the error, "Record is in use by another," if the record cannot be locked.

The BROWSE, CHANGE, EDIT, and MODIFY MEMO commands do not lock a record until you edit the record. If you're editing fields from records in related tables, the related records are locked if possible. The lock attempt fails if the current record or any of the related records are also locked by another user. If the lock attempt is successful, you can edit the record; the lock is released when you move to another record or activate another window.

Header and Table Lock Characteristics

Some Visual FoxPro commands lock an entire table while others only lock a table header. Commands that lock the entire table are more intrusive than commands that only lock the table header. When you lock the table header, other users cannot add records, but they can still change data in fields.

Users can share the table without causing a conflict when you issue the APPEND BLANK command, but an error can occur while another user is also appending a BLANK record to the table. You can trap for the error, "File is in use by another," which is returned when two or more users execute APPEND BLANK simultaneously. Commands that lock an entire table return the error, "File is in use by another," if the table cannot be locked. To cancel the attempted lock, press ESC.

Automatic Locking

In the following example, the user automatically locks the table header by appending records from another table, even though customer was opened as a shared file:

Copy Code
SET EXCLUSIVE OFF
USE customer
APPEND FROM oldcust FOR status = "OPEN"

Manual Locking

You can manually lock a record or a table using one of the following locking functions:

  • RLOCK( ) Function

  • LOCK( ) Function

  • FLOCK( ) Function

The LOCK( ) and RLOCK( ) functions can apply to a table header. If you provide 0 as the record to LOCK( ) or RLOCK( ) and the test indicates the header is unlocked, the function locks the header and returns true (.T.).

Once you lock a record or table, be sure to release the lock by using the UNLOCK command as soon as possible to provide access to other users.

These manual locking functions perform the following actions:

  • Test the lock status of the record or table.

  • If the test indicates the record is unlocked, lock the record or table and return true (.T.).

  • If the record or table cannot be locked, attempt to lock the record or table again, depending on the current setting of SET REPROCESS.

  • Return true (.T.) or false (.F.), indicating whether the lock attempt was successful.

    Tip:
    If you want to test the lock status of a record in your session without locking the record, use the ISRLOCKED( ) or ISFLOCKED( ) function.

If an attempt to lock a record or table fails, the SET REPROCESS command and your current error routine determine if the lock is attempted again. SET REPROCESS affects the result of an unsuccessful lock attempt. You can control the number of lock attempts or the length of time a lock is attempted with SET REPROCESS.

The following example opens the customer table for shared access and uses FLOCK( ) to attempt to lock the table. If the table is successfully locked, REPLACE ALL updates every record in the table. UNLOCK releases the file lock. If the file cannot be locked because another user has locked the file or a record in the file, a message is displayed.

Copy Code
SET EXCLUSIVE OFF
SET REPROCESS TO 0
USE customer    && Open table shared
IF FLOCK()
 REPLACE ALL contact ;    && Replace and unlock
  WITH UPPER(contact)
 UNLOCK
ELSE  && Output message
 WAIT "File in use by another." WINDOW NOWAIT
ENDIF

Unlocking Data

After you establish a record or file lock and complete a data operation in a shared environment, you should release the lock as soon as possible. There are several ways to release locks. In some cases, simply moving to the next record is enough to unlock the data. Other situations require explicit commands.

To unlock a record that's been automatically locked, you need only move the record pointer, even if you set MULTILOCKS ON. You must explicitly remove a lock from a record that you've manually locked; simply moving the record pointer is not enough.

The following table describes the effects of commands on manual and automatic record and table locks.

Command | Effect
UNLOCK | Releases record and file locks in the current work area.
UNLOCK ALL | Releases all locks in all work areas in the current session.
SET MULTILOCKS OFF | Enables automatic release of the current lock as a new lock is secured.
FLOCK( ) | Releases all record locks in the affected file before locking the file.
CLEAR ALL, CLOSE ALL,USE, QUIT | Releases all record and file locks.
END TRANSACTION | Releases automatic locks.
TABLEUPDATE( ) | Releases all locks after updating the table.
Caution:
If a record was automatically locked in a user-defined function and you move the record pointer off and then back on the record, the lock will be released. Use table buffering to avoid this problem.

See Also

Other Resources

Controlling Access to Data
How to: Use Data Sessions
Programming for Shared Access
RLOCK( ) Function
LOCK( ) Function
FLOCK( ) Function
UNLOCK Command


Updating Data Using Multiple Form Instances

Visual FoxPro 9.0
Updating Data Using Multiple Form Instances
See Also

While private data sessions generate separate work areas containing separate copies of a form's open tables, indexes, and relationships, every copy of the form references the same underlying base tables and base index files. When a user updates a record from one instance of a form, the base table referenced by the form is updated. You see the changes made from another instance of the form when you navigate to the changed record.

Locks taken on records or tables in one private data session are respected by other private data sessions. For example, if the user of data session 1 takes a lock on a record, the user in data session 2 cannot lock the record. If the user in session 1 opens a table exclusively, the user in data session 2 cannot open the table. By respecting locks taken by other data sessions, Visual FoxPro protects the integrity of updates to the underlying base tables.

See Also

Other Resources

How to: Use Data Sessions
Controlling Access to Data
Programming for Shared Access


How to: Use Data Sessions

Visual FoxPro 9.0
How to: Use Data Sessions
See Also

To ensure that each user in a shared environment has a secure, exact duplicate of the working environment, and to ensure that multiple instances of a form can operate independently, Visual FoxPro provides data sessions.

A data session is a representation of the current dynamic work environment. You might think of a data session as a miniature data environment running inside one open Visual FoxPro session on one machine. Each data session contains:

  • A copy of the items in the form's data environment.

  • Cursors representing the open tables, their indexes, and relationships.

The concept of a data session is easily understood when you consider what happens when you open the same form simultaneously from separate workstations in a multiuser application. In this case, each workstation is running a separate Visual FoxPro session, and therefore has its own set of work areas: cursors representing open base tables, indexes, and relationships. For more information about simultaneous access to data, see Updating Data Using Multiple Form Instances and Locking Data.

However, if you open multiple instances of the same form in a single project, on one machine, within the same Visual FoxPro session, the forms share the Default data session, representing a single dynamic work environment. Each instance of the open form open in the same Visual FoxPro session uses the same set of work areas, and actions in one instance of a form that move the record pointer in a work area automatically affect other instances of the same form.

Using Private Data Sessions

If you want to have more control over multiple instances of form, you can implement Private data sessions. When your form uses private data sessions, Visual FoxPro creates a new data session for each instance of the Form, FormSet, or Toolbar control your application creates. Each private data session contains:

  • A separate copy of each table, index, and relationship in the form's data environment.

  • An unlimited number of work areas.

  • Record pointers for each copy of each table that are independent from the base tables for the form.

The number of available data sessions is limited only by available system memory and disk space.

You implement private data sessions by setting the DataSession property for the form. The DataSession property has two settings:

  • 1 – Default data session (the default setting).

  • 2 – Private data session.

By default, the DataSession property of a form is set to 1.

To enable private data sessions

  • In the Form Designer, set the DataSession property of the form to 2 – Private data session.

    -OR-

  • In code, set the DataSession Property to 2.

    For example, type:

    Copy Code
    frmFormName.DataSession = 2
    Note:
    You can only set the DataSession property at design time. The DataSession property is read-only at run time.

When a form uses private data sessions, each instance of a form open on a single machine in a single Visual FoxPro session uses its own data environment. Using private data sessions is similar to running the same form simultaneously from separate workstations.

EquivMultipleDataSessions screenshot foxpro

Identifying Data Sessions

Each private data session is identified separately. You can see the contents of each data session in the Data Session Window. You can also change the data session description through commands in the Load event code.

To view the identification number for each data session

  • Use the run-time DataSessionID Property.

    The following example displays the DataSessionID property of a form named frmMyForm:

    Copy Code
    DO FORM frmMyForm
? frmMyForm.DataSessionID

If you activate the form using the NAME clause, you can use the form's name to access the DataSessionID property, as in the following code:

Copy Code
DO FORM MyForm NAME one
? one.DataSessionID

The DataSessionID property is designed only to identify a particular data session. Avoid changing the DataSessionID of a form instance because data-bound controls lose their data sources when you change the DataSessionID.

Overriding Automatic Private Data Session Assignment

When private data sessions for a form are in use, changes you make to data in one form are not automatically represented in other instances of the same form. If you want all instances of a form to access the same data and to immediately reflect changes to common data, you can override automatic data session assignment.

To override automatic data session assignment

  • Set the SET DATASESSION command to 1 or no value.

For example, the following code enables the Command window and Project Manager to control the default data session:

Copy Code
SET DATASESSION TO 1

-OR-

Copy Code
SET DATASESSION TO

See Also

Other Resources

Customizing the Environment of a Data Session
Controlling Access to Data
Programming for Shared Access


Customizing the Environment of a Data Session

Visual FoxPro 9.0
Customizing the Environment of a Data Session
See Also

Because data sessions control the scope of certain SET commands, you can use private data sessions to establish custom SET command settings within a single session of Visual FoxPro.

For example, the SET EXACT command, which controls the rules used when comparing character strings of different lengths, is scoped to the current data session. The default setting for SET EXACT is off which specifies that, to be equivalent, expressions must match, character for character, until the end of the expressions on the right side is reached. You might want to enable "fuzzy" or equivalent searches by leaving SET EXACT set to OFF for the default data session; however, your application might contain a specific form that requires exact matches. You could set the DataSession property for the form requiring exact matches to 2, to enable private data sessions, and then SET EXACT to ON for that form. By issuing a SET command only for the form using private data sessions, you preserve the global Visual FoxPro session settings while enabling customized session settings for a specific form.

See Also

Other Resources

How to: Use Data Sessions
Controlling Access to Data
Programming for Shared Access


Buffering Data

Visual FoxPro 9.0
Buffering Data
See Also

If you want to protect data during updates, use buffers. Visual FoxPro record and table buffering help you protect data update and data maintenance operations on single records and on multiple records of data in multiuser environments. Buffers can automatically test, lock, and release records or tables.

With buffering, you can easily detect and resolve conflicts in data update operations: the current record is copied to a memory or disk location managed by Visual FoxPro. Other users can then still access the original record simultaneously. When you move from the record or try to update the record programmatically, Visual FoxPro attempts to lock the record, verify that no other changes have been made by other users, and then write the changes. After you attempt to update data, you must also resolve conflicts that prevent the changes from being written to the original table.

Choosing a Buffering Method

Before you enable buffering, evaluate the data environment to choose the buffering method and locking options that best suit the editing needs of your application, the record and table types and sizes, how the information is used and updated, and other factors. Once you enable buffering, it remains in effect until you disable buffering or close the table.

Visual FoxPro has two types of buffering: record and table.

  • To access, modify, and write a single record at a time, choose record buffering.

    Record buffering provides appropriate process validation with minimal impact on the data update operations of other users in a multiuser environment.

  • To buffer the updates to several records, choose table buffering.

    Table buffering provides the most effective way to handle several records in one table or child records in a one-to-many relationship.

  • To provide maximum protection for existing data, use Visual FoxPro transactions.

    You can use transactions alone, but you gain additional effectiveness by using transactions as wrappers for record or table buffering commands.

Choosing a Locking Mode

Visual FoxPro provides buffering in two locking modes: pessimistic and optimistic. These choices determine when one or more records are locked, and how and when they're released.

Pessimistic Buffering

Pessimistic buffering prevents other users in a multiuser environment from accessing a particular record or table while you're making changes to it. A pessimistic lock provides the most secure environment for changing individual records but it can slow user operations. This buffering mode is most similar to the standard locking mechanism in previous versions of FoxPro, with the added benefit of built-in data buffering.

Optimistic Buffering

Optimistic buffering is an efficient way to update records because locks are only taken at the time the record is written, thus minimizing the time any single user monopolizes the system in a multiuser environment. When you use record or table buffering on views, Visual FoxPro imposes optimistic locking.

The value of the Buffering property, set with the CURSORSETPROP( ) function, determines the buffering and locking methods.

The following table summarizes valid values for the Buffering property.

To enable | Use this value
No buffering. The default value. | 1
Pessimistic record locks which lock record now, update when pointer moves or upon TABLEUPDATE( ). | 2
Optimistic record locks which wait until pointer moves, and then lock and update. | 3
Pessimistic table locks which lock record now, update later upon TABLEUPDATE( ). | 4
Optimistic table lock which wait until TABLEUPDATE( ), and then lock and update edited records. | 5

The default value for Buffering is 1 for tables and 3 for views. If you use buffering to access remote data, the Buffering property is either 3, optimistic row buffering, or 5, optimistic table buffering. For more information on accessing data in remote tables, see How to: Query Multiple Tables and Views.

Note:
Set MULTILOCKS to ON for all buffering modes above 1.

See Also

Other Resources

How to: Enable Buffering
How to: Append and Delete Records in Table Buffers
Updating Data
Programming for Shared Access
Controlling Access to Data


How to: Enable Buffering

Visual FoxPro 9.0
How to: Enable Buffering
See Also

You can enable record and table buffering to protect data during updates.

Enabling Record Buffering

Enable record buffering with the CURSORSETPROP( ) Function.

To enable pessimistic record locking in the current work area

  • Use this function and value:

    Copy Code
    CURSORSETPROP("Buffering", 2)

Visual FoxPro attempts to lock the record at the pointer location. If the lock is successful, Visual FoxPro places the record in a buffer and permits editing. When you move the record pointer or use the TABLEUPDATE( ) Function, Visual FoxPro writes the buffered record to the original table.

To enable optimistic record locking in the current work area

  • Use this function and value:

    Copy Code
    CURSORSETPROP("Buffering", 3)

Visual FoxPro writes the record at the location of the pointer to a buffer and permits edits. When you move the record pointer or use the TABLEUPDATE( ) Function, Visual FoxPro attempts a lock on the record. If the lock is successful, Visual FoxPro compares the current value of the record on the disk with the original buffer value. If these values are the same, the edits are written to the original table; if these values are different, Visual FoxPro generates an error.

Enabling Table Buffering

Enable table buffering with the CURSORSETPROP( ) function.

To enable pessimistic locking of multiple records in the current work area

  • Use this function and value:

    Copy Code
    CURSORSETPROP("Buffering", 4)

Visual FoxPro attempts to lock the record at the pointer location. If the lock is successful, Visual FoxPro places the record in a buffer and permits editing. Use the TABLEUPDATE( ) Function to write the buffered records to the original table.

To enable optimistic locking of multiple records in the current work area

  • Use this function and value:

    Copy Code
    CURSORSETPROP("Buffering", 5)

Visual FoxPro writes the records to a buffer and permits edits until you use the TABLEUPDATE( ) Function. Visual FoxPro then performs the following sequence on each record in the buffer:

  1. Attempts a lock on each edited record.

  2. Upon a successful lock, compares the current value of each record on the disk with the original buffer value.

  3. Writes the edits to the original table if the comparison shows the values to be the same.

  4. Generates an error if the values differ.

When table buffering is enabled, Visual FoxPro attempts updates only after using the TABLEUPDATE( ) Function.

See Also

Other Resources

Buffering Data
How to: Append and Delete Records in Table Buffers
How to: Use Data Sessions
Updating Data
Programming for Shared Access
Controlling Access to Data
CURSORSETPROP( )


How to: Append and Delete Records in Table Buffers

Visual FoxPro 9.0
How to: Append and Delete Records in Table Buffers
See Also

You can append and delete records while table buffering is enabled: appended records are added to the end of the buffer. To access all records in the buffer, including appended records, use the RECNO( ) Function. The RECNO( ) function returns sequential negative numbers on records you append to a table buffer. For instance, if you initiate table buffering, edit records 7, 8, and 9, and then append three records, the buffer will contain RECNO( ) values of 7, 8, 9, – 1, – 2, and – 3.

Note:
Tables containing automatically incrementing field values append table-buffered records approximately 35% slower than tables without automatically incrementing field values, which might affect performance. When using table buffering, the table header is locked when the record is appended.

EditedTableBuffer2 graphic foxpro

You can remove appended records from the buffer only by using the TABLEREVERT( ) Function. For any appended record, both TABLEUPDATE( ) and TABLEREVERT( ) delete the negative RECNO( ) value for that record while maintaining the sequence.

EditedTableBuffer graphic foxpro

While using a table buffer, you can use the GO command with the negative RECNO( ) value to access a specific appended record. For instance, using the previous example, you can type:

Copy Code
GO 7      && moves to the 1st buffered record
GO -3      && moves to the 6th buffered record (3rd appended)

To append records to a table buffer

  • Use the APPEND or APPEND BLANK command after you enable table buffering.

Appended records have sequential ascending negative RECNO( ) numbers.

To remove an appended record from a table buffer

  1. Use the GO Command with a negative value to position the record pointer at the record to be deleted.

  2. Use the DELETE Command to mark the record for deletion.

  3. Use the TABLEREVERT( ) Function to remove the record from the buffer.

    Note:
    The TABLEREVERT() function also affects the status of deleted and changed rows.

To remove all appended records from a table buffer

  • Use the TABLEREVERT( ) Function with a value of true (.T.).

TABLEREVERT( ) removes appended records from a table buffer without writing the records to the table. TABLEUPDATE( ) writes all current buffered records to a table, even if they've been marked for deletion.

See Also

Other Resources

How to: Enable Buffering
Buffering Data
How to: Use Data Sessions
Updating Data
Programming for Shared Access
Controlling Access to Data
CURSORSETPROP( )


Updating Data

Visual FoxPro 9.0
Updating Data

To update data, you can use buffers, transactions, or views.

In This Section

How to: Perform Updates Using Buffers

Explains how to enable record or table buffering, after choosing the type of buffering method and type of locking.
Managing Updates Using Transactions

Describes transactions and how to use them to protect update operations and use transactions to recover from an entire section of code as a unit.
Managing Updates by Using Views

Discusses the use of views to manage data conflicts in multiuser environments.

Reference

TABLEUPDATE( ) Function

Commit changes made to a buffered row, a buffered table, cursor, or cursor adapter.
TABLEREVERT( ) Function

Discard changes made to a buffered row or a buffered table or cursor and restore the OLDVAL( ) data for remote cursors and the current disk values for local tables and cursors.

Related Sections

Programming for Shared Access

Explains how programming for shared access makes it possible for you to create an application that will run on several machines in a network environment.
Controlling Access to Data

Discusses effective data management in a shared environment, and how you must choose how to access the data and when and where to limit that access.
Managing Conflicts when Updating

Discusses how you can anticipate and manage conflicts that result from data update operations.


How to: Perform Updates Using Buffers

Visual FoxPro 9.0
How to: Perform Updates Using Buffers
See Also

After choosing the buffering method and the type of locking, you can enable record or table buffering.

To enable buffering

  • Choose one of the following options:

    • In the Form Designer, set the BufferModeOverride property of the cursor in the data environment of the form.

    -OR-

    • Use the CURSORSETPROP( ) function to set the Buffering property.

For example, you can enable pessimistic row buffering by placing the following code in the Init procedure of a form:

Copy Code
CURSORSETPROP('Buffering', 2)

You then place code for the update operations in the appropriate method code for your controls.

To write edits to the original table, use the TABLEUPDATE( ) Function. To cancel edits after a failed update operation in a table constrained by rules, use TABLEREVERT( ) Function, which is valid even if explicit table buffering is not enabled. To specify a level of table integrity checking lower than the default setting, you can use the SET TABLEVALIDATE Command.

The following sample demonstrates how to update records when pessimistic record buffering is enabled.

Example of Updating Using Record and Table Buffers

Code Comment

OPEN DATABASE testdata

USE customers

CURSORSETPROP('Buffering', 2)

In the form Init code, open the table and enable pessimistic record buffering.

lModified = .F.

FOR nFieldNum = 1 TO FCOUNT()

IF GETFLDSTATE(nFieldNum) = 2

lModified = .T.

EXIT

ENDIF

ENDFOR

Go through fields, checking for any field that's been modified.

Note:
This code might be in the Click event of a "Save" or "Update" command button.

IF lModified

nResult = MESSAGEBOX;

("Record has been modified. Save?", ;

4+32+256, "Data Change")

Locate the next modified record.

IF nResult = 7

TABLEREVERT (.F.)

ENDIF

ENDIF

Present the current value and give the user the option to revert the change to the current field.

SKIP

IF EOF()

MESSAGEBOX( "already at bottom")

SKIP -1

ENDIF

THISFORM.Refresh

SKIP guarantees that the last change is written.

See Also

Other Resources

How to: Buffer Data
Updating Data
Managing Conflicts When Updating
Programming for Shared Access
Update Criteria
DBSETPROP( )
CURSORSETPROP( )


Managing Updates Using Transactions

Visual FoxPro 9.0
Managing Updates Using Transactions
See Also

Even with buffering, things can go wrong. If you want to protect update operations and recover from an entire section of code as a unit, use transactions.

Adding transactions to your application provides protection beyond Visual FoxPro record and table buffering by placing an entire section of code in a protected, recoverable unit. You can nest transactions and use them to protect buffered updates. Visual FoxPro transactions are available only with tables and views contained in a database.

Wrapping Code Segments

A transaction acts as a wrapper that caches data update operations to memory or to disk, rather than applying those updates directly to the database. The actual database update is performed at the end of the transaction. If for any reason the system cannot perform the update operations on the database, you can roll back the entire transaction and no update operations are performed.

Note:
Buffered update operations made outside a transaction are ignored within a transaction in the same data session.

Commands that Control Transactions

Visual FoxPro provides three commands and one function to manage a transaction.

To | Use
Initiate a transaction. | BEGIN TRANSACTION
Determine the current transaction level. | TXNLEVEL( )
Reverse all changes made since the most recent BEGIN TRANSACTION statement. | ROLLBACK
Lock records, commit to disk all changes made to the tables in the database since the most recent BEGIN TRANSACTION, and then unlock the records. | END TRANSACTION

You can use transactions to wrap modifications to tables, structural .cdx files, and memo files associated with tables within a database. Operations involving variables and other objects don't respect transactions; therefore, you cannot roll back or commit such operations.

Note:
When using data stored in remote tables, transaction commands control only updates to the data in the local copy of the view cursor; updates to remote base tables are not affected. To enable manual transactions on remote tables use SQLSETPROP( ), and then control the transaction with SQLCOMMIT( ) and SQLROLLBACK( ).

In general, you should use transactions with record buffers rather than with table buffering, except to wrap TABLEUPDATE( ) calls. If you place a TABLEUPDATE( ) command in a transaction, you can roll back a failed update, address the reason for the failure, and then retry the TABLEUPDATE( ) without losing data. This ensures the update happens as an "all-or-nothing" operation.

Though simple transaction processing provides safe data update operations in normal situations, it doesn't provide total protection against system failures. If power fails or some other system interruption occurs during processing of the END TRANSACTION command, the data update can still fail.

Use the following code template for transactions:

Copy Code
BEGIN TRANSACTION
* Update records
IF lSuccess = .F. && an error occurs
   ROLLBACK
ELSE && commit the changes
   * Validate the data
   IF && error occurs
      ROLLBACK
   ELSE
      END TRANSACTION
   ENDIF
ENDIF

The following rules apply to transactions:

  • A transaction starts with the BEGIN TRANSACTION command and ends with the END TRANSACTION or ROLLBACK command. An END TRANSACTION statement without a preceding BEGIN TRANSACTION statement generates an error.

  • A ROLLBACK statement without a preceding BEGIN TRANSACTION statement generates an error.

  • A transaction, once begun, remains in effect until the corresponding END TRANSACTION begins (or until a ROLLBACK command is issued), even across programs and functions, unless the application terminates, which causes a rollback.

  • Visual FoxPro uses data cached in the transaction buffer before using disk data for queries on the data involved in transactions. This ensures that the most current data is used.

  • If the application terminates during a transaction, all operations roll back.

  • A transaction works only in a database container.

  • You cannot use the INDEX command if it overwrites an existing index file, or if any .cdx index file is open.

  • Transactions are scoped to data sessions.

Transactions exhibit the following locking behaviors:

  • Within a transaction, Visual FoxPro imposes a lock at the time a command directly or indirectly calls for it. Any system or user direct or indirect unlock commands are cached until the completion of the transaction by ROLLBACK or END TRANSACTION commands.

  • If you use a locking command such as FLOCK( ) or RLOCK( ) within a transaction, the END TRANSACTION statement will not release the lock. In that case, you must explicitly unlock any locks explicitly taken within a transaction. You should also keep transactions containing the FLOCK( ) or RLOCK( ) commands as brief as possible; otherwise, users could be locked out of records for a long time.

Nesting Transactions

Nested transactions provide logical groups of table update operations that are insulated from concurrent processes. BEGIN TRANSACTION...END TRANSACTION pairs need not be in the same function or procedure. The following rules apply to nested transactions:

  • You can nest up to five BEGIN TRANSACTION...END TRANSACTION pairs.

  • Updates made in a nested transaction aren't committed until the outermost END TRANSACTION is called.

  • In nested transactions, an END TRANSACTION only operates on the transaction initiated by the last issued BEGIN TRANSACTION.

  • In nested transactions, a ROLLBACK statement only operates on the transaction initiated by the last issued BEGIN TRANSACTION.

  • The innermost update in a set of nested transactions on the same data has precedence over all others in the same block of nested transactions.

Notice in the following example that because changes in a nested transaction aren't written to disk but to the transaction buffer, the inner transaction will overwrite the changes made to the same STATUS fields in the earlier transaction:

Copy Code
BEGIN TRANSACTION &&  transaction 1
   UPDATE EMPLOYEE ; &&  first change
      SET STATUS = "Contract" ;
      WHERE EMPID BETWEEN 9001 AND 10000
   BEGIN TRANSACTION &&  transaction 2
      UPDATE EMPLOYEE ;
         SET STATUS = "Exempt" ;
         WHERE HIREDATE > {^1998-01-01}  &&  overwrites
   END TRANSACTION &&  transaction 2
END TRANSACTION    &&  transaction 1

The following nested transaction example deletes a customer record and all its related invoices. The transaction will roll back if errors occur during a DELETE command. This example demonstrates grouping table update operations to protect updates from partial completion and to avoid concurrency conflicts.

Example of Modifying Records in Nested Transactions

Code | Comments
DO WHILE TXNLEVEL( ) > 0 ROLLBACK ENDDO | Cleanup from other transactions.
CLOSE ALL SET MULTILOCKS ON SET EXCLUSIVE OFF | Establish environment for buffering.
OPEN DATABASE test USE mrgtest1 CURSORSETPROP('buffering',5) GO TOP | Enable optimistic table buffering.
REPLACE fld1 WITH "changed" SKIP REPLACE fld1 WITH "another change" MESSAGEBOX("modify first field of both" + ; "records on another machine") | Change a record. Change another record.
BEGIN TRANSACTION lSuccess = TABLEUPDATE(.T.,.F.) | Start transaction 1 and try to update all modified records without force.
IF lSuccess = .F. ROLLBACK AERROR(aErrors) DO CASE CASE aErrors[1,1] = 1539 ... CASE aErrors[1,1] = 1581 ... CASE aErrors[1,1] = 1582 | If the update failed, roll back the transaction. Get the error from AERROR( ). Determine the cause of the failure. If a trigger failed, handle it. If a field doesn't accept null values, handle it. If a field rule was violated, handle it.
CASE aErrors[1,1] = 1585 nNextModified = getnextmodified(0) DO WHILE nNextModified <> 0 GO nNextModified RLOCK() FOR nField = 1 to FCOUNT() cField = FIELD(nField) if OLDVAL(cField) <> CURVAL(cField) | If a record was changed by another user, locate the first modified record. Loop through all modified records, starting with the first record. Lock each record to guarantee that you can update. Check each field for any changes. Check the buffered value against the value on disk, and then present a dialog box to the user.
nResult = MESSAGEBOX; ("Data was changed " + ; "by another user — keep"+ ; "changes?", 4+48, ; "Modified Record") |
IF nResult = 7 TABLEREVERT(.F.) UNLOCK record nNextModified ENDIF | If user responded "No," revert the one record and unlock it.
EXIT ENDIF ENDFOR | Break out of the "FOR nField..." loop.
ENDDO | Get the next modified record.
BEGIN TRANSACTION TABLEUPDATE(.T.,.T.) END TRANSACTION UNLOCK | Start transaction 2 and update all non-reverted records with force. End transaction 2. Release the lock.
CASE aErrors[1,1] = 109 ... CASE aErrors[1,1] = 1583 ... CASE aErrors[1,1] = 1884 ... OTHERWISE MESSAGEBOX( "Unknown error "+; "message: " + STR(aErrors[1,1])) ENDCASE | If the record is in use by another user, handle it. If a row rule was violated, handle it. If there was a unique index violation, handle it. Otherwise, present a dialog box to the user.
ELSE END TRANSACTION ENDIF | End transaction 1.

Protecting Remote Updates

Transactions can protect you from system-generated errors during data updates on remote tables. The following example uses a transaction to wrap data-writing operations to a remote table.

Example of a Transaction on a Remote Table

Code | Comment
hConnect = CURSORGETPROP('connecthandle') SQLSETPROP(hConnect, 'transmode', DB_TRANSMANUAL) | Get the connect handle and enable manual transactions.
BEGIN TRANSACTION | Begin the manual transaction.
lSuccess = TABLEUPDATE(.T.,.F.) IF lSuccess = .F. SQLROLLBACK (hConnect) ROLLBACK | Try to update all records without force. If the update failed, roll back the transaction on the connection for the cursor.
AERROR(aErrors) DO CASE | Get the error from AERROR( ).
CASE aErrors[1,1] = 1539 ... | If a trigger failed, handle it.
CASE aErrors[1,1] = 1581 ... | If a field doesn't accept null values, handle it.
CASE aErrors[1,1] = 1582 ... | If a field rule was violated, handle it.
CASE aErrors[1,1] = 1585 nNextModified = GETNEXTMODIFIED(0) DO WHILE nNextModified <> 0 GO nNextModified | If a record was changed by another user, handle it. Loop through all modified records, starting with the first record.
FOR nField = 1 to FCOUNT() cField = FIELD(nField) IF OLDVAL(cField) <> CURVAL(cField) nResult = MESSAGEBOX; ("Data has been changed ; by another user. ; Keep changes?",4+48,; "Modified Record") | Check each field for any changes. Check the buffered value against the value on disk, and then present a dialog box to the user.
IF nResult = 7 TABLEREVERT(.F.) ENDIF EXIT ENDIF ENDFOR nNextModified = ; GETNEXTMODIFIED(nNextModified) ENDDO | If user responded "No," revert the one record. Break out of the "FOR nField..." loop. Get the next modified record.
TABLEUPDATE(.T.,.T.) SQLCOMMIT(hConnect) | Update all non-reverted records with force and issue a commit.
CASE aErrors[1,1] = 109 * Handle the error | Error 109 indicates that the record is in use by another user.
CASE aErrors[1,1] = 1583 * Handle the error | Error 1583 indicates that a row rule was violated.
CASE aErrors[1,1] = 1884 * Handle the error | Error 1884 indicates that the uniqueness of the index was violated.
OTHERWISE * Handle generic errors. |
MESSAGEBOX("Unknown error message:" ; + STR(aErrors[1,1])) ENDCASE | Present a dialog box to the user. End of error handling.
ELSE SQLCOMMIT(hConnect) END TRANSACTION ENDIF | If all errors were handled and the entire transaction was successful, issue a commit and end the transaction.

See Also

Other Resources

Updating Data
Managing Conflicts when Updating
Programming for Shared Access
Update Criteria
DBSETPROP( )
CURSORSETPROP( )


Managing Updates by Using Views

Visual FoxPro 9.0
Managing Updates by Using Views
See Also

You can use the update conflict management technology built into Visual FoxPro views to handle multiuser access to data. Views control what is sent to the base tables underlying the view by using the WhereType property. You can set this property for both local and remote views. The WhereType property provides four settings:

  • DB_KEY

  • DB_KEYANDUPDATABLE

  • DB_KEYANDMODIFIED (the default)

  • DB_KEYANDTIMESTAMP

By choosing one of these four settings, you control how Visual FoxPro builds the WHERE clause for the SQL Update statement sent to the view's base tables. You can choose the setting you want using the Update Criteria tab of the View Designer, or you can use DBSETPROP( ) to set the WhereType for a view definition. To change the WhereType setting for an active view cursor, use CURSORSETPROP( ).

To... | Choose this SQL WHERE option...
Have the update fail if a key field has been changed in the source table | Key fields only
Have the update fail if any of the fields marked as updatable have been changed on the remote table | Key and updatable fields
Have the update fail if any fields you change locally have been changed on the source table | Key and modified fields
Have the update fail if the timestamp of the record on the remote table has changed since you first retrieved it (only available if the remote table has a timestamp column) | Key and timestamp

For example, suppose you have a simple remote view based on the Customer table that includes seven fields: cust_id, company, phone, fax, contact, title, and timestamp. The primary key for your view is cust_id.

You've made only two fields updatable: contact_name and contact_title. You want the user to be able to change the company contact and their title from the view. However, if other facts about the company change, such as the company address, you want the changes to go through a coordinator who'll identify the impact of the changes on your company, such as whether the sales region for the customer will change. Now that your view has been set up to send updates, you can choose the WhereType according to your preferences.

Now suppose that you change the name in the contact field for a customer, but you don't change the value in the other updatable field, title. Given this example, the following section discusses how the WhereType setting would impact the WHERE clause that Visual FoxPro builds to send the new contact name to the base tables.

Comparing the Key Field Only

The least restrictive update uses the DB_KEY setting. The WHERE Clause used to update remote tables consists of only the primary key field specified with the KeyField or KeyFieldList property. Unless the value in the primary key field has been changed or deleted in the base table since you retrieved the record, the update goes through.

In the case of the previous example, Visual FoxPro would prepare an update statement with a WHERE clause that compares the value in the cust_id field against the cust_id field in the base table row:

Copy Code
WHERE OLDVAL(customer.cust_id) = CURVAL(customer_remote_view.cust_id)

When the update statement is sent to the base table, only the base table's key field is verified.

Comparing the Key Field and Fields Modified in the View

The DB_KEYANDMODIFIED setting, the default, is slightly more restrictive than DB_KEY. DB_KEYANDMODIFIED compares only the key field and any updatable fields you've modified in the view against their base table counterparts. If you modify a field in the view, but the field isn't updatable, the fields are not compared to the base table data.

The WHERE clause used to update base tables consists of the primary fields specified with the KeyFieldList property and any other fields that are modified in the view. In the case of the previous example, Visual FoxPro would prepare an update statement that compares the values in the cust_id field because it is the key field, and the contact field because the contact name has been changed. Even though the title field is updatable, title is not included in the update statement because we haven't modified it.

Comparing the Key Field and All Updatable Fields

The DB_KEYANDUPDATABLE setting compares the key field and any updatable fields (whether modified or not) in your view against their base table counterparts. If the field is updatable, even if you haven't changed it in the view, if anyone else has changed that field in the base table, the update fails.

The WHERE clause used to update base tables consists of the primary fields specified with the Key Field or KeyFieldList property and any other fields that are updatable. In the case of the example, Visual FoxPro would prepare an update statement that compares the values in the cust_id, contact, and title fields against the same fields in the base table row.

Comparing the Timestamp for All Fields in the Base Table Record

The DB_KEYANDTIMESTAMP is the most restrictive type of update, and is only available if the base table has a timestamp column. Visual FoxPro compares the current timestamp on the base table record against the timestamp at the time the data was fetched into the view. If any field in the base table's record has changed, even if it's not a field you're trying to change, or even a field in your view, the update fails.

In the case of the example, Visual FoxPro prepares an update statement that compares the values in the cust_id field and the value in the timestamp field against those fields in the base table row.

In order to successfully update data using the DB_KEYANDTIMESTAMP setting with a multi-table view, you must include the timestamp field in your view for each table that is updatable. For example, if you have three tables in a view and want to update only two of them, and you choose the DB_KEYANDTIMESTAMP setting, you must bring down the timestamp fields from the two updatable tables into your result set. You can also use logical values in the CompareMemo property to determine whether memo fields are included in conflict detection.

See Also

Other Resources

Updating Data
Managing Conflicts when Updating
Programming for Shared Access
Update Criteria
DBSETPROP( )
CURSORSETPROP( )


Managing Conflicts When Updating Data

Visual FoxPro 9.0
Managing Conflicts When Updating Data
See Also

Whether you choose buffering, transactions, or views, you must manage conflicts during the update process. Managing conflicts encountered in multiuser environments can require extensive and repetitive code. A complete conflict management routine performs the following:

  • Detects a conflict.

  • Identifies the nature and location of the conflict.

  • Provides enough information so that the user can intelligently resolve the conflict.

For an example of a conflict management routine, see the data checker class in Samples.vcx, located in the Visual FoxPro ...\Samples\Classes directory. Just add the class to a form and call the CheckConflicts method before any operation that writes buffered data to the table, for example moving the record pointer if you're using row buffering, closing a table, or issuing TABLEUPDATE( ).

Managing Buffering Conflicts

You can make data update operations more efficient by carefully choosing how and when to open, buffer, and lock data in a multiuser environment. You should limit the time a record or table is subject to access conflicts. Still, you must anticipate and manage the inevitable conflicts that result. A conflict occurs when one user tries to lock a record or table that's currently locked by another user. Two users cannot lock the same record or table at the same time.

Your application should contain a routine to manage these conflicts. If your application doesn't have a conflict routine, the system can lock up. A deadlock occurs when one user has locked a record or a table and tries to lock another record that's locked by a second user who, in turn, is trying to lock the record that's locked by the first user. While such occurrences are rare, the longer that a record or table is locked, the greater the chance of deadlock.

Trapping Errors

Designing a multiuser application or adding network support to a single-user system requires that you deal with collisions and trap for errors. Using Visual FoxPro record and table buffers simplifies some of this work.

If you attempt to lock a record or table already locked by another user, Visual FoxPro returns an error message. You can use SET REPROCESS to automatically deal with unsuccessful lock attempts. This command, in combination with an ON ERROR routine and the RETRY command, enables you to continue or cancel the lock attempts.

The following example demonstrates automatic reprocessing of a failed operation, using SET REPROCESS.

Using SET REPROCESS and ON ERROR to Manage User Collisions

Code | Comment
ON ERROR DO err_fix WITH ERROR(),MESSAGE() SET EXCLUSIVE OFF SET REPROCESS TO AUTOMATIC USE customer IF !FILE('cus_copy.dbf') COPY TO cus_copy ENDIF | This routine runs if an error occurs. Open the files non-exclusively. Reprocessing of unsuccessful locks is automatic. Open the table. Create the APPEND FROM table if needed.
DO app_blank DO rep_next DO rep_all DO rep_curr DO add_recs | The main routine starts here. These commands are examples of codes that could be executed in the course of your program.
ON ERROR | The main routine ends here.
PROCEDURE app_blank APPEND BLANK RETURN ENDPROC | Routine to append a blank record.
PROCEDURE rep_next REPLACE NEXT 1 contact WITH ; PROPER(contact) RETURN ENDPROC | Routine to replace data in the current record.
PROCEDURE rep_all REPLACE ALL contact WITH ; PROPER(contact) GO TOP RETURN ENDPROC | Routine to replace data in all records.
PROCEDURE rep_curr REPLACE contact WITH PROPER(contact) RETURN ENDPROC | Routine to replace data in the current record.
PROCEDURE add_recs APPEND FROM cus_copy RETURN ENDPROC | Routine to append records from another file.

The following example demonstrates an error procedure that starts when the user presses ESC.

Error Handling Using the ESC Key

Code | Comment
PROCEDURE err_fix PARAMETERS errnum, msg | This program is called when an error is encountered and the user escapes from the wait process.
DO CASE | Figure out what kind of error this is. Is it "File is in use by another"?
CASE errnum = 108 line1 = "File cannot be locked." line2 = "Try again later..." |
CASE errnum = 109 .OR. errnum = 130 line1 = "Record cannot be locked." line2 = "Try again later." | Or "Record is in use by another"?
OTHERWISE line1 = msg + " " line2 = ; "See your system administrator." ENDCASE | Or is it unknown?
=MESSAGEBOX( line1 + line2, 48, "Error!" ) RETURN | Display the error message in a dialog box with an exclamation point and an OK button.

See Also

Other Resources

Updating Data
Programming for Shared Access
SET REPROCESS
ON ERROR
RETRY


How to: Detect Updating Conflicts

Visual FoxPro 9.0
How to: Detect Updating Conflicts
See Also

During data update operations, especially in shared environments, you might want to determine which fields have changed or what the original or the current values are in changed fields. Visual FoxPro buffering and the GETFLDSTATE( ), GETNEXTMODIFIED( ), OLDVAL( ) and CURVAL( ) functions, enable you to determine which field has changed, find the changed data, and compare the current, original, and edited values so you can decide how to handle an error or conflict.

To detect a change in a field

  • After an update operation, use the GETFLDSTATE( ) function.

GETFLDSTATE( ) works on unbuffered data; however, this function is even more effective when you've enabled record buffering. For instance, use GETFLDSTATE( ) in the code of a Skip button on a form. When you move the record pointer, Visual FoxPro checks the status of all fields in the record as in the following example:

Copy Code
lModified = .F.
FOR nFieldNum = 1 TO FCOUNT( ) && Check all fields
   if GETFLDSTATE(nFieldNum) = 2  && Modified
      lModified = .T.
      EXIT && Insert update/Save routine here.
   ENDIF && See the next example
ENDFOR

To detect and locate a changed record in buffered data

  • Use the GETNEXTMODIFIED( ) function.

GETNEXTMODIFIED( ), with zero as a parameter, finds the first modified record. If another user makes changes to the buffered table, any changes encountered by a TABLEUPDATE( ) command in your buffer will cause conflicts. You can evaluate the conflicting values and resolve them using the CURVAL( ), OLDVAL( ), and MESSAGEBOX( ) functions. CURVAL( ) returns the current value of the record on disk, while OLDVAL( ) returns the value of the record at the time it was buffered.

To determine the original value of a buffered field

  • Use the OLDVAL( ) function.

OLDVAL( ) returns the value of a buffered field.

To determine the current value of a buffered field on disk

  • Use the CURVAL( ) function.

CURVAL( ) returns the current value on disk of a buffered field before any edits were performed.

You can create an error-handling procedure that compares the current and original values, enabling you to determine whether to commit the current change or to accept an earlier change to data in a shared environment.

The following example uses GETNEXTMODIFIED( ), CURVAL( ), and OLDVAL( ) to provide the user with an informed choice in an update operation. This example continues from detection of the first modified record and might be contained in an Update or Save button on a form.

Click Event Code for an Update or Save Button

Code | Comment
nCurRec = GETNEXTMODIFIED(nCurRec) DO WHILE nCurRec <> 0 GO nCurRec RLOCK( ) | Loop through buffer. Lock the modified record.
FOR nField = 1 TO FCOUNT(cAlias) cField = FIELD(nField) IF OLDVAL(cField) <> CURVAL(cField) nResult = MESSAGEBOX("Data was ; changed by another user. ; Keep changes?", 4+48+0, ; "Modified Record") | Look for conflict. Compare the original value to the current value on the disk, and then ask the user what to do about the conflict.
IF nResult = 7 TABLEREVERT(.F.) UNLOCK RECORD nCurRec ENDIF ENDIF ENDFOR nCurRec = GETNEXTMODIFIED(nCurRec) ENDDO | If the user selects "No," revert this record, and then remove the lock. Find the next modified record.
TABLEUPDATE(.T., .T.) | Force update to all records.

You can use the CompareMemo property to control when memo fields are used to detect update conflicts. This view and cursor property determines whether memo fields (types M or G) are included in the update WHERE clause. The default setting, True (.T.), means that memo fields are included in the WHERE clause. If you set this property to False (.F), memo fields don't participate in the update WHERE clause, regardless of the settings of UpdateType.

Optimistic conflict detection on Memo fields is disabled when CompareMemo is set to False. For conflict detection on memo values, set CompareMemo to True (.T.).

See Also

Other Resources

Managing Conflicts When Updating
Programming for Shared Access
Managing Updates by Using Views
GETFLDSTATE( )
GETNEXTMODIFIED( )


Optimizing Applications in Multiuser Environments

Visual FoxPro 9.0
Optimizing Applications in Multiuser Environments
See Also

When writing applications for a multiuser environment, paying attention to performance is particularly important because inefficiencies can multiply. When multiple users access data, your application must handle concurrency and network access issues.

You can use the following suggestions to improve performance and handle these issues:

  • Use table indexing and sorting appropriately.

  • Adjust the interval for lock attempts.

  • Use transaction processing efficiently.

You might also benefit from the suggestions for working with data stored on remote servers. For details, see Optimizing Access to Remote Data.

Indexing and Sorting Tables Appropriately

When the data in a table is relatively static, processing sorted tables sequentially without setting an order improves performance. However, this does not mean that sorted tables cannot or should not take advantage of index files, for example, the SEEK command requires an index and locates records quickly. However, after you find a record using the SEEK command you can turn ordering off.

Adjusting the Interval for Lock Attempts

If your application attempts to lock a record or table and is unsuccessful, you can specify that Visual FoxPro repeat the attempt automatically after a small interval. However, each lock attempt results in network traffic, adding congestion to any existing network traffic, and results in overall diminished performance for all users. To help avoid this scenario, you can call the SYS(3051) - Set Lock Retry Interval function to adjust the interval between lock attempts. Using a larger interval, which results in fewer retries per second, reduces network traffic and increases performance.

For more information, see SYS(3051) - Set Lock Retry Interval.

Using Transaction Processing Efficiently

When using transaction processing, design transactions so that they minimize their impact on other users. Transactions should begin and end as close to the actual data update as possible. An ideal transaction contains only data update statements.

When you append records to a table, Visual FoxPro locks the table header. The header remains locked for the duration of the transaction, preventing other users from also appending records. While a transaction remains open, any locks set during the transaction remain locked until the transaction is committed or rolled back. Even if you call an explicit UNLOCK command, locks remain until you call the END TRANSACTION command or ROLLBACK command. For more information, see UNLOCK Command, END TRANSACTION Command, and ROLLBACK Command.

For example, suppose you add transaction processing to table updates made from a form. Instead of opening a transaction, running the form, and then committing the transaction when the form is closed, put transaction processing statements in the Click event code for a Save command button as shown in the following lines of sample code:

Copy Code
BEGIN TRANSACTION
UPDATE Products SET reorder_amt = 0 WHERE discontinued = .T.
END TRANSACTION

See Also

Other Resources

Optimizing Visual FoxPro in a Multiuser Environment
Optimizing Access to Remote Data
Programming for Shared Access


Visual FoxPro Data Access Using the OLE DB Provider

Visual FoxPro 9.0
Visual FoxPro Data Access Using the OLE DB Provider

You can access Visual FoxPro data from other programming languages and applications. Using the Microsoft OLE DB Provider for Visual FoxPro, you can connect to Visual FoxPro databases and tables and retrieve data from Visual FoxPro databases and tables to use in Visual Studio and Microsoft Office applications and files.

In This Section

OLE DB Provider for Visual FoxPro

Describes the Visual FoxPro OLE DB Provider, the tasks you can perform, and the functionality it provides.
How to: Access Visual FoxPro Data in Visual Studio

Describes ways to access data in Visual FoxPro databases and tables using the Visual FoxPro OLE DB Provider when developing applications in Visual Studio.
How to: Access Visual FoxPro Data in Microsoft Office

Describes how to access data in Microsoft Office applications, such as Word and Excel, from Visual FoxPro databases and tables using the OLE Provider.

Related Sections

Language Reference for OLE DB Development

Describes support in the OLE DB Provider for native Visual FoxPro language and syntax.


OLE DB Provider for Visual FoxPro

Visual FoxPro 9.0
OLE DB Provider for Visual FoxPro
See Also

The Visual FoxPro OLE DB Provider (VfpOleDB.dll) exposes OLE DB interfaces that you can use to access Visual FoxPro databases and tables from other programming languages and applications.

The Visual FoxPro OLE DB Provider includes the following:

  • Support for most Open Database Connectivity (ODBC) driver functionality from earlier versions of FoxPro

  • Improved threading model for scalability

    Note:
    Visual FoxPro OLE DB Provider does not support multiple result sets.

  • Enhanced functionality for and access to stored procedures

    Stored procedures return scalar results in row sets and can accept parameters. The Visual FoxPro OLE DB Provider implements the ICommandPersist interface so that you can create, modify, and delete stored procedure code and modules.

  • Support for DBC events and the capability to create, modify, and delete functions and procedures in the DBC stored procedure module

  • Support for the following Schema Rowsets: Table, Column, Provider Types, Indexes, Primary Keys, Procedures, Foreign Keys, Views, Table Constraints, Check Constraints, and Referential Constraints

  • Recognition of any valid Visual FoxPro configuration file (.fpw) that is stored in the same directory as the Provider. However, only the following settings in the configuration file are recognized by the Provider.

    • MVCOUNT which sets the maximum number of variables that Visual FoxPro can maintain.

    • ENGINEBEHAVIOR which specifies the Engine compatibility level.

    • TABLEVALIDATE which specifies the level of table validation to perform.

You can perform the following functions through the Visual FoxPro OLE DB Provider:

  • Access Visual FoxPro data from external applications.

  • Create n-tier thin and fat clients that access legacy Visual FoxPro data.

  • Use a subset of the Visual FoxPro language in database stored procedures.

  • Create and maintain database containers (DBCs) through extended Data Manipulation Language (DML) functionality and ADOX enhancements to ADO.

The Visual FoxPro OLE DB Provider is supported by OLE DB System Components as provided by MDAC 2.6 or later. The requirements to run the Visual FoxPro OLE DB Provider are the same as for this version of Visual FoxPro.

Note:
When you use Visual FoxPro OLE DB Provider as a SQL Server-linked server, only queries are supported. The Visual FoxPro OLE DB Provider does not support update, insert, or delete operations through a linked server.

Correlation Between Visual FoxPro OLE DB Methods and ODBC Driver Functions

OLE DB and ODBC are different interfaces. No one-to-one correspondence exists between the properties of one interface and the attributes of the other. OLE DB contains a rich definition of property sets and interface method parameters that provide services significantly different from those provided by ODBC.

For more information, see the OLE DB documentation of schema rowsets, property sets, and methods. For a discussion on OLE DB relative to ODBC, see the MSDN article "OLE DB for the ODBC Programmer."

Stored Procedures in the OLE DB Provider

The Visual FoxPro OLE DB Provider accepts stored procedure commands in the following formats:

  • Calling a stored procedure using the conventional syntax:

    Copy Code
    myStoredProc( Param1, Param2, ... )
  • Calling a stored procedure using the SQL EXEC keyword with the following syntax:

    Copy Code
    EXEC myStoredProc( Param1, Param2, ... )
    where each parameter is in the format expected for its data type or is a valid expression that returns that format as in the following example:

    Copy Code
    EXEC myStoredProc( 'characterparm', {^2002/09/09}, dateTime(), 100, 99.99, .T.)
    Note:
    Be sure to replace myStoredProc with the name of the stored procedure you want.

    Tip:
    When you are using ADO or ADO.NET and setting the Command Type to Stored Procedure, you do not need to include the EXEC keyword. If the Command Type is not set to Stored Procedure, you must use the conventional syntaxfor stored procedures or use the EXEC keyword.

Registry Entries

When you install the Visual FoxPro OLE DB Provider, the installation program updates your system registry, HKEY CLASSES_ROOT, and adds the following new keys:

HKEY_CLASSES_ROOT\VFPOLEDB

HKEY_CLASSES_ROOT\VFPOLEDB.1

HKEY_CLASSES_ROOT\Vfpoledb.ConnectionPage

HKEY_CLASSES_ROOT\Vfpoledb.ConnectionPage.1

HKEY_CLASSES_ROOT\VFPOLEDB.ErrorLookup

HKEY_CLASSES_ROOT\VFPOLEDB.ErrorLookup.1

International Support

The Visual FoxPro OLE DB Provider provides international language support for the following:

  • Double-byte character sets (DBCS)

  • Multiple collating sequences

    A collating sequence defines the sort order for data stored in a Visual FoxPro table or database. The Visual FoxPro OLE DB Provider is configured to use collating sequences that support the language version of your operating system by default.

See Also

Other Resources

Visual FoxPro Data Access Using the OLE DB Provider
How to: Access Visual FoxPro Data in Visual Studio
How to: Access Visual FoxPro Data in Microsoft Office
Language Reference for OLE DB Development


How to: Access Visual FoxPro Data in Visual Studio

Visual FoxPro 9.0
How to: Access Visual FoxPro Data in Visual Studio
See Also

You can access Visual FoxPro databases and tables in Visual Studio using the Visual FoxPro OLE DB Provider. The Visual FoxPro OLE DB Provider is available through the Visual Studio Server Explorer or using connection strings in code.

Accessing Visual FoxPro Data Sources Using the Visual Studio Server Explorer

You can access Visual FoxPro databases and tables in Visual Studio by adding them to the list of data connections that appear in the Visual Studio Server Explorer pane. You need to first specify a connection through the Visual FoxPro OLE DB Provider to the databases and tables you want. You can then select the databases or tables so that they appear in the Visual Studio Server Explorer pane.

Note:
You must be able to specify the Visual FoxPro database or table folder you want to access by providing the path and file name or browsing to it.

To connect to a Visual FoxPro database or table through the Visual FoxPro OLE DB Provider

  1. Open Visual Studio.

  2. From the View menu, select Server Explorer.

  3. In the Server Explorer pane, right-click Data Connections, and click Add Connection.

  4. In the Data Link Properties dialog box, click the Provider tab.

  5. Select Microsoft OLE DB Provider for Visual FoxPro.

    The Connection tab in the Data Link Properties dialog box appears.

To add a Visual FoxPro database or table

  1. On the Connection tab and in the Select or enter a database name box, type path and name of the database or table folder you want.

    -or-

    To browse for a Visual FoxPro database or table folder, click the ellipsis (...) button to the right of the Select or enter a database name box to open the Configure Connection dialog box.

  2. Specify a different collating sequence if desired.

  3. To test the connection, click Test Connection. If connection is successful, click OK.

The database or table directory specified appears in the Visual Studio Server Explorer pane below the Data Connections node.

Accessing Visual FoxPro Data Sources Using Connection Strings

To access a Visual FoxPro data source in code, use a valid connection string to specify the Visual FoxPro OLE DB Provider, data source or data source name. For example, you can access the Visual FoxPro OLE DB Provider using Visual FoxPro code.

You can also specify an existing Visual FoxPro ODBC Data Source Name (DSN) instead of a data source. The Provider uses the data source indicated in the DSN and expands it to an appropriate Provider connection string.

To connect to the Visual FoxPro OLE DB Provider in Visual FoxPro

  1. Establish an ActiveX Data Object (ADO) Connection object and create a data object in Visual FoxPro.

  2. Specify the Visual FoxPro OLE DB Provider and data source in a connection string as shown in the following code:

    Copy Code
    oConn = CREATEOBJECT("ADODB.Connection")
oConn.ConnectionString = "provider=vfpoledb.1;;
   data source=.\MyTestDatabase.dbc"
oConn.Open

This code creates a data object you can use to retrieve data.

Note:
Be sure to replace MyTestDatbase with the appropriate database name.

Instead of a data source, you can use an existing Open Database Connectivity (ODBC) data source name (DSN) in the connection string for the Visual FoxPro OLE DB Provider. The Visual FoxPro OLE DB Provider accepts the argument, DSN = cDSNName, and uses the data source specified by the DSN as shown in the following example:

Copy Code
oConn=CREATEOBJECT("adodb.connection")
oConn.ConnectionString="Provider=vfpoledb;DSN=ODBCdataSourceName"
oConn.Open()
Note:
Be sure to replace ODBCdataSourceName with the appropriate ODBC DSN, for example, vfpTestData.

After the connection is open, you can query the value of ConnectionString to determine the data source evaluated.

A connection string includes the following attribute keywords and values:

Provider= cVFPOLEDBProvider

Specifies the Visual FoxPro OLE DB Provider (VFPOLEDB).
Data Source= cPath

Specifies the path to the Visual FoxPro database or a folder containing free tables. For example, c:\Microsoft Visual FoxPro\Samples\Data\Testdata.dbc
DSN= cDSNName

Specifies an existing ODBC DSN.
Mode= cMode

Specifies one of the following: Read, ReadWrite, Share Deny None (default), Share Deny Read, Share Deny Write, or Share Exclusive, which includes the previous two modes.

For a complete explanation of connection string syntax, see the Microsoft OLE DB 2.5 Programmer's Reference and SDK Guide.

Updating Visual FoxPro Data

You can update Visual FoxPro Data through the Visual FoxPro OLE DB Provider using ADO. The following procedure describes three ways you can update Visual FoxPro data using data from the sample Northwind database, located in the Visual FoxPro ..\Samples\Northwind directory.

Note:
Be sure to replace NorthWind.dbc with the database you want to use.

To update Visual FoxPro data through the Visual FoxPro OLE DB Provider using ADO

  1. Call an update, insert, or delete command directly.

    To call an update command directly, use the ADO Execute method. For example:

    Copy Code
    CLEAR
LOCAL oConn as "adodb.connection"
LOCAL oRS as "adodb.recordset"
oConn = CREATEOBJECT('adodb.connection')
oRS = CREATEOBJECT('adodb.recordset')
cConnStrng = ;
   "Provider=vfpoledb;Data Source="+HOME(2)+"Northwind\Northwind.dbc"
oConn.Open(cConnStrng)
oConn.BeginTrans()
oConn.Execute("UPDATE Customers SET contactname = 'Patricio X. Simpson';
   WHERE customerid='CACTU'")
oRS = oConn.Execute("SELECT * FROM customers WHERE customerid = 'CACTU'")
?oRS.Fields("contactname").Value
oConn.RollbackTrans()
oRS.Requery()
?oRS.Fields('contactname').Value
oRS.Close()
oConn.Close()

    -or-

  2. Use a client cursor.

    For example:

    Copy Code
    CLEAR
LOCAL oConn as "adodb.connection"
LOCAL oRS as "adodb.recordset"
oConn = CREATEOBJECT('adodb.connection')
oRS = CREATEOBJECT('adodb.recordset')
cConnStrng = ;
   "Provider=vfpoledb;Data Source="+HOME(2)+"Northwind\Northwind.dbc"
oConn.CursorLocation= 3            && adUseClient
oConn.Open(cConnStrng)

*!* Open RecordSet using keyset cursor and optimistic locking.
oRS.Open(;
   "SELECT * FROM customers WHERE customerid = 'CACTU'",oConn,1,3,1)
? 'Current value:',oRS.Fields("contactname").Value
oRS.Fields("contactname").Value = "Patricio X. Simpson"
oRS.Update()
oRS.Requery()
? 'New value:',oRS.Fields("contactname").Value
oRS.Close()
oConn.Close()

    -or-

  3. Use a server cursor.

    For example:

    Copy Code
    LOCAL oRS as "adodb.recordset"
oConn = CREATEOBJECT('adodb.connection')
oRS = CREATEOBJECT('adodb.recordset')
cConnStrng = ;
   "Provider=vfpoledb;Data Source="+HOME(2)+"Northwind\Northwind.dbc"
oConn.Open(cConnStrng)

*!* Updatable server cursors must use the USE <table name> command to
*!* open the table, not a SELECT statement. Server cursor is updatable,
*!* opened keyset, and lock optimistic.
oRS.Open("USE customers",oconn,1,3,1)
? 'CursorLocation:',IIF(oRS.CursorLocation=2,"adUseServer","adUseClient")

* Find CACTU.
? oRS.Find("customerid='CACTU'")
? 'Current value:',oRS.Fields("contactname").Value
oRS.Fields("contactname").Value = "Patricio Simpson"
oRS.Update()
oRS.Requery()
oRS.Find("customerid='CACTU'")
? 'New value:',oRS.Fields("contactname").Value
oRs.Close()
oRS =''
oConn.Close()oConn=''

Accessing Visual FoxPro Data from Different Languages

You can access the Visual FoxPro OLE DB Provider from other languages using different connection strings, depending on the language. For example, to connect to a Visual FoxPro database from a Visual C# application, you can use the following connection string, replacing myVFPDatabase with the appropriate data source name:

Copy Code
oleDbConnection1.ConnectionString = "Provider=VFPOLEDB.1;" +
   "Data Source=C:\\myVFPDatabase.DBC;";

The following code examples illustrate how to use connection strings that specify the Visual FoxPro OLE DB Provider and data source when accessing Visual FoxPro data from different languages.

Note:
Be sure to replace myVFPDatabase with the appropriate data source or DSN.

To access a Visual FoxPro data source in Visual C#

  • Use a connection string to specify the Visual FoxPro OLE DB Provider and access the data source as shown in the following code:

    Copy Code
    OleDbConnection oleDbConnection1 = new OleDbConnection("Provider=VFPOLEDB.1;" +
      "Data Source=C:\\myVFPDatabase.DBC;");
oleDbConnection1.Open();

To access a Visual FoxPro data source in Visual Basic

  • Use a connection string to specify the Visual FoxPro OLE DB Provider and the data source as shown in the following code, where oConnection represents an ADO Connection object:

    Copy Code
    oConnection.Open("Provider=vfpoledb.1;
   Data Source=.\myVFPDatabase.dbc")

To access Visual FoxPro data using ActiveX Data Objects (ADO) in Visual Basic

  • Use a connection string to specify the Visual FoxPro OLE DB Provider and the data source as shown in the following code:

    Copy Code
    Imports System.Data.OleDb
Public Class ConnectToVFP
    Public Function ADONETOpenVFPDatabase() As Boolean
        Dim bIsConnected As Boolean = True
        Try
            Dim cnn As New OleDbConnection("Provider=VFPOLEDB.1;" + _
               "Data Source=.\MyTestDatabase.dbc;")
            cnn.Open()
        Catch e As System.Exception
            bIsConnected = False
        End Try
        Return bIsConnected
    End Function
End Class
    Note:
    Make sure to replace MyTestDatabase with the name of the database or table directory you want to access.

To access a Visual FoxPro data source in Visual C++

  • Set the database properties by specifying the DBSetProp array, DBProp array, and the IDBProperties pointer, followed by a connection string that specifies the Visual FoxPro OLE DB Provider as shown in the following code:

    Copy Code
    HRESULT hr;
CLSID clsid;

// Set the DBProp array.
DBPROP iProp[1];
DBPROPSET rgIP;
IDBProperties* pIDBProperties = NULL;
IDBInitialize *pIDBInitialize = NULL;
VariantInit(&iProp[0].vValue);
iProp[0].dwOptions = DBPROPOPTIONS_OPTIONAL;    // Required
iProp[0].colid = DB_NULLID;

// Set the location of data source.
iProp[0].dwPropertyID = DBPROP_INIT_DATASOURCE;
iProp[0].vValue.vt = VT_BSTR;
iProp[0].vValue.bstrVal = L"c:\myVFPDatabase.dbc"; // Data source

// Set DBpropset to point to the DBPROP array.
rgIP.guidPropertySet = DBPROPSET_DBINIT;
rgIP.cProperties = 1;
rgIP.rgProperties = iProp;
::CoInitialize(NULL);
hr = CLSIDFromProgID(L"vfpoledb.1",&clsid); // Specify OLE DB Provider.
hr = CoCreateInstance(clsid,
       NULL,
       CLSCTX_INPROC_SERVER,
       IID_IDBInitialize,
       (void**)&pIDBInitialize);

// Initialize.
hr = piDBInitialize->QueryInterface(_uuidof(IDBProperties), (void**)&pIDBProperties);
hr = pIDBProperties->SetProperties(1 , &rgIP) ;
hr = pIDBProperties->Release();
hr = pIDBInitialize->Initialize();

To access a Visual FoxPro data source in ASP using ActiveX Data Objects (ADO)

  1. Create an ASP page with appropriate HTML tags.

  2. To establish a connection and run commands using ADO, add Visual Basic Scripting Language (VBScript) code:

    Copy Code
    <%
    Set conn = Server.CreateObject("ADODB.Connection")
    conn.ConnectionString="Provider=VFPOLEDB.1;
       Data Source=myVFPDatabase.dbc"
    conn.Open
    sql = "select * from tableName"
    Set rsArrival = conn.Execute(sql)
%>
    Note:
    Be sure to replace tableName with the name of the table you want.

To access a Visual FoxPro data source in JScript

  • Use a connection string to specify the Visual FoxPro OLE DB Provider and data source as shown in the following code:

    Copy Code
    var vbOKCancel = 0;
var vbInformation = 64;
var vbCancel = 2;
var L_Welcome_MsgBox_Message_Text = "This script demonstrates how to access VFP OLE DB Provider using the Windows Scripting Host.";
var L_Welcome_MsgBox_Title_Text = "VFP OLE DB Provider JScript Sample";
var sBuffer = "";
var sConnString = "Provider=vfpoledb.1;Data Source=myVFPDatabase.dbc";
var oConn = new ActiveXObject("ADODB.Connection");
var oRS = new ActiveXObject("ADODB.Recordset");
oConn.Open(sConnString);
oRS.Open("select * from tableName where fieldName1='fieldValue'",oConn,3,3);
// Get tableName.fieldName2
sBuffer = oRS.Fields('fieldName2').value;

var WSHShell = WScript.CreateObject("WScript.Shell");
var intDoIt;
intDoIt =  WSHShell.Popup(sBuffer,
   0,
   L_Welcome_MsgBox_Title_Text,
   vbOKCancel );
   if (intDoIt == vbOKCancel) {
      oRS.Close();
      oConn.Close();
      WScript.Quit();
}
    Note:
    Be sure to replace myVFPDatabase, tableName, fieldName1, fieldName2, and fieldValue with the appropriate values. You must use a backslash (\) escape characters to include the backslash character in the file path, for example, "c:\\MyFolder\\MyVFP.dbc".

See Also

Other Resources

Visual FoxPro Data Access Using the OLE DB Provider
OLE DB Provider for Visual FoxPro
How to: Access Visual FoxPro Data in Microsoft Office
Language Reference for OLE DB Development


How to: Access Visual FoxPro Data in Microsoft Office

Visual FoxPro 9.0
How to: Access Visual FoxPro Data in Microsoft Office
See Also

You can access data from Visual FoxPro databases and tables in Microsoft Office applications, such as Microsoft Excel or Microsoft Word, using the Visual FoxPro OLE DB Provider.

Note:
You can import Visual FoxPro data using the Visual FoxPro OLE DB Provider only in Office XP.

To connect to a Visual FoxPro database or table in Excel

  1. Open an Excel worksheet.

  2. From the Data menu, point to Import External Data, and click Import Data.

  3. In the Select Data Source dialog box, click New Source Data Connection.

  4. In the Data Connection Wizard, select Other/Advanced.

  5. In the Provider tab, select Microsoft OLE DB Provider for Visual FoxPro.

The Connection tab in the Data Link Properties dialog box appears.

To connect to a Visual FoxPro database or table in Word

  1. Open a Word document.

  2. From the View menu, point to Toolbars, and click Database.

  3. On the Database toolbar, click the Insert Database icon.

  4. In the Database dialog box, click Get Data.

  5. In the Select Data Source dialog box, click New Source Data Connection.

  6. In the Data Connection Wizard, select Other/Advanced.

  7. In the Provider tab, select Microsoft OLE DB Provider for Visual FoxPro.

The Connection tab in the Data Link Properties dialog box appears.

To add a Visual FoxPro database or table folder

  1. On the Connection tab and in the Select or enter a database name box, type path and name of the database or table folder you want.

    -or-

    To browse for a Visual FoxPro database or table folder, click the ellipsis (...) button to the right of the Select or enter a database name box to open the Configure Connection dialog box.

  2. Specify a different collating sequence if desired.

  3. To test the connection, click Test Connection. If connection is successful, click OK.

See Also

Other Resources

Visual FoxPro Data Access Using the OLE DB Provider
OLE DB Provider for Visual FoxPro
How to: Access Visual FoxPro Data in Visual Studio
Language Reference for OLE DB Development


Enhancing Applications Using SQL Pass-Through Technology

Visual FoxPro 9.0
Enhancing Applications Using SQL Pass-Through Technology

Whether you create and upsize a working local prototype or develop your application against remote data using remote views, you gain access to the large data stores typically available in a server database. In addition, you can take advantage of the security and transaction processing capabilities of the remote server. While remote views handle the main data management tasks, you can enhance your application by using SQL pass-through (SPT) technology to create objects on the server, run stored procedures on a server, and execute commands using native server syntax.

The following topics discuss techniques for implementing client/server technology in a working application that uses remote views.

In This Section

How to: Set Up an ODBC Data Source

Describes how to install an ODBC driver and set up an ODBC data source so you can create remote views or use SQL pass-through.
Using SQL Pass-Through Technology

Describes how remote views provide the easiest and most common method for accessing and updating remote data. The upsizing wizards can create remote views automatically in your database as part of upsizing, or you can use Microsoft Visual FoxPro to create remote views after upsizing.
Working with Remote Data Using SQL Pass-Through

Explains that after you retrieve a result set using SQL pass-through, you can view and control the properties of your result set cursor using the Microsoft Visual FoxPro functions CURSORGETPROP( ) and CURSORSETPROP( ).
Handling SQL Pass-Through Errors

Explains that Microsoft Visual FoxPro stores an error returned by a SQL pass-through function error message in an array.

Related Sections

Using Visual FoxPro

Describes Visual FoxPro programming features designed to improve developer productivity, including Access and Assign methods, support for more graphic file formats, and language to simplify programming tasks.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Application Planning

Describes how careful planning saves time, effort, and money and how many of the decisions you make during the planning phase will impact how you create elements of the application.
Creating Applications

Discusses how to create a Visual FoxPro application, which may include one or more databases, a main program that sets up the application's system environment, and a user interface comprised of forms, toolbars, and menus.
Web Services and Components

Explains how you can extend your Visual FoxPro application to work for multiple users, and take advantage of Microsoft ActiveX controls and automation-enabled applications.
Working with Data

Describes how to create effective applications with indexes, tables, and databases based on your data requirements.
Working with Projects

Defines a project a configuration and a group of files that produce a program or final binary file or files.

Compiling an Application

Explains how to use the modular approach so you can verify the functionality of each component you create before you compile them into an application, which assembles the executable components of your project.
Testing and Debugging Applications

Describes Visual FoxPro debugging tools that help you find and correct any errors you discover in your applications.
Distributing Applications

Explains how to prepare to distribute your application by including all required files and creating distribution disks, after you have completed developing and testing your application.


How to: Set Up an ODBC Data Source

Visual FoxPro 9.0
How to: Set Up an ODBC Data Source
See Also

Before you can create remote views or use SQL pass-through, you must install an ODBC driver and set up an ODBC data source.

Choosing an ODBC Driver

To install the ODBC drivers for these types of data, use the Visual FoxPro Setup program. If you choose the Complete install option, all drivers are installed.

Once you've chosen a driver, you can use the default data source or add an ODBC data source for it.

To add an ODBC data source

  1. Choose the Administrative Tools icon from the Windows Control Panel.

  2. Choose the Data Sources shortcut.

  3. In the ODBC Data Source Administrator dialog box, click Add, then select the driver you want from the Installed ODBC Drivers list and choose OK.

  4. In the Setup dialog box, set option values as necessary and choose OK.

For information on setting up a data source specific to the driver you have chosen, choose the Help button in the ODBC Setup dialog box.

Installing ODBC Data Sources

You can get Open Database Connectivity (ODBC) support if you choose the Complete or Custom installation option. With ODBC, you can access a SQL Server data source from Visual FoxPro; however, before you can access the data source, you must define it.

To define a data source

  1. Switch to the Windows Control Panel and choose the ODBC icon.

  2. In the Data Sources dialog box, choose Add.

  3. In the Add Data Source dialog box, select the SQL Server ODBC driver and choose OK.

  4. In the ODBC SQL Server Setup dialog box, enter the data source name, description, and other appropriate information, and then choose OK.

  5. In the Data Sources dialog box, choose Close.

See Also

Other Resources

Installing Visual FoxPro
Upgrading from Earlier Versions
Enhancing Applications Using SQL Pass-Through Technology


Using SQL Pass-Through Technology

Visual FoxPro 9.0
Using SQL Pass-Through Technology

Using remote views is the easiest and most common method to access and update remote data. SQL pass-through technology allows you to send SQL statements directly to the server and, because the statements execute on the server, they are a powerful way to enhance the performance of your client/server application.

The following topics provide information on how to use SQL pass-through technology in your applications.

In This Section

How to: Access Server Stored Procedures with SQL Pass-Through Functions

Describes how to use server stored procedures. Server stored procedures can greatly enhance performance of SQL statements and batches.
How to: Use SQL Pass-Through Functions

Explains how your client/server application can access remote data with SQL pass-through. A comparison of remote views and SQL pass-through technologies is also provided.
Visual FoxPro SQL Pass-Through Functions

Provides a list of SQL Pass-Through functions.
Using Result Sets

Explains how Visual FoxPro handles result sets that are returned from SQL Pass-Through functions.
How to: Return Multiple Result Sets

Explains how to retrieve multiple result sets, such as those from a stored procedure that contains native server SELECT statements.
How to: Create a Parameterized Query

Explains how to create a parameterized query with SQL pass-through technology.
Using SQL Server Input/Output Parameters

Describes how to use input and output parameters to pass values between SQL Server and Visual FoxPro.
Execution of ODBC Extensions to SQL

Provides information on how to execute OBDC extensions to SQL.
Managing Connections with SQL Pass-Through

Describes how to manage your server connections by providing an overview of the various environment and connection properties and how to set them.
Sharing Connections for Remote Data

Describes how Visual FoxPro makes it possible for you to share a connection handle for a remote data connection, which is useful for reducing the number of connections when managing SQL Server connections and server resources.
How to: Use Automatic Transaction Mode

Describes how to set Visual FoxPro to automatically wrap every data-writing operation sent to a remote server in a transaction.
How to: Control Transactions Manually

Describes how to manually control transactions with a remote server.
Selecting the Right Methods

Describes and contrasts the best practices for use of remote views and SQL pass-through technology in your client/server application.

Related Sections

Working with Remote Data Using SQL Pass-Through

Explains how you can view and control the properties of a SQL pass-through query result set cursor using the Microsoft Visual FoxPro functions CURSORGETPROP( ) and CURSORSETPROP( ).
Working with Data

Describes how to create effective applications with indexes, tables, and databases based on your data requirements.
Handling SQL Pass-Through Errors

Explains how to retrieve information about the error to examine the error and to determine its cause.


How to: Access Stored Procedures on Remote Servers with SQL Pass-Through Functions

Visual FoxPro 9.0
How to: Access Stored Procedures on Remote Servers with SQL Pass-Through Functions
See Also

You can use Visual FoxPro SQL pass-through technology to create and execute stored procedures on a remote server. Stored procedures can greatly enhance the power, efficiency, and flexibility of SQL, and dramatically improve the performance of SQL statements and batches. Many servers provide stored procedures for defining and manipulating server database objects and for performing server system and user administration.

Note:
The examples in this section use Microsoft SQL Server syntax unless otherwise noted.

To call a server stored procedure

  • Use the SQLEXEC( ) Function with the stored procedure name.

For example, the following code displays the results of calling a stored procedure named sp_who on SQL Server using an active connection to the data source sqlremote:

Copy Code
nConnectionHandle = SQLCONNECT('sqlremote')
? SQLEXEC(nConnectionHandle, 'use pubs')
? SQLEXEC(nConnectionHandle, 'sp_who')
BROWSE

For more information on creating and executing stored procedures on a remote server, see your server documentation.

See Also

Other Resources

Using SQL Pass-Through Technology
How to: Return Multiple Result Sets
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


How to: Use SQL Pass-Through Functions

Visual FoxPro 9.0
How to: Use SQL Pass-Through Functions
See Also

Your client/server application can access server data by using:

  • Remote views

  • SQL pass-through

Remote views provide the most common and easiest method for accessing and updating remote data. The upsizing wizards can automatically create remote views in your database as part of upsizing, or you can use Visual FoxPro to create remote views after upsizing. For more information on remote views, see How to: Create Remote Views.

SQL pass-through technology enables you to send SQL statements directly to a server. SQL pass-through statements, because they execute on the back-end server, are powerful ways to enhance the performance of your client/server applications. The following table compares remote views with SQL pass-through.

Comparison of Remote View and SQL Pass-Through Technologies

Remote View | SQL Pass-Through
Based on a SQL SELECT statement. | Based on any native server SQL statement, enabling data definition statements or execution of stored procedures on a remote server.
Can be used as data source for controls at design time. | Can't be used as a data source for controls.
Provides no ability to execute DDL commands on data source. | Provides method for using DDL commands on data source.
Fetches one result set. | Fetches one or multiple result sets.
Provides built-in connection management. | Requires explicit connection management.
Provides built-in default update information for updates, inserts, and deletes. | Provides no default update information.
Provides implicit SQL execution and data fetching. | Provides explicit SQL execution and result fetching control.
Provides no transaction handling. | Provides explicit transaction handling.
Stores properties persistently in database. | Provides temporary properties for SQL pass-through cursor, based on session properties.
Employs asynchronous progressive fetching while executing SQL. | Fully supports programmatic asynchronous fetching.

SQL pass-through technology offers the following advantages over remote views:

  • You can use server-specific functionality, such as stored procedures and server-based intrinsic functions.

  • You can use extensions to SQL supported by the server, as well as data-definition, server administration, and security commands.

  • You have more control over SQL pass-through Update, Delete, and Insert statements.

  • You have more control over remote transactions.

    Tip:
    Visual FoxPro can handle SQL pass-through queries that return more than a single result set.

SQL pass-through queries also have disadvantages:

  • By default, a SQL pass-through query always returns a non-updatable snapshot of remote data, which is stored in an active view cursor. You can make the cursor updatable by setting properties with the CURSORSETPROP( ) Function. An updatable remote view, in contrast, usually doesn't require that you set properties before you can update remote data, because property settings are stored in the database with the view definition.

  • You must enter SQL commands directly into the Command window or into a program, rather than using the graphical View Designer.

  • You create and manage the connection to the data source.

Whether you use remote views or SQL pass-through, you can query and update remote data. In many applications, you'll use both remote views and SQL pass-through.

Using SQL Pass-Through Functions

To use SQL pass-through to connect to a remote ODBC data source, you first call the Visual FoxPro SQLCONNECT( ) Function to create a connection. You then use the Visual FoxPro SQL pass-through functions to send commands to the remote data source for execution.

To use Visual FoxPro SQL pass-through functions

  1. Confirm your system's ability to connect your computer to your data source. Use a utility such as ODBC Test for ODBC.

  2. Establish a connection to your data source with the SQLCONNECT( ) Function or the SQLSTRINGCONNECT( ) Function.

    For example, if you're connecting Visual FoxPro to the SQL Server data source sqlremote, you might log on with the following command:

    Copy Code
    nConnectionHandle = SQLCONNECT('sqlremote','<userid>','<password>')
    Note:
    You can also use the SQLCONNECT() function to connect to a named connection.

  3. Use Visual FoxPro SQL pass-through functions to retrieve data into Visual FoxPro cursors and process the retrieved data with standard Visual FoxPro commands and functions.

    For example, you might query the authors table and browse the resulting cursor using this command:

    Copy Code
    ? SQLEXEC(nConnectionHandle,"select * from authors","mycursorname")
BROWSE

  4. Disconnect from the data source with the SQLDISCONNECT( ) function.

See Also

Other Resources

Visual FoxPro SQL Pass-Through Functions
Using Result Sets
Using SQL Pass-Through Technology
Enhancing Applications Using SQL Pass-Through Technology
How to: Access Server Stored Procedures with SQL Pass-Through Functions
How to: Return Multiple Result Sets
Processing Multiple Result Sets
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Visual FoxPro SQL Pass-Through Functions

Visual FoxPro 9.0
Visual FoxPro SQL Pass-Through Functions
See Also

The following table lists the Visual FoxPro SQL functions that support working with remote data sources, grouped according to task.

Task | Function | Purpose
Connection management | SQLCONNECT( ) | Connects to a data source for SQL pass-through operations.
 | SQLSTRINGCONNECT( ) | Connects to a data source using ODBC connection string syntax.
 | SQLDISCONNECT( ) | Breaks a connection to an ODBC data source, making the specified connection handle obsolete.
 | SQLIDLEDISCONNECT( ) | Allows a SQL pass-through connection or connections to be temporarily disconnected.
SQL statement execution and control | SQLCANCEL( ) | Cancels an asynchronously executing SQL query on an active connection.
 | SQLEXEC( ) | Executes a SQL pass-through query on an active connection; returns the number of result sets generated, or 0 if SQLEXEC( ) is still executing (asynchronous processing).
 | SQLMORERESULTS( ) | Puts another result set into a cursor. Returns 0 if the statement creating the result set is still executing.
 | SQLPREPARE( ) | Pre-compiles the SQL statement on the data source and binds the Visual FoxPro parameters, i.e. saves the actual parameter expressions for all the parameters in the SQL statement.
 | SQLCOMMIT( ) | Requests a transaction commitment.
 | SQLROLLBACK( ) | Requests a transaction rollback.
Data source information | SQLCOLUMNS( ) | Stores a list of column names and information about each to a cursor. Returns 1 if the function succeeds, or 0 if the function is still executing.
 | SQLTABLES( ) | Stores the names of tables in the source into a cursor. Returns 1 if the function succeeds, or 0 if the function is still executing.
Miscellaneous control | SQLGETPROP( ) | Gets a connection property from an active connection.
 | SQLSETPROP( ) | Sets a property of an active connection.

The SQLEXEC( ), SQLMORERESULTS( ), SQLTABLES( ), and SQLCOLUMNS( ) statements can be canceled in synchronous mode by pressing ESC if SET ESCAPE is set to ON. You can cancel these statements at any time in asynchronous mode by issuing SQLCANCEL( ). All other SQL pass-through statements function synchronously and are not interruptible.

See Also

Other Resources

How to: Use SQL Pass-Through Functions
Using SQL Pass-Through Technology
Using Result Sets
Enhancing Applications Using SQL Pass-Through Technology
How to: Access Server Stored Procedures with SQL Pass-Through Functions
How to: Return Multiple Result Sets
Processing Multiple Result Sets
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Using Result Sets

Visual FoxPro 9.0
Using Result Sets
See Also

When you use the SQL pass-through functions SQLEXEC( ) or SQLMORERESULTS( ) to query data, Visual FoxPro returns the data to you in one or many result sets. Result sets originate from cursors in the server data source and become cursors in Visual FoxPro. The default name for a result set is SQLRESULT.

How the Server Processes Result Sets and Errors

Because the server compiles each stored procedure when you create it, you receive any server syntax errors at create time. When you execute the stored procedure, the server executes the compiled SQL statements sequentially (as in a Visual FoxPro program) and Visual FoxPro fetches each result set from each SQL statement within the stored procedure separately, in the order executed.

Result sets and errors are returned in the order received, and processing stops if an error is encountered. For example, if a run-time error occurs when the server executes the third statement in a four-statement stored procedure, you receive the first two result sets and then receive the error that occurred upon processing the third result set. Processing stops after the error is returned; the fourth result set is not retrieved. You can use the AERROR( ) function to obtain information about the most recent error.

Note:
You can execute stored procedures on a remote server from Visual FoxPro only by using Visual FoxPro SQL pass-through functions. Views don't support stored procedures on a remote server, because each view contains an explicit SQL SELECT statement in its SQL definition.

See Also

Other Resources

How to: Use SQL Pass-Through Functions
Using SQL Pass-Through Technology
Enhancing Applications Using SQL Pass-Through Technology
How to: Access Server Stored Procedures with SQL Pass-Through Functions
How to: Return Multiple Result Sets
Processing Multiple Result Sets
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


How to: Return Multiple Result Sets

Visual FoxPro 9.0
How to: Return Multiple Result Sets
See Also

If you execute a stored procedure that contains native server syntax SELECT statements, each result set is returned to a separate Visual FoxPro cursor. You can use these cursors to return values or parameters from a stored procedure on a remote server to the Visual FoxPro client.

To return multiple result sets

  • Use the SQLEXEC( ) Function to select multiple results sets using your native server syntax.

For example, the following code creates and executes a SQL stored procedure on a remote server, my_procedure, that returns three Visual FoxPro cursors: sqlresult, sqlresult1, and sqlresult2:

Copy Code
=SQLEXEC(nConnectionHandle,'create procedure my_procedure as ;
      select * from sales; select * from authors;
      select * from titles')
=SQLEXEC(nConnectionHandle,'execute my_procedure')

The SQLEXEC( ) Function enables you to send a SQL statement to the data source without interpretation. In the simplest case, any string you enclose in the second parameter of the SQLEXEC( ) function is passed to your data source without interpretation. This allows you to execute any statement using your data source's native SQL.

You can also use the SQLEXEC( ) function to create a parameterized query, or to pass ODBC extensions to SQL to the data source.

See Also

Other Resources

How to: Access Stored Procedure on Remote Servers Using SQL Pass-Through Functions
How to: Create a Parameterized Query
Using SQL Pass-Through Technology
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


How to: Create a Parameterized Query

Visual FoxPro 9.0
How to: Create a Parameterized Query
See Also

Just as you can create parameterized views using the View Designer or the language, you can create a parameterized SQL pass-through query.

To create a parameterized query with SQL pass-through

  • Precede a Visual FoxPro parameter with a question mark (?), and then include the parameter in a SQL string you send with SQLEXEC( ) Function.

The parameter you supply is evaluated as a Visual FoxPro expression, and the value is sent as part of the view's SQL statement. If the evaluation fails, Visual FoxPro prompts for the parameter value.

For example, if you have the customer table from the Testdata database on a remote server, the following code creates a parameterized query that limits the view to those customers whose country matches the value supplied for the cCountry parameter:

Copy Code
? SQLEXEC(1,'SELECT * FROM customer WHERE customer.country = cCountry')

If you want to prompt the user for a parameter value, precede the parameter expression with a question mark (?). For more information, see How to: Create Parameterized Views.

Your ODBC data source doesn't accept parameters in the following locations:

  • In a SELECT fields or tables list.

  • As both expressions in a comparison predicate.

  • As both operands of a binary operator.

An ODBC data source will not accept parameters in the following locations in the WHERE or HAVING clause of a SELECT statement:

  • As both the first and second operands of a BETWEEN predicate.

  • As both the first and third operands of a BETWEEN predicate.

  • As both the expression and the first value of an IN predicate.

  • As the operand of a unary + or - operator.

  • As the argument of a SET function.

For more information, see Using SQL Server Input/Output Parameters.

See Also

Other Resources

How to: Return Multiple Result Sets
Using SQL Pass-Through Technology
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Using SQL Server Input/Output Parameters

Visual FoxPro 9.0
Using SQL Server Input/Output Parameters
See Also

You can use input/output parameters to pass values between Visual FoxPro and SQL Server. Input/output parameters are available only using SQL pass-through; they can't be used in views.

The following table provides an example using input/output parameters to pass values from Visual FoxPro to a SQL Server stored procedure, returning the result to a Visual FoxPro variable.

Using Input/Output Parameters with a SQL Server Stored Procedure

Code | Comments
resultCode = SQLExec(connHand, "CREATE PROCEDURE sp_test; @mult1 int, @mult2 int, @result int; OUTPUT AS SELECT @result = @mult1 * @mult2") | Create a stored procedure, sp_test, that multiplies two variables (mult1 and mult2), then stores the resulting amount in the variable result.
outParam = 0 | Create a Visual FoxPro variable to receive the output parameter value when it's passed from SQL Server to Visual FoxPro.
resultCode = SQLExec(connHand, ; "{CALL sp_test (2, 4, ?@outParam)}") | Execute the SQL Server stored procedure, passing the values '2' and '4' to be multiplied together in the stored procedure.
? "outParam =", outParam && the value is 8 | Display the value of the output parameter.

Defining Parameters

The syntax for output parameters is:

Copy Code
?@parameter_name

When you implement input/output parameters, define the Visual FoxPro variables you want to include in your SQL pass-through command before you use the variables in the SQL statement. To successfully send and receive information with input/output parameters, you must define:

  • A stored procedure parameter, with an output type, that returns a value.

    For example, if your stored procedure parameter is @result, you must assign an output type, such as int, to @result, and you must assign a value to @result.

  • An output parameter (@parameter_name) expression that evaluates to an existing Visual FoxPro variable.

    For example, if your output parameter expression is ?@outParam, your application must have defined the Visual FoxPro variable outParam.

    Note:
    If you don't use an output parameter, either in Visual FoxPro or in the stored procedure, or you don't define a Visual FoxPro variable to receive the return value, the Visual FoxPro parameter value will not change.

Converting Data Types

Visual FoxPro converts returned variable values using the following rules:

  • Floating point data type (N, F, B) variables are converted to N.

  • The display size is set to 20.

  • The decimal setting is set to the current session setting. The decimal setting affects only the default display format, and doesn't affect the decimal precision.

  • Date and time variables (D, T) are converted to time (T) variables.

You can't use Memo, General, Picture, or NULL data types in input/output parameters.

If your application uses cursor fields as parameters, Visual FoxPro will attempt to convert the result back to the original field data type.

Returning Parameter Values

Input/output parameters are available only after the last result set of a statement has been fetched. This means that input/output values are returned to Visual FoxPro only after:

  • SQLEXEC( ) returns (1) in batch mode

    -or-

  • SQLMORERESULTS( ) returns (2) in non-batch mode.

If your SQLEXEC( ) statement requests multiple result sets, the output parameters are only guaranteed to be available after the last result set has been fetched from the data source.

See Also

Other Resources

How to: Create a Parameterized Query
How to: Return Multiple Result Sets
Using SQL Pass-Through Technology
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Execution of ODBC Extensions to SQL

Visual FoxPro 9.0
Execution of ODBC Extensions to SQL
See Also

You can use the SQLEXEC( ) function to execute ODBC extensions to SQL by enclosing the SQL statement with SQL Access Group standard or extended escape syntax. For more information about ODBC extensions to SQL, refer to the SQL Grammar appendix in your ODBC documentation.

Creating Outer Joins Using the ODBC Escape Clause

You can use SQL pass-through to perform outer joins on remote data using the ODBC escape syntax, if your server supports outer joins. An outer join combines information from one or more tables regardless of whether matching rows are found.

The syntax for outer joins using the ODBC escape clause is:

Copy Code
{oj outer-join expression}

The following example creates a result set of the names and departments of employees working on project 544:

Copy Code
SELECT employee.name, dept.deptname;
   FROM {oj employee LEFT OUTER JOIN dept;
            ON employee.deptid = dept.deptid};
   WHERE employee.projid = 544

For more information on outer join syntax and types of outer joins, see your server documentation. For information on creating a named connection, see How to: Define Connections to Remote Data Sources.

See Also

Other Resources

Managing Connections with SQL Pass-Through
Using SQL Pass-Through Technology
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases


Managing Connections with SQL Pass-Through

Visual FoxPro 9.0
Managing Connections with SQL Pass-Through
See Also

When you create a remote view, you choose an ODBC data source name or a connection name that is then used as a pipeline to the remote server upon activation of the view. To access remote data directly with SQL pass-through, you must have the handle for an active connection. A handle is a value that refers to an object; in this case, the handle refers to a data source connection. To obtain a handle, you request a connection to the data source using the SQLCONNECT( ) or SQLSTRINGCONNECT( ) function. If the connection is successful, your application receives a connection handle for use in subsequent Visual FoxPro calls.

Your application can request multiple connections for one data source. You can also work with multiple ODBC data sources by requesting a connection to each data source you want to access. If you want to reduce the number of connections used, you can configure remote views to share the same connection. You disconnect from a data source with the SQLDISCONNECT( ) function.

Tip:
Visual FoxPro relies on the definition of the ODBC data source that is stored in Windows to connect to a data source. If you change the name or the logon information for a data source, keep in mind that these changes might affect whether an application using that data source can connect to the desired remote server.

Controlling Environment and Connection Properties

The client/server environment is established each time you open Visual FoxPro. The environment exists for that session of Visual FoxPro and disappears when you close Visual FoxPro. The client/server environment contains:

  • Global properties that act as the prototypes for new connections.

  • Error values for errors that occur outside a specific connection.

You can use a handle of 0, the environment handle, to refer to global property settings. You use the SQLSETPROP( ) function to control default property settings in the connection environment and properties within individual connections. The methods you use for entering SQLSETPROP( ) values are consistent for both the environment and individual connections:

  • Properties specified with one of two values can use a logical value (.F. or .T.) for eExpression.

  • A property name can be abbreviated to its shortest unambiguous truncation. For example, you can use "Asynchronous", "Asynch", or "A" to specify the Asynchronous property. Property names aren't case-sensitive.

When you initiate a connection, the connection inherits default connection property values. You can use SQLSETPROP( ) to change these values.

Setting Connection Properties

To view the current settings for a connection, use the SQLGETPROP( ) function with the respective connection handle. The following table lists the connection settings you can access with SQLGETPROP( ).

Visual FoxPro Connection Properties

To | Use this setting | Purpose
Display the information used to create the active connection | ConnectString | The login connection string.
 | DataSource | The name of the data source as defined by ODBC.
 | Password | The connection password.
 | UserID | The user identification.
Work with shared connections | ConnectBusy | True (.T.) if a shared connection is busy; false (.F.) otherwise.
Control interface display | DispLogin | Controls when the ODBC Login dialog box is displayed.
 | DispWarnings | Controls whether non-fatal warning messages are displayed or not.
Control time intervals | ConnectTimeout | Specifies the time (in seconds) to wait before returning a connection time-out error.
 | IdleTimeout | Specifies the idle time-out interval (in seconds). Qualifying active connections are deactivated after the specified time interval.1
 | WaitTime | Controls the amount of time in milliseconds that elapses before Visual FoxPro checks whether the SQL statement has completed executing.
 | QueryTimeout | Controls the time (in seconds) to wait before returning a general time-out error.
Manage transactions | Transactions | Determines how the connection manages transactions on the remote table.
Control fetching of result sets into view cursors | Asynchronous | Specifies if result sets are returned synchronously (the default) or asynchronously.
 | BatchMode | Specifies if SQLEXEC( ) returns result sets all at once (the default), or individually with SQLMORERESULTS( ).
 | PacketSize | Specifies the size of the network packet used by the connection.
Display internal ODBC handles | ODBChdbc2 | The internal ODBC connection handle that can be used by external library files (.fll files) to call the ODBC API functions.
 | ODBChstmt2 | The internal ODBC statement handle that can be used by external library files (.fll files) to call the ODBC API functions.

1. If in manual transaction mode, the connection is not deactivated.

2. If a connection is deactivated, the ODBChdbc and ODBChstmt values are no longer valid. Do not free or drop these values in a user library.

For more information on connection properties and their default settings, see SQLSETPROP( ).

Controlling Environment Property Settings

The values you set in the Visual FoxPro environment using handle 0 are used as prototypes or default values for each subsequent connection or attachment.

To view the current environment property settings, use SQLGETPROP( ) with 0 as the value for the handle.

The following example displays the current environment's WaitTime property setting:

Copy Code
? SQLGETPROP(0, "WaitTime")

If you set the DispWarnings property to true (.T.), Visual FoxPro displays any environment errors from that point on, and also sets DispWarnings to true (.T.) for newly created connections.

Although the values you set for handle 0 are used as prototype values for each connection, you can also set custom properties for an individual connection by issuing SQLSETPROP( ) for that connection handle. The exceptions are the ConnectTimeout, PacketSize, and DispLogin properties, whose settings the connection inherits at connect time. If you change the setting of the ConnectTimeout, PacketSize, or DispLogin property, the new setting isn't used until you reconnect.

Controlling Connection and View Objects

You can control connections and views by setting properties on the connection or view object. Properties that control databases, tables, table fields, view definitions, view fields, named connections, active connections, or active view cursors are called engine properties. You can display or set engine properties with one of the following Visual FoxPro functions:

To display engine properties use | To set engine properties use
CURSORGETPROP( ) | CURSORSETPROP( )
DBGETPROP( ) | DBSETPROP( )
SQLGETPROP( ) | SQLSETPROP( )

The function you use depends on whether you want to set properties on object 0 (connection 0 and cursor 0), the object definition in a database (named connection or view definition), or the active object (active connection or active view cursor). The following table lists objects and the functions you use to set properties on each object:

To set properties for | Connection | View
Object 0 | SQLSETPROP( ) | CURSORSETPROP( )
Object definition in a database | DBSETPROP( ) | DBSETPROP( )
Active object | SQLSETPROP( ) | CURSORSETPROP( )

Engine Properties

The following diagram lists engine properties alphabetically along with the objects that use each property.

The following table lists engine properties alphabetically along with the functions you can use to set those properties.

Engine property | Applies to
Asynchronous | Connection definitions: see DBSETPROP( ). Active connections: see SQLSETPROP( ).
BatchMode | Connection definitions: see DBSETPROP( ). Active connections: see SQLSETPROP( ).
BatchUpdateCount1 | View definitions: see DBSETPROP( ). Active view cursors: see CURSORSETPROP( ).
Buffering | Active view cursors: see CURSORSETPROP( ).
Caption | Fields in tables, fields in view definitions: see DBSETPROP( ).
Comment | Databases, tables, fields in tables, view definitions, fields in view definitions, connection definitions: see DBSETPROP( ).
CompareMemo | View definitions: see DBSETPROP( ). Active view cursors: see CURSORSETPROP( ).
ConnectBusy | Active connections: see SQLGETPROP( ).
ConnectHandle | Active view cursors: see CURSORGETPROP( ).
ConnectName1 | View definitions: see DBSETPROP( ). Active connections: see SQLGETPROP( ). Active view cursors: see CURSORGETPROP( ).
ConnectString | Connection definitions: see DBSETPROP( ). Active connections: see SQLGETPROP( ).
ConnectTimeout | Connection definitions: see DBSETPROP( ). Active connections: see SQLSETPROP( ).
Database | Active view cursors: see CURSORGETPROP( ).
DataSource | Connection definitions: see DBSETPROP( ). Active connections: see SQLGETPROP( ).
DataType | Fields in view definitions: see DBSETPROP( ).
DefaultValue | Fields in tables, fields in view definitions: see DBSETPROP( ).
DeleteTrigger | Tables: see DBGETPROP( ).
DispLogin | Connection definitions: see DBSETPROP( ). Active connections: see SQLSETPROP( ).
DispWarnings | Connection definitions: see DBSETPROP( ). Active connections: see SQLSETPROP( ).
FetchAsNeeded | View definitions: see DBSETPROP( ). Active view cursors: see CURSORGETPROP( ).
FetchMemo1 | View definitions: see DBSETPROP( ). Active view cursors: see CURSORGETPROP( ).
FetchSize1 | View definitions: see DBSETPROP( ). Active view cursors: see CURSORSETPROP( ).
IdleTimeout | Connection definitions: see DBSETPROP( ). Active connections: see SQLSETPROP( ).
InsertTrigger | Tables: see DBGETPROP( ).
KeyField | Fields in view definitions: see DBSETPROP( ).
KeyFieldList2 | Active view cursors: see CURSORSETPROP( ).
MaxRecords1 | View definitions: see DBSETPROP( ). Active view cursors: see CURSORSETPROP( ).
ODBCHdbc | Active connections: see SQLGETPROP( ).
ODBCHstmt | Active connections: see SQLGETPROP( ).
Offline | View definitions: see DBGETPROP( ).
PacketSize | Connection definitions: see DBSETPROP( ). Active connections: see SQLSETPROP( ).
ParameterList | View definitions: see DBSETPROP( ). Active view cursors: see CURSORSETPROP( ).
Password | Connection definitions: see DBSETPROP( ). Active connections: see SQLGETPROP( ).
Path | Tables: see DBGETPROP( ).
Prepared | View definitions: see DBSETPROP( ).
PrimaryKey | Tables: see DBGETPROP( ).
QueryTimeout | Connection definitions: see DBSETPROP( ). Active connections: see SQLSETPROP( ).
RuleExpression | Tables, fields in tables, view definitions, fields in view definitions: see DBSETPROP( ).
RuleText | Tables, fields in tables, view definitions, fields in view definitions: see DBSETPROP( ).
SendUpdates2 | View definitions: see DBSETPROP( ). Active view cursors: see CURSORSETPROP( ).
ShareConnection | View definitions: see DBSETPROP( ). Active view cursors: see CURSORGETPROP( ).
SourceName | Active view cursors: see CURSORGETPROP( ).
SourceType | View definitions: see DBGETPROP( ). Active view cursors: see CURSORGETPROP( ).
SQL | View definitions: see DBGETPROP( ). Active view cursors: see CURSORGETPROP( ).
Tables2 | View definitions: see DBSETPROP( ). Active view cursors: see CURSORSETPROP( ).
Transactions | Connection definitions: see DBSETPROP( ). Active connections: see SQLSETPROP( ).
Updatable | Fields in view definitions: see DBSETPROP( ).
UpdatableFieldList2 | Active view cursors: see CURSORSETPROP( ).
UpdateName | Fields in view definitions: see DBSETPROP( ).
UpdateNameList2 | Active view cursors: see CURSORSETPROP( ).
UpdateTrigger | Tables: see DBGETPROP( ).
UpdateType | View definitions: see DBSETPROP( ). Active view cursors: see CURSORSETPROP( ).
UseMemoSize1 | View definitions: see DBSETPROP( ). Active view cursors: see CURSORGETPROP( ).
UserID | Connection definitions: see DBSETPROP( ). Active connections: see SQLGETPROP( ).
Version | Databases: see DBGETPROP( ).
WaitTime | Connection definitions: see DBSETPROP( ). Active connections: see SQLSETPROP( ).
WhereType | View definitions: see DBSETPROP( ). Active view cursors: see CURSORSETPROP( ).

1. Property primarily useful for remote views; setting has no effect on performance of local views. You can set this property on local views if you want to pre-set the property on the local view and then upsize later to create a remote view.

2. Property must be set for updates to be sent to remote data source.

Using Transactions with Remote Data

You can wrap transactions around updates, deletes, and inserts to remote data using one of two methods:

  • Automatic transaction mode

  • Manual transaction mode

The transaction mode you select determines how Visual FoxPro handles transactions on your local machine.

Nested Transactions

Visual FoxPro supports transactions nested up to five levels for local data. A single level of transaction support is built into SQL pass-through.

If your server supports multiple levels of transactions, you can use SQL pass-through to manage transaction levels explicitly. Explicit transaction management is complex, however, because it can be difficult to control the interaction between the built-in transaction and the timing of remote server transactions. For more information on explicit transaction management, see your ODBC documentation.

See Also

Other Resources

Execution of ODBC Extensions to SQL
How to: Use Automatic Transaction Mode
Using SQL Pass-Through Technology
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Sharing Connections for Remote Data

Visual FoxPro 9.0
Sharing Connections for Remote Data
See Also

Visual FoxPro makes it possible for you to share a connection handle for a remote data connection. Sharing a connection handle can be desirable when you want to manage SQL Server connections and server resources better by reducing the number of connections.

By default, Visual FoxPro creates a new connection handle each time a remote data connection is created. However, when specified, Visual FoxPro can use an existing connection and associate the new statement with it. This creates a new statement handle and Visual FoxPro handle; however, the associated connection handle is the same.

There are three types of handles associated with a remote data connection. The following table describes these handles.

Shared Connections for Remote Views

A remote view can use a shared connection handle by including the SHARE keyword in the CREATE SQL VIEW command. If a shared connection is available, Visual FoxPro uses it to create a new statement handle and Visual FoxPro connection handle. If a shared connection is unavailable, Visual FoxPro creates a new, shared connection that other views can use.

Shared Connections for SQL Pass-Through

You can create a new connection that can be shared by including the lShared parameter in the SQLSTRINGCONNECT( ) command. The SQLSTRINGCONNECT( ) command always creates a new connection, statement, and Visual FoxPro connection handle.

Including the lShared parameter in the SQLCONNECT( ) command also creates a new connection that can be shared; however, including the nStatementHandle parameter causes SQLCONNECT( ) to use a currently shared connection and creates only a new statement handle and Visual FoxPro connection handle.

See Also

Tasks

How to: Share Connections for Multiple Remote Views

Reference

SQLCONNECT( ) Function
SQLSTRINGCONNECT( ) Function

Concepts

Managing Connections with SQL Pass-Through

Other Resources

Using SQL Pass-Through Technology


How to: Use Automatic Transaction Mode

Visual FoxPro 9.0
How to: Use Automatic Transaction Mode
See Also

By default, Visual FoxPro automatically wraps every data-writing operation sent to the remote server in a transaction. This default automatic transaction handling is provided when the Transactions property is set to 1, or DB_TRANSAUTO.

To use automatic transaction mode

  • Use the DBSETPROP( ) Function to set the Transactions property on the connection to 1 or DB_TRANSAUTO.

    -or-

  • Use the SQLSETPROP( ) Function to set the Transactions property on the active connection to 1 or DB_TRANSAUTO.

Transaction processing for the remote table is automatically handled.

Note:
The Visual FoxPro commands BEGIN TRANSACTION and END TRANSACTION create a transaction for the local Visual FoxPro cursor only. They don't extend the transaction to the remote server.

See Also

Other Resources

Managing Connections with SQL Pass-Through
How to: Control Transactions Manually
Using SQL Pass-Through Technology
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


How to: Control Transactions Manually

Visual FoxPro 9.0
How to: Control Transactions Manually
See Also

If you want to control transactions manually, you can set the Transactions property to 2, or DB_TRANSMANUAL. With manual transaction handling, Visual FoxPro automatically begins a transaction for you when you issue the first data-writing SQL statement, but you must submit the Visual FoxPro SQLCOMMIT( ) or SQLROLLBACK( ) functions to end the transaction. For the CursorAdapter object, you can set the UseTransactions property to false (.F.) and the CursorAdapter does not use transactions to send Insert, Update, or Delete commands.

To use manual transaction mode

  1. Use the DBSETPROP( ) Function to set the Transactions property on the connection to 2 or DB_TRANSMANUAL.

    -or-

  2. Use the SQLSETPROP( ) Function to set the Transactions property on the active connection to 2 or DB_TRANSMANUAL.

Transaction processing is handled manually through SQLCOMMIT( ) Function 3E65E927-58A3-4E71-9E88-3F07DE1DEE0Eand SQLROLLBACK( ) Function.

After committing or rolling back the prior transaction, Visual FoxPro automatically begins a new transaction when you issue the next data-writing SQL statement. For more information about transactions, see Programming for Shared Access.

Visual FoxPro supports transactions nested up to five levels for local data. A single level of transaction support is built into SQL pass-through.

If your server supports multiple levels of transactions, you can use SQL pass-through to manage transaction levels explicitly. Explicit transaction management is complex, however, because it can be difficult to control the interaction between the built-in transaction and the timing of remote server transactions. For more information on explicit transaction management, see your ODBC documentation.

See Also

Reference

UseTransactions Property

Other Resources

How to: Use Automatic Transaction Mode
Working with Remote Data Using SQL Pass-Through
Using SQL Pass-Through Technology
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Selecting the Right Methods

Visual FoxPro 9.0
Selecting the Right Methods
See Also

You can use remote views, SQL pass-through, or both to create your client/server application. You can combine both methods for powerful results: use views for the majority of your data management requirements and use SQL pass-through to enhance the power of your application.

Using Views

You can use views as the core method for developing a robust client/server application. Remote views are a powerful technology; they're designed to allow you to select just the data you need from a remote server into a local Visual FoxPro cursor, which you can then use to view and update remote data. A view is basically a result set from a SQL SELECT statement.

Views are persistent: the view definition is stored in a database. View definitions have properties that you can set and then customize further for the active view cursor. Views are the best tool for data definition of an updatable result set.

You can use local views to build a local prototype, and then use an Upsizing Wizard to transform local views into remote views. For more information, see Upsizing Visual FoxPro Databases.

If your application's users want to use data for mobile work, you can employ offline views. Offline views make data portable, allowing laptop or other portable computer users to work with a stored copy of source data that they can update while they're on the road. When the user reconnects to the server, your application can easily merge offline changes into the source tables.

You might also want to use offline view technology to allow local users to work with data "offline," merging their updates at a later time. For more information, see Manipulating Offline Data.

Using SQL Pass-Through

SQL pass-through technology provides you with direct access to a remote server with the Visual FoxPro SQL pass-through functions. These functions permit additional server access and control beyond the capability of views. For example, you can perform data definition on the remote server, set server properties, and access stored procedures on a remote server.

SQL pass-through is the best tool for creating read-only result sets and for using any other native SQL syntax. In contrast to a view, which is a result set from a SQL SELECT statement, SQL pass-through enables you to send anything you want to the server using the SQLEXEC( ) function. The following table lists the Visual FoxPro SQL pass-through functions.

SQL pass-through functions

SQLCANCEL( ) | SQLCOLUMNS( ) | SQLCOMMIT( )
SQLCONNECT( ) | SQLDISCONNECT( ) | SQLEXEC( )
SQLGETPROP( ) | SQLMORERESULTS( ) | SQLPREPARE( )
SQLROLLBACK( ) | SQLSETPROP( ) | SQLSTRINGCONNECT( )
SQLTABLES( ) |  |

You can create cursors yourself using SQL pass-through technology. Though SQL pass-through provides more direct server access, it provides less persistent access than views. In contrast to views, whose definitions are stored persistently in a database, cursors created using SQL pass-through exist only for the current session. For more information, see Enhancing Applications Using SQL Pass-Through Technology.

Combining Views and SQL Pass-Through

The most powerful paradigm for building a Visual FoxPro client/server application combines view and SQL pass-through technologies. Because views are easy to build and provide automatic buffering and update capabilities, use views for the majority of your data management tasks. Then use SQL pass-through to accomplish specific tasks on the remote server, such as data definition and the creation and execution of stored procedures on a remote server.

See Also

Other Resources

Using SQL Pass-Through Technology
Data Location on the Optimal Platform
Rapid Application Development
Planning Client/Server Applications
Application Creation with Accuracy and Data Integrity
Performance Enhancement through Set-Based Data Access
Client/Server Design for High Performance
Optimizing Client/Server Performance


Working with Remote Data Using SQL Pass-Through

Visual FoxPro 9.0
Working with Remote Data Using SQL Pass-Through

After you retrieve a result set using SQL pass-through, you can view and control the properties of your result set cursor using the Visual FoxPro functions CURSORGETPROP( ) and CURSORSETPROP( ). These are the same functions you use to set properties on an active view cursor.

Note:
Cursors are not objects and thus are not tied to the object model. However, you can view their properties, or attributes, with CURSORGETPROP() and set their properties with CURSORSETPROP().

In This Section

Setting Cursor Properties for Remote Data

Describes the purpose of the remote data cursor properties and how to set them using SQL pass-through and the Remote Data tab of the Options dialog box.
How to: Update Remote Data with SQL Pass-Through

Describes how to update remote data including specific details about the updates, such as controlling the timing of remote updates, using optimistic row and table buffering, detecting changes by other users, forcing updates, and how to troubleshoot update error messages.
Selecting an Efficient SQL Pass-Through Processing Mode

Compares and contrasts the two types of processing modes for retrieving and updating remote data using SQL pass-through: synchronous and asynchronous.
How to: Use SQL Pass-Through Asynchronously

Explains how to set your client/server application to use asynchronous processing for SQL pass-through.
Processing Multiple Result Sets

Describes how to process multiple result sets using synchronous or asynchronous batch mode and non-batch mode processing.
Data Type Conversion Control

Explains how data types are mapped between OBDC or ADO and Visual FoxPro so you can predict how a remote server's data will be treated by your Visual FoxPro application.

Related Sections

Enhancing Applications Using SQL Pass-Through Technology

Explains how your application can make use of SQL pass-through technology to access remote data, run stored server procedures, execute commands using native server syntax, and create objects on the server.
How to: Set Up an ODBC Data Source

Describes how to install an OBDC driver so you can use an OBDC data source with remote views and SQL pass-through.
Handling SQL Pass-Through Errors

Explains how to retrieve information about the error to examine the error and to determine its cause.


Setting Cursor Properties for Remote Data

Visual FoxPro 9.0
Setting Cursor Properties for Remote Data
See Also

The following table lists the Visual FoxPro cursor properties that support working with views and connected result sets, grouped according to task categories.

Visual FoxPro Cursor Properties

Task | Property | Purpose
View cursor definition. | SQL | Contains the SQL statement from which the cursor was created.
Control interactions between Visual FoxPro and ODBC. | ConnectHandle | Handle to remote connection that's used by cursor.
 | ConnectName | Name of connection used by the cursor.
 | Prepare | Specifies whether the query for the view is prepared before it's executed.
 | FetchAsNeeded | Specifies whether rows are fetched automatically during the idle loop or only on an as-needed basis.
 | CompareMemo | Specifies whether Memo and General fields participate in the WHERE clause of an UPDATE statement, regardless of the setting of the UpdateType property
 | FetchMemo | Specifies whether Memo and General fields are fetched automatically with result sets, or fetched later, on demand, as the Memo or General field is opened.
 | UseMemoSize | Specifies the minimum column size (1 to 255) in result sets for which columns are returned in Memo fields.
 | FetchSize | Specifies the number of rows that are fetched at one time from the remote result set.
 | MaxRecords | Specifies the maximum number of rows fetched when result sets are returned.
Update data | SendUpdates* | Specifies whether updates to the cursor are sent to the tables on which the cursor is based.
 | BatchUpdateCount | Specifies the number of update statements sent to the back end for buffered tables.
 | Tables* | Comma-delimited list of table names on the data source; used to define scope for UpdateNameList and UpdatableFieldsList properties.
 | KeyFieldList* | Comma-delimited list of Visual FoxPro fields that represent the primary key of the result set used for updates.
 | UpdateNameList* | Comma-delimited list pairing Visual FoxPro fields in the cursor with the table and column names of fields to which you want to send updates.
 | UpdatableFieldList* | Comma-delimited list of the Visual FoxPro fields for which updates are sent.
 | Buffering | Specifies the type of buffering being performed on the cursor.
 | UpdateType | Specifies whether updates should occur using UPDATE, or DELETE and then INSERT commands.
 | WhereType | Specifies what should be included in the WHERE clause for updates to table data.

* Properties that must be set before you can update data.

You use these properties to control the way your application interacts with remote data, such as establishing the number of rows retrieved during progressive fetching, and controlling buffering and updates to remote data.

Using the Remote Data Tab in the Options Dialog Box

Some cursor properties inherit their initial values from the environment; other properties only become available at the cursor level. Some properties are available to cursors representing remote views and ODBC or SQL pass-through connected tables.

You can control some cursor and connection property settings through the Remote Data tab of the Options dialog box. When you display the Remote Data tab, the values in the dialog box represent the cursor settings for the current session and the Visual FoxPro global default settings for the connection. When you change values in the Remote Data tab and choose OK, the new values are saved to the cursor's current session and the connection's global default settings. If you choose Set As Default, the values are written to the configurable system settings on your machine. The following diagram illustrates these interactions.

Setting Properties with SQL Pass-Through

When you create a cursor, the cursor inherits property settings, such as UpdateType and UseMemoSize, from the environment cursor, or cursor 0 of the current session. You can change these default property settings by using the CURSORSETPROP( ) function with 0 as the cursor number.

After you create a view cursor with SQL pass-through, you can change the active cursor's property settings by using the CURSORSETPROP( ) function for the view cursor. Changes you make with CURSORSETPROP( ) are temporary: the temporary settings for the active view disappear when you close the view, and the temporary settings for cursor 0 go away when you close the Visual FoxPro session.

Connections inherit properties in a similar fashion. Default properties for connection 0 are inherited when you create and store a named connection in a database. You can change these default property settings for connection 0 with the SQLSETPROP( ) function. After the connection has been created and is stored in a database, you can change connection properties with the DBSETPROP( ) function. When you use a connection, the property settings stored for the connection in the database are inherited by the active connection. You can change these properties on the active connection using the SQLSETPROP( ) function for the connection handle.

Both SQL pass-through view cursors and named connections can use a named ODBC data source. If you use an ODBC data source in a SQL pass-through view cursor, the connection inherits properties from the session defaults.

The following diagram illustrates property inheritance for cursors and connections created with SQL pass-through. The gray lines represent the flow of property inheritance; the black lines represent Visual FoxPro commands.

See Also

Other Resources

Working with Remote Data Using SQL Pass-Through
How to: Control Transactions Manually
How to: Update Remote Data with SQL Pass-Through
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Updating Remote Data with SQL Pass-Through

Visual FoxPro 9.0
Updating Remote Data with SQL Pass-Through
See Also

When you use SQL pass-through functions to update data on a remote server, you control whether data is updated, as well as specific details about the updates, by setting properties on the result set cursor. Visual FoxPro checks these properties when an update is requested before committing the update.

Tip:
SQL pass-through view cursors aren't updatable until you specify update properties for the view cursor. If you want to store update property settings persistently, create a view definition. Visual FoxPro supplies default values that prepare the view to be updatable when you create a view using the View Designer or the language. You can use the CURSORSETPROP() function to add additional information to supplement or customize the default values.

To update remote data you must set the following properties using the CURSORSETPROP( ) function:

  • Tables

  • KeyFieldList

  • UpdateNameList

  • UpdatableFieldList

  • SendUpdates

You can specify additional properties such as Buffering, UpdateType, and WhereType to best fit the requirements of your application.

The update properties you set on the active view cursor have slightly different names than their DBSETPROP( ) counterparts. The following table lists the names used for both view definitions and active cursors.

View and Cursor Update Properties

Purpose | View definition properties1 | Active cursor properties2
Make remote table updatable. | Tables | Tables
Specify the remote names for view fields. | UpdateName (field-level property) | UpdateNameList
Specify view fields you want to use as keys. | KeyField (field-level property) | KeyFieldList
Specify the view fields that are updatable. | Updatable (field-level property) | UpdatableFieldList
Turn updates on. | SendUpdates | SendUpdates

1 Set with DBSETPROP( ). 2 Set with CURSORSETPROP( ).

For more information on setting update properties, see How to: Update Data in a View, or see DBSETPROP( ) or CURSORSETPROP( ).

Controlling the Timing of Remote Updates

You control how updates to remote data are buffered by setting the cursor's Buffering property. Of the five possible buffering property settings, two are valid for remote views:

  • 3, or DB_BUFOPTROW, the default, which optimistically locks the row.

  • 5, or DB_BUFOPTTABLE, which optimistically locks the table.

Visual FoxPro supports only optimistic locking on remote cursors.

Note:
The pessimistic row and table buffering settings, 2 and 4, don't apply to remote views, because Visual FoxPro doesn't take locks on the server data. Buffering property setting 1 doesn't apply to remote views because views are always buffered.

Using Optimistic Row Buffering

The default Buffering setting, DB_BUFOPTROW, optimistically locks remote data on a row-by-row basis. For example, if you want changes to the titles table to be committed on a row-by-row basis, such as when using the SKIP command, you could set the Buffering property to 3:

Copy Code
CURSORSETPROP('buffering', 3, 'titles')

When Buffering is set to row buffering, you have two methods of sending updates to the remote server. You can:

  • Call the TABLEUPDATE( ) function.

  • Use a command that moves the record pointer off the row, such as SKIP or GO BOTTOM.

The TABLEUPDATE( ) function updates the server without moving the record pointer. Commands that move the record pointer send updates to the remote server as a by-product of moving off the updated record.

If you use row buffering and want to be able to revert changes to rows, you must wrap the changes in manual transactions using SQL pass-through transaction functions.

Using Optimistic Table Buffering

If you want changes to a table to be committed a batch at a time, such as when the user clicks a Save or OK button in a form, you can set the Buffering property to 5, or DB_BUFOPTTABLE. You must call the TABLEUPDATE( ) function to send the update to the server.

In the following example, you set the Buffering property in your form's initialization code and then commit the changes in the save code.

Code | Comments
CURSORSETPROP('buffering', 5, 'sqltitles') | Set in Init code
* Update batched changes; * ignore changes made by others |
TABLEUPDATE(.T., .T., 'titles') | Set in Save code

To restore the original values to a table and prevent updates from being sent to the remote server, you call TABLEREVERT( ). You can control whether a single row or all rows are reverted by combining the setting of the cursor's Buffering property with the TABLEREVERT( ) command. The following example reverts only the current row. You might want to invoke this code when the user clicks on a Cancel button in a form:

Copy Code
= TABLEREVERT(.F., 'titles')      && Revert current row

If you wanted to revert all rows, such as when the user presses ESC to leave a form, you could use the same example, this time changing the settings of the Buffering property and TABLEREVERT( ) command to revert all rows, with the entire table buffered:

Copy Code
= TABLEREVERT(.T., 'titles')      && Revert all rows

For more information about buffering, see Programming for Shared Access.

Detecting Changes By Other Users

In multiuser applications, conflicts with other users' updates are detected by the SQL Update query, which is generated when a write is attempted locally. The level of detection depends on the setting of the WhereType property. For more information on setting the WhereType property, see Managing Updates by Using Views.

Forcing Updates

You can use the TABLEUPDATE( ) function to control whether changes made to a table or cursor by another user on a network are overwritten when you send your updates. If you set the Force parameter of TABLEUPDATE( ) to true (.T.), and the CURSORSETPROP( ) UpdateType property is set to the default value, 1, old data is updated with the new data you send, as long as the value in the record's key field on the remote table hasn't been changed. If the value in the remote table's key field has changed, or if the UpdateType property is set to 2, Visual FoxPro sends a DELETE and then an INSERT statement to the remote table.

Troubleshooting Update Error Messages

The following table lists the Visual FoxPro and ODBC error messages that apply specifically to remote updates. The Action column contains the action you take to resolve the error condition.

Error Message | Meaning | Action
No update table(s) specified. Use the Tables cursor property. | The cursor property Tables contains no remote table names. At least one table is required to enable updates to the remote server. | Use the Tables property to specify at least one table for the cursor.
No key column(s) specified for the update table table_name. Use the KeyFieldList cursor property. | The primary key for the remote table specified in the error message isn't included in the KeyFieldList property for the cursor; a primary key is required for each table being updated. | Use the KeyFieldList property to specify the primary key for the remote table.
No valid update table specified for column column_name. Use the UpdateNameList and Tables cursor properties. | The UpdateName property for column column_name has an invalid table qualifier. | Set the table qualifier with the UpdateNameList property, or add the table qualifier to the Tables property setting, or both.
The KeyField List cursor property doesn't define a unique key. | More than one remote record has the same key. | Use the KeyField List property to define a unique key for the remote table.
From ODBC: ODBC invalid object. | ODBC cannot find the remote table or column because it doesn't exist as named. Visual FoxPro field names are validated by Visual FoxPro; remote table and column names are validated only by the remote server. | Check the object name.

For more information on error handling, see Handling SQL Pass-Through Errors.

See Also

Other Resources

Working with Remote Data Using SQL Pass-Through
Selecting an Efficient SQL Pass-Through Processing Mode
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Selecting an Efficient SQL Pass-Through Processing Mode

Visual FoxPro 9.0
Selecting an Efficient SQL Pass-Through Processing Mode
See Also

Visual FoxPro provides two processing modes for retrieving and updating remote data using SQL pass-through: synchronous and asynchronous. When you use SQL pass-through functions you can choose the method you prefer. You don't need to choose a method for remote views; Visual FoxPro automatically employs progressive fetching and manages the processing mode for you for remote views.

Benefits of Synchronous Mode

By default, Visual FoxPro SQL functions are processed synchronously: Visual FoxPro doesn't return control to an application until a function call is completed. Synchronous processing is useful when you're working with Visual FoxPro interactively.

Benefits of Asynchronous Mode

Asynchronous processing provides greater flexibility than synchronous processing. For example, when your application is processing a function asynchronously, your application can build a progress indicator to display the progress of the executing statement, display movement of the mouse pointer, create loops, and set timers to allow interruption of processing that is taking too long.

See Also

Other Resources

How to: Update Remote Data with SQL Pass-Through
How to: Use SQL Pass-Through Asynchronously
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


How to: Use SQL Pass-Through Asynchronously

Visual FoxPro 9.0
How to: Use SQL Pass-Through Asynchronously
See Also

Your application can request asynchronous processing for the four functions that submit requests to a data source and retrieve data: SQLEXEC( ), SQLMORERESULTS( ), SQLTABLES( ), and SQLCOLUMNS( ). You enable asynchronous processing by setting the Asynchronous property of the connection with the SQLSETPROP( ) function. When asynchronous communication is established for the connection, all four of these functions operate asynchronously.

To check the setting of the Asynchronous property

  • Use the SQLGETPROP( ) Function to view the Asynchronous property setting. In the following example, nConnectionHandle represents the handle number for your active connection:

    Copy Code
    ? SQLGETPROP(nConnectionHandle,'Asynchronous')

To enable asynchronous processing

  • Use the SQLSETPROP( ) Function to specify the Asynchronous property:

    Copy Code
    ? SQLSETPROP(nConnectionHandle,'Asynchronous', .T.)

In Asynchronous mode, you must call each function repeatedly until it returns a value other than 0 (still executing). While the function is still executing, you can cancel processing of the function by pressing the ESC key if the SET ESCAPE property is set to true (.T.).

Until the function has finished processing, the application can use a connection handle only with the SQLCANCEL( ) Function or with the asynchronous functions — SQLEXEC( ), SQLMORERESULTS( ), SQLTABLES( ), or SQLCOLUMNS( ) — originally associated with the handle. You can't call any of the other three asynchronous functions or SQLDISCONNECT( ) with the same connection handle until the function has finished.

See Also

Other Resources

Selecting an Efficient SQL Pass-Through Processing Mode
Processing Multiple Result Sets
Working with Remote Data Using SQL Pass-Through
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Processing Multiple Result Sets

Visual FoxPro 9.0
Processing Multiple Result Sets
See Also

Your application retrieves multiple result sets when you use the SQLEXEC( ) function to issue more than one SQL SELECT statement, or to execute a stored procedure that issues multiple SELECT statements. The results of each SQL SELECT statement are returned in a separate Visual FoxPro cursor.

The default name SQLRESULT is used for the first cursor; subsequent cursors are assigned unique names by indexing the default name. For example, the default names for the cursors returned by a SQLEXEC( ) statement requesting three result sets are Sqlresult, Sqlresult1, and Sqlresult2.

In batch mode, if a function returns multiple result sets, the respective cursor names in Visual FoxPro have unique suffixes and can have up to 255 characters. For example, the following example sets the BatchMode property to batch mode, and then issues a SQLEXEC( ) statement containing four SQL SELECT statements that build four result sets:

Copy Code
? SQLSETPROP(nConnectionHandle,'BatchMode', .T.)
? SQLEXEC(nConnectionHandle,'select * from authors ;
                     select * from titles ;
                     select * from roysched ;
                     select * from titleauthor','ITEM')

When the function above has completed processing, Visual FoxPro returns the four result sets as the Visual FoxPro cursors Item, Item1, Item2, and Item3.

You can change the default name by using the cCursorname parameter with the SQLEXEC( ) or SQLMORERESULTS( ) functions. If the name you specify for a result set has already been used, the new result set overwrites the existing cursor.

When your application retrieves multiple result sets, you can choose between asynchronous or synchronous processing and batch or non-batch modes.

Using Batch Mode Processing

The BatchMode property, set with SQLSETPROP( ), controls how SQLEXEC( ) returns multiple result sets. The default value is .T., for batch mode. Batch mode processing means that Visual FoxPro doesn't return any results from a still-executing SQLEXEC( ) call until all of the individual result sets have been retrieved.

Using Non-Batch Mode Processing

If you use SQLSETPROP( ) to set the BatchMode property to .F., for non-batch mode, each result set is returned individually. The first result set is returned by the SQLEXEC( ) function call. Your application must then call SQLMORERESULTS( ) repeatedly until a value of 2 is returned, indicating that no more results are available.

In non-batch mode, the cursor name can be changed in each subsequent SQLMORERESULTS( ) call. In the previous example, if the first cursor name in a SQLEXEC( ) sequence is Item, and the second SQLMORERESULTS( ) call changes the cCursorName parameter to Otheritem, the resulting cursors will be named Item, Item1, Otheritem, and Otheritem1.

The next section describes batch mode and non-batch mode processing with synchronous and asynchronous detail added. The following diagram provides a representation of the four possible processing combinations. The numbers 0, 1, and 2 represent the values returned when you call each function.

The behavior of each type of processing is explained below: the labels A, B, C, and D reference the preceding diagram. Each explanation assumes the execution of a statement that will return three result sets, represented in the diagram by three horizontal bands.

Using Synchronous Processing

In synchronous mode, control doesn't return to your application until the execution of a function is complete.

A: Synchronous Batch Mode

When you execute a SQL pass-through statement synchronously in batch mode, control isn't returned until all result sets have been retrieved. You specify the name of the first cursor by using the cCursorname parameter in the original function. If the cursor you specify already exists, the result set overwrites the existing cursor. When you request multiple result sets in synchronous batch mode, Visual FoxPro creates the names of additional cursors by uniquely indexing the name of the first cursor.

B: Synchronous Non-Batch Mode

When you execute a SQL pass-through statement synchronously in non-batch mode, the first statement retrieves the first result set and returns a 1. You must then call the SQLMORERESULTS( ) function repeatedly, and optionally specify a new name for the cursor. If you don't specify a new name for the cursor, multiple names for multiple result sets are created by uniquely indexing the base name. When SQLMORERESULTS( ) returns a value of 2, there are no more results available.

Using Asynchronous Processing

In asynchronous mode, your application must continue calling the same SQL pass-through function until it returns a value other than 0 (still executing). The default result set name, Sqlresult, can be explicitly changed with the cCursorname parameter the first time you call the function. If the name you specify for a result set has already been used, the new result set overwrites the information in the existing cursor.

C: Asynchronous Batch Mode

When you execute asynchronously in batch mode, each repeat call of the original function returns a 0 (still executing) until all of the multiple result sets have been returned to the specified cursors. When all results have been retrieved, the return value is either the number of cursors, or a negative number indicating an error.

D: Asynchronous Non-Batch Mode

When processing asynchronously in non-batch mode, SQLEXEC( ) returns a value of 1 when it completes the retrieval of each result set. Your application must then call SQLMORERESULTS( ) repeatedly until a value of 2 is returned, indicating that no more results are available.

Tip:
Remote result sets are retrieved in two stages: first, the result set is prepared on the server; then the result set is fetched into a local Visual FoxPro cursor. In asynchronous mode, you can call the USED( ) function to see whether Visual FoxPro has started fetching the cursor you requested.

See Also

Other Resources

How to: Use SQL Pass-Through Asynchronously
Data Type Conversion Control
Working with Remote Data Using SQL Pass-Through
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Data Type Conversion Control

Visual FoxPro 9.0
Data Type Conversion Control
See Also

When you move data between a remote server and Visual FoxPro, you might encounter differences in data types available on your server or in Visual FoxPro. There is rarely a one-to-one correlation between data types available on a remote data source and those available in Visual FoxPro. To handle these differences, Visual FoxPro uses ODBC or ADO data types to map remote data types to local Visual FoxPro data types. By understanding how data types are mapped between ODBC or ADO and Visual FoxPro, you can predict how the server's remote data is handled in your Visual FoxPro application.

You can also adjust the data types used on the server or in your application. You can override the default Visual FoxPro field data type by creating a view for the remote data set and then setting the DataType view field property in the database. The DataType property is a character property indicating the desired data type for each field of a remote view. For more information on the DataType property, see DBSETPROP( ).

Data Type Conversion between Remote Views and Visual FoxPro Cursors

When you retrieve data from a remote ODBC or ADO data source, Visual FoxPro converts the data type of each ODBC or ADO field into an equivalent Visual FoxPro data type in the resulting cursor.

Remote Data Types to Visual FoxPro Data Types

The following table lists the default data type mapping between remote field data types and Visual FoxPro data types for cursors.

ODBC/ADO data type Default Visual FoxPro cursor data types

SQL_BINARY / adBinary SQL_VARBINARY / adVarbinary

Memo/Blob1 or Varbinary

Note:
Default type is affected by the MapBinary property. For more information, see CURSORSETPROP( ) Function.

SQL_LONGVARBINARY

General/Blob

Note:
Default type is affected by the MapBinary property. For more information, see CURSORSETPROP( ) Function.

adLongVarbinary

Memo or Character

SQL_CHAR / adChar SQL_WCHAR / adWChar

Memo1 or Character

SQL_LONGVARCHAR / adLongVarChar SQL_WLONGVARCHAR / adLongVarWChar

Memo

SQL_VARCHAR / adVarChar SQL_WVARCHAR / adVarWChar

Memo1 or Character/Varchar

Note:
Default type is affected by the MapVarchar property. For more information, see CURSORSETPROP( ) Function.

SQL_DECIMAL / adNumeric SQL_NUMERIC / adNumeric

Currency2

SQL_BIT / adBoolean

Logical

SQL_TINYINT / adVarbinary SQL_SMALLINT / adSmallInt SQL_INTEGER / adInteger

Integer

SQL_BIGINT / adBigInt

Character

SQL_REAL / adSingle SQL_FLOAT / adDouble SQL_DOUBLE / adSingle

Double

Note:
For Double, the number of decimal places is the value of SET DECIMAL in Visual FoxPro.

SQL_DATE / adDBTimeStamp

Date

SQL_TIME / adDBTTimeStamp

DateTime4

SQL_TIMESTAMP / adBinary

DateTime3

1 If the ODBC/ADO field width is less than the value of the cursor property UseMemoSize, it becomes a Character/Varchar/Varbinary field in the Visual FoxPro cursor; otherwise, it becomes a Memo/Blob field.

2 If the server field is a money data type, it becomes a Currency data type in Visual FoxPro.

3 If the value in the SQL_TIMESTAMP field contains fractions of seconds, the fractions are truncated when the value is converted to a Visual FoxPro DateTime data type.

4 The day defaults to 1/1/1900.

The following table lists the data types available when using remote views or CursorAdapter objects along with ODBC or ADO data sources and the equivalent Visual FoxPro data types. For more information about specifying cursor schema, see the CursorAdapter CursorFill Method.

ODBC/ADO data type Visual FoxPro cursor acceptable data types

SQL_BINARY / adBinary SQL_VARBINARY / adVarbinary SQL_LONGVARBINARY / adLongVarbinary SQL_CHAR / adChar SQL_VARCHAR / adVarChar SQL_LONGVARCHAR / adLongVarChar

Blob, Varbinary, Character, Varchar, General, Memo5

SQL_WCHAR / adWChar SQL_WVARCHAR / adVarWChar SQL_WLONGVARCHAR / adLongVarWChar

Character, Varchar, Memo

SQL_BIT / adBoolean

Character, Varchar, Logical

SQL_REAL / adSingle SQL_FLOAT / adDouble SQL_DOUBLE / adSingle SQL_DECIMAL / adNumeric SQL_NUMERIC / adNumeric SQL_TINYINT / adVarbinary SQL_SMALLINT / adSmallInt SQL_INTEGER / adInteger SQL_BIGINT / adBigInt

Character, Varchar, Integer, Numeric, Float, Double, or Currency6

Note:
For Double, the number of decimal places is the value of SET DECIMAL in Visual FoxPro.

SQL_DATE / adDBTimeStamp SQL_TIMESTAMP / adBinary

Character, Varchar, Date, DateTime7

SQL_TIME / adDBTTimeStamp

Character, Varchar, DateTime8

5 If the ODBC field width is less than the value of the cursor property UseMemoSize, it becomes a Character field in the Visual FoxPro cursor; otherwise, it becomes a Memo field.

6 If the server field is a money data type, it becomes a Currency data type in Visual FoxPro.

7 If the value in the SQL_TIMESTAMP field contains fractions of seconds, the fractions are truncated when the value is converted to a Visual FoxPro DateTime data type.

8 The day defaults to 1/1/1900.

Note:
Null values in ODBC data source fields become null values in the Visual FoxPro cursor, regardless of the SET NULL setting in Visual FoxPro at the time your application retrieves remote data.

In Visual FoxPro 9.0, certain ODBC and ADO data types can be mapped to a logical data type in remote views and the CursorAdapter object.

If the backend value is zero, the data type is mapped to a logical False (.F.); all other values are mapped to True (.T.). When updates are performed, the mapping from a logical data type to an integer is backend specific. For ODBC, False (.F.) is usually mapped to 0 and True (.T.) is usually mapped to 1. For ADO, False (.F.) is usually mapped to zero and .T. is usually mapped to 1 or -1, depending on the command being executed. The CursorAdapter ConversionFunc Property can be used to enforce the mapping.

For remote views and the CursorAdapter object, the ODBC SQL_DECIMAL and SQL_NUMERIC data types can only be mapped to a logical value if the Scale is set to zero.

For the CursorAdapter object, the ADO adDecimal and adNumeric data types can only be mapped to a logical value if the Scale is set to zero.

The following table lists the ODBC and ADO data types that can be mapped to a logical data type.

ODBC data type | ADO data type
SQL_TINYINT SQL_SMALLINT SQL_INTEGER SQL_BIGINT SQL_DECIMAL SQL_NUMERIC | adSingle adTinyInt adSmallInt adInteger adBigInt adUnsignedTinyInt adUnsignedSmallInt adDecimal adNumeric

The following table lists Visual FoxPro data types available when using remote views with CursorAdapter objects and native Visual FoxPro data and their equivalent Visual FoxPro data types.

Visual FoxPro native data type | Visual FoxPro cursor acceptable data type
Character, Memo, General | Character, Varchar, Memo, General
Numeric, Float, Currency, Integer, Double | Numeric, Float, Currency, Integer, Double, Character, Varchar
Logical | Logical, Character, Varchar
Date, DateTime | Character, Varchar, Date, DateTime

Visual FoxPro Parameter Values to Remote View Data Types

If Visual FoxPro data exists in a cursor that originated from remote data, the data reverts to its original ODBC or ADO data type when sending data to the remote server. If you send data that originated in Visual FoxPro to the remote server using SQL pass-through, the table describes the conversions that apply.

Visual FoxPro data type | ODBC data type
Character, Varchar, Memo | SQL_CHAR or SQL_LONGVARCHAR9
Blob, Varbinary | SQL_BINARY or SQL_LONGVARBINARY
Currency | SQL_DECIMAL
Date | SQL_DATE or SQL_TIMESTAMP10
DateTime | SQL_TIMESTAMP
Double | SQL_DOUBLE
Integer | SQL_INTEGER
General | SQL_LONGVARBINARY
Logical | SQL_BIT
Numeric | SQL_DOUBLE

9 If the Visual FoxPro variable that maps to a parameter creates an expression whose width is less than 255, it becomes a SQL_CHAR type in the ODBC data source; otherwise, it becomes a SQL_LONGVARCHAR type.

10 Visual FoxPro Date data is converted to SQL_DATE for all ODBC data sources except SQL Server, where it becomes SQL_TIMESTAMP.

Visual FoxPro Parameter Values to Remote Data Type Mapping

You can map a Visual FoxPro parameter value to a particular remote data type by formatting the parameter as a character expression that uses the syntax for the desired remote data type. For example, if your server provides a DateTime data type, you can create your Visual FoxPro parameter as a character expression in the format used by your server to represent DateTime data. When your server receives the parameter value, it attempts to map the formatted data to the DateTime data type.

Note:
When you send a parameter to the remote server, be sure the data type in the WHERE clause matches the data type that's used for the parameter expression.

See Also

Other Resources

Processing Multiple Result Sets
Handling SQL Pass-Through Errors
Working with Remote Data Using SQL Pass-Through
Enhancing Applications Using SQL Pass-Through Technology
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Handling SQL Pass-Through Errors

Visual FoxPro 9.0
Handling SQL Pass-Through Errors
See Also

If a SQL pass-through function returns an error, Visual FoxPro stores the error message in an array. The AERROR( ) function provides information about errors that are detected in any of the component levels: Visual FoxPro, the ODBC data source, or the remote server. By examining the values returned by AERROR( ), you can determine the server error that occurred and its error message text.

Caution:
You must call AERROR() immediately to obtain error information. If you generate any other error before you call AERROR(), the error information is lost.

See Also

Other Resources

Enhancing Applications Using SQL Pass-Through Technology
Data Type Conversion Control
Processing Multiple Result Sets
Working with Remote Data Using SQL Pass-Through
Planning Client/Server Applications
Upsizing Visual FoxPro Databases
Creating Views


Web Services and Components

Visual FoxPro 9.0
Web Services and Components

To extend a basic Microsoft Visual FoxPro application, you can enable it to work for multiple users, access and distribute XML Web services, use Microsoft ActiveX controls and automation-enabled applications, and add international capabilities.

In This Section

XML Web Services in Visual FoxPro

Describes how to access and distribute XML Web services with your Visual FoxPro applications. XML Web services are classes or objects available on the Web that you can use in your applications programmatically as normal object-oriented calls.
Automation and COM Servers

Describes how to you can extend the functionality of your Visual FoxPro applications without a lot of extra coding time by using Automation and COM Servers.
Interoperability and the Internet

Explains how to use OLE drag-and-drop to develop applications that make it possible for you to move data between Microsoft Windows-based applications and within a Visual FoxPro application. Create documents for use on the Internet, or use one of two different Visual FoxPro run times to create COM components (Automation servers) as normal or multithreaded applications.

Reference

XML Data in Visual FoxPro

Describes XML Schema data types and shows how they map to Visual FoxPro data types and the reverse.

Related Sections

Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Enhancing Applications using SQL Pass-through Technology

Describes how you can use SQL pass-through (SPT) technology to create objects on the server, run stored procedures on a remote server, and execute commands using native server syntax.
Working with Data

Describes how to create effective applications with indexes, tables, and databases based on your data requirements.
Walkthrough: Creating XML Web Services with Visual FoxPro

Provides steps for how to create and publish a Visual FoxPro COM server as an XML Web service.
XML Functionality Using XMLAdapters

Discusses the extension of Visual FoxPro's XML features and compatibility with XML DiffGram and .NET Framework ADO.NET DataSet formats and supporting hierarchically formatted XML.


XML Web Services in Visual FoxPro

Visual FoxPro 9.0
XML Web Services in Visual FoxPro

XML Web services are classes or objects available on the Web that you can use in your applications programmatically as normal object-oriented calls. You can also publish Visual FoxPro COM Servers (OLEPUBLIC) as XML Web services to make information available to other clients on the Internet.

For example, you can use an XML Web service in your application that returns the weather for a given city when you call a method that returns the temperature when passed the name of the city.

Visual FoxPro support for XML Web services is handled through SOAP using an implementation of the Web Services Description Language (WSDL) compliant with WSDL version 1.1. Visual FoxPro includes Microsoft SOAP Toolkit version 3.0, which provides support for XML Web services through a set of extensions, and is also available from the Microsoft Web site. Visual FoxPro extends the functionality of the Toolkit; therefore, any future changes to the WSDL specification by the W3C propagate directly to Visual FoxPro when you upgrade to a newer version of the Toolkit.

Note:
You must have the Microsoft SOAP Toolkit installed to use XML Web services. If you plan to publish XML Web services from Visual FoxPro COM Servers, you must have Microsoft Internet Information Services (IIS) installed.

The SOAP Toolkit also provides objects that you can use to call XML Web services at low levels that interact directly with the actual SOAP messages. However, these objects are not directly supported by the Visual FoxPro extensions.

For more information on supported platforms, SOAP, WSDL, or the Toolkit, see the Toolkit online documentation or the SOAP Developer Resources Web site at http://msdn.microsoft.com/soap/.

In This Section

How to: Access XML Web Services

Describes how to locate, register, and use XML Web services in Visual FoxPro applications.
How to: Distribute XML Web Services

Describes how to specify a default location for publishing XML Web services, publish Visual FoxPro COM Servers as XML Web services, include components for deploying XML Web services, and generate XML Web service support files automatically when your COM Server is rebuilt.
Testing and Rebuilding COM Servers for XML Web Services

Describes how to generate XML Web service support files automatically when testing and rebuilding COM servers.
Deploying XML Web Services

Describes files you need to include to deploy XML Web services.

Related Sections

Web Services and Components

Discusses how you can enable a Visual FoxPro application to work for multiple users by taking advantage of ActiveX controls and automation-enabled applications and adding international capabilities.
Automation and COM Servers

Describes how to you can extend the functionality of your Visual FoxPro applications without a lot of extra coding time by using automation and COM Servers.
Walkthrough: Creating XML Web Services with Visual FoxPro

Explains how to create and publish a Visual FoxPro COM Server as an XML Web service.
Interoperability and the Internet

Explains how to use OLE drag-and-drop to develop applications so you can move data between Microsoft Windows-based applications and within a Visual FoxPro application. Create documents for use on the Internet, or use one of two different Visual FoxPro run-times to create COM components (Automation servers) as normal or multithreaded applications.


How to: Access XML Web Services

Visual FoxPro 9.0
How to: Access XML Web Services
See Also

Support for XML Web services in Visual FoxPro provided by the Microsoft SOAP Toolkit make it possible for you to access XML Web services from the Web. The extensions provided by the SOAP Toolkit 3.0 provide access to XML Web services using the Toolkit's SoapClient object. This high-level late-binding access architecture makes it possible for you to call an XML Web service method directly using only a few lines of simple object code.

The WSHandler foundation class, which is included with the _WS3Client.vcx class library in the ...\Ffc folder, is the XML Web service class used for all Visual FoxPro XML Web service calls.

Registering XML Web Services

Before using an XML Web service in your application, you must register it in Visual FoxPro. You can then select the XML Web service in the Visual FoxPro Toolbox and use operation or method calls from that XML Web service to return results. When calling the XML Web service, you can set the results to a property of a specified control, such as the TextBox Value property.

Note:
You do not have to register an XML Web service to access it; however, registering an XML Web service makes it possible for Visual FoxPro to provide IntelliSense for the XML Web service methods and their parameters.

To register an XML Web service

  1. On the Tools menu, click Task Pane.

  2. On the Task Pane Manager toolbar, click More Panes, and then click XML Web Services.

  3. In the XML Web Services pane, click Register an XML Web Service.

  4. In the Visual FoxPro XML Web Services Registration dialog box, type the Web Services Description Language (WSDL) URL for the XML Web service, and then click Register.

You also can open the Visual FoxPro XML Web Services Registration dialog box programmatically as shown in the following code:

Copy Code
DO (_wizard) WITH "project",,"Web","IntelliSense"

For more information about the settings you need to configure, see Visual FoxPro XML Web Services Registration Dialog Box.

Calling XML Web Services

After you register an XML Web service in Visual FoxPro, you can call and bind the XML Web service to a control or object on a form You can then process results from the XML Web service in your application. You can call and bind XML Web services using the XML Web Service Builder or in code. The builder provides extensive binding capabilities without your having to write code. For more information, see XML Web Service Builder.

The following steps illustrate how to call the XML Web service in your program using code.

To call an XML Web service using code

  1. On the Tools menu, click Toolbox.

  2. In the Toolbox, click My XML Web Services.

  3. Open an editing window to the location in your program or code where you want to call the XML Web service.

  4. Drag and drop the XML Web service in the editing window.

    The code for the XML Web service appears in the editing window.

You can also type the characters, ws, in the editing window. The Select dialog box appears so that you can select an XML Web service and any additional options and insert code for the XML Web service in the editing window. For more information, see Select Dialog Box.

You can use IntelliSense to see the available methods and parameters for the XML Web service. For example, IntelliSense displays a list of methods available for the XML Web service when you type the following line of code in the editing window:

Copy Code
? YourXMLWebService.
Note:
Make sure to replace MyXMLWebService with the XML Web service object provided in the code.

You can select a method and continue typing as follows to specify parameters for the method:

Copy Code
? MyXMLWebService.WSMethod(
Note:
Replace WSMethod with the XML Web service method you select.

IntelliSense displays the possible parameters and the return type for that method.

You can also port the code for the XML Web service to another computer that does not have the XML Web service registered. Visual FoxPro can detect that the XML Web service is not registered and prompts you to register it. If you do not want to register the XML Web service, you can remove the line that contains the WSDL reference, for example:

Copy Code
* __VFPWSDef__: lofoxtypes=http://mywebserver/foxws/foxtypes.wsdl

For more details about accessing XML Web services using high and low-level calls, see the SOAP Toolkit 3.0 documentation.

Binding XML Web Services to Controls

You can bind an XML Web service to a control or object on a Visual FoxPro form and assign the results of the XML Web service to properties of the control or object.

To bind an XML Web service to a control

  1. Create a new or open an existing form or class.

  2. On the Tools menu, click Toolbox.

  3. Under My XML Web Services in the Toolbox, drag and drop the Generic Handler control or the registered XML Web to a form or class.

    The XML Web Service Builder appears so that you can bind the XML Web service to controls or objects on the form. If the builder does not appear, right-click the XML Web service control and select Builder.

For more information, see XML Web Service Builder.

Note:
It is recommended that you save a newly created form before dropping an XML Web service because the builder needs to access controls on the form using the container path.

See Also

Tasks

Walkthrough: Creating XML Web Services with Visual FoxPro

Other Resources

XML Web Services in Visual FoxPro
How to: Distribute XML Web Services


How to: Distribute XML Web Services

Visual FoxPro 9.0
How to: Distribute XML Web Services
See Also

Support for XML Web services in Visual FoxPro provided by the Microsoft SOAP Toolkit make it possible for you to publish Visual COM Servers (OLEPUBLIC) as XML Web services that can be accessed from the Web. The extensions and objects available in the SOAP Toolkit provide publishing capabilities for XML Web services. For information about publishing Visual FoxPro COM Servers as XML Web services, see Walkthrough: Creating XML Web Services with Visual FoxPro.

Specifying a Default Location for XML Web Services

Before you publish an XML Web service, you can specify a default location for publication. This location is a local Web server Uniform Resource Locator (URL) or a virtual directory that you use to store XML Web service support files, such as ASP listeners and WSDL files. Although this location is optional, it can simplify the process of publishing XML Web services.

Note:
The Visual FoxPro XML Web Service Location dialog box appears the first time you select Web Services on the Wizards menu. If you do not provide a default location, Visual FoxPro prompts you for the default location each time you publish a new XML Web service. You can change the location later by clicking Advanced in the Visual FoxPro XML Web Services Publisher dialog box.

For more information, see Visual FoxPro XML Web Service Location Dialog Box and Visual FoxPro XML Web Services Publisher Dialog Box.

To specify a default location for an XML Web service

  1. On the Tools menu, point to Wizards, and click Web Services.

  2. In the dialog box that appears, click OK.

  3. In the Visual FoxPro XML Web Service Location dialog box, to select an existing location to publish your XML Web service, click Existing and select a location in the Select Location (Virtual Directory) box.

    -or-

    To select a new location, click New, select a location in the Select Location (Virtual Directory) box, click the Ellipsis (...) button to specify a file output path if desired, and type a name for the directory in the New Virtual Directory Name box.

Settings for each XML Web service are preserved so that you can easily update the XML Web service, for example, if the content of the WSDL changes. These settings are stored in the FoxWS3.dbf table in the same directory as the FoxCode.dbf table (_FOXCODE).

Publishing XML Web Services

You can publish a Visual FoxPro COM Server as an XML Web service to make it available on the Web.

Note:
Publishing XML Web services through the Visual FoxPro Web Services Publisher dialog box is supported only for generating WSDL files containing a single service and port or class. If you want to select multiple classes, you should use the wizard available in the SOAP Toolkit.

To publish an XML Web service

  1. On the Tools menu, click Task Pane.

  2. On the Task Pane Manager toolbar, click More Panes.

  3. In the XML Web Services pane, click Publish Your XML Web Service.

  4. In the Visual FoxPro XML Web Services Publisher dialog box, click the Ellipsis (...) button to browse for and select the Visual FoxPro COM Server you want.

You can also publish your COM Server by clicking Web Services on the Wizards menu, right-clicking an open COM Server project, clicking Builder on the shortcut menu, and selecting Web Services Publisher in the Wizard Selection dialog box. You can also open the Visual FoxPro XML Web Services Publisher dialog box using the following code:

Copy Code
DO (_wizard) WITH "project",,"Web"

For more information, see Visual FoxPro XML Web Services Publisher Dialog Box.

See Also

Other Resources

Testing and Rebuilding COM Servers for XML Web Services
Deploying XML Web Services
XML Web Services in Visual FoxPro


Testing and Rebuilding COM Servers for XML Web Services

Visual FoxPro 9.0
Testing and Rebuilding COM Servers for XML Web Services
See Also

When rebuilding your COM Server, you can generate XML Web service support files automatically by creating a project hook for the COM Server project that calls the XML Web service engine to rebuild the XML Web service support files. You can select this option in the Advanced dialog box of the Visual FoxPro XML Web Services Publisher dialog box. The project hook (WSHOOK) is stored in the XML Web services foundation class library, _WS3Utils.vcx, located in the Visual FoxPro ..\Ffc folder. For more information, see XML Web Services Foundation Classes.

When you are working with and testing your XML Web service, it is likely that IIS caches your COM Server for performance reasons. To rebuild your COM Server, you might need to first end the process that has the COM Server in use, for example, the IIS Out-Of-Process Pooled Applications COM+ application; otherwise, a denial of access message is generated during the project build process. This process can be a cumbersome if you must test and rebuild the COM Server frequently. The project hook in the XML Web service foundation class library, _WS3Utils.vcx, can close this process for you.

Note:
You might need to change the default setting in the project hook so that the application ends, depending on which OS platform and version of IIS you are running.

For more information, see XML Web Services Foundation Classes.

See Also

Other Resources

Deploying XML Web Services
XML Web Services in Visual FoxPro


Deploying XML Web Services (Visual FoxPro)

Visual FoxPro 9.0
Deploying XML Web Services (Visual FoxPro)
See Also

When deploying Visual FoxPro applications that use XML Web services, you must include the redistributable components from the SOAP Toolkit. If your application accesses only existing XML Web services, you must include only the SOAP Client merge module.

For applications that publish XML Web services, you must include the client-side and server merge modules from the SOAP Toolkit. In addition, you must include the specific server support files, for example, ASP listener and WSDL files. You should also consider using the XML Web services foundation class files, _WS3Utils.vcx and _WS3Client.vcx, to automate this process when running the deployed application for the first time.

If you automate the XML Web service publishing process, you can create a virtual directory and generate support files on the fly. However, it is recommended that you perform extensive Setup testing if you choose this approach for deployment.

See Also

Other Resources

How to: Distribute XML Web Services
XML Web Services in Visual FoxPro


Automation and COM Servers

Visual FoxPro 9.0
Automation and COM Servers

You can extend the functionality of your Visual FoxPro applications and save time writing code by using Automation and COM Servers. With Automation, you can control other applications, such as Microsoft Excel, from within your own application. COM servers allow you to package complex routines into reusable components.

In This Section

Controlling Visual FoxPro from Other Applications

Discusses how you can control Visual FoxPro from other applications by using the Visual FoxPro Application object. Applications that support Automation can create instances of Visual FoxPro, run Visual FoxPro commands, and access Visual FoxPro objects.
Visual FoxPro and Advanced COM

Shows how to take advantage of the COM features in Visual FoxPro by implementing interfaces and event binding. Discusses the inner workings of early versus late binding for both client and server, COM performance, and making COM objects more discoverable.
Referencing Data Types in COM Objects

Describes how to create an instance of a variable with a type you expect to retrieve when you use Visual FoxPro as an early binding client and want to reference a variant data type in a COM object.
Working with Automation Servers

Describes creating and using Automation servers.
Visual FoxPro Run-Time Libraries

Describes the two separate run-time libraries that ship with Visual FoxPro: one for most normal application types and the other for highly scalable in-process server applications.
Server Design Considerations and Limitations

Describes certain behaviors, processes, and limitations that can determine the effectiveness of your server application.

Related Sections

Web Services and Components

Describes how you can enable a Visual FoxPro application to work for multiple users, taking advantage of ActiveX controls and automation-enabled applications, and adding international capabilities.
Interoperability and the Internet

Explains how to use OLE drag-and-drop to develop applications that make it possible for you to move data between Microsoft Windows-based applications and within a Visual FoxPro application. Create documents for use on the Internet, or use one of two different Visual FoxPro run times to create COM components (Automation servers) as normal or multithreaded applications.


Controlling Visual FoxPro from Other Applications

Visual FoxPro 9.0
Controlling Visual FoxPro from Other Applications
See Also

Because Visual FoxPro acts as a server (with level 2 compliance) as well as a client, applications that support Automation can create instances of Visual FoxPro, run Visual FoxPro commands, and access Visual FoxPro objects.

You control Visual FoxPro from other applications by using the Visual FoxPro Application object. An Application object is automatically created whenever Visual FoxPro is launched, either directly, through DDE or through Automation.

For example, the following lines of code in Visual Basic®, or a Microsoft Excel module create a reference to a Visual FoxPro application object:

Copy Code
Dim oFox as Object
Set oFox = CreateObject("VisualFoxPro.Application")

Once you have a reference to the Visual FoxPro Application object, you can call methods associated with the application object and access other objects through the collection properties of the Application object.

Application Object Methods

DataToClip | Help
DoCmd | Quit
Eval | RequestData

The following example uses Visual Basic for Applications code in an Excel module to create a Visual FoxPro Application object, open a Visual FoxPro table, and add the results of a query to the active spreadsheet:

Copy Code
Sub FoxTest()
Dim oFox as Object
Set oFox = CreateObject("VisualFoxPro.Application")

oFox.DoCmd "USE customer"
oFox.DoCmd "SELECT contact, phone FROM customer
   WHERE country = " + Chr$(39) + USA+ Chr$(39) + " INTO CURSOR cust"
oFox.DataToClip "cust",,3
Range("A1:B1").Select
ActiveSheet.Paste
End Sub

The Visual FoxPro Application Object Model

An application object is automatically created whenever Visual FoxPro is launched, either directly, through Automation or DDE. This application object provides access to all other objects created in a Visual FoxPro session through Collection properties.

Visual FoxPro application object model graphic

Accessing Objects Through Collection Properties

The Visual FoxPro application object and all container objects in Visual FoxPro have a count property and a collection property associated with them. The collection property is an array referencing each contained object. The count property is a numeric property indicating the number of contained objects.

The following table lists objects and the corresponding collection and count properties.

Object | Collection Property | Count Property
Application | Objects Forms | Count FormCount
FormSet | Forms | FormCount
Form | Objects Controls | Count ControlCount
PageFrame | Pages | PageCount
Page | Controls | ControlCount
Grid | Columns | ColumnCount
CommandGroup | Buttons | ButtonCount
OptionGroup | Buttons | ButtonCount
Column | Controls | ControlCount
ToolBar | Controls | ControlCount
Container | Controls | ControlCount
Control | Controls | ControlCount

These properties allow you to use a program loop to manage all or specific contained objects. For example, the following lines of code set the Visible property of all forms to True (.T.):

Copy Code
FOR EACH Form IN Application.Forms
   Form.Visible = .T.
ENDFOR

See Also

Other Resources

Automation and COM Servers
Sharing Information and Adding OLE


Visual FoxPro and Advanced COM

Visual FoxPro 9.0
Visual FoxPro and Advanced COM
See Also

You can take advantage of the COM features in Visual FoxPro by implementing interfaces and event binding. Earlier versions of Visual FoxPro provided early binding support for COM servers, but only late binding support as a client. Visual FoxPro now contains support for early binding clients. This topic discusses the inner workings of early versus late binding for both client and server, as well as COM performance and making COM objects more discoverable.

Overview

COM was developed to make it possible for applications to be treated as objects, which can call each other. Object relationships can take on many forms. The simplest form is a client object, which calls a server object. Examples of object interactions that are more complex than this client-server scenario include peer-to-peer objects, which call each other.

If the objects have no a prior knowledge of each other, there must be some way for the objects to describe how another can call into itself. Event interfaces are examples of objects that describe these callback interfaces. These are interfaces that are not implemented by the software object developer but are implemented by a client of that object. Microsoft ActiveX controls are an example of COM objects with very sophisticated interfaces. These interfaces (on both the control and the host) make it possible for the control to act as a native control on a host site. The host site can implement the control's events interface. This combination can be very powerful in the hands of the developer.

This topic starts with a very simple Microsoft Visual FoxPro COM server and shows how useful it is. Then, it covers Type Libraries, how you can read them to discover how a COM object exposes itself to the world, and performance and error handling. Finally, it talks about what an interface is and about implementing interfaces.

Another dimension of objects calling each other is how they call each other. Visual FoxPro 6.0 made it possible for both early and late binding clients to call Visual FoxPro 6.0 servers, but Visual FoxPro 6.0 only could call servers using late binding. The current version of Visual FoxPro includes the capability of early binding client calls.

Creating a Simple Visual FoxPro COM Server

You create a PRG file, which will be called MYCLASS.PRG, with the following code:

Copy Code
*This entirely self-contained program will build a COM server
* called "myserver.myclass"
* It will unregister a prior instance, if any
IF PROGRAM() != "MYCLASS"
   ?"this file MUST BE NAMED 'myclass.prg'"
   return
ENDIF
IF FILE("myclass.dll")
   DECLARE integer DllUnregisterServer IN myclass.dll
   DllUnregisterServer()
   CLEAR DLLS
ENDIF
BUILD PROJECT myserver FROM myclass
BUILD DLL myserver from myserver recomp
*now test this COM server:
ox = CreateObject("myserver.myclass")    && create the server object
ox.mydocmd("USE home(1)+'samples\data\customer'")    && use a table
?ox.myeval("RECCOUNT()")    && get the record count

DEFINE CLASS myclass AS session OLEPUBLIC
   PROCEDURE MyDoCmd(cCmd as String) as Variant ;
         helpstring "Execute a VFP cmd"
      &cCmd    && just execute parm as if it were a fox command
   FUNCTION MyEval(cExpr as String) ;
         helpstring "Evaluate a VFP expression"
      RETURN &cExpr    && evaluate parm as if it were a fox expr
   FUNCTION Error(nError, cMethod, nLine)
      COMreturnerror(cMethod+'  err#='+str(nError,5)+;
         '  line='+str(nline,6)+' '+message(),_VFP.ServerName)
      && this line is never executed
ENDDEFINE

A program of this structure builds COM servers and does not pollute the registry. Note that the code before the class definition is executed at build time only. Building a COM server automatically registers it in the registry. Rebuilding the server automatically unregisters it first. However, the information to unregister is stored in the PJX file. If the PJX is deleted and rebuilt, the registry entries are not removed when a new PJX is built.

Now, you have built your first server. Building a server in Visual FoxPro also builds a Type Library and registers information in the system registry including the ProgId, Type Library, and file location. The build process creates a file called myserver.vbr, which shows what registry keys get changed for registering the server correctly.

Notice that you are using the SESSION base class that was new to Visual FoxPro 6.0 SP3. It is a very lightweight base class that is non-visual and only has the DataSession property to make it possible for separate data sessions. When building COM servers, the FORM base class also has a DataSession property, but it has many other properties that are irrelevant to a COM server. In addition, these properties are, by default, written out to the Type Library unless you mark them all as protected or hidden.

Type Libraries

A Type Library is a file that can be either freestanding or embedded as a resource inside an EXE or DLL. It is a language-independent method of publishing the interfaces, properties, and methods of a COM object. It can contain help strings, Help context IDs, parameter names, and member names (of properties and methods). If it is not embedded inside an EXE or DLL, typical file extensions are TLB or OLB.

The Visual FoxPro 6.0 generated Type Libraries contain the method and parameter names of OLE Public methods. If there is a description in the Description of the class in the VCX, then that description is put in the Type Library as a help string.

You can view a Type Library using a variety of tools. For example, use the Object Browser in Microsoft Excel or Microsoft Word, the Class Browser in Visual FoxPro, or the OLE Viewer in Visual C++ to view a Type Library. You can see that Type Libraries can contain entire object models of the server application and can be rather extensive.

When a tool is viewing a Type Library, the server cannot be rebuilt, because the Type Library cannot be rewritten. Also, if a client has the server instantiated, it cannot be rebuilt. Using a copy of the built DLL or EXE is one way to avoid this problem.

Reading a Type Library

A Type Library reading tool (TLBINF32.DLL) ships with Microsoft Visual Studio. It is a tool intended for use by multiple products, so it was written as a COM server. Here is some sample code to read the Type Library from the sample server created earlier.

Copy Code
clear
PUBLIC otlb
otli=NEWOBJECT('tli.tliapplication')
otlb=otli.TypeLibInfoFromFile("myserver.dll")
*otlb=otli.TypeLibInfoFromFile("tlbinf32.dll")
*otlb=otli.TypeLibInfoFromFile("c:\program files\microsoft office\office\excel9.olb")
?"CoClasses:"
FOR each oCoClass in otlb.CoClasses
   ?"  ",oCoClass.name
   *now each interface associated with this CoClass
   for each oInterface in oCoClass.Interfaces
      ?"     ",oInterface.name
   endfor
endfor

?
?"Interfaces"

FOR each oInterface in otlb.Interfaces
   ?"  ",oInterface.name
ENDFOR
?
?"Interface Members for 1st interface"
FOR each oMember IN otlb.Interfaces(1).Members
   ?"  ", oMember.name
   FOR each oParm in oMember.Parameters
      ?"             ",oParm.name
   ENDFOR
ENDFOR

This code first creates an instance of the TLB reading tool and then invokes the TypeLibInfoFromFile method to load a Type Library. Items within the library are represented as various collections, which can be manipulated quite easily in Visual FoxPro using the FOR EACH construct.

The Interface collection is a collection of interfaces described in the Type Library. These interfaces can be those implemented by the server or they could be interfaces that should be implemented by a client, for example, in the case of Events.

The CoClass collection describes the COM objects that can be created by a client. The default interface implemented by the CoClass is shown, along with an optional Event Source interface.

Other interfaces besides the default of the CoClass and the Event interface could be described. The way a client obtains these other interfaces could be through a method call. For example, an ICell interface could be returned from a method called GetCell.

Constants also can be defined in the Type Library. For example, to obtain the constants, such as xlMaximized, from the Excel Type Library, explore the otlb.Constants collection.

One way to learn how to use the TLBINF32.DLL tool is to use it on itself. This will show you the properties, methods, parameters, and so on that are useful.

Performance

Performance means many things to many people. In the context of software and COM objects, performance means getting results faster. COM is about making software modules communicate with one another. So improving COM communications will achieve higher performance.

For example, consider the following code:

Copy Code
ox=CreateObject("excel.application")
start = seconds()
ox.workbooks.add
SET EXCLUSIVE OFF
USE HOME()+'samples\data\customer'
ox.visible=1
FOR i= 1 TO RECCOUNT()
   FOR J = 1 TO FCOUNT()
      ox.Activesheet.cells(i,j).value = EVAL(FIELD(j))
   NEXT
   SKIP
NEXT
ox.Workbooks(1).Close(0)   && close workbook, discarding changes
ox=0   && release Excel
?seconds() - start

It fills an Excel spreadsheet with the values from a table. This code takes about 30 seconds to run for 92 records on the author's machine.

When trying to improve performance, you must keep in mind exactly what is happening and try to figure out where the bottlenecks are.

Making the spreadsheet visible only after it has been filled in, rather than before, shaves off some time. Making Excel not maximized makes it a little faster.

Note that most of the time is spent executing the single line of code that assigns the cell a value. You can remove all COM calls by changing this line to

Copy Code
      oa= EVAL(FIELD(j))

This obviously changes the intent of the code but makes the double loop take only one second. This indicates that 29 seconds was being spent in evaluating the ox.Activesheet.cells part of the line.

Analyzing this line further, Visual FoxPro evaluates ox.Activesheet, and the result is put in a temporary value. Then, this temp value is dereferenced to get the cells collection. Each "." in the expression results in a temporary value being obtained and then being dereferenced to get a new value.

Each of these "." dot operator dereferences is actually a round-trip COM method call to Excel, invoking an Excel method which returns a value. First, the IApplication.ActiveSheet method is invoked, which returns to Visual FoxPro a temporary reference to the active sheet. Then, that object's interface is used to get the cells collection. Then, the collection is dereferenced using the cell's indices as parameters to get an object reference to a single cell. Then, that cell's value property is assigned a new value (another COM round-trip). This totals four round-trips.

Obtaining an object reference to ox.Activesheet before the double nested loop and using that cached reference instead resulted in about 50 percent improvement.

Copy Code
oa = ox.Activesheet    && get an object reference
FOR i= 1 TO RECCOUNT()
   FOR J = 1 TO FCOUNT()
      oa.cells(i,j).value = EVAL(FIELD(j))
   NEXT
   SKIP
NEXT

Because the Activesheet is loop invariant with respect to the double loop, you can obtain an object reference to it before the loop and cache it in a variable. This removes one round trip, thus making the total three.

The number of round-trips decreased by 25 percent, but the time decrease was 50 percent. The removal of the number of round-trips will not result in a proportional decrease in overall time. The overhead of creating and releasing several temporary variables, the fraction of the time spent actually in the server executing the code, and other factors are not linear.

Note:
The previous code does not have to use Activesheet at all. The cells collection also is found from the Iapplication interface. It was used here only for illustration purposes.

Using Visual Basic as a Client

You can use Visual Basic as a client to accomplish the same task.

To use Visual Basic as a client

  1. Start Excel.

  2. On the Tools menu, point to Macro.

  3. Click Macros, and name it t.

  4. Click Create.

  5. On the Tools menu, click References, and add the myserver Type Library to the references.

    This makes it possible for the myserver Type Library information to be used in the macro.

  6. Paste the following code:

    Copy Code
    Sub t()
Dim ox As New myserver.myclass
ox.mydocmd ("SET EXCLUSIVE OFF")
ox.mydocmd ("USE C:\Program Files\Microsoft Visual FoxPro VersionNumber\Samples\Data\Customer")
n = ox.MyEval("reccount()")
nflds = ox.MyEval("fcount()")
nsecs = ox.MyEval("seconds()")
For i = 1 To n
    For j = 1 To nflds
        cc = "evaluate(field(" & j & "))"
        Application.Sheets(1).Cells(i, j).Value = ox.MyEval(cc)
    Next
    ox.mydocmd ("skip")
Next
MsgBox (ox.MyEval("seconds()") - nsecs)
End Sub

Error Handling

Error handling is very important in COM servers, and particularly so in DLL servers. If the client were to invoke a method on the server that caused some sort of error, such as File Not Found or Access Denied, it would not be good to have the server show a message box indicating the error. The developer should use the Error Method of the OLE Public class to handle such errors gracefully. A new function in Visual FoxPro 6.0, called COMReturnError, will cause a COM Error object to be created and returned to the COM client. It takes two parameters: the Source and the Description. You can put any strings you want into these parameters. This example method can be pasted right into the previous myserver sample.

Copy Code
FUNCTION Error(nError, cMethod, nLine)
   COMreturnerror(cMethod+'  err#='+str(nError,5)+'  line='+str(nline,6)+'
      '+message(),_VFP.ServerName)
   && this line is never executed

You can invoke this error method by calling the MyDocmd method with an invalid command:

Copy Code
ox = CreateObject("myserver.myclass")    && create the server object
?ox.mydocmd("illegal command")    && causes an Error to occur

The error that occurs in the server is trapped by the MyClass::Error method, which then causes the server to abort processing and return the COM Error object with the Source and the Description filled out.

Copy Code
?aerror(myarray)
list memo like myarray
MYARRAY     Pub    A
   (   1,   1)     N  1429        (      1429.00000000)
   (   1,   2)     C  "OLE IDispatch exception code 0 from mydocmd
                      err#=   16  line=     2 Unrecognized command v
                      erb.: c:\fox\test\myserver.exe.."
   (   1,   3)     C  "c:\fox\test\myserver.exe"
   (   1,   4)     C  "mydocmd  err#=   16  line=     2 Unrecognized
                       command verb."
   (   1,   5)     C  ""
   (   1,   6)     N  0           (         0.00000000)
   (   1,   7)     N  0           (         0.00000000)

Interfaces

Operationally, a COM interface can be thought of as a pointer to a table of function addresses. This table is sometimes called the vtable, or virtual function table. The interface definition includes the number of entries in the table, the association between the method name and the table index, and the function signatures of each method call. The signature consists of the number of parameters, the types of the parameters, and the return value.

All COM interfaces inherit from IUnknown. This means that the first three entries in every COM interface vtable are defined to be the addresses of the server's implementation of IUnkown::QueryInterface, IUnkown::AddRef, and IUnkown::Release.

When an interface inherits from another interface, all that means is that the interfaces vtable consists of the vtables of the inherited interfaces first.

Dual interfaces are COM Interfaces that inherit from the IDispatch interface. The IDispatch interface has only four methods: GetTypeInfoCount, GetTypeInfo, GetIDsOfNames, and Invoke. Thus, the first seven interfaces are well defined in an IDispatch interface and any other interface that inherits from IDispatch.

For Myserver.dll created earlier, the dual interface IMyClass would look like this:

Copy Code
   IMyClass
      QueryInterface(QI params)  (from IUnknown)
      Addref                     (from IUnknown)
      Release                    (from IUnknown)
      GetTypeInfoCount()         (from IDispatch)
      GetTypeInfo()              (from IDispatch)
      GetIDsOfNames()            (from IDispatch)
      Invoke()                   (from IDispatch)
      MyDoCmd(cCmd)              (from IMyClass)
      MyEval(cExpr)              (from IMyClass)

Suppose that the client wants to make a call to the Activesheet method of the dual interface IApplication on the server. The actual call can be made in two ways: early and late binding. Early binding is sometimes called VTtable binding, because it just means the client calls the server directly by finding the address of Activesheet in the vtable directly. This function address is an entry in the vtable and will be larger than seven. This function address index is hard coded into the client call at client compile time and is known as early binding. If subsequent versions of the server were to change the vtable order, then early binding client calls would be erroneous.

Late binding calls go through the IDispatch interface. The client calls IDispatch::GetIDsOfNames with the string Activesheet to get the function ID of that function. (This function ID then can be cached by the client for subsequent calls.) The client then packages all the Activesheet parameters into a single DISPPARAMS structure, and the IDispatch::Invoke function is called with the function ID and the DISPPARAMS as parameters. The implementation of IDispatch::Invoke on the server side unpacks the DISPPARAMS structure, makes the actual call to Activesheet, gets the return value, and passes that back to the client.

Because late binding does not hard code the function index of method calls, clients do not have to know at compile time what the function index is for methods and still will work, even if a new version of the server rearranges the vtable order or changes the method signatures. However, the parameter packaging on the client side and the unpackaging on the server side adds execution time to the method calls that does not exist with early binding calls.

Implementing Interfaces

Implementing an interface means that you examine an object's properties, events, and methods and create a new object that has exactly the same properties, events, and methods. This includes any parameters, parameter types, and return values. In other words, if an object knows how to call another object using a specific interface, then it also knows how to call any object that implements that specific interface.

Implementing an interface promises to the client that every method on that interface can be called. That means if there is a method called Sample(parm1 as int, parm2 as string, parm3 as variant @) as int, then that identical method signature must be found in the object.

In the following ADO sample, for example, if a parameter is removed from the method signature, running the code yields this message:

Note:
Class can not be instantiated because Member 'RECORDSETEVENTS_WillChangeField' has wrong # of parameters

Similarly, removing a method yields another error message.

As mentioned earlier, interfaces are described in Type Libraries for all to see. The Visual FoxPro Object Browser (on the Tools Menu) makes it possible for you to inspect type libraries. If you drag an interface from it onto a PRG that is open in the Visual FoxPro editor, then the object browser will generate the method signatures required for implementing that interface.

Event Binding

The ability to implement interfaces makes it possible for some interesting capabilities with Microsoft Office. This sample implements the events for Microsoft Outlook, Excel, and Word. As you can see from the method names, each Office application provides different interfaces. The new EventBinding command in the current version of Visual FoxPro makes it possible for the developer to bind a Visual FoxPro class that implements an interface to the COM object that is the event source and publisher.

This event model is called tightly coupled events. The client and the server must have intimate knowledge about each other, and there's a one-to-one correspondence between the objects. A new model of object event interaction is called loosely coupled events, in which an object can publish events, and another object can subscribe to those events.

Copy Code
CLEAR
CLEAR all
PUBLIC ox as Excel.Application, ;
   ow as word.application, ;
   oOutlook as Outlook.Application

oOutlookEvents= NEWOBJECT('OutlookEvents')

oOutlook = NEWOBJECT("Outlook.Application")
oOutlookEvents.oo = oOutlook
? "Outlook",EVENTHANDLER( oOutlook, oOutlookEvents)

oWordEvents = NEWOBJECT("WordEvents")
ow = NEWOBJECT("word.application")
oWordEvents.ow = ow
?"Word",EVENTHANDLER(ow,oWordEvents)
ow.visible = .t.
ow.Activate
ow.Documents.Add

oExcelEvents = NEWOBJECT("ExcelEvents")
oex = NEWOBJECT("excel.application")
oex.Workbooks.Add
?"Excel",EVENTHANDLER(oex, oExcelEvents)
oex.visible = .t.

_screen.WindowState= 1

DEFINE CLASS OutlookEvents AS SESSION OLEPUBLIC
   IMPLEMENTS ApplicationEvents IN Outlook.Application
   oo = .null.
   PROCEDURE ApplicationEvents_ItemSend(ITEM AS VARIANT, ;
         CANCEL AS LOGICAL) AS VOID
      ?PROGRAM()
      m.item.Body=STRTRAN(m.item.Body,"good","bad") + ;
         CHR(13)+CHR(10)+TRANSFORM(DATETIME())+" Fox was here!"
*      if Recipients fails, it could be outlook security
*      m.item.Recipients.Add("someone@example.com")
   PROCEDURE ApplicationEvents_NewMail() AS VOID
      ?PROGRAM()
   PROCEDURE ApplicationEvents_Reminder(ITEM AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE ApplicationEvents_OptionsPagesAdd(PAGES AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE ApplicationEvents_Startup() AS VOID
      ?PROGRAM()
   PROCEDURE ApplicationEvents_Quit() AS VOID
      ?PROGRAM()
   PROCEDURE destroy
      ?PROGRAM()
      IF !ISNULL(this.oo)
         ?EVENTHANDLER(this.oo,this,.t.)
      ENDIF
ENDDEFINE

DEFINE CLASS WordEvents as Custom
   implements applicationevents2 in "word.application"
   ow = .null.
   PROCEDURE applicationevents2_startup()
      ?PROGRAM()
   PROCEDURE applicationevents2_quit
      ?PROGRAM()
   procedure applicationevents2_DocumentBeforeClose(Cancel,Doc)
      ?PROGRAM()
   procedure DocumentBeforeClose(Cancel,Doc)
      ?PROGRAM()
   procedure applicationevents2_DocumentBeforePrint(Cancel,Doc)
      ?PROGRAM()
   procedure applicationevents2_DocumentBeforeSave(Doc,SaveAsUI,Cancel)
      ?PROGRAM()
   procedure applicationevents2_DocumentChange
      ?PROGRAM()
   procedure applicationevents2_DocumentOpen(Doc)
      ?PROGRAM()
   procedure applicationevents2_NewDocument(Doc)
      ?PROGRAM()
   procedure applicationevents2_WindowActivate(Doc,Wn)
      ?PROGRAM()
   procedure applicationevents2_WindowBeforeDoubleClick(Sel,Cancel)
      ?PROGRAM()
   procedure applicationevents2_WindowBeforeRightClick(Sel,Cancel)
      ?PROGRAM()
   procedure applicationevents2_WindowDeactivate(Doc,Wn)
      ?PROGRAM()
   procedure applicationevents2_WindowSelectionChange(Sel)
      ?PROGRAM(),sel.text
      IF sel.start < sel.end
          sel.InsertAfter("Fox!")
*!*         mtmp = sel.text
*!*         sel.text=STRTRAN(mtmp,"good","Great!")
      endif
   PROCEDURE destroy
       ?PROGRAM()
       IF !ISNULL(this.ow)
         ?EVENTHANDLER(this.ow,this,.t.)
      ENDIF
ENDDEFINE

DEFINE CLASS ExcelEvents AS session OLEPUBLIC
   IMPLEMENTS AppEvents IN "excel.application"
   PROCEDURE AppEvents_NewWorkbook(Wb AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_SheetSelectionChange(Sh AS VARIANT, ;
         Target AS VARIANT) AS VOID
      LOCAL mtmp,mcell
      mcell = m.target.Cells(1,1)
      IF !ISNULL(mcell)
         mtmp = m.target.Cells(1,1).Value
         ?PROGRAM(),VARTYPE(mtmp)
         DO case
         case ISNULL(mtmp)
   *         m.target.Cells(1,1).Value  = "Fox is great"
         CASE VARTYPE(mtmp)='C'
            m.target.Cells(1,1).Value = ;
               STRTRAN(mtmp,"good","great!")
         CASE VARTYPE(mtmp)='N'
            m.target.Cells(1,1).Value = mtmp + 1
         ENDCASE
      ENDIF
   PROCEDURE AppEvents_SheetBeforeDoubleClick(Sh AS VARIANT, ;
         Target AS VARIANT, Cancel AS LOGICAL) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_SheetBeforeRightClick(Sh AS VARIANT, ;
         Target AS VARIANT, Cancel AS LOGICAL) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_SheetActivate(Sh AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_SheetDeactivate(Sh AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_SheetCalculate(Sh AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_SheetChange(Sh AS VARIANT, Target AS VARIANT) AS
         VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookOpen(Wb AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookActivate(Wb AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookDeactivate(Wb AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookBeforeClose(Wb AS VARIANT, ;
         Cancel AS LOGICAL) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookBeforeSave(Wb AS VARIANT, ;
         SaveAsUI AS LOGICAL, Cancel AS LOGICAL) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookBeforePrint(Wb AS VARIANT, ;
         Cancel AS LOGICAL) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookNewSheet(Wb AS VARIANT, ;
         Sh AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookAddinInstall(Wb AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookAddinUninstall(Wb AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WindowResize(Wb AS VARIANT, Wn AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WindowActivate(Wb AS VARIANT, Wn AS VARIANT) AS
         VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WindowDeactivate(Wb AS VARIANT, Wn AS VARIANT) AS
         VOID
      ?PROGRAM()
   PROCEDURE AppEvents_SheetFollowHyperlink(Sh AS VARIANT, ;
         Target AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_SheetPivotTableUpdate(Sh AS VARIANT, ;
         Target AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookPivotTableCloseConnection(Sh AS VARIANT, ;
         Target AS VARIANT) AS VOID
      ?PROGRAM()
   PROCEDURE AppEvents_WorkbookPivotTableOpenConnection(Sh AS VARIANT, ;
         Target AS VARIANT) AS VOID
      ?PROGRAM()
ENDDEFINE

Here is a sample of implementing ADO event interfaces. In this case, the user is not interacting with an application, causing events to occur, as in the Office examples earlier. Here, the user is calling ADO directly using method calls, and ADO is calling back to the client using its event interface.

Copy Code
clear
CLEAR all
local ox as adodb.recordset
local oc as ADODB.Connection
oe = NEWOBJECT("myclass")
oe2 = NEWOBJECT("myclass")

oc=NEWOBJECT("adodb.connection")
connstr = "Driver={Microsoft Visual FoxPro Driver};UID=;PWD=;SourceDB=" + ;
   HOME(1)+"samples\data\testdata.dbc" + ;
    ";SourceType=DBC;Exclusive=No;BackgroundFetch=No;Collate=Machine;"
*
oc.ConnectionString= connstr
oc.Open
ox = oc.Execute("select * from customer")
* Now enable event handling
?EVENTHANDLER(ox,oe)
?EVENTHANDLER(ox,oe2)

?
?PADR(ox.Fields(0).Value,20)

?EVENTHANDLER(ox,oe2,.f.) && Turn off 2nd obj event handling
ox.MoveNext
?PADR(ox.Fields(0).Value,20)
ox.MoveNext
CLEAR all
retu
for i = 0 to ox.Fields.Count-1
*   ?PADR(ox.Fields(i).Name,20)
*   ?ox.Fields[i].value
endfor

DEFINE CLASS myclass AS session
   implements RecordsetEvents IN "adodb.recordset"
*  implements RecordsetEvents IN ;
*"C:\PROGRAM FILES\COMMON FILES\SYSTEM\ADO\MSADO15.DLL"
   PROCEDURE Recordsetevents_WillChangeField(cFields AS Number @, ;
         Fields AS VARIANT @, adStatus AS VARIANT @, ;
         pRecordset AS VARIANT @) AS Void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
   PROCEDURE Recordsetevents_FieldChangeComplete(;
         cFields AS Number @, ;
         Fields AS VARIANT @, pError AS VARIANT @, ;
         adStatus AS VARIANT @, pRecordset AS VARIANT @) AS Void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
   PROCEDURE Recordsetevents_WillChangeRecord(adReason AS VARIANT @, ;
         cRecords AS Number @, adStatus AS VARIANT @, ;
         pRecordset AS VARIANT @) AS Void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
   PROCEDURE Recordsetevents_RecordChangeComplete(adReason AS VARIANT @, ;
         cRecords AS Number @, pError AS VARIANT @, ;
         adStatus AS VARIANT @, pRecordset AS VARIANT @) AS Void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
   PROCEDURE Recordsetevents_WillChangeRecordset(adReason AS VARIANT @, ;
         adStatus AS VARIANT @, pRecordset AS VARIANT @) AS Void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
      ?adreason,adstatus,precordset.recordcount
   PROCEDURE Recordsetevents_RecordsetChangeComplete(;
         adReason AS VARIANT @, ;
         pError AS VARIANT @, adStatus AS VARIANT @, ;
         pRecordset AS VARIANT @) AS Void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
   PROCEDURE Recordsetevents_WillMove(adReason AS VARIANT @, ;
         adStatus AS VARIANT @, pRecordset AS VARIANT @) AS Void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
   PROCEDURE Recordsetevents_MoveComplete(adReason AS VARIANT @, ;
         pError AS VARIANT @, adStatus AS VARIANT @, ;
         pRecordset AS VARIANT @) AS Void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
   PROCEDURE Recordsetevents_EndOfRecordset(fMoreData AS LOGICAL @, ;
         adStatus AS VARIANT @, pRecordset AS VARIANT @) AS Void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
   PROCEDURE Recordsetevents_FetchProgress(Progress AS Number @, ;
         MaxProgress AS Number @, adStatus AS VARIANT @, ;
         pRecordset AS VARIANT @) AS Void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
   PROCEDURE Recordsetevents_FetchComplete(pError AS VARIANT @, ;
         adStatus AS VARIANT @, pRecordset AS VARIANT @) AS void
      ? " "+program() + ' ' + TRANSFORM(DATETIME())
ENDDEFINE

Using Office XP Smart Tags

Office XP includes a new capability called Smart Tags. As a typical knowledge worker at a company works, she might use several computer applications and use similar subjects in each one. For example, the company might have a customer list, and she might need to e-mail, create documents or spreadsheets, or even view Web pages about customers. Suppose that at this instant, she is writing an e-mail message about customer ALFKI, and she must know the customer phone number or credit limit. Typically, this means starting or switching to another application, which maintains this information, doing a lookup for ALFKI, and transferring the data to the e-mail.

Smart Tags technology is a way that multiple applications can recognize strings (tags) within text and optionally provide the user a way to invoke a menu right on top of that tag which can give useful information or perform useful tasks. A smart tag on ALFKI might not only offer the credit limit and address but also might offer the option to go to the customer's Web site, add to a transaction log, launch another application, or even dial the phone. The user could even type in ALFKI temporarily to any application that is being used currently, look up information, then delete that string in the app.

The following is a sample of Smart Tags technology that recognizes the customer IDs in the sample customer table. The Smart Tag action verbs make up the fields of the table, plus one to visit the customer Web site. If the application is Word, the verb for the field inserts that field into the Word document. For Excel, the field value is inserted in the adjacent column, and the width of that column is adjusted. For Internet Explorer, a message box is displayed (note that even though this is a Visual FoxPro DLL, MessageBox can be called using Declare DLL).

A Smart Tag only must register its ProgID in the registry at the appropriate places. The Smart Tag SDK (available on the Microsoft Web site) gives more details on Smart Tags.

A Smart Tag must implement two interfaces: ISmartTagRecognizer and ISmartTagAction. The first scans a string and calls back on a parsed object if a tag is recognized. The second interface describes the actions possible and actually performs the actions.

Note:
If you have any Office applications open, they will have an instance of your DLL open. You will not be able to modify the DLL until you close the Office application.

The Logit method writes to a log file, which is a useful technique to learn about how the interfaces work and to debug any code. Using an editor that automatically refreshes an externally modified file to display the log is useful.

Copy Code
CLEAR ALL
clear
SET excl off
?PROGRAM()

*Smart tags in Office XP. Just change the DATAPATH,STAGPATH if necessary
IF PROGRAM() != "STAG"
   ?"this file MUST BE NAMED 'stag.prg'"
ENDIF
#define STNAME  "MynameSpaceURI#MyLocalName"
#define DATAPATH HOME(1)+"samples\data\"
#define STAGPATH "C:\Program Files\Common Files\Microsoft Shared\Smart Tag\mstag.tlb"
IF .t.
   IF FILE("stag.dll")
      DECLARE integer DllUnregisterServer IN stag.dll
      DllUnregisterServer()
      CLEAR DLLS
   ENDIF
   BUILD PROJECT stag FROM stag
   BUILD mtDLL stag from stag recomp
   STRTOFILE("","d:\t.txt")    && null log file
endif

#DEFINE HKEY_CURRENT_USER  -2147483647  && BITSET(0,31)+1
oFoxReg=NEWOBJECT("foxreg", HOME(1)+"FFC\registry")
oFoxReg.OpenKey("Software\Microsoft\Office\Common\Smart Tag\Actions\stag.MyStag", ;
   HKEY_CURRENT_USER, .T.)
oFoxReg.OpenKey(;
   "Software\Microsoft\Office\Common\Smart Tag\Recognizers\stag.MyStag", ;
   HKEY_CURRENT_USER, .T.)

DEFINE CLASS MyStag AS Session OLEPUBLIC
   IMPLEMENTS ISmartTagRecognizer IN STAGPATH
   IMPLEMENTS ISmartTagAction IN STAGPATH
   PROCEDURE ISmartTagRecognizer_get_ProgId() AS STRING
      logit()
      RETURN   "stag.MyStag"
   PROCEDURE ISmartTagRecognizer_get_Name(LocaleID AS Integer) AS STRING
      logit()
      RETURN "VFP NorthWind Customer Recognizer"
   PROCEDURE ISmartTagRecognizer_get_Desc(LocaleID AS Integer) AS STRING
      logit()
      RETURN "VFP NorthWind Customer ID Recognizer"
   PROCEDURE ISmartTagRecognizer_get_SmartTagCount() AS Integer
      logit()
      RETURN 1
   PROCEDURE ISmartTagRecognizer_get_SmartTagName(;
         SmartTagID AS Integer) AS STRING
      logit()
      If SmartTagID = 1
         RETURN STNAME
         EndIf
      RETURN ""
   PROCEDURE ISmartTagRecognizer_get_SmartTagDownloadURL(;
         SmartTagID AS Integer) AS STRING
      logit()
      RETURN ""
   PROCEDURE ISmartTagRecognizer_Recognize(cText AS STRING, ;
         DataType AS Integer, ;
         LocaleID AS Integer, RecognizerSite AS VARIANT) AS VOID
      logit(ctext+' '+TRANSFORM(LEN(CTEXT)))
      LOCAL i,  mat,cWord,propbag
      i = 1
      DO WHILE i <= LEN(cText)
         IF ISALPHA(SUBSTR(cText,i))
            mst = i
            DO WHILE i <= LEN(cText) AND ;
                  (ISALPHA(SUBSTR(cText,i)) or ;
                  ISDIGIT(SUBSTR(cText,i)))
               i=i+1
            ENDDO
            IF mst # i
               cWord = SUBSTR(cText,mst,i-mst)
               IF SEEK(cWord,"Customer")
                  * Ask for a property bag
                  propbag = ;
                     RecognizerSite.GetNewPropertyBag()
                  * Commit the smart tag
                  propbag.write("test","value")
                  propbag.write("test2","value2")
                     RecognizerSite.CommitSmartTag(STNAME, ;
                       mst, LEN(cWord), propbag)
                    propbag=.null.
               ENDIF
            ENDIF
         ENDIF
         i=i+1
      ENDDO
***********************
   PROCEDURE ISmartTagAction_get_ProgId() AS STRING
      logit()
      RETURN "stag.MyStag"
   PROCEDURE ISmartTagAction_get_Name(LocaleID AS Integer) AS STRING
      logit()
      RETURN "Customer Actions"
   PROCEDURE ISmartTagAction_get_Desc(LocaleID AS Integer) AS STRING
      logit()
      RETURN  "Provides actions for VFP Customer data"
   PROCEDURE ISmartTagAction_get_SmartTagCount() AS Integer
      logit()
      RETURN 1
   PROCEDURE ISmartTagAction_get_SmartTagName(SmartTagID AS Integer) AS
         STRING
      logit()
      IF SmartTagID = 1
         RETURN STNAME
      EndIf
      RETURN ""
   PROCEDURE ISmartTagAction_get_SmartTagCaption(SmartTagID AS Integer, ;
         LocaleID AS Integer) AS STRING
      logit(TRANSFORM(SmartTagID ))
      RETURN  "Customer Lookup"
   PROCEDURE ISmartTagAction_get_VerbCount(SmartTagName AS STRING) AS
         Integer
      logit(SmartTagName )
      If SmartTagName = STNAME
            RETURN FCOUNT()+1
         ENDIF
         RETURN 0
   PROCEDURE ISmartTagAction_get_VerbID(SmartTagName AS STRING, ;
         VerbIndex AS Integer) AS Integer
      logit(SmartTagName +', '+ TRANSFORM(VerbIndex ))
      RETURN VerbIndex
   PROCEDURE ISmartTagAction_get_VerbCaptionFromID(VerbID AS Integer, ;
         _ApplicationName AS STRING, LocaleID AS Integer) AS STRING
      logit(TRANSFORM(VerbID )+' '+_ApplicationName +;
         ' '+TRANSFORM(LocaleID))
      IF VerbId <= FCOUNT()
         RETURN "View "+FIELD(VerbID)
      ENDIF
      RETURN "Visit customer Web site"
   PROCEDURE ISmartTagAction_get_VerbNameFromID(VerbID AS Integer) AS
         STRING
      logit(TRANSFORM(VerbID))
      IF VerbId <= FCOUNT()
         RETURN FIELD(VerbID)
      ENDIF
      RETURN "Visit Web site"
   PROCEDURE ISmartTagAction_InvokeVerb(VerbID AS Integer, ;
         cApplicationName AS STRING, ;
         Target AS VARIANT, oProperties AS VARIANT, ;
         cText AS STRING, Xml AS STRING) AS VOID
      logit(TRANSFORM(VerbID )+' '+cApplicationName +' '+cText+' ';
          +Xml+' '+TRANSFORM(oProperties.count))
      LOCAL i,cProp
      oProperties.write("iitest","iivalue")
      oProperties.write("iitest2","iivalue2")
      FOR i = 1 to oProperties.count
         cProp = oProperties.keyfromindex(i-1)
         logit(cProp)
         logit(oProperties.read(cprop))
      endfor
      LOCAL fExcel,fWord
      DO case
      CASE capplicationname = "Excel.Application.10"
         fExcel = .t.
         logit(m.target.cells[1,1].value)
      CASE capplicationname = "Word.Application.10"
         fWord = .t.
*         logit(m.target.range
      ENDCASE
      IF verbId > FCOUNT()
         LOCAL oie as internetexplorer.application
         oie = NEWOBJECT("internetexplorer.application")
         oie.navigate2("localhost/"+ctext+".html")
         oie.visible=1
      else
         IF SEEK(cText,"customer")
            DO case
            case fExcel
               target.cells[1,2].value = ;

   ALLTRIM(TRANSFORM(EVALUATE(FIELD(VerbID))))
               target.Columns(2).columnWidth = 25
            case fWord
               target.insertAfter(' '+;

   ALLTRIM(TRANSFORM(EVALUATE(FIELD(VerbID)))))
            otherwise
               DECLARE Integer MessageBox IN WIN32API ;
                  as msgbox ;
                  Integer,string,string, integer
               msgbox(0,;

   ALLTRIM(TRANSFORM(EVALUATE(FIELD(VerbID)))), ;
                  ctext+"="+company,0)
            endcase
         ELSE
            logit("not found")
         ENDIF
      ENDIF
   PROCEDURE Init
      logit()
      SET EXACT ON
      SET EXCLUSIVE off
      SET PATH TO DATAPATH
      USE customer order cust_id shared
   PROCEDURE Destroy
      logit()
   PROCEDURE MyDoCmd(cCmd as String)
      &cCmd
   PROCEDURE MyEval(cExp as String)
      RETURN &cExp
   PROCEDURE Error(nError, cMethod, nLine)
      logit(TRANSFORM(nError)+' '+TRANSFORM(nLine)+' '+MESSAGE())
ENDDEFINE
#if .f.
DEFINE CLASS STagAction AS StagRecognizer OLEPUBLIC
   PROCEDURE Error(nError, cMethod, nLine)
      logit(PROGRAM()+" "+TRANSFORM(nError)+' '+TRANSFORM(nLine)+' '+MESSAGE())

ENDDEFINE
#endif
   FUNCTION Logit(cStr)
TEXT TO mystr TEXTMERGE NOSHOW
<<DATETIME()>> <<PROGRAM(PROGRAM(-1)-1)>> <<cStr>>

ENDTEXT
      STRTOFILE(myStr,"D:\t.TXT",.T.)

Visual FoxPro Callback Design

Visual FoxPro makes it possible for the developer to create COM objects, which publish interfaces that clients can implement. This callback scenario is almost identical to Visual FoxPro objects raising events to clients. This sample consists of a main COM server class called IDEMO, which also publishes an event interface, called DemoEvents.

The client code has a single class called cCallBack, which implements DemoEvents.

IDEMO has a method called BuyStock, which clients can call to buy some stock. The BuyStock method just has a comment where code can be put to buy the stock. However, before and after that code, the method calls methods in the DemoEvents class. If the client does not have a callback procedure set using the SetCallBack method, then the calls to the DemoEvents methods do nothing. However, if there is a callback object, then those methods will be called on the client.

Copy Code
CLEAR ALL
IF PROGRAM() != "IDEMO"
   ?"this file MUST BE NAMED 'idemo.prg'"
   RETURN
ENDIF
IF .t.
   IF FILE("idemo.dll")
      DECLARE integer DllUnregisterServer IN idemo.dll
      DllUnregisterServer()
      CLEAR DLLS
   ENDIF
   BUILD PROJECT idemo FROM idemo
   BUILD DLL idemo from idemo recomp
endif
clear

oCallback = NEWOBJECT("cCallback")    && the event callback
ostock=newOBJECT("idemo.idemo")       && the business COM obj
ostock.setcallback(oCallBack)         && like BindEvents
?ostock.BuyStock("MSFT",10000 )       && invoke a method
ostock.setcallback(.null.)            && like UnBindEvents
?ostock.BuyStock("MSFT",20000 )       && this one doesn't fire events

*This is the actual implementation of the event interface
DEFINE CLASS cCallback as session
   implements iDemoEvents in idemo.dll
   procedure iDemoEvents_BeforeBuyStock(cStock as String, qty AS Number)
      ?program(),cstock,qty
   procedure iDemoEvents_AfterBuyStock(cStock as String, qty AS Number)
      ?program(),cstock,qty

enddefine
*the rest of this file is used in the COM server
DEFINE CLASS idemo as session olepublic
   oc = .null.
   PROCEDURE init
      this.SetCallBack(.null.)    && set callback to default
   PROCEDURE setcallback(oC as Variant)
      IF ISNULL(oc)
         && dummy instance that does nothing: virtual function
         this.oc = NEWOBJECT("DemoEvents")
      else
         IF VARTYPE(oc) != 'O'
            COMRETURNERROR(PROGRAM(),"callback must be obj")
         ENDIF
         this.oc = GETINTERFACE(oC,"iDemoEvents","idemo.idemo")
      endif
   procedure MyDoCmd(cCmd as String) as Variant
      &cCmd
   procedure MyEval(cExpr as String) as Variant
      return &cExpr
   procedure BuyStock(cStock as String, qty AS Number) as Boolean
      this.oc.BeforeBuyStock(cStock, qty)
      *here we buy the stock
      this.oc.AfterBuyStock(cStock, qty)
   FUNCTION Error(nError, cMethod, nLine)
      COMreturnerror(cMethod+'  err#='+str(nError,5)+'  line='+;
         str(nline,6)+' '+message(),_VFP.ServerName)
      && this line is never executed

enddefine

*Just an interface definition that should be implemented by outside callers
DEFINE CLASS DemoEvents as session olepublic
   procedure BeforeBuyStock(cStock as String, qty AS Number)
   procedure AfterBuyStock(cStock as String, qty AS Number)
enddefine

COM enables objects to interact with each other in various ways. Each addition of new COM capabilities to Visual FoxPro, including a simple COM client functionality, interface implementation, and early binding server and client support, has provided many new capabilities.

See Also

Other Resources

How to: Create Automation Servers
Automation Server Programming Notes
Event Binding for COM Objects
Automation and COM Servers


Referencing Data Types in COM Objects

Visual FoxPro 9.0
Referencing Data Types in COM Objects
See Also

When you use Visual FoxPro as an early binding client and want to reference a variant data type in a COM object, you must first create an instance of the variable with the type you expect to retrieve. For example:

Copy Code
DEFINE CLASS varianttest AS SESSION OLEPUBLIC
   FUNCTION varret(outVal AS VARIANT@, inVal AS VARIANT) AS VOID
      OutVal = inVal
   ENDFUNC
ENDDEFINE

After building this class into a DLL named myServer, you can reference the data as shown in the following code:

Copy Code
x = CREATEOBJECT("myServer.varianttest","","")
ov = ""
tt.varret(@ov, "string")   && Sets string value.
ov = 0
tt.varret(@ov, 123)         && Sets ov to an integer value.
ov = 0.0
tt.varret(@ov, 44.44)      && Sets ov to a real numeric value.
ov = l
tt.varret(@ov, f)            && Sets ov to a Boolean value.

See Also

Other Resources

Binding Type Libraries
Early (vtable) and Late (IDispatch) Binding
Working with Automation Servers


Working with Automation Servers

Visual FoxPro 9.0
Working with Automation Servers

You can expose functionality that other applications can use by creating Automation servers in Visual FoxPro.

For example, you can create an Automation server that displays reusable forms or packages a complex routine into a more simple component that other programmers can use. You can create classes for creating objects to handle enterprise-wide business rules. A client application can use those business rule objects to call methods and pass parameters to the Automation server, which can retrieve or store data, perform operations, and return results.

In This Section

Automation Servers in Visual FoxPro

Provides an overview of creating and using Automation servers.
How to: Create Automation Servers

Describes how to create Automation servers.
Automation Server Programming Notes

Provides links to topics that explain additional information on creating automation servers.
How to: Build Automation Servers

Describes how to compile Automation servers.
How to: Register Automation Servers

Describes how to register Automation servers so other applications can access them.
Binding Type Libraries

Discusses Visual FoxPro support for intrinsic Visual FoxPro properties, events, and methods in an Automation server type library.
Early (vtable) and Late (IDispatch) Binding

Discusses Visual FoxPro support for dual interface support, early (vtable) and late (Idispatch) binding.
Passing Arrays to Automation Servers

Discusses how to pass an array to an Automation server by using the COMARRAY( ) function.
Compiling Source Code

Describes how to enable an application to generate and compile a program (.prg) file during run time.
Scalability and Multithreading

Explains the differences between a component with one thread of execution and a component with multithreading. Furthermore, it explains how both types of execution work using serialization, and its importance.

Related Sections

Server Design Considerations and Limitations

Describes certain behaviors, processes, and limitations that can determine the effectiveness of your server application.
Controlling Visual FoxPro from Other Applications

Discusses how you can control Visual FoxPro from other applications by using the Visual FoxPro Application object. Applications that support Automation can create instances of Visual FoxPro, run Visual FoxPro commands, and access Visual FoxPro objects.
Sharing Information and Adding OLE

Explains how you can use Visual FoxPro to share information with other applications.


Automation Servers in Visual FoxPro

Visual FoxPro 9.0
Automation Servers in Visual FoxPro
See Also

You can create, build, distribute, and access Automation servers in Visual FoxPro.

Creating Automation Servers

You can create Automation servers as OLE public user-defined classes in program (.prg) files or visual class library (.vcx) files. You can have as many OLE public classes as you want in an application project.

Building Automation Servers

After you create an Automation server, you can build it as an out-of-process or an in-process component. An out-of-process component is an executable (.exe) file that runs in its own process. An in-process component is a dynamic-link library (.dll) file that runs in the same process address space as the client that calls it. Communication between a client application and an out-of-process server is called cross-process communication.

When you build an Automation server as an executable (.exe) file, you do not lose any functionality of normal executable files. You can run the executable file, provide a user interface, and any other functionality available for an application. In addition, you increase the extensibility of your application by making it possible for other applications use the functionality you provide in the Automation server.

When building Automation servers, consider the following:

  • In-process servers can be faster because there is no inter-process communication overhead.

  • Out-of-process servers can be deployed remotely while in-process servers cannot.

  • An in-process server and the client share a process address space; therefore, any serious error in the in-process server terminates the client. Errors in an out-of-process server terminates only the server.

Building an Automation server creates three files:

  • An .exe or .dll file.

  • A type library (.tlb) file.

    The type library file is a binary file that lists all the published classes in your Automation server, along with their properties, methods, and events. OLE object browsers read this information and present it in a readable interface. For more information, see Binding Type Libraries.

  • A registry (.vbr) file

    The registry file lists the global unique IDs (GUID) for the classes in your server.

    Note:
    A .vbr registry file is the same as a .reg registry file except that the .vbr file does not include hard-coded paths.

Distributing Visual FoxPro Automation Servers

When you distribute an Automation server (.dll), you must include the following files:

  • VFPVersionNumberR.dll or VFPVersionNumberT.dll, where VersionNumber represents the version number of this release of Visual FoxPro.

  • VFPVersionNumberRENU.dll

  • GDIPlus.dll

  • MSVCR70.dll

If you are distributing an Automation server as an executable (.exe) file, see Preparation for Distributing Applications. For more information about run-time libraries, see VFP9R.DLL Run-Time Library and VFP9T.DLL Run-Time Library.

Accessing Visual FoxPro Automation Servers

Any application that can create Automation objects can create objects based on your Automation server, set properties that are not HIDDEN or PROTECTED, and call methods. For example, assuming that your server is named foxole and contains a class named person with a GetName method, the following code could be run in Visual FoxPro:

Copy Code
oTest = CREATEOBJECT("foxole.person")
cName = oTest.GetName()

Similar code could be run in Microsoft Excel or Visual Basic:

Copy Code
Set oTest = CreateObject("foxole.person")
cName$ = oTest.GetName()

Handling Errors in Visual FoxPro Automation Servers

The only interaction with the objects provided by an Automation server is through the methods and properties of the exposed classes. When a client application calls a method of an object, and an error occurs in the Automation server, the method either returns an error value or raises an error in the client application.

The client application decides whether to alert the user or proceed with another execution path. The Automation server itself never interacts with the user. This allows the location of the Automation server to be transparent to the client application. The Automation server can be local, running on the user's computer, or you can use the Remote Automation feature of Visual FoxPro to run it on a network server.

When a Visual FoxPro Automation server generates an error, the Automation server sets the COM ErrorInfo object using IErrorInfo and cancels out of the current method. The Automation client can either release the Visual FoxPro Automation server or, if the client has access to the COM ErrorInfo object, handle the exception based on that information. For more information, see _ErrorInfo( ) API Library Routine.

The COMRETURNERROR( ) function handles errors that occur on an Automation server. You can use COMRETURNERROR( ) in the Error method, to populate the COM exception structure with information that Automation clients can use to determine the source of Automation server errors. For more information, see COMRETURNERROR( ) Function.

See Also

Other Resources

How to: Create Automation Servers
Working with Automation Servers


How to: Create Automation Servers

Visual FoxPro 9.0
How to: Create Automation Servers
See Also

You can create Automation servers in an application project by creating an OLE public class user-defined class in a program (.prg) file or visual class library (.vcx) file.

For examples of Automation servers, see the Visual FoxPro ..\Samples\Servers directory.

To create an Automation server

  1. Create the class in the Class Designer as a Custom class.

  2. On the Class menu, click Class Info.

  3. In the Class Info dialog box, click OLE Public.

For more information, see How to: Create Classes and Subclasses.

To create an Automation server programmatically

  • Create the class using the DEFINE CLASS command and include the OLEPUBLIC keyword with the AS clause.

For example, the following code in a class definition in a program file creates a custom OLE public class:

Copy Code
DEFINE CLASS person AS CUSTOM OLEPUBLIC
   FirstName = SPACE(30)
   LastName = SPACE(45)

   PROCEDURE GetName
      RETURN THIS.FirstName + " " + THIS.LastName
   ENDPROC
ENDDEFINE

See Also

Other Resources

Automation Server Programming Notes
How to: Build Automation Servers
Working with Automation Servers


Automation Server Programming Notes

Visual FoxPro 9.0
Automation Server Programming Notes
See Also

To find additional information on writing automation servers, see the topics for the following areas.

Application Objects

An Application object is not exposed in an Automation server type library, therefore you cannot access the Application object DoCmd and Eval methods. However, you can expose the Application object by creating a custom property and setting its value to the Application object, or you can provide a method that accesses the Application object.

Note:
Read/write properties of the Application object, such as AutoYield, are global to the project. Therefore, make sure multithreaded servers do not assume that the values of these settings are protected across threads.

For more information, see Application Object.

Automation Server Samples

This version of Visual FoxPro includes two sample ISAPI Automation servers, FoxWeb and FoxIS. These samples manage the return of selected Visual FoxPro records as HTML to an Internet browser. For more information about these samples, see FoxISAPI Automation Server Samples.

Note:
FoxISAPI included in Visual FoxPro includes improvements designed specifically for use with new multithreaded DLL Servers. DLL Servers that are run through FoxISAPI should not use the built-in Pool Manager.

Configuration Files

In Visual FoxPro, only configuration files, Config.fpw, bound inside EXE or DLL servers will be used during run-time initialization. The configuration file stores critical settings that are set at the time Visual FoxPro starts up, both at product and run time. Prior to Visual FoxPro 6.0, the Config.fpw file could exist as a separate file or bound into the application (.app, .exe or .dll). If a Config.fpw file is found bound within an application, it is used. Otherwise, Visual FoxPro searches along normal paths for a separate Config.fpw file.

You will still get full functionality with normal distributed .app and .exe applications.

For more information, see How to: Set Configuration Options at Startup.

Codepage Handling

Codepages are supported in all servers and are specific to a particular project (.dll). You can set the default codepage in the Config.fpw file; however, it is set only at run-time initialization. The codepage is global across all projects. Also, all objects using a particular instance of the run time share the same codepage.

Each server has its own Config.fpw with a different codepage setting. Visual FoxPro prevents changing this setting once the run time has been launched because multiple .dll servers can potentially change the default codepage for a run time. Therefore, once a codepage is set, it is permanent until the run time is released.

Tip:
Users who need servers with each having a unique codepage can place those servers, along with a copy of the VFP9T.dll run-time library, in a unique folder. A server will always default to using a run-time library stored in its folder. For more information, see VFP9T.DLL Run-Time Library.

Special Language Considerations

When working with automation servers, be aware of the functionality for following commands because their behavior differs slightly from normal product operations:

  • SET PROCEDURE command

    This command is unique to each individual thread because it is stored in thread local storage. However, Visual FoxPro implicitly performs a SET PROCEDURE to the entire server by default when you instantiate an .exe or .dll COM server.

    For example:

    Copy Code
    ? SET("PROCEDURE")
C:\VFP\MYSERVER.DLL
    This makes it possible for you to access any procedure stored in the server. If an existing object on the thread calls SET PROCEDURE, the procedure path is reset to nothing. However, a new object created on the same thread will automatically reset the procedure path to the entire server once again.

  • SET CLASS command

    This command works similarly to SET PROCEDURE. Its value is held in thread local storage; however, it is initialized to the entire set of class libraries in your .exe or .dll server.

    For example:

    Copy Code
    ? SET("CLASS")
C:\VFP\myClass.VCX ALIA
  • CD, CHDIR, and SET DEFAULT commands

    These commands change the default directory of the entire process, so they affect all threads that are part of the process. Instead of using CD, CHDIR, and SET DEFAULT, use the SET PATH command.

See Also

Other Resources

Working with Automation Servers
How to: Create Automation Servers
Selecting a Run-Time Library


How to: Build Automation Servers

Visual FoxPro 9.0
How to: Build Automation Servers
See Also

You can build an Automation server as an executable (.exe) file or as a dynamically-linked library (.dll) file.

Note:
Automation servers are invoked through class instantiation; therefore, you can build an Automation server without first specifying a main file in the Project Manager.

For information about building applications, see How to: Build Applications.

To build an Automation server (.dll)

  1. Open the project for your application.

  2. In the Project Manager, click Build.

  3. In the Build Options dialog box, click Single-threaded COM server (dll) or Multi-threaded COM server (dll).

  4. Select any other options you want and click OK.

    Tip:
    You can view and save build messages that occur during the build process. For more information, see How to: View and Save Build Messages.

  5. In the Save As dialog box, specify a name for the file, then save the file.

For more information, see Project Manager and Build Options Dialog Box.

To build an Automation server programmatically

  • Use the BUILD EXE, BUILD DLL, or BUILD MTDLL command.

For more information, see BUILD EXE Command, BUILD DLL Command, and BUILD MTDLL Command.
Note:
You must include certain dynamic-link (.dll) libraries when distributing your Automation server. For more information, see Automation Servers in Visual FoxPro.

After you build the Automation server, the server classes are listed in the Project Information dialog box. You can also specify a help file and a Help context ID for each class. This help file can be opened from most generic object browsers. You can choose class-specific instancing values in the Project Information dialog box. For more information, see Servers Tab, Project Information Dialog Box.

Tip:
For changed settings in the Servers tab to take effect, rebuild the .dll or .exe.

See Also

Other Resources

How to: Create Automation Servers
How to: Register Automation Servers
Working with Automation Servers


How to: Register Automation Servers

Visual FoxPro 9.0
How to: Register Automation Servers
See Also

You can make your Automation server available to other applications after you add the server to the Windows registry. When you build an Automation server, it is registered automatically on the computer that you build it on. When you use the Visual FoxPro Setup program to create setup disks, the setup program registers your server on the computer it is set up on. However, you can also manually register servers.

Note:
The registry contains the full path name to the file, so if you move the file, you need to register it again.

To register an .exe component

  • Run the .exe file with the /regserver switch.

    For example, to register Myserver.exe, run the following command:

    Copy Code
    myserver /regserver

To remove an .exe component registry entry

  • Run the .exe file with the /unregserver switch.

    For example, to unregister Myserver.exe, run the following command:

    Copy Code
    myserver /unregserver

To register a .dll component

  • Run REGSVR32 with the name of the server.

    For example, to register Myserver.dll run the following command:

    Copy Code
    REGSVR32 myserver.dll

To remove a .dll component registry entry

  • Run REGSVR32 with the name of the server and the /u switch.

    For example, to register Myserver.dll run the following command:

    Copy Code
    REGSVR32 /u myserver.dll

See Also

Other Resources

Working with Automation Servers


Binding Type Libraries

Visual FoxPro 9.0
Binding Type Libraries
See Also

Visual FoxPro supports intrinsic (Visual FoxPro) properties, events, and methods in an Automation server type library. Only properties whose visibility is set as PUBLIC are included in the type library.

Both custom user-defined properties, and user-defined methods appear in Visual FoxPro type libraries as long as they are marked PUBLIC. For methods, Visual FoxPro also includes a return value type (variant) and a list of parameters (variants) parsed from the original method definition. Property descriptions from .vcx class files will also appear in the type library.

Type libraries generated by the Build process are stored in .tlb files created along with the .dll or .exe server. The type libraries are also included in the .dll or .exe file as a bound resource. This eliminates the need to ship the extra .tlb file, although it is still built, along with the .vbr file, for use with remote deployment.

Note:
The Visual FoxPro Release method isn't included in the type library because it already exists as a COM method.

See Also

Other Resources

Working with Automation Servers
Interoperability and the Internet
Passing Arrays to Automation Servers


Early (vtable) and Late (IDispatch) Binding

Visual FoxPro 9.0
Early (vtable) and Late (IDispatch) Binding
See Also

Visual FoxPro COM servers support both early (vtable) binding and the existing late binding (IDispatch) interface (together known as dual-interface support). Binding describes how clients access properties and methods of a server. Early binding provides performance benefits for Automation controllers that support early binding such as Visual Basic and the Microsoft Transaction Server. While Visual FoxPro servers support both interfaces, the one used is determined by the client.

Early Binding

If your client can detect at compile time what object a property or method belongs to, it can resolve the reference to the object at compile time. The compiled executable contains only the code to invoke the object's properties, methods, and events. This is called early binding.

Example: Visual FoxPro client

Copy Code
LOCAL xlApp1 As Excel.Application
xlApp1 = CreateObjectEx("Excel.Application","","")

Example: Visual Basic client

Copy Code
Dim xlApp1 As Excel.Application
Set xlApp1 = New Excel.Application

Early binding dramatically reduces the time required to set or retrieve a property value, because the call overhead can be a significant part of the total time. For method calls, the improvement depends on the amount of work the method performs. Short methods, where the call overhead is comparable to the time required to complete the task, benefit the most.

Late Binding

Although late binding is the slowest way to invoke the properties and methods of an object, there are times when it is necessary. For example, in Visual Basic you can write a function that uses an object variable to act on any of several different classes of objects. Because you do not know in advance what class of object will be assigned to the variable, you must declare it as a late-bound variable using the Visual Basic DIM As Object command. In Visual FoxPro, you would use the CREATEOBJECT() function rather than the CREATEOBJECTEX() function.

Example: Visual FoxPro client

Copy Code
LOCAL xlApp2 As Excel.Application
xlApp2 = CreateObject("Excel.Application")

Example: Visual Basic client

Copy Code
Dim xlApp2 As Object
Set xlApp2 = CreateObject("Excel.Application")

Method calls to objects created this way may run slower than calls to early-bound object methods because the client must include code in the compiled executable that will determine at run time whether or not the server has a particular method.

See Also

Other Resources

Working with Automation Servers
Compiling Source Code
Scalability and Multithreading
Interoperability and the Internet
Visual FoxPro Run-Time Libraries


Passing Arrays to Automation Servers

Visual FoxPro 9.0
Passing Arrays to Automation Servers
See Also

Earlier versions of Visual FoxPro passed arrays to COM objects, such as Automation servers created in Visual FoxPro, Visual Basic, or Visual C++, by value. That is, the array elements remained unchanged after a method call, and the COM object changes did not propagate to the elements on the client. This restriction prevented passing large amounts of data between Visual FoxPro and COM objects.

By default, an array that passes to a COM object is assumed to be a one-based array, meaning that the first array element, row, or column is referenced with 1, for example, MyArray[1], and is passed by value. However, some COM objects require that the array pass as a zero-based array, meaning the first array element, row, or column is referenced with 0, for example, MyArray[0], and by reference.

You can specify how to pass an array to an Automation server using the COMARRAY( ) function. For more information, see COMARRAY( ) Function.

See Also

Other Resources

Working with Automation Servers
Interoperability and the Internet
Compiling Source Code


Compiling Source Code

Visual FoxPro 9.0
Compiling Source Code
See Also

In Visual FoxPro, you can compile Visual FoxPro source code into run-time files created with VFP9R.dll or VFP9T.dll. For more information about run-time files, see Visual FoxPro Run-Time Libraries.

Note:
Earlier versions of Visual FoxPro required using macro substitution or expression evaluation for each line to execute code generated at run time. This process was not always optimal because of the complexities of executing large blocks of code and the performance penalty incurred using the macro operator &, or the EVALUATE( ) function.

The COMPILE command is available in the runtime so that your applications can generate and compile a program (.prg) file. Run-time compilation works with all files supported by the COMPILE command including programs, forms, classes, labels, reports and databases. You can use the STRTOFILE( ) function to output your code to a .prg file.

There are a few differences between the compiler in the development product and in the runtime:

  • The "?" switch in the COMPILE command is unavailable for the runtime because unattended automation servers (.dlls) do not allow modes involving user input.

  • The SET DEVELOPMENT command has no effect in the runtime.

    With the full product, SET DEVELOPMENT causes Visual FoxPro to compare the creation date and time of a program with those of its compiled object file when the program is run. If SET DEVELOPMENT is set to ON, the latest version is always executed – out-of-date programs are automatically recompiled. In the runtime, you must explicitly call the COMPILE command to recompile source. This means that calling the DO command in your runtime will never cause the .prg file to be recompiled. Also, with the runtime, the DO command ignores the file extension and looks for a file with an .fxp extension, even if you specify a .prg file.

See Also

Other Resources

Working with Automation Servers
Early (vtable) and Late (IDispatch) Binding
Interoperability and the Internet
Scalability and Multithreading


Scalability and Multithreading

Visual FoxPro 9.0
Scalability and Multithreading
See Also

When a component has one thread of execution, code for only one object can execute at any given time. The Automation feature of the Component Object Model (COM) deals with this situation by serializing requests. That is, the requests are queued and processed one at a time until all have been completed.

In a multithreading operating environment, serialization protects single-threaded objects from overlapping client requests — that is, from code in a property or method being executed while one or more previous client requests are still being run. Overlapping requests can cause internal data errors if objects aren't designed for reentrancy.

Serialization is thus an extremely important feature of Automation. However, serialization of single-threaded components means that requests are sometimes blocked. For example, suppose you're using a Widget object that has two methods, spin and flip.

  • The Spin method takes anywhere from several seconds to half an hour to complete.

  • The Flip method is almost instantaneous.

Because 32-bit applications are preemptively multitasked, a second application could call the Flip method while the Spin method is already running. The short Flip method is blocked until the long Spin method is complete.

When short operations are blocked by long ones, productivity suffers and user frustration rises. Components that behave in this fashion are said to scale poorly. That is, they work poorly if many requests of mixed length are made.

Visual FoxPro provides two component features to address scalability and avoid blocked calls — SingleUse instancing and multithreaded objects. For details, see Controlling Call Blocking.

See Also

Other Resources

Working with Automation Servers
Early (vtable) and Late (IDispatch) Binding
Visual FoxPro Run-Time Libraries
Interoperability and the Internet
Compiling Source Code


Visual FoxPro Run-Time Libraries

Visual FoxPro 9.0
Visual FoxPro Run-Time Libraries
See Also

Visual FoxPro includes two run-time libraries for you to distribute with your applications:

  • VFPVersionNumberR.dll

  • VFPVersionNumberT.dll

VersionNumber indicates the version number of Visual FoxPro that you use to develop your applications. These run-time libraries are located in the ..\Program Files\Common Files\Microsoft Shared\VFP directory.

VFPVersionNumberR.dll is the typical run-time library for most application types. VFPVersionNumberT.dll is a special multithreaded run time for highly scalable in-process server applications such as those created for use with Microsoft Transaction Server. Both run-time libraries share the resource file, VFPVersionNumberRENU.dll. For more information, see VFP9R.DLL Run-Time Library and VFP9T.DLL Run-Time Library.

When you build your application from the Project Manager, the build action you choose determines which run-time library the generated application or server uses. Only Automation servers (.dll) can use the VFPVersionNumberT.dll run-time library. The Build method for Project objects also makes it possible for you to choose which run-time library to use. For more information, see How to: Build Automation Servers, How to: Build Applications, and Build Method.

Note:
The compiled source file, for example, an executable (.exe) or an Automation server is marked internally to identify which run-time library to use when called. The only way to change the run-time library an Automation server uses is by rebuilding it. Your server can determine at run time which run-time library it is using through the read-only ApplicationStartMode property. You need to know which run-time library is associated with your Automation server so that you can choose the right run time to include in the setup. For more information, see Automation and COM Servers.

See Also

Other Resources

Scalability and Multithreading
Interoperability and the Internet
Server Design Considerations and Limitations


VFP9R.DLL Run-Time Library

Visual FoxPro 9.0
VFP9R.DLL Run-Time Library
See Also

The Visual FoxPro run-time library VFP9R.dll is the main run-time library used by most Visual FoxPro applications and provides services for the following Visual FoxPro application types:

  • Distributed application (.exe) files

  • Out-of-process Automation server (.exe) files

  • In-process Automation server (.dll) files

This run-time library is located in the ..\Program Files\Common Files\Microsoft Shared\VFP directory.

The main Visual FoxPro run-time library is not shared by all the multiple in-process Automation servers (.dll). Instead, each in-process Automation server uses a separate instance of the main Visual FoxPro run-time library. The following rules determine how in-process Automation servers use the main Visual FoxPro run-time library:

  • The in-process .dll file that is called first has exclusive use of the main Visual FoxPro run-time library.

    If an in-process .dll file already has exclusive use of the main Visual FoxPro run-time library, a renamed copy of the main Visual FoxPro run-time library is created on disk and loaded into memory for each in-process .dll called. The main Visual FoxPro run-time library is assigned a name based on the name of the in-process .dll.

    For example, suppose you call an in-process .dll named MyServer.dll. A copy of the Visual FoxPro run-time library is renamed to MyServerR.dll and is loaded into memory to service the in-process .dll. This can also occur with a Visual FoxPro .exe server creating an instance of a .dll server, a situation where both share the same run-time library from the same process.

  • Visual FoxPro run-time libraries are renamed only for in-process .dlls that run within the same process.

    This means that two separate clients, each running in their own process, can load two different Visual FoxPro in-process .dll files without the run time being renamed. In this case, both Visual FoxPro in-process .dll files use the main Visual FoxPro run-time library because the clients load in separate processes.

  • Multiple Automation servers, created with OLEPUBLIC clause in the DEFINE CLASS command, in a single in-process .dll share the same main Visual FoxPro run-time library.

    In this case, it's possible that the Automation servers can affect each other by sharing PUBLIC memory variables, setting the same SET commands, and so on if they reside on a common thread. Be careful that multiple Automation servers in a single in-process .dll don't interfere with each other. The new Session class can help eliminate some of these conflicts. Using the Visual FoxPro multithreaded run-time library, VFP9T.dll, avoids these conflicts because objects created on separate threads will use their own separate memory space (thread-local storage).

You can use the main Visual FoxPro run-time library with in-process .dll servers. Because there are limitations in using the main Visual FoxPro run-time library, you should consider using the multithreaded Visual FoxPro run-time library, VFPVersionNumberT.dll instead. The main Visual FoxPro run-time library does not fully protect instance data and global values; therefore the library blocks multiple objects from executing code concurrently. If one of the objects is executing code, all other instances must queue up to execute code. When the object executing code finishes, another object can enter the run time to begin its execution, whether it is a property assignment or method invocation. While this might not be ideal in many application scenarios, there are certain types of server applications where this may be the optimal approach.

If in-process .dll servers are deployed in a Component Services (or Microsoft Transaction Server) package, creating an instance of the server will load the .dll into the memory space of a Component Services process rather than the calling process. Moreover, multiple-process .exe files can instantiate Visual FoxPro .dll servers that will be loaded into a single Component Services process. Component Services generates or reuses a thread for each client requesting an instance (OLEPUBLIC) from a Visual FoxPro server. Since such applications often require enterprise scalability, there is the potential for many concurrent instances to access your Visual FoxPro server simultaneously. If only one client (instance) is allowed to execute code at a time, all others must wait. With a single processor machine, this may be fine, depending on the nature and execution times of methods in your server. Remember, a single processor can only run one line of code at a time.

Tip:
You should always consider using the multithreaded Visual FoxPro runtime library for multiple processor machines since each processor can simultaneously execute code for different objects. Since the main Visual FoxPro run-time library blocking behavior prevents simultaneous code execution, you should use the multithreaded Visual FoxPro run-time library for most situations.

See Also

Other Resources

Visual FoxPro Run-Time Libraries
Interoperability and the Internet
Server Design Considerations and Limitations
Scalability and Multithreading


VFP9T.DLL Run-Time Library

Visual FoxPro 9.0
VFP9T.DLL Run-Time Library
See Also

The multithreaded Visual FoxPro run-time library, VFP9T.dll, helps eliminate the blocking issues associated with the Visual FoxPro run-time library, VFP9R.dll. With the multithreaded Visual FoxPro run-time library, you can deploy in-process servers without blocking of code execution. This run-time library is located in the ..\Program Files\Common Files\Microsoft Shared\VFP directory.

Because the multithreaded Visual FoxPro run-time library is a lightweight run-time library designed only for in-process servers, many commands and functions related to visual and user input features have been disabled.

Because no blocking occurs in the multithreaded Visual FoxPro run-time library, an object executing an unusually long procedure, such as printing out a report, won't prevent other objects from executing quick rapid routines. For example, with the Visual FoxPro run-time library, an object that executes a 1 second database query routine may have to wait 15 minutes for an object printing a long, complex report. If you build with the multithreaded Visual FoxPro run-time library, you won't have the same bottleneck.

In addition to addressing blocking issues, implementing Apartment-model threading in the multithreaded Visual FoxPro run-time library also eliminates conflicts in accessing global data from multiple threads by giving each apartment its own copy of global data. The multithreaded Visual FoxPro run-time library uses thread local storage to give each class instance its own set of data. This means that a variable you declare PUBLIC is global only to the thread; each thread has an instance of the variable.

Note:
Read/write properties of the Application object such as AutoYield are global to the project.

Visual FoxPro makes it possible for the same multithreaded Visual FoxPro run-time library to be deployed with multiple, concurrently called in-process .dll automation servers whether they are in same process/thread or not. The original Visual FoxPro run-time library creates a renamed copy of the library for each in-process .dll server running in the same process.

Visual FoxPro offers a Session Class, which you should use for OLEPUBLIC server classes. As with forms, the DataSession property makes it possible for you to create a private data session for your object upon instantiation. The advantage of the Session class is that it uses much less memory than a form. The multithreaded Visual FoxPro run-time library automatically protects globals and user data through thread local storage, but this only applies between apartments (threads). Objects on the same thread instantiated from the same .dll are able to access each other's data. The Session class aids in data protection within the thread.

Since the multithreaded Visual FoxPro run-time library is designed for use only with in-process servers, it has been scaled down in size. Many user interface commands and functions have been eliminated including older FoxPro 2.x READ and @...Get/Say support. In addition, some of the designers such as Table Designer and Report Designer, which exist in the main Visual FoxPro run-time library, have also been removed. The multithreaded Visual FoxPro run-time library still supports visual classes such as forms.

See Also

Other Resources

VFP9R.DLL Run-Time Library
Server Design Considerations and Limitations
Interoperability and the Internet
Visual FoxPro Run-Time Libraries
Selecting Process Types


Server Design Considerations and Limitations

Visual FoxPro 9.0
Server Design Considerations and Limitations

There are many critical issues to consider in server design. Certain behaviors, processes, and limitations can determine the effectiveness of your server application.

In This Section

Selecting Process Types

Discusses the different services provided by in-process and out-of-process servers, and what effect they have on the user interface of your application.
Controlling Call Blocking

Describes how SingleUse Objects and Apartment-model threading can be used to control issues of call blocking and enhance the scalability of your applications.
Selecting a Run-time Library

Provides information on using Visual FoxPro API calls, scalability issues, reentrancy, and resource contention.
Language Supported in Run-Time Libraries

Discusses Visual FoxPro commands, functions, and system variables that are not supported in the multithreaded Visual FoxPro run-time library.

Related Sections

VFP9T.DLL Run-Time Library

Discusses this multithreaded run time that helps eliminate the blocking issues associated with the main Visual FoxPro run-time library.
Automation and COM Servers

Describes how to you can extend the functionality of your Visual FoxPro applications without a lot of extra coding time by using Automation and COM Servers.
Automation Server Programming Notes

Describes where you can find additional information on writing automation servers.
Interoperability and the Internet

Provides links to information on how you can move data between Visual FoxPro and other applications as well as within Visual FoxPro applications.


Selecting Process Types

Visual FoxPro 9.0
Selecting Process Types
See Also

In-Process and out-of-process servers provide differing services, especially regarding the user interface of your application.

User Interfaces

Although earlier versions of Visual FoxPro make it possible for you to use forms as output-only elements in an Automation server application, the two run-time libraries in Visual FoxPro handle this situation differently for out-of-process and for in-process servers.

In-Process Servers

Apartment-model threading support requires that in-process .dll Automation servers not have user interfaces. In Visual FoxPro 5.0, it was possible (though not recommended) to create an in-process .dll Automation server that had a user interface such as a form. You could use the form only for display because the form events were not supported. Since Visual FoxPro 6, if you attempt to create a user interface in an in-process .dll, Automation generates an error. This is referred to as unattended mode.

Out-of-Process Servers

An out-of-process (.exe) Automation server can have a user interface. The Visual FoxPro function SYS(2335) enables you to disable UI and modal events for an out-of-process .exe Automation server so they can be handled remotely without user intervention. Modal events are created by user-defined modal forms, system dialogs, the MESSAGEBOX( ) function and the WAIT command, and so on and normally require user input.

See Also

Other Resources

Server Design Considerations and Limitations
Controlling Call Blocking
Selecting a Run-Time Library
Language Supported in Run-Time Libraries
Automation Server Programming Notes


Controlling Call Blocking

Visual FoxPro 9.0
Controlling Call Blocking
See Also

To enhance the scalability of your applications, Visual FoxPro provides SingleUse Objects and Apartment-model threading as ways of controlling issues of call blocking.

SingleUse Objects

You can cause each instance of an OLEPUBLIC class to run in a separate instance of your component by setting the Instancing property of the OLEPUBLIC class to SingleUse in the Project Info dialog box. This means that even though your component is single-threaded, each instance of the SingleUse class has its own thread of execution. The behavior of SingleUse objects differs between .exe and .dll servers.

SingleUse Objects in EXE Servers

With the Instancing property set to SingleUse, each instance causes a new EXE process to begin. On Windows 2000 or later, you will see each running process in the Task Manager. With the MultiUse setting, the first instance will cause a new process to start, but each new object instance shares the same process as the first.

SingleUse Objects in DLL Servers

The Instancing property is ignored for multithreaded .dlls and is only read for the VFP9R.dll run-time library. Servers built for use with the VFPVersionNumberT.dll run-time library, with VersionNumber representing the version number for this release, are always MultiUse regardless of their setting. In general, you should always set the Instancing property to MultiUse for VFPVersionNumberR.dll in-process servers. If you set it to SingleUse, only one instance of an object from that server can be created. You will get an error if you try to instantiate more objects.

Only under rare circumstances would you want to use the SingleUse setting. In fact, Microsoft Transaction Server components require the MultiUse setting. SingleUse objects often require more memory overhead than multiple objects in a multithreaded component. There are reasons, however, for which you might want to use SingleUse objects. For example, you can isolate high-risk activities in separate processes with SingleUse objects. If the object suffers a fatal error, other processes are not affected. By contrast, a fatal error in a multithreaded component terminates all threads.

Apartment-Model Threading

Visual FoxPro Automation servers now support Apartment-model threading. The Microsoft Transaction Server utilizes servers marked as apartment-threaded and offers better thread protection and scalability through serialization and marshaling.

In Visual FoxPro, apartment-model threading provides thread safety. In apartment-model threading, each thread is like an apartment — all objects created on the thread live in this apartment, and are unaware of objects in other apartments. Each Apartment-model object (such as a Visual FoxPro Automation server) may only be entered by one thread, the thread that created the object. However, an object server (such as Microsoft Transaction Server) can support multiple objects, each being entered simultaneously by different threads. Common data held by the object server must be protected against thread collisions.

Apartment-model threading provides the following benefits:

  • All of the objects a client creates on a given thread are created in the same apartment (thread) in the DLL. Calls on the same thread to these objects do not require cross-thread marshaling, making them more efficient.

  • Because an object is only accessed on the thread on which it was created, calls are serialized so that a call is never interrupted by a call from another thread.

  • Arguments for cross-thread calls are marshaled, and the calling thread is blocked. This synchronization of data protects the calling thread's state.

Apartment-threaded DLLs cannot create their own threads; the first time a client thread requests an object provided by your DLL, a new apartment is created, and the object Init event runs for that apartment. All single threaded client objects requested by that client will reside in the same apartment, and will share global data. Any PRIVATE objects (including forms) that are created by the public objects will also reside in the apartment.

Though Visual FoxPro does not provide a way for apartments to access each other, a multithreaded client could obtain a reference to an object on Thread A, and pass that reference to an object on Thread B.

For more information about Apartment-model threading, search on "Apartment-Model Threading" in the MSDN library.

The Visual FoxPro implementation of Apartment-model threading eliminates conflicts in accessing global data from multiple threads by giving each apartment its own copy of global data. This means that all objects created on the thread exist in this apartment, and are unaware of objects in other apartments.

Visual FoxPro uses thread local storage to store a unique set of application and environment global data for each thread (apartment). This means that two instances of the same class created on different threads cannot access each other's data. However, if these same two instances reside on the same thread, each object can access the other's data. This could cause timing issues for your applications. In fact, as long as two objects on the same thread are created from OLEPUBLIC classes in the same .dll server, data from those objects is common between them (Note: You can use the Session class to give each object a unique private datasession.)

In addition to thread local storage, Visual FoxPro also provides each project (.dll) a unique set of globals data. Objects created from different projects (.dll servers) cannot access each other's globals, even if the two objects reside on the same thread.

See Also

Other Resources

Server Design Considerations and Limitations
Selecting Process Types
Selecting a Run-Time Library
Interoperability and the Internet
Language Supported in Run-Time Libraries
Automation Server Programming Notes


Selecting a Run-Time Library

Visual FoxPro 9.0
Selecting a Run-Time Library
See Also

You might have an application need, such as an Internet Server Application in the FoxIsap server sample, where you want to instantiate a form to use in mapping to equivalent HTML. The impact of eliminating a number of non-critical features by using the multithreaded Visual FoxPro run-time library will improve overall performance of your multithreaded server applications.

A common misconception about server choice is that an application will automatically scale well just by building the .dll to use the new run time. You can often do this, but you should also consider issues involving use of Visual FoxPro API calls, scalability, reentrancy, and resource contention.

Using Visual FoxPro API Calls

When using Visual FoxPro FLL or standard Windows DLL libraries that make Visual FoxPro API calls, there are some issues you need to be aware of when designing your servers. The Visual FoxPro API does not readily determine to which project (.dll) a particular call belongs. So, there is a potential, although rare, for an API call to be made against the wrong project (.dll - thread local storage). This may occur if your FLL/DLL library creates an instance from a different Visual FoxPro .dll server before making its API call. There are several possible solutions if your server should experience this problem:

  • Create a separate copy of the multithreaded Visual FoxPro run-time library file, and place the copy in the same folder as your .dll server. The server will always search first in your server folder before attempting to locate files in the Windows System folder or folder of your client process. By having its own run-time library servicing it, a server will not experience potential conflicts from other .dlls (assuming these other .dlls are not in the same folder). Since this behavior (automatic copying/renaming of run time) occurs by default with the main Visual FoxPro run time, the above API issues only manifest themselves in the mulithreaded Visual FoxPro run-time library.

  • Limit your application to a single .dll server. If you are using several .dll servers (projects), there may be potential for API conflicts. Remember that a project can contain many OLEPUBLICs, so you don't need to have a separate project for each OLEPUBLIC. Be aware that on shared computer servers, its possible that people may install other Visual FoxPro COM servers, which could potentially conflict with yours if running concurrently.

Scalability Issues

The multithreaded run time in Visual FoxPro allows for very scalable Visual FoxPro in-process servers. Though scalability of your servers will be handled automatically by the run time, certain tight code loops may not allow thread switching to occur as frequently. For example, a very tight DO WHILE loop may cause this. If you experience scalability problems, you can include code such as the following example which forces the processor to switch threads:

Copy Code
DECLARE Sleep IN Win32API INTEGER
SLEEP(0)

Though you can use multithreading on a single-processor machine, consider that this may not provide quite the results you expect. For example, on a single-processor machine, multithreading results in a perceived performance improvement only with a mix of long and short tasks. Multithreaded method calls, as described in this example, may appear to be slower.

In the example, method A and method B are called at the same time. In a single-threaded component, the requests are serialized, so that B doesn't begin until A has finished. With multithreading, the two active threads duel for the processor's attention.

Not only does the perceived average completion time increase, but more processor time is spent switching between threads.

The problem is that method A and method B take about the same amount of time.

For example, if method B required only three time slices to complete, the user of the system would perceive a huge improvement in the responsiveness of method B — and only a slight degradation in the time required to execute method A.

The scenarios in which multithreading shows to best advantage are those in which most threads spend a substantial percentage of the time blocked — for example, waiting for file I/O — so that other threads can be executing code at any given time.

If you are considering an application on a single-processor machine with characteristics that provide minimal thread blocking, you may want to consider using the main Visual FoxPro run-time library. On multiprocessor machines and in most other applications, you should consider using the multithreaded Visual FoxPro run-time library for .dll servers.

Reentrancy

In the apartment model, reentrancy refers to the following sequence of events:

  1. An apartment's thread of execution enters an object's code, because a property or method has been invoked.

  2. While the thread is in the property or method, another thread invokes a property or method of the object, and Automation serializes this request — that is, it queues the request until the thread that owns the object's apartment finishes the member it's currently executing.

  3. Before the thread reaches the end of the member, it executes code that yields control of the processor.

  4. Automation tells the thread to begin executing the serialized request, so that the thread reenters the object's code.

The new request may be for the member the thread was already executing — in which case the thread enters the member a second time — or it may be for another member. If the second member doesn't yield, it will finish processing before the first member. If it changes module-level data the first member was using, the result may be unfortunate.

By serializing property and method calls for each apartment, Automation protects you from reentrancy — unless your code yields control of the processor. Ways in which your code can yield control of the processor include:

  • Calling DoEvents.

  • Invoking the properties or methods of an object on another thread, or in another process. Setting the Application.AutoYield property to false (.F.) will suspend processing of intermittent events between lines of code executing.

  • Invoking a cross-thread or cross-process method from within a method.

Unless you've carefully written all of an object's code so that it doesn't matter whether two members are executing at the same time, you should not include code that yields control of the processor.

Resource Contention

The multithreaded Visual FoxPro run-time library will protect objects from accessing each other's application data. This includes both declared and intrinsic environment globals. Some resources present potential problems of contention, including:

  • Files

  • Registry

  • Data

File I/O presents resource contentions that can be easily handled through code since file management is handled through the operating system. When using a file, your server can open (and lock) a file so that other objects see that the file is in use. A properly written server can handle this scenario by waiting for the file to become available, or otherwise gracefully handle the error. Files can also be opened shared in which case your server should be aware that other objects can potentially change values.

A common scenario is presented with INI files in which different objects can read or write values. The process of reading and then writing a value to an INI file requires two steps. So, there is a potential that the value read by one client is not necessarily the same one it overwrites later if another client alters it first, producing a need for conflict resolution.

As do INI files, the Registry stores settings, which can be accessed by multiple clients. Your applications should use common Windows API routines to access the Registry. Again, your server design should reflect that a potential exists for Registry key values to change between the time the key is read and the time it's written. The Windows API routines work to avoid the necessity for conflict resolution.

Data is a tricky resource to handle. Fortunately, the rich Visual FoxPro language available in the run-times provides all the information and functionality necessary to handle resource contention issues. For more information on handling shared data, see Programming for Shared Access.

See Also

Other Resources

Server Design Considerations and Limitations
Controlling Call Blocking
Language Supported in Run-Time Libraries
Visual FoxPro Run-Time Libraries
Interoperability and the Internet
Automation Server Programming Notes
FoxISAPI Automation Server Samples


Language Supported in Run-Time Libraries

Visual FoxPro 9.0
Language Supported in Run-Time Libraries
See Also

The main Visual FoxPro run-time library, VFPVersionNumberR.dll with VersionNumber representing the version specific to this release, supports the entire language set of objects, commands, and functions, excluding design-time specific language.

To design the multithreaded Visual FoxPro run-time library, VFPVersionNumberT.dll, as a lightweight run-time library for in-process servers, many user-input commands and functions have been removed. All Object syntax is still available, though events from visual classes such as forms are disabled. The following language categories have been removed from the multithreaded Visual FoxPro run-time library:

  • READ, @...Get/Says

  • Menu, Popup, and Bar commands and functions

  • MESSAGEBOX() and WAIT WINDOW

  • User-defined Window commands and functions

Disabled Commands that Generate Run-Time Errors

The following table is a list of unsupported commands, which will generate one of these errors at run time in the multithreaded Visual FoxPro run-time library:

  • Commands: Feature is not available

  • Functions: Function is not implemented

  • System variables: Variable is not found

The following table shows the unsupported commands.

@...BOX | @...CLASS | @...CLEAR
@...EDIT | @...FILL | @...GET
@...MENU | @...PROMPT | @...SAY
@...SCROLL | @...TO | _ALIGNMENT
_ASSIST | _BEAUTIFY | _BOX
_CALCMEM | _CALCVALUE | _CONVERTER
_COVERAGE | _CUROBJ | _DBLCLICK
_DIARYDATE | _FOXDOC | _GALLERY
_GENMENU | _GENPD | _GENSCRN
_GETEXPR | _INCSEEK | _INDENT
_LMARGIN | _PADVANCE | _PBPAGE
_PCOLNO | _PCOPIES | _PDRIVER
_PDSETUP | _PECODE | _PEJECT
_PEPAGE | _PLENGTH | _PLINENO
_PLOFFSET | _PPITCH | _PQUALITY
_PSCODE | _PSPACING | _PWAIT
_RMARGIN | _SCCTEXT | _SPELLCHK
_STARTUP | _TABS | _THROTTLE
_TRANSPORT | _WRAP |
ACCEPT | ACTIVATE MENU | ACTIVATE POPUP
ACTIVATE SCREEN | ACTIVATE WINDOW | AGETCLASS()
AMOUSEOBJ() | ANSITOOEM() | APROCINFO()
ASELOBJ() | ASSERT | ASSIST
BAR() | BARCOUNT() | BARPROMPT()
BROWSE | CALL | CHANGE
CLEAR DEBUG | CLEAR GETS | CLEAR MACROS
CLEAR MENUS | CLEAR POPUPS | CLEAR PROMPT
CLEAR READ | CLOSE DEBUGGER | CLOSE FORMAT
CLOSE MEMO | CNTBAR() | CNTPAD()
COL() | CREATE | CREATE CLASS
CREATE CLASSLIB | CREATE COLOR SET | CREATE FORM
CREATE LABEL | CREATE MENU | CREATE PROJECT
CREATE QUERY | CREATE REPORT | CREATE SCREEN
DEACTIVATE MENU | DEACTIVATE POPUP | DEACTIVATE WINDOW
DEBUG | DEBUGOUT | DEFINE BAR
DEFINE BOX | DEFINE MENU | DEFINE PAD
DEFINE POPUP | DEFINE WINDOW | EDIT
FKLABEL() | FKMAX() | GETBAR()
GETCOLOR() | GETCP() | GETDIR()
GETEXPR() | GETFILE() | GETFONT()
GETPAD() | GETPICT() | GETPRINTER()
HELP | HIDE MENU | HIDE POPUP
HIDE WINDOW | IMESTATUS() | INPUT
KEYBOARD | LOAD | LOCFILE()
MCOL() | MDOWN() | MENU
MENU TO | MENU() | MESSAGEBOX()
MODIFY Commands | MOUSE | MOVE POPUP
MOVE WINDOW | MRKBAR() | MRKPAD()
MROW() | MWINDOW() | OBJNUM()
OBJVAR() | OEMTOANSI() | ON BAR()
ON ESCAPE | ON EXIT Commands | ON KEY
ON KEY LABEL | ON PAD | ON PAGE
ON READERROR | ON SELECTION BAR | ON SELECTION MENU
ON SELECTION PAD | ON SELECTION POPUP | PAD()
PLAY MACRO | POP KEY | POP MENU
POP POPUP | POPUP() | PRMBAR()
PRMPAD() | PROMPT() | PUSH KEY
PUSH MENU | PUSH POPUP | PUTFILE()
RDLEVEL() | READ | READ MENU
READKEY() | RELEASE BAR | RELEASE MENUS
RELEASE PAD | RELEASE POPUPS | RELEASE WINDOWS
RESTORE MACROS | RESTORE SCREEN | RESTORE WINDOW
ROW() | SAVE MACROS | SAVE SCREEN
SAVE WINDOWS | SCROLL | SHOW GET(S)
SHOW MENU | SHOW OBJECT | SHOW POPUP
SHOW WINDOW | SIZE POPUP | SIZE WINDOW
SKPBAR() | SKPPAD() | SUSPEND
VARREAD() | WAIT | WBORDER()
WCHILD() | WCOLS() | WEXIST()
WFONT() | WLAST() | WLCOL()
WLROW() | WMAXIMUM() | WONTOP()
WOUTPUT() | WMINIMUM() | WPARENT()
WREAD() | WROWS() | WTITLE()
WVISIBLE() | ZOOM WINDOW |

Disabled Commands that Generate No Run-Time Errors

The following table is a list of unsupported commands, which do not generate an error when executed at run time in the multithreaded Visual FoxPro run-time library. These functions are disabled for use in the run time; however, because of the frequency of usage in commonly used code and class libraries between different types of applications, they do not cause an error. When one of these commands or functions is encountered in code, Visual FoxPro ignores that line of code and continues executing. This includes certain SET commands and SYS functions.

CD | CHDIR | DOEVENTS
SET ASSERTS | SET BELL | SET BORDER
SET BROWSEME | SET BRSTATUS | SET CONSOLE
SET COLOR | SET CLEAR | SET CLOCK
SET CONFIRM | SET CURSOR | SET CPDIALOG
SET DEBUGOUT | SET DEBUG | SET DEFAULT
SET DEVELOPMENT | SET DELIMITERS | SET DISPLAY
SET DOHISTORY | SET ESCAPE | SET ECHO
SET EVENTLIST | SET EVENTTRACKING | SET FORMAT
SET FUNCTION | SET HELP | SET INTENSITY
SET MARK OF | SET MACDESKTOP | SET MACKEY
SET MARGIN | SET MESSAGE | SET NOTIFY
SET ODOMETER | SET PALETTE | SET PDSETUP
SET READBORDER | SET REFRESH | SET RESOURCE
SET SAFETY | SET SKIP OF | SET STICKY
SET STATUS | SET SYSMENU | SET TALK
SET TRBETWEEN | SET TYPEAHEAD | SET VIEW
SET WINDOW | SYS(1037) | SYS(18)
SYS(103) | SYS(2002) | SYS(1270)
SYS(2017) | SYS(4204) | SYS(2016)

The following table lists the properties and functions that make it easier to manage Automation clients and servers.

Command or property | Description
COMARRAY( ) Function | Specifies how arrays are passed to COM objects.
COMCLASSINFO( ) Function | Returns registry information about a COM object such as a Visual FoxPro Automation server.
COMRETURNERROR( ) Function | Populates the COM exception structure with information that Automation clients can use to determine the source of Automation server errors.
CREATEOBJECTEX( ) Function | Creates an instance of a registered COM object (such as a Visual FoxPro Automation server) on a remote computer. For a Visual FoxPro in-process .dll, you can use Microsoft Transaction Server to create an instance of the .dll on a remote computer.
EVENTHANDLER( ) Function | Binds a COM server event to implemented interface methods in an instantiated Visual FoxPro object.
ProcessID Property | Returns the ID of the Process that created the object.
ServerName Property | Contains the full path and file name for an Automation server. The ServerName property is a property of the Application object.
StartMode Property | Contains a numeric value that indicates how the instance of Visual FoxPro was started.
SYS(2334) – Automation Server Invocation Mode | Returns a value that indicates how a Visual FoxPro automation server method was invoked.
SYS(2335) – Unattended Server Mode | Enables or disables support for modal states in distributable Visual FoxPro .exe Automation servers.
SYS(2336) - Critical Section Support Function | Controls access of critical section in Multithreaded servers.
SYS(2339) - Internal Global Variable Function | Returns current value of internal global variable called g_fCallCoFreeOnRelease.
ThreadID Property | Returns the ID of the thread on which the object was created.

See Also

Other Resources

Server Design Considerations and Limitations
Selecting a Run-Time Library
Automation Server Programming Notes
Interoperability and the Internet
Controlling Call Blocking
Selecting Process Types


Interoperability and the Internet

Visual FoxPro 9.0
Interoperability and the Internet

Visual FoxPro supports OLE drag-and-drop, which makes it possible for you to move data between Visual FoxPro and other applications, as well as within Visual FoxPro applications.

Visual FoxPro also makes it easy to create applications for use with the Internet and other Microsoft Windows-based applications, such as Excel and Visual Basic.

In addition, Visual FoxPro makes it easy to create Automation servers that work better with the Internet, Microsoft Transaction Server, and the Active Desktop.

In This Section

OLE Drag-and-Drop

Describes how Visual FoxPro supports OLE drag-and-drop, a powerful and useful tool, which makes it possible for you to move data between other applications that support OLE drag-and-drop (such as Visual FoxPro, Visual Basic, the Microsoft Windows Explorer, Word and Excel, and so on).
Sharing Information and Adding OLE

Explains how you can use Visual FoxPro to share information with other applications.

Related Sections

Web Services and Components

Explains how you can enable a Visual FoxPro application to work for multiple users, include XML Web services, ActiveX controls, and automation-enabled applications, and add international capabilities.
XML Web Services in Visual FoxPro

Describes how to use XML Web services with your Visual FoxPro applications. XML Web services are classes or objects available on the Web that you can use in your applications programmatically as normal object-oriented calls.
Automation and COM Servers

Describes how to you can extend the functionality of your Visual FoxPro applications without a lot of extra coding time by using Automation and COM Servers.


OLE Drag-and-Drop

Visual FoxPro 9.0
OLE Drag-and-Drop

Visual FoxPro supports OLE drag-and-drop, a powerful and useful tool that makes it possible for you to move data between other applications that support OLE drag-and-drop (such as Visual FoxPro, Visual Basic, the Windows Explorer, Microsoft Word and Excel, and so on). In a distributed Visual FoxPro application, you can move data between controls in the application or between controls and other Window applications that support OLE drag-and-drop.

Note that previous versions of Visual FoxPro supported a programmatic drag-and-drop feature for controls, making it possible for you to move controls on a form. This form of drag and drop is still supported in Visual FoxPro. However, if you choose to implement drag and drop support in your applications, you should exclusively use either programmatic drag-and-drop for controls or OLE drag-and-drop – don't mix the two types of drag-and-drop support.

In This Section

Dragging and Dropping Data

Describes the basics of OLE drag-and-drop functionality.
Design-Time OLE Drag-and-Drop Support

Describes how using OLE drag-and-drop in Visual FoxPro makes developing applications faster and easier.
Run-Time OLE Drag-and-Drop Support

Describes how to use OLE drag-and-drop support during runtime in your applications.
How to: Implement Intrinsic and Manual OLE Drag-and-Drop Modes

Explains how to implement the two modes of OLE drag-and-drop for controls in Visual FoxPro.

Related Sections

Interoperability and the Internet

Provides links to information on how you can move data between Visual FoxPro and other applications as well as within Visual FoxPro applications.


Dragging and Dropping Data

Visual FoxPro 9.0
Dragging and Dropping Data
See Also

Understanding some of the basics of OLE drag-and-drop applications makes it easier to take full advantage of their features.

The mouse is used to drag and drop data between applications and controls. For example, you can select a set of files in the Windows Explorer. You can then press and hold the mouse button down while dragging the files, then release the mouse button to drop them onto the Visual FoxPro Project Manager, or you can select text in a Word document and drop the text into a text box on a Visual FoxPro form. During the OLE drag-and-drop operation, the mouse cursor changes to indicate that an OLE drag-and-drop operation is in effect.

Drag Source

The application or control from which data is moved is called the drag source.

The following table lists the properties, events, and methods available for an OLE drag source.

Property, Event, or Method | Description
OLECompleteDrag Event | Occurs when data is dropped on the drop target or the OLE drag-and-drop operation is canceled.
OLEDrag Method | Starts an OLE drag-and-drop operation.
OLEDragPicture Property | Specifies the picture displayed under the mouse pointer during an OLE drag-and-drop operation. You can specify a picture file of type .bmp, .dib, .jpg, .gif, .ani, .cur, and .ico.
OLEDragMode Property | Specifies how a drag source manages OLE drag operations.
OLEGiveFeedBack Event | Occurs after every OLEDragOver event. Allows the drag source to specify the type of OLE drag-and-drop operation and the visual feedback.
OLESetData Event | Occurs when a drop target calls the GetData method and there is no data in a specified format on the OLE drag-and-drop DataObject.
OLEStartDrag Event | Occurs when the OLEDrag method is called.

Drop Target

The application or control to which the data is moved is called the drop target.

The following table lists the properties, events, and methods available for an OLE drop target.

Property or Event | Description
OLEDragDrop Event | Occurs when data is dropped on a drop target and the drop target's OLEDropMode property is set to 1 – Enabled.
OLEDragOver Event | Occurs when data is dragged over a drop target and the drop target's OLEDropMode property is set to 1 – Enabled.
OLEDropEffects Property | Specifies the type of drop operations an OLE drop target supports.
OLEDropHasData Property | Specifies how a drop operation is managed.
OLEDropMode Property | Specifies how a drop target manages OLE drop operations.

Moving Data

To perform a drag-and-drop operation to move data using the default (left) mouse button, select the data you want to move in the drag source. After selecting the data, press and hold down the mouse button as you move the mouse pointer over the drop target. Release the mouse button to drop the data onto the drop target. During the OLE drag-and-drop operation, the mouse cursor changes to indicate that an OLE drag-and-drop operation is in effect.

You can also click the non-default (right) mouse button on the data in a drag source and drag it to a drop target. Depending on the drop target, a context menu may be displayed when you drop the data on the drop target. The context menu contains a set of options that make it possible for you to choose how the data is processed by the drop target.

Copying Data

You can also copy data from a drag source and paste it in a drop target. Press the Ctrl key as you click the mouse on the data selected in the drag source. The mouse cursor displays a plus sign (+) while the mouse is dragged to indicate a Copy operation is in effect.

Targets and Sources Not Supporting OLE drag-and-drop

You can only move or copy data from a drag source that supports OLE drag-and-drop, and the drop target must also support OLE drag-and-drop. Note that while a drop target may support OLE drag-and-drop, the drop target doesn't have to accept the data you attempt to drop on it. For example, the data you're moving or copying may be in a format the drop target doesn't support. During a drag-and-drop operation, the mouse cursor changes to a No Drop symbol (a slashed circle) to indicate the mouse is positioned over an area of an application or control where the data cannot be dropped.

Canceling an Operation

You can cancel the OLE drag-and-drop operation by pressing ESC during the operation.

See Also

Other Resources

OLE Drag-and-Drop
Run-Time OLE Drag-and-Drop Support
Interoperability and the Internet


Design-Time OLE Drag-and-Drop Support

Visual FoxPro 9.0
Design-Time OLE Drag-and-Drop Support
See Also

Design-time support for OLE drag-and-drop in Visual FoxPro makes developing applications even faster than previous versions. OLE drag-and-drop makes it easy to drop files into the Project Manager and the Visual FoxPro designers from the Windows Explorer. Text can be easily moved or copied from other applications to the Command Window, the Visual FoxPro text editors, and the Properties Window.

The following table lists the Visual FoxPro design time features that support OLE drag-and-drop with a description of the support.

Interface item Description

Command Window

Drop target for files, drag source and drop target for text.

If a file created in Visual FoxPro is dropped on the Command window, the file is opened with the appropriate Visual FoxPro command. For example, if a database is dropped on the Command window, Visual FoxPro issues the OPEN DATABASE and MODIFY DATABASE commands to open the file for modification. If a table is dropped on the Command window, the table is opened with the USE ... AGAIN and BROWSE commands. If SET EXCLUSIVE is ON, the table is opened for exclusive use. If SET EXCLUSIVE is OFF, the table is opened for shared use.

Other Visual FoxPro files are opened with the appropriate MODIFY command — forms are opened with MODIFY FORM, queries are opened with MODIFY QUERY, text and header (.H) files are opened with MODIFY FILE, and so on.

If a file that has been created in another application is dropped on the Command window, the file is opened in the application with which it is associated. For example, dropping a Microsoft Excel spreadsheet on the Command window starts Excel and opens the spreadsheet.

Project Manager

Drop target for files.

Files are added to the appropriate Project Manager categories, based on their file extensions. If a file with an extension Visual FoxPro does not recognize is dropped on the Project Manager, the file is added to the Other category.

If a table contained in a database is dropped on the Project Manager, the database is added to the Databases category of the Data item and is marked as Excluded. If a free table is dropped on the Project Manager, the table is added to the Free Tables category of the Data item and is marked as Excluded. If a database is dropped on the Project Manager, the database is added to the Databases category of the Data item and is marked as Excluded.

While OLE drag-and-drop makes it easy to add files to the Project Manager, remember that the Project Manager automatically adds any referenced files to the project when you build the project. For example, if a program you add to the project executes a second program, the second program is automatically added to the project when the project is built. It isn't necessary to manually add the second program to the project.

Text Editors

Drag source and drop target for text.

Text editors include editing windows opened with MODIFY COMMAND, MODIFY FILE, and MODIFY MEMO, the Command window, code editing windows in the Form, Class, Menu, and Data Environment Designers, and the Stored Procedure editor in the Database Designer.

Debugger

Drag source and drop target for text.

The Watch window text box and Name list are drag sources and drop targets for text. The Trace window and the Debug Output window are drag sources for text.

Database Designer

Drop target for files.

Dropping a table onto the Database Designer adds the table to the current database.

Class Designer

Drop target for text and files.

By default, dropping text on a container object in the Class Designer creates a label with the text as the value of its Caption property. You can change the default control created when text is dropped on the Form Designer in the Field Mapping Tab of the Options Dialog Box.

If you drop text onto a non-container control (a CheckBox, CommandButton, Header, Label, or OptionButton control), the Caption property is set to the text.

Dropping a graphics file (.ani, .bmp, .cur, .gif, .ico, or .jpg) onto the Class Designer creates an Image control with the Picture property set to the name of the graphics file.

Data Environment Designer

Drop target for files.

Dropping a table onto the Data Environment Designer adds the table to the data environment. Dropping a database onto the Data Environment Designer displays the Add Table or View dialog, making it possible for you to add a table or view to the data environment.

Query Designer

Drop target for files.

Dropping a table onto the Query Designer adds the table to the query. Dropping a database onto the Query Designer displays the Add Table or View dialog, making it possible for you to add a table or view to the query.

View Designer

Drop target for files.

Dropping a table onto the View Designer adds the table to the view. Dropping a database onto the View Designer displays the Add Table or View dialog, making it possible for you to add a table or view to the view.

Properties window

Drop target for text.

You can drop text onto the text box that appears at the top of the Properties window when a design time property is selected.

Component Gallery

Drag source and drop target for files.

You can drag objects out of the Component Gallery and drop them onto the Form Designer. You can also drag files out of the Component Gallery and drop them onto the Project Manager.

Files can be dropped on the Component Gallery.

See Also

Other Resources

OLE Drag-and-Drop
Run-Time OLE Drag-and-Drop Support
Interoperability and the Internet


Run-Time OLE Drag-and-Drop Support

Visual FoxPro 9.0
Run-Time OLE Drag-and-Drop Support
See Also

OLE drag-and-drop support is available at run time for Visual FoxPro controls and the text editor. The controls and the text editor support OLE drag-and-drop interactively at run time, and the controls provide programmatic support at run time. The DataObject object provides programmatic OLE drag-and-drop support for the controls.

Two modes of OLE drag-and-drop are available for Visual FoxPro controls: intrinsic mode and manual mode. In intrinsic mode, Visual FoxPro intrinsically handles an OLE drag-and-drop operation. In manual mode, OLE drag-and-drop operations are handled programmatically. The events that occur are determined by the OLE drag-and-drop mode. For more information, see the section, "Intrinsic and Manual OLE drag-and-drop Modes."

Drag and Drop in Previous Versions of Visual FoxPro

Previous versions of Visual FoxPro supported programmatic drag-and-drop for controls, making it possible for you to move controls on a form. This form of drag and drop is still supported. If you use the default settings for the OLEDragMode and OLEDropMode properties, your existing applications will run as before without any changes.

The DataObject Object

The DataObject object is a container for data being transferred from an OLE drag source to an OLE drop target, and exists only for the duration of an OLE drag-and-drop operation. The DataObject object cannot be created programmatically and references to it become invalid once the OLE drag-and-drop operation is completed. The DataObject is passed as the oDataObject parameter in the OLEStartDrag, OLEDragOver, OLEDragDrop, and OLESetData events.

The DataObject can store multiple sets of data, each in a different format. The existence of a specific format in the DataObject can be determined with the GetFormat method. See the GetFormat Method for a listing of the formats supported by the DataObject.

DataObject Object Methods

The DataObject object has methods that make it possible for you to programmatically manipulate the data being dragged and dropped. The following table lists the methods available at run time for the DataObject.

Method | Description
ClearData | Clears all data and data formats from the OLE drag-and-drop DataObject object.
GetData | Retrieves data from the OLE drag-and-drop DataObject object.
GetFormat | Determines whether data in a specified format is available on the OLE drag-and-drop DataObject.
SetData | Places data and its format on the OLE drag-and-drop DataObject.
SetFormat | Places a data format without data on the OLE drag-and-drop DataObject.

See Also

Other Resources

Design-Time OLE Drag-and-Drop Support
Interoperability and the Internet


How to: Implement Intrinsic and Manual OLE Drag-and-Drop Modes

Visual FoxPro 9.0
How to: Implement Intrinsic and Manual OLE Drag-and-Drop Modes
See Also

Visual FoxPro supports two OLE drag-and-drop modes for controls: intrinsic and manual. In intrinsic mode, OLE drag-and-drop operations are handled by Visual FoxPro. In manual mode OLE drag-and-drop operations, you programmatically specify function and control.

Intrinsic OLE drag-and-drop Mode

Intrinsic OLE drag-and-drop mode can be implemented in an application to provide standard OLE drag-and-drop support without any additional programming.

To implement intrinsic OLE drag-and-drop support for a control

  1. Set its OLEDragMode property to 1 – Automatic, allowing the control to act as an OLE drag source.

  2. Set the control's OLEDropMode property to 1 – Enabled, to allow the control to act as an OLE drop target.

For intrinsic OLE drag-and-drop operations, Visual FoxPro determines if the drop target supports the format of the data being dropped on it; if the drop target supports the format, the drop occurs, otherwise the drop is not allowed.

The following table lists the Visual FoxPro controls and the data formats they support as drag sources in intrinsic mode. Note that CF_TEXT is text, such as text you would enter in a text box, and CFSTR_VFPSOURCEOBJECT is an object type reference to a Visual FoxPro control or object. For the controls below that support the CF_TEXT data format, you can drag text from the text portion of the control.

Drag Source Data Formats

Control | Data Format (defined in Foxpro.h)
Container, Image, Line, PageFrame, and Shape | CFSTR_VFPSOURCEOBJECT
CommandButton and Label | CFSTR_VFPSOURCEOBJECT and CF_TEXT
CheckBox, ComboBox, EditBox, ListBox, Spinner, and TextBox | CFSTR_VFPSOURCEOBJECT, CF_TEXT, and CFSTR_OLEVARIANT

The Visual FoxPro controls and data formats they support as drop targets in intrinsic mode are listed in the following table. For the controls listed in this table, you can drop text onto the text portion of the control. The text is inserted at the insertion point.

Drop Target Data Formats

Control | Data Format
EditBox and ComboBox (When the ComboBox Style property is set to 0 - Dropdown Combo) | CF_TEXT
Spinner and TextBox | CFSTR_OLEVARIANT

Manual OLE drag-and-drop Mode

There may be cases where you'd like to control the type of data that can be dropped on a drop target, or provide additional functionality for a drag-and-drop operation. For example, you can convert data to a format supported by the drop target, or you can display a dialog that asks the user to verify that they want to drop the data on the drop target. To override the intrinsic OLE drag-and-drop support and provide greater control over drag-and-drop operations use manual OLE drag-and-drop.

To implement manual OLE drag-and-drop support for a control

  • Write your own event or method code for the event or method you want to override.

Include the NODEFAULT Command in the event or method code to override the intrinsic Visual FoxPro drag-and-drop behavior.

Visual FoxPro provides backward compatibility (no OLE drag support) for existing applications when OLEDragMode is set to 0 (the default) and you do not include additional OLE drag-and-drop coding.

See Also

Other Resources

Run-Time OLE Drag-and-Drop Support
Interoperability and the Internet
Design-Time OLE Drag-and-Drop Support
OLE Drag-and-Drop


Sharing Information and Adding OLE

Visual FoxPro 9.0
Sharing Information and Adding OLE

With Visual FoxPro, you can employ the strengths of other applications by sharing information with them. You can copy and paste data between applications, create mail merges using data from Visual FoxPro tables, link or embed data from other applications, and import or export data between applications. By sharing information, you can save time and avoid errors. For example, instead of entering results from Excel in a table, you can copy the results from Excel or link to Excel to get the results automatically.

In addition, you can extend the power of your Visual FoxPro applications by employing the strengths of other Automation-enabled applications or ActiveX controls. In the forms or General fields of your applications, you can include specific functionality or data such as text, sound, pictures, and video from other applications. You can view or manipulate this data visibly by using the application that created it or you can manipulate the data invisibly and automatically by controlling the application with Automation.

Other applications also can tap into the power of Visual FoxPro through Automation. You can even create Automation servers (COM components) in Visual FoxPro that your applications or other applications can access locally and remotely.

In This Section

Dynamic Information Sharing

Explains how, using Visual FoxPro, you can include data from other applications dynamically and still have those applications maintain the data by linking or embedding it in your application.
Working with OLE Objects

Describes how you can add OLE objects to applications.

Related Sections

Interoperability and the Internet

Explains how to use OLE drag-and-drop to develop applications that make it possible for you to move data between Microsoft Windows-based applications and within a Visual FoxPro application. Create documents for use on the Internet, or use one of two different Visual FoxPro run times to create COM components (Automation servers) as normal or multithreaded applications.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
OLE Drag-and-Drop

Describes OLE drag-and-drop, a powerful and useful tool supported by Visual FoxPro, which makes it possible for you to move data between other applications that support OLE drag-and-drop (such as Visual FoxPro, Visual Basic, the Microsoft Windows Explorer, Word and Excel, and so on).
Programming in Visual FoxPro

Describes how to access the full power of Visual FoxPro by creating applications that incorporate object-oriented programming techniques and the event-driven model to maximize your programming productivity.


Dynamic Information Sharing

Visual FoxPro 9.0
Dynamic Information Sharing

You can typically include small amounts of data by copying and pasting it into your application. However, under certain conditions, you might want to link to and or embed data from other applications instead. For example, you can link or embed a Microsoft Word document in a General field or a Microsoft Excel worksheet on a form.

When you link to data, it is stored in its source file, not in your Visual FoxPro table or form. The table or form stores only the location of the source and displays a representation of the linked data. Linked data is updated when the source file changes and retains a connection to its source file, unless you break the connection.

Note:
Files with an .avi extension are always linked.

When you dynamically embed data, it is stored only in your table or form. This data does not retain a connection to its source file. If changes are made to the source file, they do not appear in your Visual FoxPro application.

In This Section

Considerations for Linking or Embedding Data

Describes considerations for choosing to link to or embed data.
Embedding Hyperlinks

Describes support for enabling and embedding hyperlinks.
How to: Insert Data in Tables

Describes how to insert data into a General field.
How to: Change or Break Links to Data in Tables

Describes how to modify the link to data in a General field.
How to: Display Embedded or Linked Data from Tables

Describes how to display data from a General field on a form or in a report.
How to: Display Embedded or Linked Data on Forms

Describes how to link or display data from a General field on a form.
How to: Replace Linked or Embedded Data with Static Data

Describes how to replace linked or embedded objects data with stand-alone bitmaps.

Related Sections

Sharing Information and Adding OLE

Explains how you can use Visual FoxPro to share information with other applications.
How to: Add OLE Objects to Applications

Describes how you can add OLE objects to tables and forms interactively or programmatically.
OLE Drag-and-Drop

Describes OLE drag-and-drop, a powerful and useful tool supported by Visual FoxPro, which makes it possible for you to move data between other applications that support OLE drag-and-drop.
Importing and Exporting Data

Explains how information is copied between Visual FoxPro and other applications by importing to and exporting from Visual FoxPro.


Considerations for Linking or Embedding Data

Visual FoxPro 9.0
Considerations for Linking or Embedding Data
See Also

Use the following guidelines when choosing whether to link to or embed data:

Link to data when:

  • Data or graphics are likely to change.

  • Your application must include the latest version of that data available.

  • The source files are available for updating on your computer or across a network.

  • The source files must be shared with other applications.

Embed data or graphics when:

  • You do not need the most current versions in your application.

  • You do not need to include the data in more than one application.

  • The source files would not be available for updating if they were linked.

  • You want to include a very large file such as a video or sound file.

  • You want to include data that is maintained separately by its source application.

See Also

Other Resources

How to: Insert Data in Tables
Dynamic Information Sharing


Embedding Hyperlinks

Visual FoxPro 9.0
Embedding Hyperlinks
See Also

Visual FoxPro editors support embedding and activating hyperlinks. When you include a valid hyperlink, Visual FoxPro applies hyperlink attributes to the hyperlink text.

If hyperlinks are activated in the Options Dialog Box or by setting the EditorOptions property, a hyperlink will be displayed in your editor with the typical underline visual cue of a hyperlink in HTML. The hyperlink termination character is a space, so if you have spaces in your path you must replace them with %20. For example, http://servername/program files/my folder must be written http://servername/program%20files/my%20folder.

By default, you need to CTRL + click to follow a link. The EditorOptions property lets you change the default so that simple clicking will follow the link. The following table describes the valid protocols.

Protocol | Trigger(s) | Syntax
File | File:/ | file:///cDrive/cPathcFile file:////cUNCPath
FTP | FTP:/ | ftp://[cUserName[:cPassword@]]cDomain
Gopher | Gopher:/ | gopher ://cDomain
HTTP | HTTP:/, www.<char> | http ://cDomain
HTTPS | HTTP:/ | https ://cDomain
MailTo | MailTo: | mailto:cAddress[;cMoreAddresses][&cSubject] [&cBody] [&cCC][&cBCC]
News | News: | news:cNewsGroup
Telnet | Telnet:/ | telnet://cDomain[:iPort]

See Also

Other Resources

Dynamic Information Sharing


How to: Insert Data in Tables

Visual FoxPro 9.0
How to: Insert Data in Tables
See Also

You can include data from other applications in a Visual FoxPro table by inserting the data into General fields. For example, if you have pictures of products, you can include them in a table containing other product information by inserting them into a General field. If the quantity of data is small enough, you can copy and paste it into the General field.

To insert data into a General field

  1. Open and browse the appropriate table.

  2. Double-click the General field in which you want to insert the data.

  3. From the Edit menu, choose Insert Object.

    The Insert Object dialog box appears listing the types of data you can insert into the field.

    Tip:
    You can save disk space when linking or embedding data by clicking Display As Icon in the Paste Special dialog box. When this is selected, Visual FoxPro displays the icon instead of the data.

  4. Choose one of the following:

    • To create data of your own, select Create New and then choose the appropriate type of data.

    -OR-

    • To use existing data, select Create from File. Then, type the name of the file containing the data, or choose Browse and select the appropriate file. If you want to link to the file, select Link.

To paste data from another application into a General field

  1. In the other application, select and copy the data to the Clipboard.

  2. Open the table containing the General field in a browse window.

  3. Double-click the General field.

  4. Choose one of the following:

    • To paste the data, on the Edit menu, click Paste.

    -OR-

    • To link to the data, on the Edit menu, click Paste Special to open the Paste Special dialog box, then click Paste Link.

      Tip:
      You can save disk space when linking or embedding data by clicking Display As Icon in the Paste Special dialog box. When this is selected, Visual FoxPro displays the icon instead of the data.

See Also

Other Resources

Dynamic Information Sharing
Importing and Exporting Data
Sharing Information and Adding OLE


How to: Change or Break Links to Data in Tables

Visual FoxPro 9.0
How to: Change or Break Links to Data in Tables
See Also

After linking to some data, you might want to use a different data source, or you might want to embed rather than link. To change the data source, you must change the link; and to embed, you must break the link.

To change the link to data in a General field

  1. Open and browse the appropriate table.

  2. Double-click the General field containing the data whose link you want to change.

  3. From the Edit menu, choose Links. The Links dialog box appears.

    Note:
    Choose Automatic to automatically update data any time it changes in the source application, or Manual if you want to manually update data.

  4. In the Links dialog box, choose Change Source.

    The Change Source dialog box appears.

  5. Specify the new data source and choose OK.

  6. In the Links dialog box, choose Close to complete the change.

To break a link to data in a General field

  1. Open and browse the appropriate table.

  2. Double-click the General field containing the data whose link you want to break.

  3. From the Edit menu, choose Links.

  4. In the Links dialog box, choose Break Link.

  5. Choose Close.

When the link is broken, the data becomes static.

See Also

Other Resources

How to: Insert Data in Tables
Dynamic Information Sharing
Importing and Exporting Data
Sharing Information and Adding OLE


How to: Display Embedded or Linked Data on Forms

Visual FoxPro 9.0
How to: Display Embedded or Linked Data on Forms
See Also

You can enhance the design of forms by linking or embedding data such as Microsoft Word documents or Microsoft Excel worksheets. Similarly, you can enhance reports by displaying linked or embedded data from General fields.

To link or embed data on a form

  1. Create or open a form.

  2. On the Form Controls toolbar, select the OLE Container Control button and drag to size on the form.

    The Insert Object dialog box appears, listing the types of files you can link or embed.

  3. Choose one of the following:

    • Create a new file by selecting Create New.

      -OR-

    • Use an existing file by selecting Create from File. Type the name of the file containing the data or choose Browse and select the appropriate file. Additionally, if you want to link to the file, select Link.

Changing or Breaking Links to Data on Forms

You change or break a link to data displayed on a form by using the Links command on the Edit menu.

To change a link to data on a form

  1. Open the appropriate form.

  2. Select the object whose link you want to change.

  3. From the Edit menu, choose Links.

  4. In the Links dialog box, choose Change Source.

  5. In the Change Source dialog box, specify the new data source and choose OK.

  6. In the Links dialog box, choose Close to complete the change.

To break a link to data on a form

  1. Open the appropriate form.

  2. Select the object whose link you want to break.

  3. From the Edit menu, choose Links.

  4. In the Links dialog box, choose Break Link.

  5. Choose Close.

When the link is broken, the data becomes static.

See Also

Other Resources

How to: Add General Fields to Reports
Working with Reports
How to: Change or Break Links to Data in Tables
How to: Display Embedded or Linked Data from Tables
How to: Edit OLE Objects in Forms and Tables
How to: Replace Linked or Embedded Data with Static Data
Dynamic Information Sharing
Importing and Exporting Data
Sharing Information and Adding OLE


How to: Display Embedded or Linked Data from Tables

Visual FoxPro 9.0
How to: Display Embedded or Linked Data from Tables
See Also

On a form or report, you can display linked or embedded data from General fields in a table. For example, suppose you have a product table in which each record includes a General field containing a brochure (a Word document) about a product. On a form, you could display selected information from the records — including the brochure describing the product.

To display data from a General field on a form

  1. In the Form Designer, add an OLE Bound control to your form.

    On the form, Visual FoxPro creates an object through which you can view the data at run time.

  2. Specify the General field that contains the data by setting the object's ControlSource property.

    For example, if the table name is Inventory and the General field name is Current, then set the ControlSource property to Inventory.Current.

  3. On the form, add buttons or menu commands for browsing the General field specified in the ControlSource property.

To display data from a General field on a report

  • Add a General field to the report.

    For details, see How to: Add General Fields to Reports.

    Tip:
    When creating a report, you can link or embed pictures or icons directly into the report from an outside source using the image container. Other forms of data, such as Word documents or Microsoft Excel spreadsheets, can be included only if they were previously linked or embedded into a General field in a Visual FoxPro table.

See Also

Other Resources

Working with Reports
How to: Display Embedded or Linked Data on Forms
How to: Edit OLE Objects in Forms and Tables
How to: Replace Linked or Embedded Data with Static Data
Dynamic Information Sharing
Importing and Exporting Data
Sharing Information and Adding OLE


How to: Replace Linked or Embedded Data with Static Data

Visual FoxPro 9.0
How to: Replace Linked or Embedded Data with Static Data
See Also

You can replace linked or embedded data with stand-alone bitmaps by using the application that created the data.

To replace linked or embedded data with a bitmap

  1. Start the application that created the data by choosing the object containing the data.

  2. In the application, copy the object's presentation to the Clipboard.

    For example, if the application has a Copy Picture command, use it to copy the object's presentation.

  3. From the Edit menu in Visual FoxPro, choose Paste Special.

  4. In the Paste Special dialog box, choose Paste Option.

  5. Choose the Picture (Metafile) option.

See Also

Other Resources

How to: Edit OLE Objects in Forms and Tables
How to: Display Embedded or Linked Data from Tables
How to: Display Embedded or Linked Data on Forms
Dynamic Information Sharing
Importing and Exporting Data
Sharing Information and Adding OLE


Working with OLE Objects

Visual FoxPro 9.0
Working with OLE Objects

You can incorporate the power and flexibility of applications, such as Microsoft Excel and Word, in your Visual FoxPro applications by adding and using OLE objects.

In This Section

Designing an OLE Application

Explains how linking or embedding OLE objects can extend an applications power and flexibility by incorporating OLE objects from OLE-capable applications such as Microsoft Word and Excel.
How to: Add OLE Objects to Applications

Describes how to add OLE objects to your application.
How to: Edit OLE Objects in Forms and Tables

Describes how to edit embedded or linked objects on a form.
How to: Use ActiveX Controls

Describes how to use ActiveX controls in an application. ActiveX controls are objects with encapsulated functionality and exposed properties, events, and methods.
Manipulating Objects with Automation

Discusses how to manipulate objects, such as, OLE objects or ActiveX objects inside OLE Container controls, using code in the same way that you can program native Visual FoxPro objects.

Reference

Table Designer

Provides links to topics that explain the Table designer in Visual FoxPro.
MODIFY GENERAL Command

Describes the MODIFY GENERAL command and its use to open a editing windows for general fields in a tables current record.
APPEND GENERAL Command

Describes the APPEND GENERAL command its use to import an OLE object from a file and place it into a general field in a table.

Related Sections

Dynamic Information Sharing

Explains how, using Visual FoxPro, you can include data from other applications dynamically and still have those applications maintain the data by linking or embedding it in your application.
OLE Drag-and-Drop

Describes OLE drag-and-drop, a powerful and useful tool supported by Visual FoxPro, which makes it possible for you to move data between other applications that support OLE drag-and-drop.


Designing an OLE Application

Visual FoxPro 9.0
Designing an OLE Application
See Also

Automation-enabled applications and COM components can act as Automation servers, clients, or both. Components that act as servers can provide objects to another application; components that act as clients can create objects.

You can easily incorporate the power and flexibility of applications, such as Microsoft Excel and Word, in your Visual FoxPro applications. Because Visual FoxPro also acts as a server, you can also provide functionality that can be integrated into solution packages based around Microsoft Office or other COM components.

Insertable OLE objects come from OLE-capable applications such as Microsoft Excel and Word. Such objects include Word documents and Excel worksheets. On forms, you can link or embed these objects using the OLE Container control, and you can store such objects in General fields of a table, displaying them in your forms with the OLE Bound control.

In a Visual FoxPro application, you can use OLE and ActiveX technology in many ways. Before you create an application, consider the ways you can use these technologies.

Linking or Embedding OLE Objects

You can embed or link files from other Windows applications in your tables and forms. For example, you can embed or link a Word document in a General field of a table, and you can embed or link an Excel worksheet on a form.

The difference between embedding and linking lies in where the data is stored. Embedding stores the data in the table or form, whereas linking does not. For example, when you embed an Excel worksheet on a form, the form contains a copy of the worksheet. When you link, however, the form contains only a reference to the worksheet — not the worksheet itself.

Both embedded and linked data start off with the original contents of the server file.

But when the original file is changed, linked data is automatically updated to reflect the change, whereas embedded data is not:

LinkedDataFormUpdated screeenshot foxpro

Embedded data is not necessarily static, though. Both embedded and linked data can be displayed, changed, and manipulated interactively and programmatically in Visual FoxPro.

Adding Bound or Unbound OLE Objects

On a form or in a report, you can create objects that are bound to General fields in tables. Such objects are called bound OLE objects and you use them to display the contents of OLE objects in General fields. You create bound OLE objects by using the OLE Bound control on the Form Controls toolbar. Alternatively, you create unbound OLE objects by using the OLE Container control. An unbound OLE object is not connected to a General field in a table.

See Also

Other Resources

How to: Add OLE Objects to Applications
Sharing Information and Adding OLE


How to: Add OLE Objects to Applications

Visual FoxPro 9.0
How to: Add OLE Objects to Applications
See Also

You can add OLE objects to tables, forms, and reports. For more information about adding OLE objects to reports, see How to: Add General Fields to Reports.

Adding OLE Objects to Tables

You can include Word documents in a table by creating General fields and adding the documents by linking or embedding them.

To add an OLE object to a table

  1. Open the table in the Table Designer.

  2. In the Table Designer, create a General field.

  3. Open a browse window for the table.

  4. Double-click the General field to open an editing window.

    Tip:
    You can also use the MODIFY GENERAL command.

  5. On the Edit menu, click Insert Object.

To add an OLE object to a table programmatically

  • Use the APPEND GENERAL command.

For more information, see APPEND GENERAL Command.

You can use APPEND GENERAL to embed OLE objects or link to OLE objects created by applications such as Microsoft Excel and Word. These applications support both linking and embedding. However, some applications such as Microsoft Graph only support embedding. When you use the APPEND GENERAL command, you can import the OLE object from a file and insert it into a General field. If the field already contains an object, the new object replaces it.

Note:
Unlike APPEND and APPEND BLANK, APPEND GENERAL does not add a new record to the table.

For example, suppose you have Microsoft Word files that you want to store in a Visual FoxPro table. If the table has a General field named WordDoc, you can embed the documents by using the following code:

Copy Code
CREATE TABLE oletable (name c(24), worddoc g)
CD GETDIR()

nFiles = ADIR(aWordFiles, "*.doc")
IF nFiles > 0
   FOR i = 1 to nFiles
      APPEND BLANK
      REPLACE Oletable.Name WITH aWordFiles(i,1)
      APPEND GENERAL WordDoc FROM aWordFiles(i,1)
   ENDFOR
ELSE
   MESSAGEBOX("No Word files found.")
ENDIF
Note:
The preceding example looks only for files ending in .doc, the standard extension used by Word files. Because Microsoft Word and OLE are aware of this, the files are automatically associated with the Word server when you use APPEND GENERAL.

If you use a different extension than the one expected by the server, you must declare the class of the server, using the CLASS clause. For example, if you add the class for Word to the previous example, the code becomes:

Copy Code
APPEND GENERAL WordDoc FROM wordfiles(i,1) CLASS "Word.Document"

If you have files with common extensions (for example, .bmp) that other servers might use, you can use the CLASS clause to specify the particular server you want to use for those files. Alternatively, if you'd rather link than embed objects, use the LINK keyword, as in the following example:

Copy Code
APPEND GENERAL WordDoc FROM wordfiles(i,1) LINK CLASS "Word.Document"

In addition, you can replace data in an object by using the DATA keyword of APPEND GENERAL.

Adding OLE Objects to Forms

Using the Form Designer, you can add insertable OLE objects to forms with the OLE Container control. In addition, you can display OLE objects from General fields by using the OLE Bound control. When you add an OLE object to a form in either the OLE Container control or the OLE Bound control, you have more control over the opening and editing of the object.

You can determine whether the OLE object is opened or edited when the control gets the focus or when the user double-clicks the control by setting the AutoActivate property of an OLE bound or container control. The AutoVerbMenu property specifies whether the shortcut menu of the ActiveX control allows a user to open or edit the OLE object. To control access so that the OLE object can only be opened or edited programmatically with the DoVerb method, set AutoActivate to 0 - Manual and AutoVerbMenu to false (.F.).

To add an OLE object to a form

  1. In the Form Designer, add an OLE Container control to your form. The Insert Object dialog box opens.

  2. In the Insert Object dialog box, select Create New or Create from File.

  3. Choose the appropriate OLE object from the Object Type list.

You can also customize the Form Controls toolbar so that you can directly add specific OLE objects.

To add OLE objects to the Form Controls toolbar

  1. From the Tools menu, choose Options.

  2. In the Controls tab of the Options dialog box, choose ActiveX controls.

  3. In the Selected list, select the OLE objects and ActiveX controls you want to be available from the Form Controls toolbar.

  4. Choose Set as Default, and then choose OK.

  5. In the Form Controls toolbar, choose View Classes, and then choose ActiveX Controls.

To display an OLE object from a General field

  1. In the Form Designer, add an OLE Bound control to your form.

  2. Specify the General field that contains the data by setting the object's ControlSource property.

    For example, if the table name is Inventory and the General field name is Current, then set the ControlSource property to Inventory.Current.

You can also display an OLE object from a General field programmatically:

Code | Comments
frm1 = CREATEOBJECT("form") | Create form.
frm1.ADDOBJECT("olb1", "oleboundcontrol") | Add control.
frm1.olb1.ControlSource = "Inventory.Current" | Bind the data to the control.
frm1.olb1.Visible = .T. frm1.Visible = .T. | Make the control and form visible.

See Also

Other Resources

How to: Edit OLE Objects in Forms and Tables
Working with OLE Objects


How to: Edit OLE Objects in Forms and Tables

Visual FoxPro 9.0
How to: Edit OLE Objects in Forms and Tables
See Also

When you add an OLE object to a table or form, you can edit the data and display settings for the object at design time or run time.

Note:
You cannot edit the data of an OLE object in an OLE Bound control at design time.

Some embedded OLE objects support in-place editing so that you can edit the object in the window used by your application. For example, if you double-click a Microsoft Excel worksheet object in a General field, the menu titles change to reflect the Microsoft Excel menu structure and the default Microsoft Excel toolbars are displayed. You or the application user can edit the Microsoft Excel object without leaving your application. However, the Visual FoxPro standard File, Program, and Window menus are not replaced.

Note:
Only embedded objects can be edited in place, not linked objects.

If you create a menu title and want it to be displayed even while the user edits an OLE object, select Negotiate in the Prompt Options dialog box of the Menu Designer. For more information, see Designing Menus and Toolbars, or the NEGOTIATE clause in the DEFINE PAD Command topic.

You can also open the Automation server in another window, edit the data or display characteristics there, and have the new values reflected in your application when you return to it.

To edit data in a General field in a table

  1. Open the table you want in a browse window.

  2. Double-click the General field you want to edit.

    An editing window opens for the General field.

  3. In the editing window, double-click the object to edit the data.

To edit embedded or linked objects on a form while designing the form

  1. Select the object representing the data.

  2. With the mouse pointer over the object, click the right mouse button.

  3. From the shortcut menu, choose the object type, and then choose Edit or Open.

To edit objects or data from General fields on a form while running the form

  1. From the Edit menu, select the object.

    For example, if the object is a Microsoft Excel worksheet, select Spreadsheet Object from the Edit menu.

    Tip:
    You can also right-click on the object if its AutoVerbMenu property is set to True. Choose the object type, and then choose Edit or Open.

  2. To edit the object visually, choose Edit from the submenu.

    -or-

    To edit the object in a separate window, choose Open from the submenu.

    Caution:
    If you change the data in an object while running a form, Visual FoxPro saves the changes only if the data is linked or is associated with an OLE Bound control. Changes associated with an OLE Container control are not saved.

See Also

Other Resources

How to: Add OLE Objects to Applications
Working with OLE Objects


How to: Use ActiveX Controls

Visual FoxPro 9.0
How to: Use ActiveX Controls
See Also

ActiveX controls are objects with encapsulated functionality and exposed properties, events, and methods. ActiveX controls provide a wide range of functionality that you can easily tap into. ActiveX controls that ship with Visual FoxPro include:

  • Windows controls, like the RichText and the TreeView controls.

  • System controls, like the Communications and MAPI controls.

ActiveX controls are versatile because you can subclass them to create other controls and you can control them by using the events, methods, and properties associated with the controls. You cannot create ActiveX controls with Visual FoxPro; however, you can create them using the Microsoft OLE Custom Control Developer's Kit provided with Microsoft Visual C++® 4.0, and with the Microsoft Visual Basic® Control Creation Edition version 5.0.

For more information about accessing ActiveX controls, see Extending Visual FoxPro with External Libraries. For more information on creating ActiveX controls specific to Visual FoxPro, see Accessing the Visual FoxPro API.

Adding ActiveX Controls to a Form

ActiveX controls in Visual FoxPro must be contained in an OLE Container control (the base class is OLEControl). When you add an OLE Container control to a form, you can choose the ActiveX control you want to add to the form.

To add an ActiveX control to a form

  1. From the Form Controls toolbar, choose OLE Container Control and drag it to size in the form.

  2. In the Insert Object dialog box, choose Insert Control.

  3. In the Control Type list, select the desired ActiveX control.

  4. Choose OK.

If an ActiveX control supports simple data binding, Visual FoxPro will expose a ControlSource property for the control. All you have to do is set the ControlSource property to a table field and the value displayed in the ActiveX control reflects that value in the underlying field. Changes to the value in the control are saved to the field.

For examples of using ActiveX controls, run Solution.app in the Visual FoxPro ...\Samples\Solution directory.

Note:
To ensure all ActiveX control events are processed, set the AutoYield property of the Visual FoxPro Application object to false (.F.).

See Also

Other Resources

How to: Add OLE Objects to Applications
Sharing Information and Adding OLE
OLE Container Control
Insert Object Dialog Box


Manipulating Objects with Automation

Visual FoxPro 9.0
Manipulating Objects with Automation
See Also

OLE objects in your forms or programs, or ActiveX controls inside OLE Container controls, can be manipulated through code in the same way that you can program native Visual FoxPro objects.

Manipulating Extrinsic Object Properties

In code, you can manipulate an object using its properties. The way you reference a property depends on whether the object stands alone or is part of a container, such as the OLE Container control or OLE Bound control.

Note:
ActiveX controls are always part of an OLE Container control.

An object in a container has two parts: the object itself and a container around the object. Both the object and the container have properties, and sometimes they have the same property names. To ensure you reference the object's properties, always append the container's Object property to the object's name. For example, the following code refers to the object's Left property:

Copy Code
frm1.olecontrol1.Object.Left = 25  && Object's Left

If you omit the Object property, you reference the container's Left property instead:

Copy Code
frm1.olecontrol1.Left= 25  && Container's Left property

For example, suppose you have an application that sends mail when the user clicks on a compose command button. If you've added a Microsoft MAPI message control to a form as olecontrol1, the code associated with the Click event of the command button might be:

Copy Code
THISFORM.olecontrol1.Object.Compose
THISFORM.olecontrol1.Object.Send(.T.)

In addition to using the Object property to reference properties of the contained object, you can use other properties of the container control. For example, you can reference the read-only OLEClass property to identify the type of object in the container and the Sizable property to prevent users from changing the size of an object. For details about container control properties, see OLE Container Control.

In the Form and Class Designers, the properties of ActiveX controls are displayed in the Visual FoxPro Properties window, but most ActiveX controls also have their own interface for setting common properties. You can see this properties interface by selecting the object-specific Properties option from the ActiveX control's shortcut menu. For example, to open the Properties dialog box for a rich text control, choose Microsoft RichText Control Properties from the shortcut menu.

Using Extrinsic Object Methods

In addition to setting and retrieving properties of objects, you can manipulate an object using methods it supports. For example, you can use the Add method of a Microsoft Excel collection object to create a new Microsoft Excel workbook.

The following Automation example uses the Add method to create an Excel workbook, the Save method to save the workbook, and the Quit method to end Excel:

Code | Comments
oleApp = CREATEOBJECT("Excel.Application") | Start Excel.
OleApp.Visible=.T. | Display Excel.
OleApp.Workbooks.Add | Create a workbook.
OleApp.Cells(1,1).Value=7 | Set a cell's value.
OleApp.ActiveWorkbook.SaveAs("C:\TEMP.XLS") | Save the workbook.
OleApp.Quit | Quit Excel.

If you create an object using the OLE Container control or OLE Bound control, you can use the DoVerb method of the control to execute a verb on the object. For example, use DoVerb(0) to execute the default verb, DoVerb(– 1) to activate the object for visual editing, and DoVerb(– 2) to open the object in a separate window.

Note:
See an application's documentation to determine what Automation commands it supports. For example, Microsoft Excel add-in components are not available for Automation.

Setting Time Outs

When you pass a request to an OLE object, the Automation server processes it. You don't have much control over the server processing, but you can specify how long you'll wait for a process to finish by setting the OLERequestPendingTimeout and OLEServerBusyTimeout properties. You can determine what happens when that time has expired by setting the OLEServerBusyRaiseError property.

Accessing Collections of Objects

An object type can represent a single object or a collection of related objects. For example, a Microsoft Excel Workbook object represents a single workbook, whereas the Workbooks object represents all the workbooks currently loaded. Because the Workbooks object represents a collection of objects, it's called a collection object.

In code, a collection is an unordered list in which the position of an object can change whenever objects are added to or removed from the collection. You access an object in a collection by iterating through the collection, using the Count property of the collection. The Count property returns the number of items in the collection. You can also use the Item method to return an item in a collection.

For example, to display the names of worksheets in a Microsoft Excel workbook, use the following code:

Copy Code
oleApp = CREATEOBJECT("Excel.Application")
oleApp.Workbooks.Add
FOR EACH x IN oleApp.Workbooks
 ? x.Name
ENDFOR

You can also access a collection within a collection. For example, you can access a cells collection within a range using the following code:

Copy Code
oleApp = CREATEOBJECT("Excel.sheet")
oleApp.Workbooks.Add
oleApp.Range(oleApp.Cells(1,1),oleApp.Cells(10,10)).Value=100
oleApp.Visible=.T.

Using Arrays of Objects

You can pass arrays to methods, and you can receive arrays back. However, you must pass arrays by reference by prefixing the array name with the @ sign.

For example, to send a Visual FoxPro array to Microsoft Excel, consider the following code. It creates an array in Visual FoxPro, assigns the array some values, starts Microsoft Excel, creates a workbook, sets a value to the first cell of a worksheet, and then copies that value to the other sheets in the array:

Copy Code
DIMENSION aV(3)
aV(1) = "Sheet1"
aV(2) = "Sheet2"
aV(3) = "Sheet3"
oleApp=CREATEOBJECT("Excel.Application")
oleApp.Workbooks.Add
oleI=oleApp.Workbooks.Item(1)
oleI.Sheets.Item(1).Cells(1,1).Value = 83
oleI.Sheets(@aV).;
 FillAcrossSheets(oleI.Worksheets("Sheet1").Cells(1,1))

oleApp.Visible = .T.

Alternatively, the following example returns an array to Visual FoxPro and then displays the contents of the array:

Copy Code
oleApp = CREATEOBJECT("Excel.Application")
aOleArray = oleApp.GetCustomListContents(3)
FOR nIndex = 1 to ALEN(aOleArray)
   ? aOleArray(nIndex)
ENDFOR
Note:
With Visual FoxPro, you cannot pass arrays larger than two dimensions to OLE objects. For more information about working with arrays in Visual FoxPro, see Arrays and Object and Member Arrays.

Releasing Extrinsic Objects

An Automation server is automatically released if it is not visible and no variables in scope reference the object. You can use the RELEASE command to release the variable associated with an object. If the server is visible, use the Quit method to release it.

See Also

Other Resources

How to: Add OLE Objects to Applications
Sharing Information and Adding OLE
OLE Container Control
OLE Bound Control
Object Property


Optimizing Applications

Visual FoxPro 9.0
Optimizing Applications

When you use Visual FoxPro to design and run applications, you want to get the best performance from your operating system, from Visual FoxPro, and from your application.

In This Section

Optimizing Tables and Indexes

Describes how you can speed access to data in tables by using indexes and by using buffering efficiently. In addition, you can use Rushmore Query Optimization technology to optimize your queries.
Using Rushmore Query Optimization to Speed Data Access

Explains that Visual FoxPro includes Rushmore data access technology to help you optimize the performance of your applications.
Optimizing Forms and Controls

Describes how you can make significant improvements in the forms and controls in your application.
Optimizing Programs

Discusses how you can write the fastest possible programs by writing your code carefully.
Optimizing ActiveX Controls

Explains that if you use Automation or Microsoft ActiveX controls in your application, you can fine-tune the application to get the best performance out of both ActiveX controls and automation.
Optimizing Access to Remote Data

Describes the expense of data retrieval from any remote database.
Optimizing International Applications

Explains that if you are developing international applications, you might want to manage the collating sequence of your data for optimal performance.

Related Sections

Programming in Visual FoxPro

Describes how you can access the full power of Visual FoxPro by using object-oriented programming techniques and the event-driven model when creating applications.
Working with Programs

Describes how to write and work with Visual FoxPro program (.prg) files, which are text files containing instructions using the Visual FoxPro language.
Object-Oriented Programming

Describes how you can use object-oriented programming to create self-contained application components that respond to user actions and to the system and which can be easily maintained and reused.
Accessing APIs

Describes how to extend Visual FoxPro if your application has requirements that cannot be met by built in Visual FoxPro features by taking advantage of external libraries such as Microsoft® ActiveX® controls or dynamic-link libraries (DLLs).


Optimizing Tables and Indexes

Visual FoxPro 9.0
Optimizing Tables and Indexes
See Also

You can speed access to data in tables by using indexes and by using buffering efficiently. In addition, you can use Rushmore Query Optimization technology to optimize your queries.

Using Indexes

To speed up access to data in a table, use an index. Adding an index to a table speeds up searches, especially if you're able to use Rushmore technology to optimize your search. Indexing also allows you to work with data in a particular order, such as viewing a customer table in order by last name.

If the records in a table have unique keys, create a primary or candidate index on the field. These types of indexes allow Visual FoxPro to validate the key at a low level, resulting in best performance.

In addition to indexing fields used for searching and sorting, you should also index any fields involved in a join. If you join two tables on fields that are not indexed, the join operation can take as much as hundreds of times longer.

An important feature of Visual FoxPro is that you can create an index on any expression. (In some database products, you can index only on fields.) This capability allows you to use indexes to optimize searching, sorting, or joining on combinations of fields, or on expressions derived from fields. For example, you can index a name field based on an expression that uses the SOUNDEX( ) function. That way, your application can provide extremely quick access to names that sound alike.

When adding indexes to your tables, you must balance the benefit you get in retrieval times against a performance loss when updating the table. As you add more indexes to your table, updates and inserts to the table are slower because Visual FoxPro needs to update each index.

Finally, avoid using indexes on fields that contain only a few discrete values, such as a logical field. In these cases, the index contains only a small number of entries, and the overhead of maintaining the index probably outweighs the benefit it provides when searching.

For details about how to index effectively when using Rushmore technology, see Using Rushmore Query Optimization to Speed Data Access.

Optimizing Joins

When you create joins using SELECT - SQL, the following situations can degrade performance and produce unexpected results:

  • Joining tables on data that is not a primary or unique key in one of the tables.

  • Joining tables containing empty fields.

To avoid these situations, create joins based on the relationship between primary keys in one table and foreign keys in the other. If you create a join based on data that is not unique, the end result can be the product of two tables. For example, the following SELECT - SQL statement creates a join, which can produce a very large result:

Copy Code
SELECT *;
 FROM  tastrade!customer INNER JOIN tastrade!orders ;
 ON  Customer.postal_code = Orders.postal_code

In the example, postal code uniquely identifies a location within a city, but has little value if your intent is to match customer rows and their order rows. The postal code doesn't necessarily uniquely identify a customer or an order. Instead, create a join using a statement such as the following:

Copy Code
SELECT *;
 FROM  tastrade!customer INNER JOIN tastrade!orders ;
 ON  Customer.customer_id = Orders.customer_id

In this example, the field customer_id uniquely identifies a specific customer and the orders belonging to that customer, and therefore creates a result set that combines the customer row with each order row.

In addition, use caution when joining tables with empty fields because Visual FoxPro will match empty fields. However, Visual FoxPro doesn't match fields containing null. When creating a join, qualify the field expressions in the join condition by testing for an empty string.

For example, if you think that the customer id field in the Orders table might be empty, use a statement such as the following to filter out order records with no customer number:

Copy Code
SELECT *;
 FROM  tastrade!customer INNER JOIN tastrade!orders ;
 ON  Customer.customer_id = Orders.customer_id;
 WHERE tastrade!orders <> ""
Tip:
You can also test for an empty string using the EMPTY( ) function, but including a function call within the filter expression is not as fast as comparing to a constant value.

Using the Project Manager

When you use the Project Manager, you can combine an unlimited number of programs and procedures into a single .app or .exe file. This can greatly increase program execution speed for a couple of reasons.

First, Visual FoxPro opens a program file and leaves it open. Later, when you issue a DO command on a program contained in the file, Visual FoxPro doesn't need to open an additional file.

Second, an application of only one or two files reduces the number of files necessary in the working directory. The speed of all file operations increases as the operating system has fewer directory entries to examine when opening, renaming, or deleting files.

For information on using the Project Manager to create applications, see Compiling an Application.

General Table and Index Optimization Hints

To create the fastest possible tables and indexes, follow the recommendations listed below.

  • If record or table buffering is not enabled, use INSERT - SQL instead of APPEND BLANK followed by REPLACE, particularly with an indexed table in a multiuser environment, because indexes only need to be updated once.

  • If you need to append a large number of records to an indexed table, it might be faster to remove the index, append the records, and then re-create the index.

  • In SQL statements, avoid function calls if possible, especially in statements that will return more than one record, because the statement must be reevaluated (and the functions called again) for each record. If you are creating a SQL statement with variable data, use name expressions or macro substitution in favor of the EVALUATE( ) function. A better strategy yet is to construct the entire statement dynamically, not just individual clauses. For more information, see Using Macros and Creating Name Expressions.

  • If you usually use a certain index order, you can improve performance by periodically sorting the table in this order.

  • Use .cdx instead of .idx files in multiuser environments because you can update one .cdx file faster than you can update multiple .idx files.

See Also

Other Resources

Optimizing Applications
Optimizing Your System
Using Rushmore Query Optimization to Speed Data Access


Using Rushmore Query Optimization to Speed Data Access

Visual FoxPro 9.0
Using Rushmore Query Optimization to Speed Data Access
See Also

To help you optimize the performance of your applications, Visual FoxPro includes Rushmore Query Optimization data access technology. Using Rushmore technology, you can run certain complex table operations hundreds or even thousands of times faster than without it.

Understanding Rushmore Query Optimization Technology

Rushmore Query Optimization technology is a data access technique that uses standard Visual FoxPro indexes to optimize access to data. You can use Rushmore with any Visual FoxPro index, including FoxPro 1.x (.idx) indexes, compact (.idx) indexes, and compound (.cdx) indexes.

Both .cdx and compact .idx indexes use a compression technique that produces indexes as small as one-sixth the size of uncompressed old-format indexes. Visual FoxPro can process a compressed index faster because it requires less disk access, and because more of the index can be buffered in memory. Although Rushmore Query Optimization, like other file access techniques, benefits from the smaller size of compact indexes, it also functions very well with indexes in older formats.

When Visual FoxPro processes very large tables on computers with only the minimum amount of RAM, Rushmore might not find sufficient memory to operate. In that case, Visual FoxPro might display a warning message ("Not enough memory for optimization"). Although your program will function correctly and not lose any data, the query will not benefit from Rushmore optimization.

In its simplest form, Rushmore speeds the performance of single-table commands using FOR clauses that specify sets of records in terms of existing indexes. Also, Rushmore can speed the operation of certain commands such as LOCATE and INDEX. For a complete list of optimizable commands, see the next section, "Using Rushmore Query Optimization with Tables."

Visual FoxPro SQL commands use Rushmore as a basic tool in multi-table query optimization, using existing indexes and even creating new ad-hoc indexes to speed queries.

Using Rushmore Query Optimization with Tables

Use Rushmore to optimize data access according to the number of tables involved. When you access single tables, you can take advantage of Rushmore anywhere that a FOR clause appears. When you access multiple tables, SELECT - SQL queries supersede all Rushmore optimizations. In an SQL command, Visual FoxPro decides what is needed to optimize a query and does the work for you. You don't need to open tables or indexes. If SQL decides it needs indexes, it creates temporary indexes for its own use.

To use Rushmore Query Optimization

  1. To access data from a single table, use a FOR clause in a command such as AVERAGE, BROWSE, or LOCATE, or use SQL commands to update tables. For a complete list of commands that use the FOR clause, refer to the table below.

    -or-

  2. To access data from more than one table, use the SELECT - SQL, DELETE - SQL, and UPDATE - SQL commands.

The following table lists commands that use FOR clauses. Rushmore is designed so that its speed is proportional to the number of records retrieved.

Potentially Optimizable Commands with FOR Clauses

AVERAGE | BLANK
BROWSE | CALCULATE
CHANGE | COPY TO
COPY TO ARRAY | COUNT
DELETE | DISPLAY
EDIT | EXPORT TO
INDEX | JOIN WITH
LABEL | LIST
LOCATE | RECALL
REPLACE | REPLACE FROM ARRAY
REPORT | SCAN
SET DELETED | SET FILTER
SORT TO | SUM
TOTAL TO |

If you use a scope clause in addition to an optimizable FOR clause expression, the scope must be set to ALL or REST to take advantage of Rushmore. The NEXT or RECORD scope clauses disable Rushmore. Because the default scope is ALL for most commands, Rushmore works when you omit the scope clause.

Rushmore can use any open indexes except for filtered and UNIQUE indexes.

Note:
For optimal performance, don't set the order of the table.

Creating index or tags automatically sets the order. If you want to take maximum advantage of Rushmore with a large data set that must be in a specific order, issue SET ORDER TO to turn off index control, then use the SORT command.

Indexing Effectively for Rushmore Query Optimization

Rushmore cannot take advantage of all indexes. If you use a FOR clause in the INDEX command, Rushmore cannot use the index for optimization. For example, because it contains a FOR clause, this statement cannot be optimized, INDEX ON ORDNUM FOR DISCOUNT > 10 TAG ORDDISC.

Similarly, Rushmore cannot use an index created with a NOT condition. For example, the this expression can be optimized, INDEX ON DELETED() TAG DEL,But this one cannot, INDEX ON NOT DELETED() TAG NOTDEL.

In the special case that you want to exclude delete records from a query, using an index, as in the first example earlier, will speed up operations when you've set SET DELETED to ON.

Operating Without Rushmore Query Optimization

Data retrieval operations proceed without Rushmore optimization in the following situations:

  • When Rushmore cannot optimize the FOR clause expressions in a potentially optimizable command.

  • When a command that might benefit from Rushmore contains a WHILE clause.

  • When memory is low. Data retrieval continues, but is not optimized.

Disabling Rushmore Query Optimization

Though you rarely want to, you can disable Rushmore. When you issue a command that uses Rushmore, Visual FoxPro immediately determines which records match the FOR clause expression. These records are then manipulated by the command.

If a potentially optimizable command modifies the index key in the FOR clause, the recordset on which Rushmore is operating can become outdated. In this case, you can disable Rushmore to ensure that you have the most current information from the table.

To disable Rushmore for an individual command

  1. Use the NOOPTIMIZE clause.

    For example, this LOCATE command is not optimized:

    Copy Code
    LOCATE FOR DueDate < {^1998-01-01} NOOPTIMIZE

You can globally disable or enable Rushmore for all commands that benefit from Rushmore, with the SET OPTIMIZE command.

To disable Rushmore globally

  1. Use the following code:

    Copy Code
    SET OPTIMIZE OFF
To enable Rushmore globally

  1. Use the following code:

    Copy Code
    SET OPTIMIZE ON

The default setting of Rushmore optimization is ON.

Optimizing Rushmore Expressions

Rushmore technology depends on the presence of a basic optimizable expression in a FOR clause or in an SQL WHERE clause. A basic optimizable expression can form an entire expression or can appear as part of an expression. You can also combine basic expressions to form a complex optimizable expression.

Creating Basic Optimizable Expressions

A basic optimizable expression takes one of the two following forms:

Copy Code
              eIndex relOp eExp

-or-

Copy Code
              eExpr relOp eIndex

A basic optimizable expression has the following characteristics:

  • eIndex exactly matches the expression on which an index is constructed.

  • eExpr is any expression and can include variables and fields from other unrelated tables.

  • relOp is one of the following relational operators: <, >, =, <=, >=, <>, #, ==, or !=. You can also use the ISNULL( ), BETWEEN( ), or INLIST( ) functions (or their SQL equivalents such as IS NULL, and so on).

You can use BETWEEN( ) or INLIST( ) in the following two forms:

Copy Code
BETWEEN(eIndex, eExpr, eExpr)

-or-

Copy Code
INLIST(eIndex, eExpr [, eExpr, eExpr, ...])
Note:
ISBLANK() and EMPTY() are not optimizable by Rushmore.

If you create the indexes firstname, custno, UPPER(lastname), and hiredate, each of the following expressions is optimizable:

Copy Code
firstname = "Fred"
custno >= 1000
UPPER(lastname) = "SMITH"
hiredate < {^1997-12-30}

An optimizable expression can contain variables and functions that evaluate to a specific value. For example, using the index addr, if you issue the command STORE "WASHINGTON AVENUE" TO cVar, then the following statements are also basic optimizable expressions:

Copy Code
ADDR = cVar
ADDR = SUBSTR(cVar,8,3)

Understanding When Queries Are Optimized

It is important to understand when queries will be optimized and when they will not. Visual FoxPro optimizes search conditions by looking for an exact match between the left side of a filter expression and an index key expression. Therefore, Rushmore can optimize an expression only if you search against the exact expression used in an index.

For example, imagine that you've just created a table and are adding the first index using a command such as the following:

Copy Code
USE CUSTOMERS
INDEX ON UPPER(cu_name) TAG name

The following command is not optimizable, because the search condition is based on the field cu_name only, not on an expression that is indexed:

Copy Code
SELECT * FROM customers WHERE cu_name ="ACME"

Instead, you should create an optimizable expression using a command such as the following, in which the expression for which you are searching exactly matches an indexed expression:

Copy Code
SELECT * FROM customers WHERE UPPER(cu_name) = "ACME"
Tip:
To determine the level of Rushmore optimization being used, call SYS(3054).

Combining Basic Optimizable Expressions

You can combine simple or complex expressions based on the FOR clause or WHERE clause to increase data retrieval speed, if the FOR expressions have the characteristics of basic optimizable expressions.

Basic expressions might be optimizable. You can combine basic expressions using the AND, OR, and NOT logical operators to form a complex FOR clause expression that might also be optimizable. An expression created with a combination of optimizable basic expressions is fully optimizable. If one or more of the basic expressions are not optimizable, the complex expression might be partially optimizable or not optimizable at all.

A set of rules determines if an expression composed of basic optimizable or non-optimizable expressions is fully optimizable, partially optimizable, or not optimizable. The following table summarizes Rushmore query optimization rules.

Combining Basic Expressions

Basic Expression | Operator | Basic Expression | Query Result
Optimizable | AND | Optimizable | Fully Optimizable
Optimizable | OR | Optimizable | Fully Optimizable
Optimizable | AND | Not Optimizable | Partially Optimizable
Optimizable | OR | Not Optimizable | Not Optimizable
Not Optimizable | AND | Not Optimizable | Not Optimizable
Not Optimizable | OR | Not Optimizable | Not Optimizable
— | NOT | Optimizable | Fully Optimizable
— | NOT | Not Optimizable | Not Optimizable

You can use the AND operator to combine two optimizable expressions into one fully optimizable expression:

Copy Code
FIRSTNAME = "FRED" AND HIREDATE < {^1997-12-30}      && Optimizable

In this example, the OR operator combines a basic optimizable expression with an expression that is not optimizable to create an expression that is not optimizable:

Copy Code
FIRSTNAME = "FRED" OR "S" $ LASTNAME      && Not optimizable

Using the NOT operator on an optimizable expression creates a fully optimizable expression:

Copy Code
NOT FIRSTNAME = "FRED"      && Fully optimizable

You can also use parentheses to group combinations of basic expressions.

Combining Complex Expressions

Just as you can combine basic expressions, you can combine complex expressions to create a more complex expression that is fully optimizable, partially optimizable, or not optimizable. You can then combine these more complex expressions to create expressions that again might be fully or partially optimizable, or not optimizable at all. The following table describes the results of combining these complex expressions. These rules also apply to expressions grouped with parentheses.

Combining Complex Expressions

Expression | Operator | Expression | Result
Fully Optimizable | AND | Fully Optimizable | Fully Optimizable
Fully Optimizable | OR | Fully Optimizable | Fully Optimizable
Fully Optimizable | AND | Partially Optimizable | Partially Optimizable
Fully Optimizable | OR | Partially Optimizable | Partially Optimizable
Fully Optimizable | AND | Not Optimizable | Partially Optimizable
Fully Optimizable | OR | Not Optimizable | Not Optimizable
— | NOT | Fully Optimizable | Fully Optimizable
Partially Optimizable | AND | Partially Optimizable | Partially Optimizable
Partially Optimizable | OR | Partially Optimizable | Partially Optimizable
Partially Optimizable | AND | Not Optimizable | Partially Optimizable
Partially Optimizable | OR | Not Optimizable | Not Optimizable
— | NOT | Partially Optimizable | Not Optimizable
Not Optimizable | AND | Not Optimizable | Not Optimizable
Not Optimizable | OR | Not Optimizable | Not Optimizable
— | NOT | Not Optimizable | Not Optimizable

You can combine fully optimizable expressions with the OR operator to create one expression that is also fully optimizable:

Copy Code
* Fully-optimizable expression
(FIRSTNAME = "FRED" AND HIREDATE < {^1997-12-30}) ;
   OR (LASTNAME = "" AND HIREDATE > {^1996-12-30})

To create partially optimizable expressions, combine a fully optimizable expression with an expression that is not optimizable. In the following example, the AND operator is used to combine the expressions:

Copy Code
* Partially-optimizable expression
(FIRSTNAME = "FRED" AND HIREDATE < {^1997-12-30}) ;
   AND "S" $ LASTNAME

Partially optimizable expressions can be combined to create one expression that is also partially optimizable:

Copy Code
* Partially-optimizable expression
(FIRSTNAME = "FRED" AND "S" $ LASTNAME) ;
   OR (FIRSTNAME = "DAVE" AND "T" $ LASTNAME)

Combining expressions that are not optimizable creates an expression that is also not optimizable:

Copy Code
* Expression that is not optimizable
("FRED" $ FIRSTNAME OR "S" $ LASTNAME) ;
   OR ("MAIN" $ STREET OR "AVE" $ STREET)

See Also

Other Resources

Optimizing Applications
Optimizing Your System
LOCATE Command
INDEX Command


Optimizing Forms and Controls

Visual FoxPro 9.0
Optimizing Forms and Controls
See Also

You can make significant improvements to the forms and controls in your application by optimizing their performance.

For example, by using a data environment for a form or report, opening tables can be much faster than executing USE, SET ORDER, and SET RELATION commands in the form Load event. When you use the data environment, Visual FoxPro uses low-level engine calls to open the tables and set up the indexes and relations.

Limiting the Number of Forms in a Form Set

Use form sets only when it is necessary to have a group of forms share a private data session. When you use a form set, Visual FoxPro creates instances of all forms and all controls on all forms in the form set, even though the first form in the form set is the only one being displayed. This can be time consuming, and is unnecessary if the forms don't have to share a private data session. Instead, you should execute DO FORM for other forms when they're needed.

Note:
If you do use a form set, you will gain some performance when you access the forms in the form set because the forms will already be loaded but not visible.

Dynamically Loading Page Controls on a Page Frame

Page frames, like form sets, load all the controls for each page when the page frame is loaded, which can cause a noticeable delay when the page frame is loaded. Instead, you can dynamically load page controls, as needed, by creating a class out of the controls on each page, then loading them as the page is activated.

The following steps outline how to dynamically load page controls:

  1. Design your form as usual including all controls on all pages.

  2. When your design is complete, go to the second page of your page frame, and save the controls as a class.

  3. Open the class you created to make sure the controls are still properly laid out.

  4. Repeat Steps 2 and 3 for the third and subsequent pages of the page frame.

  5. In the Activate event of the second and subsequent pages of the page frame, add objects and make them visible.

    For example, if your controls class is named cnrpage1, you would add the following code:

    Copy Code
    IF THIS.ControlCount = 0
   THIS.AddObject("cnrpage1","cnrpage1")
   THIS.cnrpage1.Visible = .T.
ENDIF

Dynamically Binding Controls to Data

You can reduce the load time for a form that contains many data-bound controls if you delay the binding of those controls until needed.

The following steps describe the process for binding controls to data dynamically:

  1. Put the tables and views for your form in the data environment so that they open when the form loads.

  2. For each bound control, add code to its GotFocus event code that binds the control to the data value when the control receives focus.

    For example, the following code binds a ComboBox control to the customer.company field:

    Copy Code
    * Check to see if the control has been bound yet.
IF THIS.RecordSource = ""
   * Set the record source to the right value
   * and set the record source type to "fields"
   THIS.RecordSource = "customer.company"
   THIS.RecordSourceType = 6
   THIS.Refresh
ENDIF

Delaying Screen Refresh

If you must make several changes to the screen, for example, to change the values of several controls at once, you can reduce the overall time required to update the screen by delaying screen refresh until all changes are done.

For example, suppose that you want to make controls visible or invisible, change control colors, or move records in bound controls. It is recommended that you delay painting those controls until after completing changes to controls.

The following steps outline the process for delaying screen refresh:

  1. Set the form's LockScreen property to True (.T.).

  2. Update the controls as required.

  3. Call the form's Refresh method.

  4. Set the form's LockScreen property to False (.T.).

Tip:
This technique does not provide an increase in performance when updating single controls.

For example, the following code changes the display properties of several properties at once, moves to a new record, and only then refreshes the screen with new information. If LockScreen is not set to True, each of these operations repaint the affected controls individually and reduces performance of the update operation:

Copy Code
THISFORM.LockScreen = .T.
THISFORM.MyButton.Caption = "Save"
THISFORM.MyGrid.BackColor = RGB (255, 0, 0) && Red
SKIP IN customers
SKIP IN orders
THISFORM.Refresh
THISFORM.LockScreen = .F.

Reducing Code in Frequently-Used Methods

Because the Refresh method and Paint event are called frequently, you can improve performance in forms by reducing the amount of code in these methods. Similarly, to speed the load time for a form, you could move code from the Init event to a less frequently used event such as Activate, Click, and GotFocus. Then, you use a property on the control (such as Tag or a custom property) to keep track of whether the control has already run code that only needs to be run once.

See Also

Other Resources

Using Rushmore Query Optimization to Speed Data Access
Optimizing Applications
Optimizing Your System


Optimizing Programs

Visual FoxPro 9.0
Optimizing Programs
See Also

By writing your code carefully, you can write the fastest possible programs. There are several ways to improve program performance in Visual FoxPro:

  • Following the general programming performance hints provided below.

  • Using name expressions instead of macro substitution.

  • Referencing object properties efficiently.

General Programming Performance Hints

To write the fastest programs possible, follow the recommendations listed below.

  • Choose the correct data type for your data. In particular, use the Integer data type for numeric information whenever possible, as it is processed most efficiently. Wherever possible, use Integer data types for primary and foreign key values, which will result in smaller data files, smaller (and therefore faster) indexes, and faster joins.

    Note:
    For an example showing how to create a smaller (and therefore faster) index, run Solution.app, located in the Visual FoxPro ...\Samples\Solution directory. Choose View Samples by Filtered List, select Indexes from the drop-down list, and then choose Create Small Indexes Using BINTOC( ) from the list that appears.

  • Avoid reopening files, which slows performance. Instead, assign files to work areas as you open them, then use the SELECT command to choose a specific work area as needed.

  • Use FOR ... ENDFOR loops rather than DO WHILE ... ENDDO loops when possible, because they're faster.

  • When you copy data from multiple fields, SCATTER TO ARRAY is faster than SCATTER MEMVAR.

  • To use memory most efficiently, avoid creating objects before you need them, and clear objects when you finish with them to free memory.

    Tip:
    You can test how much memory each object consumes by calling the SYS(1016) function.

  • Send output to the topmost window whenever possible; updating windows behind the top window is substantially slower. Causing output to scroll behind a window is nearly a worst-case event.

  • Disable status display with the SET TALK OFF command, which eliminates the overhead of screen update.

  • Set the SET DOHISTORY command to OFF to avoid updating the command window each time a program runs.

Using Name Expressions Instead of Macro Substitution

If you use name expressions instead of macro substitution, program performance will greatly improve. For example, if you assign a value to the variable cFile, a name expression created with cFile is faster than macro substitution.

Copy Code
cFile = "CUST"
use &cFile      && Macro substitution, slow
use (cFile)      && Name expression: faster, preferred

Referencing Object Properties Efficiently

By understanding how Visual FoxPro works with properties and objects, you can make your applications run more efficiently.

Optimizing Repeated References to a Property

When you reference an object property with the object.property syntax, Visual FoxPro must search for the object before it can access the property. If you must access the property repeatedly, this search strategy can slow performance.

To avoid referencing the same procedure repeatedly (such as in a loop), read the property value into a variable, make changes, and then set the property when you're through. For example, the following code fills a property array by first creating an array in memory, filling it, and then setting the property only once at the end:

Copy Code
* Copy string to a local variable
lcChar = THISFORM.cCharString
LOCAL laCharArray[256]   && Create local array
FOR nCounter = 1 to 256
   laCharArray[x] = SUBSTR(laChar,x,1)
ENDFOR
* Copy the local array to the property array
ACOPY(laCharArray,THISFORM.aCharArray)

Referencing Multiple Properties Efficiently

If you update more than one property for the object, Visual FoxPro must search for the object multiple times, which can affect performance. In the following example, the code causes Visual FoxPro to search through four objects (such as THISFORM, pgfCstInfo, pgCstName, and txtName) to find the property to be set. Because the code sets two properties, the fourfold search is done twice:

Copy Code
THISFORM.pgfCstInfo.pgCstName.txtName.Value = ;
 "Fred Smith"
THISFORM.pgfCstInfo.pgCstName.txtName.BackColor = ;
 RGB (0,0,0)  & Dark red

To avoid this overhead, use the WITH ... ENDWITH command. This method causes Visual FoxPro to find the object once. For example, the following example accomplishes the same task as the previous one, but faster:

Copy Code
WITH THISFORM.pgfCstInfo.pgCstName.txtName
   .Value = "Fred Smith"
   .BackColor = RGB (0,0,0)  & Dark red
ENDWITH

You can also store an object reference in a variable, then include the variable in place of the object reference:

Copy Code
oControl = THISFORM.pgfCstInfo.pgCstName.txtName
oControl.Value = "Fred Smith"
oControl.BackColor = RGB (0,0,0)  & Dark red

See Also

Other Resources

Optimizing Applications
Optimizing Your System
SELECT Command
FOR ... ENDFOR Command
SCATTER Command


Optimizing ActiveX Controls

Visual FoxPro 9.0
Optimizing ActiveX Controls
See Also

If you use Automation or ActiveX controls in your application, you can fine-tune the application to get the best performance out of both ActiveX controls and Automation.

Using ActiveX Controls Efficiently

For best performance when using ActiveX controls in your forms, use the following suggestions:

  • Start Automation servers in advance. Controls bound to general fields will generally perform better when the servers for those data types (like Microsoft Excel or Word) are already running on the client's machine.

  • Insert objects "As Icon." When you insert an ActiveX control into a field, insert it as an icon or placeholder rather than as an entire object. This reduces the amount of storage space required because Visual FoxPro stores a presentation image with the object, which can consume a lot of storage space. Inserting an object as an icon also increases performance for drawing the object.

  • Use image controls. If you want to display a bitmap (such as a company logo), image controls are much faster than OLEBound controls.

  • Use manual links whenever possible. Manual links to objects are faster because they avoid the notification time required for automatic links, and because the server doesn't need to be started to draw the object. If you don't need to update an object frequently, use manual links.

Optimizing Automation Performance

If your application interacts with other applications, you can get the best performance using the following techniques.

Avoiding Multiple Instances of the Server

In some cases, Automation servers (such as Microsoft Excel) will always start a new instance, even if one is already running. To remedy this and improve performance, use the GetObject( ) function instead of CreateObject( ). For example, the following call will always use an existing instance, if it exists:

Copy Code
x = GetObject(,"excel.Application")

In contrast, the following call creates a new instance:

Copy Code
x = CreateObject("excel.Application")

If you call GetObject( ) but the server isn't already running, you will get error 1426. In that case, you can trap for the error and call CreateObject( ):

Copy Code
ON ERROR DO oleErr WITH ERROR()
x = GetObject(,"excel.application")
ON ERROR  && restore system error handler

PROCEDURE oleErr
PARAMETER mError
IF mError = 1426 then
 x = CreateObject("excel.application")
ENDIF

Referencing Objects Efficiently

Executing expressions that use objects within the Automation server can be expensive, particularly when evaluated multiple times. It is much faster to store objects' references to variables for reference.

See Also

Other Resources

Optimizing Applications in Multiuser Environments
Optimizing Access to Remote Data
Optimizing Applications
Optimizing Your System


Optimizing Access to Remote Data

Visual FoxPro 9.0
Optimizing Access to Remote Data
See Also

Data retrieval from any remote database is expensive. In order to get data from a server database, the following steps must occur:

  1. The client issues the query to the remote database.

  2. The server parses and compiles the query.

  3. The server generates a result set.

  4. The server notifies the client that the result is complete.

  5. The client fetches the data over the network from the server. This step can happen all at once, or the client can request that results be sent in pieces as requested.

You can use a number of techniques to speed up the retrieval (or update) of data, such as:

  • Retrieving only the data you need

  • Updating remote tables efficiently

  • Sending statements in a batch

  • Setting packet size

  • Delaying retrieval of memo and binary data

  • Storing lookup data locally

  • Creating local rules

Retrieving Only the Data You Need

In most applications that use remote data, forms and reports don't need to access all the data from a table at once. Therefore, you can speed performance by creating remote views that fetch or update only the fields and records you want, which minimizes the amount of data that needs to be transmitted across the network.

To create queries that minimize the overhead of data retrieval from remote sources, follow these suggestions:

  • Specify only the fields you need. Don't use the statement SELECT * FROM customers unless you need all the fields from the table.

  • Include a WHERE clause to limit the number of records downloaded. The more specific your WHERE clause, the fewer records are transmitted to your computer, and the faster the query will finish.

  • If you cannot predict at design time what values to use in a WHERE clause, you can use parameters in the clause. When the query is executed, Visual FoxPro uses the value of a parameter variable or prompts the user for the search value. For example, this query allows the application or user to fill in the region at run time:

    Copy Code
    SELECT cust_id, company, contact, address ;
   FROM customers ;
   WHERE region = ?pcRegion
  • Set the NoDataOnLoad property of the corresponding Data Environment Cursor object. This technique is commonly used with parameterized views in which the data for the parameter comes from the value of a control on a form.

Updating Remote Tables Efficiently

When you use a view to update a table on a remote data source, Visual FoxPro must check whether the record or records you are updating have been changed. To do so, Visual FoxPro must examine the data on the server and compare it to the data being held on your computer. In some instances, this can be a time-consuming operation.

To optimize the process of updating data on remote data sources, you can specify how Visual FoxPro should check for changed records. To do this, you indicate the WHERE clause that Visual FoxPro should generate in order to perform the update.

For example, imagine that you are using a view based on a customer table on a remote data source. You created the view using a SELECT - SQL statement such as this one:

Copy Code
SELECT cust_id, company, address, contact ;
   FROM customers ;
   WHERE region = ?vpRegion

You want to be able to update all four fields that you have specified in the view except the key field (cust_id). The following table illustrates the WHERE clause that Visual FoxPro will generate for each of the options available under the SQL WHERE clause.

Note:
The OLDVAL( ) function returns the pre-update version of fields you modified, and the CURVAL( ) function returns the current value stored on the remote data source. By comparing them, Visual FoxPro can determine whether the record has changed on the remote data source since you downloaded it to your computer.

Setting | Resulting WHERE clause
Key fields only | WHERE OLDVAL(cust_id) = CURVAL(cust_id)
Key and updatable fields (default) | WHERE OLDVAL(cust_id) = CURVAL(cust_id) AND OLDVAL(<mod_fld1>) = CURVAL(<mod_fld2>) AND OLDVAL(<mod_fld2>) = CURVAL(<mod_fld2>) AND ...
Key and modified fields | WHERE OLDVAL(cust_id) = CURVAL(cust_id) AND OLDVAL(company) = CURVAL(company) AND OLDVAL(contact) = CURVAL(contact) AND OLDVAL(address) = CURVAL(address)
Key and timestamp | WHERE OLDVAL(cust_id) = CURVAL(cust_id) AND OLDVAL(timestamp) = CURVAL(timestamp)

In general, you should choose an option for the SQL WHERE clause in this order of preference:

  1. Key and timestamp, if the remote database supports timestamped fields, which is the fastest way to tell if a record has changed.

  2. Key and modified fields, because the fields you update to the server are almost always a subset of the total number of fields that you could update.

  3. Key and updatable fields.

  4. Key fields only. Using these settings implies that the remote server will insert an entirely new record using the changed key, and will delete the old record.

Sending Statements in a Batch

Some servers (such as Microsoft SQL Server) allow you to send a batch of SQL statements in a single packet. This speeds performance because you reduce network traffic, and because the server can compile multiple statements at once.

For example, if you specify a batch size of four, then update 10 records in a database, Visual FoxPro sends four statements such as the following to the server database in one batch:

Copy Code
UPDATE customer SET contact = "John Jones" ;
   WHERE cust_id = 1;
UPDATE customer SET contact = "Sally Park" ;
   WHERE cust_id = 2;
UPDATE customer SET company = "John Jones" ;
   WHERE cust_id = 3;
UPDATE customer SET contact = "John Jones" ;
   WHERE cust_id = 4
To send statements in a batch

  1. In the Options dialog box, choose the Remote Data tab, and then under Records to batch update, specify the number of records to include in a batch.

    -or-

  2. Call the DBSETPROP( ) or CURSORSETPROP( ) functions to set these properties:

    • Set Transaction to 2.

    • Set BatchUpdateCount to the number of statements to send in a batch.

      -or-

  1. In the View Designer, choose Advanced Options from the Query menu to display the Advanced Options dialog box.

  2. In the Performance area, next to Number of records to batch update, specify the number of statements to send in a batch.

    Note:
    You should experiment with different values for this property and the PacketSize property to optimize your updates.

Setting Packet Size

You can optimize access to remote servers by fine-tuning the size of the network packet that is sent to and retrieved from the remote database. For example, if your network supports large packet sizes (greater than 4,096 bytes), you can increase the packet size in Visual FoxPro in order to send more data each time you read or write to the network.

To set packet size

  1. Call the DBSETPROP( ) or CURSORSETPROP( ) functions and set the PacketSize property to a positive integer value. The default value is 4,096.

    Note:
    Different network providers will handle this property differently, so you should consult your network service documentation. Novell NetWare, for example, has a maximum packet size of 512 bytes so setting the PacketSize property to a value greater than this will have no additional benefit.

Delaying Retrieval of Memo and Binary Data

If you're storing Memo or binary data on a remote server, you can improve performance by delaying the download of this data until your application actually requires it.

To delay retrieval of memo and binary data

  1. In the Options dialog box, choose the Remote Data tab, and then under Remote view defaults, set Fetch memo.

    -or-

  2. Call the DBSETPROP( ) or CURSORSETPROP( ) functions to set the FetchMemo property.

Storing Lookup Data Locally

Many applications include static lookup data such as state abbreviations, postal codes, and employee titles. If your application contains this type of data, and if the table is not too large, you might be able to speed up your application by keeping copies of this information on each user's computer, because lookups do not generate network traffic.

This technique is primarily useful for data that never changes or changes very rarely. If the data does change on occasion, you must devise a strategy for downloading a new copy of the lookup table to each user's computer.

Creating Local Rules

You can gain efficiency in your application by creating local field-level and record-level rules within Visual FoxPro, rather than relying on rules defined on the server. These rules can prevent data that doesn't conform to data or business rules from getting into the database.

By defining rules in Visual FoxPro, you trap the invalid data before it's sent across the network, which is faster, and which gives you better control for handling error conditions. However, using local rules also means that you must coordinate them with rules on the remote server. For example, if there are changes to the rules on the server, you might have to change your local rules to match.

For more information, see How to: Create Validation Rules for Views.

See Also

Other Resources

Optimizing Applications in Multiuser Environments
Optimizing Applications
Optimizing Your System
NoDataOnLoad Property
SELECT - SQL Command


Optimizing International Applications

Visual FoxPro 9.0
Optimizing International Applications
See Also

If you are developing international applications, you might need to manage the collating sequence of your data for optimal performance. This section discusses:

  • Using collating sequence efficiently.

  • Using SELECT - SQL with multiple collating sequences.

Using Collating Sequence Efficiently

If your data does not include diacritical marks, such as accents () or umlauts (), you can improve performance by using the machine collating sequence because:

  • Non-machine index keys are twice as large because they contain the diacritical information.

  • Non-machine collation uses many special rules for indexing characters to return proper results.

Because the machine collate sequence is faster, it is usually preferred for joins and searching, while other collate sequences are perfect for ordering records.

When you create an index, Visual FoxPro uses the current collating sequence set by using the SET COLLATE, CREATE TABLE - SQL, ALTER TABLE - SQL, or INDEX commands. For example, if you want to create two indexes with two collating sequences, you can use SET COLLATE and a sequence of commands such as the following:

Copy Code
SET COLLATE TO "MACHINE"
INDEX ON lastname TAG _lastname     && Join or seek index.
SET COLLATE TO "GENERAL"
INDEX ON lastname TAG lastname  && Sort index.

When you want to seek, select, or join on the field lastname, issue the command SET COLLATE TO "MACHINE" before performing the operation. Rushmore Query Optimization uses the index created in the machine collate sequence, and the search operation runs very quickly.

Using SQL SELECT with Multiple Collating Sequences

When you issue a SELECT - SQL command, Visual FoxPro uses the current collating sequence for searching and for the ORDER BY and GROUP BY clauses. If you want to search and sort using different collating sequences, you can split your SQL commands into two steps as follows:

Copy Code
* Select records using one collating sequence.
SET COLLATE TO "MACHINE"
SELECT * FROM table INTO CURSOR temp1 ;
  WHERE lname = "Mller"
* Order records using a different collating sequence.
SET COLLATE TO "GENERAL"
SELECT * FROM temp1 INTO TABLE output ORDER BY lastname

See Also

Other Resources

Optimizing Access to Remote Data
Optimizing Applications
Optimizing Your System
Optimizing ActiveX Controls


Testing and Debugging Applications

Visual FoxPro 9.0
Testing and Debugging Applications

Testing involves finding problems in your code, while debugging consists of isolating and fixing the problems. Testing and debugging are necessary stages in the development cycle and are best incorporated early in the cycle. Thoroughly testing and debugging individual components makes testing and debugging integrated applications much easier.

When testing and debugging applications, developers typically look for different levels of robustness:

  • Running without generating error messages or crashing.

  • Appropriate action in common scenarios.

  • Reasonable action or error messages in a range of scenarios.

  • Graceful recovery from unexpected user interactions.

Visual FoxPro provides a rich set of tools to help you isolate and identify problems in code so that you can fix them effectively.

In This Section

Debugging Before Bugs Exist

Explains good coding practices and steps you can take early in the development cycle to reduce the number of bugs in code.
How to: Test a Project

Describes how to test and verify your application project before building a distributable for your application.
How to: View and Save Build Messages

Describes how to view and save build status and error messages to an error file as they occur during the build process.
Handling Run-Time Errors

Introduces different ways to handle errors that occur at run time.
Using the Debugger

Describes how to use the Visual FoxPro debugging environment to isolate those problems identified through testing.

Related Sections

Debugging and Error Handling Language

Lists Visual FoxPro language that you can use to perform debugging and error-handling operations in Visual FoxPro programs.
Compiling an Application

Discusses how to use the modular approach to make it possible to verify the functionality of each component you create. Then you can compile them into an application, which assembles the executable components of your project.
Distributing Applications

Discusses how to prepare to distribute your application by including all required files and creating distribution disks, after you have completed developing and testing your application.
Developing Visual FoxPro Applications

Provides conceptual information about how to develop Visual FoxPro applications, including instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.


Debugging Before Bugs Exist

Visual FoxPro 9.0
Debugging Before Bugs Exist
See Also

Good coding practices, such as using white space, including comments, and adhering to naming conventions, help reduce the number of bugs in your code. However, one of the best ways to create a robust application is to look for potential problems before they occur. To make testing and debugging easier later, take the following steps early in the development process:

  • Creating a Test Environment

  • Writing Code to Avoid Errors

  • Setting Asserts

  • Tracking Event Sequences

Creating a Test Environment

Though the data environment you have set up for the application is important, the system environment that you expect an application to run in is just as important. To ensure portability of your application and to create an appropriate environment for testing and debugging, you need to consider the following items:

  • Hardware and software.

  • System paths and file properties.

  • Directory structure and file locations.

Hardware and Software

For maximum portability, it is recommended that you develop applications on the lowest common platform you expect them to run on. To establish a baseline platform, use the following guidelines:

  • Develop your applications using the lowest common video mode.

  • Determine base requirements for RAM and media storage space, including any necessary drivers or concurrently running software.

  • Consider special memory, file, and record-locking scenarios for network versus stand-alone versions of applications.

System Paths and File Properties

To ensure all necessary program files are readily accessible on each computer that runs your application, you might require a baseline file configuration. To help you define a configuration baseline, consider the following questions:

  • Does your application require common system paths?

  • Have you set appropriate file access properties?

  • Are network permissions set correctly for each user?

Directory Structure and File Locations

If your source code references absolute paths or file names, those exact paths and files must exist when your application is installed on any other computer. Avoid this scenario by performing the following tasks:

  • Use Visual FoxPro configuration files. For additional information on using configuration files, see Customizing the Visual FoxPro Environment .

  • Create a separate directory or directory structure to keep source files apart from the generated application files. This way, you can test the references of the completed application and know exactly which files to distribute.

  • Use relative paths.

Writing Code to Avoid Errors

You can help reduce errors by anticipating where they might occur and write code that avoids those errors.

The following table illustrates how to avoid example error conditions.

Error condition How to avoid the error

The SKIP command moves the record pointer in a table to the next record. However, if the record pointer has moved past the last record in the table, then calling the SKIP command generates an error.

Check for end of file:

Copy Code
IF !EOF()
   SKIP
      IF EOF()
         GO BOTTOM
      ENDIF
ENDIF

The following line of code displays the Open dialog box so that a user can open a table in a new work area:

Copy Code
USE GETFILE('DBF') IN 0

The user can choose Cancel in the Open dialog box or type the name of a file that does not exist. The user might also type the name of a file that is not a Visual FoxPro table.

Make sure that the file exists before the user tries to use it:

Copy Code
cNewTable = GETFILE('DBF')
IF FILE(cNewTable)
   USE (cNewTable) IN 0
ENDIF

If the user types the name of a file that is not a Visual FoxPro table, and error message 15, "Not a table" occurs, you can display a message that prompts the user to open another file, for example, "Please open another file. This file is not a table."

Setting Asserts

Asserts display message boxes when a logical expression evaluates to False (.F.). You can include asserts in your code to verify assumptions you have about the run-time environment for the code. You can use the ASSERT command to set asserts. For more information, see ASSERT Command.

Tracking Event Sequences

By tracking event sequences in relation to other events, you can determine the most efficient location to add code to events. For more information, see How to: Track Event Sequences.

See Also

Other Resources

Testing and Debugging Applications
How to: Use the Automated Test Harness


How to: Test a Project

Visual FoxPro 9.0
How to: Test a Project
See Also

Before building an application, you can test the project to verify references and check that all components are available. Testing a project rebuilds the project, which forces Visual FoxPro to resolve file references and recompile outdated files.

Tip:
To step through code more easily, mark locations in the code by using bookmarks, shortcuts, and breakpoints. For details, see How to: Create Bookmarks and Task List Shortcuts.

You can test projects using the Project Manager or the BUILD PROJECT command. However, more options are available when you use the Project Manager. For more information, see BUILD PROJECT Command.

To test a project

  1. Open the project for your application.

  2. In the Project Manager, click Build.

  3. In the Build Options dialog box, select Rebuild project.

  4. Select any other options you want and click OK.

    Tip:
    You can view and save build messages that occur during the build process. For more information, see How to: View and Save Build Messages.

For more information, see Project Manager Window and Build Options Dialog Box.

Tip:
After the project builds successfully, run the project before building the application file. As you add components to your project, it is recommended that you test and run your project after adding each component.

To run the project

  • In the Project Manager, select the main program, and then click Run.

You can also run projects by using the DO command with the name of the main program. For example, typing the following line of code in the Command window runs a project containing the program, Main.prg:

Copy Code
DO Main.prg

If the program runs correctly, you can build an application file that contains all the files in the project. For more information, see Compiling an Application.

See Also

Other Resources

Testing and Debugging Applications
How to: Use the Automated Test Harness
How to: Log Code Coverage


How to: View and Save Build Messages

Visual FoxPro 9.0
How to: View and Save Build Messages
See Also

When you build a project, application, or dynamic-link library, Visual FoxPro includes build status and error messages in an error file, which is a text file with the .err file name extension, as they occur during the build process. The .err file has the same base name as your project and is created in the current directory. When you compile or recompile a project, application, or dynamic-link library, compile messages are also included in the same .err file.

If the build process is interrupted, you can open the .err file to review these messages. You can also select the Display Errors option in the Build Options dialog box to display an editing window for the .err file after the build process completes so you can review any errors.

Note:
If no errors occur during the build, the .err file is removed.

During the build process, build status messages appear in the status bar. After the build process completes, the number of build errors appear in the status bar.

To display or view the error file

  1. Build the project, application, or dynamic-link library file by following the steps in How to: Test a Project or How to: Build Applications.

  2. To display the error file automatically after the build process completes, when the Build Options dialog box is open, select the Display Errors check box.

    -OR-

    To view the error file after the build process completes, on the Project menu, choose Errors.

For more information, see Build Options Dialog Box.

You can also specify whether to include compile messages by using the SET LOGERRORS command. For more information, see SET LOGERRORS Command.

You can also view and save build status messages that appear in the Debug Output window when it is open in the Debugger. For more information, see Debug Output Window and Debugger Window.

To include compile error messages in the error file

  1. Build the project, application, or dynamic-link library file by following the steps in How to: Test a Project or How to: Build Applications, respectively.

  2. In the Build Options dialog box, select the Recompile All Files check box.

See Also

Other Resources

Testing and Debugging Applications


Handling Run-Time Errors

Visual FoxPro 9.0
Handling Run-Time Errors
See Also

After an application starts executing, errors can occur at run time. For example, errors can occur at run time from the following actions:

  • Writing to a file that does not exist.

  • Attempting to open an open table or select a closed table.

  • Encountering a data conflict.

  • Dividing a value by zero.

You can handle such errors, including errors that occur in reports and those due to tables with bad database back links, by using the error handlers that Visual FoxPro provides. However, if your application does not contain error-handling routines when an error occurs at run time, the application pauses, and the appropriate Visual FoxPro system error message appears with the following buttons:

  • Cancel If a user chooses Cancel, the application immediately stops running and returns control to the system.

  • Ignore If a user chooses Ignore, Visual FoxPro ignores the line that caused the error and continues to the next line in the program.

For a list and explanation of Visual FoxPro error messages, see Error Messages.

Tip:
For errors that you cannot avoid, make sure to provide documentation that describes errors that users might see and suggest ways to correct those errors.

Using Error Handling Routines

You can use the Visual FoxPro language to create error-handling routines for error conditions. The following topics explain several mechanisms for handling run-time errors in code and the order of their operation:

  • Procedural Error Handling

    Discusses using the ON ERROR command to handle errors in procedural code.

  • Class and Object Error Handling

    Discusses using the Error event to handle local errors for objects and classes.

  • Structured Error Handling

    Discusses using the TRY...CATCH...FINALLY control structure to handle errors or exceptions that can occur at run time.

  • Error Handler Priority

    Discusses the order of priority for error-handling routines.

Running the Most Recently Executed Line of Code

You can use the RETRY command, except with TRY...CATCH...FINALLY, to run a line of code that caused an error after changing conditions that caused the error.

Note:
Sometimes, the line of code that caused an error does not exist for you to execute with RETRY. The Error event can occur even when the error encountered is not associated with a line of your code. For example, if you call a data environment's CloseTables method in code when the AutoCloseTables property is set to True (.T.) and then release the form, Visual FoxPro generates an internal error when it attempts to close the tables again. You can trap the error; however, no line of code exists for you to execute with RETRY.

For more information, see RETRY Command.

See Also

Concepts

Handling Errors During Report Runs

Other Resources

Debugging and Error-Handling Language
Testing and Debugging Applications


Procedural Error Handling

Visual FoxPro 9.0
Procedural Error Handling
See Also

You can detect and handle errors in a single or multiple lines of code by using the ON ERROR command and specifying any valid command or expression. However, you typically use the DO command to specify an error-handling procedure or program. Typically, you use ON ERROR as the overall error handler in your application for those errors that more local error handlers, such as Error events and TRY...CATCH...FINALLY, do not handle.

For example, suppose you have the following invalid line of code in a program (.prg) file:

Copy Code
qxy

When you run the program, Visual FoxPro displays the appropriate error message, "Unrecognized command verb." However, you can create an ON ERROR routine to detect this invalid command and run a procedure or program that handles this error. The following lines of code precede the invalid command with the ON ERROR command, which includes the ERROR( ) function and display the results using the ? command:

Copy Code
ON ERROR ?ERROR()
qxy

When these lines of code run, the ON ERROR command detects the error and displays the error number returned by the ERROR( ) function for the error message, "Unrecognized command verb", in the active output window instead of the error message itself.

In its basic form, the following code illustrates an ON ERROR routine:

Copy Code
LOCAL lcOldOnError
lcOldOnError = ON("ERROR") && Save default error handler.

* Call ON ERROR with an error procedure.
ON ERROR DO ErrHandler WITH ERROR(), MESSAGE()

* Insert code that error handling routine applies to.

* Reset original error handler.
ON ERROR &lcOldOnError

PROCEDURE ErrHandler
   LOCAL aErrInfo[1]
   AERROR(aErrInfo)
   DO CASE
      CASE aErrInfo[1] = ErrorNum && Specify appropriate error number.
         * Display appropriate message and insert code to fix error.
      OTHERWISE
         * Display generic message.
ENDPROC

For more information, see ON ERROR Command. You can also include other error handlers, such as TRY...CATCH...FINALLY in procedural code.

See Also

Other Resources

Debugging and Error-Handling Language
Structured Error Handling
Class and Object Error Handling
Handling Run-Time Errors


Class and Object Error Handling

Visual FoxPro 9.0
Class and Object Error Handling
See Also

You can handle errors that occur in objects at run time by adding error-handling code to the Error event of an object or class definition. If you want an object to have its own error-handling behavior, add error-handling code to the object's Error event. The error-handling behavior you specify applies to that particular object only.

If you want all objects based on a particular class to use the same error-handling behavior, add Error event code to the class definition, for example, for a custom class or subclass. All objects instantiated from the class contain the same error-handling behavior. If the class or subclass does not contain Error event code, it inherits error-handling behavior from the parent class. If Error event code does not exist in the parent class, Visual FoxPro searches for Error event code in another class up the class hierarchy. You can also use the NODEFAULT command and DODEFAULT( ) function to override or call code from the parent class. For more information, see Overriding and Calling Parent Class Code.

If and when an error occurs in the object at run time, Visual FoxPro searches for Error event code in the object's Error event, the Error event of the base class, or up the class hierarchy for that object, and runs that code, if it exists. Other error handlers might affect how Visual FoxPro handles errors. For more information, see Error Handler Priority.

Error Handling for Objects in Containers

For member objects instantiated within another object or container, for example, controls on a form, you can specify error handling for each member object by adding Error event code for each member object. However, if Error event code does not exist for the member object, it does not inherit Error event code from the container object automatically. If you want the container object's Error event to handle errors for its member objects, you can pass error information from the member object's Error event to container's Error event by using the following code in the member object's Error event:

Copy Code
LPARAMETERS nError, cMethod, nLine
THIS.Parent.Error(nError, cMethod, nLine)

You can add code in the container object's Error event to process the error information passed through the parameters specified in this code.

For example, the Vcr class in the Visual FoxPro sample class library, Buttons.vcx, located in the Visual FoxPro ...\Samples\Classes directory, is based on the Visual FoxPro Container class. The container has four command buttons that navigate a table by moving the record pointer.

However, when a user clicks a button when a table is not open, an error can occur. Visual FoxPro attempts to write buffered values to a table when the record pointer moves; therefore, if optimistic row buffering is enabled and another user has changed a value in the buffered record, another error can also occur.

These errors can occur when the user chooses any button; therefore, you do not need to write four separate error-handling routines for each button. Instead, each command button's Error event contains code to pass error information to a single error-handling routine in the Error event for the Vcr class.

You can also include other error handlers, such as the TRY...CATCH...FINALLY and ON ERROR commands, in class definitions and objects. For more information about the order and priority in which error handlers operate, see Error Handler Priority.

See Also

Other Resources

Debugging and Error-Handling Language
Structured Error Handling
Procedural Error Handling
Handling Run-Time Errors


Structured Error Handling

Visual FoxPro 9.0
Structured Error Handling
See Also

You can use the TRY...CATCH...FINALLY command as a control structure to handle errors, or exceptions, that might occur in your code at run time. The TRY...CATCH...FINALLY structure contains TRY, CATCH, and FINALLY code blocks so you can specify statements that might generate errors, statements to handle those errors, and statements to perform clean up operations.

The TRY...CATCH...FINALLY structure begins with the TRY statement, which marks the beginning of the TRY block. In the TRY block, you can specify code that might produce errors at run time. If your program completes the TRY block without generating an error, or exception, it skips the CATCH block and searches for the FINALLY block near the end of the structure, if it exists, and runs the corresponding statements. If the FINALLY block does not exist, the program execution continues outside the structure at the first statement following the ENDTRY statement, which marks the end of the TRY...CATCH...FINALLY structure.

Note:
Visual FoxPro permits the existence of TRY...CATCH...FINALLY structures that do not have CATCH and FINALLY blocks, which escalate the error to a higher-level error handler.

You can also nest TRY...CATCH...FINALLY structures in a TRY, CATCH, or FINALLY block.

The following sections describe the error-handling tasks you can perform in these code blocks:

  • Generating Exceptions

  • Catching Exceptions

  • Escalating Exceptions

  • Exiting TRY...CATCH...FINALLY Immediately

  • Using Commands in TRY...CATCH...FINALLY

  • Running FINALLY Statements

For more information, see TRY...CATCH...FINALLY Command.

Generating Exceptions

Visual FoxPro generates or "throws" an exception and creates an Exception object, which contains details about the error, when an error occurs in a TRY block in the following locations:

  • A line of code. This includes calls to external procedures that contain errors but does not contain their own error handlers.

  • A method call for an object when the method code contains errors, and the object does not contain Error event code.

    Otherwise, if Error event code exists, the Error event for that object handles the error unless the method contains its own TRY...CATCH...FINALLY error handler.

Note:
You cannot run code when the Exception object is created. The Exception object created always exists as an instance of the Exception base class. If you want to use a subclass of the Exception class, you should rethrow the exception in the CATCH or FINALLY block. Only Visual FoxPro program (.prg) files support Exception objects, though you can throw exceptions from forms run in the design environment. You cannot throw Exception objects from COM objects in dynamic-link library (.dll) files or executable (.exe) files. For more information, see Exception Class.

After the error occurs, Visual FoxPro handles or "catches" the exception by moving to the first CATCH statement, and searches for appropriate statements in the CATCH block to handle the exception.

Catching Exceptions

The program looks at the CATCH statements in the order that they appear in the CATCH block to determine statements exist to handle the exception. If the program finds a CATCH statement that handles the exception, the program runs the corresponding code.

The CATCH statement can contain optional TO and WHEN clauses. You can store a reference to the created Exception object by specifying a memory variable using the VarName parameter in the TO clause. If you want to establish a condition for a CATCH block to run, you can specify a logical expression in the WHEN clause that must evaluate to True (.T.) before statements in the CATCH block run. CATCH statements work similarly to CASE statements in that the WHEN clause must evaluate to a logical expression. If the TO and WHEN clauses do not exist, the CATCH statement evaluates as CATCH WHEN .T. (True).

After the program runs statements in a CATCH block, it does not return to the TRY statement, and it does not look for other CATCH statements. Instead, the program proceeds directly to the FINALLY statement, if it exists, to run any remaining statements. Otherwise, the program exits the TRY...CATCH...FINALLY structure and moves to the statement that immediately follows ENDTRY.

Escalating Exceptions

If you want to escalate or "rethrow" the exception to a higher-level error handler, you can include a THROW statement. You can call THROW from any code block of a TRY...CATCH...FINALLY structure. However, you can use THROW anywhere in code where an error handler exists to catch the exception. You cannot call THROW from the Command window.

Caution:
Calling the THROW command outside the TRY...CATCH...FINALLY structure and without an appropriate error handler causes your program to quit.

If you use THROW outside the TRY...CATCH section where the thrown exception is handled by an ON ERROR routine or the Visual FoxPro system instead of an Error event, program execution does not return to the location where the THROW statement occurs. The following example shows how the line of code, ?2, does not execute. This behavior differs from a traditional error behavior in which program execution returns to the location where the error occurred:

Copy Code
ON ERROR ? ERROR()
DO myProc1

PROCEDURE myProc1
   ?1
   THROW 11
   ?2
ENDPROC

Remember, the intention for calling THROW is to escalate the exception to a higher-level error handler.

If an outer TRY...CATCH block exists around a THROW statement when it is called from within a CATCH or FINALLY block, Visual FoxPro reassigns the memory variable specified in the TO clause from the object reference of the previous exception object to an object reference for the most recent exception object created by the thrown exception. If no outer TRY...CATCH structure exists, Visual FoxPro throws the exception to an ON ERROR routine or an error event, if they exist. Otherwise, Visual FoxPro displays the appropriate system error message.

Exiting TRY...CATCH...FINALLY Immediately

You can exit a code block immediately by including an EXIT statement in a TRY or CATCH block. The program resumes running code at the FINALLY statement, if one exists, or at the line immediately following the ENDTRY statement.

Using Commands in TRY...CATCH...FINALLY

You can use different Visual FoxPro commands that affect how code normally runs from within a TRY or CATCH block. However, if you use one of these commands that are not permitted for a specific block, Visual FoxPro generates an error at run time. The FINALLY statements always run before handling these commands except when CANCEL or QUIT is used. The following table lists the Visual FoxPro commands you can and cannot use in a TRY, CATCH, or FINALLY block.

Command | TRY | CATCH | FINALLY
CANCEL | Yes | Yes | Yes
CLEAR ALL | Yes | No | No
CLOSE ALL | Yes | Yes | Yes
DOEVENTS | Yes | Yes | Yes
ERROR | Yes | Yes | Yes
EXIT | Yes | Yes | Yes
LOOP | No | No | No
QUIT | Yes | Yes | Yes
RELEASE | Yes | Yes | Yes
RESUME | Yes | Yes | Yes
RETRY | No | No | No
RETURN | No | No | No
RETURN TO MASTER | No | No | No
RETURN TO <ProcedureName> | No | No | No
SET STEP ON | Yes | Yes | Yes
SUSPEND | Yes | Yes | Yes
THROW | Yes | Yes | Yes
Note:
You can include commands such as LOOP in a block as long as you place it inside an embedded control statement such as FOR EACH...ENDOR or DO WHILE...ENDDO. You can call the ERROR command from the TRY, CATCH, or FINALLY blocks. TRY...CATCH...FINALLY handles the ERROR command like any other exception or use of the THROW command.

Running FINALLY Statements

If the program locates the FINALLY statement, it runs the code that is in the FINALLY block. The FINALLY block usually cleans up any resources allocated by the TRY block and is always the last code to run before control leaves the TRY...CATCH...FINALLY structure.

The FINALLY block always runs when an exception, unhandled or otherwise, occurs, even if another exception handler such as the ON ERROR routine or an object's Error event is in effect.

Note:
You cannot explicitly transfer control of your program directly to a CATCH or FINALLY block. You cannot bypass the FINALLY statement if it exists unless you use the CANCEL command to stop the program from continuing. If you wish to bypass the FINALLY statement, you need to provide code at the beginning of the FINALLY block that checks for a condition and breaks out of the block if that condition is met.

After the FINALLY block runs, the program then proceeds to the statement immediately following the ENDTRY statement. The ENDTRY statement ends the TRY...CATCH...FINALLY structure.

See Also

Other Resources

Class and Object Error Handling
Procedural Error Handling
Error Handler Priority
Debugging and Error-Handling Language
Handling Run-Time Errors
Testing and Debugging Applications


Error Handler Priority

Visual FoxPro 9.0
Error Handler Priority
See Also

Visual FoxPro provides several error handlers you can use to detect and handle errors in code.

Caution:
The use of TRY...CATCH statements in a method whose class definition does not have Error event or method code might impact existing code and possibly break backward compatibility. Therefore, TRY...CATCH statements in methods should call only other object methods that contain Error event or method code.

The following table summarizes the priority of error handlers.

When only the following error handler exists Error handler priority

None or no existing error handlers can handle the error

Visual FoxPro system error message

ON ERROR command

ON ERROR takes precedence until another ON ERROR is called or the Visual FoxPro error message system is restored.

Otherwise, Visual FoxPro displays a system error message.

TRY...CATCH...FINALLY command

TRY...CATCH...FINALLY takes precedence when an error occurs in TRY block.

Otherwise, Visual FoxPro displays a system error message.

Error event or method

Error takes precedence when an error occurs in an object's method code.

Otherwise, Visual FoxPro displays a system error message.

TRY...CATCH...FINALLY command ON ERROR command

TRY...CATCH...FINALLY takes precedence when an error occurs in a TRY block.

ON ERROR takes precedence when:

  • An error occurs outside the TRY block.

  • An error occurs in the CATCH block.

  • An error occurs in the FINALLY block.

Otherwise, Visual FoxPro displays a system error message.

Error event or methodON ERROR command

Error takes precedence when an error occurs in object method code.

ON ERROR takes precedence when:

  • An error occurs outside a class definition.

  • An error occurs inside a class definition but outside method code. The error is detected at the point of instantiating the object.

Otherwise, Visual FoxPro displays a system error message.

TRY...CATCH...FINALLY commandError event or method

TRY...CATCH...FINALLY takes precedence when:

  • An error occurs in a TRY block outside a class definition.

  • An error occurs inside an object's method code and is within a TRY block.

  • An error originates in a class definition outside method code but occurs in a TRY block outside the class definition.

  • An error occurs in a TRY block inside external procedure or object method code, and the method or procedure is called directly or from another method, regardless of whether the method call appears inside or outside a TRY block.

Error takes precedence when:

  • An error occurs inside method code but outside a TRY block.

  • An error occurs in an object's method code, and the method is called directly or is called from another method, regardless of whether the method call appears inside or outside a TRY block.

    Note:
    If the method call is in a TRY block, and no immediate Error event or method code exists for the object, Visual FoxPro searches for Error code inherited from the parent class or another class up the class hierarchy. If no Error code exists in the class hierarchy, Visual FoxPro looks for a CATCH block corresponding to the TRY block from which the method was called.

Otherwise, Visual FoxPro displays a system error message.

Summary of Error Handling in Object Method Code

For errors that occur in an object's method code, the order of priority for error handlers is summarized as follows:

  • Immediate TRY...CATCH, if it exists, in the same method that the error occurs. This applies also to external procedures that a method calls.

  • Error event, if it exists, for the object.

  • TRY...CATCH at the next level up in the calling chain or in a higher-level method.

  • ON ERROR routine, if it exists.

  • Visual FoxPro system error message.

For more information error handling priority within TRY...CATCH...FINALLY structures, see Error Handling Priority in TRY...CATCH...FINALLY Structures. For more information about error handling priority in classes and objects, see Error Handling Priority in Classes and Objects.

Error Handling Priority in TRY...CATCH...FINALLY Structures

The following table summarizes the sequence of actions when handling errors or THROW commands in the TRY block of a TRY...CATCH...FINALLY structure.

When the following error handlers exist and an error occurs in the first code block as listed | Sequence of actions
None | Display appropriate Visual FoxPro system error message.
CATCH code block | CATCH code block handles the error.
CATCH code blockFINALLY code block | CATCH code block handles the error.FINALLY code block runs.
Inner CATCH code block Inner FINALLY code block Outer TRY structure | Inner CATCH code block handles the error. Inner FINALLY code block runs. Outer FINALLY code block runs. If no inner CATCH code block exists, inner FINALLY code block runs, outer CATCH code block handles the error, and outer FINALLY code block runs.
CATCH code block FINALLY code block ON ERROR command | CATCH code block handles the error. FINALLY code block runs.ON ERROR command runs. If no CATCH code block exists, FINALLY code block runs, and ON ERROR handles the error.
CATCH code block FINALLY code block Error code block | CATCH code block handles the error. FINALLY code block runs.Error event runs. If no CATCH code block exists, FINALLY code block runs, and Error event handles the error.

For information about how TRY...CATCH...FINALLY structures handle errors, see Structured Error Handling.

Error Handling Priority in Classes and Objects

When an error occurs in an object's method code, and the method is called directly or from the TRY block of a TRY...CATCH...FINALLY structure, Visual FoxPro follows the error handling procedure for that particular object. This protocol makes it possible for you to maintain encapsulation and control of your components. Typically, the object's Error event, if it exists, takes precedence over other error handlers unless the object's method code contains its own TRY...CATCH...FINALLY structure.

For more information about error handling for classes and objects, see Class and Object Error Handling.

Examples of Error Handling Priority for Object Method Code

In the following example where the class contains an Error event, the code instantiates an object from a custom class named MyObjectClass, which defines two methods that contain TRY...CATCH blocks, one method that contains an error, and an Error event. The object then calls two of the defined methods.

The TRY block in Method1 contains a call to the custom RaiseError method, which generates an error. However, the CATCH block in Method1 does not handle this error; instead, the code in the Error event for the class handles this error and displays the message specified. If the Error event did not exist, the CATCH block in Method1 would display the specified message.

In contrast, when an error occurs preceding the TRY block in Method2, the Error event handles this error by displaying the specified message. When a second error occurs in the TRY block in Method2, the CATCH block handles the second error and displays the specified message.

Copy Code
CLEAR
oMyObject = CREATEOBJECT("MyClass")
oMyObject.Method1()
?
oMyObject.Method2()

DEFINE CLASS MyClass AS Custom
   PROCEDURE Method1
      ? "Method1"
      TRY
         ? "Calling RaiseError method in TRY block for Method1."
         This.RaiseError()
      CATCH
         ? "Entered CATCH block for Method1. Caught error."
      ENDTRY
   ENDPROC

   PROCEDURE Method2
      ? "Method2"
      ? "Generating an error before TRY block in Method2."
      ERROR 1
      TRY
         ? "Generating an error in TRY block for Method2."
         ERROR 1
      CATCH
         ? "Entered CATCH block for Method2. Caught error."
      ENDTRY
   ENDPROC

   PROCEDURE RaiseError
      ? "Entered RaiseError method. Generating an error."
      ERROR 1
   ENDPROC

   PROCEDURE Error(t1,t2,t3)
      ? "Error event for MyObjectClass occurred."
   ENDPROC
ENDDEFINE

In the following example where the class does not contain an Error event, the code instantiates an object from a custom class named MyClass, which defines two methods: the first contains a TRY...CATCH block while the second does not.

The TRY block in myMethod1 contains a call to myMethod2, which generates an error. The CATCH block in Method1 handles this error and displays information for the Visual FoxPro error generated.

However, if the example called myMethod2 directly, for example, by following oMyObject.myMethod1() with oMyObject.myMethod2(), then the ON ERROR DO errorHandler statement would need to specify a functional routine named errorHandler to handle the error in myMethod2. After handling the error, the ON ERROR routine returns execution to the program so that the statement following the one containing the error can execute.

Copy Code
CLEAR
ON ERROR DO errorHandler && Create a functional error handler to test.
oMyObject=CREATEOBJECT("myClass")
oMyObject.myMethod1()
* oMyObject.myMethod2()  && Remove comment character to test this line.

DEFINE CLASS myClass AS Custom

   PROCEDURE myMethod1
      ? "myMethod1"
      TRY
         ? "Calling myMethod2 in TRY block for myMethod1."
         THIS.myMethod2()
      CATCH TO omyError
         ? "Entered CATCH block for myMethod1. Caught: ", ;
            omyError.ErrorNo, " ", omyError.Message
      ENDTRY
   ENDPROC

   PROCEDURE myMethod2
      ?
      ? "myMethod2"
      ? "Generating an error in myMethod2."
      x=y         && Variable y does not exist. CATCH handles this error.
      ? "This line displays if CATCH does not handle the preceding error."
   ENDPROC
ENDDEFINE

See Also

Other Resources

Handling Run-Time Errors
Testing and Debugging Applications


Using the Debugger

Visual FoxPro 9.0
Using the Debugger

After identifying problems in the testing process, you can use the Visual FoxPro debugging environment to isolate those problems by:

  • Starting a debugging session

  • Tracing through code

  • Suspending program execution

  • Seeing stored values

  • Output Display

In This Section

How to: Use the Debugger

Describes how to use the debugger to trace through code during execution.
How to: Suspend Program Execution

Explains how to use breakpoints to suspend program execution. Breakpoints can be used to suspend an application so that you can check the values of variables and properties, see environtment settings, and examine code sections.
How to: See Stored Values

Describes how to see values stored in run-time variables, array elements, properties, and expressions using the Locals, Watch, or Trace windows.
Output Display

Discusses how to display or save debug information.

Reference

Trace Window

Describes the Trace windows and how it enables you to see lines of code as they are being executed.
Debugger Window

Describes the Debugger window and provides links to topics describing the various features.
DEBUG Command

Provides information on how to use the DEBUG command to open the Debugger window.

Related Sections

Testing and Debugging Applications

Provides links to topics that explain methods to debug an applications.
How to: Use the Automated Test Harness

Describes how to use the Automated Test Harness to automate the testing of an application by creating and running scripts. The Automated Test Harness records and plays mouse and keyboard events using Microsoft Active Accessiblity technology.


How to: Use the Debugger

Visual FoxPro 9.0
How to: Use the Debugger
See Also

You can use the Visual FoxPro debugger to trace through code during execution.

Starting a Debugging Session

You start a debugging session by opening the debugging environment.

To open the debugger

  • From the Tools menu, choose Debugger.

    Note:
    If you're debugging in the Visual FoxPro environment, choose the debugging tool you want to open from the Tools menu.

You can also open the debugger with any of the following commands:

  • DEBUG

  • SET STEP ON

  • SET ECHO ON

The debugger opens automatically whenever a breakpoint condition is met.

Tracing Through Code

One of the most useful debugging strategies at your disposal is the ability to trace through code, see each line of code as it executes, and check the values of all variables, properties, and environment settings.

To trace through code

  1. Start a debugging session.

  2. If no program is open in the Trace window, choose Do from the Debug menu.

  3. Choose Step Into from the Debug menu or click the Step Into toolbar button.

An arrow in the gray area to the left of the code indicates the next line to execute.

Tip:
The following tips apply:

If you isolate a problem when you're debugging a program or object code, you can immediately fix it.

To fix problems encountered while tracing code

  • From the Debug menu, choose Fix.

When you choose Fix from the Debug menu, program execution is canceled and the code editor is opened to the location of the cursor in the Trace window.

See Also

Other Resources

Using the Debugger
How to: See Stored Values
Testing and Debugging Applications
Output Display
Trace
Debugger


How to: Suspend Program Execution

Visual FoxPro 9.0
How to: Suspend Program Execution
See Also

Breakpoints allow you to suspend program execution. Once program execution has been suspended, you can check the values of variables and properties, see environment settings, and examine sections of code line by line without having to step through all your code.

Tip:
You can also suspend execution of a program running in the Trace window by pressing ESC.

Suspending Execution at a Line of Code

You can set breakpoints in your code to suspend program execution in several different ways. If you know where you want to suspend program execution, you can set a breakpoint directly on that line of code.

To set a breakpoint on a particular line of code

  1. In the Trace Window, locate the line of code you want to set the breakpoint on.

  2. Position the cursor on the line.

  3. Perform one of the following:

    • Double-click in the gray area to the left of the line of code.

    • On the Debugger toolbar, click the Toggle Breakpoints button.

    • Press F9.

A solid dot is displayed in the gray area to the left of the line of code to indicate that a breakpoint has been set on that line.

Tip:
If you are debugging objects, you can locate particular lines of code in the Trace window by choosing the object from the Object list and the method or event from the Procedure list.

You can also set breakpoints by specifying locations and files in the Breakpoints dialog box.

Examples of Locations and Files for Breakpoints

Location | File | Where execution suspends
ErrHandler | C:\Myapp\Main.prg | The first executable line in a procedure named ErrHandler in Main.prg.
Main,10 | C:\Myapp\Main.prg | The tenth line in the program named Main.
Click | C:\Myapp\Form.scx | The first executable line of any procedure, function, method or event named Click in Form.scx.
cmdNext.Click | C:\Myapp\Form.scx | The first executable line associated with the Click event of cmdNext in Form.scx.
cmdNext::Click |  | The first executable line in the Click event of any control whose ParentClass is cmdNext in any file.

Suspending Execution When Values Change

If you want to know when the value of a variable or property changes, or when a run-time condition changes, you can set a breakpoint on an expression.

To suspend program execution when the value of an expression changes

  1. From the Tools menu in the Debugger Window, choose Breakpoints to open the Breakpoints Dialog Box.

  2. From the Type list, choose Break when expression has changed.

  3. Enter the expression in the Expression box.

Examples of breakpoint expressions

Expression | Use
RECNO( ) | Suspend execution when the record pointer moves in the table.
PROGRAM( ) | Suspend execution on the first line of any new program, procedure, method, or event.
myform.Text1.Value | Suspend execution any time the value of this property is changed interactively or programmatically.

Suspending Execution Conditionally

Often you'll want to suspend program execution, not at a particular line, but when a certain condition is true.

To suspend program execution when an expression evaluates to true

  1. From the Tools menu in the Debugger Window, choose Breakpoints to open the Breakpoints Dialog Box.

  2. From the Type list, choose Break when expression is true.

  3. Enter the expression in the Expression box.

  4. Choose Add to add the breakpoint to the Breakpoints list.

Examples of breakpoint expressions

Expression | Use
EOF( ) | Suspend execution when the record pointer has moved past the last record in a table.
'CLICK'$PROGRAM( ) | Suspend execution on the first line of code associated with a Click or DblClick event.
nReturnValue = 6 | If the return value of a message box is stored to nReturnValue, suspend execution when a user chooses Yes in the message box.

Suspending Execution Conditionally at a Line of Code

You can specify that program execution be suspended at a particular line only when a particular condition is true.

To suspend program execution at a particular line when an expression evaluates to true

  1. From the Tools menu in the Debugger Window, choose Breakpoints to open the Breakpoints Dialog Box.

  2. From the Type list, choose Break at location if expression is true.

  3. Enter the location in the Location box.

  4. Enter the expression in the Expression box.

  5. Choose Add to add the breakpoint to the Breakpoints list.

  6. Choose OK.

    Tip:
    It is sometimes easier to locate the line of code in the Trace window, set a breakpoint, and then edit that breakpoint in the Breakpoints dialog box. To do this, change the Type from Break at location to Break at location if expression is true and then add the expression.

Removing Breakpoints

You can disable breakpoints without removing them in the Breakpoints dialog box. You can delete "break at location" breakpoints in the Trace window.

To remove a breakpoint from a line of code

  • In the Trace Window, locate the breakpoint and do one of the following:

    • Position the cursor on the line of code, and then choose Toggle Breakpoints from the Debugger toolbar.

      -or-

    • Double-click the gray area to the left of the line of code.

See Also

Other Resources

How to: Use the Debugger
How to: See Stored Values
Using the Debugger
Output Display
Trace
Debugger


How to: See Stored Values

Visual FoxPro 9.0
How to: See Stored Values
See Also

In the Debugger window, you can easily see the run-time values of variables, array elements, properties, and expressions in the following windows:

  • Locals Window

  • Watch Window

  • Trace Window

Seeing Stored Values in the Locals Window

The Locals window displays all the variables, arrays, objects, and object members that are visible in any program, procedure, or method on the call stack. By default, values for the currently executing program are displayed in the Locals window.

To view stored values in the Locals window

  • In the Locals For list, choose the program or procedure.

You can drill down into arrays or objects by clicking the plus (+) beside the array or object name in the Locals and Watch windows. When you drill down, you can see the values of all the elements in the arrays and all the property settings in objects.

You can even change the values in variables, array elements, and properties in the Locals and Watch windows by selecting the variable, array element, or property, clicking in the Value column, and typing a new value.

Seeing Stored Values in the Watch Window

You can see stored values in the Watch window. The value and type of the expression appears in the Watch window list. Values that have changed are displayed in red in the Watch window.

Note:
You cannot enter expressions that create objects in the Watch window.

To see stored values in the Watch window

  • In the Watch box of the Watch window, type any valid Visual FoxPro expression and press ENTER.

You can also select variables or expressions in the Trace window or other Debugger windows and drag them into the Watch window.

To remove an item from the Watch window list

  • Select the item and choose one of the following:

    • Press DEL.

      -or-

    • From the shortcut menu, choose Delete Watch.

To edit a watch

  • Double-click the watch in the Watch window and edit in place.

Seeing Stored Values in the Trace Window

You can see stored values in the Trace window as a value tip.

To see stored values in the Trace window

  • In the Trace window, move the cursor the element you want to display its value. In Visual FoxPro 9.0, you can display the value of #DEFINE compile-time constants.
TraceValueTip screenshot foxpro

See Also

Other Resources

How to: Use the Debugger
How to: Suspend Program Execution
Output Display
Using the Debugger
How to: Log Code Coverage
Handling Run-Time Errors


Output Display

Visual FoxPro 9.0
Output Display
See Also

The DEBUGOUT command allows you to write values in the Debug Output window to a text file log. Alternatively, you can use the SET DEBUGOUT TO command or the Debug tab of the Options dialog box.

If you aren't writing DEBUGOUT commands to a text file, the Debug Output window must be open in order for the DEBUGOUT values to be written. The following line of code prints in the Debug Output window at the time that the line of code executes:

Copy Code
DEBUGOUT DATETIME( )

In addition, you can enable event tracking, and choose to have the name and parameters of each event that occurs displayed in the Debug Output window.

See Also

Other Resources

How to: Use the Debugger
How to: See Stored Values
How to: Log Code Coverage
Using the Debugger
Handling Run-Time Errors
How to: Suspend Program Execution


Compiling an Application

Visual FoxPro 9.0
Compiling an Application

By creating an application one component at a time, you can verify the functionality of each component as you create it. After creating all the functional components in your application project, you can build an application and assemble the executable components in the application project, such as forms, reports, menus, and programs, into a single file that you can distribute with the application data files to your users.

In This Section

Excluding Modifiable Files from Builds

Explains why you might want to exclude files that users change using your application from the application build process.
How to: Exclude Files from Builds

Describes how to exclude files that users can modify from the application build process.
How to: Build Applications

Describes how to build distributable application files from your project.
How to: Run Applications

Describes how to run applications after you build them.

Related Sections

Testing and Debugging Applications

Explains the testing and debugging process so you can find and correct any errors that occur in your applications.

Distributing Applications

Describes how to prepare to distribute your application by including all required files and creating distribution disks, after you have completed developing and testing your application.
Developing Visual FoxPro Applications

Provides conceptual information on Visual FoxPro application development, including instructions for creating databases and the user interface, and other tasks needed to create applications.


Excluding Modifiable Files from Builds

Visual FoxPro 9.0
Excluding Modifiable Files from Builds
See Also

Your application project most likely contains files, such as tables, that users need to modify. However, when you build an application from a Visual FoxPro project, the files in the project are assembled into a single application file, and the files in the project that are designated as included become read-only.

For files that users need to modify, you should add them to your project but exclude them from the build process. Excluded files remain part of your application, so Visual FoxPro continues to track them as part of your project. However, excluded files are not compiled into the application file so users can modify them.

Generally, you should include executable files, such as forms, reports, queries, menus, and programs, and all other files that users do not need to update. You should exclude data files, ActiveX control (.ocx) libraries, Visual FoxPro dynamic-link libraries (.fll), and Windows dynamic-link libraries (.dll). By default, tables are excluded because it is assumed that users change tables in an application.

Note:
You cannot include application (.app) files in a project. You cannot exclude files that are designated as main files. For more information about main files, see How to: Set the Starting Point.

However, you should include or exclude files based on your application requirements. For example, you might include a table that contains sensitive system information or read-only information to protect it from inadvertent changes. Conversely, if your application permits users to change a report, you might exclude the report.

See Also

Other Resources

How to: Exclude Files from Builds
Compiling an Application


How to: Exclude Files from Builds

Visual FoxPro 9.0
How to: Exclude Files from Builds
See Also

Before you build a distributable file for your application project, exclude those project files that users change with your application from the build process.

Note:
If you exclude a file, make sure that Visual FoxPro can locate the excluded file when the application runs. If Visual FoxPro cannot find the excluded file, Visual FoxPro prompts the user to locate the file. For example, when a form references a visual class library (.vcx) file, the form stores a relative path to that library. If you exclude the library, the form must search for the library using the relative path or the Visual FoxPro search path as set with the SET PATH command. If the library is not found in the expected location, Visual FoxPro prompts the user to locate the library. If the library is included in the project, it becomes part of the application file, and the form can always locate the library.

To exclude files from a project

  1. Open the project for your application.

  2. In Project Manager, select the file that can be modified.

  3. On the Project menu, choose Exclude.

    Note:
    If the file is already excluded, the Exclude command is not available. Instead, the Include command appears.

The Ø symbol appears next to the names of excluded files in the Project Manager.

Tip:
To view all project files in a single list, choose Project Info on the Project menu. In the Project Information dialog box, choose the Files tab.

For more information, see Project Manager Window and Files Tab, Project Information Dialog Box.

See Also

Other Resources

Excluding Modifiable Files from Builds
How to: Build Applications
Compiling an Application


How to: Build Applications

Visual FoxPro 9.0
How to: Build Applications
See Also

When you have tested your application project for errors, and it includes all the necessary files, you can build a distributable file from the project by following the steps in one of these sections:

  • Building a Visual FoxPro Standard Application

    Describes how to build a standard application (.app) file that runs only with Visual FoxPro installed.

  • Building a Visual FoxPro Executable File

    Describes how to build an executable (.exe) file that runs without Visual FoxPro.

For information about building Automation servers or Windows dynamic-link library (.dll) files, see How to: Build Automation Servers.

For information about testing application projects, see How to: Test a Project.

Building a Visual FoxPro Standard Application

You can build a Visual FoxPro standard application (.app) file using the Project Manager or the BUILD APP command. However, more build options are available when you use the Project Manager. For information about using the BUILD APP command, see BUILD APP Command.

Note:
To build an .app file, your project must have a program set as the main program. For more information, see How to: Set the Starting Point.

To build a standard application (.app) file

  1. Open the project for your application.

  2. In the Project Manager, choose Build.

  3. In the Build Options dialog box, choose Application (app).

  4. Select any other options you want and click OK.

    Tip:
    You can view and save build messages that occur during the build process. For more information, see How to: View and Save Build Messages.

  5. In the Save As dialog box, specify a name for the file, then save the file.

For more information, see Project Manager and Build Options Dialog Box.

Building a Visual FoxPro Executable File

You can build a Visual FoxPro executable (.exe) file using the Project Manager or the BUILD EXE command. However, more build options are available when you use the Project Manager. For information about using the BUILD EXE command, see BUILD EXE Command.

Note:
To build an .exe file, your project must have a program set as the main program. For more information, see How to: Set the Starting Point.

To build an executable (.exe) file

  1. Open the project for your application.

  2. In the Project Manager, choose Build.

  3. In the Build Options dialog box, choose Win32 executable/COM server (exe).

  4. Select any other options you want and click OK.

    Tip:
    You can view and save build messages that occur during the build process. For more information, see How to: View and Save Build Messages.

  5. In the Save As dialog box, specify a name for the file, then save the file.

For more information, see Project Manager and Build Options Dialog Box.
Note:
The .exe file operates with certain dynamic-link (.dll) libraries that provide a complete Visual FoxPro run-time environment and that you need to include when distributing your application. For more information, see Preparation for Distributing Applications.

See Also

Other Resources

How to: Run Applications
Distributing Applications
Compiling an Application


How to: Run Applications

Visual FoxPro 9.0
How to: Run Applications
See Also

After you finish building a redistributable application file, you can run it. You can run application files from the Program menu or by using the DO command. For more information, see DO Command.

To run an application (.app) file

  1. On the Program menu, choose Do.

  2. In the Do dialog box, select the .app file you want to run.

To run an executable (.exe) file

  • In Windows, double-click the icon for the .exe file.

You can also run .exe files from the Program menu or by using the DO command.

See Also

Other Resources

Distributing Applications
Compiling an Application


Configuring Help Files for Applications

Visual FoxPro 9.0
Configuring Help Files for Applications

You can add Help to your application by configuring it to access a Help file that you create.

In This Section

How to: Add Context Sensitive Help to Applications

Describes how to configure Help for tasks that users perform or user interface elements they see in your application by pressing the F1 key.
How to: Implement "What's This?" Help

Describes how to configure Help for tasks that users perform or user interface elements they see in your application by clicking the "What's This?" Help button.
How to: Add Help Buttons to Forms

Describes how to add a Help button to forms to make it easier for beginning users to access Help.

Reference

SET HELP Command

Enables or disables Microsoft Visual FoxPro online Help or specifies a Help file.
SET TOPIC Command

Specifies the Help topic or topics to open when you invoke the Visual FoxPro Help system.
SET TOPIC ID Command

Specifies the Help topic to display when you invoke the Visual FoxPro Help system. The Help topic is based on the topic's context ID.

Related Sections

Developing Visual FoxPro Applications

Explains concepts about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
How to: Include Files with Applications for Distribution

Describes how you to add or include files that you want to distribute with your application.


How to: Add Context Sensitive Help to Applications

Visual FoxPro 9.0
How to: Add Context Sensitive Help to Applications
See Also

Adding context-sensitive Help to applications makes it possible for users to access Help topics related to the tasks they perform or the user interface elements they see in your application. For example, if a user is viewing a data entry form, you can configure context-sensitive Help to provide a Help topic related specifically to the data entry form.

You can choose the level of detail to implement context-sensitive Help in your application. For example, you can associate a context-sensitive Help topic with a form or you can associate more detailed Help topics with each control and field on the form.

Users can access context-sensitive Help typically by pressing the F1 key. F1 is enabled for context-sensitive Help by default.

Note:
Though you can map any key to activate context-sensitive Help using the ON KEY LABEL command, pressing the F1 key is a recognized standard for Help; therefore, redefining this key is not recommended. For more information, see ON KEY LABEL Command.

To add context-sensitive Help, you must specify a Help file for your application and then assign specific Help topics to the objects in your application.

Specifying a Help File

To specify a Help file for your application

  • Use the SET HELP command to specify the name of the Help file you want to use.

    Tip:
    This command is typically included in the setup code for the main program of your application.

For more information, see SET HELP Command.

For example, the following line of code sets the HTML Help file MyHelp.chm as the Help file to use:

Copy Code
SET HELP TO MyHelp.chm

Assigning Help Topics

You can assign specific Help topics to objects, such as forms, controls, or toolbars, in your application.

To assign a Help topic to an object

  1. At design time, select the object that you want to want to assign a topic.

  2. On the Window menu, click Properties Window.

  3. In the Properties window, set the HelpContextID property to the number associated with the topic in your Help file.

For more information, see HelpContextID Property.

See Also

Tasks

How to: Implement "What's This?" Help
How to: Add Help Buttons to Forms

Other Resources

Configuring Help Files for Applications


How to: Implement "What's This?" Help

Visual FoxPro 9.0
How to: Implement "What's This?" Help
See Also

"What's This?" Help is similar to context-sensitive Help in that it provides Help related to a specific object or control on a form that has focus. "What's This?" Help is useful for providing brief tip-style descriptions or definitions for specific controls. You can implement "What's This?" Help by adding the "What's This?" (?) button to forms. Users access "What's This?" Help by clicking the "What's This?" button (?) in the form's title bar, which changes the mouse pointer to a question mark, and then clicking objects on the form.

When you configure your application to use WinHelp files, clicking the "What's This?" button opens a pop-up window that displays Help text, which disappears when you click elsewhere on the screen. When you configure your application to use HTML Help files, clicking the "What's This?" button opens the Help file and displays the Help topic in the HTML Help viewer.

Tip:
Keep "What's This?" Help topics brief and concise so that the pop-up window does not obscure the feature it describes.

To implement "What's This?" Help

  1. Open the form you want in the Form Designer.

  2. On the Window menu, click Properties Window.

  3. In the Properties window, set the form's WhatsThisHelp property to True (.T.).

  4. To display a "What's This?" (?) Help button in the form's title bar, set the form's WhatsThisButton property to True (.T.). Set the form's MaxButton property to False (.F.) and the MinButton property to False (.F.).

  5. To associate a Help topic with the form, set the form's WhatsThisHelpID property to an ID number corresponding to the appropriate topic in the Help file.

  6. To associate a Help topic with a specific control on the form, select the control and set its WhatsThisHelpID property to an ID number corresponding to the appropriate topic in the Help file.

You can also use the WhatsThisMode method to display the "What's This?" Help question mark so users can click objects to display "What's This?" Help topics.

For more information, see WhatsThisHelp Property, WhatsThisButton Property, WhatsThisHelpID Property, and WhatsThisMode Method.

See Also

Tasks

Provide What's This? Help on a Form Sample
How to: Add Context Sensitive Help to Applications
How to: Add Help Buttons to Forms

Other Resources

Configuring Help Files for Applications


How to: Add Help Buttons to Forms

Visual FoxPro 9.0
How to: Add Help Buttons to Forms
See Also

You can program your application so that users can click a Help button to access the Help file. Adding Help buttons can make it easier for beginning users to access Help.

Tip:
You can save the Help command button as a class so that you can add it to a form more easily.

To add a Help button to a form

  1. In the form's Init event, use the SetAll method to set the HelpContextID property for all the form's objects to the value you assigned to the Help topic you want to use.

    For example, the following line of code sets all the form's objects HelpContextID properties to 7 as their Help context ID number:

    Copy Code
    THIS.SetAll("HelpContextID", 7)

  2. Add a command button to the form.

  3. Set the command button's Caption property to the text, Help.

  4. In the command button's Click event, add the following command:

    Copy Code
    HELP ID THIS.HelpContextID

For more information, see Init Event, SetAll Method, HelpContextID Property, Caption Property, Click Event, and HELP Command.

See Also

Tasks

How to: Implement "What's This?" Help

Reference

Help Button Foundation Class
Configuring Help Files for Applications

Other Resources

How to: Add Context Sensitivity to HTML Help


Distributing Applications

Visual FoxPro 9.0
Distributing Applications

After you develop and test your application, you can prepare to distribute it by including all required files and creating distribution disks.

In This Section

Application Distribution Process

Describes an overview of the steps needed to distribute your application.
Preparation for Distributing Applications

Describes considerations you need to consider when preparing your application for distribution and the run-time environment, such as choosing the type of build, testing minimum operating environment requirements, ensuring correct run-time behavior, and including Visual FoxPro system menu options.
Resource Files in Applications

Describes resource files that you can include in your application to extend its functionality, such as FoxUser.dbf, external library files, ActiveX controls and COM components, configuration and help files, and so on.
Distributable and Restricted Visual FoxPro Features and Files

Describes restricted Visual FoxPro features and files you must remove from your application as well as those files you can distribute with your application.
How to: Include Files with Applications for Distribution

Describes how you to add or include files that you want to distribute with your application.

Related Sections

Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Working with Projects

Defines a project a configuration and a group of files that produce a program or final binary file or files.

Compiling an Application

Describes how to use the modular approach to make it possible for you to verify the functionality of each component you create. Then you can compile them into an application, which assembles the executable components of your project.
Testing and Debugging Applications

Discusses testing for errors within and across components when you develop an application. Visual FoxPro provides debugging tools to help you find and correct any errors you discover in your applications.


Application Distribution Process

Visual FoxPro 9.0
Application Distribution Process
See Also

The following list identifies the overall steps you need to follow to distribute a Visual FoxPro application:

  1. Create and debug the application using the Visual FoxPro development environment.

  2. Prepare and customize your application for the run-time environment. For details, see Preparation for Distributing Applications.

  3. Make sure your project includes all the necessary files for your application, including any resource files, graphics files, or templates. For more information about the types of files you can include in your application and how to include files, see Resource Files in Applications and How to: Include Files with Applications for Distribution.

    Note:
    Required Runtime Files: Visual FoxPro requires inclusion of certain files in order for your runtime applications to function properly. The easiest way to include these files is by using a Windows Installer based tool for creating custom setups (such as InstallShield Express). By selecting the Microsoft Visual FoxPro 9.0 Runtime Libraries merge module, your setup contains the proper files necessary to run your custom Visual FoxPro 9.0 application. The core Visual FoxPro 9.0 merge module properly handles installation and registration for the following files:

    • vfp9r.dll

    • vfp9t.dll

    • vfp9renu.dll

    • msvcr71.dll

    • gdiplus.dll

      Msvcr71.dll and gdiplus.dll files are part of separate merge modules, but are included automatically because of their dependency with the Visual FoxPro 9.0 Runtime libraries. Gdiplus.dll is only installed on platforms prior to Windows 2000 (for example, Windows 98).

      If you require runtime support for an additional language, select the appropriate language merge module. These merge modules contain a specific language resource library (for example, vfp9rdeu.dll).

  4. Remove any restricted Visual FoxPro features or files from your application. Certain development environment features are not available in the run-time environment and need to be removed from your application. Make sure any files you plan to distribute meet the guidelines for redistributing files. For more information on restricted and distributable files, see Distributable and Restricted Visual FoxPro Features and Files.

  5. Build an application (.app), executable (.exe) file, or a COM component (automation server) with a .dll or .exe extension. For more information about building an application, see Compiling an Application.

  6. Create an installation package using a Windows Installer deployment program. For more information about creating installation packages, see Walkthrough: Creating a Visual FoxPro Application Setup Program Using InstallShield Express.

    Note:
    The setup creation program you use must use Windows Installer technology to create a Setup program (.msi) or merge modules (.msm) that are compatible with Microsoft Windows Installer. The Windows 2000 Logo guidelines require that setup programs be based on Windows Installer technology.

  7. Package and distribute your application disks and any printed documentation. Depending on the setup creation program you use, the program might create the disk images for you, or you might need to copy the files to the distribution location manually. Consult the documentation for the setup creation program for more information.

See Also

Other Resources

Distributing Applications
Preparation for Distributing Applications


Preparation for Distributing Applications

Visual FoxPro 9.0
Preparation for Distributing Applications
See Also

This section describes a number of issues you should consider when preparing your application for deployment.

  • Build Type Selection

  • Hardware, Memory, and Network Issues

  • Ensuring Correct Run-Time Behavior

  • Default Menu Options

Build Type Selection

Before you can distribute your application, you must build an application (.app) file, an executable (.exe) file, or a COM component (automation server) with a .dll or .exe extension. When choosing the type of build you want to create, consider the size of your final application file and whether users have Visual FoxPro installed on their computers.

The following table lists the differences between the types of builds.

Build type | Description
Application (.app) file | This file requires that the user have a copy of Visual FoxPro installed. An .app file is usually smaller than an .exe file.
Executable (.exe) file | This file includes the Visual FoxPro loader so users do not need have Visual FoxPro installed. You must provide the two support files VFPVersionNumberR.dll and VFPVersionNumberRENU.dll where VersionNumber represents the version number of this release of Visual FoxPro. The letters, "EN", denote the English version. These files must be placed in the same directory as the .exe file or along the DOS path. See BUILD EXE Command for details about creating and distributing executable files.
COM Server (.dll or .exe) files | This file is used to create a file that can be called by other applications. In Visual FoxPro, you can create two types of COM server (.dll, formerly, OLE) files. You must provide run-time support files, including the VFPVersionNumberR.dll, VFPVersionNumberT.dll, and VFPVersionNumberRENU.dll files where VersionNumber represents the version number of this release of Visual FoxPro. For details, see How to: Add OLE Objects to Applications.

Hardware, Memory, and Network Issues

You should consider and test the minimum environment your application can operate in, including the amount of disk space and memory. The results of your testing and the resolution of other issues covered in this section can help determine the type of build you choose and the files you include with your application.

The applications you create have the same hardware, memory, and network requirements as Visual FoxPro. For more information on those requirements, see Installing Visual FoxPro. For additional information on creating applications for multiuser environments, see Programming for Shared Access.

Ensuring Correct Run-Time Behavior

When distributing an executable application (.exe) file, you must include the following files:

  • VFPVersionNumberR.dll, where VersionNumber represents the version number of this release of Visual FoxPro.

  • VFPVersionNumberRENU.dll

  • GDIPlus.dll

  • MSVCR71.dll

In some cases, Visual FoxPro in-process servers, or .dll files, can use the lightweight VFPVersionNumberT.dll run-time library instead. For more information about run-time libraries, see VFP9R.DLL Run-Time Library and VFP9T.DLL Run-Time Library.

Note:
If you want to run an application (.exe) file using the development version of Visual FoxPro, you must run the .exe file with the Visual FoxPro executable file, VFPVersionNumber.exe.

An application consisting only of modeless forms will not function properly in a run-time environment unless you provide a READ EVENTS command. You can make sure the application runs properly by adding a calling program or setting the WindowType property.

You can also type DO followed by the name of your application's .exe file in the Command window or use the -E command-line switch in the command line that starts Visual FoxPro. For example, if your application is called MYAPP, you can run it with the following command line:

Copy Code
MYAPP.EXE -E

This command-line switch forces the application to use the executable file, VFPVersionNumber.exe where VersionNumber represents the version number of this release of Visual FoxPro. For this switch to work correctly, VFPVersionNumber.exe must be in the search path.

To run a form in a run-time environment

  1. Run the form from a program containing a READ EVENTS command.

    -or-

  2. Set the form's WindowType property to Modal.

Some Visual FoxPro applications rely heavily on Visual FoxPro system menus. At run time, some menus and commands are unavailable, and without a provision for a READ EVENTS command, a menu-driven application ends as quickly as it starts. Use the following section to review any menus you include in your application.

For more information on structuring an application with the READ EVENTS command, see How to: Control the Event Loop and examples of how to structure an application in Compiling an Application.

Default Menu Options

If you use the Visual FoxPro system menu, your application file includes only the following default menus and menu commands.

Menu | Menu items
File | Close, Save, Save As, Exit
Edit | Undo, Redo, Cut, Copy, Paste, Paste Special, Select All, Find, Replace
Window | Arrange All, Hide, Hide All, Show All, Clear, Cycle, all open windows
Help | Contents, Search for Help on, Product Support, About Visual FoxPro

You can disable or remove any of the default menus and menu commands, or add your own menus and menu commands to run-time applications.

Tip:
If your menu system works in the development environment but closes prematurely in your application, make sure you have a READ EVENTS command active while your menu system is running. Also be sure to include a CLEAR EVENTS command when you exit the menu system.

For more information about customizing menus, see Designing Menus and Toolbars.

See Also

Other Resources

Distributing Applications
Application Distribution Process
Resource Files in Applications
Distributable and Restricted Visual FoxPro Features and Files
How to: Include Files with Applications for Distribution


Resource Files in Applications

Visual FoxPro 9.0
Resource Files in Applications
See Also

Visual FoxPro provides several resource files that extend the basic functionality of your applications, including FoxUser resource files, API libraries, and ActiveX controls. If you use these files, you must include them in your project or distribution tree.

The following table lists some of the files you can include in your application by adding them to your project. For more information about including files in your application for distribution, see How to: Include Files with Applications for Distribution.

If you are | Add these files to your project
Applying a custom configuration to your application | Config.fpw
Applying custom settings to your application | FoxUser.dbf and FoxUser.fpt

For details about how to include files in your setup program, see the help associated with the setup creation program you are using. The setup creation program you use must create MSI setup packages using Windows Installer technology.

FoxUser.* Resource Files

Visual FoxPro resource files store useful information for your application, including window positions, Browse window configurations, and label definitions. If your application relies on specific settings for any of these resource items, you must also distribute the FoxUser database and memo files or the resource files you create specifically for your application. These resource files consist of a Visual FoxPro table with an associated memo file, usually named FoxUser.dbf and FoxUser.fpt.

Note:
The FoxUser.dbf resource file is not the same as the locale-specific resource file that contains dialog boxes and error messages. The FoxUser.dbf resource file stores application information such as macros you have defined; the locale-specific resource file stores system text strings.

External Library Files

If your application includes external library files such as ActiveX controls (.ocx files) or Visual FoxPro API libraries (.fll files), make sure they are placed in the appropriate directory in your setup package. You can distribute the Visual FoxPro file FoxTools.fll with your applications. For more information on creating external libraries to access the Visual FoxPro API, see Accessing APIs.

ActiveX Controls and COM Components

If you include ActiveX controls or have created an Automation server (a COM component) as part of your application, include any .ocx and .dll files in your project and ensure the necessary support files are installed to the proper location on the user's machine.

Note:
The Windows 2000 Logo guidelines do not recommend installing components to the Windows System directory. You can only distribute ActiveX controls for which you are licensed. For Automation servers, you must also include registration files, such as type libraries (.tlb files) and registry files (.vbr files), with your application.

If you use your setup creation program to create the distribution disks, you can include these files automatically. When you do this, the setup creation program ensures that COM components are registered properly on the user's computer when the application is installed. For more information on including files in your setup creation program, see the help associated with the program.

All users can run forms containing ActiveX controls; however, your application cannot accomplish certain tasks if it is running under the run-time version of Visual FoxPro. Remember the following guidelines:

  • Your application must be running under a full version of Visual FoxPro to change forms, classes, or subclasses that include ActiveX controls.

  • Your application must be running under a full version of Visual FoxPro to add ActiveX controls to forms at run time. For example, the full version of Visual FoxPro is required to add the Listview control to a form by running the following code:

    Copy Code
    PUBLIC frmOleNewForm
frmOleNewForm = CREATEOBJECT("form")
frmOleNewForm.Show
frmOleNewForm.ScaleMode = 3
frmOleNewForm.Addobject("NewListview","OLEControl",;
   "MSComctlLib.ListViewCtrl")
    Note:
    When a form is closed, controls added at run time are not saved.

  • Your application can be running under either the run-time or full version of Visual FoxPro to add subclassed ActiveX controls to a form at run time. For example, you can define the RedListview subclass from the Listview class, and distribute the subclass in Olelib.vcx; all users can then add the RedListview control to a form by running the following code:

    Copy Code
    PUBLIC frmOleNewForm
frmOleNewForm = CREATEOBJECT("form")
frmOleNewForm.Show
frmOleNewForm.ScaleMode = 3
SET CLASSLIB TO CURR() + OLELIB.VCX
frmOleNewForm.Addobject("NewListview","RedListview")

Configuration Files

You can use the configuration file, Config.fpw, to establish many default Visual FoxPro settings. For instance, you can change the Visual FoxPro title, the background color, and the way a user navigates with the keyboard.

If you want the configuration file to be read-only, place it in your project and mark it as included. If you want the configuration to be modifiable, place the file in your project and mark it as excluded. Distribute the configuration file with your application or executable file, as a separate file. By default, Visual FoxPro looks for a configuration file named Config.fpw. However, you can specify a different configuration file name using the -C command-line switch when starting Visual FoxPro.

For more information about options that you can set in the configuration file, see "Using a Configuration File" in Customizing the Visual FoxPro Environment.

Locale-Specific Resource Files

If you are distributing your application along with the run-time version of Visual FoxPro, you might need to include a locale-specific resource file. This file contains the dialog boxes and other user interface elements that Visual FoxPro uses to interact with the user. A different run-time resource file exists for each language in which Visual FoxPro is available.

For more information about using locale-specific run-time files, see "Distributing Locale-Specific Run-Time Files" in Developing International Applications.

Note:
The locale-specific resource file is not the same as the FoxUser.dbf resource file, which stores application information such as macros you have defined. The locale-specific resource file stores system text strings.

If you are creating an application for Middle Eastern platforms, be sure to add VBAME.DLL file to your distribution set and have it installed in the Windows System directory.

Note You cannot distribute Winhelp.exe or the Help files shipped with Visual FoxPro.

See Also

Other Resources

Distributing Applications
Preparation for Distributing Applications
Distributable and Restricted Visual FoxPro Features and Files
How to: Include Files with Applications for Distribution


Distributable and Restricted Visual FoxPro Features and Files

Visual FoxPro 9.0
Distributable and Restricted Visual FoxPro Features and Files
See Also

Visual FoxPro and its development environment contain many files and features that are licensed only for your use in designing, developing, and testing your applications. If your application contains any of these restricted features or files as well as files other than those authored by you or in Redist.txt, you must remove them. Under the terms of the Microsoft License Agreement you received with this product, you cannot ship these files in your application or on your disks.

You can distribute any Visual FoxPro file that is not restricted. For a list of redistributable files, see Redist.txt, which is located in your Visual FoxPro installation directory, and the guidelines for including redistributable files in this topic.

Restricted Visual FoxPro Features

You cannot include the following restricted Visual FoxPro menus and their menu commands in a distributed executable (.exe) file:

  • Database

  • Form

  • Menu

  • Program

  • Project

  • Query

  • Table

The following table lists commands for which your application returns the message, "Feature not available", if included. Although you cannot include commands that create or modify menus, forms, or queries, you can run compiled menu, form, or query programs in your application.

Unavailable commands |
APPEND PROCEDURES | MODIFY DATABASE
BUILD APP | MODIFY FORM
BUILD EXE | MODIFY MENU
BUILD PROJECT | MODIFY PROCEDURE
CREATE FORM | MODIFY PROJECT
CREATE MENU | MODIFY QUERY
CREATE QUERY | MODIFY SCREEN
CREATE SCREEN | MODIFY VIEW
CREATE VIEW | MODIFY CONNECTION
SET STEP |

The following table lists commands that are ignored when used in a distributed application.

Ignored commands |
ASSERT | DEBUGOUT
SET DEBUG | SET DOHISTORY
SET DEVELOPMENT | SET ECHO

Restricted Visual FoxPro Files

Visual FoxPro installs files on your computer that are restricted and cannot be reproduced or distributed, including:

  • Some wizard files

  • TrueType fonts

  • Visual FoxPro Help files

Distributable Visual FoxPro Files

Pursuant to the Microsoft License Agreement you received with this product, you must distribute files in conjunction with a corresponding application. The following guidelines apply to distributable files.

Samples

Visual FoxPro provides files in the Visual FoxPro \Samples directory for you to learn from and build on. Although you cannot distribute unmodified Visual FoxPro samples, you can refer to portions of sample application code as examples for building your own application.

If you use any files in these directories, including all .bmp, .ico, and .cur files, you must include them in your project and application build. They must not appear by name on the distributable disks and cannot be distributed independently of your applications.

Class Libraries

You can use any .vcx file, including those in the \Ffc and \Gallery directories, the wizard class library, Wizstyle.vcx, and the sample class libraries without modification in your applications. You must include the libraries in your project and in your application build.

ODBC Files

Please refer to the Microsoft License Agreement you received with this product for specific restrictions with respect to your redistribution of ODBC files.

ActiveX Controls

Visual FoxPro includes a set of ActiveX controls (.ocx files) you can add to and distribute with your applications.

See Also

Reference

ActiveX Controls Overview

Other Resources

Distributing Applications
Preparation for Distributing Applications
Resource Files in Applications
How to: Include Files with Applications for Distribution


How to: Include Files with Applications for Distribution

Visual FoxPro 9.0
How to: Include Files with Applications for Distribution
See Also

You can freely reproduce and distribute some Visual FoxPro files, graphics, and programs with the applications you create; however, you must remove restricted files from your application. For more information, see Distributable and Restricted Visual FoxPro Features and Files.

Before you build your application, make sure that your project includes the necessary files for your application as well as any additional resource files, such as graphics files or templates.

To add files to your application

  1. Include the files in your project.

    If you do not want to change these files in the distributed application, place the files in your project and mark them as included. The files are then read-only and cannot be modified.

    -or-

  2. Add the files to your application directory to make them easily accessible to your setup creation program.

    If you want to modify them, place the files in your project and mark them as excluded. Then distribute them with your application as separate files.

For more information about creating a project, and including or excluding files in a project, see Compiling an Application.

See Also

Other Resources

Distributing Applications
Preparation for Distributing Applications
Resource Files in Applications


Programming in Visual FoxPro

Visual FoxPro 9.0
Programming in Visual FoxPro

You can create applications and programs by learning about and using Visual FoxPro's programming language and capabilities.

In This Section

Basic Programming Concepts

Provides an overview of programming fundamentals necessary to work in Visual FoxPro, including data storage, data types, containers, operators, commands, and controlling program flow.
Working with Programs

Introduces how to create and work with Visual FoxPro programs, which are text files containing instructions using the Visual FoxPro language.
Working with Procedures and Functions

Introduces how to call native functions as well as user-defined functions and procedures, provides an overview and aspects of user-defined functions and procedures, and how to create functions and procedures.
Passing Data to Parameters

Discusses ways and how to pass data to parameters.
Object-Oriented Programming

Discusses how you can create self-contained application components that respond to user actions and to the system and which can be easily maintained and reused.
Accessing APIs

Discusses how you can extend an application by taking advantage of external libraries such as Microsoft ActiveX controls or dynamic-link libraries (DLLs).
How to: Create Quit Routines

Describes how to create customized quit routines when users quit your application, Visual FoxPro, or Microsoft Windows.

Related Sections

Using Visual FoxPro

Provides an overview of Visual FoxPro features, describes concepts and productivity tools for developing, programming, and managing high-performance database applications and components.
Developing Visual FoxPro Applications

Explains concepts about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Development Productivity Tools

Discusses the developer tools for application development within the Visual FoxPro application and the Visual FoxPro language.
Walkthroughs

Provides common scenarios and step-by-step guides on how to create different types of applications and components.


Basic Programming Concepts

Visual FoxPro 9.0
Basic Programming Concepts
See Also

When you write a program, you can store data and manipulate it with a series of instructions. Data and data storage containers are the basic building blocks in programs, and you use commands, functions, and operators to manipulate data and data storage containers.

Storing Data

The data that you work with can include amounts of time, money, and countable items, as well as dates, names, descriptions, and so on. Each piece of data is a certain type: it belongs to a category of data that you manipulate in similar ways. You could work directly with this data without storing it, but you would lose most of the flexibility and power of Visual FoxPro. Visual FoxPro provides numerous storage containers to extend your ability to easily manipulate data.

Data types determine how data is stored and how it can be used. You can multiply two numbers together, but you can't multiply characters. You can print characters in uppercase, but you can't print numbers in uppercase. Some of the primary data types in Visual FoxPro are listed in the following table.

Data Types

Type | Examples
Numeric | 123 3.1415 – 7
Character | "Test String" "123" "01/01/98"
Logical | .T. .F.
Date DateTime | {^1998-01-01} {^1998-01-01 12:30:00 p}

Data Containers

Data containers allow you to perform the same operations on multiple pieces of data. For example, you add the hours an employee has worked, multiply them by the hourly wage, and then deduct the taxes to determine the amount of pay the employee has earned. You'll have to perform these operations for every employee and every pay period. If you store this information in containers, and perform the operations on the containers, you can just replace the old data with new data and run the same program again. This table lists some of the main containers for data in Visual FoxPro.

Type | Description
Variables | Single elements of data stored in your computer's RAM (Random Access Memory).
Table Records | Multiple rows of predetermined fields, each of which can contain a predefined piece of data. Tables are saved to disk.
Arrays | Multiple elements of data stored in RAM.

Manipulating Data

Containers and data types give you the building blocks you need to manipulate data. The final pieces are operators, functions, and commands.

Using Operators

Operators tie data together. Here are the most common operators in Visual FoxPro.

Operator | Valid Data Types | Example | Result
= | All | ? n = 7 | Prints .T. if the value stored in the variable n is 7, .F. otherwise
+ | Numeric, Character, Date, DateTime | ? "Fox" + "Pro" | Prints "FoxPro"
! or NOT | Logical | ? !.T. | Prints .F.
*, / | Numeric | ? 5 * 5 ? 25 / 5 | Prints 25 Prints 5
Note:
A question mark (?) in front of an expression causes a new line character and the results of the expression to be printed in the active output window, which is usually the main Visual FoxPro window.

Remember that you must use the same type of data with any one operator. The following statements store two numeric pieces of data to two variables. The variables have been given names that start with n so we can tell at a glance that they contain numeric data, but you could name them with any combination of alphanumeric characters and underscores.

nFirst = 123

nSecond = 45

The following statements store two pieces of character data to two variables. The variables have been given names that start with c to indicate that they contain character data.

cFirst = "123"

cSecond = "45"

The following two operations, addition and concatenation, yield different results because the type of data in the variables is different.

? nFirst + nSecond

? cFirst + cSecond

Output

168

12345

Because cFirst is character data and nSecond is numeric data, you get a data type mismatch error if you try the following command:

? cFirst + nSecond

You can avoid this problem by using conversion functions. For example, STR( ) returns the character equivalent of a numeric value and VAL( ) returns the numeric equivalent of a character string of numbers. These functions and LTRIM( ), which removes leading spaces, enable you to perform the following operations:

? cFirst + LTRIM(STR(nSecond))

? VAL(cFirst) + nSecond

Output

12345

168

Using Commands

A command causes a certain action to be performed. Each command has a specific syntax, which indicates what must be included in order for the command to work. There are also optional clauses associated with commands that allow you to specify in more detail what you want.

For example, the USE command allows you to open and close tables.

USE Syntax | Description
USE | Closes the table in the current work area.
USE customer | Opens the CUSTOMER table in the current work area, closing any table that was already open in the work area.
USE customer IN 0 | Opens the CUSTOMER table in the next available work area.
USE customer IN 0 ; ALIAS mycust | Opens the CUSTOMER table in the next available work area and assigns the work area an alias of mycust.

The following table shows some examples of commands.

Command | Description
DELETE | Marks specified records in a table for deletion.
REPLACE | Replaces the value stored in record field with a new value.
Go | Positions the record pointer to a specific location in the table.

Controlling Program Flow

Visual FoxPro includes a special category of commands that "wrap around" other commands and functions, determining when and how often the other commands and functions are executed. These commands allow conditional branching and looping, two very powerful programming tools. The following program illustrates conditional branches and loops. These concepts are described in more detail after the example.

Suppose that you had 10,000 employees and wanted to give everybody making $30,000 or more a 3 percent raise, and everybody making under $30,000 a 6 percent raise. The following sample program accomplishes this task.

This program assumes that a table with a numeric field named salary is open in the current work area. For information about work areas, see "Using Multiple Tables" in Working with Tables.

Sample Program to Increase Employee Salaries

Code | Comments
SCAN | The code between SCAN and ENDSCAN is executed as many times as there are records in the table. Each time the code is executed, the record pointer moves to the next record in the table.
IF salary >= 30000.00 REPLACE salary WITH ; salary * 1.03 | For each record, if the salary is greater than or equal to 30,000, replace this value with a new salary that is 3% higher. The semicolon (;) after WITH indicates that the command is continued on the next line.
ELSE REPLACE salary WITH ; salary * 1.06 | For each record, if the salary is not greater than or equal to 30,000, replace this value with a new salary that is 6% higher.
ENDIF ENDSCAN | End of the conditional IF statement. End of the code that is executed for each record in the table.

This example uses both conditional branching and looping commands to control the flow of the program.

Conditional Branching

Conditional branching allows you to test conditions and then, depending on the results of that test, perform different operations. There are two commands in Visual FoxPro that allow conditional branching:

  • IF ... ELSE ... ENDIF

  • DO CASE ... ENDCASE

The code between the initial statement and the ENDIF or ENDCASE statement is executed only if a logical condition evaluates to true (.T.). In the example program, the IF command is used to distinguish between two states: either the salary is $30,000 or more, or it isn't. Different actions are taken depending on the state.

In the following example, if the value stored in the variable nWaterTemp is less than 100, no action is taken:

Copy Code
* set a logical variable to true if a condition is met.
IF nWaterTemp >= 100
   lBoiling = .T.
ENDIF
Note:
An asterisk at the beginning of a line in a program indicates that the line is a comment. Comments help the programmer remember what each segment of code is designed to do, but are ignored by Visual FoxPro.

If there are several possible conditions to check for, a DO CASE ... ENDCASE block can be more efficient and easier to keep track of than multiple IF statements.

Looping

Looping allows you to execute one or more lines of code as many times as you need to. There are three commands in Visual FoxPro that allow looping:

  • DO WHILE ... ENDDO

  • FOR ... ENDFOR

  • FOR EACH ... ENDFOR

  • SCAN ... ENDSCAN

Use SCAN when you are performing a series of actions for each record in a table, as in the example program just described. The SCAN loop enables you to write the code once and have it executed for each record as the record pointer moves through the table.

Use FOR when you know how many times the section of code needs to be executed. For example, you know there are a specific number of fields in a table. Because the Visual FoxPro function FCOUNT( ) returns this number, you can use a FOR loop to print the names of all the fields in the table:

Copy Code
FOR nCnt = 1 TO FCOUNT( )
   ? FIELD(nCnt)
ENDFOR

Use DO WHILE when you want to execute a section of code as long as a certain condition is met. You might not know how many times the code will have to execute, but you know when it should stop executing. For example, let's assume you have a table with people's names and initials, and you want to use the initials to look people up. You would have a problem the first time you tried to add a person who had the same initials as someone else already in your table.

To solve the problem, you could add a number to the initials. For example, Michael Suyama's identification code could be MS. The next person with the same initials, Margaret Sun, would be MS1. If you then added Michelle Smith to the table, her identification code would be MS2. A DO WHILE loop enables you to find the right number to append to the initials.

Sample Program with DO WHILE to Generate a Unique ID

Code | Comments
nHere = RECNO() | Save the location of the record.
cInitials = LEFT(firstname,1) + ; LEFT(lastname,1) nSuffix = 0 | Get the person's initials from the first letters of the firstname and lastname fields. Establish a variable to hold the number to be added to the end of a person's initials if necessary.
LOCATE FOR person_id = cInitials | See if there is another person in the table with the same initials.
DO WHILE FOUND( ) | If another record in the table has a person_id value that is the same as cInitials, the FOUND( ) function returns true (.T.) and the code in the DO WHILE loop executes. If no match is found, the next line of code to be executed is the line following ENDDO.
nSuffix = nSuffix + 1 cInitials = ; LEFT(cInitials,2); + ALLTRIM(STR(nSuffix)) | Prepare a fresh suffix and append it to the end of the initials.
CONTINUE | CONTINUE causes the last LOCATE command to be evaluated again. The program checks to see if the new value in cInitials already exists in the person_id field of another record. If so, FOUND( ) will still return .T. and the code in the DO WHILE loop will execute again. If the new value in cInitials is indeed unique, FOUND( ) will return .F. and program execution continues with the line of code following ENDDO.
ENDDO | End of the DO WHILE loop.
GOTO nHere REPLACE person_id WITH cInitials | Return to the record and store the unique identification code in the person_id field.

Because you don't know beforehand how many times you'll find matching identification codes already in use, you use the DO WHILE loop.

See Also

Other Resources

Object-Oriented Programming
Working with Tables
SCAN ... ENDSCAN Command
FOR ... ENDFOR Command
DO WHILE ... ENDDO Command
IF ... ELSE ... ENDIF Command
DO CASE ... ENDCASE Command
GETDIR( ) Function
USE Command


Working with Programs

Visual FoxPro 9.0
Working with Programs

Program files contain code for executing a series of instructions. Storing code in a program (.prg) file offers benefits such as the following:

  • You can create and save programs to run later instead of running them immediately.

  • You can edit programs in Visual FoxPro editing windows and format code blocks or entire program files.

  • You can edit and run programs multiple times.

  • You can run programs from menus, forms, and toolbars.

  • You can use programs to run other programs.

When your program is part of a project, you can also search for and replace code references and text and view definitions of code elements found in searches in the current program file. For more information, see How to: Search For Code References and How to: View Code Definitions.

In This Section

How to: Create Programs

Describes how to create a Visual FoxPro program.
How to: Edit Programs

Describes how to edit programs after you create them.
How to: Format Code in Programs

Describes how you can set formatting options and apply them to code in programs.
How to: Save Programs

Describes how to save the programs after you create and edit them.
How to: Run Programs

Describes how to run programs.

Related Sections

Working with Projects

Describes using projects as a way to develop large applications.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.
Language Reference

Contains descriptions of language elements in Visual FoxPro.
Development Productivity Tools

Describes Visual FoxPro developer tools that you can use for application development within the FoxPro application and the FoxPro language.


How to: Create Programs

Visual FoxPro 9.0
How to: Create Programs
See Also

You can create a standalone program, a program as part of a project, or programmatically.

Note:
After creating a program, make sure you save it. If you try to close an unsaved or modified program, Visual FoxPro prompts you to save the program or discard changes.

To create a standalone program

  1. On the File menu, click New.

  2. In the New dialog box, click Program, and then New File.

  3. In the editing window, type the code for the program.

To create a program in a project

  1. Open the project for your application in the Project Manager.

  2. In the Project Manager, expand the Code node.

  3. Click Programs, then New.

  4. In the editing window, type the code for the program.

To create a program programmatically

  • In the Command window, use the MODIFY COMMAND to open an editing window.

See Also

Other Resources

How to: Edit Programs
How to: Save Programs
Working with Programs
Project Manager Window
MODIFY COMMAND Command
Command Window


How to: Edit Programs

Visual FoxPro 9.0
How to: Edit Programs
See Also

After creating a program, you can make changes to it or an existing program.

Note:
After editing a program, make sure you save it.

To edit a standalone program

  1. On the File menu, click Open.

  2. In the Open dialog box, choose Program in the Files of type list to show only program files.

  3. Click the program you want to modify, and then OK.

To edit a program in a project

  1. Open the project for your application in the Project Manager.

  2. In the Project Manager, expand the Code node, and then the Programs node.

  3. In the Programs node, select the program you want, and click Modify.

To edit a program programmatically

  • In the Command window, perform one of the following:

    • Use the MODIFY COMMAND with the name of the program (.prg) file to open an editing window for the program. For example:

      Copy Code
      MODIFY COMMAND MyProgram
    • Use the MODIFY COMMAND with a question mark (?) to display the Open dialog box so you can browse for and select a program file. For example:

      Copy Code
      MODIFY COMMAND ?

See Also

Other Resources

How to: Save Programs
How to: Run Programs
Working with Programs
Project Manager Window
MODIFY COMMAND Command
Command Window


How to: Format Code in Programs

Visual FoxPro 9.0
How to: Format Code in Programs
See Also

You can format specific blocks of code or the entire program file by setting the options you want in the Beautify Options dialog box and then apply the formatting options you chose. After formatting the code using the Beautify tool, you can make any additional changes in the formatting of the code.

To set code formatting options

  1. Open the program file.

  2. To format a specific block of code, select the code you want to format.

    Note:
    To format the entire program, do not select any code.

  3. On the Tools menu, click Beautify.

  4. In the Beautify Options dialog box, select the formatting options you want.

    The formatting process uses the top line in the block selected for determining the base indentation level.

To apply formatting options to code

  • In the Beautify Options dialog box, click Run.

See Also

Other Resources

How to: Edit Programs
How to: Save Programs
Working with Programs
Beautify Options Dialog Box


How to: Save Programs

Visual FoxPro 9.0
How to: Save Programs
See Also

After you create or modify a program, save your changes.

To save a program

  • On the File menu, click Save.

Visual FoxPro saves programs with the .prg file name extension. After you save your program, you can run or modify it.

Note:
If you save a program that does not have a name, Visual FoxPro displays the Save As dialog box so you can specify a name for the program. If you save a program created in the Project Manager, Visual FoxPro adds the program to the project.

See Also

Other Resources

How to: Edit Programs
How to: Run Programs
Working with Programs


How to: Run Programs

Visual FoxPro 9.0
How to: Run Programs
See Also

After you save a program, you can run it.

To run a standalone program

  1. On the Program menu, click Do.

  2. In the Do dialog box, browse for and select the program you want.

  3. Click Do.

To run a program from a project

  1. Open the project for your application in the Project Manager.

  2. In the Project Manager, expand the Code node, and then the Programs node.

  3. In the Programs node, select the program you want, and click Run.

To run a program programmatically

  • In the Command window, perform one of the following:

    • Use the DO command with the name of the program (.prg) file to run the program. For example:

      Copy Code
      DO MyProgram
    • Use the DO command with a question mark (?) to display the Do dialog box so you can browse for and select a program file. For example:

      Copy Code
      DO ?

See Also

Other Resources

How to: Edit Programs
Working with Programs
DO Command
Command Window
Project Manager Window


Working with Procedures and Functions

Visual FoxPro 9.0
Working with Procedures and Functions

Visual FoxPro includes a wide range of native functions that you can use to perform data manipulation or other operations. Functions in Visual FoxPro perform operations on data and return results with a specific type. You can also create procedures and functions to store code that performs frequently or commonly used routines in your programs.

In This Section

User-Defined Procedures and Functions

Introduces procedures and functions that you can define and create in Visual FoxPro.
Parameters in Procedures and Functions

Describes how data passes to procedures and functions for processing.
How to: Create Procedures and Functions

Explains how to create procedures and functions.
How to: Call Procedures and Functions

Explains how to call native functions as well as user-defined functions and procedures.
Verifying Data Passed to Procedures and Functions

Describes ways to verify that correct data passes to procedures and functions.
Returning Data from Procedures and Functions

Describes how to return data from procedures and functions.

Reference

Functions

Lists functions available in Visual FoxPro.

Related Sections

Passing Data to Parameters

Describes how data passes to parameters by reference or by value.
Working with Programs

Introduces how to create and work with Visual FoxPro programs.
Programming in Visual FoxPro

Describes aspects of programming, such as basic programming concepts, working with programs, object-oriented programming, and optimizing applications, in Visual FoxPro.


User-Defined Procedures and Functions

Visual FoxPro 9.0
User-Defined Procedures and Functions
See Also

Defining commonly and frequently used routines and operations as separate procedures and functions can reduce program size and complexity, making code easier to read and maintain. For example, you need to make changes only once in the procedure or function instead of multiple times throughout your program. Procedures and functions make it possible for you to keep commonly used code in a single location so you can call it from different parts of your application.

Conventionally, a procedure contains code that performs an operation, while a function contains code that performs operations and returns a specific value. Most, if not all, native Visual FoxPro functions return values. In Visual FoxPro, both procedures and functions can return values. When you create procedures and functions, you can choose whether to follow the convention of returning a value only from functions.

For example, the following lines of code illustrate the basic form of a procedure and function:

Copy Code
PROCEDURE myProcedure
   * Insert procedure code.
ENDPROC

FUNCTION myFunction
 * Insert function code.
  RETURN myFuncReturnValue
ENDFUNC

In their basic forms, procedures and functions might not seem useful or different from each other. However, procedures and functions can also accept and process data that the calling program passes to them through parameters, which you can include as part of procedure and function definitions and calls. Data that passes to procedures and functions are sometimes referred to as "arguments". Procedures and functions also differ in the way that programs pass data to them by default. For more information, see Parameters in Procedures and Functions.

Functions that you create in Visual FoxPro are sometimes called user-defined functions (UDFs). You can include procedures or functions with other normal executable code in a program (.prg) file or standalone in a separate .prg file.

Note:
If you include procedures and functions with other code, they must exist at the end of the .prg file following all other normal code. You cannot include normal executable program code following procedures and functions in a .prg file. Only other user-defined procedures, functions, and class definitions can follow the first PROCEDURE or FUNCTION statement in the file.

See Also

Other Resources

How to: Create Procedures and Functions
How to: Call Procedures and Functions
Working with Procedures and Functions


Parameters in Procedures and Functions

Visual FoxPro 9.0
Parameters in Procedures and Functions
See Also

When a program calls a procedure or function, it can pass data to the procedure or function for processing. However, when you create a procedure or function that performs operations on data that passes to it from the calling program, the procedure or function must contain parameters in its definition to handle the data. The following sections contain information about working with parameters:

  • Defining Parameters in Procedures and Functions

  • Passing Data to Procedures and Functions

Defining Parameters in Procedures and Functions

When a program passes data to a procedure or function, the parameters in the procedure or function handles that data so the procedure or function can perform operations on the data. When you want to create procedures and functions that process data that the calling program passes to them, you need to include parameters in the procedure and function definitions.

The following lines of code illustrate the basic format for including parameters in procedure definition:

Copy Code
PROCEDURE myProcedure
   LPARAMETERS Par1, Par2, Par3, ...
   * Insert procedure code.
ENDPROC

-OR-

Copy Code
PROCEDURE myProcedure(Par1, Par2, Par3, ...)
  * Insert procedure code.
ENDPROC

The first procedure includes an LPARAMETERS statement that can contain one or more parameters. The second procedure lists the same parameters enclosed by parentheses (()) immediately following the procedure name. Using the LPARAMETERS statement or enclosing the parameter list in parentheses defines the parameters with local scope for the procedure. You can also use the PARAMETERS keyword instead of LPARAMETERS to accept privately scoped parameters. You can pass multiple values to a procedure or function by separating the values with commas.

For example, the following examples show procedure definitions that include parameters. The first procedure includes an LPARAMETERS statement and two parameters, myPar1 and myPar2. The second procedure lists the same parameters enclosed by parentheses (()) immediately following the procedure name. Both procedures add the value in myPar2 to myPar1 and assign the result to myPar1. By default, data passes to procedures by reference, so the new value of myPar1 replaces its original value.

Copy Code
PROCEDURE myProcedure
   LPARAMETERS myPar1, myPar2
   myPar1 = myPar1 + myPar2
ENDPROC

-OR-

Copy Code
PROCEDURE myProcedure(myPar1, myPar2)
  myPar1 = myPar1 + myPar2
ENDPROC

You can include parameters similarly in a function definition. For more information, see PROCEDURE Command, FUNCTION Command, LPARAMETERS Command, and PARAMETERS Command.

Passing Data to Procedures and Functions

You can pass data, or specifically, "arguments", from your program to procedures and functions in different ways, depending on the following:

  • Whether you want to pass data by reference or by value. For more information, see Passing Data to Parameters.

  • How you call the procedure or function. For more information, see How to: Call Procedures and Functions.

For example, when you call a procedure with the DO command, you can pass data using the WITH clause and a parameter list. In the following example, the variables myVar and myVar2 contain the values 4 and 5. When you call the procedure myProcedure using the DO command, the parameter list in the WITH clause passes the variables to the procedure:

Copy Code
myVar = 4
myVar2 = 5
DO myProcedure WITH myVar, myVar2

By default, variables and arrays pass to procedures by reference. Therefore, changes made in the procedure to passed variables and arrays are passed back to the calling program. For example, suppose the procedure increments the value in myVar by the value in myVar2. The modified value of myVar becomes the new value of myVar when the procedure returns control to the calling program.

Alternatively, if you want to use the DO command but want to pass data by value, enclose each parameter with parentheses (()) as shown in the following example:

Copy Code
DO myProcedure WITH (myVar), (myVar2)

When you call a function, you can pass data using a parameter list enclosed in parentheses (()) as shown in the following line of code:

Copy Code
myFunction(myVar, myVar2)

By default, variables and arrays pass to user-defined functions by value. Therefore, changes made in the function to passed variables and arrays are not passed back to the calling program. However, you can pass variables and arrays by reference by prefacing variables and arrays with the at sign (@) as shown in the following line of code:

Copy Code
myFunction(@var1, @var2, ...)

The following table summarizes the ways you can pass variables to procedures and functions in the example.

Procedure or function call | Comments
DO myProcedure WITH var1, var2, ... | Calls a procedure and passes variables by reference.
DO myProcedure WITH (var1), (var2), ... | Calls a procedure and passes variables by value.
myFunction(var1, var2, ...) | Calls a function and passes variables by value.
myFunction(@var1, @var2, ...) | Calls a function and passes variables by reference.

See Also

Other Resources

User-Defined Procedures and Functions
Verifying Data Passed to Procedures and Functions
How to: Create Procedures and Functions
Working with Procedures and Functions


How to: Create Procedures and Functions

Visual FoxPro 9.0
How to: Create Procedures and Functions
See Also

You can create procedures and functions programmatically.

To create a procedure

  1. Begin the procedure definition with the PROCEDURE command and the procedure name.

  2. To define parameters, on the second line of the procedure definition, include an LPARAMETERS or PARAMETERS statement with a list of parameters.

    -OR-

    On the same line as the PROCEDURE statement and immediately following the procedure name, include a parameter list enclosed in parentheses.

  3. On the following lines, include the code statements you want to execute in the procedure.

  4. End the procedure definition with the ENDPROC keyword.

For example, the following lines of code show a basic example of a procedure:

Copy Code
PROCEDURE myProcedure
   LPARAMETERS myPar1, myPar2
   myPar1 = myPar1 + myPar2
ENDPROC

-OR-

Copy Code
PROCEDURE myProcedure(myPar1, myPar2)
  myPar1 = myPar1 + myPar2
ENDPROC

By default, values pass to procedures by reference. Therefore, changes made to the passed values in the procedure are passed back to the calling program.

For more information, see PROCEDURE Command, PARAMETERS Command, and LPARAMETERS Command.

To create a function

  1. Begin the function definition with the FUNCTION command and the function name.

  2. To define parameters, on the second line of the procedure definition, include an LPARAMETERS or PARAMETERS statement with a list of parameters.

    -OR-

    On the same line as the FUNCTION statement and immediately following the function name, include a parameter list enclosed in parentheses.

  3. On the following lines, include the code statements you want to execute in the function.

  4. Include a RETURN statement when you want to return a value from the function and control of code execution to the calling program.

  5. End the procedure definition with the ENDFUNC keyword.

For example, the following lines of code show a basic example of a function:

Copy Code
FUNCTION myFunction
  LPARAMETERS myPar1, myPar2
  myFuncReturnValue = myPar1 + myPar2
  RETURN myFuncReturnValue
ENDFUNC

-OR-

Copy Code
FUNCTION myFunction(myPar1, myPar2)
  myFuncReturnValue = myPar1 + myPar2
  RETURN myFuncReturnValue
ENDFUNC

By default, values pass to user-defined functions by value. Therefore, changes made to the passed values in the function are not passed back to the calling program.

For more information, see FUNCTION Command, PARAMETERS Command, and LPARAMETERS Command.

See Also

Other Resources

How to: Call Procedures and Functions
Passing Data to Parameters
Returning Data from Procedures and Functions
User-Defined Procedures and Functions
Working with Procedures and Functions


How to: Call Procedures and Functions

Visual FoxPro 9.0
How to: Call Procedures and Functions
See Also

You can call native Visual FoxPro functions, user-defined functions, and procedures in different ways. In addition, you can call user-defined functions (UDFs) the same way you call procedures. You can call procedures that you create in a program (.prg) file as if they were standalone programs or as functions if your procedures return values you want to use.

Tip:
If you include procedures and user-defined functions in a separate program (.prg) file, you can open those files using the SET PROCEDURE command. For example, suppose you have a file called ProcFile.prg. The following line of code opens the file:

Copy Code
SET PROCEDURE TO ProcFile.prg

To call a Visual FoxPro or user-defined function

  • Call the function without storing the return value.

    -OR-

  • Call the function and assign the return value to a variable.

    -OR-

  • Include the function call within another command or function.

Some functions also accept data as arguments that are passed from the calling program. For more information, see Passing Data to Parameters and Parameters in Procedures and Functions.

In the following example, the first line of code calls the DATE( ) function, which returns the current system date, without performing any operations with the return value. The second line of code stores the return value to a variable named dToday. The third line of code includes the function in another command and sends the return value to the currently active output window. The fourth line of code includes the function in another function and passes the return value to the outer function, which returns the day of the week.

Copy Code
DATE( )
dToday = DATE( )
? DATE( )
DOW(DATE( ))

For more information, see Returning Data from Procedures and Functions.

To call a procedure

  • Use the DO command followed by the procedure name.

In the following example, the DO command calls procedures named myProc1 and myProc2. The first line of code calls myProc1 without arguments. The second line of code includes the WITH clause in the DO command to pass a list of arguments to myProc2.

Copy Code
DO myProc1
var1=4
var2=5
DO myProc2 WITH (var1, var2)

For more information, see DO Command.

See Also

Other Resources

User-Defined Procedures and Functions
How to: Create Procedures and Functions
Working with Procedures and Functions


Verifying Data Passed to Procedures and Functions

Visual FoxPro 9.0
Verifying Data Passed to Procedures and Functions
See Also

When passing data or "arguments" to parameters in procedures and functions, it is recommended that you verify that the data that procedures and functions receive is as expected. You can use the TYPE( ) and PARAMETERS( ) functions to verify the type and number of arguments passed to procedures and functions.

Verifying Data Type Passed to Parameters

You can use the TYPE( ) function to verify that data passed to parameters has the correct type. In the following example, the function accepts a date value through the parameter dDate. The function returns a date that is 14 days later than the date that was passed:

Copy Code
FUNCTION plus2weeks( dDate )
   PARAMETERS dDate
   RETURN dDate + 14
ENDFUNC

The parameter in the function requires a value with Date type. The following version of the function includes code that uses the TYPE( ) function to make sure that the passed value has the correct type:

Copy Code
FUNCTION plus2weeks( dDate )
   IF TYPE("dDate") = "D"
      RETURN dDate + 14
   ELSE
      MESSAGEBOX( "Function requires a date value." )
      RETURN { - - }      && Return an empty date.
   ENDIF
ENDFUNC

Verifying the Correct Number of Arguments

When a program passes more arguments than the procedure or function expects, Visual FoxPro generates an error message. When a program passes fewer arguments than the procedure or function expects, the remaining parameters are initialized to False (.F.).

For example, suppose you include two parameters in a procedure definition, but you call the procedure with three arguments, Visual FoxPro generates an error message. However, if you call the procedure with only one argument, the remaining parameter is initialized to False (.F.). However, there is no way to know whether the argument for the last parameter was truly omitted or merely evaluated to .F. Therefore, the following example code uses the PARAMETERS( ) function to check for the appropriate number of arguments:

Copy Code
FUNCTION SaveValue( cStoreTo, cNewVal, lIsInTable )
   IF PARAMETERS( ) < 3
      MESSAGEBOX( "Too few parameters passed." )
      RETURN .F.
   ENDIF
   IF lIsInTable
      REPLACE (cStoreTo) WITH (cNewVal)
   ELSE
      &cStoreTo = cNewVal
   ENDIF
   RETURN .T.
ENDFUNC

See Also

Other Resources

Parameters in Procedures and Functions
How to: Create Procedures and Functions
Working with Procedures and Functions


Returning Data from Procedures and Functions

Visual FoxPro 9.0
Returning Data from Procedures and Functions
See Also

Conventionally, functions return values to the calling program. However, in Visual FoxPro, you can return values from procedures and functions. When procedures and functions do not include explicit RETURN statements that return a specified value, Visual FoxPro includes an implicit RETURN statement that returns a default value of True (.T.) automatically. Generally, you want to use the RETURN command to return a specified value from functions, for example, as a processing result or to indicate whether the function operation succeeded.

Note:
The RETURN command also returns control over code execution to the calling program. For more information, see RETURN Command.

In the following example, suppose you pass a date to the following function. The function returns a date that is 14 days later than the date that was passed:

Copy Code
FUNCTION plus2weeks
   PARAMETERS dDate
   RETURN dDate + 14
ENDFUNC

You can then assign the return value from the function to a variable as shown in the following line of code:

Copy Code
dDeadLine = plus2weeks(DATE())

Assigning Return Values from Procedures and Functions

You can assign values returned from procedures and functions explicitly, for example, to a variable, by using the equal sign (=) operator or pass the return value directly, for example, to another function.

In the following example, suppose the function myFunc returns a specific value. The first line of code assigns the return value from myFunc to a variable named myVar. The second line of code passes the return value from myFunc directly to a Visual FoxPro STR( ) function, whose return value is then displayed to the current active output window using the ? command:

Copy Code
myVar = myFunc( )
? STR( myFunc( ) )

See Also

Other Resources

How to: Create Procedures and Functions
How to: Call Procedures and Functions
Working with Procedures and Functions


Passing Data to Parameters

Visual FoxPro 9.0
Passing Data to Parameters
See Also

You can pass data, such as variables and array elements, as "arguments" to parameters by reference or by value. Passing data by reference saves changes made to data and passes those changes back to the calling program. Passing data by value passes a copy of the data for processing, leaving the original data intact.

By default, data passes to procedures by reference and to user-defined functions (UDFs) by value. However, you can change the default protocols for passing data through parameters, although Visual FoxPro always passes objects by reference.

Note:
When passing entire arrays to parameters, you must pass them by reference. If you do not pass arrays by reference, only the first element is passed. Therefore, individual array elements are always passed by value.

See Also

Other Resources

How to: Pass Data to Parameters by Reference
How to: Pass Data to Parameters by Value
Parameters in Procedures and Functions
Programming in Visual FoxPro


How to: Pass Data to Parameters by Reference

Visual FoxPro 9.0
How to: Pass Data to Parameters by Reference
See Also

You can pass data to parameters by reference throughout a program or at specific locations.

To pass parameters by reference throughout a program

  • Precede code where you want to pass data to parameters by reference with the following line of code:

    Copy Code
    SET UDFPARMS TO REFERENCE

For more information, see SET UDFPARMS Command.

To pass parameters by reference at specific locations

  • Preface the variable or array name with an at sign (@) as shown in the following example:

    Copy Code
    myFunc(@var1, var2)

See Also

Other Resources

How to: Pass Data to Parameters by Value
Passing Data to Parameters


How to: Pass Data to Parameters by Value

Visual FoxPro 9.0
How to: Pass Data to Parameters by Value
See Also

You can pass parameters by value throughout a program or at specific locations.

To pass parameters by value throughout a program

  • Precede code where you want to pass data to parameters by value with the following line of code:

    Copy Code
    SET UDFPARMS TO VALUE
Note:
Using SET UDFPARMS TO VALUE does not affect the WITH clause in the DO command, which, by default, passes arguments to parameters by reference.

For more information, see SET UDFPARMS Command.

To pass parameters by value at specific locations

  • Enclose the variable or array name with parentheses (()) as shown in the following example:

    Copy Code
    DO myProcedure WITH (myVar), (myVar2)

See Also

Other Resources

How to: Pass Data to Parameters by Reference
Passing Data to Parameters


Object-Oriented Programming

Visual FoxPro 9.0
Object-Oriented Programming

While Visual FoxPro supports standard procedural programming, it also includes the power and flexibility of object-oriented programming. Object-oriented design and object-oriented programming represent a change in focus from standard procedural programming. Instead of thinking about program flow from the first line of code to the last line of code, think about creating objects. You can create and manipulate objects as self-contained components of an application and use them to provide public functionality that you can expose to users as well as private.

In This Section

Working with Classes in Visual FoxPro

Introduces classes in Visual FoxPro and how to use them to create objects.
Working with Objects in Visual FoxPro

Introduces objects in Visual FoxPro and how to create and use them.
Understanding the Event Model

Introduces events and how you can use them to perform operations when the system or user performs an action.

Related Sections

Programming in Visual FoxPro

Describes aspects of programming, such as basic programming concepts, working with programs, object-oriented programming, and optimizing applications, in Visual FoxPro.
Working with Programs

Introduces how to create and work with Visual FoxPro programs.
Optimizing Applications

Describes ways to optimize your stable application's performance by making it smaller and faster.
Accessing APIs

Describes how to extend Visual FoxPro if your application has requirements that cannot be met by the built in features by taking advantage of external libraries such as Microsoft ActiveX controls or dynamic-link libraries (DLLs).


Working with Classes in Visual FoxPro

Visual FoxPro 9.0
Working with Classes in Visual FoxPro

Visual FoxPro includes the capability to work with classes as part of providing the features of object-oriented programming. When you design and create a class, you are building a template so you can create objects from that class. Visual FoxPro includes designers and other tools for creating and managing classes.

In This Section

Classes in Visual FoxPro

Provides an overview of classes in Visual FoxPro and discusses the benefits that classes provide.
Base Classes in Visual FoxPro

Provides a list of the base classes provided in Visual FoxPro.
Subclasses in Visual FoxPro

Provides an overview of subclasses in Visual FoxPro and provides possible uses for them.
Considerations for Creating Classes

Contains information on best practices for creating classes.
How to: Create Classes and Subclasses

Describes how to create classes and subclasses using the Visual FoxPro Class Designer or programmatically.
How to: Implement Strong Typing for Class, Object, and Variable Code

Describes how to implement strong typing so that you have more control over code and can make IntelliSense available for certain Visual FoxPro elements.
How to: Modify Classes

Describes how to modify a class using the Class Designer and when it is in a project.
How to: Add Properties to Classes

Describes how you can add custom properties to a class.
How to: Create Access and Assign Methods

Describes how you can create new Access and Assign Methods for properties.
How to: Add Methods to Classes

Describes how you can add custom methods to a class.
How to: Add Code to Methods and Events

Describes how to add custom code to a method or event.
How to: Modify Class and Class Member Attributes

Describes how to add or edit the description for classes and attributes for custom properties and methods.
How to: Remove Properties and Methods from Classes

Describes how to remove custom properties and methods from a class.
How to: Specify Design-Time Appearance for Classes

Describes how you can specify the appearance of non-visual classes in design-time.
How to: Add Classes to Visual FoxPro Tools

Describes how to add custom classes to the Visual FoxPro Toolbox and Form Controls toolbar and how to register a class library.
Access and Assign Methods

Provides an overview about Access and Assign methods that you can use to execute code when querying or attempting to change the value of a property.
Protecting and Hiding Class Members

Provides an overview about designating properties and methods as hidden or protected.
Overriding Default Property Settings

Provides an overview about overriding the default setting of a property for a user-defined class.
Overriding and Calling Parent Class Code

Provides an overview about how to call or override parent class code.

Related Sections

Working with Objects in Visual FoxPro

Introduces objects in Visual FoxPro and how to create and use them.
Understanding the Event Model

Introduces events and how you can use them to perform operations when the system or user performs an action.
Object-Oriented Programming

Discusses how you can create self-contained application components that respond to user actions and to the system and which can be easily maintained and reused.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Classes in Visual FoxPro

Visual FoxPro 9.0
Classes in Visual FoxPro
See Also

Classes define properties, methods, and events, which are characteristics and functionality that objects possess and that you can use to manipulate objects. Classes can also contain other objects or data members such as variables. When an object, or instance, is created from a class, it contains the properties, methods, events, and any other objects or members as defined by the class.

The properties that a class defines specify characteristics for an object of that class. For example, the CommandButton class has a Name property, which defines the name of the command button as opposed to the Caption property, which defines the text that the command button displays to the user.

The methods of a class define and store procedure code that runs when you call the method for an object of that class. For example, the CommandButton class has a Move method, which moves the command button to coordinates that you specify.

The events of a class define code that executes when the system or user performs actions that trigger the events for an object of that class. For example, the CommandButton class contains a Click event, which is a procedure that you can use to define code that executes when the user clicks the command button.

Classes can also contain other objects, for example, a Form class can contain a control object, such as a command button. You can also specify data members, such as variables, as part of a class.

The following sections provide more information about Visual FoxPro classes:

  • Benefits of Using Classes

  • Types of Visual FoxPro Classes

For more information about objects in Visual FoxPro, see Working with Objects in Visual FoxPro.

Benefits of Using Classes

Classes provide the following features that make it possible for you to create reusable and more maintainable code:

  • Encapsulation

    Encapsulation, which includes packaging property and method code into an object, hides unnecessary complexity and helps contribute to abstraction. Abstraction makes it possible for you to focus on aspects of the object that you want or need to use instead of the low-level details.

    For example, when a person uses a computer, the person usually does not want to know how it operates, such as how it processes data or maintains files. The person wants to accomplish tasks, such as write a letter, and does not need to know how those tasks are performed.

    Likewise, a list box class encapsulates properties controlling how items display in the list box and functionality determining the actions performed when choosing items in the list box into a single control.

  • Subclass creation

    For more information, see Subclasses in Visual FoxPro.

  • Inheritance

    For more information, see Subclasses in Visual FoxPro.

These features help you create and maintain code more easily and quickly.

Types of Visual FoxPro Classes

Visual FoxPro classes, and by extension, objects, fall into two primary types: container classes and control classes. Classes can also be visual or non-visual.

Container Classes and Control Classes

Containers can consist of other objects, such as controls, and provide access to the objects they contain. Control classes are more encapsulated than container classes; however, for that reason, they can be less flexible. Control classes do not have an AddObject Method.

For example, suppose you create a container class that consists of two list boxes and two command buttons. You then add an object based on the container class to a form. You can manipulate each object in the container at design time and run time; for example, you can change the positions of the list boxes or the captions of the command buttons. You can also add other objects to the container at design time; for example, you can add labels to identify the list boxes.

The following table lists examples of objects that can exist in container classes.

Container | Can contain
Column | Headers and any objects except form sets, forms, toolbars, timers, and other columns
CommandGroup | Command buttons
Container | Any controls
Control | Any controls
Custom | Any controls, data environment, page frame, container, custom
DataEnvironment | Cursors, relations, and cursor adapters
FormSet | Forms, toolbars
Form | Page frames, data environment, any controls, containers, custom
Grid | Columns
OptionGroup | Option buttons
PageFrame | Pages
Page | Any controls, containers, custom
Project | Files, servers
Toolbar | Any controls, page frame, container

Visual and Non-Visual Classes

In Visual FoxPro, objects and controls created from visual classes display a visual element at design time and run time. Objects and controls based on non-visual classes, such as the Custom class and Timer control, display a visual element only at design time but not at run time.

See Also

Other Resources

Base Classes in Visual FoxPro
Considerations for Creating Classes
How to: Create Classes and Subclasses
Working with Classes in Visual FoxPro


Base Classes in Visual FoxPro

Visual FoxPro 9.0
Base Classes in Visual FoxPro
See Also

Visual FoxPro provides a default set of classes, or base classes, that you can use immediately to provide basic functionality in your application. The following table lists the base classes in Visual FoxPro, though not all base classes are available in the Class Designer or for creating subclasses.

CheckBox | Collection | Column* | ComboBox
CommandButton | CommandGroup | Container | Control
Cursor | CursorAdapter | Custom | DataEnvironment
EditBox | Empty* | Exception | Form
FormSet | Grid | Header* | Hyperlink
Image | Label | Line | ListBox
OLE Bound | OLE Container | OptionButton | OptionGroup
Page | PageFrame | ProjectHook | Relation
ReportListener | Separator | Session Object | Shape
Spinner | TextBox | Timer | ToolBar
XMLAdapter | XMLField | XMLTable |

* Not available for subclass creation

All Visual FoxPro base classes except the Empty class recognize the following minimum set of events:

  • Init Event

  • Destroy Event

  • Error Event

All Visual FoxPro base classes except the Empty class have the following minimum set of properties:

  • Class Property

  • BaseClass Property

  • ClassLibrary Property

  • ParentClass Property

See Also

Other Resources

Classes in Visual FoxPro
Considerations for Creating Classes
How to: Create Classes and Subclasses
Working with Classes in Visual FoxPro


Subclasses in Visual FoxPro

Visual FoxPro 9.0
Subclasses in Visual FoxPro
See Also

You can create a new class or a subclass from most of the Visual FoxPro base classes or other existing classes. A subclass can include some or all the functionality of the original, or parent, class, plus any additional characteristics, such as custom default properties, or functionality that you want to include to customize the new class.

Creating and using subclasses offer the benefits of reusability by helping to decrease the amount of code you need to write, and inheritance, which saves time and effort updating classes when you make changes to a parent class. When you modify a parent class, the changes you make propagate to all subclasses that inherit from the parent class.

For example, suppose you have a command button class. You can create a subclass from the command button class that contains all the standard properties, methods, and events for a command button plus additional properties or functionality you want to include, such as displaying the command button with a certain color or size or performing actions such as displaying a specific message when clicked.

Subclasses are not limited to a single class. For example, you can add multiple controls to a container class definition, such as a form class. Many of the classes in the Visual FoxPro sample class library fall into this category. For more information, see Sample Class Libraries.

See Also

Other Resources

Considerations for Creating Classes
How to: Create Classes and Subclasses
Working with Classes in Visual FoxPro


Considerations for Creating Classes

Visual FoxPro 9.0
Considerations for Creating Classes
See Also

There are many different contexts for creating and using classes and subclasses. However, using strategic planning, you can determine more effectively which classes you need to design and the type of functionality to include in those classes. When creating classes, remember the following considerations.

  • Be selective when creating classes.

    Though you can create a class for every control and form you might want to use, this strategy might not be the most effective way to design your application. The result might be that you have many classes that perform the same task but need to be maintained separately.

  • Create and use control classes for encapsulating generic functionality.

    You can provide generic functionality in your application creating control classes. For example, you can create command buttons that users click to move record pointers in tables, close forms, or open a Help file and save them as classes so you can add the controls to forms.

    You can expose properties and methods on a class so that the user can integrate them into the particular data environment of a form or form set.

  • Determine the functionality you want to include for classes at the class level, subclass level, and object level in advance.

    When you create subclasses and objects from the classes you create, you can include additional properties, methods, and events in those subclasses, and by extension, objects created from those classes. You can also choose to override default property values as well as method and event code as specified by the original class.

  • Provide a consistent look and feel for your application.

    You can create form, form set, and control classes with a distinctive appearance so that all the components of your application have the same look. For example, you can add graphics and specific color patterns to a form class and use that class as a template for all forms you create. You can create a text box class with a distinctive appearance, such as a shadowed effect, and use this class throughout your application any time you want to add a text box.

See Also

Other Resources

Classes in Visual FoxPro
How to: Create Classes and Subclasses
Working with Classes in Visual FoxPro


How to: Create Classes and Subclasses

Visual FoxPro 9.0
How to: Create Classes and Subclasses
See Also

You can create classes and subclasses using the Visual FoxPro Class Designer or programmatically. When you use the Class Designer to create classes, you can view the class as you design it.

Tip:
For convenience and speed, you might want to keep a class and all its subclasses in one class library. If you have a class that contains elements from different class libraries, these libraries must all be open, so it might take longer to initially load the class at design time and run time.

To create a class or subclass

  1. On the File menu, choose New.

  2. In the New dialog box, choose Class, and then click New File.

    The New Class dialog box opens.

  3. In the Class Name box of the New Class dialog box, type the name of the class.

  4. In the Based On box, select the name of a Visual FoxPro base class.

    Tip:
    To create a user-defined class, choose Custom as the base class. When you choose the Custom base class, the class you create is a non-visual class, which displays a visual element at design time but not at run time. For more information, see Custom Object and How to: Specify Design-Time Appearance for Classes.

    -OR-

    Click the ellipsis (...) button to select a visual class library (.vcx) file.

  5. In the Store In box, type the name of the class library file for storing the class.

  6. Click OK.

    The Class Designer opens and displays the class.

  7. When you are finished with creating the class, save the class.

    The class is saved in a Visual FoxPro visual class library (.vcx) file.

Visual FoxPro stores classes you create using the Class Designer in visual class library (.vcx) files. These classes include visual and non-visual classes.

For more information about base classes in Visual FoxPro, see Base Classes in Visual FoxPro. For more information about the Class Designer, see Class Designer.

You can also add classes and subclasses to an existing class library. For more information, see How to: Add Classes and Subclasses to Class Libraries.

To create classes or subclasses in a project

  1. Open the project for your application.

  2. In the Project Manager, choose the Classes tab, and click New.

    The New Class dialog box opens so you can specify information for the new class or subclass.

  3. Follow the steps for creating a class or subclass.

For more information, see Project Manager Window.

To create classes and subclasses programmatically

  • Use the CREATE CLASS command or DEFINE CLASS command.

The CREATE CLASS command opens the Class Designer, while the DEFINE CLASS command is for programmatic use. You can also create and add properties and methods and add code to respond to events for the class by using the DEFINE CLASS command.

Note:
If you store class definitions in a program (.prg) file when you use DEFINE CLASS, you can precede, but not follow, class definitions with program code. This is similar to not following procedures with program code in a program.

For more information, see CREATE CLASS Command and DEFINE CLASS Command.

See Also

Other Resources

Classes in Visual FoxPro
How to: Modify Classes
How to: Add Properties to Classes
How to: Add Methods to Classes
Working with Classes in Visual FoxPro


How to: Implement Strong Typing for Class, Object, and Variable Code

Visual FoxPro 9.0
How to: Implement Strong Typing for Class, Object, and Variable Code
See Also

To gain more control over your code, make coding easier and less vulnerable to errors, and make IntelliSense functionality available for visual objects, class references, ActiveX controls, COM servers, and user-defined code elements, use strong typing. OLEPUBLIC type libraries also use strong typing.

Note:
Visual FoxPro is not a strongly typed language and does not require that you declare variables with a specific data types. Visual FoxPro does not enforce strong typing at design time or run time.

For more information, see IntelliSense Support in Visual FoxPro.

To implement strong typing

  • For objects, method parameters, and values, use the AS clause in the DEFINE CLASS command.

-OR-

  • For parameter and variable declarations, use the AS clause in following commands:

    • FUNCTION Command

    • LOCAL Command

    • LPARAMETERS Command

    • PARAMETERS Command

    • PROCEDURE Command

    • PUBLIC Command

When you use the AS clause in code, IntelliSense displays a drop-down list of available types, including types from the following sources:

  • Visual FoxPro object base classes.

  • Visual FoxPro data types.

The following example uses the AS clause in the DEFINE CLASS command to implement strong typing for the custom OLEPUBLIC class and the method MyMethod:

Copy Code
DEFINE CLASS MyClass1 AS Custom OLEPUBLIC
   FUNCTION MyMethod (MyParam1 AS integer, MyParam2 AS string) AS integer
      RETURN MyParam1
   ENDFUNCTION
ENDDEFINE

The following example uses the AS clause in the LOCAL, PUBLIC, LPARAMETERS, PARAMETERS, and FUNCTION commands to implement strong typing:

Copy Code
LOCAL oExcel AS "excel.application"
oExcel = CREATEOBJECT("excel.application")
oExcel.   && Displays a list of members.

PUBLIC ARRAY MyArray[2] AS _form OF ffc\_base
LPARAMETERS MyParam1 AS String OF _Base.vcx
PARAMETERS MyParam1 AS Custom OF MyBase.vcx
FUNCTION MyFunction AS Custom

See Also

Other Resources

Considerations for Creating Classes
How to: Create Classes and Subclasses
How to: Modify Classes
Working with Classes in Visual FoxPro


How to: Modify Classes

Visual FoxPro 9.0
How to: Modify Classes
See Also

After you create a class, you can make changes to the class. Changes that you make to the class propagate to all subclasses and objects based on the class. For example, suppose you add an enhancement to a class or fix a bug in the class. All the subclasses and objects based on the class inherit the change.

Caution:
If the class is being used in any other application components, do not change the Name property of the class. Otherwise, Visual FoxPro will not be able to locate the class when it is needed.

You can modify classes by opening the Class Designer through the Visual FoxPro IDE, the Class Browser, the Project Manager if the class is part of a project, or programmatically.

To modify a class

  1. On the File menu, choose Open.

  2. In the Files of type box in the Open dialog box, select the class library you want to open, and click OK.

    An Open dialog box appears for you to select a class from the class library you opened.

  3. In the Class Name list of the Open dialog box, select a class, and click Open.

    The class you selected opens in the Class Designer.

    -OR-

  4. In the Class Browser, open the class library you want.

    For information about opening class libraries, see How to: Open Class Libraries.

  5. In the class list, right-click the class and choose Modify.

    The class you selected opens in the Class Designer.

To modify a class in a project

  1. Open the project containing the class you want.

  2. In the Project Manager, select the class you want, and click Modify.

    The class you selected opens in the Class Designer.

You can also modify classes in visual class library (.vcx) files using the MODIFY CLASS command to open the Class Designer.

For example, typing the following line in the Command window opens the class MyClass, which is stored in the class library MyClassLibrary, in the Class Designer so you can modify it:

Copy Code
MODIFY CLASS MyClass OF MyClassLibrary

For more information, see MODIFY CLASS Command.

See Also

Other Resources

Classes in Visual FoxPro
How to: Add Properties to Classes
How to: Add Methods to Classes
Working with Classes in Visual FoxPro


How to: Add Properties to Classes

Visual FoxPro 9.0
How to: Add Properties to Classes
See Also

When you create a class, you can add custom properties to the class. For more information about properties, see Classes in Visual FoxPro.

Note:
When you create custom properties for classes, the properties apply to the class, not to individual components in the class.

You can add properties to classes using the Visual FoxPro IDE or programmatically.

To add a property to a class

  1. Open the class in the Class Designer.

    When the class opens in the Class Designer, the Class menu appears.

  2. On the Class menu, choose New Property.

  3. In the Name box of the New Property dialog box, type the property name.

  4. In the Visibility box, choose the visibility level for the property.

  5. To create an Access method, select Access Method. To create an Assign method, select Assign method. To create both Access and Assign methods, select both boxes.

  6. To specify a default value other than False (.F.) for the property, include a different default value in the Default Value box.

    Tip:
    To set the default value of a property an empty string (""), click in the Default Value box and press the SPACE key.

  7. To specify a description to display for the property in the Properties window, include a description in the Description box.

    Tip:
    You can document valid property values in the Description box.

  8. Click Add.

  9. Continue adding properties, or if you are finished, click Close.
Note:
Properties in subclasses inherit the default property values that you specify unless you reset the default values to those of the parent class. When you add a property that can be set by the user, the user might enter an invalid property value that can cause run-time errors. It is recommended that you include code in your application that validates values entered for the property or that you document the valid property values.

After you add the property, it appears in the Properties window at the end of the properties list along with any default value that you specified. You can change values for the property in the Properties Window.

For more information about opening classes, see How to: Modify Classes. For more information about visibility levels for properties, see Protecting and Hiding Class Members. For more information, see Access and Assign Methods and How to: Create Access and Assign Methods.

To add properties to classes programmatically

  • Use the DEFINE CLASS command.

    At run time, you can add properties to objects by using the ADDPROPERTY( ) function or the object's AddProperty method.

For more information, see DEFINE CLASS Command, ADDPROPERTY( ) Function, and AddProperty Method.

Array Properties

You can create and add array properties to a class. Array properties are arrays that you can add to the class as properties. An array property is read-only at design time and appears in italic in the Properties window; however, you can manipulate and redimension an array property at run time. For example, you can create an array property for a form to store object variables associated with each instance of a form. For an example of using an array property, see How to: Manage Multiple Instances of a Form. For information about limits on the number of elements in arrays, see Visual FoxPro System Capacities.

To create an array property

  1. Follow the steps for adding a property to a class.

  2. In the Name box of the New Property dialog box, type the name, size, and dimension of the array.

For example, specifying myArrayProperty[10,2] creates an array property named myArrayProperty with ten rows and two columns.

See Also

Other Resources

How to: Add Methods to Classes
Working with Classes in Visual FoxPro


How to: Create Access and Assign Methods

Visual FoxPro 9.0
How to: Create Access and Assign Methods
See Also

You can create Access and Assign methods for new custom properties, native Visual FoxPro properties, or existing custom properties. You can create them when adding or editing custom properties. For more information about Access and Assign methods, see Access and Assign Methods. For information about adding custom properties to forms, form sets, and classes, see How to: Add Properties to Forms and How to: Add Properties to Classes.

You can create Access and Assign methods interactively in the Form Designer or Class Designer. To create Access and Assign methods for properties of forms and form sets, use the Form Designer. To create Access and Assign methods for properties of classes for controls and other objects, use the Class Designer. You can also create Access and Assign methods programmatically.

To create an Access or Assign method when adding a new property

  1. In the New Property dialog box, select the Access Method box, the Assign Method box, or both.

  2. When you are finished creating the property, click Add.

When you create an Access or Assign method, the new method is added to the end of the properties list in the Properties window and appears with the suffix, _access or _assign.

For more information, see New Property Dialog Box.

To create an Access or Assign method for a native Visual FoxPro property

  1. If you are in the Form Designer, on the Form menu, choose New Method.

    -OR-

    If you are in the Class Designer, on the Class menu, choose New Method.

  2. In the Name box of the New Method dialog box, type the name of the native Visual FoxPro property followed with the suffix _ACCESS or _ASSIGN.

  3. When you are finished creating the method, click Add.

For more information, see New Method Dialog Box.

To create an Access or Assign method for existing custom properties

  1. If you are in the Form Designer, on the Form menu, choose Edit Property/Method.

    -OR-

    If you are in the Class Designer, on the Class menu, choose Edit Property/Method.

  2. In the Edit Property/Method dialog box, select the property you want.

  3. Select the Access Method box, the Assign Method box, or both.

  4. Click Apply, and then Close.

For more information, see Edit Property/Method Dialog Box.

When you create an Access or Assign method for an existing custom property, the new method is added to the end of the properties list in the Properties window and appears with the suffix, _access or _assign.

To create Access and Assign methods programmatically

  • Use the DEFINE CLASS command and include the PROCEDURE clause.
Note:
In Assign methods, you must include a PARAMETERS or LPARAMETERS statement so that when you attempt to assign a value to a property at run time, Visual FoxPro can accept the value and pass it to the Assign method.

For more information, see DEFINE CLASS Command.

For example, the following code creates a class named MyClass with Access and Assign methods called MyProperty_ACCESS and MyProperty_ASSIGN for the custom property MyProperty. MyProperty_ACCESS responds to queries on the value of MyProperty, while MyProperty_ASSIGN responds to changes in the value of MyProperty.

Note:
The Assign method includes an LPARAMETERS statement so it can accept the value that is passed to it.

Copy Code
DEFINE CLASS MyClass AS Custom
   MyProperty = 100

   PROCEDURE MyProperty_ACCESS
      WAIT WINDOW 'This is the Access method';
         +  ' ' + PROGRAM( )
      RETURN THIS.MyProperty
   ENDPROC

   PROCEDURE MyProperty_ASSIGN
      LPARAMETERS tAssign
      WAIT WINDOW 'This is the Assign method';
          + ' ' + PROGRAM( )
   ENDPROC
ENDDEFINE

The following code example creates a Form class named frmMyForm with an Assign method called Left_ASSIGN for the form's native Left property. Left_ASSIGN performs simple validation on the property value and runs when an attempt is made to assign a value to the property. If you attempt to change the Left property to a negative value, the Assign method displays a message and leaves the value unchanged. If you attempt to change the Left property to a nonnegative value, the method sets the property to the specified value.

Note:
The Assign method includes an LPARAMETERS statement so it can accept the value that is passed to it.

Copy Code
DEFINE CLASS frmMyForm AS Form
   PROCEDURE Left_ASSIGN
      LPARAMETERS tAssign
      DO CASE
         CASE tAssign < 0 && Value passed is negative.
            WAIT WINDOW 'Value must be greater than 0'
         OTHERWISE  && Value passed is not negative.
            THIS.Left = tAssign
      ENDCASE
   ENDPROC
ENDDEFINE

Creating THIS_ACCESS Methods

You can create THIS_ACCESS methods from the Form Designer, Class Designer, or programmatically.

To create a THIS_ACCESS method

  1. On the Form menu in the Form Designer or on the Class Menu in the Class Designer, choose New Method.

  2. In the New Method dialog box, type THIS_ACCESS.

  3. Click Add.

    When created, the THIS_ACCESS method appears in the Properties window. To add code to the method, double-click the method in the Properties window.

To create THIS_ACCESS methods programmatically

  • Use the DEFINE CLASS command and include the THIS_ACCESS keyword.

For more information, see DEFINE CLASS Command.

The following code example creates a Form class named MyForm with a THIS_ACCESS method, which contains an LPARAMETER statement with an object member name and some code to execute. The first line of code creates a form named oTempForm using the CREATEOBJECT( ) function. The second line of code attempts to assign a value to the form's Caption property. This action executes the THIS_ACCESS method and passes the name of the Caption property to the method. The THIS_ACCESS method displays the name of the object member, or 'Caption' in this example, using the question mark (?) command, and then returns an object reference for the form.

The third line attempts to display the value of the form's Caption property using the ? command. This action executes THIS_ACCESS again, passes the name of the Caption property to the method, displays 'Caption', and returns an object reference for the form. The value of the Caption property, 'abc', is then finally displayed.

Copy Code
oTempForm = CREATEOBJECT('MyForm')
oTempForm.Caption = 'abc'
? oTempForm.Caption

DEFINE CLASS MyForm AS Form
   PROCEDURE THIS_ACCESS
      LPARAMETER cMemberName

      IF cMemberName = 'caption'
         ? cMemberName
      ENDIF
      RETURN THIS
   ENDPROC
ENDDEFINE

For more information, see DEFINE CLASS Command.

See Also

Other Resources

How to: Add Properties to Classes
Working with Classes in Visual FoxPro


How to: Add Methods to Classes

Visual FoxPro 9.0
How to: Add Methods to Classes
See Also

After you create a class, you can create and add custom methods to the class. When you add methods to classes, you are creating a procedure or function in the class definition. For more information about methods, see Classes in Visual FoxPro.

Note:
When you create custom methods for classes, the methods are scoped to the class, not to individual components in the class. If you create a method that has the same name as an event in the class definition, the code in the method executes when the event occurs.

You can add methods to classes using the Visual FoxPro IDE or programmatically. When you add a method, you can specify the level of visibility for the method. For more information about visibility levels for methods, see Protecting and Hiding Class Members.

To add a method to a class

  1. Open the class in the Class Designer.

    For more information about opening classes, see How to: Modify Classes.

    When the class opens in the Class Designer, the Class menu appears.

  2. On the Class menu, choose New Method.

  3. In the Name box of the New Method dialog box, type the name of the method.

  4. In the Visibility box, choose the visibility level for the method.

  5. To specify a description for the method when the method appears in the Properties window, include a description in the Description box.

  6. Click Add.

  7. Continue adding methods, or if you are finished, click Close.

After you add the method, it appears in the Properties window at the end of the properties list. For information about adding code to methods, see How to: Add Code to Methods and Events.

To add methods to classes programmatically

  • Use the DEFINE CLASS command and include the FUNCTION clause when you create a class.

For more information, see DEFINE CLASS Command.

See Also

Other Resources

How to: Add Properties to Classes
Working with Classes in Visual FoxPro


How to: Add Code to Methods and Events

Visual FoxPro 9.0
How to: Add Code to Methods and Events
See Also

You can add code for methods that you add to classes or class events using the Class Designer or programmatically.

To add code for a method or event

  1. Open the class in the Class Designer.

    For more information about opening classes, see How to: Modify Classes.

  2. On the Visual FoxPro toolbar, click Properties Window.

  3. In the properties list of the Properties window, double-click the method or event you want to add code for to open a code window.

    Note:
    Custom methods appear at the end of the properties list.

  4. In the code window, add code for the method or event.

  5. When you are finished adding code, close the code window.

For more information, see Properties Window and Code Window.

To add code to methods and events programmatically

  • Use the DEFINE CLASS command and include the FUNCTION or PROCEDURE clause.

For more information, see DEFINE CLASS Command.

See Also

Other Resources

Classes in Visual FoxPro
Understanding the Event Model
Working with Classes in Visual FoxPro


How to: Modify Class and Class Member Attributes

Visual FoxPro 9.0
How to: Modify Class and Class Member Attributes
See Also

After you create classes, you can add or edit their descriptions using the Class Designer or Class Browser. By using the Class Browser, you do not need to open each class. You can also modify attributes for custom properties and methods.

To modify a class description

  1. Open the class in the Class Designer.

    For more information about opening classes, see How to: Modify Classes.

    When the class opens in the Class Designer, the Class menu appears.

  2. On the Class menu, choose Class Info.

  3. In the Class Info dialog box, choose the Class tab.

  4. Make changes to the description in the Description box.

  5. When you are finished making changes, click OK.

To modify a class description without opening each class

  1. Open the class library in the Class Browser.

    For more information about opening class libraries, see How to: Open Class Libraries.

  2. In the class list of the Class Browser, select the class you want to change the description for.

  3. In bottom-left corner of the Class Browser, type the text for the class description.

If no member is selected in the member list of the Class Browser, the bottom-right corner of the Class Browser displays the class and timestamp information for the selected class.

Modifying Custom Property and Method Attributes

You can edit the attributes, such as the visibility level and description, for custom properties and methods using the Visual FoxPro IDE, the Project Manager when the class is part of a project, or in the Class Browser.

Caution:
Use caution when editing attributes, such as the visibility level, for custom properties and methods. Changes you make might affect code that references those properties and methods.

To modify attributes for a custom property or method

  1. Open the class in the Class Designer.

    For more information about opening classes, see How to: Modify Classes.

    When the class opens in the Class Designer, the Class menu appears.

  2. On the Class menu, choose Edit Property/Method.

  3. When you are finished making changes, click Apply.

You can also right-click the property or method in the properties list of the Properties window and choose Edit Property/Method.

To modify attributes for a custom property and method without opening each class

  1. Open the class library in the Class Browser.

    For more information about opening class libraries,, see How to: Open Class Libraries.

  2. In the member list of the Class Browser, select a method or property.

  3. In the bottom-right corner of the Class Browser, type the text for the property or method description.
Note:
For member properties and methods, the bottom-right corner displays a description you can edit. However, for object members and instances of classes, the bottom-right corner displays read-only information for the class and base class of the object member, including the visibility level, member names, and property values.

See Also

Other Resources

How to: Add Code to Methods and Events
Working with Classes


How to: Remove Properties and Methods from Classes

Visual FoxPro 9.0
How to: Remove Properties and Methods from Classes
See Also

You can remove custom properties and methods from classes.

Caution:
Use caution when removing properties and methods from classes. Changes you make affect code that references those properties and methods.

To remove a custom property or method

  1. Open the class in the Class Designer.

    For more information about opening classes, see How to: Modify Classes.

    When the class opens in the Class Designer, the Class menu appears.

  2. On the Class menu, choose Edit Property/Method.

  3. In the Property/Method Information list, select the property or method you want to remove, and click Remove.

See Also

Other Resources

Classes in Visual FoxPro
Working with Classes in Visual FoxPro


How to: Specify Design-Time Appearance for Classes

Visual FoxPro 9.0
How to: Specify Design-Time Appearance for Classes
See Also

In Visual FoxPro, objects and controls created from visual classes display a visual element at design time and run time. However, objects and controls based on non-visual classes, such as the Custom class and Timer control, display a visual element at design time but not at run time.

At design time, Visual FoxPro displays objects created from non-visual classes with a default graphic. However, you can change the default graphic so that you can distinguish one non-visual class from another at design time. However, objects created from non-visual classes do not display these graphics at run time.

You can also specify toolbar and container icons that appear for classes in the Visual FoxPro IDE. You can specify icons that appear in the Forms Control toolbar and Toolbox after you add classes to them. You can also specify container icons that appear in the Project Manager and Class Browser.

To specify a visual element for a non-visual class

  1. Open the class in the Class Designer.

    For more information about opening classes, see How to: Modify Classes.

  2. On the Visual FoxPro toolbar, click Properties Window.

  3. In the Properties window, specify an image file, such as a bitmap (.bmp) file, for the Picture property.

  4. Save the class.

You can specify a toolbar icon for a class. After you add the class to the Form Controls toolbar or the Toolbox, the icon for the class appears on the toolbar or in the Toolbox.

To specify a toolbar icon for a class

  1. Open the class in the Class Designer.

    For more information about opening classes, see How to: Modify Classes.

    When the class opens in the Class Designer, the Class menu appears.

  2. On the Class menu, choose Class Info.

  3. In the Toolbar icon box in the Class Info dialog box, type the name and path of the icon (.ico) or bitmap (.bmp) file.

    -OR-

    Click the ellipsis (...) button to browse for an .ico or .bmp file.

  4. Click OK and save the class.
Note:
The bitmap (.bmp file) for a toolbar icon is 15 by 16 pixels. If the picture is larger or smaller, it is sized to 15 by 16 pixels and might not look the way you want it to.

You can specify a container icon for a class. The icon for the class appears in containers such as the Project Manager and Class Browser. In the Class Browser, the icon for the class appears next to the class in the class list and next to the type box when the class is selected. By default, the container icon and toolbar icon for the class are the same as those for the parent class.

To specify a container icon for a class

  1. Open the class in the Class Designer.

    For more information about opening classes, see How to: Modify Classes.

    When the class opens in the Class Designer, the Class menu appears.

  2. On the Class menu, choose Class Info.

  3. In the Container icon box of the Class Info dialog box, type the name and path of the icon (.ico) or bitmap (.bmp) file.

    -OR-

    Click the ellipsis (...) button to browse for an .ico or .bmp file.

  4. Click OK and save the class.

You can also specify the container icon in the Class Browser by right-clicking the class in the class list, choosing Container icon, selecting an .ico or .bmp file, and clicking OK.

Tip:
If you click Cancel instead of OK, Visual FoxPro displays a message prompting whether you want to reset the icon to the default, which is the icon Visual FoxPro uses for its base classes. If you want the icon to match its base class, choose Yes.

The new icon replaces the previous icon in the class list. The icon that appears next to the class list refreshes when you select the class in the class list.

Note:
If the previous icon for the container and toolbar are the same, then the new icon replaces both the container and toolbar icon. Otherwise, if the previous toolbar icon differed from the container icon, only the container icon changes.

See Also

Other Resources

Classes in Visual FoxPro
How to: Create Classes and Subclasses
Working with Classes in Visual FoxPro


How to: Add Classes to Visual FoxPro Tools

Visual FoxPro 9.0
How to: Add Classes to Visual FoxPro Tools
See Also

Typically, you can add objects to forms by dragging classes from the Toolbox or adding them from the Form Controls toolbar. However, Visual FoxPro does not add custom classes to the Toolbox or the Form Controls toolbar automatically.

To add a class to the Toolbox

  1. On the Tools menu, choose Toolbox.

  2. Right-click the Toolbox and choose Add Class Library.

  3. In the Category box in the Add Class Library dialog box, type or choose the category you want to add the class to.

  4. In the Class Library box, type the name of the class library.

    -OR-

    Click the ellipsis (...) button to select a class library.

Visual FoxPro adds the class to the end of category you chose in the Toolbox.

For more information, see Toolbox and How to: Customize the Toolbox.

To add a class to the Form Controls toolbar

  1. Open a form.

  2. On the View menu, choose Form Controls Toolbar.

  3. On the Form Controls toolbar, click View Classes, and then choose Add.

  4. In the Open dialog box, select a class library, and then click Open.

    The class appears on the Form Controls toolbar.

When you add class libraries to the Form Controls toolbar, they appear registered in the Controls tab of the Options dialog box. If you want the class to appear in the Forms Control toolbar in future sessions of Visual FoxPro, click Set As Default in the Controls tab of the Options dialog box.

Tip:
You can register the class library so that when you choose View Classes on the Form Controls toolbar, the class library appears in the list of class libraries you can choose.

To register a class library

  1. On the Tools menu, choose Options.

  2. In the Options dialog box, choose the Controls tab.

  3. On the Controls tab, choose Visual class libraries, and then click Add.

  4. In the Open dialog box, select a class library, and then click Open.

  5. To make the class library available on the Form Controls toolbar for future sessions of Visual FoxPro, click Set As Default.

  6. Click OK.

See Also

Other Resources

Working with Classes in Visual FoxPro


Access and Assign Methods

Visual FoxPro 9.0
Access and Assign Methods
See Also

Visual FoxPro supports Access and Assign methods, which are user-defined procedures or functions that have the same name as a class property and have the suffix _ACCESS or _ASSIGN appended to the procedure or function name. You can use Access and Assign methods to execute code when querying the value of a property or attempting to change the property's value. Visual FoxPro executes Access and Assign methods only when querying or changing property values at run time, not design time. You can create Access and Assign methods separately and independently of each other.

Access and Assign methods provide the following benefits:

  • You can create a public interface for a class or object that separates the interface from the implementation.

  • You can easily implement property validation.

  • You can easily protect properties in subclassed ActiveX controls.

Visual FoxPro executes code in an Access method when querying the value of a property, typically by using the property in an object reference, storing the property value to a variable, or displaying the property value with the question mark (?) command.

Visual FoxPro executes code in an Assign method when you attempt to change the property value, typically by using the STORE command or = operator to assign a new value to the property.

Note:
You can create Access and Assign methods for most native Visual FoxPro properties. You can create Assign methods for properties that are read-only; however, the method never executes. Visual FoxPro does not support the Assign method for the Value property for controls nor does it support Access and Assign methods for native properties, events, or methods of ActiveX controls. However, Visual FoxPro supports Access and Assign methods for properties, events, and methods of the Visual FoxPro OLE Container in which an ActiveX control is contained.

Note:
Access and Assign methods for member arrays do not fire when accessing the array using a native array function such as ASCAN().

Note:
The Assign method will fire for certain native properties when their value is queried and not changed. These include dimensional properties such as Top, Left, Height, Width as well as a few others like Visible. This is due to how Visual FoxPro handles these properties internally.

Visual FoxPro treats Access and Assign methods as Protected at run time, so they cannot be accessed outside of the class definition. However, when you are in the Class Designer, Visual FoxPro treats these Access and Assign methods in a special way. When you drop an object onto a container, such as a command button onto a form, Visual FoxPro usually marks Protected methods of such objects as read-only and not modifiable in the designer. However, you can edit Access and Assign methods of such objects in the Class Designer.

THIS_ACCESS Methods

You can create THIS_ACCESS methods to execute code when changing the value for an object member or querying the object member. The THIS_ACCESS method must always return an object reference; otherwise, Visual FoxPro generates an error. Typically, the method returns the object reference, THIS. The THIS_ACCESS method must also include a parameter to accept the name of the object member that is changed or queried.

Note:
THIS_ACCESS is not intended as a global replacement for Access and Assign methods. It only provides information about the object member that is accessed or queried. Unlike an Access or Assign method, THIS_ACCESS does not provide control over values returned to specific object members.

See Also

Other Resources

How to: Create Access and Assign Methods
Working with Classes in Visual FoxPro


Protecting and Hiding Class Members

Visual FoxPro 9.0
Protecting and Hiding Class Members
See Also

When you create and add properties and methods to a class in the Class Designer, you can specify one of the following levels of visibility for the property or method: Public, Protected, or Hidden. When you create a class using the DEFINE CLASS command, you can designate properties and methods as Hidden or Protected using the PROTECTED and HIDDEN keywords.

By default, properties and methods in a class definition are Public, which means code in other classes or procedures can set those properties or call those methods. However, certain classes might need to restrict users from changing its properties or calling its methods from outside the class. You can designate the properties and methods that you add to a class as Protected, which restricts access to members of the class and subclasses. You can also designate properties and methods as Hidden, which restricts access to only members of the class.

For example, suppose you create a class that stores employee information, and you do not want permit users to change the hire date for the employee. You can designate the hire date as Protected, and instead, provide a method that returns the hire date so that users can view the hire date if they need to. The following code example creates the Employee class using the DEFINE CLASS command and designates the HireDate property as Protected using the PROTECTED keyword and contains the method GetHireDate that returns the hire date:

Copy Code
DEFINE CLASS Employee AS CUSTOM
   PROTECTED HireDate
   First_Name = ""
   Last_Name = ""
   Address = ""
   HireDate = { - - }

   PROCEDURE GetHireDate
      RETURN This.HireDate
   ENDPROC
ENDDEFINE

For more information, see DEFINE CLASS Command.

The Visual FoxPro sample, Display a Stop Watch Sample, also illustrates the use of protected properties and methods in a class.

See Also

Other Resources

Classes in Visual FoxPro
How to: Add Properties to Classes
How to: Add Methods to Classes
Working with Classes in Visual FoxPro


Overriding Default Property Settings

Visual FoxPro 9.0
Overriding Default Property Settings
See Also

For a user-defined class, you can change the default values for properties that are not marked as Protected when you add objects based on that class to a form. This action overrides the default values of those properties as defined by the class. If you later change the default values for properties in the class, for example, using the Class Designer, the values of those properties for the object on the form are not affected.

However, if you do not change the default property value when you add the object to the form and you change the default property value in the class, the property value of the object changes to match the new default value.

For example, suppose you add a command button based on a user-defined class to a form and changes the BackColor property from white to red. If you change the default value of the BackColor property in the user-defined class to green, the back color of the command button on the form remains red. However, if you do not change the back color of the command button and you change the default value color of the BackColor property in the class to green, the back color of the command button on the form inherits the change and is set to green.

See Also

Other Resources

Overriding and Calling Parent Class Code
Working with Classes in Visual FoxPro


Overriding and Calling Parent Class Code

Visual FoxPro 9.0
Overriding and Calling Parent Class Code
See Also

When you create a class, the class inherits all the properties, methods, and events of the parent class automatically. For example, if code exists for an event in the parent class, that code executes when the event occurs for an object based on a subclass created from the parent class.

The following sections describe how you can override or execute method or event code from the parent class:

  • Overriding Parent Class Code

  • Calling Parent Class Code

Overriding Parent Class Code

Usually, you want to add functionality to a new class or the object created from that class in addition to the original functionality. However, you can override the method or event code inherited from the parent. For example, suppose you create a subclass or add an object based on the subclass to a container, such as a form. You can write new code for the Click event of the class to override the event code in the parent class. In both cases, the new code, not the original code, is executed at run time.

You can also prevent the default behavior of the base class from occurring in a subclass's method or event. To prevent base class behavior, include the NODEFAULT keyword in the method or event code that you add.

For example, the following program uses the NODEFAULT keyword in a text box's KeyPress event to prevent the typed characters from displaying in the text box:

Copy Code
frmKeyExample = CREATEOBJECT("test")
frmKeyExample.Show
READ EVENTS
DEFINE CLASS myForm AS FORM
   ADD OBJECT text1 AS TEXTBOX
   PROCEDURE text1.KeyPress
      PARAMETERS nKeyCode, nShiftAltCtrl
      NODEFAULT
      IF BETWEEN(nKeyCode, 65, 122) && Between 'A' and 'z'
         This.Value = ALLTRIM(This.Value) + "*"
         ACTIVATE SCREEN      && Send output to main Visual FoxPro window.
         ?? CHR(nKeyCode)
      ENDIF
   ENDPROC
   PROCEDURE Destroy
      CLEAR EVENTS
   ENDPROC
ENDDEFINE

Calling Parent Class Code

You can optimize class design by adding and executing code at different levels in the class or container hierarchy.

To execute method or event code in the parent class in addition to code for the same method or event in the subclass, precede the subclass's method or event code with the DODEFAULT( ) function or the scope resolution operator (::).

Tip:
When you use the DODEFAULT( ) function, you do not need to know the name of the parent class. However, to determine all the classes in an object's class hierarchy, use the ACLASS( ) function. For more information, see ACLASS( ) Function.

For example, suppose you have a class named cmdGoBottom based on the CommandButton class that has the following code in its Click event:

Copy Code
GO BOTTOM
THISFORM.Refresh

This code moves the table record pointer to the bottom of the table. When you create a command button, for example, cmdGoBottom1, based on the cmdGoBottom class and add it to a form, you might decide to execute the code in parent class's Click event and display a message indicating that the table record pointer is positioned at the bottom of the table. Suppose you add only the following line of code to cmdGoBottom1's Click event to display the message, "At the Bottom of the Table":

Copy Code
WAIT WINDOW "At the Bottom of the Table" TIMEOUT 1

When you run the form, the message displays; however, the record pointer does not move because the code in cmdGoBottom1's Click event overrides that of the parent class. To make sure that the code in the parent class's Click event also executes, include the following lines of code instead in cmdGoBottom1's Click event:

Copy Code
DODEFAULT( )
WAIT WINDOW "At the Bottom of the Table" TIMEOUT 1

The following lines of code in the cmdGoBottom1's Click event show how to accomplish the same task using the scope resolution operator (::) and the name of the parent class:

Copy Code
cmdGoBottom::Click()
WAIT WINDOW "At the Bottom of the Table" TIMEOUT 1

As another example, the Buttons.vcx visual class library in the Visual FoxPro ...\Samples\Classes directory contains two command button classes: cmdOK and cmdCancel. Suppose a command button created from the cmdOK class exists on a form. The code in the Click event of the command button releases the form when you click the button. However, the cmdCancel command button class is a subclass of the cmdOK class. Suppose you wanted to discard changes made to a table when you click a command button created from the cmdCancel class. You can add functionality to the Click event of the cmdCancel class that calls the method code in the cmdOK class by using the following sample code:

Copy Code
IF USED( ) AND CURSORGETPROP("Buffering") != 1
   TABLEREVERT(.T.)
ENDIF
DODEFAULT( )

The code added to the cmdCancel class reverts changes to the table using the TABLEREVERT( ) function before it uses the DODEFAULT( ) function to call the code in cmdOK class to release the form.

Note:
You do not need to add the TABLEUPDATE( ) function to the cmdOK class because changes are written to a buffered table by default when the table closes.

For more information, see DODEFAULT( ) Function and :: Scope Resolution Operator.

See Also

Other Resources

Overriding Default Property Settings
Working with Classes in Visual FoxPro


Managing Classes and Class Libraries

Visual FoxPro 9.0
Managing Classes and Class Libraries

Visual FoxPro uses stored definitions of classes in class library files. You can perform tasks such as create class libraries, add classes and subclasses, copy and rename classes, redefine parent class relationships, and remove classes from class libraries.

Visual FoxPro provides several means for managing classes and class libraries. However, using the Class Browser to manage classes updates projects and forms as well as class libraries. Changes that you make in the Class Browser propagate through every class library (.vcx) and form (.scx) file that is open in the Class Browser.

In This Section

Operating the Class Browser

Describes working with the Class Browser.
How to: Create Class Libraries

Describes the methods for creating class libraries.
How to: Open Class Libraries

Describes how to open class libraries.
How to: Add Classes and Subclasses to Class Libraries

Describes how to add new classes and subclasses to existing class libraries.
How to: Rename Classes in Class Libraries

Describes the methods to rename a class within a class library.
How to: Copy Classes Between Class Libraries

Describes the process to copy a class from one class library to another class library.
How to: Redefine Parent Class Relationships

Describes the method to change the parent class of a class.
How to: Remove Classes from Class Libraries

Describes how to remove a class from a class library.
How to: View Type Library Information

Describes how to view type library information.

Related Sections

Object-Oriented Programming

Discusses how you can create self-contained application components that respond to user actions and to the system and which can be easily maintains and reused.


Operating the Class Browser

Visual FoxPro 9.0
Operating the Class Browser

The Class Browser makes it possible for you to manage classes and class libraries.

In This Section

How to: Run the Class Browser

Explains how to open and run the Class Browser.
How to: Customize the Class Browser

Explains how to customize the Class Browser.
How to: View Class Hierarchies

Explains how to view class hierarchies.
How to: Filter the Class Browser Class List

Explains how to filter the classes displayed in the Class Browser.
How to: View Class Definition Code

Explains how to view class definition code.

Related Sections

Managing Classes and Class Libraries

Describes how to manage the classes that you create.
Working with Classes in Visual FoxPro

Introduces classes in Visual FoxPro and how to use them to create objects.


How to: Run the Class Browser

Visual FoxPro 9.0
How to: Run the Class Browser
See Also

You can run multiple instances of the Class Browser at the same time.

To run the Class Browser

  • On the Tools menu, choose Class Browser.

For more information, see Class Browser Window and Class Browser Buttons.

To run the Class Browser programmatically

  • In the Command window, use the DO command with the _BROWSER system variable, which specifies the name of the class browser application as shown in the following line of code:

    Copy Code
    DO (_BROWSER)

For more information, see _BROWSER System Variable.

When running the Class Browser using the DO command, you can use the following additional parameters and syntax:

Copy Code
DO (_BROWSER) [WITH [tcFileName][, tcDefaultClass[.member]][, tlListBox][, tcClassType][, tnWindowState]]

The following table describes the optional parameters you can use when running the Class Browser using the DO command.

Parameter | Description
tcFileName | The name of the .vcx, .scx, .olb, .tlb, .pjx, or .exe file to open in the Class Browser. For more information, see File Extensions and File Types.
tcDefaultClass[.member] | Specifies the class to select by default in the .vcx file. If no default class is specified, the class library is selected. If a class member is specified, the class member appears selected in the member list of the Class Browser.
tlListBox | Specifies whether to display the classes and members in list boxes rather than using tree-view controls. To display list boxes, specify True (.T.). Default: False (.F.)
tcClassType | Specifies the initial type filter for the classes displayed in the Class Browser. To change the filter in the Class Browser, choose another value in the type list of the Class Browser. Default: No filter.
tnWindowState | Specifies the state of the Class Browser window when opened. 0 - Normal (Default) 1 - Minimized 2 – Maximized
tlGallery | Specifies whether to open the Component Gallery instead of the Class Browser. To open the Component Gallery, specify True (.T.). Default: False (.F.)

For example, you can run the Class Browser with a specific visual class library (.vcx) file or an object reference. You can also include the class name to be initially selected. The following line of code opens the Class Browser, the Buttons.vcx class library, and selects the VCR class:

Copy Code
DO (_BROWSER) WITH HOME(2) + 'Classes\Buttons.vcx', 'VCR'

As another example, you can run the Class Browser and specify to select the cmdOK object from the Print_Report class in the Samples.vcx class library, display the forms and members in Samples.vcx in list boxes, filter the classes displayed using the Form class, and open the Class Browser window as maximized:

Copy Code
DO (_BROWSER) WITH "Samples.vcx", "Print_Report.cmdOK", .T., "form", 2

See Also

Other Resources

How to: Customize the Class Browser
How to: View Class Hierarchies
How to: Filter the Class Browser Class List
How to: View Class Definition Code
Operating the Class Browser
Managing Classes and Class Libraries


How to: Customize the Class Browser

Visual FoxPro 9.0
How to: Customize the Class Browser
See Also

You can customize the Class Browser by changing the values for its properties and using its methods and events. You can perform additional operations, such as specifying default class libraries to open in the Class Browser, using Class Browser methods. For more information, see Class Browser Properties, Class Browser Methods, and Class Browser Object Members

When you open the Class Browser, the public variable, _oBrowser, is automatically created. You can use this variable to reference or manipulate the Class Browser as you can any form object.

To set properties for the Class Browser

  • In the Command window, use the following syntax to set Class Browser properties that you want to change:

    Copy Code
    _oBrowser.Property = newValue

For example, after opening the Class Browser, you can use the following lines of code to set the Caption property of the Class Browser to "My Class Browser" and the Left property to 10:

Copy Code
_OBROWSER.Caption = "My Class Browser"
_OBROWSER.Left = 10

To specify the default class library to open in the Class Browser

  1. Open the class library in the Class Browser.

  2. In the class list of the Class Browser, select the class library.

  3. In the Command window, type the following code:

    Copy Code
    _oBrowser.SetDefaultFile

This resets any previously specified default libraries.

You can specify class libraries to open by default in addition to the default library.

To specify additional libraries to open with the Class Browser

  1. In the Class Browser, click the View Additional File button.

  2. In the class list of the Class Browser, select the class library.

  3. In the Command window, type the following code:

    Copy Code
    _oBrowser.SetDefaultFile(.T.)

To remove class libraries from the Class Browser list

  1. In the class list of the Class Browser, select the class library.

  2. In the Command window, type the following code:

    Copy Code
    _oBrowser.ResetDefaultFile

To remove all libraries from the Class Browser list

  • In the Command window, type the following code:

    Copy Code
    _oBrowser.ResetDefaultFile(.T.)

See Also

Other Resources

Class Browser Window
How to: View Class Hierarchies
How to: Filter the Class Browser Class List
How to: View Class Definition Code
Operating the Class Browser
Managing Classes and Class Libraries


How to: View Class Hierarchies

Visual FoxPro 9.0
How to: View Class Hierarchies
See Also

You can view the hierarchy in a class library, user-defined members in a class, and inheritance of members between related classes using the Class Browser.

To view class members and hierarchies

  1. In the Class Browser, open the class library you want to view.

    For information about opening the Class Browser, see How to: Run the Class Browser.

  2. In the class list of the Class Browser, select the class you want.

When a class is selected, an icon for the class appears next to the type list, which appears above the class list. Any user-defined class members that exist appear in the member list. Subclasses appear indented beneath parent classes when Hierarchical mode is selected on the Class Browser shortcut menu.

When a class is selected, you can view its parent class if available.

To view the parent class

  • Right-click the class, and on the shortcut menu, choose Select ParentClass.

    The parent class appears selected.

If a chevron (<<) appears next to a class, its parent class is located in a class library (.vcx) that is not displayed in the class list. If you choose Select ParentClass on the class shortcut menu, the class library containing the parent class is added to the class list, and the parent class is selected.

You can view multiple class libraries or form files by opening another file in the current Class Browser window or by opening another Class Browser window. You can also open the same file in several Class Browser windows.

See Also

Other Resources

Class Browser Window
How to: Filter the Class Browser Class List
How to: View Class Definition Code
Operating the Class Browser
Managing Classes and Class Libraries


How to: Filter the Class Browser Class List

Visual FoxPro 9.0
How to: Filter the Class Browser Class List
See Also

You can display a specific set of classes by specifying a class type, class name, or a filter in the Class Browser.

To filter the class list

  1. In the Class Browser, open the class library you want.

    For information about opening the Class Browser, see How to: Run the Class Browser.

  2. In the type box, select a class from the list, type the name of a class, or type a single filter or filters separated by commas, which act as logical OR operators.

    Note:
    A class needs to match only one filter for inclusion in the class list.

    The classes that match the class, type, or filter you specified appear in the class list. The filters you specify are added to the type list.

The type list keeps a history of the types and filters you selected only for the current instance of the Class Browser. The list is not saved after you close the Class Browser.

Note:
Hierarchical mode is selected by default on the Class Browser shortcut menu. When Hierarchical mode is selected, Visual FoxPro evaluates parent classes. If a parent class matches the filter, its child classes are evaluated. If the parent class does not match the filter, its child classes are not evaluated and do not appear in the list, even if the child matches the filter.

You can expand your search for classes to include a specific character string in the name or description.

To search by class name and description text

  1. In the Class Browser, open the class library you want.

  2. In the Class Browser, click the Find button.

  3. In the Look for box of the Find Class dialog box, type a string of text that you want to search for.

  4. Click Find.

Classes that contain the string in its name or description appear in the class list.

Note:
When Hierarchical mode is selected, only the matching parent classes and their associated matching subclasses appear in the list.

The following table of filter operators and expressions describes wildcard characters you can combine with the characters in a class name to create a filter in the Class Browser.

Filter contains | Description
+ cTargetName | Name must start with cTargetName.
% cTargetName % | Name contains cTargetName. For example, to view all classes containing the string "mover," type %MOVER%.
- cTarget | Name does NOT contain cTarget. Takes precedence over other search filters.
~ cTarget | Name contains something similar to cTarget.
cTarget * An asterisk (*) replaces an unlimited number of characters. | Name contains anything following cTarget. For example, to view all classes beginning with "VCR," type VCR*.
" cTarget " | Name is cTarget. If cTarget is not a base class, report results of class name search.
cTarget | If cTarget is a base class, report all members of the base class regardless of the name.
[?...]cTarget[?...] | Name contains cTarget plus the specified unknown characters in the specified relative positions. The question mark (?) replaces a single character. You can use question marks in any position and in any quantity. For example, to view all classes starting with MsgBox and some number, such as MsgBox1, type MsgBox?.

The following table describes examples that illustrate combinations of filter expressions separated by spaces, which represent the OR operator.

If you want this | Use an expression like this
The target is a string that must start with "test" but is NOT a "form" class. | -%form% +test*
The target is any string that does NOT contain "debug" and starts with "c" OR contains "test". | c* %test% -%debug%
The target is any string that does NOT start with "debug" and is similar to "test" OR is the string "myform" | ~test -debug* "myForm"

See Also

Other Resources

Class Browser Window
How to: View Class Hierarchies
How to: View Class Definition Code
Operating the Class Browser
Managing Classes and Class Libraries


How to: View Class Definition Code

Visual FoxPro 9.0
How to: View Class Definition Code
See Also

You can view the code for class definitions, specific parameters, or parent class code for user-defined methods using the Class Browser. You can also save class definition code to another class library.

To view class definition code

  1. In the Class Browser, open the class library you want.

    For information about opening the Class Browser, see How to: Run the Class Browser.

  2. In the class list, select the class you want.

  3. In the Class Browser, click the View Class Code button.

Visual FoxPro displays definition code for the class in a read-only program (.prg) file. The class definition displayed includes all property settings and method and event code.

Note:
The code is displayed for viewing purposes only. In many cases, you can save it to a program and run it directly; however, code with nested containers generate errors. To view type library information, use the Object Browser.

You can use a limited selection of editing commands, such as Find, Copy, and Select All, on the Edit menu.

If parent class code is available for a user-defined method, you can view the parent class code.

To view parent class code for a user-defined method

  1. In the Class Browser, double-click a class or class member.

    The class or class member opens in the Class Designer or Form Designer. If no code window is open, on the View menu, choose Code.

  2. On the Visual FoxPro toolbar, click the Edit ParentClass Method button.

See Also

Other Resources

Class Browser Window
How to: View Class Hierarchies
How to: Filter the Class Browser Class List
Operating the Class Browser
Managing Classes and Class Libraries


How to: Create Class Libraries (Visual FoxPro)

Visual FoxPro 9.0
How to: Create Class Libraries (Visual FoxPro)
See Also

You can create class libraries when you create classes using the Visual FoxPro IDE or empty class libraries programmatically.

Visual FoxPro stores classes you create using the Class Designer in visual class library (.vcx) files. These classes include visual and non-visual classes. You can also choose to store class definitions in program (.prg) files when using the DEFINE CLASS command to create classes.

To create a class library when creating a class

  1. Create a class using the Visual FoxPro IDE.

  2. In the Store In box of the New Class dialog box, type the name of the class library.

For more information about creating classes, see How to: Create Classes and Subclasses.

To create class libraries programmatically

  • Use the CREATE CLASSLIB command to create an empty class library.

    -OR-

  • Include the OF clause in the CREATE CLASS command when you create a class.

For example, the following line of code uses the CREATE CLASSLIB command to create an empty class library named MyClassLibrary:

Copy Code
CREATE CLASSLIB MyClassLibrary

The following line of code includes the OF clause in the CREATE CLASS command to specify the name of the class library that will store the class MyClass, which is based on the Form class.

Copy Code
CREATE CLASS MyClass OF MyClassLibrary AS Form

For more information, see CREATE CLASSLIB Command.

See Also

Other Resources

How to: Add Classes and Subclasses to Class Libraries
Managing Classes and Class Libraries


How to: Open Class Libraries

Visual FoxPro 9.0
How to: Open Class Libraries
See Also

You can open class libraries to view or add classes.

You can open classes using the Class Browser, the Project Manager when the class library is part of a project, or programmatically.

To open a class library

  1. On the Tools menu, choose Class Browser.

  2. In the Class Browser, click Open.

  3. In the Open dialog box, select the class library you want, and click OK.

    The class library you selected appears in the class list in the Class Browser along with any classes it contains.

To open a class library in a project

  1. Open the project containing the class library.

  2. In the Project Manager, select the Classes tab.

  3. Select the class library you want to open and click Modify.

    The class library you selected opens in the Class Browser.

To open and close class libraries programmatically

  1. To open class libraries programmatically, use the SET CLASSLIB command.

    -OR-

  2. To close class libraries programmatically, use the RELEASE CLASSLIB command.

For more information, see SET CLASSLIB Command and RELEASE CLASSLIB Command.

See Also

Other Resources

How to: Modify Classes
How to: Add Classes and Subclasses to Class Libraries
Managing Classes and Class Libraries


How to: Add Classes and Subclasses to Class Libraries

Visual FoxPro 9.0
How to: Add Classes and Subclasses to Class Libraries
See Also

When you create a class or subclass interactively or programmatically, the class is stored in the class library that you specify. If the class library exists, the class is added to the class library.

To add a class to a class library

  1. Open the class library in the Class Browser.

    For more information about opening class libraries, see How to: Open Class Libraries.

  2. In the class list of the Class Browser, select the class library you want to add a class for.

  3. In the Class Browser, click the New Class button.

    The New Class dialog box opens so you can specify information for the new class.

  4. Follow the steps for creating a class or subclass. For more information, see How to: Create Classes and Subclasses.

When you finish creating and saving the class, the class appears in the class library displayed in the Class Browser.

To add a subclass to a class library

  1. Open the class library in the Class Browser.

    For more information about opening class libraries, see How to: Open Class Libraries.

  2. In the class list of the Class Browser, select the class you want to create a subclass from.

  3. In the Class Browser, click the New Class button.

    The New Class dialog box opens so you can specify information for the new class. The class you selected appears by default in the Based On box.

  4. Follow the steps for creating a class or subclass. For more information, see How to: Create Classes and Subclasses.

When you finish creating and saving the subclass, the subclass appears in the class library displayed in the Class Browser.

To add classes to class libraries programmatically

  • Use the ADD CLASS command.

For example, the following line of code adds the class MyClass to MyClassLibrary:

Copy Code
ADD CLASS MyClass TO MyClassLibrary2

For more information, see ADD CLASS Command.

See Also

Other Resources

How to: Add Properties to Classes
How to: Add Methods to Classes
Managing Classes and Class Libraries


How to: Rename Classes in Class Libraries

Visual FoxPro 9.0
How to: Rename Classes in Class Libraries
See Also

You can rename classes in class libraries. You can rename classes in class libraries using the Class Browser, the Project Manager when the class library is part of a project, or programmatically.

Caution:
When you rename a class, forms that contain that class and subclasses in other class libraries continue to refer to the original name and will no longer function correctly.

Tip:
If you rename a class using the Class Browser when all associated subclasses and forms are open in the Class Browser, the new name is automatically referenced in all affected subclasses and forms.

To rename a class in a class library

  1. Open the class library in the Class Browser.

    For more information about opening class libraries, see How to: Open Class Libraries.

  2. In the class list of the Class Browser, select the class you want rename, and click the Rename button.

  3. In the Rename dialog box, type the new name, and click Rename.

    The class list in the Class Browser displays the renamed class.

For more information, see Class Browser.

To rename a class in a project

  1. Open the project containing the class library with the class you want to rename.

  2. In the Project Manager, select the Classes tab.

  3. Expand the class library containing the class you want to rename.

  4. Right-click the class library and choose Rename.

  5. In the To: box of the Rename File dialog box, type a new name for the class.

  6. Click OK.

To rename classes programmatically

  • Use the RENAME CLASS command.

For example, the following line of code changes the name of the class MyClass in the class library MyClassLibrary to YourClass:

Copy Code
RENAME CLASS MyClass OF MyClassLibrary TO YourClass

For more information, see RENAME CLASS Command.

See Also

Other Resources

Managing Classes and Class Libraries


How to: Copy Classes Between Class Libraries

Visual FoxPro 9.0
How to: Copy Classes Between Class Libraries
See Also

You can copy classes between class libraries. You can copy classes using Class Browser, the Project Manager when the class libraries are parts of projects though not necessarily the same project, or programmatically.

To copy a class between class libraries

  1. Open the class library containing the class you want to copy in the Class Browser.

    For more information about opening class libraries, see How to: Open Class Libraries.

  2. Open the destination class library in another instance of the Class Browser.

  3. In the Class Browser containing the source class library, select the class you want to copy.

  4. Press and hold the CTRL key while you drag the class icon above the class list to the destination class library.

    A plus (+) sign appears above the cursor when you drag the class icon into the destination class library.

Tip:
To move a class from one class library to another, do not press and hold the CTRL key while dragging the class icon.

To copy a class between class libraries in projects

  1. Open the project or projects containing the class libraries.

  2. In the Project Manager, select the Classes tab.

  3. Expand the class library containing the class you want to copy and the destination class library.

  4. Drag the class to the destination library.

    The mouse pointer changes into a class library icon when you move it over a valid destination library.

To copy classes between class libraries programmatically

  • Use the ADD CLASS command with the OF clause.

For example, the following line of code copies the class MyClass from MyClassLibrary1 to MyClassLibrary2.

Copy Code
ADD CLASS MyClass OF MyClassLibrary1 TO MyClassLibrary2

For more information, see ADD CLASS Command.

See Also

Other Resources

Managing Classes and Class Libraries


How to: Redefine Parent Class Relationships

Visual FoxPro 9.0
How to: Redefine Parent Class Relationships
See Also

You can redefine the relationship between a class and its parent class.

Caution:
When you redefine a class, forms that contain that class and subclasses in other class libraries that do not currently appear in the Class Browser might not function correctly.

To change the parent class of a class

  1. Open the class library in the Class Browser.

    For more information about opening class libraries, see How to: Open Class Libraries.

  2. In the class list of the Class Browser, select the class you want to redefine.

  3. In the Class Browser, click the Redefine button.

  4. In the As list of the Redefine dialog box, select the name of the new parent class.

    -OR-

    Click the ellipsis (...) button to select a class.

  5. Click Redefine.

See Also

Other Resources

Managing Classes and Class Libraries


How to: Remove Classes from Class Libraries

Visual FoxPro 9.0
How to: Remove Classes from Class Libraries
See Also

You can remove classes from class libraries.

Caution:
When you remove a class from a class library, you delete the class.

You can remove classes from class libraries using the Class Browser, the Project Manager when the class library is part of a project, or programmatically.

To remove a class from a class library

  1. Open the class library in the Class Browser.

    For more information about opening class libraries, see How to: Open Class Libraries.

  2. In the class list of the Class Browser, right-click the class you want to remove, and choose Remove.

To remove a class from a project

  1. Open the project containing the class library.

  2. In the Project Manager, choose the Classes tab.

  3. Expand the class library containing the class you want to remove.

  4. Select the class you want to remove and choose Remove.

To remove classes from class libraries programmatically

  • Use the REMOVE CLASS command.

For example, the following line of code removes a class named MyClass from the class library named MyClassLibrary:

Copy Code
REMOVE CLASS MyClass OF MyClassLibrary.vcx

For more information, see REMOVE CLASS Command.

See Also

Other Resources

Managing Classes and Class Libraries


How to: View Type Library Information

Visual FoxPro 9.0
How to: View Type Library Information
See Also

Type libraries are COM Component definition files that include information about types and objects exposed by an OLE application. A type library can be a standalone binary (.tlb) file, compiled in an application (.exe) file, embedded in an ActiveX control (.ocx), or included in a dynamic-link library (.dll or DLL) file. DLL files with one or more type libraries are often compiled as object (.olb) libraries.

To view type library information

  1. In the Object Browser, choose Open Type Library.

  2. In the Open dialog box select the tab that will give you access to the library you want.

    Recent History tab lists the most recently opened libraries.

    COM libraries tab lists the available libraries and provide a Browse button so you can find the library you want.

    Current Selection lists any open libraries.

    In the Files of type drop-down list in the Open dialog box, choose Application, *.dll, *.ocx, *.olb, or *.tlb.

  3. Select a library and click OK.

The type library information for the selected file is displayed in the Classes & Members list.

See Also

Other Resources

Browsing Classes with the Class Browser
Using Object Browser


Working with Objects in Visual FoxPro

Visual FoxPro 9.0
Working with Objects in Visual FoxPro

Visual FoxPro provides many ways to work with objects. By using objects you can create objects from classes for more reusable code, use objects to store data, and create code that is easier to read and reference.

In This Section

Objects in Visual FoxPro

Introduces objects in Visual FoxPro and how to create and use them.
Creating Objects from Classes

Describes how to create an object based on a saved visual class.
How to: Add Classes to Forms

Describes how to add a class to a form using Project Manager.
Adding Objects to a Container Class

Details how to add objects to a container through use of the ADD OBJECT clause in the DEFINE CLASS command or the AddObject method.
How to: Add Objects to a Control or Container Class

Describes how to add objects to a class using the Class Designer.
Creating Table Navigation Buttons

Provides an explanation of how to design and build table navigation buttons through code.
Defining a Grid Control

Outlines how to define grid control programmatically.
How to: Set Properties

Describes how to set the properties of an object at run time or design time.
Container Hierarchy Object Referencing

Describes how objects are referenced in the container hierarchy and explains the importance of identifying objects in relation to the container hierarchy.
Object Reference Creation

Explains how to make a reference to an object, and describes the benefits of creating references over making copies of objects.
Object and Member Arrays

Describes how to create arrays containing objects and to define class members as arrays.
Data Storage with Objects

Describes when and how to store data in objects.
How to: Call Methods

Describes how to call the methods of an object from anywhere in an application once it has been created.
Object and Data Integration

Contains information on why integrating objects and data is important.
How to: Create Instances of Classes with the Class Browser

Describes how to create a new instance of a class using the Class Browser.
How to: Add Controls to Forms with the Class Browser

Describes how to add objects to a form with the Class Browser.

Reference

Objects, Collections, and Classes

Provides a list of objects, collections, and classes in Visual FoxPro.

Related Sections

Managing Classes and Class Libraries

Discusses how to create and modify classes and class libraries within Visual FoxPro.
Working with Classes in Visual FoxPro

Discusses methods to use, modify, and create classes within Visual FoxPro.


Objects in Visual FoxPro

Visual FoxPro 9.0
Objects in Visual FoxPro
See Also

When an object is created from a class, it exists as an instance of that class. The class describes the data, characteristics, and functionality for the objects created from that class. Objects in Visual FoxPro can be forms, form sets, controls, and so on. They also have properties and methods, which you can use to manipulate the objects, and they can detect and respond to events, which are occur when certain actions are performed. An object's properties, methods, and events are defined by the class it is created from.

You can create objects by using the Form Designer or the CREATEOBJECT( ) function. For more information, see Creating Objects from Classes, Form Designer, or CREATEOBJECT( ) Function.

Features of Objects

Objects possess the following features:

  • Object Properties

  • Object Methods

  • Object Events

Object Properties

An object that you create in Visual FoxPro has properties, or attributes, that pertain specifically to that object. You can set and modify values for these properties, which determine the characteristics for the objects. You can set properties for Visual FoxPro objects at design time or run time, depending on the property.

For example, a computer has properties that can include the following: color, size, shape, location in a room, or state. Likewise, in Visual FoxPro, a check box created from the CheckBox control class includes the following properties:

  • Caption

  • Enabled

  • Top

  • Visible

For more information, see How to: Set Properties for Objects and How to: Add Properties to Classes.

Object Methods

An object has methods, which contain procedures for performing a specific task. However, object methods differ from standard Visual FoxPro procedures in that object methods are inextricably bound to an object and are called differently compared to standard Visual FoxPro procedures.

For example, a check box created from the CheckBox control class includes the following methods:

  • Drag

  • Move

  • ReadExpression

  • Refresh

You can include methods in object events or use them independently outside events. When you use methods outside events, you must call them explicitly and programmatically. You can also create and extend methods. For more information, see How to: Call Methods and How to: Add Properties to Classes.

Object Events

An object can detect and respond to specific actions called events. An event is a specific and predetermined activity that occurs when the user or system performs an action. In most cases, events occur because of user interaction. In Visual FoxPro, user actions that trigger events include clicking or moving the mouse and pressing keys. System events include initializing an object and encountering a line of code that generates an error.

For example, a check box created from the CheckBox control class includes the following events:

  • MouseEnter

  • MouseUp

  • MouseDown

  • RightClick

Events can have methods associated with them. For example, when you include method code in a Click event, the code is executed when the Click event occurs. Though extensive, the set of events available is fixed. You cannot create new events.

For more information, see Events in Visual FoxPro.

See Also

Other Resources

Object-Oriented Programming
How to: Create Classes and Subclasses
Manipulating Objects
Working with Classes in Visual FoxPro


Creating Objects from Classes

Visual FoxPro 9.0
Creating Objects from Classes
See Also

When you have saved a visual class, you can create an object based on it with the CREATEOBJECT( ) function. The following example demonstrates running a form saved as a class definition in the class library file Forms.vcx:

Creating and Showing a Form Object Whose Class Was Designed in the Form Designer

Code | Comments
SET CLASSLIB TO Forms ADDITIVE | Set the class library to the .vcx file that the form definition was saved in. The ADDITIVE keyword prevents this command from closing any other class libraries that happen to be open.
frmTest = CREATEOBJECT("TestForm") | This code assumes that the name of the form class saved in the class library is TestForm.
frmTest.Show | Display the form.

See Also

Reference

SET CLASSLIB Command
CREATEOBJECT( ) Function

Other Resources

Protecting and Hiding Class Members
Addition of Objects to a Container Class
Object-Oriented Programming


How to: Add Classes to Forms

Visual FoxPro 9.0
How to: Add Classes to Forms
See Also

You can drag a class from the Project Manager to the Form Designer or to the Class Designer. You can also register your classes so that they can be displayed directly on the Form Controls toolbar in the Class Designer or Form Designer and added to containers the same way the standard controls are added.

To add a class to a form

  1. From the Project Manager window, select a class to add to a form.

  2. Click and drag the class from the Project Manager window to an open Form Designer.

See Also

Other Resources

Working with Classes in Visual FoxPro
Object-Oriented Programming
Container Hierarchy Object Referencing
How to: Set Properties
How to: Call Methods


Adding Objects to a Container Class

Visual FoxPro 9.0
Adding Objects to a Container Class
See Also

You can use the ADD OBJECT clause in the DEFINE CLASS command or the AddObject method to add objects to a container.

For example, the following class definition is based on a form. The ADD OBJECT command adds two command buttons to the form:

Copy Code
DEFINE CLASS myform AS FORM
  ADD OBJECT cmdOK AS COMMANDBUTTON
  ADD OBJECT PROTECTED cmdCancel AS COMMANDBUTTON
ENDDEFINE

Use the AddObject method to add objects to a container after the container object has been created. For example, the following lines of code create a form object and add two command buttons to it:

Copy Code
frmMessage = CREATEOBJECT("FORM")
frmMessage.AddObject("txt1", "TEXTBOX")
frmMessage.AddObject("txt2", "TEXTBOX")

You can also use the AddObject method in the method code of a class. For example, the following class definition uses AddObject in the code associated with the Init event to add a control to a grid column.

Copy Code
DEFINE CLASS mygrid AS GRID
ColumnCount = 3
PROCEDURE Init
  THIS.Column2.AddObject("cboClient", "COMBOBOX")
  THIS.Column2.CurrentControl = "cboClient"
ENDPROC
ENDDEFINE

Adding and Creating Classes in Method Code

You can programmatically add objects to a container with the AddObject method. You can also create objects with the CREATEOBJECT( ) function in the Load, Init, or any other method of the class.

When you add an object with the AddObject method, the object becomes a member of the container. The Parent property of the added object refers to the container. When an object based on the container or control class is released from memory, the added object is also released.

When you create an object with the CREATEOBJECT( ) function, the object is scoped to a property of the class or a variable in the method that calls this function. The parent property of the object is undefined.

See Also

Other Resources

Creating Objects from Classes
Protecting and Hiding Class Members
Object-Oriented Programming
Parent Object Reference


How to: Add Objects to a Control or Container Class

Visual FoxPro 9.0
How to: Add Objects to a Control or Container Class
See Also

If you base a new class on a control or container class, you can add controls to it using the Class Designer the same way you add controls in the Form Designer.

To add controls to a class

  1. Open the class in the Class Designer.

  2. From the Form Controlstoolbar, drag a control to the control or container class in the Class Designer.

    Tip:
    To deactivate the snap-to-grid functionality, press and hold the CTRL key while dragging objects from the toolbar.

See Also

Other Resources

Working with Classes in Visual FoxPro
How to: Add Properties to Classes
Object-Oriented Programming
Container Hierarchy Object Referencing


Creating Table Navigation Buttons

Visual FoxPro 9.0
Creating Table Navigation Buttons
See Also

A common feature of many applications is a series of navigation buttons that allow users to move through a table. These typically include buttons to move the record pointer to the next or prior record in the table, as well as to the top or bottom record in the table.

Designing the Navigation Buttons

Each of the buttons will have some characteristics and functionality in common, so it is a good idea to create a navigation button class. Then the individual buttons can easily derive this common appearance and functionality. This parent class is the Navbutton class defined later in this section.

Once the parent class is defined, the following subclasses define the functionality and appearance specific to each of the four navigation buttons: navTop, navPrior, navNext, navBottom.

Finally, a container class, vcr, is created and each of the navigation buttons is added to the container class. The container can be added to a form or a toolbar to provide table navigation functionality.

NAVBUTTON Class Definition

To create Navbutton, save the following six class definitions (Navbutton, navTop, navBottom, navPrior, navNext, and vcr) to a program file such as Navclass.prg.

Definition of the Generic Navigation Commandbutton Class

Code | Comments
DEFINE CLASS Navbutton AS COMMANDBUTTON Height = 25 Width = 25 TableAlias = "" | Define the parent class of the navigation buttons. Give the class some dimensions. Include a custom property, TableAlias, to hold the name of the alias to navigate through.
PROCEDURE Click IF NOT EMPTY(This.TableAlias) SELECT (This.TableAlias) ENDIF ENDPROC | If TableAlias has been set, this parent class procedure selects the alias before the actual navigation code in the subclasses is executed. Otherwise, assume that the user wants to navigate through the table in the currently selected work area.
PROCEDURE RefreshForm _SCREEN.ActiveForm.Refresh ENDPROC | Using _SCREEN.ActiveForm.Refresh instead of THISFORM.Refresh allows you to add the class to a form or a toolbar and have it function equally well.
ENDDEFINE | End the class definition.

The specific navigation buttons are all based on the Navbutton class. The following code defines the Top button for the set of navigation buttons. The remaining three navigation buttons are defined in the following table. The four class definitions are similar, so only the first one has extensive comments.

Definition of the Top Navigation Button Class

Code | Comments
DEFINE CLASS navTop AS Navbutton Caption = "|<" | Define the Top navigation button class and set the Caption property.
PROCEDURE Click | Create method code to be executed when the Click event for the control occurs.
DODEFAULT( ) GO TOP THIS.RefreshForm | Call the Click event code in the parent class, Navbutton, so that the appropriate alias can be selected if the TableAlias property has been set. Include the code to set the record pointer to the first record in the table: GO TOP. Call the RefreshForm method in the parent class. It is not necessary to use the scope resolution operator (::) in this case because there is no method in the subclass with the same name as the method in the parent class. On the other hand, both the parent and the subclass have method code for the Click event.
ENDPROC | End the Click procedure.
ENDDEFINE | End the class definition.

The other navigation buttons have similar class definitions.

Definition of the Other Navigation Button Classes

Code | Comments
DEFINE CLASS navNext AS Navbutton Caption = ">" | Define the Next navigation button class and set the Caption property.
PROCEDURE Click DODEFAULT( ) SKIP 1 IF EOF( ) GO BOTTOM ENDIF THIS.RefreshForm ENDPROC ENDDEFINE | Include the code to set the record pointer to the next record in the table. End the class definition.
DEFINE CLASS navPrior AS Navbutton Caption = "<" | Define the Prior navigation button class and set the Caption property.
PROCEDURE Click DODEFAULT( ) SKIP –1 IF BOF( ) GO TOP ENDIF THIS.RefreshForm ENDPROC ENDDEFINE | Include the code to set the record pointer to the previous record in the table. End the class definition.
DEFINE CLASS navBottom AS Navbutton Caption = ">|" | Define the Bottom navigation button class and set the Caption property.
PROCEDURE Click DODEFAULT( ) GO BOTTOM THIS.RefreshForm ENDPROC ENDDEFINE | Include the code to set the record pointer to the bottom record in the table. End the class definition.

The following class definition contains all four navigation buttons so that they can be added as a unit to a form. The class also includes a method to set the TableAlias property of the buttons.

Definition of a Table Navigation Control Class

Code | Comments
DEFINE CLASS vcr AS CONTAINER Height = 25 Width = 100 Left = 3 Top = 3 | Begin the class definition. The Height property is set to the same height as the command buttons it will contain.
ADD OBJECT cmdTop AS navTop ; WITH Left = 0 ADD OBJECT cmdPrior AS navPrior ; WITH Left = 25 ADD OBJECT cmdNext AS navNext ; WITH Left = 50 ADD OBJECT cmdBot AS navBottom ; WITH Left = 75 | Add the navigation buttons.
PROCEDURE SetTable(cTableAlias) IF TYPE("cTableAlias") = 'C' THIS.cmdTop.TableAlias = ; cTableAlias THIS.cmdPrior.TableAlias = ; cTableAlias THIS.cmdNext.TableAlias = ; cTableAlias THIS.cmdBot.TableAlias = ; cTableAlias ENDIF ENDPROC | This method is used to set the TableAlias property of the buttons. TableAlias is defined in the parent class Navbutton. You could also use the SetAll method to set this property:IF TYPE ("cTableAlias") = 'C' This.SetAll("TableAlias", "cTableAlias")ENDIF However, this would cause an error if an object were ever added to the class that did not have a TableAlias property.
ENDDEFINE | End class definition.

Once you have defined the class, you can subclass it or add it to a form.

Creating a Subclass Based on the New Class

You can also create subclasses based on vcr that have additional buttons such as Search, Edit, Save, and Quit. For example, vcr2 includes a Quit button:

Definition of a Table Navigation Control Subclass

Code | Comments
DEFINE CLASS vcr2 AS vcr ADD OBJECT cmdQuit AS COMMANDBUTTON WITH ; Caption = "Quit",; Height = 25, ; Width = 50 Width = THIS.Width + THIS.cmdQuit.Width cmdQuit.Left = THIS.Width - ; THIS.cmdQuit.Width | Define a class based on vcr and add a command button to it.
PROCEDURE cmdQuit.CLICK RELEASE THISFORM ENDPROC | When the user clicks cmdQuit, this code releases the form.
ENDDEFINE | End class definition.

Vcr2 has everything that vcr does, plus the new command button, and you don't have to rewrite any of the existing code.

Changes to VCR Reflected in the Subclass

Because of inheritance, changes to the parent class are reflected in all subclasses based on the parent. For example, you could let the user know that the bottom of the table has been reached by changing the IF EOF( ) statement in navNext.Click to the following:

Copy Code
IF EOF( )
   GO BOTTOM
   SET MESSAGE TO "Bottom of the table"
ELSE
   SET MESSAGE TO
ENDIF

You could let the user know that the top of the table has been reached by changing the IF BOF( ) statement in navPrior.Click to the following:

Copy Code
IF BOF()
   GO TOP
   SET MESSAGE TO "Top of the table"
ELSE
   SET MESSAGE TO
ENDIF

If these changes are made to the navNext and navPrior classes, they will also apply automatically to the appropriate buttons in vcr and vcr2.

Adding VCR to a Form Class

Once vcr is defined as a control, the control can be added in the definition of a container. For example, the following code added to Navclass.prg defines a form with added navigation buttons:

Copy Code
DEFINE CLASS NavForm AS Form
   ADD OBJECT oVCR AS vcr
ENDDEFINE

Running the Form Containing VCR

Once the form subclass is defined, you can display it by loading the class definition, creating an object based on the subclass and calling the Show method for the form:

Copy Code
SET PROCEDURE TO navclass ADDITIVE
frmTest = CREATEOBJECT("navform")
frmTest.Show

If you don't call the SetTable method of oVCR (the VCR object in NavForm) when the user clicks the navigation buttons, the record pointer moves in the table in the currently selected work area. You can call the SetTable method to specify what table to move through.

Copy Code
frmTest.oVCR.SetTable("customer")
Note:
When the user closes the form, frmTest is set to a null value (.NULL.). To release the object variable from memory, use the RELEASE command. Object variables created in program files are released from memory when the program is completed.

See Also

Other Resources

Defining a Grid Control
Caption property
Height property
SetAll method
Object-Oriented Programming


Defining a Grid Control

Visual FoxPro 9.0
Defining a Grid Control
See Also

A grid contains columns, which in turn can contain headers and any other control. The default control contained in a column is a text box, so that the default functionality of the grid approximates a Browse window. However, the underlying architecture of the grid opens it up to endless extensibility.

The following example creates a form that contains a Grid object with two columns. The second column contains a check box to display the values in a logical field in a table.

Definition of a Grid Class with a Check Box in a Grid Column

Code | Comments
DEFINE CLASS grdProducts AS Grid Left = 24 Top = 10 Width = 295 Height = 210 Visible = .T. RowHeight = 28 ColumnCount = 2 | Start the class definition and set properties that determine the grid appearance. When you set the ColumnCount property to 2, you add two columns to the grid. Each column contains a header with the name Header1. In addition, each column has an independent group of properties that determines its appearance and behavior.
Column1.ControlSource ="prod_name" Column2.ControlSource ="discontinu" | When you set the ControlSource of a column, the column displays that field's values for all the records in the table.Discontinu is a logical field.
Column2.Sparse = .F. | Column2 will contain the check box. Set the column's Sparse property to .F. so that the check box will be visible in all rows, not just in the selected cell.
Procedure Init THIS.Column1.Width = 175 THIS.Column2.Width = 68 THIS.Column1.Header1.Caption = ; "Product Name" THIS.Column2.Header1.Caption = ; "Discontinued" THIS.Column2.AddObject("chk1", ; "checkbox") THIS.Column2.CurrentControl = ; "chk1" THIS.Column2.chk1.Visible = .T. THIS.Column2.chk1.Caption = "" ENDPROC | Set column widths and header captions. The AddObject method allows you to add an object to a container — in this case, a check box named chk1. Set the CurrentControl of the column to the check box so that the check box will be displayed. Make sure that the check box is visible. Set the caption to an empty string so that the default caption "chk1" won't be displayed.
ENDDEFINE | End of the class definition.

The following class definition is the form that contains the grid. Both class definitions can be included in the same program file.

Definition of a Form Class that Contains the Grid Class

Code | Comments
DEFINE CLASS GridForm AS FORM Width = 330 Height = 250 Caption = "Grid Example" ADD OBJECT grid1 AS grdProducts | Create a form class and add an object, based on the grid class, to it.
PROCEDURE Destroy CLEAR EVENTS ENDPROC ENDDEFINE | The program that creates an object based on this class will use READ EVENTS. Including CLEAR EVENTS in the Destroy event of the form allows the program to finish running when the user closes the form. End of the class definition.

The following program opens the table with the fields to be displayed in the grid columns, creates an object based on the GridForm class, and issues the READ EVENTS command:

Copy Code
CLOSE DATABASE
OPEN DATABASE (HOME(2) + "data\testdata.dbc")
USE products
frmTest= CREATEOBJECT("GridForm")
frmTest.Show
READ EVENTS

This program can be included in the same file with the class definitions if it comes at the beginning of the file. You could also use the SET PROCEDURE TO command to specify the program with the class definitions and include this code in a separate program.

See Also

Other Resources

How to: Create Classes and Subclasses
How to: Create a Set of Table Navigation Buttons
Object Reference Creation
Browse
Sparse property
AddObject method
CurrentControl
Object-Oriented Programming


How to: Set Properties

Visual FoxPro 9.0
How to: Set Properties
See Also

You can set the properties of an object at run time or design time.

Specifying the Default Value for a Property

You can set any of the base class properties in the Class Designer. When an object based on the class is added to the form, the object reflects your property settings rather than the Visual FoxPro base class property settings.

Caution:
Properties in subclasses inherit the default property values that you specify unless you choose Reset to Default on the shortcut menu for the property, which resets the default values to those of the parent class.

To set a property

  • Use the following syntax to set an object property programmatically:

    Container.Object.Property = Value

    For example, the following statements set various properties of a text box named txtDate on a form named frmPhoneLog:

    Copy Code
    frmPhoneLog.txtDate.Value = DATE( ) && Display the current date
frmPhoneLog.txtDate.Enabled = .T. && The control is enabled
frmPhoneLog.txtDate.ForeColor = RGB(0,0,0)    && black text
frmPhoneLog.txtDate.BackColor = RGB(192,192,192)  && gray background

For the property settings in the preceding examples, frmPhoneLog is the highest-level container object. If frmPhoneLog were contained in a form set, you would also need to include the form set in the parent path:

Copy Code
frsContacts.frmPhoneLog.txtDate.Value = DATE( )

To set multiple properties

  • Use the WITH ... ENDWITH Command structure to simplify setting multiple properties.

For example, to set multiple properties of a column in a grid in a form in a form set, you could use the following syntax:

Copy Code
WITH THISFORMSET.frmForm1.grdGrid1.grcColumn1
 .Width = 5
 .Resizable = .F.
 .ForeColor = RGB(0,0,0)
 .BackColor = RGB(255,255,255)
 .SelectOnEntry = .T.
ENDWITH
Note:
You can also modify an object's properties in the Properties Window.

See Also

Other Resources

Object-Oriented Programming
Working with Classes in Visual FoxPro
Protecting and Hiding Class Members
Overriding Default Property Settings


Container Hierarchy Object Referencing

Visual FoxPro 9.0
Container Hierarchy Object Referencing
See Also

The container and the class hierarchy are two separate entities. Objects are referenced in the container hierarchy, whereas Visual FoxPro searches for event code up through the class hierarchy.

To manipulate an object, you need to identify it in relation to the container hierarchy. For example, to manipulate a control on a form in a form set, you need to reference the form set, the form, and then the control.

You can compare the referencing of an object within its container hierarchy to giving Visual FoxPro an address to your object. When you describe the location of a house to someone outside your immediate frame of reference, you need to indicate the country, the state or region, the city, the street, or just the street number of the house, depending on how far they are from you. Otherwise, there could be some confusion.

The following illustration shows a possible container-nesting situation.

To disable the control in the grid column, you need to provide the following address:

Copy Code
Formset.Form.PageFrame.Page.;
 Grid.Column.Control.Enabled = .F.

The ActiveForm property of the application object (_VFP) allows you to manipulate the active form even if you don't know the name of the form. For example, the following line of code changes the background color of the active form, no matter what form set it belongs to:

Copy Code
_VFP.ActiveForm.BackColor = RGB(255,255,255)

Similarly, the ActiveControl property allows you to manipulate the active control on the active form. For example, the following expression entered in the Watch window displays the name of the active control on a form as you interactively choose the various controls:

Copy Code
_VFP.ActiveForm.ActiveControl.Name

Relative Referencing

When you are referencing objects from within the container hierarchy (for example, in the Click event of a command button on a form in a form set), you can use some shortcuts to identify the object you want to manipulate. The following table lists properties or keywords that make it easier to reference an object from within the object hierarchy:

Property or keyword | Reference
Parent | The immediate container of the object.
THIS | The object.
THISFORM | The form that contains the object.
THISFORMSET | The form set that contains the object.
Note:
You can use THIS, THISFORM, and THISFORMSET only in method or event code.

The following table provides examples of using THISFORMSET, THISFORM, THIS, and Parent to set object properties:

Command | Where to include the command
THISFORMSET.frm1.cmd1.Caption = "OK" | In the event or method code of any controls on any form in the form set.
THISFORM.cmd1.Caption = "OK" | In the event or method code of any control on the same form that cmd1 is on.
THIS.Caption = "OK" | In the event or method code of the control whose caption you want to change.
THIS.Parent.BackColor = RGB(192,0,0) | In the event or method code of a control on a form. The command changes the background color of the form to dark red.

See Also

Other Resources

Object-Oriented Programming
Working with Classes in Visual FoxPro


Object Reference Creation

Visual FoxPro 9.0
Object Reference Creation
See Also

Instead of making a copy of an object, you can create a reference to the object. A reference takes less memory than an additional object, can easily be passed between procedures, and can aid in writing generic code.

Returning a Reference to an Object

Sometimes, you might want to manipulate an object by means of one or more references to the object. For example, the following program defines a class, creates an object based on the class, and returns a reference to the object:

Copy Code
*--NEWINV.PRG
*--Returns a reference to a new invoice form.
frmInv = CREATEOBJECT("InvoiceForm")
RETURN frmInv

DEFINE CLASS InvoiceForm AS FORM
   ADD OBJECT txtCompany AS TEXTBOX
   * code to set properties, add other objects, and so on
ENDDEFINE

The following program establishes a reference to the object created in Newinv.prg. The reference variable can be manipulated in exactly the same way as the object variable can:

Copy Code
frmInvoice = NewInv() && store the object reference to a variable
frmInvoice.SHOW

You can also create a reference to an object on a form, as in the following example:

Copy Code
txtCustName = frmInvoice.txtCompany
txtCustName.Value = "Fox User"
Tip:
Once you've created an object, you can use the DISPLAY OBJECTS command to display the object's class hierarchy, property settings, contained objects, and available methods and events. You can fill an array with the properties (not the property settings), events, methods, and contained objects of an object with the AMEMBERS() function.

Releasing Objects and References from Memory

If a reference to an object exists, releasing the object does not clear the object from memory. For example, the following command releases frmInvoice, the original object:

Copy Code
RELEASE frmInvoice

However, because a reference to an object belonging to frmInvoice still exists, the object is not released from memory until txtCustName is released with the following command:

Copy Code
RELEASE txtCustName

Checking to See if an Object Exists

You can use the TYPE( ), ISNULL( ), and VARTYPE( ) functions to determine if an object exists. For example, the following lines of code check to see whether an object named oConnection exists:

Copy Code
IF TYPE("oConnection") = "O" AND NOT ISNULL(oConnection)
   * Object exists
ELSE
   * Object does not exist
ENDIF
Note:
ISNULL() is necessary because .NULL. is stored to the form object variable when a user closes a form, but the type of the variable remains "O".

See Also

Other Resources

Defining a Grid Control
Object and Member Arrays
DISPLAY OBJECTS
AMEMBERS( )
Object-Oriented Programming


Object and Member Arrays

Visual FoxPro 9.0
Object and Member Arrays
See Also

You can create arrays containing objects and as class members.

Object Arrays

You can create arrays that contain objects. When creating arrays that contain objects, keep in mind the following considerations:

  • You cannot assign an individual object to all the elements in an array using a single command. You must assign the object to each element of the array individually.

  • You cannot assign a value to the property of an entire array.

    For example, the following command results in an error:

    Copy Code
    MyArray.Enabled = .F.
  • When you redimension an object array so that it is larger than the original array, the new elements are initialized to False (.F.) as is the case with all arrays in Visual FoxPro. When you redimension an object array so that it is smaller than the original array, the objects with a subscript greater than the largest new subscript are released.

For example, the following code creates an array named MyArray that holds five command buttons using a loop structure:

Copy Code
DIMENSION MyArray[5]
FOR x = 1 TO 5
   MyArray[x] = CREATEOBJECT("CommandButton")
ENDFOR

Class Member Arrays

You can include arrays as class members and store objects in them.

The following example creates a form that contains an object created from the custom Container class, ButtonList. The ButtonList class contains a member that is an array named, aChoices, in which each element contain a different control object.

When you run the example from a program (.prg) file, a form appears with two command buttons and a check box. When the user clicks a command button or selects the check box on the form, Visual FoxPro passes the index number of the array element that contains the control to the Click event through the tnIndex parameter. A DO CASE command structure displays a window with the number of the element.

different code depending on which button was clicked.

Copy Code
loForm = CREATEOBJECT("Form")
loForm.AddObject("cntButtons", "ButtonList")
loForm.cntButtons.SetAll("Visible", .T.)
loForm.cntButtons.Visible = .T.
loForm.Show(1)

DEFINE CLASS ButtonList AS Container
   Height = 100
   Width = 130
   BorderWidth = 0

   DIMENSION aChoices[3]

   ADD OBJECT aChoices[1] AS CommandButton WITH ;
      Top = 10, ;
      Height = 20, ;
      Left = 10, ;
      Caption = "Element One"
   ADD OBJECT aChoices[2] AS CommandButton WITH ;
      Top = 40, ;
      Left = 10, ;
      Height = 20, ;
      Caption = "Element Two"
   ADD OBJECT aChoices[3] AS CheckBox WITH ;
      Top = 70, ;
      Left = 10, ;
      Caption = "Element Three"

   PROCEDURE aChoices.Click
      LPARAMETER tnIndex
      DO CASE
         CASE tnIndex = 1
            WAIT WINDOW "1"
         CASE tnIndex = 2
            WAIT WINDOW "2"
         CASE tnIndex = 3
            WAIT WINDOW "3"
      ENDCASE
   ENDPROC
ENDDEFINE

See Also

Other Resources

Arrays
Objects in Visual FoxPro
Adding Objects to a Container Class
Working with Objects


Data Storage with Objects

Visual FoxPro 9.0
Data Storage with Objects
See Also

In object-oriented languages, a class offers a useful and convenient vehicle for storing data and procedures related to an entity. For example, you could define a customer class to hold information about a customer as well as a method to calculate the customer's age:

Copy Code
DEFINE CLASS customer AS CUSTOM
   LastName = ""
   FirstName = ""
   Birthday = { - - }
   PROCEDURE Age
      IF !EMPTY(THIS.Birthday)
         RETURN YEAR(DATE()) - YEAR(THIS.Birthday)
      ELSE
         RETURN 0
      ENDIF
   ENDPROC
ENDDEFINE

However, data stored in objects based on the customer class are stored only in memory. If this data were in a table, the table would be stored on disk. If you had more than one customer to keep track of, the table would give you access to all of the Visual FoxPro database management commands and functions. As a result, you could quickly locate information, sort it, group it, perform calculations on it, create reports and queries based on it, and so on.

Storing and manipulating data in databases and tables is what Visual FoxPro does best. There are times, however, when you'll want to store data in objects. Usually, the data will be significant only while your application is running and it will pertain to a single entity.

For example, in an application that includes a security system, you would typically have a table of users who have access to the application. The table would include user identification, password, and access level. Once a user has logged on, you won't need all the information in the table. All you need is information about the current user, and this information can be easily stored and manipulated in an object. The following class definition, for example, initiates a logon when an object based on the class is created:

Copy Code
DEFINE CLASS NewUser AS CUSTOM
   PROTECTED LogonTime, AccessLevel
   UserId = ""
   PassWord = ""
   LogonTime = { - - : : }
   AccessLevel = 0
   PROCEDURE Init
      DO FORM LOGON WITH ; && assuming you have created this form
         This.UserId, ;
         This.PassWord, ;
         This.AccessLevel
      This.LogonTime = DATETIME( )
   ENDPROC
* Create methods to return protected property values.
   PROCEDURE GetLogonTime
      RETURN This.LogonTime
   ENDPROC
   PROCEDURE GetAccessLevel
      RETURN This.AccessLevel
   ENDPROC

ENDDEFINE

In the main program of your application, you could create an object based on the NewUserclass:

Copy Code
oUser = CREATEOBJECT('NewUser')
oUser.Logon

Throughout your application, when you need information about the current user, you can get it from the oUser object. For example:

Copy Code
IF oUser.GetAccessLevel( ) >= 4
   DO ADMIN.MPR
ENDIF

See Also

Other Resources

Object and Member Arrays
Object and Data Integration
Object Reference Creation
Object-Oriented Programming


How to: Call Methods

Visual FoxPro 9.0
How to: Call Methods
See Also

Once an object has been created, you can call the methods of that object from anywhere in your application.

To call a method

  • Use this syntax:

    Copy Code
                  Parent.Object.Method

The following statements call methods to display a form and set the focus to a text box:

Copy Code
frsFormSet.frmForm1.Show
frsFormSet.frmForm1.txtGetText1.SetFocus

Methods that return values and are used in expressions must end in open and closed parentheses. For example, the following statement sets the caption of a form to the value returned from the user-defined method GetNewCaption:

Copy Code
Form1.Caption = Form1.GetNewCaption( )
Note:
Parameters passed to methods must be included in parentheses after the method name; for example, Form1.Show(nStyle) passes nStyle to Form1's Show method code.

See Also

Other Resources

Protecting and Hiding Class Members
Overriding Default Property Settings
Working with Classes in Visual FoxPro
Object-Oriented Programming


Object and Data Integration

Visual FoxPro 9.0
Object and Data Integration
See Also

In most applications, you can best utilize the power of Visual FoxPro by integrating objects and data. Most Visual FoxPro classes have properties and methods that allow you to integrate the power of a relational database manager and a full object-oriented system.

Properties for Integrating Visual FoxPro Classes and Database Data

Class | Data properties
Grid | RecordSource, ChildOrder, LinkMaster
All other controls | ControlSource
List box and combo box | ControlSource, RowSource
Form and form set | DataSession

Because these data properties can be changed at design or run time, you can create generic controls with encapsulated functionality that operate on diverse data.

For more information about integrating data and objects, see Creating Forms, and Using Controls

See Also

Other Resources

Data Storage with Objects
Object Reference Creation
Object-Oriented Programming


How to: Create Instances of Classes with the Class Browser

Visual FoxPro 9.0
How to: Create Instances of Classes with the Class Browser
See Also

You can create instances of classes in the Class Browser so you can view instances of those classes. For example, if you create an instance of a form or form class, the form is created and displayed.

Note:
When you create an instance of a class, the code in the Init event and possibly other events runs. Before you create an instance, know what code is associated with your classes. If the class requires a particular environment that has not been set up, Visual FoxPro generates errors. The Class Browser does not provide error handling for user-defined classes.

To create an instance of a class

  1. Open the class library or form in the Class Browser.

  2. In the class list of the Class Browser, select the class or form you want to create an instance of.

  3. Drag the class icon that appears next to the type list in the Class Browser to the main Visual FoxPro window.

    Note:
    If you drag a form or form class to the main Visual FoxPro window, the form is created and displayed. If you drag a control to the main Visual FoxPro window, the control is added to the _SCREEN object. For more information, see _SCREEN System Variable.

To create an instance of the class without displaying it, press and hold the SHIFT key during the drag operation. To suppress error messages when you create instances, press and hold the CTRL key during the drag operation.

To call the appropriate NEWOBJECT( ) or CREATEOBJECT( ) function to instantiate the class, you can drag the class icon to the Command window.

To remove an object from the _SCREEN object

  • Use the RemoveObject method for _SCREEN.

For example, suppose you drag the VCR class from Buttons.vcx class in the Visual FoxPro ...\Samples\Classes directory to a form. You can remove the instance of the class from _SCREEN by typing the following line of code in the Command window:

Copy Code
_SCREEN.RemoveObject("VCR1")

See Also

Other Resources

Operating the Class Browser
Class Browser Buttons
Class Browser Window
How to: Customize the Class Browser
SaveAs Method
SaveAsClass Method
How to: View Class Hierarchies
How to: View Type Library Information


How to: Add Controls to Forms with the Class Browser

Visual FoxPro 9.0
How to: Add Controls to Forms with the Class Browser
See Also

You can add controls from the Class Browser while designing or running a form.

To add controls to a form or container

  1. In the Form Designer, open the form.

  2. In the Class Browser, open the class library file containing the class of the object you want to add to the form.

  3. From the Class list, select the class name, and then drag the class icon on the form. The class icon is located above the Class list.

To view the class for a control on a form or in a container

  1. In the Form Designer, select the control.

  2. From the Tools menu, choose Class Browser. The Class Browser opens and displays the class of the control you selected on the form.

You can design your forms so that you can add objects of a class from the Class Browser on the form while it is running. You might want to design a form class that has this feature as one of its properties.

To add objects on a running form or a container on a form

  1. Run the form.

  2. Open the Class Browser and view the class list containing the class of object you want to add to the form.

  3. Select the class you want and drag the class icon from the Class Browser to the form.

  4. A new object appears on the form based on the class you selected from the Class Browser.

    Tip:
    You can also add an instance of the selected class to any container by positioning the mouse pointer over the container and entering the following line of code in the Command window: _oBrowser.FormAddObject(SYS(1270))

To view the class for a control on a running form

  1. Set the focus to the control.

  2. From the Tools menu, choose Class Browser. The Class Browser evaluates _SCREEN.ActiveForm.ActiveControl and displays the class of the control you selected on the form.

See Also

Other Resources

Operating the Class Browser
Class Browser Buttons
Class Browser Window
How to: Customize the Class Browser
SaveAs Method
SaveAsClass Method
How to: View Class Hierarchies
How to: View Type Library Information


Understanding the Event Model

Visual FoxPro 9.0
Understanding the Event Model

The Visual FoxPro event model is extensive and provides much control over how the components in your application respond to wide variety of system and user actions. Visual FoxPro manages the processing of events so you can provide a richer interactive environment for application users.

In This Section

Events in Visual FoxPro

Provides an overview of events in Visual FoxPro.
Event Sequence in Visual FoxPro

Explains and illustrates the sequence in which events occur.
How to: Track Event Sequences

Explains how to track events.
Considerations for Event Code

Describes considerations to remember when adding code to events.
Event Binding for Objects

Introduces event binding which makes it possible for you to attach events, methods, and properties from a Visual FoxPro object or an event from a Component Object Model (COM) object to a Visual FoxPro object.

Related Sections

Object-Oriented Programming

Discusses how you can create self-contained application components that respond to user actions and to the system and which can be easily maintained and reused.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.


Events in Visual FoxPro

Visual FoxPro 9.0
Events in Visual FoxPro
See Also

Events occur automatically when the system or application user performs a specific action. Events associated with an object occur when a user interacts with the object in any way, such as tabbing to it, clicking it, or moving the mouse pointer over it. For example, the CommandButton class contains a Click event that is triggered when the user clicks the command button.

You can add code to the event procedure of an object so that when the event occurs for the object, the code executes automatically. For example, you can add code to the Click event so that when the user clicks the command button, the code executes automatically to perform an action, such as opening a form. System events can also execute code in events as in the case of the Timer event in a Timer control.

The following table contains a list of the core set of Visual FoxPro events, which apply to most controls.

Core Events in Visual FoxPro

Event | Event occurs when
Init | An object is created.
Destroy | An object is released from memory.
Click | The user clicks the object using the primary mouse button.
DblClick | The user double-clicks the object using the primary mouse button.
RightClick | The user clicks the object using the secondary mouse button.
GotFocus | The object receives the focus through user action such as tabbing or clicking or by changing the focus in code using the SetFocus Method. For more information, see SetFocus Method.
LostFocus | The object loses the focus through user action such as tabbing to or clicking another object or by changing the focus in code using the SetFocus method.
KeyPress | The user presses and releases a key.
MouseDown | The user presses the mouse button while the mouse pointer is over the object.
MouseMove | The user moves the mouse pointer over the object.
MouseUp | The user releases the mouse button while the mouse pointer is over the object.

Triggering Events Programmatically

Most events occur automatically when the system or user performs an action. However, you can generate the following events programmatically using certain Visual FoxPro commands:

  • Use the MOUSE command to generate the Click, DblClick, MouseMove, and DragDrop events.

  • Use the ERROR command to generate the Error event.

  • Use the KEYBOARD command to generate the KeyPress event.

For more information, see MOUSE Command, ERROR Command, and KEYBOARD Command.

Though you cannot trigger most events programmatically, you can call the procedure associated with the event, which executes the code in the event but does not trigger the event itself. For example, the following line calls the Activate event procedure for the form frmPhoneLog and executes the code in the event; however, it does not activate the form itself:

Copy Code
frmPhoneLog.Activate

If you want to activate the form, use the form's Show method:

Copy Code
frmPhoneLog.Show

Calling the Show method displays and activates the form, which also executes the code in the Activate event.

See Also

Other Resources

Event Sequence in Visual FoxPro
Considerations for Event Code
Event Binding for Objects
Understanding the Event Model


Event Sequence in Visual FoxPro

Visual FoxPro 9.0
Event Sequence in Visual FoxPro
See Also

Though some events occur as single events, a user action often triggers multiple events. Some of these events occur independently; however, some event sequences are fixed, for example, the event sequence that occurs when a form is created or destroyed.

When a sequence of events is triggered for a control, the entire sequence of events is associated with the control. For example, suppose you click the left mouse button on a command button and the drag the mouse pointer away from the command button. The command button's MouseMove event continues to occur even though the mouse pointer moves over the form. If you release the left mouse button over the form instead of over the command button, the MouseUp event that occurs is associated with the command button instead of the form.

The following table shows the general sequence of Visual FoxPro events, assuming that the data environment's AutoOpenTables property is set to True (.T.). Other events can occur based on user interaction and system response.

Visual FoxPro Event Sequence

Object | Event that occurs
Data environment | BeforeOpenTables
Form set | Load
Form | Load
Data environment cursor(s) | Init
Data environment | Init
Objects 1 | Init
Form | Init
Form set | Init
Form set | Activate
Form | Activate
Object1 2 | When
Form | GotFocus
Object1 | GotFocus
Object1 | Message
Object1 | Valid 3
Object1 | LostFocus
Object2 3 | When
Object2 | GotFocus
Object2 | Message
Object2 | Valid 4
Object2 | LostFocus
Form | QueryUnload
Form | Destroy
Object 5 | Destroy
Form | Unload
Form set | Unload
Data environment | AfterCloseTables
Data environment | Destroy
Data environment cursor(s) | Destroy

1. For each object, from innermost object to outermost container 2. First object in the tab order 3. Next object to get focus 4. As the object loses focus 5.For each object, from outermost container to innermost object

Event Sequence Example

The following example uses a form to illustrate the order in which events occur in response to user interaction.

In this example, the user performs the following actions:

  1. Runs the form.

  2. Types text in the Text1 text box.

  3. Selects the text and copies it to the Clipboard.

  4. Moves to the Text2 text box by pressing the TAB key.

  5. Pastes the text into Text2.

  6. Closes the form by clicking the Command2 command button.

These actions trigger system events for each object. The following tables list the events that occur in response to each user action.

Note:
In this example, the Paint event has been removed from the tables because this event occurs frequently and makes it difficult to see the sequences of the other events.

Action 1

The user runs the form by typing the following command in the Command window:

Copy Code
DO FORM form1 NAME frmObject

Visual FoxPro loads the form, initializes each object, and then initializes the form. The form is activated and the first text box receives input focus.

Object | Event
DataEnvironment | BeforeOpenTables
Form1 | Load
DataEnvironment | Init
Text1 | Init
Text2 | Init
Command1 | Init
Command2 | Init
Form1 | Init
Form1 | Activate
Form1 | GotFocus
Text1 | When
Text1 | GotFocus

Action 2

The user types the text "Test" in the text box, Text1. Each keystroke generates two events.

Note:
The KeyPress event receives two parameters: a number representing the pressed key and the state of the SHIFT, ALT, and CTRL keys.

Object | Event | Parameters
Text1 | KeyPress | (84 for "T", 1)
Text1 | InteractiveChange |
Text1 | KeyPress | (101 for "e", 0)
Text1 | InteractiveChange |
Text1 | KeyPress | (115 for "s", 0)
Text1 | InteractiveChange |
Text1 | KeyPress | (116 for "t",0)
Text1 | InteractiveChange |

Action 3

The user selects the text in the text box, Text1, by double-clicking the text and copies the text to the Clipboard by pressing CTRL+C. Mouse events and a Click event accompany the DblClick event.

Note:
The MouseMove, MouseDown, and MouseUp events receive four parameters: a number indicating the pressed button, the state of the SHIFT key, and (X, Y) coordinates. The X and Y coordinates are relative to the form and reflect the form's scale mode, for example, pixels. Though only one MouseMove event is listed for each control, in actuality, this event can occur half a dozen times or more.

Object | Event | Parameters
Form1 | MouseMove | (0, 0, 100, 35)
Text1 | MouseMove | (0, 0, 44, 22)
Text1 | MouseDown | (1, 0, 44, 22)
Text1 | MouseUp | (1, 0, 44, 22)
Text1 | Click |
Text1 | MouseDown | (1, 0, 44, 22)
Text1 | MouseUp | (1, 0, 44, 22)
Text1 | DblClick |

Action 4

The user moves to the text box, Text2, by pressing the TAB key.

Object | Event | Parameters
Text1 | KeyPress | (9, 0)
Text1 | Valid |
Text1 | LostFocus |
Text2 | When |
Text2 | GotFocus |

Action 5

The user pastes the text into the text box, Text2, by pressing CTRL+V.

Object | Event
Text2 | InteractiveChange

Action 6

The user clicks the command button, Command2, to close the form.

Object | Event |
Form1 | MouseMove |
Command2 | MouseMove |
Text2 | Valid |
Command2 | When |
Text2 | LostFocus |
Command2 | GotFocus |
Command2 | MouseDown | (1, 0, 143, 128)
Command2 | MouseUp | (1, 0, 143, 128)
Command2 | Click |
Command2 | Valid |
Command2 | When |

When the form closes and objects are released, additional events take place in the opposite order of the events listed for Action 1.

Object | Event
Form1 | Destroy
Command2 | Destroy
Command1 | Destroy
Text2 | Destroy
Text1 | Destroy
Form1 | Unload
DataEnvironment | AfterCloseTables
DataEnvironment | Destroy

See Also

Other Resources

Events in Visual FoxPro
How to: Track Event Sequences
Event Binding for Objects
Understanding the Event Model


How to: Track Event Sequences

Visual FoxPro 9.0
How to: Track Event Sequences
See Also

You can view the sequence in which events occur by turning on event tracking in the Visual FoxPro Debugger. You can determine the most efficient location to add code to events by using event tracking to see when the events associated with your forms and controls occur in relation to other events.

To turn on event tracking

  1. On the Tools menu, choose Debugger.

  2. On the Tools menu of the Visual FoxPro Debugger, choose Event Tracking.

  3. In the Event Tracking dialog box, select Turn event tracking on.

You can also set event tracking by using the SET EVENTTRACKING command. For more information, see SET EVENTTRACKING Command.

By default, the events that appear in the event tracking list appear in the Debug Output window as they occur. You can also choose to send output results to a file.

For more information, see How to: Use the Debugger, Debugger Window, and Event Tracking Dialog Box.

See Also

Other Resources

Event Sequence in Visual FoxPro
Events in Visual FoxPro
Considerations for Event Code
Understanding the Event Model


Considerations for Event Code

Visual FoxPro 9.0
Considerations for Event Code
See Also

When you add code to events, remember the following considerations:

  • The set of events for Visual FoxPro base classes is fixed and cannot be extended.

  • Every class recognizes a set of fixed default events, which includes a minimum of the Init, Destroy, and Error events.

  • Containers do not process events associated with the controls they contain.

  • If no event code is associated with a control, Visual FoxPro checks whether code exists for the event higher up in the class hierarchy for the control.

  • The sequence of events can affect the location where you add code.

The following sections contain more information about the last three considerations.

Events of Objects in Containers

Each object, even those in containers, receives its events independently. For example, suppose a form contains a command button. When the user clicks the command button, only the Click event for the command button is triggered, not the form's Click event. Therefore, if code exists for a form's Click event but no code exists for the command button's Click event, nothing happens when the user clicks the button.

This consideration also applies to grid controls. A grid contains columns, which contain headers and controls. When an event occurs for an inner object, only the object associated with event recognizes the event. The higher-level container does not recognize the event.

Note:
An exception to this rule exists. If event code exists for an option button group or a command button group, but no event code exists for the event of a particular option or button in the group, the group's event code is executed when the event for the particular option or button occurs.

Events of Controls from User-Defined Classes

When an event occurs for a control based on a user-defined class, Visual FoxPro checks the control for event code. If code exists in the control's event procedure, Visual FoxPro executes it. However, if no code exists in the control's event procedure, Visual FoxPro searches the next level up in the control's class hierarchy for code associated with that event. If Visual FoxPro finds code for the event, it executes that code and does not continue searching further up the hierarchy.

Event Sequence Considerations

When determining where to add event code, remember the following considerations:

  • The Init event of a form occurs after all Init events for controls on the form occur. Therefore, you can include code in the form's Init event to manipulate any of the controls on the form before the form displays.

  • If you want to execute code when the value of a list box, combo box, or check box changes, add the code to the control's InteractiveChange event instead of the Click event. The Click event might not occur or might be called even if the value does not change.

  • When you drag a control, other mouse events are suspended. For example, the MouseUp and MouseMove events do not occur during a drag operation.

  • The Valid and When events return a value with True (.T.) as the default. If code returns False (.F.) or 0 in the When event, the control cannot receive focus. If code returns False (.F.) or 0 in the Valid event, focus cannot leave the control.

See Also

Other Resources

Events in Visual FoxPro
Event Sequence in Visual FoxPro
Understanding the Event Model


Event Binding for Objects

Visual FoxPro 9.0
Event Binding for Objects

You can use event binding to attach an event, method, or property from a Visual FoxPro object or an event from a Component Object Model (COM) object, both of which can act as event sources, to a Visual FoxPro object. However, the approach for binding events from native and COM objects differs.

In This Section

Event Binding for Visual FoxPro Objects

Discusses binding events, methods, and properties from other native Visual FoxPro objects to Visual FoxPro objects.
Event Binding for COM Objects

Discusses binding events from COM objects to Visual FoxPro objects.

Related Sections

Understanding the Event Model

Provides an overview of events, how events occur, and how to track events.
Using Visual FoxPro

Provides an overview of Visual FoxPro features, describes concepts and productivity tools for developing, programming, and managing high-performance database applications and components.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.
Samples and Walkthroughs

Contains Visual FoxPro code samples and step-by-step walkthroughs that you can use for experimenting with and learning Visual FoxPro features.


Event Binding for Visual FoxPro Objects

Visual FoxPro 9.0
Event Binding for Visual FoxPro Objects
See Also

You can use event binding to trigger events, properties, or methods of native Visual FoxPro objects from other Visual FoxPro objects using the following functions:

  • BINDEVENT( )

    Associates an event from a native Visual FoxPro object with the method or event of another Visual FoxPro object.

  • UNBINDEVENTS( )

    Detaches events previously bound to Visual FoxPro objects.

  • RAISEEVENT( )

    Raises, or triggers, events for user-defined custom methods. You can also use RAISEEVENT( ) for native events and methods.

  • AEVENTS( )

    Retrieves information about the number of existing event bindings.

For a solution sample demonstrating binding events, raising events programmatically, unbinding events, and retrieving events, see Binding, Raising, Unbinding, and Retrieving Events Sample.

For information about binding events from Component Object Model (COM) objects, see Event Binding for COM Objects and EVENTHANDLER( ) Function.

Binding an Event

You can use the BINDEVENT( ) function to attach, or bind, an event, method, or property from one Visual FoxPro object, or event source, to the method or event of another Visual FoxPro object, or the event handler. The method that handles the event acts as a "delegate" for the event handler.

You can bind to any valid Visual FoxPro object method or event, including the Access and Assign methods. However, both the event source and event handler must be valid Visual FoxPro objects. You cannot use COM objects or bind to methods of objects in collections referenced by the _VFP system variable because these collections also pass through COM.

Note:
When you specify objects for event binding, make sure they are fully instantiated. Do not bind events, methods, or properties to an object in its Load or Init event because the object might not yet be fully instantiated and can cause the binding operation to fail.

You can use the same object as both the event source and event handler. The following example shows how Form1 acts as both source and handler:

Copy Code
BINDEVENT( Form1, "Resize", Form1, "myresize1" )

You can use different objects from the same class as the event source and handler. However, the event of an object that is used as both the event source and handler cannot be the same as the delegate method.

You can bind multiple event handlers to the same event source and event in an act referred to as "multi-casting." If multiple handlers exist for the same event, events occur in first in, first out (FIFO) order.

You can bind multiple delegate methods from an event handler to a particular event source and event. For example:

Copy Code
BINDEVENT( Form1, "Resize", oHandler, "myresize1" )
BINDEVENT( Form1, "Resize", oHandler, "myresize2" )

You cannot bind to an event with parameters that are passed by reference. Though calling BINDEVENT( ) succeeds, raising the event, for example, using RAISEEVENT( ), fails.

Visual FoxPro does not support event binding in designers such as the form and class designers, even though you can obtain object references using the ASELOBJ( ) or SYS(1270) functions.

For more information, see BINDEVENT( ) Function, ASELOBJ( ) Function, and SYS(1270) - Object Location.

Unbinding an Event

You can use the UNBINDEVENTS( ) function to detach events, methods, and properties that were bound using the BINDEVENT( ) function from native Visual FoxPro objects. UNBINDEVENTS( ) returns the number of events that it unbinds if it succeeds. You can specify a Visual FoxPro object event source or an object reference, which can be used as the event source or event handler.

For more information, see UNBINDEVENTS( ) Function.

Raising an Event

You can use the RAISEEVENT( ) function to raise, or trigger, events for custom and native methods. Directly calling methods does not make events occur, unless you set the appropriate flags when using BINDEVENT( ) to attach events to other objects. Therefore, you need RAISEEVENT( ) to trigger these events.

For more information, see RAISEEVENT( ) Function.

Retrieving Event Binding Information

You can use the AEVENTS( ) function to retrieve the number of Visual FoxPro events that are currently bound to Visual FoxPro objects. Visual FoxPro stores the information in an array. Depending on the parameters you pass, AEVENTS( ) returns either a single-element array containing an object reference to the event source or an array which represents each existing event binding as a row and contains information about the binding across five columns.

For more information, see AEVENTS( ) Function.

See Also

Other Resources

Event Binding for Objects
Understanding the Event Model


Event Binding for COM Objects

Visual FoxPro 9.0
Event Binding for COM Objects
See Also

You can bind events from Component Object Model (COM) objects to a Visual FoxPro object by using the EVENTHANDLER( ) function. For example, by binding an event from an ActiveX Data Object (ADO) recordset, you can run Visual FoxPro code when the record pointer moves around in the recordset. The EVENTHANDLER( ) function specifically handles binding events raised by COM objects and by the IConnectionPoint interface, which is part of COM. For more information, see EVENTHANDLER( ) Function.

However, Visual FoxPro does not support the raising events through the IConnectionPoint interface directly. In order to bind a COM event to a Visual FoxPro object, the object must implement the event interface of the COM object, an action referred to as tightly-coupled event handling, where both the event source and event sink objects are live when the event occurs. Event sinks are clients that bind to a connectable object because they receive events triggered by the connectable object.

Instead, COM+ Events, part of COM+ Services, provides the preferred strategy for handling events between COM components. COM+ Events sends and delivers event notifications between applications. Applications can send and receive notifications of events, such as the hiring of a new employee, a change in a stock price, or a drop in inventory level that requires restocking.

In the COM+ Events model, applications that send out event notifications act as event sources and are called publishers. Applications that receive event notifications are called subscribers. COM+ Events are often called loosely coupled events because publishers and subscribers do not possess any knowledge about each other and allow event subscribers to remain inactive until events occur. Instead, you define a set of events inside the scope of an event class, and this event class is installed in a COM+ application.

To use COM+ Events, you author an event class that implements one or more interfaces. Each interface defines a group of methods, which represents a set of events. You write subscriber components that implement these interfaces and respond to events when they occur. Finally, you write a publisher application to create objects from the event class and call various methods when the application is ready to fire events. The event service handles processing the method and delivering the events to every subscriber.

See Also

Other Resources

Event Binding for Visual FoxPro Objects
Event Binding for Objects
Understanding the Event Model


Accessing APIs

Visual FoxPro 9.0
Accessing APIs

If your application has requirements that cannot be met by the features already built into Visual FoxPro, you can extend the program by taking advantage of external libraries such as Microsoft ActiveX controls or dynamic-link libraries (DLLs). Using external libraries, you can add all kinds of objects to your application, from enhanced text boxes to calendars and other full-featured applications, and you can take advantage of the functionality offered by other programs (including Microsoft Windows) through their application programming interfaces (APIs).

In This Section

Extending Visual FoxPro with External Libraries

Explains that you can add Microsoft ActiveX controls (.ocx files) to your application easily, which provides you with new objects to use in forms, to subclass, and to manage the way you work with native Visual FoxPro controls. In addition, you can link to an external library, such as a DLL, and call the library's functions to use in your own programs.
Accessing the Visual FoxPro API

If an external library is not available to suit your needs, you can write your own Microsoft ActiveX control or Visual FoxPro-specific dynamic-link library (.fll file). By calling the functions available in the Visual FoxPro API, you can create controls or libraries that are tightly integrated with and optimized for use in Visual FoxPro.

Related Sections

Programming in Visual FoxPro

Visual FoxPro is a powerful interactive data management tool, but you also can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.
How to: Create Programs

Explains the two ways to create a Visual FoxPro program, which is a text file containing a series of commands.
Object-Oriented Programming

With object-oriented programming, you can create self-contained application components that respond to user actions and to the system and which can be easily maintained and reused.
Optimizing Applications

Describes ways to optimize the performance of your stable, running application by making your application smaller and faster.


Extending Visual FoxPro with External Libraries

Visual FoxPro 9.0
Extending Visual FoxPro with External Libraries

You can extend the native capabilities of Microsoft® Visual FoxPro® by taking advantage of the facilities of Microsoft® ActiveX® controls (.ocx files), ActiveX objects, and dynamic-link libraries (DLLs). External libraries make it possible for you to access not only the capabilities of other programs but also those of Microsoft® Windows®. For example, you can use an ActiveX control to read and update the Windows registry directly, or it can call system-level functions by linking to one of the DLLs in Windows.

In This Section

Accessing External Libraries

In most cases, Visual FoxPro provides all the tools you must have to complete your application. However, occasionally you might find that an application requires additional functionality not available in Visual FoxPro already.
How to: Access ActiveX Controls and Objects

You can use any Microsoft® ActiveX® control that is available on your computer. To use an ActiveX control, you add it to a form and then set its properties, write handlers for its events, or call its methods.
How to: Access Dynamic-Link Libraries

If the functionality you require is available in a DLL, you can link to the library and call its functions.
How to: Access a Visual FoxPro Library

Like a DLL, a Visual FoxPro library (.fll file) contains functions you can call as you would any other function.

Related Sections

Accessing APIs

If your application has requirements that cannot be met by the features already built into Visual FoxPro, you can extend the program by taking advantage of external libraries — Microsoft® ActiveX® controls or dynamic-link libraries (DLLs).
Accessing the Visual FoxPro API

If an external library is not available to suit your needs, you can write your own Microsoft® ActiveX® control or Visual FoxPro -specific dynamic-link library (.fll file). By calling the functions available in the API available in Visual FoxPro, you can create controls or libraries that are tightly integrated with and optimized for use in Visual FoxPro.


Accessing External Libraries

Visual FoxPro 9.0
Accessing External Libraries
See Also

In most cases, Visual FoxPro provides all the tools you need to complete your application. However, occasionally you might find that an application requires additional functionality not already available in Visual FoxPro. In those cases, you can reach outside Visual FoxPro and take advantage of the capabilities of external libraries.

Visual FoxPro makes it possible for you to access these kinds of external libraries:

  • ActiveX controls (.ocx files) and Objects. ActiveX controls and objects are programs that include objects designed to accomplish specific tasks. Most ActiveX controls and objects add new objects to Visual FoxPro — everything from a new type of text box to a calendar, calculator, or other complex object. Some ActiveX controls and objects also incorporate additional facilities, such as access to your e-mail system or to the communications ports on your computer. As a rule, after incorporating an ActiveX control or object into Visual FoxPro, you can use the objects in them as you would any Visual FoxPro base class.

  • Dynamic-link libraries (.dll files). A .dll file is a library of functions that you can call from Visual FoxPro programs as you would any user-defined function in Visual FoxPro. Many Windows programs — and Windows itself — make their functionality available using .dll files. For example, you can access the system color settings for Windows by linking to a system .dll file and calling functions in it.

  • Visual FoxPro external libraries (.fll files). An .fll file is like a .dll file, but uses special protocol for sharing data with Visual FoxPro, and often contains calls to internal Visual FoxPro functions. As a consequence, .fll files are specific to Visual FoxPro, unlike .dll files, which can be called from any Windows program. You can call the functions in an .fll as you would any user-defined function in Visual FoxPro.

Before you use any library, you must be familiar with the conventions used to access its controls or functions. For example, if you want to include an ActiveX control on a form, you must know what properties, events, and methods you can use to manage the control. For an ActiveX control, you can use a Visual FoxPro Class Browser to determine the properties, events, and methods you can use. Similarly, if you want to call a function in a .dll file, you must know the function name, the number and data types of the parameter it requires, and the data type of its return value. In general, you can obtain this type of information from the documentation that accompanies a library, whether in a book or a Help system. For information about system .dll files for Windows, you can refer to the Software Development Kit (SDK) appropriate to your version of Windows.

See Also

Other Resources

Extending Visual FoxPro with External Libraries
How to: Access ActiveX Controls and Objects
How to: Access Dynamic-Link Libraries
How to: Access a Visual FoxPro Library
Accessing the Visual FoxPro API


How to: Access ActiveX Controls and Objects

Visual FoxPro 9.0
How to: Access ActiveX Controls and Objects
See Also

You can use any ActiveX control that is available on your computer. To use an ActiveX control, you add it to a form, then set its properties, write handlers for its events, or call its methods. You can add an ActiveX control to a form using the Form Controls toolbar or the OLE Container Control, or by using code. For details about adding an ActiveX control in the Form Designer, see Sharing Information and Adding OLE.

You can create an ActiveX control in code in much the same way you would create any Visual FoxPro control. However, before creating the control you must determine the name of the control's class library, which is stored in the Windows registry. If you have no other way to determine the class library name, use the Form Designer to create the control (as described in the previous section), and then get the control's OLEClass property.

ActiveX objects can be created directly with CREATEOBJECT( ), and don't require an instance of a form.

To create an ActiveX control in code

  1. Call CREATEOBJECT( ) Function to create a form.

  2. Call the new form's AddObject Method to add the control, specifying olecontrol as the class. You must pass the control's class library name as the third parameter of the AddObject method.

For example, the following program creates a new form and adds a listview control to it:

Copy Code
oMyForm = CREATEOBJECT("form")
oMyForm.AddObject("oleListview","olecontrol", ;
   "MSComctlLib.ListViewCtrl")

After you've created the form and control, you can display the form by calling its Show method, and display the control by setting its Visible property to true:

Copy Code
oMyForm.oleListview.Visible = .T.
oMyForm.Show

Some ActiveX controls aren't designed primarily to be used interactively by a user. For example, a timer control doesn't support methods for user interaction. Even then, you can still create the control on a form because the control will usually make available a default visible component, such as an icon. Frequently you will not be able to change or resize the icon.

If you don't want your application to display the icon for non-interactive controls, you can hide the control by setting the Visible property of its OLE container control to false, or set its Left property to a negative value (such as –100) that moves it off the visible portion of the screen. Alternatively, you can place the control on a form that's never made visible (that is, for which the Show method is never called). In all cases, you can still call the control's methods as if the control were visible.

See Also

Other Resources

Accessing External Libraries
How to: Access Dynamic-Link Libraries
How to: Access a Visual FoxPro Library
Extending Visual FoxPro with External Libraries
Accessing the Visual FoxPro API
Sharing Information and Adding OLE
CREATEOBJECT( )


How to: Access Dynamic-Link Libraries

Visual FoxPro 9.0
How to: Access Dynamic-Link Libraries
See Also

If the functionality you require is available in a DLL, you can link to the library and call its functions. Before calling a DLL function, you must determine its calling protocol, including the name of the function, the number and data types of its parameters, and the data type of its return value.

In Visual FoxPro, you can only use DLLs that have been written for a 32-bit environment. However, if you require access to a 16-bit DLL, you can call it using functions available in Foxtools.fll. For details, see Help for Foxtools (Foxtools.chm).

To call a DLL function

  1. Register the DLL function using the DECLARE - DLL Command. Function names are case-sensitive.

    Note:
    If you specify WIN32API for the library name, Visual FoxPro searches for the 32-bit Windows DLL function in Kernel32.dll, Gdi32.dll, User32.dll, Mpr.dll, and Advapi32.dll.

  2. Call the function as you would any Visual FoxPro function.

For example, the following program registers the GetActiveWindow( ) function from the Windows USER system DLL, which displays the handle of the Visual FoxPro main window. The GetActiveWindow( ) takes no parameters, but returns a single integer:

Copy Code
DECLARE INTEGER GetActiveWindow IN win32api
MESSAGEBOX(STR( GetActiveWindow() ) )

The DLL containing the function you're registering must be available in the default directory, in the Windows or System directories, or along the DOS path.

If the function you want to call has the same name as another function already available in Visual FoxPro (either a native function or a DLL function previously declared), you can assign an alias to the function with the duplicate name, then call it using the alias.

Copy Code
DECLARE INTEGER GetActiveWindow IN win32api AS GetWinHndl
MESSAGEBOX(STR( GetWinHndl() ) )

Linked DLL functions remain available until you quit Visual FoxPro, so you only need to declare them once per session. If you don't intend to call the functions in a DLL again, you can issue the CLEAR DLLS command to remove it from memory and free resources.

Note:
Issuing CLEAR DLLS clears all declared DLL functions from memory.

See Also

Other Resources

Accessing External Libraries
Passing Parameters to Dynamic-Link Libraries
Extending Visual FoxPro with External Libraries


Passing Parameters to Dynamic-Link Libraries

Visual FoxPro 9.0
Passing Parameters to Dynamic-Link Libraries
See Also

When you register a DLL function, you must specify the number and data types of its parameters. By default, data is passed by value. You can force a parameter to be passed by reference by including an at sign (@) in front of the parameter.

In general, DLL functions follow the data type conventions used for C, which differ from those used in Visual FoxPro. For example, DLL functions do not support a data type for a date or for currency. If the data you're passing to a DLL function is in a data type not supported by the function, you must convert it to an appropriate type before passing it. For example, you can convert a date to a numeric Julian format using commands such as the following:

Copy Code
cDate = sys(11, date())
nDate = val( cDate )

Some DLL functions require more complex parameters, such as structures or arrays. If the function requires a pointer to a structure, you must determine the layout of the structure, then emulate it as a string in Visual FoxPro before passing it or receiving it from the DLL function. For example, the Windows system function GetSystemTime( ) expects a pointer to a structure consisting of eight words or unsigned 16-bit integers indicating the year, month, day, and so on. The structure is defined this way:

Copy Code
typedef struct _SYSTEMTIME {
   WORD wYear ;
   WORD wMonth ;
   WORD wDayOfWeek ;
   WORD wDay ;
   WORD wHour ;
   WORD wMinute ;
   WORD wSecond ;
   WORD wMilliseconds ;
} SYSTEMTIME

To pass data between Visual FoxPro and the GetSystemTime( ) function, you must create a 40-byte string buffer (consisting initially of spaces) and then pass the address of this string to the function for it to fill in. When the string is returned, you must parse it in 2-byte increments to extract the individual fields of the structure. The following fragment illustrates how you could extract three of the fields from the structure:

Copy Code
DECLARE INTEGER GetSystemTime IN win32api STRING @
cBuff=SPACE(40)
=GetSystemTime(@cBuff)

tYear = ALLTRIM(STR(ASC(SUBSTR(cBuff,2)) *  ;
   256 + ASC(SUBSTR(cBuff,1))))
tMonth = ALLTRIM(STR(ASC(SUBSTR(cBuff,4)) * ;
   256 + ASC(SUBSTR(cBuff,3))))
tDOW = ALLTRIM(STR(ASC(SUBSTR(cBuff,6)) * ;
   256 + ASC(SUBSTR(cBuff,5))))

For more information, you can examine the sample form Systime.scx in the Visual FoxPro ...\Samples\Solution\Winapi directory. For other examples of how to pass parameters to DLL functions, see the program Registry.prg in the Visual FoxPro ...\Samples\Classes directory.

If the data you're working with in Visual FoxPro is in an array, you must loop through the array and concatenate it into a single string representing a C-style array before passing it to the DLL function. If the Windows function expects 16-bit or 32-bit values, you must convert the values to their hex equivalents before concatenating them into string. When you pass the string containing the array data, Visual FoxPro passes the address of the string variable to the DLL, which can then manipulate it as an array. For an example of this, see the sample form Syscolor.scx in the Visual FoxPro ...\Samples\Solution\Winapi directory.

See Also

Other Resources

How to: Access Dynamic-Link Libraries
Extending Visual FoxPro with External Libraries


How to: Access a Visual FoxPro Library

Visual FoxPro 9.0
How to: Access a Visual FoxPro Library
See Also

A Visual FoxPro library (.fll file), like a .dll file, contains functions you can call as you would any other function. It is generally easier to pass parameters to and from functions in .fll files because they are created specifically for calling from Visual FoxPro.

To use a Visual FoxPro library, register the .fll file by specifying the name of the .fll file with the SET LIBRARY command, and then call the function normally. Unlike registering .dll functions, you do not need to register individual functions in the .fll file, nor do you need to specify information about the parameters or data types used by the function.

Note:
If you want to use an .fll library from an earlier version of Visual FoxPro, the library must be recompiled to work with Visual FoxPro version 5.0.

To call an .fll function

  1. Register the .fll library by issuing a SET LIBRARY command.

  2. Call the functions in the library as you would any function.

For example, the following code calls a function from the Foxtools.fll library in the Visual FoxPro installation directory to determine what type of drive the C: drive is:

Copy Code
SET LIBRARY TO "C:\Program Files\Microsoft Visual FoxPro 9.0\Foxtools.fll"
? DriveType("C:")

If you need to register more than one .fll file, include the ADDITIVE keyword in the SET LIBRARY command. If you don't, the previously registered .fll file is cleared and replaced by the one most recently registered.

If a function name conflicts with that of another function already available in Visual FoxPro, the last function defined takes precedence. If the function name in a linked library has the same name as that of an intrinsic Visual FoxPro function, the Visual FoxPro function takes precedence.

You only need to register functions in an .fll file once per session because they remain available until you quit Visual FoxPro. If you do not intend to call the functions in a .fll file again, remove the .fll file from memory and free resources by issuing the RELEASE LIBRARY, RELEASE ALL, or SET LIBRARY commands. For more information, see RELEASE LIBRARY Command and RELEASE Command.

See Also

Other Resources

How to: Access Dynamic-Link Libraries
How to: Access ActiveX Controls and Objects
Accessing External Libraries
Extending Visual FoxPro with External Libraries
Accessing the Visual FoxPro API


Accessing the Visual FoxPro API

Visual FoxPro 9.0
Accessing the Visual FoxPro API

If Visual FoxPro does not include the features you require for your application, you can extend the capabilities of Visual FoxPro by creating external libraries, for example, a Microsoft ActiveX control (.ocx) file or Visual FoxPro dynamic-link library (FLL) file.

Visual FoxPro includes the Library Construction Kit, which contains the files Pro_Ext.h, WinAPIMS.lib, and OcxAPI.lib so you can create ActiveX controls and FLLs.

Note:
The Library Construction Kit has a limit of 65,000 elements for arrays.

In This Section

Library or ActiveX Object Creation

Explains extending the capabilities of Visual FoxPro by creating external libraries that accomplish tasks required by your application.
How to: Create a Basic ActiveX Object

Describes how to create an ActiveX control.
Creating Visual FoxPro Dynamic-Link Libraries

Provides information about creating Visual FoxPro dynamic-link libraries.
FoxInfo Structure

Describes the FoxInfo structure used to communicate function names and parameter descriptions between Visual FoxPro and your FLL library.
FoxTable Structure

Describes the FoxTable structure which keeps track of all the FoxInfo structures you have for a given library.
How to: Add Visual FoxPro API Calls

Describes how to integrate your external library with Visual FoxPro using Visual FoxPro API routines.
Parameters in External Libraries

Describes how to pass arguments to parameters in external libraries.
How to: Return Values from ActiveX Controls and FLL Libraries

Describes how to return values from external libraries to Visual FoxPro.
Passing Parameters to Visual FoxPro API Functions

Explains how Visual FoxPro API routines require parameters of a particular Visual FoxPro data structure.
Access to Visual FoxPro Variables and Fields

Explains accessing Visual FoxPro variables or field values in your ActiveX control or FLL function.
Memory Management Using the Visual FoxPro API

Provides an overview about managing memory using the Visual FoxPro API.
How to: Manage Memory

Describes how the Visual FoxPro API provides direct access to the Visual FoxPro dynamic memory manager.
How to: Build and Debug Libraries and ActiveX Controls

Describes how to build and debug ActiveX controls and FLLs.

Related Sections

Accessing APIs

Discusses how you can extend an application by taking advantage of external libraries such as Microsoft ActiveX controls or Visual FoxPro dynamic-link libraries (FLLs).
Extending Visual FoxPro with External Libraries

Explains that you can add Microsoft ActiveX controls (.ocx files) to your application, which provides you with new objects to use in forms, to subclass, and to manage the way you work with native Visual FoxPro controls. In addition, you can link to an external library, such as a Visual FoxPro dynamic-link library (FLL) and call the library's functions to use in your own programs.
API Library Construction

Provides reference material about API Library routines, system events, and key codes.


Library or ActiveX Object Creation

Visual FoxPro 9.0
Library or ActiveX Object Creation
See Also

You can extend the capabilities of Visual FoxPro by creating programs in C or C++ that accomplish tasks required by your application. For example, if your application requires direct access to Windows facilities, you can write a C or C++ program that makes calls to the Windows API, and then returns information to Visual FoxPro.

You can create three types of programs to access the Visual FoxPro API:

  • An ActiveX control (.ocx file).

  • A COM object.

  • A DLL specific to Visual FoxPro. Because the DLL can be called only from Visual FoxPro, it is customary to use the file name extension .fll for the DLL file.

Each type of program has advantages. ActiveX controls have the following advantages:

  • Can be accessed using standard object-oriented techniques, such as setting its properties and invoking its methods.

  • Can be subclassed, and its methods overridden.

  • Is encapsulated, and can be called (instantiated) multiple times without complex environment management to preserve user states.

  • Features simpler parameter passing.

  • Can also be called from other Windows programs, if you program it with this in mind.

COM objects have the following advantages:

  • Can be accessed using standard object-oriented techniques, such as setting its properties and invoking its methods.

  • Its methods can be overridden.

  • Is encapsulated, and can be called (instantiated) multiple times without complex environment management to preserve user states.

  • Features simpler parameter passing.

  • Can also be called from other Windows programs, if you program it with this in mind.

Visual FoxPro dynamic-link (.fll) libraries might be more familiar to you if you have used previous versions of Visual FoxPro.

See Also

Other Resources

How to: Create a Basic ActiveX Object
Creating Visual FoxPro Dynamic-Link Libraries
Accessing the Visual FoxPro API


How to: Create a Basic ActiveX Object

Visual FoxPro 9.0
How to: Create a Basic ActiveX Object
See Also

You can create COM objects with the ActiveX Template Library provided with Microsoft® Visual C++.

You create Microsoft ActiveX controls specific to Visual FoxPro as you would any similar control. Most C++ compilers allow you to create skeletons of the control, and they can be created with the Microsoft Visual Basic Control Creation Edition.

The following sections describe the steps for creating an ActiveX control with Microsoft Visual C++ 6.0 for use in Visual FoxPro.

To create a project for the ActiveX control

  1. Start Microsoft Visual C++.

  2. From the File menu, choose New.

  3. In the New dialog box, choose Project Workspace.

  4. In the New Project Workspace dialog box, specify a project name.

  5. In the Type list, choose OLE ControlWizard.

  6. Choose Create, and then follow the steps in the wizard.

When the wizard is finished, you can build the ActiveX control immediately. However, you will also need to define properties and methods for the control.

To add properties and methods to the ActiveX control

  1. From the View menu, choose ClassWizard.

  2. Choose the OLEAutomation tab.

  3. Choose Add Method or Add Property.

  4. Fill in the name, parameter, and other information required by the element you are creating, and then choose OK.

  5. Choose Edit Code to display the editor, and then enter the code that defines the property or method you are creating.

For example, to create a Version property that returns the .ocx file version as an integer (such as 101), you create the property with a return type of long, and add code similar to the following:

Copy Code
#define VERSION 101

long CPyCtrl::GetVersion()
{
   // set the version number here
   return VERSION;
}

Because the version number is ordinarily read-only, you wouldn't create a SetVersion( ) function.

See Also

Other Resources

Library or ActiveX Object Creation
Creating Visual FoxPro Dynamic-Link Libraries
Accessing the Visual FoxPro API
Extending Visual FoxPro with External Libraries
How to: Add Visual FoxPro API Calls


Creating Visual FoxPro Dynamic-Link Libraries

Visual FoxPro 9.0
Creating Visual FoxPro Dynamic-Link Libraries
See Also

A Visual FoxPro dynamic-link library (FLL) is essentially a DLL that contains calls to the Visual FoxPro API. You can create the basic DLL structure in your development environment and then add the Visual FoxPro functions you want to call. The following sections describe example templates for creating FLL templates in C and C++.

Setting Up a Library Template

Each Visual FoxPro FLL library has the same basic structure. You can use a template for the structure so that you need only to add code for your specific library routine.

There are five elements in a Visual FoxPro library template:

  • #include statement.

  • Function definition.

    The function definition has a void return value and is passed the ParamBlk *parm parameter. For more information about the ParamBlk parameter, see Parameters in External Libraries.

  • Function code.

  • FoxInfo structure.

    The functions in the FLL interact with Visual FoxPro through the FoxInfo structure. Visual FoxPro uses FoxInfo to determine the function name and the number and type of parameters.

  • FoxTable structure.

    The FoxTable structure is a linked list that keeps track of the FoxInfo structures.

For more information about FoxInfo and FoxTable struct definitions, see the Pro_ext.h file.

You also need the following files:

  • The Pro_ext.h header file.

    You can print this file to see the function declarations, typedefs, and structs used in the Visual FoxPro API.

  • The Winapims.lib file.

Both of these files are located in the Microsoft Visual FoxPro ..\Samples\API directory.

Sample Templates

For C routines, you can use the following template:

Copy Code
#include <Pro_ext.h>

void Internal_Name(ParamBlk *parm)
{
// Function code goes here.
}

FoxInfo myFoxInfo[] = {
   {"FUNC_NAME", (FPFI) Internal_Name, 0, ""},
};

FoxTable _FoxTable = {
   (FoxTable *)0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

For C++ routines, you need to declare the FoxTable structure as external in the following template:

Copy Code
#include <Pro_ext.h>

void Internal_Name(ParamBlk  *parm)
{
// Function code goes here.
}

   FoxInfo myFoxInfo[] = {
      {"FUNC_NAME", (FPFI) Internal_Name, 0, ""},
   };

extern "C" {
   FoxTable _FoxTable = {
      (FoxTable *)0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
   };
}

See Also

Other Resources

FoxInfo Structure
FoxTable Structure
API Library Construction
How to: Add Visual FoxPro API Calls
Accessing the Visual FoxPro API


FoxInfo Structure

Visual FoxPro 9.0
FoxInfo Structure
See Also

The FoxInfo structure is used to communicate function names and parameter descriptions between Visual FoxPro and your FLL library.

The following code illustrates the syntax for a FoxInfo structure:

Copy Code
FoxInfo arrayname[ ] = {
   {funcName1, FPFI function1, parmCount1, parmTypes1}
   {funcName2, FPFI function2, parmCount2, parmTypes2}
      . . .
   {funcNameN, FPFI functionN, parmCountN, parmTypesN}
};

The following table describes the parameters in this structure.

Parameter Description

arrayname

Specifies a variable of type FoxInfo.

Note:
You can include several FoxInfo structure lines in this array.

funcName

Contains the name that the Visual FoxPro user calls to invoke your function.

function

Specifies the address of your C language routine. This is the exact (case-sensitive) name you use to define your function.

parmCount

Specifies the number of parameters described in the parmTypes string or one of the following flag values. The following list describes possible flag values:

  • INTERNAL

    Specifies that the function cannot be called directly from Visual FoxPro.

  • CALLONLOAD

    Specifies that the routine is to be called when the library is loaded. CALLONLOAD can't call any routine that returns results to Visual FoxPro.

  • CALLONUNLOAD

    Specifies that the routine is to be called when the library is unloaded or when the Visual FoxPro QUIT command is issued. CALLONUNLOAD cannot call any routine that returns results to Visual FoxPro.

parmTypes

Describes the data type of each parameter.

The following lists the valid values for parmTypes.

  • " "

    No parameter.

  • "?"

    Specifies that any type can be passed. In the body of the function, you'll need to check the type of the passed parameter.

  • "C"

    Specifies a Character type parameter.

  • "D"

    Specifies a Date type parameter.

  • "I"

    Specifies an Integer type parameter.

  • "L"

    Specifies a Logical type parameter.

  • "N"

    Specifies a Numeric type parameter.

  • "R"

    Reference.

  • "T"

    Specifies a DateTime type parameter.

  • "Y"

    Specifies a Currency type parameter

  • "O"

    Specifies an Object type parameter

Note:
Include a type value for each parameter passed to the library. To indicate that a parameter is optional, precede it with a period (.). Only trailing parameters can be omitted.

For example, suppose you create a function that accepts a character and a numeric parameter. When you specify parmType, use "CN".

The following example FoxInfo structure defines a library with one function, which is internally named dates and externally accessed as DATES. The structure accepts one Character type parameter:

Copy Code
FoxInfo myFoxInfo[] = {
   { "DATES", (FPFI) dates, 1, "C" }
};

After you compile your FLL library with this FoxInfo structure and load it in Visual FoxPro using the SET LIBRARY command, you can call this function in Visual FoxPro with the following line of code:

Copy Code
=DATES("01/01/95")

See Also

Other Resources

Creating Visual FoxPro Dynamic-Link Libraries
API Library Construction
How to: Add Visual FoxPro API Calls
Accessing the Visual FoxPro API


FoxTable Structure

Visual FoxPro 9.0
FoxTable Structure
See Also

The FoxTable structure is a linked list that keeps track of all the FoxInfo structures you have for a given library.

The following code illustrates the syntax for the FoxTable structure:

Copy Code
FoxTable _FoxTable = {nextLibrary, infoCount,infoPtr};

The following table describes the parameters in this structure.

Parameter | Description
nextLibrary | Specifies a pointer used internally by Visual FoxPro and should be initialized to 0.
infoCount | Specifies the number of Visual FoxPro external routines defined in this library.
infoPtr | Specifies the address of the first element of an array of FoxInfo structures. This name must match the array name listed in the FoxInfo statement.

The following example illustrates a FoxTable statement. If your FoxInfo array name is myFoxInfo, you'll never need to change this statement:

Copy Code
FoxTable _FoxTable = {
   (FoxTable  *) 0,
   sizeof( myFoxInfo) / sizeof( FoxInfo ),
   myFoxInfo
};

Visual FoxPro captures General Protection Faults (GPFs) in ActiveX controls placed on a form, or COM objects instantiated from within Visual FoxPro. A GPF in an ActiveX control or COM object is now treated as a trappable Visual FoxPro error (Error 1440 - OLE object might be corrupt).

See Also

Other Resources

Creating Visual FoxPro Dynamic-Link Libraries
API Library Construction
How to: Add Visual FoxPro API Calls
Accessing the Visual FoxPro API


How to: Add Visual FoxPro API Calls

Visual FoxPro 9.0
How to: Add Visual FoxPro API Calls
See Also

To integrate your program with Visual FoxPro, you can call Visual FoxPro API routines. These API routines are functions you can call from any C or C++ program, including an .ocx or .fll file, that give you access to variables, manage database operations, and accomplish many other Visual FoxPro-specific tasks.

The following table lists the general categories of API calls available in Visual FoxPro. For details about individual API functions, see API Library Routines A-Z or API Library Routines by Category.

To use the Visual FoxPro API routines, you must include the file Pro_ext.h, available in the Visual FoxPro API directory. This file includes the prototypes for the functions and structures that allow you to share information with Visual FoxPro.

If you're writing an ActiveX control, you must also add calls to initialize and clear the API.

To add Visual FoxPro API routines to your ActiveX object

  1. Use #INCLUDE to include the Pro_ext.h file along with any other required header files.

  2. In the Constructor (Init method) of the control, call _OCXAPI( ) to initialize the interface to Visual FoxPro using this code:

    Copy Code
    _OCXAPI(AfxGetInstanceHandle(),DLL_PROCESS_ATTACH);

  3. Include calls to the Visual FoxPro API as required in your object.

  4. In the Destructor (Destroy method) for the object, call _OCXAPI( ) again to release the process created in the Constructor, using this code:

    Copy Code
    _OCXAPI(AfxGetInstanceHandle(),DLL_PROCESS_DETACH);

For an example of an .fll library that includes calls to the Visual FoxPro API, see the sample programs in \Api\Samples directory that have the extension C: EVENT.C, HELLO.C, and so on.

If you use Visual FoxPro API calls in your ActiveX control, COM object, or .fll library, the code containing the calls is incompatible with other applications. You might therefore want to build one or more tests into the program to determine whether the object is being called from Visual FoxPro.

For example, if you're creating an ActiveX control using the Microsoft Foundation Classes, you can change the control's constructor code to include a test and then alert the user if the control has been called from a program other than Visual FoxPro:

Copy Code
if (!_OCXAPI(AfxGetInstanceHandle(),DLL_PROCESS_ATTACH))
{
   ::MessageBox(0,"This OCX can only be hosted by Visual Foxpro","",0);
      //Here you can do whatever you want when the host isn't VFP:
      // you might want to reject loading or you
      // might want to set a property
      // saying that the host isn't VFP and the control will use other
      // means to achieve it's purpose.
}

If you're creating an ActiveX control using the Microsoft ActiveX Template Library, use the following code:

Copy Code
if (!_OCXAPI(_Module.GetModuleInstance(),DLL_PROCESS_ATTACH))
{
   ::MessageBox(0,"This OCX can only be hosted by Visual Foxpro","",0);
      //Here you can do whatever you want when the host isn't VFP:
      // you might want to reject loading or you
      // might want to set a property
      // saying that the host isn't VFP and the control will use other
      // means to achieve it's purpose.
}

In this example, the control doesn't exit, and will continue running after the user has acknowledged the message. The strategy you choose depends on how you anticipate the control will be used. For example, if you detect that the control is being used outside of Visual FoxPro, you can set a flag that you test at each point in the control where you call the Visual FoxPro API. If the flag indicates that the control is outside Visual FoxPro, you can branch around the API call to an alternative means of accomplishing the same task.

See Also

Other Resources

Creating Visual FoxPro Dynamic-Link Libraries
Accessing the Visual FoxPro API
Parameters in External Libraries
How to: Return Values from ActiveX Controls and FLL Libraries
Extending Visual FoxPro with External Libraries
API Library Construction


Parameters in External Libraries

Visual FoxPro 9.0
Parameters in External Libraries
See Also

You can pass arguments to parameters when Visual FoxPro calls an ActiveX control, COM object, or Visual FoxPro dynamic-link library (FLL). For example, an ActiveX control might accept arguments when calling one of its methods. Similarly, a Visual FoxPro program might call a function in your FLL library and pass arguments to it.

Visual FoxPro can pass arguments to parameters in an external library by value or by reference. By default, the setting of the SET UDFPARMS command is respected. However, other variables, such as arrays or fields, and expressions are passed by value. For information about how to change the default way of passing arguments, see Passing Data to Parameters.

Because ActiveX controls and COM objects are Windows-standard programs, no special mechanism is required to pass arguments from Visual FoxPro to parameters in an ActiveX control or COM object. You can write library code as if it were receiving arguments from any C or C++ program.

However, functions in an FLL library use the FoxInfo structure to receive data from Visual FoxPro. The FoxInfo structure lists library functions and the number and type of parameters they expect. For example, the following FoxInfo structure belongs to a library with one function, internally called dates, that accepts one Character parameter:

Copy Code
FoxInfo myFoxInfo[] = {
   { "DATES", (FPFI) dates, 1, "C" }
};

Functions you define in external libraries actually receive only one parameter, a pointer to the parameter block. This parameter block, defined in the ParamBlk structure, stores all the information about the parameters that were passed from the Visual FoxPro function call. The following code illustrates the format that your function declaration should follow:

Copy Code
void function_name(ParamBlk *parm)

For example, the function definition for dates is:

Copy Code
void dates(ParamBlk *parm)

The ParamBlk structure consists of an integer that represents the number of parameters, immediately followed by an array of parameter unions. The structure definition is included in Pro_ext.h:

Copy Code
/* A parameter list to a library function.      */
typedef struct {
   short int pCount;      /* number of parameters passed */
   Parameter p[1];         /* pCount parameters */
} ParamBlk;

The Parameter typedef included in the ParamBlk structure is a union of a Value structure and a Locator structure. Call by value is handled by a Value structure; call by reference is handled by a Locator structure. You use these structures to access the parameters passed to your function when the function is called in Visual FoxPro.

The following information is extracted from the file Pro_ext.h and shows the definition of the Parameter type:

Copy Code
/* A parameter to a library function.         */
typedef union {
   Value val;
   Locator loc;
} Parameter;

Value Structure Definition

If a parameter is passed to your function by value, use the Value structure to access it. The following Value structure definition is extracted from the Pro_ext.h file:

Copy Code
// An expression's value.
Typedef struct {
   char         ev_type;
   char         ev_padding;
   short         ev_width;
   unsigned      ev_length;
   long         ev_long;
   double         ev_real;
   CCY         ev_currency;
   MHANDLE      ev_handle;
   ULONG         ev_object;
} Value;

Value Structure Fields

The following table is a guide to the values you can pass and receive in the Value structure for different types of data. Only the structure fields listed for a data type are used for that data type.

Contents of Value structure for different data types

Data type | Structure field | Value
Character | ev_type | 'C'
 | ev_length | string length
 | ev_handle | MHANDLE to string
Numeric | ev_type | 'N'
 | ev_width | Display width
 | ev_length | Decimal places
 | ev_real | Double precision
Integer | ev_type | 'I'
 | ev_width | Display width
 | ev_long | Long integer
Date | ev_type | 'D'
 | ev_real | Date1
Date Time | ev_type | 'T'
 | ev_real | Date + (seconds/86400.0)
Currency | ev_type | 'Y'
 | ev_width | Display width
 | ev_currency | Currency value2
Logical | ev_type | 'L'
 | ev_length | 0 or 1
Memo | ev_type | 'M'
 | ev_wdith | FCHAN
 | ev_long | Length of memo field
 | ev_real | Offset of memo field
General | ev_type | 'G'
 | ev_wdith | FCHAN
 | ev_long | Length of general field
 | ev_real | Offset of general field
Object | ev_type | 'O'
 | ev_object | Object identifier
Null | ev_type | '0' (zero)
 | ev_long | Data type

1. The date is represented as a double-precision floating-point Julian day number calculated using Algorithm 199 from Collected Algorithms of the ACM. 2. The currency value is a long integer, with an implied decimal point in front of the last four digits.

Note:
ev_length is the only true indicator of a string's length. The string can't have a null terminator because the string can contain embedded null characters.

Locator Structure Definition

Use the Locator structure to manipulate parameters passed by reference. The following Locator structure definition is extracted from the Pro_ext.h file:

Copy Code
typedef struct {
  char  l_type;
  short l_where, /* Database number or -1 for memory */
  l_NTI,      /* Variable name table offset*/
  l_offset,  /* Index into database*/
  l_subs,  /* # subscripts specified 0 <= x <= 2 */
  l_sub1, l_sub2; /* subscript integral values */
} Locator;

Locator Structure Fields

The following table is a guide to the fields in the Locator structure.

Locator field | Field use
l_type | 'R'
l_where | The number of the table containing this field, or – 1 for a variable.
l_NTI | Name Table Index. Visual FoxPro internal use.
l_offset | Field number within table. Visual FoxPro internal use.
l_subs | For variables only, the number of subscripts (0 – 2).
l_sub1 | For variables only, the first subscript if l_subs is not 0.
l_sub2 | For variables only, the second subscript if l_subs is 2.
Note:
It's good programming practice to check for the parameter type in ev_type to help determine which fields to access from the Value structure.

An Example of Accessing Parameters in an FLL Library

The following example uses _StrCpy( ) to return a Character type to Visual FoxPro that's the concatenation of its two Character parameters. Notice that although the handle of each parameter's Value structure is used as working memory to perform the concatenation, changes to this memory allocation don't affect the Visual FoxPro argument that was passed by value.

Copy Code
#include <Pro_ext.h>

Example(ParamBlk *parm)
{
// make the paramBlk structure easier
// to manage by using #define shortcuts
#define p0 (parm->p[0].val)
#define p1 (parm->p[1].val)

// make sure there is enough memory
if (!_SetHandSize(p0.ev_handle, p0.ev_length + p1.ev_length))
   _Error(182); // "Insufficient memory"

// lock the handles
_HLock(p0.ev_handle);
_HLock(p1.ev_handle);

// convert handles to pointers and make sure the
// strings are null-terminated
((char *)_HandToPtr(p0.ev_handle))[p0.ev_length] = '\0';
((char *)_HandToPtr(p1.ev_handle))[p1.ev_length] = '\0';

// concatenate strings using the API function _StrCpy
_StrCpy((char *)_HandToPtr(p0.ev_handle) + p0.ev_length,
_HandToPtr(p1.ev_handle));

// return the concatenated string to Visual FoxPro
_RetChar(_HandToPtr(p0.ev_handle));

// unlock the handles
_HUnLock(p0.ev_handle);
_HUnLock(p1.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"STRCAT", Example, 2, "CC"},
};

FoxTable _FoxTable = {
   (FoxTable *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

How to: Add Visual FoxPro API Calls
How to: Return Values from ActiveX Controls and FLL Libraries
Accessing the Visual FoxPro API
Passing Parameters to Visual FoxPro API Functions
Extending Visual FoxPro with External Libraries
API Library Construction


How to: Return Values from ActiveX Controls and FLL Libraries

Visual FoxPro 9.0
How to: Return Values from ActiveX Controls and FLL Libraries
See Also

You can return values from ActiveX controls or Visual FoxPro dynamic-link libraries (FLL) to Visual FoxPro.

To return values from ActiveX controls to Visual FoxPro

  • Use the RETURN statement in the control and pass a single value.

The following example returns uses a RETURN statement to return the version number stored in VERSION:

Copy Code
#define VERSION 101

// other code here

long CPyCtrl::GetVersion()
{
   // set the version number here in variable fVersion
   return VERSION;
}

Returning Values from FLL Libraries

When you want to return values from FLL libraries, use API functions, not native C or C++ commands.

Note:
When return values from an ActiveX control (.ocx) file, do not use the API functions for returning values from FLL libraries. Instead, use the RETURN statement.

To return values from an FLL library

  • Use the API functions listed in the following table.

The following API functions should be used only for FLL libraries.

Function | Description
_RetChar(char *string) | Sets the function return value to a null-terminated string.
_RetCurrency(CCY cval, int width) | Sets the function return value to a currency value.
_RetDateStr(char *string) | Sets the function return value to a date. The date is specified in mm/dd/yy[yy] format.
_RetDateTimeStr(char *string) | Sets the function return value to a date and time specified in mm/dd/yy[yy] hh:mm:ss format.
_RetFloat(double flt, int width, int dec) | Sets the function return value to a float value.
_RetInt(long ival, int width) | Sets the function return value to a numeric value.
_RetLogical(int flag) | Sets the function return value to a logical value. Zero is considered FALSE. Any non-zero value is considered TRUE.
_RetVal(Value *val) | Passes a complete Visual FoxPro Value structure; any Visual FoxPro data type except for memo can be returned. You must call _RetVal( ) to return a string that contains embedded null characters or to return a .NULL. value.
Note:
To return the value of an object data type, use the _RetVal() function, filling in the ev_object field in the Value structure.

The following example, Sum, accepts a reference to a numeric field in a table and uses _RetFloat to return the sum of the values in the field:

Copy Code
#include <Pro_ext.h>

Sum(ParamBlk *parm)
{
// declare variables
double tot = 0, rec_cnt;
int i = 0, workarea = -1; // -1 is current workarea
Value val;

// GO TOP
_DBRewind(workarea);

// Get RECCOUNT( )
rec_cnt = _DBRecCount(workarea);

// Loop through table
for(i = 0; i < rec_cnt; i++)
{
   //Place value of the field into the Value structure
   _Load(&parm->p[0].loc, &val);

   // add the value to the cumulative total
   tot += val.ev_real;

   // SKIP 1 in the workarea
   _DBSkip(workarea, 1);
}

// Return the sum value to Visual FoxPro
_RetFloat(tot, 10, 4);
}
// The Sum function receives one Reference parameter
FoxInfo myFoxInfo[] = {
   {"SUM", Sum, 1,"R"}
};
FoxTable _FoxTable = {
   (FoxTable *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

Assuming there's a numeric field named amount in the currently open table, the following line of code in a Visual FoxPro program calls the function:

Copy Code
? SUM(@amount)

See Also

Other Resources

Parameters in External Libraries
Passing Parameters to Visual FoxPro API Functions
Accessing the Visual FoxPro API
Extending Visual FoxPro with External Libraries
Access to Visual FoxPro Variables and Fields
API Library Construction


Passing Parameters to Visual FoxPro API Functions

Visual FoxPro 9.0
Passing Parameters to Visual FoxPro API Functions
See Also

Often the Visual FoxPro API routines will require parameters of a particular Visual FoxPro data structure. The following sections provide a list of Visual FoxPro data types and additional data structures. For the actual type definitions and structure definitions, refer to the Pro_ext.h file.

Visual FoxPro API Data Types

The following data types are used in Visual FoxPro API routines.

Data type | Description
EDLINE | The number of a line in an open file in an editing window. The first line is 1.
EDPOS | The offset position of a character in an open file in an editing window. The offset position of the first character in the file or memo field is 0.
FCHAN | File channel. Every file opened by Visual FoxPro, or through the API by using _FCreate( ) and _FOpen( ), is assigned an FCHAN.
FPFI | A 32-bit pointer to a function returning an integer.
ITEMID | A unique identifier assigned to a single command on a menu.
MENUID | A unique identifier assigned to a menu.
MHANDLE | A unique identifier given to every block of memory allocated by Visual FoxPro, or allocated through the API using _AllocHand( ). It can be de-referenced to its pointer using _HandToPtr( ).
NTI | Name table index. Every variable and table field's name has an entry in this table.
WHANDLE | Window handle. A unique identifier assigned to every window opened by Visual FoxPro, or opened through the API using _WOpen( ).
Note:
Because FAR pointers are not appropriate for 32-bit compilers, #define statements in Pro_ext.h redefine FAR, _far, and __far as null values.

Visual FoxPro API Data Structures

The primary data structures used in the Visual FoxPro API library are listed in the following table.

Structure | Description
EventRec | A structure used to describe what the system is doing at a given time.
FoxInfo | Used in FLL libraries for communicating between Visual FoxPro and your program; not used in .ocx files.
FoxTable | Used in FLL libraries for communicating between Visual FoxPro and your program; not used in .ocx files.
Locator | A structure used to access parameter values (FLL) or Visual FoxPro variables or fields (FLL and ocx).
ParamBlk | Used in FLL libraries for communicating between Visual FoxPro and your program; not used in .ocx files.
Parameter | Used in FLL libraries for communicating between Visual FoxPro and your program; not used in .ocx files.
Point | A structure that defines the horizontal and vertical coordinates of a single point on the screen. Coordinates are specified in rows and columns.
Rect | A structure that defines the coordinates of a rectangle on the screen. The upper-left corner of the rectangle is defined by (top,left) and the lower-right corner is defined by (bottom-1,right-1). Coordinates are specified in rows and columns.
Value | A structure used to access parameter values (FLL) or Visual FoxPro variables or fields (FLL and OCX).

See Also

Other Resources

How to: Return Values from ActiveX Controls and FLL Libraries
Access to Visual FoxPro Variables and Fields
Accessing the Visual FoxPro API
Extending Visual FoxPro with External Libraries
How to: Manage Memory
API Library Construction


Access to Visual FoxPro Variables and Fields

Visual FoxPro 9.0
Access to Visual FoxPro Variables and Fields
See Also

You can access Visual FoxPro variables or field values in your ActiveX control or FLL function, either to read them or to set them. In addition, you can create new variables that can be accessed from within Visual FoxPro.

Variables and fields are made available in Visual FoxPro in a name table, which is an array containing the names of all currently defined variables and fields. You can access an individual element in the array using a name table index (NTI). A special API function, _NameTableIndex( ), returns the index of an existing variable or field based on a name that you provide. After you've determined the NTI for a given variable, you can read it using the _Load( ) API function or set it using the _Store( ) API function. To create a new variable, you can call the API function _NewVar( ).

To access Visual FoxPro variables or fields, you use the Value and Locator structures defined in Pro_ext.h. If you're creating an FLL library, you can use the same technique you used to access parameters passed to your functions. For details about the Value and Locator structures, see Parameters in External Libraries.

The following example illustrates how you can use the Value and Locator structures in an ActiveX control to access Visual FoxPro variables.

Copy Code
long CFoxtlibCtrl::TLGetTypeAttr(long pTypeInfo, LPCTSTR szArrName)
{
  int nResult = 1;
  TYPEATTR *lpTypeAttr;
  Locator loc;
  Value val;
  OLECHAR szGuid[128];
  char *szBuff;
__try {
   if (_FindVar(_NameTableIndex(( char *)szArrName),-1,&loc)) {
      ((ITypeInfo *)pTypeInfo)->GetTypeAttr(&lpTypeAttr);
      if (_ALen(loc.l_NTI, AL_ELEMENTS) < 16) {
         _Error(631); //Array argument not of proper size.
      }

      //1 = Guid
      StringFromGUID2(lpTypeAttr->guid, (LPOLESTR )&szGuid,sizeof(szGuid));
      OLEOleToAnsiString(szGuid,&szBuff);
      val.ev_type = 'C';
      val.ev_length = strlen(szBuff);
      val.ev_handle = _AllocHand(val.ev_length);
      _HLock(val.ev_handle);
      _MemMove((char *) _HandToPtr( val.ev_handle ), szBuff, val.ev_length);
      OLEFreeString((void **)&szBuff);
      _HUnLock(val.ev_handle);
      loc.l_sub1 = 1;
      _Store(&loc,&val);
      _FreeHand(val.ev_handle);

      //2 = LCID
      loc.l_sub1 = 2;
      val.ev_type = 'I';
      val.ev_long = lpTypeAttr->lcid;
      _Store(&loc,&val);

      // code for values 3 - 16 here
      ((ITypeInfo *)pTypeInfo) -> ReleaseTypeAttr(lpTypeAttr);
      }
   } __except  (EXCEPTION_EXECUTE_HANDLER) {
      nResult = 0;
   }
return nResult;

See Also

Other Resources

Passing Parameters to Visual FoxPro API Functions
How to: Manage Memory
Accessing the Visual FoxPro API
Extending Visual FoxPro with External Libraries
How to: Build and Debug Libraries and ActiveX Controls
_NameTableIndex( ) API Library Routine


Memory Management Using the Visual FoxPro API

Visual FoxPro 9.0
Memory Management Using the Visual FoxPro API
See Also

The Visual FoxPro API provides direct access to the Visual FoxPro dynamic memory manager. API routines that request memory allocations return memory handles, which identify memory. The Visual FoxPro segment-loading architecture uses handles instead of pointers so it can manage memory more efficiently.

A memory handle is essentially an index in an array of pointers. The pointers point to blocks of memory that Visual FoxPro knows about. Nearly all references to memory in the API are made through handles instead of the more conventional C pointers.

Understanding Stacks

The control or library you create does not have its own memory stack. Instead, it uses the memory stack of its calling program, or in this case, the Visual FoxPro stack. However, you cannot control the size of the Visual FoxPro stack or affect the amount of stack space available to an ActiveX control or FLL.

Under normal circumstances, this distinction isn't important. The Visual FoxPro stack is generally large enough to hold the automatic variables you might need to allocate in a control or library. If you run out of stack space, you can always allocate additional memory on the heap dynamically.

Rules for Using Handles

The following rules apply to allocating and freeing memory handles:

  • Users must free all handles they allocate, including handles allocated by functions such as _Load().

  • _Load() only creates a handle when the variable you're loading is a character string (that is, ev_type = 'C'). All the other data types store their values in the Value structure itself, while loading a character string puts an MHANDLE in the ev_handle of the Value structure.

  • In an FLL library, Visual FoxPro assumes responsibility for freeing all handles returned with _RetVal( ). Users must not free these handles, even if they allocate them.

  • Users must not free handles passed to them in their ParamBlk.

    Caution:
    When you write an external routine that calls functions, make sure to follow all rules and check the return results. A stray pointer or handle reference could damage the Visual FoxPro internal data structures, causing an immediate abnormal termination or delayed problems, which could result in data loss.

See Also

Other Resources

How to: Manage Memory
Accessing the Visual FoxPro API


How to: Manage Memory

Visual FoxPro 9.0
How to: Manage Memory
See Also

You can allocate and manage memory using the Visual FoxPro API.

Note:
The techniques described apply to both ActiveX controls and FLL libraries.

To allocate and use memory

  1. Allocate a handle with _AllocHand( ).

  2. Lock the handle with _HLock( ).

  3. Convert the handle into a pointer with _HandToPtr( ).

  4. Reference the memory by using the pointer.

  5. Unlock the handle with _HUnLock( ).

    Note:
    To avoid memo file corruption, don't write to a memo file before calling _AllocMemo( ).

In order to address the allocated memory, your API routines must convert the handle to a pointer by calling the _HandToPtr( ) routine. Even if the Visual FoxPro memory manager needs to reorganize memory to obtain more contiguous memory for subsequent memory requests, the handle remains the same. Routines that grow, shrink, free, and lock memory allocations are also provided.

When you're creating external routines, try to minimize memory use. If you create an external routine that dynamically allocates memory, try to use the least amount of memory possible. Be especially careful about locking large memory allocations for long periods of time. Remember to unlock memory handles with _HUnLock( ) when they no longer need to be locked, because the performance of Visual FoxPro can be adversely affected by locked memory handles.

Caution:
Excessive use of dynamic memory deprives Visual FoxPro of memory for buffers, windows, menus, and so on, and degrades performance, because the memory given to fill API requests is managed by the Visual FoxPro memory manager. Allocating large handles and retaining them could cause Visual FoxPro to run out of memory and terminate abnormally. The Visual FoxPro environment has no memory protection. The external API routine cannot provide all the validation that's inherent in a standard Visual FoxPro program. If you corrupt memory, you receive messages such as "Transgressed handle," "Internal consistency error," and "Transgressed node during compaction."

The following function from an FLL library illustrates memory allocation. The example uses _RetDateStr( ) to return a Visual FoxPro Date type (assuming that the Character parameter is a proper date):

Copy Code
#include <Pro_ext.h>

void dates(ParamBlk  *parm)
{
   MHANDLE mh;
   char *instring;

   if ((mh = _AllocHand(parm->p[0].val.ev_length + 1)) == 0) {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   instring = _HandToPtr(parm->p[0].val.ev_handle);
   instring[parm->p[0].val.ev_length] = '\0';
   _RetDateStr(instring);
   _HUnLock(parm->p[0].val.ev_handle);
}
FoxInfo myFoxInfo[] = {
   {"DATES", (FPFI) dates, 1, "C"}
};
FoxTable _FoxTable = {
   (FoxTable *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

Memory Management Using the Visual FoxPro API
Accessing the Visual FoxPro API


How to: Build and Debug Libraries and ActiveX Controls

Visual FoxPro 9.0
How to: Build and Debug Libraries and ActiveX Controls
See Also

After creating a project in Visual Studio, you can build and debug it. The following procedures are for Visual Studio 6.0. For the most recent information, read the documentation for version you are using.

Building the Project

Before building your project, you need to establish the project settings. Some of the settings you make depend on whether you want to create a debug or release version of the control or library. As a rule, create debug versions of the program until you are satisfied that it works correctly, then create a release version.

To specify a debug or release version

  1. On the Build menu, choose Set Default Configuration.

  2. Choose whether you're creating a debug or release version of the control.

  3. Choose OK.

To establish project settings

  1. From the Build menu, choose Settings.

  2. Under Settings For, choose whether you're creating a debug or release version of the program.

  3. Click the C/C++ tab and then make these settings:

    • In the Category list, choose Code Generation.

    • In the Calling Convention list, choose _fastcall.

    • In the Use run-time library list, choose Multithreaded DLL.

  4. Choose the Link tab and then in the Object/Library Modules text box, add one of the following libraries:

    • If you're building an .ocx, add OCXAPI.LIB from the Visual FoxPro API directory.

    • If you're building an .fll, add WINAPIMS.LIB from the Visual FoxPro API directory.

  5. Unmark Ignore all default libraries.

  6. Choose OK.

To make sure the compiler can find the necessary files

  1. From the Tools menu, choose Options.

  2. Click the Directories tab.

  3. In the Show directories for list, choose Include files.

  4. In the Directories toolbar, click the Add button.

  5. Add the directory with Pro_ext.h.

  6. In the Show directories for list, choose Library files.

  7. In the Directories toolbar, click the Add button.

  8. Add the directory with Ocxapi.lib from the Visual FoxPro API directory (when creating a control) or add the Winapims.lib from the Visual FoxPro API directory (when creating an FLL)

  9. In the Options dialog box, choose OK.

After you've specified the settings, you can compile and link your program.

To compile and link an .ocx file

  • From the Build menu, choose Build projname.ocx.

When you compile and link the .ocx file, Visual C++ automatically registers the control on the computer on which it was built. If for any reason you must register the control manually, you can do so using the following procedure.

To register the ActiveX control

  1. From the Tools menu in the Microsoft Development Environment, choose Register Control.

    -or-

  2. Declare and call DLLRegisterServer( ) from your program.

Debugging an ActiveX control or FLL library in the context of a full Visual FoxPro application is more difficult than debugging it separately from the application. It's a good idea to create a simple test program to test the operation of your control or library.

Debugging with the Microsoft Development Environment

Microsoft Visual C++ version 4.0 and higher offers an integrated debugging environment that makes it easy to set break points and to step through your code. You can even run Visual FoxPro from Visual C++.

To start debugging with Microsoft Visual C++

  1. From the Build menu, choose Settings.

  2. In the Project Settings dialog box, click the Debug tab.

  3. In the Executable for debug session text box, type the path and name of the Visual FoxPro executable (.exe) file. For example, you can type the following line with the appropriate substitution for the Visual FoxPro version number:

    C:\Program Files\Microsoft Visual FoxPro <versionNumber>\Vfp<versionNumber>.exe

  4. Choose OK.

  5. Set a break point in your library.

  6. From the Build menu, choose Debug. Then, from the submenu choose Go.

  7. When Visual Studio displays a message that says, " VFP9.exe does not contain debugging information," choose Yes to continue.

For more information about debugging in Visual C++, see the Visual C++ documentation set.

Debugging with Other Debuggers

You should be able to debug a control or library with any debugger that correctly handles an INT 3 (_BreakPoint( )) embedded in your program. You can use any debugger for symbolic debugging as long as it can do all of the following:

  • Make a symbol table from a map file.

  • Load the symbol table independent of the program.

  • Relocate the symbols to a new address.

To debug a library

  1. Add a _BreakPoint( ) call to the routine at the point where debugging will begin.

  2. Build the control or library.

  3. Invoke your debugger.

  4. If your debugger supports symbols, load the symbol table for your library.

  5. Start Visual FoxPro.

  6. Call your library routine from Visual FoxPro.

  7. When the breakpoint is reached, make adjustments to the symbol base to align your symbols with the actual location where the library was loaded.

  8. Increment the instruction pointer (IP) register by 1 to skip over the INT 3 instruction.

  9. Continue debugging as with a normal program.

    Note:
    Always remove any breakpoints specified in your debugger before you release your product.

See Also

Other Resources

How to: Manage Memory
Access to Visual FoxPro Variables and Fields
Accessing the Visual FoxPro API
Extending Visual FoxPro with External Libraries
How to: Return Values from ActiveX Controls and FLL Libraries


How to: Create Quit Routines

Visual FoxPro 9.0
How to: Create Quit Routines
See Also

You can create customized quit routines for your application when the user wants to quit your application, Visual FoxPro, or Microsoft Windows.

To create a quit routine

  • Use the ON SHUTDOWN command and include a command or procedure to run.

The ON SHUTDOWN command typically uses a DO command to call a procedure or program if a user tries to quit the application. For example, the following line of code specifies a quit routine named My_QuitRoutine:

Copy Code
ON SHUTDOWN DO My_QuitRoutine

The quit routine typically includes a dialog box that prompts the user whether they want to quit the current application. If the user wants to quit the application, the routine can close open files and clean up the environment, and then call the QUIT command. If the user does not want to exit the current application, the routine can return control to the application.

For more information, see ON SHUTDOWN Command.

See Also

Other Resources

Working with Programs
Programming in Visual FoxPro


Development Productivity Tools

Visual FoxPro 9.0
Development Productivity Tools
See Also

Visual FoxPro continues to provide developer tools for application development within the FoxPro application and the FoxPro language. Visual FoxPro has added and enhanced object-oriented language and behaviors. This version of Visual FoxPro includes Web-oriented language and tools designed to help rapid application development in multi-tier environments and to streamline your maintenance tasks.

In This Section

IntelliSense Overview

Describes how IntelliSense in Visual FoxPro displays information in pop-up windows and drop-down lists that assists you with statement and function completion syntax and displays the available variables, objects, properties, methods, and events of objects.
Using the Component Gallery

Describes the Component Gallery, a container for catalogs of software objects, such as class libraries, forms, buttons, and so on.
Coverage Profiler Application

Describes a coverage application, which writes information about which lines of code in a file were run whereas a profiler application provides information about which lines actually run, how many times a line is run, duration, and so on.
Utility Programs

Describes the tools, which are provided with Microsoft Visual FoxPro to help speed the process of application development.
How to: Customize the Toolbox

Describes how to add, deleted, and organize the Toolbox for quick access to the tools you use most often.
How to: Use the Task List Manager

Describes how to use the Task List Manager to keep track of shortcut, user-defined, and custom tasks.
How to: Create Bookmarks and Task List Shortcuts

Discusses how to use bookmarks and Task List shortcuts in the editing window so you can navigate your code more easily.
Customizing the Task List Manager

Describes how you can customize the display for the Task List Manager.
How to: Use the Object Browser

Describes how to use the Object Browser to view information about components, such as objects, classes, properties, methods, and events.
How to: Operate the Command Window

Describes the Command window, which can be used to run code. When you type a Visual FoxPro command in the window, the code is executed immediately.
How to: Use the Accessibility Browser

Discusses the Accessibility Browser, which you can use to verify that your application is accessible to people with disabilities.
How to: Use the Automated Test Harness

Provides information on the Automated Test Harness, which can be used to run scripts to help automate the testing of your application.

Related Sections

Customizing the Visual FoxPro Environment

Describes how to customize your development environment after installing Visual FoxPro. Environment settings include the main window title, default directory, project, editor, debugger and form tool options, temporary file storage, field mappings for drag-and-drop operations, and many other options.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.

See Also

Reference

XSource Folder


IntelliSense Overview

Visual FoxPro 9.0
IntelliSense Overview

At design time, IntelliSense functionality in Visual FoxPro helps you complete programming syntax while you type code by displaying Visual FoxPro language syntax information and lists of available members, property values, most recently used files, table names, field names, and variable names.

In This Section

IntelliSense Support in Visual FoxPro

Describes the level and scope of IntelliSense support in Visual FoxPro.
IntelliSense Syntax Completion

Describes how IntelliSense helps you complete Visual FoxPro programming syntax when you type code.
IntelliSense Auto MRU (Most Recently Used) Files

Describes how IntelliSense displays lists of available and most recently used (MRU) files when you type certain Visual FoxPro commands.
IntelliSense Auto Table, Field, and Variable Names

Describes how IntelliSense displays names of available tables, fields, and variables when you type certain Visual FoxPro commands.
How to: Activate or Disable IntelliSense

Describes how to turn IntelliSense off or on.
How to: View IntelliSense When Writing Code

Describes how to view IntelliSense functionality when you type code.
How to: Set IntelliSense Options

Describes how to specify settings that affect availability and appearance for IntelliSense functionality.
Customizing IntelliSense in Visual FoxPro

Describes how to customize IntelliSense functionality.

Related Sections

Development Productivity Tools

Describes Visual FoxPro tools you can use to improve productivity during application development.
Project Manager Hooks

Describes how you can access projects programmatically so you can manipulate projects as objects.
Automating Keystroke Tasks with Macros

Describes how you can record and save keystrokes using macros to automate keystroke tasks for application users or reuse the same keystrokes repeatedly.


IntelliSense Support in Visual FoxPro

Visual FoxPro 9.0
IntelliSense Support in Visual FoxPro
See Also

Visual FoxPro includes IntelliSense support for native Visual FoxPro language elements such as Visual FoxPro commands and functions, and for classes, instantiated objects and their properties, methods, and events, visual objects, the _VFP and _SCREEN system variables, Microsoft ActiveX controls, and COM servers. You can also add IntelliSense support for registered type libraries, user-defined types, members, and code elements, enumerated values, and custom classes.

The following list describes some of the locations where Visual FoxPro provides IntelliSense support:

  • Windows where you can type code, such as the Command window, program (.prg) file editors, code windows, and the Watch window in the Visual FoxPro Debugger.

    Note:
    Limited IntelliSense support is available in the Watch window. For more information, see IntelliSense Table Structure. IntelliSense support in program (.prg) files for elements such as class references, ActiveX controls, and COM servers exists only when these elements are strongly typed. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.

  • Containers and controls in Visual FoxPro designers, such as the Form Designer.

The following table summarizes the locations where IntelliSense is available for specific Visual FoxPro elements.

Visual FoxPro element | Visual FoxPro editor | Code window | Command window
_SCREEN | A | A | A
_VFP / Applications | A | A | A
Instantiated objects |  |  | A
Visual objects | S | A |
Class references | S | S |
ActiveX controls | S | A |
COM servers | S | S |
THIS, THISFORM, THISFORMSET | S | A |
Table and field names |  |  | A
User-defined | A | A | A

A = all appropriate members S = only strongly typed members

IntelliSense Runtime Support

Selected IntelliSense features are available at run time in distributed Visual FoxPro 9.0 applications. IntelliSense can be explicitly controlled at run time through FoxCode scripts. See Customizing IntelliSense in Visual FoxPro in Help for additional information on how to add IntelliSense to your runtime application.

The following table lists the IntelliSense features that are available at run time.

Feature Description

Editor opened with MODIFY COMMAND Command

Syntax coloring is available only in an editor opened with the MODIFY COMMAND command. Syntax coloring is supported even if word wrap is turned off.

List Members

Only available through the oFoxCode object in a FoxCode script.

Quick Info

Only available through the oFoxCode object in a FoxCode script.

_FOXCODE System Variable

Available at run time, but you must set its value to the name of the table file used by your runtime application.

_CODESENSE System Variable

Available at runtime, this system variable contains the name of the application that provides functionality for the IntelliSense Manager. By default, the application is FoxCode.app, which also contains the library for the common FoxCode scripts.

Note:
An application is not explicitly required for IntelliSense support at run time.

By default, _CODESENSE contains the empty string at run time. You must set its value to the name of the IntelliSense application used by your runtime application.

_VFP.EditorOptions

The EditorOptions Property is not set at run time. You must explicitly set the property at run time to enable IntelliSense support.

FoxCode Field Type = C (Command)

Supported at run time.

FoxCode Field Type = F (Function)

Supported at run time.

FoxCode Field Type = U (User)

Supported at run time.

FoxCode Field Type = S (Script)

Supported at run time.

The following table lists the IntelliSense features that are not available at run time.

Feature | Description
Keyboard Shortcuts | IntelliSense keyboard shortcuts are not available at run time for Automatic List Members, Quick Info, or List Values functionality.
Menu Commands | The IntelliSense List Members and Quick Info commands in the Edit menu are not available in the Visual FoxPro editors at run time.
List Values | Not supported at run time.
Native Object Support | Not supported at run time.
Variable Typing | Not supported at run time.
Most Recently Used List | Not supported at run time.
FoxCode Field Type = T (Typing) | Not supported at run time.
FoxCode Field Type = O (COM Typing) | Not supported at run time.
FoxCode Field Type = P (Property) | Not supported at run time.
FoxCode Field Type = E (XML) | Not supported at run time.

See Also

Other Resources

IntelliSense Syntax Completion
IntelliSense Auto Table, Field, and Variable Names
IntelliSense Auto MRU (Most Recently Used) Files
How to: Activate or Disable IntelliSense
How to: View IntelliSense When Writing Code
IntelliSense Overview


IntelliSense Syntax Completion

Visual FoxPro 9.0
IntelliSense Syntax Completion
See Also

When you type code, Visual FoxPro IntelliSense can help you complete Visual FoxPro programming syntax using the following functionality:

  • Quick Info

  • List Members

  • List Values

Quick Info

Quick Info functionality displays additional syntax information for Visual FoxPro language elements such as functions and methods. For example, when you type a SYS( ) function in the Command window, Quick Info displays a list box containing available syntax elements you can choose from. When entering argument values for methods, Quick Info displays the syntax in a Tip window and the next argument in bold. For other Visual FoxPro language elements, such as commands, syntax information displays in a Tip window.

Quick Info is available in any location you can type Visual FoxPro code, such as the Command window, editors, and code windows.

List Members

List Members functionality displays a list box of available members for certain Visual FoxPro language elements, such as the _VFP and _SCREEN system variables, and in more limited locations, available members such as properties, methods, events, and objects for instantiated objects. List Members is also available for visual objects, ActiveX controls, COM servers, native Visual FoxPro classes, and user-defined members when they are strongly typed. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.

For objects created at run time by functions such as CREATEOBJECT( ), CREATEOBJECTEX( ), NEWOBJECT( ), and GETOBJECT( ), IntelliSense populates the List Members list box with information from class definitions or type libraries that Visual FoxPro searches for in the following locations:

  • Visual FoxPro object base classes.

  • Class definitions in memory in the order that they were loaded.

  • Class definitions in the current program.

  • Class definition in a visual class library (.vcx) file opened by the SET CLASS command.

  • Class definitions in the procedure files opened by the SET PROCEDURE command.

  • Class definitions in the Visual FoxPro program execution chain. For more information, see DO Command.

  • System registration database (registry).

  • Keyboard shortcuts for Quick Info and List Members.

List Values

When assigning values to properties programmatically for objects, List Values functionality displays value editors, such as font or color pickers, or a list box of available values. List Values is available for properties that have a defined set of values, and the type library of the referenced object determines the contents of the List Values list box. For properties in type libraries, List Values supports enumerations.

See Also

Other Resources

IntelliSense Auto MRU (Most Recently Used) Files
IntelliSense Auto Table, Field, and Variable Names
How to: Activate or Disable IntelliSense
How to: View IntelliSense When Writing Code
How to: Set IntelliSense Options
IntelliSense Overview


IntelliSense Auto MRU (Most Recently Used) Files

Visual FoxPro 9.0
IntelliSense Auto MRU (Most Recently Used) Files
See Also

When you type certain Visual FoxPro commands, you can use IntelliSense to view a list of available and most recently used files of the appropriate type for each command.

The following table lists the commands and the corresponding default file types that IntelliSense searches for and displays.

Command | IntelliSense displays files with the following types
CD | Files in the current or specified path.
DO | .prg, .mpr, .qpr, .fxp, .app, .exe
DO FORM | .scx
LABEL FORM | .frx, .lbx
MODIFY CLASS | .vcx
MODIFY COMMAND | .prg, .mpr, .qpr
MODIFY DATABASE | .dbc
MODIFY FILE | Any file type and extension.
MODIFY FORM | .scx
MODIFY LABEL | .lbx
MODIFY MENU | .mnx
MODIFY PROJECT | .pjx
MODIFY QUERY | .qpr
MODIFY REPORT | .frx
MODIFY VIEW | Local and remote views.
OPEN DATABASE | .dbc
REPORT FORM | .frx, .lbx
SET DATABASE | .dbc
USE | .dbf, view

See Also

Other Resources

IntelliSense Syntax Completion
IntelliSense Auto Table, Field, and Variable Names
How to: Activate or Disable IntelliSense
How to: View IntelliSense When Writing Code
How to: Set IntelliSense Options
IntelliSense Overview


IntelliSense Auto Table, Field, and Variable Names

Visual FoxPro 9.0
IntelliSense Auto Table, Field, and Variable Names
See Also

When you type certain Visual FoxPro commands, IntelliSense displays names of appropriate tables, fields, and variables.

Displaying Table and Field Names Automatically

When you are working with an open table and type certain commands in the Command window, IntelliSense displays a list of appropriate table or field names. When you browse a list of fields, IntelliSense displays a Tip window that shows the type and width for the selected field.

The following table lists the commands and the corresponding tables or fields that IntelliSense displays.

Visual FoxPro command | IntelliSense displays a list of
USE or USE tableAlias | Tables from the active database and Most Recently Used (MRU) list.
REPLACE | Fields from the table, cursor, or view in the currently selected work area.
MODIFY MEMO | Memo fields from the table, cursor, or view in the currently selected work area.
MODIFY GENERAL | General fields from the table, cursor, or view in the currently selected work area.

Displaying Variable Names Automatically

When you type the letter "m" followed by a period (.) in the Command window, IntelliSense displays a list of all declared and available variables. When you browse the list of variable names, IntelliSense displays a Tip window with information about the variable's value.

See Also

Other Resources

IntelliSense Syntax Completion
IntelliSense Auto MRU (Most Recently Used) Files
How to: Activate or Disable IntelliSense
How to: View IntelliSense When Writing Code
How to: Set IntelliSense Options
IntelliSense Overview


How to: Activate or Disable IntelliSense

Visual FoxPro 9.0
How to: Activate or Disable IntelliSense
See Also

You can activate or disable IntelliSense functionality using the IntelliSense Manager or programmatically. By default, IntelliSense functionality is activated.

To disable or activate IntelliSense

  1. On the Tools menu, click IntelliSense Manager.

  2. In the IntelliSense Manager dialog box, click the General tab.

  3. To disable IntelliSense, clear the Enable IntelliSense check box.

    -OR-

    To activate IntelliSense, select the Enable IntelliSense check box.

You can also activate or disable IntelliSense functionality programmatically by setting the appropriate values in the EditorOptions property using the _VFP system variable. For more information, see Visual FoxPro IntelliSense Manager Window and EditorOptions Property.

You can also set levels of availability for different parts of IntelliSense functionality. For example, when IntelliSense is set to Manual, you can activate IntelliSense using keyboard shortcuts. For more information, see How to: Set IntelliSense Options.

See Also

Other Resources

How to: View IntelliSense When Writing Code
IntelliSense Overview


How to: View IntelliSense When Writing Code

Visual FoxPro 9.0
How to: View IntelliSense When Writing Code
See Also

You can display IntelliSense functionality when typing code in Visual FoxPro editors, code windows, and the Command window or when debugging code in the Watch window of the Visual FoxPro Debugger.

When List Members or Quick Info in IntelliSense is set to Automatic, IntelliSense functionality displays when you press an activator key. The activator key you press differs depending on the code context. When List Members or Quick Info is set to Manual, you can display IntelliSense functionality by pressing the appropriate keyboard shortcut in the appropriate cursor position. For more information, see IntelliSense Activator, Navigation, and Terminator Keys and Keyboard Shortcuts.

The following sections describe how you can view IntelliSense functionality when you type code:

  • Viewing Quick Info and Available Members and Values

  • Viewing Most Recently Used (MRU) Files

  • Viewing Available Tables, Fields, and Variables

Viewing Quick Info and Available Members and Values

You can view Quick Info (syntax information) or available members or values when you type code. For more information, see IntelliSense Syntax Completion.

To view Quick Info for commands

  1. Type the first word in the command and press SPACEBAR.

    IntelliSense performs one of the following actions so you can continue typing the command:

    • Inserts partial syntax.

    • Displays a list of valid members so you can select one.

      Tip:
      To browse the list and view Quick Info for each member in the list, press the DOWN ARROW or UP ARROW key. IntelliSense displays a Tip window with information, if available, about each member.

    • Displays a Tip window with the remaining syntax.

  2. Continue typing.

    -OR-

    Select a member by double-clicking the member. You can also click the member and press SPACEBAR.

    The member appears at the current cursor position.

For example, suppose you type the following line of code followed by a space (" ") in the Command window:

Copy Code
ALTER

IntelliSense completes the SQL ALTER TABLE command partially and displays the remaining syntax information in a Tip window.

To view Quick Info for functions and object methods

  1. Type the name of the function or object method followed immediately by an opening parenthesis (().

    IntelliSense performs one of the following actions so you can continue typing the function or method:

    • Displays a Tip window with the remaining syntax. When entering argument values, the syntax for the next argument appears in bold.

    • Displays a list of valid values so you can select one.

      Tip:
      To browse the list and view Quick Info for each value in the list, press the DOWN ARROW or UP ARROW key. IntelliSense displays a Tip window with information, if available, about each value.

  2. Continue typing.

    -OR-

    Select a valid value by double-clicking the value or click the value and press SPACEBAR.

For example, suppose you type the following line of code followed immediately by an opening parenthesis in the Command window:

Copy Code
SYS(

IntelliSense displays a list of valid values so you can select one.

For more information, see IntelliSense Syntax Completion.

To view available members for system variables or objects

  1. Type the name of a valid system variable or instantiated object followed immediately by a period (.).

    IntelliSense displays a list of available members so you can choose one.

    Tip:
    To browse the list and view Quick Info for each member in the list, press the DOWN ARROW or UP ARROW key. IntelliSense displays a Tip window with information, if available, about each member.

  2. To select a valid member, double-click the member. You can also click the member in the list and press SPACEBAR.

For example, suppose you want to set the Visible property for a form programmatically by typing the following in the Command window:

Copy Code
oMyForm = CREATEOBJECT("Form")
oMyForm.

When you type the period (.) following oMyForm, IntelliSense displays a list with the members of the object oMyForm. You can then choose the Visible property from the list.

The member list remains visible until you perform one of the following actions:

  • Enter all required parameters followed by a space (" ").

  • Type a terminator key, such as ESC, END, or HOME, or an invalid character key.

  • Change the active window.

For more information, see IntelliSense Syntax Completion.

To view available values for properties

  1. Type the name of the property followed immediately by an equal sign (=).

    -OR-

    Select the property from a member list, press SPACEBAR, and then type an equal sign.

    IntelliSense displays a list of values, if available, so you can choose one.

  2. Select a value by double-clicking the value. You can also click the value and press SPACEBAR.

    The value appears at the current cursor position.

For example, suppose you set the Visible property for a form programmatically by typing the following in the Command window:

Copy Code
oMyForm = CREATEOBJECT("Form")
oMyForm.Visible=

When you type the equal sign (=) to assign a True (.T.) or False (.F.) value to the Visible property, IntelliSense displays a list box with the appropriate values for you to choose from.

For more information, see IntelliSense Syntax Completion.

Viewing Most Recently Used (MRU) Files

You can view and select available most recently used files in the appropriate locations when you type code. For more information, see IntelliSense Auto MRU (Most Recently Used) Files.

To view available and most recently used (MRU) files

  1. Type the appropriate command followed immediately by a space (" ").

    IntelliSense displays a list of available files so you can browse the list and select a file.

  2. Select a file by double-clicking the file. You can also click the file and press SPACEBAR.

    The path, if appropriate, and file name appear at the current cursor position.

Viewing Available Tables, Fields, and Variables

You can view and select available tables, fields, and variables in the appropriate locations when you type code. For more information, see IntelliSense Auto Table, Field, and Variable Names.

To view available tables and fields

  1. Open a table in Visual FoxPro.

  2. Type the appropriate command followed immediately by a space (" ").

    Depending on the command, IntelliSense displays a list of available tables or fields so you can browse the list and select a table or field.

  3. Select a table or field by double-clicking the table or field. You can also click the table or field and press SPACEBAR.

    The table or field name appears at the current cursor position.

To view available variables

  • In the Command window, type the letter "m" followed immediately by a period (.).

    IntelliSense displays a list of all declared and available variables.

For example, suppose you declare two variables by typing the following code in the Command window:

Copy Code
oMyForm=CREATEOBJECT("Form")
oMyForm2=CREATEOBJECT("Form")
m.

When you type the period following the letter "m", IntelliSense displays a list of all declared and available variables.

See Also

Other Resources

How to: Set IntelliSense Options
Customizing IntelliSense in Visual FoxPro
IntelliSense Overview


How to: Set IntelliSense Options

Visual FoxPro 9.0
How to: Set IntelliSense Options
See Also

You can set IntelliSense options that affect its availability and appearance as described by the following sections:

  • Setting Availability Levels for Quick Info and List Members

  • Specifying the Number of Files in the Most Recently Used (MRU) List

  • Setting the Number of Items to Display in IntelliSense List Boxes

To customize IntelliSense functionality for Visual FoxPro and user-defined language elements, including commands and functions that display IntelliSense-like lists, such as SET commands, modify the records in the IntelliSense table. For more information, see Customizing IntelliSense in Visual FoxPro.

Setting Availability Levels for Quick Info and List Members

You can change the level of availability for Quick Info and List Members to Auto, Manual, or Disabled. Setting these options makes it possible for you to activate or disable Quick Info and List Members in the following ways:

  • When set to Automatic (default), Quick Info or List Members appears where appropriate when the corresponding activator key is pressed. For more information about using activator keys, see How to: View IntelliSense When Writing Code.

  • When set to Manual, Quick Info or List Members is available when you choose Quick Info or List Members, respectively, on the Edit menu, a shortcut menu, or by pressing the appropriate keyboard shortcut when the cursor is positioned at a location where Quick Info or List Members is available.

  • When set to Disabled, Quick Info or List Members is unavailable and does not appear.

    Note:
    For commands, syntax information that appears in Tip windows appears automatically unless Quick Info and List Members are set to Disabled.

For more information, see Visual FoxPro IntelliSense Manager Window.

To set availability for Quick Info and List Members

  1. On the Tools menu, click IntelliSense Manager.

  2. In the IntelliSense Manager dialog box, click the General tab.

  3. To make options available for Quick Info or List Members, make sure the Enable IntelliSense check box is selected.

    If the Enable IntelliSense check box is cleared, Quick Info and List Members are both disabled.

  4. Select the options you want in the List members or Quick info tips list boxes.

  5. When you are finished, click OK.

You can also activate or disable List Members and Quick Info programmatically by setting the appropriate options in the EditorOptions property using the _VFP system variable. For more information, see EditorOptions Property.

Specifying the Number of Files in the Most Recently Used (MRU) List

You can specify the number of files displayed in the MRU list using the Options dialog box.

To specify the number of files in the MRU list

  1. On the Tools menu, click Options.

  2. In the Options dialog box, click the View tab.

  3. In the Most Recently Used list contains box, select or type the number of files you want to display.

  4. When you are finished, click OK.

For more information, see View Tab, Options Dialog Box.

Setting the Number of Items to Display in IntelliSense List Boxes

You can set the number of items to display initially in IntelliSense list boxes using the Options dialog box.

To set the number of items to display in IntelliSense list boxes

  1. On the Tools menu, click Options.

  2. In the Options dialog box, click the View tab.

  3. In the List display count box, select or type the number of items you want to display initially in IntelliSense list boxes.

  4. When you are finished, click OK.

For more information, see View Tab, Options Dialog Box.

See Also

Other Resources

How to: View IntelliSense When Writing Code
How to: Activate or Disable IntelliSense
IntelliSense Overview


IntelliSense Activator, Navigation, and Terminator Keys

Visual FoxPro 9.0
IntelliSense Activator, Navigation, and Terminator Keys
See Also

IntelliSense responds to activator keys such as the SPACEBAR, navigation keys such as alphanumeric keys, and terminator keys such as the ESC key. The code context and the language element determine which activator keys you can use.

The following tables describe activator, navigation, and terminator keys that IntelliSense responds to.

Activator Keys

Key | Description
SPACEBAR | Space (" "). Activator key for Visual FoxPro commands and user-defined language elements. Displays member lists or Tip windows.
( | Opening parenthesis. Activator key for Visual FoxPro functions and object methods. Displays value lists or Tip windows.
PERIOD | Period (.). Activator key for system variables or objects. Displays member lists of object properties, methods, or events or Tip windows.
= | Equal sign. Activator key for properties. Verifies white space between the property and the "=" character. Displays value lists, value editors, for example, font or color pickers, or Tip windows.

Navigation Keys

Key | Description
a–z, A-Z, 0-9 | Alphanumeric. Navigates matching items in IntelliSense lists until no more matches exist.
< | LEFT ARROW. Positions the cursor one character to the left. Closes the IntelliSense list if the cursor moves out of context, for example, preceding a period.
> | RIGHT ARROW. Positions the cursor one character to the right. Closes the IntelliSense list if the cursor moves out of context, for example, following what has been typed.
PAGE UP | Moves the cursor one page up in the IntelliSense list.
PAGE DOWN | Moves the cursor one page down in the IntelliSense list.
TAB | Inserts a selected item in an IntelliSense list into the code and positions the cursor immediately following the added item.

Terminator Keys

Key | Description
ESC | Closes the IntelliSense list box.
HOME | Closes the IntelliSense list box and positions the cursor at the beginning of the current line.
END, ENTER, SPACEBAR, and other non-alphanumeric characters | Closes the IntelliSense list box and positions the cursor at the end of the current line.

See Also

Other Resources

How to: View IntelliSense When Writing Code
IntelliSense Overview


Customizing IntelliSense in Visual FoxPro

Visual FoxPro 9.0
Customizing IntelliSense in Visual FoxPro

You can customize IntelliSense functionality for Visual FoxPro and user-defined language elements by modifying or adding records in the IntelliSense table. For example, you can add or modify syntax completion items or create scripts that run when you use IntelliSense functionality.

Note:
Changes in the IntelliSense table do not affect IntelliSense functionality for object properties, methods, and events.

In This Section

IntelliSense Table Structure

Describes the structure of the IntelliSense table.
How to: Edit IntelliSense Records

Describes how to open the IntelliSense table and edit its records.
How to: Create IntelliSense Scripts

Describes how to create and use scripts that run when using IntelliSense functionality.
How to: Restore the Default IntelliSense Table

Describes how to restore the IntelliSense table to its original configuration for native Visual FoxPro language elements and how to delete user-defined items.

Related Sections

IntelliSense Overview

Describes how IntelliSense in Visual FoxPro helps you complete programming syntax and displays lists of available files, tables, fields, and variables when you type code.
IntelliSense Support in Visual FoxPro

Describes the level and scope of IntelliSense support in Visual FoxPro.


IntelliSense Table Structure

Visual FoxPro 9.0
IntelliSense Table Structure
See Also

The IntelliSense table contains records that specify IntelliSense functionality for native Visual FoxPro and user-defined language elements. By default, the IntelliSense table is named FoxCode and is stored in the FoxCode.dbf file, which is located in the main Microsoft Visual FoxPro directory and is specified by the _FOXCODE system variable. For more information, see _FOXCODE System Variable.

Note:
The IntelliSense table contains limited support for the Watch window in the Visual FoxPro Debugger and depends on whether an expression is valid for the Watch window.

Support for the Watch window exists in the IntelliSense table for the following areas:

  • List Members for instantiated objects.

  • Quick Info for instantiated objects.

  • Function items.

  • Memory variable expansion by typing m.

IntelliSense functionality is not supported in the Watch window for the following:

  • List Values for instantiated objects.

  • Command items.

  • Default script handlers.

  • Property value editors.

  • User-defined commands.

  • Most recently used (MRU) files.

The following table describes the structure of the IntelliSense table.

Field name | Type (size) | Description
Type | C (1) | Specifies the type of item in the record. For more information, see Valid Item Types for the Type Field.
Abbrev | C (24) | Represents the minimum set of characters typed to activate IntelliSense functionality for this item. The text you type from the Abbrev field is replaced by the text in the Expanded field.
Expanded | C (26) | Specifies the text that IntelliSense uses to replace text typed at the current cursor position. The text in the Expanded field replaces the text you type from Abbrev field.
Cmd | C (15) | Specifies the script reference for this item.
Tip | M | Specifies the text to display in the Quick Info Tip window.
Data | M | Specifies contents for IntelliSense List Values functionality, Visual FoxPro code specific to this item, or other script text.
Case | C (1) | Specifies letter casing for replacement text. U = Uppercase L = Lowercase M or <empty> = Mixed case P = Proper case X = Unchanged Any value you specify in the field of the version record sets a global default for individual records that do not have a Case setting.
Save | L | Specifies whether the record is saved when the field is updated.
TimeStamp | T | Represents a unique timestamp for this item.
Source | M | Specifies the source of record contents. The word RESERVED specifies core contents shipped with this version of Visual FoxPro. This field can contain path and file name information for user-supplied records.
UniqueID | C (10) | Specifies a unique identifier for this record.
User | M | Specifies user information.

Valid Item Types for the Type Field

The following table describes valid values and item types for the Type field in the IntelliSense table.

Type field | Item type | Description
O | COM Component | Specifies the COM type library reference to display in AS clause IntelliSense lists. For more information, see COM Component Item Type.
C | Command | Specifies syntax completion items for Visual FoxPro commands. For more information, see Command Item Type.
E | XML | Specifies that the item is a property or method that has member metadata. For more information, see MemberData Extensibility.
F | Function | Specifies syntax completion items for Visual FoxPro functions, procedures, and user-defined functions. For more information, see Function Item Type.
P | Property | Specifies script references for displaying value editors for certain Visual FoxPro properties. For more information, see Property Item Type.
S | Script | Specifies the Visual FoxPro scripts to run. For more information, see Script Item Type.
T | Typing | Specifies items that appear in AS clause IntelliSense lists or when referencing objects. For more information, see Typing Item Type.
U | User | Specifies user-defined auto-expansion items. Unlike Command items, User items do not require exact pattern matches. For more information, see User Item Type.
V | Version | Specifies a special record for version and tracking information (reserved). For more information, see Version Item Type.

COM Component Item Type

The COM Component item type specifies an IntelliSense table record whose contents appear in AS clause IntelliSense lists, similar to Typing items. A COM Component item specifies the name of a COM type library that contains a collection of classes (ProgIDs) that Visual FoxPro can create instances of using the CREATEOBJECT( ) function. The Data field for a COM Component item contains the GUID and version for the type library.

The following table illustrates an example IntelliSense record for a COM Component item.

Field Name | Example
Type | O
Abbrev | Excel
Cmd | {}
Tip | Microsoft Excel 9.0 Object Library
Data | {00020813-0000-0000-C000-000000000046}#1.3

Command Item Type

The Command item specifies a IntelliSense table record whose contents complete or replace syntax or display a Tip window for Visual FoxPro commands.

Note:
The characters in the Abbrev field of Command item records must match the initials of the text in the Expanded field. For example, if the Expanded field contains the command MODIFY COMMAND, the Abbrev field must contain the initials MC.

The following table illustrates an example IntelliSense record for a Command item.

Field Name | Example
Type | C
Abbrev | MC
Expanded | MODIFY COMMAND

_MemberData Property Type

The _MemberData record supports the GetMemberData design-time builder hooks.

Field Name | Example
Type | E - Indicates that the item is property or method with metadata
Abbrev | _GETMEMBERDATA - Name of a member property or method
Data | Contents of the script to run for the property or method

Function Item Type

The Function item specifies an IntelliSense table record whose contents complete or replace syntax or display a Tip window for Visual FoxPro and user-defined functions and procedures.

The following table illustrates an example IntelliSense record for a Function item.

Field Name | Example
Type | F
Abbrev | FCOU
Expanded | FCOUNT
Tip | [nWorkArea | cTableAlias]

Property Item Type

The Property item specifies an IntelliSense table record whose contents can specify code in its Data field or a script reference in its Data field to a Script item. The code or script reference can run to display a custom value editor when you assign values for the property that the Property item corresponds to.

The following table illustrates an example IntelliSense record for a Property item.

Field Name | Example
Type | P
Abbrev | .Picture
Cmd | {picture}

In this example, the Cmd field contains the script reference "{picture}" for a script stored by a separate Script item. The Abbrev field in the Script record contains the character string, "Picture", and the code in the Data field of the Script record runs when you type the following line of code or use IntelliSense to complete the following syntax:

Copy Code
Object.Picture=

For more information, see Script Item Type.

Script Item Type

The Script item specifies an IntelliSense table record that contains code or data in its Data field. When you store code in a separate Script item, other IntelliSense table records can reference and run that code by storing a script reference in the Cmd field.

Note:
A script reference is an optional keyword that appears in the Abbrev field of the Script record and is enclosed by a pair of opening and closing braces ({}).

Code that IntelliSense runs must contain a parameter to pass to the FoxCode parameter object. The FoxCode parameter object contains metadata describing how the script was called, including the source record in the IntelliSense table. Therefore, the code in a Data field must contain a PARAMETERS or LPARAMETERS statement to accommodate the object reference. For more information about the FoxCode parameter object, see FoxCode Object Reference.

The value returned by the code replaces any text that is typed at the current cursor position. However, if the return value evaluates to an empty string (""), Visual FoxPro leaves the typed text unchanged.

The following table illustrates an example IntelliSense record for a Script item.

Field Name Example

Type

S

Abbrev

Picture

Data

(Stored in a memo field)

Copy Code
LPARAMETERS oFoxcode
   LOCAL lcPicture
   oFoxcode.ValueType="V"
   lcPicture = GETPICT()
   IF LEN(lcPicture) > 0
      lcPicture = ['] + lcPicture + [']
   ENDIF
   RETURN lcPicture

For this example, suppose the Cmd field in a Property item for the Picture property contains the script reference "{picture}" for the example Script item. When you select the Picture property for an object by typing .Picture followed by an equal sign (=) and select the image picker, the code in the Data field of the Script item runs and displays the Open Picture dialog box.

For more information about using scripting, see How to: Create IntelliSense Scripts.

Typing Item Type

The Typing item specifies an IntelliSense table record whose contents describe an item that appears in the IntelliSense list for AS clauses. The Data field for a Typing item can optionally contain code that returns a value that IntelliSense inserts at the current cursor position.

Tip:
If you include code in the Data field, end it with a RETURN statement.

The following table illustrates an example IntelliSense record for a Typing item.

Field Name | Example
Type | T
Abbrev | CommandButton
Data | CommandButton

User Item Type

The User item specifies an IntelliSense table record whose contents complete or replace user-defined abbreviations. Unlike the Abbrev field in Command items, the User item abbreviation does not need to match the initials of text in the Expanded field.

Field Name | Example
Type | U
Abbrev | MYADDRESS
Expanded | 101 Main Street

Version Item Type

The Version item type specifies an IntelliSense table record that contains default settings and tracks version information. The Version item type is reserved for internal use.

Field Name | Example
Type | V
Expanded | Identifies latest version of IntelliSense. For internal use.

See Also

Reference

_MemberData Property

Concepts

MemberData Extensibility

Other Resources

Howto:EditIntelliSenseRecords
Howto:CreateIntelliSenseScripts
CustomizingIntelliSenseinVisualFoxPro


How to: Edit IntelliSense Records

Visual FoxPro 9.0
How to: Edit IntelliSense Records
See Also

You can add new items to the IntelliSense table or edit existing items. You can edit user-defined items in the IntelliSense table using the Visual FoxPro IntelliSense Manager or all IntelliSense records by opening and browsing the table directly or accessing the table programmatically.

To add new items to the IntelliSense table

  1. On the Tools menu, click IntelliSense Manager.

  2. In IntelliSense Manager, click the Custom tab.

    The Custom tab lists all user-defined items in the IntelliSense table.

  3. In the Type box, select the item type you want.

    Note:
    The Add button becomes available when you initially select a type other than Command.

  4. Click Add.

    A new record appears at the beginning of the table displayed on the Custom tab.

  5. In the Replace box, type the characters to replace with text in the With box.

    Note:
    When you type the characters in the Replace box at the appropriate cursor location, the text you specify in the With box replaces the text you typed.

  6. In the With box, type the characters you want to use to replace the text in the Replace box.

  7. To add code to the Data field, click Script.

    An editor window opens so you can add code to the Data field for that item.

  8. To view and edit the entire record, click Edit.

    The IntelliSense table opens so you can edit other fields in the record.

For more information, see Visual FoxPro IntelliSense Manager Window.

To edit existing user-defined items in the IntelliSense table

  1. On the Tools menu, click IntelliSense Manager.

  2. In IntelliSense Manager, click the Custom tab.

    The Custom tab lists all user-defined items in the IntelliSense table.

  3. In the list of items, select the item you want to edit.

  4. To view and edit the entire record, click Edit.

Opening the IntelliSense Table Programmatically

You can access the IntelliSense table programmatically using the _FOXCODE system variable. For more information, see _FOXCODE System Variable.

To open the IntelliSense table programmatically

  • In the Command window, type the following lines of code:

    Copy Code
    USE (_FOXCODE) SHARED
BROWSE

    The IntelliSense table opens in a Browse window.

See Also

Other Resources

IntelliSense Table Structure
How to: Create IntelliSense Scripts
How to: Restore the Default IntelliSense Table
Customizing IntelliSense in Visual FoxPro


How to: Create IntelliSense Scripts

Visual FoxPro 9.0
How to: Create IntelliSense Scripts
See Also

You can create IntelliSense scripts for items in the IntelliSense table. Creating IntelliSense scripts make it possible for commands, functions, or properties to run certain code, for example, to open a value editor when you want to assign values to certain properties. For more information, see IntelliSense Table Structure.

The following sections describe different ways for creating and referencing scripts:

  • Creating or Referencing Scripts for Multiple Items

  • Referencing Scripts for Single Items

Creating or Referencing Scripts for Multiple Items

In the IntelliSense table, you can create Script record whose Data field contains a custom procedure or Visual FoxPro code that other IntelliSense records can run, or you can store code in the Data field of an item that runs for that item only. Though the Data field generally contains code that other IntelliSense records run, it can also store metadata used by scripts. The FoxCode parameter object passes this metadata automatically to a script. For details about the FoxCode object, see FoxCode Object.

To create IntelliSense scripts that other IntelliSense records can run

  1. Open the IntelliSense table in the FoxCode.dbf file using the IntelliSense Manager or programmatically.

  2. Create a record in the IntelliSense table for a Script item.

  3. In the Abbrev field of the Script item, type the keyword that you want other records to use as part of the script reference for running the script.

  4. In the Data field of the Script item, type the Visual FoxPro code you want for other IntelliSense records to run.

    Note:
    Code in the Data field must contain a PARAMETERS or LPARAMETERS statement to accommodate the FoxCode object reference. Each IntelliSense script must contain a parameter that IntelliSense passes to the FoxCode parameter object. The FoxCode parameter object contains metadata describing how the script was called, including the source record in the IntelliSense table. For more information, see the description for the Script item type in IntelliSense Table Structure.

  5. In the Cmd field of items that run the script, type a script reference, which encloses the script keyword from the Abbrev field of the Script item with opening and closing braces ({}).

For example, typing the following text in the Abbrev field of the Script item designates the text as the script keyword:

Picture

Inserting the following code in the Data field of the Script item displays the Open Picture dialog box:

Copy Code
LPARAMETERS oFoxcode  && Required statement.
LOCAL lcPicture
oFoxcode.valuetype="V"
lcPicture = getpict()
IF LEN(lcPicture) > 0
   lcPicture = ['] + lcPicture+ [']
ENDIF
RETURN lcPicture

Typing the following text, which is the script keyword enclosed with opening and closing braces ({}), in the Cmd field of other IntelliSense records designates the text as the script reference:

{picture}

To reference existing IntelliSense scripts from other IntelliSense records

  1. In the IntelliSense table, find the Script item you want to use.

  2. In the Abbrev field of the Script item, find the keyword that you want to use as part of the script reference.

  3. In the Cmd field of the IntelliSense record that runs the script, type the keyword from the Abbrev field in the Script item enclosed by opening and closing braces ({}).

Referencing Scripts for Single Items

Except in Typing and COM Component items, when the Cmd field of an IntelliSense record contains only opening and closing braces with no script keyword, typing the text in the Abbrev field of that item runs any code that exists in the Data field of the same item.

To create scripts for single IntelliSense records

  1. In the IntelliSense table, find the item you want to create a script for.

  2. In the Data field of the item, type the Visual FoxPro code you want the item to run.

  3. In the Cmd field of the item, type opening and closing braces ({}) without a space between them.

For example, the following table illustrates an example code in the Data field of a Command item that runs when IntelliSense functionality is activated for that Command item only.

Field Name | Example
Type | C
Abbrev | NOW
Cmd | {}
Data | (Stored in a memo field) LPARAMETERS oFoxCode RETURN TRANSFORM(DATE( ))

See Also

Other Resources

How to: Edit IntelliSense Records
How to: Restore the Default IntelliSense Table
Customizing IntelliSense in Visual FoxPro


How to: Restore the Default IntelliSense Table

Visual FoxPro 9.0
How to: Restore the Default IntelliSense Table
See Also

You can restore IntelliSense functionality for native Visual FoxPro language elements in the IntelliSense table to its default configuration. However, user-defined IntelliSense records remain unless you delete them manually.

To restore the IntelliSense table configuration for native Visual FoxPro language elements

  1. On the Tools menu, click IntelliSense Manager.

  2. In IntelliSense Manager, click the Advanced tab.

  3. On the Advanced tab, click Clean Up.

  4. In the Maintenance dialog box, click Restore FoxCode.

    Visual FoxPro prompts you to confirm restoring your IntelliSense table to the original table.

  5. To confirm restoration, click Yes.

    Visual FoxPro confirms that it has restored a clean copy of the IntelliSense table.

  6. To finish restoration, click OK.

To delete user-defined IntelliSense records

  1. On the Tools menu, click IntelliSense Manager.

  2. In IntelliSense Manager, click the Custom tab.

  3. On the Custom tab, select the user-defined IntelliSense record you want to delete.

  4. Click Delete.

  5. When prompted to confirm deletion, click Yes to mark the record for deletion.

  6. When you are finished marking all records you want to delete, click the Advanced tab.

  7. On the Advanced tab, click Clean Up.

  8. In the Maintenance dialog box, click Clean Up FoxCode to remove records marked for deletion.

See Also

Other Resources

How to: Edit IntelliSense Records
How to: Create IntelliSense Scripts
Customizing IntelliSense in Visual FoxPro


Using the Component Gallery

Visual FoxPro 9.0
Using the Component Gallery

The Component Gallery is a container for catalogs of software objects such as class libraries, forms, buttons, and so on. The Component Gallery also contains Visual FoxPro classes. You can use the Component Gallery to organize components into object, project, application, or other groupings. These visual groupings are dynamically customizable so that you can use, duplicate, or rearrange components among several classifications within the Component Gallery. You can access a specific component from any of the places in the Component Gallery in which you place a reference to that component. You can have several references in different catalogs or folders to a single object. For instance, a button might appear in one or more Component Gallery project categories (represented as folders), but might also be visible in a "Tools" category that holds references to all the buttons you use.

You can use the Component Gallery for all the functions provided by the separate Project Manager, Class Browser, and Form Controls toolbar. Each of the other Visual FoxPro components provides very specific focus to the projects or classes from within the special environment of either Project file or Class library. The Component Gallery allows you to manage the relationships between components and many of the behaviors of those components from an abstract design level as well as from a more intimate development perspective.

You can drag and drop components within the Component Gallery and from the Component Gallery to projects or forms. You can also change properties of objects or classes from within the Component Gallery.

The Component Gallery can contain any Visual FoxPro element, including local and remote documents, files, or folders, Automation servers like Microsoft Excel and Word, and HTML locations and files. You can also include .prg files containing code snippets, classes, wizards, builders, or art.

In This Section

How to: Manage Projects with the Component Gallery

Explains how to use the Component Gallery to use the templates, builders, and wizards in the Component Gallery to create the project or applications.
Component Gallery Catalogs

Describes how to use the Visual FoxPro Component Gallery catalogs and the default catalog, which includes items grouped into several categories, including forms, controls, and others.
How to: Customize the Component Gallery

Describes how you can change the default behavior of the Visual FoxPro Component Gallery catalog, folders, and gallery items by customizing the Component Gallery.
Component Gallery Object Members

Provides a list of classes and items that reference the class, which comprise the Visual FoxPro Component Gallery interface.
Component Gallery Class Library (Vpfgallery.vcx)

Explains how the Visual FoxPro Component Gallery class library, Vpfgallery.vcx, provides the item types as classes.
Component Gallery Table Structure

Describes the table structure of the Visual FoxPro Component Gallery.

Related Sections

Development Productivity Tools

Provides information on developer tools provided for application development within the Visual FoxPro application and the language.
IntelliSense Overview

Provides information on IntelliSense, which displays information in popup windows and drop-down lists that assist you with statement and function completion syntax.
Coverage Profiler Application

Discusses a coverage application, which writes information about which lines of code in a file were run, and a profiler application, which provides information about which lines actually run, how many times a line is run, duration, and so on.
Project Manager Hooks

Describes how you can access a project programmatically, making it possible for you to manipulate a project as an object.
Automating Keystroke Tasks with Macros

Describes how you can record and save keystrokes in macros by using the Macros dialog box.


How to: Manage Projects with the Component Gallery

Visual FoxPro 9.0
How to: Manage Projects with the Component Gallery
See Also

You can use the Component Gallery to create Projects and Applications and to manage their development. Use the Component Gallery to arrange components within the Component Gallery or use the templates, builders, and wizards in the Component Gallery to create the project or application you want.

The Component Gallery folders represent an arbitrary grouping of gallery items. You can reassemble the gallery items using drag and drop or you can duplicate items into other folders. You can copy and rename a catalog or folder and reassemble the items it contains. There are few, if any, limits on how you can use, modify, or create catalogs or folders.

The default settings for catalogs and folders enable you to perform basic review and management with gallery items. If you want to modify characteristics of catalogs or folders, or if you want greater access to gallery properties, select Advanced editing enabled in the Component Gallery Options dialog box.

To create a project or an application from the Component Gallery

  • Use the Application Wizard or New Application template in the Applications folder of the Visual FoxPro catalog.

For catalogs and folders, select tabs and options for the change you want to make. For details, see Component Gallery Options dialog box in Help.

Moving and Viewing Items in the Component Gallery

You can move items in the right, Object, pane of the Component Gallery window to the desktop or to an open project or form. The Project Manager recognizes the item referenced by the Component Gallery item and places it in the proper location in the Project Manager. Component Gallery items placed on the desktop are nonfunctional. There is no desktop representation for the Database, Folder, and gallery items representing nonvisual files.

To move items from the Component Gallery

  1. In the right pane, click the item you want to move.

    The Move icon, located in the upper-left corner of the Component Gallery window, changes according to what item you select.

  2. Drag and drop the Move icon to the desktop or to an open project or form.

When the Component Gallery cannot find the original item represented by the gallery item, a Find dialog box opens so that you can locate the item.

The following table identifies the gallery items included in Visual FoxPro and their default behaviors.

Component Gallery Item Type | Project | Form | Screen | Controls
Class (_ClassItem) |  |  | 6 |
File (_FileItem) |  |  |  |
URL (_UrlItem) |  | 1 |  |
Form (_FormItem) |  | 9 | 11 |
Report (_ReportItem) |  | 9 | 11 |
Program (_ProgramItem) |  |  | 11 |
Menu (_MenuItem) |  | 10 | 11 |
Image (_ImageItem) |  | 2 | 7 | 2
Sound (_SoundItem) |  | 3 |  |
Video (_VideoItem) |  | 3 |  |
ActiveX (_ActiveXItem) |  |  |  |
Data (_DataItem) |  | 4 |  |
Template (_TemplateItem) | 5 |  |  |
Catalog (_CatalogItem) |  |  | 8 |
Sample (_SampleItem) |  |  |  |
Project (_ProjectItem) |  |  | 11 |

1 – Add hyperlink class 2 – Add an image class or set a Picture property 3 – Add a multimedia class 4 – Add a grid class 5 – Depending on the type (for example, form) creates a new file and adds it to the project 6 – Creates an instance in Screen 7 – Sets the Visual FoxPro wallpaper 8 – Launches a new Gallery window with that catalog 9 – Add a Button class to launch a form/report 10 – Add a shortcut menu to a form 11 – Opens in a designer (modifies)

Reviewing and Modifying Classes

Because Component Gallery items represent real items that can be objects or classes, you can review or modify these classes by accessing the original object through the Component Gallery.

To review a class

  1. In the Component Gallery, right-click a class.

  2. On the shortcut menu, click View in Browser.

    This opens the Class Browser, so you can view the properties and methods of the selected class.

To modify a class

  1. In the Component Gallery, right-click a class.

  2. On the shortcut menu, click Modify.

    This opens the class in the Class Designer.

Creating and Modifying Forms

You can use the Component Gallery to duplicate or modify forms and to add forms and other gallery items to a project.

To create a form from the Component Gallery

  • Double-click any template or select New Form from the shortcut menu of any template in the Forms folder of the Component Gallery.

    -or-

    Double-click the Form Wizard in the Forms folder of the Component Gallery.

    -or-

    Select Create Form from the shortcut menu of Component Gallery items in the Forms folder of the Component Gallery.

See Also

Other Resources

Using the Component Gallery
Component Gallery Catalogs
Development Productivity Tools
How to: Customize the Component Gallery
Component Gallery Object Members


Component Gallery Catalogs

Visual FoxPro 9.0
Component Gallery Catalogs
See Also

When you open the Component Gallery, the left, Catalog, pane displays the default catalog shipped with the Component Gallery. A catalog is a visual representation of items that belong to a Visual FoxPro or user-defined group of items. Within a catalog you can create folders to further organize subgroups of items. Items can be forms, queries, programs, templates, art files, sound files, or other objects. The Visual FoxPro Component Gallery default catalog includes items grouped into several categories, including forms, controls, and others. The default catalog also includes an empty folder named Favorites that you can use to create or copy gallery items into. You can also copy and rename the default catalog, or create your own catalogs.

Component Gallery catalog options are set for catalog content and opening behavior. Global catalogs can contain any Component Gallery item type. Default catalogs open automatically when you start the Component Gallery. For details, see the Catalogs tab of the Component Gallery Options dialog box in Help.

The Component Gallery includes the following catalogs.

Catalog | Description
VFPGLRY | Contains components used by other catalogs in the gallery. Contains all the catalogs shipped with Visual FoxPro. Default and Global catalog.
Visual FoxPro | Contains the Visual FoxPro Foundation classes. Default catalog.
Favorites | An empty folder. Global catalog
My Base Classes | Contains subclassed Visual FoxPro base classes. Default catalog
ActiveX | A dynamic catalog containing either a list of all registered ActiveX Controls or a list of all Visual FoxPro ActiveX Controls. Default catalog.
World Wide Web | A collection of Web site URLs
Multimedia | A variety of images, sounds, and video items you can use in your applications
Samples | References to the Solutions, ActiveX Servers and Client/Server samples

When you click a catalog in the list view, the right, Object, pane, displays the contents of that catalog. You can open other catalogs by double-clicking the catalog in either panel. Several Catalogs are included in the Gallery folder.

See Also

Other Resources

How to: Manage Projects with the Component Gallery
How to: Customize the Component Gallery
Component Gallery Object Members
Component Gallery Class Library (Vpfgallery.vcx)
Development Productivity Tools
Using the Component Gallery


How to: Customize the Component Gallery

Visual FoxPro 9.0
How to: Customize the Component Gallery
See Also

You can customize the Component Gallery by changing the default behavior of catalog, folder, and gallery items through the appropriate Properties dialogs.

To create a Component Gallery catalog

  1. Select the Options button on the Component Gallery toolbar.

  2. Click the Catalogs tab in the Component Gallery Options dialog box.

  3. Click New and name the new catalog in the Open dialog.

  4. Click OK.

  5. The Component Gallery adds the catalog to the treeview so you can begin using it as you would any existing catalog.

To change a catalog or folder configuration

  1. Right-click the catalog or folder.

  2. From the shortcut menu, click Properties.

  3. In the Catalog Properties dialog box or Folder Properties dialog box, select the tab containing the options you want to configure.

    Gallery catalogs and folders, as displayed in the Component Gallery window Catalog pane, can represent URLs, folders, or files on your hard disk. You can view a Gallery folder as Web view or as an Explorer-level view, depending on the way you specify the name in the General tab of the Folder properties dialog.

Web Views

You can specify URLs or files as Gallery catalogs or as Gallery items. When you configure an item as a Gallery folder, the item automatically opens as a Web view in the Object (right) pane when you select it in the Catalog pane.

To configure a Gallery catalog or folder as a Web view

  1. In the Folder Properties Dialog Box, select the Node tab.

  2. In the Dynamic folder field, specify the Web page or file name as in the following examples:

    http:\\www.microsoft.com\

    file:\\c:\my documents\testpage.htm

    file:\\c:\my documents\Wordfile.doc

When you highlight the Web view icon in the Catalog pane, the toolbar changes to include Web navigation buttons. The Web view will reflect the settings of your Windows Explorer.

Explorer-level Views

You can specify a directory as a Gallery folder or catalog that has characteristics of Windows Explorer.

To configure a Gallery catalog or folder as an Explorer-level view

  1. In the Folder Properties Dialog Box, select the Node tab.

  2. In the Dynamic folder field, specify a folder or file name and backslash (\) as the value as in the following examples:

    C:\My Documents\

    Note:
    This specification creates a view of actual files, unlike other Component Gallery views. In this view you can delete files from your disk. To create an Explorer-level view that maintains protection of displayed files, specify the target using a wildcard designation as in the following example:

    C:\My Documents\*.*

Avoid using wildcards to create dynamic folders when you can expect to find more than 512 items, unless you have a fast machine with a large amount of RAM.

See Also

Other Resources

Component Gallery Catalogs
Component Gallery Object Members
Development Productivity Tools
Using the Component Gallery
Component Gallery Class Library (Vpfgallery.vcx)


Component Gallery Object Members

Visual FoxPro 9.0
Component Gallery Object Members
See Also

The Component Gallery is comprised of an interface, whose classes are contained in Vfpglry.vcx, and items that reference the following Visual FoxPro Foundation Classes.

Object | Description | Class library
About Dialog Box | Provides a simple About dialog box for custom applications. | _dialogs.vcx
ActiveX Calendar | A calendar control that can be tied to a date field. | _datetime.vcx
Application Registry | Provides a set of registry functions that return application-specific information. | Registry.vcx
Array Handler | Provides methods for handling array operations not performed by native product array functions. | _utility.vcx
Cancel Button | Releases a form and discards any outstanding buffered data. | _miscbtns.vcx
Clock | A simple clock control for a form or container. | _datetime.vcx
Conflict Catcher | A dialog box for resolution of row conflicts encountered while editing under optimistic buffering. | _dataquery.vcx
Cookies | A simple Web class for handling cookies between Web pages. | _internet.vcx
Cross Tab | Generates a cross tab. | _utility.vcx
Data Edit Buttons | A complete set of edit buttons (as used by Form Wizards). | Wizbtns.vcx
Data Navigation Buttons | A Top, Next, Prev, Bottom navigation button group and the DataChecker class to check for conflicts when moving records. | _datanav.vcx
Data Navigation Object | A nonvisual navigation object that other classes can use. | _table.vcx
Data Session Manager | Manages data sessions and handles data updates. | _app.vcx
Data Validation | Traps for data conflicts on buffered data. | _datanav.vcx
DBF -> HTML | Converts a Visual FoxPro cursor (.dbf) to HTML. | _internet.vcx
Distinct Values Combo | Performs a lookup of unique values from the controlsource field to populate a combo box. | _dataquery.vcx
Error Object | A generic error handler that works for both object and procedural code. | _app.vcx
Field Mover | A supermover list box that automatically loads fields from current data source. | _movers.vcx
File Version | Retrieves information from the version resource of a file. | _utility.vcx
Filter Button | Displays dialog to specify a data filter on a particular field. | _table2.vcx
Filter Dialog | A dialog that enables you to specify filter conditions on data. | _table.vcx
Filter Expression Dialog | Creates an advanced filter expression dialog. | _table.vcx
Find (Findnext) Buttons | A generic find/findnext buttonset. | _table.vcx
Find Button | Locates a record based on specific criteria. | _table.vcx
Find Dialog | A find dialog with simple options such as Field choice. | _table.vcx
Find Files/Text | Uses the Filer.DLL COM object to search for files. | _utility.vcx
Find Object | Creates a generic object that locates a record based on specified critereria. | _table.vcx
Font Combobox | A combo box that lists available fonts. It is also used by tbrEditing and rtfControls classes. | _format.vcx
Fontsize Combobox | A combo box that lists available font sizes. It is also used by tbrEditing and rtfControls classes. | _format.vcx
Format Toolbar | Provides a toolbar for applying font formatting to text of the active control. | _format.vcx
FRX -> HTML | Converts a Visual FoxPro reporting output (.frx) to HTML. | _internet.vcx
GetFile and Directory | Retrieves both a file and a folder name. | _controls.vcx
Goto Dialog Box Button | Creates a button that displays the Goto dialog box. | _table2.vcx
Goto Dialog Box | Creates a Goto record dialog box. | _table.vcx
Graph By Record Object | A navigation button group that allows you to refresh a new graph per record on the fly. | _utility.vcx
Graph Object | Generates a Graph using the core Graph Wizard engine. | Autgraph.vcx
Help Button | Displays the Help file as it starts searching for the specified HelpContextID. | _miscbtns.vcx
Hyperlink Button | Launches a Web browser from a button. | _hyperlink.vcx
Hyperlink Image | Launches a Web browser from an image. | _hyperlink.vcx
Hyperlink Label | Launches a Web browser from a label. | _hyperlink.vcx
INI Access | A set of registry functions that access old INI-style file settings. | Registry.vcx
Item Locator | This button brings up a dialog to locate a record. | _dialogs.vcx
Keywords Dialog | Creates a dialog like the Component Gallery keywords dialog. | _dialogs.vcx
Launch Button | Launches an application with an optional document. | _miscbtns.vcx
Locate Button | Displays a dialog to locate a record. | _table2.vcx
Lookup Combobox | Performs a lookup of values in a field to populate a combo box. | _dataquery.vcx
Mail Merge Object | Generates a Word Mail Merge using the core Mail Merge Wizard engine. | Mailmerge.vcx
Messagebox Handler | A simple wrapper around the MessageBox function. | _dialogs.vcx
MouseOver Effects | Highlights a control as the mouse passes over it. | _ui.vcx
Mover | Provides a simple mover list box class with move/remove buttons. | _movers.vcx
Navigation Shortcut Menu | A shortcut menu that can be dropped onto a form. | _table2.vcx
Navigation Toolbar | A set of navigation buttons in a toolbar. | _table2.vcx
Object State | Determines the state of an object and saves/restores the object property settings. | _app.vcx
ODBC Registry | A set of registry functions that return ODBC-specific information. | Registry.vcx
Offline Switch | Provides a view of online data for use offline. | _dataquery.vcx
OK Button | Performs a simple form release. | _miscbtns.vcx
Output Control | Displays a complex dialog box that prompts the user for a reporting output option. | _reports.vcx
Output Dialog | Displays a dialog box that prompts the user for a reporting output option. | _reports.vcx
Output Object | Various reporting output options. | _reports.vcx
Password Dialog | A simple Password dialog for custom applications. | _dialogs.vcx
Pivot Table | Generates a Microsoft Excel Pivot Table using the core PivotTable Wizard engine. | Pivtable.vcx
Preview Report | A generic button to run a report. | _miscbtns.vcx
QBF | Provides a buttonset for Query-By-Form querying. | _dataquery.vcx
Registry Access | Provides access to information in the Windows Registry. | registry.vcx
Resize Object | Causes form objects to resize/move with the Form's resize event. | _controls.vcx
RTF Controls | Provides a set of buttons for applying font formatting to text of the active control. | _format.vcx
Run Form Button | A button that runs a form. | _miscbtns.vcx
SCX -> HTML | Converts an .scx form to HTML. | _internet.vcx
SendMail Buttons | Uses the MAPI ActiveX Control to send a mail message from a form. | _miscbtns.vcx
Shell Execute | Provides Windows Explorer double-click behavior. | _environ.vcx
Shortcut Menu Class | This wrapper class dynamically creates shortcut pop-up menus. | _menu.vcx
Simple Edit Buttons | Provides simple Add, Edit, Delete, Duplicate, Save, and Cancel buttons (as used by Form Wizards). | Wizbtns.vcx
Simple Navigation Buttons | Provides a set of Next and Previous navigation buttons. | _table.vcx
Simple Picture Navigation Buttons | This is a set of simple picture navigation buttons. | _table2.vcx
Sort Button | Displays a dialog that enables you to perform an ascending or descending data sort on a particular field. | _table2.vcx
Sort Dialog | Enables you to perform an ascending or descending data sort on a particular field. | _table2.vcx
Sort Mover | This subclass of the supermover list box class automatically handles sorting of data. | _movers.vcx
Sort Object | Performs a sort on a data source. | _table.vcx
Sort Selector | Performs an ascending or descending sort based on the current control. | _table2.vcx
Sound Player | This class loads and plays a sound file. | _multimedia.vcx
Splash Screen | Provides a simple Splash Screen for custom applications. | _dialogs.vcx
SQL Pass Through | Provides SQL Pass-Through and can allow you to execute stored procedures on your host database. | _dataquery.vcx
Stop Watch | Provides a stop watch control for a form or container. | _datetime.vcx
String Library | Performs various string conversions. | _utility.vcx
Super Mover | Provides Move, Remove, Moveall, and Removeall buttons. | _movers.vcx
System Toolbars | A manager class that handles and tracks Systoolbars. | _app.vcx
Table Mover | This subclass of the supermover list box class automatically loads tables and fields from the current data source. | _movers.vcx
Text Preview | Provides a viewer of output text. | _reports.vcx
Thermometer | Provides a standard thermometer class. | _controls.vcx
Trace Aware Timer | This is an application utility that determines whether the trace window is open. | _app.vcx
Type Library | The main routine ExportTypeLib creates a text file with Typelib output. | _utility.vcx
URL Combo | Creates a combo box for typing in a Web URL. It launches Microsoft Internet Explorer and navigates to the site. | _internet.vcx
URL Open Dialog | Provides a dialog that creates a drop-down list that stores URL history. | _internet.vcx
VCR Buttons | A Top, Next, Prev, and Bottom navigation button group. | _table.vcx
VCR Picture Navigation Buttons | A set of VCR picture navigation buttons. | _table2.vcx
Video Player | Loads and plays a video file using MCI commands. | _multimedia.vcx
Web Browser control | A subclass of the Internet Explorer 4.0 Browser control, which provides hooks for Visual FoxPro code. | _webview.vcx
Window Handler | Performs several common window operations typical of applications. | _ui.vcx

For details on these class libraries, see Visual FoxPro Foundation Classes A-Z. For information on how to use the foundation classes, see Guidelines for Using Visual FoxPro Foundation Classes.

See Also

Other Resources

How to: Customize the Component Gallery
Development Productivity Tools
Using the Component Gallery
Component Gallery Class Library (Vpfgallery.vcx)
Component Gallery Table Structure


Component Gallery Class Library (Vpfgallery.vcx)

Visual FoxPro 9.0
Component Gallery Class Library (Vpfgallery.vcx)
See Also

The Component Gallery class library, Vpfgallery.vcx, provides the item types as classes.

Item type Description

Class (_ClassItem)

The generic item type for any Visual FoxPro class. This can be either from .vcx or .prg files.

File (_FileItem)

This is any file. Visual FoxPro reads the Registry for shell functions and adds them to the menu. The gallery includes a look up routine that checks for specific extensions and redirects the item type.

The gallery supports UNC naming conventions for team development (sharing of Catalogs across networks).

ActiveX (_ActiveXItem)

This is an ActiveX Control or Server such as an .ocx created by Visual Basic CCE or .exe/.dll created by Visual FoxPro.

Data (_DataItem)

This is a Visual FoxPro datasource (.dbc, .dbf, View, and so forth.).

Image (_ImageItem)

This is a File Item Type whose file has an image file extension such as .bmp, .jpg, .gif, .ico, .cur, .ani, and so on.

Sound (_SoundItem)

This is a File Item Type whose file has either a .wav or .rmi extension.

Video(_VideoItem)

This is a File Item Type whose file has a .avi extension.

URL (_UrlItem)

This is a Web Item Type and includes Web and local documents such as HTML files.

Sample (_SampleItem)

This is a File Item Type for files that run in Visual FoxPro and can be an executable Visual FoxPro file such as .app, .exe, .prg, .scx, or .frx files.

Template (_TemplateItem)

This is a Script Item Type that opens a builder for the Visual FoxPro element represented by the type of the highlighted item, including forms and reports.

Catalog (_CatalogItem)

This is a Component Gallery type that allows you to Add and Open Visual FoxPro catalogs.

Form(_FormItem)

This is a type for Visual FoxPro forms (.scx).

Report (_ReportItem)

This is a type for Visual FoxPro reports (.frx).

Menu (_MenuItem)

This is a type for Visual FoxPro menus (.mnx).

Program (_ProgramItem)

This is a type for Visual FoxPro programs (.prg).

Project (_ProjectItem)

This is a type for Visual FoxPro projects (.pjx).

You can use the Class Browser to examine the details of any of these classes.

For details on other classes used in the Component Gallery, see Visual FoxPro Foundation Classes A-Z or use the Class Browser to examine the libraries in the Ffc folder.

See Also

Other Resources

Component Gallery Object Members
Component Gallery Table Structure
Development Productivity Tools
Coverage Profiler Application
Using the Component Gallery


Component Gallery Table Structure

Visual FoxPro 9.0
Component Gallery Table Structure
See Also

The Visual FoxPro Component Gallery is described in the following table structure.

Field | Field Name | Type | Width | Index
1 | TYPE | Character | 12 | No
2 | ID | Character | 12 | No
3 | PARENT | Memo | 4 | No
4 | LINK | Memo | 4 | No
5 | TEXT | Memo | 4 | No
6 | TYPEDESC | Memo | 4 | No
7 | DESC | Memo | 4 | No
8 | PROPERTIES | Memo | 4 | No
9 | FILENAME | Memo | 4 | No
10 | CLASS | Memo | 4 | No
11 | PICTURE | Memo | 4 | No
12 | FOLDERPICT | Memo | 4 | No
13 | SCRIPT | Memo | 4 | No
14 | CLASSLIB | Memo | 4 | No
15 | CLASSNAME | Memo | 4 | No
16 | ITEMCLASS | Memo | 4 | No
17 | ITEMTPDESC | Memo | 4 | No
18 | VIEWS | Memo | 4 | No
19 | KEYWORDS | Memo | 4 | No
20 | SRCALIAS | Memo | 4 | No
21 | SRCRECNO | Numeric | 6 | No
22 | UPDATED | DateTime | 8 | No
23 | COMMENT | Memo | 4 | No
24 | USER | Memo | 4 | No

See Also

Other Resources

Component Gallery Class Library (Vpfgallery.vcx)
Coverage Profiler Application
Development Productivity Tools
Using the Component Gallery
Component Gallery Object Members


Coverage Profiler Application

Visual FoxPro 9.0
Coverage Profiler Application

A coverage application writes information about the lines of code in a file that run. A profiler application provides information about the lines that were actually run, how many times a line is run, duration, and more. Coverage and profiling enable a developer to identify problem areas in an application, especially skipped code and performance bottlenecks.

The Visual FoxPro Coverage Profiler is provided in two parts, a Coverage engine object you can use or customize and a multiple window application you can use to analyze programs and projects. The Coverage Profiler source files are not installed by default. To use these files, expand the XSource.zip file in the \Tools\XSource folder of the main Visual FoxPro directory.

The Coverage Profiler application (Coverage.app) provides several ways to view the data provided by the Coverage engine. Coverage.app is a subclass of the Coverage engine class. You can automate coverage or modify the user interface to suit your needs, run Coverage.app in unattended mode and not display the application window, or use engine features without using the interface.

When starting up, Coverage.app suspends coverage logging enabled with the SET COVERAGE command. When you release the coverage object, the application provides a choice to restore the SET COVERAGE setting.

In This Section

Coverage Profiler Log File

Describes how the Visual FoxPro Coverage Profiler uses a log file, which consists of records in comma-delimited lines.
How to: Examine Application Coverage and Profile

Provides information about how the Coverage Profiler can provide accurate and useful information about your project or application.
Coverage Profiler Modification

Describes how to change the default setting of the Coverage Profiler application so that it can run inside the main Visual FoxPro window, instead of in a separate window.
Coverage Profiler Add-Ins

Describes how to write add-ins and enhance the Coverage Profiler application.
How to: Log Code Coverage

Explains how code coverage gives you information about which lines of code have been executed and how long it took to execute them. You can use this information to refine your code for performance and ensure that you've adequately tested the code.
Conserving Disk Space During Coverage Runs

Discusses how you can change the size of some of the engine work table fields to make these tables somewhat smaller to avoid "out of disk space" errors during coverage runs.
Coverage Engine Object

Describes the Coverage engine class and its properties, methods, and events.

Related Sections

Development Productivity Tools

Provides information on developer tools provided for application development within the Visual FoxPro application and the language.
IntelliSense Overview

Provides information on IntelliSense, which displays information in popup windows and drop-down lists that assist you with statement and function completion syntax.
Project Manager Hooks

Describes how you can access a project programmatically, making it possible for you to manipulate a project as an object.
Automating Keystroke Tasks with Macros

Describes how you can record and save keystrokes in macros by using the Macros dialog box.


Coverage Profiler Log File

Visual FoxPro 9.0
Coverage Profiler Log File
See Also

Coverage Profiler uses a log file generated by Visual FoxPro when you use the Coverage option in the Debugger Tools menu or use SET COVERAGE TO as in the following command:

Copy Code
SET COVERAGE TO cCoverage.log

When you use the command, the ADDITIVE clause allows you to avoid overwriting an existing log. This command starts data streaming and opens the file cCoverage.log, a text file that will gather the stream of details on the file or application you examine.

A coverage log file consists of records in comma-delimited lines. The following list describes the structure of each record.

Item | Description
1 | execution time
2 | class executing the code
3 | object, method, or procedure in which the code is found or called
4 | line number within the method or procedure
5 | fully defined file
6 | call stack level

After specifying the log file name, run the program or application you want to examine. When you end the program you can use the SET COVERAGE TO command to stop the data stream to the coverage log.

You can view the coverage log by starting Coverage Profiler from the Tools menu or by using DO as in the following command:

Copy Code
DO (_COVERAGE) [WITH cCoverage]

Visual FoxPro prompts you for the name if you do not specify a log file. The _COVERAGE System variable in Visual FoxPro defaults to the Coverage Profiler application, Coverage.app.

See Also

Other Resources

Component Gallery Table Structure
How to: Examine Application Coverage and Profile
Development Productivity Tools
Using the Component Gallery
Coverage Profiler Application


How to: Examine Application Coverage and Profile

Visual FoxPro 9.0
How to: Examine Application Coverage and Profile
See Also

To use the Coverage Profiler effectively, prepare your application and your environment carefully. If you use the following guidelines, the Coverage Profiler can provide accurate and useful information about your project or application.

To use the Coverage Profiler to examine application coverage

  1. Use the Coverage Logging option of the Debugger Tools menu or the SET COVERAGE command to start the coverage data stream and to open the file to log that data.

  2. Run the program or application you want to examine for coverage.

  3. Run the coverage application from the Tools menu or use DO (_COVERAGE) in the command window.

    The Coverage Profiler application starts in Coverage Mode by default.

To use Coverage Profiler to examine application profile

  1. Use the SET COVERAGE command to start the coverage data stream and to open the file to log that data.

  2. Run the program or application you want to profile.

  3. Run the coverage application from the Tools menu or use DO (_COVERAGE) in the command window.

  4. Click the Profile Mode button in the Coverage Profiler dialog box.

    If you find that you are most often interested in profiling, you can change the default to Profile Mode in the Coverage Profiler Options dialog box.

To use the Coverage Profiler with a specific log file

  • Run the coverage application using the WITH option and the log file name as in the following example:

    Copy Code
    DO (_COVERAGE) WITH "Mylog.LOG"

    This example uses the log file Mylog.log and opens the Coverage Profiler application window to display the results. If you specify no file name, the Coverage Profiler uses the log specified in a current SET COVERAGE TO command or displays the Open file dialog box when coverage logging is OFF.

To use the Coverage Profiler without the User Interface

  • Run the coverage application using the WITH option and specify true (.T.) for unattended mode running as in the following example:

    Copy Code
    DO (_COVERAGE) WITH "Mylog.LOG",.T.

    In this example, the Coverage Profiler application uses the log file Mylog.log and runs without displaying the Coverage Profiler application window.

To use the Coverage Profiler with a specific Add-In file

  • Run the coverage application using the WITH option and the add-in file name as in the following example:

    Copy Code
    DO (_COVERAGE) WITH "Mylog.LOG",, "add_ui.prg"

    This example uses the log file Mylog.log and opens the Coverage Profiler application window to display the results, and then the Add-In program ADD_UI.PRG runs. The second, unspecified, parameter is a logical value that specifies whether the coverage engine operates in unattended mode. In the default setting, false (.F.), the Coverage Profiler window displays.

Besides viewing the profiler information, you can insert comments or markers and you can save the information as a file to use later.

See Also

Other Resources

Coverage Profiler Modification
Development Productivity Tools
Coverage Profiler Add-Ins
Project Manager Hooks
Coverage Profiler Application


Coverage Profiler Modification

Visual FoxPro 9.0
Coverage Profiler Modification
See Also

By default the Coverage Profiler application runs in a separate window. You can reconfigure it to run inside the main Visual FoxPro window by changing the Environment Option. In the Coverage Profiler Options dialog box, change the Environment selection from Coverage frame to FoxPro frame, and then restart the Coverage Profiler.

You can also use the Coverage Profiler Options dialog box to modify the following Coverage Profiler characteristics.

Characteristic | Description
Add-Ins | Specifies whether Add-Ins are registered in the Coverage Profiler as they are used. For more information, see the section, "."
Coverage Marks | Specifies whether the Coverage Profiler marks code that is run or code that is not run. Specifies the character(s) used to mark code. Specifies when code is marked.
Fonts | Specifies the fonts used in the Coverage Profiler as code and in displays.
Smart Pathing | Specifies whether Coverage Profiler automatically seeks files in previously specified locations.
Start Mode | Specifies whether Coverage Profiler opens in Coverage or Profile Mode.

Ensuring Relevance in the Coverage Profiler

To help ensure that the files processed by the Coverage Profiler are the correct files:

  • Set your project directory as the default before you start coverage logging so that the referenced files are relative.

  • Avoid renaming objects dynamically. The Coverage Profiler will not find objects if you rename them at run time.

  • Avoid using source files with exactly the same root name, even with different extensions. Internally, the Coverage Profiler cannot distinguish between them.

  • Make sure that your project contains only the correct versions of much-modified files.

  • Make sure your project does not contain multiple copies of a file in subdirectories.

  • Perform a compile for the coverage run:

    • Make sure Debug information is in your application.

    • Turn Encrypt OFF.

    • Use RECOMPILE or Build All to force a fresh compile of all source code.

    • Perform the compile immediately before the coverage run so that you know that the source code exactly matches the object code.

Some lines in code, such as comments, DEFINE CLASS and ELSE statements, and lines within TEXT ... ENDTEXT do not appear in coverage logs because they are not even potentially executable. Also, lines broken by continuation symbols (semicolons) are considered as a single line of code and marked only on the last line.

See Also

Other Resources

How to: Examine Application Coverage and Profile
Coverage Profiler Add-Ins
Development Productivity Tools
Coverage Profiler Application
Project Manager Hooks


Coverage Profiler Add-Ins

Visual FoxPro 9.0
Coverage Profiler Add-Ins
See Also

Add-Ins are code files (usually .prg or .scx) that provide an easy way for you to adjust the Coverage Profiler. The cov_standard subclass of the coverage engine, which comprises the User Interface of Coverage.app, shows only a small part of what you can do with the engine. The engine analyzes the coverage log; cov_standard just displays the results in one of many ways you could want to see them.

You could create a different subclass of cov_engine with a very different display. For example, your subclass might display a dialog that runs queries against the coverage statistics gathered by the engine. The display options might provide a view of the marked code for a filtered set of log entries, or only a graph of the profiling results.

You might not want to subclass cov_engine to create a new interface from scratch because the cov_engine class provides an easier process. You can add functionality to cov_standard, or any cov_engine subclass, using Add-Ins. Cov_standard exposes this feature through a button in the main dialog of Coverage Profiler. When you run an Add-In on an instance of cov_standard such as Coverage Profiler, the Add-In can manipulate the capabilities of cov_engine, the coverage tables, as well as cov_standard. Add-Ins might also add new dialogs and features to the cov_standard visual interface.

Writing Add-Ins

You can write Add-Ins to enhance the standard interface or you can subclass cov_standard to create your own wholly new interface.

Enhancing the Standard Application

The following list includes features you might want to provide through Add-Ins:

  • Add a visible feature to the main dialog.

  • Add a dialog into the coverage engine formset (reference limitation below on how to make sure your dialog shows up in the right place).

  • Display a separate dialog that accesses a Coverage engine feature (reference limitation below on how to make sure your dialog shows up in the right place).

  • Provide a querying interface that uses the Source table and presents a list of all lines that meet your criteria, and filters or orders the results.

    Note:
    You can use the Adjust... methods (AdjustCoverageFilenameCursor(), AdjustSourceCursor(), and AdjustTargetCursor()) of the Engine to add fields to the Source and Target tables when the engine creates them, and use these fields in your Add-Ins.

  • Add file names to the IgnoredFiles cursor, to eliminate those files from analysis. This can save analysis time.

  • Use the special Init hook for Add-Ins.

  • Register Add-Ins for retrieval and easy access to a list of Add-Ins.

    The modal dialog class cov_AddInDialog in the standard coverage engine subclass, presents previously registered dialogs in a drop-down list. When you set the coverage engine lRegisterAdd-In option ON, the full path name of successfully run Add-Ins are added to the Windows Registry so you can easily run these Add-Ins again. The Standard UI class also allows you to set this property in the Coverage Profiler Options dialog box.

    The Coverage Engine object maintains a list of all registered Add-Ins in the aAddIns property.

  • Use the final coverage.log field information, callstack, to design your own interface or your own view of the coverage log.

When you write Add-Ins, consider the following information:

  • You can use any of the supported file types as Add-Ins. The supported file types are .qpr, .qpx, .mpr, .mpx, .app, .exe, .scx, fxp, .prg and .procedures (if the procedures are already available in an open procedure library).

  • The Coverage Engine formset has an "invisible" toolbar. If your Add-In is nonvisual you can use this toolbar to contain it. If your Add-In is a visual control, the standard subclass main dialog .Cov_tools member container is probably the most convenient place to put it. This allows the position and size of the toolbar to be automatically synchronized with the rest of the dialog when it is resized.

  • All the engine methods that use the Source and Target tables take optional arguments that allow you to point these methods at the appropriate aliases while you're working with them. You can also change the current cSourceAlias and cTargetAlias property contents to match the pair of cursors in which you are interested. This allows you to compare multiple Coverage log runs to each other within the same interface.

  • Limitations:

    • Add-Ins must accept one parameter (the Coverage engine passes a reference to itself).

    • An Add-In must be one of the permitted file types, listed above.

    • Procedures you use as Add-Ins should be available in a currently loaded procedure library (see SET PROCEDURE Command) in Help. The Engine does not use the IN FileName syntax, and it does not call procedures or .prg files as functions and RETURN their values. It does not use the NAME or LINK keywords on the DO FORM command; you can either manage the reference yourself, or allow the Engine to scope a form for you by making your form a member of the Engine formset.

    • If you run an Add-In at startup, you must use a reference because the public _oCoverage variable is not yet available. At other times, you can use the public variable reference within your own code, if you prefer.

    • When you write an Add-In as a form, if you create the form as ShowWindow = 1 and run Coverage in its own frame, your Add-In forms should display in the Coverage frame.

    • If you use .RunAddIn from the Command window, make sure the coverage frame is the active MDI frame before you instantiate your forms.

Subclass Cov_Standard Class

You can subclass either the coverage engine or its standard subclass. The following list describes the structure of the COVERAGE project source file set.

File Description

Coverage.prg

A "wrapper" for the coverage object, which instantiates the object.

Coverage.vcx Coverage.vct

All classes for the engine and its standard subclass.

Cov_short.mnx Cov_short.mnt

Shortcut menu.

Cov_pjx.frx Cov_pjx.frt

Default mechanism to deliver project-level results.

Coverage.h

Header file for all Coverage code, incorporating the following elements:

*— Coverage character constants for log and parsing:

Copy Code
   #INCLUDE COV_CHAR.H

*— Coverage localized strings (can use some log and parsing constants):

Copy Code
   #INCLUDE COV_LOCS.H

*— Coverage common dialog component constants:

Copy Code
   #INCLUDE COV_DLGS.H

*— Coverage specs & requirements:

Copy Code
   #INCLUDE COV_SPEC.H

*— Coverage registry object constants:

Copy Code
   #INCLUDE COV_REGS.H

*— Coverage tune-able options:

Copy Code
   #INCLUDE COV_TUNE.H

The COVERAGE project source file set also includes various .ico .bmp, and .msk files.

Use the file COV_TUNE.H (containing appropriate comments and explanations) to become familiar with options available to you without rewriting code.

Because Add-In use is governed by the coverage engine base class, any other coverage subclass you create can use Add-Ins in the same manner as the standard subclass.

The coverage engine subclass instantiated by the default Coverage.app does not augment the coverage engine RunAddIn( ) method in any way. It does, however, invoke a modal dialog box to allow the user to pick an Add-In before it invokes the coverage engine RunAddIn( ) method. The modal dialog box receives a reference to the Coverage object and sets the coverage engine cAddIn property.

If you write your own coverage engine subclass, ensure that your subclass can use the same modal dialog class (cov_AddInDialog) to handle Add-Ins as the standard Coverage application; the dialog box does not rely on any features of the standard subclass.

You can call a different modal dialog box, set the cAddIn file name directly in the cAddIn property, or override the contents of the cAddIn property by passing the name of the Add-In file you wish to run to the RunAddIn( ) method.

However you access an Add-In to run in your subclass, you can investigate the list of Add-Ins registered to Coverage.app by checking the file names in the coverage engine aAddIns property.

For details on the Properties, Events, and Methods of the coverage engine, see Coverage Engine Object in Help.

See Also

Other Resources

Coverage Profiler Modification
Project Manager Hooks
Development Productivity Tools
Project Object Hierarchy
Coverage Profiler Application


How to: Log Code Coverage

Visual FoxPro 9.0
How to: Log Code Coverage
See Also Example

Later in the development process, you might want to refine your code for performance and ensure that you've adequately tested the code by logging code coverage information.

Code coverage gives you information about which lines of code have been executed and how long it took to execute them. This information can help you identify areas of code that aren't being executed and therefore aren't being tested, as well as areas of the code that you might want to fine tune for performance.

You can toggle code coverage on and off by clicking the Code Coverage toolbar button in the Debugger Window. If you toggle code coverage on, the Coverage Dialog Box opens so that you can specify a file to save the coverage information to.

You can also toggle coverage logging on and off programmatically by using the SET COVERAGE TO command. You could, for example, include the following command in your application just before a piece of code you want to investigate:

Copy Code
SET COVERAGE TO mylog.log

After the section of code you want to log coverage for, you could include the following command to set code coverage off:

Copy Code
SET COVERAGE TO

When you've specified a file for the coverage information, switch to the main Visual FoxPro window and run your program, form, or application. For every line of code that is executed, the following information is written to the log file:

  • How long in seconds the line took to execute.

  • The class, if any, that the code belongs to.

  • The method or procedure the line of code is in.

  • The number of the line of code.

  • The file that the code is in.

  • Call stack level in which the line of code executes.

The easiest way to extract information from the log file is to convert it into a table so that you can set filters, run queries and reports, execute commands, and manipulate the table in other ways.

The Coverage Profiler application creates a cursor from the data generated in coverage logging and uses this cursor in a window for easy analysis.

Example

The following program converts the text file created by the coverage log into a table:
Copy Code
cFileName = GETFILE('DBF')
IF EMPTY(cFileName)
   RETURN
ENDIF

CREATE TABLE (cFileName) ;
   (duration n(7,3), ;
   class c(30), ;
   procedure c(60), ;
   line i, ;
   file c(100))

APPEND FROM GETFILE('log') TYPE DELIMITED

See Also

Other Resources

Output Display
Handling Run-Time Errors
Testing and Debugging Applications
Debugger
Coverage Dialog Box
SET COVERAGE TO
Coverage Profiler Application


Conserving Disk Space During Coverage Runs

Visual FoxPro 9.0
Conserving Disk Space During Coverage Runs
See Also

If you experience "out of disk space" errors during coverage runs, you can change the size of some of the engine work table fields to make these tables somewhat smaller.

The default values of these fields are 115, because it allows for long path names and long object and method names. Values longer than 115 are not recommended, because two of these fields might be used in concatenated keys in which the sum of any two field lengths must not exceed the maximum key length (240).

Do not decrease the Hostfile field unless you are sure the lengths of your fully-qualified source files will not be exceeded. Otherwise, the engine might generate errors when it tries to find the uncompiled versions of these files.

If you know that you nest pageframes and grids several container-layers deep or that you tend to use very long class names, specify values greater than the maximum string length that ObjClass or Executing fields are likely to contain, plus a margin for error. You might want to examine the source and target files first to see how the engine uses these fields.

When you have decreased the size of the ObjClass or Executing fields, beware of suddenly-incorrect coverage and profiling statistics. Although the Profiler generates no obvious errors when the analyzing the log, statistical errors will occur if object and method names are being truncated in the fields.

Ordinarily, you use the iLenHostfile, iLenObjClass, and iLenExecuting property values to change the size of these fields. You can even change them dynamically while Coverage is open, before you open a coverage log that is unusually large.

Note:
When you have opened a log, do not change these values until you are ready to evaluate a new log, or you might experience statistical errors when new target entries' code is marked.

However, if you have set COV_TOPSPEED true (.T.) in the COV_TUNE.H header file, to increase speed by forcing the engine to make in-line calls, the engine uses constants also defined in COV_TUNE.H, rather than property values, to determine the size of these fields. (These values are used repeatedly, to ensure exact comparisons, as the engine parses lines of code.) If you set COV_TOPSPEED true (.T.), you must set the values in COV_TUNE.H directly.

See Also

Other Resources

Coverage Profiler Application
Coverage Engine Object


Coverage Engine Object

Visual FoxPro 9.0 Language Reference
Coverage Engine Object
See Also

The Coverage engine class is a subclass of the Visual FoxPro FormSet class. Though it provides no visible components, it provides the data session of a FormSet class and includes provisions for feedback on coverage log processing through the WAIT Command, MESSAGEBOX( ) Function, and subclasses of MSComDlg.CommonDialog.

Note:
This formset is not a subclass of _formset, therefore the Coverage Profiler runs in Visual FoxPro 5.0 and later.

Class | cov_engine
Class Library | coverage.vcx
Base Class | formset
Parent Class | scov_formset

For more information, see Coverage Profiler Application.

Remarks

This formset has one member, a toolbar, that remains hidden while providing a container for custom objects, such as CusRegistry or Dialog subclasses. Cov_standard, a subclass of cov_engine, provides a sample user interface, the Coverage Profiler Application. You can subclass either cov_engine or cov_standard to fit your requirements.

Properties, events, and methods Description

*.cStackXSLT Property

Holds filename providing default XSL Transformation stylesheet to be applied by default to the generated Stack XML analysis document, when TransformStackXML is called.

aAddIns array Property

This one-dimensional array holds a list of registered add-in files.

Default .F. (the array will be dimensioned [1])

aFileTypes array Property

This two-dimensional array holds a list of the file types (extensions) the Coverage Profiler handles. The first column holds the extension listed in the coverage text log (such as .fxp or .vct). The second column holds the extension of the matching source code file (such as .prg or .vcx) that the Coverage Profiler must locate to analyze the code. This array is filled at startup by the FillFileTypeArray( ) method.

Default .F. (the array will be dimensioned [1, 2])

cAddIn Property

Specifies the add-in last run successfully. At startup this property can be set by an add-in passed to the Coverage Profiler application as a parameter and run in the Init. Otherwise, if add-in file names have been stored to the registry previously, this property is filled using the aAddIns array.

Default ""

cBaseFontName Property

Specifies a base font name for any interface elements. The default for this attribute when no preference has been saved to the registry is the #DEFINE constant COV_DEFAULT_BASE_FONTNAME in COV_TUNE.H.

Default MS Sans Serif

cBaseMonoFontName Property

Specifies a base font name for any interface elements that require a monospaced font.

The default for this attribute when no preference has been saved to the registry is, first, any Visual FoxPro resource file entry for MODIFY Command window preferences. Otherwise, the coverage engine looks for a Visual FoxPro registry entry for the Trace window. If one of these is not found, the coverage engine uses the #DEFINE constant COV_DEFAULT_MONO_FONTNAME in COV_TUNE.H.

Default Courier New

cCovFilesAlias Property

Specifies the name of the cursor holding names of source files the Coverage Profiler should not locate and analyze. The engine fills this cursor with a set of file names using the CreateCoverageFileNameCursor( ) and FillCoverageFileNameCursor( ) methods. You can use the coverage engine abstract AdjustCoverageFileNameCursor( ) method to add file names to the set.

Default IgnoredFiles

cDefaultWritePath Property

Specifies the path to cSourceFile. Supplies the default path for any file output of the Coverage Profiler.

Default ""

cMarkExecuted Property

Specifies the character(s) that marks lines of code that executed according to the current coverage log. Although this property defaults to an empty string, the engine uses the SetMarks( ) procedure to adjust the length of cMarkExecuted and cMarkNotExecuted to equal lengths so the appearance of marked code is unspoiled. At startup, therefore, cMarkExecuted's value is SPACE(4), to match the default length of cMarkNotExecuted.

Default ""

cMarkNotExecuted Property

Specifies the character(s) that marks lines of code not run during the current coverage log.

Default |+SPACE(3)

cSavedSkipFiles Property

Specifies the name of the table (.dbf) file that contains the list of source files skipped during coverage analysis.

Default ""

cSavedStackXML Property

Holds the name of the saved Coverage stacklevel analysis in XML form, after this file has been saved to disk. Set back to default ("") when you load a new log.

cSavedTargetDBF Property

Specifies the name of the table (.dbf) file that contains the coverage results.

Default ""

cSkippedAlias Property

Specifies the name of the cursor which holds names of source files the Coverage Profiler could not locate or analyze. The engine fills this cursor using the CreateSkippedCursor( ) method and saves it to disk using the SaveSkippedCursor( ) method.

Default SkippedFiles

cSourceAlias Property

Specifies the name of the source which holds the appended and processed records stored by the coverage text log. The engine creates this cursor in the CreateSourceCursor( ) method and provides the abstract AdjustSourceCursor( ) method so you can add fields, index tags, and so on. Then the engine fills the cursor with records from the text log in the FillSourceCursor( ) method.

Default FromLog

cSourceFile Property

Specifies the name of the file to be analyzed. You can specify this value as the first parameter of the DO (_COVERAGE) WITH command.

Default ""

cSuspendedLog Property

Specifies the name of the current coverage log (SET(COVERAGE)) if the Coverage Profiler suspends coverage data logging. This property is set with the SuspendCoverage( ) method.

Default ""

cTargetAlias Property

Specifies the target cursor that holds the names of classes, source file names, coverage-marked procedure source code, and coverage statistics. The engine creates this cursor in the CreateTargetCursor( ) method and provides the abstract AdjustTargetCursor( ) method so you can add fields, tags, and so on. Then the coverage engine locates and analyses source code in the FillTargetCursor( ) method.

Default MarkedCode

iLenDuration Property

Specifies the length, including decimal places, of the numeric field in the source file.

Default 8 (in Visual FoxPro versions 5.0 and 6.0. Defaults to 11 in later versions.)

iLenExecuting Property

Specifies the length of the field in the source work file that contains information about the object and method name that is running covered lines of code when the #DEFINE COV_TOPSPEED in COV_TUNE.H is false (.F.).

You can decrease the default value, with care, if your fully qualified object names and method names are short and if you want to conserve the disk space used by the Profiler work files. See COV_TUNE.H for more information about this value. See Conserving Disk Space During Coverage Runs for more information on using iLenExecuting.

Default 115

iLenHostFile Property

Default 115

iLenObjClass Property

Specifies the length of a field in the source and target work files that holds information about the object executing Covered lines of code when the #DEFINE COV_TOPSPEED in COV_TUNE.H is false (.F.).

To conserve the disk space used by the Profiler work files, you can decrease the default value, with care, if your object names are short. You can do this even when object names are fully-qualified by their container hierarchy. See COV_TUNE.H for more information about this value. See Conserving Disk Space During Coverage Runs for more information on using iLenObjClass.

Default 115

lBaseFontBold Property

Specifies a base font attribute (bold) for any displayed characters.

Default .F.

lBaseFontItalic Property

Specifies a base font attribute (italic) for any displayed characters.

Default .F.

lBaseMonoFontBold Property

Specifies a base font attribute (bold) for any displayed characters that require a monospaced font.

Default .F.

lBaseMonoFontItalic Property

Specifies a base font attribute (italic) for any displayed characters that require a monospaced font.

Default .F.

lError Property

A flag that specifies an error occurred; set by the Error method and checked by critical operations during processing.

Default .F.

lInCoverageFrame Property

Specifies whether the Coverage Profiler opens in the main Visual FoxPro window. The default displays Coverage Profiler elements in a separate window.

Default .F.

lInProfileMode Property

Specifies whether the Coverage Profiler analyzes the coverage log for profiling characteristics. In the default setting, the Coverage Profiler analyses for coverage characteristics.

Default .F.

lMarkAllOnLoad Property

Specifies whether all source code is marked when a target file is loaded. In the default setting, individual source code records are marked one at a time as required by the user.

Default .F.

lSaveFormPositions Property

Specifies whether all forms in the formset receive an instance of cov_SavePosition to handle form positions and size.

Default .F.

lSmartPath Property

Specifies whether the engine retains a reference to directories in which you have located files.

Default .T.

lStackXMLExtendedTree Property

If .T., then it generates more extensive StackXML, so profiling of each branch can assess effects of args and other factors for different invocations of a module. Defaults to .F. but if COV_LOAD_STACK_FROM_DBF is .T., then this more extensive XML is generated always.

lStartInProfileMode Property

Specifies how the lInProfileMode property is set when each coverage log loads. This value is significant when the property lMarkAllOnLoad is set to true (.T.).

Default .F.

lTurnedOffTrace Property

Specifies whether the Coverage Profiler issued SET TRBETWEEN OFF during processing.

Default .F.

lUsingRegistry Property

Specifies whether user options are saved to and restored from the Microsoft Windows registry.

Default .T.

lUsingStatusBar Property

Determines whether feedback messages during processing are displayed in the status bar or as a WAIT WINDOW NOWAIT message. The status bar is used when the Coverage Profiler runs in the main Visual FoxPro window or in Unattended mode and STATUS BAR is ON.

Default .F.

lVFP5 Property

Specifies whether the Coverage Profiler is running in Visual FoxPro 5.0.

Default (ATC("FoxPro 05",VERSION( )) > 0)

nBasefontsize Property

Specifies a base font size for any displayed characters.

Default 11 (defaults to 8 in version 5.0 and 6.0)

oFrame Property

Specifies a reference to the Coverage Frame window when the Coverage Profiler exists in a separate window. The engine makes sure this window exists before displaying any related dialog boxes or other elements (including common dialog subclasses, SET TALK display, and so on).

Default .NULL.

*.TransformStackXML( ) Method

Syntax: TransformStackXML(tcXSLT, tcXMLIn, tcXMLOut, tlNoShow)

Return Value: Returns .T. if successful.

Parameters: tcXSLT Specifies the name of the XSL file.tcXMLIn Specifies the name of the XML input file.tcXMLOut Specifies the name of the XML output file.tlNoShow Specifies whether to call DisplayStackXML.

Remarks: Applies tcXSLT (default to .cStackXSLT) to tcXMLIn (default .cSavedStackXML, GetStackXML( ) called if empty). Saves result to tcXMLOut (defaults to tcXMLIn-based generated name w/ HTM ext). If ! tlNoShow, calls DisplayStackXML( ).

AddFormPositionSaver( ) Method

Adds an instance of cov_SavePosition to a form to save and restore form size and position.

Syntax: AddFormPositionSaver(toForm)

Return Values: None

Parameters: toForm Specifies that the cov_SavePosition object is saved to a form.

AddPath( ) Method

Extracts directory information to concatenate to SET(PATH).

Syntax: AddPath(tcFileName)

Return Values: None

Parameters: tcFileName Specifies a file name.

Remarks: Extracts the directory information from the passed file name, tcFileName, to concatenate into the current SET(PATH).

AddRegisteredAddin( ) Method

Adds file name to the aAddIns array.

Syntax: AddRegisteredAddin(tcFileToAdd)

Return Values: None

Parameters: tcFileToAdd Specifies the file to add to the aAddIns array.

Remarks: Adds a file name, TcFileToAdd, to the aAddIns array when called by the RunAddIn( ) method after an add-in runs successfully.

AdjustCoverageFilenameCursor( ) Method

Enables adding files to cursor list of unanalyzed files.

Syntax: AdjustCoverageFilenameCursor(tcTarget)

Return Values: NOT THIS.lReturn

Parameters: tcTarget Specifies the name of the cursor you want to modify.

Rema rks: Makes it possible for you to add files that you do not want analyzed to the cursor's file list when called by the CreateCoverageFilenameCursor( ) method. See the cCovFilesAlias property.

AdjustSourceCursor( ) Method

Abstract method that makes it possible for you to add index tags and custom fields to the source cursor when called by the CreateSourceCursor( ) method.

Syntax: AdjustSourceCursor(tcSource)

Return Values: NOT THIS.lReturn

Parameters: tcSource Specifies the name of the cursor containing the source records.

AdjustTargetCursor( ) Method

Abstract method called by the CreateTargetCursor( ) method makes it possible for you to add index tags and custom fields to the target cursor.

Syntax: AdjustTargetCursor(tcTarget)

Return Values: NOT THIS.lReturn

Parameters: tcTarget Specifies the name of the table being modified.

ClearStatus( ) Method

Removes a message from the status bar or performs a CLEAR WAIT WINDOW command. See lUsingStatusBar property.

Syntax: ClearStatus( )

Return Values: None

Parameters: None

CreateCoverageFilenameCursor( ) Method

Creates a cursor to hold the names of source files that the Coverage Profiler should not locate and analyze. See the cCovFilesAlias property.

Syntax: CreateCoverageFileNameCursor( )

Return Values: lReturn AND NOT THIS.lError

Parameters: None

CreateForms( ) Method

At startup, displays the Coverage Profiler window after workfiles have been set up if the coverage engine is not in Unattended mode. In the coverage engine base class, this method creates only the Coverage frame (if the engine is not running in the Visual FoxPro window). Subclasses can augment this method to add their own dialogs.

Syntax: CreateForms( )

Return Values: None

Parameters: None

CreateSkippedCursor( ) Method

The engine creates this cursor by looking for deleted records in the Source table, because skipped records are deleted when the engine encounters file names that cannot be located or that are in the Ignored Files list during its load of the log file. See the CSkippedAlias property.

Syntax : CreateSkippedCursor(tcSource, tcSkipped)

Return Values: NOT THIS.lError

Parameters: tcSource Specifies the name of the table containing the source records.TcSkipped Specifies the alias of the cursor containing the skipped records.

CreateSourceCursor( ) Method

Creates a source cursor in the following format:

Copy Code
CREATE CURSOR(cSource) ;
(Duration n(COV_LEN_DURATION,N_COVLOG_PRECISION), ;ObjClass c(COV_LEN_OBJCLASS), ;Executing c(COV_LEN_EXECUTING), ;Procline i, ;Hostfile c(COV_LEN_HOSTFILE), ;Stacklevel I, ;FileType c(4) )

The Stacklevel field is excluded when the value of the lVFP5 property is true (.T.). See COV_TUNE.H for #DEFINE field lengths.

Syntax: CreateSourceCursor(tcSource)

Return Values: lReturn AND NOT THIS.lError

Parameters: tcSource Specifies the name of the cursor containing the source records.

CreateTargetCursor( ) Method

Creates a target cursor in the following format:

Copy Code
CREATE CURSOR (cTarget) ;
(Hostfile c(COV_LEN_HOSTFILE), ;ObjClass c(COV_LEN_OBJCLASS), ;FileType c(4), ;Marked m, ;Profiled m, ;SourceCode m, ;Coverable i, ;Covered i, ;ObjTotal i, ;ObjHits i)

See COV_TUNE.H for #DEFINE field lengths.

Syntax: CreateTargetCursor(tcSource, tcTarget)

Return Values: NOT THIS.lError

Parameters: tcSource Specifies the name of the file to analyze.TcTarget Specifies the name of the file you want to modify.

Remarks: The target file contains one record for each of the following in the coverage log:

  • An ASCII source file.

  • A class contained in an ASCII source file.

  • A class contained in a .vcx or .scx file.

  • A stored procedure list in a .dbc file.

  • A Data Environment class or other Data Environment member class (such as a cursor) in a .frx or .lbx source file.

DeleteRegisteredAddin( ) Method

Removes a file name from the aAddIns array.

Syntax: DeleteRegisteredAddin(tcFileToDelete)

Return Values: None

Parameters: tcFileToDelete Specifies the add-in to remove from the registry.

Remarks: Called by the RunAddIn method after an add-in does not run successfully, whether the Registry is currently in use or not.

DisplayProjectStatistics( ) Method

Enables reporting after project statistics have been gathered in GetProjectStatistics( ).

Syntax: DisplayProjectStatistics(tcSource, tcTarget, tcProject)

Return Values: NOT THIS.lError

Parameters: tcSource Specifies the name of the table containing the source records.tcTarget Specifies the name of the table being modified.tcProject Specifies the alias of the project being analyzed.

DisplayStackXML( ) Method

Displays XML file.

Syntax: DisplayStackXML(tcXMLFile)

Return Value: Logical. .T. if no error occurs.

Defaults to the current Stack Analysis filename indicated by the cSavedStackXML property.

Remarks: This method is similar to DisplayProjectStatistics, except that, instead of being abstract in the engine, cov_engine.DisplayStackXML performs a ShellExecuteA.

DoMessage( ) Method

Displays tcMessage.

Syntax: DoMessage(tcMessage [, tnMessageBoxOptions [, tcMessageBoxTitle]])

Return Values: liReturn

Parameters: tcMessage Specifies the message that appears in the MESSAGEBOX.TnMessageBoxOptions Specifies the MESSAGEBOX nDialogBoxType setting.TcMessageBoxTitle Specifies the MESSAGEBOX cTitleBarText setting.LiReturn Specifies any return value from MESSAGEBOX( ), or 0 if a WAIT WINDOW executes.

Remarks: If the Coverage Profiler is running in Unattended mode, the message is displayed in a WAIT WINDOW TIMEOUT window so it does not prevent further processing. You can specify the timeout value using COV_TIMEOUT_SECS (a #DEFINE in COV_TUNE.H).

Error( ) Method

Sets the dialog error flag.

Syntax: Error(nError, cMethod, nLine)

Return Values: None

Parameters: nError Specifies the Visual FoxPro error number.CMethod Specifies the name of the method that caused the error.NLine Specifies the line number where the error occurred.

Remarks: Depending on the value of COV_DEBUG (a #DEFINE in COV_TUNE.H), this will display an error MESSAGEBOX and release the engine or display a WAIT WINDOW with error information and invoke the native Visual FoxPro error handler to make it possible for you to cancel, suspend, or ignore the current error.

FillCoverageFileNameCursor( ) Method

Adds files to the list of ignored files.

Syntax: FillCoverageFileNameCursor( )

Retu rn Values: NOT THIS.lError

Parameters: None

Remarks: CreateCoverageFileNameCursor( ) calls this method to add the names of the coverage engine file set to the group of files that should be ignored during processing. This method is a hard-coded set of INSERTs in the base coverage engine. You can override this set in a subclass designed to read in a set of file names from a text file generated from the Coverage.pjx file list.

FillFileTypeArray( ) Method

Initializes the aFileTypes array with known file extensions. See the aFileTypes property.

Syntax: FillFileTypeArray( )

Return Values: NOT(EMPTY(THIS.aFileTypes[1,1]) OR THIS.lError)

Parameters: None

FillOneTargetRecord( ) Method

Adds unmarked source code to memo field.

Syntax: FillOneTargetRecord(tcSource, tcTarget, tlFillingAll)

Return Values: lReturn AND(NOT THIS.lError)

Parameters: tcSource Specifies the name of the table containing the source records.TcTarget Specifies the name of the table being modified.TlFillingAll Specifies whether all records are processed in a loop, which changes the user feedback and displayed character handling.

Remarks: Places the unmarked source code for a target record into the appropriate memo field for later marking using a different strategy to find the right code for each type of source code. When COV_TOPSPEED is not #DEFINEd true (.T.), this method also places certain initial statistics into the Target file.

FillSourceCursor( ) Method

APPENDs the coverage log contents to the coverage analysis source file.

Syntax: FillSourceCursor(tcSource)

Return Values: lReturn

Parameters: tcSource Specifies the name of the source file.

Remarks: This method calls the SourceAvailable( ) method to eliminate records that refer to source files unavailable for analysis. It marks these records deleted in the source cursor.

FillTargetCursor( ) Method

Calls the FillOneTargetRecord( ) method for all target records in a loop.

Syntax: FillTargetCursor(tcTarget)

Return Values: (THIS.iTargetReccount > 0 AND NOT THIS.lError)

Parameters: tcTarget Specifies the target file that receives the processed results.

Remarks: Replicates the ObjHits statistics from the CreateTargetCursor( ) method for additional records referring to the same source files with the target files. See the CreateTargetCursor( ) method.

FilterListByLocation( ) Method

Provides a placeholder for future enhancements.

Syntax: FilterListByLocation( )

Return Values: NOT THIS.lError

Parameters: None

Remarks: FilterListByLocation( ) can be called either when a log loads or in response to a user action, with or without the Coverage Profiler application. This method is abstract in the engine.

GetAlias( ) Method

Returns the current or default alias of a Coverage Profiler workfile type.

Syntax: GetAlias(tAlias, tcWhichProp)

Returns: cReturn

Parameters: tAlias Specifies the alias of a file.tcWhichProp Specifies the workfile type (currently, either Source or Target) of the current default.

Remarks: GetAlias( ) returns either a currently used alias or the default alias of one of the Coverage Profiler workfile types. The valid workfile types include the following:

Note:
"SOURCE","TARGET","SKIPPED","COVFILES", and "PROJECT"

(The list of types is #DEFINEd in COV_SPEC.H as COV_KNOWN_ALIAS_PROPERTIES.) Each workfile type matches one c...Alias property to specify the default alias for this workfile.

The Coverage Profiler usually has a cursor open using each one of the workfile default aliases. However, the Coverage Profiler is capable of handling many sets of workfiles at the same time, within its data session, as long as you specify separate aliases for each one. The GetAlias( ) method and the system of defined work types plus the following properties make it possible for you to have default alias names without the default aliases being hard-coded:

  • cBaseFontName

  • cBaseMonoFontName

  • cCovFileAlias

  • cDefaultWritePath

  • cMarExecuted

  • cMarkNotExecuted

  • cOldPath

  • cSavedSkippedFiles

  • cSavedTargetDBF

  • cSkippedAlias

  • cSourceAlias

  • cSourcefile

  • cSuspendedLog

  • cTargetAlias

The engine methods that process the workfiles use aliases as parameters, so you can specify which source, target, or other file you are interested in at any time. Because you usually are interested only in one set of workfiles, however, these methods all use the GetAlias( ) methods to specify which alias and workfile default type to seek if you do not pass them a specific alias or aliases.

GetFontsFromUser( ) Method

Creates an instance of a common dialog subclass to ask the user to set font properties. If lUsingOCXs is False (.F.) or there has been an error creating an instance of the common dialog, the method uses the GETFONT( ) method. If the first parameter, tlBaseMonoFont, is True (.T.), the method shows only monospaced fonts and fills the monospaced font attribute properties of the engine. If this parameter is False (.F.), the second set of base font attribute properties is filled from a list of all available screen fonts.

See to the GetResourceLocation( ) method for more information on the lUsingOCXs property.

Syntax: GetFontsFromUser(tlBaseMonoFont, toMemberHost )

Return Values: lFontChange AND NOT THIS.lError

Parameters: tlBaseMonoFont Specifies the default monospace font style.ToMemberHost Specifies a reference to the current Coverage object.

GetProjectStatistics( ) Method

Creates a cursor containing project information.

Syntax: GetStatistics(tcSource, tcTarget, tcProject)

Return Values: lReturn

Parameters: tcSource Specifies the name of the alias containing the source records.tcTarget Specifies the name of the alias being modified.tcProject Specifies the project containing the source files.

Remarks: The information contained in the cursor is in the following format.

CREATE CURSOR(cProject) ;

Note:
(Hostfile c(COV_LEN_HOSTFILE), ;FileType c(4), ;Coverable n(8), ;Covered n(8), ;ObjTotal n(8), ;ObjHits n(8))

GetProjectStatistics( ) creates a header file in this cursor, indicating the project to which this cursor applies and fills this cursor with statistics drawn from the current coverage log that apply to each source file in the project. If necessary, GetProjectStatistics( ) calls MarkOneTargetRecord( ) for any project files that have not yet had their source code marked.

GetRegisteredAddins( ) Method

Fills the aAddIns array and the cAddIn property.

Syntax: GetRegisteredAddins( )

Return Values: None

Parameters: None

GetRegistryKeyValue( ) Method

Retrieves registry value of user option

Syntax: GetRegistryKeyValue(tcOption, tDefaultValue, tcPath)

Return Values: vReturn

Parameters: tcOption Specifies the file type option.tDefaultValue Specifies the default registry value.tcPath Specifies RegKey.

Remarks: This method, typically used at startup, uses the registry-handling member of the toolbar in the engine formset to get a registry key value for a user option. It converts the registry value to other TYPE( )s as required and compares this TYPE( ) to the passed value, tDefaultValue. It returns the registry value or the default value if the registry value is not found or is of the wrong type.

GetResourceLocation( ) Method

Specifies whether GETFILE( )/ShowOpen( ) strategy or PUTFILE( )/ShowSave( ) strategy is followed.

Syntax: GetResourceLocation(tcHost, tcTitle, tcCDLFilter, tcFileName, tcWhichDialog, [toMemberHost] )

Return Values: lcFileName

Parameters: tcHost Specifies the name of the file the method is starting from, usually seeking the matching file name of the uncompiled version of the code. If it is passed, it provides information for the common file dialog .InitDir property. tcTitle Specifies the title to use in the dialog or, in the GETFILE( )/PUTFILE( ) version, to use as a WAIT WINDOW NOWAIT prompt. If tcHost also is passed and includes a file name, then this information is added to the dialog title or prompt.tcCDLFilter Specifies the file types allowed in the dialog. This parameter is expressed in the format required by the common dialog filter expression. If the GETFILE( )/PUTFILE( ) is called, the method parses the common dialog filter to put it into appropriate format for the two Visual FoxPro functions.tcFileName Specifies the default file name to display.tcWhichDialog Specifies the GETFILE or PUTFILE.toMemberHost Specifies an optional form reference that can be passed to indicate where the dialog is displayed. If toMemberHost is not passed, the file dialog will display relative to the Coverage frame (if the Coverage frame exists) or to the first form in the formset collection (if the Coverage Profiler is in the Visual FoxPro window).

Remarks: Adds a member of the appropriate common dialog subclass (depending on the value of tcWhichDialog) if this is the first call. The dialog subclasses differ in how they set various flags.

Note:
This method provides for additional dialog subclasses, showing a Help file or print dialog, to be instantiated and used in the future.

If a common dialog subclass or .ocx-related error occur in the Coverage Profiler, this method sets the lUsingOCXs property to false (.F.) and uses GETFILE( )/PUTFILE( ).

You can set the #DEFINE COV_USE_OCXS if you prefer to default to the native Visual FoxPro functions even if there are no OCX errors.

GetStackXML( ) Method

Generates Stack Analysis XML from tcLog.

Syntax: GetStackXML(tclog)

Return Value: Logical. .T. if successful.

Parameters: tcLog Specifies the name of the log file.

Remarks: This function defaults to current Coverage source log. The tcLog argument is ignored if DEFINEd COV_LOAD_STACK_FROM_DBF is .T.

GetTableName( ) Method

Generates file names for unattended operation.

Syntax: GetTableName(tcWhichSuffix)

Return Values: cLogfileStem+SUFFIX[+n]+.dbf

Parameters: tcWhichSuffix Specifies which file extension to use.

Remarks: This method allows the coverage engine to generate file names with which to save its work to disk without overwriting existing files. Generally it just supplies file name defaults, but in Unattended mode, this method creates the file names without user intervention. Each method that saves a file to disk calls GetTableName( ) with a specific suffix; for example, in the SaveSkippedCursor:

Copy Code
cDBFName = ; THIS.GetTableName(COV_SKIPFILEDBF_SUFFIX)

GetTableName( ) uses the path and stem of the current log file name (THIS.cSourceFile) and attaches the appropriate suffix to this stem plus a digit, followed by the DBF extension. For example, Testlog.txt would produce TESTLOG_SKIP1.DBF in the previous example.

GetTableName( ) then increments the digit if the generated file name exists, until it finds a name that does not exist.

The default suffixes are #DEFINEs in COV_TUNE.H.

LockScreens( ) Method

Freezes or releases LockScreen properties and MousePointer properties for all members of _Screen during various long procedures.

Syntax: LockScreens(tlOn)

Return Values: Logical. .T.

Parameters: tlOn Specifies whether to lock the Lockscreen and MousePointer properties.

MarkAllTargetRecords( ) Method

Calls the MarkOneTargetRecord( ) method for all target records in a loop. Can be called because lMarkAllOnLoad is true (.T.) or because the coverage engine is in Unattended mode.

Syntax: MarkAllTargetRecords(tcSource, tcTarget)

Return Values: NOT THIS.lError

Parameters: tcSource Specifies the name of the table containing the source records.tcTarget Specifies the name of the table being modified.

MarkCodeLine( ) Method

Creates a marked-up version of a line of code, plus coverage statistics.

Syntax: MarkCodeLine(tcLine, tiExecuted, tnFirst, tnAverage)

Return Values: CMarkedLine

Parameters: tcLine Specifies the line of code.tiExecuted Specifies the number of times tcLine was run.tnAverage Specifies the average length of time to run.

Remarks: In Coverage mode, MarkCodeLine( ) marks code as "Executed" if tiExecuted is a positive number and "not Executed" if tiExecuted is 0. In Profile mode, MarkCodeLine( ) marks coverage statistics appropriately for the line. In either mode, MarkCodeLine( ) marks code as uncoverable (preceded by spaces) if tiExecuted is .NULL.

MarkOneTargetRecord( ) Method

Determines the marked status of the current line.

Syntax: MarkOneTargetRecord(tcSource, tcTarget, tlFillingAll)

Return Values: lReturn AND (NOT THIS.lError)

Parameters: tcSource Specifies the name of the table containing the source records.tcTarget Specifies the record being modified.tlFillingAll Specifies whether other target records are being processed. If all records are processed in a loop, then the user feedback and handling of displayed characters changes.

Remarks: Determines whether the current target record, tcTarget, is already marked in the current coverage mode and, if not, passes the relevant information to the MarkTargetCoverage( ) method for processing.

MarkTargetCoverage( ) Method

Marks up a copy of the source and REPLACEs a memo field in the target file.

Syntax: MarkTargetCoverage(tcSource, tcTarget)

Return Values: NOT (EMPTY(cMemo) OR THIS.lError)

Parameters: tcSource Specifies the name of the table containing the source records.tcTarget Specifies the name of the table being modified.

Remarks: MarkTargetCoverage( ) creates a marked-up version of tcSource and REPLACEs a memo field in the target file, tcTarget, (whether the code is for a class or a full procedure file).

To perform this action, the method starts with the sourcecode memo. The memo field REPLACEd depends on whether Coverage Profiler is marking Profiler or Coverage information, because the Target record retains both sets of marked-up code.

This method parses the source code and evaluates its statistics line by line. By default, this method calls the MarkCodeLine( ) method to mark each line when it has the appropriate statistics. However, the way this method marks the code line is #DEFINEd as COV_MARK_CODE_LINE in COV_TUNE.H, not directly implemented as a call to the MarkCodeLine( ) method. This makes it possible for you to replace the call to the MarkCodeLine( ) method with a different marking system. A second #DEFINE, COV_TOPSPEED, in COV_TUNE.H also makes it possible for you to switch the MarkCodeLine( ) call to a simpler, in-line marking system for fastest response time.

MarkTargetCoverage( ) evaluates each line to find out whether it was executed, how many times it was executed, and its execution timings (first and average) when in Profile mode. However, many lines are considered uncoverable in Coverage Profiler. These lines, such as comments, DEFINE CLASS and ELSE/Otherwise statements, and lines within TEXT ... ENDTEXT, do not appear in coverage logs, because they are not executable.

Note:
Other uncoverable code lines include #DEFINE statements, empty lines, continuations of executing lines, and parameter lines.

This method sets the number of times these lines run to .NULL. These lines are not considered when Coverage Profiler compiles statistics. In addition, lines broken by continuation symbols (semicolons) are considered as a single line of code and marked only on the last line.

OrderListByTime( ) Method

Provides a placeholder for future enhancements and subclasses.

Syntax: OrderListByTime( )

Return Values: NOT THIS.lError

Parameters: None

Remarks: OrderListByTime( ) is abstract in the engine.

PassedProperParams( ) Method

Syntax: PassedProperParams(tcFile, tlUnattended, tcAddIn)

Return Values: lReturn

Parameters: tcFile Specifies the name of the log file.tlUnattended Specifies whether to run in Unattended mode.tcAddIn Specifies the add-in file name(s).

Remarks: Test at startup to determine whether passed parameters are appropriate to the class. If any passed parameters are not appropriate TYPE( ), provides a MESSAGEBOX showing what parameters may be passed and RETURNs false (.F.), preventing any further coverage processing, as well as the creation of an instance of the class.

This method uses a MESSAGEBOX for feedback and stops processing even if the Coverage Profiler is starting up in Unattended mode. If you are setting up the Coverage Profiler for automated testing, be sure your calling program sends correct parameters or the analysis will not proceed.

RestoreCoverage( ) Method

Resumes coverage logging from suspended operation.

Syntax: RestoreCoverage( )

Return Values: None

Parameters: None

Remarks: If the Coverage Profiler previously suspended coverage logging, this method gives the user a chance to resume coverage logging when the Coverage Profiler releases. The user can choose to overwrite this previous log, append new log entries to it, or not resume coverage logging at that time.

RunAddin( ) Method

Runs an add-in file.

Syntax: RunAddin(tcAddin)

Return Values: lReturn AND NOT THIS.lError

Parameters: tcAddin Specifies the name of the file to run.

Remarks: RunAddin( ) runs a file (.scx, .fxp, .app, .prg, .qpx, .qpr, .mpx, or .mpr) that adds functionality to the Coverage object. If you do not pass a file name, RunAddin( ) runs the file specified by the cAddIn property.

The tcAddin file must accept an object reference, because the file is run by passing a reference to the coverage form, as in the following examples (depending on the file type):

Copy Code
DO (cFileName) WITH THIS
DO FORM (cFileName) WITH THIS

SaveFormsetAttributes( ) Method

Saves general frame and formset characteristivs to the registry as Profiler ends.

Syntax: SaveFormsetAttributes( )

Return Values: None

Parameters: None

SaveOptionsToRegistry( ) Method

Saves current user values to the registry.

Syntax: SaveOptionsToRegistry( )

Return Values: lSuccess

Parameters: None

Remarks: SaveOptionsToRegistry( ) can be called any time the user's current values should be saved to the registry. It saves the following user preferences:

  • Work options group

    lStartInProfileModelSmartPathlMarkAllOnLoadcMarkExecutedcMarkNotExecutedlRegisterAddIn

  • UI options group

    Font name, size, italic, bold for base monospace font

There are a few registry settings not saved by this method, because they have to be done at specific moments during the life of the engine. These are:

Coverage or the main Visual FoxPro frame (must be done when the user makes a choice and will be in effect next session but does not correspond to or affect any of the coverage property values for this session).

Registered add-ins (this array is manipulated over the life of the session, and the full set of file names it contains is saved to the registry at the end of the session).

SaveSkippedCursor( ) Method

Saves the skipped files cursor to disk.

Syn tax: SaveSkippedCursor(tcSkipped)

Return Values: RETURN NOT THIS.lError

Parameters: tcSkipped Specifies the cursor containing skipped records.

Remarks: Saves the skipped files cursor to disk if it contains any records and places the name of the table on disk in the cSavedSkipFiles property. See the cSkippedAlias and cSavedSkipFiles properties.

SaveTargetToDisk( ) Method

Saves output file, including marked-up code and statistics, to disk.

Syntax: SaveTargetToDisk(tcTarget)

Return Values: lReturn and NOT THIS.lError

Parameters: tcTarget Specifies the name of the modified table saved to disk.

SetFontValues( ) Method

Sets up initial font attribute values using registry key values and other defaults.

Syntax: SetFontValues( )

Return Values: NOT THIS.lError

Parameters: None

Remarks: See cBaseFontName and cBaseMonoFontName for information on how the coverage engine derives these defaults.

SetFormsetAttributes( ) Method

Reads and restores general frame and formset characteristics.

Syntax: SetFormsetAttributes( )

Return Values: None

Parameters: None

Remarks: Reads and restores general frame and formset characteristics from the registry as Profiler starts.

SetLogFile( ) Method

Attempts to set up a file for analysis.

Syntax: SetLogFile(tcFile)

Return Values: lReturn

Parameters: tcFile Specifies the name of the file to analyze.

Remarks: If you pass no string value, the SET COVERAGE value is used. If there is no current log file, the method prompts for a file name. If a log file can be set successfully, the method returns .T. If the user designates no log file, the method returns. F. If no new log is specified, the Coverage Engine returns to the currently loaded log, if one is loaded, or releases, if no log is loaded.

SetMarks( ) Method

Synchronizes and returns the values of cMarkExecuted and cMarkNotExecuted.

Syntax: SetMarks( )

Return Values: NOT THIS.lError

Parameters: None

Remarks: Synchronizes the lengths of cMarkExecuted and cMarkNotExecuted and returns the values of either or both properties to a default if they are not character-type or both properties are empty. If user options are not available from the registry, this method gets defaults from the #DEFINE values, COV_DEFAULT_MARKNOTEXECUTED and COV_DEFAULT_MARKEXECUTED, which you can set in COV_TUNE.H. A third #DEFINE, COV_DEFAULT_MARKSPACING, makes sure there is space between the marks and the line of code.

SetRegisteredAddins( ) Method

Saves the file names in the aAddIns array to registry values.

Syntax: SetRegisteredAddins( )

Return Values: None

Parameters: None

SetRegistryKeyValue( ) Method

Sets a registry key value from a user option.

Syntax: SetRegistryKeyValue(tcWhichOption, tValue)

Return Values: NOT THIS.lError

Parameters: tcWhichOption Specifies the user option to be accessed.tValue Specifies the value of tcWhichOption.

Remarks: SetRegistryKeyValue( ) uses the registry-handling member of the toolbar in the engine formset to set a registry key value from a user option. It converts all values to string type before sending them to the registry-handler to apply to the registry.

SetUIFonts( ) Method

Provides font preferences.

Syntax: SetUIFonts( )

Return Value: NOT THIS.lError

Parameters: None

Remarks: Abstract in the engine, called by SetUiOptions, SetUIFonts( ), makes it possible for the user font preferences saved in the various Base and BaseMont font properties to be applied to appropriate displayed characters.

SetUIOptions( ) Method

Sets UI options and defaults.

Syntax: SetUIOptions( )

Return Value: lReturn and NOT THIS.lError

Parameters: None

Remarks: Sets up initial UI options according to user preferences or defaults after initial setup of workfiles. This group of options includes fonts and the array of registered add-ins. It is required for UI display and user interaction with the workfiles, after they have been processed.

SetUIToShowCode( ) Method

Enables display of current target record in new log.

Syntax: SetUIToShowCode(tcTarget)

Return Val ue: NOT THIS.lError

Parameters: tcTarget Specifies the name of the table being modified.

Remarks: Abstract in the engine, called at the end of SetupWorkFiles( ) to allow UI to show current Target record in the newly loaded log.

SetUIToShowFileStates( ) Method

Enables reporting of log loading status.

Syntax: SetUIToShowFileStates(tcSource, tcTarget)

Return Value: NOT THIS.lError

Parameters: tcSource Specifies the name of the table containing the source records.tcTarget Specifies the name of the table being modified.

Remarks: Abstract in the engine, called at the end of SetupWorkFiles( ) to allow UI to indicate success or failure or current attempt to load a log.

SetUpWorkFiles( ) Method

Sets and validates a coverage log.

Syntax: SetupWorkFiles(tcLogFile, tcSource, tcTarget)

Return Value: lReturn AND NOT THIS.lError

Parameters: TcLogFile Specifies the name of the text log to analyze.tcSource Specifies the name of the file to use as source.tcTarget Specifies the name of the cursor being modified.

Remarks: SetUpWorkFiles( ) sets and validates a coverage log and then creates and fills the source and target work files for this text log. If the user choice is the same as the log file currently loaded, the method asks the user whether the log should be reloaded and analyzed. It makes sure the log is not open in a text window before loading the log. If the user specifies lMarkAllOnLoad, it marks all records in the current mode (Coverage or Profile) after successfully filling the target file with source code entries. If Coverage Profiler is in Unattended mode, it marks all records in both Coverage and Profile mode after successfully filling the target file. If the load succeeds, this method also sets the cDefaultWritePath to mark the path of the text log and the cSourceFile property to hold the name of this text log.

SetWorkOptions( ) Method

Sets initial user defined options.

Syntax: SetWorkOptions( )

Return Value: NOT THIS.lError

Parameters: None

Remarks: SetWorkOptions( ) sets up initial options according to user preferences or defaults before initial setup of workfiles. This group of options includes coverage marks and initial coverage mode and is required for processing the workfiles.

ShowProjectStatistics( ) Method

Runs coverage analysis figures against a Visual FoxPro project.

Syntax: ShowStatistics(tcSource, tcTarget, tcProject)

Return Value: lReturn AND NOT THIS.lError

Parameters: tcSource Specifies the name of the table containing the source records.tcTarget Specifies the name of the table being modified.tcProject Specifies the project containing tcSource.

Remarks: ShowProjectStatistics( ) calls GetProjectStatistics( ) and DisplayProjectStatistics( ) to run coverage analysis figures against a specific Visual FoxPro project set of files.

ShowStackXML( ) Method

Syntax: ShowStackXML(tclog)

Return Value: Logical. .T. if successful.

Parameters: tcLog Specifies the name of the log file.

Remarks: ShowStackXML( ) calls GetStackXML(tcLog) and DisplayStackXML(tcXMLFile) to run coverage analysis figures against a specific Visual Foxpro project set of files. The tcLog argument is ignored if DEFINEd COV_LOAD_STACK_FROM_DBF is .T.

ShowStatistics( ) Method

Abstract in the base engine.

Syntax: ShowStatistics( )

Return Value: NOT THIS.lError

Parameters: None

ShowStatus( ) Method

Places a message in the status bar or a WAIT WINDOW. See lUsingStatusBar property.

Syntax: ShowStatus(cMessage)

Parameters: cMessage Specifies the message to display in the status bar or WAIT WINDOW.

SourceAvailable( ) Method

Replaces the current Source log compiled file name with the full path name of the file holding the uncompiled source code.

Syntax: SourceAvailable( )

Return Value: lReturn

Parameters: None

Remarks: SourceAvailable( ) calls GetSourceLoc( ) if necessary to locate uncompiled source code. If the lSmarthPath property is true (.T.), it uses AddPath( ) to adjust SET (PATH) as the user specifies directories in which to find source files. RETURNs false (.F.) if the source file is on the Ignored Files list, if the file is of an unknown type, or if the uncompiled source code cannot be found.

SourceFileIsLog( ) Method

Checks the file name held in the cSourceFile property for valid coverage log format.

Syntax: SourceFileIsLog( )

Return Value: lReturn

Parameters: None

SuspendCoverage( ) Method

Sets the cSuspendedLog property to the name of the current log.

Syntax: SuspendCoverage( )

Return Value: None

Parameters: None

Remarks: Sets cSuspendedLog to the name of the current log and temporarily stops Visual FoxPro from writing this log, in one of the following cases:

  • The passed file name is the same as the current coverage log.

  • No file name is passed and the engine defaults to analyzing the current coverage log.

ToggleCoverageProfileMode( ) Method

Marks all target records in the new mode.

Syntax: ToggleCoverageProfileMode(tcSource, tcTarget)

Return Value: RETURN NOT THIS.lError

Parameters: tcSource Specifies the name of the table containing the source records.tcTarget Specifies the name of the table being modified.

Remarks: If the lMarkAllOnLoad property is true (.T.), marks all target records in the new mode.

ToggleStackXMLExtendedTree( ) Method

Toggles .lStackXMLExtendedTree.

Syntax: ToggleStackXMLExtendedTree( )

Return Value: Logical. .T. if no error occurs.

Parameters: None

Remarks: Designed to be augmented in subclasses to reflect this switch in the UI, change default XSLT on this basis, and so on. This method is similar to ToggleCoverageProfileMode.

See Also

Other Resources

Coverage Profiler Application


Utility Programs

Visual FoxPro 9.0 Samples
Utility Programs

These tools are provided with Microsoft Visual FoxPro to help speed the process of application development.

In This Section

How to: Add a Label Definition Using Addlabel.app

Adds label sizes to the New Label dialog box in the Label designer.
Code Analyzer

Provides visual controls, a menu, and keyboard options to navigate through application file code by using output from the Documenting wizard.
Cpzero.prg

Removes the code page mark from any file that has a table file structure.
Filer.dll

Supports the most popular features of the Filer, including support for searching files for text strings and opening multiple files for editing.
Gendbc.prg

Generates a program that can re-create a database.
Genhtml.prg

Generates a Web page based on data in a table.
HexEdit

Examines or changes address, byte, and ASCII values of data in a file.

Related Sections

Development Productivity Tools

Describes the different tools available to help make creating Visual FoxPro applications easier and faster.
How to: Use the Task List Manager

Explains how the Task List Manager can help keep track of shortcut, user-defined, and custom tasks.
Using the Object Browser

Describes how the Object Browser enables you to view information about components, such as objects, classes, properties, methods and events.
How to: Operate the Command Window

Explains that the Command window can be used to run code and that when you type a Visual FoxPro command in the window, the code is executed immediately.
How to: Use the Accessibility Browser

Describes how you can use the Accessibility Browser to verify that your application is accessible to people with disabilities.
How to: Use the Automated Test Harness

Explains that the Automated Test Harness can be used to run scripts to help automate the testing of your application.


How to: Add a Label Definition Using Addlabel.app

Visual FoxPro 9.0 Samples
How to: Add a Label Definition Using Addlabel.app
See Also

Located in the Visual FoxPro Tools\Addlabel folder, Addlabel.app makes it possible for you to add custom label sizes to the new label dialog box in the label designer by adding new sizes to the Windows Registry.

Copy Code
DO Addlabel.app

Adding Label Sizes

If you don't see a label size that you need in the Label Designer, you can add label sizes to the New Label dialog box by adding new label definitions.

To add a label definition

  1. Run Addlabel.app.

  2. In the Custom Labels dialog box, choose New.

  3. In the Label Name box of the New Label Definition dialog box, enter a name for the new label definition. This name will be displayed in the New Label dialog box when you create a new label.

  4. In the text boxes that are displayed over the label illustration, type values for label height, width and margins. You also need to specify how many labels to print in a row in the Number Across spinner.

  5. Choose Add.

See Also

Other Resources

Code Analyzer
Cpzero.prg
Gendbc.prg
Genhtml.prg
HexEdit
Label Designer
Utility Programs


Code Analyzer

Visual FoxPro 9.0 Samples
Code Analyzer
See Also

Located in the Visual FoxPro Tools\Analyzer folder, Analyzer.app provides a way to dynamically trace the structure and symbols in Visual FoxPro application files. Code Analyzer provides visual controls, a menu, and keyboard options to navigate through application file code by using output from the Documenting Wizard.

Copy Code
DO HOME( ) + 'tools\analyzer\analyzer' WITH 'DocWizTargetDirectory'

Parameters

DocWizTargetDirectory

Specifies the name of the Documenting Wizard target directory.

Remarks

The Symbols Tab provides access to all the user symbols in the open code document. The Hierarchies Tab provides display of either the calling tree hierarchy or the class hierarchy of your program.

See Also

Other Resources

Coverage Profiler Application
Utility Programs
Documenting Wizard


Symbols Tab, Code Analyzer

Visual FoxPro 9.0 Samples
Symbols Tab, Code Analyzer
See Also

This tab displays the symbols available in your documented code and provides a way to navigate through the code and between symbols. The tab contains the following controls.

Tab Options

Goto

Opens a text window or moves the cursor to the first occurrence of the symbol selected in the Files grid.
Next

Moves the text window cursor to the next occurrence of the symbol selected in the Files grid.
Symbols

Displays all the symbols available in the documented file.
Files

Displays the procedures and files in which the selected symbol occurs.

See Also

Other Resources

Code Analyzer
Documenting Wizard
Hierarchies Tab, Code Analyzer
Code Analyzer
Utility programs


Hierarchies Tab, Code Analyzer

Visual FoxPro 9.0 Samples
Hierarchies Tab, Code Analyzer
See Also

This tab provides display of either the calling tree hierarchy or the class diagram of your program. The tab contains the following controls:

Tab options

Files

Displays either the calling tree hierarchy or the class diagram of your program.
Option

Selects the alternate displays of the Files outline control.

See Also

Other Resources

Code Analyzer
Documenting Wizard
Symbols Tab, Code Analyzer
Code Analyzer
Utility programs


Cpzero.prg

Visual FoxPro 9.0 Samples
Cpzero.prg
See Also Example

Located in the Visual FoxPro Tools\Cpzero folder, Cpzero.prg removes the code page mark from any file that has a table file structure. After removing the mark, Cpzero applies another mark that you specify.

Typically, you use Cpzero with files from other platforms or earlier versions of FoxPro. If these files do not have code page marks when you open them, Visual FoxPro prompts you for a code page. If you specify the wrong code page, however, the data in the files won't display properly. To correct the code page, use Cpzero.

DO Cpzero [WITH "filename"[, codepage_number]]

Parameters

filename

Specifies the name of the file and must be delimited with single or double quotation marks. If filename is not included, a Locate File dialog box is displayed.
codepage_number

Specifies the desired code page number. If it is not included, the Code Page dialog box is displayed.
Note:
Before you run Cpzero on a table, make sure it is closed.

Example

Copy Code
* Remove the code page from MYFILE.DBF and specify 437
* as the new code page.
*
DO Cpzero WITH 'MYFILE.DBF',437

See Also

Other Resources

How to: Add a Label Definition Using Addlabel.app
Code Analyzer
Gendbc.prg
Genhtml.prg
HexEdit
Code Pages Supported by Visual FoxPro
CPCONVERT( ) Function
CPCURRENT( ) Function
CPDBF( ) Function
GETCP( ) Function
Utility Programs
SET CPDIALOG Command
SET NOCPTRANS Command


Filer.dll

Visual FoxPro 9.0
Filer.dll
See Also

Located in the Visual FoxPro \Tools\Filer directory, Filer.dll is a base component that provides a file and text search engine without a user interface. You can distribute Filer.dll and its companion files, Filer.ico, Filer.scx, and Filer.sct, with your Visual FoxPro run-time applications.

Note:
These files are unsupported. Technical support is not available for problems you encounter when using these files.

For more information about using Filer.dll, see the following sections:

  • Creating a Filer Object

  • Creating a User Interface for Filer

  • Using Filer Object Properties and Methods

Creating a Filer Object

You can use Filer.dll to programmatically create an instance of Filer to search for and manipulate files without any input from a user. Filer.dll also includes support for searching text strings in files and opening multiple files for editing.

Filer.dll is a COM object and supports Automation. Therefore, you can create an instance of Filer for other Automation servers such as Microsoft Visual Basic and Microsoft Excel.

To create an instance of the Filer search engine

  1. Include the following line of code to create an instance of Filer.

    Copy Code
    oMyFiler = CREATEOBJECT('Filer.FileUtil')

To create an instance of Filer for other Automation servers, you can use similar syntax.

Creating a User Interface for Filer

Visual FoxPro includes a sample form, Filer.scx (and Filer.sct), to show how you can create a user interface for Filer. When you run the form, the File Finder dialog box appears, and Filer is added to the Visual FoxPro Tools menu for the current Visual FoxPro session.

To run the Filer form

  1. Run the DO FORM command as follows:

    Copy Code
    DO FORM (HOME(1) + 'Tools\Filer\Filer.scx')

For more information, see File Finder Dialog Box.

To view the code behind or modify the Filer form

  1. Run the MODIFY FORM command as follows:

    Copy Code
    MODIFY FORM (HOME(1) + 'Tools\Filer\Filer.scx')

Using Filer Object Properties and Methods

The Filer object has properties and methods that you can use, for example, to specify file search conditions and run a file search.

When running a file search using the Filer method, Find, a Files collection object is created. The Files collection object has properties that you can use to determine information about the files that match search conditions. The Files collection object also has methods you can use to open or delete matching files.

The following example demonstrates how you can search for and open text files from Visual FoxPro.

Copy Code
oMyFiler = CREATEOBJECT('Filer.FileUtil')
oMyFiler.SearchPath = HOME() && Point search path to home directory.
oMyFiler.FileExpression = '*.TXT' && Specify text file search.
oMyFiler.Find(0) && Search and discard last collection

FOR nFileCount = 1 TO oMyFiler.Files.Count
   oMyFiler.Files.Item(nFileCount).Edit && Open files.
ENDFOR

Filer Object Properties

The following table describes the properties associated with the Filer object.

Property | Data Type | Description
SearchPath | C | The folder from which the search starts. Universal naming conventions (UNC) are supported. Read/write.
FileExpression | C | The file search mask that can include multiple masks separated by semicolons (;). For example, the file search mask *.scx; *.sct specifies to search for all files with the extensions .scx and .sct. The default file search mask is *.*. Read/write.
SubFolder | N | A numeric value that specifies if a recursive search is performed from the folder specified with the SearchPath property. If SubFolder is 0, the file search is performed only in the folder specified with the SearchPath property. If SubFolder is 1, the file search is performed in the folder specified with the SearchPath property and all its subfolders. Note that the Filer ignores System folders. The default value is 0. Read/write.
SearchText1 | C | A text string to search for in the files that match the file search mask specified by the FileExpression property. The default value is the empty string. Read/write.
SearchText2 | C | An additional text string to search for in the files that match the file search mask specified by the FileExpression property. Ignored if SearchText1 contains the empty string. The default value is the empty string. Read/write.
SearchText3 | C | An additional text string to search for in the files that match the file search mask specified by the FileExpression property. Ignored if SearchText1 and SearchText2 contain the empty string. The default value is the empty string. Read/write.
IgnoreCase | N | A numeric value specifying whether or not case is ignored for text in the text strings specified in SearchText1, SearchText2, and SearchText3. If IgnoreCase is 0, case isn't ignored (upper- and lower-case are significant). If IgnoreCase is 1, case is ignored. The default value is 1. Read/write.
WholeWords | N | A numeric value specifying whether or not the text in the text strings specified in SearchText1, SearchText2, and SearchText3 must match whole words for the search to be successful. If WholeWords is 0, the text in the text strings do not have to match whole words for the search to be successful. If WholeWords is 1, the text in the text strings must match whole words for the search to be successful. The default value is 0. Read/write.
SearchAnd | N | A numeric value specifying whether or not all the text in the text strings specified in SearchText1, SearchText2, and SearchText3 must match for the search to be successful. If SearchAnd is 0, the search is successful if any of the text in the text strings matches. If SearchAnd is 1, the search is successful only if all of the text in the text strings matches. The default value is 0. Read/write.
Editor | C | The editor in which files are opened with the Files collection Open method. Ignored if the IsHostedByFox property is 1. The default editor is Notepad. Read/write.
IsHostedByFox | N | A numeric value indicating the client that instantiated Filer.dll. If IsHostedByFox is 1, the client is Visual FoxPro, and the Visual FoxPro editor is used to open files. If IsHostedByFox is 0, the client is an application other than Visual FoxPro, and the editor used to open files is specified by the Editor property. The default value is 1 in Visual FoxPro. Read/write.
SortBy | N | A numeric value that specifies the order in which the Files collection is sorted. The following table lists the values for the SortBy property and the order in which the files are sorted. 0 No order 1 Path and file name 2 File name 3 File extension 4 File size 5 File last write date 6 File last access date 7 File creation date 8 File attributes The default value is 1. Read/write.
SortDirection | N | A numeric value that specifies if the Files collection is sorted in ascending or descending order. If SortDirection is 0, the Files collection is sorted in ascending order. If SortDirection is 1, the Files collection is sorted in descending order. The default value is 0. Read/write.

Filer Object Methods

The following table describes the methods associated with the Filer object.

Method Description

Find(nValue)

A method that performs the file search and creates a Files collection. The Find method contains a numeric value indicating the number files in the Files collection.

nValue is a numeric value that specifies if Files collections from previous searches are discarded. If nValue is 0, the Files collections from previous searches are discarded. If nValue is 1, the Files collection created by the current search is appended to the previous searches.

Note that nValue is not optional.

Files Collection Objects

The following table describes the object references associated with the Files collection.

Object | Description
Item(nValue) | An object reference to a file in the Files collection. nValue is an index to a file in the Files collection. nValue begins at 1, and continues to the number of files in the Files collection. You can use the Count property, described below, to determine the number of files in the Files collection.

Files Collection Properties

The following table describes the properties associated with the Files collection.

Property | Data Type | Description
Count | N | Contains the number of files in the Files collection. Read-only.
Name | C | The name of the file, excluding the path. Read-only.
Size | N | The size of the file in bytes. Read-only.
SizeHigh | N | The high 4 bytes of the file size if the file size is greater than 4 gigabytes. Read-only.
Attr | N | The Windows file attributes for a file. The following is a list of numeric values for typical file attributes. 0 No attributes set 1 Read-Only 2 Hidden 4 System 32 Archived The value of Attr can be the sum of several file attributes. For example, if Attr is 7 (1+2+4), the file is a read-only, hidden system file. For more information about the other file attributes for which Attr returns values, see the GetFileAttributes function described in the Microsoft Developer's Network library. Read/write.
DateTime | N | The time stamp assigned by Windows to a file when it is created. The integer portion of the time stamp is the number of days since 12/30/1899, and the remainder is the fractional remainder of the day from which you can determine the time when the file was created. The Filer form, Filer.scx, contains a user-defined method called GetTime that demonstrates how you can determine the date and time a file was created from the DateTime property. Read-only.
LastAccessTime | N | The time stamp assigned by Windows to a file when it is was last accessed. Read-only.
LastWriteTime | N | The time stamp assigned by Windows to a file when it is was last written to. Read-only.
AlternateName | C | The short name of the file if the file name is longer than the MS-DOS® 8.3 character naming convention. Read-only.
Path | C | The full path to file. Read-only.

Files Collection Methods

The following table describes the methods associated with the Files collection.

Method | Description
Edit | Opens the specified file for editing. If the IsHostedByFox property is 1 (the default for Visual FoxPro), the file is opened in the Visual FoxPro editor. If the IsHostedByFox property is 0, the file is opened in the editor specified with the Editor property (NotePad by default).
Delete | Deletes the specified file from disk. The file isn't placed in the Recycling Bin.

See Also

Other Resources

Utility Programs
Development Productivity Tools
Automation and COM Servers
CREATEOBJECT( ) Function
DO FORM Command
MODIFY FORM Command
Distributing Applications


Gendbc.prg

Visual FoxPro 9.0 Samples
Gendbc.prg
See Also Example

Located in the Visual FoxPro Tools\Gendbc folder, this tool generates a program that can recreate a database. GenDBC.prg supports autoincrementing, collating sequences, and filtered primary keys. In Visual FoxPro 9.0, it also supports Blob, VarChar, and VarBinary type fields, and the AllowSimultaneousFetch, RuleExpression, and RuleText properties for views.

You can use this program to generate the following:

  • Code that you can analyze to learn how a database is created by using program code

  • Code that you can insert in your program code, eliminating the need to ship databases with your application

  • Code that you can insert in your program code to recreate the database if a customer's data is corrupt

DO GENDBC WITH filename

Parameters

filename

Specifies a character string containing the name of an output file. The filename can contain path information and a file extension. If no extension is supplied, the default extension, .prg, is used.
Note:
This program works only on the currently active database.

Example

The following example creates a program called MyData.prg, which contains code for recreating a database, MyDatabase. The program, Main.prg is created in the C:\VFP folder and contains code for recreating the database, Main.
Copy Code
OPEN DATABASE MyDatabase
DO gendbc WITH 'MyData.prg'
SET DATABASE TO Main
DO gendbc WITH 'c:\vfp\main'

See Also

Other Resources

How to: Add a Label Definition Using Addlabel.app
Code Analyzer
Genhtml.prg
HexEdit
Cpzero.prg
Utility Programs


Genhtml.prg

Visual FoxPro 9.0 Samples
Genhtml.prg
See Also

Genhtml.prg is the default program called by the _GENHTML system variable.

You can use _GenHTML to easily collect static data or to convert forms, labels, reports, and menus for viewing or transmitting in email or posting as Web pages. You can use _GenHTML to share data with sites that don't have Visual FoxPro installed or to create templates for use in Web pages.

GenHTML.PRG is accessed from the File menu when you choose the Save As HTML option. This menu option is available when the Form Designer, Label Designer, Menu Designer, or Report Designer is active or when a table or cursor is open in a Browse window. GenHTML uses the specified data source as the basis for generating an HTML document using classes contained in the _HTML.VCX class library.

You can run GenHTML from the Command window with the following syntax:

Copy Code
DO (_GENHTML) WITH <cOutFile> <cSourceFile> [, <nShow>][,<vIELink>][,...

parameter | description
cOutFile | Default = "" Specifies the name of the output file. When specify no extension, .HTM is the default.
cSourceFile | Default: = "" Specifies the source file name, alias or object.
nShow | Default: = 0 Specifies whether GenHTML will create and open the output file. tnShow can take the following values: 0 = Generate output file1 = Generate and display output file in Visual FoxPro editor.2 = Generate and display output file in Internet Explorer.3 = Generate and display output file after using a Save As dialog box4 = Create PUBLIC _oHTML object and generate a file.5 = Create a PUBLIC _oHTML object without generating a file.
vIELink | Default: Specifies a link to an Internet Explorer object or Web browser control.
Object | Default: Specifies a reference to an Internet Explorer object.
cStyle | Default: Specifies a Style ID in GenHTML.DBF.
tcScope | Default: Specifies the scope of scan by setting the cScope property.
cHTMLClass | Default: Specifies the class, and optionally, the class library that is instantiated for HTML object.

See Also

Other Resources

How to: Add a Label Definition Using Addlabel.app
Code Analyzer
Gendbc.prg
HexEdit
Cpzero.prg
Utility Programs


HexEdit

Visual FoxPro 9.0 Samples
HexEdit
See Also

Located in the Visual FoxPro Tools\Hexedit folder, Hexedit.app provides a way to examine address values, or examine or change byte and ASCII values of data in a file. HexEdit is a visual equivalent of the MS-DOS Debug program DUMP Command.

Caution:
If you want to edit the file, make sure it is not in use or otherwise locked.

Copy Code
DO HEXEDIT.app

Remarks

When you choose a file, HexEdit displays a dialog box with the following control options.

Note:
If you want to edit the file, make sure it is not in use or otherwise locked.

Dialog Options

Select File

Displays the Open dialog box so you can change the current file.
Address

Displays the file offset address of the first byte of data in a 16-byte block displayed in the next columns.
0...F

Displays sixteen 2-digit numbers, representing the hexadecimal byte value in that file location.
Text

Displays the ASCII representation of the byte value in the corresponding location in the byte value columns.
Save Edits

Saves changes to the open file.
Undo Edits

Discards all edits to the open file.
Find

Enables you to specify a character to seek in the file. You can also choose to search forward or backward from anywhere in the file.
Jump

Enables you to specify either a hexadecimal or decimal address to edit.
Close

Closes HexEdit and the open file.

See Also

Other Resources

Addlabel.app
Code Analyzer
Gendbc.prg
Cpzero.prg
Genhtml.prg
Utility programs
Visual FoxPro Key Codes


How to: Customize the Toolbox

Visual FoxPro 9.0
How to: Customize the Toolbox
See Also

The Toolbox can be customized to contain the categories and items that you use the most. You can also order items in a way that you find most effective. This can be done by adding or deleting a category, changing the order of categories, and adding or deleting items in a category.

Before you can customize the Toolbox, you must have it open.

To open the Toolbox

  • On the Tools menu, click Toolbox.

To add a new category

  1. Right-click the Toolbox, and click Customize Toolbox on the shortcut menu.

  2. In the Customize Toolbox dialog box, click the Categories folder.

  3. At the top of the Customize Toolbox dialog box, click Add Category.

  4. In the Add Category dialog box, type a new category name in the Category name box.

  5. In the Category type list, select the type of category you are adding, and click OK.

To delete a category

  1. Right-click the Toolbox, and select Customize Toolbox on the shortcut menu.

  2. In the Customize Toolbox dialog box, click the category you want to delete.

  3. At the top of the Customize Toolbox dialog box, click Remove Category.

  4. When prompted to delete the category, click OK.

To add an item to a category

  1. Right-click the Toolbox, and select Customize Toolbox on the shortcut menu.

  2. In the Customize Toolbox dialog box, select the category that you want to add your class.

  3. Click Add Item on the Customize Toolbox dialog box.

  4. In the Add Item dialog box, select the type of item you want to add, and click OK.

  5. In the Add Class Library dialog box, select the category to add to your Class Library.

  6. Click the ellipsis (...) button next to the Class Library box, select a class to add from the Open box, and click OK

  7. In the Add Class Library dialog box, click OK.

To delete an item from a category

  1. Right-click the Toolbox, and select Customize Toolbox on the shortcut menu.

  2. In the Customize Toolbox dialog box, select the category that you want to delete an item from.

  3. In the Category Item list, select the item that you want to delete.

  4. Click Remove Item on the Customize Toolbox dialog box.

  5. When prompted to delete the item, click OK.

See Also

Other Resources

Development Productivity Tools
Utility Programs
Toolbox
_TOOLBOX System Variable


How to: Use the Task List Manager

Visual FoxPro 9.0
How to: Use the Task List Manager
See Also

You can keep track of tasks using the Task List Manager, which stores tasks in the FoxTask.dbf table file. You can create the following types of tasks:

  • Shortcut References a specific line of code you might want to edit or view later.

  • User-defined Specifies a to-do or information item you might want to track. These are added manually.

  • Other A custom task. You must add this type of task programmatically in your application.

    Note:
    Make sure to set the Type field of the custom task to "O" in FoxTask.dbf file, which is referenced by the _FOXTASK system variable. For more information, see _FOXTASK System Variable.

To open the Task List Manager

  • On the Tools menu, click Task List.

For more information, see Task List Manager Window.

You can perform many actions in the Task List Manager, such as add, edit, prioritize, set status for, and delete tasks.

Adding Tasks

You can add shortcut and user-defined tasks in the Task List Manager.

To add a shortcut task

  1. Open the program file in which you want to create the shortcut.

  2. In the code editing window, select the line of code that you want to create as a shortcut.

  3. On the Edit menu, point to Bookmarks and click Toggle Task List Shortcut.

You can also add a shortcut by doing one of the following after selecting the line of code:

  • Right-click the selected code and click Add Task List Shortcut.

  • Press ALT+F2 to add or remove the shortcut.

  • Press and hold the CTRL key, and then double-click the Editor's Selection Margin.

Shortcut tasks are indicated by an arrow icon in the task type column.

To add a user-defined task

  1. In the Tasks window, click Click here to add a new task in the Contents column.

    A cursor appears in the text box.

  2. Type information about the task you want to perform.

  3. When you are finished, press RETURN or click outside the text box.

    The task is added to the end of the list so you can enter additional information.

User-defined tasks are indicated by a person/task icon in the task type column.

Editing Tasks

You can edit a task directly in the Task List or using the Task Properties dialog box. The Task Properties dialog box contains the Task and Fields tabs, which displays information for all available fields, even if they are not shown in the Tasks window.

Note:
Double-clicking a shortcut task in the Tasks window opens the appropriate editing window and moves directly to that shortcut.

To edit a task in the Task Properties dialog box

  1. In the task type column (third column from the left), double-click the icon next to the task.

  2. In the Task Properties dialog box, click the Task tab.

  3. Edit the fields and settings you want.

You can also open the Task Properties dialog box by right-clicking the task, and clicking Open Task.

Prioritizing Tasks

You can set and organize priorities for tasks.

To set a priority for a task

  1. In the priority column, indicated by an exclamation mark (!), click the box for the task you want

  2. From the list, select a priority.

You can organize tasks by priority by clicking the priority column header. You can also enter a due date for a task.

Marking Tasks

You can mark tasks to indicate their status as read or complete in the Task List Manager.

Tasks that are not yet read appear in bold. You can mark tasks as read when you are finished reading about the task.

To mark a task as read

  • Right-click the task, and click Mark as Read.

    When a task is read, it no longer appears in bold.

You can also mark a task as read by opening the Task Properties dialog box, clicking the Task tab, and selecting the Read check box.

You can mark tasks as complete when you are finished with the task.

To mark a task as complete

  • In the task list column, or second column from the left, select the check box for the task you want to complete.

    When a task is complete, it appears as strikethrough text.

You can also mark a task as complete by right-clicking the task, and clicking Mark as Complete or by opening the Task Properties dialog box, clicking the Task tab, and selecting the Complete check box.

Deleting Tasks

You can delete tasks in the Task List Manager.

Note:
Shortcut tasks are deleted automatically when you remove the shortcut in the editing window.

To delete a task

  • Right-click the task, and click Delete Task.

Adding Files to User-Defined Tasks

Shortcut tasks have a file automatically associated with them. You can add file associations to user-defined or other tasks, although it is not required.

To add a file association

  • In the File Name field for the task, type the full path and name of the file and any additional information required, such as line or method.

You can also add a file association by opening the Task Properties dialog box, and entering the file name in the File Name field.

Opening Files for Editing

You can open and edit files associated with tasks.

To open and edit a file associated with a task

  • Double-click the task in the Tasks window.

You can also right-click shortcut tasks or user-defined tasks that have file associations, and click Open File.

Editing Custom Fields

You can edit custom fields that exist in the Task List Manager.

To edit custom fields

  1. In the task type column (third column from the left), double-click the icon next to the task.

  2. In the Task Properties dialog box, click the Fields tab.

    A list of available custom fields appears.

Cleaning and Editing the Task List Table

You can clean the Task List table and edit the structure of the user-defined columns table.

To clean the Task List table

  1. Right-click the Tasks window, and click Options.

  2. In the Tasklist Options dialog box, click Clean Up FoxTask.
To edit the structure of the user-defined columns table

  1. Right-click the Tasks window, and click Options.

  2. In the Tasklist Options dialog box, click Edit Structure.

You can also customize the Task List manager by sorting or filtering tasks, and selecting or adding custom fields. For more information, see Customizing the Task List Manager.

See Also

Other Resources

Utility Programs
Task List Manager Window
_FoxTask System Variable
_TASKLIST System Variable
How to: Create Bookmarks and Task List Shortcuts


How to: Create Bookmarks and Task List Shortcuts

Visual FoxPro 9.0
How to: Create Bookmarks and Task List Shortcuts
See Also

You can set bookmarks and shortcuts for code in an editing window so you can navigate your code more easily during the programming and debugging processes. By setting bookmarks, you can navigate between bookmarks in your code.

By creating shortcuts, you can create tasks in the Task List Manager associated with those shortcuts. When you create a shortcut in your code, an entry appears in the Tasks window of the Task List Manager for you to create a task, which makes it possible for you to move quickly to the marked code. For more information, see How to: Use the Task List Manager and Task List Manager Window.

Note:
Before you can create bookmarks and shortcuts, you must have previously saved the file. You can create a bookmark or a shortcut but not both for a line of code. Bookmarks and shortcuts relate to the position of a line of code in the editing window rather than the code itself. Therefore, certain editing operations, such as inserting text before a bookmark, can cause the line of code that a bookmark or shortcut refers to move to a different line. If you do not want the bookmark to refer to the new line, remove the bookmark or shortcut and add a new one in the desired location.

To create bookmarks and shortcuts

  1. If your code file has not been saved, save the file.

  2. In the line of code that you want to create a bookmark, insert the mouse cursor.

  3. On the Edit menu, point to Bookmarks.

  4. To create a bookmark, click Toggle Bookmark.

    A rectangle appears in the selection margin on the left side of the editing window.

    Tip:
    If the selection margin does not appear in the editing window, you can specify the margin on the Editor tab in the Options dialog box. For more information, see Editor Tab, Options Dialog Box.

    -OR-

    To create a shortcut, click Toggle Task List Shortcut.

    A curved arrow appears in the selection margin on the left side of the editing window.

You can also create a bookmark by placing the mouse cursor in the selection margin next to the line of code and pressing the SHIFT key while double-clicking. You can also create a shortcut by placing the mouse cursor in the selection margin next to the line of code line and pressing the CTRL key while double-clicking. You can also create and navigate bookmarks and shortcuts using shortcut keys. For information about keyboard shortcuts, see Keyboard Shortcuts.

Note:
Bookmarks are preserved when you close and reopen the editing window, but they do not exist after exiting and restarting Visual FoxPro. Shortcuts persist between editing sessions.

To navigate bookmarks and shortcuts

  • On the Edit menu, click Next Bookmark/Shortcut or Previous Bookmark/Shortcut.

To remove bookmarks and shortcuts

  1. In the line of code that you want to remove a bookmark or shortcut, insert the mouse cursor.

  2. On the Edit menu, point to Bookmarks. To remove a bookmark, click Toggle Bookmark.

    -OR-

    To remove a shortcut, click Toggle Task List Shortcut.

See Also

Other Resources

Programming in Visual FoxPro
Testing and Debugging Applications


Customizing the Task List Manager

Visual FoxPro 9.0
Customizing the Task List Manager
See Also

You can customize the view of your Task List Manager in several ways:

  • Sorting tasks You can sort the task list by clicking on the column header of the field by which you want to sort. Clicking a column repeatedly toggles that field between ascending/descending order.

  • Filtering task types You can filter the types of tasks you want to display in the Task List by selecting specific task types from the Show Tasks submenu of the Task List context menu. The submenu contains options to display shortcuts, user-defined and other Tasks.

  • Choose fields for viewing You can choose which fields you want to view in the Task List by selecting the Column Chooser menu item from the Task List context menu. A Columns picker dialog box appears so you can add new fields using drag-and-drop directly to the Task List. To remove a field, right-click the column header and select the Remove This Column menu item.

  • Adding custom fields You can add custom fields to your Task List. Custom fields are stored in a separate table from your main _FOXTASK (Foxtask.dbf) table. This custom fields table must have a UniqueID field, so it can be linked to the field in the Foxtask table. You can edit Custom fields from the Fields tab of the Task Properties dialog box.

    You can add a new or existing custom fields table in the Options dialog box. Access the Options dialog box from the Options menu item of the Task List context menu item. All custom fields appear in the Columns Chooser dialog box, so you can add them to or remove them from the Task List.

See Also

Other Resources

How to: Use the Task List Manager
Utility Programs
Task List Manager Window
_FoxTask System Variable
_TASKLIST System Variable
How to: Create Bookmarks and Task List Shortcuts


Using the Object Browser

Visual FoxPro 9.0
Using the Object Browser
See Also

The Object Browser makes it possible for you to browse, filter, and search for components that you might want to consume in your projects.

To open the Object Browser from the Tools menu, click Object Browser.

You can also open the Object Browser by clicking the Object Browser button on the main Visual FoxPro toolbar, or, type the following line of code in the Command window:

Copy Code
DO (_OBJECTBROWSER)
Note:
After the Object Browser opens, you can open it programmatically by using the _OBJECTBROWSER system variable.

You can view any COM class type library that is registered on your system. The left pane shows a list of all loaded class type libraries. You can expand each category to display the classes in the library. Members associated with those classes appear in the right pane.

Working with Classes

Classes provide complete member information for a particular COM component or ActiveX control that you might want to consume in your application. Instances of these objects typically are created using one of the following Visual FoxPro functions:

CREATEOBJECT( ), CREATEOBJECTEX( ), NEWOBJECT( ), GETOBJECT( ), ADDOBJECT Method

Note:
ActiveX controls usually are dropped onto a form class directly and are instantiated with the form.

You can drill down into a class to view member detail by selecting the class from the Classes node in the Classes & Members pane. When selected, the properties, methods, and events for that class are displayed in the Members pane on the right. Protected members are shown with a lock icon.

When you click class members in the Members pane, detail information is shown in the Description pane. The contents of the Description pane give details of data types for member parameters and return values. Underlined items in the Description pane are links you can click to go directly to that item for more information. If available, a functional description of the member also will be displayed in the Description pane.

Working with Properties, Methods and Events

The best way to view properties, methods, and events is to use a particular class in the Members pane. Typically you work with a single class at a time. Sometimes you might wish to view all the properties, methods, and events in a library at one time, not filtered by class. To do this, click the appropriate node in the Classes & Members pane. Depending on the size of the type library, it might take several seconds or minutes to list all the members.

When you click a property, method, or event in the Classes & Members pane, you can view all the classes and interfaces that use it in the Members pane.

Working with Cached Classes

When you expand one of the Properties, Methods, or Events nodes in the Classes & Methods pane, it might take a while to display all the contents. Because of this, the Object Browser caches this information in the Objectbrowser.dbf. This saves time when you want to reload a library later. You can click the Refresh button to have properties, methods or events reloaded next time one of these nodes is expanded.

Working with Constants and Enums

Many type libraries contain constants. A constant is the equivalent of a numeric #DEFINE with which Visual FoxPro developers are familiar. Enums are collections of two or more constants.

Enums are special in that a member can denote a specific enum as the data type for a parameter or return value. For a parameter this means that the value passed for a parameter must be one of the Constants associated with the specified Enum.

You can view the value of a constant by clicking it and viewing the numeric value in the Description pane.

When specifying a constant for a method parameter, you must pass in the actual numeric value. Visual FoxPro does not recognize the actual constant name as a reference as with other languages, such as Visual Basic.

You can create a set of #DEFINE directives that represent all the constants by using drag and drop from the Constants node of a type library to an editor window.

Working with Interfaces

Advanced developers might want to work with specific interfaces in the COM library. Interfaces are particularly useful when you create COM Servers in Visual FoxPro that use the IMPLEMENTS clause of the DEFINE CLASS command. The IMPLEMENTS clause accepts an interface name as a parameter and can be used in association with a variety of COM+ Services as well as the EVENTHANDLER( ) Function.

You can create a class template by using drag and drop from an Interface node to an editor window. This template will contain any IMPLEMENTS statement and member details of the interface.

Searching within Libraries

You can perform searches for text in a library by clicking on the Find button. The Find button displays a unique Find view above the two main panes. The Simple Find view searches for a specified string within all opened libraries. The search is made within all elements of a library and for strings "contained within". The Advanced Find view supports greater refinement of the search.

Persistence of Object Browser Data

The Object Browser session is persisted between uses. Object Browser information is saved to an objectbrowser.dbf table stored in the same location as the Object Browser. This information includes the following:

  • A Recent History list of all previously opened libraries so you can retrieve one of these libraries quickly in the future.

  • Cached properties, methods, and events for a library so it can be loaded quickly next time accessed.

  • All previously loaded add-ins.

  • User preferences specified in the Options dialog box.

  • COM components and ActiveX controls displayed in the Open dialog box (stored in Foxrefs.dbf).

Working with Add-Ins

  • Object Browser add-ins can perform a variety of useful functions not native to the browser itself. These include adding additional user interface elements, new menu items, and drag-drop capabilities.

    Add-ins typically are created as VCX classes.

Existing Add-Ins Install Wizard

The first step of the Existing Add-Ins wizard specifies the following options:

  • Enter a user-friendly name for the add-in as you wish it to appear in the Add-Ins list of the Options dialog box.

  • Enter a description for the add-in as you want it to appear in the Add-Ins list of the Options dialog box.

  • Select an icon to display in the Add-Ins list of the Options dialog box (optional).

The second step specifies input for class information of the add-in.

  • Select the specific class and class library for the add-in class.

The third step is an optional step to provide support information:

  • You can specify a URL to a Web page that provides additional information for using the add-in. You also can provide specific HTML that appears in the add-in description.

The last step makes it possible for you to finish the add-in installation.

  • You can specify some advanced options. These include Properties and User Defined Settings.

See Also

Other Resources

Utility Programs
Object Browser
Class Browser
_ObjectBrowser System Variable
DEFINE CLASS
EVENTHANDLER( )
How to: View Type Library Information


How to: Operate the Command Window

Visual FoxPro 9.0
How to: Operate the Command Window
See Also

In general, you can do anything in the Command window that you can do in a program. For example, you can execute a line of code, such as a Visual FoxPro command, by typing it in the Command window. However, when you execute code in the Command window, that code is executed immediately. You can also run multiple lines of code in the Command window as if though they were in a self-contained program.

In addition, choices you make from menus and dialog boxes are echoed in the Command window. You can copy and paste these commands into a Visual FoxPro program, then run the program repeatedly, making it easy to execute multiple commands repeatedly.

The Command window is an editing window; therefore, you can edit code using the editing tools available in Visual FoxPro. For example, you can edit, insert, delete, cut, copy, or paste text in the Command window.

To execute a line of code in the Command window

  • In the Command window, type a line of code and press the ENTER key.

To execute the same line of code in the Command window

  1. In the Command window, move the cursor to any position in the line of code you want to execute.

  2. Press the ENTER key.

To run multiple lines of code in the Command window

  1. In the Command window, select the lines of code you want to execute.

  2. Press the ENTER key.

Although you can run code in the Command window that you might usually execute in a program file, certain advantages exist when running code from a program. For more information, see Working with Programs.

See Also

Other Resources

Development Productivity Tools
Command Window


How to: Use the Accessibility Browser

Visual FoxPro 9.0
How to: Use the Accessibility Browser
See Also

You can use the Accessibility Browser to help you develop applications that are more accessible to people with disabilities, write automated test suites, or select and buy off-the-shelf test software. You can use the Accessibility Browser to examine the IAccessible properties of objects and how objects relate to each other.

To launch the Accessibility Browser

  1. On the Program menu, select Do.

  2. In the Do dialog box, browse the Microsoft Visual FoxPro directory, ..\Tools\MSAA\, for the file, accbrow.app.

  3. Select the file and click Do.

For more information, see Accessibility Browser Window.

By following accessibility design practices and using Active Accessibility when needed, you can make applications more accessible. For more information, see Accessibility for People with Disabilities.

See Also

Other Resources

Utility Programs
SYS(2800) - Accessibility Support
Development Productivity Tools


How to: Use the Automated Test Harness

Visual FoxPro 9.0
How to: Use the Automated Test Harness
See Also

You can automate testing of your Visual FoxPro applications by creating and running scripts using the Automated Test Harness. The Automated Test Harness records and plays mouse and keyboard events using Microsoft Active Accessibility (MSAA) technology and is installed in the Microsoft Visual FoxPro VersionNumber\Tools\Test directory. For additional information, see the ReadMe file, aatesthelp.htm, in the \Tools\Test directory.

To run the Automated Test Harness

  1. Run the Automated Test Harness from \Tools\Test\AATEST.APP

    -OR-

    In the Visual FoxPro Command window, enter the following line:

    Copy Code
    DO (HOME() + "tools\test\aatest")

  2. To record the script, click Record in the toolbar or on the Record menu.

    A list of available applications appears.

  3. Select a Visual FoxPro application, and, when prompted, enter a name for your text script.

    The selected Visual FoxPro application or window appears, and the tool is ready to record the events.

  4. Record the events. Run your application as you typically would using the keyboard and mouse. Make sure you have run through all of the user interface elements, including forms, menus, windows, and dialog boxes.

  5. When finished, click Stop in the toolbar. You also can pause and resume recording as needed.

To view the events log, which has been selected or currently recorded, click "Edit the script."

To play back scripts, select the script you want to run, and click Play. If the program detects an error, you see a prompt in the testing application.

To see the test log, select the Test Log tab.

Note:
Only one instance of the test tool can be run from one installation because the test tables are opened exclusively.

See Also

Other Resources

Utility Programs
Testing and Debugging Applications
Accessibility Browser Window
Debugging and Error-Handling Language


Samples and Walkthroughs

Visual FoxPro 9.0
Samples and Walkthroughs

Visual FoxPro includes numerous code samples, as well as step-by-step walkthroughs to help you learn and experiment with various program features.

In This Section

Samples

Provides class library, server, solutions, and foundation class code samples that you can use for experimenting and getting to know particular features in Visual FoxPro.
Walkthroughs

Provides a list of common scenarios in Visual FoxPro and gives step-by-step instructions for each, making it a good place to start learning about various Visual FoxPro features.

Related Sections

Getting Started with Visual FoxPro

Provides links to areas to help you get started with creating database management solutions, including information on installing, upgrading, and customizing Visual FoxPro.
Using Visual FoxPro

Provides an information about features and tools in Visual FoxPro and describes how to develop applications.
Programming in Visual FoxPro

Provides links to basic information about creating applications in Visual FoxPro to maximize your programming productivity.


Samples

Visual FoxPro 9.0 Samples
Samples

Visual FoxPro comes with numerous code samples that you can use for experimenting and becoming acquainted with features.

For additional samples, see the Visual FoxPro ..\Samples folder, which contains samples that illustrate APIs, COM+ services, and data access.

In This Section

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Server Samples

Contains server samples that illustrate Automation Servers.
Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.

Related Sections

Getting Started with Visual FoxPro

Provides information about installing, upgrading, and configuring Visual FoxPro, as well as customizing the development environment.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.
Reference

Includes topics on productivity tools, as well as the controls, objects, properties, methods, events, statements, functions, and constants available.
Walkthroughs

Provides step-by-step instructions for common scenarios, making them a good place to begin learning about the various features of Visual FoxPro.


Sample Class Libraries

Visual FoxPro 9.0 Samples
Sample Class Libraries
See Also

The Visual FoxPro sample class library provides encapsulated functionality that you can easily add to your applications. The Solution Samples illustrate using most of the sample classes. The sample classes are contained in the following files:

  • Buttons Class Library

  • Samples Class Library

  • Utility Class Library

  • Registry Program

Buttons Class Library

Buttons.vcx contains the following classes.

Class Description

CmdOK

A command button that releases the form it is added to. If the form is contained in a form set, cmdOK releases the form set.

CmdCancel

A subclass of cmdOK with the Caption property set to "Cancel."

CmdHelp

A command button that invokes Help with the HelpContextID of the form to which it is added.

MailBtn

A container with a command button, a Microsoft MAPI Message control, and a Microsoft MAPI Session control. Code in the Click event of the command button logs on to mail and composes a message containing the values in the current record of a table.

For an example of using the MailBtn class, see SENDMAIL.SCX in the Visual FoxPro Samples\Solution\OLE folder.

VCR

A set of table navigation buttons that makes it possible for a user to move the record pointer to the next, prior, top, and bottom records of a table.

Set the Skiptable property to the alias of the table you want to move the record pointer in. If Skiptable is empty, the record pointer is moved in the currently selected work area.

Samples Class Library

Samples.vcx contains the following classes.

Class Description

CboFontName

A combo box that displays all the currently available fonts in the system.

CboFontSize

A combo box that displays all the available point sizes for a particular font. Pass a font name to the FillList method to populate the combo box. The nLargestFont and nSmallestFont properties delimit the maximum and minimum font sizes displayed. You can use this control in conjuction with the cboFontName class. In the InteractiveChange event of the cboFontName object, call the FillList method of the cboFontSize object:

THISFORM.cboFontSize1.FillList(THIS.Value)

For an example of using this class, see the tbrEditing class in the same class library.

Clock

A container that displays the current date and time.

The "Display a system clock" component in the Solutions sample also uses the Clock class.

Datachecker

A custom class that manages resolving data conflicts. Code in the Error event of the VCR class in BUTTONS.vcx calls the CheckConflicts method of this class if an attempt to write buffered data to a table encounters changed values:

nConflictStatus = ; THIS.DataChecker1.CheckConflicts()

The "Run multiple instances of a form" component in the Solutions sample also uses this class to check for data conflicts.

For more information, open the class and read the comments in the code.

Distinct_values_combo

A combo box that is populated on initialization with the distinct values in the ControlSource alias. For example, if you add this class to a form and set the ControlSource to "customer.country", the combo box will be populated with the countries in the customer table without displaying the country names more than once.

FrmNoTitle

A form with properties set so that no title is displayed. If you want to display information in a separate window, you can create an object based on this class and use form graphics methods.

The "Display line animation on a form" component in the Solutions sample also uses a form with no title to display the animation.

Lookup_combo

A combo box that makes it easy to display values from one field, for example a company name, while binding a ControlSource to another field, for example a company id number. This class has four custom properties:

order_column: Column to sort the table by (optional).

lookup_table: Table to fill the combo box from.

display_column: Column in the table to display.

return_column: Column whose value is written to the ControlSource.

MoverLists

A container with two list boxes and four command buttons. A user can move selected items from one list to the other list by clicking the command buttons or by dragging and dropping.

You need to make sure the RowSourceType of each list box is set to 0 and use the AddItem method to add items to the source list box.

MoverLists has three custom properties:

CanDropIcon: Cursor to be displayed over a valid target in a drag and drop operation.

NoDropIcon: Cursor to be displayed when dropping will not add the selected items to the list box.

DragThreshold: Number of pixels before the drag operation begins.

The "Move items between list boxes" component in the Solutions sample illustrates the use of this class.

Print_reports

A modal form that makes it possible for a user to preview a report, print it, or direct it to a file. You can set the cReport property of the class to the name of the report or pass the report name in as a parameter:

o = CREATEOBJECT(print_reports, ; "myreport.frx")

QBF

A container with three command buttons. Add this class and the VCR class to a form with data-bound controls. When the user chooses Enter QBF, the values in the controls are blanked out. Values that the user enters in the controls specify the filter to be set on the table when the user chooses Query.

The controls need to have a ControlSource set and the Parent of the controls needs to be the form, not another container.

The "Create a query by example form" component in the Solutions sample illustrates the use of this class.

Resizable

A custom class that manages resizing and repositioning the controls on a form at run time, maintaining their relative sizes and positions. Add the class to a form and, in the Resize event of the form, call the AdjustControls method:

THIS.Resizable2.AdjustControls

Resizable has two custom properties you need to set:

RepositionList: A string containing all the classes for which objects are repositioned.

ResizeList: A string containing all the classes for which objects are resized.

The "Resize and reposition controls at run time" component in the Solutions sample illustrates the use of this class.

RTFcontrols

A container class containing cboFontName, cboFontSize and command buttons for Bold, Italic, and ForeColor. The cboFontSize control is refreshed in the InteractiveChange event of cboFontName, but no additional functionality is coded with the Bold, Italic and ForeColor command buttons.

The "Use the RichText control" component in the Solutions sample illustrates the use of this class.

SoundPlayer

This class can be used to play a non-visual multimedia file such as a .WAV audio file. See the following section, Sample Multimedia Classes, for more information about this class.

StopWatch

A container class with a timer and labels to display stop watch values.

StopWatch has three custom methods you'll want to use:

Start: Starts the stop watch

Stop: Stops the stop watch

Reset: Resets the displayed time to 0:00

The "Display a stop watch" component in the Solutions sample illustrates the use of this class.

TbrEditing

tbrEditing has a custom property and a method you'll want to use:

nAppliesTo Property: This property can be set to 1, 2, or 3.

  1. User choices affect the current control on the active form.

  2. User choices affect all text boxes and edit boxes on the active form.

  3. User choices affect all controls on the active form.

Refresh: Accepts an object reference as a parameter and sets all the editing controls to the appropriate values of the object. Call the Refresh method in the GotFocus event of a control.

The "Change font attributes" component in the Solutions sample illustrates the use of this class.

VideoFrame

This class can be used to play a visual multimedia file, such as a video for Windows file. See the following section, Sample Multimedia Classes, for more information about this class.

Sample Multimedia Classes

Two of the classes (SoundPlayer and VideoFrame) in the Visual FoxPro Samples\Classes\Samples.vcx class library make it possible for you to use the MCI (Multimedia Command Interface) to play multimedia files.

To locate documentation for the MCI commands, search for "Multimedia Commands" in the MSDN Library (http://msdn.microsoft.com/library).

Sound Player Class

This class can be used to play a non-visual multimedia file, such as a .WAV audio file. It makes it possible for you to specify the file to be played, and then provides built-in methods to easily play the media file.

Property | Description
AutoOpen | Specifies whether the sound file should be automatically opened and displayed when the object is instantiated. The default value is True (.T.).
AutoPlay | Specifies whether the sound file should be automatically played when it is opened. The default value is True (.T.).
AutoRepeat | Specifies whether the sound file plays continuously. The default value is False (.F.).
ControlSource | Specifies the column that contains the sound file reference. If empty, the class expects a static file name to be in the SoundFile property.
MCIAlias | Specifies the alias to be used by MCI. If left empty, the alias defaults to the Name property of the class. Normally this can be left empty, but if the user wants to play the same sound file twice at the same time, a different alias would need to be specified for each.
SoundFile | Holds the name of a sound file to play, for example "C:\WINDOWS\CHIMES.WAV".

Method | Description
OpenSound | Opens the sound file.
PlaySound | Plays the sound file. The file must be opened with the OpenSound method before it can be played.
PauseSound | Pauses the playing of a sound file. Play can be continued by calling the PlaySound method.
SetPosition | Makes it possible for the user to specify the position of the media file. It can be executed at any time after the file has been opened. Valid values are "Start," "End," or a specific millisecond into the sound.
CloseSound | Closes the sound file and releases all resources associated with it.

VideoFrame Class

The VideoFrame class can be used to play a visual multimedia file such as a video for Windows file. This class makes it possible for you to position and size the video to be played, and then provides built-in methods to easily play the media file.

For an example of using this class, see Video.scx in the Visual FoxPro Samples\Solution\Forms folder.

Property | Description
AutoOpen | Specifies whether the video file should automatically be opened and displayed when the object is instantiated. The default value is True (.T.).
AutoPlay | Specifies whether the video file should automatically play when it is opened. The default value is True (.T.).
AutoRepeat | Specifies whether the video file will loop the video. Setting this to .T. will cause the video to play continuously. The default value is False (.F.).
ControlSource | Specifies a Field that contains the video file reference. If empty, the class expects a static file name to be in the VideoFile property.
MCIalias | Specifies the alias to be used by MCI. If left empty, the alias defaults to the Name property of the class. Normally this can be left empty, but if the user wants to play the same video file twice at the same time, a different alias would need to be specified for each.
VideoFile | Holds the name of a video file to play, for example: "C:\VFP\SAMPLES\SOLUTION\FORMS\FOX.AVI".

Method | Description
CloseVideo | Closes the video file and releases all resources associated with it.
DoMCI | Called by the other methods to execute MCI commands. It can also be called by a user to execute a specific MCI command.
OpenVideo | Opens the video file and shows the first frame.
PauseVideo | Pauses a playing video. The video can be restarted by using the PlayVideo method.
PlayVideo | Plays the video file. The video file must be opened in the OpenVideo method before it can be played.
SetPosition | Makes it possible for the user to specify the position of the media file. It can be executed at any time after the video file has been opened. Valid values are "Start", "End", or a specific millisecond into the video.

Utility Class Library

Utility.vcx contains the following classes.

Class | Description
Arraylib | A custom class with methods for inserting array elements, deleting array elements, and scanning array columns.
Execsp | A custom class with methods that facilitate SQL pass through and executing stored procedures on a remote database.
Filelib | A custom class with methods that perform common string tasks used when manipulating file names, for example, removing the extension, adding a backslash to a path, and so on.
Menulib | A container class with methods that create a shortcut menu from an array. The "Create dynamic shortcut menus" component in the Solutions sample illustrates the use of this class.

Registry Program

Registry.prg contains the following classes.

Class | Description
FileReg | A subclass of the Registry class that provides methods for reading the application associated with particular file extensions and the path to the application.
FoxReg | A subclass of the Registry class that provides methods for reading and writing Visual FoxPro settings in the Windows Registry.
ODBCReg | A subclass of the Registry class that provides methods for reading ODBC data source and driver information.
OldINIReg | A subclass of the Registry class that provides methods for reading and writing to an .INI file.
Registry | A custom class that provides methods for accessing Windows API functions for manipulating the Windows Registry.

For examples of using the registry classes, run SOLUTION.app in the ..\Samples\Solution folder.

See Also

Other Resources

Samples and Walkthroughs
Solution Samples
Visual FoxPro Foundation Classes
Server Samples


Server Samples (Visual FoxPro)

Visual FoxPro 9.0 Samples
Server Samples (Visual FoxPro)

Visual FoxPro includes several samples, which focus on Automation Servers. An Automation server is a COM component application that exposes functionality that can be used and reused by other applications through Automation. In addition, you can create one or more classes to handle enterprise-wide business rules. A client application that uses the business rule object would pass input parameters in a method call, and the Automation server might then do a great deal of work, retrieving or storing data from various sources and performing complex calculations, before returning the answer.

In This Section

FoxISAPI Automation Server Samples

Describes the Visual FoxPro ISAPI extension that makes it possible for you to access Visual FoxPro custom Automation servers from any ISAPI supported Web server, such as Microsoft Internet Information Services (IIS) version 5.0 or later and Microsoft Personal Web Server.
COM+ Samples

Describes samples for using Queued Components, COM+ Events, and Compensation Resource Managers.

Related Sections

Using Visual FoxPro

Provides an overview of Visual FoxPro features, describes concepts and productivity tools for developing, programming, and managing high-performance database applications and components.
Developing Visual FoxPro Applications

Explains concepts about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.
Samples and Walkthroughs

Contains Visual FoxPro code samples and step-by-step walkthroughs that you can use for experimenting with and learning Visual FoxPro features.
Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.


FoxISAPI Automation Server Samples

Visual FoxPro 9.0 Samples
FoxISAPI Automation Server Samples
See Also

Visual FoxPro includes an ISAPI extension called Foxisapi.dll that makes it possible for you to access Visual FoxPro custom Automation servers from any ISAPI supported Web server such as Microsoft Internet Information Services (IIS) version 5.0 or later and Microsoft Personal Web Server. The FoxISAPI extension works by creating an instance of a Visual FoxPro automation server and then calling a method on that server that returns HTML. The HTML is passed from the Web server back to a Web browser such as Microsoft Internet Explorer.

Note:
The Foxisapi.dll is intended solely as a sample ISAPI extension to illustrate using Visual FoxPro automation servers with an ISAPI supported Web server. The Foxisapi.dll should not be used in production or secured systems.

Visual FoxPro includes two FoxISAPI automation server samples that demonstrate how you can use the power of Visual FoxPro to dynamically support a Web site. The first sample, FoxWeb, located in the Samples\Servers\FoxIsapi\FoxWeb folder, is a simple sample designed to demonstrate basic FoxISAPI concepts. This sample steps you through the process of setup and deployment of FoxISAPI servers, both local and remotely. In addition, the sample walks through steps needed to implement pooling of servers for improved scalability.

The second sample, FoxIs, located in the Samples\Servers\FoxIsapi\FoxIs folder, is a more complex sample that contains routines to map visual and functional content of a Visual FoxPro form to HTML. The concepts are the same as FoxWeb; FoxISAPI instantiates a server and invokes a method to return HTML. Because the FoxIs sample uses a visual form, it offers additional versatility by making it possible for you to run it as a stand-alone program, from OLE clients, and from a Web browser.

If you are not familiar with creating Visual FoxPro Automation servers, see How to: Create Automation Servers.

FoxISAPI Components

The following table lists the core FoxWeb Automation server sample files and a description of each.

File | Description
Foxisapi.dll | The main component of the FoxISAPI Automation server samples, FoxWeb and FoxIs. Foxisapi.dll is used with IIS or Microsoft Personal Web Server. Foxisapi.dll creates an instance of a Visual FoxPro Automation server and executes a method on that server. The method then returns the HTML displayed in the Web browser. Foxisapi.dll is used primarily with Visual FoxPro; however, it can be used with any Automation server.
Foxisapi.ini | An initialization file for Foxisapi.dll file that makes it possible for you to configure Foxisapi.dll.
Odebug.prg | A Visual FoxPro program used for debugging your Internet applications.

Configuring FoxISAPI Components

To install the core FoxISAPI components, follow these steps:

  1. Copy the Foxisapi.dll and Foxisapi.ini files to your Web server's script folder. For example, C:\InetPub\scripts\.

  2. Copy the Oldebug.prg program file to your Visual FoxPro root folder (the location returned by HOME( ) function). For example, C:\Program Files\Microsoft Visual FoxPro\.

See Also

Other Resources

FoxWeb, a Simplified Visual FoxPro Internet Automation Server
FoxIs, a Visual FoxPro Internet Server
Solution Samples
Server Samples


FoxWeb, a Simplified Visual FoxPro Internet Automation Server

Visual FoxPro 9.0 Samples
FoxWeb, a Simplified Visual FoxPro Internet Automation Server
See Also

FoxWeb is a simplified ISAPI Automation server sample designed to quickly get a Web site up and running. FoxWeb provides a new version of Foxisapi.dll (also provided with the Visual FoxPro FoxIs server sample). Foxisapi.dll now can manage multiple instances of Visual FoxPro Automation servers, and provides additional debugging methods for Visual FoxPro applications designed for the Internet.

The FoxWeb Automation Server

The FoxWeb sample uses a simple Visual FoxPro server class intended to demonstrate the basic usage of a server run under FoxISAPI. All the code is stored in a file called FoxWeb.prg. This file contains a class called Server, which is marked as OLEPUBLIC so that it gets registered as an Automation server COM component when it is built. This class is instantiated by FoxISAPI and contains a number of methods that can be invoked (such as the Hello and Delay methods) as shown below. These methods illustrate the structures required by FoxISAPI in order to function properly.

The FoxWeb Sample Files

The files for the new Visual FoxPro FoxWeb Automation server sample are located in the Visual FoxPro ...\Samples\Servers\Foxisapi\FoxWeb directory.

Setting up the FoxWeb Automation Server

The following sections describe how to use Visual FoxPro to quickly get a Web site up and running with FoxWeb.

Registering the Visual FoxPro FoxWeb Automation Server

The Visual FoxPro Automation servers that return HTML must be registered. Registration is done automatically if your .exe or .dll was built with the Visual FoxPro Project Manager or with the BUILD EXE, BUILD DLL, or BUILD MTDLL commands. For example, if you open the FoxWeb project provided with the FoxWeb sample in the Project Manager, you can choose Build to create an Automation server as an in-process .dll or an out-of-process .exe file. Note that the registration occurs only on the machine on which the file was built.

A Visual FoxPro Automation server built as an out-of-process .exe can also be registered by specifying the Automation server name and including the /RegServer switch. For example, the following command registers the Visual FoxPro FoxWeb Automation server:

Copy Code
FoxWeb.exe /RegServer

A Visual FoxPro Automation server built as an in-process .dll can also be registered with Regsvr32.exe. For example, the following command registers the Visual FoxPro FoxWeb Automation server:

Copy Code
Regsvr32 FoxWeb.dll
Note:
If your Visual FoxPro ISAPI Automation server uses additional files such as .gif or .jpg files, be sure to place these files in directories that Microsoft Internet Information Services (IIS) or Microsoft Personal Web Server can access.

Using your Web Browser to access a Visual FoxPro ISAPI Automation Server

A Visual FoxPro ISAPI Automation server is accessed from your Web browser by providing the URL (Universal Resource Locator) of the Automation server. The Web browser makes an HTTP request that is passed to Microsoft IIS or the Microsoft Personal Web Server. The Automation server passes the request to Foxisapi.dll, which, in turn, passes the request to your Automation server.

For example, the URL below accesses the ISAPI Automation server named FoxWeb.Server:

Copy Code
HTTP://MyServer/Scripts/Foxisapi.dll/FoxWeb.server.Delay?30

The following table describes each of the elements of the URL example above.

URL Element Description

Myserver

The virtual folder of IIS or the Personal Web Server.

Scripts/Foxisapi.dll

The IIS or Microsoft Personal Web Server Scripts folder and Foxisapi.dll.

FoxWeb.Server

The registered name (ProgID) of the Visual FoxPro ISAPI Automation server to call.

In this example, FoxWeb is the name of the .exe or .dll file for the Visual FoxPro Automation server. Server is the class name specified in the OLEPUBLIC clause of the DEFINE CLASS command that creates the Automation server.

FoxWeb.Server is also the ProgID for the Automation server as it is stored in the Windows Registry. You can use RegEdit to view or modify the Automation server's ProgID.

Delay

The name of the method to execute on the Visual FoxPro ISAPI Automation server.

?30

A parameter passed to the method. The question mark is a delimiter that specifies that a parameter follows. For this method, 30 specifies that execution is delayed for 30 seconds. The parameter is passed as a character string.

Passing Parameters to Methods

The following code is from the Delay method in FoxWeb.prg, and demonstrates the structure for methods executed on the Visual FoxPro ISAPI Automation servers.

Copy Code
PROCEDURE Delay
   LPARAMETERS cParm1, cIniFile, nPersistInstance
   *** Your code here ***
   RETURN AnHTMLString
ENDPROC
cParm1

A character string passed to the method. In the Delay method, this parameter specifies the number of seconds that execution is delayed.
cIniFile

The name of the .ini file (passed to the method by Foxisapi.dll) created each time a Visual FoxPro ISAPI Automation server is accessed. Each .ini file is created in the Scripts folder and has a unique name that begins with "Fox." You can use the GetPrivateProfileString function in FoxWeb.prg, for example, to read information from the .ini file and return custom HTML based on a user's configuration.
nPersistInstance

Specifies if the instance of the Visual FoxPro ISAPI Automation server persists after it is finished executing your method. nPersistInstance is passed by reference to the method by Foxisapi.dll. If nPersistInstance is set to 0 in your Web application, the instance of the Automation server remains alive after execution is finished. If nPersistInstance is a value other than 0, the instance of the Automation server is released. For optimal performance, nPersistInstance should be set to 0, otherwise the Automation server must be launched again the next time it is called.

Using Foxisapi.dll to Pool Automation Servers

Because Foxisapi.dll is free-threaded, it can now pool multiple Visual FoxPro ISAPI Automation servers to provide better scalability for your Web applications. Pooled ISAPI Automation servers allow a free ISAPI Automation server to service a request when other ISAPI Automation servers are busy. To take advantage of ISAPI Automation server pooling, the instances of the ISAPI Automation servers should be made persistent by setting nPersistInstance to 0 in your Web application.

The number of ISAPI Automation servers available to service requests is determined by settings in your Foxisapi.ini initialization file. To create a pool of multiple ISAPI Automation servers, include an entry in square brackets with the name of the ISAPI Automation server for which a pool is created. This entry is followed with a list of ISAPI Automation servers that comprise the pool, with a numeric value that specifies the maximum number of instances of each ISAPI Automation server that can be created.

For example, placing the following lines in Foxisap.ini creates a pool of seven ISAPI Automation servers for service requests to FoxWeb.myserver. Foxisapi.dll creates up to four instances of the FoxWeb.server ISAPI Automation server and up to three instances of the FoxWeb2.server ISAPI Automation server to service requests.

Copy Code
[FOXWEB.MYSERVER]
FOXWEB.SERVER=4
FOXWEB2.SERVER=3

The following URL executes the Delay method on either an instance of the FoxWeb.server or the FoxWeb2.server ISAPI Automation servers:

Copy Code
HTTP://MyServer/Scripts/Foxisapi.dll/FoxWeb.Myserver.Delay?30

Foxisapi.ini can specify that the ISAPI Automation servers are instantiated up front before a service request is received. To do so, add a comma followed by an asterisk (*) after the number of instances, as shown in the following example.

Copy Code
[FOXWEB.MYSERVER]
FOXWEB.SERVER=4,*
FOXWEB2.SERVER=3,*

Using the Pool Manager across Multiple Machines

Foxisapi.dll provides the ability to manage Visual FoxPro ISAPI Automation servers on multiple machines. You can use Remote Automation or DCOM (Distributed Component Object Model) to access the ISAPI Automation servers. Note that for optimal performance and scalability the instances of the ISAPI Automation servers should be made persistent by setting nPersistInstance to 0 in your Web application.

The following example describes a scenario where two Visual FoxPro ISAPI Automation servers, FoxWeb and FoxWeb2, are placed on two machines.

Machine_A is your local machine running Windows 98, DCOM, and Personal Web Server. Machine_B is your remote machine, accessible over your network, running Windows 2000 and DCOM.

  1. Machine_A is your Visual FoxPro development machine on which you've installed the Visual FoxPro FoxISAPI Automation server samples. On this machine, open the FoxWeb project in the Visual FoxPro Project Manager, and choose Build to create an ISAPI Automation server as an out-of-process .exe file. Building the .exe automatically registers the ISAPI Automation server on the machine as FoxWeb.exe. Now open the FoxWeb2 project in the Visual FoxPro Project Manager, and choose Build to create and register another ISAPI Automation server as an .exe file.

  2. To verify that the ISAPI Automation servers FoxWeb and FoxWeb2 are properly registered, you can use RegEdit and search for FoxWeb and FoxWeb2. Note that the ProgIDs for the servers are FoxWeb.Server and FoxWeb2.Server, respectively. Server is the class name specified in the OLEPUBLIC clause of the DEFINE CLASS command that creates the ISAPI Automation server. FoxWeb.prg is the Visual FoxPro Internet application included in both the FoxWeb and FoxWeb2 projects.

    The ProgIDs for the ISAPI Automation servers both point to Machine_A, the local machine. The Registry settings for the FoxWeb2 ISAPI Automation server need to be changed to point to Machine_B, the remote machine.

  3. Now copy the FoxWeb2.exe, FoxWeb2.vbr, and FoxWeb2.tlb files from Machine_A, the local machine, to Machine_B, the remote machine.

  4. Use the /RegServer option to register FoxWeb2.exe on Machine_B at the MS-DOS prompt:

    Copy Code
    C:\VFP\FOXWEB2.EXE /RegServer
  5. Finally, stop and restart the Personal Web Server on Machine_A to ensure that it is aware of the changes to the Registry.

You can execute the Status command on Foxisapi.dll to check the status of all the ISAPI Automation servers registered in Foxisapi.ini. The following URL executes the Status command:

Copy Code
HTTP://Machine_A/Scripts/FoxISAPI.dll/Status

You can execute the Reset command on Foxisapi.dll to reset all the ISAPI Automation servers registered in Foxisapi.ini. The Reset command releases all ISAPI Automation server instances. The following URL executes the Reset command:

Copy Code
HTTP://Machine_A/Scripts/FoxISAPI.dll/Reset

To test the installation, you can open up as many instances of your Web browser as there are ISAPI Automation servers in the pool. The Web browsers can be on multiple machines connected to your network. You can then call the Delay method in the URL from each Web browser so that Foxisapi.dll routes service requests to the other free ISAPI Automation servers. After the Delay method is executed from each Web browser, you can use the Status method to check to see if all ISAPI Automation servers in the pool received service requests.

Using FoxISAPI with DLL Servers

If you use FoxISAPI with multithreaded in-process servers in the previous version of Visual FoxPro, you need to disable Pool Manager support in FoxISAPI. You can do this by using the PoolMode setting in the FoxIsapi.ini file. The PoolMode setting is global to all servers, so we recommend that you do not let a single FoxIsapi.dll service both EXE and DLL servers. Instead, you should copy and rename the FoxIsapi.dll and FoxIsapi.ini files so that you have one set for EXE servers and one for DLL servers.

Debugging your ISAPI Automation Servers

FoxIsapi.dll also makes it possible for you to debug your ISAPI Automation servers on your local machine. Set the number of instances of the ISAPI Automation server you wish to debug to 0 as shown in the following example FoxIsapi.ini file:

Copy Code
[FOXWEB.MYSERVER]
FOXWEB.SERVER=0

The Odebug.prg program file must be present in your Visual FoxPro root folder and the ISAPI Automation server source files must be present. Be sure that the ISAPI Automation server you wish to debug is configured as a persistent ISAPI Automation server, and debugging information is turned on in the project containing the ISAPI Automation server source files.

When the ISAPI Automation server is instantiated, Foxisapi.dll starts Visual FoxPro for debugging, making it possible for you to set breakpoints, trace through code, and so on.

Foxisapi.dll Commands

Foxisapi.dll has commands you can call to determine the status of your ISAPI Automation servers and to reset the servers. The following table lists the Foxisapi.dll commands with a description of each.

Command | Description
MultiMode | Executes the Reset command, then limits the number of ISAPI Automation server instances to the values specified in Foxisapi.ini.
PoolMode | Enables or disables Pool Manager support in FoxISAPI. Use this command to turn off Pool Manager for in-process DLL servers. 0 – disables 1 - enables (default)
Reset | Releases all instances of the ISAPI Automation servers.
SingleMode | Executes the Reset command, then limits the number of ISAPI Automation server instances to one instance. Execute this command to perform maintenance; for example, you can open tables exclusively in when SingleMode is in effect.
Status | Displays the current status of the ISAPI Automation servers, the Foxisapi.ini settings, and whether SingleMode or MultiMode is in effect.

Each of the Foxisapi.dll commands is called by a URL that is specified in Foxisapi.ini. The following is the contents of the sample Foxisapi.ini file with the default URLs:

Copy Code
[FOXISAPI]
StatusURL = Status
ResetURL = Reset
SingleModeURL = SingleMode
MultiModeURL = MultiMode

The following URL executes the Status command:

Copy Code
HTTP://MyServer/Scripts/Foxisapi.dll/Status

In the following sample Foxisapi.ini file, the URL for the Status command is changed from Status to MyStatus:

Copy Code
[FOXISAPI]
StatusURL = MyStatus
ResetURL = Reset
SingleModeURL = MSingleMode
MultiModeURL = MultiMode

After this change to Foxisapi.ini, the following URL executes the Status command:

Copy Code
HTTP://MyServer/Scripts/FoxISAPI.dll/MyStatus
Note:
You must reset Foxisapi.dll with the Reset command after you make changes to Foxisapi.ini file in order for the changes to take effect.

Additional FoxISAPI.ini Settings

Foxisapi.dll reads Foxisapi.ini and configures its settings according to the items contained in Foxisapi.ini. The following table describes each of the additional items you can place in your Foxisapi.ini file.

Item | Description
AutoRefreshStatus | Specifies the number of seconds between Status page refreshes. The default is 0 seconds (the Status page isn't refreshed) if this item is omitted or if Foxisapi.ini isn't present.
BusyTimeout | Specifies the number of seconds Foxisapi.dll waits for the Visual FoxPro application servers to respond before a time-out message is generated. The default is 2 seconds if this item is omitted or if Foxisapi.ini isn't present.
ReleaseTimeout | Specifies the number of seconds Foxisapi.dll waits for a busy Visual FoxPro application server to respond before the Reset command is executed. The default is 2 seconds if this item is omitted or if Foxisapi.ini isn't present.

The following is taken from the sample Foxisapi.ini file, and demonstrates the formats of the additional items you can place in the file:

Copy Code
[FOXISAPI]
BusyTimeout = 5
ReleaseTimeout = 15
Note:
You must reset Foxisapi.dll with the Reset command after you make changes to Foxisapi.ini file in order for the changes to take effect.

Configuration Tips for Microsoft Internet Information Services (IIS)

Two Microsoft IIS registry entries, PoolThreadLimit and ThreadTimeout, can be added to your registry to improve performance with the Visual FoxPro FoxISAPI Automation servers. These registry entries determine the total number of threads that Internet Information Services can create, and the length of time the threads exist. For more information about these registry entries, see the Internet Information Services documentation.

A Microsoft Knowledge Base article titled "How to Launch Automation servers from ISAPI Extensions" (number Q156223) is available on www.microsoft.com. This article provides information about the access security permissions required to launch Automation servers such as the Visual FoxPro ISAPI Automation Servers.

See Also

Other Resources

Solution Samples
FoxISAPI Automation Server Samples
FoxIs, a Visual FoxPro Internet Server


FoxIs, a Visual FoxPro Internet Server

Visual FoxPro 9.0 Samples
FoxIs, a Visual FoxPro Internet Server
See Also

FoxIs, located in the Visual FoxPro ...\Samples\Servers\Foxisapi\FoxIs directory, illustrates creating an out-of-process .exe or in-process .dll with ISAPI functionality that can be accessed from within Visual FoxPro as a stand-alone program, from Automation clients, and from a Web browser. Changes you make to its classes can enhance the Automation server, no matter how it is run.

To open the FoxIs sample project

  • Type the following in the Command window:

    Copy Code
    MODIFY PROJECT (HOME(2) + 'servers\foxisapi\foxis\foxis')

Running the FoxIs Sample

You can run the FoxIs sample four different ways. When you are trying out the code, it's a good idea to go run the sample in this order:

Running from Within Visual FoxPro

To run the FoxIs sample from within Visual FoxPro, run the following code in the Command window.

Copy Code
SET DEFAULT TO (HOME(2) + 'servers\foxisapi\foxis\')
SET CLASSLIB TO employee
ox = CREATEOBJECT('employee')
ox.show

Running as an Independent Executable

You can build the sample into an executable file with the following line of code:

Copy Code
BUILD EXE foxis FROM foxis

The compiled file, FOXIS.EXE, is a Windows program that can be added to the Windows Start menu, started from the Windows Explorer, and so on.

Running as an Automation server

Once the FoxIs sample has been compiled into a .exe or a .dll, it is registered as an Automation server in the Windows registry. You can create an object based on the employee class from any OLE controller, for example Excel, Visual Basic, and Visual FoxPro:

Copy Code
ox = CREATEOBJECT('foxis.employee')
ox.SHOW

Running from a Web Browser

You can even run the FoxIs sample from a Web browser, which could be on another machine such as a 286 running MS-DOS, a Unix machine, a Macintosh, or a Personal Digital Assistant.

System Requirements for Internet Use

To run the FoxIs sample from a Web browser, you must be running:

  • Windows 98 or Windows 2000 or later.

  • An ISAPI-compatible Web server, such as the Microsoft Personal Web Server for Windows 98 or Microsoft Internet Information Services (IIS). IIS comes with Windows 2000 and later and can be downloaded from www.microsoft.com; Personal Web Server also can be downloaded from www.microsoft.com.

If you're using Windows 2000 or later, you need to run the DCOMCNFG utility to configure DCOM to give rights to the IIS service to instantiate OLE objects.

To configure Windows 2000 or later DCOM

  1. At the Command prompt, type DCOMCNFG and press Enter.

  2. In the Applications tab, select the name of the Automation server. When you build the server, the application is "employee" by default.

  3. In the Default Security tab of the Distributed COM Configuration Properties dialog box, choose Edit Default for each area: Default Access Permissions, Default Launch Permissions, and Default Configuration Permissions.

  4. In the Registry Value Permissions dialog box for each area, choose Add.

  5. In the Add Names box of the Add Users and Groups dialog box, type your WWW server's name and your login user name.

    You can see the server's name in the Microsoft Internet Service Manager Properties window. If your machine name is MINE, the following line in the Add Names box sets up a default user:

    Copy Code
    \MINE\IUSR_MINE

    If your machine name is MINE and you log in as HOMER, the following line in the Add Names box sets up permissions for you when you login:

    Copy Code
    \MINE\HOMER

Setting Up the FoxIs Sample for Internet Access

To set up the FoxIs sample, you need to create a .exe or .dll from the FoxIs project, and then copy the file to your Inetsvr\Scripts directory.

To set up the FoxIs Sample

  1. Open the FOXIS project.

  2. Choose the Build button, and then choose Build COM DLL.

  3. Copy Foxisapi.dll to your Inetsrv\Scripts folder.

Preliminary Testing

You can test the FoxIs sample application at various levels to see if you are configured correctly.

To see if the code works

  1. From the Program menu choose Do.

  2. Select Main.prg in the Visual FoxPro Samples\Servers\Foxisapi folder.

  3. Choose Do.

To see if the .EXE works

  1. From the Visual FoxPro Command window, issue the following command:

    Copy Code
    BUILD EXE Foxis.exe FROM foxis

  2. Double-click Foxis.exe in the Windows Explorer.

To see if the FoxIs Automation server works

  • Run the following commands:

    Copy Code
    OX= CREATEOBJECT('FOXIS.EMPLOYEE')
OX.Show    && See if it works as a ISAPI Automation server
?OX.Startup( )  && See if it returns html

It is much easier to debug Automation servers from an Automation controller (such as Visual FoxPro) before instantiating it in FoxIs.

Set up the HTML page

To get things started, you need an HTML page that contains a reference to a URL. For example, take the following code and put it in the Wwwroot\default.htm file.

Copy Code
<a HREF="/scripts/foxisapi.dll/FoxIS.employee.startup"> <i>VFP ISAPI AUTOMATION SERVER DEMO PAGE</i> </a>

Then use a browser (which can be on the same machine) and connect to YourMachineName. For example, if your machine name was "myMachine," then type "myMachine" as the URL to go to. This would bring up the Default.htm page on the server named "myMachine"

A CreateObject("foxis.employee") is initiated and the Startup method is invoked on the object, which returns a generated HTML page. If the ISAPI Automation server hasn't been built yet, then the Foxisapi.dll returns an HTML error page.

Then use your Web browser to access the href above. If you get an error HTML page that says "Foxisapi error", then you know the DLL is being loaded and is working.

Copy Code
 <FORM ACTION = "/scripts/foxisapi.dll/foxis.employee.cmd">
<INPUT NAME="Cmd" VALUE = "Reset">
<INPUT TYPE="submit" VALUE="Dos Command">
</FORM>

You can actually put in any valid MS-DOS command and it will be executed on the server machine. If the command is "Reset" (default), then it will make the ISAPI Automation server release the first instance as well as it's own, thus releasing the ISAPI Automation server completely.

In addition, you can evaluate any Visual FoxPro expression. However, if the Visual FoxPro expression displays a modal interface, as the MESSAGEBOX( ) function does, the Automation server will hang waiting for a response that cannot be provided. However, for an in-process .dll, the modal interface is automatically managed and the Automation server won't hang.

Copy Code
<FORM ACTION = "/scripts/foxisapi.dll/foxis.employee.cmd?FOXCMD">
<INPUT NAME="Cmd">
<INPUT TYPE="submit" VALUE="Fox Expression">
like "today is "+ cdow(date()) or 45 * 3 or SYS(2004)
</FORM>

Debugging the Server

A Windows NT service has no Desktop, therefore no user interface will appear on the server machine. This means you should debug your server applications before deploying them.

To trace through Foxisapi.dll with Visual C++ 5.0

  1. Open Foxisapi.mak.

  2. Remove the comment mark from the following line in HttpExtensionProc:

    Copy Code
    //   _asm int 3

  3. Rebuild the project.

  4. Start MSDEV with the process id (PID) of Inetinfo.exe. You can get the process id in the Windows Task Manager.

This process applies to Windows 2000 or later.

Tip:
When debugging, you don't have to shut down the Web server to change the Automation server. You can just terminate the out-of-process component by sending a reset value to the cmd method, as described above, or by using the Win32 SDK tools TLIST, KILL, PVIEW, or the Task Manager in Windows 2000 or later.

The ISForm Class

The "engine" of the sample is the ISForm class in Isapi.vcx.

Entry Points into the ISForm Class

The following methods can be called from the Web browser, by way of Foxisapi.dll, to return HTML pages.

Method | Returns
Cmd | Evaluation of a Visual FoxPro expression or the results of a MS-DOS command.
DoSave | Saves the user changes to the data and returns the employee HTML page.
Skipit | The employee information for the specified employee in the table. Skipit takes cookie information passed in as a parameter from the Web browser, checks the cookies table to find the previous record number, and moves the record pointer forward or backward relative to the record number stored in the cookies table. The new record number is written back to the cookies table and the GenHTML method is called.
Startup | The employee information for the first employee in the table. Startup creates a new cookie id for the user and sends it back as a hidden input area in the HTML.

Keeping the Server Active

Normally, for each request from a Web client, the Automation server is instantiated, generates an HTML page, and is released with the Release( ) call in CallObject( ) in Foxisapi.cpp. This means the entire Visual FoxPro runtime will start up and shut down for each request.

If the ISAPI Automation server is registered as Multi-Use, and the Release( ) is not called, then the first request will start up the server but subsequent requests will use the same instance of the server, making performance much better. Code in Foxisapi.dll and in the Load, Cmd, DoSave, Startup, and Skipit methods of the ISForm manage keeping the same instance of the server active.

Variables in the DLL

Two variables are declared: pdispObj and pdispDoRelease. When the server is initially created, pdispObj is the dispatch handle to the OLE object. The pdispDoRelease variable is set to the same value as pdispObj and passed by reference as a parameter to the method of the ISForm server that was requested by the Web browser. Code in the Visual FoxPro ISForm Automation server can change the value of pdispDoRelease.

Tip:
For more information about this sample, see the comments in the code in ISForm and Foxisapi.cpp.

The Form Load Event

When the ISForm is created, code in the Load event creates two public variables, gpInstance and gpDisp. The first time the ISForm server is loaded, the gpInstance variable is set to 1. Subsequent instances increment this variable. When an instance is released, gpInstance is decremented.

The Entry Point Methods

When a method (Cmd, DoSave, Skipit, or Startup) of the ISForm is invoked through Foxisapi.dll, the .dll passes a dispatch pointer by reference as a parameter to the method.

The first time the server is run, the instance count is set to 1 and the dispatch pointer is stored to the global variable. Then value 0 is stored to the dispatch pointer.

Copy Code
IF m.gnInstance = 1
   IF TYPE('pDisp') $ 'NI'
      gpDisp = m.pDisp
      pDisp = 0
   ENDIF
ENDIF

At this point, two variables point to the same dispatch pointer value: gpDisp in the ISForm Automation server and pdispObj in Foxisapi.dll. The value of pdispDoRelease in the .dll is 0, as changed in the ISForm Automation server.

Subsequent times the server is called the instance count in incremented, a new pdispObj is generated in the .dll, stored to pdispDoRelease, and passed by reference to the requested method. Because the gnInstance value is not 1, the gpDisp variable is not changed. From this point on, gpDisp in the Automation server holds a different value than pdispObj and pdispDoRelease in the .dll.

Releasing the Server

To force a release, pdispDoRelease cannot be 0 and must be a different value than pdispObject. The following HTML text sends a value to the server that affects a release:

Copy Code
 <FORM ACTION = "/scripts/foxisapi.dll/foxis.employee.cmd">
<INPUT NAME="Cmd" VALUE = "Reset">
<INPUT TYPE="submit" VALUE="Dos Command">
</FORM>

The following code in the cmd method sets the pdispDoRelease value to the dispatch value of the first instance.

Copy Code
CASE 'RESET'$upper(m.p1)
   m.pDisp= m.gpDisp

Code in the .dll will now release the current instance and the original instance that has been kept in existence to prevent the Visual FoxPro runtime from having to be reloaded each time the server was called.

Sending HTML Back to the Client

The GenHTML method of the ISForm class is called from each of the entry point methods. The HTML returned from the GenHTML method is returned to the Web browser through Internet Information Services.

If the mode parameter passed to the GenHTML method is not "FORM," the GenHTML method simply looks up the value in a table and sends back preformatted HTML.

Copy Code
IF m.mode != 'FORM'
   =SEEK(m.mode,'html')
   rv = html.html
  RETURN m.rv
ENDIF

If the mode parameter is "FORM," code in GenHTML identifies each of the labels and textboxes on the form, sorts them in top to bottom and left-to-right order, evaluates the Captions and ControlSources of the controls, and uses Visual FoxPro's text merge capabilities to construct the appropriate HTML text to approximate the display of the form.

If you add additional labels and text boxes to the form, they are automatically displayed in the generated HTML.

Creating and Using Cookies

As a Web server, this application can be hit dozens of times by various clients, and we need to keep track of the user state. In this case, we only track the current record number for that user. We could present the user with a login screen, and use the username as a key for the cookie, but instead we generate a cookie value in the MakeCookie method and pass it as a hidden value in the HTML sent back to the user. Each time the user chooses to go to a different record, we can read the cookie value from the HTTP string sent to the .dll, locate the cookie in the Cookies table, find the current record number and move the record number relative to this number.

The following property and methods are used in the cookie manipulation process:

  • Cookie property

  • GetCookie method

  • MakeCookie method

  • WriteCookieInfo method

Error Handling

If an error occurs, code in the Error event of the ISForm class calls the GenHTML method with a parameter of "ERROR." GenHTML reads the pre-formatted HTML text for errors and returns it to the Error event code. The Error event code substitutes error information for placeholders in the HTML:

Copy Code
   LOCAL rv
   rv = THIS.GenHTML('ERROR')
   rv = strtran(m.rv,'%METHOD%',m.cMethod)
   rv = strtran(m.rv,'%ERRORNO%',STR(m.nError,4))
   rv = strtran(m.rv,'%ERRORMSG%',Message(1))
   rv = strtran(m.rv,'%LINENO%',STR(m.nLine,4))
   THIS.ErrorHTML = m.rv

When the ErrorHTML property isn't empty, GenHTML sends the value of ErrorHTML back to the client.

Tables Used in the FoxIs Sample

In addition to the employee table used for data entry and display, the FoxIs sample uses the following tables.

Table | Description
HTML | Holds HTML text to be sent back to the Web browser as a header for FoxCMD and DosCMD evaluations or in case of an error.
Cookies | Keeps track of record numbers for various Web browsers. The unique cookie field value is passed as a hidden value in HTML text sent to a particular user.

See Also

Other Resources

Solution Samples
FoxISAPI Automation Server Samples
FoxWeb, a Simplified Visual FoxPro Internet Automation Server


COM+ Samples

Visual FoxPro 9.0 Samples
COM+ Samples
See Also

Windows 2000 introduces a new set of component services (COM+ Services) that extend the ability to create rich distributed transactional solutions for your Windows or Web applications. Visual FoxPro includes new and enhanced server features to better support many of these services. The COM+ samples are very simple and meant to show basic concepts of using a specific COM+ Service. Samples for using Queued Components, COM+ Events, and Compensation Resource Managers are located in the ...\Samples\COM+ folder. For more information, see the Readme.htm file in the folder.

Some of the COM+ Services, such as Transactions, existed prior to Windows 2000 and were supported by Visual FoxPro. New services, such as COM+ Events and Queued Components, offer new options for your applications that were not available previously in Visual FoxPro.

See Also

Other Resources

Server Samples
FoxISAPI Automation Server Samples


Solution Samples

Visual FoxPro 9.0 Samples
Solution Samples

Visual FoxPro Solution samples demonstrate particular features of Visual FoxPro and can be run independently. The Solution samples also include examples based on the Visual FoxPro Foundation Classes.

You can run Visual FoxPro Solution samples from the Visual FoxPro Task Pane Manager, which includes functionality for searching and installing additional samples. You can also run the Solution samples from the Solution sample application located in ...\Samples\Solution\Solution.app.

In This Section

How to: Run Visual FoxPro Solution Samples

Describes how to run samples from the Task Pane Manager.
ActiveX Solution Samples

Contains Solution samples that illustrate how you can use ActiveX controls in Visual FoxPro.
Automation Solution Samples

Contains Solution samples that illustrate how you can perform automation with files from other applications.
Controls Solution Samples

Contains Solution samples that illustrate application development tasks you can perform with controls.
Data Solution Samples

Contains Solution samples that illustrate application development tasks you can perform with different data sources.
Databases Solution Samples

Contains Solution samples that illustrate application development tasks you can perform with databases.
Forms Solution Samples

Contains Solution samples that illustrate application development tasks you can perform with forms.
Menus and Toolbars Solution Samples

Contains Solution samples that illustrate application development tasks you can perform with menus and toolbars.
Programming Solution Samples

Contains Solution samples that illustrate a variety of programming tasks you can perform with Visual FoxPro.
Reports Solution Samples

Contains Solution samples that illustrate tasks you can perform with reports.
Views and Queries Solution Samples

Contains Solution samples that illustrate application development tasks you can perform with queries and views.
Windows API Solution Samples

Contains Solution samples that illustrate application development tasks you can perform with the Windows API.
Miscellaneous Solution Samples

Contains Solution samples that illustrate other tasks you can perform with Visual FoxPro features.

Reference

Visual FoxPro Foundation Classes A-Z

Describes Visual FoxPro Foundation classes you can use for rapid application development.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.

Related Sections

Samples

Contains samples you can use to learn more about the features in Visual FoxPro.
Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Server Samples

Contains samples that illustrate Automation Servers.
Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Walkthroughs

Contains step-by-step instructions for common scenarios.


How to: Run Visual FoxPro Solution Samples

Visual FoxPro 9.0 Samples
How to: Run Visual FoxPro Solution Samples
See Also

You can run Visual FoxPro Solution samples from the Visual FoxPro Task Pane Manager, which includes functionality for searching and installing additional samples.

To run Solution samples

  1. To open the Task Pane Manager, select Task Pane from the Tools menu.

  2. From the Task Pane Manager toolbar, select Solution Samples.

  3. From one of the sample categories, choose a sample that you want to run.

  4. To run the sample, click the hyperlink for the sample. To see code for the sample, click the Click here to view the code icon located to the right of the sample description.

For more information about the Task Pane Manager, see Task Pane Manager.

You can also run the Solution samples from the Solution sample application located in ...\Samples\Solution\Solution.app.

See Also

Other Resources

Solution Samples


ActiveX Solution Samples

Visual FoxPro 9.0 Samples
ActiveX Solution Samples

These Solution samples illustrate how you can use ActiveX controls in Visual FoxPro.

In This Section

Add and Remove Items in a Treeview Control Sample

Illustrates how to add, delete, and select nodes for a treeview control, which displays a collection of Node objects. This sample also illustrates how to write and read a treeview hierarchy to and from a table.
Customize the Open Dialog Box Sample

Illustrates how to customize the appearance and behavior of the Open dialog box.
Display System Information Sample

Illustrates how to use the SysInfoControl to display system information and notify when a system setting changes.
Play an AVI File in an ActiveX Control Sample

Illustrates how to use the Multimedia control to play an AVI file in a control that has the hWnd property.
Provide a Hierarchical Display of Items Sample

Illustrates how to use two different types of ActiveX controls to display a hierarchy of items, for example, as an outline.
Send Mail Sample

Illustrates how to create a simple messaging form that can send Visual FoxPro data to an e-mail address.
Use Slider and Status Bar Controls Sample

Illustrates how to use the Slider control and StatusBar control.
Use the RichText Control Sample

Illustrates how to use a RichText control to display and edit RTF text in the memo field of a table.

Reference

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Classes A-Z

Describes Visual FoxPro Foundation classes you can use for rapid application development.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.

Related Sections

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Classes A-Z

Describes Visual FoxPro Foundation classes you can use for rapid application development.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.


Add and Remove Items in a Treeview Control Sample

Visual FoxPro 9.0 Samples
Add and Remove Items in a Treeview Control Sample
See Also

File: ...\Samples\Solution\OLE\Bldtree.scx

A treeview control displays a collection of Node objects, each of which consists of a label and an optional bitmap. After creating a treeview control, you can add, remove, arrange, and otherwise manipulate Node objects by setting properties and invoking methods.

This sample illustrates adding nodes to a treeview control, deleting nodes, selecting nodes programmatically, writing a treeview hierarchy to a table, and reading a treeview hierarchy from a table.

Adding Nodes

Each node in a treeview control needs to have a unique key that is a character string, generated by the NewKey method in this sample form.

Copy Code
*NewKey method
cKey = THIS.cNextKey
THIS.cNextKey = ALLTRIM(STR(VAL(THIS.cNextKey) + 1) + "_")
RETURN cKey

The Add method of the treeview control is used to add new nodes. The code associated with the Click event of cmdNewNode adds a root level node using the Add method.

Copy Code
o = THISFORM.oleTree
o.Nodes.Add(,1,THISFORM.NewKey(),"Click to edit text",0)

The code associated with the Click event of cmdNewChild adds a node as a child of the currently selected node.

Copy Code
o = THISFORM.oleTree
IF !ISNULL(o.SelectedItem) THEN
   o.Nodes.Add(o.SelectedItem.Key, 4, THISFORM.NewKey(), "Click to edit text",0)
ENDIF

Deleting Nodes

You can delete all of the nodes by calling the Clear method.

Copy Code
THISFORM.oleTree.Nodes.Clear

Or you can use the Remove method to delete selected nodes. All children of the deleted node are also deleted.

Copy Code
THISFORM.oleTree.Nodes.Remove(THISFORM.oleTree.SelectedItem.Key)

Writing and Reading Hierarchies in Tables

To save your treeview hierarchy in a table so you can reload it and edit it, loop through all the nodes in the treeview control and write the Key, the parent node's Key, and the Text to the appropriate fields of a table.

Copy Code
FOR i = 1 TO loNodes.Count
   IF ISNULL(loNodes.Item(i).Parent)
      lcParent = "0_" && Root
   ELSE
      lcParent = loNodes.Item(i).Parent.Key
   ENDIF
   INSERT INTO (lcDBFName) VALUES ;
      (loNodes.Item(i).Key, ;
       lcParent, ;
       loNodes.Item(i).Text)
ENDFOR

To reconstruct the treeview hierarchy, scan through the records in the table, using the parent key, key, and text values that you previously stored.

Copy Code
* Fill the TreeView control with values in the table.
o = THISFORM.oleTree.Nodes
   SCAN
      IF ALLTRIM(parent) = '0_'
         o.add(,1,ALLTRIM(key),ALLTRIM(text),0)
      ELSE
         o.add(ALLTRIM(parent),4,ALLTRIM(key), ALLTRIM(text),0)
      ENDIF
      THISFORM.cNextKey = ALLTRIM(STR(VAL(key) + 1) + "_")
   ENDSCAN

See Also

Other Resources

Treeview/Listbox Drag and Drop
ActiveX Solution Samples
Solution Samples


Customize the Open Dialog Box Sample

Visual FoxPro 9.0 Samples
Customize the Open Dialog Box Sample
See Also

File: ...\Samples\Solution\OLE\Commdlog.scx

This sample demonstrates how you can customize the appearance and behavior of the Open dialog box as exposed through the Common Dialog control.

To specify the behavior of the Open dialog box, you can set the Flags property of the Common Dialog control to the sum of specific flag values. The following table lists the possible individual values you can use.

Value | Description
1 | Causes the read-only check box to be initially checked when the dialog box is created. This flag also indicates the state of the read-only check box when the dialog box is closed.
2 | Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.
4 | Hides the read-only check box.
8 | Forces the dialog box to set the current directory to what it was when the dialog box was opened.
16 | Causes the dialog box to display the Help button.
256 | Specifies that the common dialog box makes it possible for invalid characters in the returned file name.
512 | Specifies that the File Name list box makes it possible for multiple selections. The user can select more than one file at run time by pressing the SHIFT key and using the UP ARROW and DOWN ARROW keys to select the desired files. When this is done, the File Name property returns a string containing the names of all selected files. The names in the string are delimited by spaces.
1024 | Indicates that the extension of the returned file name is different from the extension specified by the DefaultExt property. This flag isn't set if the DefaultExt property is Null, if the extensions match, or if the file has no extension. This flag value can be checked upon closing the dialog box.
2048 | Specifies that the user can enter only valid paths. If this flag is set and the user enters an invalid path, a warning message is displayed.
4096 | Specifies that the user can enter only names of existing files in the File Name text box. If this flag is set and the user enters an invalid file name, a warning is displayed. This flag automatically sets the 2048 flag.
8192 | Specifies that the dialog box prompts the user to create a file that doesn't currently exist. This flag automatically sets the 4096 and 2048 flags.
16384 | Specifies that sharing violation errors will be ignored.
32768 | Specifies using the Windows Explorer Open A File dialog box template.
524288 | Use the Explorer Open A File dialog box template.
1048576 | Do not dereference shell links (also known as shortcuts). By default, choosing a shell link causes it to be dereferenced by the shell.
1048576 | Do not dereference shortcuts (shell links). By default, choosing a shortcut causes it to be dereferenced by the shell.
2097152 | Makes it possible for the user to use long file names.

The following code in the Click event of cmdFiles checks the values of the various check boxes on the form and sets the Flags property of the Common Dialog control.

Set the Read-only Check Box Flag

Copy Code
IF !thisform.chkRead.Value
   m.nFlags = m.nFlags + 4
ENDIF

Set the Multiple Files Flag

Copy Code
IF thisform.chkMulti.Value
   m.nFlags = m.nFlags + 512
ENDIF

Set the Help Button Flag

Copy Code
IF thisform.chkHelp.Value
   m.nFlags = m.nFlags + 16
ENDIF

Set the Enforce File Existence Flag

Copy Code
IF thisform.chkMulti.Value
   m.nFlags = m.nFlags + 4096
ENDIF

Set the Flags Property of the Common Dialog Control

Copy Code
THISFORM.oleCommDlog.Flags = m.nFlags

Set the Filter Property of the Common Dialog Control

You can use the Filter property of the Common Dialog control to specify what files a user is allowed to choose.

Copy Code
THISFORM.oleCommDlog.Filter = "All files" + ;
   "(*.*)|*.*|Text (*.txt)|*.txt" + ;
   "|Pictures(*.bmp;*.ico)|*.bmp;*.ico"

See Also

Other Resources

ActiveX Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Display System Information Sample

Visual FoxPro 9.0 Samples
Display System Information Sample
See Also

File: ...\Samples\Solution\OLE\Sysinfo.scx

This sample illustrates using the SysInfoControl to display system information and to notify when a system setting changes.

The bulk of the code in this sample is in the CheckStatus method. Code in this method checks the settings of various SysInfoControl properties to see their current settings, and populates a treeview control with this information. For example, the following section of code checks the BatteryLifePercent setting:

Copy Code
IF ThisForm.SysInfo.BatteryLifePercent = 255
   * Add a node to display the information
ENDIF

When a system setting changes, an event of the SysInfoControl occurs. Code associated with each of these events sets the caption of a label and calls the CheckStatus method to refresh the treeview control. For example, the following code is associated with the SysColorsChanged event:

Copy Code
ThisForm.Status.Caption = SysColorsChanged_LOC
ThisForm.CheckStatus

See Also

Other Resources

ActiveX Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Play an AVI File in an ActiveX Control Sample

Visual FoxPro 9.0 Samples
Play an AVI File in an ActiveX Control Sample
See Also

File: ...\Samples\Solution\OLE\Mmsample.scx

This sample shows how to use the Multimedia control to play an AVI file in a control that has an hWnd property.

The control with the hWnd is a custom ActiveX Control called hWin, created with the OLE Control Wizard in Microsoft Visual C++ 4.0. In creating the hWin .ocx, all the default options in the OLE Control wizard were chosen, all the default properties were added to the control, and the code was compiled.

In the Init of the form, the following line of code directs the Multimedia control to play the AVI in the form:

Copy Code
ThisForm.VCR.hWndDisplay = ThisForm.Test.hWnd

See Also

Other Resources

Video Player
ActiveX Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Provide a Hierarchical Display of Items Sample

Visual FoxPro 9.0 Samples
Provide a Hierarchical Display of Items Sample
See Also

File: ...\Samples\Solution\OLE\Outline.scx

This sample shows two different types of ActiveX controls, which you can use for outlining. In this sample, a directory structure is displayed. A custom method on the form named FillTree is called recursively to iterate through the entire tree structure.

The Treeview control also allows display of images with each node.

Treeview Control

The Treeview control can give your applications a truly genuine Windows look. Unlike the Outline control, which uses methods and item indexes, the Treeview control uses a Nodes collection.

Note:
To display images in a treeview control, you must add an ImageList control to the form.

Copy Code
* Add items to treeview control
o = THIS.PageFrame1.Page2.oleTreeview
IF cnt = 1
   oNode = o.nodes.add(,1,LOWER(m.path)+"_",LOWER(m.path),,)
   oNode.Image = "world"   &&name of image
ELSE
   oNode = o.nodes.add(m.pkey,4,LOWER(m.path)+"_",LOWER(m.path),,)
   oNode.Image = "fldr"   &&name of image
ENDIF

See Also

Other Resources

Treeview/Listbox Drag and Drop
ActiveX Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Send Mail Sample (Visual FoxPro)

Visual FoxPro 9.0 Samples
Send Mail Sample (Visual FoxPro)
See Also

File: ...\Samples\Solution\OLE\Sendmail.scx

This sample illustrates using the mailbtn class in ...\Samples\Classes\Buttons.vcx to create a simple messaging form that can send Visual FoxPro data to an e-mail address.

Mailbtn is a container class that contains a command button and two ActiveX controls: MAPI Session and MAPI Messages, both of which are defined in Msmapi32.ocx. The MAPI Session control establishes a MAPI session, and the MAPI Messages control makes it possible for the user to perform a variety of messaging system functions.

The mailbtn class starts a new Mail session, collects data from the current record, and brings up the Send Mail dialog with the data inserted as the message text.

This class includes two custom methods AddTabs and StripPath for formatting the information gathered from the table and inserted in the mail message.

This class also takes advantage of another custom method called Signon as well as a custom property called logsession, which is set to .F. initially.

When the user clicks the cmdMail button, the following code in the Click event calls the signon method, setting logsession to true (.T.).:

Copy Code
this.logsession = .T.
this.OLEMSess.signon

If there is a failure on signon, the Error event of the class is called and logsession is set to .F.

The MAPI controls are invisible at run time. In addition, there are no events for the controls. To use them, you must specify the appropriate methods. For these controls to work, MAPI services must be present. MAPI services are provided in Microsoft Outlook and Exchange electronic mail systems for Microsoft Windows 95 or later.

See Also

Other Resources

SendMail Buttons
ActiveX Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Use Slider and Status Bar Controls Sample

Visual FoxPro 9.0 Samples
Use Slider and Status Bar Controls Sample
See Also

File: ...\Samples\Solution\OLE\Slider.scx

This sample illustrates using the Slider control and the StatusBar control.

Slider Controls

Code in the Scroll event of each slider control sets the Value property of the other controls.

Copy Code
#DEFINE TXT_LOC "slider value: "
THISFORM.Olecontrol2.Panels(2).Text = TXT_LOC + ALLTRIM(STR(THIS.value))
THIS.Parent.spn1.Value = THIS.Value
THIS.Parent.oleV.Value = THIS.Value

StatusBar Control

The StatusBar Control Properties dialog box makes setting status bar properties easy.

To open the StatusBar Control Properties dialog, choose StatusBar Control Properties from the shortcut menu of a StatusBar Control.

See Also

Other Resources

ActiveX Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Use the RichText Control Sample

Visual FoxPro 9.0 Samples
Use the RichText Control Sample
See Also

File: ...\Samples\Solution\OLE\Rtf.scx

This sample illustrates using a RichText control to display and edit RTF text stored in the memo field of a table.

You can set the ControlSource of a RichText control directly to a character field, but not a memo field. Instead, create a form property to mediate between the RichText control and the memo field.

To store RTF text in a memo field

  1. Set the ControlSource property of the RichText control to the form property.

    Copy Code
    THISFORM.oleRTF.ControlSource = THISFORM.cText

  2. Store the memo field contents to the form property.

    Copy Code
    THISFORM.cText = rtf.source

  3. Before moving the record pointer, store the TextRTF property of the RichText control to the memo field.

    Copy Code
    REPLACE rtf.Source WITH THISFORM.oleRTF.TextRTF

The text stored in the memo file is standard RTF format, for example:

{\rtf1\ansi\deff0\deftab720{\fonttbl{\f0\fswiss MS Sans Serif;}{\f1\froman\fcharset2 Symbol;}{\f2\fswiss Arial;}{\f3\fswiss Arial;}} {\colortbl\red0\green0\blue0;\red255\green0\blue0;} \deflang1033\pard\qc\plain\f3\fs32\i The RichTextBox Control \par \pard\plain\f3\fs20

See Also

Other Resources

ActiveX Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Automation Solution Samples

Visual FoxPro 9.0 Samples
Automation Solution Samples

These Solution samples illustrate how you can perform automation with files from other applications.

In This Section

Automate a Microsoft Excel Spreadsheet Sample

Describes how to call an Excel worksheet through automation.
Automate a Microsoft Word Document in a Form Sample

Describes how to automate an embedded Word object on a form, insert rich text, and format the text.
Automate Microsoft Word and Excel Sample

Describes how to use Visual FoxPro as an automation controller to select data from a data from a Visual FoxPro database, insert the data in an Excel worksheet, graph the data, and display the data in Word.
Manipulate Display Characteristics of a Graph Sample

Describes how to incorporate MS Graph 5.0, which is an Automation server, into your applications.
Refresh a Graph in a Form Sample

Describes how select data from a Visual FoxPro table and passing the data to MS Graph to refresh values in a chart.

Reference

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Classes A-Z

Describes Visual FoxPro Foundation classes you can use for rapid application development.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.

Related Sections

Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Server Samples

Contains samples that illustrate Automation Servers.
Walkthroughs

Contains step-by-step instructions for common scenarios.


Automate a Microsoft Excel Spreadsheet Sample

Visual FoxPro 9.0 Samples
Automate a Microsoft Excel Spreadsheet Sample
See Also

File: ...\Samples\Solution\OLE\Olexl.scx

This form shows two samples of Visual FoxPro calling an Excel worksheet through automation.

The Trend button performs a query followed by a cross-tab to create a dataset to pass to Excel through automation using the Excel.Sheet object. Once in Excel, Visual FoxPro can call a Trend function to perform a simple regression analysis.

The Chart button automates the Excel.Chart object to create a chart. Excel supports passing data through automation, but MS Graph does not. However, you can distribute MS Graph with your applications.

See Also

Other Resources

Automation Solution Samples
Automate a Microsoft Word Document in a Form
Automate Microsoft Word and Excel


Automate a Microsoft Word Document in a Form Sample

Visual FoxPro 9.0 Samples
Automate a Microsoft Word Document in a Form Sample
See Also

File: ...\Samples\Solution\OLE\Oleword.scx

This sample shows how you can automate an embedded Word object on a form, insert some rich text, and then format the text. Typical automation with Word is usually done using the "Word.Basic" object used interactively with a CREATEOBJECT( ) function.

Copy Code
oForm = THISFORM
oForm.AddObject('oWordDoc','OleControl','WordDocument')
oForm.oWordDoc.Visible =  .t.
oForm.oWordDoc.DoVerb(0)

See Also

Other Resources

Automation Solution Samples
Automate a Microsoft Excel Spreadsheet
Automate Microsoft Word and Excel


Automate Microsoft Word and Excel Sample

Visual FoxPro 9.0 Samples
Automate Microsoft Word and Excel Sample
See Also

File: ...\Samples\Solution\OLE\Oleaut1.scx

This is a simple sample showing Visual FoxPro as an Automation controller. It demonstrates how to select data from a Visual FoxPro database, place the data in a Microsoft Excel worksheet, graph the data using Chart, and then display the graph in Word. To use this sample, you need at least Excel 5.0, Word 6.0, and Testdata.dbc, located in the ...\Samples\Data directory.

The following line of code creates a reference to a Microsoft Excel spreadsheet.

Copy Code
objXLsheet=createobject("Excel.Sheet")

The following line of code adds a chart to the spreadsheet.

Copy Code
objChart1 = objXLsheet.ChartObjects.Add(100, 100, 200, 200)

The following line of code creates a reference to Microsoft Word.

Copy Code
objWDdoc=createobject("word.basic")

oWordRef = GetObject('','word.basic')

See Also

Other Resources

Automation Solution Samples
Automate a Microsoft Word Document in a Form
Automate a Microsoft Excel Spreadsheet


Manipulate Display Characteristics of a Graph Sample

Visual FoxPro 9.0 Samples
Manipulate Display Characteristics of a Graph Sample
See Also

File: ...\Samples\Solution\OLE\Olegraph.scx

This sample shows how to incorporate MS Graph into your applications. MS Graph 5.0 is an Automation server that Visual FoxPro can automate using the standard CREATEOBJECT( ) function. With Visual FoxPro, Graph objects can be embedded in either bound or unbound OLE Controls. An OleBoundControl (bound to a General field) is the only way to programmatically insert data into a graph.

MS Graph's automation support provides access only to a graph object, not its datasheet. Data can be inserted into a Graph only with the APPEND GENERAL command on a General field. The following code uses the HasLegend property and is an example of automation:

Copy Code
cGData = ""+TAB+"Cats"+TAB+"Dogs"+CRLF+;
      "1994"+TAB+"11"+TAB+"22"+CRLF+;
      "1995"+TAB+"33"+TAB+"44"+CRLF+;
      "1996"+TAB+"55"+TAB+"55"+CRLF
APPEND GENERAL gen1 CLASS "msgraph.chart" DATA m.cGData
THIS.OleBoundControl1.ControlSource = "Gen1"
THIS.OleBoundControl1.HasLegend = .F.

The APPEND GENERAL command in this case creates a new chart object. If you do not include the CLASS "msgraph.chart" clause, then the chart is merely updated. The CLASS clause will create a new chart and override any existing formatting.

See Also

Other Resources

Automation Solution Samples
Graph Object
Refresh a Graph in a Form Sample


Refresh a Graph in a Form Sample

Visual FoxPro 9.0 Samples
Refresh a Graph in a Form Sample
See Also

File: ...\Samples\Solution\OLE\Stock.scx

This sample illustrates selecting data from a table and passing it to MS Graph to refresh the values in a chart. Most of the code to do this is associated with the InteractiveChange event of the cboMonth combo box.

Select the data into a cursor

Copy Code
SELECT date, close;
  FROM Stock1 WHERE MONTH(date) = THIS.Value ;
  ORDER BY date INTO CURSOR wtemp

Create a character string containing the selected data

Copy Code
SELECT wtemp

lcData = " " + TAB + "Closing Price" + CRLF

SCAN
 lcData = lcData + DTOC(date)
 lcData = lcData + TAB
 lcData = lcData + ALLTRIM(STR(close)) + CRLF
ENDSCAN

Send the character string to MS Graph

Copy Code
SELECT Graph
APPEND GENERAL msgraph DATA lcData

See Also

Other Resources

Automation Solution Samples
Manipulate Display Characteristics of a Graph
Graph Object


Controls Solution Samples

Visual FoxPro 9.0 Samples
Controls Solution Samples

These Solution samples, organized in order of control type, illustrate many tasks you can perform with controls.

In This Section

Add Items Interactively to a List Box Sample

Illustrates how to add and remove items from a list box.
Add New Items to a Combo Box Sample

Illustrates how to add text entered by a user into the list for a combo box.
Allow Users to Choose List Values Sample

Illustrates how to provide a set of values from a table in a list box and combo box.
Allow Users to Drag and Drop Controls Sample

Illustrates how to implement drag and drop operations for controls.
Change Pages When a User Chooses a Button Sample

Illustrates how to display different combinations of command buttons in a message box using option buttons.
Change the Number of Tabs at Run Time Sample

Illustrates how to use a page frame with tabs.
Display a Stop Watch Sample

Illustrates how to use the Stopwatch class to display a stopwatch.
Display a System Clock Sample

Illustrates how to display a system clock.
Display Calculated Values in a Column Sample

Illustrates how to display a calculated value in a grid column.
Display Child Records from a Relationship Sample

Illustrates how to coordinate a form with a one-to-many relationship and two grids and display the types of relationships.
Display Controls in a Grid Sample

Illustrates how to display controls in grid columns.
Display Different Pages without Tabs Sample

Illustrates how to manipulate pages without tabs in a page frame.
Display Multiple Columns in a List Box Sample

Illustrates how to display multiple columns in a list box.
Display Pictures in a List Sample

Illustrates how to display pictures next to items in list boxes.
Dynamically Format Grid Columns Sample

Illustrates how to set the dynamic foreground and background colors in grid columns.
Edit a Memo Field or Text File Sample

Illustrates how to view and edit text from a Memo field or text file in an edit box.
Execute Commands at Specified Intervals Sample

Illustrates how to set intervals between the display of text using a text box and a spinner.
Fill a List with Values from Different Sources Sample

Illustrates how to set the RowSourceType property of a list box so you can display values from different sources.
Format Input and Validate Data in a Text Box Sample

Illustrates how to make it easy for the user to enter data with a specific format in a text box.
Grid Highlighting, Column Resizing, and Header Images Sample

Demonstrates how to select style and colors for grid highlighting, resize columns automatically to the width of data in the column, lock the first grid column so that it does not scroll, and specify images in column headers.
Hot Tracking and Hover Effects Sample

Illustrates how you can add special effects to controls on forms.
Manipulate Text Programmatically Sample

Illustrates how to use properties of an edit box to manipulate text at run time.
Move Items Between List Boxes Sample

Illustrates how to move items from one list box to another.
Multiselect Items in a List Box Sample

Illustrates how to manage selected multiple items in a list box.
Present a User with Multiple Choices Sample

Illustrates how to use an option button group to present multiple choices.
Open Multiple Files Interactively Sample

Illustrates how to display files in a list.
Resize and Reposition Controls at Run Time Sample

Illustrates how you can resize a form as desired and have the controls on the form resize or reposition themselves relative to the new dimensions of the form.
See Check Box Design Options Sample

Illustrates a variety of properties used to customize the display of check boxes.
See Command Button Design Options Sample

Illustrates a variety of properties used to customize the display of command buttons.
Sort List Box Items Sample

Illustrates how to make it possible for the user to rearrange or sort items in a list box.
Treeview/Listbox Drag and Drop Sample

Illustrates how to set the drag-and-drop properties for tree view and list box controls.

Reference

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Classes A-Z

Describes Visual FoxPro Foundation classes you can use for rapid application development.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.

Related Sections

Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Server Samples

Contains samples that illustrate Automation Servers.
Walkthroughs

Contains step-by-step instructions for common scenarios.


Add Items Interactively to a List Box Sample

Visual FoxPro 9.0 Samples
Add Items Interactively to a List Box Sample
See Also

File: ...\Samples\Solution\Controls\Lists\Ladd.scx

This sample demonstrates adding and removing list box items. When a user types text in the text box and presses ENTER, the text in the text box is added to the list and the cursor is returned to the text box so that the user can enter another value.

To make it possible for a user to interactively add items to a list, use the AddItem method. In the sample, the following code in the text box KeyPress event adds the text in the text box to the list box and clears the text box when the user presses ENTER:

Copy Code
PARAMETERS nKeyCode, nShiftCtrlAlt
IF nKeyCode = 13     && Enter Key
   THISFORM.lstAdd.AddItem (This.Value)
   THIS.Value = ""
ENDIF

The following code in the DblClick event of the list box removes the item that was double-clicked, sending the value to the text box:

Copy Code
THISFORM.txtAddText.Value = This.List(This.ListIndex)
THIS.RemoveItem (This.ListIndex)

See Also

Other Resources

Controls Solution Samples
Display Multiple Columns in a List Box Sample
Display Pictures in a List Sample
Fill a List with Values from Different Sources Sample
Move Items Between List Boxes Sample
Multiselect Items in a List Box Sample
Open Multiple Files Interactively Sample
Sort List Box Items Sample
Treeview/ListBox Drag and Drop Sample


Add New Items to a Combo Box Sample

Visual FoxPro 9.0 Samples
Add New Items to a Combo Box Sample
See Also

File: ...\Samples\Solution\Controls\Combobox\Lookup.scx

This sample illustrates adding user-entered text to a combo box drop-down and providing lookup capability.

Adding User Text to a Combo Box Drop-Down

A combo box makes it possible for a user to enter text or select an item from a drop-down list. You can also add the text a user types in the combo box as a new item in the drop-down list so the user won't have to type the same text multiple times.

There are multiple ways to add user text to the drop-down list of a combo box, depending on the RowSourceType property setting of the combo box. In this sample, the RowSourceType of the combo boxes is 1 - Value. If the value the user enters isn't already in the drop-down list for cboCombo, the following code adds a comma and the new value to the RowSource:

Copy Code
cCountryName = ALLTRIM(Custs.Country)
IF ATC(m.cCountryName,THIS.RowSource)=0 AND !EMPTY(m.cCountryName)
   THIS.RowSource=THIS.RowSource+","+m.cCountryName
ENDIF

The combo box in the Manipulate Text Programmatically Sample example has a RowSourceType of 0 - None. The following code in the Valid event of cboSearchString in ...\Samples\Solution\Controls\TXT_EDT\Text.scx adds a user-entered value to the drop-down list of the combo box:

Copy Code
IF !EMPTY(THIS.Text)
   FOR i = 1 TO THIS.ListCount
      IF THIS.List(i) = THIS.Text
         RETURN
      ENDIF
   ENDFOR
   THIS.AddItem(THIS.Text)
ENDIF

If the RowSource of the combo box is an array, you need to add the user text to the array and call the Requery method of the combo box.

If the RowSource is a table or a cursor, you need to add a record, REPLACE the blank field with the user-entered value and Requery the combo box.

Provide Lookup Capability

In addition to illustrating how to add items to a combo box, this sample demonstrates three ways of making it possible for a user to filter a table for particular values. A user can do the following:

  • Enter values in a combo box.

  • Select an item from a drop-down list.

  • Enter partial values in a combo box for incremental search.

Enter Values in a Combo Box

The key code is associated with the LostFocus event of cboCombo. After making sure that the user has entered a value, the LostFocus code selects the records that match the user's text and sets the RecordSource property of the grid to the result set.

Copy Code
cDisplayValue = ALLTRIM(THIS.DisplayValue)

IF THIS.Value = "(All)"
   SELECT country AS location,* FROM CUSTOMER;
      INTO CURSOR Custs
   thisform.grdcust.recordsource = "Custs"
ELSE
   SELECT country AS location,* FROM CUSTOMER ;
    WHERE UPPER(ALLTRIM(Customer.Country)) = UPPER(m.cDisplayValue);
    INTO CURSOR Custs
   THISFORM.grdCust.RecordSource = "Custs"
ENDIF

Select an Item from a Drop-down List

Basically the same lookup code is associated with the InteractiveChange event of cboDrop – if the Value of the combo box is "(All)", select all records into the cursor, otherwise, select the records that match the user's choice.

Enter Partial Values for Incremental Search

Code in the InteractiveChange event of cboIntSearch performs the lookup every time the user types a character in the combo box.

Copy Code
#DEFINE DELKEY 127
LPARAMETERS nKeyCode, nShiftAltCtrl
LOCAL cDisplayValue
IF nKeyCode = DELKEY
   cDisplayValue = ALLTRIM(THIS.DisplayValue)
   IF LEN(m.cDisplayValue)=1
      cDisplayValue = ""
   ELSE
      cDisplayValue = LEFT(cDisplayValue,LEN(cDisplayValue)-1)
   ENDIF
ELSE
   cDisplayValue = ALLTRIM(THIS.DisplayValue)+CHR(nKeyCode)
ENDIF
THISFORM.LockScreen = .T.
DO CASE
CASE EMPTY(m.cDisplayValue)
   THISFORM.grdCust.RecordSource = " "
CASE THIS.Value = "(All)"
   SELECT country AS location,* FROM CUSTOMER;
      INTO CURSOR Custs
   THISFORM.grdCust.RecordSource = "Custs"
OTHERWISE
   SELECT country AS location,* FROM CUSTOMER ;
    WHERE UPPER(ALLTRIM(Customer.Country)) = UPPER(m.cDisplayValue);
    INTO CURSOR Custs
   THISFORM.grdCust.RecordSource = "Custs"
ENDCASE
THISFORM.ResetCombos(THIS)
THISFORM.LockScreen = .F.

See Also

Other Resources

Controls Solution Samples
Add Data Lookup Combo Boxes Sample
Allow Users to Choose List Values Sample


Allow Users to Choose List Values Sample

Visual FoxPro 9.0 Samples
Allow Users to Choose List Values Sample
See Also

File: ...\Samples\Solution\Forms\Datalook.scx

This sample illustrates providing users with a set of values, selected from another table, in a list box and in a combo box. The value the user chooses is stored in the current table.

It is often more convenient for a user to choose from a list of predetermined values, and, of course, you minimize the risk that the user will mistype a value. Setting a few list box properties is all that is required to provide this capability. For example, the following properties were set for cboEmp_id on the Using Combo Box page:

Property | Setting
BoundColumn | 2
ColumnCount | 2
ControlSource | orders.emp_id
RowSource | SELECT DISTINCT ALLTRIM( employee.first_name) + " " + ALLTRIM( employee.last_name) , EMP_ID FROM employee INTO CURSOR cEmpCombo ORDER BY first_name
RowSourceType | 3 – SQL Statement

Rather than having the user choose an employee id number from the drop-down list, the SELECT statement makes it possible for you to show the user the employees' first and last names.

Because the SELECT statement creates a cursor, code in the Destroy event closes the cursor.

Copy Code
IF USED("cEmpCombo") THEN
   USE IN cEmpCombo
ENDIF

See Also

Other Resources

Controls Solution Samples
Add New Items to a Combo Box Sample


Allow Users to Drag and Drop Controls Sample

Visual FoxPro 9.0 Samples
Allow Users to Drag and Drop Controls Sample
See Also

File: ...\Samples\Solution\Forms\Ddrop.scx

This sample explains how to implement drag and drop operations. One page on the form illustrates manual dragging of controls by calling the Drag method. Explicitly calling the Drag method makes it possible for you to process other code in the Click event of the control. The other page illustrates using the Automatic DragMode setting so that the Drag and Drop operation is started automatically when the user presses the mouse button over the controls.

Repositioning the Command Button

In the MouseMove event of cmdDrop, if the left mouse button is down, find out how far the mouse pointer is from the top and the left of the command button and begin the drag operation.

Copy Code
LPARAMETERS nButton, nShift, nXCoord, nYCoord
IF nButton = 1 && Left button
   THISFORM.XOffset = nXCoord – THIS.Left
   THISFORM.YOffset = nYCoord - THIS.Top
   THIS.Drag
ENDIF

In the DragDrop event of the page that the command button is on, reposition the command button.

Copy Code
oSource.Left = nXCoord - THISFORM.XOffset
oSource.Top = nYCoord - THISFORM.Yoffset

Changing the Color of the Shape

The DragMode property of the colored squares on the Change Colors page of the form is set to 1 –Automatic. As soon as the user presses the mouse button on the squares, the drag operation begins. Any code added to the Click event of the squares would never be executed.

Code in the DragDrop event of the circle changes its BackColor property to match that of the drag source.

Copy Code
LPARAMETERS oSource, nXCoord, nYCoord
THIS.BackColor = oSource.BackColor

See Also

Other Resources

Controls Solution Samples
Treeview/Listbox Drag and Drop Sample
Hot Tracking and Hover Effects Sample
Allow Users to Choose List Values
OLE Drag-and-Drop Data Formats


Change Pages When a User Chooses a Button Sample

Visual FoxPro 9.0 Samples
Change Pages When a User Chooses a Button Sample
See Also

File: ...\Samples\Solution\Controls\PgFrame\Msgbox.scx

This sample makes it possible for you to interactively construct a message box.

There are six command button combinations possible in a message box. Each of these combinations is displayed on a separate page in a page frame on the Messagebox Builder form.

The option buttons, labeled 0 through 5, make it possible for you to specify which combination of command buttons you want to be displayed in your message box. The selected button in the page indicates the default Messagebox button selection. The ActivePage property of the page frame is set to the Value of the Option group.

Constructing the MESSAGEBOX Code

In the InteractiveChange event of the controls on the form, the WriteCode method of the form is called to dynamically construct the MESSAGEBOX code.

Copy Code
* WriteCode Method
#DEFINE QM '"'

cString = '=MESSAGEBOX('
cString = cString + QM + ALLTRIM(STRTRAN(THIS.edtMessage.Value, CHR(13)+CHR(10), QM + '+CHR(13)+' + QM)) + QM + ','
cString = cString + THIS.cboIcon.Value + '+'
cString = cString + THIS.DefaultButton + '+'
cString = cString + ALLTRIM(STR(THIS.opgButtons.Value - 1)) + ','
cString = cString + QM + ALLTRIM(THIS.txtCaption.Value) + QM + ')'

THIS.edtCode.Value = cString

See Also

Other Resources

Controls Solution Samples
Present a User with Multiple Choices Sample
Display Different Pages without Tabs Sample
Messagebox Handler


Change the Number of Tabs at Run Time Sample

Visual FoxPro 9.0 Samples
Change the Number of Tabs at Run Time Sample
See Also

File: ...\Samples\Solution\Controls\Pgframe\Pfsam1.scx

This sample illustrates using a page frame with tabs. The number of tabs changes dynamically when a user chooses a new value in a spinner. When the user selects a tab, a list box displays values specific to the tab.

To change the number of tabs at run time

  1. Set the PageCount property to the desired number of pages.

The list box in this sample is positioned on the form, not on any of the pages in the page frame. This placement makes it possible for you to have a single control visible in all of your pages.

Two user-defined form methods set the captions on the tabs and make sure the values in the list box match: UpdateList and SetCaption.

UpdateList Method

UpdateList is called when the number of tabs changes and when the user selects a new tab.

Copy Code
LOCAL lnPage, lcHigh, lcLow
#define NO_MATCH_LOC 'No Matching Names for '
DIMENSION THISFORM.aCustomers[1,2]
lnPage = THISFORM.pgfRolodex.activepage
THISFORM.aCustomers[1,1] = NO_MATCH_LOC + ;
   THISFORM.pgfRolodex.Pages(lnPage).Caption
THISFORM.aCustomers[1,2] = ""

lcHigh = substr(THISFORM.pgfrolodex.Pages(lnPage).caption,3,1)
lcLow = substr(THISFORM.pgfrolodex.Pages(lnPage).caption,1,1)
SELECT company, phone FROM customer;
   WHERE company <= lcHigh and company => lcLow;
   ORDER BY company;
   INTO ARRAY THISFORM.aCustomers

THISFORM.lstCustomers.Requery
THISFORM.lstCustomers.Value = 1

SetCaption Method

SetCaption is called in the spinner's UpClick and DownClick events to calculate what captions should appear on the tabs.

Copy Code
THISFORM.LockScreen = .T.
FOR n = 1 to THISFORM.pgfRolodex.PageCount
   FirstLetter = SUBSTR(THISFORM.Alphabet,((n - 1)*ROUND(LEN(THISFORM.Alphabet)/THISFORM.pgfRolodex.PageCount,0))+1,1)
   IF n = THISFORM.pgfRolodex.PageCount   &&last page
      LastLetter = right(THISFORM.Alphabet,1)
   ELSE
      LastLetter = SUBSTR(THISFORM.Alphabet,((n)*ROUND(LEN(THISFORM.Alphabet)/THISFORM.pgfRolodex.PageCount,0)),1)
   ENDIF
   THISFORM.pgfRolodex.Pages(n).Caption = FirstLetter + "-" + LastLetter
ENDFOR
THISFORM.LockScreen = .F.

Alphabet is a user-defined form property that is used to determine the captions for each tab. To get the same functionality in different languages, set the Alphabet property to a string containing all the letters in the target language alphabet.

See Also

Other Resources

Display Different Pages without Tabs
Controls Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Display a Stop Watch Sample

Visual FoxPro 9.0 Samples
Display a Stop Watch Sample
See Also

File: ...\Samples\Solution\Controls\Timer\Swatch.scx

This sample includes the Stopwatch class.

Stopwatch Class

The Stopwatch class includes a timer and several display labels. The Timer increments numeric custom properties of the class and sets the Caption property of the labels accordingly.

The Start method of the class sets the Enabled property of the Timer to true (.T.). The Stop method sets the Enabled property of the Timer to false (.F.). And the Reset method sets the numeric properties to 0.

Property Settings for the Stopwatch Class

Control | Property | Setting
lblSeconds | Caption | 00
lblColon1 | Caption | :
lblMinutes | Caption | 00
lblColon2 | Caption | :
lblHours | Caption | 00
tmrSWatch | Interval | 1000

Swatch Form

The Swatch form contains an object derived from the Stopwatch class, along with some command buttons. The code written for the Click event of the first command button on the form calls the Start and Stop methods of the Stopwatch class. The second button calls the Reset method of the Stopwatch class.

Protected Properties and Methods

This sample also illustrates the use of protected properties and methods. The Stopwatch class contains three protected properties, nSec, nMin, and nHour, and one protected method, UpdateDisplay.

Tip:
Choose Class Info on the Class menu to see the visibility of all properties and methods of a class.

The protected properties are used in internal calculations in the UpdateDisplay method and the Timer event. The UpdateDisplay method sets the captions of the labels to reflect the elapsed time.

UpdateDisplay Method

Code Comments
Copy Code
cSecDisplay = ALLTRIM(STR(THIS.nSec))
cMinDisplay = ALLTRIM(STR(THIS.nMin))
cHourDisplay = ALLTRIM(STR(THIS.nHour))

Convert the numeric properties to Character type for display in the label captions.
Copy Code
THIS.lblSeconds.Caption = ;
 IIF(THIS.nSec < 10, ;
   "0" ,"") + cSecDisplay
THIS.lblMinutes.Caption = ;
  IIF(THIS.nMin < 10, ;
   "0", "") + cMinDisplay
THIS.lblHours.Caption = ;
  IIF(THIS.nHour < 10, ;
   "0", "") + cHourDisplay

Set the label captions, retaining the leading 0 if the value of the numeric property is less than 10.

The following table lists the code in the tmrSWatch.Timer event:

The Timer Event

Code Comments
Copy Code
THIS.Parent.nSec = THIS.Parent.nSec + 1
IF THIS.Parent.nSec = 60
  THIS.Parent.nSec = 0
  THIS.Parent.nMin = ;
  THIS.Parent.nMin + 1
ENDIF

Increment the nSec property every time the timer event fires: every second. If nSec has reached 60, reset it to 0 and increment the nMin property.
Copy Code
IF THIS.Parent.nMin = 60
  THIS.Parent.nMin = 0
  THIS.Parent.nHour = ;
  THIS.Parent.nHour + 1
ENDIF
THIS.Parent.UpdateDisplay

If nMin has reached 60, reset it to 0 and increment the nHour property.

Call the UpdateDisplay method when the new property values are set.

The Stopwatch class has three custom methods that are not protected: Start, Stop, and Reset. A user can call these methods directly to control the stopwatch.

The Start method contains the following line of code:

Copy Code
THIS.tmrSWatch.Enabled = .T.

The Stop method contains the following line of code:

Copy Code
THIS.tmrSWatch.Enabled = .F.

The Reset method sets the protected properties to zero and calls the protected method:

Copy Code
THIS.nSec = 0
THIS.nMin = 0
THIS.nHour = 0
THIS.UpdateDisplay

The user cannot directly set these properties or call this method, but code in the Reset method can.

See Also

Other Resources

Stop Watch
Controls Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Display a System Clock Sample

Visual FoxPro 9.0 Samples
Display a System Clock Sample
See Also

File: ...\Samples\Solution\Controls\Timer\Clock.scx

This sample contains the Clock custom control in Samples.vcx on a form. The class includes a text box for displaying the date and time and a timer for updating the display.

The TimeFormat property of the clock class can be set to 0 for 24-hour time format or 1 for 12-hour format. The code in the Timer event of the timer updates the time.

Copy Code
#DEFINE LONGDATE_LOC CDOW(DATE())+" "+CMONTH(DATE())+" "+ ;
         ALLTRIM(STR(DAY(DATE())))+", "+ALLTRIM(STR(YEAR(DATE())))

IF This.Parent.TimeFormat = 0
   This.Parent.txtTime.Value = IIF(VAL(SUBSTR(TIME(),1,2))>12, ;
      ALLTRIM(STR((VAL(SUBSTR(TIME(),1,2))-12)))+SUBSTR(TIME(),3,6),TIME())
ELSE
   This.Parent.txtTime.Value = TIME()
ENDIF

THIS.Parent.txtDate.Value = LONGDATE_LOC

This class contains a separate text box for date and time values. If you want to hide one or the other, you can easily set its Visible property to false (.F.). An easier way to display the time and date is to use a single text box and set the value of this text box in a timer control to DATETIME( ). This will make it possible for you to take advantage of the Hours, Seconds, and DateFormat properties of a text box.

See Also

Other Resources

Clock Foundation Class
Controls Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Display Calculated Values in a Column Sample

Visual FoxPro 9.0 Samples
Display Calculated Values in a Column Sample
See Also

File: ...\Samples\Solution\Controls\Grid\Calc.scx

This sample illustrates how to display a calculated value in a column.

Set the ControlSource property of the column to an expression with a calculation. For example, the following expression for the ControlSource of the Profit column displays the difference between the price and cost.

Copy Code
Products.Unit_Price - Products.Unit_Cost

When you change one or more values in the expression, the value in the column is automatically updated.

Note:
Columns that display an expression containing a calculation are read-only.

See Also

Other Resources

Controls Solution Samples
Display Child Records from a Relationship Sample
Display Controls in a Grid Sample
Dynamically Format Grid Columns Sample


Display Child Records from a Relationship Sample

Visual FoxPro 9.0 Samples
Display Child Records from a Relationship Sample
See Also

File: ...\Samples\Solution\Controls\Grid\1_many.scx

This sample demonstrates coordinating a one-to-many form with two grids displaying the many sides of the relationships. Very little code is needed in this sample. Setting a few properties is all that is involved.

Property Settings

Text boxes for the "one" side of the relationship:

Copy Code
ControlSource = Customer.cust_id
ControlSource = Customer.company

Grid for the first "many" side of the relationship:

Copy Code
ChildOrder = cust_id
LinkMaster = customer
RecordSource = orders
RecordSourceType = 1 - Alias
RelationalExpr = customer.cust_id
ColumnCount = 4
   Column1.ControlSource = "orders.order_no"
   Column1.Header1.Caption = "Order"
   Column2.ControlSource = "orders.order_date"
   Column2.Header1.Caption = "Date"
   Column3.ControlSource = "orders.to_name"
   Column3.Header1.Caption = "Ship To"
   Column4.ControlSource = "orders.order_amt"
   Column4.Sparse = .F.
   Column4.Header1.Caption = "Total"
   Column4.Text1.InputMask = "$$999,999.99"

Grid for the 2nd "many" side of the relationship:

Copy Code
ChildOrder = order_id
LinkMaster = Orders
RecordSource = Orditems
RecordSourceType = 1 - Alias
RelationalExpr =Orders.order_id
ColumnCount = 4
   Column1.ControlSource = "orditems.line_no"
   Column1.Header1.Caption = "Item"
   Column2.ControlSource = "products.prod_name"
   Column2.Header1.Caption = "Product"
   Column3.ControlSource = "orditems.quantity"
   Column3.Header1.Caption = "Qty."
   Column4.ControlSource = "orditems.unit_price"
   Column4.Sparse = .F.
   Column4.Header1.Caption = "Price"
   Column4.Text1.InputMask = "$$9,999.99"

In addition to the text boxes and the grids, the form contains an object based on the VCR class in Buttons.vcx. The SkipTable property of this class is set to the table you want the record pointer to be moved in when the user chooses a table navigation button. Because the user can easily manually move through the records in the grids (Orders and Orditems), SkipTable is set to Customer.

See Also

Other Resources

Controls Solution Samples
Display Calculated Values in a Column Sample
Display Controls in a Grid Sample
Dynamically Format Grid Columns Sample


Display Controls in a Grid Sample

Visual FoxPro 9.0 Samples
Display Controls in a Grid Sample
See Also

File: ...\Samples\Solution\Controls\Grid\Controls.scx

This sample demonstrates controls displayed in grid columns.

You can add controls to a column in the Form Designer by selecting a column and adding a control, or programmatically with the AddObject method.

There are a few properties that are important for displaying controls in a column.

CurrentControl Property

After you add a control to a grid column, you need to set the column's CurrentControl property to the new control for the new control to be displayed.

Sparse Property

The check boxes on the form make it possible for you to toggle the Sparse property of the grid columns that contain controls. When Sparse is set to .T., the control is only displayed when the focus is on a cell in the column. When Sparse is set to .F., the control is always displayed in each cell in the column.

Controls and Events

Notice that the control in the column processes the events when you set the focus to a cell in the column. For example, if you select a cell in a column with a spinner, when you press the up and down arrows, you increment or decrement the value in the spinner. This is the default behavior for a spinner, not the default behavior for a text box in a grid cell.

See Also

Other Resources

Controls Solution Samples
Display Calculated Values in a Column Sample
Display Child Records from a Relationship Sample
Dynamically Format Grid Columns Sample


Display Different Pages without Tabs Sample

Visual FoxPro 9.0 Samples
Display Different Pages without Tabs Sample
See Also

File: ...\Samples\Solution\Controls\PgFrame\Pfsam2.scx

This sample demonstrates manipulating pages without tabs in a form page. The frame in the middle of the form contains three pages that are brought to the front as the user chooses command buttons. Each page can have its own controls and appearance.

The method that brings a particular page to the front is ZOrder. For example, the following line of code in the click event of one of the command buttons brings pagCustomers to the front:

Copy Code
THISFORM.pgfPeople.pagCustomers.ZOrder

You can also use the ActivePage property of the page frame to determine which pages are displayed.

Copy Code
THISFORM.pgfPeople.ActivePage = 1

See Also

Other Resources

Change Pages When a User Chooses a Button
Controls Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Display Multiple Columns in a List Box Sample

Visual FoxPro 9.0 Samples
Display Multiple Columns in a List Box Sample
See Also

File: ...\Samples\Solution\Controls\Lists\Lmulcol.scx

This sample demonstrates displaying multiple columns in a list box. The form displayed contains a list box and a spinner. The number of columns in the list box is set to the Value property of the spinner: 1, 2, 3, or 4.

To set the width of the columns in a multi-column list box, use the ColumnWidths property. For example, if there are 3 columns in the list box, the following command will set the column widths to 10, 15, and 20, respectively:

Copy Code
Form.List.ColumnWidths = "10, 15, 20"

To set the fields to be displayed in the columns, set the RowSource property. For example, the following command sets the sources of three columns in a 3-column list box to the contact, city, and country fields of the customer table:

Copy Code
Form.List.RowSource = "contact,city,country"

The ColumnLines property determines whether lines are displayed between the columns in the list.

See Also

Other Resources

Controls Solution Samples
Add Items Interactively to a List Box Sample
Display Pictures in a List Sample
Fill a List with Values from Different Sources Sample
Move Items Between List Boxes Sample
Multiselect Items in a List Box Sample
Open Multiple Files Interactively Sample
Sort List Box Items Sample
Treeview/ListBox Drag and Drop Sample


Display Pictures in a List Sample

Visual FoxPro 9.0 Samples
Display Pictures in a List Sample
See Also

File: ...\Samples\Solution\Controls\Lists\Piclist.scx

This sample illustrates how you can enhance your list boxes by adding picture graphics beside the individual text items. In this sample, you can pick any database (.dbc) file, and the list box will show different images beside the names of tables, local views and remote views.

The following code from cmdDatabase.Click enumerates through a .dbc and selectively adds pictures to list items using the Picture property. The Picture property relies on an index setting to determine which list item to affect.

Copy Code
FOR i = (m.nTblCount+1) TO thisform.lstDatabase.ListCount
IF DBGETPROP(ALLTRIM(thisform.lstDatabase.List[m.i]),; "view","sourcetype") = 1
       *Local view
      thisform.lstDatabase.Picture[m.i] = m.cLViewBMP
   ELSE
      * Remote view
      thisform.lstDatabase.Picture[m.i] = m.cRViewBMP
   ENDIF
ENDFOR
Note:
You need to ensure that the images used are sized correctly to fit within the space of a single list box item, which differs with the FontSize of the list.

See Also

Other Resources

Controls Solution Samples
Add Items Interactively to a List Box Sample
Display Multiple Columns in a List Box Sample
Fill a List with Values from Different Sources Sample
Move Items Between List Boxes Sample
Multiselect Items in a List Box Sample
Open Multiple Files Interactively Sample
Sort List Box Items Sample
Treeview/ListBox Drag and Drop Sample


Dynamically Format Grid Columns Sample

Visual FoxPro 9.0 Samples
Dynamically Format Grid Columns Sample
See Also

File: ...\Samples\Solution\Controls\Grid\Dyngrid.scx

This sample illustrates setting the DynamicForeColor and DynamicBackColor properties of grid columns.

The code of interest in this sample is associated with the InteractiveChange event of the drop-down list cboFormat.

First, the code clears the dynamic fore and backcolor settings:

Copy Code
oGrd.SetAll("dynamicbackcolor", "", "Column")
oGrd.SetAll("dynamicforecolor", "", "Column")

Then, code in a CASE statement sets the new DynamicForeColor or DynamicBackColor properties. For example, the following line of code displays discontinued items with a gray ForeColor.

Copy Code
oGrd.SetAll("dynamicforecolor", ;
   "IIF(discontinu, RGB(192,192,192), RGB(0,0,0))", "Column")

Discontinu is a logical field in the Products table.

See Also

Other Resources

Controls Solution Samples
Display Calculated Values in a Column Sample
Display Child Records from a Relationship Sample
Display Controls in a Grid Sample


Edit a Memo Field or Text File Sample

Visual FoxPro 9.0 Samples
Edit a Memo Field or Text File Sample
See Also

File: ...\Samples\Solution\Controls\TXT_EDT\Editbox.scx

This sample enables you to view and edit text from a memo field or a text file in an edit box.

Displaying text from a memo field is as easy as setting the ControlSource of the edit box to the memo field.

There are two ways you can edit a text file in an edit box: using low-level file functions and creating a cursor to hold the text. This sample creates a cursor instead of using low-level file functions.

Editing a Text file with Low-Level File Functions.

You can open a file using FOPEN( ), read the contents of the file using FREAD( ), and store the contents to a memory variable or to the Value property of the edit box. You can then write changes to the file using FWRITE( ) and close the file using FCLOSE( ).

Editing a Text File by Loading it into a Cursor Field

The advantage to creating a cursor for a text file, other than the fact that the code is a little simpler, is that Visual FoxPro manages writing large amounts of text in a cursor to temporary files if there isn't enough memory.

Copy Code
IF SELECT("textfile") = 0
   CREATE CURSOR textfile (filename c(60),mem m)
   APPEND BLANK
ENDIF
REPLACE textfile.FileName WITH GETFILE("TXT")
IF EMPTY(textfile.FileName)
   RETURN
ENDIF
SELECT textfile
APPEND MEMO mem FROM (textfile.FileName) OVERWRITE
THIS.Parent.edtText.ControlSource = "textfile.mem"
THIS.Parent.cmdSave.Enabled = .T.
THIS.Parent.lblFileName.Caption = ALLTRIM(textfile.FileName)
THIS.Parent.Refresh

See Also

Other Resources

Controls Solution Samples
Manipulate Text Programmatically Sample


Execute Commands at Specified Intervals Sample

Visual FoxPro 9.0 Samples
Execute Commands at Specified Intervals Sample
See Also

File: ...\Samples\Solution\Controls\Timer\Timecomm.scx

This sample form contains a text box and a spinner. Text you type in the text box is displayed in a WAIT WINDOW. You can set the spinner to the number of seconds you want to elapse between each WAIT WINDOW command.

In the InteractiveChange event of the spinner, the appropriate timer interval is set. The Interval property is 1/1000th of a second, so the interval is set to the spinner value * 1000.

Copy Code
THISFORM.Timer1.Interval = (THIS.Value * 1000)

In the Timer event, the WAIT WINDOW command is issued.

Copy Code
WAIT WINDOW ALLTRIM(THISFORM.Text1.Value) TIMEOUT 0.5

The code associated with the Timer event can include any command or procedure: code to update data, check for mail, display system resources, and so on.

See Also

Other Resources

Controls Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Fill a List with Values from Different Sources Sample

Visual FoxPro 9.0 Samples
Fill a List with Values from Different Sources Sample
See Also

File: ...\Samples\Solution\Controls\Lists\Multdat1.scx

This sample demonstrates setting the RowSourceType of a list box at run time to a value, an alias, a SQL statement, a query (.qpr), an array, fields in a table, files in a directory, and the structure of a table.

The combo box on the form contains all the possible RowSourceTypes of a list (except for 9 - popup, which is included for backward compatibility). The code associated with the InteractiveChange event sets the new RowSourceType and RowSource properties for the list.

When you change both the RowSourceType and RowSource of a list box at run time, you need to do the following:

  1. Set the RowSourceType to 0.

  2. Set the RowSource to the new source.

  3. Set the RowSourceType to the new type.

If you don't follow this order, the existing RowSource and RowSourceType settings could conflict after one new value is set and before the corresponding value is set.

See Also

Other Resources

Controls Solution Samples
Add Items Interactively to a List Box Sample
Display Multiple Columns in a List Box Sample
Display Pictures in a List Sample
Move Items Between List Boxes Sample
Multiselect Items in a List Box Sample
Open Multiple Files Interactively Sample
Sort List Box Items Sample
Treeview/ListBox Drag and Drop Sample


Format Input and Validate Data in a Text Box Sample

Visual FoxPro 9.0 Samples
Format Input and Validate Data in a Text Box Sample
See Also

File: ...\Samples\Solution\Controls\TXT_EDT\Textbox.scx

This sample shows how to set text box properties to make it easy for a user to enter data in the required format.

Format | Property | Setting
Allow Only Digits | InputMask | 999999999
Select On Entry | SelectOnEntry | .T.
All Uppercase | Format | !
Read-Only | ReadOnly | .T.
US Telephone Number | InputMask | (999) 999-9999
Password text | PasswordChar | *
Date Formatting | DateFormat | a number between 0 and 14

Validating Input

The following code in the Valid event of a text box prevents a user from leaving the text box if the letter "a" is in the text:

Copy Code
IF "a"$ THIS.Value
   #DEFINE MESSAGE_LOC "The text box value cannot contain the letter 'a'"
   MESSAGEBOX(MESSAGE_LOC,48+0+0)
   RETURN 0
ELSE
   RETURN .T.
ENDIF

See Also

Other Resources

Controls Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Grid Highlighting, Column Resizing, and Header Images Sample

Visual FoxPro 9.0 Samples
Grid Highlighting, Column Resizing, and Header Images Sample
See Also

File: ...\Samples\Solution\Toledo\Griders.scx

This sample demonstrates how you can perform the following actions:

  • Select style and colors for grid highlighting.

  • Resize columns automatically to the width of data in the column.

  • Lock the first grid column so that it does not scroll.

  • Specify images in column headers.

Selecting Grid Highlight Styles

You can use highlighting styles to control how highlighting appears and behaves in a grid when you select rows and the focus moves from the grid. To set highlighting styles, use the Grid HighlightStyle property.

In the sample, to set the HighlightStyle, select a style in the combo box on the form. The combo box contains the following code:

Copy Code
ThisForm.grdCustomers.HighlightStyle = VAL(this.Value)

For more information about HighlightStyle, see HighlightStyle Property.

You can also set highlighting colors. For more information, see HighlightBackColor Property, HighlightForeColor Property, SelectedItemBackColor Property, and SelectedItemForeColor Property.

Fitting Columns to Width of Data

This sample resizes grid columns automatically to fit the width of data in the column using the Grid AutoFit method as follows:

Copy Code
ThisForm.grdCustomers.AutoFit()

You can also resize grid columns by double-clicking the upper-left corner of the grid. To resize an individual column automatically, double-click the dividing line on right side of the column. You can control this behavior using the Grid AllowAutoColumnFit property.

For more information, see AutoFit Method and AllowAutoColumnFit Property.

Locking Grid Columns

You can lock columns so the columns remain fixed when the scrolling horizontally across a grid by using the Grid LockColumns property.

In the sample, you can lock the first column in the grid by setting grdCustomers.LockColumns to 1 as in the following code:

Copy Code
ThisForm.grdCustomers.LockColumns = 1

You can also lock the Customer ID column by clicking the column header. The pushpin in the column header indicates whether the column is locked. To lock individual columns, right-click the area between the column headers.

For more information, see LockColumns Property and LockColumnsLeft Property.

Displaying Images in Column Headers

You can specify an image for a column header using the Picture property and set image orientation using the Header Alignment property.

In the sample, an image appears in the Company Name column header to indicate the direction of the sort order in the column. Clicking the column header displays different images to indicate ascending or descending sort order.

For more information, see Picture Property and Alignment Property.

See Also

Other Resources

Controls Solution Samples


Hot Tracking and Hover Effects Sample

Visual FoxPro 9.0 Samples
Hot Tracking and Hover Effects Sample
See Also

File: ...\Samples\Solution\Sedona\Dvds.scx

This sample shows several new events and properties that make it possible for you to add special effects such as hot tracking to your controls on forms.

See Also

Other Resources

Controls Solution Samples
Allow Users to Drag and Drop Controls Sample
Resize and Reposition Controls at Run Time Sample


Manipulate Text Programmatically Sample

Visual FoxPro 9.0 Samples
Manipulate Text Programmatically Sample
See Also

File: ...\Samples\Solution\Controls\TXT_EDT\Text.scx

This sample illustrates using the SelStart, SelLength, and SelText properties of an edit box to manipulate the text at run time. The sample also counts the characters, words, and paragraphs in a text file and makes it possible for a user to search for a string in a text file.

Formatting Text

The following code is included in the Click event of the button that formats selected text to uppercase:

Copy Code
lo = THIS.Parent.edtText
lnOldStart = lo.SelStart
lnOldLength = lo.SelLength
lo.SelText = UPPER(lo.SelText)
lo.SelStart = lnOldStart
lo.SelLength = lnOldLength

If you want to specify the font attributes of selected sections of text, use a RichText control.

Searching for Text

After getting the text to search for, the following code loops through all the text in the edit box, comparing it to the target string:

Copy Code
llKeepLooking = .T.
DO WHILE llKeepLooking
  FOR i = lnStart TO LEN(loEDT.Value)
    loEDT.SelStart = i
     loEDT.SelLength = lnLen
    IF loEDT.SelText = ALLTRIM(loCBO.Text) OR ;
         (!llCaseSensitive AND ;
         (UPPER(loEDT.SelText) = UPPER(ALLTRIM(loCBO.Text))))
      llFound = .T.
      llKeepLooking = .F.
      EXIT
    ENDIF
  ENDFOR
  IF !llFound
    lnChoice=MESSAGEBOX("Search string not found.", ;
        64+0+4)
    IF lnChoice = 6 && Yes
      llKeepLooking = .T.
      lnStart = 0
    ELSE
      llKeepLooking = .F.
    ENDIF
  ENDIF
ENDDO
Tip:
Be sure to set the form's LockScreen property to true (.T.) before searching and false (.F.) after searching. Otherwise, the form will repaint every time the SelStart property of the edit box is changed.

See Also

Other Resources

Controls Solution Samples
Edit a Memo Field or Text File Sample
Manipulate Objects Programmatically Sample


Move Items Between List Boxes Sample

Visual FoxPro 9.0 Samples
Move Items Between List Boxes Sample
See Also

File: ...\Samples\Solution\Controls\Lists\Lmover.scx

This sample demonstrates moving items from one list box to another. A user can double-click one item to move it, select one or more items and drag them, or use the appropriate command buttons to move the items between the lists.

The two list boxes and four associated command buttons are saved as a class: MoverLists in Samples.vcx. The base class of MoverLists is CONTAINER. To be able to add and remove items from lists, the RowSourceType of the lists must be set to 0 – None. If you want to fill the list box with array elements or values from a table, you can use code like the following:

Copy Code
*array
FOR i = 1 to ALEN(myarray)
   List.AddItem(myarray[i])
ENDFOR

*table
SCAN
   List.AddItem(table.field)
ENDSCAN

To Move Items by Double-clicking

The following code is associated with the DblClick event of the left list box (lstSource). Similar code is associated with the DblClick event of the right list box (lstSelected).

Copy Code
THIS.Parent.lstSelected.AddItem(THIS.List(THIS.ListIndex))
This.RemoveItem(THIS.ListIndex)
THIS.Parent.Refresh

"THIS" refers to lstSource. "THIS.Parent" refers to the moverlists class, the container of the lists.

To Move all Items from One List to Another

The following code is associated with the Click event of cmdAddAll:

Copy Code
  DO WHILE THIS.PARENT.lstSource.ListCount > 0
    THIS.PARENT.lstSelected.AddItem;
        (THIS.PARENT.lstSource.List(1))
   THIS.PARENT.lstSource.RemoveItem(1)
  ENDDO
  THIS.PARENT.Refresh

To Move Selected Items from One List to Another

If you remove an item from a list box, the ListCount property of the list box is decremented, as is the ListIndex of all the subsequent items in the list. To move multiply selected items, you need to use a DO WHILE loop. The following code is associated with the Click event of cmdAdd:

Copy Code
nCnt = 1
DO WHILE nCnt <= THIS.PARENT.lstSource.ListCount
   IF THIS.PARENT.lstSource.Selected(nCnt)
      THIS.PARENT.lstSelected.AddItem;
         (THIS.PARENT.lstSource.List(nCnt))
      THIS.PARENT.lstSource.RemoveItem(nCnt)
   ELSE
      nCnt = nCnt + 1
   ENDIF
ENDDO
THIS.PARENT.Refresh

To Drag and Drop Items from One List to Another

Implementing drag-and-drop between the list boxes involves code associated with the MouseDown, MouseMove, DragOver, and DragDrop events. Three user-defined properties (DragThreshold, MouseX, and MouseY) extend the usability of the class.

The MouseDown code stores the X and Y coordinates of the mouse pointer to class properties.

Copy Code
*MouseDown
Parameters nButton, nShift, nXCoord, nYCoord
THIS.PARENT.MouseX = nXCoord
THIS.PARENT.MouseY = nYCoord

The MouseMove code makes sure the left mouse button is pressed before initiating the drag procedure. In addition, to guard against accidental dragging, this code checks to make sure that the user has moved the mouse a distance greater than a set threshold (8 pixels by default).

Copy Code
*MouseMove
Parameters nButton, nShift, nXCoord, nYCoord
IF nButton = 1 && Left Mouse
   IF ABS(nXCoord - THIS.PARENT.MouseX) > ;
      THIS.Parent.DragThreshold OR ;
         ABS(nYCoord - THIS.PARENT.MouseY) > ;
         THIS.Parent.DragThreshold
      THIS.Drag
   ENDIF
ENDIF

The DragOver code changes the DragIcon of the source when the mouse pointer enters and leaves the list box "air space."

Copy Code
*DragOver
Parameters oSource, nXCoord, nYCoord, nState
DO CASE
   CASE nState = 0 && Enter
      oSource.DragIcon = THIS.Parent.CanDropIcon
   CASE nState = 1 && Leave
      oSource.DragIcon = THIS.Parent.NoDropIcon
ENDCASE

The DragDrop code makes sure that the source of the drag is not the same as the target of the drag and calls the method associated with the Click event of the cmdAdd command button (in the case of lstSelected) or cmdRemove (in the case of lstSource).

Copy Code
*DragDrop
Parameters oSource, nXCoord, nYCoord
IF oSource.Name != THIS.Name
   THIS.PARENT.cmdAdd.Click
ENDIF

See Also

Other Resources

Controls Solution Samples
Add Items Interactively to a List Box Sample
Display Multiple Columns in a List Box Sample
Display Pictures in a List Sample
Fill a List with Values from Different Sources Sample
Multiselect Items in a List Box Sample
Open Multiple Files Interactively Sample
Sort List Box Items Sample
Treeview/ListBox Drag and Drop Sample


Multiselect Items in a List Box Sample

Visual FoxPro 9.0 Samples
Multiselect Items in a List Box Sample
See Also

File: ...\Samples\Solution\Controls\Lists\Lmsel.scx

This sample shows how to manage multiple items selected in a list box. The form contains a list box with the MultiSelect property set to True (.T.). A combo box on the form contains all the items that are selected in the list box.

To process the multiple-selected items in a list box — to copy them to an array or incorporate them elsewhere in your application — loop through the list items and process the ones for which the Selected property is set to true (.T.). The following code is included in the Click event of the list box to display the selected items in a combo box and the number of selected items in a text box:

Copy Code
nNoSelected = 0    && variable to track number of selected items
THISFORM.cboSelected.Clear    && clear the combo box

* main processing loop
FOR i = 1 TO THIS.ListCount
   IF THIS.Selected(i)
      nNoSelected = nNoSelected + 1
      THISFORM.cboSelected.Additem (THIS.List(i))
   ENDIF
ENDFOR

THISFORM.txtNoSelected.Value = nNoSelected

In the code associated with the Init event of this form, and in many places throughout this sample application, the character string values initially added to the list are first defined with a #DEFINE directive. Each of the defined constants ends with "_LOC". Microsoft internal localization tools extract these definitions so that the strings can be translated into whatever language the application is being localized in.

See Also

Other Resources

Controls Solution Samples
Add Items Interactively to a List Box Sample
Display Multiple Columns in a List Box Sample
Display Pictures in a List Sample
Fill a List with Values from Different Sources Sample
Move Items Between List Boxes Sample
Open Multiple Files Interactively Sample
Sort List Box Items Sample
Treeview/ListBox Drag and Drop Sample


Present a User with Multiple Choices Sample

Visual FoxPro 9.0 Samples
Present a User with Multiple Choices Sample
See Also

File: ...\Samples\Solution\Controls\Buttons\Quiz.scx

This sample illustrates using an option button group with no default selection and binding a character field to the option group.

To display an option group with no selected button, do one of the following:

  1. Set the Value property of each of the option buttons in the group to 0 of .F.

  2. Set the Value property of the option button group to 0.

To store the caption of option buttons to a table field

  1. Set the ControlSource of the option button group to the field.

See Also

Other Resources

Controls Solution Samples
Change Pages When a User Chooses a Button Sample
Display Different Pages without Tabs Sample


Open Multiple Files Interactively Sample

Visual FoxPro 9.0 Samples
Open Multiple Files Interactively Sample
See Also

File: ...\Samples\Solution\Controls\Lists\Multfile.scx

This sample shows how to populate a list with files. When you populate a list with files, built-in functionality makes it possible for a user to select new drives and directories. In this sample, a user can select one or more files in the list and open them for editing.

The following code loops through the items in the list box and opens the selected files for editing:

Copy Code
FOR nFile = 5 to THISFORM.lstFiles.ListCount
   IF THISFORM.lstFiles.Selected(nFile)
      MODIFY FILE (THISFORM.lstFiles.List(2) + ;
         THISFORM.lstFiles.List(nFile)) NOWAIT
   ENDIF
ENDFOR

When the RowSourceType property is set to 7 - Files:

  • lstFiles.List(1) refers to the drive.

  • lstFiles.List(2) refers to the path.

  • lstFiles.List(3) is a separator line.

  • lstFiles.List(4) is [..]. Click to go to the parent directory.

Files can start at lstFiles.List(5)

See Also

Other Resources

Controls Solution Samples
Add Items Interactively to a List Box Sample
Display Multiple Columns in a List Box Sample
Display Pictures in a List Sample
Fill a List with Values from Different Sources Sample
Move Items Between List Boxes Sample
Multiselect Items in a List Box Sample
Sort List Box Items Sample
Treeview/ListBox Drag and Drop Sample


Resize and Reposition Controls at Run Time Sample

Visual FoxPro 9.0 Samples
Resize and Reposition Controls at Run Time Sample
See Also

File: ...\Samples\Solution\Forms\Cresize.scx

A user can resize this sample form as desired. The controls on the form are resized or repositioned relative to the new Height and Width properties of the form.

This form uses the resizable class in ...\Samples\Classes\Samples.vcx to manage resizing and repositioning of the controls. The following line of code is added to the Resize event of the form, calling the AdjustControls method of the resizable class:

Copy Code
THIS.Resizable2.AdjustControls

In the Init of the resizable class, code loops through all the controls in the form, storing their positions and sizes relative to the form in an array. When the form is resized, the AdjustControls method resizes and repositions the controls to their relative sizes and positions.

You can add more controls to the form and the new controls will also be resized and repositioned.

The RepositionList and ResizeList properties contain a space-delimited list of all the classes that you want to reposition and resize. If you do not want a certain class to be resized, remove it from the ResizeList.

You can prevent a user from making the form too small for the objects contained on it by setting the form's MinHeight and MinWidth properties.

See Also

Other Resources

Controls Solution Samples
Resize Object
Allow Users to Drag and Drop Controls Sample
Hot Tracking and Hover Effects Sample


See Check Box Design Options Sample

Visual FoxPro 9.0 Samples
See Check Box Design Options Sample
See Also

File: ...\Samples\Solution\Controls\Checkbox\Checkbox.scx

This sample illustrates a variety of properties that can be set to customize check box display.

Property | Description
ControlSource | A variable or table field that is numeric or logical.
Picture | Bitmap displayed if Style is Graphical.
Style | Graphical for pictures or standard for a box.
Value | .T., .F., 0, 1, 2, or .NULL.

See Also

Other Resources

Controls Solution Samples
Distinct Values Combo
How to: Use Check Boxes to Specify States


See Command Button Design Options Sample

Visual FoxPro 9.0 Samples
See Command Button Design Options Sample
See Also

File: ...\Samples\Solution\Controls\Buttons\Cmdbtn.scx

This sample illustrates a variety of properties that can be set to customize command button display.

Property | Description
Cancel | The Click event code of the command button with Cancel set to true (.T.) is executed when a user presses ESC.
Default | The Click event code of the command button with Default set to true (.T.) is executed when a user presses ENTER.
Picture | Bitmap displayed if Style is Graphical.

See Also

Other Resources

Controls Solution Samples


Sort List Box Items Sample

Visual FoxPro 9.0 Samples
Sort List Box Items Sample
See Also

File: ...\Samples\Solution\Controls\Lists\Lsort.scx

This sample demonstrates making it possible for a user to rearrange or sort the items in a list. The key properties to set are:

Copy Code
   List.MoverBars = .T.
   List.Sorted = .T.

Set the MoverBars property to true (.T.) to make it possible for a user to reorder an item in the list by dragging the button to the left of the item to the new position.

Set the Sorted property to true (.T.) to display the list items in alphabetical order. You can still rearrange the items in the list after they have been sorted. Set the Sorted property to .T. again to sort the list in alphabetical order again.

The Sorted property applies only if the RowSourceType property of the list is set to 0 (None) or 1 (Value).

See Also

Other Resources

Controls Solution Samples
Add Items Interactively to a List Box Sample
Display Multiple Columns in a List Box Sample
Display Pictures in a List Sample
Fill a List with Values from Different Sources Sample
Move Items Between List Boxes Sample
Multiselect Items in a List Box Sample
Open Multiple Files Interactively Sample
Treeview/ListBox Drag and Drop Sample
Use Mover List Boxes for Selecting Data Sample


Treeview/Listbox Drag and Drop Sample

Visual FoxPro 9.0 Samples
Treeview/Listbox Drag and Drop Sample
See Also

File: ...\Samples\Solution\Tahoe\Listdd.scx

This sample provides demonstrations of settings for OLEDragMode and OLEDropMode properties of the TreeView and ListBox controls.

See Also

Other Resources

Controls Solution Samples
Add Items Interactively to a List Box Sample
Display Multiple Columns in a List Box Sample
Display Pictures in a List Sample
Fill a List with Values from Different Sources Sample
Move Items Between List Boxes Sample
Multiselect Items in a List Box Sample
Open Multiple Files Interactively Sample
Sort List Box Items Sample
Add and Remove Items in a Treeview Control


Data Solution Samples

Visual FoxPro 9.0 Samples
Data Solution Samples

These Solution samples illustrate how to perform application development tasks using data.

In This Section

Create a Cursor from an XML DataSet Sample

Demonstrates how to create a cursor from an XML DataSet using the CursorAdapter and XMLAdapter classes and how to bind the data to controls on a form.
Load and Generate XML Using the XMLAdapter Class Sample

Demonstrates some of the many uses for the XMLAdapter class, such as select an XML file to create cursors or generate XML from multiple tables.
Manage Data Access Using CursorAdapters Sample

Demonstrates how CursorAdapter objects retrieve data from three different data source types.

Related Sections

Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Walkthroughs

Contains step-by-step instructions for common scenarios.


Create a Cursor from an XML DataSet Sample

Visual FoxPro 9.0 Samples
Create a Cursor from an XML DataSet Sample
See Also

File: ...\Samples\Solution\Toledo\CAXML.scx

This sample demonstrates how to create a cursor from an XML DataSet using the CursorAdapter and XMLAdapter classes and how to bind the data to controls on a form.

To see the changes in an XML DiffGram

  1. Make changes in the grid and click Show DiffGram.

To view CursorAdapter property settings

  1. Click Show CursorAdapter Properties.

For more information about CursorAdapter and XMLAdapter, see CursorAdapter Class and XMLAdapter Class.

Loading XML into a Cursor

In this sample, the XMLAdapter LoadXML method loads an XML DataSet into an XMLAdapter object and works with a CursorAdapter object to create a cursor. Loading the XML DataSet into the XMLAdapter creates XMLTable objects in the XMLAdapter Tables collection corresponding to the tables in the XML DataSet. The CursorAdapter SelectCmd property is set to the XMLTable object you want to display. When the CursorAdapter CursorFill method is called on the CursorAdapter object, the cursor is created.

For more information, see LoadXML Method, XMLTable Class, and CursorFill Method.

This sample uses an ADO.NET DataSet as the XML file, but the XML file can also be a Visual FoxPro-generated XML DataSet.

To load an XML DataSet into an XMLAdapter object

  1. In the Init event of the sample form, add a property that is an object reference to an XMLAdapter by using the Form or Class designers or by using the AddProperty method in code:

    Copy Code
    ThisForm.AddProperty('oXMLAdapter',CREATEOBJECT('XMLAdapter'))

  2. To create the Tables collection in the XMLAdapter object, load the XML file as shown in the following code:

    Copy Code
    WITH ThisForm.oXMLAdapter
   .LoadXML(ThisForm.cRunPath+'getcustomers.xml',.T.)
ENDWITH

  3. Set CursorAdapter SelectCmd to the XMLTable object and call the CursorAdapter CursorFill method:

    Copy Code
    ThisForm.DataEnvironment.cursor1.SelectCmd= ;
   "ThisForm.oXMLAdapter.Tables.Item(1)"
ThisForm.DataEnvironment.cursor1.CursorFill()

To view the properties of the CursorAdapter object, look in the DataEnvironment object. You can open the DataEnvironment Designer by right-clicking the CursorAdapter object and selecting Builder. The CursorAdapter properties have been set by the CursorAdapter Builder.

For more information, see DataEnvironment Object, Init Event, and CursorAdapter Builder.

Controlling Data Binding

The cursor containing the data that the form uses does not exist when data binding usually occurs. This is because the XMLAdapter object is loading the XML in the form's Init event, which occurs after data binding by default. However, you can control when data binding occurs by setting the Form BindControls property.

In this sample, the form's BindControls property is set to False (.F.). After the CursorAdapter CursorFill method creates the cursor containing the data, BindControls is set to True (.T.). You can then bind the controls on the form using the following code:

Copy Code
ThisForm.BindControls = .T.

For more information, see BindControls Property.

Generating XML DiffGrams with the XMLAdapter

To generate an XML DiffGram, use the XMLAdapter ToXML method, as illustrated in the cmdDiffgram.Click event of this sample:

Copy Code
WITH ThisForm.oXMLAdapter
   .ReleaseXML(.F.)      && Release XML document but preserve schema.
   .UTF8Encoded = .T.    && Indicates International characters.
   .IsDiffgram = .T.     && Generate XML DiffGram.
   llIncludeBefore = .T. && Include <diffgram:before> format.
   llChangesOnly = .T.   && Generate only changes made.
   llIsFile = .F.        && XML is a variable.
   lcSchemaLocation = "" && Generate inline schema.
   .ToXml("lcXML",lcSchemaLocation,llIsFile,llIncludeBefore,llChangesOnly)
ENDWITH

See Also

Other Resources

Data Solution Samples
XML Functionality Using XMLAdapters


Load and Generate XML Using the XMLAdapter Class Sample

Visual FoxPro 9.0 Samples
Load and Generate XML Using the XMLAdapter Class Sample
See Also

File: ...\Samples\Solutions\Toledo\XMLAdapter.scx

You can use the XMLAdapter class to create multiple cursors from XML, such as ADO.NET DataSets, and in reverse, generate XML from multiple cursors.

This sample demonstrates some of the many uses for the XMLAdapter class, such as select an XML file to create cursors or generate XML from multiple tables.

For more information, see XMLAdapter Class.

Loading XML

In this sample, you can load an XML DataSet into an XMLAdapter object by clicking Load XML on the XMLTables tab and selecting a valid XML file, such as one generated from an ADO.NET DataSet or another XMLAdapter object. The Click event of the Load XML button contains the following code that uses the XMLAdapter LoadXML method:

Copy Code
ThisForm.oXMLAdapter.LoadXML(cFilename, .T.)

The name of the file you select is passed as the first parameter to the LoadXML method. The second parameter of LoadXML indicates that the first parameter is a file; otherwise, it assumes that the first parameter is a variable that contains the XML string.

After selecting a file, the XMLAdapter Tables collection fills with as many XMLTable objects as there are tables in the XML DataSet, which you can use to generate cursors.

Adding Tables

In this sample, you can add tables and generate XML by selecting Add Table on the XMLTables tab, selecting a table, and clicking To XML.

When you select Add Table, a list of Northwind tables appears so you can select one or more tables. After opening a table, the table is added to the XMLAdapter object using the AddTableSchema method as follows:

Copy Code
USE ? SHARED IN 0
cTable = LOWER(ALIAS())
ThisForm.oXMLAdapter.AddTableSchema(cTable)

Generating XML

In this sample, you can generate XML after adding tables to the XMLAdapter object and setting any additional properties on XMLAdapter Properties tab.

To generate XML, select To XML on the XMLTables tab, which calls the XMLAdapter ToXML method:

Copy Code
ThisForm.oXMLAdapter.ToXML(XML_FILENAME,, .T., ;
ThisForm.tabXMLAdapter.Page1.chkBefore.Value, ;
ThisForm.tabXMLAdapter.Page1.chkChangesOnly.Value)

In ToXML, leaving the second parameter blank indicates that schema should be generated inline. The third parameter indicates whether the first parameter is the name of a file (True - .T.) or a variable (False - .F.).

See Also

Other Resources

Data Solution Samples
XML Functionality Using XMLAdapters


Manage Data Access Using CursorAdapters Sample

Visual FoxPro 9.0 Samples
Manage Data Access Using CursorAdapters Sample
See Also

File: ...\Samples\Solution\Toledo\CASample.scx

This sample demonstrates how CursorAdapter objects retrieve data from three different data source types:

  • Native

    This sample demonstrates a Native cursor connected to the Visual FoxPro Northwind database.

  • Open Database Connectivity (ODBC)

    This sample demonstrates an ODBC cursor connected to the SQL Server Northwind Database, if installed.

  • ActiveX® Data Objects (ADO)

    This sample demonstrates an ADO cursor connected to the SQL Server Northwind Database, if installed.

The cursors are row buffered and use automatic updates, so when you move off the row, any changes to the row are sent to the database.

To view the property settings of the CursorAdapter objects, click the View CursorAdapter Properties button. These property settings were set using the CursorAdapter Builder.

See Also

Other Resources

Data Solution Samples
CursorAdapter Class
Data Access Management Using CursorAdapters
CursorAdapter Builder


Databases Solution Samples

Visual FoxPro 9.0 Samples
Databases Solution Samples

These Solution samples illustrate application development tasks you can perform with databases.

In This Section

Create a Default Unique ID Value for a Field Sample

Illustrates how to use a stored procedure in a database to provide a default primary key value.
Create Small Indexes Using BINTOC( ) Sample

Illustrates how to use various indexing schemes using numeric and integer data types to reduce index size and disk space.
Index on Expressions Sample

Illustrates several options you can consider when using a character field to represent a unique ID, often comprised of numeric data.
Nest Transactions Sample

Illustrates beginning, ending, and rolling back transactions.
Programmatically Check Table Properties Sample

Illustrates how to retrieve information about a table at run time.
Sort or Order a Table at Run Time Sample

Illustrates how to change the order in which table records are listed.
Use DBC Events Sample

Illustrates how database events make it possible for you to perform actions when a database and its objects are opened, accessed, or manipulated.

Reference

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Classes A-Z

Describes Visual FoxPro Foundation classes you can use for rapid application development.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.

Related Sections

Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Server Samples

Contains samples that illustrate Automation Servers.
Walkthroughs

Provides step-by-step instructions for common scenarios, making them a good place to begin learning about the various features of Visual FoxPro.


Create a Default Unique ID Value for a Field Sample

Visual FoxPro 9.0 Samples
Create a Default Unique ID Value for a Field Sample
See Also

File: ...\Samples\Solution\Db\Newid.scx

This sample uses a stored procedure in a database to provide a default primary key value.

To create a default unique ID

  1. Add a separate table to the database that stores the next ID for each table in the database.

    The name of the table in the sample is Ids.dbf. It contains two fields: Table C(10), NextID I.

  2. In the stored procedures of the database, create a function that returns the next ID value from the ID table.

    The name of the function in the sample is NewID. The code for this function is included in this topic.

  3. Set the default value for the field to the function.

NewID Stored Procedure

Copy Code
FUNCTION NewID(tcAlias)
LOCAL lcAlias, lnID, lcOldReprocess, lnOldArea

  lnOldArea = SELECT()

  IF PARAMETERS() < 1
    lcAlias = UPPER(ALIAS())
  ELSE
    lcAlias = UPPER(tcAlias)
  ENDIF

  lcOldReprocess = SET('REPROCESS')

  * Lock until user presses Esc
  SET REPROCESS TO AUTOMATIC

  IF !USED("IDS")
    USE newid!ids IN 0
  ENDIF
  SELECT ids

  IF SEEK(lcAlias, "Ids", "table")
    IF RLOCK()
      lnID = ids.nextid
      REPLACE ids.nextid WITH ids.nextid + 1
      UNLOCK
    ENDIF
  ENDIF

  SELECT (lnOldArea)
  SET REPROCESS TO lcOldReprocess

  RETURN lnID
ENDFUNC

See Also

Other Resources

Databases Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Create Small Indexes Using BINTOC( ) Sample

Visual FoxPro 9.0 Samples
Create Small Indexes Using BINTOC( ) Sample
See Also

File: ...\Samples\Solution\Db\Index1.scx

This sample shows various indexing schemes you can use with numeric and integer data types to get significant savings in index size and disk space consumed. In addition, smaller sized indexes usually result in faster searches. The BINTOC() function makes it possible for you to convert an integer (numeric) value to a binary character representation.

Syntax

BINTOC(nExpression [, nSize])

Depending on the size of your expression, you can set the nSize parameter to accommodate the value of your expression in the least amount of characters.

The following line of code creates an index on a numeric field:

Copy Code
INDEX on line_no TAG line_no

The next time you are working with indexes on numeric integer data, consider using something like the following:

Copy Code
INDEX on BINTOC(line_no,1) TAG line_no

See Also

Other Resources

Databases Solution Samples
BINTOC( ) Function


Index on Expressions Sample

Visual FoxPro 9.0 Samples
Index on Expressions Sample
See Also

File: ...\Samples\Solution\Db\Index2.scx

This index sample shows several options you might consider when using a character field to represent a Unique ID (one often comprised of numeric data). An index tag based on a character field will sort based on the ASCII values of the data whereas a numeric expression, using the VAL( ) function, will sort on numeric sequences. The following table shows the sort difference of two indexes:

cExpression | VAL(cExpression)
1 | 1
11 | 2
2 | 11
Note:
When you use the VAL( ) function, all non-numeric values will be converted to 0.

By incorporating the BINTOC( ) function, you also can reduce the size of your index tags considerably.

See Also

Other Resources

Databases Solution Samples
VAL( ) Function
BINTOC( ) Function


Nest Transactions Sample

Visual FoxPro 9.0 Samples
Nest Transactions Sample
See Also

File: ...\Samples\Solution\Db\Trans.scx

This sample illustrates beginning, ending, and rolling back transactions. You can decide to commit or discard changes to a single table when you use table buffering, but you can decide to commit or discard changes to any number of tables when you use transactions.

Before editing either table, click the Begin button. After editing, you can click Begin again to nest another transaction, or you can click End to commit your edits to the table or Rollback to discard your changes.

The key commands in this example are as follows:

Copy Code
BEGIN TRANSACTION

END TRANSACTION

ROLLBACK

The function that returns the current number of nested transactions is as follows:

Copy Code
TXNLEVEL( )

See Also

Other Resources

Databases Solution Samples
BEGIN TRANSACTION Command
END TRANSACTION Command
ROLLBACK Command
TXNLEVEL( ) Function


Programmatically Check Table Properties Sample

Visual FoxPro 9.0 Samples
Programmatically Check Table Properties Sample
See Also

File: ...\Samples\Solution\Db\Info.scx

This sample illustrates retrieving information about a table at run time.

Field Information

The AFIELDS( ) function provides most of the information about table fields displayed in this sample. In addition to the information displayed in this sample, AFIELDS( ) provides information about field and table validation expressions and messages, trigger expressions and messages, as well as long table names and table comments in the database.

Index Information

The TAG( ) and KEY( ) functions provide index information.

Copy Code
lo = THISFORM.edtProperties
FOR i = 1 TO TAGCOUNT( )
   IF !EMPTY(TAG(i))  && Checks for tags in the index
      lo.Value = lo.Value + TAG(i) + "  " + KEY(i)
   ELSE
      EXIT
   ENDIF
ENDFOR

See Also

Other Resources

Databases Solution Samples
AFIELDS( ) Function
TAG( ) Function
KEY( ) Function


Sort or Order a Table at Run Time Sample

Visual FoxPro 9.0 Samples
Sort or Order a Table at Run Time Sample
See Also

File: ...\Samples\Solution\Db\Order.scx

This sample illustrates changing the order in which records in a table are listed. The customer table has index tags on the fields displayed in the grid. In the MouseUp event of each of the headers in the grid, the order of the table is set to the index tag associated with the field displayed in the column. For example, the following code is associated with the MouseUp event of the Company header:

Copy Code
LPARAMETERS nButton, nShift, nXCoord, nYCoord
IF nShift = 2 && CTRL
   SET ORDER TO Company DESCENDING
ELSE
   SET ORDER TO Company ASCENDING
ENDIF

GO TOP
THISFORM.Refresh

See Also

Other Resources

Databases Solution Samples
MouseUp Event


Use DBC Events Sample

Visual FoxPro 9.0 Samples
Use DBC Events Sample
See Also

File: ...\Samples\Solution\Sedona\Dbcevents.scx

This sample illustrates database events that make it possible for you to perform actions when a database and its objects (tables, views, relations, etc.) are opened, accessed, or manipulated.

See Also

Other Resources

Databases Solution Samples
Database Container Events


Forms Solution Samples

Visual FoxPro 9.0 Samples
Forms Solution Samples

These Solution samples illustrate application development tasks you can perform with forms.

In This Section

Create a One-To-Many Data Entry Form Sample

Illustrates basic tasks associated with a one-to-many data entry form.
Create a Query-By-Example Form Sample

Illustrates how to provide searching and filtering capabilities for records in the same interface that displays those records.
Create a Single Table Data Entry Form Sample

Illustrates a simple scenario for a single user and single table data entry form.
Create an SDI Form Sample

Illustrates Visual FoxPro support for single document interface (SDI) forms.
Create an Irregularly Shaped Window Sample

Illustrates how you can use the Windows API SetLayeredWindowAttributes function to change the default rectangular-shaped client area of the main Visual FoxPro window or any forms you create.
Display Line Animation on a Form Sample

Illustrates how to draw lines on a form.
Display Pictures in an Image Control Sample

Illustrates how to display bitmaps or icons in an Image control on a form.
Draw Lines and Shapes on a Form Sample

Illustrates how to use form methods to draw figures and shapes on forms.
Graph Equations on a Form Sample

Illustrates how to graph equations on forms.
Manipulate Objects Programmatically Sample

Illustrates how to pass parameters to forms and retrieving values.
Pass Parameters Between Forms Sample

Illustrates how to pass parameters to forms and retrieving values.
Provide "What's This?" Help on a Form Sample

Illustrates how to provide the "What's This?" Help button on a form.
Return a Value from a Form Sample

Illustrates how to return a value from a logon form.
Run Multiple Instances of a Form Sample

Illustrates how to run multiple instances of a form.
Transparent Forms Sample

Illustrates how to use layered windows to improve performance and visual effects with complex shapes.
Use Access/Assign Methods on a Form Sample

Illustrates how to use Access and Assign methods in a form.

Reference

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Classes A-Z

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Reference

Includes topics on productivity tools, as well as the controls, objects, properties, methods, events, statements, functions, and constants available.

Related Sections

Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Server Samples

Contains server samples that illustrate Automation Servers.
Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Walkthroughs

Provides step-by-step instructions for common scenarios, making them a good place to begin learning about the various features of Visual FoxPro.


Create a One-To-Many Data Entry Form Sample

Visual FoxPro 9.0 Samples
Create a One-To-Many Data Entry Form Sample
See Also

File: ...\Samples\Solution\Forms\Many.scx

This sample illustrates the basic tasks associated with a one-to-many data entry form.

When you choose the New button beside the parent table text boxes, the following code is executed:

Copy Code
SELECT CUSTOMER
APPEND BLANK
THISFORM.Refresh

When you choose the New button beside the grid that displays the child records, more code is executed.

After selecting the orders table, the code calculates a new id value for the order, adds the blank record, then stores the parent id and order id to the appropriate fields.

Copy Code
CALCULATE MAX(order_id) ALL TO lMaxID
lMaxID = ALLTRIM(STR(VAL(lMaxID) + 1))

APPEND BLANK

REPLACE cust_id WITH Customer.Cust_id IN orders
REPLACE order_id with lMaxID in orders
Note:
This method of creating a new id value would not be reliable if multiple users were adding new orders at the same time. Instead, you can create a new id as illustrated in the Create a Default Unique ID Value for a Field sample.

See Also

Other Resources

Create a Single Table Data Entry Form
Forms Solution Samples
Solution Samples
Create a Default Unique ID Value for a Field


Create a Query-By-Example Form Sample

Visual FoxPro 9.0 Samples
Create a Query-By-Example Form Sample
See Also

File: ...\Samples\Solution\Forms\Qbf.scx

This sample enables users to search and filter records in the same interface that they view the records.

When a user chooses Enter QBF, the code associated with the Click event of cmdQBFMode begins a transaction and appends a blank record to the table to store the user's query text.

Copy Code
* extract from cmdQBFMode.Click
BEGIN TRANSACTION
APPEND BLANK
THISFORM.Refresh

When the user chooses Query, code associated with the Click event of cmdExecuteQBF rolls back the transaction, throwing away the new record.

You can use transactions only with tables contained in a database. If you want to include QBF capabilities for a table that is not in a database, you can loop through all the controls on the form, save the old ControlSource property setting and set the ControlSource property of the controls to an empty string. After getting the user query string, you can loop back through the controls and reset the ControlSource properties.

Code associated with the Click event of cmdExecuteQBF also loops through the controls on the form, checks for user-entered values, and calls the ParseCondition method to assemble the filter string.

A user can enter a single value to match or an expression. For example, a user can enter either of the values below in the Title text box to set a filter:

Copy Code
Sales Manager

!= "Sales Manager"

If the user doesn't enter an expression, quotation marks aren't required.

The ParseCondition Method

Copy Code
LPARAMETERS cCondition, cControlSource
LOCAL lcRetCondition, lcFieldName
IF TYPE('cCondition') = 'C'
   cCondition = ALLTRIM(cCondition)
ENDIF

lcFieldName = SUBSTRC(cControlSource,(RATC(".",cControlSource)+1))

IF !EMPTY(cCondition) THEN
   IF TYPE('cCondition')$ "CM"
      IF ("<"       $ cCondition OR ;
         "=="    $ cCondition OR ;
         "LIKE"    $ cCondition OR ;
         "<>"    $ cCondition OR ;
         "!="    $ cCondition OR ;
         "#"    $ cCondition OR ;
         "="    $ cCondition OR ;
         ">"    $ cCondition)
           lcRetCondition = lcFieldName + cCondition
      ENDIF
   ENDIF

   IF EMPTY(lcRetCondition)
      DO CASE
         * put quotes around character expressions
         CASE TYPE(cControlSource) $ "CM"
            lcRetCondition = lcFieldName + " = " + CHR(34) + cCondition + CHR(34)

         * put braces around date expressions
         CASE TYPE(cControlSource) $ "DT"
            lcRetCondition = lcFieldName + " = {" + DTOC(cCondition) + "}"

         OTHERWISE
            lcRetCondition = lcFieldName + " = " + STR(cCondition)
      ENDCASE
   ENDIF
ELSE
   lcRetCondition = ""
ENDIF

RETURN lcRetCondition

See Also

Other Resources

Create a One-To-Many Data Entry Form
Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Create a Single Table Data Entry Form Sample

Visual FoxPro 9.0 Samples
Create a Single Table Data Entry Form Sample
See Also

File: ...\Samples\Solution\Forms\Single.scx

This sample illustrates the simplest scenario for a single-user, single-table data entry form.

The ControlSource property of each of the text boxes and combo boxes on the form is set to a field in the Customer table.

An APPEND BLANK command is issued in the Click event of cmdNew.

Copy Code
APPEND BLANK
THISFORM.Refresh

The DELETE command is issued in the Click event of cmdDelete.

Copy Code
* cmdDelete.Click
#DEFINE MSGBOX_YES      6
#DEFINE C_MSGBOX1      36
#DEFINE C_DELETE_LOC   "Are you sure you want to delete this record?"

IF MESSAGEBOX(C_DELETE_LOC,C_MSGBOX1) = MSGBOX_YES
   DELETE
   IF !EOF()
      SKIP 1
   ENDIF
   IF EOF() AND !BOF()
      SKIP -1
   ENDIF
   THISFORM.Refresh
ENDIF

Extending the Data Entry Form

To create a more robust data entry form, one that makes it possible for a user to cancel changes or makes it possible for multiple users to access the same data, you need to use transactions and table or row buffering.

See Also

Other Resources

Create a Query-By-Example Form
Create a One-To-Many Data Entry Form
Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Create an SDI Form Sample

Visual FoxPro 9.0 Samples
Create an SDI Form Sample
See Also

File: ...\Samples\Solution\Forms\Sdiform.scx

This sample illustrates Visual FoxPro support of SDI forms. In order to create an SDI form, all you have to do is set the form's ShowWindow property to 2 – s Top-Level Form. SDI forms do not require the Visual FoxPro window to be visible.

Adding Forms

There are two ways to add forms to a Top-Level (SDI) form. The first and easiest is to create a new form and set its ShowWindow property to 1 (In Top-Level form). While this might seem the most appropriate, it is not always the best solution because the ShowWindow property can only be set at design time.

Another method is to use the ACTIVATE WINDOW command. The code below from the SDIForm sample shows just this. Since this command is not object-based, you must reference a form by its window name (Name property).

Copy Code
ACTIVATE WINDOW (thisform.oWindows[m.nGetWin].NAME) ;
IN WINDOW (thisform.name)

Adding Menus

Menus can also be added to SDI forms. There is now a new Top-Level Form check box in the Menu Designer's View menu General Options dialog box. A Top-Level Form menu will be generated if you check this option and can be called as shown here.

Copy Code
DO sdiform.mpr WITH THISFORM,.T.
Note:
If system menu items rely on the main Visual FoxPro window being visible, they won't give the expected results when the main Visual FoxPro window is hidden.

Adding Toolbars

In addition to menus and windows, you can also add toolbars to your SDI forms. Toolbars are objects like forms, so you can take advantage of the Visual FoxPro object model and scope that toolbar to the form. The SDI form sample uses a custom property to create and keep the toolbar in scope.

Copy Code
SET CLASSLIB TO sditbar ADDITIVE
thisform.oToolbar=create("sditb1")
thisform.oToolbar.show

See Also

Other Resources

Create a Single Table Data Entry Form
Create a Query-By-Example Form
Create a One-To-Many Data Entry Form
Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Create an Irregularly Shaped Window Sample

Visual FoxPro 9.0 Samples
Create an Irregularly Shaped Window Sample
See Also

File: ...\Samples\Solution\Toledo\Irregular.scx

The main Visual FoxPro window and any forms you create have rectangular-shaped client areas by default. To change the shape, you can use the Windows API SetLayeredWindowAttributes function, which sets the opacity and transparency color key of a layered window. SetLayeredWindowAttributes is supported in Microsoft Windows 2000 and Windows XP.

Windows API Function Declarations

In this sample, the form's Init event contains the following declarations for the necessary API functions:

Copy Code
DECLARE INTEGER SetLayeredWindowAttributes IN win32api;
      INTEGER HWND, INTEGER crKey, INTEGER bAlpha, INTEGER dwFlags
DECLARE INTEGER SetWindowLong IN user32.DLL ;
   INTEGER hWnd, INTEGER nIndex, INTEGER dwNewLong
DECLARE INTEGER GetWindowLong IN user32.DLL ;
   INTEGER hWnd, INTEGER nIndex

For more information about the Init event, see Init Event. For detailed information about these declarations and functions, see MSDN online at http://msdn.microsoft.com.

Displaying Irregularly-Shaped Windows

You can display a nonrectangular form by using the SetLayeredWindowAttributes function and setting a transparent color. Shapes that are drawn using this color appear transparent. Also, any mouse clicks in these shapes pass through to the visible form.

This functionality is supported only in Microsoft Windows 2000 and Windows XP but is more efficient than previous techniques for setting a bounding region on the form. Although this technique makes a form transparent, the form must be set up properly to work with this functionality.

To set up the form

  1. On the form, set the Form ShowWindow property to 2 (As Top-Level Form) to make it possible to draw a layered window.

  2. Turn off the window frame because it is not drawn when transparent by setting the following properties for the form:

    Copy Code
    BorderStyle   = 0
Caption   = ""
Closable   = .F.
ControlBox   = .F.
TitleBar   = 0

  3. In the MakeIrregular method of the sample, set the magenta areas, as specified by the nColor variable, to transparent using the following code:

    Copy Code
    * Gets existing flags from the window.
lnFlags = GetWindowLong(nHWND, GWL_EXSTYLE)
ThisForm.nFlags = lnFlags
* Appends Layered flag to existing flags.
lnFlags = BITOR(lnFlags, WS_EX_LAYERED)
* Sets new flags to the window.
SetWindowLong(nHWND, GWL_EXSTYLE, lnFlags)
SetLayeredWindowAttributes(nHWND, nColor, 0, LWA_COLORKEY)

For more information, see Form Designer, Creating Forms, and ShowWindow Property.

See Also

Other Resources

Forms Solution Samples
Solution Samples


Display Line Animation on a Form Sample

Visual FoxPro 9.0 Samples
Display Line Animation on a Form Sample
See Also

File: ...\Samples\Solution\Forms\Graphics\Anim.scx

This sample illustrates drawing lines on a form. More specifically, it demonstrates saving coordinates of sets of lines drawn on a form and redrawing them, along with additional lines at intermediate positions, giving the illusion of motion.

Adding Lines to the Table

Each time a user draws a line on the form, its coordinates are stored in a table with the following structure:

Name | Type | Description
Frameno | I | Incremented each time the user chooses New Frame.
Objno | I | Incremented each time a line is added to a frame.
X1 | I | The starting X coordinate for a line.
X2 | I | The ending X coordinate for a line.
Y1 | I | The starting Y coordinate for a line
Y2 | I | The ending Y coordinate for a line.

Playing the Frames

The following code plays the frames, uses the table again in another work area, selects the second work area, and goes to the next frame:

Copy Code
USE (lcTable) AGAIN IN 0 ALIAS shadow
SELECT shadow
LOCATE FOR frameno # &lcTable..frameno

The variable nBetween determines how many intermediate lines are drawn on the form between a line in one frame and the corresponding line in the next frame.

Copy Code
FOR nb = 1 TO nBetween

Inside the FOR loop, the code scans for all of the lines associated with a frame and calculates coordinates for the intermediate lines, for example:

Copy Code
nx1 = frames.x1 + nb * (shadow.x1 - frames.x1) / nBetween
ny1 = frames.y1 + nb * (shadow.y1 - frames.y1) / nBetween

The code then prints each intermediate line, and after a WAIT of .05 seconds clears the form and continues the loop.

Copy Code
THISFORMSET.frmAnimation.line(nx1,ny1,nx2,ny2)

See Also

Other Resources

Draw Lines and Shapes on a Form
Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Display Pictures in an Image Control Sample

Visual FoxPro 9.0 Samples
Display Pictures in an Image Control Sample
See Also

File: ...\Samples\Solution\Forms\Image.scx

This sample illustrates displaying bitmaps or icons in an image control.

The list box on the form displays files. In the InteractiveChange event of the list box, the Picture property of the image control is set to the selected file, if the file is a .bmp or .ico.

Copy Code
* lstFiles.InteractiveChange
cSelected = UPPER(THIS.List(THIS.ListIndex))
CD THIS.List(2)
IF ".BMP"$cSelected OR ".ICO"$cSelected
   THISFORM.imgDisplay.Picture = THIS.List(2) + cSelected
ENDIF

See Also

Other Resources

Forms Solution Samples
Display Pictures in a List
Solution Samples
Visual FoxPro Foundation Classes A-Z


Draw Lines and Shapes on a Form Sample

Visual FoxPro 9.0 Samples
Draw Lines and Shapes on a Form Sample
See Also

File: ...\Samples\Solution\Forms\Graphics\Fdmain.scx

This sample illustrates how to use form graphics methods (PSet, Line, and Circle) and properties (DrawMode, DrawStyle, DrawWidth) to make it possible for a user to draw figures and shapes on a form in different colors and different pen widths.

The sample includes a toolbar (defined in Fdproc.prg) and a form (based on frmFD in Fd.vcx). The user can select settings in the toolbar that affect the graphics properties of the form. When the form is set to accept user drawing, the MousePointer is set to 2 (cross-hairs).

The drawing functionality is coded in the methods associated with the MouseDown and MouseMove events of the form.

Copy Code
* MouseDown
PARAMETERS nButton, nShift, nXCoord, nYCoord
IF THIS.MousePointer = 2
   THIS.PSet(nXCoord, nYCoord)
ENDIF

* MouseMove
PARAMETERS nButton, nShift, nXCoord, nYCoord
IF THIS.MousePointer = 2
   THISFORM.LINE(nXCoord, nYCoord)
ENDIF

See Also

Other Resources

Display Line Animation on a Form
Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Graph Equations on a Form Sample

Visual FoxPro 9.0 Samples
Graph Equations on a Form Sample
See Also

File: ...\Samples\Solution\Forms\Graphics\Graph.scx

This sample shows how to graph equations with form graphics. The user can scale the equation by choosing the Zoom command buttons. The user also can move the graph's origin by clicking and dragging.

The graphing engines for this sample are in two programs: Cgraph.prg and Pgraph.prg. CGRAPH graphs equations based on Cartesian coordinates. PGRAPH graphs equations based on Polar coordinates. These programs use the PSet and Line methods of a form to draw the equation.

The following code, associated with the OneGraph method of the form set, runs the CGRAPH program when a user chooses the Graph button:

Copy Code
THISFORMSET.frmGraph.Draw

   DO cgraph WITH ;
      graph.equation, ;
      graph.step, ;
      graph.ecolor, ;
      graph.connect, ;
      THISFORMSET.nFormX, ;
      THISFORMSET.nFormY, ;
      .F., ;
      THISFORMSET.frmgraph, ;
      THISFORMSET.nFormScale

The following table lists the parameters for CGRAPH:

Parameter | Type | Description
equation | C | The equation in terms of X. Will plot the answer as Y.
step | N | Step increment.
ecolor | N | Equation color.
connect | L | Whether the previous point is connected to the current point with a line.
nFormX | N | Point on form where x = 0
nFormY | N | Point on form where y = 0
lAddCoords |  | Whether to draw coordinate lines.
frmgraph | C | Name of the form to write to.
nFormScale | N | Scale to graph the equation at.

See Also

Other Resources

Graph Object
Refresh a Graph in a Form
Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Manipulate Objects Programmatically Sample

Visual FoxPro 9.0 Samples
Manipulate Objects Programmatically Sample
See Also

File: ...\Samples\Solution\Forms\Objects.scx

This sample shows how to set properties at run time for objects in a form set. The sample form set contains two forms. Code associated with the Click event of controls on both forms changes the property settings of other controls.

When setting properties of controls at run time, remember to reference the control through its container hierarchy. For example, to set the Value property of a control on one form from code in a method of another form, reference the highest-level container (the form set), and all subsequent containers.

Copy Code
THISFORMSET.frmLeft.chkBold.Value = .F.

See Also

Other Resources

Manipulate Text Programmatically Sample
Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Pass Parameters Between Forms Sample

Visual FoxPro 9.0 Samples
Pass Parameters Between Forms Sample
See Also

File: ...\Samples\Solution\Forms\Param.scx

This solution illustrates passing parameters to a form and returning a value back.

PARAM Form

This form has the user enter a question and possible responses. Then, in the Click event of the cmdAsk button, the ParamAsk form is opened by passing the Question and Possible responses.

Copy Code
cParam1 = THISFORM.txtPassValue1.value
nParam2 = THISFORM.opgPassValue2.value

DO FORM LOCFILE("ParamAsk.scx") WITH cParam1, nParam2 TO nRetValue

PARAMASK Form

The PARAMETERS are passed to the Init of the form where they are processed.

Copy Code
PARAMETERS cQuestion, nButtons
THISFORM.txtQuestion.caption = cQuestion

In the Unload event of the form, the value stored in retvalue is returned back to the calling form:

Copy Code
RETURN THISFORM.retValue

See Also

Other Resources

Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Provide What's This? Help on a Form Sample

Visual FoxPro 9.0 Samples
Provide What's This? Help on a Form Sample
See Also

File: ...\Samples\Solution\Forms\Whatthis.scx

When you provide "What's This?" Help on a form, a button with a question mark is displayed in the upper right corner of the form.

When a user clicks this button or presses SHIFT+ F1, the form is set to WhatsThis mode. You also can programmatically enter this state by calling the WhatsThisMode method of the form. When the form is in WhatsThis mode, the mouse pointer changes. A user can click a control and get context-sensitive help for that control in a pop-up window.

Note:
If the WhatsThisHelpID of a control or a form is set to -1 (the default), the text in the pop-up window indicates that no help topic is available for the control.

To provide "What's This?" Help

  1. Create a Help file with a topic for each control on the form.

  2. In the Map section of the Help project, map HelpContextID values to the topics.

  3. Set the WhatsThisHelp property of the form to true (.T.).

  4. Set the WhatsThisButton property of the form to true (.T.).

  5. Set the WhatsThisHelpID of the controls to the appropriate helpcontextID values.

  6. In the Load or Init of the form, use the SET HELP TO command to specify the help file for the form.

In addition to Whatthis.scx, this sample includes the following files:

File | Description
Whatthis.hlp | The Help file for the form
Whatthis.hpj | The Help project file
Whatthis.rtf | The source document for the Help file

See Also

Other Resources

Help Button Foundation Class
Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Return a Value from a Form Sample

Visual FoxPro 9.0 Samples
Return a Value from a Form Sample
See Also

File: ...\Samples\Solution\Forms\Logform.scx

This sample illustrates returning a value from a logon form. The launching form (Logform.scx) uses the DO FORM command to run the logon form and store the return value to a variable (cUser).

Copy Code
DO FORM Login TO cUser
Note:
To return a value from a form, the WindowType property of the form must be set to 1 - Modal.

The logon form (Login.scx) makes it possible for a user to enter a user name and a password. Code associated with the Click event of cmdOK checks to make sure that the correct password was entered.

Copy Code
LOCATE FOR UPPER(login.userid) = UPPER(ALLTRIM(THISFORM.txtUserName.Value))

IF FOUND() AND ALLTRIM(password) == ALLTRIM(THISFORM.txtPassword.Value)
   THISFORM.cUser = ALLTRIM(login.userid)
   THISFORM.Release
ELSE
   #DEFINE MISMATCH_LOC "The user name or password is incorrect. Please try again."
   WAIT WINDOW MISMATCH_LOC TIMEOUT 1.5
   THISFORM.txtUserName.Value = ""
   THISFORM.txtPassword.Value = ""
   THISFORM.txtUserName.SetFocus
ENDIF

Code associated with the Unload event of the logon form returns the name of the user, if the user entered the correct password, or an empty string.

Copy Code
RETURN THIS.cUser

See Also

Other Resources

Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Run Multiple Instances of a Form Sample

Visual FoxPro 9.0 Samples
Run Multiple Instances of a Form Sample
See Also

File: ...\Samples\Solution\Forms\Launch.scx

This sample demonstrates running multiple instances of a form. aForms is an array property of the form that launches the multiple instances. The following code is associated with the Click event of the command button that launches multiple forms:

Get the number of the last element in the array

Copy Code
nInstance = ALEN(THISFORM.aForms)

Determine the Top and Left Properties to cascade the new forms. These settings are passed as parameters when the form instances are launched.

Copy Code
IF nInstance > 1 AND ;
   TYPE('THISFORM.aForms[nInstance -1]') = 'O'
   nFormTop = THISFORM.aForms[nInstance -1].Top + 1
   nFormLeft = THISFORM.aForms[nInstance -1].Left + 1
ELSE
   nFormTop = 1
   nFormLeft = 1
ENDIF

Set the caption to reflect the instance number

Copy Code
cFormCaption = "Instance" + ALLTRIM(STR(nInstance))

Run the form and assign the object variable to the array element. The Linked keyword indicates that all instances will be released when the array is released. Without LINKED, the multiple instance forms would persist after the array is released.

Copy Code
DO FORM Multi NAME THISFORM.aForms[nInstance] WITH ;
   nFormTop, nFormLeft, cFormCaption LINKED

Redimension the array so that more instances of the form can be launched.

Copy Code
DIMENSION THISFORM.aForms[nInstance + 1]

See Also

Other Resources

Forms Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Transparent Forms Sample

Visual FoxPro 9.0 Samples
Transparent Forms Sample
See Also

File: ...\Samples\Solution\Sedona\Fadeaway.scx

Microsoft Windows 2000 has support for layered windows. Using a layered window can improve significantly performance and visual effects for a window that has a complex shape, animates its shape, or wants to use alpha blending effects. The system automatically composes and repaints layered windows and the windows of underlying applications. As a result, layered windows are rendered smoothly, without the flickering typical of complex window regions. In addition, layered windows can be partially translucent, that is, alpha-blended. This sample shows how you can use layered windows in Visual FoxPro to add special opacity and transparency effects.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Forms Solution Samples
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Use Access/Assign Methods on a Form Sample

Visual FoxPro 9.0 Samples
Use Access/Assign Methods on a Form Sample
See Also

File: ...\Samples\Solution\Tahoe\Aa_fun.scx

This sample demonstrates ways to use Access/Assign methods in a form.

This sample contains the following classes.

Method | Description
caption_assign | Assigns a new value to a form's Caption property.
mybuttons_access | Returns the index of the button.
oshape_access | Returns the shape of the object.
cshapecolor_access | Returns the color of the object.
this_access | Adds a new property and returns its value.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Forms Solution Samples
Visual FoxPro Foundation Class Samples
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Menus and Toolbars Solution Samples

Visual FoxPro 9.0 Samples
Menus and Toolbars Solution Samples

In This Section

Add Menu Items at Run Time Sample

Illustrates how to add menu items to a menu at run time.
Add Personalized Menus Sample

Illustrates how to add personalized menus similar to those in Microsoft Office 2000.
Change Font Attributes Sample

Illustrates how to use a toolbar to set font and color properties for controls on a form.
Coordinate Menu Items and Toolbar Buttons Sample

Illustrates how to coordinate menu items and toolbar buttons that provide the same functionality.
Create Dynamic Shortcut Menus Sample

Illustrates how to alternatively create shortcut menus.
Disable or Display a Check beside a Menu Item Sample

Illustrates how to dynamically make menu items unavailable and display check marks next to specific menu items.
Display Shortcut Menus Sample

Illustrates how to display shortcut menus when the user right-clicks an object.
Use Style Toolbars Sample

Illustrates how to display a custom toolbar with a picture button drop-down list similar to Microsoft Office toolbars.

Reference

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Classes A-Z

Describes Visual FoxPro Foundation classes you can use for rapid application development.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.

Related Sections

Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Server Samples

Contains samples that illustrate Automation Servers.
Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Walkthroughs

Provides step-by-step instructions for common scenarios, making them a good place to begin learning about the various features of Visual FoxPro.


Add Menu Items at Run Time Sample

Visual FoxPro 9.0 Samples
Add Menu Items at Run Time Sample
See Also

File: ...\Samples\Solution\Menus\Fillmenu.scx

This sample illustrates adding menu items to a menu at run time.

The menu definition in this sample is defined in the Menu Designer, with a single prompt and an empty submenu named empty_pop.

Code is included to be executed when a user chooses any item in the menu.

Copy Code
PROCEDURE takeaction(cPrompt)
#DEFINE MSG_LOC "You chose " + cPrompt + "."

IF cPrompt = "Release this menu"
   RELEASE PAD dynmenu of _MSYSMENU
ELSE
   WAIT WINDOW MSG_LOC TIMEOUT 1
ENDIF

The code associated with the Click event of cmdRefresh on the form runs the menu.

Copy Code
DO dynamic.mpr

Then, for each item in the list, the code defines a menu item with the prompt and message text.

Copy Code
FOR i = 1 TO THISFORM.lstMenu.ListCount
   DEFINE BAR i OF empty_pop PROMPT (ALLTRIM(THISFORM.lstMenu.List(i,1))) ;
      MESSAGE (THISFORM.lstMenu.List(i,2))
ENDFOR

There is also code to provide the prompt to make it possible for a user to release the menu.

Copy Code
DEFINE BAR i + 1 OF empty_pop PROMPT "\-"
DEFINE BAR i + 2 OF empty_pop PROMPT "Release this menu" ;
   MESSAGE "Remove the Dynamic Items menu from the menu bar."

See Also

Other Resources

Coordinate Menu Items and Toolbar Buttons
Menus and Toolbars Solution Samples
Solution Samples


Add Personalized Menus Sample

Visual FoxPro 9.0 Samples
Add Personalized Menus Sample
See Also

File: ...\Samples\Solution\Sedona\Mrumenu.scx

You can add personalized menus similar to Microsoft Office 2000 where only the most common menus items appear in the menu. This sample uses a sample menu (Dvdmenu.mnx), which has the special menu code.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Menus and Toolbars Solution Samples
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Change Font Attributes Sample

Visual FoxPro 9.0 Samples
Change Font Attributes Sample
See Also

File: ...\Samples\Solution\Toolbars\Format.scx

This example illustrates using a toolbar to set FontName, FontSize, FontBold, FontItalic, ForeColor, and BackColor properties of controls on a form.

The toolbar is the tbrEditing class in ...\Samples\Classes\Samples.vcx. The nAppliesTo property of the class specifies whether to set the properties of the currently selected control, all text boxes and edit boxes on the form, or all controls on the form. The code in the InteractiveChange or Click event of the toolbar controls sets the properties. For example, the following code is associated with the Click event of cmdBold:

Copy Code
IF TYPE("_SCREEN.ActiveForm") = 'O'
   oForm = _SCREEN.ActiveForm
ELSE
   RETURN
ENDIF

DO CASE
   CASE THIS.Parent.nAppliesTo = 1   && Current Control
      oForm.ActiveControl.FontBold = THIS.Value

   CASE THIS.Parent.nAppliesTo = 2   && Text and edit boxes
      oForm.SetAll('FontBold', THIS.Value, 'TEXTBOX')
      oForm.SetAll('FontBold', THIS.Value, 'EDITBOX')

   CASE THIS.Parent.nAppliesTo = 3   && All Controls
      oForm.SetAll('FontBold', THIS.Value)
ENDCASE

The only code in the form is associated with the GotFocus event of the controls. Each GotFocus event contains the following line of code:

Copy Code
THISFORMSET.tbrEditing.Refresh(THIS)

The Refresh method of tbrEditing sets the values of the editing controls of the toolbar to reflect the current settings of the object whose reference is passed in as a parameter.

See Also

Other Resources

Font Combobox
Fontsize Combobox
Menus and Toolbars Solution Samples
Solution Samples


Coordinate Menu Items and Toolbar Buttons Sample

Visual FoxPro 9.0 Samples
Coordinate Menu Items and Toolbar Buttons Sample
See Also

File: ...\Samples\Solution\Menus\Toolmenu.scx

This sample illustrates coordinating menu items and toolbar buttons that provide the same functionality.

Sometimes you'll want to make particular functionality accessible from both menu items and toolbar buttons. For example, in Visual FoxPro you can save a file by choosing the Save toolbar button or by choosing Save from the File menu.

The three components to this sample are as follows:

Component | Description
Toolmenu.scx | the form
tbrBackColor in Solution.vcx | the toolbar
Toolmenu.mnx | the menu

In the Init event of the form, a toolbar object is created whose object reference is a property on the form, oToolbar.

Copy Code
SET CLASSLIB TO ..\solution
This.oToolbar = CREATEOBJECT('tbrbackcolor')

* Position the toolbar and show it
THIS.oToolbar.Left = THIS.Left + 10
THIS.oToolbar.Top = THIS.Top - 50
THIS.oToolbar.Visible = .T.

* Push the current menu on the stack so it can be
* restored in the Destroy event of the form.
PUSH MENU _MSYSMENU

* Run the menu
DO toolmenu.mpr

Rather than coding duplicate functionality in the toolbar and the menu, updating it both places if changes are required, the code associated with the menu items calls the code associated with the toolbar buttons. For example, the following command is associated with the first menu item:

Copy Code
_VFP.ActiveForm.oToolbar.cmdRed.click

The SKIP FOR clause of the menu items causes them to be disabled when the associated toolbar button is disabled. For example, the following expression is associated with the SKIP FOR clause of the first menu item:

Copy Code
!_VFP.ActiveForm.oToolbar.cmdRed.Enabled

See Also

Other Resources

Item Locator
Format Toolbar
Menus and Toolbars Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Create Dynamic Shortcut Menus Sample

Visual FoxPro 9.0 Samples
Create Dynamic Shortcut Menus Sample
See Also

File: ...\Samples\Solution\Menus\Dynshort.scx

This sample illustrates an alternative way to create shortcut menus.

The shortcut menus in the Display Shortcut Menus sample were created in the Menu Designer. The advantages of using the Menu Designer are ease of design, the ability to create cascading menus, and simple integration on a form. With the Menu Designer, however, you need a separate .mnx, .mnt, and .mpr file for each shortcut menu. If you make a change, you need to generate and compile the menu code again.

The dynamic shortcut menu engine is a custom class that you can add to any form: menulib in ...\Samples\Classes\Utility.vcx. The ShowMenu method of this class defines a menu and displays it at the MousePointer location as determined by the MROW( ) and MCOL( ) functions.

In the RightClick event of the objects you want to create a shortcut menu for, do the following:

  1. Create an array with the shortcut menu items.

  2. Pass the array to the ShowMenu method of the menulib class.

  3. Process the user choice by checking the BAR( ) value.

For example, the following code is associated with the RightClick event of the form:

Copy Code
LOCAL laMenu[5]

laMenu=""
laMenu[1]="\<Center"
laMenu[2]="\<Font..."
laMenu[3]="\<Minimize"
laMenu[4]="\-"
laMenu[5]="E\<xit"
THISFORM.oMenuShortcut.ShowMenu(@laMenu)
DO CASE
   CASE BAR()=1
      THISFORM.AutoCenter=.T.
   CASE BAR()=2
      THISFORM.SetFont
   CASE BAR()=3
      THISFORM.WindowState=1
   CASE BAR()=5
      THISFORM.Release
ENDCASE

See Also

Other Resources

Add Shortcut Menus to Objects
Display Shortcut Menus
Menus and Toolbars Solution Samples
Solution Samples


Disable or Display a Check beside a Menu Item Sample

Visual FoxPro 9.0 Samples
Disable or Display a Check beside a Menu Item Sample
See Also

File: ...\Samples\Solution\Menus\Chkmenu.scx

This sample illustrates dynamically disabling menu items and displaying check marks beside specific menu items.

The menu in this sample was created in the Menu Designer and is run when the form is initialized.

Copy Code
DO chkmenu.mpr

To disable a menu item, include an expression that evaluates to false (.F.) in the SET SKIP OF command. For example, the following line of code in the InteractiveChange event of a check box issues SET SKIP OF with the inverse of the value of the check box, disabling the menu item when the check box is not selected.

Copy Code
SET SKIP OF BAR 1 OF checkitems !THIS.Value

To display a check mark beside a menu item, include an expression that evaluates to true (.T.) after the TO keyword of the SET MARK OF command. For example, the following line of code in the InteractiveChange event of a check box issues the SET MARK OF command with the Value property setting of the check box.

Copy Code
SET MARK OF BAR 1 OF checkitems TO THIS.Value

See Also

Other Resources

Menus and Toolbars Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Display Shortcut Menus Sample

Visual FoxPro 9.0 Samples
Display Shortcut Menus Sample
See Also

File: ...\Samples\Solution\Menus\Shortcut.scx

This sample illustrates displaying shortcut menus when a user "right-clicks" an object. When you have created a shortcut menu in the Menu Designer, the code in the form to activate the menu is very simple. The following code is associated with the RightClick event of the form:

Copy Code
DO frmshort.mpr WITH THIS

The following code is associated with the RightClick event of the edit boxes on the form:

Copy Code
DO edtshort.mpr WITH THIS

The FRMSHORT Menu

The FRMSHORT menu was designed to take an object parameter. The following code is included in the menu's setup code:

Copy Code
PARAMETER oREF
#PREPOP

The #PREPOP generative directive causes the code in the menu's cleanup to be generated before the ACTIVATE POPUP command. This makes it possible for you to disable or enable menu items at run time, as well as display check marks beside menu items.

The code associated with the menu items sets properties of the object that was passed to the .mpr as a parameter. For example, the Always on top item sets the AlwaysOnTop property of the form.

The following code, included in the menu's cleanup code, displays a check mark beside the Always on top item when the form's AlwaysOnTop property is set to true (.T.).

Copy Code
SET MARK OF BAR 4 OF frmshort TO oRef.AlwaysOnTop

The EDTSHORT Menu

The EDTSHORT menu also accepts an object parameter in its setup code. Because there is no need to display a check mark beside the items in this menu, the #PREPOP generator directive is not used.

For an alternative way to display shortcut menus, see the Create Dynamic Shortcut Menus sample.

See Also

Other Resources

Menus and Toolbars Solution Samples
Solution Samples
Create Dynamic Shortcut Menus
Visual FoxPro Foundation Classes A-Z


Use Style Toolbars Sample

Visual FoxPro 9.0 Samples
Use Style Toolbars Sample
See Also

File: ...\Samples\Solution\Sedona\Newtbars.scx

This sample shows a custom toolbar that has a picture button drop-down similar to those on Microsoft Office style toolbars. These drop-downs can be created easily by combining two command buttons and using the VisualEffect property to show them working together in tandem. A standard popup menu can be used for the actual drop-down itself.

This sample contains the following classes

Class | Library | Description
tbar1 | newtbars.vcx | Contains toolbar class showing picture dropdown sample using simple command buttons.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Menus and Toolbars Solution Samples
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Programming Solution Samples

Visual FoxPro 9.0 Samples
Programming Solution Samples

These Solution samples illustrate application development tasks you can perform with Visual FoxPro.

In This Section

Bind, Raise, Unbind, and Retrieve Events Sample

Demonstrates binding events, raising events programmatically, unbinding events, and retrieving events.
Member Classes Sample

Demonstrates how specifying and subclassing member classes makes it possible for you to select a parent container, set the member class library, increase or decrease the member count, and view behavior at design time or run time.
OLE Drag-and-Drop Events Sample

Demonstrates ways to use OLE drag and drop by adding code to the OLEDragDrop and OLEDragOver events.
OLE Drag-and-Drop Data Formats Sample

Demonstrates how to use OLE drag and drop to report data about the dragged item by adding code to the OLEDragDrop and OLEDragOver events.
Pass Strongly Typed Arrays Sample

Demonstrates how you can pass a strongly typed array by reference to a COM server using the COMARRAY function. This sample also demonstrates the interface declaration syntax for specifying ByRef type arrays in the generated COM type library.
SCATTER NAME...ADDITIVE Sample

Demonstrates how to update and saves some form properties from and to a table using the SCATTER command with the NAME and ADDITIVE clauses and the GATHER command with the NAME clause.
Structured Exception Handling Sample

This sample demonstrates how to catch exceptions using the TRY and CATCH blocks, clean up resources using the FINALLY block, and throwing, or escalating, exceptions using a THROW statement.
Taskbar Icon Sample

Demonstrates some common uses of the Systray class, which supports using icons in the Taskbar Notification Area. The Systray class also supports mouse events, balloon tips, and Visual FoxPro shortcut menus for your Taskbar icon so you can use all the features of the Visual FoxPro Menu Designer.
Windows XP Themes Support Sample

Demonstrates different levels of Visual FoxPro support for Windows XP Themes.

Related Sections

Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Walkthroughs

Contains step-by-step instructions for common scenarios.


Bind, Raise, Unbind, and Retrieve Events Sample

Visual FoxPro 9.0 Samples
Bind, Raise, Unbind, and Retrieve Events Sample
See Also

File: ...\Samples\Solution\Toledo\FrmEvents.scx

This sample demonstrates binding events, raising events programmatically, unbinding events, and retrieving events for _SCREEN system variable, or the main Visual FoxPro window. In the sample, you can manually raise a bound event for _SCREEN by selecting an event from the combo box or invoke the same events and their respective handlers by using the mouse.

For more information about _SCREEN, see _SCREEN System Variable.

Binding Events

To respond to Visual FoxPro events, use the BINDEVENT( ) function. In this sample, the BINDEVENT( ) function is called in the custom InitBindEvent method and binds several _SCREEN events to the form's methods. When one of the _SCREEN events fires, the associated handler method is called:

Copy Code
BINDEVENT(_SCREEN,"Resize",ThisForm,"screenresize")
BINDEVENT(_SCREEN,"Mousedown",ThisForm,"screenmousedown")
BINDEVENT(_SCREEN,"Mouseup",ThisForm,"screenmouseup")
BINDEVENT(_SCREEN,"Rightclick",ThisForm,"screenrightclick")
BINDEVENT(_SCREEN,"Dblclick",ThisForm,"screendblclick")

For more information, see BINDEVENT() Function and Init Event.

Raising Events Programmatically

To raise events programmatically, use the RAISEEVENT( ) function. In this sample, when the combo box is selected, the InteractiveChange event uses the returned value to programmatically raise the specified event.

Copy Code
RAISEEVENT(_SCREEN,this.Value)

For more information, see RAISEEVENT() Function and InteractiveChange Event.

Unbinding Events

To unbind event handlers, use the UNBINDEVENTS( ) function. In this sample, the custom UnbindHandlers method unbinds events for _SCREEN.

Copy Code
UNBINDEVENTS(_SCREEN)

For more information, see UNBINDEVENTS() Function.

Retrieve Event Bindings

To retrieve existing event bindings into an array, use the AEVENTS( ) function. In this sample, the custom ScreenDblClick method, which is bound to the _SCREEN DblClick event, uses the AEVENTS( ) function to report the number of event bindings:

Copy Code
AEVENTS(laEvents,Thisform)

For more information, see AEVENTS() Function, and DblClick Event.

See Also

Other Resources

Programming Solution Samples
Event Binding for Visual FoxPro Objects


Member Classes Sample

Visual FoxPro 9.0 Samples
Member Classes Sample
See Also

File: ...\Samples\Solution\Toledo\frmMember.scx

You can specify member classes for the following container classes:

  • PageFrame (Page member class)

  • OptionGroup (OptionButton member class)

  • CommandGroup (CommandButton member class)

  • Grid (Column member class)

  • Column (Header member class)

You can also create subclasses of the Page, OptionButton, CommandButton, Column, and Header classes.

In this sample, you can select a parent container, set the member class library, increase or decrease the member count, and choose to view behavior at design time or run time.

Note:
Observe the differences in behavior that exist during design time and run time. Changes to MemberClass affect all member classes at design time. Only new members are affected at run time.

This sample uses program (.prg)-based and visual class library (.vcx)-based member classes. For more information, see Member Classes.

Specifying a Member Class and Member Class Library

You can specify the member class and its member class library you want to use for the PageFrame, OptionGroup, CommandGroup, Grid, and Column containers by setting the MemberClass and MemberClassLibrary properties for those objects as shown in the following code:

Copy Code
MemberClassLibrary = "MyClasses.vcx"
MemberClass = "MyClassName"

-or-

Copy Code
MemberClassLibrary = "MyClasses.prg"
MemberClass = "MyClassName"

You must set MemberClassLibrary before setting the MemberClass property.

For more information, see MemberClass Property, and MemberClassLibrary Property.

See Also

Other Resources

Programming Solution Samples


OLE Drag-and-Drop Events Sample

Visual FoxPro 9.0 Samples
OLE Drag-and-Drop Events Sample
See Also

File: ...\Samples\Solution\Tahoe\Oledd.scx

This sample demonstrates ways to use OLE drag and drop by adding code to the OLEDragDrop and OLEDragOver events.

See Also

Other Resources

Programming Solution Samples
OLE Drag-and-Drop


OLE Drag-and-Drop Data Formats Sample

Visual FoxPro 9.0 Samples
OLE Drag-and-Drop Data Formats Sample
See Also

File: ...\Samples\Solution\Tahoe\Querydd.scx

This sample demonstrates how to use OLE drag and drop to report data about the dragged item by adding code to the OLEDragDrop and OLEDragOver events.

See Also

Other Resources

Programming Solution Samples
OLE Drag-and-Drop


Pass Strongly Typed Arrays Sample

Visual FoxPro 9.0 Samples
Pass Strongly Typed Arrays Sample
See Also

File: ...\Samples\Solution\Toledo\ComArray.scx

This sample demonstrates how you can pass a strongly typed array by reference to a COM server using the COMARRAY function. The COM server performs calculations and modifies the contents of the array. The client form then uses the DIMENSION command with the AS clause to declare the strongly typed array.

In this sample, the COM server is written in Visual FoxPro. The sample also demonstrates the interface declaration syntax for specifying ByRef type arrays in the generated COM type library.

When opening the sample, you are prompted to register a COM server. The COM server is removed from the registry when you close the sample.

To pass a matrix as a strongly typed array to a COM server

  1. In the sample, type values into the matrix and click Determinant.

The COM server calculates the determinant of the matrix using Gauss-Jordan Reduction.

For more information, see COMARRAY( ) Function and DIMENSION Command.

Passing Strongly Typed Arrays

In the sample, the form uses DIMENSION...AS to declare a strongly typed array as show in the custom CallCOMServer method:

Copy Code
DIMENSION laMatrix(ThisForm.Matrixdim, ThisForm.Matrixdim) AS Double

The array is passed by reference to the Visual FoxPro COM server using the COMARRAY( ) function:

Copy Code
* Instantiate COM server.
loMatrixCalc = CREATEOBJECT("VFPCOMArray.COMARRAYDemo")
* Array is one based and is passed by reference.
COMARRAY(loMatrixCalc,11)
* Pass array to COM server by reference "As Double".
lnResult = loMatrixCalc.Determinant(@laMatrix)

Passing COM Parameters By Reference

In the sample, the custom RegisterCOMServer method contains code that compiles a Visual FoxPro COM server on the fly and registers it. The COM server code illustrates the interface declaration syntax for specifying ByRef typed arrays in the generated COM type library as follows:

Copy Code
FUNCTION Determinant(mat[] AS Double @) AS Double

The array is correctly written to the type library as a strongly typed array. The at sign (@) indicates that the array is passed ByRef in the type library.

See Also

Other Resources

Programming Solution Samples


SCATTER NAME...ADDITIVE Sample

Visual FoxPro 9.0 Samples
SCATTER NAME...ADDITIVE Sample
See Also

File: ...\Samples\Solution\Toledo\ScatterName.scx

This sample demonstrates how to update and saves some form properties from and to a table using the SCATTER command with the NAME and ADDITIVE clauses and the GATHER command with the NAME clause.

In this sample, you can update an existing object with values from the current record using the ADDITIVE clause with SCATTER NAME. You can then change the color, resize, move, or minimize the form, and close it. When you run the form again, it appears with the color, size, location, and previous state from when it was closed.

For more information, see GATHER Command and SCATTER Command.

Setting Form Properties from a Table Using SCATTER...NAME... ADDITIVE

In this sample, the following code in the form's Init event opens a table and sets the form's properties from matching fields in the table as shown:

Copy Code
USE (ThisForm.cRunPath+"FormProps")
SCATTER NAME ThisForm ADDITIVE
USE IN FormProps

The ADDITIVE keyword makes it possible to update and add object properties.

Saving Form Properties to a Table Using GATHER NAME

In this sample, when the form closes, the property values are saved in the matching fields of the table, which occurs in the form's Destroy event.

Copy Code
USE (ThisForm.cRunPath+"FormProps")
GATHER NAME ThisForm
USE IN FormProps
Note:
This table is created in a database so that the lengths of the fields can be longer than 10 characters.

See Also

Other Resources

Programming Solution Samples


Structured Exception Handling Sample (Visual FoxPro)

Visual FoxPro 9.0 Samples
Structured Exception Handling Sample (Visual FoxPro)
See Also

File: ...\Samples\Solution\Toledo\TryCatch.scx

You can implement structured exception handling using the TRY...CATCH...FINALLY error handling structure to run a particular block of statements if a specified exception occurs when your program runs. When an error, or exception, occurs, an Exception object is created.

This sample demonstrates how to catch exceptions using the TRY and CATCH blocks, clean up resources using the FINALLY block, and throwing, or escalating, exceptions using a THROW statement.

For more information, see Structured Error Handling, TRY...CATCH...FINALLY Command and Exception Object.

Catching Exceptions

In this sample, you can choose an error, or exception, you want to cause in the TRY block and view the properties for the Exception object generated from the exception.

To raise an exception

  1. In the CATCHing Exceptions tab, select the error you want from the drop-down list and click Execute TRY block.

The CATCH block runs and displays the Exception object properties.

The following code shows the error handling structure in this particular sample. Usually, code that might generate an exception appears in the TRY block; however, the ERROR command is called specifically to show how the flow of control is passed to the CATCH block only when an exception occurs.

You can use the Exception UserValue property to store any additional information about the error.

Copy Code
TRY
   ERROR nErrorCode
CATCH TO myExceptionmyException.UserValue = "I can handle this."
ENDTRY

Cleaning Up Resources

The FINALLY block usually cleans up any resources allocated by the TRY block and is always the last code to run before control leaves the TRY...CATCH...FINALLY structure.

To observe how FINALLY executes after all other code

  1. In the Using FINALLY tab, select an option or type a table name and path in the combo box and click TRY.

The following code demonstrates how FINALLY executes after all other code.

Copy Code
TRY
   lnPrevArea = SELECT()
   USE CUSTOMERS IN 0 EXCLUSIVE
* Handle when file does not exist.
CATCH TO myException WHEN myException.ErrorNo = 1
* Handle when file is in use.
CATCH TO myException WHEN myException.ErrorNo = 3
* Handle when file access is denied.
CATCH TO myException WHEN myException.ErrorNo = 1704
* Catch everything else.
CATCH TO myException

* Code in FINALLY block always executes.
FINALLY
IF USED('CUSTOMERS')
      USE IN CUSTOMERS
   ENDIF
   SELECT (lnPrevArea)
ENDTRY

Throwing Exceptions

To escalate an exception to a higher-level error handler, use a THROW statement in a CATCH block.

This sample uses nested TRY blocks. The inner TRY block can handle only the first error. For subsequent errors, the inner TRY block escalates the Exception object to the outer TRY block. When a specific exception is thrown, specifically THROW oMyException in this example, the UserValue property of the caught exception in the outer block contains the thrown exception from the inner block.

Copy Code
TRY
   * Run some code.
   TRY
      * Error occurs.
      ERROR 3
      CATCH TO InnerException WHEN InnerException.ErrorNo = 1
      InnerException.UserValue = "INNER TRY: I can handle this."
      CATCH TO InnerException
      InnerException.UserValue = "INNER TRY: I can't handle this."
      * Error cannot be handled so escalate to outer TRY block.
      THROW InnerException
   ENDTRY
CATCH TO OuterException
* In this case, when the exception is escalated, the caught exception's
* UserValue property contains the escalated exception from inner TRY.
? OuterException.UserValue.UserValue
ENDTRY

You can also throw a string message. In this case, the string message is stored in the UserValue property of the outer exception:

Copy Code
TRY
   * Run some code.
   TRY
      * Error occurs.
        ERROR 1
   CATCH
      THROW "INNER TRY: I can't handle this one."
   ENDTRY
CATCH TO OuterException
   ? OuterException.UserValue
ENDTRY

See Also

Other Resources

Programming Solution Samples


Taskbar Icon Sample

Visual FoxPro 9.0 Samples
Taskbar Icon Sample
See Also

File: ...\Samples\Solution\Toledo\SysTray_Sample.scxLibrary: ...\ Samples\Solution\Toledo\SysTray.vcxReadMe: ...\Samples\Solution\Toledo\SysTray_ReadMe.htm

This sample demonstrates some common uses of the Systray class. This class supports using icons in the Taskbar Notification Area. The Systray class also supports mouse events, balloon tips, and Visual FoxPro shortcut menus for your taskbar icon so you can use all the features of the Visual FoxPro Menu Designer.

For detailed information about the properties, events, and methods of the Systray class library included with the sample, see SysTray_ReadMe.htm.

See Also

Other Resources

Programming Solution Samples
Menu and Shortcut Designers


Windows XP Themes Support Sample

Visual FoxPro 9.0 Samples
Windows XP Themes Support Sample
See Also

File: ...\Samples\Solution\Toledo\Themes.scx

This sample demonstrates different levels of Visual FoxPro support for Windows XP Themes. Themes are turned on by default.

Visual FoxPro supports Windows XP themes at three levels:

  • Application level using SYS(2700) - Enables Windows XP Themes and _SCREEN Themes property

  • Form level using the Form Themes property

  • Control level

Themes Support at the Application Level

In this sample, you can turn Themes on in the entire Visual FoxPro application using the SYS(2700) - Enables Windows XP Themes function by selecting Enable Themes at the application level - SYS(2700), which uses the following code:

Copy Code
SYS(2700,1)

To turn Themes off, pass a zero (0) as the second parameter to SYS(2700).

Copy Code
SYS(2700,0)

To turn Themes on using the _SCREEN variable, select Enable Themes at the application level - _SCREEN.Themes, which sets _SCREEN Themes to True (.T.):

Copy Code
_SCREEN.Themes = .T.

To turn Themes off using _SCREEN, set _SCREEN Themes to False (.F.):

Copy Code
_SCREEN.Themes = .F.

For more information, see SYS(2700) - Enables Windows XP Themes and Themes Property.

Themes Support at the Form Level

In this sample, to turn Themes on at the form level, select Enable Themes at the form level, which sets the form's Themes property to True (.T.):

Copy Code
ThisForm.Themes = .T.

Themes Support at the Control Level

You can also turn on Themes support for individual controls. Turning Themes off at the control level overrides the Themes setting at the application or form level. Depending on the control, you can set Themes support through the Themes or Style properties.

For more information, see Style Property.

See Also

Other Resources

Programming Solution Samples


Reports Solution Samples

Visual FoxPro 9.0 Samples
Reports Solution Samples

These Solution samples illustrate tasks you can perform with reports.

In This Section

Print a Percent of Total in a Report Sample

Illustrates how to calculate and display values at the beginning of a report before all records from the record source have been printed.
Print an Invoice Sample

Illustrates how a report uses a view to combine information from multiple tables, a function to collect data from the user, and a one-to-many report layout.
Print Customer Mailing Labels Sample

Illustrates how to print mailing labels.
Print Data Dictionary Information Sample

Illustrates how to generate a report with the contents of a Visual FoxPro database.
Print in Catalog Format Sample

Illustrates how to print a directory, wrap text around graphics, alternate the printing position of controls, and position floating fields below fields that stretch.
Print Product Orders By Quarter Sample

Illustrates how to generate and print graphs without suspending normal operations.
Print Report Details in a Ledger Style Sample

Illustrates how to print a record list with an alternating background color.
Use Conditional Formatting in a Report Sample

Illustrates how to change field formatting based on record values.

Reference

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Classes A-Z

Describes Visual FoxPro Foundation classes you can use for rapid application development.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.

Related Sections

Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Server Samples

Contains samples that illustrate Automation Servers.
Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Walkthroughs

Provides step-by-step instructions for common scenarios, making them a good place to begin learning about the various features of Visual FoxPro.


Print a Percent of Total in a Report Sample

Visual FoxPro 9.0 Samples
Print a Percent of Total in a Report Sample
See Also

File: ...\Samples\Solution\Reports\Percent.frx

The sample report, Percent.frx, shows one way to calculate and display values at the beginning report before all the records from the record source have been printed. This sample report prints a percentage based on a total that is usually calculated and printed at the end of a report.

The sample report uses the tables, EMPLOYEE and ORDERS, in its Data Environment. A public variable and expressions using the ORDER_AMT field are used to calculate the percentages.

To sort the data appropriately for the group defined in the report, the Order property on Cursor1 is set to the EMP_ID index.

The public variable, nTotalSales, defined in the Init event of Cursor2, stores the total for all orders. The variable is declared public to make it visible beyond the Cursor2 Init code.

A field control in the Group Footer band calculates and displays the percentage for each employee using the following expression:

Copy Code
STR(INT((emp_total / nTotalSales)*100)) + " " + "%"

A field control in the Summary band calculates and displays the total percentage for all employees using the following expression:

Copy Code
STR(INT((nTotalSales / nTotalSales)*100)) + " " + "%"

See Also

Other Resources

Reports Solution Samples
Print an Invoice
Solution Samples
Visual FoxPro Foundation Classes A-Z


Print an Invoice Sample

Visual FoxPro 9.0 Samples
Print an Invoice Sample
See Also

File: ...\Samples\Solution\Reports\Invoice.frx

This report shows an invoice report that uses a view to combine information from multiple tables, a function to collect data from the user, and a one-to-many report layout. When the report is run, the view runs first and prompts the user for a date range using a function called Datepick.prg. After the user provides the dates, the view runs and selects the records to display in the report.

The Record Source The view, INVOICE, used in this report resides in the TESTDATA database provided with the Solution project. This view combines data from four tables, CUSTOMER, ORDERS, ORDITEMS, and PRODUCTS. To filter the tables for records within a date range, the view has two filters each with a parameter, dStart_Date and dEnd_Date.

The Data Environment The view is included in the data environment. To store values collected for the view and to restore the path setting, the BeforeOpenTables method of the data environment declares three public variables: dStart_date, dEnd_Date, and cOldPath. The first two match the parameters specified in the view. The third, cOldPath, saves the current path setting so the path can be restored in the Destroy method. The path is then changed so the report is able to find the function, which prompts the user for a range of dates. The final command runs the function.

The Destroy method of the data environment has public variables for the start and end dates, path setting to return the default path to what it was before the report was run, and release statements for all three of the public variables.

The Datepick.prg This function defines and runs a form class called frmDATEPICK. The form class includes four combo boxes that display and collect values to use in the public variables, dStart_Date and dEnd_Date. The four variables collected are nFromMonth, nFromYear, nToMonth, and nToYear. These variables store the user input and are used to determine the value of dStart_Date and dEnd_Date. The function also checks to make sure the user entered values for each element of the date and verifies that the end date is after the start date.

The Report Layout In the report layout, a Group Header band holds the controls for the customer information, the Detail band has the controls for the order items, and the Group Footer band holds the controls that display the calculated values for the invoice.

To format the address appropriately, an expression in the control concatenates several fields with appropriate punctuation. To calculate values in the Group Footer band, two report variables, nSubtotal and nDiscount, store values for the subtotal and the percentage discount.

See Also

Other Resources

Reports Solution Samples
Print Customer Mailing Labels
Solution Samples
Visual FoxPro Foundation Classes A-Z


Print Customer Mailing Labels Sample

Visual FoxPro 9.0 Samples
Print Customer Mailing Labels Sample
See Also

File: ...\Samples\Solution\Reports\Cust.lbx

This sample illustrates printing mailing labels, one for each customer in the customer table.

The labels include the following four items:

  • Company

  • Contact + ", " + Title

  • Address

  • City + ", " + Region+ " " + Country

The logo is displayed on each label by using the OLE container control.

See Also

Other Resources

Reports Solution Samples
Print an Invoice
Solution Samples
Visual FoxPro Foundation Classes A-Z


Print Data Dictionary Information Sample

Visual FoxPro 9.0 Samples
Print Data Dictionary Information Sample
See Also

File: ...\Samples\Solution\Reports\Dbctofrx.scx

This sample illustrates a simple way to generate a report with the contents of a Visual FoxPro database (dbc). Simply pick a .dbc file when prompted and a report will be generated for you to preview. You can click on the Print button to generate a hard copy of it.

The sample creates a temporary cursor and inserts new records as the .dbc is scanned. Table and view records are added along with their associated field and index information.

See Also

Other Resources

Reports Solution Samples
Print an Invoice
Solution Samples
Visual FoxPro Foundation Classes A-Z


Print in Catalog Format Sample

Visual FoxPro 9.0 Samples
Print in Catalog Format Sample
See Also

File: ...\Samples\Solution\Reports\Wrapping.frx

The sample report, Wrapping.frx, prints an employee directory and shows how you can wrap text around graphics, alternate the print position of controls, and float controls below fields that stretch. The data environment for this report contains the EMPLOYEE table from the Testdata.dbc in the Solution project.

The Report Layout

The Title band holds the name and description of the report. The Detail band holds the field and label controls that print for each record. For each record the report displays the following four categories of information:

  • Employee name and title

  • Biography

  • Box of quick reference information such as phone and address

  • Photograph

After printing the name and title, this report wraps the text of the biography around the photograph, alternates information from left to right, and floats the box down the page relative to the biography.

Wrap Text around Graphics

To wrap the memo field around the picture, the report uses two field controls to display the contents of the memo field. The first control is above the picture to display two lines of text. The second field is also sized to show two lines of text, but is narrower and positioned next to the picture.

The first field control prints all of the words in the memo field up to the position where a break should occur to continue the words in the second control. The expression is shown below.

Copy Code
LEFTC(employee.notes,nWrapCharPos)

The second field control prints the remaining words from the memo field. The expression for the second field control is shown below.

Copy Code
LTRIM(RIGHTC(employee.notes,(nMemoLen-(nWrapCharPos))))

The expressions for the controls use report variables to determine the words the controls display from the memo field.

  • nFirstMemoLen determines the number of characters that can be displayed in the first field without truncating. For this report, the variables value is always 185. If you use this in your own report, you will need to change this constant to match the maximum number of characters you want above the picture.

  • nMemoLen determines the length of the memo field for the current record. This variable's expression is LENC(employee.notes).

  • nSpace determines the character position of the first space after the characters displayed in the first control. This variable's expression is AT_C(CHR(32),RIGHTC(employee.notes,(nMemoLen - nFirstMemoLen))).

  • nWrapCharPos determines the character position within the memo field where the break should occur. This variable's expression is nSpace + nFirstMemoLen.

Alternate the Position of Printed Objects

In this report, the positions of the employee biography, the quick reference group, and the photograph alternate from left to right with each record. To alternate the positions, the report has two sets of controls for the parts of the report that alternate. Because two controls are used to wrap the biography text, the first control does not alternate and, therefore, does not need to be included in the two sets.

One set of controls specifies printing with the photograph on the left side. A second set specifies the printing for the photograph on the right side. The controls in both sets use a report variable, nCounter, that calculates a count which determines when the set should print. One set prints when nCounter's value is 0; the other when the value is 1. The Print When expression for the first set of controls is MOD(nCounter,2) = 0. For the second set, the expression is MOD(nCounter,2) = 1.

Float Controls below Controls That Stretch

This report prints the box of information that prints below the biography. Since the length of the biography varies with each record, the control that displays the biography information next to the picture is set to stretch and uses only the space necessary to print the contents of the field. The box that prints below the biography floats down the page depending on the length of the biography. This box is a group of field, label, and rectangle controls. To prevent the biography from printing on top of the group, the field position for each of the controls in the group is set to float.

See Also

Other Resources

Reports Solution Samples
Print Report Details in a Ledger Style
Solution Samples
Visual FoxPro Foundation Classes A-Z


Print Product Orders By Quarter Sample

Visual FoxPro 9.0 Samples
Print Product Orders By Quarter Sample
See Also

File: ...\Samples\Solution\Reports\Ordgraph.scx

This sample illustrates generating and printing graphs on the fly. Visual FoxPro makes it possible for you to add graphs to forms as either OleControls or OleBoundControls. The latter representing a graph, which is bound to data using a General field.

If you intend to use the Visual FoxPro report writer to print graphs, you need to use General fields to store the graphs. The easiest way to create a new graph in a General field is to use the APPEND GENERAL command, for example:

Copy Code
APPEND GENERAL graphfield CLASS "msgraph"

The example above will create a graph in a General field, however, it will not contain your data. The DATA clause actually passes data to the graph.

The following code loops through records already containing data and constructs a string to pass to the graph with APPEND GENERAL .... DATA:

Copy Code
SCAN NEXT m.totrecs
   m.cData = ""+TAB+m.f2+TAB+m.f3+TAB+m.f4+CRLF+;
      EVAL(fields(1))+ TAB + ;
      ALLTRIM(STR(EVAL(field(2))))+ TAB +;
      ALLTRIM(STR(EVAL(field(3))))+ TAB + ;
      ALLTRIM(STR(EVAL(field(4))))
   m.cDetails = ;

f2+"-" +ALLTRIM(STR(EVAL(FIELD(2)))) ;
      + CRLF + f3+"-" +ALLTRIM(STR(EVAL(FIELD(3)))) ;
      + CRLF + f4+" - "+ALLTRIM(STR(EVAL(FIELD(4)))) +CRLF
   INSERT INTO prodsales ;
VALUES(SalesData.prod_name,tmpgrph.graph,m.cDetails)
   APPEND GENERAL prodsales.sales DATA m.cData
ENDSCAN

Once you have a table or cursor containing a General field with your graphs, you can then print it to a Visual FoxPro report using the REPORT FORM command. You cannot include an ActiveX control in a report.

See Also

Other Resources

Reports Solution Samples
Create Record Bound Graphs
Solution Samples
Visual FoxPro Foundation Classes A-Z


Print Report Details in a Ledger Style Sample

Visual FoxPro 9.0 Samples
Print Report Details in a Ledger Style Sample
See Also

File: ...\Samples\Solution\Reports\Ledger.frx

The report, Ledger.frx, prints an employee phone list that alternates printing a gray background behind records. The data environment for this report contains the EMPLOYEE table from the Testdata.dbc in the Solution project.

In the report layout, the Page Header band has label controls that print the report title, description, and column headings. The Detail band has the field and label controls that print the information for each employee.

To print with ledger style, the controls for the employee information are on top of a rectangle. The rectangle's color is gray and its mode is opaque. The report prints the rectangle for every other record by evaluating an expression in the Print When options of the rectangle control. The expression is MOD(nCounter,2) = 1 which uses a report variable, nCounter that increments for each record printed. The report uses the value of this variable to determine when to print the rectangle.

See Also

Other Resources

Reports Solution Samples
Print in Catalog Format
Solution Samples
Visual FoxPro Foundation Classes A-Z


Use Conditional Formatting in a Report Sample

Visual FoxPro 9.0 Samples
Use Conditional Formatting in a Report Sample
See Also

File: ...\Samples\Solution\Reports\Colors.frx

This sample report demonstrates how you can use Print When conditions for controls to change field formatting based on the values in the record. The sample prints a "Product Inventory Report." If the product item is discontinued, it is printed in strikeout. If the In Stock amount is below the reorder level and the product is not discontinued, the item is printed in red. Otherwise, the product item is printed in standard black.

This report uses the table, PRODUCTS, from the database, TESTDATA, in the Data Environment. The Detail band has field controls for the product information such as ID, name, amount in stock, and amount on order. Another field control prints a reminder when the stock goes below a set reorder amount.

To handle the three cases, three sets of field controls for the product information are layered on top of each other in the Detail band. For the first set, the text color is red; for the second, the color is black; and for the third, the font effect is Strikeout.

Each control set has a different Print When expression.

  • For the plain black fields:

    Copy Code
    (products.in_stock > products.reorder_at) and products.discontinu = .F.
  • For the strikeout fields:

    Copy Code
    products.discontinu = .T.
  • For the red text color fields:

    Copy Code
    products.in_stock <= products.reorder_at and products.discontinu = .F.

See Also

Other Resources

Reports Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Views and Queries Solution Samples

Visual FoxPro 9.0 Samples
Views and Queries Solution Samples

These Solution samples illustrate application development tasks you can perform with queries and views.

In This Section

Interactively Build a SELECT Statement Sample

Illustrates how to create a custom query at run time.
Select Customers in a Specific Country Sample

Illustrates how to use a parameterized view to display a subset of records matching a variable that is set at run time.
Select Records from a Full Outer Join Sample

Illustrates how to select records from two tables using a full outer join condition.
Select Records from a Left Outer Join Sample

Illustrates how to select records from two tables using a left outer join condition.
Select Records from a Nested Join Sample

Illustrates how to select records from multiple tables using nested join conditions.
Select Records from a Right Outer Join Sample

Illustrates how to select records from two tables using a right outer join condition.
Select Records from an Inner Join Sample

Illustrates how to select records from two tables using an inner join condition.
Select Records from Both Inner and Outer Joins Sample

Illustrates how to select records from multiple tables using a combination of inner and outer join conditions.
Select the 10 Worst-Selling Products Sample

Illustrates how to select the records using the TOP clause in the SQL SELECT command.
Select the Top 10 Best-Selling Products Sample

Illustrates how to select the records using the TOP clause in the SQL SELECT command.

Reference

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Classes A-Z

Describes Visual FoxPro Foundation classes you can use for rapid application development.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.

Related Sections

Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Server Samples

Contains samples that illustrate Automation Servers.
Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Walkthroughs

Provides step-by-step instructions for common scenarios, making them a good place to begin learning about the various features of Visual FoxPro.


Interactively Build a SELECT Statement Sample

Visual FoxPro 9.0 Samples
Interactively Build a SELECT Statement Sample
See Also

File: ...\Samples\Solution\Forms\Makesql.scx

This sample shows how to make it possible for a user to build a custom query at run time. Combo boxes on the form make it possible for a user to choose fields from the currently open table. The BldSQL method processes the names of the fields and the values users type into text boxes to create an executable SQL SELECT statement.

Additional methods, ValidateType and SetTextboxFormat, make sure that the appropriate values are entered into the text boxes and correctly incorporated into the SELECT statement.

After the WHERE clause has been constructed and stored to the variable lcWhere, the following command creates the SELECT statement:

Copy Code
lcSQL = "SELECT * FROM " + lcAlias + " " + lcWHERE

Once the SELECT statement is constructed, it can be executed with macro substitution.

Copy Code
&lcSQL

See Also

Other Resources

Views and Queries Solution Samples
Array Handler
Solution Samples
Visual FoxPro Foundation Classes A-Z


Select Customers in a Specific Country Sample

Visual FoxPro 9.0 Samples
Select Customers in a Specific Country Sample
See Also

File: ...\Samples\Data\Testdata.dbc

This sample illustrates using a parameterized view ("customers in specific country" in the testdata database) to display a subset of records that match a variable set at run time.

To create a parameterized view in the View Designer, enter a variable prefixed with a question mark (?) in the Example box of the Filter tab.

If the variable does not exist at run time, the user is prompted to enter a value for the variable, whichcountry in this example. If the variable already exists, the view displays matching records without prompting for a new value.

See Also

Other Resources

Views and Queries Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Select Records from a Full Outer Join Sample

Visual FoxPro 9.0 Samples
Select Records from a Full Outer Join Sample
See Also

File: ...\Samples\Data\Fouterj.qpr

The query, FOUTERJ, in the Solution project combines information from the country table and the customer table using a full outer join. Each result record has a field for each of the fields from the country table, and the country and cust_id field for the field from the customer table as specified in the SELECT clause of the SELECT-SQL statement.

Copy Code
SELECT Country.*, Customer.country, Customer.cust_id;
 FROM testdata!customer FULL JOIN country ;
  ON Customer.country = Country.country

Typically, a full outer join answers three questions about the records in your database. Some of the questions this query could answer include:

  • Which customers are in which countries or regions?

  • Which countries or regions do not have any of our customers in them?

  • Which customer records are missing country/region information?

This information might help someone decide if they should expand their business to other countries, change their marketing strategy in some countries or regions, or simply that some records in the database need the country/region information updated.

The full outer join returns all records from both tables and combines records that match the join condition. The result set includes the following three subsets of records:

  • Records matching the join condition that combine information from a record in each table.

  • Records from the country table that do not match the join condition.

  • Records from the customers table that do not match the join condition.

Because each record in the results has the same fields, the records that did not have a match in the other table have NULL values in the fields that would otherwise hold values from the other table. For example, if a record for the country Russia did not have any related customer records in the customer table, that record appears in the results with NULL as the value of the field, cust_id and country_b.

You can change the results of the query by specifying filters, a sort order, group, or other miscellaneous options for the query.

See Also

Other Resources

Views and Queries Solution Samples
Solution Samples


Select Records from a Left Outer Join Sample

Visual FoxPro 9.0 Samples
Select Records from a Left Outer Join Sample
See Also

File: ...\Samples\Data\Louterj.qpr

The query, LOUTERJ, in the Solution project combines information from the orders table and the customer table using a left outer join. Each result record has a field for the order_id from the orders table and for the cust_id, company, country fields from the customer table as specified in the SELECT clause of the SELECT-SQL statement.

Copy Code
SELECT Customer.cust_id, Customer.company, Customer.country,;
 Orders.order_id;
 FROM testdata!orders LEFT OUTER JOIN testdata!customer ;
  ON Orders.cust_id = Customer.cust_id

Typically, a left outer join can answer two questions about the records in your database. Some of the questions this query could answer include:

  • Which orders belong to which customers?

  • Which orders do not have related customer information?

This information helps the database administrator determine which order records are missing information.

The left outer join returns all records from the table on the left of the join condition combined with the records from the table on the right of the condition that match the condition. The results set includes the following two subsets of records:

  • Records matching the join condition that combine information from a record in each table.

  • Records from the orders table that do not match the join condition.

Because each record in the results has the same fields, the records with an order_id that did not have a match in the customer table have NULL values in the fields that would otherwise hold values from the customer table. For example, if the record for order 11079 did not have any related customer records in the customer table, that record appears in the results with the value NULL in the fields, cust_id, company, and country.

You can change the results of the query by specifying filters, a sort order, group, or other miscellaneous options for the query.

See Also

Other Resources

Views and Queries Solution Samples
Solution Samples


Select Records from a Nested Join Sample

Visual FoxPro 9.0 Samples
Select Records from a Nested Join Sample
See Also

File: ...\Samples\Data\Nested.qpr

The query, NESTED, in the Solution project combines information from the customer, orders, and orditems tables using two inner join conditions. One join condition is between customer and orders; the other between orders and orditems. Each result record has fields for the cust_id and company from the customers table, order_id from the orders table, and line_no from the orditems table as specified in the SELECT clause of the SELECT-SQL statement.

Copy Code
SELECT Customer.cust_id, Customer.company, Orders.order_id, Orditems.line_no;
 FROM testdata!customer INNER JOIN testdata!orders;
 INNER JOIN testdata!orditems ;
 ON Orders.order_id = Orditems.order_id ;
 ON Customer.cust_id = Orders.cust_id

The order in which the tables are joined determines the order in which the join conditions are evaluated. In this query, the join between orders and orditems is evaluated first and produces a subset of records that meets the join condition. This subset of records is matched to the records in the customer table and produces the final results set.

You can change the results of the query by specifying filters, a sort order, group, or other miscellaneous options for the query.

See Also

Other Resources

Views and Queries Solution Samples
Solution Samples


Select Records from a Right Outer Join Sample

Visual FoxPro 9.0 Samples
Select Records from a Right Outer Join Sample
See Also

File: ...\Samples\Data\Routerj.qpr

The query, ROUTERJ, in the Solution project uses the testdata database, and combines information from the orders table and the employee table using a right outer join. Each result record has a field for the order_id from the orders table and for the lastname field from the employee table.

Copy Code
SELECT Orders.order_id, Employee.last_name;
 FROM testdata!employee RIGHT OUTER JOIN testdata!orders ;
 ON Employee.emp_id = Orders.emp_id

Typically, a right outer join can answer two questions about the records in your database. Some of the questions this query could answer include:

  • Which orders were entered by which employees?

  • Which orders do not have an employee specified?

This information might help track specific orders and identify orders that do not have an employee specified as placing the order.

The right outer join retrieves all records from the table on the right of the join condition combined with the records from the table on the left that match the join condition. The results set includes the following two subsets of records:

  • Records matching the join condition that combine information from a record in each table.

  • Records from the orders table that do not match the join condition.

Because each record in the results has the same fields, the records with a lastname that did not have a match in the orders table have NULL values in the field that would otherwise hold values from the orders table. For example, if a record for order number 11078 did not have any related employee records in the employee table, that record appears in the results with the value NULL in the field, lastname.

You can change the results of the query by specifying filters, sort order, group, or other miscellaneous options for the query.

See Also

Other Resources

Views and Queries Solution Samples
Solution Samples


Select Records from an Inner Join Sample

Visual FoxPro 9.0 Samples
Select Records from an Inner Join Sample
See Also

File: ...\Samples\Data\Innerj.qpr

The query, INNERJ, in the Solution project uses the database, TESTDATA, and combines information from the tables, ORDERS and CUSTOMER using an inner join condition. Each result record has fields for the CUST_ID, COMPANY, and COUNTRY from the CUSTOMERS table, and ORDER_ID from the ORDERS table as specified in the SELECT clause of the SELECT-SQL statement.

Copy Code
SELECT Customer.cust_id, Customer.company, Customer.country,;
 Orders.order_id;
 FROM testdata!orders INNER JOIN testdata!customer ;
 ON Orders.cust_id = Customer.cust_id

This query retrieves and combines the records between the two tables that match the join condition. The condition specifies that the records must have the same value in the cust_id field.

An inner join typically answers one basic question. In this query, the question is what orders did each customer place? If a customer has a record in the database but has not placed an order, the record does not appear in the results because it is not part of the subset that matches the join condition.

You can change the results of the query by specifying filters, a sort order, group, or other miscellaneous options for the query.

See Also

Other Resources

Views and Queries Solution Samples
Solution Samples


Select Records from Both Inner and Outer Joins Sample

Visual FoxPro 9.0 Samples
Select Records from Both Inner and Outer Joins Sample
See Also

File: ...\Samples\Data\Comboj.qpr

The query, COMBOJ, uses the testdata database, and combines information from the tables, customer, orders, and orditems. Each result record has fields for the company from the customer table, the order_date from the orders table, and the line_no from the orditems table as specified in the SELECT clause of the SELECT-SQL statement.

Copy Code
SELECT Customer.company, Orders.order_id, Orditems.line_no;
 FROM testdata!customer LEFT OUTER JOIN testdata!orders;
    INNER JOIN testdata!orditems ;
   ON Orders.order_id = Orditems.order_id ;
   ON Customer.cust_id = Orders.cust_id

The order in which the tables are joined determines the order in which the join conditions are evaluated. In this query, the join between orders and orditems is evaluated first and produces a subset of records that meets the join condition. Because of the inner join, the subset of records has only records from both tables that match the condition. This subset of records is matched to the records in the customer table. Because of the outer join between customer and orders, any customers not having orders also appear in the results and have the value NULL.

You can change the results of the query by specifying filters, a sort order, group, or other miscellaneous options for the query.

See Also

Other Resources

Views and Queries Solution Samples
Solution Samples


Select the 10 Worst-Selling Products Sample

Visual FoxPro 9.0 Samples
Select the 10 Worst-Selling Products Sample
See Also

File: ...\Samples\Data\Worstten.qpr

This query displays the 10 worst-selling products based on sales recorded in the Order Items table. The query uses the TOP n feature of the SELECT statement, and, because the default order is from smallest to largest, ordering by the sum of price and quantity returns the 10 lowest values.

Copy Code
SELECT TOP 10 Products.prod_name,;
  SUM(Orditems.unit_price*Orditems.quantity);
 FROM testdata!products INNER JOIN testdata!orditems ;
   ON Products.product_id = Orditems.product_id;
 GROUP BY Products.prod_name;
 ORDER BY 2

See Also

Other Resources

Views and Queries Solution Samples
Select the Top 10 Best-Selling Products Sample
Solution Samples
Visual FoxPro Foundation Classes A-Z


Select the Top 10 Best-Selling Products Sample

Visual FoxPro 9.0 Samples
Select the Top 10 Best-Selling Products Sample
See Also

File: ...\Samples\Data\Topten.qpr

This query displays the top 10 best-selling products based on sales recorded in the Order Items table. The query uses the TOP n feature of the SELECT statement. Because the order is set to DESCENDING, ordering by the sum of price and quantity returns the 10 highest values.

Copy Code
SELECT TOP 10 Products.prod_name,;
  SUM( Orditems.unit_price*  Orditems.quantity);
 FROM testdata!products INNER JOIN testdata!orditems ;
   ON Products.product_id = Orditems.product_id;
 GROUP BY Products.prod_name;
 ORDER BY 2 DESC

See Also

Other Resources

Views and Queries Solution Samples
Select the 10 Worst-Selling Products Sample
Solution Samples
Visual FoxPro Foundation Classes A-Z


Windows API Solution Samples

Visual FoxPro 9.0 Samples
Windows API Solution Samples

These Solution samples illustrate application development tasks you can perform with the Windows API.

In This Section

Get Application Information from the Windows Registry Sample

Illustrates how to obtain Windows registry information about other applications by using Visual FoxPro language.
Get Version Information Sample

Illustrates how to display the version information from a .dll or .exe file.
Play Multimedia Files Using MCI Commands Sample

Illustrates how to use the Media Control Interface (MCI) to play multimedia files.
Read and Write Visual FoxPro Registry Values Sample

Illustrates how to obtain Visual FoxPro settings from the Windows registry by using Visual FoxPro language.
Read ODBC Registry Values Sample

Illustrates how to obtain ODBC driver and data source information from the Windows registry by using Visual FoxPro language.
Use API Functions that Require a STRUCT Sample

Illustrates how to call the Windows API function GetSystemTime to fill in a structure of WORD values with system time information.
Use API Functions That Require Pointers to Arrays Sample

Illustrates how to call two Windows API functions to retrieve and reset system color settings using pointers to arrays.
View Type Library Information Sample

Illustrates how to use the TypeLib class to read Type Library information from any .dll, .exe, or .tlb file.

Reference

Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Visual FoxPro Foundation Classes A-Z

Describes Visual FoxPro Foundation classes you can use for rapid application development.
Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.

Related Sections

Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Server Samples

Contains samples that illustrate Automation Servers.
Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Walkthroughs

Provides step-by-step instructions for common scenarios, making them a good place to begin learning about the various features of Visual FoxPro.


Get Application Information from the Windows Registry Sample

Visual FoxPro 9.0 Samples
Get Application Information from the Windows Registry Sample
See Also

File: ...\Samples\Solution\WINAPI\Regfile.scx

This sample shows how to access the Windows registry using the native Visual FoxPro DECLARE-DLL command. The Windows API provides a number of functions you can use to access, read and write to the registry. The Registry.prg class library in ...\Samples\Classes contains a complete set of these functions you can use in your applications.

In this specific sample, you can use registry functions to check for the existence of a particular application. For example, you might want to distribute an application, which relies on using Excel to automate the creation of a Pivot Table. The registry contains the location, version, and other information about a particular application.

See Also

Other Resources

Windows API Solution Samples
Registry Access
Application Registry
Solution Samples
Visual FoxPro Foundation Classes A-Z


Get Version Information Sample

Visual FoxPro 9.0 Samples
Get Version Information Sample
See Also

File: ...\Samples\Solution\WINAPI\Getver.scx

This sample makes it possible for you to display version information from a .dll or .exe.

A new function called GetFileVersion( ) has been added to Foxtool.fll ,which makes it possible for you to obtain version information on a file. The following code illustrates how you can call the function. See Tools\Foxtools.hlp for details on the specific array elements.

Copy Code
SET LIBRARY TO FoxTools ADDITIVE
DIMENSION aFileVer[12]
nRetVal = GetFileVersion(GetFile("EXE"),@aFileVer)
IF nRetVal = 0
   DISPLAY MEMO LIKE aFileVer
ENDIF
SET LIBRARY TO
Note:
Visual FoxPro now makes it possible for you to add File Version information to EXE and DLL files at build time. This version information is stored in a file resource and can be accessed using the Windows Explorer. EXE files created in Visual FoxPro 3.0 will not have a file version resource.

See Also

Other Resources

Windows API Solution Samples
File Version
Solution Samples
Visual FoxPro Foundation Classes A-Z


Play Multimedia Files Using MCI Commands Sample

Visual FoxPro 9.0 Samples
Play Multimedia Files Using MCI Commands Sample
See Also

File: ...\Samples\Solution\Forms\Mci_play.scx

This sample form uses the Media Control Interface (MCI) to play multimedia files and can play any visual or non-visual media that is installed on your system. However, the GETFILE( ) function prompts for the most common media files of .avi, .wav, .mov, and .mid. To choose another file, select All Files and choose the desired file. To locate documentation for the MCI commands, see the MSDN Library.

The following three Windows API functions are declared in the Init event of the form:

  • mciSendString

  • mciGetErrorString

  • SetWindowPos

The DoMCI method of the form executes an MCI command that is passed in as a parameter.

Classes

You can open the form to see all the code necessary to run multimedia files, but the functionality has also been extracted into classes that you can easily incorporate into your own applications.

VideoFrame Class

The VideoFrame class in the Visual FoxPro ...\Samples\Classes\Samples.vcx class library can be used to play a visual multimedia file, such as a Video for Windows file. The class makes it possible for you to position and size the video to be played, and then provides built-in methods to easily play the media file.

For an example of using this class, see Video.scx in the Visual FoxPro ...\Samples\Solution\Forms directory.

Property | Description
AutoOpen | Specifies whether the video file should automatically open and display when the object is instantiated. The default value is true (.T.).
AutoPlay | Specifies whether the video file should automatically play when it is opened. The default value is true (.T.).
AutoRepeat | Specifies whether the video file will loop the video. Setting this to .T. will cause the video to play continuously. The default value is false (.F.).
ControlSource | Specifies a Field that contains the video file reference. If empty, the class expects a static file name to be in the VideoFile property.
MCIalias | Specifies the alias to be used by MCI. If left empty, the alias defaults to the Name property of the class. Normally this can be left empty, but if the user wants to play the same video file twice at the same time, a different alias would need to be specified for each.
VideoFile | Holds the name of a video file to play, for example: "D:\...\Samples\Solution\FORMS\FOX.AVI"

Method | Description
CloseVideo | Closes the video file and releases all resources associated with it.
DoMCI | Called by the other methods to execute MCI commands. It also can be called by a user to execute a specific MCI command.
OpenVideo | Opens the video file and shows the first frame.
PauseVideo | Pauses a playing video. The video can be restarted by using the PlayVideo method.
PlayVideo | Plays the video file. The video file must be opened in the OpenVideo method before it can be played.
SetPosition | Makes it possible for the user to specify the position of the media file. It can be executed at any time after the video file has been opened. Valid values are "Start", "End", or a specific millisecond into the video.

Sound Player Class

This class is also contained in the ...\Samples\Classes\Samples.vcx class library. It can be used to play a non-visual multimedia file, such as a waveaudio file. The class makes it possible for you to specify the file to be played, and then provides built-in methods to easily play the media file.

Property | Description
AutoOpen | Specifies whether the sound file should be automatically opened and displayed when the object is instantiated. The default value is true (.T.).
AutoPlay | Specifies whether the sound file should be automatically played when it is opened. The default value is true (.T.).
AutoRepeat | Specifies whether the sound file plays continuously. The default value is false (.F.).
ControlSource | Specifies the column that contains the sound file reference. If empty, the class expects a static file name to be in the SoundFile property.
MCIAlias | Specifies the alias to be used by MCI. If left empty, the alias defaults to the Name property of the class. Normally this can be left empty, but if the user wants to play the same sound file twice at the same time, a different alias would need to be specified for each.
SoundFile | Holds the name of a sound file to play, for example: "C:\WINDOWS\CHIMES.WAV"

Method | Description
OpenSound | Opens the sound file.
PlaySound | Plays the sound file. The file must be opened with the OpenSound method before it can be played.
PauseSound | Pauses the playing of a sound file. Play can be contiued by calling the PlaySound method.
SetPosition | Makes it possible for the user to specify the position of the media file. It can be executed at any time after the file has been opened. Valid values are "Start", "End", or a specific millisecond into the sound.
CloseSound | Closes the sound file and releases all resources associated with it.

See Also

Other Resources

Windows API Solution Samples
Solution Samples
Visual FoxPro Foundation Classes A-Z


Read and Write Visual FoxPro Registry Values Sample

Visual FoxPro 9.0 Samples
Read and Write Visual FoxPro Registry Values Sample
See Also

File: ...\Samples\Solution\WINAPI\Regfox.scx

This sample shows how to access the Windows Registry using the native Visual FoxPro DECLARE-DLL command. The Windows API provides a number of functions you can use to access, read and write to the registry. The Registry.prg class library in ...\Samples\Classes contains a class definition that exposes these functions as methods that you can call in your applications.

The contents of the Visual FoxPro Options dialog, Field Mapping settings, and Label definitions (to name a few) are stored in the Registry. Since many of these settings are not available using SET functions, you can use Registry functions to access these values. The following code populates an array of all the settings in the Options dialog:

Copy Code
regfile = HOME(2)+"classes\registry.prg"
SET PROCEDURE TO (m.regfile) ADDITIVE
oReg = CreateObject("FoxReg")

DIMENSION aFoxOptions[1,2]
m.nErrNum = oReg.EnumFoxOptions(@aFoxOptions)

The following code calls the SetFoxOption method of the FoxReg class (defined in Registry.prg) to set TALK OFF in the registry:

Copy Code
regfile = HOME(2)+"classes\registry.prg"
SET PROCEDURE TO (m.regfile) ADDITIVE
oReg = CreateObject("FoxReg")

m.nErrNum = oReg.SetFoxOption("TALK","OFF")

See Also

Other Resources

Windows API Solution Samples
Get Application Information from the Windows Registry
Registry Access
Application Registry
Solution Samples
Visual FoxPro Foundation Classes A-Z


Read ODBC Registry Values Sample

Visual FoxPro 9.0 Samples
Read ODBC Registry Values Sample
See Also

File: ...\Samples\Solution\WINAPI\Regodbc.scx

This sample shows how to access the Windows Registry using the native Visual FoxPro DECLARE-DLL command. The Windows API provides a number of functions you can use to access, read and write to the registry. The Registry.prg class library in ...\Samples\Classes contains a class definition that exposes these functions as methods that you can call in your applications.

The Registry contains a listing of all installed ODBC drivers and data sources. If your application relies on using ODBC, then you might want to perform a Registry check to see if a particular driver or data source is installed. This sample shows how to query for ODBC information.

Copy Code
LOCAL oReg,regfile,nErrNum,lDrivers
PUBLIC aODBCData

regfile = HOME(2)+"classes\registry.prg"
SET PROCEDURE TO (m.regfile) ADDITIVE

oReg = CreateObject("ODBCReg")

DIMENSION aODBCData[1]
m.nErrNum = oReg.GetODBCDrvrs(@aODBCData)

See Also

Other Resources

Windows API Solution Samples
Registry Access
ODBC Registry
Solution Samples
Visual FoxPro Foundation Classes A-Z


Use API Functions that Require a STRUCT Sample

Visual FoxPro 9.0 Samples
Use API Functions that Require a STRUCT Sample
See Also

File: ...\Samples\Solution\Winapi\Systime.scx

This example illustrates calling the Windows API function GetSystemTime. GetSystemTime fills in a structure of WORD (16-bit unsigned integer) values with system time information.

C Function Declaration and Struct Definition

Copy Code
VOID GetSystemTime(
    LPSYSTEMTIME lpSystemTime    // address of system time structure
   );

This is the struct definition:

Copy Code
typedef struct _SYSTEMTIME {
    WORD wYear;
    WORD wMonth;
    WORD wDayOfWeek;
    WORD wDay;
    WORD wHour;
    WORD wMinute;
    WORD wSecond;
    WORD wMilliseconds;
} SYSTEMTIME;

Calling the Function in Visual FoxPro

The Visual FoxPro code passes GetSystemTime, a reference to a character variable, which is filled in with the WORD values.

Copy Code
* Visual FoxPro Code: cmdSystemTime.Click
DECLARE INTEGER GetSystemTime IN win32api STRING @
cBuff=SPACE(40)

GetSystemTime(@cBuff)

To retrieve the information from the character variable, cBuff, the following code converts 8-bit ASCII characters for year and month in the variable into 16-bit equivalents.

Copy Code
THIS.Parent.lblYear.Caption = ALLTRIM(STR(ASC(SUBSTR(cBuff,2)) * 256 + ASC(SUBSTR(cBuff,1))))

THIS.Parent.lblMonth.Caption = MONTH_LOC + ALLTRIM(STR(ASC(SUBSTR(cBuff,4)) * 256 + ASC(SUBSTR(cBuff,3))))

See Also

Other Resources

Windows API Solution Samples
Use API Functions That Require Pointers to Arrays
Solution Samples
Visual FoxPro Foundation Classes A-Z


Use API Functions That Require Pointers to Arrays Sample

Visual FoxPro 9.0 Samples
Use API Functions That Require Pointers to Arrays Sample
See Also

File: ...\Samples\Solution\Winapi\Syscolor.scx

This example uses two Windows API functions to first get the system color settings (GetSysColor) and then to reset the system colors to new values (SetSysColors). Two of the three arguments required by SetSysColors are pointers to native C arrays.

GetSysColor

The GetSysColor function accepts an integer parameter, a number between 0 and 18, and returns a DWORD (32-bit unsigned integer) indicating the current color setting.

Copy Code
DWORD GetSysColor(
    int nIndex    // display element
   );

nIndex is a value representing an area of the interface, as defined in the following list:

Copy Code
#define COLOR_SCROLLBAR         0
#define COLOR_BACKGROUND        1
#define COLOR_ACTIVECAPTION     2
#define COLOR_INACTIVECAPTION   3
#define COLOR_MENU              4
#define COLOR_WINDOW            5
#define COLOR_WINDOWFRAME       6
#define COLOR_MENUTEXT          7
#define COLOR_WINDOWTEXT        8
#define COLOR_CAPTIONTEXT       9
#define COLOR_ACTIVEBORDER      10
#define COLOR_INACTIVEBORDER    11
#define COLOR_APPWORKSPACE      12
#define COLOR_HIGHLIGHT         13
#define COLOR_HIGHLIGHTTEXT     14
#define COLOR_BTNFACE           15
#define COLOR_BTNSHADOW         16
#define COLOR_GRAYTEXT          17
#define COLOR_BTNTEXT           18
#define COLOR_INACTIVECAPTIONTEXT 19
#define COLOR_BTNHIGHLIGHT      20

#if(WINVER >= 0x0400)
#define COLOR_3DDKSHADOW        21
#define COLOR_3DLIGHT           22
#define COLOR_INFOTEXT          23
#define COLOR_INFOBK            24

#define COLOR_DESKTOP           COLOR_BACKGROUND
#define COLOR_3DFACE            COLOR_BTNFACE
#define COLOR_3DSHADOW          COLOR_BTNSHADOW
#define COLOR_3DHIGHLIGHT       COLOR_BTNHIGHLIGHT
#define COLOR_3DHILIGHT         COLOR_BTNHIGHLIGHT
#define COLOR_BTNHILIGHT        COLOR_BTNHIGHLIGHT
#endif /* WINVER >= 0x0400 */

SetSysColors

The SetSysColors function requires three arguments: the number of elements in two arrays and the addresses of the two arrays.

Copy Code
BOOL WINAPI SetSysColors(
    int cElements,                  // number of elements to change
    CONST INT *lpaElements,         // address of array of elements
    CONST COLORREF *lpaRgbValues    // address of array of RGB values
   );

Calling SetSysColors in Visual FoxPro

The following code is extracted from cmdSetSysColors.Click:

Copy Code
DECLARE INTEGER SetSysColors IN win32api INTEGER, STRING, STRING

Construct the elements of the first array in a character variable.

Copy Code
cElements = ""
FOR i = 0 TO 18
   cElements = cElements + THISFORM.DecToHex(i)
ENDFOR

Construct the elements of the second array in a character variable. The cursor that is scanned was filled with GetSysColor values in the Init of the form.

Copy Code
cColors = ""
SCAN
   cColors = cColors + THISFORM.DecToHex(INT(color))
ENDSCAN

=SetSysColors(18,cElements,cColors)

See Also

Other Resources

Windows API Solution Samples
Use API Functions that Require a STRUCT
Solution Samples
Visual FoxPro Foundation Classes A-Z


View Type Library Information Sample

Visual FoxPro 9.0 Samples
View Type Library Information Sample
See Also

File: ...\Samples\Solution\Winapi\Typelib.scx

The TYPELIB sample uses a Visual FoxPro class named Typelib, which is stored in ...\Samples\Classes\Typelib.vcx. This container class has an ActiveX control that contains a number of methods to read Type Library information from any .dll, .exe, or .tlb file.

The Typelib wrapper class saves you time by handling much of the work for you. There is a method called ExportTypeLib in this class, which exports the contents of a specified Type Library to a text File.

Copy Code
THISFORM.typelib1.TypeLibName = THISFORM.txtFileName.Value
THISFORM.typelib1.ExportTypeLib( )

If you take a look at the generated text file, you will notice that a Type Library can consist of multiple Type Infos. Each Type Info represents a specific class. When you generate a new EXE or DLL from a project using Visual FoxPro, each class in the project, which is marked as OLEPUBLIC will generate a separate Custom OLE Server.

Note:
You only have a single .exe/.dll file, however, this file can contain multiple servers (one for each OLEPUBLIC class). And Visual FoxPro generates a single TLB file for the project. This Type Library file contains a separate Type Info for each OLEPUBLIC class.

Within each Type Info (OLEPUBLIC class), there are also function descriptions. These represent all of the properties and methods of a class. For methods, the Type Library contains both parameter and return types. Some of the possible types are Boolean, string, and variant. Because Visual FoxPro does not strong type memory variables, many of the types used in your custom methods will be variant.

If you take a close look at the functions exported, you will notice double entries for many of the properties. This is because users can set or get the value of this property. And some languages such as Visual Basic make it possible for you to have code executed when one of these properties is accessed or assigned. Hence, the Type Library will represent a single property with 2 entries. If only a single entry exists, then that property is read-only. Properties and methods, which are marked as Hidden or Protected will not appear in the Type Library.

See Also

Other Resources

Windows API Solution Samples
Type Library
Solution Samples
Visual FoxPro Foundation Classes A-Z


Miscellaneous Solution Samples

Visual FoxPro 9.0 Samples
Miscellaneous Solution Samples

These Solution samples illustrate other tasks you can perform with Visual FoxPro.

In This Section

Control MSN Messenger Sample

Demonstrates how to perform operations with MSN Messenger using the Messenger API and Windows Scripting Host.
Track Activities in a Project Sample

Demonstrates how project hooks can be used to track project activity, including adding, deleting, and modifying files.

Related Sections

Solution Samples

Contains samples that demonstrate particular features of Visual FoxPro and can be run independently.
Sample Class Libraries

Contains sample class libraries that provide encapsulated functionality you can add to your applications.
Foundation Class Samples

Contains samples that illustrate use of the Visual FoxPro Foundation classes.
Walkthroughs

Contains step-by-step instructions for common scenarios.


Control MSN Messenger Sample

Visual FoxPro 9.0 Samples
Control MSN Messenger Sample
See Also

File: ...\Samples\Solution\Toledo\Messenger.scx

This sample demonstrates how to perform operations with MSN Messenger using the Messenger API and Windows Scripting Host. You can use these methods to automate sending messages, e-mail, and files to any MSN user from automated processes. Additionally, if users have mobile messaging, alerts can be sent to their pagers.

This sample is not meant as an alternate user interface to MSN Messenger. For information on the MSN Messenger APIs, see MSDN online at http://msdn.microsoft.com.

MSN Messenger API

This sample demonstrates the Messenger APIs that you can access through the Component Object Model (COM). In this sample, the Messenger object is instantiated in the Init event:

Copy Code
ThisForm.oMessenger = CREATEOBJECT("Messenger.UIAutomation.1")

The Init event also declares some Windows APIs used to bring Messenger windows to the foreground so that you can automate composing e-mail messages and sending files.

Copy Code
DECLARE LONG SetForegroundWindow IN WIN32API LONG
DECLARE INTEGER FindWindow IN WIN32API STRING @ cClass, STRING @ cTitle
DECLARE LONG CloseWindow IN WIN32API LONG
DECLARE Sleep IN WIN32API long

After creating an instance of a Messenger object, you can call methods such as AutoSignin, InstantMessage, OpenInbox, SendFile, SendMail, and SignOut. The SendFile and SendEmail methods also use the Windows APIs to bring Messenger windows to the foreground so that the Windows Scripting Host Shell object can be used to send keystrokes to those windows.

Windows Scripting Host

This sample illustrates how to use Windows Scripting Host to send keystrokes to the activated windows. You can then fill out forms automatically for sending e-mail and files. Windows Scripting Host is required because the MSN Messenger API does not have this functionality. The Windows Scripting Host Shell object is instantiated in the Init event of the sample form:

Copy Code
ThisForm.oWsh = CREATEOBJECT("wscript.Shell")

To send keystrokes to the active window, the SendKeys method of the sample form calls the SendKeys( ) function of the Windows Scripting Host Shell object and automates the composition of e-mail and sending of files.

Copy Code
ThisForm.oWsh.SendKeys(tcKeys)

See Also

Other Resources

Solution Samples
Init Event


Track Activities in a Project Sample

Visual FoxPro 9.0 Samples
Track Activities in a Project Sample
See Also

File: ...\Samples\Solution\Tahoe\Acttrack.scx

This sample makes it possible for you to open a project and then manipulate the project in any manner. Any changes you make to the project are stored in a table. When you close the project, you can view the changes you made to the project in a browse window.

For more information about how the sample works, open the form so you can examine the code for the sample.

This sample contains the following classes.

Class | Library | Description
activity_tracker | project_hook.vcx | Creates a project and a log to document project activity.

The event procedures in the ProjectHook class library, Project_hook.vcx, contain most of the code that is executed when project events occur. The ProjectHook class library is assigned to the project in the sample. Project_hook.vcx is located in the ...\Samples\Solution\Tahoe directory.

See Also

Other Resources

Solution Samples
Miscellaneous Solution Samples
Retrieve Project Location and Name Sample


Foundation Class Samples

Visual FoxPro 9.0 Samples
Foundation Class Samples

The Visual FoxPro foundation classes provide rapid application development with as little coding as possible and are supplied with the Component Gallery. The classes work immediately by addressing the following needs:

  • Provide common database development tools and structures.

  • Provide fast, extensible generic components.

  • Provide components that enhance and ease Web page development.

  • Provide effective wrappers for system API functions.

  • Provide an extensive set of functions to a wide range of Visual FoxPro users.

In This Section

Guidelines for Using Visual FoxPro Foundation Classes

Provides an overview of the situations and solutions in which to use foundation classes.
Add a Data-Bound Calendar Sample

Demonstrates the use of a data-bound ActiveX calendar control to enhance data entry in date fields in forms.
Add Data Lookup Combo Boxes Sample

Performs a lookup of values in a field to populate a combo box.
Add Data Querying to Forms Sample

Demonstrates options that enable you to navigate within a table and locate data.
Add Data Sorting and Filtering to Forms Sample

Demonstrates the use of advanced querying options in a form as well as options for performing an ascending or descending order sort of data.
Add Encryption to Applications Sample

Demonstrates how you can add encryptions to your applications.
Add Miscellaneous Form Buttons Sample

Shows the use of command buttons in applications to perform such tasks as starting and stopping an application, displaying a form, or previewing a report.
Add Navigation to Forms Sample

Demonstrates various options for providing data navigation in forms.
Add Shortcut Menus to Objects Sample

Demonstrates the use of shortcut menus on a form, including using separators, bold text, checked commands, and cascading menus.
Add Web Hyperlinks to a Form Sample

Demonstrates adding hyperlink functionality and launching a Web browser from various controls.
Application Error Handling Sample

Demonstrates application error handling and recording details of the application state.
Create a Visual FoxPro Web Browser Sample

Demonstrates providing a Web browser control in a Visual FoxPro form to display data in HTML.
Create Record Bound Graphs Sample

Shows the use of data from fields to generate graphs on a record-by-record basis.
Create Toolbar Control Effects Sample

Demonstrates various effects you can achieve on toolbar controls when the mouse is moved over them.
Display Data Reporting Output Options Sample

Demonstrates a simple text editor and provides a variety of report output options.
Expanding the SetAll Method Sample

Uses the SetAllx Foundation Class to allow for programmatic setting of object properties based on extended criteria not available with the native SetAll( ) method.
Generate HTML Sample

Shows how you can use HTML classes to create Web pages from your data, forms, and reports.
Handle Application Environment Tasks Sample

Demonstrates utilities for saving and restoring critical state settings and handling common application operations.
Handle Common Windowing Tasks Sample

Demonstrates arranging and cascading various forms on the desktop.
Handle Data Conflicts Sample

Demonstrates resolving data conflicts, allowing the user to update data in the form.
Pool Manager Sample

Demonstrates how to use the Pool Manager class, which manages a pool or collection of objects from a class and is useful when you need to use objects repeatedly for a short amount of time.
Retrieve Project Location and Name Sample

Demonstrates providing the user with a place to enter a file and directory location, primarily to create new projects.
Run Word, Excel, and Graph Automation Sample

Demonstrates adding automation routines to an application to create Microsoft Excel pivot tables, Microsoft Word mail merge documents, Visual FoxPro cross-tabs, and Graph charts.
Search Text Using Regular Expressions Sample

Demonstrates the use of regular expression searching in applications.
Set VFP Shell Open Commands Sample

Illustrates how to change the Shell Open settings for various file types.
Tips for the Windows 2000 Logo Program Sample

Shows several Foundation Classes that provide information that might be of use in making applications Windows 2000 Logo compliant.
Use an Enhanced Openfile Dialog Box Sample

Illustrates how to use the Common File Dialog foundation class to create the look and feel of Windows file dialog boxes.
Use Array Handling Sample

Demonstrates useful methods for expanding array-handling functionality. This sample uses ACOLSCAN( ) to search a specific column in an array.
Use an Enhanced Openfile Dialog Box Sample

Shows use of the Common File Dialog Foundation Class.
Use Common Application Dialog Boxes Sample

Shows how you can use dialog boxes in applications for common operations such as user logons, splash screens, about boxes, and so on.
Use Edit Buttons for a Complex Form Sample

Demonstrates using buttons for editing forms involving one-to-many relationships.
Use Edit Buttons for a Simple Form Sample

Demonstrates the use of simple data edit buttons for editing simple forms with a single table.
Use Mover List Boxes for Selecting Data Sample

Demonstrates using mover list boxes to load tables and fields from a data source and to handle data sorting.
Use Progress Thermometer Sample

Demonstrates the use of a standard display to show progress in applications.
Working with Microsoft Agent Sample

Demonstrates adding animated characters to applications using Microsoft Agent technologyy.

Related Sections

Visual FoxPro Foundation Classes A-Z

Lists the foundation classes in alphabetical order. Many of these foundation classes are used in the Solutions sample located in the ...\Samples\Solution folder.
Samples

Provides class library, server, solutions, and foundation class code samples that you can use for experimenting and getting to know particular features in Visual FoxPro.


Guidelines for Using Visual FoxPro Foundation Classes

Visual FoxPro 9.0 Language Reference
Guidelines for Using Visual FoxPro Foundation Classes
See Also

The Visual FoxPro visual class (.vcx) libraries located in the Visual FoxPro ...\FFC directory contain a variety of foundation classes for enhancing your Visual FoxPro applications with little or no programming. You can freely distribute the foundation classes with your applications.

You can browse these foundation classes in the Component Gallery. The Component Gallery provides a quick and easy way to learn more about the properties, events, and methods of each of the foundation classes. For more information about the Component Gallery, see Using the Component Gallery.

You can also open a foundation class in the Class Designer or Class Browser to see its structure and code. This is a great way to learn how the foundation class works as well as offering excellent insights into programming with Visual FoxPro.

The following guidelines provide information about how you can add the Visual FoxPro foundation classes to your applications.

Class Types

Before you can add a foundation class to your application, you need to know the Visual FoxPro base class of the foundation class.

Tip:
To see the base class from the Component Gallery, right-click the foundation class in the Component Gallery, click Properties on the shortcut menu, then the Class Item tab. The base class name appears in the Class name box.

Certain foundation classes can be used only as visual objects on forms, while others are non-visual and can be run programmatically without being placed on a form. To determine if the foundation class can be added to a form or run programmatically in your application, see Visual FoxPro Foundation Classes A-Z, which contains Help topics for each foundation class that indicate the base class for each foundation class.

The following table lists Visual FoxPro base classes and how they can be added to your applications.

Category A – base classes that can be dropped onto a form | Category B – base classes that can be dropped onto a form or run programmatically in your application | Category C – base classes that can only be run programmatically in your application
Checkbox | Custom | Form
Combobox | Container | Formset
Commandbutton | Timer | Toolbar
Commandgroup | ProjectHook |
Editbox |  |
Grid |  |
Hyperlink |  |
Image |  |
Label |  |
Line |  |
Listbox |  |
OLE Control |  |
Optionbutton |  |
Optiongroup |  |
Shape |  |
Spinner |  |
Textbox |  |

Adding Foundation Classes to Forms

You will most often add foundation classes to forms. You can drag and drop foundation classes from the Component Gallery, Class Browser, Project Manager, and the Forms Control toolbar onto forms.

Note:
You can select a foundation class that you have added to a form and then choose Class Browser from the Tools menu to display more information about the foundation class.

Component Gallery The Component Gallery provides the easiest way to add foundation classes to a form. For foundation classes with Category A and B base classes, you can drag the foundation class from the Component Gallery and then drop it on a form. You can also right-click a foundation class in the Component Gallery to display a shortcut menu, and then choose Add to Form to add the foundation class to the form.

Some of the foundation classes have associated builders that are automatically launched to prompt you for more information needed by the foundation class.

Class Browser You can drag foundation classes with Category A and B base classes directly from the Class Browser to a form by using the drag icon in the upper left corner of the Class Browser. Select the foundation class in the Class Browser, click the icon for the foundation class in the upper left corner of the Class Browser, and then drag the icon over the form. Release the mouse button over the form where you would like the foundation class to appear on the form.

Foundation classes dragged from the Class Browser to a form do not launch the associated builder. However, you can launch the builder by after the foundation class has been dropped on the form. Select the foundation class on the form, and then right-click to display the shortcut menu. Choose Builder from the shortcut menu to launch the builder.

Project Manager Foundation classes with Category A and B base classes can be dragged from the Project Manager and dropped on a form.

Foundation classes dragged from the Project Manager to a form do not launch the associated builder. However, you can launch the builder by after the foundation class has been dropped on the form. Select the foundation class, and then right-click to display the shortcut menu. Choose Builder from the shortcut menu to launch the builder.

Form Controls toolbar Foundation classes with Category A and B base classes added to the Form Controls toolbar can be added to a form.

If the Builder Lock is not on, foundation classes dropped from the Form Controls toolbar may launch an associated builder. If the Build Lock is on, you can launch the builder by after the foundation class has been added to the form. Select the foundation class on the form, and then right-click to display the shortcut menu. Choose Builder from the shortcut menu to launch the builder.

Adding Foundation Classes to Projects

When a form containing foundation classes is added to a Visual FoxPro project, the Project Manager automatically adds the visual class libraries containing the foundation classes to the project. However, there are other cases where you may need to add foundation classes to a project. For example, your application may run a Category C foundation class, so the foundation class must be added to the application's project.

Foundation classes can be added to a project from the Component Gallery, by dragging the .vcx visual class library containing the foundation classes from the Windows Explorer, or by choosing the Add button in the Project Manager.

Adding Foundation Classes from the Component Gallery

You can drag a foundation class from the Component Gallery to a project, or you can right-click the foundation class in the Component Gallery to display a shortcut menu, and then choose Add to Project to add the foundation class to the project. When you add a foundation class to a project, the Add Class to Project dialog box is displayed, prompting you with the following options:

Add class to project

Choose this option to add the foundation class and its .vcx class library to the project. Again, this is done automatically for classes dropped onto a form (Categories A and B). For certain Category B and C classes where you plan to call them programmatically from within your application, you will want to choose this option.
Create a new class from selected class

Choose this option to create a new subclass from the foundation class you want to add to the project. This option makes it possible for you to enhance the functionality of the original foundation class, usually by adding additional program code.
Create a new form from selected class

Choose this option for foundation classes with a Form base class (for example, the foundation classes in _dialogs.vcx). This option makes it possible for you to create a new form from the foundation class and enhance the functionality of the original foundation class.

Adding Foundation Classes from the Windows Explorer

A foundation class can be added to a project by dragging the .vcx visual class library containing the foundation class from the Window Explorer to the Project Manager. The visual class library is added to the Class Libraries item in the Project Manager.

Adding Foundation Classes from within the Project Manager

A foundation class can be added to a project by selecting the Classes tab and then choosing the Add button. Select the class library from the \Ffc\ folder that contains the foundation class to add to the project.

Incorporating Classes into your Application

In many situations, most foundation classes do not require additional programming to work with your application. However, you may need to provide additional program code for certain foundation classes (those of Category B and Category C non-visual base classes).

Non-Visual Foundation Classes

For example, foundation classes are often based on the Category B Custom class, and these require additional programming. These non-visual classes often perform common tasks such as checking information in the Windows registry, handling environment settings, managing application errors, and utilizing Automation with other applications, such as performing mail merge with Microsoft Word.

You can drop these non-visual classes onto a form, but you will need to do some additional work in order for them to work with your application. In some cases, a builder is launched when you drag a foundation class onto a form.

The following example demonstrates some of the program code typically necessary to use a non-visual foundation class in your application:

  1. Drag the File Version foundation class from the Component Gallery (Foundation Classes\Utilities folder) onto a form.

  2. Add a command button to the form and add the following code to its Click event:

    Copy Code
    WITH THISFORM._FILEVERSION1
   .cFileName = HOME( )+ 'VFP8.EXE'
   .GetVersion( )
   .DisplayVersion( )
ENDWITH
  3. Run the form and click the command button.

You can incorporate a non-visual class in your application without dropping it on a form, as long as you include it in the project used to create the application. The following code illustrates how to executed this same File Version foundation class if the class is not dropped onto a form.

Copy Code
LOCAL oFileVersion
oFileVersion = NewObject('_fileversion', '_utilities.vcx')
WITH oFileVersion
   .cFileName = HOME( )+ 'VFP8.EXE'
   .GetVersion( )
   .DisplayVersion( )
ENDWITH
Note:
This example assumes that the code can locate the _utilities.vcx class library or from an .app file that is built containing _utilities.vcx.

When you use a non-visual foundation class, you need to know how and when the class is used within your application so it can be scoped correctly. If only a single form uses the class, you can just drag the class onto the form. However, if the class is used by many forms or is used globally by the application, the foundation class should have a global scope in the application so it remains accessible throughout the application. A global scope may also improve performance.

Adding Visual Foundation Classes to Applications

You can programmatically add visual foundation classes, such as those containing form base classes, to your application. For example, you can use the following code to display an About dialog box:

Copy Code
LOCAL oAbout
oAbout = NewObject('_aboutbox','_dialogs.vcx')
oAbout.Show( )

To customize the contents of the About dialog box for each application, create a subclass of the About Dialog Box foundation class for each of your applications:

  1. Open the project for your application.

  2. On the Tools menu, click Component Gallery.

  3. In the Component Gallery, expand the Visual FoxPro Catalog node, then the Foundation Classes node, and click Dialogs.

  4. Drag the Aboutbox class to the Project Manager for your application.

  5. In the Add Class to Project dialog box, click Create new form from selected class.

  6. In the Save As dialog box, enter a name for the new form.

    After saving the form, the Form Designer opens and displays the newly created form.

  7. In the Properties window, change the Caption property for the title of the new form for your application. Save and close the form.

  8. Add program code, such as DO FORM FormName, to the procedure that runs the form, such as an About menu item procedure.

    -or-

    From the Foundation Classes\Buttons folder in the Component Gallery, drag the Run Form button class onto the form. A builder launches so you can specify the name of the form to execute.

If you use the Visual FoxPro Application Framework, the Application Builder automatically handles adding forms (both .scx and .vcx form classes). The new Application Wizard or the Component Gallery New Application item installs this framework in the projects they create. The Application Builder interacts directly with the framework and enables you to specify how and where the form is launched.

By using a framework built with the Application Wizard, the Application Builder, and Component Gallery, you have a rich set of tools for creating entire applications with minimal manual coding.

Class Naming Conventions

The Visual FoxPro Foundation classes and their properties and methods use the following naming conventions.

Classes and Class Libraries

Most foundation classes are subclassed from classes in the _base.vcx visual class library, which you can also find in the \Ffc\ folder. The naming conventions for these classes reflect the base class used. For example, a subclass of the Custom class is called _Custom in _base.vcx. All classes use an underscore ( _ ) to preface the name of a class in _base.vcx.

A few class libraries do not contain classes that are subclassed from _base.vcx because these classes are shared with other Visual FoxPro components such as wizards and builders. These classes are contained in class libraries without a preceding underscore, such as Registry.vcx.

Methods and Properties

Methods are often based on an action name such as RunForm. If the name contains several words, for example, RunForm, then capitalization reflects this. Properties are usually prefaced with a single letter characterizing the data type of that particular property. For example, cFileName indicates that the property is of character type. In addition, default values for properties are also set to the appropriate data type. For example, a logical property can be initialized to false (.F.), while a numeric property can be initialized to 0.

Properties of classes that shipped in earlier versions of Visual FoxPro do not strictly adhere to these property-naming conventions, and retain their earlier names to avoid compatibility conflicts with user code referencing these properties.

Enhancing or Modifying FoxPro Foundation Classes

You can enhance or modify the Visual FoxPro foundation classes to meet the needs of your application. However, we recommend that you do not modify the foundation classes themselves. The foundation classes may be periodically updated with new functionality.

Subclassing the Foundation Class

The source code is provided for the foundation classes, so you can subclass any foundation class to override or enhance properties and methods. This choice is common when the behavior of a particular foundation class varies between different applications. One application might use a foundation class directly, while another application uses a subclass of the foundation class.

Updating _base.vcx

If you want to add global changes to the Visual FoxPro foundation classes, you can modify _base.vcx. Since foundation classes are subclassed from _base.vcx, changes to this class library are automatically propagated to the foundation classes. A common set of methods and properties are provided for all the classes in _base.vcx. However, you can alter the classes in _base.vcx if they add desired behavior to your applications (unlike the foundation classes that we recommend that you do not change).

Instead of changing _base.vcx, however, you should redefine the classes in _base.vcx to inherit their behavior from your own custom base classes (rather than from the Visual FoxPro base classes currently used). If you already have a custom class library which subclasses the Visual FoxPro base classes, you can redefine the classes in _base.vcx to inherit from your custom classes so that when components use the _base classes they will inherit from your custom classes too. You can use the Class Browser to redefine the parent class for a particular class.

Note:
If you redefine the classes to inherit from your own custom base classes, you should add DODEFAULT() calls at appropriate locations if you desire that parent class method code be executed.

If you replace the entire _base.vcx class with your own, make sure that you have the same set of named classes; otherwise the foundation classes will have missing links.

See Also

Other Resources

Visual FoxPro Foundation Classes A-Z
Foundation Class Samples
File Version Foundation Class
About Dialog Box Foundation Class
Run Form Button Foundation Class


Add a Data-Bound Calendar Sample

Visual FoxPro 9.0 Samples
Add a Data-Bound Calendar Sample
See Also

File: ...\Samples\Solution\Ffc\Datacal.scx

This sample contains the following classes.

Class | Library | Description
_olecalendar | _datetime.vcx | Displays a calendar that highlights a date, bound to a field in a table.
_nav2buttons | _table.vcx | Displays a pair of navigation buttons.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Add Data Lookup Combo Boxes Sample

Visual FoxPro 9.0 Samples
Add Data Lookup Combo Boxes Sample
See Also

File: ...\Samples\Solution\Ffc\DataLook2.scx

This sample contains the following classes.

Class | Library | Description
_cbodistinctvalues | _dataquery.vcx | Performs a lookup of unique values in the controlsource field to populate a combo box.
_cbolookup | _dataquery.vcx | Performs a lookup of values in a field to populate a combo box.
_nav2buttons | _table.vcx | Displays a pair of buttons that provide GoNext( ) and GoPrevious( ) functions.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Lookup Combobox
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Add Data Querying to Forms Sample

Visual FoxPro 9.0 Samples
Add Data Querying to Forms Sample
See Also

File: ...\Samples\Solution\Ffc\DataQry.scx

This sample contains the following classes.

Class | Library | Description
_findnextbuttons | _table.scx | Provides a Find/Find Next button set for navigating within a table.
_locatebutton | _table2.vcx | Provides a Locate button to display a dialog box for navigating within a table.
_findbutton | _table.vcx | Provides a generic Find button.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Find Button
Locate Button
Add Data Sorting and Filtering to Forms
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Add Data Sorting and Filtering to Forms Sample

Visual FoxPro 9.0 Samples
Add Data Sorting and Filtering to Forms Sample
See Also

File: ...\Samples\Solution\Ffc\DataSort.scx

This sample contains the following classes.

Class | Library | Description
_sortbutton | _table2.vcx | Provides buttons to perform an ascending or descending order sort of data.
_navtoolbarclass | _table2.vcx | Provides data navigation controls on a toolbar.
_navmenu | _table2.vcx | Provides a shortcut menu that can include data navigation options.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Data Navigation Object
Data Navigation Buttons
Add Data Querying to Forms
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Add Encryption to Applications Sample

Visual FoxPro 9.0 Samples
Add Encryption to Applications Sample
See Also

File: ...\Samples\Solution\FFC\Crypto.scx

This sample shows use of the Crypto Foundation Class that extends the Windows Crypto API routines. You can add encryption to text, files, and data in your applications. A variety of encryption styles are shown as well as file signing.

This sample contains the following classes.

Class | Library | Description
_cryptapi | _ crypt.vcx | Foundation class contains extended properties and methods for adding encryption to your applications. It uses the Windows Crypto API routines.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Add Miscellaneous Form Buttons Sample

Visual FoxPro 9.0 Samples
Add Miscellaneous Form Buttons Sample
See Also

File: ...\Samples\Solution\Ffc\Buttons.scx

This sample contains the following classes.

Class | Library | Description
_shellexecute | _environ.vcx | Runs applications other than Visual FoxPro in the Windows shell.
_mailbtn | _miscbtns.vcx | Uses the MAPI ActiveX control to send an e-mail message from a form.
_cmdlaunch | _miscbtns.vcx | Provides a button to launch an application using the Run command.
_cmdok | _miscbtns.vcx | Releases a form and updates any outstanding buffered data.
_cmdcancel | _miscbtns.vcx | Releases a form and discards any outstanding buffered data.
_cmdhelp | _miscbtns.vcx | Provides a button that displays a Help topic.
_cmdrunform | _miscbtns.vcx | Provides a button to run a form.
_cmdrunreport | _miscbtns.vcx | Provides a button to run a report.

This sample demonstrates adding command buttons to your application. The command buttons perform the following functions:

  • Launch an application

  • Open a Web page in the Windows shell

  • Display a form

  • Preview a report

  • Stop a program with OK or Cancel options

  • Display a Help topic

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Run Form Button Foundation Class
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Add Navigation to Forms Sample

Visual FoxPro 9.0 Samples
Add Navigation to Forms Sample
See Also

File: ...\Samples\Solution\Ffc\DataNav.scx

This sample contains the following classes.

Class | Library | Description
_nav2buttons | _table2.vcx | Displays a pair of buttons that provide GoNext( ) and GoPrevious( ) functions.
_nav4buttons | _table2.vcx | Displays two additional buttons that provide GO TOP and GO BOTTOM functions to the _Nav2Button class.
_tablenav | _table.vcx | A non-visual class that provides data navigation to other controls.
_nav2picbuttons | _table2.vcx | Displays a pair of picture buttons that provide GoNext( ) and GoPrevious( ) functions.
_gotobutton | _table2.vcx | Provides a button that displays a Go To dialog box.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Simple Navigation Buttons
Data Navigation Buttons
Add Data Querying to Forms
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Add Shortcut Menus to Objects Sample

Visual FoxPro 9.0 Samples
Add Shortcut Menus to Objects Sample
See Also

File: ...\Samples\Solution\Ffc\NewMenu.scx

This sample contains the following classes.

Class | Library | Description
_shortcutmenu | _menu.vcx | Dynamically creates shortcut menus.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Shortcut Menu Class
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Add Web Hyperlinks to a Form Sample

Visual FoxPro 9.0 Samples
Add Web Hyperlinks to a Form Sample
See Also

File: ...\Samples\Solution\Ffc\HyperLnk.scx

This sample contains the following classes.

Class | Library | Description
_urlcombobox | Internet.vcx | Creates a combo box for specifying and navigating to Web sites.
_hyperlinklabel | Internet.vcx | Provides Hyperlink functionality and launches a Web browser from a label.
_hyperlinkimage | Internet.vcx | Provides Hyperlink functionality and launches a Web browser from an image.
_hyperlinkcommandbutton | Internet.vcx | Provides Hyperlink functionality and launches a Web browser from a button.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Hyperlink Button
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Application Error Handling Sample

Visual FoxPro 9.0 Samples
Application Error Handling Sample
See Also

File: ...\Samples\Solution\Ffc\Error.scx

This sample contains the following classes.

Class | Library | Description
_error | _app.vcx | Provides error handling for both object and procedural code.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Create a Visual FoxPro Web Browser Sample

Visual FoxPro 9.0 Samples
Create a Visual FoxPro Web Browser Sample
See Also

File: ...\Samples\Solution\Ffc\DoHTML.scx

This sample contains the following classes.

Class | Library | Description
_webbrowser4 | _webview.vcx | Provides a Web browser control in a Visual FoxPro form.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Web Browser Control
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Create Record Bound Graphs Sample

Visual FoxPro 9.0 Samples
Create Record Bound Graphs Sample
See Also

File: ...\Samples\Solution\Ffc\GraphRec.scx

This sample contains the following classes.

Class | Library | Description
_graphbyrecord | _utility.vcx | Provides navigation buttons and generates graphs on a record-by-record basis using data from fields.
_nav4buttons | _table2.vcx | Displays two additional buttons that provide GO TOP and GO BOTTOM functions to the _Nav2Button class.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Graph By Record
Data Navigation Buttons
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Create Toolbar Control Effects Sample

Visual FoxPro 9.0 Samples
Create Toolbar Control Effects Sample
See Also

File: ...\Samples\Solution\Ffc\MouseFx.scx

This sample contains the following classes.

Class | Library | Description
_mouseoverfx | _ui.vcx | Highlights a control as the mouse is dragged over it.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Display Controls in a Grid
MouseOver Effects
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Display Data Reporting Output Options Sample

Visual FoxPro 9.0 Samples
Display Data Reporting Output Options Sample
See Also

File: ...\Samples\Solution\Ffc\Output.scx

This sample contains the following classes.

Class | Library | Description
_showtext | _reports.vcx | Provides a simple text editor in a dialog box that also contains buttons to format or save text, and to close the editor.
_outputdialog | _reports.vcx | Displays a dialog box that prompts the user for a report output option.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Expanding the SetAll Method Sample

Visual FoxPro 9.0 Samples
Expanding the SetAll Method Sample
See Also

File: ...\Samples\Solution\FFC\Setallx.scx

This sample uses the SetAllx Foundation Class to allow for programmatic setting of object properties based on extended criteria not available with the native SetAll( ) method.

This sample contains the following classes

Class | Library | Description
_setallx | _setallx.vcx | Provides wrapper method called SetAllx that adds expanded SetAll capabilities.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Generate HTML Sample

Visual FoxPro 9.0 Samples
Generate HTML Sample
See Also

File: ...\Samples\Solution\Ffc\DoHTML.scx

This sample contains the following classes.

Class | Library | Description
_webform | Webview.vcx | Provides a Visual FoxPro form containing a Web browser control to display HTML text.
_resizable | Controls.vcx | Causes objects dropped onto a form to resize and move with the Form's resize event.
_dbf2html | Internet.vcx | Converts a Visual FoxPro table (.dbf) to HTML.
_frx2html | Internet.vcx | Converts a Visual FoxPro report (.frx) to HTML.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Handle Application Environment Tasks Sample

Visual FoxPro 9.0 Samples
Handle Application Environment Tasks Sample
See Also

File: ...\Samples\Solution\Ffc\Environ.scx

This sample contains the following classes.

Class | Library | Description
System Toolbar | _app.vcx | Handles and tracks system toolbars.
_objectstate | _app.vcx | Determines the state of an object, allowing you to save or restore its state.
_traceawaretimer | _app.vcx | Detects if the trace window is open and handles debug timing appropriately.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
System Toolbar
Handle Common Windowing Tasks
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Handle Common Windowing Tasks Sample

Visual FoxPro 9.0 Samples
Handle Common Windowing Tasks Sample
See Also

File: ...\Samples\Solution\Ffc\WHandler.scx

This sample contains the following classes.

Class | Library | Description
_windowhandler | Ui.vcx | Performs several common window operations, typical for applications.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Window Handler
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Handle Data Conflicts Sample

Visual FoxPro 9.0 Samples
Handle Data Conflicts Sample
See Also

File: ...\Samples\Solution\Ffc\Conflicts.scx

This sample contains the following classes.

Class | Library | Description
_conflicts | _dataquery.vcx | Displays a dialog box allowing you to resolve conflicting rows encountered during editing sessions under optimistic buffering.
_nav4picbutton | _table.vcx | Displays two additional buttons that provide GO TOP and GO BOTTOM functions to the _Nav2PicButton class.
_resizable | _controls.vcx | Causes objects dropped onto a form to resize and move with the Form's resize event.
_datachecker | _datanav.vcx | Traps for data conflicts.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Conflict Catcher Foundation Class
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Pool Manager Sample

Visual FoxPro 9.0 Samples
Pool Manager Sample
See Also

File: ...\Samples\Solution\Ffc\_PoolManager.scx

This sample demonstrates how to use the Pool Manager class, which manages a pool or collection of objects from a class and is useful when you need to use objects repeatedly for a short amount of time.

This sample contains the following classes.

Class | Library | Description
_poolmanager | _poolmanager.vcx | Manages a pool, or collection, of objects from a single class.

Pooling Objects

In this sample, forms are collected in a pool so that you can reuse any form that is available in the pool instead of having to create a new form when you select a customer from the drop-down list.

To use the Pool Manager class in this sample, the following Pool Manager class properties must be set in the Properties window:

cClass = frmCustomer

cClassLibrary = frmCustomer.vcx

Binding to Pool Manager Events

You can bind to _PoolManager events. In this sample, the form's Init event contains code that binds the form's custom handler methods, PoolManager_ObjectRequested and PoolManager_ObjectReturned, to the _PoolManager ObjectRequested and ObjectReturned events so that status can be reported on the sample form:

Copy Code
BINDEVENT(This.PoolManager,"ObjectRequested",ThisForm,"PoolManager_ObjectRequested")
BINDEVENT(This.PoolManager,"ObjectReturned",ThisForm,"PoolManager_ObjectReturned")

Requesting Objects

To request an object from the pool, call the _PoolManager Get method.

To open a customer form in this sample

  1. Select a customer name from the drop-down list.

  2. Click View Customer.

You can open multiple forms by clicking View Customer repeatedly, which requests a form object from the Pool Manager class each time. The form's custom ViewCustomer method contains the following code:

Copy Code
loForm = ThisForm.PoolManager.Get(m.lcCustID)
If Vartype(m.loForm) == "O"
   loForm.Show()
EndIf

In this sample, the Get method returns an unused object that exists in the pool or creates a new object. When a new customer form is created, code in the form's Init event binds to the _PoolManager ObjectRequested and ObjectReturned methods using the private variable THISPOOLMANAGER created in the Get method:

Copy Code
BINDEVENT(THISPOOLMANAGER,"ObjectRequested",This,"PoolManager_ObjectRequested")
BINDEVENT(THISPOOLMANAGER,"ObjectReturned",This,"PoolManager_ObjectReturned")

This event binding makes it possible for the form to call its Hide method instead of the Release method so the form returns to the pool instead of being destroyed.

Returning Objects

To return objects to the pool, call the _PoolManager Free method. In this sample, the form's QueryUnload event occurs when the customer form is closed and returns the form to the pool:

Copy Code
If Vartype(This.oPoolManager) == "O"
   This.oPoolManager.Free(This)
   NoDefault
EndIf

See Also

Other Resources

Foundation Class Samples
Visual FoxPro Foundation Classes A-Z


Retrieve Project Location and Name Sample

Visual FoxPro 9.0 Samples
Retrieve Project Location and Name Sample
See Also

File: ...\Samples\Solution\Ffc\GetProject.scx

This sample contains the following classes.

Class | Library | Description
_folder | _controls | Provides a dialog box for retrieving both a file and folder name.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Get File and Directory
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Run Word, Excel, and Graph Automation Sample

Visual FoxPro 9.0 Samples
Run Word, Excel, and Graph Automation Sample
See Also

File: ...\Samples\Solution\Ffc\Automate.scx

This sample contains the following classes.

Class | Library | Description
Cross Tab | _utility.vcx | Generates a cross-tab report.
Mail Merge | Mailmerge.vcx | Generates a Word mail merge using the core Mail Merge Wizard engine.
Pivot Table | Pivtable.vcx | Generates an Excel pivot table using the core PivotTable Wizard engine.
Graph Object | _utility.vcx | Generates a graph using the core Graph Wizard engine.

This sample demonstrates adding automation routines to your application. Choose the buttons in the dialog box to generate a cross tab summary, an Excel pivot table, a Word mail merge document, and a data graph.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Cross Tab Foundation Class
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Search Text Using Regular Expressions Sample

Visual FoxPro 9.0 Samples
Search Text Using Regular Expressions Sample
See Also

File: ...\Samples\Solution\FFC\Regexp.scx

This sample illustrates how you can use regular expression searching in your applications and uses the Regular Expressions Foundation Class, which provides access to routines for using regular expressions. Regular expressions provide a more complex set of search/filter criteria against a selection of text than the wildcard pattern searching available in the Find dialog box.

This sample contains the following classes

Class | Library | Description
_regexp | _ regexp.vcx | Provides methods for performing regular expression search capabilities against a chunk of text.

See Also

Other Resources

Foundation Class Samples
Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


Set VFP Shell Open Commands Sample

Visual FoxPro 9.0 Samples
Set VFP Shell Open Commands Sample
See Also

File: ...\Samples\Solution\Winapi\Shellopen.scx

This sample is a utility that you can use to change the Shell Open settings of various file types (extensions) and uses the Registry Access Foundation Class. The Shell Open settings control how a file is opened when you double-click the file in Windows Explorer.

Prior to Visual FoxPro 7.0, Visual FoxPro opened a file in a running instance of Visual FoxPro. Starting with Visual FoxPro 7.0, Visual FoxPro opens that file in a new instance of Visual FoxPro. This sample makes it possible for you to control how you want files opened at a file type level.

This sample contains the following classes

Class | Library | Description
registry | registry.vcx | Contains routines to access the Windows Registry.

See Also

Other Resources

Foundation Class Samples
Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


Tips for the Windows 2000 Logo Program Sample

Visual FoxPro 9.0 Samples
Tips for the Windows 2000 Logo Program Sample
See Also

File: ...\Samples\Solution\FFC\Logo.scx

Custom applications can be submitted to receive the Windows 2000 Logo. There are a number of requirements your application must adhere to in order to obtain the Logo (see http://www.microsoft.com/winlogo). This sample shows several Foundation Classes that provide information that might be of use in making your application Logo compliant.

This sample contains the following classes

Class | Library | Description
_sysmetrics | _ system.vcx | Returns system information, such as number of mouse buttons, number of monitor, and whether a mousewheel is present.
_userpriv | _ system.vcx | Returns the logged on user access rights (guest, power user, administrator).
_commonfolder | _ system.vcx | Returns path to common system folders such as My Documents.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Use an Enhanced Openfile Dialog Box Sample

Visual FoxPro 9.0 Samples
Use an Enhanced Openfile Dialog Box Sample
See Also

File: ...\Samples\Solution\FFC\Getfilex.scx

The standard Visual FoxPro GETFILE() and PUTFILE() commands provide file picker dialogs, which do not have the look and feel of the latest dialogs. This sample shows use of the Common Dialog Box Foundation Class. With this class, you can now have extended UI features on these dialogs including the Places bar on the left side of the dialog, which provides for quick access to other search locations, such as History, Desktop, and My Document.

This sample contains the following classes

Class | Library | Description
_comdlg | _ system.vcx | Contains a set of properties and methods so that you can use the native Windows open and save file dialogs.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Forms Solution Samples
Foundation Class Samples
Guidelines for Using Visual FoxPro Foundation Classes


Use Array Handling Sample

Visual FoxPro 9.0 Samples
Use Array Handling Sample
See Also

File: ...\Samples\Solution\Ffc\Arrays.scx

This sample contains the following classes.

Class | Library | Description
_arraylib | _utility.vcx | Provides methods for handling certain array operations that are not provided by the Visual FoxPro array functions.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z

See Also

Other Resources

Foundation Class Samples
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Use Common Application Dialog Boxes Sample

Visual FoxPro 9.0 Samples
Use Common Application Dialog Boxes Sample
See Also

File: ...\Samples\Solution\Ffc\Dialogs.scx

This sample contains the following classes.

Class | Library | Description
_splash | _dialogs.vcx | Provides a splash screen for an application.
_login | _dialogs.vcx | Provides a Login box for an application.
_aboutbox | _dialogs.vcx | Provides an About box for an application.
_keywords | _dialogs.vcx | Provides access to the keyword table (.dbf).
_locateitem | _dialogs.vcx | Displays Locate Item dialog boxes for an application.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Password Dialog Box
Splash Screen
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Use Edit Buttons for a Complex Form Sample

Visual FoxPro 9.0 Samples
Use Edit Buttons for a Complex Form Sample
See Also

File: ...\Samples\Solution\Ffc\Dataedit.scx

This sample contains the following classes.

Class | Library | Description
picbtns | Wizbtns.vcx | Provides a full set of edit and navigation buttons.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Simple Edit Buttons
Data Edit Buttons
Use Edit Buttons for a Simple Form
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Use Edit Buttons for a Simple Form Sample

Visual FoxPro 9.0 Samples
Use Edit Buttons for a Simple Form Sample
See Also

File: ...\Samples\Solution\Ffc\Dataedit2.scx

This sample contains the following classes.

Class | Library | Description
_picformbtns | _wizbtns.vcx | Displays buttons that provide Find, Print, Add, Delete, and Exit functions.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z

See Also

Other Resources

Foundation Class Samples
Use Edit Buttons for a Complex Form
Simple Edit Buttons
Data Edit Buttons
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Use Mover List Boxes for Selecting Data Sample

Visual FoxPro 9.0 Samples
Use Mover List Boxes for Selecting Data Sample
See Also

File: ...\Samples\Solution\Ffc\Movers.scx

This sample contains the following classes.

Class | Library | Description
_tablemover | _movers.scx | Automatically loads tables and fields from the currently selected data source.
_fieldmover | _movers.scx | Automatically loads fields from the current data source.
_sortmover | _movers.scx | Automatically handles sorting of data.
_supermover | _movers.scx | Provides a mover list box with Move, Remove, Move All, and Remove All buttons.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Add Items Interactively to a List Box
Mover
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Use Progress Thermometer Sample

Visual FoxPro 9.0 Samples
Use Progress Thermometer Sample
See Also

File: ...\Samples\Solution\Ffc\Therm.scx

This sample contains the following classes.

Class | Library | Description
_thermometer | _therm.vcx | Provides a standard thermometer progress display class.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Foundation Class Samples
Thermometer
Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Working with Microsoft Agent Sample

Visual FoxPro 9.0 Samples
Working with Microsoft Agent Sample
See Also

File: ...\Samples\Solution\FFC\Agent.scx

This sample shows how you can add animated characters to your applications using Microsoft Agent technology. These characters are similar to Office Assistants and can perform a variety of actions.

This sample contains the following classes

Class | Library | Description
_agent | _agent.vcx | Provides methods for handling operations with Microsoft Agent.

For details on all classes available in the foundation classes, see Visual FoxPro Foundation Classes A-Z.

See Also

Other Resources

Visual FoxPro Foundation Classes A-Z
Guidelines for Using Visual FoxPro Foundation Classes


Walkthroughs

Visual FoxPro 9.0 Walkthroughs
Walkthroughs

Walkthroughs give step-by-step instructions for common scenarios, which makes them a good place to start learning about Visual FoxPro or a particular feature area.

In This Section

Walkthrough: Creating Applications with Visual FoxPro

Provides steps for creating a simple program, including moving data and creating forms, and shows how to use it as the basis for an application.
Walkthrough: Creating Reports with Visual FoxPro

Provides steps for creating reports using the Report wizard and the Report designer, and discusses issues to consider when planning and creating reports.
Walkthrough: Retrieving Data from Different Data Sources

Provides steps for retrieving data from Visual FoxPro native tables or data using Open Database Connectivity (ODBC), ActiveX Data Objects (ADO), or XML data sources.
Walkthrough: Creating XML Web Services with Visual FoxPro

Provides steps for how to create and publish a Visual FoxPro COM server as an XML Web service.
Walkthrough: Creating a Visual FoxPro Application Setup Program Using InstallShield Express

Provides steps for packaging and deploying your applications using InstallShield Express, making it possible for users to install and configure your products efficiently.

Related Sections

Using Visual FoxPro

Microsoft Visual FoxPro provides the tools needed to create and to manage high-performance, 32-bit database applications and components. With its robust tools and data-centric object-oriented language, you can build modern, scalable, multi-tier applications that integrate client/server computing and the Internet.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Explains how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity so you can access the full power of Visual FoxPro.
Development Productivity Tools

Explains that Visual FoxPro provides developer tools for application development within the FoxPro application and the FoxPro language.
Samples and Walkthroughs

Provides extensive samples for database and application development.


Walkthrough: Creating Applications with Visual FoxPro

Visual FoxPro 9.0 Walkthroughs
Walkthrough: Creating Applications with Visual FoxPro
See Also

You can use Visual FoxPro to create simple programs or more complex enterprise level applications, servers, and XML Web services. You can use tools to create programs or manually write them. When you compile Visual FoxPro programs, you can compile them as application (.app) files for running in a Visual FoxPro environment or as executable (.exe) or dynamic-link library (.dll) files that you can call from anywhere in a Microsoft Windows environment.

The following sections in this walkthrough explain how to create a simple program and use it as the basis for an application:

  • Using Data

  • Creating a Program for a Form

  • Creating an Application

Using Data

Visual FoxPro programs and applications are based on data in tables or cursors. Data can exist already on your hard disk, a remote server, or a Web site, or you can create it in Visual FoxPro. Data can be in any of the formats that Visual FoxPro recognizes, including OLE objects.

For this sample application, the data you use will be copied from the Orders table, which is included with Visual FoxPro in the \Program Files\Microsoft Visual FoxPro VersionNumber\Samples\Data folder.

To move data from one table to another

  1. On the File menu, click Export.

  2. In the Type drop-down list in the Export dialog box, select Visual FoxPro 3.0 (DBF).

  3. In the To text box, type myApp as the name of the file you want to create.

  4. Click the ellipsis (...) button and save the file in the Visual FoxPro Projects folder (..\My Documents\Visual FoxPro Projects).

  5. In the From text box in the Export dialog box, click the ellipsis (...) button, and locate the Orders.dbf table in \Program Files\Microsoft Visual FoxPro 8\Samples\Data folder.

  6. In the Export dialog box, click Options .

  7. In the Export Options dialog box, click Fields, move cust_id, to_city, to_country, and order_amt from the All fields list to the Selected fields list, and then click OK. Click OK twice more to close the Export Options dialog box and the Export dialog box.

  8. On the File menu, click Open.

  9. In the Files of type drop-down list, choose Table, select the open exclusive check box, and browse to myApp.dbf.

  10. On the View menu, click Table Designer.

  11. On the Fields tab, select the to_city row, click the Index drop-down list, and choose Ascending.

  12. Click OK, and click Yes to make the structure change permanent.

  13. On the Window menu, click Data Session to order the table according to your new index.

    Note:
    You have created a table that, because it is indexed, supports group calculations in the Report Designer.

  14. In the Data Session window, click Properties.

  15. In the Index Order drop-down list, select myApp:to_city, and then click OK.

    You have now exported selected fields from one table to another and then set an index on the new table. Leave the Data Session window open, and use this table immediately for the rest of this sample.

Creating a Program for a Form

You can create simple Visual FoxPro programs from the menus and the IDE. These programs either run in Visual FoxPro or access the Visual FoxPro Runtime.

To create the form

  1. On the File menu, click New.

  2. Click Form, and then click New file.

    This opens the Form Designer, adds the Form menu and the Form Controls toolbar, and displays the Properties window for the form. If the toolbar is not visible, you can open it from the View menu.

  3. In the Properties window for the form, select Caption, and type myForm.

To add a label

  1. On the Form Controls toolbar, click Label, and drag a rectangle on the form.

  2. In the Properties window for the label control, select Caption, and change it to My Data Form. Then, select FontSize, and type 20.

  3. If necessary, resize the label so the text fits.

To add a grid

  1. On the Form Controls toolbar, click Grid, and then draw a rectangle on the form.

  2. Right-click the Grid control, and select Builder from the shortcut menu.

  3. In the Grid Builder, select the table, myApp.

  4. On the Grid Items tab, move all the items in the Available fields list to the Selected fields list, and then close the builder.

To add a button

  1. On the Form Controls toolbar, click the Command Button icon, and then draw a rectangle on the form below the grid.

  2. Double-click the newly created button, and type the following code in the code editor. Close the code editing window when you are finished.

    Copy Code
    THISFORM.RELEASE

    This code will close the form when you do not need it any more.

  3. In the Properties window for the button control, select Caption, and type Exit.

  4. On the File menu, click Save As, and save the form as myForm.

  5. Click Run (!) on the toolbar to preview your form.

To complete the program

  1. On the File menu, click New.

  2. Click Program, and then click New file. This opens the Visual FoxPro editor.

  3. In the editor, type the following:

    Copy Code
    DO FORM myForm.scx

  4. Save this program as myProgram. This creates a Visual FoxPro program (.prg) file that runs your form from the following command in the Command window:

    Copy Code
    DO myProgram

Now you have placed a table (as a grid), a label, and a button on a form. You created a program to run from the Command window or Program menu. In the next section, the application exchanges a data review form for the grid and adds it to the program before compiling it to a file.

Creating an Application

Running the program you created earlier requires Visual FoxPro to be installed on the computer. However, you can create an application with Visual FoxPro that will run on a computer that does not have Visual FoxPro installed on it.

The earlier program has only one form and does not have much functionality. This section walks you through adding a data review form with some additional controls and then compiling the two forms — first into a Visual FoxPro application and then into a Windows application. A Visual FoxPro application (.app) file or a Visual FoxPro executable (.exe) file can each run on Windows platforms if Visual FoxPro is installed. A Visual FoxPro application compiled as an executable (.exe) file also can run on Windows platforms with only the Visual FoxPro Runtime installed.

In this section, you will create an application using the Application wizard, the Application builder, and the Project manager.

  • The Application wizard creates a project and provides the advanced application framework so you can add components you might have created already or create an application from start to finish, including splash screens and other enhancements.

  • The Application builder makes it possible for you to add tables, forms, and reports to an existing project.

  • The Project manager, the most fundamental application-building tool in Visual FoxPro, provides access to all the components you might want to include in an application and contains them for compilation.

For this walkthrough, you use the Application wizard first.

To create an application

  1. On the Tools menu, point to Wizards, and click Application.

  2. In the Project name box, type MyApplication, save the project in your Visual FoxPro Projects folder (..\My Documents\Visual FoxPro Projects), and then click OK.

Visual FoxPro prepares to create a project file with the name you specified. When it has finished creating the project, two windows appear: the Project Manager and the Application Builder. In the following procedures, you use the Application Builder to add components and functionality to your application.

To specify splash screen and About dialog box information

  1. On the General tab of the Application Builder, click the ellipsis (...) button next to the Image box.

  2. Find the Visual FoxPro logo, fox.bmp, in your Visual FoxPro folder (..\Program Files\Microsoft Visual FoxPro VersionNumber), and click OK. This image will appear on your application splash screen.

    Note:
    If you close the Application builder, you can reopen it by clicking the Tools menu, pointing toWizards, and clicking All Wizards. Click Application Builder in the Wizard Selection dialog box, and then click OK.

  3. On the Credits tab of the Application Builder, add the appropriate authoring and version information.

To specify the data source

  1. On the Data tab, click Select, and find and select myAPP (the table you used earlier in the simple program).

    Note:
    You can choose any available table. This tab also provides buttons, so you can create tables or a database easily.

To create a form and a report

  1. On the Data tab, you can select from lists of form and report templates that are part of the Advanced Application Framework (included in the Application Builder). Accept the default values in the drop-down lists, and then click Generate.

    Visual FoxPro generates a form and a report from the table you specify and gives you access to them from the Forms and Reports tabs of the Application builder. These components become part of the project you are building, and the files are saved in the Forms or Reports folder in your Visual FoxPro Projects folder (..\My Documents\Visual FoxPro Projects).

To add controls to the form

  1. On the Forms tab of the Application Builder, click Edit to open the Form Designer, where you can make any additions or changes.

    As is, the form will display only the first record, so you must add at least one more control; in this procedure, you add two.

  2. On the Form Designer toolbox, click the Button icon, and drag a rectangle in the form. In the Caption property, type Next.

  3. Double click the Next button on the form, and type the following code in the code editor.Close the code-editing window when you are finished.

    Copy Code
    IF NOT EOF()
   SKIP
ELSE
   GO TOP
ENDIF
THISFORM.REFRESH

    This code steps through the table records and displays each record. You also could add another button, with appropriate code, to move back through the table.

  4. Copy the Next button, and place the copy at the far right of the form. In the Caption property, type Exit.

  5. Double click the Exit button, and, in the Click event edit window, replace the code in the window with the following code, and then close the window:

    Copy Code
    THISFORM.RELEASE

    This code closes your form.

To add calculations to the report

  1. On the Reports tab of the Application Builder, click Edit for MyApp to open the Report Designer. Expand all the bands of the report to make it easier to perform the following operations.

    Note:
    This is where you can make any additions or changes, such as rearranging fields or adding controls.

  2. On the View menu, click Data Environment.

  3. Right click the Data Environment window, and select Properties from the shortcut menu.

    This will set the Properties window to the Dataenvironment.

  4. In the Properties window, choose the cursor from the Properties Description drop-down list, and change the Order property to to_city to make grouping possible.

  5. On the Report menu, click Data Grouping.

  6. In the Data Grouping dialog box, click the ellipsis (...) button under Group expressions. In the Expression Builder, double-click to_city in the Fields list. Click OK in both dialog boxes.

  7. In the Report Designer, copy and paste the to_city element, and then drag the pasted element from the Detail band to the Group Footer band for group totals. Repeat this procedure to place another copy of the to_city element in the Page Footer for the entire table.

  8. For each copy of the to_city element, double-click the element to open the Report Expression dialog box.

  9. Click Calculations.

  10. In the Calculation Field dialog box, click Count.

    The Reset drop-down list should display the default selection, which is the to_city field. This means the Count function will reset to zero each time the value of the to_city element changes in the pass through the table. This is correct for the Group Footer band, but you must change this selection for the to_city element in the Page Footer band.

  11. After you select Count in the Calculate Field dialog box of the to_city element you placed in the Page Footer band, change the Reset value to End of Report.

  12. After setting the Calculation field of each to_city element, click OK to close the dialog box.

  13. Click OK to close the Application Builder.
Note:
In addition to the features you specified in the Application wizard, Visual FoxPro created other components for your application. When you run your application, you will discover a customized File menu and a dialog box from which you can run your form and your report.

Now you can use the Project manager to review the components you have created. You will find that the Application wizard created many components, which you modified in the Application builder and the Form and Report designers. You can examine and modify these components in various Visual FoxPro tools, such as the designers or the Class Browser and Object Browser.

At this point, the most important use of the Project manager is to complete the compilation of your files into an application.

To complete the application

  1. In the Project Manager, click Build.

  2. Click Application (app) to create an application to be run only in Visual FoxPro.

    Note:
    If you select Win 32 executable / COM server (exe), you create an application that can be run on a computer with only the Visual FoxPro Runtime installed.

  3. Click OK.

When the build process is complete, you have an application you can run in Visual FoxPro by double-clicking the .app file. When the program opens, it displays the splash screen and then the Quick Start dialog box from which you can view your form and your report. The application also provides a Quick Start menu item.

For more information on creating programs and applications, see Application Wizard and Application Builder.

For more information on the Project Manager and for details on application build options, see Project Manager Window, and Build Options Dialog Box.

See Also

Other Resources

Application Wizard
Application Builder
Walkthroughs


Walkthrough: Creating Reports with Visual FoxPro

Visual FoxPro 9.0 Walkthroughs
Walkthrough: Creating Reports with Visual FoxPro
See Also

You can design and create reports to provide clarity and readability for data, transforming it from developer data to user information. Reports are ideal for displaying and distributing data because you can easily repeat, duplicate, and share them.

This walkthrough shows how to create Visual FoxPro reports using the Report wizard to quickly get a report of any single or related tables. If you want to customize your report, or add non-data elements, use the Report designer.

  • Creating a Single-table Report

  • Creating a Multi-table Report

For more information, see Working with Reports.

Creating a Single-table Report

If you only want to look at what you have, use the Browse window on any table.

To access the Browse window

  1. From the File menu, open the table.

  2. On the View menu, select Browse.

If you want to print or mail a report quickly, you can export the file as text, and then print or mail the new text file. The Export dialog box options make it possible for you to select portions of the table to convert to text. (Remember to check the paper orientation for wide tables.)

To report raw data from a table as text quickly

  1. On the File menu, click Open.

  2. In the Open dialog box, select Table in the Files of type drop-down list, locate the table you want, and click OK.

  3. On the View menu, click Browse.

    This displays the selected table. At this time, in the IDE, you can change the column widths or locations, or you can make lasting changes from the Table menu.

  4. On the File menu, click Export.

  5. In the Export dialog box, select Delimited Text from the Type drop-down list.

    If you were going to use the table in another application, such as Microsoft Excel, you could select the application from the list, and the table would be converted to the proper format and saved with the correct extension.

  6. Click To, and enter the file name of your new file, including the extension.

  7. In the Field separator drop-down list, select the delimiter you want in the new file, and then click OK.

Visual FoxPro Report Wizard

If you find you must have formal presentations, summaries, or calculations, or you must use the same information repeatedly, then use the Report wizard or the Report designer to generate reusable, updatable, modifiable reports.

The Report wizard prompts you with choices that make it possible for you to create a well-formatted report of one or more tables quickly. In many circumstances, these quick reports work very well.

To use the Report wizard

  1. On the File menu, click New.

  2. In the New dialog box, select Report.

  3. Click the Wizard button, and select the type of report you want to create.

In the wizard, you can preview a report before you save it. In addition, you can save it and then open it in the Report designer to use the Visual FoxPro IDE to add to your report design.

To experiment with the Report wizard, use the Labels.dbf table, which ships with Visual FoxPro. Use the following procedures to work with simple, one-table reports

To create a simple Report using the Labels.dbf table

  1. On the File menu, click New.

  2. In the New dialog box, select Report and then click the Wizard button.

  3. In the Wizard selection dialog box, double-click Report Wizard.

  4. In the Report wizard, select Free Tables in the Databases and tables drop-down list box, and select or locate the Labels table.

  5. Select any or all of the available fields, and continue the wizard, making the appropriate selections up to Step 5.

  6. In Step 5, choose a report style and orientation.

    In addition, you can click Summary options to access five functions — Sum, Avg, Count, Min, and Max — for fields displayed in your report. The selected functions are added automatically with appropriate labeling and positioning.

  7. In Step 6, click the Preview button to see the report your selections would create if you click Finish. You can print the preview without creating a report file.

    The Report wizard creates labels and selects fonts, font sizes, indentation, and other styling and formatting characteristics to help turn the table data into report information. Often, creating reports with the wizard is as fast as creating the ad hoc Browse window copy, and the results often look much nicer.

  8. Click Finish.

For more information, see Report Wizard and One-To-Many Report Wizard.

Visual FoxPro Report Designer

You can use the Report designer to create simple reports, called Quick Reports. In addition, the Report designer is a powerful tool for creating formatted reports. The main difference between using the Report wizard and using the Report designer is that the designer provides greater control of the positioning of data and other content.

To create Quick Reports with the Report designer

  1. On the File menu, click New.

  2. In the New dialog box, select Report, and click the New File button.

  3. On the Report menu, click Quick Report.

    If you have a table open, Visual FoxPro will use it as the source for your report. If no table is open, Visual FoxPro displays the Open dialog box, so you can choose a table.

The Report designer populates the Detail and Page Footer bands. Then, the details are up to you. You have more control than with the Report wizard; you also have more responsibility. If you want to generate information, such as sums, averages, or counts, use Data Grouping on the Report menu. Your specification for a data group can be as simple as the name of the index field selected from the Expression builder.

To include a calculation in your report, open an ordered table (indexed on cust_id), create a Quick Report as basis, specify data grouping, and then specify how and where in the report the calculation is displayed. Finally, preview, print, and save the report.

To create a report containing a calculation

  1. From the File menu, open the ..\samples\DATA\orders.dbf table.

  2. On the Window menu, click Data Session, and click Properties for the orders table.

  3. In the Work Area Properties dialog box, choose Orders.cust_id as the Index order, click OK, and then close the Data Session dialog box.

  4. On the File menu, click New. In the New dialog box, select Report, and then click New File.

  5. On the Report menu, click Quick Report, and then select the vertical layout.

    Note:
    For this example, you do not need all the fields, so you might want to remove the labels and fields following order_amt, as well as the labels and fields between emp_id and order_date. Move the fields together, and resize the report bands.

  6. On the Report menu, click Data Grouping.

  7. In the Data Grouping dialog box, click the ellipsis (...) button under Group Expressions. In the Fields list in the Expression builder, double-click Orders.cust_id. Click OK in both dialog boxes.

  8. In the Report Designer, place a copy of the order_amt field in the Group Footer band for group totals, and place another copy in the Page Footer for the entire table.

  9. Copy, paste, and then drag the copied fields from the Detail band.

  10. For each copy of order_amt, double-click the field to open the Report Expression dialog box.

  11. Click the Calculations button.

  12. Select the Sum function from the Option Group.

    The Reset drop-down list box should display the default selection, which is the Order.cust_id field. This means that the Sum function resets to zero each time the value of the cust_id field changes in the pass through the table. This is fine for the group sub totals, but you must change this selection for the order_amt field in the Page Footer band.

  13. After you select Sum in the Calculate Field dialog box of the order_amt field you placed in the Page Footer band, change the Reset value to End of Report.

  14. After setting the Calculation field of each order_amt, close the dialog boxes by clicking OK.

Use the print preview to see what you have created and to make sure that you are getting the information you expected. Save the report if you are satisfied with it. The last page displays the total for all orders — information not specifically included in the table.

While the Report designer is open, you have access to tools and other designers, so you can review the current table or modify the data environment by selecting other tables or indexes. In addition, you can add functionality to the report through the Report Controls toolbar and the Report menu.

For more information on the Report designer, see Report Designer and Report Designer Band Dialog Boxes.

Creating a Multi-table Report

In addition to single-table data, Visual FoxPro reports can display data from several related tables and can perform calculations and produce summaries.

This procedure uses two tables, customer and orders, from the testdata.dbc database in the Samples folder.

To create a report using the Testdata database that ships with Visual FoxPro

  1. On the File menu, click New.

  2. In the New dialog box, select Report, and click the Wizard button.

  3. In the Wizard selection dialog box, double-click One-To-Many Report Wizard.

  4. In the One-To-Many Report wizard, select the TESTDATA database in the Databases and Tables drop-down list, and select the Customer table.

  5. In Step 1 of the wizard, highlight the Customer table, and select the cust_id and Customer fields from the Available Fields drop-down list.

  6. In Step 2, highlight the Orders table, and select the cust_id, to_city, and order_amt fields from the Available Fields drop-down list.

    In Step 3, you see the way the two tables are related — customer.cust_id to orders.cust_id; in other words, the tables are indexed on matching fields.

    If you want a different relationship, you could choose from the drop-down lists for the parent and child tables. If you change the specified relationship, you would also have to make sure you had chosen the correct fields in steps 1 and 2.

  7. In Step 5, choose a report style and orientation.

    In addition, you can click Summary options to access five functions — SUM, AVG, COUNT, MIN, and MAX — for fields displayed in your report. The selected functions are added automatically with appropriate labeling and positioning.

  8. In Step 6, click Preview to see the report your selections would create if you click Finish. You can print the preview without creating a report file.

  9. Click Finish.

You can create the same report in the Report designer, but to specify the database and the tables, you must establish the data environment of the report. You then use that data environment in a Quick Report or through drag-and-drop in the IDE to create your report.

For samples of various kinds of report you can create, see the Solution Samples.

For more information on using reports, see How to: Specify Expressions in Field Controls.

See Also

Other Resources

Report Wizard
One-To-Many Report Wizard
Report Designer
Report Designer Band Dialog Boxes
Solution Samples
Walkthroughs


Walkthrough: Retrieving Data from Different Data Sources

Visual FoxPro 9.0 Walkthroughs
Walkthrough: Retrieving Data from Different Data Sources
See Also

You can retrieve data using various data source connection types. You can then create Visual FoxPro cursors or cursor adapters using the retrieved data. Cursor adapters can retrieve data from a wider range of data sources than is possible with conventional cursors.

This walkthrough explains how to build a data environment for a Visual FoxPro form by configuring a data source and, if needed, a connection type that applies to all cursor adapters in the data environment using the DataEnvironment Builder. You can then create cursors in the data environment that have specific properties for accessing data using the CursorAdapter Builder.

This walkthrough contains the following sections:

  • Prerequisites

  • Opening the Data Environment for a Form

  • Setting Data Source Types and Data Sources

  • Retrieving Data for Cursor Adapters

  • Using the Cursor Adapter on the Form

For more information cursor adapters, see Data Access Management Using CursorAdapters, CursorAdapter Class, DataEnvironment Builder, and CursorAdapter Builder.

Prerequisites

This walkthrough requires the following:

  • Data sources using the following connection types:

    • Native

      Use the Northwind sample database included with Visual FoxPro and located in the ...\Samples\Northwind directory.

    • ODBC or ADO

      Set up access to a local or remote SQL server (SQL Server 7 or 2000) with the Northwind database installed.

    • XML

      Use the GetCustomers.XML DataSet file included with Visual FoxPro and located in the ...\Samples\Solution\Toledo directory.

  • A Visual FoxPro form based on the FrmSolution class included with the Solution.vcx class library, which is located in the ...\Samples\Solution folder. A form based on the FrmSolution class appears similar to the forms used in the Solution samples.

You can create a form based on the FrmSolution class by creating a category in the Toolbox, adding the FrmSolution class to the Toolbox, and creating a form based on that class.

To create the form used in this walkthrough

  1. On the Tools menu, click Toolbox.

  2. Right-click the Toolbox, and click Add Category.

  3. In the Category name box type a category name.

    The category you created appears in the Toolbox.

  4. In the Toolbox, right-click the category, and click Add Class Library.

  5. In the Add Class Library dialog box, click the ellipsis (...) button, browse to the ...\Samples\Solution folder, and select Solution.vcx.

    The classes in the Solution.vcx class library appear in the category you created in the Toolbox.

  6. In the Toolbox, right-click frmsolution (SOLUTION), and click Create Form.

Opening the Data Environment for a Form

When you create a form, Visual FoxPro creates a DataEnvironment object as a container for Cursor, CursorAdapter, and Relation objects that are associated with the form, a form set, or a report. You need to open and set the form's data environment to the appropriate data source type and data source to retrieve data from.

Before you select the data source type and data source from which to retrieve data, open the form's data environment.

To open the form's data environment

  1. Open the form.

  2. In the Form Designer, right-click the form, and click DataEnvironment to open the data environment.

    For a form with an empty data environment, the Open dialog box appears.

  3. In the Open dialog box, click Cancel.

  4. To open the Data Environment Builder, right-click the Data Environment surface, and click Builder.

    The DataEnvironment Builder opens and displays the following tabs: Data Source and Cursors.

For more information about DataEnvironment objects, see DataEnvironment Object.

Setting Data Source Types and Data Sources

Set the data source type and configure the appropriate data source that you want to retrieve data by from setting options on the Data Source tab in the DataEnvironment Builder.

To select the data source type for the form's data environment

  1. In the DataEnvironment Builder, click the Data Source tab.

  2. On the Data Source tab, select the appropriate data source type: ADO, Native, ODBC, or XML.

Depending on your selection, the appropriate options appear. The following procedures demonstrate how to set the data environment to native Visual FoxPro tables, ODBC, ADO, and XML.

For more information, see Data Source Tab, DataEnvironment Builder.

Specifying Native Visual FoxPro Data Sources

To specify native Visual FoxPro data sources, use the following procedure:

To use native Visual FoxPro tables

  1. After selecting Native on the Data Source tab, click the ellipsis (...) button to the right of the Database box

  2. Browse to the ...\Samples directory and select the Northwind database.

To continue this walkthrough, see Retrieving Data for Cursor Adapters.

Specifying Data Sources Using ODBC

To specify ODBC data sources, use the following procedure:

To use ODBC data sources

  1. After selecting ODBC in the Data Source tab, click Use connection string.

  2. Type the connection string to connect to the Northwind database on your local or remote SQL Server. For example:

    Copy Code
    Driver={Sql Server};Server=localhost;Database=Northwind;Int Security=yes;
    Note:
    You must have access to a local or remote SQL Server (SQL Server 7 or 2000) with the Northwind database installed. If your SQL Server is not local, you can change the value of the Server= parameter in the connection string to the name of the remote server.

  3. Click Test Connection to test the connection.

If the connection is successful, you can continue and retrieve data from the data source.

To continue this walkthrough, see Retrieving Data for Cursor Adapters.

Specifying Data Sources Using ADO

To use ADO data sources, use the following procedure:

To use ADO data sources

  1. After selecting ADO on the Data Source tab, click Use connection string.

  2. Type the connection string to connect to the Northwind database on your local or remote SQL Server. For example:

    Copy Code
    Provider=SQLOLEDB.1;Integrated Security=SSPI;Initial Catalog=Northwind;Data Source=localhost
    Note:
    You must have access to a local or remote SQL Server (SQL Server 7 or 2000) with the Northwind database installed. If your SQL Server is not local, you can change the value of the Data Source= parameter in the connection string to the name of the remote server.

  3. Click Test Connection to test the connection.

    If the connection is successful, you can continue and retrieve data from the data source.

If you want to construct a connection string instead of typing one on the Data Source tab, click Build to open the Data Link Properties dialog box in the Visual FoxPro OLE DB Provider. For more information, see OLE DB Provider for Visual FoxPro.

To continue this walkthrough, see Retrieving Data for Cursor Adapters.

Specifying XML Data Sources

In this walkthrough, the method for creating cursor adapters from XML demonstrates only one example of how you can access an XML data source, more specifically, an XML DataSet file generated from ADO.NET. Actual code can vary depending on your specific needs.

To use XML data sources

  1. After selecting XML on the Data Source tab, click the Cursors tab.

You can also use cursor adapters with cursors generated from XML with XML adapters or XMLAdapter objects. You can use this combination to access more advanced features of the design-time environment and to bind controls on a form to fields in the cursor adapter. The XML adapter performs the actual work at run time.

When you create a cursor adapter from XML, you can use the CursorAdapter Builder to set the CursorAdapter properties. However, you need to create an XMLAdapter object to load the XML into its Tables collection. After creating the XML adapter, you can load an XML file into the XML adapter, set the Select command of the cursor adapter to the desired XMLTable object reference in the XMLAdapter Tables collection, and then call the CursorAdapter CursorFill method to populate the cursor with XML data.

To continue this walkthrough, see Retrieving Data for Cursor Adapters.

For more information about how cursor adapters work with XML adapters, see the Create a Cursor from an XML DataSet Sample as an example of how to access an XML file and generate XML DiffGrams and XML Functionality Using XMLAdapters.

For more information about XML adapters and cursor adapters, see XMLAdapter Class and CursorAdapter Class.

Retrieving Data for Cursor Adapters

After setting the form's data environment in the DataEnvironment Builder to data source you want to use, create CursorAdapter objects in the form's data environment to retrieve data from the data source. You can create CursorAdapter objects by setting options on the Cursors tab of the CursorAdapter Builder.

To create a new cursor adapter

  1. In the DataEnvironment Builder, click the Cursors tab to make it visible.

  2. On the Cursors tab, click New to open the CursorAdapter Builder.

The CursorAdapter Builder appears, displays the Properties, Data Access, and Auto-Update tabs, and creates a new cursor adapter named Cursor1.

For more information, see Cursors Tab, DataEnvironment Builder.

Setting Properties for Cursor Adapters

Set properties for a new cursor adapter by editing settings in the Properties tab of the CursorAdapter Builder.

To set properties for a new cursor adapter

  1. In the CursorAdapter Builder, click the Properties tab to make it visible if not already visible.

  2. On the Properties tab, edit the name for Cursor1 if you want; rename the cursor adapter alias to Customer.

    Note:
    Usually, you type the name and alias you want for the cursor adapter.

  3. Click Use DataEnvironment data source to use the data source previously set for the form's data environment.

For more information, see Properties Tab, CursorAdapter Builder.

Specifying How Cursor Adapters Retrieve Data

After creating a new cursor adapter, specify how the cursor adapter retrieves data from the data source by setting options in the Data Access tab of the CursorAdapter Builder.

If you are using the Native, ODBC, or ADO data source type, use the following instructions for constructing the Select command to retrieve data from the data source. If you are using the XML data source type, follow the instructions for specifying a well-formed XML file that contains schema.

To construct the Select command for data sources using Native, ODBC, and ADO

  1. In the CursorAdapter Builder, click the Data Access tab to make it visible.

  2. On the Data Access tab, click Build to open the Select Command Builder dialog box.

  3. In the Select Command Builder dialog box, select the CUSTOMERS table in the Table list.

    The fields that the CUSTOMERS table contains appear in the list on the left side of the Select Command Builder dialog box.

  4. In the list on the left, click CUSTOMERS.* to include the CUSTOMERS table and all its fields in the Select command.

    Note:
    Usually, if you want to select individual fields in the table for the Select command, click tableName.fieldName to add each field separately to the list of selected fields appearing on the right side of the Select Command Builder dialog box.

  5. Click the single right arrow (>) to add CUSTOMERS.* to the list of selected fields, and then click OK.

    The constructed Select command appears in the Select command box, and the schema for the cursor adapter appears in the Schema box.

You can set additional options for data retrieval. However, this walkthrough uses the default settings for these options.

Note:
In this walkthrough, buffer mode for the cursor adapter is set to optimistic row buffering by default on the Data Access tab for Native, ODBC, and ADO data source types. Therefore, when you make changes in a grid row on the form and move to another row, those changes are sent to the Customer.dbf table in the data source through the appropriate connection type. For more information about buffer modes, see BufferModeOverride Property.

For more information about additional options you can set, see Data Access Tab, CursorAdapter Builder.

To specify an XML file for XML data sources

  1. In the CursorAdapter Builder, click the Data Access tab to make it visible.

  2. On the Data Access tab, click Build located above the Schema box to display the Open dialog box.

  3. Browse to the ...\Samples\Solution\Toledo\ folder, and select the GetCustomers.XML file.

    The schema for the cursor adapter appears in the Schema box.

  4. In the Buffer mode override box, select Optimistic table buffering.

    Note:
    In this walkthrough, buffer mode for the cursor adapter is set to optimistic table buffering on the Data Access tab for XML data source types to make it possible for the XML adapter to create XML DiffGrams. For more information about buffer mode settings, see BufferModeOverride Property.

  5. Click OK to close the CursorAdapter Builder, and then click OK again to close the DataEnvironment Builder.

    The new cursor adapter, now named Customer, appears in the Data Environment for the form and contains all the fields from the GetCustomer.xml file.

You can set additional options for data retrieval. However, except for the buffer mode setting for the cursor created by the cursor adapter in the XML example, this walkthrough uses the default settings for these options. For more information about these options, see Data Access Tab, CursorAdapter Builder.

To continue with the XML example, see Using the Cursor Adapter on the Form.

Configuring Updating for Cursor Adapters

After constructing the Select command for the cursor adapter to retrieve data, you can specify how the cursor adapter performs updates to the data source by setting options on the Auto-Update tab of the CursorAdapter Builder.

To configure how the cursor adapter updates the data source

  1. In the CursorAdapter Builder, click the Auto-Update tab.

  2. On the Auto-Update tab, select the Auto-update check box.

    Selecting the Auto-update check box populates the field list on the Auto-Update tab with fields that you selected on the Data Access tab and enables automatic updating for specified fields.

  3. Select the Update all fields check box to designate all fields from the specified table for automatic updating.

    A check mark appears in the automatic updating column, indicated by a pencil symbol, for each field in the field list.

  4. Select the check box in the key field column, indicated by a key symbol, for the CUSTOMERID field to designate it as the primary key field.

  5. Clear the check box in the automatic updating column for the CUSTOMERID field to prevent it from being modified as the primary key.

  6. Click OK to close the CursorAdapter Builder, and then click OK again to close the DataEnvironment Builder.

    The new cursor adapter, now named Customer, appears in the Data Environment for the form and contains all the fields from the Customer table as specified.

You can set additional options for how the cursor adapter updates the data source. However, this walkthrough uses the default settings for these options.

For more information, see Auto-Update Tab, CursorAdapter Builder.

Using the Cursor Adapter on the Form

After creating the cursor adapter in the form's data environment, you can drop the cursor adapter on the form to create a grid.

To create a grid using the created cursor adapter

  1. In the form's data environment, click and drag the Customer cursor adapter to the form to create a grid.

    If you are using the XML data source type, type the following code in the form's Init event to create and configure the XMLAdapter object:

    Copy Code
    LOCAL oXMLAdapter as XMLAdapter
DODEFAULT()
ThisForm.AddProperty('oXMLAdapter',CREATEOBJECT('XMLAdapter'))
WITH ThisForm.oXMLAdapter
   .LoadXml(ThisForm.cRunPath+'getcustomers.xml',.T.)
ENDWITH
ThisForm.DataEnvironment.cursor1.SelectCmd="ThisForm.oXMLAdapter.Tables.Item(1)"
ThisForm.DataEnvironment.cursor1.CursorFill()
GO TOP
ThisForm.BindControls = .T.
ThisForm.grdCustomer.AutoFit()

  2. In the Properties window, set the form's BindControls property to False (.F.).

  3. Save the form in the ...\Samples\Solution\Toledo folder.

  4. On the Visual FoxPro toolbar, click the Run (!) button to run the form.

The form appears and displays a grid that contains the following:

  • Native, ODBC, and ADO data source types: Data from the fields in the CUSTOMER table.

  • XML data source type: Data loaded from the XML DataSet, GetCustomer.xml.

    When using XML adapters with cursor adapters, you can generate XML DiffGrams using the XML adapter created. For example, the following code creates an XML DiffGram string in a local variable called lcXML:

    Copy Code
    LOCAL lcXML, llIncludeBefore, llChangesOnly, llIsFile, lcSchemaLocation
WITH ThisForm.oXMLAdapter
...* Release XML document but preserve schema.
....ReleaseXML(.F.)
....UTF8Encoded = .T.    && Indicates international characters.
....IsDiffgram = .T.       && Generate XML DiffGram.
...llIncludeBefore = .T. && Include <diffgram:before> format.
...llChangesOnly = .T.   && Generate only changes made.
...llIsFile = .F.        && Sample XML is a stream.
...lcSchemaLocation = "" && Sample schema is inline.
....ToXML("lcXML",lcSchemaLocation,llIsFile,llIncludeBefore,llChangesOnly)
ENDWITH

See Also

Other Resources

Walkthroughs
Manage Data Access Using CursorAdapters Sample
Load and Generate XML Using the XMLAdapter Class Sample


Walkthrough: Creating XML Web Services with Visual FoxPro

Visual FoxPro 9.0 Walkthroughs
Walkthrough: Creating XML Web Services with Visual FoxPro
See Also

XML Web services are the fundamental building blocks for distributed computing on the Internet. An XML Web service is an object or class that is deployed on the Internet and that you can access programmatically through typical method calls. XML Web services provide functionality and access to data between platforms and across diverse connections. The most important aspect of XML Web services is that because of how they use HTTP and SOAP, functionality is available through firewalls. You can call an XML Web service regardless of the platform you are running because HTTP and SOAP operate independently from your computer platform. In some cases, this can provide functionality that was unavailable under distributed COM.

You can create XML Web services or access them on the Web from wherever they are published. You can use Visual FoxPro to create an XML Web service, or you can use Visual FoxPro to access an XML Web service created in other programming languages.

This walkthrough explains how to create a COM Server and publish it as an XML Web service. Additionally, it guides you through using your newly created XML Web service. The XML Web service provides a list of customers from a table where the customers meet a certain requirement. The list is sent as an XML string that is then placed into a cursor using the XMLAdapter class.

This walkthrough contains the following sections:

  • Prerequisites

  • Internet Information Services

  • Creating a COM Server

  • Creating and Publishing an XML Web Service

  • Testing an XML Web Service

  • Using an XML Web Service

Prerequisites

This walkthrough requires the following:

  • Microsoft Internet Information Services (IIS)

  • SOAP

  • Visual FoxPro COM Servers

SOAP is automatically installed when you install Visual FoxPro. IIS is an optional component for Windows 2000 and is automatically installed on Windows 2000 Server. IIS serves your XML Web services from your virtual directory to users on the Internet. Its virtual directory references the location on your hard disk where you place your XML Web services. You use Visual FoxPro to create COM objects. After your COM objects are created, you can then use the Visual FoxPro XML Web Service builder to publish them to your virtual directory.

Internet Information Services

IIS provides the reference to the location of your XML Web service to users accessing it from the Internet. To publish an XML Web service, you must create a virtual directory in IIS that contains the necessary Web Services Description Language (.wsdl) files. These files are created by the Web Service Wizard from your COM component.

To create a virtual directory

  1. In the main Visual FoxPro directory ..\Program Files\Microsoft Visual FoxPro VersionNumber, create a folder named Web Services.

  2. In the Windows Control Panel, double-click Administrative Tools, and then double-click Internet Information Services.

    The Internet Information Services window opens, displaying a tree control on the left that displays a list of Internet information services on your computer.

  3. Right-click the Default Web Site node.

  4. Click New, and then click Virtual Directory to open the Virtual Directory Creation Wizard.

  5. Follow the instructions in the wizard, and specify the Web Services folder that you created in step 1 as your virtual directory.

    This virtual directory references the Web Services folder where you will store all the XML Web service files you create.

Creating a COM Server

Because an XML Web service is a dynamic-link Library (.dll) or executable (.exe) file, you must use a COM Server as the basis for your XML Web service. A COM Server in Visual FoxPro is a file with a .dll or .exe extension, containing a custom class based on the Session object. The custom class is specified as OLEPUBLIC when it is defined. This exposes functionality that can be used and reused by other applications through automation.

For this COM Server example, you create a custom class that reports some basic information. You write a program that creates a class with one method, compile the project containing it into a COM Server, and then publish it as an XML Web service.

To create a COM Server

  1. On the File menu in Visual FoxPro, click New.

  2. In the New dialog box, click Project, and then click New file. Save the project as myWServ1.

  3. In the All tab of Project Manager, expand Code, click Programs, and then click New.

  4. Copy the following code into the Editing window.

    Copy Code
    DEFINE CLASS ShowCustomers AS Session OLEPUBLIC
   PROCEDURE CustomersInGermany AS String
      LOCAL loXMLAdapter AS XMLAdapter
      LOCAL lcXMLCustomers AS String

      loXMLAdapter = CREATEOBJECT("XMLAdapter")

      OPEN DATABASE "C:\Program Files\Microsoft Visual FoxPro ;
         VersionNumber\" + "Samples\Northwind\northwind.dbc"

      USE customers
      SELECT * ;
         FROM customers ;
         WHERE country LIKE "Germany%" ;
         INTO CURSOR curCustomers

      loXMLAdapter.AddTableSchema("curCustomers")
      loXMLAdapter.UTF8Encoded = .T.
      loXMLAdapter.ToXML("lcXMLCustomers")

      CLOSE DATABASES ALL

      RETURN lcXMLCustomers
   ENDPROC
ENDDEFINE

    This program defines one class, ShowCustomers, that has one method, CustomersInGermany.

  5. On the File menu, click Save.

  6. In the Save As dialog box, name the program myWServ1, and click Save.

  7. Close the Editing window.

  8. In Project Manager, click Build.

  9. Select Multi-threaded COM server (dll), click OK, and accept the name myWServ1.

Visual FoxPro now compiles the file myWServ1 into a COM Server called myWServ1.dll. You can now publish it as an XML Web service.

Creating and Publishing an XML Web Service

From the myWServ1.dll file, created in the previous procedure, a new Web Services Description Language (.wsdl) file is generated when you publish the XML Web service. The .wsdl file is an XML file that describes the XML Web service and the classes it contains.

To add the components necessary to turn your COM Server into an XML Web service, you must compile the COM Server as an XML Web service. After you specify the settings in the Web Services Publisher, Visual FoxPro creates the SOAP files necessary to turn your COM Server into an XML Web service, publishes them in your virtual directory, and registers your new XML Web service in IntelliSense.

To compile and publish an XML Web service

  1. On the Tools menu, click Task Pane.

  2. In the Task Pane Manager, click XML Web Services.

  3. Under XML Web Service Tools, select Publish Your XML Web Service.

  4. If the file myWServ1.dll is not listed in the COM Server field, click the ellipsis (...) button, and select myWServ1.dll.

  5. Click Advanced to display the Visual FoxPro XML Web Services Publisher dialog box.

  6. Make sure the Listener URI box displays your virtual directory. If it does not, click the ellipsis (...) button, and select your virtual directory.

  7. Click the Methods tab, and make sure that CustomersInGermany is selected.

  8. Click the Namespaces table, replace tempuri.org with your domain in all fields, and click OK.

    If you do not have your own domain, you can leave tempuri.org for this example.

  9. Click OK to close the Visual FoxPro XML Web Services Publisher dialog box.

  10. Click Generate.

    Visual FoxPro generates the XML Web service files. After it is finishes, the XML Web Services Publishing Results dialog box appears, displaying a list of files generated, .wsdl file, ISAPI or ASP listener, and whether the file was generated properly.

At this point, you have created and published your XML Web service. Anyone who has access to the virtual directory you established earlier can use HTTP to access the XML Web service you published.

Testing an XML Web Service

After you have published your new XML Web service, you should test it to make sure it is working correctly. Visual FoxPro provides a mechanism to test XML Web services that is available in the XML Web Service pane in Task Pane Manager. The test mechanism displays any results returned from the XML Web service, XML schemas used, error feedback.

To test a XML Web service

  1. On the Tools menu in Visual FoxPro, click Task Pane.

  2. In Task Pane Manager, click XML Web Services.

  3. Under Explore an XML Web Service, click ShowCustomers in the Service Name box.

  4. In the The following methods are supported by this XML web service box, click CustomersInGermany.

    This box lists all the available methods on the XML Web service.

  5. Click Test this XML Web Service.

If testing is successful, the Web Service Test Results window appears. It displays the results from the XML Web service, and you can view the .wsdl file associated with the XML Web service. If there is an error in testing, the Web Service Test Results window displays information on the error.

Using an XML Web Service

You use an XML Web service the same way you would any COM Server: to expose functionality of one application to another. In the following procedure, you create a program (.prg) file to access your XML Web service and use the Toolbox to add the required code that references the XML Web service properly.

To use an XML Web service

  1. On the File menu in Visual FoxPro, click New.

  2. In the New dialog box, select Project, and click New file. Save the project as wsTest.

  3. On the All tab of Project Manager, expand Code, select Programs, and then click NewOn the Tools menu, click Toolbox.

  4. In the Toolbox, click the My XML Web Services.

  5. Click and drag the ShowCustomers XML Web service from the Toolbox to the Editing window.

    This adds the proper code to your XML Web service.

  6. In the Editing window, below the line that reads, "Call your XML Web service here," insert the following code.

    Copy Code
    LOCAL lcXML, lcAlias AS String
LOCAL loXMLAdapter AS XMLAdapter

lcXML = loShowCustomers.CustomersInGermany

loXMLAdapter = CREATEOBJECT("XMLAdapter")
loXMLAdapter.LoadXML(lcXML)

lcAlias = loXMLAdapter.Tables.Item(1).Alias
loXMLAdapter.Tables.Item(1).ToCursor()

SELECT(lcAlias)
BROWSE
CLOSE DATABASES ALL

  7. On the File menu, click Save.

  8. In the Save As dialog box, name the program WebServiceTest, and click Save.

  9. Close the Editing window.

  10. In Project Manager, select the WebServiceTest program file, and click Run.

    A browse window appears with all the customers from Germany selected in the Northwind database. This cursor was populated from XML provided from your XML Web service using the XMLAdapter class.

For more information on Web Services, see Web Services and Components. For more information on COM Servers, see How to: Create Automation Servers.

See Also

Other Resources

Walkthroughs


Walkthrough: Creating a Visual FoxPro Application Setup Program Using InstallShield

Visual FoxPro 9.0 Walkthroughs
Walkthrough: Creating a Visual FoxPro Application Setup Program Using InstallShield
See Also

When you are ready to distribute an application, you can create a setup program to help your customers install it. This walkthrough explains considerations you should make prior to distributing the application and shows how to create a Setup project, include files and set their properties, and distribute the application files from Setup using InstallShield Express Visual FoxPro Limited Edition.

This walkthrough contains the following sections:

  • Prerequisites

  • Creating the Setup Program Using InstallShield Express

  • Distributing An Application

For more information about distributing applications, see Distributing Applications.

Prerequisites

Visual FoxPro includes the limited edition of InstallShield Express version 5.0, replacing the Setup Wizard found in versions prior to Visual FoxPro 7.0. To learn how to install InstallShield Express Limited Edition on your computer, see How to: Install Additional Applications.

Note:
You can use any setup creation program that uses Microsoft Windows Installer technology to create a Setup program (.msi) or merge modules (.msm) that are compatible with Microsoft Windows Installer. Some distribution scenarios require merge modules in addition to the Visual FoxPro run-time files. For more information, see Visual FoxPro Distribution Scenarios in this walkthrough.

The Windows 2000 Logo guidelines require that setup programs be based on Windows Installer technology. The Windows Installer is part of the Windows 2000 and Zero Administration Windows efforts to reduce the overall cost of deploying, using, and managing desktop computers. Both the limited and full editions of InstallShield Express use Microsoft Installer, which features comprehensive and flexible Setup creation technology. This technology makes it possible for your customers to install and configure your application efficiently.

This walkthrough does not act as a replacement for the InstallShield Express documentation, which you should read first. It is a supplement to assist you in using InstallShield Express to package and distribute applications. You can also download the Platform SDK Components for Windows Installer Developers from the Microsoft download Web site at http://www.microsoft.com/msdownload/platformsdk/sdkupdate/.

You should consider several issues when preparing an application for distribution. In addition to following the procedure outlined in the Application Distribution Process, you must identify the structure of your application; decide how to deliver the application to users, and how to best organize your Setup program. When you have addressed all these issues, you are ready to distribute your Visual FoxPro application.

Creating the Setup Program Using InstallShield Express

Creating the Setup project is the first step in creating a Setup program. The Setup project (.ism) file you create with InstallShield Express is based on the Windows Installer project file. This file stores all the logic and information necessary to build a setup program compatible with Windows Installer.

To create a Setup project

  1. On the Start menu, point to All Programs. Point to InstallShield, and click Express to open InstallShield Express.

  2. On the File menu, click New to open the New Project dialog box.

  3. Browse to the location where you want to save your project, rename the default project file name in the Project Name and Location box, and click OK.

  4. To create your setup program in a language other than English, select an alternate language in the Project Language list.

    Note:
    After you choose a language, you cannot change it for the project.

Defining Project Properties

After you create a Setup project, you can define properties, such as:

  • Product name

  • Product version

  • Product icons

  • Default installation folder for all application files

  • Name and location of a Readme file

At the minimum, you should specify the product name and a default installation folder for your application files. The INSTALLDIR property in InstallShield Express specifies the location of the default installation folder, for example, the application home directory. The location of the default installation folder specified by INSTALLDIR is:

[ProgramFilesFolder]Your Company Name\Your Product Name

Note:
It is recommended that you change Your Company Name and Your Product Name to the appropriate names for your application.

You can also specify a different folder for your application by setting INSTALLDIR to a folder with the name of your application as specified by MyApp in the following example:

[ProgramFilesFolder]\MyApp

If you plan to install any data or database files, you can also edit the DATABASEDIR property to specify the default destination folder for those files.

To specify general information for your Setup project

  1. In the Organize Your Setup node, click General Information.

  2. In the property list, double-click the value field of a property to edit its value.

  3. Click elsewhere in the property list to see your changes take effect.

Dividing Your Product into Features

From the perspective of the application user and InstallShield Express, a feature is considered a building block of an application. Features make it possible for users to install parts of an application. For example, during Visual FoxPro installation, you can specify whether to install the Visual FoxPro Samples and Visual FoxPro Tools as features.

Note:
Dividing your product into features is not required when creating a Setup program, although it can be helpful to users.

The default setting for installing features is Always Install, which lists the components that install with all Setup Types.

To create a feature

  1. In the Organize Your Setup node, click Features.

  2. To add a new feature, right-click the Features node in the tree view in the middle pane, and click New Feature Ins.

  3. Type a name for the new feature, and press ENTER.

When you have identified the your product features, you can set feature properties, such as feature description, how the feature is advertised, and whether the feature is required. Although advertised features appear to be installed to the user, they are not installed during setup. Windows Installer installs the advertised feature when the user tries to use the feature for the first time.

To set a feature property

  1. Select the feature for which you want to modify properties.

  2. In the property list, double-click the value field of the property to edit its value.

    To display more options, click the ellipsis (...) or arrow button that appears next to the property value field when additional options are available.

  3. Type or select a new value for the property.

For example, suppose you wanted to provide the option of installing the Help file for your application. Follow the steps to create the feature, and name it "Help file." If you want to make the Help file installation optional, set the Required property to No. If you want the feature to be installed the first time the user tries to invoke the feature by pressing F1 for Help, set the Advertised property to Yes.

Specifying Features for a Setup Type

You can include different Setup types in a Setup program and specify which features each Setup type should install. Setup types offer different levels of installation that the user can choose:

  • Typical Setup installs all features and files.

  • Minimal Setup installs the minimum number of features and files necessary for an application to function.

  • Custom Setup makes it possible to specify which features to install.

You must include at least one Setup type.

All three Setup types install features listed by Always Install. For example, a basic Setup includes features listed by Always Install and the &Typical Setup type. The ampersand (&) in the Setup type name indicates the access key for a particular Setup type in the Setup user interface. You can include or remove Setup types depending on whether you want it included, as long as one remains available, or rename the Setup types.

Note:
Specifying features for each Setup type is not required when creating a Setup program.

To select Setup types and specify features for each Setup type

  1. In the Organize Your Setup node, click Setup Types.

  2. In the Setup Types pane, select the check box for each Setup type you want to include.

  3. In the Features installed for <selected> setup type pane, select the check box for each feature you want to this Setup type to install.

Adding Files to Setup

The executable (.exe) file is usually needed for the user to start an application. You can add this file first along with other files your application requires, followed by any optional files.

Visual FoxPro provides resource files that extend the basic functionality of your applications, including FoxUser resource files, API libraries, and Microsoft ActiveX controls. If you use these files, you must add them to the Setup program so they can be installed when running Setup. For more information about resource files that you can use, see Resource Files in Applications.

To view files you can add to Setup

  • In the Specify Application Data node, click Files.

The Files view is divided into four panes. The left panes display folders on the source and destination computers. The right panes display the files in those folders. The Feature box appears above the four panes.

Note:
The INSTALLDIR property specifies the directory containing the root folder for your application files and is usually specified as the destination installation directory.

Before adding files to the Setup project, you must specify the feature to associate those files with by selecting it in the Feature box.

Note:
Add required files as Always Install features.

Make sure the feature appears in the Feature box. After selecting the feature, you can add files to the Setup project by copying them from the source folders to the folders on the destination computer.

To add files from the source folder to the destination folder

  1. In the Destination computer's folders pane, select the destination folder where you want to install the application file.

  2. In the Source computer's files pane, drag the source file to the destination folder.

    Note:
    The folder specified by INSTALLDIR in the General Information node as the default installation directory should appear in the Destination computer's folders pane. Dragging the source file to the destination folder only instructs InstallShield Express where to locate the source file when you build your Setup program. It does not move or remove any files on the source computer.

You can also view a list of predefined folders, such as the desktop folder, that you can select and add to the list of destination computer folders.

To view and add predefined folders

  1. In the Destination computer's folders pane, right-click Destination Computer.

  2. Click Show Predefined Folders.

  3. Select the folder you want to add.

    The folder appears in the list of destination computer folders.

You can create one or more subfolders in a destination folder.

To create a subfolder in a destination folder

  1. Right-click the destination folder, and click Add.

  2. Type a name for the new folder, and press ENTER.

Registering Files

Windows Installer includes the following capabilities:

  • Roll back an unsuccessful installation, returning the target computer to its preinstallation state.

    For example, COM Servers, such as ActiveX, COM, and COM+ files, require special registration so applications can access their interfaces. These .ocx, .exe, and .dll files traditionally contained self-registration functions that can be invoked to register the files during installation. However, relying on self-registration can cause some problems with Windows Installer.

    Note:
    When registering a COM Server, it is highly recommended that you select Extract COM Information instead of Self-registration as the registration type for the file. If you select Self-registration, Windows Installer will not have the information needed to remove the COM Server from the registry properly.

    With traditionally scripted Setup programs, self-registration was acceptable for installing COM objects and is still valid. However, self-registering COM objects do not pass their installation and registration information to Windows Installer. Therefore, Windows Installer cannot roll back installation and registration of self-registered COM objects or advertise those objects.

  • Advertise installed products or individual product elements, such as COM objects.

    Advertising makes a product or COM object available to the user or target computer without installing the product until the user or another computer function attempts to access the advertised element. Advertisement occurs by placing a shortcut in the appropriate location such as the Start menu or registry.

To register a COM server with InstallShield Express

  1. In the Specify Application Data node, click Files.

  2. Copy the file for the COM Server from the source folder to the destination folder.

  3. Right-click the file you want to register, and click Properties.

  4. In the Properties dialog box, click the COM & .NET Settings tab.

  5. Select a Registration Type.

For more information registering COM Servers, see Visual FoxPro Distribution Scenarios.

Selecting Objects and Merge Modules

A merge module (.msm file) contains all of the logic, registry entries, and files needed to install an application or run-time files successfully. If you were to install your application manually, you would need to copy the Visual FoxPro run-time files to the destination computer and register those files. However, if you select the Microsoft Visual FoxPro 9 Runtime Libraries merge module, InstallShield Express copies and registers the run-time files properly.

For a Visual FoxPro application, you should select, at the minimum, the Microsoft Visual FoxPro 9 Runtime Libraries and MSXML 4.0 modules. For more information about Visual FoxPro run-time libraries, see Visual FoxPro Run-Time Libraries.

Note:
When you select the Microsoft Visual FoxPro 9 Runtime Libraries module in InstallShield Express, the check boxes for the Microsoft Visual C Runtime Library 7.1 and GDI Plus Redist modules are automatically selected and should remain selected. Visual FoxPro 9.0 requires these modules; therefore, do not clear selection of these modules.

There are two MSXML 4.0 modules that should be included:

  • MSXML 4.0 (msxml4sxs32.msm)

  • MSXML 4.0 (msxml4sys32.msm)

You should also include the Microsoft Visual FoxPro 9 Report Applications merge module which contains runtime applications used by the Visual FoxPro 9.0 reporting engine. For more information, see Including Report Files for Distribution.

If your application uses one of the CURSORTOXML functions, you should also include the MSXML 3.0 merge modules. These include the following:

  • MSXML 3.0 (msxml3_wim32.msm)

  • Msxml3 Exception INF Merge Module (msxml3inf_wim32.msm)

  • WebData std library (wdstddll_wim32.msm)

If you are deploying your application internationally, you may need to include one or more of the Microsoft Visual FoxPro 9 Resource language modules.

To select objects and merge modules for installation

  1. In the Specify Application Data node, click Redistributables.

  2. In the InstallShield Redistributables pane, select the check box for each merge module you want to install.

  3. You can install a merge module feature by feature by selecting or clearing the check boxes in the Conditional Installation pane when available.

For more information on merge modules, see Visual FoxPro Distribution Scenarios.

Creating Shortcuts and Folders

InstallShield Express makes it possible for you to create shortcuts and folders in the Start menu and on the desktop.

To create folders or shortcuts

  1. In the Configure the Target System node, click ShortCuts/Folders.

  2. From the Shortcuts tree view in the middle pane, right-click the node where you want to install a shortcut or folder, and click New Shortcut or New Folder.

  3. If you created a shortcut, you must specify a target file. In the Browse for Shortcut Target dialog box, double-click the file for which you want to create a shortcut in the Look in list.

    You can also associate your shortcut with a feature by navigating to the folder containing the file associated with the feature and selecting the file from the list.

  4. Type a name for the shortcut or folder, and press ENTER.

    To rename the folder or shortcut right-click it, click Rename, type a new name, and press ENTER.

    Note:
    Files for your application are at the bottom of the Look in list.

Creating Registry Keys

If your application uses registry keys, for example, to keep track of user options, InstallShield Express can add them to the target computer during setup. If the keys do not exist on the development computer, you can create them manually.

Note:
Creating registry keys is not required when creating a Setup program.

Registry entries are created in registry hives. Registry hives categorize registry entries by function. For example, COM Server classes are stored in the HKEY_CLASSES_ROOT registry hive. Software options, such as options for Visual FoxPro, are stored in the Software folder in the HKEY_CURRENT_USER hive.

To create registry keys

  1. In the Configure the Target System node, click Registry.

  2. In the Destination computer's Registry view pane, right-click the desired registry hive.

  3. On the shortcut menu, point to New, and click Key.

  4. Type a name for the key, and press ENTER.

  5. Right-click the new key, point to New, and select the type of value you want to add to the key.

  6. In the Destination computer's registry data pane, double-click the key to enter a data value.

    Depending on the type of key, you can enter a name for it.

Creating Open Database Connectivity (ODBC) Data Source Names (DSNs)

If the development computer has previously existing DSNs, you can instruct InstallShield Express to install the DSN on the destination computer. If you are installing DSNs, you should include the MDAC merge module when selecting merge modules in case the destination computer does not have ODBC components installed.

Note:
Creating ODBC DSNs is not required when creating a Setup program.

To create DSNs

  1. In the Configure the Target System node, click ODBC Resources.

  2. In the ODBC Resources tree view, select the check boxes for the DSNs you want to create on the destination computer.

Customizing Setup Appearance

You can select and change the appearance of dialog boxes that users see when installing your application. You can specify bitmap (.bmp) images for each dialog box and add additional dialog boxes, for example, to allow the user to specify a destination folder.

Note:
Customizing Setup appearance is not required when creating a Setup program.

To select dialog boxes

  1. In the Customize the Setup Appearance node, select Dialogs.

  2. In the Dialogs tree view, select the dialog boxes you want to display during installation.

    When you select a dialog box, an image of the dialog box appears in the lower-left pane, and properties for the dialog box appear in the upper-right pane.

To make it possible for the user to specify a destination folder

  1. In the Customize the Setup Appearance node, select Dialogs.

  2. In the Dialogs tree view, click Destination Folder.

Building Your Setup Program

After you have finished designing and setting the properties for all the elements in your Setup project, including the features, files, shortcuts, registry entries, and user interface, you are ready to build your Setup program.

The most commonly selected build types are CD-ROM or single image. Selecting CD_ROM creates a Setup program that contains files organized in a directory structure. Selecting SingleImage combines the files into a single file.

To build a Setup program

  1. In the Prepare for Release node, click Build Your Release.

  2. In the Builds tree view, select the type of media you want to build.

  3. In the property list, set or edit the build properties.

  4. To build your Setup program, right-click the selected media type, and click Build.

    InstallShield Express places the built Setup package into the following folder:

    <project directory>\Express\<media type>\DiskImages\DISK1

Testing Your Setup Program

It is important to test your Setup program. You can do so without running the actual installation using InstallShield Express.

To test your Setup program with InstallShield Express

  1. In the Prepare for Release node, click Test Your Setup.

  2. In the Builds tree view, select the media type containing the build you want to test.

  3. If you want to run the Setup program and install your application and its files on the development computer, click Run Your Setup.

    -or-

    If you want to test only the Setup dialog boxes and any custom actions you have chosen, click Test Your Setup.

    This option does not install any files or make any system changes.

Distributing an Application

After building and testing your Setup program, you are ready to distribute it.

To distribute your Setup program

  1. In the Prepare for Release node, click Distribute Your Release.

  2. In the Builds tree view, select the media type containing the build you want to distribute.

  3. Enter the location, or click Browse and navigate to the location where your Setup package will be copied.

  4. Click Distribute to Location.

You can also copy your Setup package to an FTP location.

For additional information and options for distributing applications, see the InstallShield Express documentation.

This walkthrough assumes you are installing a simple Visual FoxPro application that does not have dependencies other than the Visual FoxPro Runtime Libraries. The following information includes instructions needed for distribution scenarios other than installing only Visual FoxPro applications and their native data. For these scenarios, add the following appropriate merge modules when selecting objects and merge modules for your Setup program.

Web Services and SOAP

If your application uses Web services or SOAP, you must include the following merge modules:

  • SOAP SDK Files (Soap_Core.msm)

  • Visual Basic Virtual Machine (MSVBVM60.msm)

  • Microsoft Component Category Manager Library (Comcat.msm)

  • Microsoft OLE 2.40 (OLEAUT32.msm)

Applications using Visual FoxPro Report Application Components

If your application uses the default Report Builder Application, Report Output Application, or Report Preview Application, and you want to ensure that these components are available to your application by default, include the following merge module:

  • Visual FoxPro 9 Report Applications (vfp9rptapps.msm)

For more information, see Including Report Files for Distribution.

Microsoft Visual FoxPro OLE DB Provider

The Visual FoxPro OLE DB Provider makes it possible for both Visual FoxPro and other applications to access Visual FoxPro data using OLE DB or ActiveX® Data Objects (ADO). To install the Visual FoxPro OLE DB Provider on the destination computer, include the Microsoft Visual FoxPro OLE DB Provider (VfpOLEDB.msm) merge module.

ActiveX Controls

ActiveX controls are a common element of many Visual FoxPro applications. To include ActiveX controls with your InstallShield Express Setup, you should include the Microsoft Component Category Manager Library (Comcat.msm) merge module.

Note:
Windows 2000 and Windows XP also install files in this merge module.

The ActiveX controls you install affect the type of merge modules you need to install and the extra steps you must take to install them.

  • Common ActiveX Controls

    These are common ActiveX controls that ship with Visual FoxPro and Microsoft Visual Studio. InstallShield Express ships with merge modules for most of these controls.

    If necessary, add the appropriate merge module for the needed control. For example, if your application uses the Treeview control, you should include the MSCOMCTL.msm merge module.

    Note:
    The Common ActiveX Controls included in the InstallShield Express merge modules contain registration information that is compliant with Windows Installer.

  • Microsoft Foundation Class (MFC) Controls

    Some older controls, such as the Calendar control, use the MFC libraries; therefore, it is recommended that you include the appropriate MFC merge modules, such as MFC42.msm. As with VBCCE controls, you must add the control manually to the project and set various settings.

  • Third-party controls

    Be sure to register any included third-party controls. In addition, you might need to add specific registry keys using the InstallShield Express Registry window for any necessary licensing requirements.

    For more information about third-party controls, see the documentation provided by the vendor about how and where to install these controls. Third-party control documentation should also provide information about any needed dependency files, such as MFC files.

To make sure that Windows Installer can roll back or advertise installed files, you must install files in a manner compliant with Windows Installer requirements. Self-registration of files is not compliant with Windows Installer requirements. You can make sure InstallShield Express installs COM objects that are compliant with Windows Installer by following the instructions about registering files in this topic. For more information, see the InstallShield Express online documentation.

Applications Using HTML Help

The Microsoft Visual FoxPro HTML Help Support Library (VFP9HTMLHelp.msm) merge modules include both FOXHHELP9.exe and FOXHHELPPS9.dll files needed to support context-sensitive HTML Help within your Visual FoxPro applications.

In addition to your application-specific .chm file, you can include the core HTML Help viewer files. Later versions of Microsoft Internet Explorer include these files. You also can distribute them with the HHUPD.exe file available on the Microsoft Developer Network (MSDN).

Applications Using MDAC Components

For Visual FoxPro applications running on operating systems earlier than Windows 2000 or Windows XP, it is recommended that you include the Microsoft Data Access Components (MDAC) merge module (MDAC25.msm) if your applications use any of the following data components:

  • ODBC drivers, including Microsoft Visual FoxPro ODBC Driver (VFPODBC.msm)

  • OLE DB Provider

  • ADO, RDS

COM Servers

The Windows Installer rollback and advertising features make it possible to undo component installation and registration if the product installation does not succeed. However, you must install and register COM objects correctly to make these features available. To register installed COM objects correctly, set the Registration Type to Extract COM Information. Self-registering installed COM objects sacrifices Windows Installer rollback and advertising functionality.

For more information, see the instructions about registering files in this topic.

Localized Applications

The Visual FoxPro Runtime Libraries (VFP9Runtime.msm) contain the standard language-neutral resource file (VFP9renu.dll) used for shipping all English (US) applications. If you want to include support for another localized resource file (VFP9Rnnn.dll), include the appropriate Microsoft Visual FoxPro Resource merge module that contains the localized resource file you want.

Note:
Localized resource files do not localize Setup dialog boxes. You can select the desired language for Setup dialog boxes when you create your Setup project.

To include a localized Visual FoxPro resource file

  1. In the Specify Application Data node, click Redistributables.

  2. To identify the Microsoft Visual FoxPro Resource merge module you want, look at the description for each merge module in the lower-left pane.

  3. Select the merge module you want.

    For example, to include the German resource file, select the VFP9rdeu.msm merge module. The following table lists available merge modules containing the corresponding localized resource files.

    Language Merge Module

    Chinese, Simplified

    VFP9rchs.msm

    Chinese, Traditional

    VFP9rcht.msm

    Czech

    VFP9rcsy.msm

    French

    VFP9rfra.msm

    German

    VFP9rdeu.msm

    Korean

    VFP9rkor.msm

    Russian

    VFP9rrus.msm

    Spanish, International Sort

    VFP9resn.msm

See Also

Other Resources

Walkthroughs
Resource Files in Applications
Distributable and Restricted Visual FoxPro Features and Files


Reference (Visual FoxPro)

Visual FoxPro 9.0
Reference (Visual FoxPro)

The Visual FoxPro reference topics describe the commands, controls, objects, properties, methods, events, statements, functions, constants and productivity tools available.

In This Section

General Reference

Includes Visual FoxPro-related technical information, including file types, file structures, and other reference information about Visual FoxPro elements.
Language Reference

Provides a list of language reference topics in alphabetical order.
User Interface Reference

Explains the options that appear on various dialog boxes, windows, and other user interfaces. Generally, these topics appear when you press F1 in a dialog box or window.
Error Messages

Provides information about some of the more common error messages in Visual FoxPro.

Related Sections

Microsoft Visual FoxPro 9.0

Provides links to additional resources available to the Visual FoxPro application developer.
Getting Started with Visual FoxPro

Provides information about installing, upgrading, and configuring Visual FoxPro, as well as customizing the development environment.
Using Visual FoxPro

Gives an overview of Visual FoxPro features, concepts, and productivity tools for developing and managing high-performance database applications and components.
Samples and Walkthroughs

Provides code samples that you can use for experimenting and becoming acquainted with features.
Product Support

Provides information about the various technical support options available for Visual FoxPro.


General Reference

Visual FoxPro 9.0
General Reference

This section contains more general technical information, including file types, file structures, and other reference information about Visual FoxPro elements.

In This Section

Data and Field Types

Provides links to information about data types used in Visual FoxPro and conversions to other data types, such as XML Schema data types.
Data Manipulation

Provides information on expressions that you can build to get full access to the power of manipulating data in Visual FoxPro.
Data Storage Containers

Discusses how you determine which type of data storage container to use and summarizes the scope differences between different data containers.
Building Expressions

Provides information on how Visual FoxPro expressions combine data and operators to create a value of a given data type.
File Structures

Contains technical information about file structures and file types.
Fonts Overview

Shows how Visual FoxPro can use the fonts you have installed to determine the appearance of displayed or printed text as well as the position and size of controls.
Graphics Support in Visual FoxPro

Discusses Graphics Device Interface+ (GDI+), the graphics device interface for Microsoft Windows XP and future releases of the Windows operating system. Visual FoxPro supports all graphics formats that GDI+ supports.
Keyboard Shortcuts

Provides information on keyboard shortcuts supported in Visual FoxPro.
MemberData Extensibility

Discusses extensibility model for design time use of meta data with class members.
Naming Conventions

Discusses the choice of names for exposed objects, properties, and methods that can be understood by users of the application easily.
Regular Expressions and Operators

Describes regular expressions and operators, which are symbols that you can use to create more complex searches for finding and replacing patterns of text.
Reserved Words

Provides a list of reserved words that you should avoid using as names when programming.
String and Value Comparison in Visual FoxPro

Describes operators you can use to compare strings and values.
System Menu Names

Provides a list of the internal names and user interface names for the Visual FoxPro system menu bar, menu titles, menus, and menu items. With these names, you can use the Visual FoxPro system menu bar to create a menu system for your own application.
Visual FoxPro and Other Programming Languages

Provides a comparison of Visual FoxPro language elements with other programming languages.
Visual FoxPro System Capacities

Lists the maximum and minimum system limits for Visual FoxPro table and index files, field characteristics, variables and arrays, program and procedure files, Report Designer capacities, and so on.
XSource Folder

Lists the .zip files in the XSource folder that expand into the Solution Sample HTML Help files and folders that contain other additions to Visual FoxPro, such as the Addlabel, Browser, Builder, Coverage, and Wizards source files.

Related Sections

Reference

Includes topics on productivity tools, as well as the controls, objects, properties, methods, events, statements, functions, and constants available.
User Interface Reference

Explains the options that appear on various dialog boxes, windows, and other user interfaces. These types of topics generally appear when you press F1 in a dialog box or window.
Error Messages

Provides information about some of the more common error messages in Microsoft Visual FoxPro.
Using Visual FoxPro

Gives an overview of Visual FoxPro features, concepts, and productivity tools for developing and managing high-performance database applications and components.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Data and Field Types

Visual FoxPro 9.0
Data and Field Types

This section contains a list of data types and functions you can use to operate on data types.

In This Section

Visual FoxPro Data and Field Types

Provides information about Visual FoxPro data types, including descriptions and permissible values and the range and size of those values.
XML Data in Visual FoxPro

Introduces XML data in Visual FoxPro.
Visual FoxPro and XML Schema Data Type Mapping

Describes XML Schema data types and shows how they map to Visual FoxPro data types and the reverse.
Blob Data Type

Describes the Blob data type, which stores binary data with indeterminate length.
Character Data Type

Describes the Character data type, which stores alphanumeric text. The Character (Binary) field type stores alphanumeric text that you do not want translated across code pages.
Currency Data Type

Describes the Currency data type, which stores monetary values or precise financial calculations.
Date Data Type

Describes the Date data type, which stores date values without time values.
DateTime Data Type

Describes the DateTime data type, which stores both date and time values or only date values.
Double Field Type

Describes the Double field type, which offers more precision than the Numeric type.
Float Field Type

Describes the Float data type, which is included for compatibility and is functionally equivalent to Numeric.
General Field Type

Describes the General field type, which stores OLE objects.
Integer Field Type

Describes the Integer field type, which stores non-decimal numeric values and can be used when performance and table storage limitations are important.
Logical Data Type

Describes the Logical data type, which provides an efficient way to store data that has only two values.
Memo Field Type

Describes the Memo field type, which stores blocks of data. The Memo (Binary) version of the Memo field type stores blocks of data that you do not want translated across code pages.
Numeric Data Type

Describes the Numeric data type, which stores values indicating magnitude.
Varbinary Data Type

Describes the Varbinary data type, which stores binary values and literals with fixed length without additional padding and truncating spaces.
Varchar Field Type

Describes the Varchar field type, which stores alphanumeric text without additional padding and truncating trailing spaces. The Varchar (Binary) field type stores alphanumeric text that you do not want translated across code pages and without additional padding and truncating trailing spaces.
Variant Data Type

Describes the Variant data type, which stores any kind of data except fixed-length data.

Related Sections

General Reference

Includes Visual FoxPro-related technical information, including file types, file structures, and other reference information about Visual FoxPro elements.
Language Categories

Contains a list of language functionality and descriptions.
Using Visual FoxPro

Discusses how Visual FoxPro programming features are designed to improve developer productivity, including Access and Assign methods, support for more graphic file formats, and language to simplify programming tasks.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Visual FoxPro Data and Field Types

Visual FoxPro 9.0
Visual FoxPro Data and Field Types
See Also

All data in Visual FoxPro have a particular data type, which defines values permitted for the data and the range and size of those values. After you identify and specify the data type you are using, Visual FoxPro can efficiently store and manipulate the data.

When you create a table, you can specify the type of data to store in each field of the table. You can specify more data types for fields in a table than for variables and arrays. Variables and arrays can store only a subset of the available Visual FoxPro data types; however. The value you store in a variable or array element determines the type of data in the variable or array element. For more information, see How to: Choose Data Types.

Tip:
You can use the TYPE( ) function to determine the type of data stored in a variable, array element, or field.

Visual FoxPro Data Types

Data type | Description | Size | Range
Blob | Binary data of indeterminate length. Blob values are in a memo (.fpt) file. No code page translation is performed on Blob data. | 4 bytes in a table | Limited by available memory and/or 2GB file size limit.
Character | Alphanumeric text For example, a customer address | 1 byte per character to 254 | Any characters
Currency | Monetary amounts For example, the price of an item | 8 bytes | - $922337203685477.5807 to $922337203685477.5807
Date | Chronological data consisting of month, day, and year For example, an order date | 8 bytes | When using strict date formats, {^0001-01-01}, January 1st, 1 A.D to {^9999-12-31}, December 31st, 9999 A.D.
DateTime | Chronological data consisting of month, day, year, hours, minutes, and seconds For example, date and time of arrival | 8 bytes | When using strict date formats, {^0001-01-01}, January 1st, 1 A.D to {^9999-12-31}, December 31st, 9999 A.D., plus 00:00:00 a.m. to 11:59:59 p.m.
Logical | Boolean value of True or False For example, whether or not an order has been filled | 1 byte | True (.T.) or False (.F.)
Numeric | Integers or decimal numbers For example, the quantity of items ordered | 8 bytes in memory; 1 to 20 bytes in table | - .9999999999E+19 to .9999999999E+20
Varbinary | Binary values. Varbinary data is similar to Varchar data in that values do not include padding with zero (0) bytes. The length of the contained value is stored internally. No code page translation is performed on Varbinary data. | 1 byte per hexadecimal value up to 255 total bytes | Any hexadecimal value
Variant | Variant data can be any of the Visual FoxPro data types and the null value. Once a value is stored to a variant, the variant assumes the data type of the data it contains. Variants are designated with an e prefix in language syntax. | See other data types. | See other data types.

In addition, Visual FoxPro provides data types that apply only to fields in tables.

Visual FoxPro Field Types

Field type | Description | Size | Range
Character (Binary) | Any Character data that you do not want translated across code pages For example, user passwords stored in a table and used in different countries or regions. | 1 byte per character to 254 | Any characters
Double | A double-precision floating-point number For example, scientific data requiring a high degree of precision. | 8 bytes | +/-4.94065645841247E-324 to +/-8.9884656743115E307
Float | Same as Numeric | 8 bytes in memory; 1 to 20 bytes in table | - .9999999999E+19 to .9999999999E+20
General | Reference to an OLE object For example, a Microsoft Excel worksheet. | 4 bytes in table | Limited by available memory.
Integer | Numeric value with no decimals For example, a line number in an order. | 4 bytes | -2147483647 to 2147483647
Integer (Autoinc) | Same as Integer but also an automatically incrementing value. Read-only. | 4 bytes | Value controlled by autoincrement Next and Step values.
Memo | Alphanumeric text of indeterminate length or reference to a block of data For example, notes about a phone call in a phone log. | 4 bytes in table | Limited by available memory.
Memo (Binary) | Same as Memo except that memo field data does not change across code pages For example, a login script used in different countries or regions. | 4 bytes in table | Limited by available memory.
Varchar | Alphanumeric text. Varchar is similar to Character except values in Varchar fields do not include padding with additional spaces. The length of the contained value is stored internally. | 1 byte per character up to 254 total bytes | Any characters
Varchar (Binary) | Varchar type data that you do not want translated across code pages. | 1 byte per character up to 254 total bytes | Any characters

Each data type has its own characteristics, including storage size:

To see a list of the functions you can use with each data type, see Language Categories.

See Also

Other Resources

Data and Field Types


XML Data in Visual FoxPro

Visual FoxPro 9.0
XML Data in Visual FoxPro
See Also

You can work with XML data in Visual FoxPro by importing or exporting XML documents using the Visual FoxPro functions or XMLAdapter objects. The following sections introduce valid, or "well-formed", XML documents and XML schemas, which help explain requirements for working with XML data in Visual FoxPro:

  • Well-Formed XML Docments

  • Support for XML Schemas

Well-Formed XML Docments

XML documents are valid when they are "well-formed". Visual FoxPro produces XML documents that are well-formed. A well-formed document conforms to the basic rules of XML:

  • Each XML document must have a unique root element, which is an element that encompasses the entire document.

  • All start and end tags match. XML tags are case-sensitive.

  • For each start tag, a corresponding end tag exists. A special shorthand tag can denote empty elements.

  • Elements do not overlap. In other words, start and end tags must be properly nested within other elements.

  • Certain reserved characters are part of the XML syntax and are not interpreted as they are if used in the data portion of an element. The following table lists special character sequences, or entities, used to substitute for these reserved characters.

    Character Data type Entity encoding

    & (ampersand) < (left angle bracket) > (right angle bracket) " (quotation mark) ' (apostrophe)

    String String String String String

    Replace with &amp; Replace with &lt; Replace with &gt; Replace with &quot; Replace with &apos;
    For other data types, the following table lists rules for entity encoding.

    Data type Character and entity encoding

    Date

    Must follow the ISO 8601 format

    Numbers

    Punctuation must use U.S. English rules. For example, you must use a period as a decimal separator. Numbers can include exponents.

    Boolean

    False = 0, True = 1. (SQL XML returns 0 and1)

    BLOB

    Use MIME Base64 encoding

The following example shows a well-formed XML document:

Copy Code
<?xml version="1.0"?>
<Data>
<ORDER>
 <CUSTOMER>Mary Baker</CUSTOMER>
  <ITEM>Coho Winery&apos;s Chablis</ITEM>
 <PRICE>$10.00</PRICE>
 <QUANTITY>1 Bottle</QUANTITY>
 </ORDER>
</Data>
Tip:
You can use white space throughout the document to enhance readability.

In the example, the code illustrates certain parts of the XML document:

  • <?xml version="1.0"?>

    Declares the XML document and provides the version number. This declaration is optional but recommended in any XML document.

  • <ORDER>

    Specifies the root element that encompasses the entire document.

  • <CUSTOMER> ... </CUSTOMER>

    Specifies a start and end tag set, which describes an element of data, in this case, the customer's name.

    Note:
    Each tag set has both start and end tags, is case sensitive, and is properly nested. When the data is imported by the receiving application, the entity &apos is transformed to an apostrophe ('). The apostrophe has a special purpose in an XML document and might be misinterpreted if used directly in text. The converted data is displayed as Coho Winery's Chablis.

Support for XML Schemas

XML schemas can help define the rules and structure for XML documents. Visual FoxPro can interpret XML files with or without schemas. However, Visual FoxPro supports XML Schema Definition (XSD), which is a basic infrastructure for describing the type and structure of XML documents. An XML schema definition serves several purposes:

  • Describes the structure of data in a common format that customers, other Web browsers, and any number of XML-enabled software programs can recognize.

  • Defines the rules of an XML data document, including element names and data types, which elements can appear in combination, and which attributes are available for each element.

  • Provide a model for an XML data document by defining the arrangement of tags and text within all documents referencing the schema.

By using an XML schema, you can ensure that any XML document used to import or export data contains specific data and conforms to a defined structure. When you specify a schema when exporting XML from Visual FoxPro, the exported XML documents are considered valid XML. This means that in addition to being well-formed, the documents conform to a defined schema. You can also provide a schema to other businesses and applications so that they can structure XML data they provide to you as well as provide their schema to you.

In particular, Visual FoxPro supports the W3C XSD schema format. The XSD schema format is based on the W3C Recommendation of the XSD Schema specification. For more information, see http://www.w3.org/TR/2001/REC-xmlschema-0-20010502/ and related documents.

See Also

Other Resources

Converting Between XML and Visual FoxPro Data
XML Functionality Using XMLAdapters
XML Functions
Data and Field Types


Visual FoxPro and XML Schema Data Type Mapping

Visual FoxPro 9.0
Visual FoxPro and XML Schema Data Type Mapping
See Also

The following tables describe the following default data type mappings between Visual FoxPro and XML schema data types:

  • XML Schema Primitive Data Types to Visual FoxPro Data Types

  • XML Schema Derived Types to Visual FoxPro Data Types

  • Visual FoxPro Data Types to XML Schema Definition (XSD) Data Types

  • XML Schema Definition (XSD) Data Types to Visual FoxPro Data Types

  • XML Data Reduced (XDR) Schema Data Types to Visual FoxPro Data Types

XML Schema Primitive Data Types to Visual FoxPro Data Types

XML data type Facets Description Visual FoxPro data type

anyURI

length, pattern, maxLength, minLength, enumeration, whiteSpace

Represents a Uniform Resource Identifier (URI) as defined by RFC 2396. An anyURI value can be absolute or relative and might have an optional fragment identifier.

Memo. Visual FoxPro applies a hyperlink to a URI in a Memo.

base64Binary

length, pattern, maxLength, minLength, enumeration, whiteSpace

Represents base64-encoded arbitrary binary data. A base64Binary is the set of finite-length sequences of binary octets.

Memo (Binary), Varbinary or Blob

boolean

pattern, whiteSpace

Represents Boolean values, which are either true or false.

Logical

date

enumeration, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents a calendar date. The pattern for date is CCYY-MM-DD with an optional time zone indicator as allowed for dateTime.

Date

dateTime

enumeration, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents a specific instance of time.

The pattern for dateTime is CCYY-MM-DDThh:mm:ss where CC represents the century, YY the year, MM the month, and DD the day, preceded by an optional leading negative (-) character to indicate a negative number. If the negative character is omitted, positive (+) is assumed. The T is the date/time separator and hh, mm, and ss represent hour, minute, and second respectively. Additional digits can be used to increase the precision of fractional seconds if desired. For example, the format ss.ss... with any number of digits after the decimal point is supported. The fractional seconds part is optional.

This representation may be immediately followed by a "Z" to indicate Coordinated Universal Time (UTC) or to indicate the time zone. For example, the difference between the local time and Coordinated Universal Time, immediately followed by a sign, + or -, followed by the difference from UTC represented as hh:mm (minutes is required). If the time zone is included, both hours and minutes must be present.

DateTime

decimal

enumeration, pattern, totalDigits, fractionDigits, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents arbitrary precision numbers.

Numeric, Currency, or Character

double

pattern, enumeration, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents double-precision 64-bit floating-point numbers.

Double

duration

enumeration, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents duration of time. The pattern for duration is PnYnMnDTnHnMnS, where nY represents the number of years, nM the number of months, nD the number of days, T the date/time separator, nH the number of hours, nM the number of minutes, and nS the number of seconds.

For example, to indicate a duration of 1 year, 2 months, 3 days, 10 hours, and 30 minutes, you write: P1Y2M3DT10H30M. You could also indicate a duration of minus 120 days as -P120D.

Character (C(30))

float

pattern, enumeration, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents single-precision 32-bit floating-point numbers.

Double

gDay

enumeration, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents a Gregorian day that recurs, specifically a day of the month, such as the fifth day of the month. A gDay is the space of a set of calendar dates. Specifically, it is a set of one-day long, monthly periodic instances.

The pattern for gDay is --DD with an optional time zone indicator as allowed for date.

Character (C(10))

gMonth

enumeration, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents a Gregorian month that recurs every year. A gMonth is the space of a set of calendar months. Specifically, it is a set of one-month long, yearly periodic instances.

The pattern for gMonth is -MM- with an optional time zone indicator as allowed for date.

Character (C(10))

gMonthDay

enumeration, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents a specific Gregorian date that recurs, specifically a day of the year, such as the third of May. A gMonthDay is the set of calendar dates. Specifically, it is a set of one-day long, annually periodic instances.

The pattern for gMonthDay is --MM-DD with an optional time zone indicator as allowed for date.

Character (C(10))

gYear

enumeration, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents a Gregorian year. A set of one month-long, nonperiodic instances.

The pattern for gYear is CCYY with an optional time zone indicator as allowed for dateTime.

Character (C(15))

gYearMonth

enumeration, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents a specific Gregorian month in a specific Gregorian year. A set of one month-long, nonperiodic instances.

The pattern for gYearMonth is CCYY-MM with an optional time zone indicator.

Character (C(15))

hexBinary

length, pattern, maxLength, minLength, enumeration, whiteSpace

Represents arbitrary hex-encoded binary data. A hexBinary is the set of finite-length sequences of binary octets. Each binary octet is encoded as a character tuple, consisting of two hexadecimal digits ([0-9a-fA-F]) representing the octet code.

Memo (Binary)

NOTATION

length, enumeration, pattern, maxLength, minLength, whiteSpace

Represents a NOTATION attribute type. A set of QNames.

Memo

QName

length, enumeration, pattern, maxLength, minLength, whiteSpace

Represents a qualified name. A qualified name is composed of a prefix and a local name separated by a colon. Both the prefix and local names must be an NCName. The prefix must be associated with a namespace Uniform Resource Identifier (URI) reference, using a namespace declaration.

Memo

string

length, pattern, maxLength, minLength, enumeration, whiteSpace

Represents character strings.

Character when maxLength is specified and less than 255 characters. Otherwise, Memo.

time

enumeration, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, whiteSpace

Represents an instance of time that recurs every day.

The pattern for time is hh:mm:ss.sss with an optional time zone indicator.

Character (C(20))

XML Schema Derived Types to Visual FoxPro Data Types

XML data type | Facets | Description | Visual FoxPro data type
byte | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer with a minimum value of -128 and maximum of 127. This data type is derived from short. | Integer
ENTITIES | length, maxLength, minLength, enumeration, whiteSpace | Represents the ENTITIES attribute type and contains a set of values of type ENTITY. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
ENTITY | length, enumeration, pattern, maxLength, minLength, whiteSpace | Represents the ENTITY attribute type in XML 1.0 Recommendation. This is a reference to an unparsed entity with a name that matches the specified name. An ENTITY must be an NCName and must be declared in the schema as an unparsed entity name. This data type is derived from NCName. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
ID | length, enumeration, pattern, maxLength, minLength, whiteSpace | Represents the ID attribute type defined in the XML 1.0 Recommendation. The ID must be a no-colon-name (NCName) and must be unique within an XML document. This data type is derived from NCName. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
IDREF | length, enumeration, pattern, maxLength, minLength, whiteSpace | Represents a reference to an element that has an ID attribute that matches the specified ID. An IDREF must be an NCName and must be a value of an element or attribute of type ID within the XML document. This data type is derived from NCName. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
IDREFS | length, maxLength, minLength, enumeration, whiteSpace | Represents the IDREFS attribute type and contains a set of values of type IDREF. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
int | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer with a minimum value of -2147483648 and maximum of 2147483647. This data type is derived from long. | Integer
integer | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents a sequence of decimal digits with an optional leading sign (+ or -). This data type is derived from decimal. | Integer, if totalDigits is less than 10. Otherwise, Character with totalDigits respected.
language | length, pattern, maxLength, minLength, enumeration, whiteSpace | Represents natural language identifiers (defined by RFC 1766). This data type is derived from token. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
long | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer with a minimum value of -9223372036854775808 and maximum of 9223372036854775807. This data type is derived from integer. | Integer, if totalDigits is less than 10. Otherwise, Character with totalDigits respected.
Name | length, pattern, maxLength, minLength, enumeration, whiteSpace | Represents names in XML. A Name is a token that begins with a letter, underscore, or colon and continues with name characters (letters, digits, and other characters). This data type is derived from token. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
NCName | length, pattern, maxLength, minLength, enumeration, whiteSpace | Represents noncolonized names. This data type is the same as Name, except it cannot begin with a colon. This data type is derived from Name. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
negativeInteger | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer that is less than zero and consists of a negative sign (-) and sequence of decimal digits. This data type is derived from nonPositiveInteger. | Integer, if totalDigits is less than 10. Otherwise, Character with totalDigits respected.
NMTOKEN | length, pattern, maxLength, minLength, enumeration, whiteSpace | Represents the NMTOKEN attribute type. An NMTOKEN is set of name characters, such as letters, digits, and other characters, in any combination. Unlike Name and NCName, NMTOKEN has no restrictions on the starting character. This data type is derived from token. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
NMTOKENS | length, maxLength, minLength, enumeration, whiteSpace | Represents the NMTOKENS attribute type and contains a set of values of type NMTOKEN. | Memo
nonNegativeInteger | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer that is greater than or equal to zero. This data type is derived from integer. | Integer, if totalDigits is less than 10. Otherwise, Character with totalDigits respected.
nonPositiveInteger | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer that is less than or equal to zero and A nonPositiveInteger consists of a negative sign (-) and sequence of decimal digits. This data type is derived from integer. | Integer, if totalDigits is less than 10. Otherwise, Character with totalDigits respected.
normalizedString | length, pattern, maxLength, minLength, enumeration, whiteSpace | Represents white space normalized strings. This data type is derived from string. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
positiveInteger | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer that is greater than zero. This data type is derived from nonNegativeInteger. | Integer, if totalDigits is less than 10. Otherwise, Character with totalDigits respected.
token | enumeration, pattern, length, minLength, maxLength, whiteSpace | Represents tokenized strings. This data type is derived from normalizedString. | Character, if maxLength is specified and less than 255. Otherwise, Memo.
short | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer with a minimum value of -32768 and maximum of 32767. This data type is derived from int. | Integer
unsignedByte | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer with a minimum of zero and maximum of 255. This data type is derived from unsignedShort. | Integer
unsignedInt | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer with a minimum of zero and maximum of 4294967295. This data type is derived from unsignedLong. | Integer, if totalDigits is less than 10. Otherwise, Character with totalDigits respected.
unsignedLong | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer with a minimum of zero and maximum of 18446744073709551615. This data type is derived from nonNegativeInteger. | Integer, if totalDigits is less than 10. Otherwise, Character with totalDigits respected.
unsignedShort | enumeration, fractionDigits, pattern, minInclusive, minExclusive, maxInclusive, maxExclusive, totalDigits, whiteSpace | Represents an integer with a minimum of zero and maximum of 65535. This data type is derived from unsignedInt. | Integer

Visual FoxPro Data Types to XML Schema Definition (XSD) Data Types

Visual FoxPro data type | XSD data type and examples | Restrictions and sample restriction | Comments
Blob | xs:base64Binary | <xs:element name="ts12" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:base64Binary"/> </xs:simpleType> </xs:element> | Content is translated to base64 encoding. Maps to SQL Binary.
Character | xs:string Confirm this is electric | <xs:element name="cc04" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:maxLength value="128"/> </xs:restriction> </xs:simpleType> </xs:element> |
Character (Binary) | xs:string Confirm this is electric | <xs:element name="cc04" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:maxLength value="128"/> </xs:restriction> </xs:simpleType> </xs:element> |
Currency | xs:decimal -1.23, 0, 123, 4, 1000.00 | <xs:element name="yc07" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:decimal"> <xs:totalDigits value="19"/> <xs:fractionDigits value="4"/> </xs:restriction> </xs:simpleType> </xs:element> | Currency is always 19,4.
Date | xs:date 1999-05-31 | None |
DateTime | xs:dateTime 1999-05-31T13:20:00.000-05:00 | None |
Double | xs:double -INF, -1E4, -0, 0, 12.78E-2, 12, INF, NaN | None | The export value should include the maximum scale allowed for double and not be limited to display scale (internal value of double).
Float | xs:decimal | <xs:element name="fc06" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:decimal"> <xs:totalDigits value="14"/> <xs:fractionDigits value="4"/> </xs:restriction> </xs:simpleType> </xs:element> | totalDigits is the number of digits not including decimal point.
General | Not supported |  |
Integer | xs:int -1, 126789675 |  |
Logical | xs:boolean true, false, 1, 0 |  | Values are either true and false or 1 and 0.
Memo | xs:string | <xs:element name="mc03" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:maxLength value="2147483647"/> </xs:restriction> </xs:simpleType> </xs:element> |
Memo (Binary) | xs:base64Binary | <xs:element name="ts12" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:base64Binary"/> </xs:simpleType> </xs:element> | Content is translated to base64 encoding. Maps to SQL Binary.
Numeric | xs:decimal -1.23, 0, 123, 1000.00 | <xs:element name="nc00" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:decimal"> <xs:totalDigits value="10"/> <xs:fractionDigits value="4"/> </xs:restriction> </xs:simpleType> </xs:element > | totalDigits is the number of digits not including decimal point.
Varbinary | xs:base64Binary | <xs:element name="cc04" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:base64Binary"> <xs:maxLength value="128"/> </xs:restriction> </xs:simpleType> </xs:element> | Content is translated to base64 encoding.
Varchar | xs:string Confirm this is electric | <xs:element name="cc04" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:maxLength value="128"/> </xs:restriction> </xs:simpleType> </xs:element> |
Varchar (Binary) | xs:string Confirm this is electric | <xs:element name="cc04" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:maxLength value="128"/> </xs:restriction> </xs:simpleType> </xs:element> |

XML Schema Definition (XSD) Data Types to Visual FoxPro Data Types

XSD data type | Visual FoxPro data type
xsd:binaryBase64 | Memo (Binary)
xsd:boolean | Logical
xsd:date | Date
xsd:dateTime | DateTime
xsd:decimal | Numeric
xsd:double | Double
xsd:int | Integer
xsd:string | Character
xsd:string (more than 254 characters in length) | Memo

XML Data Reduced (XDR) Schema Data Types to Visual FoxPro Data Types

XDR data type Description Visual FoxPro data type XSD type

bin.base64

Specifies MIME-style Base64-encoded binary data.

Memo (Binary)

base64Binary

bin.hex

Specifies hexadecimal-encoded binary data.

Memo (Binary)

hexBinary

boolean

Specifies a Boolean value of either 0 or 1.

Example: 0 is false and 1 is true.

Logical

boolean

char

Specifies a number corresponding to the Unicode representation of a single character.

None

Not supported

date

Specifies the date in a subset of the ISO 8601 format without the time data.

Example: "1994-11-05"

Date

date

dateTime

Specifies a date in a subset of the ISO 8601 format with optional time and no optional zone. Fractional seconds can be as precise as nanoseconds.

Example: "1988-04-07T18:39:09"

DateTime

dateTime

dateTime.tz

Specifies a date in a subset of the ISO 8601 format with optional time and optional zone. Fractional seconds can be as precise as nanoseconds.

Example: "1988-04-07T18:39:09-08:00"

None

None

entity

Specifies a reference to an unparsed entity, requiring a matching <!ENTITY> declaration for each instance of the entity.

None

None

entities

Specifies a list of entities delimited by white space.

None

None

enumeration

Similar to nmtoken but with an explicit list of allowed values. Supported on attributes only.

Example: "Red Blue Green"

None

None

fixed.14.4

Specifies a number with no more than fourteen digits to the left of the decimal point and no more than four to the right of the decimal point.

Example: 9999.0044

Currency

decimal 19,4

float

Specifies a real floating point number.

Examples: 111, 3.14, -123.456E+10

Double

double

i1

Specifies a 1-byte integer with an optional sign ranging from -128 to 127.

Examples: 1, 127, -128

Integer

byte

i2

Specifies a 2-byte integer with optional sign ranging from -32768 to 32767.

Examples: 1, 703, -32768

Integer

short

i4

Specifies a 4-byte integer with optional sign ranging from -2147483648 to 2147483647

Examples: 1, 703, -32768, 148343, -1000000000

Integer

int

i8

Specifies an 8-byte integer with optional sign ranging from -9223372036854775808 to 9223372036854775807.

Examples: 1, 703, -32768, 1483433434334, -1000000000000000

Character or Integer

long

id

Specifies a value that identifies an attribute as an id type attribute. The id values must be unique throughout the document.

In a document, idref(s) attributes refer to an id type attribute, forming a relationship similar to primary key and foreign key in relational databases.

Example: Cust1

None

None

idref

Specifies a value corresponding to an id type, enabling intra-document links.

Example: Cust1

None

None

idrefs

Similar to idref, except it contains multiple id type values separated by white space.

Example: Cust1 Cust2 Cust3

None

None

int

Specifies a signed integer.

Examples 11123, -123

Integer

int

nmtoken

Contains values that conform to the rules of the name token.

Example: Cust1

None

None

nmtokens

Similar to nmtoken except it can have a list of nmtoken values separated by white space.

Example: Cust1 Cust2 Cust3

None

None

notation

A NOTATION type

None

None

number

A number with no limits on the digits

Examples: 111, 3.14, -123.456E+10

Note:
For ADO RecordSets, a special case exists where the number might have Currency type. When dt:type='number' in an ADO XDR Schema, Visual FoxPro checks for the existence of rs:dbtype='currency'.

Character, Currency, or Numeric as appropriate

decimal

r4

Same as float but only 4-byte encoding. Value ranges from 1.17549435E-38F to 3.40282347E+38F.

Double

float

r8

Specifies a floating point number. This data type supports only 15 digits of precision and value ranges from 2.2250738585072014E-308 to 1.7976931348623157E+308.

Double

double

string

Specifies a string.

Example: "This is a string"

Character, if maxLength is less than 255. Otherwise, Memo.

string

time

Specifies a time in a subset of the ISO 8601 format with no date and no time zone.

Example: "08:15:27"

None

None

time.tz

Specifies a time in a subset of the ISO 8601 format with no date but optional time zone.

Example: "08:15:27-05:00"

None

None

ui1

Specifies a 1-byte unsigned integer ranging from 0 to 255.

Examples: 1, 255

Integer

unsignedByte

ui2

Specifies a 2-byte unsigned integer ranging from 0 to 65535.

Examples: 1, 255, 65535

Integer

unsignedShort

ui4

Specifies a 4-byte unsigned integer ranging from 0 to 4294967296.

Examples: 1, 703, 3000000000

Character or Integer

unsignedInt

ui8

Specifies an 8-byte unsigned integer ranging from 0 to 18446744073709551615.

Example: 1483433434334

Character or Integer

unsignedLong

uri

Identifies a Uniform Resource Identifier (URI).

Example: "urn:schemas-microsoft-com:Office9"

Memo

anyURI

uuid

Contains hexadecimal digits representing octets with optional embedded hyphens that are ignored.

Example: 333C7BC4-460F-11D0-BC04-0080C7055A83

Character (C(40))

string

See Also

Other Resources

Data and Field Types
Visual FoxPro Data and Field Types
XMLAdapter Class
XMLTable Class
XMLField Class


Blob Data Type

Visual FoxPro 9.0
Blob Data Type
See Also

To store binary data of any kind, such as ASCII text, an executable (.exe) file, or a stream of bytes, and with indeterminate length, use the Blob data type. Blob data types are particularly useful for storing Image data from SQL Server.

You can assign values to a Blob field using binary literals. Binary literals begin with a prefix, 0h, followed by a string of hexadecimal numbers and are not enclosed with quotation marks (""), unlike character strings. The following list includes examples of binary literals:

  • 0h202020

  • 0h6ABCDEF

  • 0h (empty binary literal)

Binary literals are limited to 255 encoded bytes.

To store binary values of fixed length, use the Varbinary data type instead. For more information, see Varbinary Data Type.

Support for Blob Data Type

The Blob type is supported for database containers (.dbc), free tables, cursors, and views. For example, you can select this type for a field on the Fields tab in the Table Designer. Tables can contain multiple Blob fields. You can specify default and null values for Blob fields. Blob fields support field validation.

You can view the contents of a field with Blob type using an EditBox control, a TextBox control in a Grid control, or by issuing the MODIFY MEMO command with the name of the Blob field; however, the contents are read-only. The edit box displays Blob type data as hexadecimal values without the 0h prefix. In grids, Blob type fields display the string "blob" if they are empty, and the string "Blob" if they contain data. You can double-click the Blob field in the grid, and an editing window displays the data as read-only.

Index keys based on Blob fields are not supported. No code page translation is performed on data with Blob type.

The following table lists language that contains functionality affected by the Blob data type.

AFIELDS( ) Function | ALTER TABLE - SQL Command | ALINES( ) Function
BITAND( ) Function | BITCLEAR( ) Function | BITNOT( ) Function
BITOR( ) Function | BITSET( ) Function | BITTEST( ) Function
BITXOR( ) Function | COPY STRUCTURE EXTENDED Command | COPY TO Command
CREATE CURSOR - SQL Command | CREATE FROM Command | CREATE TABLE - SQL Command
CursorSchema Property | CURSORGETPROP( ) Function | CURSORSETPROP( ) Function
CURSORTOXML( ) Function | DataType Property | EMPTY( ) Function
ISBLANK( ) Function | MLINE( ) Function | MODIFY MEMO Command
SET ANSI Command | SET EXACT Command | TRANSFORM( ) Function
XMLTOCURSOR( ) Function |  |
Note:
Values with Blob type are not compatible with the binary expressions produced by the BINTOC( ) function or used by the CTOBIN( ) function. String functions that usually return strings, such as the SUBSTR( ) function, now return binary values when passed binary values.

For more specifications about the Blob data type, see Visual FoxPro Data and Field Types.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
Fields Tab, Table Designer
DISPLAY STRUCTURE Command
String and Value Comparison in Visual FoxPro
TYPE( ) Function
VARTYPE( ) Function


Character Data Type

Visual FoxPro 9.0
Character Data Type
See Also

To store alphanumeric text, such as letters, numbers, spaces, symbols, and punctuation, use the Character data type. To prevent data in Character fields from being translated across code pages, use the Character (Binary) field type.

Tip:
To create a Character (Binary) field, use the NOCPTRANS option in the SQL CREATE TABLE and CREATE CURSOR commands or select it in the Fields tab in the Table Designer.

Character fields or variables and Character (Binary) fields can store text information that is not used in mathematical calculations, such as names, addresses, and numbers. For example, phone numbers or zip codes, though they include mostly numbers, are actually best stored as character values.

If the value stored in a Character field is smaller than the width of the field, Visual FoxPro inserts additional spacing to the right side of the value in the field up to the maximum width of the field. Trailing spaces are truncated. To store alphanumeric text in fields without additional padding or truncating trailing spaces, use the Varchar field type instead. Fields with Varchar and Varchar (Binary) type have priority over the Character type in UNION and concatenation operations. For more information, see Varchar Field Type and Considerations for SQL SELECT Statements.

For specifications about the Character data type and the Character (Binary) field type, see Visual FoxPro Data and Field Types.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
Character Operators
CREATE TABLE - SQL Command
Creating Character Expressions


Currency Data Type

Visual FoxPro 9.0
Currency Data Type
See Also

To store monetary values or precise financial calculations, use the Currency data type instead of Numeric.

Tip:
You can convert values from Numeric to Currency and the reverse using the NTOM( ) and MTON( ) functions. For more information, see Numeric Data Type, NTOM( ) Function, and MTON( ) Function.

To assign the Currency data type, use the dollar sign:

Copy Code
money = $50.33
moremoney = $675.43886

If you specify more than four decimal places in a currency expression, Visual FoxPro rounds to the expression to four places before evaluating the expression. In the example, the variable moremoney is internally rounded to 675.4389.

Currency fields respect system settings, such as SET CURRENCY, when displayed in Browse windows, fields, or when listed to the screen.

For more specifications about the Currency data type, see Visual FoxPro Data and Field Types.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
SET CURRENCY Command


Date Data Type (Visual FoxPro)

Visual FoxPro 9.0
Date Data Type (Visual FoxPro)
See Also

To store dates without time values, use the Date data type.

Visual FoxPro 5.0 and later supports a strict Date and DateTime format that provides year 2000 compliance. It is recommended that you use strict date formats for all Date and DateTime constants and expressions. For more information, see StrictDateEntry Property.

In both Date and DateTime data types, the following rules apply:

  • {00:00:00AM} is equivalent to {12:00:00AM}, Midnight.

  • {00:00:00PM} is equivalent to {12:00:00PM}, Noon.

  • {00:00:00} to {11:59:59} is equivalent to {12:00:00AM} to {11:59:59AM}.

  • {12:00:00} to {23:59:59} is equivalent to {12:00:00PM} to {11:59:59PM}.

For more specifications about the Date data type, see Visual FoxPro Data and Field Types.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
CREATE TABLE - SQL Command
Creating Date Expressions
Date and Time Operators


DateTime Data Type

Visual FoxPro 9.0
DateTime Data Type
See Also

To store values that are both dates and times or only dates, use the DateTime data type. A DateTime value is stored in eight bytes — two four-byte integers.

Visual FoxPro versions 5.0 and later support a strict Date and DateTime format that provides year 2000 compliance. It is recommended that you use strict date formats for all Date and DateTime constants and expressions. For more information, see StrictDateEntry Property.

In both Date and DateTime data types, the following rules apply:

  • {00:00:00AM} is equivalent to {12:00:00AM}, Midnight.

  • {00:00:00PM} is equivalent to {12:00:00PM}, Noon.

  • {00:00:00} to {11:59:59} is equivalent to {12:00:00AM} to {11:59:59AM}

  • {12:00:00} to {23:59:59} is equivalent to {12:00:00PM} to {11:59:59PM}

For more specifications about the DateTime data type, see Visual FoxPro Data and Field Types.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
CREATE TABLE - SQL Command
Creating Date Expressions
Date and Time Operators


Double Field Type

Visual FoxPro 9.0
Double Field Type
See Also Example

When you need more accuracy, for example, when you have a fixed amount of storage in your table or true floating-point values, use the Double data type instead of Numeric. Unlike with numeric data, you determine the position of the decimal point when you enter the value in a table.

Note:
When the Double data type is used in a table, the number of decimals specified when the field is created is for display purposes only. Visual FoxPro stores the actual value in the field.

For specifications about the Double field type, see Visual FoxPro Data and Field Types.

Example

The following example creates a cursor with a Double field and specifies 2 digits of precision for the field. The field displays only 2 digits of precision even though the value contains more than 2 digits of precision.

Copy Code
&& Close any open databases and clear memory.
CLOSE DATABASES ALL
CLEAR

&& Create a cursor with field of Double type.
CREATE CURSOR myCursor (myField B(2))

&& Insert value into cursor.
INSERT INTO myCursor VALUES (1234.561234)

&& Evaluate and display value in myField.
? EVALUATE("myCursor.myField") && Displays 1234.56.

&& Evaluate and compare values to determine actual value.
? EVALUATE("myCursor.myField") = 1234.56 && Displays .F.
? EVALUATE("myCursor.myField") = 1234.561234 && Displays .T.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
Creating Numeric Expressions
Numeric Operators
CREATE CURSOR - SQL Command
INSERT - SQL Command
EVALUATE( ) Function


Float Field Type

Visual FoxPro 9.0
Float Field Type
See Also

Included for compatibility, the Float data type is functionally equivalent to Numeric.

For specifications about the Float field type, see Visual FoxPro Data and Field Types.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
CREATE TABLE - SQL Command
Creating Numeric Expressions
Numeric Operators


General Field Type

Visual FoxPro 9.0
General Field Type
See Also

To store OLE objects, use the General field type.

The General field contains a ten-byte reference to the actual contents of the field: a spreadsheet, a word processor document, or a picture, created by another application. The actual type and amount of data, however, depends on the Automation server that creates the object and whether you link or embed the OLE object.

If you link an OLE object, your table contains only the reference to the data and to the application that created it. If you embed an OLE object, the table contains a copy of the data as well as a reference to the application that created it. The size of a General field is limited only by the amount of available disk space. For more information about using OLE in your application, see Sharing Information and Adding OLE.

For specifications about the General field type, see Visual FoxPro Data and Field Types.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
APPEND GENERAL Command
CREATE TABLE - SQL Command
General Field Window


Integer Field Type

Visual FoxPro 9.0
Integer Field Type
See Also

To store non-decimal numeric values when performance and table storage limitations are especially important, use the Integer field type. To generate values, such ID numbers, use Integer (Autoinc) that automatically increments the value.

In tables, the Integer field type is stored as a 4-byte binary value. As a result, it requires less memory than other Numeric data types. As a binary value, it requires no ASCII

For specifications about the Integer and Integer (Autoinc) field types, see Visual FoxPro Data and Field Types.

See Also

Tasks

How to: Set Autoincrementing Field Values

Reference

ALTER TABLE - SQL Command
CREATE TABLE - SQL Command
CREATE CURSOR - SQL Command

Concepts

Autoincrementing Field Values in Tables

Other Resources

Data and Field Types
How to: Choose Data Types
CREATE TABLE - SQL Command
Creating Numeric Expressions
Numeric Operators


Logical Data Type

Visual FoxPro 9.0
Logical Data Type
See Also

To store data with only two values more efficiently, use the Logical data type.

Logical data is stored as True (.T.) or False (.F.).

For specifications about the Logical data type, see Visual FoxPro Data and Field Types.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
CREATE TABLE - SQL Command
Logical Operators


Memo Field Type

Visual FoxPro 9.0
Memo Field Type
See Also

To store data blocks of any kind, such as null values, assembler code, printer drivers, and alphanumeric text of indeterminate length, or a reference to a data block in a field, use the Memo field type. To prevent data in Memo fields from being translated across code pages, use the Memo (Binary) field type.

Tip:
To create a Memo (Binary) field, use the NOCPTRANS option in the SQL CREATE TABLE and CREATE CURSOR commands or select it in the Fields tab in the Table Designer.

Memo and Memo (Binary) fields contain a ten-byte reference to the actual contents of the memo. However, the actual size of memos depends on the amount of data you store in them. Data from Memo and Memo (Binary) fields from records in a table are stored in a separate file with the same name as the table and an .fpt file name extension. Memo and Memo (Binary) fields are limited only by the amount of available disk space.

You can store contents of Memo fields as memory-resident strings. You can then manipulate these strings with all functions that operate on character data.

For specifications about the Memo and Memo (Binary) field type, see Visual FoxPro Data and Field Types.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
CREATE TABLE - SQL Command
Fields Tab, Table Designer
MODIFY MEMO Command


Numeric Data Type

Visual FoxPro 9.0
Numeric Data Type
See Also

To indicate magnitude, use the Numeric data type. Numeric values contain digits from 0 to 9 and, optionally, a sign and a decimal point. Visual FoxPro supports hexadecimal values for numeric data. For example, the decimal value 255 can be represented as 0xFF.

Tip:
For precise financial calculations, use the Currency data type instead of Numeric. You can convert values from Numeric to Currency and the reverse using the NTOM( ) and MTON( ) functions. For more information, see Currency Data Type, NTOM( ) Function, and MTON( ) Function.

In fields with Numeric data type, the length of the decimal portion is determined at design time when you create the field. The length of the decimal portion is part of the total length. For example, if you specify a length of 6 for a numeric field and a decimal setting of 4, the field can store values up to 9.9999.

For specifications about the Numeric data type, see Visual FoxPro Data and Field Types.

Numeric Precision

When storing floating-point numbers in Numeric fields, numeric precision is limited to approximately 15 digits in Visual FoxPro. Therefore, precision more than 15 digits might be lost when converting from decimal to binary numbers, storing numbers with infinitely repeating decimal values in binary, performing multiple repeated operations, and storing numeric values in Character fields and in memory variables in binary format.

This limitation is based on the way Pentium-based processors calculate and store floating-point numbers and follows the Institute of Electrical and Electronics Engineers (IEEE) floating-point specification for manipulating floating-point numbers in binary format. This standard makes it possible for floating-point numbers to be stored in reasonable amount of space and for performing calculations more quickly.

For example, the fraction 1/10 can be represented as a decimal value of 0.1. However, when storing 1/10 in binary, the decimal value is not the same as the fraction. Instead, the fraction is a repeating binary decimal of 0001100110011100110011 and so on. This type of number cannot be represented in memory that is finite or limited; therefore, the decimal value is rounded when stored in binary.

For values requiring higher precision, see Double Field Type.

For more details about floating-point numbers are stored and how Pentium-based processors handle their calculation, see the Microsoft Knowledge Base Article - Q78113, "XL: Floating-Point Arithmetic May Give Inaccurate Results" at http://support.microsoft.com/default.aspx?scid=kb;en-us;Q78113.

The following example illustrates the limit on numeric precision for floating-point numbers for Numeric data types:

Copy Code
x=1234567890.0987654321
? x

The result is 1234567890.0987650000.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
Creating Numeric Expressions
Numeric Operators


Varbinary Data Type

Visual FoxPro 9.0
Varbinary Data Type
See Also

To store binary values or literals of fixed length without padding by additional zero (0) bytes or truncating trailing 0 bytes, use the Varbinary data type. To store binary data with indeterminate length, use the Blob data type instead. For more information, see Blob Data Type.

Binary literals begin with a prefix, 0h, followed by a string of hexadecimal numbers and are not enclosed with quotation marks (""), unlike character strings. The following list includes examples of binary literals:

  • 0h202020

  • 0h6ABCDEF

  • 0h (empty binary literal)

Binary literals are limited to 255 encoded bytes. Varbinary fields are limited to 254 encoded bytes.

When performing comparison or concatenation operations, such as =, !=, ==, >, >=, <=, +, and -, the results vary depending on the operation and order of types in the operation. When you concatenate two binary values, the result is a binary value. When you concatenate variables of Varbinary (Q) type with Varchar (V) or Character (C) type, the result has the data type of the first item in the concatenation list. For example:

V + Q = V

Q + V = Q

When you compare between Varbinary and Character types, the type on the left side of the comparison expression governs the operation. For example, suppose a comparison expression such as the following is binary-based:

Q = V

Visual FoxPro evaluates these values on a byte for byte basis, and the result is the same as performing CAST(V AS Q(n) = Q.

Suppose the following comparison expression is character-based:

V = Q

Visual FoxPro evaluates these values as if they were character strings, and the result is the same as performing CAST(Q AS V(n) = V.

Index keys based on Varbinary fields or expressions are padded with zeros from the right of the value to the maximum length of the field. For example, the values 0hAA, 0hAA00, and 0hAA000 have the same index key of 0hAA0000. The default collation sequence for index keys based on binary expressions is MACHINE. No other collation sequences are permitted. For more information, see INDEX Command and Index Creation Based on Expressions.

Support for Varbinary Data Type

The Varbinary type is supported for database containers (.dbc), free tables, cursors, and views. For example, you can select this type for a field on the Fields tab in the Table Designer. Tables can contain multiple Varbinary fields. You can specify default and null values for Varbinary fields. Varbinary fields support field validation.

No code page translation is performed for data with Varbinary type.

The following clauses and functions do not support Varbinary data types:

  • LIKE in join and filter conditions for SQL statements

  • LIKE( ) Function

  • LIKEC( ) Function

  • BINTOC( ) Function

  • BITLSHIFT( ) Function

  • BITRSHIFT( ) Function

  • CTOBIN( ) Function

The following functions remove leading or trailing zero bytes from binary values:

  • ALLTRIM( ) Function

  • LTRIM( ) Function

  • RTRIM( ) Function

  • TRIM( ) Function

The following table lists language that contains functionality affected by the Varbinary data type.

? ?? Command | AFIELDS( ) Function | ALINES( ) Function
ALTER TABLE - SQL Command | APPEND FROM Command | BITAND( ) Function
BITCLEAR( ) Function | BITNOT( ) Function | BITOR( ) Function
BITSET( ) Function | BITTEST( ) Function | BITXOR( ) Function
COPY STRUCTURE EXTENDED Command | COPY TO Command | CREATE CURSOR - SQL Command
CREATE FROM Command | CREATE TABLE - SQL Command | CURSORGETPROP( ) Function
CursorSchema Property | CURSORSETPROP( ) Function | CURSORTOXML( ) Function
DataType Property | EMPTY( ) Function | Format Property
InputMask Property | ISBLANK( ) Function | LIST Commands
MLINE( ) Function | SET ENGINEBEHAVIOR Command | SET ANSI Command
SET EXACT Command | TRANSFORM( ) Function | XMLTOCURSOR( ) Function
Note:
Values with Varbinary type are not compatible with the binary expressions produced by the BINTOC( ) function or used by the CTOBIN( ) function. String functions that usually return strings, such as the SUBSTR( ) function, now return binary values when passed binary values.

For more specifications about the Varbinary data type, see Visual FoxPro Data and Field Types.

The following example clears the main Visual FoxPro window using the CLEAR command and creates a cursor with a field named myVarbinaryField with Varbinary type using the SQL CREATE CURSOR command. For each SQL INSERT statement, the INSERT command inserts a row into the cursor containing a binary literal in the myVarbinary field. GO TOP positions the record pointer at the first record. The DO WHILE loop displays the number of characters in the field for each row using the LEN( ) function until the last record in the table is reached.

You can type the example in a program (.prg) file and run it from the Command window using the DO Command.

Copy Code
CLEAR
CREATE CURSOR myCursor (myVarbinaryField Q(10))
INSERT INTO myCursor (myVarbinaryField) VALUES (0h616161202020)
INSERT INTO myCursor (myVarbinaryField) VALUES (0hABCDEF)
INSERT INTO myCursor (myVarbinaryField) VALUES (0h)
GO TOP
DO WHILE !EOF()
   ? "# Varbinary characters: ", LEN(myVarbinaryField)
   ?
   SKIP
ENDDO

For more information about the commands and functions used in this example, see CLEAR Commands, CREATE CURSOR - SQL Command, INSERT - SQL Command, BROWSE Command, GO GOTO Command, DO WHILE ... ENDDO Command, EOF( ) Function, and SKIP Command.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
Fields Tab, Table Designer
String and Value Comparison in Visual FoxPro
TYPE( ) Function
VARTYPE( ) Function


Varchar Field Type

Visual FoxPro 9.0
Varchar Field Type
See Also

To include alphanumeric text in fields without including additional padding with spaces or truncating trailing spaces, use the Varchar type. Alphanumeric text can contain letters, numbers, spaces, symbols, and punctuation. The Varchar type also provides a convenient method for mapping SQL Server Varchar types to corresponding Visual FoxPro data types.

To prevent data in Varchar fields from being translated across code pages, use the Varchar (Binary) type.

The Varchar and Varchar (Binary) field types are similar to the Character data and Character (Binary) field type in that you can store text information that is not used in mathematical calculations, such as names, addresses, and numbers. When storing Varchar and Varchar (Binary) values in variables, they are treated as Character types.

Tip:
To create a Varchar (Binary) field in a table, use the NOCPTRANS option in the SQL CREATE TABLE and CREATE CURSOR commands or select it in the Fields tab in the Table Designer.

The Varchar and Varchar (Binary) field types have priority over the Character type when performing UNION and concatenation operations between these types. For example, suppose you have Varchar (X) and Character (Y) fields with X representing the length of character value stored in the Varchar field and Y representing the length of the Character field. When performing concatenation operations, the result is a Varchar field with a character value length of X+Y.

When performing concatenation operations between Varchar (Binary) (X) and Character (Binary) (Y), the result is Varchar (Binary) (X+Y). For Visual FoxPro functions that return Character values, if at least one parameter is a Varchar or Varchar (Binary) field in a table or cursor, the return type is Varchar. For more information about data type conversion and precedence in UNION operations, see Considerations for SQL SELECT Statements.

Index keys based on Varchar and Varchar (Binary) fields or expressions are padded with spaces from the right of the value to the maximum length of the field. Therefore, LIKE clauses in SQL join and filter conditions with a Varchar or Varchar (Binary) field can be only partially Rushmore-optimized. For more information, see Using Rushmore Query Optimization to Speed Data Access.

Support for Varchar and Varchar (Binary) Types

The Varchar and Varchar (Binary) field types are supported for database containers (.dbc), free tables, cursors, and local and remote views. For example, you can select these types for a field on the Fields tab in the Table Designer. Tables can contain multiple Varchar and Varchar (Binary) fields. You can specify default and null values for Varchar and Varchar (Binary) fields. Varchar and Varchar (Binary) fields support field validation.

The following table lists language that contains functionality affected by the Varchar and Varchar (Binary) field types.

AFIELDS( ) Function | ALTER TABLE - SQL Command | APPEND FROM Command
COPY STRUCTURE EXTENDED Command | COPY TO Command | CREATE CURSOR - SQL Command
CREATE FROM Command | CREATE TABLE - SQL Command | CURSORGETPROP( ) Function
CursorSchema Property | CURSORSETPROP( ) Function | CURSORTOXML( ) Function
DataType Property | Format Property | MaxLength Property
InputMask Property | SET ENGINEBEHAVIOR Command | SET ANSI Command
SET EXACT Command | XMLTOCURSOR( ) Function |

For more specifications about the Varchar and Varchar (Binary) types, see Visual FoxPro Data and Field Types.

The following example clears the main Visual FoxPro window using the CLEAR command and creates a cursor with two fields named myVarCharField with Varchar type and myCharField with Character type using the SQL CREATE CURSOR command. For each SQL INSERT statement, the INSERT command inserts a row into the cursor containing character expressions of increasing length into each field. BROWSE displays the cursor, and GO TOP positions the record pointer at the first record. The DO WHILE loop displays the number of characters in each field for each row using the LEN( ) function until the last record in the table is reached.

You can type the example in a program (.prg) file and run it from the Command window using the DO Command.

Copy Code
CLEAR
CREATE CURSOR myCursor (myVarCharField V(10), myCharField C(10))
INSERT INTO myCursor (myVarCharField, myCharField) VALUES ("a", "a")
INSERT INTO myCursor (myVarCharField, myCharField) VALUES ("aa", "aa")
INSERT INTO myCursor (myVarCharField, myCharField) VALUES ("aaa", "aaa")
INSERT INTO myCursor (myVarCharField, myCharField) VALUES ("aaaa", "aaaa")
BROWSE
GO TOP
DO WHILE !EOF()
   ? "# VarChar characters: ", LEN(myVarCharField), ;
      ", # Char characters:      ", LEN(myCharField)
   ?
   SKIP
ENDDO

For more information about the commands and functions used in this example, see CLEAR Commands, CREATE CURSOR - SQL Command, INSERT - SQL Command, BROWSE Command, GO GOTO Command, DO WHILE ... ENDDO Command, EOF( ) Function, and SKIP Command.

See Also

Other Resources

Data and Field Types
How to: Choose Data Types
Fields Tab, Table Designer
DISPLAY STRUCTURE Command
TYPE( ) Function
VARTYPE( ) Function


Variant Data Type

Visual FoxPro 9.0
Variant Data Type
See Also

Variant is a special data type that can contain any kind of data except fixed-length string data. Variant data can also be the special values Empty, Error, and NULL. This data type is used in extrinsic clients to Visual FoxPro applications because Visual FoxPro is not a strongly typed language.

For specifications about the Variant data type, see Visual FoxPro Data and Field Types.

See Also

Other Resources

Data and Field Types
EMPTY( )
ERROR
NULL as a Value


Data Manipulation

Visual FoxPro 9.0
Data Manipulation

The expressions you can build give you full access to the power of manipulating data in Visual FoxPro. You can extend the power with user-defined functions, manipulate fields, records and arrays, use classes and objects, and manipulate null values.

In This Section

Field and Record Manipulation

Lists topics about specifying and narrowing the scope and range of records you want to access.
Data Transfer and Arrays

Lists topics about transferring data to arrays and using them to manipulate data.
Class and Object Manipulation

Lists topics about language elements you can use to manipulate objects.
Null Value Handling

Lists topics about how Visual FoxPro handles null values.

Related Sections

User-Defined Procedures and Functions

Introduces procedures and functions that you can define and create in Visual FoxPro.
General Reference

Includes Visual FoxPro-related technical information, including file types, file structures, and other reference information about Visual FoxPro elements.


Field and Record Manipulation

Visual FoxPro 9.0
Field and Record Manipulation

You access data in fields by specifying one or more records that contain the target data. You can access a particular record by moving the record pointer using the GOTO command or you can specify a range or group of records using scope, FOR, or WHILE clauses in a command.

In This Section

Scope Clauses

Describes scope clauses that you can use to specify a range of records.
FOR Clauses

Describes FOR clauses that you can use to specify logical conditions to control the records you want to include.
WHILE Clauses

Describes WHILE clauses that you can use to specify logical conditions that control whether to continue performing operations on records.

Related Sections

Data Manipulation

Provides information on expressions that you can build to get full access to the power of manipulating data in Visual FoxPro.
Fields

Provides the definition of a field.
Records

Provides the definition of a record.


Scope Clauses

Visual FoxPro 9.0
Scope Clauses
See Also

If a Visual FoxPro command has a Scope clause, you can specify a range of records for the command to act on.

The following table describes the clauses you can use for Scope.

Scope | Description
ALL | Command affects all records in the table.
NEXT nExpr | Command affects the next nExpr number of records beginning with the current record. In the following example, the REPLACE command acts on the current record and the two following records: REPLACE status WITH "open" NEXT 3
RECORD nRecordNumber | Command affects only the specified record number. In the following example, the REPLACE command acts on record number 5: REPLACE status WITH "open" RECORD 5
REST | Command affects a range of records beginning with the current record and ending with the last record in the table. In the following example, the REPLACE command stores a null value in the remaining records: REPLACE status WITH .NULL. REST

You can also specify record ranges using FOR and WHILE clauses. For more information, see FOR Clauses and WHILE Clauses.

See Also

Other Resources

REPLACE Command
Data Manipulation
Field and Record Manipulation


FOR Clauses

Visual FoxPro 9.0
FOR Clauses
See Also

A FOR clause causes a command to act on each record that meets the specified logical condition. FOR clauses have the following syntax:

The following example stores low balance in the alert field of all records that contain less than 500 in the total field.

Copy Code
FOR lExpr
REPLACE ALL alert WITH "low balance" FOR total < 500

Remarks

The following table lists commands in which you can use a FOR clause.

Commands That Use FOR Clauses

APPEND FROM ARRAY | COUNT | LOCATE
APPEND FROM | DEFINE PAD | RECALL
AVERAGE | DELETE | REPLACE FROM ARRAY
BLANK | DISPLAY | REPLACE
BROWSE | EXPORT | REPORT
CALCULATE | FOR( ) | SCAN...ENDSCAN
CHANGE | INDEX | SORT
COPY TO ARRAY | LABEL | SUM
COPY TO | LIST |

Using the FOR clause can speed operation of single-table commands. For more information about performance enhancement, see Optimizing Applications.

See Also

Other Resources

REPLACE Command
Scope Clauses
WHILE Clauses
Field and Record Manipulation
Data Manipulation


WHILE Clauses

Visual FoxPro 9.0
WHILE Clauses
See Also

A WHILE clause causes a command to act on each record as long as the logical expression evaluates to true (.T.). The first time the expression evaluates to false (.F.), the command ceases without attempting any remaining records. This expression is typically used with a table that's been sorted or indexed on the field(s) included in the WHILE expression. For instance, the following example navigates an indexed table to locate the first record that meets the condition, then the REPLACE command acts on those records that meet the WHILE condition.

Copy Code
USE Mytable INDEX street
LOCATE FOR UPPER(street) = "MAIN"
REPLACE street WITH "Maine" WHILE UPPER(street) = "MAIN"

You can use Scope, FOR, and WHILE expressions in the same Visual FoxPro command. For instance, the following examples store a new value in the status field of several records.

Copy Code
REPLACE ALL status WITH "Active" FOR total > 30 ;
   WHILE expd > {^1998/02/16}

When you specify both FOR and WHILE, the WHILE expression takes precedence and the FOR clause is used to filter the records selected by WHILE.

The following table lists commands in which you can use a WHILE clause.

Commands That Use WHILE Clauses

AVERAGE | COUNT | RECALL
BLANK | DELETE | REPLACE
BROWSE | DISPLAY | REPLACE FROM ARRAY
CALCULATE | EXPORT | REPORT
CHANGE | LABEL | SCAN ... ENDSCAN
COPY TO ARRAY | LIST | SORT
COPY TO | LOCATE | SUM

See Also

Other Resources

LOCATE Command
REPLACE Command
Field and Record Manipulation
Data Manipulation


Data Transfer and Arrays

Visual FoxPro 9.0
Data Transfer and Arrays

Arrays provide a way to quickly order information. Once information is in an array, you can easily search, sort, and perform other data manipulation. To get information to and from arrays, you transfer data to a table or transfer data from a table to an array.

Visual FoxPro makes no size or data type restrictions on array contents. The only restriction on size is the amount of memory available.

In This Section

Data Transfer from an Array to a Table

AddDefinition
Data Transfer from a Table to an Array

AddDefinition
Arrays and SELECT - SQL

AddDefinition

Related Sections

Field and Record Manipulation

AddDefinition
Data Manipulation

Provides information on expressions that you can build to get full access to the power of manipulating data in Visual FoxPro.


Data Transfer from a Table to an Array

Visual FoxPro 9.0
Data Transfer from a Table to an Array
See Also

The following Visual FoxPro commands transfer data from a table to an array:

  • SCATTER transfers data from a single table record to an array.

  • COPY TO ARRAY transfers data from a series of records to an array.

  • SELECT - SQL can transfer the results of a query to an array. For details about SELECT - SQL, refer to the topic Arrays and SELECT - SQL.

SCATTER and COPY TO ARRAY differ in the following respects:

  • SCATTER transfers data from the current record in the current table. COPY TO ARRAY can transfer data from multiple records in the current table.

  • The SCATTER BLANK option automatically creates an array having elements the same size and type as the fields in the table, but the array elements are empty.

  • The SCATTER VAR option automatically creates a set of variables having the same size, type, and name as the fields in the table.

See Also

Other Resources

Arrays and SELECT - SQL
COPY TO ARRAY Command
SCATTER Command
SELECT - SQL Command
Data Transfer From an Array to a Table
Data Transfer and Arrays
Data Manipulation


Data Transfer from an Array to a Table

Visual FoxPro 9.0
Data Transfer from an Array to a Table
See Also

The following Visual FoxPro commands transfer data from an array to a table:

  • GATHER transfers data from an array to a single table record.

  • APPEND FROM ARRAY adds new records to a table and fills the records with data from an array.

  • INSERT - SQL appends a single new record to a table and fills the record with data from an array.

GATHER, APPEND FROM ARRAY, and INSERT - SQL differ in the following respects:

  • GATHER transfers data from an array to the current record in the current table. Additionally, the GATHER MEMVAR option transfers data from a set of variables to the current table record.

  • APPEND FROM ARRAY appends new records to the end of the current table and then transfers data from the array to the newly appended records.

  • INSERT - SQL appends a new record and then transfers data from the array to the newly appended record. Unlike GATHER and APPEND FROM ARRAY, INSERT - SQL can append a record in an unselected table (a table open in a work area other than the current work area).

    Note:
    APPEND FROM ARRAY or INSERT - SQL performs faster than APPEND BLANK followed by REPLACE, especially on a network.

See Also

Other Resources

APPEND FROM ARRAY Command
GATHER Command
INSERT - SQL Command
Data Transfer from a Table to an Array
Data Transfer and Arrays
Data Manipulation
Arrays and SELECT - SQL


Arrays and SELECT - SQL

Visual FoxPro 9.0
Arrays and SELECT - SQL
See Also Example

Use the SELECT - SQL Command - INTO or TO Clausec to query tables and direct query results to an array.

If an array does not exist and the SQL SELECT Statement returns one or more records, the command creates an array. An existing array is re-created to accommodate the query results.

Note If the SQL SELECT statement does not return any records, an existing array remains unchanged and may contain previous results. If an array does not exist, the command does not create one. Consider using the _TALLY System Variable to determine if a SQL SELECT statement returns any records.

Example

In the following example, SELECT - SQL directs its query results to an array named RESULTS:
Copy Code
SELECT DISTINCT a.cust_id, a.company, b.amount ;
FROM customer a, payments b ;
WHERE a.cust_id = b.cust_id INTO ARRAY results

DISPLAY MEMORY LIKE results

RESULTS   Priv A            TEST
  ( 1, 1)   C  "000004"
  ( 1, 2)   C  "Stylistic Inc."
  ( 1, 3)   N    13.91  (    13.91000000)
  ( 2, 1)   C  "000008"
  ( 2, 2)   C  "Ashe Aircraft"
  ( 2, 3)   N    4021.98  (  4021.98000000)
  ( 3, 1)   C  "000010"
  ( 3, 2)   C  "Miakonda Industries"
  ( 3, 3)   N     9.84  (   9.84000000)

See Also

Other Resources

SELECT - SQL Command
Data Transfer and Arrays
Data Manipulation
Data Transfer from a Table to an Array
Data Transfer from an Array to a Table


Class and Object Manipulation

Visual FoxPro 9.0
Class and Object Manipulation
See Also

Visual FoxPro provides two special operators for object programming: the dot operator (.) and the scope resolution operator (::). Visual FoxPro also adds commands that enable you to create a class, and to create and add objects to a class.

Operator, Command, Function | Description
. (Dot operator) | Scopes objects to their parents and properties, events, and methods to objects.
:: (Scope resolution operator) | Calls a parent class method from within the subclass.
CREATEOBJECT( ) | Creates an object from a class, a subclass, or an OLE object.
DEFINE CLASS with ADD OBJECT clause | Creates a class definition. The ADD OBJECT clause adds an object based on an existing class or subclass at design time.
GETOBJECT( ) | Returns a reference to an OLE object.

For more information about using classes and objects, see Object-Oriented Programming.

See Also

Other Resources

:: Scope Resolution Operator
CREATEOBJECT( ) Function
DEFINE CLASS Command
GETOBJECT( ) Function
Data Transfer and Arrays
Data Manipulation
Null Value Handling


Null Value Handling

Visual FoxPro 9.0
Null Value Handling
See Also

Visual FoxPro provides support for null values. This support simplifies the task of representing unknown data and makes it easier to work with Microsoft Access or SQL databases that may contain null values.

Null values are:

  • Equal to the absence of any value.

  • Different than zero, the empty string (""), or blank.

  • Sorted ahead of other data.

  • Propagated in calculations and most functions.

Null values affect the behavior of commands and functions, logical expressions, and parameters.

Visual FoxPro support for null values complies with ANSI standards and affects any area of the product where values and expressions are used.

To use null values in | See
Commands and functions | Behavior of Null Values in Commands and Functions
Expressions | Behavior of Null Values in Logical Expressions
Parameters | NULL as a Parameter

Using NULL in Values and Expressions

In Visual FoxPro, you assign the null value programmatically with the .NULL. token or interactively with CTRL+0 in a field. Note that the periods around .NULL. are optional. To detect whether a field or variable contains a null value, or whether an expression evaluates to a null value, use ISNULL( ).

See Also

Other Resources

EMPTY( ) Function
ISBLANK( ) Function
ISNULL( ) Function
NULL as a Parameter
NULL as a Value
Data Manipulation


NULL as a Value

Visual FoxPro 9.0
NULL as a Value
See Also

A null value is different from an empty string, a blank field, or zero. For instance, both EMPTY( ) and ISBLANK( ) return true (.T.) when a variable contains blank or an empty string. EMPTY( ) also returns true (.T.) for zero. ISNULL( ) returns false (.F.) for these values and both EMPTY( ) and ISBLANK( ) return false (.F.) for null values.

You can use null values with array and field commands like STORE, GATHER, and SCATTER. The following example assigns .NULL. to each member of the array aX:

Copy Code
DIMENSION aX[4]
STORE .NULL. TO aX

The null value is not a data type. When you assign .NULL. to a field or variable, the value changes to .NULL. but the data type of the field or variable does not change. For example:

Copy Code
STORE 5 TO nX
nX = .NULL.
? TYPE ("nX")  && Data type reported as numeric

See Also

Other Resources

Behavior of Null Values in Logical Expressions
Behavior of Null Values in Commands and Functions
EMPTY( ) Function
ISBLANK( ) Function
ISNULL( ) Function
Null Value Handling
Data Manipulation
NULL as a Parameter


Behavior of Null Values in Commands and Functions

Visual FoxPro 9.0
Behavior of Null Values in Commands and Functions
See Also

The following table describes how commands and functions interpret null values.

Data type | Behavior
Logical | Most logical expressions that evaluate to .NULL. return .NULL. or generate an error. EMPTY( ), ISBLANK( ), and ISNULL( ) are exceptions.
Numeric | Numeric expressions that evaluate to .NULL. return .NULL. A numeric function evaluates to .NULL. when passed a null value.
Date | Date expressions containing null values return .NULL.

See Also

Other Resources

Null Value Handling
Date Data Type
EMPTY( ) Function
ISBLANK( ) Function
ISNULL( ) Function
Logical Data Type
Numeric Data Type
Behavior of Null Values in Logical Expressions
NULL as a Value
NULL as a Parameter


Behavior of Null Values in Logical Expressions

Visual FoxPro 9.0
Behavior of Null Values in Logical Expressions
See Also

Null values persist through logical expressions in most cases. The following table describes the behavior of null values in logical expressions.

Logical expression | Result if x=TRUE | Result if x=FALSE | Result if x=.NULL.
x AND .NULL. | .NULL. | FALSE | .NULL.
x OR .NULL. | TRUE | .NULL. | .NULL.
NOT x | FALSE | TRUE | .NULL.

When a conditional expression encounters a null value, the condition fails, because .NULL. is not true (.T.). For example, a FOR clause that evaluates to .NULL. is treated as false (.F.). Note that null values are treated as .NULL. until the entire expression is evaluated.

See Also

Other Resources

FOR Clauses
Null Value Handling
Data Manipulation
Behavior of Null Values in Commands and Functions
NULL as a Value
NULL as a Parameter


NULL as a Parameter

Visual FoxPro 9.0
NULL as a Parameter
See Also

Passing a null value as a parameter affects the behavior of many commands and functions in Visual FoxPro. The following general rules apply to null values passed to commands and functions:

  • Commands generate errors when passed a null value.

  • Functions that accept .NULL. as a valid value propagate .NULL. to the result.

  • Functions that accept parameters that could be numeric values generate an error if you supply .NULL. for those parameters.

    Copy Code
    STORE .NULL. TO n
USE Mytable ALIAS &n            && Expected a workarea
                              && name or number
? SUBSTR("Hello, world",n,5)   && Expected a position
                              && in the string
  • ISBLANK( ), ISDIGIT( ), ISLOWER( ), ISUPPER( ), ISALPHA( ), and EMPTY return false (.F.) when passed a null value. ISNULL( ) returns true (.T.) when passed a null value.

  • The commands INSERT - SQL and SELECT - SQL process null values through the IS NULL and IS NOT NULL clauses and, in the case of INSERT, UPDATE, and REPLACE, place null values into records.

  • SQL Aggregate functions ignore instead of propagate null values.

  • Visual FoxPro aggregate functions only propagate .NULL. if all supplied values are null values; otherwise, any null value is ignored.

For more information on using null values in your application, see Working with Tables.

See Also

Other Resources

EMPTY( ) Function
INSERT - SQL Command
ISALPHA( ) Function
ISBLANK( ) Function
ISDIGIT( ) Function
ISLOWER( ) Function
ISNULL( ) Function
ISUPPER( ) Function
REPLACE Command
SELECT - SQL Command
SQL Commands and Functions
UPDATE Command
Null Value Handling
Data Manipulation
NULL as a Value


Data Storage Containers

Visual FoxPro 9.0
Data Storage Containers
See Also

You choose a data storage container according to the amount and type of data you need to store, and how you want to use it. You determine the availability of data by the way you declare it and where you create it in the program. This range of availability or effectiveness is called scope.

Most programming languages make it possible for you to store data in constants, variables, and arrays. In Visual FoxPro, you can also store data in records and objects. For more information about differences, see Visual FoxPro and Other Programming Languages.

Scope of Data Containers

The following table summarizes the scope differences between data containers.

Container | Scope | Example
Arrays | Public, private, or local | ArrayName[1,1] = "John Brown"
Constants | PRIVATE Command | #DEFINE ERRSTR "Error!"
Fields | Permanent storage, accessible while the table containing the records is open | REPLACE name WITH "John Brown"
Variables | PUBLIC Command, private, or LOCAL Command | Var = 7
Objects | Referenced through the object and the object's container hierarchy | txtCustomer.Value = "John Brown"

See Also

Other Resources

General Reference
Access to Variables
LOCAL Command
PRIVATE Command
PUBLIC Command
Records
Visual FoxPro and Other Programming Languages


Arrays

Visual FoxPro 9.0
Arrays
See Also

An array is an ordered series of data values, which are called array elements. Array elements are referenced by their position in the array, which are numbers called array subscripts or indexes. Because arrays exist in memory, you can quickly and easily specify, access, and manipulate data elements in an array. A Visual FoxPro array can contain any or all types of data as elements. Arrays have the same scoping options as variables.

You can create an array using the DIMENSION or DECLARE command and assign a value to each element by specifying the element using the array name and the element's position, or subscript. You can use the SCATTER, GATHER, COPY TO ARRAY, and APPEND FROM ARRAY commands to move field values to and from array elements.

For example, the following line of code creates a two-dimensional array of five rows and two columns, then assigns a value to the second column of the first row:

Copy Code
DIMENSION ArrayName[5,2]
ArrayName[1,2] = 966789
Note:
Visual FoxPro arrays are one-based - the first element, row, or column of an array is specified with the number 1. (Arrays in other programming languages may be zero-based; the first element, row, or column of an array is specified with the number 0.)

For more information, see DIMENSION Command, DECLARE Command, SCATTER Command, GATHER Command, COPY TO ARRAY Command, and APPEND FROM ARRAY Command. For more information about using arrays in your application, see Data Transfer and Arrays.

See Also

Other Resources

Visual FoxPro System Capacities
Data Storage Containers
Variables


Constants

Visual FoxPro 9.0
Constants
See Also

A constant is a named item that retains its value throughout all operations. The value π, or 3.1415926535, is an example of a numeric constant; the letter A is an example of a character constant.

You can create compile-time constants that exist throughout the operation of a Visual FoxPro application. You can use a constant and know that its value doesn't change during the operation of your application. At design time, you can effect a change throughout an application by changing only the value of a single constant.

A constant can contain any data type value.

For information about defining and undefining constants, see How to: Define a Constant.

See Also

Other Resources

Variables
#DEFINE ... #UNDEF Preprocessor Directive
PI( ) Function
Constant is already created with #DEFINE (Error 1725)
#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive
Data Storage Containers


How to: Define a Constant

Visual FoxPro 9.0
How to: Define a Constant
See Also

A constant can contain any data type value.

To assign a value to a constant

  • Use the #DEFINE preprocessor directive.

In the following example, the constant TABLERR1 is defined as a character string.

Copy Code
#DEFINE TABLERR1 "This table is not available. Please try later."

In an application, wherever you would normally specify the character string "This table is not available. Please try later." you can use TABLERR1 instead.

To release a defined constant

  • Use the #UNDEFINE preprocessor directive.

    Copy Code
    #UNDEF TABLERR1

See Also

Other Resources

Variables
#DEFINE ... #UNDEF Preprocessor Directive
PI( ) Function
Constant is already created with #DEFINE (Error 1725)
#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive
Data Storage Containers


Fields

Visual FoxPro 9.0
Fields
See Also

A field is a named location in a record that contains a particular type of data. Fields can be any Visual FoxPro data type or field type.

A field's data type is specified at design time in the Table Designer or at run time with the CREATE TABLE command.

See Also

Other Resources

CREATE TABLE - SQL Command
Records
Table Designer
Data Storage Containers


Records

Visual FoxPro 9.0
Records
See Also

A record is a set of fields in a table. Records can have up to 255 fields. All records in a table contain the same fields. Though the content of fields differ from record to record, the size of a field is the same for all records in a table. The data type for each field is the same for all records in a table.

To create records, use the INSERT - SQL command or the APPEND command.

For more information about creating records and using tables, see Working with Tables.

See Also

Other Resources

APPEND Command
Fields
INSERT – SQL Command
Data Storage Containers


Variables (Visual FoxPro)

Visual FoxPro 9.0
Variables (Visual FoxPro)
See Also Example

A variable is a memory location whose value can change throughout the operation of a program. A variable can contain any data type value. You can change the value of a variable at any time. This option enables you to monitor the status of anything that changes throughout the operation of an application.

Variables exist only while an application is running or in the Visual FoxPro session in which they are created. To specify the scope of a variable, use the LOCAL, PRIVATE, and PUBLIC keywords.

Creating Variables

To create a variable, store a value to a named Visual FoxPro element using the STORE command or the = (equal) operator.

Example

The following examples are simple assignment statements that are functionally equivalent.

Copy Code
STORE 7 TO nVar
nVar = 7

The following example uses a variable, nInc, to hold the value of a loop counter. Visual FoxPro assigns a new value to the variable during each loop.

Copy Code
FOR nInc = 1 TO 10
   ? nInc
ENDFOR

The following example uses a variable, cName, to hold the value of the Firstname field from the Customer table.

Copy Code
USE Customer
STORE Customer.Firstname TO cName

See Also

Other Resources

Access to Variables
= Command
FOR ... ENDFOR Command
LOCAL Command
PRIVATE Command
PUBLIC Command
STORE Command
Data Storage Containers


Access to Variables

Visual FoxPro 9.0
Access to Variables
See Also

Variables exist only while an application is running or during the Visual FoxPro session in which they are created. To specify the scope of a variable, use the LOCAL, PRIVATE, and PUBLIC keywords.

  • LOCAL creates variables or arrays that can be used and modified only in the program they are created, and cannot be accessed by higher or lower level programs. Local variables and arrays are released once the program containing them stops running.

  • PRIVATE hides variables or arrays that were defined in a calling program from the current program. You can then reuse those variable names in the current program without affecting the original variables. Once the program containing PRIVATE has stopped running, all variables and arrays that were declared privately are again available.

  • PUBLIC defines global variables or arrays. Global variables and arrays can be used and modified from any program you run during the current Visual FoxPro session. Any variable or array you create in the Command window is automatically public.

Accessing Variables

If a variable has the same name as a field, Visual FoxPro always gives precedence to the field name. You can reference the variable using m. or m-> plus the variable name, as in the following examples.

Copy Code
?  m.cFname
?  m->cFname      && print value in cFname
?  cFname         && prints contents of field cFname

For more information about these commands, see the appropriate topics in Help.

Note:
In object-oriented programming you can create properties of objects to hold values instead of using variables. For more information, see Object-Oriented Programming.

See Also

Other Resources

Variables
PUBLIC Command
PRIVATE Command
LOCAL Command
Object-Oriented Programming
Data Storage Containers


Building Expressions

Visual FoxPro 9.0
Building Expressions

Visual FoxPro expressions combine data and operators to create a value with a specific data type. When you need to supply a value with a specific data type, you can also supply an expression.

In This Section

Creating Character Expressions

Introduces character expressions for providing character values.
Creating Visual FoxPro Names

Introduces names used by data containers, commands, and functions in Visual FoxPro.
Name Expression Creation

Introduces name expressions as substitutes for Character variable and array element values for names needed by commands and functions.
Macro Substitution

Introduces using macro substitution for replacing names with variables.
Creating Numeric Expressions

Introduces numeric expressions for providing numeric values.
Creating Logical Expressions

Introduces logical expressions for providing logical values.
Creating Date Expressions

Introduces date expressions for providing date values.
Using Commands and Functions

Introduces using expressions with Visual FoxPro commands and functions.
Trimming and Concatenating Expressions

Explains trimming values in fields and concatenating expressions into a single expression.
Operating the Expression Builder

Describes how to create expressions in the Expression Builder when it is available.

Related Sections

General Reference

Includes Visual FoxPro-related technical information, including file types, file structures, and other reference information about Visual FoxPro elements.


Creating Character Expressions

Visual FoxPro 9.0
Creating Character Expressions
See Also

Compose character expressions by combining character operators with the following Visual FoxPro elements:

  • Character fields.

  • Functions that return character values.

  • Variables and array elements that contain character data.

  • Character constants, called string literals.

You can embed quotation marks ("" or '') in a character string by enclosing the character string within square brackets ([]):

Copy Code
STORE [Robert's Diner] TO cCompanyName
STORE [See the "Sunday Special"] TO cBanner

You can also embed quotation marks by enclosing the character string with quotation marks of the alternate type:

Copy Code
STORE "Robert's Diner" TO cCompanyName
STORE 'See the "Sunday Special"' TO cBanner

For more information, see STORE Command.

See Also

Other Resources

Character Operators
Building Expressions


Creating Visual FoxPro Names

Visual FoxPro 9.0
Creating Visual FoxPro Names
See Also

Data containers and some parameters to commands and functions require a name. When you create a name in Visual FoxPro, apply the following rules:

  • Use only letters, underscores, and numbers.

  • Begin the name with a letter or underscore.

  • Use 1 to 128 characters, except for field names in free tables and index tags — those can be 10 characters at most.

  • Avoid words reserved by Visual FoxPro.

File names follow your operating system's conventions.

See Also

Other Resources

Name Expression Creation
Macro Substitution
Building Expressions


Name Expression Creation

Visual FoxPro 9.0
Name Expression Creation
See Also

Many Visual FoxPro commands and functions require that you supply a name. Although a name cannot be a variable or an array element, you can create a name expression that substitutes the value of a Character variable or array element as the name.

When you store the name to the variable or array element, you can substitute the name into a command or function by enclosing the variable in parentheses. To use a list of names, separate the names with commas. A name is not an expression, a variable or array element, or a field. A name should not be surrounded by quotation marks. Otherwise, names follow the Visual FoxPro naming rules described in the section Creating Visual FoxPro Names.

For example, the REPLACE command requires a field name. You can store a field name to a variable and use a name expression in REPLACE where the field name occurs:

Copy Code
STORE 'city' TO cVarCity
REPLACE (cVarCity) WITH 'Paris'

Visual FoxPro stores the field name city to the variable cVarCity, then stores the value "Paris" in the field, city, which is the value of the name expression cVarCity.

For more information, see STORE Command and REPLACE Command.

See Also

Other Resources

Macro Substitution
Building Expressions
Creating Visual FoxPro Names


Macro Substitution (Visual FoxPro)

Visual FoxPro 9.0
Macro Substitution (Visual FoxPro)
See Also

You can replace names with variables by using macro substitution. To use macro substitution, place an ampersand (&) before the variable to tell Visual FoxPro to use the value of the variable as a name, and use a period (.) to end the macro substitution expression.

For example, the following print statement produces "FoxPro":

Copy Code
x = "Fox"
? "&x.Pro"

A command or function containing a name expression runs faster than one containing macro substitution, so use a name expression instead of macro substitution whenever possible. For more information about macro substitution, see the & Command topic in Help.

See Also

Other Resources

Creating Visual FoxPro Names
Name Expression Creation
Building Expressions


Creating Numeric Expressions

Visual FoxPro 9.0
Creating Numeric Expressions
See Also

Compose numeric expressions by combining numeric operators with the following Visual FoxPro elements:

  • Numeric type fields.

  • Functions that return numeric values.

  • Variables and array elements that contain numeric data.

  • Numeric constants.

See Also

Other Resources

Numeric Operators
Numeric Data Type
Building Expressions


Creating Logical Expressions

Visual FoxPro 9.0
Creating Logical Expressions
See Also

Logical expressions evaluate to either true or false, which are represented by the values .T. and .F. in Visual FoxPro. Compose logical expressions by combining logical operators with the following Visual FoxPro elements:

  • Logical type fields.

  • Functions that return logical values.

  • Variables and array elements that contain logical values.

  • Any expression that evaluates to a logical value.

Visual FoxPro evaluates logical expressions from left to right, and only for as long as necessary. In the following example, the AND operator is used to create a logical expression. If any of the values in the expression are false (.F.), the entire expression is false. When Visual FoxPro encounters the first logical false (.F.), it doesn't evaluate the rest of the expression.

Copy Code
.T. AND .T. AND .F. AND .T. AND .T. AND .T.

See Also

Other Resources

Logical Operators
Logical Data Type
Building Expressions


Creating Date Expressions

Visual FoxPro 9.0
Creating Date Expressions
See Also

Compose date expressions by combining date operators with the following Visual FoxPro elements:

  • Date or DateTime fields.

  • Functions that return dates or dates and times.

  • Variables and array elements that contain dates or times.

  • Date and DateTime constants.

Visual FoxPro treats an invalid date as an empty date.

See Also

Other Resources

Date and Time Operators
Building Expressions


Using Commands and Functions

Visual FoxPro 9.0
Using Commands and Functions
See Also

Visual FoxPro commands and functions perform an action or return values for use in other commands and functions. Commands and functions can accept expressions as parameters, or they can appear in expressions. You can also use user-defined functions (UDFs) whenever you can use a Visual FoxPro command or function.

Commands and functions behave differently:

  • Commands perform an action. For example, you can use the BROWSE command to look at the contents of a table.

  • Functions return a value of a given data type. For example, the DATE( ) function returns the system date from your computer. Functions end with a pair of parentheses that distinguish them from commands.

Functions are not used by themselves, but are always combined with a Visual FoxPro command. For example, the question mark (?) is a command that sends output to the screen. DATE( ) is a function that returns the current system date. You can combine them to output the system date to the screen:

Copy Code
? DATE( )

Commands and functions have a prescribed syntax for parameters and clauses you can supply. For a full description of the syntax of any command or function, see the Language Reference A-Z.

See Also

Other Resources

Building Expressions


Trimming and Concatenating Expressions

Visual FoxPro 9.0
Trimming and Concatenating Expressions
See Also

When you specify expressions containing multiple fields, they might not display the way you want because of unwanted spacing. You can trim fields and concatenate expressions to remove the unwanted spacing. For example, suppose you want to display an address line containing the city name, region, and postal code. Specifying separate fields that contain the city name, region, and postal code in a row might produce display unwanted spaces between each value.

Trimming Fields and Concatenating Expressions

You can trim and concatenate expressions containing multiple fields with values that vary into a single expression. You can trim fields by enclosing the ALLTRIM( ) function around each field name, insert punctuation or desired space enclosed by quotation marks (" "), and concatenate expressions using a plus sign (+) between each expression.

The space required by each value can vary. However, if the value lengths in the fields do not vary, for example, postal codes or abbreviations, you can enclose only the field name that varies using ALLTRIM( ) as shown in the following example:

Copy Code
ALLTRIM(city) + ", " + region + "  " + postal_code
Note:
Space, rather than a comma, enclosed by quotation marks separate the region and the postal code.

For more examples, see the sample report Invoice.frx in the Visual FoxPro directory, ...\Samples\Solution\Reports.

Trimming and Concatenating Expressions Quickly

When you do not need or want to include punctuation in the expression, you can trim or concatenate expressions quickly by inserting commas (,) between each expression. The value of the expression preceding the comma is trimmed.

Note:
Provided that the trimmed value has a length greater than zero, you can use semicolons (;) to place the trimmed expression on a new line.

The following example shows a trimmed and concatenated expression containing multiple fields for a mailing address:

Copy Code
contact_name; address; city, region, postal_code

See Also

Other Resources

How to: Trim and Concatenate Fields
Building Expressions


Operating the Expression Builder

Visual FoxPro 9.0
Operating the Expression Builder

You can build expressions using the Expression Builder when access is provided in the Visual FoxPro user interface. In locations where you need to specify an expression in the Visual FoxPro user interface, an ellipsis (...) button is usually provided so you can open the Expression Builder.

In This Section

How to: Build a Function Expression

Explains how to build a function expression in the Expression Builder.
How to: Build a Variable Expression

Explains how to build a variable expression in the Expression Builder.
How to: Trim and Concatenate Fields

Explains how to trim and concatenate expressions containing fields in the Expression Builder.

Related Sections

Building Expressions

Provides information about how Visual FoxPro expressions combine data and operators to create a value of a given data type.


How to: Build a Function Expression

Visual FoxPro 9.0
How to: Build a Function Expression
See Also

In the Expression Builder, you can build an expression that contains a function.

To build a function expression

  1. When available, click the ellipsis (...) button to open the Expression Builder.

  2. In the Functions area of the builder, select a function from one of the function lists.

  3. Click OK.

For more information, see Expression Builder Dialog Box.

See Also

Other Resources

Operating the Expression Builder
Building Expressions


How to: Build a Variable Expression

Visual FoxPro 9.0
How to: Build a Variable Expression
See Also

In the Expression Builder, you can build an expression that contains the name of a variable.

To build a variable expression

  1. When available, click the ellipsis (...) button to open the Expression Builder.

  2. Perform one of the following:

    • In the main expression box, type a variable name.

    • In the Variables list of the builder, select a system variable name.

  3. Click OK.

For more information, see Expression Builder Dialog Box.

See Also

Other Resources

Operating the Expression Builder
Building Expressions


How to: Trim and Concatenate Fields

Visual FoxPro 9.0
How to: Trim and Concatenate Fields
See Also

In the Expression Builder, you can trim and concatenate multiple fields with values that vary into a single field expression using the ALLTRIM( ) function.

To concatenate fields

  1. When available, click the ellipsis (...) button to open the Expression Builder.

  2. In the String box of builder, select ALLTRIM(expC).

    The string function appears in the main expression box with expC selected.

  3. In the Fields list, double-click the first field you want to appear in the control.

    The field name replaces the expC.

  4. Type a plus sign (+) following the field name, or in the String box, select the plus sign.

  5. Type a comma (,) following the plus sign, or in the String box, select "text" and then type a comma.

  6. To complete the expression with any additional fields, repeat steps 2 through 5, and then click OK to return to the location from which you opened the Expression Builder.

For more information, see Expression Builder Dialog Box.

See Also

Other Resources

Trimming and Concatenating Expressions
Operating the Expression Builder
Building Expressions


File Structures

Visual FoxPro 9.0
File Structures

This section contains technical information about file structures and file types.

In This Section

Compound Index File Structure (.cdx)

Describes how the compound file structure is different from the compact index file structure.
Compact Index File Structure (.idx)

Provides information about the compact index header record.
File Extensions and File Types

Contains lists of the extensions and their associated file types that are used with Microsoft Visual FoxPro.
FoxUser Resource File Structure

Contains a variety of resource information, including window positions, color sets, Browse window configurations, label definitions, and so on.
Index File Structure (.idx)

Describes the contents of index files, index header records, and index node records.
Macro File Format (.fky)

Provides a description of the file header and individual macros.
Memo File Structure (.FPT)

Describes the contents of the memo header record, memo block header, and memo text.
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)

Provides a list of file types that are saved as tables, as well as the table header record and field subrecords structure.
Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)

Provides information about the reports available that document table structures.

Related Sections

General Reference

Provides Visual FoxPro related technical information, including file types, file structures, and other reference information about Visual FoxPro elements.
Naming Conventions

Provides links to additional information about choosing names for exposed objects, properties, and methods that can be understood by users of the application easily.
Visual FoxPro and Other Programming Languages

Provides a comparison of Visual FoxPro language elements with other programming languages.


Compound Index File Structure (.cdx)

Visual FoxPro 9.0
Compound Index File Structure (.cdx)
See Also

All compound indexes are compact indexes.

One file structure exists to track all the tags in the .cdx file. This structure is identical to the compact index file structure with one exception — the leaf nodes at the lowest level of this structure point to one of the tags in the compound index.

All tags in the index have their own complete structure that is identical to the compact index structure for an .idx file.

See Also

Other Resources

File Structures
Index File Structure (.idx)
Compact Index File Structure (.idx)
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
Memo File Structure (.FPT)
Macro File Format (.fky)
File Extensions and File Types


Compact Index File Structure (.idx)

Visual FoxPro 9.0
Compact Index File Structure (.idx)
See Also

Compact Index Header Record

Byte offset | Description
00 – 03 | Pointer to root node
04 – 07 | Pointer to free node list ( -1 if not present)
08 – 11 | Reserved for internal use
12 – 13 | Length of key
14 | Index options (any of the following numeric values or their sums): 1 – a unique index 8 – index has FOR clause 32 – compact index format 64 – compound index header
15 | Index signature
16 – 19 | Reserved for internal use
20 – 23 | Reserved for internal use
24 – 27 | Reserved for internal use
28 – 31 | Reserved for internal use
32 – 35 | Reserved for internal use
36 – 501 | Reserved for internal use
502 – 503 | Ascending or descending: 0 = ascending 1 = descending
504 – 505 | Reserved for internal use
506 – 507 | FOR expression pool length1
508 – 509 | Reserved for internal use
510 – 511 | Key expression pool length1
512 – 1023 | Key expression pool (uncompiled)

1 This information tracks the space used in the key expression pool.

Compact Index Interior Node Record

Byte offset Description

00 – 01

Node attributes (any of the following numeric values or their sums): a. 0 – index node b. 1 – root node c. 2 – leaf node

02 – 03

Number of keys present (0, 1 or many)

04 – 07

Pointer to node directly to left of current node (on same level, -1 if not present)

08 – 11

Pointer to node directly to right of current node (on same level; -1 if not present)

12 – 511

Up to 500 characters containing the key value for the length of the key with a four-byte hexadecimal number (stored in normal left-to-right format):

This node always contains the index key, record number and intra-index pointer.2

The key/four-byte hexadecimal number combinations will occur the number of times indicated in bytes 02 – 03.

Compact Index Exterior Node Record

00 – 01 | Node attributes (any of the following numeric values or their sums): 0 – index node 1 – root node 2 – leaf node
02 – 03 | Number of keys present (0, 1 or many)
04 – 07 | Pointer to the node directly to the left of current node (on same level; -1 if not present)
08 – 11 | Pointer to the node directly to right of the current node (on same level; -1 if not present)
12 – 13 | Available free space in node
14 – 17 | Record number mask
18 | Duplicate byte count mask
19 | Trailing byte count mask
20 | Number of bits used for record number
21 | Number of bits used for duplicate count
22 | Number of bits used for trail count
23 | Number of bytes holding record number, duplicate count and trailing count
24 – 511 | Index keys and information2

2 Each entry consists of the record number, duplicate byte count and trailing byte count, all compacted. The key text is placed at the logical end of the node, working backwards, allowing for previous key entries.

See Also

Other Resources

File Structures
Compound Index File Structure (.cdx)
Index File Structure (.idx)
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
Memo File Structure (.FPT)
Macro File Format (.fky)
File Extensions and File Types


File Extensions and File Types

Visual FoxPro 9.0
File Extensions and File Types
See Also

This table lists the extensions and their associated file types that are used with Visual FoxPro.

Extension | File type
.act | Documenting Wizard action diagram
.app | Generated application
.cdx | Compound index
.chm | Compiled HTML Help
.cur | Cursor
.dbc | Database
.dbf | Table
.dbg | Debugger configuration
.dct | Database memo
.dcx | Database index
.dll | Windows dynamic-link Library
.err | Compilation error
.exe | Executable program
.fky | Macro
.fll | Visual FoxPro dynamic-link library
.fmt | Format file
.fpt | Table memo
.frt | Report memo
.frx | Report
.fxp | Compiled program
.h | Header file (for inclusion in a Visual FoxPro or C/C++ program)
.hlp | WinHelp
.htm | HTML
.ico | Icon file
.idx | Single index
.lbt | Label memo
.lbx | Label
.log | Coverage log
.lst | Documenting Wizard list
.mem | Variable save
.mnt | Menu memo
.mnx | Menu
.mpr | Generated menu program
.mpx | Compiled menu program
.ocx | ActiveX control
.pjt | Project memo
.pjx | Project
.prg | Program
.qpr | Generated query program
.qpx | Compiled query program
.sct | Form memo
.scx | Form
.spr | Generated screen program (earlier versions of FoxPro only)
.spx | Compiled screen program (earlier versions of FoxPro only)
.tbk | Memo backup
.txt | Text
.vct | Visual class library memo
.vcx | Visual class library
.vue | FoxPro 2.x view
.win | Window file
.xml | XML

See Also

Other Resources

File Structures
Compact Index File Structure (.idx)
Compound Index File Structure (.cdx)
Index File Structure (.idx)
Memo File Structure (.FPT)
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)


FoxUser Resource File Structure

Visual FoxPro 9.0
FoxUser Resource File Structure
See Also

The FoxPro resource file FoxUser.dbf holds a variety of resource information (for example, window positions, color sets, Browse window configurations, label definitions, and so on.). FoxUser.dbf is a standard FoxPro table with an associated memo file (.FPT). If the index file does not exist, it is created when the FoxUser.dbf file is opened.

Unlike in earlier versions of Visual FoxPro, the FoxUser.dbf resource file is opened SHARED

While RESOURCE is SET ON, FoxPro handles all resource management. You can modify the data contained in this file in two ways:

  1. Special window configurations or other window preferences, once established and saved in the resource file, can be protected from subsequent interactive changes by modifying the READONLY field for the specific resource (see the example in the Predefining Browse Window Configuration section).

  2. Resources that are no longer needed or wanted may be deleted and the resource file may be packed.

Modifying the READONLY field and/or deleting records from the resource file are the only actions you should perform on the FoxUser.dbf file. You should make a copy of the resource file before making any modifications.

The FoxUser.dbf table has the following structure:

Field | Field Name | Type | Width
1 | TYPE | Character | 12
2 | ID | Character | 12
3 | NAME | Memo | 4
4 | READONLY | Logical | 1
5 | CKVAL | Numeric | 6
6 | DATA | Memo | 4
7 | UPDATED | Date | 8
TYPE

Identifies the type of information the resource holds
ID

Identifies the record with the TYPE
NAME

Contains the name assigned to the resource, for instance the name assigned to color sets, BROWSE windows, and system windows
READONLY

A logical field that can be set to true (.T.) to indicate that the resource should be used for read-only access and cannot be changed
CKVAL

Used by FoxPro to verify the data (in the memo field DATA) is valid
DATA

Memo field that holds the actual data for the resource
UPDATED

The date the current resource was last changed

You can make the FoxUser.dbf resource file read-only by marking it at the MS-DOS level. The MS-DOS command ATTRIB uses the <+R> setting to mark a file as read only. Marking a file read-only is useful in multiuser situations, because the FoxUser.dbf can be shared on a network.

Modifying the FoxUser.dbf Resource File

The following SET RESOURCE commands make it possible for you to open and easily modify the FoxUser.dbf file's contents, as well as use a resource file other than FoxUser.dbf.

SET RESOURCE TO <resourcefile>

SET RESOURCE TO

SET RESOURCE ON

SET RESOURCE OFF

If you want to make changes to your resources, in the Command window, use the following commands:

Copy Code
SET RESOURCE OFF
USE FOXUSER
BROWSE

With the resource file open, you can use CHANGE, EDIT, BROWSE, DELETE, REPLACE and other FoxPro commands to modify or delete data. You can even use COPY TO to create a new resource table. When you have finished modifying the resource file, pack it if you marked records for deletion, and close it. Then, set the resource feature on with the following commands:

Copy Code
USE
SET RESOURCE ON

You can open the FoxUser.dbf file in a work area without setting resource OFF by issuing the command USE SYS(2005) AGAIN. SYS(2005) returns the name of the current resource file.

Predefining Browse Window Configuration

One useful modification that you can make to the FoxUser.dbf file is changing the READONLY field for predefined Browse window configurations.

First, adjust a BROWSE window to display specific fields that are sized for easy manipulation, position the window and size it, split the window into two partitions, with one partition in BROWSE mode and one in CHANGE, then close the window. When the BROWSE window is closed, its configuration is saved in the current resource file, provided the field named READONLY is not set to T, and provided the window was not closed with Ctrl+Q.

Then, issue USE SYS(2005) AGAIN and edit the READONLY field, setting it to true ("T"). To do this, look for the BROWSE window resource that has a TYPE of PREFW, and ID of WINDBROW, and a NAME field with the alias of the table you just browsed. When the READONLY field is true (T), the corresponding resource data will not be overwritten if the Browse window configuration is later changed interactively.

Now, whenever the table is browsed with the BROWSE LAST command, the Browse window appears in the same position with all its field, size, and placement configurations the same as the last session. No matter how much the Browse window is changed by the user, it will always return according to the data in the resource when you BROWSE LAST.

See Also

Other Resources

File Structures
Resource Files in Applications
Visual FoxPro Configuration


Index File Structure (.idx)

Visual FoxPro 9.0
Index File Structure (.idx)
See Also

Index files contain one header record and one or many node records. The header record contains information about the root node, the current file size, the length of the key, index options and signature, and printable ASCII representations of the key1 and FOR expressions. The header record starts at file position zero.

The remaining node records contain an attribute, number of keys present, and pointers to nodes on the left and right (on the same level) of the current node. They also contain a group of characters encompassing the key value and either a pointer to a lower level node or an actual table record number. The size of each record that is output to a file is 512 bytes.

Index Header Record

Byte offset | Description
00 – 03 | Pointer to the root node
04 – 07 | Pointer to the free node list ( -1 if not present)
08 – 11 | Pointer to the end of file (file size)
12 – 13 | Length of key
14 | Index options (any of the following numeric values or their sums): 1 – a unique index 8 – index has FOR clause
15 | Index signature (for future use)
16 – 235 | Key expression (uncompiled; up to 220 characters)1,3
236 – 455 | FOR expression (uncompiled; up to 220 characters ending with a null value byte)
456 – 511 | Unused

Index Node Record

Byte offset Description

00 – 01

Node attributes (any of the following numeric values or their sums): 0 – index node 1 – root node 2 – leaf node

02 – 03

Number of keys present (0, 1 or many)

04 – 07

Pointer to the node directly to left of the current node (on same level; -1 if not present)

08 – 11

Pointer to the node directly to right of the current node (on same level; -1 if not present)

12 – 511

Up to 500 characters containing the key value for the length of the key with a four-byte hexadecimal number stored in normal left-to-right format: If the node is a leaf (attribute = 02 or 03) then the four bytes contain an actual table number in hexadecimal format; otherwise, the 4 bytes contain an intra-index pointer.2

The key/four-byte hexadecimal number combinations will occur the number of times indicated in bytes 02 – 03.

1 The type of the key is not stored in the index. It must be determined by the key expression. 2 Anything other than character strings, numbers used as key values, and the four-byte numbers in the leaf node are represented in reversed bytes (Intel 8086 format). 3 Numbers are a special case when used as a key. They are converted through the following algorithm so they can be sorted using the same ASCII collating sequence as characters:

  • Convert the number to IEEE floating point format. For details, see Visual FoxPro System Capacities.

  • Swap the order of the bytes from Intel 8086 order to left-to-right order.

  • If the number was negative, take the logical complement of the number (swap all 64 bits, 1 to 0 and 0 to 1); otherwise, invert only the leftmost bit.

Example of an Ordered Tree Structure

Finding a key in the structure below requires searching a single path between the root and leaf nodes. Nodes at the lowest level are leaf nodes. Because the keys are sorted, all keys in the sub-tree are less than or equal to the parent node.

In the illustration above, the letters are used as the key values. Each key would also have a four-byte hexadecimal number. The numbers associated with the keys in the leaf nodes would be actual table numbers — all keys in other nodes would have intra-index pointers associated with them.

Bytes 12-511 in the index node record could be viewed as follows:

The key value/hexadecimal number combination occurs in bytes 12 – 511 n times where n is the number of keys present.

See Also

Other Resources

File Structures
Compact Index File Structure (.idx)
Compound Index File Structure (.cdx)
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
Memo File Structure (.FPT)
Macro File Format (.fky)
File Extensions and File Types


Macro File Format (.fky)

Visual FoxPro 9.0
Macro File Format (.fky)
See Also

File Header

Byte offset | Description
01 – 03 | Signature, Hex 79FF
04 – 15 | Ignored
16 – 17 | Number of macros (binary)
18 – end | The macros

Individual Macros

Byte offset | Description
00 – 19 | Macro name
20 – 21 | Macro length (in keystrokes, binary)
22 – 23 | Keystroke (two bytes, binary)
24 – end | Macro keystrokes

See Also

Other Resources

File Structures
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
Compound Index File Structure (.cdx)
File Extensions and File Types
Memo File Structure (.FPT)
Compact Index File Structure (.idx)
Index File Structure (.idx)


Memo File Structure (.FPT)

Visual FoxPro 9.0
Memo File Structure (.FPT)
See Also

Memo files contain one header record and any number of block structures. The header record contains a pointer to the next free block and the size of the block in bytes. The size is determined by the SET BLOCKSIZE command when the file is created. The header record starts at file position zero and occupies 512 bytes. The SET BLOCKSIZE TO 0 command sets the block size width to 1.

Following the header record are the blocks that contain a block header and the text of the memo. The table file contains block numbers that are used to reference the memo blocks. The position of the block in the memo file is determined by multiplying the block number by the block size (found in the memo file header record). All memo blocks start at even block boundary addresses. A memo block can occupy more than one consecutive block.

Memo Header Record

Byte offset | Description
00 – 03 | Location of next free block1
04 – 05 | Unused
06 – 07 | Block size (bytes per block)1
08 – 511 | Unused

1 Integers stored with the most significant byte first.

Memo Block Header and Memo Text

Byte offset | Description
00 – 03 | Block signature 1 (indicates the type of data in the block) 0 – picture (picture field type) 1 – text (memo field type)
04 – 07 | Length 1 of memo (in bytes)
08 – n | Memo text (n = length)

1 Integers stored with the most significant byte first.

See Also

Reference

Memo File Structure (.FPT)

Other Resources

File Structures
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
SET BLOCKSIZE Command
Index File Structure (.idx)
Compact Index File Structure (.idx)
Compound Index File Structure (.cdx)
Macro File Format (.fky)
File Extensions and File Types


Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)

Visual FoxPro 9.0
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
See Also

Visual FoxPro uses tables to store data that defines different file types. The following list includes the file types that are saved as tables:

  • Database (.dbc)

  • Form (.scx)

  • Label (.lbx)

  • Menu (.mnx)

  • Project (.pjx)

  • Report (.frx)

  • Table (.dbf)

  • Visual class library (.vcx)

You can use and browse these files in the same way that you browse any table file because these files are actually tables.

A table file consists of a header record and data records. The header record defines the structure of the table and contains any other information related to the table. The header record starts at file position zero. Data records follow the header, in consecutive bytes, and contain the actual text of the fields.

Note:
The data in the data file starts at the position indicated in bytes 8 to 9 of the header record. Data records begin with a delete flag byte. If this byte is an ASCII space (0x20), the record is not deleted. If the first byte is an asterisk (0x2A), the record is deleted. The data from the fields named in the field subrecords follows the delete flag.

The length of a record, in bytes, is determined by summing the defined lengths of all fields. Integers in table files are stored with the least significant byte first.

For information about the table structures of the different file types, see Table Structures of Table Files.

Table Header Record Structure

Byte offset | Description
0 | File type: 0x02 FoxBASE: 0x03 FoxBASE+/Dbase III plus, no memo: 0x30 Visual FoxPro: 0x31 Visual FoxPro, autoincrement enabled: 0x32 Visual FoxPro, Varchar, Varbinary, or Blob-enabled: 0x43 dBASE IV SQL table files, no memo: 0x63 dBASE IV SQL system files, no memo: 0x83 FoxBASE+/dBASE III PLUS, with memo: 0x8B dBASE IV with memo: 0xCB dBASE IV SQL table files, with memo: 0xF5 FoxPro 2.x (or earlier) with memo: 0xFB FoxBASE
1 - 3 | Last update (YYMMDD)
4 – 7 | Number of records in file
8 – 9 | Position of first data record
10 – 11 | Length of one data record, including delete flag
12 – 27 | Reserved
28 | Table flags: 0x01 file has a structural .cdx 0x02 file has a Memo field 0x04 file is a database (.dbc) This byte can contain the sum of any of the above values. For example, the value 0x03 indicates the table has a structural .cdx and a Memo field.
29 | Code page mark
30 – 31 | Reserved, contains 0x00
32 – n | Field subrecords The number of fields determines the number of field subrecords. One field subrecord exists for each field in the table.
n+1 | Header record terminator (0x0D)
n+2 to n+264 | A 263-byte range that contains the backlink, which is the relative path of an associated database (.dbc) file, information. If the first byte is 0x00, the file is not associated with a database. Therefore, database files always contain 0x00.

Field Subrecords Structure

Byte offset Description

0 – 10

Field name with a maximum of 10 characters. If less than 10, it is padded with null characters (0x00).

11

Field type:

W - Blob

C – Character

C – Character (binary)

Y – Currency

B – Double

D – Date

T – DateTime

F – Float

G – General

I – Integer

L – Logical

M – Memo

M – Memo (binary)

N – Numeric

P – Picture

Q - Varbinary

V - Varchar (binary)

Note:
For each Varchar and Varbinary field, one bit, or "varlength" bit, is allocated in the last system field, which is a hidden field and stores the null status for all fields that can be null. If the Varchar or Varbinary field can be null, the null bit follows the "varlength" bit. If the "varlength" bit is set to 1, the length of the actual field value length is stored in the last byte of the field. Otherwise, if the bit is set to 0, length of the value is equal to the field size.

12 – 15

Displacement of field in record

16

Length of field (in bytes)

17

Number of decimal places

18

Field flags: 0x01 System Column (not visible to user) 0x02 Column can store null values 0x04 Binary column (for CHAR and MEMO only) 0x06 (0x02+0x04) When a field is NULL and binary (Integer, Currency, and Character/Memo fields) 0x0C Column is autoincrementing

19 - 22

Value of autoincrement Next value

23

Value of autoincrement Step value

24 – 31

Reserved

For information about limitations on characters per record, maximum fields, and so on, see Visual FoxPro System Capacities.

Remarks

Visual FoxPro modifies the table header when you turn on or add autoincrementing for field values.

Visual FoxPro does not modify the header of a file that has been saved to a FoxPro 2.x file format unless one of the following features has been added to the file:

  • Null value support

  • DateTime, Currency, and Double data types

  • CHAR or MEMO field is marked as Binary

  • A table is added to a database (.dbc) file

    Tip:
    You can use the following formula to return the number of fields in a table file: (x – 296/32). In the formula, x is the position of the first record (bytes 8 to 9 in the table header record), 296 is 263 (backlink info) + 1 (header record terminator) + 32 (first field subrecord), and 32 is the length of a field subrecord.

See Also

Other Resources

File Structures
Code Pages Supported by Visual FoxPro
Data and Field Types
Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
How to: Check for Differences in Forms, Reports, and Other Table Files
File Extensions and File Types


Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)

Visual FoxPro 9.0
Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
See Also

The descriptions of the table structures are stored in files located in the FILESPEC directory. The FILESPEC directory contains two project files: 60SPEC.pjx and 26SPEC.pjx. The 60SPEC.pjx file contains tables and reports that document Visual FoxPro versions 5.0 and later. The 26SPEC.pjx file contains tables and reports that document FoxPro version 2.6 table files.

To see the descriptions for any table structure, print the appropriate report. The following tables list the file types and their associated reports. Some file types require more than one report because there are too many columns to fit across a single page.

Note:
All the reports are formatted for landscape printing.

Files Types for Visual FoxPro 5.0 and Later

To see the table structure of a... | Print this report | Which uses
Database1 | 60DBC.frx | 60DBC.dbf
Form and Visual Class Library | 60SCX1.frx 60SCX2.frx | 60SCX.dbf
Menu2 | 60MNX.frx | 60MNX.dbf
Project | 60PJX1.frx 60PJX2.frx | 60PJX.dbf
Report and Label | 90FRX.frx or 60FRX1.frx and 60FRX2.frx | 60FRX.dbf

1 The database properties can be printed from 60DBCPRO.frx. 2 The location field in Visual FoxPro 6.0 structure differs from Visual FoxPro 5.0 structure. Additional fields to support pictures in Visual FoxPro 7.0 are included in the report.

FoxPro version 2.6

To see the table structure of a... | Print this report | Which uses
Screen | 26SCX1.frx 26SCX2.frx | 26SCX.dbf
Menu | 26MNX.frx | 26MNX.dbf
Project | 26PJX1.frx 26PJX2.frx | 26PJX.dbf
Report and Label | 26FRX1.frx 26FRX2.frx | 26FRX.dbf

See Also

Concepts

Understanding and Extending Report Structure

Other Resources

File Structures
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
Code Pages Supported by Visual FoxPro
Data and Field Types
How to: Check for Differences in Forms, Reports, and Other Table Files
File Extensions and File Types


Fonts Overview

Visual FoxPro 9.0 Language Reference
Fonts Overview
See Also

Visual FoxPro can use the fonts you have installed. Fonts determine the appearance of displayed or printed text. In addition, fonts determine the position and size of controls.

Control Size and Position

In Visual FoxPro, the ScaleMode property for the Form on which a control is placed determines the control's size and position. If ScaleMode is set to Pixels (3), the size of a control is specified in pixels. If ScaleMode is set to Foxels (0), the size of a control is determined by the Form's current font and font size.

Foxel is a Visual FoxPro term that corresponds to the maximum height and average width of a character in the current font. The row height corresponds to the maximum height of a letter in the current font; the column width corresponds to the average width of a letter in the current font.

In Visual FoxPro, you can use decimal fractions for row and column coordinates to facilitate precise positioning of controls and output. In FoxPro for MS-DOS, fractional portions of row and column coordinates are ignored.

In Visual FoxPro, to determine or change the font for the main Visual FoxPro window, press SHIFT while you display the Format menu, then choose the Screen Font option. The font for a user-defined window can be specified by including the FONT clause when you create the window with DEFINE WINDOW.

Font Substitution

If you specify a font that is not available, Windows substitutes a font with similar font characteristics. Windows considers the point size, serif characteristics and the pitch of the font you request. A TrueType font is typically substituted. A raster or vector font is only substituted when the characteristics of the font you request closely match those of the raster or vector font.

Font Functions

Several functions can be used to return information about fonts and text in a specific font.

The following table describes these functions.

Function | Description
AFONT( ) | Places information about available fonts into an array.
FONTMETRIC( ) | Returns font attributes for installed fonts.
GETFONT( ) | Displays the Font dialog and returns the name of the font you choose.
SYSMETRIC( ) | Returns the size of a display element.
SCOLS( ) | Returns the number of columns available in the main Visual FoxPro window. Useful when centering text or controls in the main Visual FoxPro window.
SROWS( ) | Returns the number of rows available in the main Visual FoxPro window.Useful when centering text or controls in the main Visual FoxPro window.
WCOLS( ) | Returns the number of columns within the specified window.Useful when centering text or controls in a user-defined window.
WFONT( ) | Returns the name, size or style of the current font for a window.
WROWS( ) | Returns the number of columns within the specified window.Useful when centering text or controls in a user-defined window.

See Also

Other Resources

ScaleMode Property
Functions
Properties


Graphics Support in Visual FoxPro

Visual FoxPro 9.0
Graphics Support in Visual FoxPro
See Also

Visual FoxPro 8.0 and later replaces native support for rendering Graphics Interchange Format (.gif) and Joint Photographic Electronic Group (.jpeg) formats with Graphics Device Interface+ (GDI+) for Microsoft Windows XP and later. Visual FoxPro supports all formats that GDI+ handles, including animated .gif files.

The following table lists the graphics formats that Visual FoxPro supports.

File extension | File type name
.ani | Animated Cursor
.bmp | Bitmap
.cur | Cursor
.dib | Device Independent Bitmap
.emf | Windows Enhanced Metafile
.exif | Exchangeable Image File
.gif, .gfa | Graphics Interchange Format
.ico | Icon
.jpg, .jpeg, .jpe, .jfif | Joint Photographic Electronic Group, JPEG File Interchange Format
.png | Portable Networks Graphics
.tif, .tiff | Tag Image File Format
.wmf | Windows Metafile
Note:
In Visual FoxPro, cursor, animated cursor, and icon files can be used as graphics files. For example, you can specify an animated cursor file for the Picture property for the Image control. However, the Image control displays the static representation of the cursor.

If Visual FoxPro does not recognize a particular version of a natively supported format such as a .bmp, .dib, .cur, .ani, or .ico, it passes them to GDI+ for rendering. Therefore, as new static file formats become supported in future versions of GDI+, Visual FoxPro can support them automatically.

With GDI+, Visual FoxPro includes the RotateFlip property on the Image control so you can rotate and invert, or flip, an image. For more information, see RotateFlip Property.

Note:
GDI+ is installed with the Windows XP operating system and is required to run Visual FoxPro. Visual FoxPro includes a merge module for redistribution with custom applications running on Windows 98, Windows Me, and Windows 2000 platforms.

Visual FoxPro provides graphics support in the following three areas:

  • Language

  • Controls and objects

  • User interface

Language

You can use the GETPICT( ) function to access the Visual FoxPro dialog that provides access to valid file formats. You also can access graphics through properties in the controls and objects described here.

Controls and Objects

The following table lists Visual FoxPro controls and objects with properties for which you can specify graphics files. You can now specify .gif, .jpg, .cur, .ani, and .ico graphic files for these properties in addition to the .bmp and .dib graphic files supported in previous versions of Visual FoxPro.

Control or object | Properties
CheckBox control | DisabledPicture DownPicture Picture
CommandButton control | DisabledPicture DownPicture Picture
ComboBox control | Picture
Container object | Picture
Control object | Picture
Custom object | Picture
Form object | Picture
Image control* | Picture
ListBox control | Picture
OptionButton control | DisabledPicture DownPicture Picture
Page object | Picture
_SCREEN system variable | Picture

* Visual FoxPro supports animated .gif files only for the Picture property of an Image control.

User Interface

You can choose graphics files by using the Open dialog box in several Visual FoxPro designers. The Open dialog box for the following designers includes all valid graphic file formats.

Form Designer and Class Designer

You can find and select an image by opening the Open dialog box in the Form and Class designers for a property in those controls that support graphics files.

To select an image in the Form and Class designers

  • In the Properties window, double-click the Picture property.

Visual FoxPro displays the Open dialog box for you to find and select an image.

Project Manager

You can find, select, and add a graphics file to a project in the Project Manager.

To add a graphics file to a project

  • In the Project Manager, select Other Files in the All or Other tabs and click Add.

Visual FoxPro displays the Open dialog box for you to find and select an image.

GDI+ Image Support

GDI+ is a class-based application programming interface (API) for C/C++ programmers. It enables applications to use graphics and formatted text on both the video display and the printer. Applications based on the Microsoft Win32 API do not access graphics hardware directly. Instead, GDI+ interacts with device drivers on behalf of applications. GDI+ is also supported by the 64-bit Windows operating system.

GDI+ can be used in all Windows-based applications. GDI+ is included in Microsoft Windows XP and Windows Server 2003 operating systems. GDI+ is required and available as a redistributable for Visual FoxPro applications that run on the Windows 2000, Windows Millennium Edition, and Windows 98 operating systems. To download the most recent distributable, visit the Microsoft Windows Platform SDK Web site at http://www.microsoft.com/msdownload/platformsdk/sdkupdate/ or the Microsoft Download Center Web site at http://www.microsoft.com/downloads/.

Visual FoxPro might include both VFP9R.dll and VFP9T.dll run-time libraries. The GDIPlus.dll file must be present in the system directory of the user's computer.

Animated .gif Image Support

Animated .gif files are a popular variety of the .gif file format. They use the same file extension (.gif) and contain specific image frames that cycle through to produce an animated effect. The animated .gif file contains the number of times the .gif file cycles through before stopping. Visual FoxPro supports animated .gif files as follows:

  • Visual FoxPro supports animated .gif files only for the Picture property in the Image control.

  • Animated .gif files are displayed at both design and run time.

  • Visual FoxPro displays only the first frame of an animated .gif file when it appears anywhere else but the Image control.

  • Visual FoxPro cycles through an animated .gif file based only on its internal loop count setting.

  • Visual FoxPro pauses between animation loops for one second.

  • If the size or location of the Image control changes at run time while an image animation plays, Visual FoxPro resets to the first frame and continues.

  • Visual FoxPro draws the .gif image size as specified by the .gif file author, not the Image control. Visual FoxPro does not clip or stretch the image.

  • During animations, the entire image or part of it is erased so that the next frame can be redrawn. Visual FoxPro minimizes unnecessary redrawing to avoid flickering. If the image position is moved, for example, the control or its container is moved, the entire image needs to be redrawn.

  • Because Visual FoxPro internally stores a single representation of a particular image as an off-screen bitmap, multiple Image controls using the same animated .gif file are always synchronized together. If you want the animations of the same image to behave differently for each Image control, you should create a copy of each animated .gif file and rename each one.

  • The author of animated .gif files can specify the amount of time between frames. This amount of time can differ between each frame. Therefore, it is possible for animated .gif files to have excessively long delays between frames.

  • If you use an animated .gif file in a control other than an Image control, animation of the image does not play. However, if you later use the image in an Image control, the image animates only if you first issue a CLEAR...RESOURCES command. This occurs because the image is already stored in memory, and the animation attribute is being ignored when the image is rendered in a non-image control. You must use CLEAR...RESOURCES to reload the image into memory.

See Also

Other Resources

General Reference
How to: Create Access and Assign Methods
Access and Assign Methods
Picture Property
Image Control
CLEAR Commands


Keyboard Shortcuts (Visual FoxPro)

Visual FoxPro 9.0
Keyboard Shortcuts (Visual FoxPro)
See Also

Visual FoxPro supports keyboard shortcuts in these areas:

  • Browse window

  • Class Browser

  • Code window

  • Controls

  • Editor

  • Form Designer and Class Designer

  • Help

  • Menu commands

  • Print Preview window

  • Properties window

  • Report Designer and Label Designer

  • Window manipulation

Browse Window

Shortcut | Action
CTRL+HOME | Moves to first record of a cursor or table in a grid and when using the BROWSE command.
CTRL+END | Moves to the last record of a cursor or table in a grid and when using the BROWSE command.
CTRL+HOME CTRL+SHIFT+HOME CTRL+PAGE UP CTRL+PAGE DOWN | Opens an editing window when pressed in a memo field.

Class Browser

Shortcut | Action
F5 | Refreshes the current view.
SHIFT+F10 | Displays a shortcut menu.
Right-click+Open button Right-click+Add button Right-click+Component Gallery button | Displays a history of last 32 files loaded.
Right-click+View Class Code button | Displays the class code in a webview form.
CTRL+Right-click+Class icon (in upper left corner of the Class Browser) | Creates an instance of the class with the NEWOBJECT( ) function in the Command window. Identical to dragging the Class icon onto the Command window.
SHIFT+Right-click+Class icon (in upper left corner of the Class Browser) | For forms, runs the form. For other controls and objects, creates an instance of the control or object. For controls, also adds the control to the Visual FoxPro desktop at 0,0. Identical to dragging the Class icon onto the Visual FoxPro desktop.

Code Window

Shortcut | Action
ALT+I | Presses the View Parent Code button.

Controls

Shortcut | Action
CTRL+TAB | When a Grid control has focus, exits the grid. When an EditBox control has focus, and EditBox AllowTabs property is True (.T.), exits the edit box. When inside a form or dialog box containing a PageFrame control, moves to the next page in the page frame. However, this behavior is not supported in project files or when the page frame contains an ActiveX control.
CTRL+SHIFT+TAB | If inside a form or dialog box containing a PageFrame control, moves to the previous page in the page frame. However, this behavior is not supported in project files or when the page frame contains an ActiveX control.
TAB | When a Grid control has focus, moves to the next field.

Editor

Shortcut | Action
ALT+Drag | Cuts and pastes. Note To change the default drag-and-drop behavior from dragging text in words to dragging text between words, on the Tools menu, click the Editor tab, and select the Drag drop between words option. To toggle between dragging text within words and dragging text between words, press ALT+Drag.
CTRL+Drag | Copies and pastes.
CTRL+I | Show IntelliSense Quick Info.
CTRL+J | Show IntelliSense List Members or List Values.
F2 | Moves to the line containing the next bookmark.
SHIFT+F2 | Moves to the line containing the previous bookmark.
ALT+SHIFT+F2 | Toggles a bookmark for the current line on and off.
F3 | Finds the next occurrence of the specified text.
CTRL+F3 CTRL+G | Finds the next occurrence of the selected text.
SHIFT+F3 | Finds the previous occurrence of the specified text.
CTRL+SHIFT+F3 | Finds the previous occurrence of the selected text.
CTRL+DOWNARROW | Scrolls window up without moving cursor.
CTRL+UPARROW | Scrolls window down without moving cursor.
CTRL+LEFTARROW | Moves the cursor one word to the left.
CTRL+RIGHTARROW | Moves the cursor one word to the right.
F9 | Inserts or removes a breakpoint.
CTRL+F9 | Enables or disables a breakpoint.
CTRL+B | Brings up Breakpoints dialog box.
ALT+F2 | Adds/Removes Task List shortcut.
CTRL+U | Makes the selection all lowercase.
CTRL+SHIFT+U | Makes the selection all uppercase.
CTRL+BACKSPACE | Deletes a word to the left.

Form Designer and Class Designer

Shortcut | Action
Arrow keys | Moves the selected control or controls in pixel increments.
CTRL+E | Runs the form in the Form Designer.
CTRL+SHIFT+Click the control | Drills down to a control in a container.
CTRL+Click the container | Drills down through the container.
SHIFT+Arrow key | Changes the height or width of the selected control or controls in pixel increments.

Help

Shortcut | Action
F1 | Displays Help topics or context-sensitive Help on active items, for example, a highlighted keyword in the Command window or the current property in the Properties window.
SHIFT+F1 | Enables user-prompted context-sensitive Help. The insertion pointer changes to a question mark so that you can click an item, for example, a menu command or toolbar, to display context-sensitive Help.

Menu Commands

Shortcut | Command
CTRL+A | Select All on the Edit menu.
CTRL+C | Copy on the Edit menu.
CTRL+D | Do on the Program menu.
CTRL+E | Delete Item on the Menu menu.
CTRL+E | Do <program> on the Program menu. Run Form on the Form menu.
CTRL+F | Find on the Edit menu.
CTRL+G | Find Again on the Edit menu.
CTRL+H | Change Partitions on the Table menu.
CTRL+I | Insert Item on the Menu menu.
CTRL+J | Project Info on the Project menu.
CTRL+L | Replace on the Edit menu.
CTRL+M | Resume on the Program menu.
CTRL+N | New on the File menu.
CTRL+O | Open on the File menu.
CTRL+P | Print on the File menu.
CTRL+Q | Closes current text window and discards changes. See also CTRL+W. Run Query on the Query menu.
CTRL+R | Redo on the Edit menu.
CTRL+S | Save on the File menu.
CTRL+T | Toggle Deletion Mark on the Table menu.
CTRL+V | Paste on the Edit menu.
CTRL+W | Closes current text window or dialog box and saves changes.
CTRL+X | Cut on the Edit menu.
CTRL+Y | Append New Record on the Table menu.
CTRL+Z | Undo on the Edit menu.

Print Preview Window

Shortcut | Action
Z | Zooms in and out of the page.
L | Toggles between various zoom levels.
G | Opens Goto page dialog box.
ESC | Closes Print Preview window.
LEFTARROW | Scrolls to the left of the page in the Print Preview window.
RIGHTARROW | Scrolls to the right of the page in the Print Preview window.
UPARROW | Scrolls towards the top of the page in the Print Preview window.
DOWNARROW | Scrolls towards the bottom of the page in the Print Preview window.
PAGEDOWN | Moves to the next page in the Print Preview window.
PAGEUP | Moves to the previous page in the Print Preview window.
HOME | Moves to the first page in the Print Preview window.
END | Moves to the last page in the Print Preview window.

Properties Window

Shortcut | Action
ALT+DOWN ARROW | Expands the object list.
ALT+UP ARROW | Closes the object list.
CTRL+PAGE DOWN DOWN ARROW RIGHT ARROW | Moves to next object in the object list.
CTRL+PAGE UP UP ARROW LEFT ARROW | Moves to previous object in object list.
CTRL+END | Moves to last object in the object list.
CTRL+HOME | Moves to first object in the object list.
TAB | Moves to the next control in the Properties window.
SHIFT+TAB | Moves to the previous control in the Properties window.
SHIFT+F10 | Displays the appropriate shortcut menu.
CTRL+ALT+letter | Selects the next property in the properties list that begins with the letter character. For example, pressing CTRL+ALT+B selects the next property that begins with B.

Report Designer and Label Designer

Shortcut | Action
ALT+ENTER | Opens the appropriate report control settings dialog box.
Arrow keys | Moves the selected control or controls in pixel increments.
CTRL+E | Enters Edit mode for a Label control when it is selected in the Report designer.
ESC | Exits Edit mode for a Label control and returns to Select mode.
SHIFT+Arrow key | Changes the height or width of the selected control or controls in pixel increments.
SHIFT+TAB | Moves to the previous object on the Report Designer when in Tab mode.
SHIFT+Double Click on a report band | Selects all objects in the band.
TAB | Enters Tab mode automatically and moves to the next object in the Report Designer.

Window Manipulation

Shortcut | Action
CTRL+F1 | Cycles through windows.
CTRL+TAB | Moves to the next window.
CTRL+SHIFT+TAB | Moves to the previous window.
CTRL+F2 | Displays Command window.
CTRL+F4 | Closes active window.
CTRL+F6 | Moves to the next window.
CTRL+ALT+SHIFT | Hides all child windows while the keys are pressed down. Hiding windows makes it easy to see output displayed in the main application window.
CTRL+F10 | Toggles window size between maximum and restore.

Visual FoxPro preserves the order of windows and brings the newest window to the foreground instead of shifting the last window to the background when cycling through windows.

See Also

Other Resources

General Reference
Debugger Keyboard Shortcuts and Menus
Command Window
Class Browser Window


MemberData Extensibility

Visual FoxPro 9.0
MemberData Extensibility
See Also

Visual FoxPro 9.0 provides extended metadata attributes for class members. Through this new extensibility model, you now have the ability to extend the functionality of class properties and methods, allowing you to create design-time enhancements such as the following:

  • Specify a custom property editor.

  • Add a property, event, or method to the new Favorites tab in the Properties window.

  • Control the display (capitalization) of a custom property or method in the Properties window and IntelliSense.

  • Extend with user-defined attributes.

MemberData Extensible Model

Extensibility is provided through MemberData which uses an XML string to specify the metadata settings for class properties and methods.

The customization you add to _MemberData is at the class and global levels. The class level always overrides the global level. At the class level, support is handled by the _MemberData Property. This property contains an XML string with the actual member metadata. As a property, it is inherited and overridden by subclasses. At the global level, MemberData is specified in special Foxcode.dbf records.

MemberData Inheritance

The inheritance structure for MemberData traverses the following path:

Copy Code
Class -> Container -> Global

The inheritance behavior is similar to (but not the same as) standard object-oriented programming inheritance. Visual FoxPro will first look for MemberData at the Class level along the parent hierarchy. If the particular MemberData attribute or tag is not found, then the Containership hierarchy is searched (from inner container to outer). Finally, if the search is not successful at the Container level, then MemberData is searched for at the Global level (the table specified in the _FOXCODE system variable). It is important to understand that searching occurs for a particular attribute or tag within the MemberData XML (not just the existence of MemberData itself). Therefore, it is possible to have MemberData that spans multiple locations. The following example illustrates this.

A form (Myform) containing a pageframe (Mypageframe) that has a button (Mycmd) which is inherited from _commandbutton in FFC\_base.vcx has a property called “Myprop” with MemberData associated with it. The MemberData Hierarchy for Myprop is as follows:

Copy Code
** Class Level - Mycmd (Myclasses.vcx)
<memberdata name="Myprop" display="MYProp" type="property"/>

** Class Level - _commandbutton (_base.vcx)
<memberdata name="Myprop" display="MYPROP" type="property"/>

** Container Level - mypageframe (myclasses.vcx)
<memberdata name="Myprop" favorites="True" display="myPRop" type="property"/>

** Container Level - myform (myclasses.vcx)
<memberdata name="Myprop" favorites="False" helpfile="Myhelp.chm" type="property"/>

** Global Level - foxcode.dbf
<memberdata name="Myprop" type="property" display="MYPROP" script="DO (_CODESENSE) WITH 'RunPropertyEditor','','MYPROP'"/>

Based on the priority of (Class -> Container -> Global), the current values for Myprop MemberData settings are as follows:

Copy Code
display="MYProp"
favorites="True"
script="DO (_CODESENSE) WITH 'RunPropertyEditor','','myprop'"
helpfile="myhelp.chm"   (note: this is a custom user-defined attribute)

Remarks

MemberData can contain XML as defined by the MemberData XSD Schema described below.

MemberData is case-sensitive. Attributes such as Favorites must be specified as “favorites.” Values are also case-sensitive (e.g., favorites=”True”).

MemberData does not need to be set for each defined attribute or tag. If a particular requested MemberData attribute or tag is not found at the current level, other MemberData along the inheritance path is searched.

If the MemberData XML contains an Override attribute set to True, additional inheritance path searching is suspended beyond that point.

If the MemberData is not valid XML, the entire XML is ignored and the search continues along the inheritance path.

If an entry in MemberData does not contain a valid value (e.g., favorites=”123”), the entry is ignored. However, the search is also suspended (similar to having Override attribute set to True).

FOXCODE.dbf, the Global Store

FOXCODE.dbf, the global store, is a Visual FoxPro table that stores IntelliSense information. If a property or method specified in the _MEMBERDATA property cannot be found in its inheritance tree, FOXCODE.dbf is searched. Because FOXCODE.dbf is a global store, any property or method setting applies to all Visual FoxPro properties or methods unless the _MEMBERDATA property is used to override the FOXCODE.dbf settings.

Note:
For events, only the favorites attribute is recognized. The favorites attribute determines if a property, event, or method appears in the Favorites tab in the Properties window.

FOXCODE.dbf MEMBERDATA Format

The following table describes the format in which MemberData information is stored in FOXCODE.dbf. Each MemberData entry requires a single record with a Type field set of "E."

Field Name | Value | Description
Type | E |
Abbrev | <name> | Name of the property, event1, or method.
Cmd | {command} | Script to run for the property or method.
Tip |  | MemberData XML string for the property or method.
Data |  | Contents of the script to run for a custom property editor.

1 For events, only the favorites attribute is stored. The attribute is specified in the MemberData XML string in the Tip field.

MemberData XML Content Definition

The following table lists the reserved XML elements and attributes recognized by Visual FoxPro 9.0.

Note:
You can include MemberData XML with your own custom elements and attributes which Visual FoxPro will preserve but ignore.

Element | Attribute | Parent | Description
VFPData |  |  | Root element denoting the metadata for a class.
memberdata |  | VFPData | An element containing metadata for a specific member. A member is defined as a property or method.
memberdata | name |  | Name of the member (for example, Caption or MyProperty).
memberdata | type |  | Property or method.
memberdata | display |  | Visual representation of member. This affects the display in the Properties window as well as in IntelliSense.
memberdata | favorites |  | True or False.
memberdata | override |  | True or False.
memberdata | script |  | Script method to execute.

MemberData XSD Schema

The following is the MemberData XSD schema Visual FoxPro employs. Descriptions of special attributes are included in the schema.

Note:
The VFP MemberData schema shown below includes two MemberData document variants: a sequence of memberdata elements supported for use with Visual FoxPro classes, and a sequence of reportdata elements supported for use in extending the Visual FoxPro Reporting System. Visual FoxPro does not use reportdata elements directly, but the parallel document design allows you to use similar mechanisms to parse both types of extensions and store them in a common global store. Like class memberdata, reporting MemberData can be used both at design time and run time. For more information, see Report XML MemberData Extensions.

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified" attributeFormDefault="unqualified">
 <xs:element name="VFPData">
  <xs:complexType>
   <xs:choice>
    <xs:sequence>

     <xs:element name="reportdata" maxOccurs="unbounded">
      <xs:complexType>
       <xs:attributeGroup ref="Common"/>
       <xs:attributeGroup ref="ReportTemplate"/>
       <xs:anyAttribute processContents="lax"/>
      </xs:complexType>
     </xs:element>
    </xs:sequence>
    <xs:sequence>

     <xs:element name="memberdata" maxOccurs="unbounded">
      <xs:complexType>
       <xs:attributeGroup ref="Common"/>
       <xs:attributeGroup ref="PropertySheet"/>
       <xs:anyAttribute processContents="lax"/>
      </xs:complexType>
     </xs:element>

    </xs:sequence>
   </xs:choice>
  </xs:complexType>
 </xs:element>

 <xs:annotation>
  <xs:documentation>
  You can add extension attributes as required.
  </xs:documentation>
  <xs:documentation>
Use the name and ref attributes of the Common attribute group to
declare that certain rows "belong" to you. Use the script attribute of
the Common attribute group for design-time scripting.
  </xs:documentation>
   </xs:annotation>

 <xs:attributeGroup name="Common">
  <xs:attribute name="name" type="xs:string" use="required"/>
  <xs:attribute name="type" type="xs:string"/>
  <xs:attribute name="script" type="xs:string"/>
 </xs:attributeGroup>

<xs:annotation>
<xs:documentation>
The ReportTemplate-specific execute attribute is a script run at
runtime (by Listeners) whereas the Common script attribute is
potentially run by design-time tools. The declass and declasslib
attributes are looked for in the header record's template information,
not individual DataEnvironment related object records. The class and
classlib attributes in the header record are not used, and can be
leveraged for a custom helper class for report builders or listeners as
desired. Class and classlib attributes in layout objects are meant for
use in run-time and design-time templating. You can use these template
classes to build custom rendering objects at runtime or to assign
common style attributes at design-time, or both.
</xs:documentation>
 </xs:annotation>

 <xs:attributeGroup name="ReportTemplate">
  <xs:attribute name="class" type="xs:string"/>
  <xs:attribute name="classlib" type="xs:string"/>
  <xs:attribute name="declass" type="xs:string"/>
  <xs:attribute name="declasslib" type="xs:string"/>
  <xs:attribute name="execute" type="xs:string"/>
  <xs:attribute name="execwhen" type="xs:string"/>
 </xs:attributeGroup>

 <xs:attributeGroup name="PropertySheet">
  <xs:attribute name="override" type="xs:boolean"/>
  <xs:attribute name="display" type="xs:string"/>
  <xs:attribute name="favorites" type="xs:boolean"/>
 </xs:attributeGroup>

</xs:schema>

MemberData Example

The following is an example MemberData XML string that demonstrates the use of the reserved Visual FoxPro 9.0 XML elements and attributes. The first section adds the BorderStyle property to the Favorites tab in the Properties window and displays the property name in upper-case.

The second section creates a custom property named MyProperty that is also added to the Favorites tab in the Properties window. The script named MyPropertyScript is executed when the ellipsis button for the custom property is chosen or you double-click the property.

Copy Code
<?xml version="1.0" encoding="Windows-1252" standalone="yes"?>
<VFPData>
<memberdata name="borderstyle" type="property" favorites="True" display="BORDERSTYLE"override="False"/>
<memberdata name="MyProperty" type="property" display="MyProperty" favorites="True" override="False" script="MyPropertyScript"/>
</VFPData>

Custom Property Editors

You can create your own custom property editor in Visual FoxPro 9.0. Your custom property editor can be run by selecting the property in the Properties window and then choosing the ellipsis (…) button or by double-clicking the property. The ellipsis button is only displayed when a property has a custom property editor.

Visual FoxPro supports custom property editors in the following manner:

  • When the Properties window is opened, Visual FoxPro looks at the _MemberData property and its inheritance tree. If a value for the script attribute exists for a property and the script is valid, the ellipses button is displayed for the property.

  • The script is executed when the ellipsis button for the custom property is chosen or you double-click the property.

  • Custom and native Visual FoxPro properties can have custom property editors. For native Visual FoxPro properties, the script must return the proper data type and value for the property, otherwise an error is generated.

  • A custom property editor will override the native Visual FoxPro property editor (for example, the Color Picker for the ForeColor property).

  • Like the Visual FoxPro builder applications, a custom Property editor is responsible for setting the correct property value. A custom Property editor should use the ASELOBJ( ) Function to return a reference to the selected object or objects. Property editors should work in a similar manner as the Visual FoxPro builder applications, and should hide the Properties window if it is not docked. For more information about custom builder applications, see How to: Specify a Builder Application with Builder.dbf with Builder.dbf.

Custom Property Editor Menu Hooks

You can execute your own custom property editor when you choose the MemberData Editor… option from the Form menu, or when you right-click a property, event, or method and choose the Add to Favorites… option in the shortcut menu.

When you choose the MemberData Editor… option from the Form menu, four parameters are passed to the application specified in the _BUILDER System Variable. The following table describes the type of data passed to the parameters in the Builder application.

Parameter Number | Description
1 | Top level object (container) reference.
2 | "MemberData" text string.
3 | Numeric value, 0 for the class designer, 1 for the form designer.
4 | Name of the property, event, or method selected as a text string.

For example, choosing the MemberData Editor… option from the Form menu is identical to executing the following command:

Copy Code
DO (_BUILDER) WITH oForm, "MemberData", 1

If no property is selected or the Properties window is closed, the last parameter will contain an empty string. If the Properties window is closed, the base object is passed as the first parameter. If multiple objects are selected, only the first one is passed as the first parameter.

When you choose the Add to Favorites… option in the shortcut menu, four parameters are passed to the application specified in the _BUILDER System Variable. The following table describes the type of data passed to the parameters in the Builder application.

Parameter | Description
1 | Top level object (container) reference.
2 | "MemberData" text string.
3 | Numeric value, 10 for the class designer, 11 for the form designer.
4 | Name of the property, event, or method selected as a text string.

For example, choosing the Add to Favorites… option in the shortcut menu when the Caption property is selected in the Property window is identical to executing the following command:

Copy Code
DO (_BUILDER) WITH oForm, "MemberData", 11, "Caption"
Note:
The Add to Favorites… option in the shortcut menu is disabled when the Properties window is open for the Visual FoxPro _SCREEN application system variable.

MemberDataEditor.app

Visual FoxPro includes a Member Data Editor application, MemberDataEditor.app, which lets you easily edit member metadata for properties, events, and method. When the Properties window is open, you can run MemberDataEditor.app by choosing the MemberData Editor… option from the Form menu.

The MemberDataEditor.app allows you to do the following:

  • Create MemberData for a property or method.

  • Specify if the MemberData is global (MemberData is written to FoxCode.dbf).

  • Specify if the MemberData overrides the global MemberData attributes.

  • Specify if default behavior is used for unspecified property or method attributes.

  • Add a property, event, or method to the Favorites tab in the Properties window.

  • Create a script (Visual FoxPro code) for a property or method.

  • Specify how a property or method is displayed in the Properties window, and specify display defaults.

  • Specify how XML elements are formatted.

For more information, see MemberData Editor.

Foxcode.dbf Script Hooks

Several new script records can be added to _FOXCODE (FoxCode.dbf) that contain special scripts (Visual FoxPro code) that are called during design time.

Note:
The script records are not included in the default _FOXCODE table. You can find Visual FoxPro Menu Scripts in the Solution Samples application under New in Visual FoxPro 9.0. For more information about the application, see How to: Run Visual FoxPro Solution Samples.

_GetMemberData Script

The _GetMemberData script can be used by a custom property editor to add a _MEMBERDATA property to a container or controls when they are opened in the Form or Class designers. The _GetMemberData script is called for the following events:

  • When the Form or Class Designer is opened.

  • When a new control is added to the Form or Class Designer.

  • When a control is selected in the Form or Class Designer, or a container is clicked to select it.

The following table lists the fields and field values in the Foxcode.dbf record.

Field Name | Value | Description
Type | E | Indicates that the item is a property or method that has member metadata.
Abbrev | _GETMEMBERDATA | Indicates this is the record for a _GetMemberData script.
Data |  | Script to run for the property or method.

The _GetMemberData script is not passed any parameters.

Note:
The _GetMemberData script can use the ASELOBJ( ) Function to obtain an object reference for the currently selected control or container.

MenuHit Script

The MenuHit script is called when a Visual FoxPro system menu is chosen. It can be used to override an existing Visual FoxPro dialog box with a custom dialog box.

The following table lists the fields and field values in the Foxcode.dbf record.

Field Name | Value | Description
Type | S | Indicates that the item is a script.
Abbrev | MENUHIT | Indicates this is the MenuHit script record.
Data |  | Script (Visual FoxPro code) to run for the custom dialog box.

The MenuHit script is passed two parameters as character strings:

Parameter | Description
UserTyped | The internal Visual FoxPro system menu title from which the menu item was selected. The empty string is passed to this parameter if the menu is a shortcut menu.
MenuItem | The internal Visual FoxPro name of the chosen menu item.

See System Menu Names for a listing of the internal Visual FoxPro system menu names.

To prevent Visual FoxPro from handling the menu, set the parameter object's ValueType property to V or L.

Note:
Since _Foxcode supports a single MenuHit script record and it is possible that you may want to handle multiple menu items with your own custom scripts, it is recommended that you create a default MenuHit handler record that can call other records. The Foxcode menu scripts Solution Sample contains a recommended generic Menuhit script that you can use.

The following is an example script for the MenuHit record that you can use for looking up other records in _Foxcode whose Type field = "M", Abbrev field is name of menu and Data field contains script to execute. This is the same script installed for both MenuHit and MenuContext scripts by the Foxcode menu scripts Solution Sample.

Copy Code
LPARAMETERS toParameter

LOCAL lnSelect, lcCode, llReturn, lScriptHandled, lcSaveUdfParms
TRY
* First try FoxCode lookup for Type="M" records
lnSelect = SELECT()
SELECT 0
USE (_FOXCODE) AGAIN SHARE ORDER 1
IF SEEK('M' + PADR(UPPER(toParameter.MenuItem), LEN(ABBREV)))
lcCode = DATA
ENDIF
USE
SELECT (lnSelect)
IF NOT EMPTY(lcCode)
llReturn = EXECSCRIPT(lcCode, toParameter)
lScriptHandled=.T.
ENDIF

* Handle by passing to external routine as specified in Tip field
IF !lScriptHandled
lcProgram = ALLTRIM(toParameter.Tip)
IF FILE(lcProgram)
lcSaveUdfParms=SET("Udfparms")
SET UDFPARMS TO REFERENCE
DO (lcProgram) WITH toParameter,llReturn
SET UDFPARMS TO &lcSaveUdfParms
ENDIF
ENDIF

* Custom script successful so let's disable native behavior
IF llReturn
toParameter.ValueType = 'V'
ENDIF
CATCH
ENDTRY

RETURN llReturn

MenuContext Script

The MenuContext script can be used to override an existing Visual FoxPro shortcut menu with a custom shortcut menu, and is called just before a Visual FoxPro shortcut menu is displayed. A shortcut menu is displayed by right-clicking a window or object.

The following table lists the fields and field values in the Foxcode.dbf record.

Field Name | Value | Description
Type | S | Indicates that the item is a script.
Abbrev | MENUCONTEXT | Indicates this is the MenuContext script record.
Data |  | Script (Visual FoxPro code) to run for the custom shortcut menu.

The MenuContext script is passed a single parameter which is an object containing properties that can be referenced by the script including following:

Parameter | Description
Items | An array of items in the shortcut menu.
UserTyped | Indicates additional information, if available, related to context of the shortcut menu.
MenuItem | An internal Visual FoxPro menu ID for the shortcut menu.

To suppress the Visual FoxPro shortcut menu from appearing, set the parameter object's ValueType property to V or L. You can use the DEFINE MENU Command with the SHORTCUT option to create a custom shortcut menu.

Note Since _Foxcode supports a single MenuContext script record and it is possible that you may want to handle multiple shortcut menus with your own custom scripts, it is recommended that you create a default MenuContext handler record that can call other records. The Foxcode menu scripts Solution Sample contains a recommended generic MenuContext script that you can use. See the MenuHit section above for this code.

See Also

Reference

_MemberData Property
IntelliSense Table Structure


Naming Conventions

Visual FoxPro 9.0
Naming Conventions

When naming exposed objects, properties, and methods, choose names that users can understand easily. Visual FoxPro does not require the following naming conventions but recommends them as part of good programming habits and to help remind you of the type of data you are working with. Using the recommended naming conventions does not dictate the type or contents of the data you are working with.

In This Section

Constant Naming Conventions

Provides a suggested format for naming constants.
Object Naming Conventions

Provides a suggested format for naming objects.
Table Field Naming Conventions

Provides a suggested format for naming fields in tables. These conventions are recommended, not required.
Variable Naming Conventions

Provides a suggested format for naming variables.
Window Naming Conventions

Provides a suggested format for naming windows.

Related Sections

Language Categories

Contains a list of language functionality and descriptions.
Language Reference A-Z

Contains a list of language reference topics in alphabetical order.
Using Visual FoxPro

Discusses Visual FoxPro programming features that are designed to improve developer productivity, including Access and Assign methods, support for more graphic file formats, and language to simplify programming tasks.
Developing Visual FoxPro Applications

Provides conceptual information about how to develop Visual FoxPro applications, including instructions for creating databases and the user interface, and other programming tasks.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Constant Naming Conventions

Visual FoxPro 9.0
Constant Naming Conventions
See Also Example

When naming constants, use the following format.

NAME

Parameters

NAME

Specifies the name of the constant in uppercase characters.

Example

The following example illustrates using the #DEFINE preprocessor directive with the name of the constant MAX_VALUE in uppercase characters:
Copy Code
#DEFINE MAX_VALUE 10

See Also

Other Resources

Creating Visual FoxPro Names
Object Naming Conventions
Table Field Naming Conventions
Variable Naming Conventions
Window Naming Conventions
Naming Conventions


Object Naming Conventions

Visual FoxPro 9.0
Object Naming Conventions
See Also Example

When naming objects, use the following recommended format.

PrefixObjectName

Parameters

Prefix

Specifies characters that indicate the associated object. The following table lists suggested values for Prefix.

Prefix Object Example

chk

CheckBox

chkReadOnly

col

Collection

colFormObjects

cbo

ComboBox

cboEnglish

cmd

CommandButton

cmdCancel

cmg

CommandGroup

cmgChoices

cnt

Container

cntMoverList

ctl

Control

ctlFileList

cur

Cursor

curRecordsReturned

cad

CursorAdapter

cadInventory

<user-defined>

Custom

user-defined

dte

DataEnvironment

dteSalesForm

edt

EditBox

edtTextArea

frm

Form

frmFileOpen

frs

FormSet

frsDataEntry

grd

Grid

grdPrices

grc

Column

grcCurrentPrice

grh

Header

grhTotalInventory

hpl

HyperLink

hplHomeURL

img

Image

imgIcon

lbl

Label

lblHelpMessage

lin

Line

linVertical

lst

ListBox

lstPolicyCodes

olb

OLEBoundControl

olbObject1

ole

OLE

oleObject1

opt

OptionButton

optFrench

opg

OptionGroup

opgType

pag

Page

pagDataUpdate

pgf

PageFrame

pgfLeft

prj

ProjectHook

prjBuildAll

rel

Relation

relCustomerRelation

rpt

ReportListener

rptListener1

sep

Separator

sepToolSection1

shp

Shape

shpCircle

spn

Spinner

spnValues

txt

TextBox

txtGetText

tmr

Timer

tmrAlarm

tbr

ToolBar

tbrEditReport

xad

XMLAdapter

xadRemoteXMLData

xfd

XMLField

xfdPrices

xtb

XMLTable

xtbInventory

ObjectName

Specifies the name of the object.

Example

The following example illustrates how the letters "cmd" indicate that the cmdCancel object is a CommandButton control:
Copy Code
cmdCancel

See Also

Other Resources

Creating Visual FoxPro Names
Constant Naming Conventions
Table Field Naming Conventions
Variable Naming Conventions
Window Naming Conventions
Naming Conventions


Table Field Naming Conventions

Visual FoxPro 9.0
Table Field Naming Conventions
See Also Example

When naming fields in tables, use the following format.

TableAlias.PrefixFieldName

Parameters

TableAlias

Specifies the name or alias for a table.
Prefix

Indicates the data type for a table field. The following table lists the suggested prefixes for Prefix.

Prefix Description

c

Character

y

Currency

d

Date

t

DateTime

b

Double

f

Float

g

General

i

Integer

l

Logical

m

Memo

n

Numeric

q

Varbinary

v

Varchar, Varchar (Binary)

w

Blob

FieldName

Specifies the name of the field.

Example

The following example illustrates how the letter "c" indicates that the LastName field of the Customer table has Character type:
Copy Code
Customer.cLastName

See Also

Other Resources

Creating Visual FoxPro Names
Constant Naming Conventions
Object Naming Conventions
Variable Naming Conventions
Window Naming Conventions
Naming Conventions


Variable Naming Conventions

Visual FoxPro 9.0
Variable Naming Conventions
See Also Example

When naming variables, use the following recommended format.

[Scope]TypeVariableName

Parameters

[ Scope]

Specifies a character that indicates the range of reference for the variable. The following table lists suggested values for Scope.

Scope Description

l

Local

t

Parameter

g

Public (Global)

p

Private (Default)
Note:
In some cases, explicit scoping does not apply. For example, in the main program of a standalone application, there is no difference in visibility for variables scoped as PUBLIC or PRIVATE. In sample programs, the type prefix is always relevant and required.

Type

Specifies a character that indicates the data type of the variable. The following table lists suggested values for Type.

Type Description

a

Array

c

Character, Varchar, Varchar (Binary)

y

Currency

d

Date

t

DateTime

b

Double

f

Float

l

Logical

n

Numeric

o

Object

q

Varbinary, Blob

u

Unknown

VariableName

Specifies the name of the variable.

Example

The following example illustrates how the letter "n" indicates that the Counter variable has Numeric type and local scope:
Copy Code
nCounter
lnCounter

See Also

Other Resources

Creating Visual FoxPro Names
Constant Naming Conventions
Object Naming Conventions
Table Field Naming Conventions
Window Naming Conventions
Naming Conventions


Window Naming Conventions

Visual FoxPro 9.0
Window Naming Conventions
See Also Example

When naming windows, use the following format.

wWindowName

Remarks

Note:
Do not use a prefix with class definitions; use prefixes only when the object is instantiated.

Example

The following example illustrates naming a window object when using the DEFINE WINDOW command:
Copy Code
DEFINE WINDOW wCustomerInvoices ;
   FROM nFirstRow, nFirstColumn TO nLastRow, nLastColumn

See Also

Other Resources

DEFINE WINDOW Command
Creating Visual FoxPro Names
Constant Naming Conventions
Object Naming Conventions
Table Field Naming Conventions
Variable Naming Conventions
Naming Conventions


Regular Expressions and Operators

Visual FoxPro 9.0
Regular Expressions and Operators
See Also

Regular expressions are sets of symbols that you can use to create searches for finding and replacing patterns of text. Regular expressions provide a concise and flexible way to specify more complex search and filter criteria against a selection of text than the wildcard character pattern searching available in the Find dialog box.

The following table describes the behavior of regular expression operators in a query.

Operator Behavior

.

Matches any single character except the newline (\n) character.

*

Matches the preceding character zero or more times. You can also use a question mark (?).

Example "zo*" matches either "z" or "zoo". The expression "a?ve?" matches the "ve" in "never".

+

Matches the preceding character one or more times.

Example "zo+" matches "zoo" but not "z".

^

Matches the beginning of the input string.

$

Matches the end of the input string.

[xyz]

Matches any one character in the set. Both opening and closing brackets are required.

Example "[abc]" matches the "a" in "plain".

[^xyz]

Matches any one character not in the set. Both opening and closing brackets are required.

Example "[^abc]" matches the "p" in "plain".

[a-z]

Matches any character in the specified range.

Example "[a-z]" matches any lowercase alphabetic character in the range of "a" through "z".

[^a-z]

Matches any character not in the specified range.

Example "[^m-z]" matches any character not in the range of "m" through "z".

\

Marks the next character as either a special character such as an escape character or a literal.

Example "\\" matches "\", and "\(" matches "(".

(pattern)

Matches a pattern group. Both the opening and closing parentheses are required.

Example "(tress)" matches "mattress" but not "mattres". To match parenthesis characters, use "\(" or "\)".

x|y

Matches either x or y.

Example "z|wood" matches "z" or "wood". The expression "(z|w)ood" matches "zood" or "wood".

{m}

Matches the preceding character exactly m number of times, where m is nonnegative. Both opening and closing braces are required.

Example "o{2}" does not match the "o" in "Bob" but matches the first two letter o's in "food" or "foooood".

{m,}

Matches the preceding character at least m number of times, where m is nonnegative.

Example "o{2,}" does not match the "o" in "Bob" but matches all the o's in "fooooood". In addition, the expression "o{1,}" is equivalent to "o+", and "o{0,}" is equivalent to "o*".

{m,n}

Matches the preceding character at least m and at most n number of times, where both m and n are nonnegative.

Example "o{1,3}" matches the first three o's in "foooooood". In addition, the expression "o{0,1}" is equivalent to "o?".

All else

Matches itself.

The following rules apply when you use regular expression operators:

  • You can enclose regular expressions in matching quotation marks (" "). You must enclose regular expressions in quotation marks if the expression contains a space or a closing parenthesis ()).

The Regular Expressions Foundation Class provides access to routines for using regular expressions in your applications. For more information, see Regular Expressions Foundation Class.

Visual FoxPro provides a regular expressions sample that you can use to determine how to incorporate regular expression text searching in your application. For more information, see Search Text Using Regular Expressions.

You can refer to MSDN for general details about regular expressions and pattern property matching.

See Also

Other Resources

General Reference
Look Up Reference Dialog Box
Find Dialog Box


Reserved Words (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Reserved Words (Visual FoxPro)
See Also

Reserved words in Microsoft Visual FoxPro include functions, system variables, properties, events, methods, commands, menu constants, and clauses. When programming, avoid using reserved words as names for window, table, or field names. If you use a reserved word as a name, it might generate a syntax error.

The following are all Visual FoxPro reserved words.

Operators and Miscellaneous Items

-

!

!=

#

$

%

(

)

*

**

,

.

.AND.

.F.

.N.

.NOT.

.NULL.

.OR.

.T.

.Y.

/

/R

:

::

;

?

??

???

@

[

]

^

+

<

<??>

<=

<>

=

=

==

=>

>

->

>=

#

#DEFINE

#ELIF

#ELSE

#ENDIF

#IF

#ITSEXPRESSION

#READCLAUSES

#REGION

#SECTION

#UNDEF

#WNAME

_

_ALIGNMENT

_ASCIICOLS

_ASCIIROWS

_ASSIST

_BEAUTIFY

_BOX

_BROWSER

_BUILDER

_CALCMEM

_CALCVALUE

_CLIPTEXT

_CODESENSE

_CONVERTER

_COVERAGE

_CUROBJ

_DATETIMEFORMAT

_DBLCLICK

_DIARYDATE

_DOS

_FONTCLASS

_FOXBASECLASS

_FOXCODE

_FOXDOC

_FOXDRAGDROP

_FOXDROPTARGET

_FOXREF

_FOXGRAPH

_FOXTASK

_GALLERY

_GENGRAPH

_GENHTML

_GENMENU

_GENPD

_GENSCRN

_GENXTAB

_GETEXPR

_HELPWEBDEVONLY

_HELPWEBDIRECTORY

_HELPWEBFILLER1

_HELPWEBFILLER2

_HELPWEBMSDNONLINE

_HELPWEBMSFTHOMEPAGE

_HELPWEBSEARCH

_HELPWEBTUTORIAL

_HELPWEBVFPFAQ

_HELPWEBVFPFREESTUFF

_HELPWEBVFPHOMEPAGE

_HELPWEBVFPONLINESUPPORT

_HELPWEBVFPSENDFEEDBACK

_HELPWEBVSPRODNEWS

_INCLUDE

_INCSEEK

_INDENT

_LMARGIN

_MAC

_MBR_APPND

_MBR_CPART

_MBR_DELET

_MBR_FONT

_MBR_GOTO

_MBR_GRID

_MBR_LINK

_MBR_MODE

_MBR_MVFLD

_MBR_MVPRT

_MBR_SEEK

_MBR_SP100

_MBR_SP200

_MBR_SZFLD

_MBROWSE

_MDA_APPND

_MDA_AVG

_MDA_BROW

_MDA_CALC

_MDA_COPY

_MDA_COUNT

_MDA_LABEL

_MDA_PACK

_MDA_REPRT

_MDA_RINDX

_MDA_SETUP

_MDA_SORT

_MDA_SP100

_MDA_SP200

_MDA_SP300

_MDA_SUM

_MDA_TOTAL

_MDATA

_MDIARY

_MED_BEAUT

_MED_BLDEX

_MED_CLEAR

_MED_COPY

_MED_CUT

_MED_CVTST

_MED_EXBLK

_MED_FIND

_MED_FINDA

_MED_GOTO

_MED_INSOB

_MED_LINK

_MED_OBJ

_MED_PASTE

_MED_PREF

_MED_PSTLK

_MED_REDO

_MED_REPL

_MED_REPLA

_MED_SLCTA

_MED_SP100

_MED_SP200

_MED_SP300

_MED_SP400

_MED_SP500

_MED_SP600

_MED_UNDO

_MEDIT

_MEMBERDATA

_MENUDESIGNER

_MFI_CLALL

_MFI_CLOSE

_MFI_EXPORT

_MFI_IMPORT

_MFI_NEW

_MFI_OPEN

_MFI_PGSET

_MFI_PREVU

_MFI_PRINT

_MFI_PRINTONECOPY

_MFI_QUIT

_MFI_REVRT

_MFI_SAVAS

_MFI_SAVE

_MFI_SAVEASHTML

_MFI_SEND

_MFI_SETUP

_MFI_SP100

_MFI_SP200

_MFI_SP300

_MFI_SP400

_MFI_SYSPRINT

_MFILE

_MFILER

_MFIRST

_MLABEL

_MLAST

_MLINE

_MMACRO

_MMB_DELET

_MMB_GENER

_MMB_GOPTS

_MMB_INSBR

_MMB_INSRT

_MMB_MOPTS

_MMB_PREVU

_MMB_QUICK

_MMB_SP100

_MMB_SP200

_MMB_SP300

_MMBLDR

_MOUSEEVENTS

_MOUSEEVENTSNODBL

_MPR_BEAUT

_MPR_CANCL

_MPR_COMPL

_MPR_DO

_MPR_DOCUM

_MPR_FORMWZ

_MPR_GENER

_MPR_GRAPH

_MPR_RESUM

_MPR_SP100

_MPR_SP200

_MPR_SP300

_MPR_SUSPEND

_MPROG

_MPROJ

_MRC_APPND

_MRC_CHNGE

_MRC_CONT

_MRC_DELET

_MRC_GOTO

_MRC_LOCAT

_MRC_RECAL

_MRC_REPL

_MRC_SEEK

_MRC_SP100

_MRC_SP200

_MRECORD

_MREPORT

_MRQBE

_MSCREEN

_MSM_DATA

_MSM_EDIT

_MSM_FILE

_MSM_FORMAT

_MSM_PROG

_MSM_RECRD

_MSM_SYSTM

_MSM_TEXT

_MSM_TOOLS

_MSM_VIEW

_MSM_WINDO

_MST_ABOUT

_MST_ASCII

_MST_CALCU

_MST_CAPTR

_MST_DBASE

_MST_DIARY

_MST_DOCUM

_MST_FILER

_MST_HELP

_MST_HPHOW

_MST_HPSCH

_MST_MACRO

_MST_MSDNC

_MST_MSDNI

_MST_MSDNS

_MST_OFFICE

_MST_PUZZL

_MST_SAMP

_MST_SP100

_MST_SP200

_MST_SP300

_MST_SPECL

_MST_TECHS

_MSYSMENU

_MSYSTEM

_MTABLE

_MTB_APPND

_MTB_CPART

_MTB_DELET

_MTB_DELRC

_MTB_GOTO

_MTB_LINK

_MTB_MVFLD

_MTB_MVPRT

_MTB_PROPS

_MTB_RECAL

_MTB_SP100

_MTB_SP200

_MTB_SP300

_MTB_SP400

_MTB_SZFLD

_MTI_CALLSTACK

_MTI_DBGOUT

_MTI_LOCALS

_MTI_RUNACTIVEDOC

_MTI_TRACE

_MTI_WATCH

_MTL_BROWSER

_MTL_COVERAGE

_MTL_DEBUGGER

_MTL_GALLERY

_MTL_MACRO

_MTL_OPTNS

_MTL_SP100

_MTL_SP200

_MTL_SP300

_MTL_SP400

_MTL_SPELL

_MTL_WZRDS

_MTOOLS

_MVI_TOOLB

_MVIEW

_MWI_ARRAN

_MWI_CLEAR

_MWI_CMD

_MWI_COLOR

_MWI_DEBUG

_MWI_HIDE

_MWI_HIDEA

_MWI_MIN

_MWI_MOVE

_MWI_ROTAT

_MWI_SHOWA

_MWI_SIZE

_MWI_SP100

_MWI_SP200

_MWI_TOOLB

_MWI_TRACE

_MWI_VIEW

_MWI_ZOOM

_MWINDOW

_MWIZARDS

_MWZ_ALL

_MWZ_APPLIC

_MWZ_APPLICATION

_MWZ_DATABASE

_MWZ_FORM

_MWZ_FOXDOC

_MWZ_IMPORT

_MWZ_LABEL

_MWZ_MAIL

_MWZ_PIVOT

_MWZ_QUERY

_MWZ_REPRT

_MWZ_SETUP

_MWZ_TABLE

_MWZ_UPSIZING

_MWZ_WEBPUBLISHING

_NETWARE

_OBJECTBROWSER

_OLEBASECONTROL

_OLEDRAGDROP

_ORACLE

_PADVANCE

_PAGENO

_PAGETOTAL

_PBPAGE

_PCOLNO

_PCOPIES

_PDPARMS

_PDRIVER

_PDSETUP

_PECODE

_PEJECT

_PEPAGE

_PFORM

_PLENGTH

_PLINENO

_PLOFFSET

_PPITCH

_PQUALITY

_PRETEXT

_PSCODE

_PSPACING

_PWAIT

_RECTCLASS

_RMARGIN

_REPORTBUILDER

_REPORTPREVIEW

_REPORTOUTPUT

_RUNACTIVEDOC

_SAMPLES

_SCCTEXT

_SCREEN

_SHELL

_SPELLCHK

_SQLSERVER

_STARTUP

_TABS

_TALLY

_TASKLIST

_TEXT

_THROTTLE

_TOOLTIPTIMEOUT

_TRANSPORT

_TRIGGERLEVEL

_UNIX

_VFP

_VIEWPORT

_VSBUILD

_WEBDEVONLY

_WEBMENU

_WEBMSFTHOMEPAGE

_WEBVFPHOMEPAGE

_WEBVFPONLINESUPPORT

_WINDOWS

_WIZARD

_WRAP

A

A

ABS

ACCELERATE

ACCEPT

ACCESS

ACLASS

ACOPY

ACOS

ACTIVATE

ACTIVATECELL

ACTIVECOLUMN

ACTIVECONTROL

ACTIVEDOC

ACTIVEFORM

ACTIVEOBJECTID

ACTIVEPAGE

ACTIVEROW

ADATABASES

ADBOBJECTS

ADD

ADDBS

ADDCOLUMN

ADDITEM

ADDITIVE

ADDLISTITEM

ADDOBJECT

ADDPROPERTY

ADDRELATIONTOENV

ADDTABLETOENV

ADDTABLESCHEMA

ADOCKSTATE

ADOCODEPAGE

ADEL

ADIR

ADLLS

ADMIN

ADOCKSTATE

ADJUSTOBJECTSIZE

AELEMENT

AERROR

AEVENTS

AFIELDS

AFONT

AFTER

AFTERBAND

AFTERBUILD

AFTERCLOSETABLES

AFTERCURSORATTACH

AFTERCURSORCLOSE

AFTERCURSORDETACH

AFTERCURSORFILL

AFTERCURSORREFRESH

AFTERCURSORUPDATE

AFTERDELETE

AFTERDOCK

AFTERINSERT

AFTERRECORDREFRESH

AFTERREPORT

AFTERROWCOLCHANGE

AFTERUPDATE

AGAIN

AGETCLASS

AGETFILEVERSION

AINDENT

AINS

AINSTANCE

ALANGUAGE

ALEN

ALIAS

ALIGN

ALIGNMENT

ALIGNRIGHT

ALINES

ALL

ALLOWADDNEW

ALLOWAUTOCOLUMNFIT

ALLOWCELLSELECTION

ALLOWDELETE

ALLOWEXTERNAL

ALLOWHEADERSIZING

ALLOWINSERT

ALLOWMODALMESSAGES

ALLOWOUTPUT

ALLOWRESIZE

ALLOWROWSIZING

ALLOWTABS

ALLOWTABS+

ALLOWUPDATE

ALLTRIM

ALT

ALTER

ALTERNATE

ALWAYSONBOTTOM

ALWAYSONTOP

AMEMBERS

AMOUSEOBJ

ANCHOR

AND

ANETRESOURCES

ANSI

ANSITOOEM

ANY

APLABOUT

APP

APPEND

APPLICATION

APPLYDIFFGRAM

APRINTERS

APROCINFO

ARRAY

AS

ASC

ASCAN

ASCENDING

ASCII

ASELOBJ

ASESSIONS

ASIN

ASORT

ASQLHANDLES

ASSERT

ASSERTS

ASSIST

ASTACKINFO

ASUBSCRIPT

ASYNCHRONOUS

AT

AT_C

ATAGINFO

ATAN

ATC

ATCC

ATCLINE

ATGETCOLORS

ATLINE

ATLISTCOLORS

ATN2

ATTACH

ATTRIBUTES

AUSED

AUTOACTIVATE

AUTOCENTER

AUTOCLOSETABLES

AUTOCOMPLETE

AUTOCOMPSOURCE

AUTOCOMPTABLE

AUTOFIT

AUTOFORM

AUTOHIDESCROLLBAR

AUTOINC

AUTOINCERROR

AUTOMATIC

AUTOOPEN

AUTOOPENTABLES

AUTORELEASE

AUTOREPORT

AUTOSAVE

AUTOSIZE

AUTOVERBMENU

AUTOYIELD

AVAILNUM

AVCXCLASSES

AVERAGE

AVG

B

B

BACKCOLOR

BACKSTYLE

BACKSTYLE

BAR

BARCOUNT

BARPROMPT

BASECLASS

BATCHMODE

BATCHUPDATECOUNT

BEFORE

BEFOREBAND

BEFOREBUILD

BEFORECURSORATTACH

BEFORECURSORCLOSE

BEFORECURSORDETACH

BEFORECURSORFILL

BEFORECURSORREFRESH

BEFORECURSORUPDATE

BEFOREDELETE

BEFOREDOCK

BEFOREINSERT

BEFOREOPENTABLES

BEFORERECORDREFRESH

BEFOREREPORT

BEFOREROWCOLCHANGE

BEFOREUPDATE

BEGIN

BELL

BELLSOUND

BETWEEN

BINDCONTROLS

BINDEVENT

BINTOC

BITAND

BITCLEAR

BITLSHIFT

BITMAP

BITNOT

BITOR

BITRSHIFT

BITSET

BITTEST

BITXOR

BLANK

BLINK

BLOB

BLOCKSIZE

BOF

BORDER

BORDERCOLOR

BORDERSTYLE

BORDERWIDTH

BOTTOM

BOUND

BOUNDCOLUMN

BOUNDTO

BOX

BROWSE

BROWSEALIGNMENT

BROWSECELLMARG

BROWSEDESTWIDTH

BROWSEIMECONTROL

BROWSEREFRESH

BRSTATUS

BUCKET

BUFFERING

BUFFERMODE

BUFFERMODEOVERRIDE

BUFFERS

BUILD

BUILDERLOCK

BUTTONCOUNT

BUTTONINDEX

BUTTONS

BUTTONSBOF

BY

C

C

CALCULATE

CALL

CANACCELERATE

CANCEL

CANCELREPORT

CANDIDATE

CANGETFOCUS

CANLOSEFOCUS

CAPSLOCK

CAPTION

CARRY

CASCADE

CASE

CAST

CATALOG

CATCH

CD

CDOW

CDX

CEILING

CENTER

CENTERED

CENTRAL

CENTURY

CGA

CHANGE

CHANGESTOCURSOR

CHAR

CHARACTER

CHDIR

CHECK

CHECKBOX

CHILDALIAS

CHILDORDER

CHILDORDER

CHILDTABLE

CHR

CHRSAW

CHRTRAN

CHRTRANC

CIRCLE

CLASS

CLASS

CLASSLIB

CLASSLIBRARY

CLEAR

CLEARDATA

CLEARRESULTSET

CLEARSTATUS

CLICK

CLIPCONTROLS

CLIPRECT

CLOCK

CLONEOBJECT

CLOSABLE

CLOSE

CLOSEEDITOR

CLOSETABLES

CLS

CMONTH

CNT

CNTBAR

CNTPAD

CODEPAGE

COL

COLLATE

COLLECTION

COLOR

COLORSCHEME

COLORSOURCE

COLUMN

COLUMNCOUNT

COLUMNHEADERS

COLUMNLINES

COLUMNORDER

COLUMNS

COLUMNWIDTHS

COM1

COM2

COMARRAY

COMBOBOX

COMCLASSINFO

COMMAND

COMMANDBUTTON

COMMANDCLAUSES

COMMANDGROUP

COMMANDTARGETEXEC

COMMANDTARGETQUERY

COMMENT

COMPACT

COMPAREMEMO

COMPATIBLE

COMPILE

COMPLETED

COMPOBJ

COMPRESS

COMPUTE

COMRETURNERROR

CONCAT

CONFIRM

CONFLICTCHECKCMD

CONFLICTCHECKTYPE

CONNECTBUSY

CONNECTHANDLE

CONNECTION

CONNECTIONS

CONNECTNAME

CONNECTSTRING

CONNECTTIMEOUT

CONNSTRING

CONSOLE

CONTAINER

CONTAINERRELEASE

CONTAINERRELEASETYPE

CONTINUE

CONTINUOUSSCROLL

CONTROL

CONTROLBOX

CONTROLCOUNT

CONTROLINDEX

CONTROLS

CONTROLSOURCE

CONVERSIONFUNC

COPIES

COPY

COS

COT

COUNT

COVERAGE

CPCOMPILE

CPCONVERT

CPCURRENT

CPDBF

CPDIALOG

CPNOTRANS

CREATE

CREATEBINARY

CREATEOBJECT

CREATEOBJECTEX

CREATEOFFLINE

CRSBUFFERING

CRSFETCHMEMO

CRSFETCHSIZE

CRSMAXROWS

CRSMETHODUSED

CRSNUMBATCH

CRSSHARECONNECTION

CRSUSEMEMOSIZE

CRSWHERECLAUSE

CSV

CTOBIN

CTOBIN

CTOD

CTOT

CURDATE

CURDIR

CURRENCY

CURRENTCONTROL

CURRENTDATASESSION

CURRENTPASS

CURRENTX

CURRENTY

CURRENTY

CURRLEFT

CURRSYMBOL

CURSOR

CURSORADAPTER

CURSORATTACH

CURSORDETACH

CURSORFILL

CURSORGETPROP

CURSORREFRESH

CURSORSCHEMA

CURSORSETPROP

CURSORSOURCE

CURSORSTATUS

CURSORTORS

CURSORTOXML

CURTIME

CURVAL

CURVATURE

CUSTOM

CYCLE

D

D

DATABASE

DATABASES

DATAENVIRONMENT

DATAOBJECT

DATASESSION

DATASESSIONID

DATASOURCE

DATASOURCEOBJ

DATASOURCETYPE

DATATOCLIP

DATATYPE

DATE

DATEFORMAT

DATEMARK

DATETIME

DAY

DAYNAME

DAYOFMONTH

DAYOFWEEK

DAYOFYEAR

DB_BUFLOCKROW

DB_BUFLOCKTABLE

DB_BUFOFF

DB_BUFOPTROW

DB_BUFOPTTABLE

DB_COMPLETTE

DB_DELETEINSERT

DB_KEYANDMODIFIED

DB_KEYANDTIMESTAMP

DB_KEYANDUPDATABLE

DB_LOCALSQL

DB_NOPROMPT

DB_PROMPT

DB_REMOTESQL

DB_TRANSAUTO

DB_TRANSMANUAL

DB_TRANSNONE

DB_UPDATE

DB4

DB4

DBALIAS

DBC

DBC_Activate

DBC_AfterAddRelation

DBC_AfterAddTable

DBC_AfterAppendProc

DBC_AfterCloseTable

DBC_AfterCopyProc

DBC_AfterCreateConnection

DBC_AfterCreateOffline

DBC_AfterCreateTable

DBC_AfterCreateView

DBC_AfterDBGetProp

DBC_AfterDBSetProp

DBC_AfterDeleteConnection

DBC_AfterDropOffline

DBC_AfterDropRelation

DBC_AfterDropTable

DBC_AfterDropView

DBC_AfterModifyConnection

DBC_AfterModifyProc

DBC_AfterModifyTable

DBC_AfterModifyView

DBC_AfterOpenTable

DBC_AfterRemoveTable

DBC_AfterRenameConnection

DBC_AfterRenameTable

DBC_AfterRenameView

DBC_AfterValidateData

DBC_BeforeAddRelation

DBC_BeforeAddTable

DBC_BeforeAppendProc

DBC_BeforeCloseTable

DBC_BeforeCopyProc

DBC_BeforeCreateConnection

DBC_BeforeCreateOffline

DBC_BeforeCreateTable

DBC_BeforeCreateView

DBC_BeforeDBGetProp

DBC_BeforeDBSetProp

DBC_BeforeDeleteConnection

DBC_BeforeDropOffline

DBC_BeforeDropRelation

DBC_BeforeDropTable

DBC_BeforeDropView

DBC_BeforeModifyConnection

DBC_BeforeModifyProc

DBC_BeforeModifyTable

DBC_BeforeModifyView

DBC_BeforeOpenTable

DBC_BeforeRemoveTable

DBC_BeforeRenameConnection

DBC_BeforeRenameTable

DBC_BeforeRenameView

DBC_BeforeValidateData

DBC_CloseData

DBC_Deactivate

DBC_ModifyData

DBC_OpenData

DBC_PackData

DBF

DBFDBLCLICK

DBGETPROP

DBLCLICK

DBMEMO3

DBSETPROP

DBTRAP

DBUSED

DDEABORTTRANS

DDEADVISE

DDEENABLED

DDEEXECUTE

DDEINITIATE

DDELASTERROR

DDEPOKE

DDEREQUEST

DDESETOPTION

DDESETSERVICE

DDESETTOPIC

DDETERMINATE

DEACTIVATE

DEACTIVATE

DEBUG

DEBUGGER

DEBUGOUT

DECIMALS

DECLARE

DECLAREXMLPREFIX

DECLASS

DECLASSLIBRARY

DEFAULT

DEFAULTEXT

DEFAULTFILEPATH

DEFAULTSOURCE

DEFAULTVALUE

DEFBUTTON

DEFBUTTONORIG

DEFHEIGHT

DEFINE

DEFINEWINDOWS

DEFLEFT

DEFOLELCID

DEFTOP

DEFWIDTH

DEGREES

DELAYBIND

DELAYEDMEMOFETCH

DELETE

DELETECMD

DELETECMDDATASOURCE

DELETECMDDATASOURCETYPE

DELETECOLUMN

DELETED

DELETEMARK

DELETETABLES

DELETETRIGGER

DELIMITED

DELIMITERS

DESC

DESCENDING

DESCRIPTION

DESIGN

DESKTOP

DESTROY

DETAILS

DEVELOPMENT

DEVICE

DIF

DIFFERENCE

DIMENSION

DIR

DIRECTORY

DISABLED

DISABLEDBACKCOLOR

DISABLEDBYEOF

DISABLEDFORECOLOR

DISABLEDITEMBACKCOLOR

DISABLEDITEMFORECOLOR

DISABLEDPICTURE

DISABLEENCODE

DISCONNECTED

DISKSPACE

DISPLAY

DISPLAYCOUNT

DISPLAYORIENTATION

DISPLAYPATH

DISPLAYVALUE

DISPLAYVALUEDIRTY

DISPLOGIN

DISPPAGEHEIGHT

DISPPAGEWIDTH

DISPWARNINGS

DISTINCT

DLL

DLLS

DMY

DO

DOC

DOCK

DOCKABLE

DOCKED

DOCKPOSITION

DOCMD

DOCREATE

DOCUMENTFILE

DODEFAULT

DOEVENTS

DOHISTORY

DOMESSAGE

DOS

DOSCROLL

DOSMEM

DOSTATUS

DOUBLE

DOVERB

DOW

DOWN

DOWNCLICK

DOWNPICTURE

DRAG

DRAGDROP

DRAGICON

DRAGMODE

DRAGOVER

DRAGSTATE

DRAW

DRAW

DRAWMODE

DRAWSTYLE

DRAWWIDTH

DRIVER

DRIVETYPE

DROP

DROPDOWN

DROPOFFLINE

DTOC

DTOR

DTOS

DTOT

DUPLEX

DYNAMICALIGNMENT

DYNAMICBACKCOLOR

DYNAMICCURRENTCONTROL

DYNAMICFONTBOLD

DYNAMICFONTITALIC

DYNAMICFONTNAME

DYNAMICFONTOUTLINE

DYNAMICFONTSHADOW

DYNAMICFONTSIZE

DYNAMICFONTSTRIKETHRU

DYNAMICFONTUNDERLINE

DYNAMICFORECOLOR

DYNAMICINPUTMASK

DYNAMICLINEHEIGHT

E

E

EACH

ECHO

EDIT

EDITBOX

EDITFLAGS

EDITOROPTIONS

EDITSOURCE

EDITWORK

EGA25

EGA43

EJECT

ELIF

ELSE

EMPTY

EMS

EMS64

ENABLED

ENABLEDBYREADLOCK

ENABLEHYPERLINKS

ENCRYPT

ENCRYPTION

END

ENDCASE

ENDDEFINE

ENDDO

ENDFOR

ENDFUNC

ENDIF

ENDPRINTJOB

ENDPROC

ENDSCAN

ENDTEXT

ENDTRY

ENDWITH

ENGINEBEHAVIOR

ENTERFOCUS

ENVIRONMENT

ENVLEVEL

EOF

ERASE

ERASEPAGE

ERROR

ERRORMESSAGE

ERRORNO

ESCAPE

EVALUATE

EVALUATECONTENTS

EVENTHANDLER

EVENTLIST

EVENTS

EVENTTRACKING

EVL

EXACT

EXCEPT

EXCEPTION

EXCLUSIVE

EXE

EXECSCRIPT

EXISTS

EXIT

EXITFOCUS

EXP

EXPORT

EXPRESSION

EXTENDED

EXTERNAL

F

F

F11F12

FCHSIZE

FCLOSE

FCOUNT

FCREATE

FDATE

FDOW

FEOF

FERROR

FETCH

FETCHMEMO

FETCHMEMOCMDLIST

FETCHMEMODATASOURCE

FETCHMEMODATASOURCETYPE

FETCHSIZE

FFLUSH

FGETS

FIELD

FIELDS

FIELDSF

FILE

FILER

FILES

FILETOSTR

FILL

FILLCOLOR

FILLSTYLE

FILTER

FINALLY

FIND

FIRSTELEMENT

FIRSTNESTEDTABLE

FIXED

FKLABEL

FKMAX

FLAGS

FLDCOUNT

FLDLIST

FLOAT

FLOCK

FLOOR

FLUSH

FOLDCONST

FONT

FONTBOLD

FONTCHARSET

FONTCLASS

FONTCONDENSE

FONTEXTEND

FONTITALIC

FONTMETRIC

FONTMETRIC

FONTNAME

FONTOUTLINE

FONTSHADOW

FONTSIZE

FONTSTRIKETHRU

FONTUNDERLINE

FOOTER

FOPEN

FOR

FORCE

FORCECLOSETAG

FORCEEXT

FORCEFOCUS

FORCEPATH

FORECOLOR

FOREIGN

FORM

FORMAT

FORMATCHANGE

FORMATTEDOUTPUT

FORMCOUNT

FORMINDEX

FORMPAGECOUNT

FORMPAGEINDEX

FORMS

FORMSCLASS

FORMSET

FORMSETCLASS

FORMSETLIB

FORMSLIB

FOUND

FOX2X

FOXCODE

FOXDOC

FOXFONT

FOXGEN

FOXGRAPH

FOXOBJECT

FOXPLUS

FOXPRO

FOXTASK

FOXVIEW

FPUTS

FRACTIONDIGITS

FREAD

FREE

FREEZE

FRENCH

FROM

FRXDATASESSION

FSEEK

FSIZE

FTIME

FULL

FULLNAME

FULLPATH

FUNCTION

FV

FW2

FWEEK

FWRITE

G

G

GATHER

GDIPLUSGRAPHICS

GENERAL

GERMAN

GET

GETAUTOINCVALUE

GETBAR

GETCOLOR

GETCP

GETCURSORADAPTER

GETDATA

GETDIR

GETDOCKSTATE

GETENV

GETEXPR

GETFILE

GETFLDSTATE

GETFONT

GETFORMAT

GETHOST

GETINTERFACE

GETKEY

GETNEXTMODIFIED

GETOBJECT

GETPAD

GETPAGEHEIGHT

GETPAGEWIDTH

GETPEM

GETPICT

GETPRINTER

GETRESULTSET

GETS

GETWORDCOUNT

GETWORDNUM

GLOBAL

GO

GOBACK

GOFIRST

GOFORWARD

GOLAST

GOMONTH

GOTFOCUS

GOTO

GRAPH

GRID

GRIDHITTEST

GRIDHORZ

GRIDLINECOLOR

GRIDLINES

GRIDLINEWIDTH

GRIDSHOW

GRIDSHOWPOS

GRIDSNAP

GRIDVERT

GROUP

GROW

H

H

HALFHEIGHT

HALFHEIGHTCAPTION

HASCLIP

HAVING

HEADER

HEADERCLASS

HEADERCLASSLIBRARY

HEADERGAP

HEADERHEIGHT

HEADING

HEADINGS

HEIGHT

HELP

HELPCONTEXTID

HELPFILTER

HELPON

HELPTO

HIDDEN

HIDE

HIDEAPPOBJ

HIDEDOC

HIDESELECTION

HIGHLIGHT

HIGHLIGHTBACKCOLOR

HIGHLIGHTFORECOLOR

HIGHLIGHTSTYLE

HIGHLIGHTROW

HISTORY

HMEMORY

HOME

HOSTNAME

HOTKEY

HOUR

HOURS

HPROJ

HSCROLLSMALLCHANGE

HWND

HYPERLINK

I

I

IBLOCK

ICASE

ICON

ID

IDHISTORY

IDLETIMEOUT

IDXCOLLATE

IF

IFDEF

IFNDEF

IGNOREINSERT

IIF

IMAGE

IMEMODE

IMESTATUS

IMPORT

IN

INCLUDE

INCLUDEPAGEINOUTPUT

INCREMENT

INCREMENTALSEARCH

INDBC

INDEX

INDEXES

INDEXSEEK

INDEXTOITEMID

INFORMATION

INIT

INITIALSELECTEDALIAS

INKEY

INLIST

INNER

INPUT

INPUTMASK

INRESIZE

INSERT

INSERTCMD

INSERTCMDDATASOURCE

INSERTCMDDATASOURCETYPE

INSERTCMDREFRESHCMD

INSERTCMDREFRESHFIELDLIST

INSERTCMDREFRESHKEYFIELDLIST

INSERTTRIGGER

INSMODE

INSTRUCT

INT

INTEGER

INTEGRALHEIGHT

INTENSITY

INTERACTIVECHANGE

INTERSECT

INTERVAL

INTO

IS

ISALPHA

ISATTRIBUTE

ISBASE64

ISBINARY

ISBLANK

ISCOLOR

ISDIFFGRAM

ISDIGIT

ISEXCLUSIVE

ISFLOCKED

ISHOSTED

ISLEADBYTE

ISLOADED

ISLOWER

ISMEMOFETCHED

ISMOUSE

ISNULL

ISOMETRIC

ISPEN

ISREADONLY

ISRLOCKED

ISTRANSACTABLE

ISUPPER

ITALIAN

ITEM

ITEMBACKCOLOR

ITEMDATA

ITEMFORECOLOR

ITEMIDDATA

ITEMIDTOINDEX

ITEMTIPS

IXMLDOMELEMENT

J

J

JAPAN

JOIN

JUSTDRIVE

JUSTEXT

JUSTFNAME

JUSTPATH

JUSTREADLOCKED

JUSTSTEM

K

KEY

KEYBOARD

KEYBOARDHIGHVALUE

KEYBOARDLOWVALUE

KEYCOLUMNS

KEYCOMP

KEYFIELD

KEYFIELDLIST

KEYMATCH

KEYPRESS

KEYPREVIEW

KEYSET

KEYSORT

L

LABEL

LANGUAGEOPTIONS

LAST

LASTKEY

LASTPROJECT

LCASE

LDCHECK

LEDIT

LEFT

LEFTC

LEFTCOLUMN

LEN

LENC

LENGTH

LEVEL

LIBRARY

LIKE

LIKEC

LINE

LINECONTENTS

LINENO

LINESLANT

LINKED

LINKMASTER

LIST

LISTBOX

LISTCOUNT

LISTENERTYPE

LISTINDEX

LISTITEM

LISTITEMID

LOAD

LOADPICTURE

LOADREPORT

LOADXML

LOCAL

LOCFILE

LOCK

LOCKCOLUMNS

LOCKCOLUMNSLEFT

LOCKDATASOURCE

LOCKSCREEN

LOG

LOG10

LOGERRORS

LOGOUT

LONG

LOOKUP

LOOP

LOSTFOCUS

LOWER

LPARAMETER

LPARAMETERS

LPARTITION

LTRIM

LTRJUSTIFY

LUPDATE

M

M

MAC

MACDESKTOP

MACHELP

MACKEY

MACROS

MACSCREEN

MAIL

MAKETRANSACTABLE

MAP19_4TOCURRENCY

MAPBINARY

MAPVARCHAR

MARGIN

MARK

MASTER

MAX

MAXBUTTON

MAXHEIGHT

MAXLEFT

MAXLENGTH

MAXMEM

MAXRECORDS

MAXTOP

MAXWIDTH

MBLOCK

MCOL

MD

MDI

MDIFORM

MDOWN

MDX

MDY

MEMBERCLASS

MEMBERCLASSLIBRARY

MEMLIMIT

MEMLINES

MEMO

MEMORY

MEMOS

MEMOWIDTH

MEMOWINDOW

MEMVAR

MENU

MENUS

MESSAGE

MESSAGEBOX

MESSAGES

METHOD

MIDDLE

MIDDLECLICK

MIN

MINBUTTON

MINHEIGHT

MINIMIZE

MINUS

MINUTE

MINWIDTH

MKDIR

MLINE

MOD

MODAL

MODIFY

MODULE

MONO

MONO43

MONO43

MONTH

MONTHNAME

MOUSE

MOUSEDOWN

MOUSEICON

MOUSEMOVE

MOUSEPOINTER

MOUSEUP

MOUSEWHEEL

MOVABLE

MOVE

MOVED

MOVEITEM

MOVERBARS

MOVERS

MRKBAR

MRKPAD

MROW

MTB_SP100

MTON

MULTILOCKS

MULTISELECT

MVARSIZ

MVCOUNT

MWINDOW

N

NAME

NAPTIME

NATIVE

NAVIGATETO

NDX

NEAR

NEGOTIATE

NEST

NESTEDINTO

NETWORK

NEWINDEX

NEWITEMID

NEWOBJECT

NEXT

NEXTSIBLINGTABLE

NEXTVALUE

NOALIAS

NOAPPEND

NOCLEAR

NOCLOSE

NOCONSOLE

NOCPTRANS

NODATA

NODATAONLOAD

NODEBUG

NODEFAULT

NODEFINE

NODELETE

NODIALOG

NODUP

NOEDIT

NOEJECT

NOENVIRONMENT

NOFILTER

NOFLOAT

NOFOLLOW

NOGROW

NOINIT

NOLGRID

NOLINK

NOLOCK

NOLOG

NOMARGIN

NOMDI

NOMENU

NOMINIMIZE

NOMODIFY

NOMOUSE

NONE

NOOPTIMIZE

NOORGANIZE

NOOVERWRITE

NOPROJECTHOOK

NOPROMPT

NOREAD

NOREFRESH

NOREQUERY

NORGRID

NORM

NORMAL

NORMALIZE

NOSAVE

NOSHADOW

NOSHOW

NOSPACE

NOT

NOTAB

NOTE

NOTIFY

NOTIFYCONTAINER

NOUPDATE

NOVALIDATE

NOVERIFY

NOW

NOWAIT

NOWINDOW

NOWRAP

NOZOOM

NPV

NTOM

NULL

NULLDISPLAY

NULLSTRING

NUMBER

NUMBEROFELEMENTS

NUMLOCK

NVL

O

OBJECTS

OBJNUM

OBJREF

OBJTOCLIENT

OBJVAR

OCCURS

ODBCHDBC

ODBCHSTMT

ODOMETER

OEMTOANSI

OF

OFF

OLDVAL

OLEBASECONTROL

OLEBOUNDCONTROL

OLECLASS

OLECLASSID

OLECLASSIDISPOUT

OLECOMPLETEDRAG

OLECONTROL

OLECONTROLCONTAINER

OLEDRAG

OLEDRAGDROP

OLEDRAGMODE

OLEDRAGOVER

OLEDRAGPICTURE

OLEDROPEFFECTS

OLEDROPHASDATA

OLEDROPMODE

OLEDROPTEXTINSERTION

OLEGIVEFEEDBACK

OLEIDISPATCHINCOMING

OLEIDISPATCHOUTGOING

OLEIDISPINVALUE

OLEIDISPOUTVALUE

OLELCID

OLEOBJECTS

OLEPUBLIC

OLEREQUESTPENDINGTIMOU

OLESERVERBUSYRAISEERRO

OLESERVERBUSYTIMOUT

OLESETDATA

OLESTARTDRAG

OLETYPEALLOWED

ON

ONETOMANY

ONLINE

ONLY

ONMOVEITEM

ONPREVIEWCLOSE

ONRESIZE

OPEN

OPENEDITOR

OPENTABLES

OPENVIEWS

OPENWINDOW

OPTIMIZE

OPTIONBUTTON

OPTIONGROUP

OR

ORACLE

ORDER

ORDERDIRECTION

ORIENTATION

OS

OTHERWISE

OUTER

OUTPUT

OUTPUTPAGE

OUTPUTPAGECOUNT

OUTPUTTYPE

OUTSHOW

OVERLAY

OVERWRITE

P

PACK

PACKETSIZE

PAD

PADC

PADL

PADPROMPT

PADR

PAGE

PAGECOUNT

PAGEFRAME

PAGEHEIGHT

PAGEHEIGHT

PAGENO

PAGEORDER

PAGES

PAGETOTAL

PAGEWIDTH

PAINT

PALETTE

PANEL

PANELLINK

PAPERLENGTH

PAPERSIZE

PAPERWIDTH

PARAMETERS

PARENT

PARENTALIAS

PARENTCLASS

PARENTTABLE

PARTITION

PASSWORD

PASSWORDCHAR

PATH

PATTERN

PAUSE

PAYMENT

PCOL

PCOUNT

PDOX

PDSETUP

PEMSTATUS

PEN

PERCENT

PFS

PI

PICTURE

PICTUREMARGIN

PICTUREPOSITION

PICTURESPACING

PICTURESELECTIONDISPLAY

PICTUREVAL

PIVOT

PIXELS

PLAIN

PLATFORM

PLAY

POINT

POLYPOINTS

POP

POPUPS

POWER

PRECISION

PREFERENCE

PRESERVEWHITESPACE

PRETEXT

PREVIEW

PREVIEWCONTAINER

PRIMARY

PRIMARYKEY

PRINT

PRINTER

PRINTFORM

PRINTJOB

PRINTJOBNAME

PRINTQUALITY

PRINTSTATUS

PRIVATE

PRMBAR

PRMPAD

PROCEDURE

PROCEDURES

PRODUCTION

PROGCACHE

PROGRAM

PROGRAMMATICCHANGE

PROGWORK

PROJECT

PROJECTCLICK

PROJECTHOOK

PROMPT

PROPER

PROTECTED

PROW

PRTINFO

PSET

PSET

PUBLIC

PUSH

PUTFILE

PV

Q

QPR

QUARTER

QUERY

QUERYADDFILE

QUERYMODIFYFILE

QUERYNEWFILE

QUERYREMOVEFILE

QUERYRUNFILE

QUERYTIMEOUT

QUERYUNLOAD

QUERYUNLOAD

QUIETMODE

QUIT

R

RADIANS

RAISEEVENT

RAND

RANDOM

RANGE

RANGEHIGH

RANGELOW

RAT

RATC

RATLINE

RD

RDLEVEL

READ

READACTIVATE

READBORDER

READCOLORS

READCYCLE

READDEACTIVATE

READERROR

READEXPRESSION

READFILLER

READKEY

READLOCK

READMETHOD

READMOUSE

READONLY

READSAVE

READSHOW

READSIZE

READTIMEOUT

READVALID

READWHEN

RECALL

RECCOUNT

RECENTLYUSEDFILES

RECNO

RECOMPILE

RECORD

RECORDMARK

RECORDREFRESH

RECORDSOURCE

RECORDSOURCETYPE

RECOVER

RECSIZE

RECT

RECTCLASS

RECYCLE

REDIT

REFERENCE

REFERENCES

REFRESH

REFRESHALIAS

REFRESHCMD

REFRESHCMDDATASOURCE

REFRESHCMDDATASOURCETYPE

REFRESHIGNOREFIELDLIST

REFRESHTIMESTAMP

REINDEX

RELATEDCHILD

RELATEDTABLE

RELATEDTAG

RELATION

RELATIONALEXPR

RELATIVE

RELATIVECOLUMN

RELATIVEROW

RELEASE

RELEASEERASE

RELEASETYPE

RELEASEWINDOWS

RELEASEXML

REMOTE

REMOVE

REMOVEITEM

REMOVELISTITEM

REMOVEOBJECT

REMOVEPROPERTY

RENAME

RENDER

REPEAT

REPLACE

REPLICATE

REPORT

REPORTBEHAVIOR

REPORTLISTENER

REPROCESS

REQUERY

REQUESTDATA

REQUIRED

RESET

RESETTODEFAULT

RESHEIGHT

RESIZABLE

RESIZE

RESOURCE

RESOURCEON

RESOURCES

RESOURCETO

RESPECTCURSORCP

RESPECTNESTING

REST

RESTORE

RESTRICT

RESUME

RESWIDTH

RETRY

RETURN

REVERTOFFLINE

RGB

RGBSCHEME

RIGHT

RIGHTC

RIGHTCLICK

RIGHTTOLEFT

RLOCK

RMDIR

ROLLBACK

ROLLOVER

ROTATION

ROTATEFLIP

ROUND

ROW

ROWCOLCHANGE

ROWHEIGHT

ROWSET

ROWSOURCE

ROWSOURCETYPE

RPD

RSTOCURSOR

RTLJUSTIFY

RTOD

RTRIM

RULEEXPRESSION

RULETEXT

RUN

RUNTIME

RVIEW

S

SAFETY

SAME

SAMPLE

SAVE

SAVEAS

SAVEASCLASS

SAVEPICTURE

SAY

SCALE

SCALEMODE

SCALEUNITS

SCAN

SCATTER

SCCDESTROY

SCCINIT

SCHEME

SCOLS

SCOREBOARD

SCREEN

SCREENS

SCROLL

SCROLLBARS

SCROLLED

SCROLLSCROLLBARS

SDF

SDIFORM

SEC

SECOND

SECONDS

SECONDS

SEEK

SELECT

SELECTCMD

SELECTED

SELECTEDBACKCOLOR

SELECTEDFORECOLOR

SELECTEDID

SELECTEDITEMBACKCOLOR

SELECTEDITEMFORECOLOR

SELECTION

SELECTIONNAMESPACES

SELECTONENTRY

SELFEDIT

SELLENGTH

SELSTART

SELTEXT

SENDGDIPLUSIMAGE

SENDUPDATES

SEPARATOR

SET

SETALL

SETDATA

SETDEFAULT

SETFLDSTATE

SETFOCUS

SETFORMAT

SETRESULTSET

SETUP

SETVAR

SETVIEWPORT

SHADOWS

SHAPE

SHARECONNECTION

SHARED

SHEET

SHELL

SHIFT

SHORTCUT

SHOW

SHOWDOC

SHOWINTASKBAR

SHOWOLECONTROLS

SHOWOLEINSERTABLE

SHOWTIPS

SHOWVCXS

SHOWWHATSTHIS

SHOWWINDOW

SHUTDOWN

SIGN

SIN

SINGLE

SIZABLE

SIZE

SIZE<HEIGHT>

SIZE<MAXLENGTH>

SIZE<WIDTH>

SIZEBOX

SKIP

SKIPFORM

SKPBAR

SKPPAD

SOM

SOME

SORT

SORTED

SORTWORK

SOUNDEX

SOURCENAME

SOURCETYPE

SPACE

SPARSE

SPECIALEFFECT

SPINNER

SPINNERHIGHVALUE

SPINNERLOWVALUE

SPLITBAR

SQL

SQLASYNCHRONOUS

SQLBATCHMODE

SQLCANCEL

SQLCOLUMNS

SQLCOMMIT

SQLCONNECT

SQLCONNECTTIMEOUT

SQLDISCONNECT

SQLDISPLOGIN

SQLDISPWARNINGS

SQLEXEC

SQLGETPROP

SQLIDLEDISCONNECT

SQLIDLETIMEOUT

SQLL

SQLMORERESULTS

SQLPREPARE

SQLQUERYTIMEOUT

SQLROLLBACK

SQLSETPROP

SQLSTRINGCONNECT

SQLSTRINGCONNECT

SQLTABLES

SQLTRANSACTIONS

SQLWAITTIME

SQRT

SROWS

STACKLEVEL

STANDALONE

STATUS

STATUSBAR

STATUSBARTEXT

STD

STEP

STICKY

STORE

STR

STRCONV

STRETCH

STRICTDATE

STRICTDATEENTRY

STRING

STRTOFILE

STRTRAN

STRUCTURE

STUFF

STUFFC

STYLE

SUBCLASS

SUBSTR

SUBSTRC

SUBSTRING

SUM

SUMMARY

SUPPORTSLISTENERTYPE

SUSPEND

SYLK

SYS

SYSFORMATS

SYSMENUS

SYSMETRIC

SYSTEM

SYSTEMREFCOUNT

T

TAB

TABFIXEDHEIGHT

TABFIXEDWIDTH

TABHIT

TABINDEX

TABLE

TABLEPROMPT

TABLEREFRESH

TABLEREVERT

TABLES

TABLEUPDATE

TABLEVALIDATE

TABORDERING

TABORIENTATION

TABS

TABSTOP

TABSTRETCH

TABSTYLE

TAG

TAGCOUNT

TAGNO

TALK

TAN

TARGET

TASKPANE

TEDIT

TERMINATEREAD

TEXT

TEXTBOX

TEXTHEIGHT

TEXTMERGE

TEXTWIDTH

THEMES

THEN

THIS

THISFORM

THISFORMSET

THROW

TIME

TIMEOUT

TIMER

TIMESTAMP

TIMESTAMPDIFF

TIMESTAMPFIELDLIST

TITLEBAR

TITLES

TMPFILES

TO

TOCURSOR

TOOLBAR

TOOLBOX

TOOLTIPTEXT

TOP

TOPIC

TOPINDEX

TOPITEMID

TOTAL

TOXML

TRANSACTION

TRANSACTIONS

TRANSFORM

TRAP

TRBETWEEN

TRIGGER

TRIM

TRUNCATE

TRY

TTOC

TTOD

TTOPTION

TWOPASSPROCESS

TXNLEVEL

TXTWIDTH

TYPE

TYPEAHEAD

U

UCASE

UDFPARMS

UIENABLE

UNBINDEVENT

UNDEFINE

UNDOCK

UNICODE

UNION

UNIQUE

UNLOAD

UNLOADREPORT

UNLOCK

UNLOCKDATASOURCE

UNNEST

UNPACK

UP

UPCLICK

UPDATABLE

UPDATABLEFIELDLIST

UPDATE

UPDATECMD

UPDATECMDREFRESHCMD

UPDATECMDREFRESHFIELDLIST

UPDATECMDREFRESHKEYFIELDLIST

UPDATECMDSOURCE

UPDATECMDSOURCETYPE

UPDATED

UPDATEDATASOURCE

UPDATEGRAM

UPDATEGRAMSCHEMALOCATION

UPDATENAME

UPDATENAMELIST

UPDATESTATUS

UPDATETRIGGER

UPDATETYPE

UPPER

UPSIZING

USA

USE

USECODEPAGE

USECURSORSCHEMA

USED

USEMEMOSIZE

USERID

USERS

USERVALUE

USETRANSACTIONS

UTF8ENCODED

V

VAL

VALID

VALIDATE

VALUE

VALUEDIRTY

VALUES

VAR

VARBINARY

VARCHAR

VARCHARMAPPING

VARREAD

VARTYPE

VERB

VERSION

VGA25

VGA50

VIEW

VIEWPORTHEIGHT

VIEWPORTLEFT

VIEWPORTTOP

VIEWPORTWIDTH

VIEWS

VISIBLE

VISUALEFFECT

VOLUME

VSCROLLSMALLCHANGE

W

WAIT

WAITTIME

WASACTIVE

WASOPEN

WBORDER

WCHILD

WCOLS

WDOCKABLE

WEEK

WEXIST

WFONT

WHATSTHISBUTTON

WHATSTHISHELP

WHATSTHISHELPID

WHATSTHISMODE

WHEN

WHERE

WHEREWHERETYPE

WHILE

WIDTH

WINDCMD

WINDHELP

WINDMEMO

WINDMENU

WINDMODIFY

WINDOW

WINDOWLIST

WINDOWNTILIST

WINDOWS

WINDOWSTATE

WINDOWTYPE

WINDQUERY

WINDSCREEN

WINDSNIP

WINDSTPROC

WITH

WIZARDPROMPT

WK1

WK3

WKS

WLAST

WLCOL

WLROW

WMAXIMUM

WMINIMUM

WONTOP

WORDWRAP

WORKAREA

WOUTPUT

WP

WPARENT

WR1

WRAP

WRAPCHARINCDATA

WRAPINCDATA

WRAPMEMOINCDATA

WREAD

WRITEEXPRESSION

WRITEMETHOD

WRK

WROWS

WTITLE

WVISIBLE

X

XCMDFILE

XL5

XL8

XLS

XMLADAPTER

XMLCONSTRAINTS

XMLFIELD

XMLNAME

XMLNAMEISXPATH

XMLNAMESPACE

XMLPREFIX

XMLSCHEMALOCATION

XMLTABLE

XMLTOCURSOR

XMLTYPE

XMLUPDATEGRAM

XSDFRACTIONDIGITS

XSDMAXLENGTH

XSDTOTALDIGITS

XSDTYPE

Y

YEAR

YRESOLUTION

Z

ZAP

ZOOM

ZOOMBOX

ZORDER

ZORDERSET

See Also

Other Resources

Language Reference A-Z
Error Messages A-Z
General Reference


String and Value Comparison in Visual FoxPro

Visual FoxPro 9.0
String and Value Comparison in Visual FoxPro
See Also

Visual FoxPro has two relational operators that test for equality: the equal sign (=) operator and the double equal sign (==) operator. You can use the = operator to perform a comparison between two values of the same type and is suitable for comparing data of Character, Numeric, Date, and Logical type. However, when you compare character expressions with the = operator, the results might not exactly as expected.

Character expressions are compared character for character from left to right until one of the expressions does not equal the other or until the end of the expression on the right of the = operator is reached, as specified by setting the SET EXACT command to OFF, or until the ends of both expressions are reached, as specified by setting the SET EXACT command to ON.

You can use the == operator to perform an exact comparison of character or binary data. If you compare two character or binary expressions using the == operator, the expressions on both sides of the == operator must contain precisely the same characters or bytes, including spaces or zero (0) bytes, respectively, to be considered equal. The SET EXACT setting is ignored when character strings or binary expressions are compared using the == operator. For more information, see Relational Operators.

The following table shows how the choice of operator and the SET EXACT setting affect comparisons.

Note:
An underscore represents a blank space.

Comparison | = with SET EXACT OFF | = with SET EXACT ON | == with SET EXACT ON or OFF
"abc" = "abc" | Match | Match | Match
"ab" = "abc" | No match | No match | No match
"abc" = "ab" | Match | No match | No match
"abc" = "ab_" | No match | No match | No match
"ab" = "ab_" | No match | Match | No match
"ab_" = "ab" | Match | Match | No match
"" = "ab" | No match | No match | No match
"ab" = "" | Match | No match | No match
"__" = "" | Match | Match | No match
"" = "___" | No match | Match | No match
TRIM("___") = "" | Match | Match | Match
"" = TRIM("___") | Match | Match | Match

When working with SQL statements such as SELECT - SQL Command, the SET ANSI setting can affect results if you use the = operator.

See Also

Other Resources

SET EXACT Command
SET ANSI Command
General Reference


System Menu Names

Visual FoxPro 9.0 Language Reference
System Menu Names
See Also

The following tables list the internal names and user interface names for the Visual FoxPro system menu bar, menu titles, menus, and menu items. With these names you can use the Visual FoxPro system menu bar to create a menu system for your own application.

The SYS(2013) function returns a space-delimited string containing these names. You can also create a quick menu using the Menu Designer to see the internal system menu names.

For more information on the system menu bar, see Designing Menus and Toolbars.

System Menu Names in Visual FoxPro

The internal name for the system menu bar itself in Visual FoxPro is _MSYSMENU.

System Menus

Menu titles | Internal name
File | _MSM_FILE
Edit | _MSM_EDIT
View | _MSM_VIEW
Format | _MSM_TEXT
Tools | _MSM_TOOLS
Program | _MSM_PROG
Window | _MSM_WINDO
Help | _MSM_SYSTM

File Menu

Menu and items | Internal name
File menu | _MFILE
New | _MFI_NEW
Open | _MFI_OPEN
Close | _MFI_CLOSE
Close All | _MFI_CLALL
1st Separator | _MFI_SP100
Save | _MFI_SAVE
Save As | _MFI_SAVAS
Save As HTML | _MFI_SAVASHTML
Revert | _MFI_REVRT
2nd Separator | _MFI_SP200
Import | _MFI_IMPORT
Export | _MFI_EXPORT
3rd Separator | _MFI_SP300
Page Setup | _MFI_PGSET
Print Preview | _MFI_PREVU
Print | _MFI_SYSPRINT
Send | _MFI_SEND
4th Separator | _MFI_SP400
Exit | _MFI_QUIT

Edit Menu - Visual FoxPro

Menu and items | Internal name
Edit menu | _MEDIT
Undo | _MED_UNDO
Redo | _MED_REDO
1st Separator | _MED_SP100
Cut | _MED_CUT
Copy | _MED_COPY
Paste | _MED_PASTE
Paste Special | _MED_PSTLK
Clear | _MED_CLEAR
2nd Separator | _MED_SP200
Select All | _MED_SLCTA
3rd Separator | _MED_SP300
Find | _MED_FIND
Replace | _MED_REPL
Go To Line | _MED_GOTO
4th Separator | _MED_SP400
List Members | _MED_LISTMEMBERS
QuickInfo | _MED_QUICKINFO
5th Separator | _MED_SP500
Bookmarks | _MED_BKMKS
6th Separator | _MED_SP600
Insert Object | _MED_INSOB
Object | _MED_OBJ
Links | _MED_LINK
7th Separator | _MED_SP700
Properties | _MED_PREF

View Menu

Menu and items | Internal name
View menu | _MVIEW
Toolbars | _MVI_TOOLB

Tools Menu

Menu and items | Internal name
Tools menu | _MTOOLS
Wizards | _MTL_WZRDS
1st Separator | _MTL_SP100
Macros | _MST_MACRO
Class Browser | _MTL_BROWSER
Component Gallery | _MTL_GALLERY
Object Browser | _MTL_OBJECTBROWSER
IntelliSense Manager | _MTI_FOXCODE
2nd Separator | _MTL_SP200
Beautify | _MED_BEAUT
Task List | _MTI_TASKLIST
Document View | _MTI_DOCVIEW
3rd Separator | _MTL_SP300
Coverage Profiler | _MTL_COVERAGE
Breakpoints | _MTI_BREAKPOINT
Debugger | _MTL_DEBUGGER
4th Separator | _MTL_SP400
Trace | _MTI_TRACE
Locals | _MTI_LOCALS
Call Stack | _MTI_CALLSTACK
Output | _MTI_DBGOUT
Options | _MTL_OPTNS

Program Menu

Menu and items | Internal name
Program item | _MPROG
Do | _MPR_DO
Cancel | _MPR_CANCL
Resume | _MPR_RESUM
Suspend | _MPR_SUSPEND
1st Separator | _MPR_SP100
Compile | _MPR_COMPL

Window Menu

Menu and items | Internal name
Window menu | _MWINDOW
Cascade | _MWI_CASCADE
Arrange All | _MWI_ARRAN
1st Separator | _MWI_SP100
Dockable | _MWI_DOCKABLE
2nd Separator | _MWI_SP200
Hide | _MWI_HIDE
Clear | _MWI_CLEAR
Cycle | _MWI_ROTAT
3rd Separator | _MWI_SP300
Command Window | _MWI_CMD
Data Session | _MWI_VIEW (maintains compatibility with earlier versions of Visual FoxPro)
Properties | _MWI_PROPERTIES

Help Menu

Menu and items | Internal name
Help menu | _MSYSTEM
Microsoft Visual FoxPro Help | _MST_HPSCH
MSDN Search | _MST_MSDNS
1st Separator | _MST_SP100
Technical Support | _MST_TECHS
Visual FoxPro on the Web | _MST_VFPWEB
2nd Separator | _MST_SP200
About Microsoft Visual FoxPro | _MST_ABOUT

See Also

Other Resources

SYS(2013) - System Menu Name String
SYS(1500) - Activate a System Menu Item
Menu Designer
Designing Menus and Toolbars
SYS( ) Functions Overview


Visual FoxPro and Other Programming Languages

Visual FoxPro 9.0 Language Reference
Visual FoxPro and Other Programming Languages
See Also

Most programming languages have similar basic features. If you are familiar with one programming language, you can easily translate this knowledge to another language. Choose an item below to see a comparison of Visual FoxPro with BASIC, C/C++, and Pascal.

To compare | See
Whether the language is case-sensitive. | Case Sensitivity
How variables are declared. | Variable Declaration
How to insert comments in programs. | Comments
How to store values to variables. | Assignment Statements
The structure of IF statements. | IF Statements
The structure of CASE statements. | CASE Statements
The structure of FOR loops. | FOR Loops
The structure of WHILE loops. | WHILE Loops
How to pass data to parameters | Passing Data to Parameters in Other Programming Languages

See Also

Other Resources

General Reference


Case Sensitivity (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Case Sensitivity (Visual FoxPro)
See Also

You can compare how case sensitivity differs between Visual FoxPro and other languages.

Visual FoxPro | BASIC
Not case-sensitive | Not case-sensitive

Pascal | C/C++
Case-sensitive | Case-sensitive

See Also

Other Resources

Visual FoxPro and Other Programming Languages


Variable Declaration (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Variable Declaration (Visual FoxPro)
See Also

You can compare how variable declaration differs between Visual FoxPro and other programming languages. In Visual FoxPro, you do not assign a data type to a variable. However, it is recommended that you name your variable with a prefix suggesting the data type you plan to use it with. Other languages require that you assign a data type to a variable when you declare it. For more information, see Variable Naming Conventions.

Note:
When you store a value to a variable and the variable does not exist, Visual FoxPro implicitly declares it with PRIVATE scope. Other languages that require explicit declaration of variables return an error. To create variables in Visual FoxPro with PUBLIC or LOCAL scope, you must explicitly declare them with the PUBLIC or LOCAL command. For more information, see PUBLIC Command and LOCAL Command.

Visual FoxPro | BASIC
Variables are implicitly declared with no data typing. | Variables can be implicitly declared, and the variable name dictates data type.

Pascal | C/C++
Variables must be explicitly declared and assigned a data type. | Variables must be explicitly declared and assigned a data type.

See Also

Other Resources

Variables
Access to Variables
Visual FoxPro and Other Programming Languages


Comments

Visual FoxPro 9.0 Language Reference
Comments
See Also

You can compare how comment formatting differs between Visual FoxPro and other programming languages. Visual FoxPro, C, and C++ have different formats for whole line comments and comments on partial lines.

Visual FoxPro | BASIC
* Full line comment. USE && Inline comment. NOTE Multiple-line ; comment | ' Comment

Pascal | C/C++
{ Comment } | // Comment /* Multiple-line comment */

See Also

Other Resources

* Command
&& Command
NOTE Command
Visual FoxPro and Other Programming Languages


Assignment Statements (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Assignment Statements (Visual FoxPro)
See Also

You can compare how assignment statements differ between Visual FoxPro and other programming languages.

Note:
In Visual FoxPro, you can also assign values to fields in a table with the REPLACE command.

Visual FoxPro BASIC

nVal = 7

-OR-

STORE 7 to nVal

Copy Code
nVal = 7

Pascal C/C++
Copy Code
nVal := 7
Copy Code
nVal = 7

See Also

Other Resources

= Command
STORE Command
Visual FoxPro and Other Programming Languages


CASE Statements

Visual FoxPro 9.0 Language Reference
CASE Statements
See Also

You can compare how case statements differ between Visual FoxPro and other programming languages. Only Pascal does not offer default values in case statements.

Visual FoxPro BASIC
Copy Code
DO CASE
 CASE n = 0
  ? 'Zero'
 CASE n > 0
  ? 'Pos'
 OTHERWISE
  ? 'Neg'
ENDCASE
Copy Code
Select Case n
 Case 0
  Print 'Zero'
 Case Is > 0
  Print 'Pos'
 Case Else
  Print 'Neg'
End Select

Pascal C/C++
Copy Code
case n of
 0: writeln("Zero");
 1: writeln("One");
end
Copy Code
switch(n) {
 case 0:
  printf("Zero\n");
  break;
 case 1:
  printf("One\n");
  break;
 default:
  printf("?\n");}

See Also

Other Resources

DO CASE ... ENDCASE Command
Visual FoxPro and Other Programming Languages


IF Statements

Visual FoxPro 9.0 Language Reference
IF Statements
See Also

You can compare how IF statements differ between Visual FoxPro and other programming languages. The THEN clause is allowed only on the IF statement in Visual FoxPro.

Visual FoxPro | BASIC
IF nCnt < nMax nTot = nTot * nCnt nCnt = nCnt + 1 ENDIF | If nCnt < nMax Then nTot = nTot * nCnt nCnt = nCnt + 1 End If

Pascal | C/C++
if nCnt < nMax then begin nTot:=nTot * nCnt; nCnt:=nCnt + 1; end | if(nCnt < nMax) { nTot *= nCnt; nCnt++; }

See Also

Other Resources

IF ... ENDIF Command
Visual FoxPro and Other Programming Languages


FOR Loops (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
FOR Loops (Visual FoxPro)
See Also

You can compare how FOR loops differ between Visual FoxPro and other programming languages.

Visual FoxPro | BASIC
FOR n = 1 TO 10 ? n ENDFOR | For n = 1 to 10 Print n Next n

Pascal | C/C++
for n := 1 to 10 do writeln(n); | for(n=1; n<11; n++) printf("%d\n",n);

See Also

Other Resources

FOR ... ENDFOR Command
Visual FoxPro and Other Programming Languages


WHILE Loops (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
WHILE Loops (Visual FoxPro)
See Also

You can compare how WHILE loops differ between Visual FoxPro and other programming languages.

Visual FoxPro | BASIC
DO WHILE n < 100 n = n + n ENDDO | Do While n < 100 n = n + n Loop

Pascal | C/C++
while n < 100 do n := n + n; | while(n < 100) n += n;

See Also

Other Resources

WHILE Clauses
Visual FoxPro and Other Programming Languages


Passing Data to Parameters in Other Programming Languages

Visual FoxPro 9.0 Language Reference
Passing Data to Parameters in Other Programming Languages
See Also

You can compare how the passing of data differs between Visual FoxPro and other languages.

The following table compares passing data to parameters by reference between Visual FoxPro and other languages.

Visual FoxPro | BASIC
=ABC(@X) –OR– DO ABC WITH X | ABC X

Pascal | C/C++
procedure ABC var x:integer); | ABC(&VAR);

The following table compares passing data to parameters by value between Visual FoxPro and other languages.

Visual FoxPro | BASIC
=ABC(X) | ABC ByVal X

Pascal | C/C++
procedure ABC (x:integer); | ABC(X);

See Also

Other Resources

How to: Pass Data to Parameters by Reference
How to: Pass Data to Parameters by Value
Passing Data to Parameters
Visual FoxPro and Other Programming Languages


Visual FoxPro System Capacities

Visual FoxPro 9.0
Visual FoxPro System Capacities
See Also

Different parts of Visual FoxPro have system capacity limits. The following tables list these limits.

Note:
Some capacities might be limited by available memory and disk space.

Table and Index Files

Feature | Capacity
Maximum # of records per table file. | 1 billion
Maximum size of a table file. | 2 gigabytes
Maximum size of an FPT file. | 2 gigabytes
Maximum # of characters per record. | 65,500
Maximum # of fields per record1. | 255
Maximum # of tables open at one time2. | 65,535
Maximum # of characters per table field. | 254
Maximum # of bytes per index key in a non-compact index3. | 100
Maximum # of bytes per index key in a compact index3. | 240
Maximum # of open index files per table2. | Limited by available memory
Maximum # of open indexes in all work areas2. | Limited by available memory
Maximum # of relations. | Limited by available memory
Maximum length of relational expressions. | Limited by available memory

Fields

Feature | Capacity
Maximum size of character fields. | 254
Maximum size of numeric and float fields. | 20
Maximum number of characters in field names in a free table. | 10
Maximum number of characters in field names for a table contained in a database. | 128
Minimum value of an integer. | -2,147,483,647
Maximum value of an integer. | 2,147,483,647
Digits of precision in numeric computations. Visual FoxPro can handle numbers up to 9007199254740992 (2^53) in exact computations. | 16
Miscellaneous: 64 bits = 8 bytes Largest number = 10 ^ 308 = 2 ^ 1023 -> 10 bits per exponent + 1 for exponent sign plus 1 for number sign => 12 bits Leaving 52 bits for the mantissa + 1 for implied normalized bit -> 53 bits LOG10(2^53) = 15.95 decimal digits accuracy |

Variables and Arrays

Feature | Capacity
Default # of variables. | 16,384
Maximum # of variables. | 65,000
Maximum # of arrays. | 65,000
Maximum # of elements per array. | Normal: 2 gigabytes Member array: 2 gigabytes Array of member objects: 65,000

Program and Procedure Files

Feature Capacity

Maximum # of lines in source program files.

Limited by available memory

Maximum size of compiled program modules4.

Limited by available memory

Maximum # of procedures per file.

Limited by available memory

Maximum # of nested DO calls.

Tip:
You can change the default level of nesting by using a configuration file that includes the STACKSIZE setting. For more information, see Special Terms for Configuration Files.

128 (Default)

Maximum # of READ nesting levels.

5

Maximum # of nested structured programming commands.

384

Maximum # of passed parameters.

26

Maximum # of transactions.

5

Maximum # of compiler levels for #INCLUDE.

4

Reports

Feature | Capacity
Maximum # of objects in a report definition. | Limited by available memory
Maximum height of a single report band. | 20 inches | 50.8 cm | 1920 pixels
Maximum # of data grouping levels. | 74
Maximum length of character report variable names or a report expression. | 255
Maximum # of Detail bands. | 20
Maximum # of pages in a report at run time. | 65534 In object-assisted preview, limited by available GDI+ resources

Miscellaneous

Feature | Capacity
Maximum # of open windows (all types)2. | Limited by available memory
Maximum # of open Browse windows. | 255
Maximum # of characters per character string or memory variable. | 16,777,184
Maximum # of characters per command line. | 8,192
Maximum # of characters per label control on a report. | 252
Maximum # of characters per macro substituted line. | 8,192
Maximum # of open files. | Operating system limit
Maximum keystrokes in keyboard macro. | 1,024
Maximum fields that can be selected by a SQL SELECT statement. | 255
Maximum length of a string literal. | 255

1 If one or more fields allow null values, the limit is reduced by one to 254 fields.

2 Limited by memory and available file handles. .cdx files use only one file handle.

3 If the collating sequence is set to MACHINE, each character uses one byte. If the collating sequence is not set to MACHINE, each character uses two bytes. If the indexed field supports null values, one additional byte is used in the index key. Note that non-machine indexes are always compact.

4 A program module is one procedure. A program or application can contain an unlimited number of program modules.

See Also

Other Resources

General Reference
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)
How to: Set Up an ODBC Data Source
Display System Information Sample
Optimizing Your System
File Extensions and File Types
Optimizing Visual FoxPro Startup Speed
Special Terms for Configuration Files


XSource Folder

Visual FoxPro 9.0
XSource Folder
See Also

The XSource folder in your Visual FoxPro \Tools directory contains a .zip file that expands to folders containing source files for various Visual FoxPro components. Under its VFPSource root folder, the .zip file includes folders containing source files for the applications listed in the following table.

Default application name and location | Xsource subfolder | Help topics with information about the application
HOME()+ "Tools\AddLabel\"+ "AddLabel.app" | Addlabel | How to: Add a Label Definition Using Addlabel.app
HOME()+ "Browser.app" | Browser | Class Browser Window
HOME()+ "Builder.app" | Builders | Builders
HOME()+ "Convert.app" | Convert | Visual FoxPro Converter Dialog Box
HOME()+ "Coverage.app" | Coverage | Coverage Profiler Application
HOME()+ "DataExplorer.app" | DataExplorer | Data Explorer Task Pane
HOME()+ "EnvMgr.app" | EnvMgr | Environment Manager Task Pane
HOME()+ "FoxCode.app" | Foxcode | IntelliSense Support in Visual FoxPro
HOME()+ "FoxRef.app" | Foxref | Code References Window
HOME()+ "MemberDataEditor.app" | MemberData | MemberData Editor
HOME()+ "ObjectBrowser.app" | Obrowser | Object Browser Window
HOME()+ "ReportBuilder.app" | ReportBuilder | Extending Reports at Design Time
HOME()+ "ReportOutput.app" | ReportOutput | Extending Report Output Functionality
HOME()+ "ReportPreview.app" | ReportPreview | Extending Report Preview Functionality
HOME()+ "TaskList.app" | Tasklist | Task List Manager Window
HOME()+ "TaskPane.app" | Taskpane | Task Pane Manager
HOME()+ "Toolbox.app" | Toolbox | Toolbox (Visual FoxPro)
HOME()+ "VFPClean.app" | Vfpclean | How to: Reinstall Visual FoxPro
HOME()+ "Wizards\"+ "WebService.app" | Webservice | XML Web Services in Visual FoxPro
HOME()+ "Wizards\"+ "AnchorEditor.app" | Wizards\AnchorEditor | Miscellaneous Enhancements
HOME()+ "Wizards\"+ "DEBuilder.app" | Wizards\debuilder | DataEnvironment Builder
HOME()+ "Wizards\"+ "WzApp.app" | Wizards\wzapp | Application Wizard
HOME()+ "Wizard.app" | Wizards\wzcommon | Wizards (Visual FoxPro)
HOME()+ "Wizards\"+ "WzApp.app" | Wizards\wzform | Form Wizard
HOME()+ "Wizards\"+ "WzFoxDoc.app" | Wizards\wzfoxdoc | Documenting Wizard
HOME()+ "Wizards\"+ "WzGraph.app" | Wizards\wzgraph, Wizards\automate, | Graph Wizard
HOME()+ "Wizards\"+ "WzImport.app" | Wizards\wzimport | Import Wizard
HOME()+ "Wizards\"+ "WzMail.app" | Wizards\wzmail, Wizards\automate | Mail Merge Wizard
HOME()+ "Wizards\"+ "WzPivot.app" | Wizards\wzpivot, Wizards\automate | PivotTable Wizard Cross-Tab Wizard
HOME()+ "Wizards\"+ "WzQuery.app" | Wizards\wzquery | Query Wizard
HOME()+ "Wizards\"+ "WzReport.app" | Wizards\wzreport | Report Wizard
HOME()+ "Wizards\"+ "WzTable.app" | Wizards\wztable | Table Wizard
HOME()+ "Wizards\"+ "WzUpsize.app" | Wizards\wzupsize | SQL Server Upsizing Wizard
HOME()+ "Wizards\"+ "WzWeb.app | Wizards\wzweb, Wizards\wzintnet | Web Publishing Wizard

See Also

Other Resources

General Reference
Development Productivity Tools
Utility Programs


Language Reference (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Language Reference (Visual FoxPro)

You can use the Visual FoxPro interface to perform many database tasks and develop applications for cataloging, tracking, and processing information. Knowing more about the Visual FoxPro programming language enhances your ability to access the power of Visual FoxPro.

Like other programming languages, the Visual FoxPro programming language makes it possible for you to work with various types of data, such as numbers and character strings. You can store data of these various types in tables, arrays, variables, and other data containers. To manipulate data, you can perform operations, such as addition and concatenation. In addition to operators, Visual FoxPro provides a rich set of commands and functions, so you can protect, display, and manage your data.

This section contains information about programming language elements in Visual FoxPro.

In This Section

Language Categories

Contains categories describing areas of functionality offered by Visual FoxPro.
Commands

Lists the commands available in Visual FoxPro.
Objects, Collections, and Classes

Lists the classes, collections, and objects available in Visual FoxPro.
Properties

Lists the properties of classes and objects in Visual FoxPro.
Methods

Lists the methods available in Visual FoxPro.
Events

Lists the events that occur in Visual FoxPro.
Functions

Lists the functions available in Visual FoxPro.
Operators

Lists the operators you can use to manipulate data in Visual FoxPro.
Preprocessor Directives

Lists the preprocessor directives you can include in your Visual FoxPro programs.
System Variables

Lists the Visual FoxPro system variables which you can use to store values.
API Library Construction

Describes API library routines, system events, and key codes.
SQL Commands and Functions

Describes Structured Query Lanaguage (SQL) commands and functions supported by Visual FoxPro.
Language Reference for OLE DB Development

Describes support in the OLE DB Provider for native Visual FoxPro language and syntax.
Backward-Compatible Language Elements

Lists obsolete language elements that are included for backwards compatibility.

Related Sections

Reference

Includes Visual FoxPro general, programming language, user interface, and error message reference topics.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.
Samples and Walkthroughs

Contains Visual FoxPro code samples and step-by-step walkthroughs that you can use for experimenting with and learning Visual FoxPro features.


Language Categories

Visual FoxPro 9.0 Language Reference
Language Categories

This section contains basic categories describing the functionality of Visual FoxPro.

In This Section

Databases

Links to information on how you can manipulate databases, tables, records, and fields, as well as indexes and relations.
Input and Output

Contains links to information about controlling input and output from your applications.
Programming

Contains links to more programming information, including array manipulation, debugging and error handling, structured programming, and so on.
Shared Access to Data

Contains commands and functions that make it possible for you to manage multiple users.
Visual FoxPro Environment

Lists commands and functions that make it possible for you to access the Visual FoxPro environment.

Related Sections

Language Reference

Contains a list of language reference topics in alphabetical order.
Naming Conventions

Discusses how to choose names for exposed objects, properties, and methods that can be understood easily by users of the application.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.
Visual FoxPro and Other Programming Languages

Provides a comparison between Visual FoxPro and other programming languages.


Databases

Visual FoxPro 9.0 Language Reference
Databases

You can manipulate databases, tables, records, and fields, as well as indexes and relations.

In This Section

Database Manipulation

Lists the commands and functions that manipulate databases.
Field Manipulation

Lists the commands and functions that make it possible for you to manipulate fields in a table.
Indexes

Lists the commands and functions that perform operations on and return information about index files.
Record Manipulation

Lists the commands and functions that make it possible for you to select records within a table or position the record pointer.
Relations

Lists the commands and functions that make it possible for you to establish or break relations between table files.
Table Manipulation

Lists the commands and functions that make it possible for you to create, manipulate, and monitor table files.

Related Sections

Language Categories

Contains a list of language functionality and descriptions.
Using Visual FoxPro

Discusses how Visual FoxPro programming features are designed to improve developer productivity including Access and Assign methods, support for more graphic file formats, and language to simplify programming tasks.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Database Manipulation Language

Visual FoxPro 9.0 Language Reference
Database Manipulation Language
See Also

The following table lists commands and functions that make it possible to manipulate databases.

Use | To
ADATABASES( ) Function | Place the names and paths of all open databases into an array.
ADD TABLE Command | Add a free table to the current database.
APPEND PROCEDURES Command | Append stored procedures in a text file to the stored procedures in the current database.
AUSED( ) Function | Place table aliases and work areas for a data session into a variable array.
CLOSE Commands | Close various file types.
COMPILE Command | Compile the specified source files and create an object file for each one.
COPY PROCEDURES Command | Copy stored procedures in the current database to a text file.
CREATE CONNECTION Command | Create a named connection and stores it in the current database.
CREATE DATABASE Command | Create a database and open it.
CREATE SQL VIEW Command | Display the View Designer, where you can create a SQL view.
CREATE TRIGGER Command | Create a Delete, Insert, or Update trigger for a table.
CREATEOFFLINE( ) Function | Take an existing view offline.
DROPOFFLINE( ) Function | Discard all changes made to an offline view and take the offline view back online.
CURSORGETPROP( ) Function | Retrieve the current property settings for a Visual FoxPro table or a cursor.
CURSORSETPROP( ) Function | Specify property settings for a Visual FoxPro table or a cursor.
CURVAL( ) Function | Return field values directly from disk for a table or a remote data source.
DATETIME( ) Function | Return the current date and time as a DateTime value, or create a year 2000-compliant DateTime value.
DBC( ) Function | Return the name and path of the current database.
DBGETPROP( ) Function | Retrieve the value of a property for the current database or for fields, named connections, tables, or views in the current database.
DBSETPROP( ) Function | Set a property for the current database or for fields, named connections, tables, or views in the current database.
DBUSED( ) Function | Return true (.T.) if the specified database is open.
DELETE - SQL Command | Mark records for deletion.
DELETE CONNECTION Command | Delete a named connection from the current database.
DELETE DATABASE Command | Delete a database from disk.
DELETE TRIGGER Command | Remove a trigger for a table from the current database.
DELETE VIEW Command | Delete a SQL view from the current database.
DISPLAY CONNECTIONS Command | Display information about the named connections in the current database.
DISPLAY DATABASE Command | Display information about the current database or fields, named connections, tables, or views in the current database.
DISPLAY PROCEDURES Command | Display the names of procedures stored in the current database.
DISPLAY TABLES Command | Display names and information about all the tables contained in the current database.
DISPLAY VIEWS Command | Display information about SQL views in the current database.
FREE TABLE Command | Remove a database reference from a table.
GETFLDSTATE( ) Function | Return a numeric value indicating the status of a field in a table or cursor.
GETNEXTMODIFIED( ) Function | Return the record number for the next modified record in a buffered table or cursor.
INDBC( ) Function | Return whether a specified database object is in the current database.
ISEXCLUSIVE( ) Function | Return whether a specified database is opened exclusively.
LIST CONNECTIONS Command | Display information about the named connections in the current database.
LIST DATABASE Command | Display information about the current database.
LIST PROCEDURES Command | Display the names of stored procedures in the current database.
LIST TABLES Command | Display the table information contained in the current database.
LIST VIEWS Command | Display the information about SQL views in the current database.
MODIFY CONNECTION Command | Display the Connection Designer.
MODIFY DATABASE Command | Display the Database Designer.
MODIFY PROCEDURE Command | Open the Visual FoxPro text editor.
MODIFY VIEW Command | Display the View Designer.
OLDVAL( ) Function | Return original field values for fields that have been modified but not updated.
OPEN DATABASE Command | Open a database.
PACK DATABASE Command | Remove records marked for deletion from the current database.
REFRESH( ) Function | Refresh data in an updatable SQL remote or local view or CursorAdapter cursor.
REMOVE TABLE Command | Remove a table from the current database.
RENAME CONNECTION Command | Rename a named connection in the current database.
RENAME TABLE Command | Rename a table in the current database.
RENAME VIEW Command | Rename a SQL view in the current database.
REQUERY( ) Function | Retrieve data again for a SQL view.
SET DATABASE Command | Specify the current database.
SET DATASESSION Command | Activate the specified form's data session.
SETFLDSTATE( ) Function | Assign a field modification or deletion state value to a field or record in a table or cursor.
SQLCANCEL( ) Function | Request cancellation of an executing SQL statement.
SQLCOLUMNS( ) Function | Store column information for a specified data source table in a cursor.
SQLCOMMIT( ) Function | Commit a transaction.
SQLCONNECT( ) Function | Establish a connection to a data source.
SQLDISCONNECT( ) Function | Terminate a connection to a data source.
SQLEXEC( ) Function | Send a SQL statement to the data source, where the statement is processed.
SQLGETPROP( ) Function | Retrieve the current settings for an active connection.
SQLMORERESULTS( ) Function | Copy another result set to a Visual FoxPro cursor if more result sets are available.
SQLROLLBACK( ) Function | Cancel any changes made during the current transaction.
SQLSETPROP( ) Function | Specify settings for an active connection.
SQLSTRINGCONNECT( ) Function | Establish a connection to a data source using a connection string.
SQLTABLES( ) Function | Store the names of tables in a data source to a Visual FoxPro cursor.
TABLEREVERT( ) Function | Discard changes made to a buffered row, buffered table, or cursor.
TABLEUPDATE( ) Function | Commit changes made to a buffered row, a buffered table, cursor, or cursor adapter.
_TRIGGERLEVEL System Variable | Contains a read-only numeric value indicating the current trigger procedure nesting level.
VALIDATE DATABASE Command | Ensure that the locations of tables and indexes in the current database are correct.

See Also

Other Resources

Databases
Language Categories


Field Manipulation Language

Visual FoxPro 9.0 Language Reference
Field Manipulation Language
See Also

These commands and functions make it possible for you to manipulate fields in a table.

Use | To
AFIELDS( ) Function | Store information about the structure of the current table into an array and return the number of fields.
BLANK Command | Clear data from the specified fields.
DELETED( ) Function | Indicate if a record is marked for deletion.
FCOUNT( ) Function | Return the number of fields in a table.
FIELD( ) Function | Return the name of a field, reference by number.
FLDLIST( ) Function | Included for compatibility with dBASE.
FSIZE( ) Function | Return the size in bytes of a specified field or file.
GATHER Command | Replace the data in a record with data from a specified source.
ISBLANK( ) Function | Determine whether an expression is blank.
LUPDATE( ) Function | Return the date on which a table was last updated.
NDX( ) Function | Return the name of an open index (.IDX) file for the current or specified table.
SCATTER Command | Copy data from a record into a specified target.
SET BLOCKSIZE Command | Specify how to allocate disk space for memo field storage.
SET EXACT Command | Specify the rules to compare two strings of different lengths.
SET NOCPTRANS Command | Prevent translation to a different code page for selected fields in an open table.
SET TEXTMERGE Command | Enable or disable the evaluation of fields, variables, array elements, functions, or expressions that are surrounded by text-merge delimiters, and specify text-merge output.
SET TEXTMERGE DELIMITERS Command | Specify the text-merge delimiters.
SYS(14) - Index Expression | Return index expression of an open single-entry .idx index file or index expressions for tags in compound .cdx index files.

See Also

Other Resources

Databases
Language Categories


Index Manipulation Language

Visual FoxPro 9.0 Language Reference
Index Manipulation Language
See Also

These commands and functions perform operations on and return information about index files.

Use | To
ATAGINFO( ) Function | Create an array that contains information about index files for the selected table.
CANDIDATE( ) Function | Specify if an index tag is a candidate index tag.
CDX( ) Function | Return the name of the open compound index file that has the specified index position.
CLOSE Commands | Close various file types.
COPY INDEXES Command | Create compound index tags from single-entry .idx index files.
COPY TAG Command | Create a single-entry index (.idx) file from a tag in a compound index file.
DESCENDING( ) Function | Determine if an index was created with the DESCENDING keyword.
DELETE TAG Command | Remove a tag from a compound index file.
FOR( ) Function | Return an index filter expression.
IDXCOLLATE( ) Function | Return the collating sequence for an index or index tag.
INDEX Command | Create an index file.
INDEXSEEK( ) Function | Search and indexed table without moving the record pointer.
KEY( ) Function | Return the index key expression for an index tag or index file.
KEYMATCH( ) Function | Search an index tag or index file for an index key.
MDX( ) Function | Return the name of the open compound index file that has the specified index position number.
NDX( ) Function | Return the name of an open index (.IDX) file for the current or specified table.
ORDER( ) Function | Return the name of the controlling index file or tag
PRIMARY( ) Function | Determine if an index tag is the primary index tag.
REINDEX Command | Rebuild open index files.
SET COLLATE Command | Specify a collation sequence for character fields in indexing and sorting operations.
SET INDEX Command | Open one or more index files for use with the current table.
SET KEY Command | Specify access to a range of records based on their index keys.
SET ORDER Command | Designate a controlling index file or tag for a table.
SET UNIQUE Command | Specify whether records with duplicate index key values are maintained in an index file.
SYS(14) - Index Expression | Return the index expressions from indexes.
SYS(21) - Controlling Index Number | Return the index position for the current selected work area.
SYS(2021) - Filtered Index Expression | Return a filter expression from an index.
TAG( ) Function | Return a tag name from an open compound index file or the name from an open single-entry index file.
TAGCOUNT( ) Function | Return the number of open indexes.
TAGNO( ) Function | Return the index position for an index file.

See Also

Other Resources

Databases
Language Categories


Record Manipulation Language

Visual FoxPro 9.0 Language Reference
Record Manipulation Language
See Also

These commands and functions make it possible for you to select records within a table or position the record pointer.

Use | To
APPEND FROM Command | Add records to a table.
APPEND MEMO Command | Copy the contents of a text file to a memo field.
BLANK Command | Clear data from fields.
CONTINUE Command | Continue the previous LOCATE.
DELETE - SQL Command | Mark records for deletion.
FILTER( ) Function | Return a table filter expression specified in SET FILTER.
GO | GOTO Command | Move a record pointer.
INDEXSEEK( ) Function | Search an indexed table without moving the record pointer.
INSERT – SQL Command | Append new records to a table.
ISBLANK( ) Function | Determine if an expression is blank.
KEYMATCH( ) Function | Search and index tag or an index file for an index key.
LOCATE Command | Sequentially search a table for a specified logical expression.
LOOKUP( ) Function | Search a table for the first record with a field matching a specified expression
REPLACE FROM ARRAY Command | Update data in fields with values from a variable array.
SEEK Command | Search a table for a record whose index key matches a general expression.
SEEK( ) Function | Search an indexed table for a record whose index key matches a specified expression.
SET COLLATE Command | Specify a collate sequence for character fields in subsequent indexing and sorting operations.
SET FILTER Command | Specify a condition that records must meet to be accessible.
SET KEY Command | Specify access to a range of records based on their index keys.
SET NEAR Command | Determine where the record pointer is positions after an unsuccessful search for a record.
SET RELATION Command | Establish a relation between two open tables.
SKIP Command | Move the record pointer forward or backward in a table.
UPDATE - SQL Command | Update records in a table with new values.

See Also

Other Resources

Databases
Language Categories


Relation Manipulation Language

Visual FoxPro 9.0 Language Reference
Relation Manipulation Language
See Also

These commands and functions make it possible for you to establish or break relations between table files.

Use | To
RELATION( ) Function | Return a specified relational expression for a table open in a specific work area.
SELECT - SQL Command | Retrieve data from one or more tables.
SET RELATION Command | Establish a relationship between two open tables.
SET RELATION OFF Command | Break an established relationship between the parent table and the related child table.
SET SKIP Command | Create a one-to-many relationship among tables.
TARGET( ) Function | Return the alias of a table that is the target for a relation as specified in the INTO clause of SET RELATION.

See Also

Other Resources

Databases
Language Categories


Table Manipulation Language

Visual FoxPro 9.0 Language Reference
Table Manipulation Language
See Also

These commands and functions make it possible for you to create, manipulate, and monitor table files.

Use | To
ADD TABLE Command | Add a free table to the current database.
ALINES( ) Function | Copy each line in a memo field to a corresponding row in an array.
ALTER TABLE - SQL Command | Modify the structure of a table.
APPEND Command | Add records to the end of a table.
AUSED( ) Function | Place table aliases and work areas for a data session into a variable array.
AVERAGE Command | Compute the arithmetic mean of numeric expressions or fields.
BEGIN TRANSACTION Command | Begin a transaction.
BROWSE Command | Open the browse window and display records from a table.
CHANGE Command | Display fields for editing.
CLOSE TABLES Command | Close open tables.
COPY MEMO Command | Copy the contents of a memo field to a text file.
COPY STRUCTURE Command | Create a new empty table with the same structure as the currently selected table.
COPY STRUCTURE EXTENDED Command | Create a new table with fields containing the structure of the currently selected table.
COPY TO Command | Create a new file from the contents of a table.
COUNT Command | Count table records.
CPCURRENT( ) Function | Return the current code page settings.
CPDBF( ) Function | Return the code page information that a table was marked with.
CREATE Command | Build a new table.
CREATE FROM Command | Create a table from a table created with the COPY STRUCTURE EXTENDED command.
CREATE QUERY Command | Open the Query designer.
CREATE TABLE - SQL Command | Build a new table.
CURVAL( ) Function | Return field values.
DELETE Command | Mark records for deletion.
DELETE - SQL Command | Mark records for deletion.
DELETED( ) Function | Determine if a record is marked for deletion.
DISPLAY STRUCTURE Command | Display the structure of a table.
DISPLAY TABLES Command | Display the names and information about all the tables in a database.
EDIT Command | Display fields for editing.
END TRANSACTION Command | End a transaction.
EXPORT Command | Copy data from a table to a file in a different format.
FLUSH Command | Save table and index changes to disk.
GETFLDSTATE( ) Function | Return a numeric value indicating the status of a field in a table or cursor.
GETNEXTMODIFIED( ) Function | Get the record number for the next modified record in a buffered table or cursor.
IMPORT Command | Import data from an external file format to create a new table.
ISEXCLUSIVE( ) Function | Determine if a table is opened exclusively.
ISREADONLY( ) Function | Determine if a table is opened as read-only.
LIST TABLES Command | Display the names and information about all the tables in a database
MEMLINES( ) Function | Return the number of lines in a memo field.
MLINE( ) Function | Return a specific line in a memo as a character string
MODIFY GENERAL Command | Open editing windows for general fields in the current record.
MODIFY MEMO Command | Open an editing window for a memo or blob field in the current window.
MODIFY QUERY Command | Open the Query Designer.
MODIFY STRUCTURE Command | Display the Table Designer.
OLDVAL( ) Function | Return the original values for fields that have been modified but not updated.
PACK Command | Permanently remove all records in a table that have been marked for deletion and reduce the size of a memo file associated with the table.
RECALL Command | Unmark records marked for deletion in a table.
REFRESH( ) Function | Refresh data in an updatable SQL remote or local view, or CursorAdapter cursor.
REMOVE TABLE Command | Remove a table from the current database.
REPLACE Command | Update table records.
REPLACE FROM ARRAY Command | Update data in fields with values from a variable array.
RENAME TABLE Command | Rename a table.
ROLLBACK Command | Cancel any changes made during the current transaction.
SELECT Command | Activate the specified work area.
SELECT - SQL Command | Retrieve data from one or more tables.
SET ANSI Command | Determine whether to pad a shorter string with spaces when making a SQL string comparison or binary expression with zero (0) bytes when making a binary expression comparison in SQL commands using the equal sign operator (=).
SET AUTOSAVE Command | Determine whether Visual FoxPro flushes data buffers to disk when you exit a READ or return to the Command window.
SET DATASESSION Command | Activate a specified forms data session.
SET DELETED Command | Specify whether Visual FoxPro processes records marked for deletion and whether they are available for use with other commands.
SET FIELDS Command | Specify which fields in a table can be accessed.
SET NULL Command | Specify how null values are supported by various commands.
SET OLEOBJECT Command | Specify if Visual FoxPro searches the registry when an object cannot be located.
SET OPTIMIZE Command | Enable or disable Rushmore Query Optimization.
SORT Command | Sort records in a table and output the sorted records to a new table.
SUM Command | Total numeric fields in a table.
SYS(2029) - Table Type | Return a value corresponding to the table type.
TABLEREVERT( ) Function | Discard changed made to a buffered row or a buffered table or cursor and restore the OLDVAL( ) data.
TABLEUPDATE( ) Function | Commit changes made to a buffered row, a buffered table, or a cursor adapter.
TOTAL Command | Compute totals for numeric fields in a table.
TXNLEVEL( ) Function | Return a numeric value indicating the current transaction level.
UPDATE - SQL Command | Update records in a table with new values.
USE Command | Open a table.
USED( ) Function | Determine if an alias is in use or a table is open in a specific work area.
ZAP Command | Remove all records from a table, leaving just the table structure.

See Also

Reference

Table Designer (Visual FoxPro)

Other Resources

Databases
Query and View Designers
Language Categories


Input and Output (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Input and Output (Visual FoxPro)

To find out more about controlling input and output from your applications, choose one of the following sections.

In This Section

Data Formatting

Lists the commands and functions that make it possible for you to format and display data from records, fields, memory variables, or arrays.
Keyboard and Mouse Input

Lists the commands and functions that make it possible for you to control input with the keyboard or mouse.
Menus and Menu Bars

Lists the commands and functions that make it possible for you to develop, display, and activate user-defined menus and menu bars.
Printing

Lists the commands and functions that make it possible for you to print or display data from records or memory variables to the screen, a printer, or an output file.
Reports and Labels

Lists the commands that make it possible for you to create reports and control output.
Windows Commands and Functions

Lists the commands and functions that make it possible for you to create, display, and activate user-defined windows.

Related Sections

Language Categories

Contains a list of language functionality and descriptions.
Using Visual FoxPro

Discusses how Visual FoxPro programming features are designed to improve developer productivity, including Access and Assign methods, support for more graphic file formats, and language to simplify programming tasks.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Data Formatting Language

Visual FoxPro 9.0 Language Reference
Data Formatting Language
See Also

These commands and functions make it possible for you to format and display data from records, fields, memory variables, or arrays. They also make it possible for you to manipulate general screen or window display features.

Use | To
\ | \\ Command | Print or display lines of text.
? | ?? Command | Evaluate an expression and send the results to the main Visual FoxPro window, an active user-defined window, or the printer.
@ ... CLEAR Command | Clear a portion of the main Visual FoxPro window or a user-defined window.
@ ... FILL Command | Change the color of existing text within an area of the screen.
ACTIVATE SCREEN Command | Send all subsequent output to the main Visual FoxPro window instead of to the active user-defined window.
APPEND Command | Add one or more records to the end of a table.
BROWSE Command | Opens the browse window and displays records from a table.
CHANGE Command | Display fields for editing.
CLEAR Commands | Release specified items from memory.
CLOSE FORMAT Command | Close various file types.
CREATE FORM Command | Open the form designer.
DISPLAY Command | Display record contents and expression results for the current table.
DisplayPath( ) Function | Truncate long path expressions to a specified length for display.
EDIT Command | Display fields for editing.
FUNCTION Command | Create a user-defined function in a program file.
INKEY( ) Function | Return a number corresponding to the first mouse click or key press in the type-ahead buffer.
LIST Commands | Display table or environment information without pausing the main Visual FoxPro or user-defined window.
MESSAGEBOX( ) Function | Display a user-defined dialog box.
MODIFY FORM Command | Open the Form Designer so you can modify or create a form.
OBJTOCLIENT( ) Function | Return a position or dimension of a control or object relative to its form.
RESTORE SCREEN Command | Restore the main Visual FoxPro window or a user-defined window previously saved to the screen buffer, a variable, or an array element.
SAVE SCREEN Command | Restore the main Visual FoxPro window or a user-defined window previously saved to the screen buffer, a variable, or an array element.
SCOLS( ) Function | Return the number of columns available in the main Microsoft Visual FoxPro window.
SCROLL Command | Scroll an area of the main Visual FoxPro window or a user-defined window up, down, left, or right.
SET CARRY Command | Determine whether Visual FoxPro carries data forward from the current record to a new record created with INSERT, APPEND, and BROWSE.
SET COLOR OF SCHEME Command | Specify the colors of a color scheme or copies one color scheme to another color scheme.
SET COLOR SET Command | Load a previously defined color set.
SET CONFIRM Command | Specify whether the user can exit a text box by typing past the last character in the text box.
SET CONSOLE Command | Enable or disables output to the main Visual FoxPro window or to the active user-defined window from within programs.
SET CURSOR Command | Determine whether the insertion point is displayed when Visual FoxPro waits for input.
SET DECIMALS Command | Specify the number of decimal places displayed in numeric expressions.
SET DEVICE Command | Direct output from @ ... SAY to the screen, a printer, or a file.
SET FIXED Command | Specify if the number of decimal places used in the display of numeric data is fixed.
SET HEADINGS Command | Determine whether column headings are displayed for fields and whether file information is included when TYPE is issued to display the contents of a file.
SET MARK TO Command | Specify a delimiter for the display of date expressions.
SET MEMOWIDTH Command | Specify the displayed width of memo fields and character expressions.
SET MESSAGE Command | Define a message for display in the main Visual FoxPro window or in the graphical status bar, or specifies the location of messages for user-defined menu bars and menu commands.
SET ODOMETER Command | Specify the reporting interval of the record counter for commands that process records.
SET SPACE Command | Determine whether a space is displayed between fields or expressions when you use the ? or ?? command.
SET TEXTMERGE Command | Enable or disable the evaluation of fields, variables, array elements, functions, or expressions that are surrounded by text-merge delimiters, and specify text-merge output.
SET TEXTMERGE DELIMITERS Command | Specify the set of text-merge delimiter characters to use other than the default.
SROWS( ) Function | Return the number of rows available in the main Visual FoxPro window.
SYS(7) - Current Format File | Return the name of the current format file.
SYS(2002) - Turn Insertion Point On or Off | Turn the insertion point on or off.
TEXT ... ENDTEXT Command | Send lines of text specified by TextLines to the current output device.
TRANSFORM( ) Function | Return a character string from an expression in a format determined by a format code.

See Also

Reference

Form Designer

Other Resources

Input and Output
Language Categories


Keyboard and Mouse Input

Visual FoxPro 9.0 Language Reference
Keyboard and Mouse Input
See Also

These commands and functions make it possible for you to control input with the keyboard or mouse.

Use | To
AMOUSEOBJ( ) Function | Create an array containing information about the mouse pointer position and the object over which the mouse pointer is positioned.
CAPSLOCK( ) Function | Return the current mode of the CAPS LOCK key or set the CAPS LOCK key mode on or off.
CHRSAW( ) Function | Determine whether or not a character is present in the keyboard buffer.
CLEAR MACROS Command | Release the specified item or items from memory.
CLEAR TYPEAHEAD Command | Release the specified item or items from memory.
INSMODE( ) Function | Return the current insert mode, or sets the insert mode on or off.
KEYBOARD Command | Place the specified character expression in the keyboard buffer.
LASTKEY( ) Function | Return an integer corresponding to the last key pressed.
MCOL( ) Function | Return the column position of the mouse pointer in the main Visual FoxPro window or a user-defined window.
MOUSE Command | Perform the equivalent of clicking, double-clicking, or moving the mouse, or perform a drag operation.
MROW( ) Function | Return the row position of the mouse pointer in the main Visual FoxPro window or in a user-defined window.
NUMLOCK( ) Function | Return the current mode of the NUM LOCK key or set the mode of the NUM LOCK key on or off.
ON KEY LABEL Command | Specify a command that executes when you press a specific key or key combination or click the mouse button.
PLAY MACRO Command | Execute a keyboard macro.
POP KEY Command | Restore ON KEY LABEL assignments that were placed on the stack with PUSH KEY.
PUSH KEY Command | Place all current ON KEY LABEL command settings on a stack in memory.
RESTORE MACROS Command | Restore to memory keyboard macros saved in a keyboard macro file or memo field.
SAVE MACROS Command | Save a set of keyboard macros to a keyboard macro file or to a memo field.
SET FUNCTION Command | Assign an expression (keyboard macro) to a function key or key combination.
SET KEYCOMP Command | Control Visual FoxPro keystroke navigation.
SET MACKEY Command | Specify a key or key combination that displays the Macro Key Definition dialog box.
SET TYPEAHEAD Command | Specify the maximum number of characters that can be stored in the type-ahead buffer.

See Also

Other Resources

Input and Output
Language Categories


Menus and Menu Bars

Visual FoxPro 9.0 Language Reference
Menus and Menu Bars
See Also

These commands and functions make it possible for you to develop, display, and activate user-defined menus and menu bars.

Use | To
\ | \\ Command | Print or display lines of text.
ACTIVATE POPUP Command | Display and activate a menu.
BAR( ) Function | Return the number of the most recently chosen item from a menu defined with DEFINE POPUP or a menu item chosen from a Visual FoxPro menu.
BARPROMPT( ) Function | Included for compatibility with dBASE.
CLEAR MENUS Command | Release the specified item or items from memory.
CLEAR POPUPS Command | Release the specified item or items from memory.
CNTBAR( ) Function | Return the number of menu items on a user-defined menu or the Visual FoxPro system menu.
CNTPAD( ) Function | Return the number of menu titles on a user-defined menu bar or the Visual FoxPro system menu bar.
CREATE MENU Command | Open the Menu designer in Visual FoxPro.
DEACTIVATE MENU Command | Deactivate a user-defined menu bar and remove it from the screen.
DEACTIVATE POPUP Command | Deactivate a menu created with DEFINE POPUP.
DEFINE BAR Command | Create a menu item on a menu created with DEFINE POPUP.
DEFINE MENU Command | Create a menu bar.
DEFINE PAD Command | Create a menu title (pad) on a user-defined menu bar or the Visual FoxPro system menu bar.
DEFINE POPUP Command | Create a menu.
GETBAR( ) Function | Return the number of an item on a menu defined with DEFINE POPUP or the Visual FoxPro system menu.
GETPAD( ) Function | Return the menu title for a given position on the menu bar.
HIDE MENU Command | Hide one or more active user-defined menu bars.
HIDE POPUP Command | Hide one or more active menus created with DEFINE POPUP.
MODIFY MENU Command | Open the Menu designer so you can modify or create a menu system.
MOVE POPUP Command | Move a user-defined menu created with DEFINE POPUP to a new location.
MRKBAR( ) Function | Determine whether a menu item on a user-defined or Microsoft Visual FoxPro system menu is marked.
MRKPAD( ) Function | Determine whether a menu title on a user-defined menu bar or on the Visual FoxPro system menu bar is marked.
ON BAR Command | Specify a menu or menu bar that is activated when you choose a specific menu item from a menu.
ON EXIT BAR Command | Included for compatibility with dBASE.
ON EXIT MENU Command | Included for compatibility with dBASE.
ON EXIT PAD Command | Included for compatibility with dBASE.
ON EXIT POPUP Command | Included for compatibility with dBASE.
ON PAD Command | Specify the menu or menu bar that is activated when you choose a specific menu title.
ON SELECTION BAR Command | Specify a command that executes when you choose a specific menu item.
ON SELECTION MENU Command | Specify a command that executes when you choose any menu title on a menu bar.
ON SELECTION PAD Command | Specify a command that executes when you choose a specific menu title on a menu bar.
ON SELECTION POPUP Command | Specify a command that executes when you choose any menu item from a specified menu or from all menus.
PAD( ) Function | Return as an uppercase character string the menu title most recently chosen from a menu bar, or returns a logical value indicating if a menu title is defined for an active menu bar.
POP MENU Command | Restore the specified menu bar definition that was placed on the stack with PUSH MENU.
POP POPUP Command | Restore the specified menu definition that was placed on the stack with PUSH POPUP.
POPUP( ) Function | Return as a string the name of the active menu, or a logical value indicating if a menu has been defined.
PRMBAR( ) Function | Return the text of a menu item.
PRMPAD( ) Function | Return the text of a menu title.
PROMPT( ) Function | Return the text for a menu title chosen from a menu bar or for a menu item chosen from a menu.
PUSH MENU Command | Place a menu bar definition in a stack of menu bar definitions in memory.
PUSH POPUP Command | Place a menu definition on a stack of menu definitions in memory.
RELEASE BAR Command | Remove a specified menu item or all menu items on a menu from memory.
RELEASE MENUS Command | Remove user-defined menu bars from memory.
RELEASE PAD Command | Remove a specific menu title or all menu titles from memory.
RELEASE POPUPS Command | Remove a specific menu or all menus from memory.
SET MARK OF Command | Specify a mark character for menu titles or menu items, displays, or clear the mark character.
SET SKIP OF Command | Enable or disable a menu, menu bar, menu title, or menu item for user-defined menus or the Microsoft Visual FoxPro system menu.
SIZE POPUP Command | Change the size of a menu created with DEFINE POPUP.
SKPBAR( ) Function | Determine if a menu item is enabled or disabled with SET SKIP OF.
SKPPAD( ) Function | Determine whether a menu title is enabled or disabled with SET SKIP OF.
SHOW MENU Command | Display one or more user-defined menu bars without activating them.
SHOW POPUP Command | Display one or more menus defined with DEFINE POPUP without activating them.
SYS(2013) - System Menu Name String | Return a space-delimited character string containing the internal names of the Visual FoxPro menu system.

See Also

Other Resources

Input and Output
Menu Designer
Language Categories


Printing (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Printing (Visual FoxPro)
See Also

These commands and functions make it possible for you to print or display data from records or memory variables to the screen, a printer, or an output file.

Use | To
_ASCIICOLS System Variable | Specify the number of columns in an ASCII text file created with the ASCII keyword in the REPORT FORM command.
_ASCIIROWS System Variable | Specify the number of rows in an ASCII text file created with the ASCII keyword in the REPORT FORM command.
\ | \\ Command | Print or display lines of text.
? | ?? Command | Evaluate expressions and sends the results to the main Visual FoxPro window, an active user-defined window, or the printer.
??? Command | Send output directly to the printer.
APRINTERS( ) Function | Store information about currently installed printers into an array.
CLOSE ALTERNATE Command | Close various file types.
DISPLAY Command | Display record contents and expression results for the current table in the main Visual FoxPro window or a user-defined window.
EJECT Command | Send a formfeed to the printer.
EJECT PAGE Command | Send a conditional page advance to the printer.
GETPRINTER( ) Function | Display the Printer dialog box and returns the name of the selected printer.
LIST Commands | Display table or environment information without pausing the main Visual FoxPro or user-defined window.
ON PAGE Command | Specify a command that executes when printed output reaches a specified line number in a report or when you issue EJECT PAGE.
PCOL( ) Function | Return the current column position of the printer's print head.
PRINTJOB ... ENDPRINTJOB Command | Activate the settings for print job system variables.
PROW( ) Function | Return the current row number of the printer's print head.
PRTINFO( ) Function | Return the current specified printer setting.
REPORT FORM Command | Display or print a report specified by a report definition (.frx) file, for example, created with the CREATE REPORT or MODIFY REPORT command.
SET MARGIN Command | Set the left printer margin.
SET PDSETUP Command | Load a printer driver setup or clears the current printer driver setup.
SET PRINTER Commands | Enable or disable output to the printer or routes output to a file, port, or network printer.
SYS(6) - Current Printer Device | Return the current print device.
SYS(1037) - Page Setup Dialog Box | Display 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.
TYPE Command | Display the contents of a file.

See Also

Reference

Print Dialog Box (Visual FoxPro)
Report Designer

Other Resources

Input and Output
Language Categories


Reports and Labels

Visual FoxPro 9.0 Language Reference
Reports and Labels
See Also

These commands make it possible for you to create reports and control output.

Use | To
_ASCIICOLS System Variable | Specify the number of columns in an ASCII text file created with the ASCII keyword in the REPORT FORM command.
_ASCIIROWS System Variable | Specify the number of rows in an ASCII text file created with the ASCII keyword in the REPORT FORM command.
\ | \\ Command | Print or display lines of text.
CREATE LABEL Command | Open the Label Designer to create a label in standard label format or to design a custom label.
CREATE REPORT Command | Open the Label Designer to create a label in standard label format or to design a custom label.
LABEL Command | Send labels from a label file to the specified output format.
MODIFY LABEL Command | Open the Label Designer to create or modify a label.
MODIFY REPORT Command | Open the Report Designer to create or modify a report.
REPORT Command | Display or print a report specified by a report definition (.frx) file, for example, created with the CREATE REPORT or MODIFY REPORT command.

See Also

Reference

Report Designer
Label Designer

Other Resources

Input and Output
Language Categories


Windows Commands and Functions

Visual FoxPro 9.0 Language Reference
Windows Commands and Functions
See Also

These commands and functions make it possible for you to create, display, and activate user-defined windows.

Use | To
ACTIVATE WINDOW Command | Display and activate one or more user-defined windows or Visual FoxPro system windows.
BorderStyle Property | Specify the border style of an object.
CLEAR WINDOWS Command | Release the specified item or items from memory.
CREATE FORM Command | Open the Form Designer.
DEACTIVATE WINDOW Command | Deactivate user-defined windows or Visual FoxPro system windows and remove them from the screen, but not from memory.
DEFINE WINDOW Command | Create a window and specify its attributes.
HIDE WINDOW Command | Hide an active user-defined window or Microsoft Visual FoxPro system window.
MODIFY FORM Command | Open the Form Designer so you can modify or create a form.
MODIFY WINDOW Command | Modifie a user-defined window or the main Visual FoxPro window.
MOVE WINDOW Command | Move a user-defined window created with DEFINE WINDOW, or a Visual FoxPro system window, to a new location.
Refresh Method | Repaint a form or control and refresh any values, or refresh a project's visual display.
RELEASE WINDOWS Command | Remove user-defined windows or Visual FoxPro system windows from memory.
RESTORE WINDOW Command | Restore to memory window definitions and window statuses saved to a window file or memo field.
SAVE WINDOWS Command | Save all or specified window definitions to a window file or memo field.
SHOW WINDOW Command | Display one or more user-defined windows or Visual FoxPro system windows without activating them.
SIZE WINDOW Command | Change the size of a window created with DEFINE WINDOW or a Visual FoxPro system window.
TextBox Control | Create a text box.
WBORDER( ) Function | Determine whether the active or specified window has a border.
WCHILD( ) Function | Return either the number of child windows in a parent window or the names of the child windows in the order in which they are stacked in the parent window.
WCOLS( ) Function | Return the number of columns within the active or specified window.
WEXIST( ) Function | Determine whether the specified user-defined window exists.
WFONT( ) Function | Return the name, size, or style of the current font for a window in Visual FoxPro for Windows.
WLAST( ) Function | Return the name of the window that was active prior to the current window or determines whether the specified window was active prior to the current window.
WLCOL( ) Function | Return the column coordinate of the upper-left corner of the active or specified window.
WLROW( ) Function | Return the row coordinate of the upper-left corner of the active or specified window.
WMAXIMUM( ) Function | Determine whether the active or specified window is maximized.
WMINIMUM( ) Function | Determine whether the active or specified window is minimized.
WONTOP( ) Function | Determine whether the active or specified window is in front of all other windows.
WOUTPUT( ) Function | Determine whether output is being directed to the active or specified window.
WPARENT( ) Function | Return the name of the parent window of the active or specified window.
WREAD( ) Function | Included for backward compatibility. Use the Form Designer instead.
WROWS( ) Function | Return the number of rows within the active or specified window.
WTITLE( ) Function | Return the title assigned to the active or specified window.
WVISIBLE( ) Function | Determine if the specified window has been activated and isn't hidden.
ZOOM WINDOW Command | Change the size and position of a user-defined window or a Visual FoxPro system window.

See Also

Other Resources

Input and Output
Language Categories


Programming

Visual FoxPro 9.0 Language Reference
Programming

The following categories contain Visual FoxPro language for programming tasks.

In This Section

Array Manipulation

Lists the commands and functions that make it possible for you to work with arrays of variables.
Debugging and Error-Handling Language

Lists Visual FoxPro language that you can use to perform debugging and error-handling operations in Visual FoxPro programs.
Event Handlers

Lists the commands and functions that make it possible for you to specify the action a program takes when a given event occurs.
Low-Level File Functions

Lists the functions that make it possible for you to manipulate files and communication ports at a low level. Low-level file functions should be used carefully, especially when manipulating table files.
Object-Oriented Programming Commands and Functions

Lists the commands and functions that make it possible for you to create and manipulate classes and objects.
Program Execution

Lists the commands and functions that make it possible for you to control how Visual FoxPro programs are executed, suspended, and terminated.
Structured Programming

Lists the commands and functions that make it possible for you to control program execution and branching within a Visual FoxPro program.
Variable Manipulation

Lists the commands and functions for manipulating variables.
System Variables Overview

Lists the built-in variables that Visual FoxPro creates and maintains automatically.

Related Sections

Language Categories

Lists language functionality and descriptions by groups.
Using Visual FoxPro

Discusses how Visual FoxPro programming features are designed to improve developer productivity, including Access and Assign methods, support for more graphic file formats, and language to simplify programming tasks.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Array Manipulation

Visual FoxPro 9.0 Language Reference
Array Manipulation
See Also

These commands and functions make it possible for you to work with arrays of variables.

To | Use
ACOPY( ) Function | Copies elements from one array to another array.
ADEL( ) Function | Deletes an element from a one-dimensional array, or a row or column from a two-dimensional array.
ADIR( ) Function | Places information about files into an array and then returns the number of files.
AELEMENT( ) Function | Returns the number of an array element from the element's subscripts.
AFIELDS( ) Function | Retrieves and stores information about the structure of the table in a specified work area, specified by a table alias, or in the currently selected work area in an array and returns the number of fields in the table.
AFONT( ) | Places information about available fonts, such as their names, into an array.
AINS( ) Function | Inserts an element into a one-dimensional array, or a row or column into a two-dimensional array.
ALEN( ) Function | Returns the number of elements, rows, or columns in an array.
APPEND FROM ARRAY Command | Adds one record to the currently selected table for each row in an array and fills each record with data from the corresponding array row.
ASESSIONS( ) Function | Creates an array of existing data session IDs.
ASCAN( ) Function | Searches an array for an element containing the same data and data type as an expression.
ASORT( ) Function | Sorts elements in an array in ascending or descending order.
ASUBSCRIPT( ) Function | Returns the row or column subscript of an element from the element's number.
COPY TO ARRAY Command | Copies data from the currently selected table to an array.
DECLARE Command | Creates a one- or two-dimensional array.
DIMENSION Command | Creates a one-dimensional or two-dimensional array of variables.
GATHER Command | Replaces the data in the current record of the currently selected table with data from an array, a set of variables, or an object.
SCATTER Command | Copies data from the current record to a set of variables or to an array.

See Also

Other Resources

Programming
Language Categories


Debugging and Error-Handling Language

Visual FoxPro 9.0 Language Reference
Debugging and Error-Handling Language
See Also

The following table lists language makes it possible for you to perform debugging and error-handling operations in Visual FoxPro programs.

Debugging Language

Use | To
* Command | Indicate the beginning of a comment line.
&& Command | Indicate the beginning of an inline comment.
CLEAR EVENTS Command | Release the specified item or items from memory.
DEBUG Command | Open the Visual FoxPro Debugger.
DEBUGOUT Command | Direct the result of one or more expressions to the Debug Output window.
SET DEVELOPMENT Command | Determine whether the Trace window is opened when an error occurs in a form that is running.
SET TALK Command | Determine whether Visual FoxPro displays command results.
SET TRBETWEEN Command | Enable or disables tracing between breakpoints in the Trace window.
WAIT Command | Display a message and pauses Visual FoxPro execution until the user presses a key or clicks the mouse.

Error Handling Language

Use | To
AERROR( ) Function | Store error information in an array.
COMRETURNERROR( ) Function | Store error information in the COM exception structure.
DEBUG Command or SET STEP Command | Open the Debugger or Trace window.
ERROR Command | Generate a specific Visual FoxPro error to test your error handling.
ERROR( ) Function | Return an error number.
LINENO( ) Function | Return an executing program line.
MESSAGE( ) Function | Return an error message string.
ON ERROR Command | Execute a command when an error occurs.
ON( ) Function | Return commands assigned to error handling commands.
ON SHUTDOWN Command | Executes a command when exiting Visual FoxPro or Windows.
PROGRAM( ) Function OR SYS(16) - Executing Program File Name | Return the name of the currently executing program.
RETRY Command | Run the most recently executed command.
SET AUTOINCERROR Command | Generate an error when attempting to update or insert values in an autoincrementing field.
SYS(2018) - Error Message Parameter | Return any current error message parameter.
SYS(2410) - Error Handler | Return error handler type for an error.
TRY...CATCH...FINALLY Command | Handle errors and exceptions that might occur while running a block of code.

See Also

Reference

Debugger Window
Trace Window

Other Resources

Testing and Debugging Applications
Programming
Language Categories


Event Handlers

Visual FoxPro 9.0 Language Reference
Event Handlers
See Also

These commands and functions make it possible for you to specify the action a program takes when a given event occurs.

Use | To
EVENTHANDLER( ) Function | Bind a COM server event to implemented interface methods on a Visual FoxPro object.
ON ERROR Command | Specify a valid expression or Visual FoxPro command to execute when an error occurs in code at run time.
ON ESCAPE Command | Specify a command that executes when you press the ESC key during program or command execution.
ON KEY LABEL Command | Specify a command that executes when you press a specific key or key combination or click the mouse button.
ON PAD Command | Specify the menu or menu bar that is activated when you choose a specific menu title.
ON SELECTION PAD Command | Specify the menu or menu bar that is activated when you choose a specific menu title.
ON SELECTION POPUP Command | Specify a command that executes when you choose any menu item from a specified menu or from all menus.
ON SHUTDOWN Command | Specify a command that executes when you try to exit Visual FoxPro, or Microsoft Windows.
ON( ) Function | Return the command assigned to each of these event-handling commands: ON ERROR, ON ESCAPE, ON KEY LABEL, or ON PAGE.

See Also

Reference

Form Designer

Other Resources

Programming
Language Categories


Low-Level File Functions

Visual FoxPro 9.0 Language Reference
Low-Level File Functions
See Also

These functions make it possible for you to manipulate files and communication ports at a low level. Low-level file functions should be used carefully, especially when manipulating table files. Before using these functions, test them on sample files before using them on files that contain important data.

Use | To
FCHSIZE( ) Function | Change the size of a file opened with a low-level file function.
FCLOSE( ) Function | Flush and close a file or communication port opened with a low-level file function.
FCREATE( ) Function | Create and open a low-level file.
FEOF( ) Function | Determine whether the file pointer is positioned at the end of a file.
FERROR( ) Function | Return a number corresponding to the most recent low-level file function error.
FFLUSH( ) Function | Flush to disk a file opened with a low-level function.
FGETS( ) Function | Return a series of bytes from a file or a communication port opened with a low-level file function until it encounters a carriage return.
FOPEN( ) Function | Open a file for use with low-level file functions.
FPUTS( ) Function | Write a character string, carriage return, and line feed to a file opened with a low-level file function.
FREAD( ) Function | Return a specified number of bytes from a file opened with a low-level function.
FSEEK( ) Function | Move the file pointer in a file opened with a low-level file function.
FWRITE( ) Function | Write a character string to a file opened with a low-level file function.
HEADER( ) Function | Return the number of bytes in the header of the current or specified table file.

See Also

Other Resources

Programming
Language Categories


Object-Oriented Programming Commands and Functions

Visual FoxPro 9.0 Language Reference
Object-Oriented Programming Commands and Functions
See Also

These commands and functions make it possible for you to create and manipulate classes and objects.

Use | To
:: Scope Resolution Operator | Run a parent class method from within a subclass method.
@ ... CLASS Command | Create a control or object that can be activated with READ.
_WIZARD System Variable | Contain the name of the Visual FoxPro wizard application.
ACLASS( ) Function | Place an object's class name and its ancestor class names into a variable array.
ADATABASES( ) Function | Place the names of all open databases and their paths into a variable array.
ADBOBJECTS( ) Function | Place the names of named connections, relations, tables, or SQL views in the current database into a variable array.
ADD CLASS Command | Add a class definition to a .vcx visual class library.
AGETCLASS( ) Function | Display class libraries in the Open dialog box and create an array containing the name of the class library and class chosen.
AINSTANCE( ) Function | Place instances of a class into a variable array and returns the number of instances placed in the array.
AMEMBERS( ) Function | Place the names of properties, procedures, and member objects for an object into a variable array.
AMOUSEOBJ( ) Function | Create an array containing information about the mouse pointer position and the object over which the mouse pointer is positioned.
ASELOBJ( ) Function | Place an object reference for the currently selected control or container that exists in the Form Designer, Class Designer, or code editing window into a specified variable array.
AVCXCLASSES( ) Function | Place the information about classes in a class library into an array.
_BUILDER System Variable | Contain the name of the Visual FoxPro builder application.
COMCLASSINFO( ) Function | Return registry information about a COM object such as a Visual FoxPro automation server.
COMPOBJ( ) Function | Compare the properties of two objects and returns True (.T.) if their properties and property values are identical.
CREATE CLASS Command | Open the Class Designer, allowing you to create a new class definition.
CREATE CLASSLIB Command | Create a new, empty visual class library (.vcx) file.
CREATEOBJECT( ) Function | Create an object from a class definition or an Automation-enabled application.
DEFINE CLASS Command | Create a user-defined class or subclass and specifies the properties, events, and methods for the class or subclass.
DISPLAY OBJECTS Command | Display information about an object or a group of objects.
GETINTERFACE( ) Function | Provide access to COM object properties, methods, and events through early binding.
GETOBJECT( ) Function | Activate an Automation object and creates a reference to the object.
LIST OBJECTS Command | Continuously display information about an object or a group of objects
LOADPICTURE( ) Function | Create an object reference for a bitmap, icon, or Windows meta file.
MODIFY CLASS Command | Open the Class Designer, making it possible for you to modify an existing class definition or create a new class definition.
NEWOBJECT( ) Function | Create a new class or object directly from a visual class library (.vcx) file or program (.prg) file without opening the file.
RELEASE CLASSLIB Command | Close .vcx visual class libraries containing class definitions.
REMOVE CLASS Command | Remove a class definition from a .vcx visual class library.
RENAME CLASS Command | Rename a class definition contained in a .VCX visual class library.
SAVEPICTURE( ) Function | Create a bitmap (.bmp) file from a picture object reference.
_SCREEN System Variable | Specify properties and methods for the main Visual FoxPro window.
SET CLASSLIB Command | Open a .vcx visual class library containing class definitions.
SET OLEOBJECT Command | Specify whether Visual FoxPro searches the registry when an object cannot be located.
WITH ... ENDWITH Command | Specify multiple properties for an object.

See Also

Reference

Form Designer

Concepts

Class Designer

Other Resources

Programming
Language Categories


Program Execution

Visual FoxPro 9.0 Language Reference
Program Execution
See Also

These commands and functions make it possible for you to control how Microsoft Visual FoxPro programs are executed, suspended, and terminated.

Use | To
BUILD APP Command | Create a standard application (.app) file from a Visual FoxPro project.
BUILD DLL Command | Create a single-threaded Windows dynamic-link library (.dll), or Automation server, using class definitions from a Visual FoxPro project.
BUILD EXE Command | Create an executable (.exe) file from a Visual FoxPro project.
BUILD PROJECT Command | Create a Visual FoxPro project table (.pjx) file by opening, processing, and including one or more specified program, menu, report, label, form, or library files in the project.
CANCEL Command | End execution of the current Visual FoxPro program file.
CLEAR PROGRAM Command | Release the specified item or items from memory.
CLOSE Commands | Close various file types.
COMPILE Command | Compile one or more specified source files and creates an object file for each source file.
CREATE PROJECT Command | Open the Project Manager so you can create a project.
#DEFINE ... #UNDEF Preprocessor Directive | Create and release compile-time constants.
DO Command | Execute a Visual FoxPro program or procedure.
DO FORM Command | Run a compiled form or form set created with the Form designer.
EXECSCRIPT( ) Function | Enable you to run multiple lines of code from variables, tables, and other text at runtime.
FUNCTION Command | Create a user-defined function in a program file. There are two versions of the syntax.
#IF ... #ENDIF Preprocessor Directive | Conditionally includes source code at compile-time.
#INCLUDE Preprocessor Directive | Instruct the Visual FoxPro preprocessor to treat the contents of a specified header file as if it appeared in a Visual FoxPro program.
_INCLUDE System Variable | Specify a default header file included with user-defined classes, forms, or form sets.
LPARAMETERS Command | Assign data passed from a calling program to local variables or arrays.
MESSAGEBOX( ) Function | Display a user-defined dialog box.
MODIFY PROJECT Command | Open the Project Manager so you can modify or create a project file.
PARAMETERS Command | Assign data from a calling program to private variables or arrays.
PARAMETERS( ) Function | Return the number of parameters passed to the most recently called program, procedure, or user-defined function.
PROCEDURE Command | Create a user-defined procedure in a program file. There are two versions of the syntax.
RELEASE PROCEDURE Command | Close procedure files opened with SET PROCEDURE.
RESUME Command | Continue execution of a suspended program.
RETURN Command | Return program control to a calling program.
RUN | ! Command | Execute external operating commands or programs.
SET ESCAPE Command | Determine whether pressing the ESC key interrupts program and command execution.
SET LIBRARY Command | Open an external API (application programming interface) library file.
SET LOGERRORS Command | Determine whether to send Visual FoxPro compilation error messages to a text file.
SET PROCEDURE Command | Open a procedure file.
SET SYSMENU Command | Enable or disables the Visual FoxPro system menu bar during program execution, and allows you to reconfigure it.
SET UDFPARMS Command | Specify whether Visual FoxPro passes variables by value or by reference to parameters in procedures and user-defined functions (UDFs).
SUSPEND Command | Pause program execution and returns to interactive Visual FoxPro.
SYS(2015) - Unique Procedure Name | Return a unique 10-character procedure name that begins with an underscore followed by a combination of letters and numbers.
WAIT Command | Display a message and pauses Visual FoxPro execution until the user presses a key or clicks the mouse.

See Also

Other Resources

Programming
Language Categories


Structured Programming

Visual FoxPro 9.0 Language Reference
Structured Programming
See Also

These commands and functions make it possible for you to control program execution and branching within a Visual FoxPro program.

Use | To
DO CASE ... ENDCASE Command | Execute the first set of commands whose conditional expression evaluates to true (.T.).
DO WHILE ... ENDDO Command | Execute a set of commands within a conditional loop.
EXIT Command | Exit a DO WHILE, FOR, or SCAN loop.
FOR EACH ... ENDFOR Command | Execute a set of commands for each element in a Visual FoxPro array or collection.
FOR ... ENDFOR Command | Execute a set of commands a specified number of times.
#IF ... #ENDIF Preprocessor Directive | Conditionally include source code at compile-time.
#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive | Conditionally include a set of commands at compile time if a compile-time constant is defined.
ICASE( ) Function | Evaluate the results from a list of conditions.
IF ... ENDIF Command | Conditionally execute a set of commands based on the value of a logical expression.
IIF( ) Function | Return one of two values depending on the value of a logical expression.
LOOP Command | Return program control directly to the beginning of a looping structure.
SCAN ... ENDSCAN Command | Move the record pointer through the currently selected table and execute a block of commands for each record that meets the specified conditions.

See Also

Other Resources

Programming
Language Categories


Variable Manipulation

Visual FoxPro 9.0 Language Reference
Variable Manipulation
See Also

These commands and functions make it possible for you to assign values to variables or text.

Use | To
& Command | Perform macro substitution.
= Command | Evaluate one or more expressions.
ACOPY( ) Function | Copy elements from one array to another array.
ADEL( ) Function | Delete an element from a one-dimensional array, or a row or column from a two-dimensional array.
ADIR( ) Function | Place information about files into an array and then return the number of files.
AELEMENT( ) Function | Return the number of an array element from the element's subscripts.
AFIELDS( ) Function | Retrieve and stores information about the structure of the table in a specified work area, specified by a table alias, or in the currently selected work area in an array and return the number of fields in the table.
AINS( ) Function | Insert an element into a one-dimensional array, or a row or column into a two-dimensional array.
ASCAN( ) Function | Search an array for an element containing the same data and data type as an expression.
ASORT( ) Function | Sort elements in an array in ascending or descending order.
ASUBSCRIPT( ) Function | Return the row or column subscript of an element from the element's number.
AVERAGE Command | Compute the arithmetic mean of numeric expressions or fields.
CLEAR ALL Command | Release the specified item or items from memory.
CLEAR MEMORY Command | Release the specified item or items from memory.
COUNT Command | Count table records.
DISPLAY MEMORY Command | Display the current contents of variables and arrays.
GETEXPR Command | Display the Expression Builder Dialog Box so you can create an expression and store the expression to a variable or array element.
_GETEXPR System Variable | Specify the program that is executed when you issue the GETEXPR command or invoke the Expression Builder dialog box from within Visual FoxPro.
LEN( ) Function | Determine the number of characters in a character expression, indicating the length of the expression.
LIST MEMORY Command | Display table or environment information without pausing the main Visual FoxPro or user-defined window.
LOCAL Command | Create local variables and variable arrays.
PARAMETERS Command | Assign data from a calling program to private variables or arrays.
PRIVATE Command | Hide specified variables or arrays that were defined in a calling program from the current program.
PUBLIC Command | Define global variables or arrays.
RELEASE Command | Remove variables and arrays from memory.
RESTORE FROM Command | Retrieve variables and variable arrays saved in a variable file or a memo field and places them into memory.
SAVE TO Command | Store current variables and arrays to a variable file or memo field.
STORE Command | Store data to a variable, to an array, or to an array element.
SUM Command | Total all or specified numeric fields in the currently selected table.
TEXTMERGE( ) Function | Provide evaluation of a character expression.
WAIT Command | Display a message and pause Visual FoxPro execution until the user presses a key or clicks the mouse.

See Also

Other Resources

Programming
Language Categories


System Variables

Visual FoxPro 9.0 Language Reference
System Variables
See Also

The following system variables are available in Visual FoxPro.

A

Use | To
_ASCIICOLS | Specify the number of columns in an ASCII text file created with the ASCII keyword in the REPORT FORM command.
_ASCIIROWS | Specify the number of rows in an ASCII text file created with the ASCII keyword in the REPORT FORM command.

B

Use | To
_BEAUTIFY | Specify the beautification application for Visual FoxPro programs.
_BROWSER | Specify the name of the class browser application to use for browsing classes.
_BUILDER | Specify the name of the Visual FoxPro builder application.

C

Use | To
_CALCMEM | Specify the numeric value that Microsoft Visual FoxPro stores in the Calculator's memory.
_CALCVALUE | Specify the numeric value that the Calculator displays initially.
_CLIPTEXT | Specify the contents of the Clipboard.
_CODESENSE | Specify the name of the application that provides functionality for the IntelliSense Manager.
_CONVERTER | Specify the name of the Microsoft Visual FoxPro converter application.
_COVERAGE | Specify the name of the Visual FoxPro application that creates the Debugger coverage and profiler output.

D

Use | To
_DBLCLICK | Specify the time interval between double and triple mouse clicks.
_DIARYDATE | Specify the current date in the Calendar/Diary.
_DOS | Included for backward compatibility.

E

F

Use | To
_FOXCODE | Specify the name of the table file used for Visual FoxPro IntelliSense.
_FOXREF | Specify the name of the application that provides the Code References tool.
_FOXTASK | Specify the name of the FOXTASK table that supports Visual FoxPro Task Manager.

G

Use | To
_GALLERY | Specify the program that is executed when you choose Component Gallery from the Tools menu.
_GENHTML | Specify an HTML (Hypertext Markup Language) generation program.
_GENMENU | Specify a menu generation program.
_GETEXPR | Specify the program that is executed when you issue the GETEXPR command or invoke the Expression Builder dialog box from within Visual FoxPro.

H

I

Use | To
_INCSEEK | Specify the time interval that is open for keystrokes within an incremental seek such as within a Listbox or ComboBox control.
_INCLUDE | Specify a default header file included with user-defined classes, forms, or form sets.

J

K

L

M

Use | To
_MAC | Included for backward compatibility.
_MLINE | Specify the memo field offset for the MLINE( ) function.

N

O

Use | To
_OBJECTBROWSER | Specify the name of the object browser application.

P

Use | To
_PAGENO | Specify the current page number.
_PAGETOTAL | Specify the total number of pages in a report.
_PRETEXT | Specify a character expression to preface text merge lines.

Q

R

Use | To
_REPORTBUILDER System Variable | Set the Visual FoxPro handler application for Report Designer and Label Designer events.
_REPORTOUTPUT System Variable | Set the Visual FoxPro handler application for the OBJECT TYPE <n> clause of the REPORT FORM command, and maintain a registry of ReportListener classes for different output results.
_REPORTPREVIEW System Variable | Set the Visual FoxPro handler application providing a PreviewContainer reference to ReportListener objects.

S

Use | To
_SAMPLES | Specify the path of the directory in which the Microsoft Visual FoxPro samples are installed.
_SCCTEXT | Specify a Visual FoxPro conversion program that handles translating Visual FoxPro binary files into text equivalents and back.
_SCREEN | Specify properties and methods for the main Visual FoxPro window. You can use _SCREEN to manipulate the main Visual FoxPro window as an object. There are two versions of the syntax.
_SHELL | Specify a program shell.
_SPELLCHK | Specify a spelling checker program for the Visual FoxPro text editor.
_STARTUP | Specify the name of the application that runs when you start Visual FoxPro.

T

Use | To
_TASKLIST | Specify the name of the task list manager program.
_TASKPANE | Specify the path and file name for the Visual FoxPro Task Pane Manager.
_TALLY | Specify the number of records processed by the most recently executed table command.
_TEXT | Direct output from the \ | \\ and TEXT ... ENDTEXT text merge commands to a low-level file.
_THROTTLE | Specify the execution speed of programs when the Trace window is open.
_TOOLBOX | Specify the path and file name for the Visual FoxPro Toolbox
_TRIGGERLEVEL | Read the value indicating the current trigger procedure nesting level.

U

Use | To
_UNIX | Included for backward compatibility.

V

Use | To
_VFP | Reference the Application object for the current instance of Visual FoxPro.

W

Use | To
_WINDOWS | Included for backward compatibility.
_WIZARD | Specify the name of the Visual FoxPro wizard application.

X

Y

Z

See Also

Other Resources

Programming
Language Categories


Shared Access to Data

Visual FoxPro 9.0 Language Reference
Shared Access to Data

The commands and functions listed in this section make it possible for you to manage multiple users.

In This Section

Shared Access to Data Commands and Functions

Lists the commands and functions that make it possible for multiple users on a network to share data from tables.
Commands that Scope to a Data Session

Lists the commands that affect only the data session in which they are issued.

Related Sections

Language Categories

Contains a list of language functionality and descriptions.
Using Visual FoxPro

Discusses how Visual FoxPro programming features are designed to improve developer productivity, including Access and Assign methods, support for more graphic file formats, and language to simplify programming tasks.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Shared Access to Data Commands and Functions

Visual FoxPro 9.0 Language Reference
Shared Access to Data Commands and Functions
See Also

These commands and functions make it possible for multiple users on a network to share data from tables.

Use | To
CURSORSETPROP( ) Function | Specify property settings for a Visual FoxPro table or a cursor.
CURVAL( ) Function | Return field values directly from disk for a table or a remote data source.
FLOCK( ) Function | Attempt to lock the current or specified table.
LOCK( ) Function or RLOCK( ) Function | Attempt to lock one or more records in a table.
OLDVAL( ) Function | Return original field values for fields that have been modified but not updated.
SET EXCLUSIVE Command | Open table files for exclusive or shared use on a network.
SET LOCK Command | Enable or disable automatic file locking in certain commands.
SET MULTILOCKS Command | Determine whether you can lock multiple records using LOCK( ) or RLOCK( ).
SET REFRESH Command | To update a browse window or memo editing window, or to refresh local memory buffers with changes from other users on the network.
SET REPROCESS Command | Specify how often and for how long Visual FoxPro attempts to lock a file or record after an unsuccessful locking attempt.
SYS(3051) - Set Lock Retry Interval | Specify the time in milliseconds that Visual FoxPro waits before attempting to lock a record, table, memo, or index file after an unsuccessful locking attempt.
SYS(3052) - Override SET REPROCESS Locking | Specify whether Visual FoxPro uses the SET REPROCESS setting when attempting to lock an index or memo file.
TABLEREVERT( ) Function | Discard changes made to a buffered row or a buffered table or cursor and restores the OLDVAL( ) data for remote cursors and the current disk values for local tables and cursors.
TABLEUPDATE( ) Function | Commit changes made to a buffered row, a buffered table, cursor, or cursor adapter.
UNLOCK Command | Release a record lock, multiple record locks, or a file lock from a table or all open tables.

See Also

Other Resources

Shared Access to Data
Language Categories


Commands that Scope to a Data Session

Visual FoxPro 9.0 Language Reference
Commands that Scope to a Data Session
See Also

These commands affect only the data session in which they are issued.

Use | To
BEGIN TRANSACTION Command | Begin a transaction.
END TRANSACTION Command | End the current transaction and save any changes made to tables, table memo files, or index files included in a transaction.
ROLLBACK Command | Cancel any changes made during the current transaction.
SET ANSI Command | Specify whether to pad a shorter string or binary expression during comparison in SQL commands.
SET AUTOINCERROR Command | Specify whether attempts to update or insert values in a field with automatically incrementing values generate errors.
SET AUTOSAVE Command | Determine whether Visual FoxPro flushes data buffers to disk when you exit a READ or return to the Command window.
SET BLOCKSIZE Command | Specify how Visual FoxPro allocates disk space for the storage of memo fields.
SET CARRY Command | Determine whether Visual FoxPro carries data forward from the current record to a new record created with INSERT, APPEND, and BROWSE.
SET CENTURY Command | Display the century portion of date expressions and determine how to interpret dates that specify only 2 digit years.
SET COLLATE Command | Specify a collation sequence for character fields in subsequent indexing and sorting operations.
SET CONFIRM Command | Specify whether the user can exit a text box by typing past the last character in the text box.
SET CURRENCY Command | Define the currency symbol and specifies its position in the display of numeric, currency, float, and double expressions.
SET DATABASE Command | Specify the current database.
SET DATE Command | Specify the format for the display of Date and DateTime expressions.
SET DECIMALS Command | Specify the number of decimal places displayed in numeric expressions.
SET DELETED Command | Specify whether to process records marked for deletion and whether they are available for use with other commands.
SET EXACT Command | Specify rules to use when comparing two strings of different lengths.
SET EXCLUSIVE Command | Specify whether to open table files for exclusive or shared use on a network.
SET FIELDS Command | Specify which fields in a table can be accessed.
SET FIXED Command | Specify if the number of decimal places used in the display of numeric data is fixed.
SET HOURS Command | Set the system clock to a 12- or 24-hour time format.
SET LOCK Command | Enable or disable automatic file locking in certain commands.
SET MARK TO Command | Specify a delimiter for the display of date expressions.
SET MEMOWIDTH Command | Specify the displayed width of memo fields and character expressions.
SET MULTILOCKS Command | Determine whether you can lock multiple records using LOCK( ) or RLOCK( ).
SET NEAR Command | Determine where the record pointer is positioned after an unsuccessful FIND or SEEK operation.
SET NULL Command | Determine how null values are supported by the ALTER TABLE, CREATE TABLE and INSERT - SQL commands.
SET POINT Command | Determine the decimal point character used in the display of numeric and currency expressions.
SET REFRESH Command | Specify the update interval for a browse window, memo editing window, or local memory buffers changed by other users on the network.
SET REPROCESS Command | Specify how often and for how long Visual FoxPro attempts to lock a file or record after an unsuccessful locking attempt.
SET SAFETY Command | Display a dialog box before overwriting an existing file, or determine whether table or field rules, default values, and error messages are evaluated when changes are made in the Table Designer or with ALTER TABLE.
SET SECONDS Command | Specify whether seconds are displayed in the time portion of a DateTime value.
SET SYSFORMATS Command | Specify whether Visual FoxPro for Windows system settings are updated with the current Microsoft Windows system settings.
SET TALK Command | Determine whether Visual FoxPro displays command results.
SET UNIQUE Command | Specify whether records with duplicate index key values are maintained in an index file.

See Also

Reference

Command Window (Visual FoxPro)
Table Designer (Visual FoxPro)

Other Resources

Shared Access to Data
Language Categories


Visual FoxPro Environment

Visual FoxPro 9.0 Language Reference
Visual FoxPro Environment

The commands and functions listed in this section make it possible for you to access the Microsoft Visual FoxPro environment.

In This Section

Environment

Contains commands and functions that make it possible for you to manage a wide range of Visual FoxPro system and environment parameters.
File Management

Contains commands and functions for managing and manipulating disk files.

Related Sections

Language Categories

Provides a list of language functionality and descriptions.
Using Visual FoxPro

Discusses how Visual FoxPro programming features are designed to improve developer productivity, including Access and Assign methods, support for more graphic file formats, and language to simplify programming tasks.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Environment (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Environment (Visual FoxPro)
See Also

These commands and functions make it possible for you to manage a wide range of Microsoft Visual FoxPro system and environment parameters.

Use | To
ADIR( ) Function | Place information about files into an array and then return the number of files.
ADLLS( ) Function | Return an array containing the names of functions loaded by DECLARE DLLs.
ALANGUAGE( ) Function | Return an array containing the names of all valid Visual FoxPro commands, functions, or base classes.
APROCINFO( ) | Create an array containing Visual FoxPro language elements contained in a program file.
ASESSIONS( ) Function | Create an array of existing data session IDs.
ASTACKINFO( ) Function | Create an array and populate it with information about the current state of the call stack.
_BROWSER System Variable | Specify the name of the class browser application.
_BUILDER System Variable | Specify the name of the Visual FoxPro builder application.
CAPSLOCK( ) Function | Return the current mode of the CAPS LOCK key or sets the CAPS LOCK key mode on or off.
CREATE COLOR SET Command | Create a color set from the current color settings.
CREATE VIEW Command | Create a view file from the Visual FoxPro environment.
CurrentX, CurrentY Properties | Specify the horizontal (X) and vertical (Y) coordinates for the next drawing method. Not available at design time; read/write at run time.
DECLARE - DLL Command | Register a function in an external shared library.
DIR or DIRECTORY Command | Display information about the files in a directory.
DISKSPACE( ) Function | Return the number of bytes available on the default or specified disk drive or volume.
DISPLAY DLLS Command | Display information about shared library functions registered in Visual FoxPro with DECLARE – DLL.
DISPLAY STATUS Command | Display the status of the Visual FoxPro environment.
FKLABEL( ) Function | Return the name of the function key (F1, F2, F3 ...) from the key's corresponding function key number.
FKMAX( ) Function | Return the number of programmable function keys or function key combinations on your keyboard.
FONTMETRIC( ) Function | Return font attributes for the current installed operating system fonts.
_GALLERY System Variable | Specify the program that is executed when you choose Component Gallery from the Tools menu.
_GENHTML System Variable | Specify an HTML (Hypertext Markup Language) generation program.
GETCOLOR( ) Function | Display the Windows Color dialog box and return the color number of the chosen color.
GETCP( ) Function | Prompt for a code page by displaying the Code Page dialog box, and then return the number of the code page chosen.
GETENV( ) Function | Return the contents of the specified MS-DOS environment variable.
_GETEXPR System Variable | Specify the program that is executed when you issue the GETEXPR command or invoke the Expression Builder dialog box from within Visual FoxPro.
GETFILE( ) Function | Display the Open dialog box and return the name of the file you chose.
GETFONT( ) Function | Display the Font dialog box and return information about the font you choose.
GETPEM( ) Function | Return the current value for a property or program code for an event or method at design time.
HOME( ) Function | Return the names of the Visual FoxPro and Visual Studio directories.
HELP Command | Open the Help window.
IMESTATUS( ) Function | Turn the IME (Input Method Editor) window on or off or returns the current IME status.
_INCLUDE System Variable | Specify a default header file included with user-defined classes, forms, or form sets.
INKEY( ) Function | Return a number corresponding to the first mouse click or key press in the type-ahead buffer.
INSMODE( ) Function | Return the current insert mode, or sets the insert mode on or off.
ISCOLOR( ) Function | Determine whether a computer can display color.
ISMOUSE( ) Function | Return true (.T.) if mouse hardware is present.
LIST DLLS Command | Continuously display information about shared library functions registered in Visual FoxPro with DECLARE - DLL.
LIST STATUS Command | Display table or environment information without pausing the main Visual FoxPro or user-defined window. There are multiple versions of the syntax.
LOCFILE( ) Function | Locate a file on disk and return the file name with its path.
MEMORY( ) Function | Return the amount of memory available to run an external program.
MESSAGE( ) Function | Return either the current error message as a character string or the contents of the program line that caused the error.
NUMLOCK( ) Function | Return the current mode of the NUM LOCK key or set the mode of the NUM LOCK key on or off.
_OBJECTBROWSER System Variable | Contain the name of the object browser application.
OBJTOCLIENT( ) Function | Return a position or dimension of a control or object relative to its form.
OS( ) Function | Return the name and version number of the operating system under which Visual FoxPro is running.
PCOL( ) Function | Return the current column position of the printer's print head.
PEMSTATUS( ) Function | Retrieve an attribute for a property, event, method, or object.
PROW( ) Function | Return the current row number of the printer's print head.
PUTFILE( ) Function | Invoke the Save As dialog box and return the file name you specify.
QUIT Command | End the current Visual FoxPro session and return control to the operating system.
RGB( ) Function | Return a single color value from a set of red, green, and blue color components.
SCHEME( ) Function | Return a color pair list or a single color pair from a specified color scheme.
_SCREEN System Variable | Specify properties and methods for the main Visual FoxPro window.
SET( ) Function | Return the status of various SET commands.
SET Commands | Open the Data Session window. The Data Session window provides an easy way to open tables, establish relations, or set or change many Visual FoxPro options.
SYS(3) - Legal File Name | Return a legal file name that can be used to create temporary files.
SYS(5) - Default Drive | Return the current Visual FoxPro default drive.
SYS(6) - Current Printer Device | Return the current Visual FoxPro default drive.
SYS(7) - Current Format File | Return the name of the current format file.
SYS(9) - Visual FoxPro Serial Number | Return your Visual FoxPro serial number.
SYS(12) - Available Memory in Bytes | Return the amount of memory below 640K that is available to execute an external program.
SYS(16) - Executing Program File Name | Return the file name of the program being executed. You can use SYS(16) to recover from errors.
SYS(17) - Processor in Use | Return the central processing unit (CPU) being used.
SYS(1001) - Visual FoxPro Memory | Return the total amount of memory available to the Visual FoxPro memory manager.
SYS(1016) - User Object Memory Use | Return amount of memory being used by objects you define.
SYS(1023) - Enable Help Diagnostic Mode | Enable the Help diagnostic mode, making it possible for you to trap the HelpContextID passed to the Visual FoxPro Help system.
SYS(1024) - Disable Help Diagnostic Mode | Disable the Help diagnostic mode enabled by issuing SYS(1023).
SYS(1269) - Property Information | Return a value that indicates whether a property setting has changed from its default setting or whether the property is read-only.
SYS(1270) - Object Location | Return a reference for an object at the specified point.
SYS(1271) - Object's .SCX File | Return the name of the .SCX file in which the specified instantiated object is stored.
SYS(1272) - Object Hierarchy | Return the object hierarchy for a specified object. Not available at design time.
SYS(2001) - SET ... Command Status | Return the status of the specified SET commands.
SYS(2003) - Current Directory | Return the name of the current directory on the default drive.
SYS(2004) - Visual FoxPro Start Directory | Return the name of the directory from which Visual FoxPro was started.
SYS(2005) - Current Resource File | Return the name of the current Visual FoxPro resource file.
SYS(2006) - Current Graphics Card | Return the type of graphics card and monitor you are using.
SYS(2010) - CONFIG.SYS File Settings | Return the files setting in CONFIG.SYS.
SYS(2013) - System Menu Name String | Return a space-delimited character string containing the internal names of the Visual FoxPro menu system.
SYS(2019) - Configuration File Name and Location | Return the name and location of the Visual FoxPro configuration file.
SYS(2020) - Default Disk Size | Return the free space in bytes on the default disk.
SYS(2022) - Disk Cluster (Block) Size | Return the cluster size in bytes of a specified disk.
SYS(2023) - Temporary File Drive | Return the path in which Visual FoxPro stores its temporary files.
SYS(2334) – Automation Server Invocation Mode | Return a value indicating how a Visual FoxPro automation server method was invoked.
SYS(2800) – Accesibility Support | Disable or enable Microsoft Active Accessibility support and set certain options to track the keyboard focus of the currently selected control in a Visual FoxPro form.
SYS(3004) - Return Locale ID | Return the Locale ID used by automation and ActiveX controls.
SYS(3005) - Set Locale ID | Set the Locale ID used by automation and ActiveX controls.
SYS(3006) - Set Language and Locale IDs | Set the Language ID and the Locale ID.
SYS(3050) - Set Buffer Memory Size | Set the foreground or background buffer memory size.
SYS(3053) - ODBC Environment Handle | Return the ODBC environment handle.
SYS(3056) – Read Registry Settings | Read Visual FoxPro registry settings and update with the current registry settings.
SYS(3095) – IDispatch Pointer | Return an outgoing IDispatch pointer for a COM object.
SYSMETRIC( ) Function | Return the size of the operating system's screen elements.
_TASKLIST System Variable | Contains the name of the task list manager program.
TXTWIDTH( ) Function | Return the length of a character expression with respect to the average character width for a font.
VERSION( ) Function | Return information about the Visual FoxPro version you are using.
WFONT( ) Function | Return the name, size, or style of the current font for a window in Visual FoxPro for Windows.
_WIZARD System Variable | Contain the name of the Visual FoxPro wizard application.

See Also

Other Resources

Visual FoxPro Environment
Customizing the Visual FoxPro Environment
Language Categories


File Management

Visual FoxPro 9.0 Language Reference
File Management
See Also

These commands and functions manage and manipulate disk files.

Use | To
ADDBS( ) Function | Add a backslash to a path expression.
ADIR( ) Function | Place information about files into an array and then return the number of files.
CD | CHDIR Command | Change the default Visual FoxPro directory to the directory you specify.
CLOSE Commands | Close various file types.
COPY FILE Command | Duplicate any type of file.
CREATE VIEW Command | Create a view file from the Visual FoxPro environment.
CURDIR( ) Function | Return the current directory.
DEFAULTEXT( ) Function | Return a file name with a new extension if one does not already exist.
DELETE FILE Command | Delete a file from a disk.
DIR or DIRECTORY Command | Display information about the files in a directory.
DISPLAY FILES Command | Display information about files.
DISKSPACE( ) Function | Return the number of bytes available on the default or specified disk drive or volume.
DO Command | Execute a Visual FoxPro program or procedure.
DRIVETYPE( ) Function | Return the type of the specified drive.
EDITSOURCE( ) Function | Open the Visual FoxPro editor and, optionally positions the cursor.
ERASE Command | Erase a file from disk.
FDATE( ) Function | Return the last modification Date or DateTime for a file.
FTIME( ) Function | Return the last modification time for a file.
FILE( ) Function | Locate the specified file.
FILETOSTR( ) Function | Return the contents of a file as a character string.
FLUSH Command | Save table and index changes to disk.
FORCEEXT( ) Function | Return a string with the old file name extension replaced by a new extension.
FORCEPATH( ) Function | Return a file name with a new path name substituted for the old one.
FULLPATH( ) Function | Return the path to a specified file or the path relative to another file.
GETFILE( ) Function | Display the Open dialog box and returns the name of the file you chose.
GETPICT( ) Function | Display the Open Picture dialog box and return the name of the picture file you chose.
ISNULL( ) Function | Return true (.T.) if an expression evaluates to a null value; otherwise, ISNULL( ) returns false (.F.).
JUSTDRIVE( ) Function | Return the drive letter from a complete path.
JUSTEXT( ) Function | Return the file name portion of a complete path and file name.
JUSTFNAME( ) Function | Return the file name portion of a complete path and file name.
JUSTPATH( ) Function | Return the path portion of a complete path and file name.
JUSTSTEM( ) Function | Return the stem name (the file name before the extension) from a complete path and file name.
LIST FILES Command | Display table or environment information without pausing the main Visual FoxPro or user-defined window.
LOCFILE( ) Function | Locate a file on disk and returns the file name with its path.
MD | MKDIR Command | Create a new directory or subdirectory on disk.
MODIFY COMMAND Command | Open an editing window so you can modify or create a program file.
MODIFY FILE Command | Open an editing window so you can modify or create a text file.
NVL( ) Function | Return a non-null value from two expressions.
OPEN DATABASE Command | Opens a database.
PUTFILE( ) Function | Invoke the Save As dialog box and return the file name you specify.
RD | RMDIR Command | Remove a directory or folder from disk.
RENAME Command | Change the name of a file to a new name.
SET ALTERNATE Commands | Direct screen or printer output created with ?, ??, DISPLAY, or LIST to a text file.
SET DEFAULT Command | Specify the default drive and directory.
SET FULLPATH Command | Specify if CDX( ), DBF( ), MDX( ), and NDX( ) return the path in a file name.
SET PATH Command | Specify a path for file searches.
SET SAFETY Command | Display a dialog box before overwriting an existing file, or evaluate table or field rules, default values, and error messages when changes are made in the Table Designer or with ALTER TABLE.
SET VIEW Command | Open or close the Data Session window or restores the Visual FoxPro environment from a view file.
STRTOFILE( ) Function | Write the contents of a character string to a file.
SYS(3) - Legal File Name | Return a legal file name that can be used to create temporary files.
SYS(2000) - File Name Wildcard Match | Return the name of the first file in alphabetic order by file name and extension, that matches a file name skeleton.
SYS(2014) - Minimum Path | Returns the minimum path relative to the current or specified directory for a specified file.
TYPE Command | Display the contents of a file.

See Also

Other Resources

Visual FoxPro Environment
Language Categories


Commands (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Commands (Visual FoxPro)
See Also

Supported Visual FoxPro Commands and Functions in OLE DB Provider

Unsupported Visual FoxPro Commands and Functions in OLE DB Provider

For information about backward compatible-only language reference, see Backward-Compatible Language Elements.

& Command

&& Command

* Command

= Command

? | ?? Command

??? Command

@ ... BOX Command

@ ... CLASS Command

@ ... CLEAR Command

@ ... EDIT - Edit Boxes Command

@ ... FILL Command

@ ... GET - Check Boxes Command

@ ... GET - Combo Boxes Command

@ ... GET - Command Buttons Command

@ ... GET - List Boxes Command

@ ... GET - Option Buttons Command

@ ... GET - Spinners Command

@ ... GET - Text Boxes Command

@ ... GET - Transparent Buttons Command

@ ... MENU Command

@ ... PROMPT Command

@ ... SAY - Pictures & OLE Objects Command

@ ... SAY Command

@ ... SCROLL Command

@ ... TO Command

\ | \\ Command

ACTIVATE MENU Command

ACTIVATE POPUP Command

ACTIVATE SCREEN Command

ACTIVATE WINDOW Command

ADD CLASS Command

ADD TABLE Command

ALTER TABLE – SQL Command

APPEND Command

APPEND FROM ARRAY Command

APPEND FROM Command

APPEND GENERAL Command

APPEND MEMO Command

APPEND PROCEDURES Command

ASSERT Command

ASSIST Command

AVERAGE Command

BEGIN TRANSACTION Command

BLANK Command

BROWSE Command

BUILD APP Command

BUILD DLL Command

BUILD EXE Command

BUILD MTDLL Command

BUILD PROJECT Command

CALCULATE Command

CALL Command

CANCEL Command

CD | CHDIR Command

CHANGE Command

CLEAR Commands

CLOSE Commands

CLOSE MEMO Command

COMPILE Command

CONTINUE Command

COPY FILE Command

COPY INDEXES Command

COPY MEMO Command

COPY PROCEDURES Command

COPY STRUCTURE Command

COPY STRUCTURE EXTENDED Command

COPY TAG Command

COPY TO ARRAY Command

COPY TO Command

COUNT Command

CREATE CLASS Command

CREATE CLASSLIB Command

CREATE COLOR SET Command

CREATE Command

CREATE CONNECTION Command

CREATE CURSOR – SQL Command

CREATE DATABASE Command

CREATE FORM Command

CREATE FROM Command

CREATE LABEL Command

CREATE MENU Command

CREATE PROJECT Command

CREATE QUERY Command

CREATE REPORT – Quick Report Command

CREATE REPORT Command

CREATE SCREEN – Quick Screen Command

CREATE SCREEN Command

CREATE SQL VIEW Command

CREATE TABLE – SQL Command

CREATE TRIGGER Command

CREATE VIEW Command

DEACTIVATE MENU Command

DEACTIVATE POPUP Command

DEACTIVATE WINDOW Command

DEBUG Command

DEBUGOUT Command

DECLARE - DLL Command

DECLARE Command

DEFINE BAR Command

DEFINE BOX Command

DEFINE CLASS Command

DEFINE MENU Command

DEFINE PAD Command

DEFINE POPUP Command

DEFINE WINDOW Command

DELETE - SQL Command

DELETE Command

DELETE CONNECTION Command

DELETE DATABASE Command

DELETE FILE Command

DELETE TAG Command

DELETE TRIGGER Command

DELETE VIEW Command

DIMENSION Command

DIR or DIRECTORY Command

DISPLAY Command

DISPLAY CONNECTIONS Command

DISPLAY DATABASE Command

DISPLAY DLLS Command

DISPLAY FILES Command

DISPLAY MEMORY Command

DISPLAY OBJECTS Command

DISPLAY PROCEDURES Command

DISPLAY STATUS Command

DISPLAY STRUCTURE Command

DISPLAY TABLES Command

DISPLAY VIEWS Command

DO CASE ... ENDCASE Command

DO Command

DO FORM Command

DO WHILE ... ENDDO Command

DOCK Command

DOEVENTS Command

DROP TABLE Command

DROP VIEW Command

EDIT Command

EJECT Command

EJECT PAGE Command

END TRANSACTION Command

ERASE Command

ERROR Command

EXIT Command

EXPORT Command

EXTERNAL Command

FIND Command

FLUSH Command

FOR EACH ... ENDFOR Command

FOR ... ENDFOR Command

FREE TABLE Command

FUNCTION Command

GATHER Command

GETEXPR Command

GO | GOTO Command

HELP Command

HIDE MENU Command

HIDE POPUP Command

HIDE WINDOW Command

IF ... ENDIF Command

IMPORT Command

INDEX Command

INPUT Command

INSERT – SQL Command

INSERT Command

JOIN Command

KEYBOARD Command

LABEL Command

LIST Commands

LIST CONNECTIONS Command

LIST DATABASE Command

LIST DLLS Command

LIST OBJECTS Command

LIST PROCEDURES Command

LIST TABLES Command

LIST VIEWS Command

LOAD Command

LOCAL Command

LOCATE Command

LOOP Command

LPARAMETERS Command

MD | MKDIR Command

MENU Command

MENU TO Command

MODIFY CLASS Command

MODIFY COMMAND Command

MODIFY CONNECTION Command

MODIFY DATABASE Command

MODIFY FILE Command

MODIFY FORM Command

MODIFY GENERAL Command

MODIFY LABEL Command

MODIFY MEMO Command

MODIFY MENU Command

MODIFY PROCEDURE Command

MODIFY PROJECT Command

MODIFY QUERY Command

MODIFY REPORT Command

MODIFY SCREEN Command

MODIFY STRUCTURE Command

MODIFY VIEW Command

MODIFY WINDOW Command

MOUSE Command

MOVE POPUP Command

MOVE WINDOW Command

NOTE Command

ON BAR Command

ON ERROR Command

ON ESCAPE Command

ON EXIT BAR Command

ON EXIT MENU Command

ON EXIT PAD Command

ON EXIT POPUP Command

ON KEY = Command

ON KEY Command

ON KEY LABEL Command

ON PAD Command

ON PAGE Command

ON READERROR Command

ON SELECTION BAR Command

ON SELECTION MENU Command

ON SELECTION PAD Command

ON SELECTION POPUP Command

ON SHUTDOWN Command

OPEN DATABASE Command

PACK Command

PACK DATABASE Command

PARAMETERS Command

PLAY MACRO Command

POP KEY Command

POP MENU Command

POP POPUP Command

PRINTJOB ... ENDPRINTJOB Command

PRIVATE Command

PROCEDURE Command

PUBLIC Command

PUSH KEY Command

PUSH MENU Command

PUSH POPUP Command

QUIT Command

RD | RMDIR Command

READ Command

READ EVENTS Command

READ MENU Command

RECALL Command

REINDEX Command

RELEASE BAR Command

RELEASE CLASSLIB Command

RELEASE Command

RELEASE LIBRARY Command

RELEASE MENUS Command

RELEASE PAD Command

RELEASE POPUPS Command

RELEASE PROCEDURE Command

RELEASE WINDOWS Command

REMOVE CLASS Command

REMOVE TABLE Command

RENAME CLASS Command

RENAME Command

RENAME CONNECTION Command

RENAME TABLE Command

RENAME VIEW Command

REPLACE Command

REPLACE FROM ARRAY Command

REPORT Command

RESTORE FROM Command

RESTORE MACROS Command

RESTORE SCREEN Command

RESTORE WINDOW Command

RESUME Command

RETRY Command

RETURN Command

ROLLBACK Command

RUN | ! Command

SAVE MACROS Command

SAVE SCREEN Command

SAVE TO Command

SAVE WINDOWS Command

SCAN ... ENDSCAN Command

SCATTER Command

SCROLL Command

SEEK Command

SELECT - SQL Command

SELECT Command

SET ALTERNATE Command

SET ANSI Command

SET ASSERTS Command

SET AUTOINCERROR Command

SET AUTOSAVE Command

SET BELL Command

SET BLOCKSIZE Command

SET BORDER Command

SET BROWSEIME Command

SET BRSTATUS Command

SET CARRY Command

SET CENTURY Command

SET CLASSLIB Command

SET CLEAR Command

SET CLOCK Command

SET COLLATE Command

SET COLOR OF Command

SET COLOR OF SCHEME Command

SET COLOR SET Command

SET COLOR TO Command

SET Command

SET COMPATIBLE Command

SET CONFIRM Command

SET CONSOLE Command

SET COVERAGE Command

SET CPCOMPILE Command

SET CPDIALOG Command

SET CURRENCY Command

SET CURSOR Command

SET DATABASE Command

SET DATASESSION Command

SET DATE Command

SET DEBUG Command

SET DEBUGOUT Command

SET DECIMALS Command

SET DEFAULT Command

SET DELETED Command

SET DELIMITERS Command

SET DEVELOPMENT Command

SET DEVICE Command

SET DISPLAY Command

SET DOHISTORY Command

SET ECHO Command

SET ENGINEBEHAVIOR Command

SET ESCAPE Command

SET EVENTLIST Command

SET EVENTTRACKING Command

SET EXACT Command

SET EXCLUSIVE Command

SET FDOW Command

SET FIELDS Command

SET FILTER Command

SET FIXED Command

SET FORMAT Command

SET FULLPATH Command

SET FUNCTION Command

SET FWEEK Command

SET HEADINGS Command

SET HELP Command

SET HOURS Command

SET INDEX Command

SET INTENSITY Command

SET KEY Command

SET KEYCOMP Command

SET LIBRARY Command

SET LOCK Command

SET LOGERRORS Command

SET MACKEY Command

SET MARGIN Command

SET MARK OF Command

SET MARK TO Command

SET MEMOWIDTH Command

SET MESSAGE Command

SET MULTILOCKS Command

SET NEAR Command

SET NOCPTRANS Command

SET NOTIFY Command

SET NULL Command

SET NULLDISPLAY Command

SET ODOMETER Command

SET OLEOBJECT Command

SET OPTIMIZE Command

SET ORDER Command

SET PALETTE Command

SET PATH Command

SET PDSETUP Command

SET POINT Command

SET PRINTER Command

SET PROCEDURE Command

SET READBORDER Command

SET REFRESH Command

SET RELATION Command

SET RELATION OFF Command

SET REPROCESS Command

SET RESOURCE Command

SET SAFETY Command

SET SECONDS Command

SET SEPARATOR Command

SET SKIP Command

SET SKIP OF Command

SET SPACE Command

SET STATUS BAR Command

SET STATUS Command

SET STEP Command

SET STRICTDATE Command

SET SYSFORMATS Command

SET SYSMENU Command

SET TABLEVALIDATE Command

SET TALK Command

SET TEXTMERGE Command

SET TEXTMERGE DELIMITERS Command

SET TOPIC Command

SET TOPIC ID Command

SET TRBETWEEN Command

SET TYPEAHEAD Command

SET UDFPARMS Command

SET UNIQUE Command

SET VIEW Command

SET WINDOW OF MEMO Command

SHOW GET Command

SHOW GETS Command

SHOW MENU Command

SHOW OBJECT Command

SHOW POPUP Command

SHOW WINDOW Command

SIZE POPUP Command

SIZE WINDOW Command

SKIP Command

SORT Command

STORE Command

SUM Command

SUSPEND Command

SYS(2001) – SET ... Command Status

TEXT ... ENDTEXT Command

TOTAL Command

TRY...CATCH...FINALLY Command

TYPE Command

UNLOCK Command

UPDATE - SQL Command

UPDATE Command

USE Command

VALIDATE DATABASE Command

WAIT Command

WITH ... ENDWITH Command

ZAP Command

ZOOM WINDOW Command

See Also

Other Resources

Language Reference


& Command

Visual FoxPro 9.0 Language Reference
& Command
See Also Example

Performs macro substitution.

& VarName[.cExpression]

Parameters

& VarName

Specifies the name of the variable or array element to reference in the macro substitution. Do not include the M. prefix that distinguishes variables from fields. Such inclusion causes a syntax error. The macro should not exceed the maximum statement length permitted in Visual FoxPro. A variable cannot reference itself recursively in macro substitution. For example, the following generates an error message:
Copy Code
STORE '&gcX' TO gcX
? &gcX
Macro substitution statements that appear in DO WHILE, FOR, and SCAN are evaluated only at the start of the loop and are not reevaluated on subsequent iterations. Any changes to the variable or array element that occur within the loop are not recognized.
[. cExpression]

The optional period (.) delimiter and .cExpression are used to append additional characters to a macro. cExpression appended to the macro with .cExpression can also be a macro. If cExpression is a property name, include an extra period (cExpression..PropertyName).

Remarks

Macro substitution treats the contents of a variable or array element as a character string literal. When an ampersand (&) precedes a character-type variable or array element, the contents of the variable or element replace the macro reference. You can use macro substitution in any command or function that accepts a character string literal.

Tip:
Whenever possible, use a name expression instead of macro substitution. A name expression operates like macro substitution. However, a name expression is limited to passing character strings as names. Use a name expression for significantly faster processing if a command or function accepts a name (a file name, window name, menu name, and so on). For additional information on name expressions, see Name Expression Creation.

While the following commands are acceptable:

Copy Code
STORE 'customer' TO gcTableName
STORE 'company'  TO gcTagName
USE &gcTableName ORDER &gcTagName

use a name expression instead:

Copy Code
USE (gcTableName) ORDER (gcTagName)

Macro substitution is useful for substituting a keyword in a command. In the following example, the TALK setting is saved to a variable so the setting can be restored later in the program. The original TALK setting is restored with macro substitution.

Note:
Performing concatenation with a single ampersand (&) when attempting to include double ampersands (&&) in a string literal might produce undesirable results. For example, suppose you assign the string "YYY" to a variable, BBB. Performing concatenation using "AAA&" and "&BBB" replaces "BBB" with "YYY" so instead of getting the result "AAA&&BBB", the result is "AAA&YYY". For more information, see && Command.

Example

Copy Code
STORE SET('TALK') TO gcSaveTalk
SET TALK OFF
*
*  Additional program code
*
SET TALK &gcSaveTalk  && Restore original TALK setting

See Also

Other Resources

Commands
STORE Command
&& Command
Macro Substitution


&& Command

Visual FoxPro 9.0 Language Reference
&& Command
See Also Example

Indicates the beginning of a nonexecuting inline comment in a program file.

&& [Comments]

Parameters

&& [ Comments]

Specifies inline comments that follow.

Remarks

Inserting inline comments to denote the end of the IF ... ENDIF, DO, and FOR ... ENDFOR structured programming commands greatly improves the readability of programs when including many such structures.

Caution:
Including double ampersands (&&) in a string literal, for example, "AAA&&BBB", generates an error. Instead, to include double ampersands, use concatenation as shown: "AAA&" + "&" + "BBB".

Note:
When using concatenation, use caution with placement of a single ampersand (&), which is used to perform macro substitution and thus might produce undesirable results. For example, suppose you assign the string "YYY" to a variable, BBB. Performing concatenation using "AAA&" and "&BBB" replaces "BBB" with "YYY", so instead of getting the result "AAA&&BBB", the result is "AAA&YYY". For more information, see & Command.

To continue a comment on the following line, place a semicolon (;) at the end of the comment line to be continued.

Note:
In earlier versions of Visual FoxPro, you cannot place && and a comment after the semicolon that is used to continue a command line to an additional line.

Example

The following example includes the inline comments "20 years of monthly payments" indicated by the && command:

Copy Code
STORE (20*12) TO gnPayments  && 20 years of monthly payments
Copy Code
NOTE  Initialize the page number;
   variable.
STORE 1 to gnPageNum
* Set up the loop
DO WHILE gnPageNum <= 25  && loop 25 times
   gnPageNum = gnPageNum + 1
ENDDO  && DO WHILE gnPageNum <= 25

See Also

Other Resources

* Command
MODIFY COMMAND Command
MODIFY FILE Command
NOTE Command
& Command
Commands


* Command

Visual FoxPro 9.0 Language Reference
* Command
See Also Example

Indicates the beginning of a nonexecuting comment line in a program file.

* [Comments]

Parameters

Comments

Specifies the comment in the comment line. For example:
Copy Code
*   This is a comment

Remarks

Place a semicolon (;) at the end of each comment line that continues to a following line.

Any text added to a method or event in a Visual Class Library (VCX) or form (SCX) Code window will cause that class to have Override behavior for the method or event. Therefore, code for the method or event in a parent class will not be executed by default (it must be explicitly executed). This includes non-executable comment lines that begin with "*".

Example

Copy Code
* Initialize the page number;
   variable.
STORE 1 to gnPageNum
* Set up the loop
DO WHILE gnPageNum <= 25  && loop 25 times
   gnPageNum = gnPageNum + 1
ENDDO  && DO WHILE gnPageNum <= 25

See Also

Concepts

Overriding and Calling Parent Class Code

Other Resources

&& Command
MODIFY COMMAND Command
MODIFY FILE Command
NOTE Command
Commands


? | ?? Command

Visual FoxPro 9.0 Language Reference
? | ?? Command
See Also Example

Evaluates expressions and sends the results to the main Visual FoxPro window, an active user-defined window, or the printer.

? | ?? Expression1 [PICTURE cFormatCodes] | [FUNCTION cFormatCodes] |
   [VnWidth] [AT nColumn]
   [FONT cFontName [, nFontSize [, nFontCharSet]] [STYLE cFontStyle | Expression2]]
   [, Expression3] ...

Parameters

? Expression1

Evaluates the expression specified by Expression1 and sends a carriage return and line feed preceding the expression results. The results display on the next line of the main Visual FoxPro window or the active user-defined window and are printed at the left margin of a page unless a function code specified by cFormatCodes or the _ALIGNMENT system variable specifies otherwise. If you omit the expressions, a blank line is displayed or printed. A space is placed between expression results when multiple expressions are included. If Expression1 is an object, the ? command returns the character string, "(Object)".
?? Expression1

Evaluates the expression specified by Expression1 and displays the expression results on the current line at the current position of the main Visual FoxPro window, an active user-defined window, or the printer. A carriage return and line feed are not sent before the results.
PICTURE cFormatCodes

Specifies a picture format in which the result of Expression1 is displayed. cFormatCodes can consist of function codes, picture codes, or a combination of both. You can use the same codes available in the Format Property and InputMask Property. Function codes affect the overall format of the result; picture codes act on individual characters in the result. If function codes are used in cFormatCodes, they must appear before the picture codes and they must be preceded by an at (@) sign. Multiple function codes with no embedded spaces can immediately follow the @ sign. The last function code must be followed by one or more spaces. The space or spaces signal the end of the function codes and the start of the picture codes.
FUNCTION cFormatCodes

Specifies a function code to include in the output from the ? and ?? commands. If the function clause is included, do not precede the function codes with an @ sign. Function codes must be preceded by a @ sign when included in PICTURE.
V nWidth

Specifies a special function code that enables the results of a character expression to stretch vertically within a limited number of columns. nWidth specifies the number of columns in the output.
Copy Code
? 'This is an example of how the V function code works.' ;
   FUNCTION 'V10'
AT nColumn

Specifies the column number where the output is displayed. This option makes it possible for you to align output in columns to create a table. The numeric expression nColumn can be a user-defined function that returns a numeric value.
FONT cFontName[, nFontSize [, nFontCharSet]]

Specifies a font for output by the ? or ?? command. cFontName specifies the name of the font, and nFontSize specifies the point size. You can specify a language script with nFontCharSet. See the GETFONT( ) Function for a list of available language script values. For example, the following command displays the system date in 16-point Courier font:
Copy Code
? DATE( ) FONT 'Courier',16
If you include the FONT clause but omit the point size nFontSize, a 10-point font is used. If you omit the FONT clause, and output for the ? or ?? command is placed in the main Visual FoxPro window, the main Visual FoxPro window font is used for the output. If you omit the FONT clause, and output for the ? or ?? command is placed in a user-defined window, the user-defined window font is used for the output.
Note:
If the font you specify is not available, a font with similar font characteristics is substituted.

STYLE cFontStyle

Specifies a font style for output by the ? or ?? commands. If you omit the STYLE clause, the Normal font style is used. If the font style you specify is not available, a font style with similar characteristics is substituted.
Note:
You must include the FONT clause when you specify a font style with the STYLE clause.

The following table lists font styles that you can specify for cFontStyle.

cFontStyle Font style

B

Bold

I

Italic

N

Normal

Q

Opaque

-

Strikeout

T

Transparent

U

Underline
You can include more than one character to specify a combination of font styles. For example, the following command displays the system date in Courier Bold Italic:
Copy Code
? DATE( ) FONT 'COURIER' STYLE 'BI'

Remarks

To send the results to the printer only, use the following commands:

Copy Code
SET PRINTER ON
SET CONSOLE OFF

To send the results to the printer and the main Visual FoxPro window or an active user-defined window, use the following command:

Copy Code
SET PRINTER ON

The setting of SET ALTERNATE affects the destination for the ? and ?? commands. For more information, see SET ALTERNATE Command.

The ? command displays binary data for Varbinary data types in hexadecimal format with no limitation on size. For more information, see Varbinary Data Type.

Example

The following example displays evaluates and displays the expressions specified:
Copy Code
? 15 * (10+10)
? 'Welcome to ' PICTURE '@!'
?? 'Visual FoxPro'

See Also

Reference

??? Command
SET MEMOWIDTH Command

Other Resources

Commands
@ ... SAY Command
_ALIGNMENT System Variable
SET PRINTER Command
SET SPACE Command
Format Property
InputMask Property


??? Command

Visual FoxPro 9.0 Language Reference
??? Command
See Also

Sends output directly to the printer.

??? cExpression

Parameters

cExpression

Specifies the characters that are sent to the printer.

Remarks

A group of three question marks bypasses the printer driver and sends the contents of cExpression directly to the printer. cExpression must contain valid printer codes.

Printer control codes make it possible for you to reset the printer, change type styles and sizes, and enable or disable boldface printing. These codes can consist of any combination of printable or nonprintable characters that are specific to the printer you are using. You can direct control codes to the printer in several different ways:

  • Use combinations of CHR( ) and quoted strings concatenated with + to send ASCII characters directly to the printer.

  • Use quotation marks to send a string containing printer codes or ASCII characters.

  • Codes can be sent to the printer before printing begins and after printing ends with the _PSCODE and _PECODE system variables. For more information, see _PSCODE System Variable and _PECODE System Variable.

Printer control codes vary from printer to printer. The best source for information about printer control codes is the manual that came with your printer.

See Also

Other Resources

? | ?? Command?
@ ... SAY Command
CHR( ) Function
Print Dialog Box
Commands


@ ... CLASS Command

Visual FoxPro 9.0 Language Reference
@ ... CLASS Command
See Also Example

Creates a control or object that can be activated with READ.

@ nRow, nColumn CLASS ClassName NAME ObjectName

Parameters

@ nRow, nColumn

Specifies the position of the control or object. The height and width of the control or object is determined by the class default height and width values. Rows are numbered from top to bottom. The first row is number 0 in the main Visual FoxPro window or in a user-defined window. Row 0 is the row immediately beneath the Visual FoxPro system menu bar. Columns are numbered from left to right. The first column is number 0 in the main Microsoft Visual FoxPro window or in a user-defined window. When a control or object is placed in a user-defined window, the row and column coordinates are relative to the user-defined window, not to the main Visual FoxPro window. A position in the main Visual FoxPro window or in a user-defined window is determined by the font of the window. Most fonts can be displayed in a wide variety of sizes; some are proportionally spaced. A row corresponds to the height of the current font; a column corresponds to the average width of a letter in the current font. You can position the control or object using decimal fractions for row and column coordinates.
CLASS ClassName

Specifies the class of the control or object. ClassName can be a Visual FoxPro base class or a user-defined class. The following table lists the Visual FoxPro base classes you can specify for ClassName.
NAME ObjectName

Specifies the name of the object reference variable to create. The object-oriented properties, events, and methods of the control or object can be manipulated by referencing this variable. For a complete list of the Visual FoxPro base classes, see Base Classes in Visual FoxPro.

Remarks

@ ... CLASS provides an intermediate step for converting programs and applications created in earlier versions of FoxPro to the preferred object-oriented programming methods of Visual FoxPro. For additional information about backward compatibility with FoxPro 2.x controls, see Controls and Objects Created in Earlier Versions.

For information about object-oriented programming in Visual FoxPro, see Object-Oriented Programming.

Example

The following example demonstrates how @ ... CLASS can be used with programming techniques used in earlier FoxPro versions (in this example, use of READ to activate controls). @ ... CLASS is used to create a text box whose properties can be changed with the Visual FoxPro object-oriented programming techniques.

ON KEY LABEL is used to display the Windows Color dialog box when you press CTRL+I. The TextBox is placed on the main Visual FoxPro window using @ ... CLASS, and READ activates the text box.
Copy Code
CLEAR
ON KEY LABEL CTRL+I _SCREEN.PageFrame1.Page1.goFirstName.BackColor;
    = GETCOLOR( )
@ 2,2 SAY 'Press Ctrl+I to change the background color'

@ 4,2 CLASS TextBox NAME goFirstName
READ
CLEAR

See Also

Other Resources

Commands
CREATEOBJECT( ) Function
DEFINE CLASS Command
READ Command
_SCREEN System Variable


@ ... CLEAR Command

Visual FoxPro 9.0 Language Reference
@ ... CLEAR Command
See Also Example

Clears a portion of the main Visual FoxPro window or a user-defined window.

@ nRow1, nColumn1 [CLEAR
CLEAR TO nRow2, nColumn2]

Parameters

@ nRow1, nColumn1 CLEAR

Clears a rectangular area whose upper-left corner begins at nRow1 and nColumn1 and continues to the lower-right corner of the main Visual FoxPro window or a user-defined window.
CLEAR TO nRow2, nColumn2

Clears a rectangular area whose upper-left corner is at nRow1 and nColumn1 and whose lower-right corner is at nRow2 and nColumn2.

Remarks

If you omit CLEAR or CLEAR TO, Visual FoxPro clears nRow1 from nColumn1 to the end of the row.

Example

The following example clears the screen, main Visual FoxPro window, or user-defined window from the second row to the bottom of the window.

Copy Code
@ 2,0 CLEAR

The following example clears a rectangular region. The area from row 10 and column 0 to row 20 and column 20 is cleared.

Copy Code
@ 10,0 CLEAR TO 20,20

See Also

Other Resources

Commands
CLEAR Commands
SET CLEAR Command
_WClear( ) API Library Routine


@ ... FILL Command

Visual FoxPro 9.0 Language Reference
@ ... FILL Command
See Also Example

Changes the colors of existing text within an area of the screen.

@ nRow1, nColumn1 FILL TO nRow2,
  nColumn2[COLOR SCHEME nSchemeNumber
COLOR ColorPairList]

Parameters

@ nRow1, nColumn1

Specifies the upper-left corner of the area to change.
FILL TO nRow2, nColumn2

Specifies the lower-right corner of the area to change.
COLOR SCHEME nSchemeNumber

Specifies the color of the area. Only the first color pair in the specified color scheme determines the color of the area.
COLOR ColorPairList

Specifies the color of the area. Only the first color pair in the specified color pair list determines the color of the area. If you omit the COLOR SCHEME or COLOR clauses, the rectangular portion is cleared. An area can also be cleared with @ ... CLEAR.

Remarks

This command changes the colors of text within a rectangular area of the main Visual FoxPro window or the active user-defined window. You can set the foreground and background color attributes for existing text only. Any text output to the same area after you issue @ ... FILL appears in the default screen or window colors.

Example

The following example clears the main Visual FoxPro window and fills an area with color.
Copy Code
ACTIVATE SCREEN
CLEAR
@ 4,1 FILL TO 10, 8 COLOR GR+/B

See Also

Other Resources

Commands
@ ... SAY Command
ColorScheme Property
FillColor Property


@ ... SCROLL Command

Visual FoxPro 9.0 Language Reference
@ ... SCROLL Command
See Also

Moves an area of the main Microsoft Visual FoxPro window or a user-defined window up, down, left, or right.

@ nRow1, nColumn1 TO nRow2, nColumn2 SCROLL
[UP | DOWN | LEFT | RIGHT]   [BY nMoveAmount]

Parameters

@ nRow1, nColumn1 TO nRow2, nColumn2 SCROLL

Moves a rectangular area whose upper-left corner is at nRow1, nColumn1 and lower-right corner is at nRow2, nColumn2.
UP | DOWN | LEFT | RIGHT

Specifies the direction in which rectangular area is moved. If you omit a direction clause, the area is moved upward.
BY nMoveAmount

Specifies the number of rows or columns the rectangular area is moved. If you omit BY nMoveAmount, the region is moved by one row or column.

See Also

Other Resources

Commands
SCROLL Command
Scrolled Event


\ | \\ Command

Visual FoxPro 9.0 Language Reference
\ | \\ Command
See Also Example

Prints or displays lines of text.

\TextLine
\\TextLine

Parameters

\ TextLine

When you use \, the text line is preceded by a carriage return and a line feed.
\\ TextLine

When you use \\, the text line is not preceded by a carriage return and a line feed. Any spaces preceding \ and \\ are not included in the output line, but spaces following \ and \\ are included. You can embed an expression in the text line. If the expression is enclosed in the text merge delimiters (<< >> by default) and SET TEXTMERGE is ON, the expression is evaluated and its value is output as text.

Remarks

The \ and \\ commands facilitate text merge in Visual FoxPro. Text merge makes it possible for you to output text to a file to create form letters or programs.

Use \ and \\ to output a text line to the current text-merge output file and the screen. SET TEXTMERGE is used to specify the text merge output file. If text merge is not directed to a file, the text line is output only to the main Visual FoxPro window or the active user-defined output window. SET TEXTMERGE NOSHOW suppresses output to the main Visual FoxPro window or the active user-defined window.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer && Open customer table
SET TEXTMERGE ON
SET TEXTMERGE TO letter.txt
\<<CDOW(DATE( ))>>, <<CMONTH(DATE( ))>>
\\ <<DAY(DATE( ))>>, <<YEAR(DATE( ))>>
\
\
\Dear <<contact>>
\Additional text
\
\Thank you,
\
\XYZ Corporation
CLOSE ALL
MODIFY FILE letter.txt NOEDIT

See Also

Other Resources

_PRETEXT System Variable
SET TEXTMERGE Command
SET TEXTMERGE DELIMITERS Command
_TEXT System Variable
TEXT ... ENDTEXT Command
Commands


= Command

Visual FoxPro 9.0 Language Reference
= Command
See Also

Evaluates one or more expressions.

= Expression1 [, Expression2 ...]

Parameters

Expression1[, Expression2...]

Specifies the expression or expressions that the = command evaluates.

Remarks

The = command evaluates one or more expressions, Expression1, Expression2 ..., and discards the return values. This option is particularly useful when a Visual FoxPro function or a user-defined function has a desired effect, but there is no need to assign the function's return value to a variable, array element, or field.

For example, to turn insert mode on, you can issue the following command:

Copy Code
= INSMODE(.T.)

INSMODE normally returns a True (.T.) or False (.F.) value. In the example above, the function is executed but the return value is discarded.

If only one expression (Expression1) is included, the equal sign is optional.

Note:
There are two unrelated uses for the equal sign (=). It can be used as an operator in logical expressions to make a comparison, or to assign values to variables and array elements. In these two cases, the equal sign (=) is an operator and not a command. See Relational Operators for more information about using the equal sign (=) as an operator in logical expressions. See STORE Command for more information about using the equal sign (=) to assign values to variables and array elements.

See Also

Other Resources

EVALUATE( ) Function
INSMODE( ) Function
Relational Operators
STORE Command
ON KEY = Command
Commands


ACTIVATE MENU Command

Visual FoxPro 9.0 Language Reference
ACTIVATE MENU Command
See Also Example

Displays and activates a menu bar.

ACTIVATE MENU MenuBarName   [NOWAIT]   [PAD MenuTitleName]

Parameters

MenuBarName

Specifies the name of the menu bar to activate.
NOWAIT

Specifies that at run time the program should not wait for the user to choose a menu from the active menu bar or to press ESC. Instead, the program continues to execute. A menu activated with the NOWAIT option does not return program execution to the line following the ACTIVATE MENU command when DEACTIVATE MENU is issued.
PAD MenuTitleName

Specifies the menu title name that is automatically selected when the menu bar is activated. If you don't specify a menu title name, the first menu title name in the activated menu bar is activated by default.

Remarks

Displays and activates the menu bar specified with MenuBarName. This command works in conjunction with DEFINE MENU and DEFINE PAD.

Note:
When you include the Visual FoxPro system menu bar (_MSYSMENU) in an application, there is no need to activate the menu. Instead, issue SET SYSMENU AUTOMATIC.

Example

The following example uses ACTIVATE MENU to display and activate a user-defined menu system. The current system menu bar is first saved to memory with SET SYSMENU SAVE, and then all system menu titles are removed with SET SYSMENU TO.

Two menu titles are created with DEFINE PAD; DEFINE POPUP is used to create a drop-down menu for each menu title. DEFINE BAR is used to create menu items on each of the menus. When a menu title is chosen, ON PAD uses ACTIVATE POPUP to activate the corresponding menu. ACTIVATE MENU displays and activates the menu bar.

When a menu item is chosen from a menu, the CHOICE procedure is executed. CHOICE displays the name of the chosen item and the name of the menu containing the item.
Copy Code
*** Name this program ACTIMENU.PRG ***
CLEAR
SET SYSMENU SAVE
SET SYSMENU TO
ON KEY LABEL ESC KEYBOARD CHR(13)
DEFINE MENU example BAR AT LINE 1
DEFINE PAD convpad OF example PROMPT '\<Conversions' COLOR SCHEME 3 ;
   KEY ALT+C, ''
DEFINE PAD cardpad OF example PROMPT 'Card \<Info' COLOR SCHEME 3 ;
   KEY ALT+I, ''
ON PAD convpad OF example ACTIVATE POPUP conversion
ON PAD cardpad OF example ACTIVATE POPUP cardinfo
DEFINE POPUP conversion MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF conversion PROMPT 'Ar\<ea' ;
   KEY CTRL+E, '^E'
DEFINE BAR 2 OF conversion PROMPT '\<Length' ;
   KEY CTRL+L, '^L'
DEFINE BAR 3 OF conversion PROMPT 'Ma\<ss' ;
   KEY CTRL+S, '^S'
DEFINE BAR 4 OF conversion PROMPT 'Spee\<d' ;
   KEY CTRL+D, '^D'
DEFINE BAR 5 OF conversion PROMPT '\<Temperature' ;
   KEY CTRL+T, '^T'
DEFINE BAR 6 OF conversion PROMPT 'T\<ime' ;
   KEY CTRL+I, '^I'
DEFINE BAR 7 OF conversion PROMPT 'Volu\<me' ;
   KEY CTRL+M, '^M'
ON SELECTION POPUP conversion DO choice IN actimenu;
   WITH PROMPT( ), POPUP( )
DEFINE POPUP cardinfo MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF cardinfo PROMPT '\<View Charges' ;
   KEY ALT+V, ''
DEFINE BAR 2 OF cardinfo PROMPT 'View \<Payments' ;
   KEY ALT+P, ''
DEFINE BAR 3 OF cardinfo PROMPT 'Vie\<w Users' ;
   KEY ALT+W, ''
DEFINE BAR 4 OF cardinfo PROMPT '\-'
DEFINE BAR 5 OF cardinfo PROMPT '\<Charges ' ;
   KEY ALT+C, ''
ON SELECTION POPUP cardinfo;
   DO choice IN actimenu WITH PROMPT( ), POPUP( )

ACTIVATE MENU example
DEACTIVATE MENU example
RELEASE MENU example EXTENDED
SET SYSMENU TO DEFAULT
ON KEY LABEL ESC
PROCEDURE choice
PARAMETERS mprompt, mpopup
WAIT WINDOW 'You chose ' + mprompt + ' from popup ' + mpopup NOWAIT

See Also

Other Resources

CLEAR Commands
CREATE MENU Command
DEACTIVATE MENU Command
DEFINE MENU Command
DEFINE PAD Command
HIDE MENU Command
SET SYSMENU Command
SHOW MENU Command
Commands
Language Reference


ACTIVATE POPUP Command

Visual FoxPro 9.0 Language Reference
ACTIVATE POPUP Command
See Also Example

Displays and activates a menu.

ACTIVATE POPUP MenuName   [AT nRow, nColumn]
[BAR nMenuItemNumber]   [NOWAIT]   [REST]

Parameters

MenuName

Specifies the name of the menu to activate.
AT nRow, nColumn

Specifies the position of the menu on the screen or in a user-defined window. The row and column coordinate applies to the upper-left corner of the menu. The position you specify with this argument takes precedence over a position you specify with the FROM argument in DEFINE POPUP.
BAR nMenuItemNumber

Specifies the item in the menu that is selected when the menu is activated. For example, if nMenuItemNumber is 2, the second item is selected. The first item is selected if you omit BAR nMenuItemNumber or if nMenuItemNumber is greater than the number of items in the menu.
NOWAIT

Specifies that, at run time, a program does not wait for the user to choose an item from the menu before continuing program execution. Instead, the program continues to execute.
REST

A menu created with the PROMPT FIELD clause of DEFINE POPUP places records from a field into the menu. When the menu is activated, the first item in the menu is initially selected, even if the record pointer in the table containing the field is positioned on a record other than the first record. Include REST to specify that the item selected when the menu is activated corresponds to the current record pointer position in the table.

Remarks

ACTIVATE POPUP works in conjunction with DEFINE POPUP, used to create the menu, and DEFINE BAR, used to create the items on the menu.

Example

This example uses ACTIVATE POPUP with ON PAD to activate a menu when a menu title is chosen. The current system menu bar is first saved to memory with SET SYSMENU SAVE, and then all system menu titles are removed with SET SYSMENU TO.

Two new system menu titles are created with DEFINE PAD; DEFINE POPUP is used to create a menu for each menu title. DEFINE BAR is used to create menu items on each of the menus. When a menu title is chosen, ON PAD uses ACTIVATE POPUP to activate the corresponding menu.

When an item is chosen from a menu, the CHOICE procedure is executed. CHOICE displays the name of the chosen item and the name of the menu containing the item. If the Exit item is chosen from the Card Info menu, the original Visual FoxPro system menu is restored.
Copy Code
*** Name this program ACTIPOP.PRG ***
CLEAR
SET SYSMENU SAVE
SET SYSMENU TO
DEFINE PAD convpad OF _MSYSMENU PROMPT '\<Conversions' COLOR SCHEME 3 ;
   KEY ALT+C, ''
DEFINE PAD cardpad OF _MSYSMENU PROMPT 'Card \<Info' COLOR SCHEME 3 ;
   KEY ALT+I, ''
ON PAD convpad OF _MSYSMENU ACTIVATE POPUP conversion
ON PAD cardpad OF _MSYSMENU ACTIVATE POPUP cardinfo
DEFINE POPUP conversion MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF conversion PROMPT 'Ar\<ea' KEY CTRL+E, '^E'
DEFINE BAR 2 OF conversion PROMPT '\<Length' ;
   KEY CTRL+L, '^L'
DEFINE BAR 3 OF conversion PROMPT 'Ma\<ss' ;
   KEY CTRL+S, '^S'
DEFINE BAR 4 OF conversion PROMPT 'Spee\<d' ;
   KEY CTRL+D, '^D'
DEFINE BAR 5 OF conversion PROMPT '\<Temperature' ;
   KEY CTRL+T, '^T'
DEFINE BAR 6 OF conversion PROMPT 'T\<ime' ;
   KEY CTRL+I, '^I'
DEFINE BAR 7 OF conversion PROMPT 'Volu\<me' ;
   KEY CTRL+M, '^M'
ON SELECTION POPUP conversion;
   DO choice IN actipop WITH PROMPT(), POPUP()
DEFINE POPUP cardinfo MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF cardinfo PROMPT '\<View Charges' ;
   KEY ALT+V, ''
DEFINE BAR 2 OF cardinfo PROMPT 'View \<Payments' ;
   KEY ALT+P, ''
DEFINE BAR 3 OF cardinfo PROMPT 'Vie\<w Users' ;
   KEY ALT+W, ''
DEFINE BAR 4 OF cardinfo PROMPT '\-'
DEFINE BAR 5 OF cardinfo PROMPT '\<Charges' ;
   KEY ALT+C, ''
DEFINE BAR 6 OF cardinfo PROMPT '\-'
DEFINE BAR 7 OF cardinfo PROMPT 'E\<xit';
   KEY ALT+X, ''
ON SELECTION POPUP cardinfo;
DO choice IN actipop WITH PROMPT(),POPUP()

PROCEDURE choice
PARAMETERS mprompt, mpopup
WAIT WINDOW 'You chose ' + mprompt + ;
   ' from popup ' + mpopup NOWAIT
IF mprompt = 'Exit'
   SET SYSMENU TO DEFAULT
ENDIF

See Also

Other Resources

CLEAR Commands
CREATE MENU Command
DEACTIVATE POPUP Command
DEFINE BAR Command
DEFINE POPUP Command
HIDE POPUP Command
MOVE POPUP Command
ON SELECTION POPUP Command
POP POPUP Command
POPUP( ) Function
PROMPT( ) Function
PUSH POPUP Command
SHOW POPU CommandP
Commands
Language Reference


ACTIVATE SCREEN Command

Visual FoxPro 9.0 Language Reference
ACTIVATE SCREEN Command
See Also

Sends all subsequent output to the main Visual FoxPro window instead of to the active user-defined window.

ACTIVATE SCREEN

Remarks

Use ACTIVATE WINDOW to direct output to a user-defined window.

See Also

Other Resources

ACTIVATE WINDOW Command
DEACTIVATE WINDOW Command
DEFINE WINDOW Command
HIDE WINDOW Command
SHOW WINDOW Command
Commands
Language Reference


ACTIVATE WINDOW Command

Visual FoxPro 9.0 Language Reference
ACTIVATE WINDOW Command
See Also Example

Displays and activates one or more user-defined windows or Visual FoxPro system windows.

ACTIVATE WINDOW WindowName1 [, WindowName2 ...]
| ALL   [IN [WINDOW] WindowName3 | IN SCREEN
[BOTTOM | TOP | SAME]    [NOSHOW]

Parameters

WindowName1[, WindowName2...]

Specifies the name of each window to activate. Separate the window names with commas. In Visual FoxPro, you can specify the name of a toolbar to activate. See SHOW WINDOW for a list of Visual FoxPro toolbar names.
ALL

Specifies that all windows are activated. The last window activated is the active output window.
IN [WINDOW] WindowName3

Specifies the name of the parent window within which the window is placed and activated. The activated window becomes a child window. A parent window can have multiple child windows. A child window activated inside a parent window cannot be moved outside the parent window. If the parent window is moved, the child window moves with it.
Note:
The parent window must be visible for any of its child windows to be visible.

IN SCREEN

Places and activates a window in the main Visual FoxPro window. A window can be placed in a parent window by including IN WINDOW in DEFINE WINDOW when the window is created. Including the IN SCREEN clause in ACTIVATE WINDOW overrides the IN WINDOW clause in DEFINE WINDOW.
BOTTOM | TOP | SAME

Specifies where windows are activated with respect to other previously activated windows. By default, a window becomes the window on top when it is activated. Including BOTTOM places a window behind all other windows. TOP places it in front of all other windows. SAME activates a window without affecting its front-to-back placement.
NOSHOW

Activates and directs output to a window without displaying the window.

Remarks

To successfully use this command on user-defined windows, any target user-defined window must have been created using the DEFINE WINDOW command.

Activating a window makes it the window on top and directs all output to that window. Output can be directed to only one window at a time. A window remains the active output window until it is deactivated or released, or until another window or the main Visual FoxPro window is activated.

The names of user-defined windows appear in the bottom section of the Window menu. The name of the active user-defined window is marked with a check mark.

More than one window can be placed in the main Visual FoxPro window at one time, but output is directed only to the last window activated. When more than one window is open, deactivating the active output window removes it from the main Visual FoxPro window and sends subsequent output to another window. If there is no active output window, output is directed to the main Visual FoxPro window.

Note:
To ensure output is directed to a specific window when you deactivate the active output window, you must explicitly activate the window you want to send output to with ACTIVATE WINDOW.

All activated windows are displayed until DEACTIVATE WINDOW or HIDE WINDOW is issued to remove them from view. Issuing either command removes windows from view but not from memory. Windows can be redisplayed by issuing ACTIVATE WINDOW or SHOW WINDOW.

To remove windows from view and from memory, use CLEAR WINDOWS, RELEASE WINDOWS, or CLEAR ALL. Windows that are removed from memory must be redefined to place them back in the main Visual FoxPro window.

You can use ACTIVATE WINDOW to place Visual FoxPro system windows in the main Visual FoxPro window or in a parent window.

The following system windows can be opened with ACTIVATE WINDOW:

  • Command

  • Call Stack

  • Debug

  • Debug Output

  • Document View

  • Locals

  • Trace

  • Watch

  • View

To activate a system window and or a toolbar, enclose the entire system window or toolbar name in quotation marks. For example, to activate the Call Stack debugging window in Visual FoxPro, issue the following command:

Copy Code
ACTIVATE WINDOW "Call Stack"

Historically in prior versions of Visual FoxPro, the Data Session window has always been referred to as the View window. Additionally, language used to control this window, such as HIDE WINDOW, ACTIVATE WINDOW, WONTOP( ), also refers to this window as the View window. Visual FoxPro continues to refer to the View window for the ACTIVATE WINDOW command.

Use HIDE WINDOW or RELEASE WINDOW to remove a system window from the main Visual FoxPro window or a parent window.

Example

The following example defines a window named output and activates it, placing it in the main Visual FoxPro window. The WAIT command pauses execution, the window is hidden, and then redisplayed.
Copy Code
CLEAR
DEFINE WINDOW output FROM 2,1 TO 13,75 TITLE 'Output' ;
   CLOSE FLOAT GROW ZOOM
ACTIVATE WINDOW output
WAIT WINDOW 'Press any key to hide window output'
HIDE WINDOW output
WAIT WINDOW 'Press any key to show window output'
SHOW WINDOW output
WAIT WINDOW 'Press any key to release window output'
RELEASE WINDOW output

See Also

Other Resources

CLEAR WINDOWS Command
DEACTIVATE WINDOW Command
DEFINE WINDOW Command
HIDE WINDOW Command
RELEASE WINDOWS Command
SHOW WINDOW Command
Commands
Language Reference


ADD CLASS Command

Visual FoxPro 9.0 Language Reference
ADD CLASS Command
See Also

Adds a class definition to a .vcx visual class library.

ADD CLASS ClassName [OF ClassLibraryName1] TO ClassLibraryName2
   [OVERWRITE]

Parameters

ClassName

Specifies the name of the class definition added to the .vcx visual class library ClassLibraryName2. If you omit the optional OF ClassLibraryName1 clause, Visual FoxPro searches for the class definition in any .vcx visual class libraries opened with SET CLASSLIB. Visual FoxPro generates an error if the class definition cannot be located or a class definition with the name you specify already exists in ClassLibraryName2.
OF ClassLibraryName1

Specifies a .VCX visual class library from which the class definition is copied.
TO ClassLibraryName2

Specifies the .vcx visual class library to which the class definition is added. If you specify a .vcx visual class library that does not exist, Visual FoxPro creates the visual class library and adds the class definition to the library.
OVERWRITE

Specifies that a class definition with the same name as the class definition you specify with ClassName is overwritten. An error message is generated if you omit OVERWRITE and a class definition with the same name as ClassName already exists in the .vcx visual class library.

Remarks

Use ADD CLASS to add a class definition to a class library, or to copy a class definition from one .vcx visual class library to another. A class definition cannot be added from a Visual FoxPro program or application (.prg or .app), or a procedure file.

See Also

Other Resources

ACLASS( )
AMEMBERS( )
CREATE CLASS Command
CREATE CLASSLIB Command
DEFINE CLASS Command
MODIFY CLASS Command
RELEASE CLASSLIB Command
REMOVE CLASS Command
RENAME CLASS Command
SET CLASSLIB Command
Commands
Language Reference


ADD TABLE Command

Visual FoxPro 9.0 Language Reference
ADD TABLE Command
See Also Example

Adds a free table to the current database.

ADD TABLE TableName | ?   [NAME LongTableName]

Parameters

TableName

Specifies the name of the table added to the database.
?

Displays the Open dialog box from which you can choose a table to add to the database.
NAME LongTableName

Specifies a long name for the table. Long names can contain up to 128 characters and can be used in place of short file names that have a .DBF extension.

Remarks

After the table is added to the database, you can perform the same operations on it as you can on any other table.

Once the table is added to the database, it is no longer free. However, any table in the database can be made free by issuing REMOVE TABLE.

The table you are adding:

  • Must be a valid .DBF file.

  • Cannot have the same name as an existing table in the open database, unless you assign the table a unique long name.

  • Cannot exist in another database. Use REMOVE TABLE to remove the table from another database.

The database to which you are adding a table cannot be involved in a transaction.

Example

The following example creates two databases named mydbc1 and mydbc2, and a table named table1. The table is added to mydbc1 when it is created. The table is then closed and removed from mydbc1. ADD TABLE is then used to add the table to mydbc2. RENAME TABLE is used to change the name of the table from table1 to table2.
Copy Code
CREATE DATABASE mydbc1
CREATE DATABASE mydbc2
SET DATABASE TO mydbc1
CREATE TABLE table1 (cField1 C(10), n N(10))  && Adds table to mydbc1
CLOSE TABLES&& A table must be closed to remove it from a database
REMOVE TABLE table1
SET DATABASE TO mydbc2
ADD TABLE table1
RENAME TABLE table1 TO table2

See Also

Reference

INDBC( ) Function

Other Resources

CLOSE Commands
CREATE DATABASE Command
DISPLAY TABLES Command
FREE TABLE Command
OPEN DATABASE Command
REMOVE TABLE Command
Commands
Language Reference


ALTER TABLE - SQL Command

Visual FoxPro 9.0 Language Reference
ALTER TABLE - SQL Command
See Also Example

Programmatically modifies the structure of a table. There are several versions of the syntax.

ALTER TABLE TableName1 ADD | ALTER [COLUMN] FieldName1
      FieldType [( nFieldWidth [, nPrecision])] [NULL | NOT NULL] [CHECK lExpression1 [ERROR cMessageText1]]
   [AUTOINC [NEXTVALUE NextValue [STEP StepValue]]] [DEFAULT eExpression1]
   [PRIMARY KEY | UNIQUE [COLLATE cCollateSequence]]
   [REFERENCES TableName2 [TAG TagName1]] [NOCPTRANS] [NOVALIDATE]
ALTER TABLE TableName1 ALTER [COLUMN] FieldName2 [NULL | NOT NULL] [SET DEFAULT eExpression2]
   [SET CHECK lExpression2 [ERROR cMessageText2]] [ DROP DEFAULT ] [ DROP CHECK ] [ NOVALIDATE ]
ALTER TABLE TableName1 [DROP [COLUMN] FieldName3]
   [SET CHECK lExpression3 [ERRORcMessageText3]] [DROP CHECK]
   [ADD PRIMARY KEY eExpression3 [FOR lExpression4] TAG TagName2
   [COLLATE cCollateSequence]] [DROP PRIMARY KEY]
   [ADD UNIQUE eExpression4 [[FOR lExpression5] TAG TagName3
      [COLLATE cCollateSequence]]] [DROP UNIQUE TAG TagName4]
   [ADD FOREIGN KEY [eExpression5] [FOR lExpression6] TAG TagName4
      REFERENCES TableName4 [TAG TagName4][COLLATE cCollateSequence]
      REFERENCES TableName2 [TAG TagName5]]
   [DROP FOREIGN KEY TAG TagName6 [SAVE]]
   [RENAME COLUMN FieldName4 TO FieldName5] [NOVALIDATE]

Parameters

ALTER TABLE TableName1

Modifies the structure of a table. The TableName1 parameter specifies the name of the table to be modified.
ADD | ALTER [COLUMN] FieldName1

Specifies the name of the field to add or modify. A single table can contain up to 255 fields. If one or more fields allow null values, the limit decreases by one field to 254 fields. Using ALTER COLUMN resets the collating sequence to the default. You should index the table again with the desired collating sequence after performing ALTER COLUMN. You can also use the COLLATE clause in the ALTER TABLE command when appropriate (primary key or foreign key).
FieldType[( nFieldWidth[, nPrecision])]

Specifies the field type, field width, and field precision (number of decimal places) for the new or modified field. FieldType can be a single letter indicating the field's data type, or a long name indicating the field's data type. Some field data types require that you specify nFieldWidth or nPrecision, or both. The following table lists the values for FieldType and whether nFieldWidth and nPrecision are required:

FieldType nFieldWidth nPrecision Data type

W, Blob

-

-

Blob

C, Char, Character

N

–

Character field of width n

Y, Currency

–

–

Currency

D, Date

–

–

Date

T, DateTime

–

–

DateTime

B, Double

–

D

Double

G, General

–

–

General

I, Int, Interger

–

–

Integer

L, Logical

–

–

Logical

M, Memo

–

–

Memo

N, Num, Numeric

N

D

Numeric field of width n with d decimal places

F, Float

N

D

Floating Numeric field of width n with d decimal places

Q, Varbinary

n

-

Varbinary field of width n

V, Varchar

n

-

Varchar field of width n
The nFieldWidth and nPrecision parameters are ignored for the W, Y, D, T, G, I, L, and M types. If nPrecision is not included for the N, F, or B types, the nPrecision parameter defaults to zero (no decimal places).
NULL | NOT NULL

Specifies whether null values are allowed in the field. NULL permits null values, while NOT NULL does not allow null values. If one or more fields can contain null values, the maximum number of fields the table can contain is reduced from 255 to 254.
Note:
Changing the structure of a field that is used by a binary index so that it can contain null values generates an error.

CHECK lExpression1

Specifies a validation rule for the field. The lExpression1 parameter must evaluate to a logical expression and can be a user-defined function or a stored procedure. Visual FoxPro checks the validation rule specified in the CHECK clause when a blank record is appended.
ERROR cMessageText1

Specifies an error message. Visual FoxPro displays this message when the validation rule specified with the CHECK clause generates an error. The message displays only when data is changed within a Browse window or Edit window.
AUTOINC [NEXTVALUE NextValue[STEP StepValue]]

Enables automatic incrementing for the field. NextValue specifies the start value and can be a positive or a negative integer value ranging from 2,147,483,647 to -2,147,483,647. The default value is 1. You can set NextValue using the Next Value spin box in Fields tab of the Table Designer. StepValue specifies the increment value for the field and can be a positive, nonzero integer value ranging from 1 to 255. The default value is 1. You can set StepValue using the Step spin box in the Fields tab of the Table Designer. Autoincrementing values cannot be NULL.
Note:
Tables containing automatically incrementing field values append table-buffered records approximately 35% slower than tables without automatically incrementing field values, which might affect performance. When using table buffering, the table header is locked when the record is appended.

DEFAULT eExpression1

Specifies a default value for the field specified in FieldName1. The data type of eExpression1 must be the same as the data type for the field. You cannot specify a default value if you use the AUTOINC clause to turn on autoincrementing for a field. Visual FoxPro generates an error message if you specify values for both the AUTOINC and DEFAULT clauses.
PRIMARY KEY | UNIQUE

PRIMARY KEY creates a primary index for the field specified in FieldName1. UNIQUE creates a candidate index for the field specified in FieldName1. The primary index tag or candidate index tag has the same name as the field. For more information about primary and candidate indexes, see Visual FoxPro Index Types.
COLLATE cCollateSequence

Specifies a collation sequence other than the default setting, MACHINE. The cCollateSequence parameter must be a valid Visual FoxPro collation sequence. For more information about setting collation sequences, see Optimizing International Applications and SET COLLATE Command.
REFERENCES TableName2[TAG TagName1]

Specifies the parent table to which a persistent relationship is established. The parent table cannot be a free table. The TagName1 parameter clause specifies an index tag name for the parent table in TableName2. Index tag names can contain up to 10 characters. If you omit the TAG clause, the relationship is established using the primary index key of the parent table. If the parent table does not have a primary index, Visual FoxPro generates an error.
NOCPTRANS

Prevents translation to a different code page for Character, Memo, and Varchar fields. You can specify NOCPTRANS only for Character, Memo, and Varchar fields. This creates what appears as Character (Binary), Memo (Binary), and Varchar (Binary) data types in the Table Designer.
NOVALIDATE

Specifies that Visual FoxPro allows changes to the table structure that can violate the data integrity of the table. By default, Visual FoxPro prevents ALTER TABLE from making such changes to the table structure. To override the default behavior, include the NOVALIDATE option.
ALTER [COLUMN] FieldName2

Specifies the name of a field to modify. You need to include multiple ALTER COLUMN clauses to change more than one property of a field in a single ALTER TABLE command. For more information about how ALTER COLUMN clauses are structured, see the examples in this topic.
SET DEFAULT eExpression2

Specifies a new default value for an existing field. The data type of eExpression2 must be the same as the data type for the field. You cannot specify a default value if you use the AUTOINC clause to turn on autoincrementing for a field. Visual FoxPro generates an error message if you specify values for both the AUTOINC and SET DEFAULT clauses.
SET CHECK lExpression2

Specifies a new validation rule for an existing field. The lExpression2 parameter must evaluate to a logical expression and can be a user-defined function or a stored procedure.
ERROR cMessageText2

Specifies an error message for the field validation rule in lExpression2. Visual FoxPro displays this message when the field validation rule generates an error. The message displays only when data is changed within a Browse window or Edit window.
DROP DEFAULT

Removes the default value for an existing field.
DROP CHECK

Removes the validation rule for an existing field.
DROP [COLUMN] FieldName3

Specifies a field to remove from the table. Removing a field from the table also removes the field's default value setting and field validation rule. If index key or trigger expressions reference the field, the expressions become invalid when the field is removed. In this case, an error is not generated when the field is removed, but the invalid index key or trigger expressions generate errors at run time.
SET CHECK lExpression3

Specifies the table validation rule. The lExpression3 parameter must evaluate to a logical expression and can be a user-defined function or a stored procedure.
ERROR cMessageText3

Specifies an error message for the table validation rule in lExpression3. Visual FoxPro displays this message when the table validation rule generates an error. The message displays only when data is changed within a Browse window or Edit window.
DROP CHECK

Removes the table validation rule.
ADD PRIMARY KEY eExpression3[FOR lExpression4] TAG TagName2

Adds a primary index to the table. The eExpression3 specifies the primary index key expression. You can use lExpression4 to specify a filter expression where only records that satisfy the condition are available for display and access. Primary index keys are created in the index file just for those records that match the filter expression. You should avoid using the FOR clause to create a primary index; the uniqueness of a primary key is enforced only for those records that match the condition specified in the FOR clause. Instead, use the INDEX command with a FOR clause to create a filtered index. Rushmore Query Optimization optimizes an ALTER TABLE ... FOR lExpression4 command if the lExpression4 expression can be optimized. For the best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access. The TagName2 parameter specifies the name of the primary index tag. Index tag names can contain up to 10 characters. If you omit TAG TagName2, and eExpression3 is a single field, the primary index tag has the same name as the field specified in eExpression3.
DROP PRIMARY KEY

Removes the primary index and its index tag. A table can have only one primary key, so you do not need to specify the name of the primary key. Removing the primary index also deletes any persistent relations based on the primary key.
ADD UNIQUE eExpression4[TAG TagName3[FOR lExpression5]]

Adds a candidate index to the table. The eExpression4 parameter specifies the candidate index key expression. The TagName3 parameter specifies the name of the candidate index tag. Index tag names can contain up to 10 characters. If you omit TAG TagName3, and if eExpression4 is a single field, the candidate index tag has the same name as the field specified in eExpression4. You can use the lExpression5 parameter to specify a filter expression where only records that satisfy the condition are available for display and access. Candidate index keys are created in the index file just for those records that match the filter expression. Rushmore optimizes an ALTER TABLE ... FOR lExpression5 command if the lExpression5 expression can be optimized. For the best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
DROP UNIQUE TAG TagName4

Removes the candidate index and its index tag. A table can have multiple candidate keys, so you must specify the name of the candidate index tag.
ADD FOREIGN KEY [ eExpression5] TAG TagName4[FOR lExpression6]

Adds a foreign (non-primary) index to the table. The eExpression5 parameter specifies the foreign index key expression. The TagName4 parameter specifies the name of the foreign index tag. Index tag names can contain up to 10 characters. You can use the lExpression6 parameter to specify a filter expression where only records that satisfy the condition are available for display and access. Foreign index keys are created in the index file just for those records that match the filter expression. Rushmore optimizes an ALTER TABLE ... FOR lExpression6 command if the lExpression6 expression can be optimized. For the best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
REFERENCES TableName2[TAG TagName5]

Specifies the parent table to which a persistent relationship is established. You can use the TAG TagName5 clause to establish a relationship based on an existing index tag for the parent table. Index tag names can contain up to 10 characters. If you omit the TAG clause, Visual FoxPro establishes the relationship using the parent table's primary index tag.
DROP FOREIGN KEY TAG TagName6[SAVE]

Deletes a foreign key whose index tag is TagName6. You can use SAVE to keep the index tag in the structural index. If you omit SAVE, the index tag is deleted from the structural index.
RENAME COLUMN FieldName4TO FieldName5

Makes it possible for you to change the name of a field in the table. The FieldName4 parameter specifies the name of the field to be renamed. The FieldName5 paramter specifies the new name of the field.
Caution:
Exercise care when renaming table fields because index expressions, field and table validation rules, commands, functions, and so on might refer to the original field names.

Remarks

You can use ALTER TABLE to modify the structure of a table that has not been added to a database. However, Visual FoxPro generates an error if you include the DEFAULT, FOREIGN KEY, PRIMARY KEY, REFERENCES, or SET clauses when modifying a free table.

ALTER TABLE might rebuild the table by creating a new table header and appending records to the table header. For example, changing the type or width of a field can cause the table to rebuild.

After a table is rebuilt, field validation rules are executed for any fields whose type or width is changed. If you change the type or width of any field in the table, the table rule is executed.

If you modify field or table validation rules for a table that has records, Visual FoxPro tests the new field or table validation rules against the existing data and issues a warning on the first occurrence of a field or table validation rule or of a trigger violation.

You cannot specify a value or expression in the DEFAULT clause if you turn on autoincrementing for a field.

To remove autoincrementing, use ALTER TABLE - SQL to change COLUMN but do not include the AUTOINC clause.

Field validation should remain enabled for autoincrementing fields. You might want to use validation to return a new autoincrementing value.

When you change a table that does not contain an autoincrementing field to include one, either by using ALTER TABLE or the Table Designer, autoincrementing begins with the next added row. Previous rows in the table are not updated with autoincrementing values starting with the first record. You need to make sure that no conflicts occur as a result.

ALTER TABLE might not produce consistent results when used with Visual FoxPro cursors created by the CREATE CURSOR command. In particular, you can create a Visual FoxPro cursor with features, such as long field names, that are normally available only with tables that are part of a database container. ALTER TABLE saves a temporary copy of the cursor, so the rules that apply to free tables also apply, and any features requiring database support are lost or changed in an unpredictable manner. Therefore, you should generally avoid using ALTER TABLE with Visual FoxPro cursors unless you have tested and understood the outcome.

If you omit NULL and NOT NULL, the current setting of the SET NULL command determines if null values are allowed in the field. However, if you omit NULL and NOT NULL but include the PRIMARY KEY or UNIQUE clause, Visual FoxPro disregards the current setting of SET NULL, and the field defaults to NOT NULL.

Visual FoxPro generates an error if the validation rule specified in the CHECK clause does not allow for a blank field value in an appended record.

Null values and duplicate records are not permitted in a field used for a primary or candidate index. If you are creating a new field using ADD COLUMN, Visual FoxPro does not generate an error if you create a primary or candidate index for a field that supports null values. However, Visual FoxPro generates an error if you attempt to enter a null or duplicate value into a field used for a primary or candidate index.

Note:
Candidate indexes, created by including the UNIQUE option (provided for ANSI compatibility) in CREATE TABLE – SQL or ALTER TABLE – SQL commands, are not the same as indexes created in the INDEX command with the UNIQUE option. An index created in the INDEX command using the UNIQUE option allows duplicate index keys; candidate indexes do not allow duplicate index keys. For more information about the UNIQUE option in the INDEX command, see INDEX Command. The term CANDIDATE is a synonym of UNIQUE and can be used instead if you choose.

If you modify an existing field, and the primary index expression or candidate index expression consists of fields in the table, Visual FoxPro checks the fields to see if they contain null values or duplicate records. If they do, Visual FoxPro generates an error and the table is not altered.

If the table is converted to another code page, the fields for which NOCPTRANS has been specified are not translated.

Example

Example 1 adds a field called Fax to a Customer table and allows the field to have null values.

Example 2 makes the Cust_id field the primary key of the Customer table.

Example 3 adds a field validation rule to the Quantity field of the Orders table so that values in the Quantity field must be non-negative.

Example 4 adds a one-to-many persistent relation between the Customer and Orders tables based on the primary key Cust_id in the Customer table and a new foreign key index Cust_id in the Orders table.

Example 5 removes the field validation rule from the Quantity field in the Orders table.

Example 6 removes the persistent relation between the Customer and Orders tables, but keeps the Cust_id index tag in the Orders table.

Example 7 adds a field called Fax2 to the Customer table and prevents the field from containing null values. The new structure of the table is displayed. Two ALTER COLUMN clauses are used to allow the field to have null values and set the default value for the field to the null value. Note that multiple ALTER COLUMN clauses are required to change more than one property of a field in a single ALTER TABLE command. The new field is then removed from the table to restore the table to its original state.

Copy Code
* Example 1
SET PATH TO (HOME(2) + 'Data\')     && Sets path to table.
ALTER TABLE Customer ADD COLUMN Fax c(20) NULL

* Example 2
ALTER TABLE Customer ADD PRIMARY KEY Cust_id TAG Cust_id
ALTER TABLE Customer ALTER COLUMN Cust_id Character(5) PRIMARY KEY

* Example 3
ALTER TABLE Orders;
    ALTER COLUMN Quantity SET CHECK Quantity >= 0;
    ERROR "Quantities must be non-negative"

* Example 4
ALTER TABLE Orders;
   ADD FOREIGN KEY Cust_id TAG Cust_id REFERENCES Customer

* Example 5
ALTER TABLE Orders ALTER COLUMN Quantity DROP CHECK

* Example 6
ALTER TABLE Orders DROP FOREIGN KEY TAG Cust_id SAVE

* Example 7
CLEAR
ALTER TABLE Customer ADD COLUMN Fax2 c(20) NOT NULL
DISPLAY STRUCTURE
ALTER TABLE Customer;
   ALTER COLUMN Fax2 NULL;
   ALTER COLUMN Fax2 SET DEFAULT .NULL.
ALTER TABLE Customer DROP COLUMN Fax2

See Also

Other Resources

Autoincrementing Field Values in Tables
AFIELDS( ) Function
CREATE TABLE - SQL Command
INDEX Command
MODIFY STRUCTURE Command
OPEN DATABASE Command
SET OPTIMIZE Command
Using Rushmore Query Optimization to Speed Data Access
Commands
Language Reference


APPEND Command

Visual FoxPro 9.0 Language Reference
APPEND Command
See Also Example

Adds one or more new records to the end of a table.

APPEND [BLANK] [IN nWorkArea | cTableAlias] [NOMENU]

Parameters

BLANK

Adds one blank record to the end of the current table. Visual FoxPro does not open an editing window when you issue APPEND BLANK. You can edit the new record with BROWSE, CHANGE, or EDIT.
IN nWorkArea

Specifies the work area of the table to which a new record is appended.
IN cTableAlias

Specifies the alias of the table to which a new record is appended. If you omit nWorkArea and cTableAlias, a new record is appended to the table in the currently selected work area. If you issue APPEND, a blank record is added to the table you specify with nWorkArea or cTableAlias and the table is automatically selected. If you issue APPEND BLANK, a blank record is added to the table you specify with nWorkArea or cTableAlias and the table is not selected.
NOMENU

Specifies that the Table menu title is removed from the system menu bar, preventing changes to the format of the editing window.

Remarks

When you issue APPEND or APPEND BLANK and a table isn't open in the currently selected work area, the Open dialog appears so that you can choose a table to which you can append records.

APPEND opens an editing window so you can enter data into one or more new records. When you add a new record, Visual FoxPro updates any indexes that are open.

Example

The following example uses APPEND BLANK to create a table with 10 records containing random values, and then displays the maximum and minimum values in the table.
Copy Code
CLOSE DATABASES
CREATE TABLE curRandom (nValue N(3))
FOR nItem = 1 TO 10
   APPEND BLANK
   REPLACE nValue WITH 1 + 100 * RAND( )
ENDFOR

CLEAR
LIST
SELECT MIN(nValue) as nMinimum, MAX(nValue) AS nMaximum;
   FROM curRandom INTO CURSOR curMinMax
? 'The minimum value is: ', nMinimum
? 'The maximum value is: ', nMaximum
CLOSE DATABASES

See Also

Reference

SELECT - SQL Command

Other Resources

APPEND FROM ARRAY Command
BROWSE Command
Commands
Language Reference


APPEND FROM ARRAY Command

Visual FoxPro 9.0 Language Reference
APPEND FROM ARRAY Command
See Also Example

Adds one record to the currently selected table for each row in an array and fills each record with data from the corresponding array row.

APPEND FROM ARRAY ArrayName [FOR lExpression]
   [FIELDS FieldList | FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton]

Parameters

ArrayName

Specifies the name of the array that contains the data to be copied to the new records. New records are added to the table until all rows in the array are appended.
FOR lExpression

Specifies a condition for appending records from the array. lExpression must contain the name of a target field in its conditional expression. Before a row of the array is appended to a record in the table, the array element corresponding to the target field specified in lExpression is checked to determine whether that array element meets the condition in lExpression. If the array element satisfies the condition, a record is appended. If the array element does not satisfy the condition, the array row is not appended and the next row in the array is checked to determine whether it meets the condition.
FIELDS FieldList

Specifies that only the fields in FieldList are updated from the array. The first field in the list is updated with the contents of the first element in the array, the second field is updated from the second element, and so on.
FIELDS LIKE Skeleton

Specifies that fields that match the field skeleton Skeleton are updated from the array.
FIELDS EXCEPT Skeleton

Specifies that all fields except those that match the field skeleton Skeleton are updated from the array. The field skeleton Skeleton supports wildcards. For example, to specify that all fields that begin with the letters A and P are updated from the array, use the following:
Copy Code
APPEND FROM ARRAY aMyArray FIELDS LIKE A*,P*
The LIKE clause can be combined with the EXCEPT clause:
Copy Code
APPEND FROM ARRAY aMyArray FIELDS LIKE A*,P* EXCEPT PARTNO*

Remarks

Memo, General, and Blob fields are ignored in APPEND FROM ARRAY.

When a table is open for shared use, APPEND FROM ARRAY locks the table header while records are being added.

If the array is one-dimensional, APPEND FROM ARRAY adds one record to the table. The contents of the first array element fill the first field of the newly added record, the contents of the second element of the array fill the second field of the record, and so on.

If the one-dimensional array has more elements than the table has fields, the additional elements are ignored. If the table has more fields than the array has elements, the additional fields are initialized to the default empty value. Here are the default empty values for each field type:

Field type | Default value
Character | Spaces
Currency | 0
Date | Empty Date (e.g. CTOD(""))
DateTime | Empty DateTime (e.g. CTOT(""))
Double | 0
Float | 0
Integer | 0
Logical | False (.F.)
Memo | Empty (no contents)
Numeric | 0

If the array is two-dimensional, APPEND FROM ARRAY adds a new record to the table for each row in the array. For example, if the array has four rows, four new records are appended to the table.

The contents of the first array column fill the first field of the newly added records, the second array column fills the second field of the new records, and so on. For example, if the array has four rows and three columns, elements from the first array column fill the first field in each of the four new records appended to the table.

If the two-dimensional array has more columns than the table has fields, the additional columns are ignored. If the table has more fields than the array has columns, the additional fields are initialized to empty values.

APPEND FROM ARRAY can fill a field even if the corresponding array element's data type does not match the field's data type an provided that the array element data is compatible with the data type of the corresponding field. If the data is not compatible, the field is initialized to an empty value.

If the target table uses autoincrementing, APPEND FROM ARRAY fails if SET AUTOINCERROR is ON, unless the FIELDS option is used to omit the AUTOINC column. Setting AUTOINCERROR to OFF or turning off autoincrementing in the target table by using CURSORSETPROP( ) allows the APPEND FROM ARRAY to succeed. The target table's autoincrementing field or fields are incremented according to the values specified, and the values in source table are not applied.

Example

This example creates a table and then uses APPEND FROM ARRAY to append a record to the new table.
Copy Code
LOCAL ARRAY aNewRec(3)

* Create the table
CREATE TABLE Test FREE  (Object C(10), Color C(16), SqFt n(6,2))
SCATTER TO aNewRec BLANK  && Create a new array from the table
aNewRec[1]="Box"         && Fill the array
aNewRec[2]="Red"
aNewRec[3]=12.5
APPEND FROM ARRAY aNewRec   && Add record containing array contents
          && to the table

See Also

Other Resources

APPEND Command
COPY TO ARRAY Command
DIMENSION Command
GATHER Command
SCATTER Command
Commands
Language Reference


APPEND FROM Command

Visual FoxPro 9.0 Language Reference
APPEND FROM Command
See Also Example

Adds records to the end of the currently selected table from another file.

APPEND FROM FileName | ?[FIELDS FieldList] [FOR lExpression]
   [[TYPE] [DELIMITED [WITH Delimiter | WITH BLANK | WITH TAB
      | WITH CHARACTER Delimiter] | DIF | FW2 | MOD | PDOX | RPD |
      SDF | SYLK | WK1 | WK3 | WKS | WR1 | WRK | CSV | XLS | XL5
      [SHEET cSheetName] | XL8 [SHEET cSheetName]]] [AS nCodePage]

Parameters

FileName

Specifies the name of the file to append from. If you don't include a file name extension, a Visual FoxPro table and a default extension .dbf is assumed. If you are appending from a Visual FoxPro table, records in the table that are marked for deletion are appended if the current SET DELETED setting is OFF.
?

Displays the Open dialog box, from which you can choose a table to append from.
FIELDS FieldList

Specifies to which fields data is appended.
Note:
You cannot append to memo fields from text files such as CSV and SDF files.

FOR lExpression

Appends a new record for each record in the currently selected table for which lExpression evaluates to True (.T.). Records are appended until the end of the currently selected table is reached. If you omit FOR, the entire source file is appended to the currently selected table.
TYPE

Specifies the source file type of the file you are appending from. Although you must specify a file type if the file you are appending from isn't a Visual FoxPro table, you need not include the TYPE key word. You can append from a wide variety of different file types including delimited ASCII text files, in which you can specify a field delimiter. If the source file you are appending from doesn't have the usual default file extension for that type of file, the source file name must include the file's extension. For example, Microsoft Excel worksheets normally have an .xls extension. If the Microsoft Excel worksheet you append from has an extension other than the expected .xls, be sure to specify the extension.
Note:
When you are appending from a worksheet, the data in the worksheet must be stored in a row-major order rather than a column-major order. This allows the appended worksheet data to match the table structure.

DELIMITED

Specifies that the source file from which data is appended to the current Visual FoxPro table is a delimited file. A delimited file is an ASCII text file in which each record ends with a carriage return and line feed. Field contents are by default assumed to be separated from each other by commas (do not include extra spaces before or after the commas), and character field values to be additionally delimited by double quotation marks. For example:
Copy Code
"Smith",9999999,"TELEPHONE"
The file extension is assumed to be .txt for all delimited files. You can import dates from delimited files if the dates are in proper date format. The date format defaults to mm/dd/yy. Including the century portion of a date is optional. Visual FoxPro will import a date, such as 12/25/95, that doesn't include the century and assumes the date is in the twentieth century. Date delimiters can be any non-numeric character except the delimiter that separates the fields in the delimited file. Dates in other formats can be imported if their formats match date formats available in SET DATE. To import dates that are not in the default format, issue SET DATE with the proper date format before using APPEND FROM. To test whether a date format can be successfully imported, use it with CTOD( ). If the date is acceptable to CTOD( ), the date will import properly.
DELIMITED WITH Delimiter

Indicates that character fields are separated by a character other than the quotation mark.
DELIMITED WITH BLANK

Specifies files that contain fields separated by spaces instead of commas.
DELIMITED WITH TAB

Specifies files that contain fields separated by tabs rather than commas.
DELIMITED WITH CHARACTER Delimiter

Specifies files that contain fields all enclosed by the character specified with Delimiter. If Delimiter is a semicolon (the character used in Visual FoxPro to indicate command line continuation), enclose the semicolon in quotation marks. You can also specify the BLANK and TAB keywords for Delimiter. The WITH Delimiter clause can be combined with the WITH CHARACTER clause. For example, the following command adds records from a text file with character fields enclosed by underscores and all fields delimited from each other with asterisks:
Copy Code
APPEND FROM mytxt.txt DELIMITED WITH _ WITH CHARACTER *
DIF

Include DIF to import data from a VisiCalc .dif (Data Interchange Format) file. Vectors (columns) become fields in the currently selected table and tuples (rows) become records. DIF file names are assumed to have a .dif extension.
FW2

Include FW2 to import data from a file created by Framework II. FW2 file names are assumed to have a .fw2 extension.
MOD

Include MOD to import data from a Microsoft Multiplan version 4.01 file. MOD files are created by Microsoft Multiplan version 4.01, and are assumed to have a .mod extension.
PDOX

Include PDOX to import data from a Paradox version 3.5 or 4.0 database file. Paradox file names are assumed to have a .db extension.
RPD

Include RPD to import data from a file created by RapidFile version 1.2. RapidFile file names are assumed to have an .rpd extension.
SDF

Include SDF to import data from a System Data Format file. An SDF file is an ASCII text file in which records have a fixed length and end with a carriage return and line feed. Fields are not delimited. The file name extension is assumed to be .txt for SDF files. Effective conversion of date data from SDF files to Visual FoxPro tables requires data to be stored in YYYYMMDD format. If date information is stored in ambiguous formats, you should map the date column to a character column of appropriate width so you can inspect the value and then apply the correct conversion routine to create correctly formatted date data.
SYLK

Include SYLK to import data from a SYLK (Symbolic Link) interchange format file. SYLK files are used in Microsoft MultiPlan. Columns in the SYLK file become fields in the Visual FoxPro table and rows become records. SYLK file names have no extension.
WK1

Include WK1 to import data from a Lotus 1-2-3 version 2.x spreadsheet. Each column from the spreadsheet becomes a field in the table; each spreadsheet row becomes a record in the table. A .WK1 file name extension is assigned to a spreadsheet created in Lotus 1-2-3 revision 2.x.
WK3

Include WK3 to import data from a Lotus 1-2-3 spreadsheet. Each column from the spreadsheet becomes a field in the table; each spreadsheet row becomes a record in the table. A .wk3 file name extension is assigned to a spreadsheet created in Lotus 1-2-3 revision 3.x.
WKS

Include WKS to import data from a Lotus 1-2-3 revision 1-A spreadsheet. Each column from the spreadsheet becomes a field in the table; each spreadsheet row becomes a record in the table. A .wks file name extension is assigned to a spreadsheet created in Lotus 1-2-3 revision 1-A.
WR1

Include WR1 to import data from a Lotus Symphony version 1.1 or 1.2 spreadsheet. Each column from the spreadsheet becomes a field in the table and each spreadsheet row becomes a record in the table. A .wr1 file name extension is assigned to a spreadsheet created in Symphony versions 1.1 or 1.2.
WRK

Include WRK to import data from a Lotus Symphony version 1.0 spreadsheet. Each column from the spreadsheet becomes a field in the table and each spreadsheet row becomes a record in the table. A .wrk file name extension is assigned to a spreadsheet created in Symphony version 1.0.
CSV

Include CSV to import data from a comma separated value file. A CSV file has field names as the first line in the file; the field names are ignored when the file is imported.
XLS

Include XLS to import data from a Microsoft Excel worksheet. Each column from the worksheet becomes a field in the table and each worksheet row becomes a record in the table. Worksheet files created in Microsoft Excel are given an .xls file name extension.
XL5

Include XL5 to import data from Microsoft Excel version 5.0. Columns from the worksheet become fields in the table; the worksheet rows become records in the table. Worksheet files created in Microsoft Excel have an .xls extension. If you omit the SHEET clause, the data in Sheet1 is imported. To import data from a specific sheet, include the SHEET keyword and specify the sheet name with cSheetName.
XL8

Include XL8 to import data from Microsoft Excel 97. Columns from the worksheet become fields in the table; the worksheet rows become records in the table. Worksheet files created in Microsoft Excel have an .xls extension. If you omit the SHEET clause, the data in Sheet1 is imported. To import data from a specific sheet, include the SHEET keyword and specify the sheet name with cSheetName.
AS nCodePage

Specifies the code page of the source table or file. Visual FoxPro copies the contents of the source table or file and, as it copies the data, automatically converts the data to the code page of the current table. If you specify a value for nCodePage that is not supported, Visual FoxPro generates an error message. You can use GETCP( ) for nCodePage to display the Code Page dialog box, making it possible for you to specify a code page for the appended table or file. If you omit AS nCodePage and Visual FoxPro cannot determine the code page of the source table or file, Visual FoxPro copies the contents of the source table or file. As it copies the data, it automatically converts the data to the current Visual FoxPro code page. If SET CPDIALOG is ON, the table in the currently selected work area is marked with a code page. If you're appending from a table not marked with a code page, the Code Page dialog is displayed, making it possible for you to choose the code page of the table from which you're appending. The current Visual FoxPro code page can be determined with CPCURRENT( ). If you omit AS nCodePage and Visual FoxPro can determine the code page of the table or file being appended, Visual FoxPro copies the contents of the appended table or file. As it copies the data, it automatically converts the data to the code page of the currently selected table. If nCodePage is 0, Visual FoxPro assumes that the code page of the table or file being appended is the same as the code page of the currently selected table. No conversion to the current Visual FoxPro code page occurs.

Remarks

If the file from which you append is a Visual FoxPro table or a table created in an earlier version of FoxPro, a .dbf extension is assumed. If the Visual FoxPro table or the table created in an earlier version of FoxPro doesn't have a .dbf extension, you must specify its extension. If the file is not a Visual FoxPro table or a table created in an earlier version of FoxPro, you must specify the type of file from which you append.

Before you can append from a table created in dBASE IV or dBASE V that contains a memo field, you must first open the table in Visual FoxPro with USE. When you are prompted to convert the file, choose Yes.

If you append from a Visual FoxPro table or a table created in an earlier version of FoxPro, the table you append from can be open in another work area. Records marked for deletion in the table you are appending from are unmarked once the records are appended.

Use the DBF( ) function to append from a temporary read-only cursor created by a SELECT - SQL command. Include the name of the cursor in the DBF( ) function as in the following example:

Copy Code
APPEND FROM DBF('<Cursor Name>')

If the target table uses autoincrementing, APPEND FROM fails if AUTOINCERROR is set to ON, unless the FIELDS option is used to omit the AUTOINC column. Setting AUTOINCERROR to OFF or turning off autoincrementing in the target table by using CURSORSETPROP( ) allows the APPEND FROM to succeed. The target table's autoincrementing field or fields are incremented according to the values specified, and the values in source table are not applied.

Example

In the following example, the customer table is opened, its structure is copied to a table called backup, and backup is then opened. Visual FoxPro then appends all records where country is equal to Finland from the customer table. These records are then copied to a new delimited file called TEMP.TXT.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Open customer table
COPY STRUCTURE TO backup
USE backup
APPEND FROM customer FOR country = 'Finland'
COPY TO temp TYPE DELIMITED
MODIFY FILE temp.txt
USE
DELETE FILE backup.dbf
DELETE FILE temp.txt

See Also

Other Resources

COPY FILE Command
COPY TO Command
EXPORT Command
GETCP( ) Function
IMPORT Command
SET DELETED Command
Commands
Language Reference


APPEND GENERAL Command

Visual FoxPro 9.0 Language Reference
APPEND GENERAL Command
See Also Example

Imports an OLE object from a file and places it into a general field.

APPEND GENERAL GeneralFieldName [FROM FileName]
   [DATA cExpression] [LINK] [CLASS OLEClassName]

Parameters

GeneralFieldName

Specifies the name of the general field in which the OLE object is placed. You can specify a general field in a table open in a noncurrent work area by including the table alias with the field name.
FROM FileName

Specifies the file containing the OLE object. You must include the entire file name, including its extension. If the file is located in a directory other than the current default directory, include the path with the file name.
DATA cExpression

Specifies a character expression that is evaluated and passed as a character string to the OLE object in the general field. The OLE object must be capable of receiving and processing the string. For example, you cannot send a character string to a graphics object such as one created using Paintbrush.
LINK

Creates a link between the OLE object and the file that contains the object. The OLE object appears in the general field but the object's definition remains in the file. If you omit LINK, the OLE object is embedded in the general field.
CLASS OLEClassName

Specifies an OLE class for an OLE object other than the default class. You can specify a class name when the file extension for the file containing the OLE object is different from the default extension and you want to force the behavior for the class. If the default extension can be used by multiple Automation servers, include the class to specify a particular server.

Remarks

If an OLE object already exists in the general field, it is replaced with the OLE object from the file. To remove an OLE object from a general field, issue APPEND GENERAL GeneralFieldName (GeneralFieldName is the name of the general field to clear) without any additional arguments.

For additional information about OLE objects in Visual FoxPro, see Sharing Information and Adding OLE.

Example

The following example imports a Microsoft Excel chart in the Excel directory to a general field named mygenfield.
Copy Code
CREATE TABLE MyGenTbl (mygenfield G)
APPEND BLANK  && Add a blank record
APPEND GENERAL mygenfield FROM C:\EXCEL\BOOK1.XLS CLASS EXCELCHART

See Also

Reference

Image Control (Visual FoxPro)
OLE Container Control

Other Resources

MODIFY GENERAL Command
OLE Bound Control
Commands
Language Reference


APPEND MEMO Command

Visual FoxPro 9.0 Language Reference
APPEND MEMO Command
See Also Example

Copies the contents of a text file to a memo field.

APPEND MEMO MemoFieldName FROM FileName[OVERWRITE] [AS nCodePage]

Parameters

MemoFieldName

Specifies the name of the memo field to which the file is appended.
FROM FileName

Specifies the text file whose contents are copied to the memo field. You must include the entire text file name, including its extension.
OVERWRITE

Replaces the current contents of the memo field with the contents of the file.
AS nCodePage

Specifies the code page of the text file copied to the memo field. Microsoft Visual FoxPro copies the contents of the text file and, as it copies the data to the memo field, automatically converts the data from the code page you specify to the code page of the table containing the memo field. If the table containing the memo field is not marked with a code page, Visual FoxPro automatically converts the data from the code page you specify to the current Visual FoxPro code page. If you specify a value for nCodePage that is not supported, Visual FoxPro generates an error message. You can use GETCP( ) for nCodePage to display the Code Page dialog box, allowing you to specify a code page for the appended table or file. If you omit the AS nCodePage clause or specify 0 for nCodePage, no code page conversion occurs for the text file.

Remarks

The entire text file is appended to the contents of the specified memo field in the current record if overwrite is omitted.

Example

In the following example, the contents of the memo field notes are copied to a file called Test.txt. Test.txt is then appended to the contents of the memo field. Finally, the contents of Test.txt replace the current contents of the memo field.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE employee  && Open Employee table
WAIT WINDOW 'Employee notes memo field - press ESC' NOWAIT
MODIFY MEMO notes NOEDIT  && Open the notes memo field
COPY MEMO notes TO test.txt  && Create test file from memo field
WAIT WINDOW 'TEST.TXT text file - press ESC' NOWAIT
MODIFY FILE test.txt NOEDIT && Open the text file
WAIT WINDOW 'Employee notes now appended - press ESC' NOWAIT
APPEND MEMO notes FROM test.txt  && Add contents of text file
MODIFY MEMO notes NOEDIT  && Display memo field again
WAIT WINDOW 'Overwrite Employee notes- press ESC' NOWAIT
APPEND MEMO notes FROM test.txt OVERWRITE  && Replace notes
MODIFY MEMO notes NOEDIT NOWAIT
DELETE FILE test.txt

See Also

Other Resources

COPY MEMO Command
GETCP( ) Function
CLOSE MEMO Command
SET WINDOW OF MEMO Command
Commands
Language Reference


APPEND PROCEDURES Command

Visual FoxPro 9.0 Language Reference
APPEND PROCEDURES Command
See Also Example

Appends stored procedures in a text file to the stored procedures in the current database.

APPEND PROCEDURES FROM FileName   [AS nCodePage] [OVERWRITE]

Parameters

FileName

Specifies the name of a text file from which the stored procedures are appended.
AS nCodePage

Specifies the code page of the text file from which the stored procedures are appended. Visual FoxPro copies the contents of the text file and, as it does, automatically convert the contents of the text file to the code page you specify. If you specify a value for nCodePage that is not supported, Visual FoxPro generates an error message. You can use GETCP( ) for nCodePage to display the Code Page dialog box, allowing you to specify a code page for the text file from which the stored procedures are appended. If you omit AS nCodePage, Visual FoxPro copies the contents of the text file from which the stored procedures are appended and, as it does so, automatically converts the contents of the text file to the current Visual FoxPro code page. The current Visual FoxPro code page can be determined with CPCURRENT( ). If nCodePage is 0, Visual FoxPro assumes that the code page of the text file from which the stored procedures are appended is the same as the code page of the current database, and that no conversion to the current Visual FoxPro code page occurs.
OVERWRITE

Specifies that the current stored procedures in the database be overwritten by those in the text file. If you omit OVERWRITE, the current stored procedures in the database are not overwritten, and the stored procedures in the text file are appended to the current stored procedures.

Remarks

APPEND PROCEDURES is not available in a distributed executable file. If your application uses this command, it will generate the error, "Feature is not available." For more information about restricted and distributable Visual FoxPro files, see Distributable and Restricted Visual FoxPro Features and Files

Use APPEND PROCEDURES to programmatically modify stored procedures in a database. A database must be open and current when APPEND PROCEDURES is issued; otherwise Visual FoxPro generates an error message.

Note:
To view or edit stored procedures through the user interface, use the Database Designer.

Example

The following example opens the testdata database. A temporary table named mytable with a single memo field is created, and REPLACE is used to place a stored procedure named MyProcedure in the memo field. COPY MEMO is used to create a temporary text file named Mytemp.txt that contains the contents of the memo field.

APPEND PROCEDURES is used to append the stored procedure from the temporary text file to the database. DISPLAY PROCEDURES displays the stored procedures in the database and then the temporary table and text file are erased.

Copy Code
CLOSE DATABASES
* Open the testdata database
OPEN DATABASE (HOME(2) + 'Data\testdata')

* Create a free, temporary table with one memo field called mProcedure
CREATE TABLE mytable FREE (mProcedure M)
APPEND BLANK          && Add a blank record to mytable

* Add PROCEDURE command, name, and carriage return/linefeed to
* memo field
REPLACE mProcedure WITH "PROCEDURE MyProcedure" + CHR(13) + CHR(10)

* Copy contents of memo field to temporary file
COPY MEMO mProcedure TO mytemp.txt
USE             && Close the temporary table

APPEND PROCEDURES FROM mytemp.txt   && Copy procedure to the database
CLEAR

* Display the procedures associated with the current database
DISPLAY PROCEDURES
DELETE FILE mytable.dbf     && Erase temporary table
DELETE FILE mytable.fpt     && Erase temporary table memo file
DELETE FILE mytemp.txt      && Erase temporary text file

See Also

Other Resources

COPY PROCEDURES Command
CREATE TRIGGER Command
DISPLAY PROCEDURES Command
MODIFY PROCEDURE Command
OPEN DATABASE Command
PROCEDURE Command
SET DATABASE Command
Commands
Language Reference


ASSERT Command

Visual FoxPro 9.0 Language Reference
ASSERT Command
See Also Example

Displays a message box when a logical expression evaluates to False (.F.).

When the condition stipulated in the ASSERT command evaluates to False (.F.), an assert message box displays and echoes to the Debug Output window in the Debugger.

Note:
ASSERT is disregarded in applications you distribute.

ASSERT lExpression [MESSAGE cMessageText]

Parameters

lExpression

Specifies the logical expression to evaluate. If lExpression evaluates to a logical False (.F.), a debugging dialog box displays. If lExpression evaluates to a logical True (.T.), the dialog box does not display.
cMessageText

Specifies the text to display in the debugging dialog box. If you omit cMessageText, the default text displays and indicates the line number on which the assertion failed and the procedure containing the assertion.

Remarks

You can specify whether assert messages display by setting the SET ASSERTS command. For more information, see SET ASSERTS Command.

The message box that displays contains Debug, Cancel, Ignore, and Ignore All buttons. The following table describes the action performed when choosing each button.

Button | Description
Debug | Suspends program execution and displays the Debugger window with the Trace window active.
Cancel | Ends program execution.
Ignore | Continues program execution with the line following the ASSERT command.
Ignore All | Continues program execution with the line following the ASSERT command and sets SET ASSERTS to OFF. Disregards subsequent ASSERT commands until SET ASSERTS is set to ON.

Example

Suppose you create a function that expects a nonzero parameter value. The following line of code in the function alerts you if the value of the parameter is 0:
Copy Code
ASSERT nParm != 0 MESSAGE "Received a parameter of 0"

See Also

Other Resources

Debugger Window
Debugging Before Bugs Exist
Commands
Language Reference


AVERAGE Command

Visual FoxPro 9.0 Language Reference
AVERAGE Command
See Also Example

Computes the arithmetic average of numeric expressions or fields.

AVERAGE [ExpressionList]   [Scope] [FOR lExpression1] [WHILElExpression2]
   [TO VarList | TO ARRAY ArrayName]   [NOOPTIMIZE]

Parameters

ExpressionList

Specifies the expressions to average. ExpressionList can be a list of fields from the table separated by commas, or numeric expressions involving fields from the table.
Scope

Specifies the record or range of records to include in the average. Only the records that fall within the range of records specified by the scope are averaged. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. The default scope for AVERAGE is ALL records. Commands that include Scope operate only on the table in the active work area.
FOR lExpression1

Specifies a condition whereby only the records that satisfy the logical condition lExpression are included. This argument allows you to filter out undesired records. Rushmore Query Optimization optimizes an AVERAGE FOR query if lExpression is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For information on Rushmore optimizable expressions, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies that as long as the logical expression lExpression2 evaluates to true (.T.), records are included in the average.
TO VarList

Specifies the list of variables or array elements to which the results of the average are stored.
TO ARRAY ArrayName

Specifies the one-dimensional array to which the results of the average are stored. The one-dimensional array can be created before the execution of AVERAGE. If the array you include in AVERAGE doesn't exist, Visual FoxPro automatically creates it. If the array exists and isn't large enough to contain all the results, Visual FoxPro increases the size of the array automatically to accommodate the information.
NOOPTIMIZE

Disables Rushmore optimization of AVERAGE. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

Remarks

All numeric fields in the selected table are averaged unless you include an optional expression list. The result is displayed on the screen if SET TALK is ON. If SET HEADINGS is ON, the field names or expression involving the field names are displayed above the results.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE orders  && Open order table

CLEAR
AVERAGE Order_Amt  && Calcuate averages of all orders
AVERAGE Order_Amt TO gnAvg  && Store average to memory variable
? 'Average order amount: '
?? gnAvg  && Display the average again

See Also

Other Resources

CALCULATE Command
DIMENSION Command
SET HEADINGS Command
SUM Command
Using Rushmore Query Optimization to Speed Data Access
SET OPTIMIZE Command
Commands
Language Reference


BEGIN TRANSACTION Command

Visual FoxPro 9.0 Language Reference
BEGIN TRANSACTION Command
See Also Example

Begins a transaction. Transactions are supported only for tables in a database. See CREATE DATABASE and ADD TABLE for information on how to create and add tables to a database.

BEGIN TRANSACTION

Remarks

To save any modifications you made and end the transaction, issue END TRANSACTION. If the transaction fails (the server fails, the workstation fails, or you exit Visual FoxPro without committing the transaction) or if you issue ROLLBACK, the file or files in the transaction are restored to their original state.

Transactions can be nested five levels deep. An error is generated if you attempt a sixth level of nesting.

When you modify records in a table that is part of a transaction, other users on the network do not have access (read or write) to the records until you end the transaction.

When other users on the network try to access records you have modified, they must wait until you end your transaction. They receive the message "Record not available ... please wait" until the records become available. Because of this, it is important to keep the length of the transaction to a minimum or conduct the transaction during times when others do not need access.

All IDX index files (non-structural, or non-CDX based, indexes) must be closed during transactions. Only structural indexes are supported within transactions.

The following commands and functions are not supported during a transaction:

Commands and functions |
ADD TABLE | DELETE CONNECTION
APPEND PROCEDURES | DELETE DATABASE
CLEAR ALL | DELETE TRIGGER
CLOSE ALL1 | DELETE VIEW
CLOSE DATABASES1 | MODIFY CONNECTION
COPY INDEXES | MODIFY DATABASE
COPY PROCEDURES | MODIFY PROCEDURE
CREATE CONNECTION | MODIFY VIEW
CREATE DATABASE | REMOVE TABLE
CREATE TRIGGER | RENAME TABLE
CREATE VIEW | REQUERY( )
CREATE SQL VIEW |

1 If CLOSE ALL is issued while a transaction is in progress, all tables in all open databases are closed. However, the databases remain open. Issuing CLOSE DATABASES within a transaction closes all tables in the current database, but the database remains open.

Also, the following commands and functions cannot be issued for a specific table participating in a transaction:

Commands and functions |
ALTER TABLE | MODIFY STRUCTURE
CREATE TABLE | PACK
CURSORSETPROP( ) | REINDEX
DELETE TAG | TABLEREVERT( )
INDEX | ZAP
INSERT |

Example

In the following example, the customer table in the testdata database is opened. Optimistic table buffering is set for the customer table. The contents of the cust_id and company fields are displayed, and then the contents of the company field are replaced within the buffered data.

BEGIN TRANSACTION is issued to start a transaction. The TABLEUPDATE( ) function is used to write the changes to the table. The new contents are displayed, and ROLLBACK is issued to restore the original contents of the company field. The cust_id and company fields are displayed again with the company field containing its original values.
Copy Code
CLEAR
CLOSE DATABASES

* Transactions are only supported within a DBC
OPEN DATABASE (HOME(2) + 'Data\testdata')

SET MULTILOCKS ON      && Required for buffering

USE customer
=CURSORSETPROP("Buffering",5)
? 'The original company field'
LIST FIELDS cust_id, company NEXT 5
REPLACE ALL company WITH "***" && Change field contents

BEGIN TRANSACTION
   =TABLEUPDATE(.T.)
   GO TOP
   ? 'The modified company field'
   LIST FIELDS cust_id, company NEXT 5
   ROLLBACK           && Restore original field contents

=TABLEREVERT(.T.)
GO TOP
? 'The restored company field'
LIST FIELDS cust_id, company NEXT 5

See Also

Reference

MAKETRANSACTABLE( ) Function
ISTRANSACTABLE( ) Function

Other Resources

END TRANSACTION Command
ROLLBACK Command
TXNLEVEL( ) Function
Commands
Language Reference


BLANK Command

Visual FoxPro 9.0 Language Reference
BLANK Command
See Also Example

Clears data from the specified fields in the current record or from all fields in the current record when issued without additional arguments.

BLANK [FIELDS FieldList] [DEFAULT [AUTOINC]] [Scope] [FOR lExpression1]
   [WHILE lExpression2] [NOOPTIMIZE] [IN nWorkArea | cTableAlias]

Parameters

[FIELDS FieldList]

Clears only the fields you specify with FieldList. If you omit the FIELDS clause, all fields in a record are cleared by default. Any field you specify in an unselected work area must be prefaced with the alias of the work area.
Note:
BLANK does not clear field data of a record in another related work area if the record pointer is at the end of the file in the current work area. The record pointer must be on a record in the current work area in order for BLANK to act on the fields in the related record.

[DEFAULT [AUTOINC]]

Initializes specified fields to their default values as specified with the DEFAULT clause for tables that belong to a database and cursors. If no fields are specified, the default values of all fields in the current record are initialized. DEFAULT does not apply to free tables. The AUTOINC keyword specifies to include all automatically incrementing fields. If you omit AUTOINC, the automatically incrementing fields are left intact with their original values.
Note:
Performing updates to automatically incrementing fields requires locking the table header. If you call the BLANK command with the DEFAULT AUTOINC clause with the table file opened in shared mode, is unlocked, and the SETMULTILOCKS command is set to OFF, Visual FoxPro generates an error.

Scope

Specifies a range of records to clear. The default scope for BLANK is the current record (NEXT 1). Only the records that fall within the range are cleared. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. Commands that include the Scope parameter operate only on the table in the active work area. For more information on scope clauses, see Scope Clauses.
FOR lExpression1

Clears field data in records for which lExpression1 evaluates to True (.T.). Rushmore Query Optimization optimizes BLANKFOR if lExpression1 is an optimizable expression. A discussion of Rushmore Query Optimization appears in Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies a condition whereby field data in records is cleared as long as the logical expression lExpression2 evaluates to True (.T.).
NOOPTIMIZE

Prevents Rushmore optimization of BLANK. For more information see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
IN nWorkArea| cTableAlias

Specifies the work area or table alias affected by the BLANK command. Use this clause to specify a work area or a table outside the current work area.

Remarks

To determine if a field in a record is blank, use ISBLANK( ).

To add a new blank record to the end of a table, use APPENDBLANK.

Example

The following example opens the customer table in the testdata database. The contents of the first record are displayed. SCATTER is used to save the contents of the record to an array. The record is cleared with BLANK, and the contents of the record are displayed again. GATHER is used to restore the original record contents, and the restored record contents are displayed again.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table

CLEAR
DISPLAY  && Displays the current record
SCATTER TO gaCustomer  && Create array with record contents
BLANK  && Clear the record
DISPLAY  && Displays the blank record
GATHER FROM gaCustomer  && Restore original record contents
DISPLAY  && Display the restored record

See Also

Other Resources

APPEND Command
EMPTY( ) Function
ISBLANK( ) Function
REPLACE Command
SET OPTIMIZE Command
Using Rushmore Query Optimization to Speed Data Access
Commands
Language Reference


BROWSE Command

Visual FoxPro 9.0 Language Reference
BROWSE Command
See Also

Opens the Browse window and displays records from the current or selected table.

BROWSE [FIELDS FieldList] [FONT cFontName [, nFontSize [, nFontCharSet]]]
   [STYLE cFontStyle] [FOR lExpression1 [REST]] [FORMAT]
   [FREEZE FieldName] [KEY eExpression1 [, eExpression2]] [LAST | NOINIT]
   [LOCK nNumberOfFields] [LPARTITION] [NAME ObjectName] [NOAPPEND]
   [NOCAPTIONS] [NODELETE] [NOEDIT | NOMODIFY] [NOLGRID] [NORGRID]
   [NOLINK] [NOMENU] [NOOPTIMIZE] [NOREFRESH] [NORMAL] [NOWAIT]
   [PARTITION nColumnNumber [LEDIT] [REDIT]]
   [PREFERENCE PreferenceName] [SAVE] [TIMEOUT nSeconds]
   [TITLE cTitleText] [VALID [:F] lExpression2 [ERROR cMessageText]]
   [WHEN lExpression3] [WIDTH nFieldWidth] [WINDOW WindowName1]
   [IN [WINDOW] WindowName2 | IN SCREEN] [COLOR SCHEME nSchemeNumber]

Parameters

FIELDS FieldList

Specifies the fields that appear in the Browse window. The fields are displayed in the order specified in FieldList. You can include fields from other related tables in the field list. When you include a field from a related table, preface the field name with its table alias and a period. If you omit FIELDS, all the fields in the table are displayed in the order they appear in the table structure.
FONT cFontName[, nFontSize [, nFontCharSet]]

Specifies the Browse window's font and font size. The character expression cFontName specifies the name of the font, and the numeric expression nFontSize specifies the font size. You can specify a language script with nFontCharSet. See the GETFONT( ) Function for a list of available language script values. For example, the following clause specifies 16-point Courier font for the fields displayed in a Browse window:
Copy Code
FONT 'Courier',16
If you include the FONT clause but omit the font size nFontSize, a 10-point font is used in the Browse window. If you omit the FONT clause, 8-point MS Sans Serif is used. If the font you specify is not available, a font with similar font characteristics is substituted.
STYLE cFontStyle

Specifies the Browse window's font style. If you omit the STYLE clause, the Normal font style is used If the font style you specify is not available, a font style with similar characteristics is substituted or the Normal font style is used.

Character Font style

B

Bold

I

Italic

N

Normal

O

Outline

Q

Opaque

S

Shadow

–

Strikeout

T

Transparent

U

Underline
You can include more than one character to specify a combination of font styles. The following example opens a Browse window and uses an underlined font:
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
IF _WINDOWS
   BROWSE FIELDS contact FONT 'System', 15  STYLE 'NU'
ENDIF
IF _MAC
   BROWSE FIELDS contact FONT 'Geneva', 14  STYLE 'NU'
ENDIF
FOR lExpression1

Specifies a condition whereby only records for which lExpression1 is true are displayed in the Browse window. Rushmore Query Optimization optimizes a query specified with a BROWSE FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For information on Rushmore optimizable expressions, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access. Include FOR to move the record pointer to the first record meeting the condition. Include REST to keep the record pointer at its current position.
REST

Prevents the record pointer from being moved from its current position to the top of the table when a Browse window is opened with the FOR clause. Otherwise, BROWSE positions the record pointer at the top of the table by default.
FORMAT

Specifies the use of a format file to control the display and data-entry format in a Browse window. The format file must first be opened with SET FORMAT. The following information is extracted from the format file and applied to the Browse window:
  • The list of fields to browse

  • All VALID clauses

  • All WHEN clauses

  • All RANGE clauses

  • Field sizes (as specified in PICTURE clauses)

  • All SAY expressions (included as calculated BROWSE fields)

The following example uses a format file to validate data entered into a Browse window. Positions specified with @ ... GET are ignored. The first line creates a BROWSE field (cust_id) that is 5 characters wide and allows the entry of letters and digits only. The second line creates a BROWSE field (company) that cannot contain a blank value and can contain a maximum of 20 alphabetic characters. The third line creates a BROWSE field (contact) into which you enter data only when the field is blank. Here are the contents of the Custentr.fmt format file, which is used to validate data entered into the customer table:
Copy Code
@ 3,0 GET cust_id PICTURE 'NNNNN'
@ 3,0 GET company VALID company != SPACE(40) ;
   PICTURE 'AAAAAAAAAAAAAAAAAAAA'
@ 3,0 GET contact WHEN contact = SPACE(40)

* This is the program that uses the format file
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
SET FORMAT TO custentr.fmt
BROWSE FORMAT
FREEZE FieldName

Permits changes to be made to only one field in the Browse window. You specify this field with FieldName. The remaining fields are displayed but cannot be edited.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE FIELDS phone :H = 'Phone Number:' , ;
   company :H = 'Company:' ;
   FREEZE phone
KEY eExpression1[, eExpression2]

Limits the scope of records that are displayed in the Browse window. With KEY you can specify an index key value (eExpression1) or a range of key values (eExpression1, eExpression2) for the records that are displayed in the Browse window. The table you browse must be indexed, and the index key value or values included in the KEY clause must be the same data type as the index expression of the master index file or tag. For example, the customer table includes a character field containing postal codes. If the table is indexed on the postal code field, you can specify a range of postal codes in the KEY clause. In the following example, only records with postal codes falling within the range of 10,000 to 30,000 are displayed in the Browse window:
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
SET ORDER TO postalcode
BROWSE KEY '10000', '30000'
LAST | NOINIT

Saves any configuration changes made to the appearance of a Browse window. The changes are saved in the FoxUser.dbf file and can include changes to the field list, the size of each field, and the location and size of the Browse window. If you issue BROWSE with the LAST or NOINIT clause, the Browse window opens in the same configuration that was last saved in the FoxUser.dbf file if SET RESOURCE is ON. This restores the Browse window configuration created with the last BROWSE command. If the last BROWSE issued in the Command window included a long list of clauses, issue BROWSE with the LAST or NOINIT option to avoid having to retype the command. For more information on the FoxUser resource file, see SET RESOURCE. If the last Browse window was opened with a BROWSE that included a PREFERENCE clause, BROWSE LAST won't restore the preference. Any Browse window configuration changes you make in the current session aren't saved if you exit BROWSE by pressing CTRL+Q. The LAST and NOINIT clauses are identical; NOINIT provides dBASE compatibility.
LOCK nNumberOfFields

Specifies either a positive number, which indicates the number of fields that you can see in the left partition of the Browse window without tabbing or scrolling, or a negative number, which indicates the number of fields that remain locked in the Browse window when tabbing to the right. The left partition sizes automatically to display the number of fields you specify with nNumberOfFields. A column separator line, which appears 1 pixel wider than the line separating the other columns, indicates the area where the locked columns end and the normal columns begin.
LPARTITION

Specifies that the cursor is placed in the first field in the left Browse window partition. By default, the cursor is placed in the first field in the right partition when the Browse window is opened.
NAME ObjectName

Creates an object reference for the Browse window, allowing you to manipulate the Browse window with object-oriented properties available for the Grid control. For additional information about object-oriented programming in Visual FoxPro, see, Object-Oriented Programming. For additional information about the Grid control properties that you can specify for a Browse window created with the NAME clause, see Grid Control.
NOAPPEND

Prevents the user from adding records to the table by pressing CTRL+Y or by choosing Append Record from the Table menu.
Note:
Including NOAPPEND doesn't prevent you from appending a record from within a routine (created with VALID, WHEN, or ON KEY LABEL) while in the Browse window.

NOCAPTIONS

Specifies to always use the field name of a table or view for the column headers, even when the database contains a friendly caption for the table field. This clause applies only to tables or views in a database.
NODELETE

Prevents records from being marked for deletion from within a Browse window. By default, a record can be marked for deletion by pressing CTRL+T, choosing Toggle Delete from the Table menu, or by clicking in the leftmost column of the record to be deleted.
NOEDIT | NOMODIFY

Prevents a user from modifying the table. NOEDIT and NOMODIFY are identical. If you include either clause, you can browse or search the table, but you cannot edit it. However, you can append and delete records.
NOLGRID

Removes the field gridlines in the left partition of the Browse window.
NORGRID

Removes the field gridlines in the right partition of the Browse window.
NOLINK

Unlinks the partitions in a Browse window. By default, the left and right partitions of the Browse window are linked together so that when you scroll through one partition, the other partition scrolls.
NOMENU

Removes the Table menu title from the system menu bar, preventing access to the Browse menu.
NOOPTIMIZE

Disables Rushmore Query Optimization of BROWSE. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
NOREFRESH

Prevents the Browse window from being refreshed. Browse windows are refreshed at the rate determined by SET REFRESH. NOREFRESH is useful with read-only files and improves performance.
NORMAL

Opens the Browse window with its normal default settings, such as its colors, size, position, title, and control options (GROW, FLOAT, ZOOM, and so on). If you omit NORMAL, and the current output window is a user-defined window with its own settings, the Browse window assumes those user-defined settings also.
NOWAIT

Continues program execution immediately after the Browse window is opened. The program doesn't wait for the Browse window to be closed but continues executing on the program line immediately following the program line containing BROWSE NOWAIT. If you omit NOWAIT when BROWSE is issued from within a program, a Browse window is opened and program execution pauses until the Browse window is closed. NOWAIT is available only from within a program. Including NOWAIT when issuing BROWSE from the Command window has no effect.
PARTITION nColumnNumber

Splits a Browse window into left and right partitions with nColumnNumber specifying the column number of the split bar. For example, if nColumnNumber is 20, the split bar is placed in column 20 of the Browse window.
LEDIT

Specifies that the left partition of the Browse window appear in Edit mode.
REDIT

Specifies that the right partition of the Browse window appear in Edit mode. This example opens a Browse window with the split bar placed in column 20 and the right partition open in Edit mode. Include both keywords to open both partitions in Edit mode.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE PARTITION 20 REDIT
PREFERENCE PreferenceName

Saves a Browse window's attributes and options for later use. Unlike LAST, which restores the Browse window as it appeared in the previous session, PREFERENCE saves a Browse window's attributes indefinitely in the FoxUser.dbf resource file. Preferences can be retrieved at any time. Issuing BROWSE with the specified preference name for the first time creates an entry in the FoxUser.dbf file that saves the Browse window configuration. Issuing BROWSE later with the same preference name restores the Browse window to that preference state. When the Browse window is closed, the preference is updated. Preference names can be up to 10 characters long, must begin with a letter or an underscore, and can contain any combination of letters, numbers and underscores. Once you have a preference the way you like it, you can prevent it from being changed. Close the Browse window, issue SET RESOURCE OFF, open the FoxUser.dbf file as a table, and change the record containing the preference to read-only by changing the value of the logical field READONLY to true (.T.). For more information about the FoxUser.dbf resource file, see SET RESOURCE. If you exit a Browse window by pressing CTRL+Q, no Browse window changes are saved to the resource file.
SAVE

Keeps the Browse window and any of its memo field text-editing windows active and visible (open). You can then return to the Browse window after cycling through other open windows with the keyboard or the mouse. SAVE is available only from within a program. SAVE has no effect when included with BROWSE in the Command window because BROWSE SAVE is always the default in the interactive mode.
TIMEOUT nSeconds

Specifies how long a Browse window waits for input. The numeric expression nSeconds specifies how many seconds can elapse without any input before the Browse window automatically closes. TIMEOUT is available only from within a program; it has no effect when you issue BROWSE from the Command window. In the following example, the Browse window is closed if no input occurs in 10 seconds.
Copy Code
DEFINE WINDOW wBrowse FROM 1,1 TO 24,40 ;
   CLOSE ;
   GROW ;
   COLOR SCHEME 10
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE WINDOW wBrowse ;
   FIELDS phone :H = 'Phone Number:' , ;
   company :H = 'Company:' ;
   TIMEOUT 10
RELEASE WINDOW wBrowse
TITLE cTitleText

Overrides the default table name or alias that appears in the Browse window title bar with the title you specify with cTitleText. Otherwise, the name or alias of the table being browsed appears in the title bar. If you issue BROWSE WINDOW to place the Browse window in a user-defined window, the Browse window's title replaces the user-defined window's title.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE;
   TITLE 'My Browse Window' ;
   FIELDS phone :H = 'Phone Number' , ;
   company :H = 'Company:'
VALID lExpression2

Performs record-level validation in a Browse window. The VALID clause is executed only if a change is made to the record and you attempt to move the cursor to another record. The VALID clause is not executed if the only change is to a memo field. If VALID returns a value that is true (.T.), the user can move the cursor to another record. If VALID returns a false value (.F.), the cursor remains in the current field and Visual FoxPro generates an error message. If VALID returns 0, the cursor remains in the current field, and an error message isn't displayed. The VALID clause shouldn't be confused with the verify option (:V), which enables field-level validation.
:F

Forces the VALID clause to execute before the user moves the cursor to the next record. In this case, VALID is executed even if the record isn't changed.
ERROR cMessageText

Specifies an error message that overrides the system default error message. Visual FoxPro displays cMessageText when VALID returns false (.F.).
WHEN lExpression3

Evaluates a condition when the user moves the cursor to another record. If lExpression3 evaluates to true (.T.), the user can modify the record moved to. If lExpression3 evaluates to false (.F.) or 0, the record the user moves to becomes read-only and cannot be modified. The WHEN clause isn't executed when another window is activated.
WIDTH nFieldWidth

Limits the number of characters displayed for all fields in a Browse window to nFieldWidth. The contents of a field can be scrolled horizontally using the LEFT ARROW and RIGHT ARROW keys or the horizontal scroll bar. Including the WIDTH clause doesn't change the size of fields in the table; it alters only the way the fields are displayed in the Browse window. If a width has been specified for an individual field with the FIELDS clause, it overrides the width specified with the WIDTH clause for that field.
WINDOW WindowName1

Specifies a user-defined window whose characteristics the Browse window assumes. For example, if the user-defined window is created with the FLOAT clause, the Browse window can be moved. The specified window doesn't have to be active or visible, but it must be defined.
IN [WINDOW] WindowName2

Specifies the parent window within which the Browse window is opened. The Browse window doesn't assume the characteristics of the parent window. A Browse window activated inside a parent window cannot be moved outside the parent window. If the parent window is moved, the Browse window moves with it. To access the Browse window, the parent window must first be defined with DEFINE WINDOW and must be active and visible.
IN SCREEN

Explicitly places a Browse window on the main Visual FoxPro window when a user-defined window is active.
COLOR SCHEME nSchemeNumber

Specifies the number of a color scheme used for the Browse window's colors. The Browse window assumes the color scheme established using the Windows Color Control Panel.

Remarks

A Browse window allows you to view records in a table, edit those records, and append additional records. Visual FoxPro allows you to have several Browse windows open at the same time.

If you press ESC to exit a Browse window, changes made to the last field you modified are discarded. However, if you move to another record after modifying a field, your changes to the field are saved.

The field list can specify any combination of fields or calculated fields. The syntax of the field list is:

Copy Code
FieldName1
   [:R]
   [:nColumnWidth]
   [:V = lExpression1 [:F] [:E = cMessageText]]
   [:P = cFormatCodes]
   [:B = eLowerBound, eUpperBound [:F]]
   [:H = cHeadingText]
   [:W = lExpression2]
   [, FieldName2 [:R]...]

Calculated Fields The field list can contain statements for creating calculated fields. A calculated field contains read-only data created with an expression. The expression can take any form, but it must be a valid Visual FoxPro expression.

The format of the statement you use to create a calculated field is:

CalculatedFieldName = eExpression

The following example creates a calculated field called location:

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE FIELDS location = ALLTRIM(city) + ', ' + country

city and country are the names of fields from the currently selected table.

The FIELDS clause field list includes options that enable special handling of fields displayed in a Browse window:

:R

Specifies that the field is read-only. The data it contains can be viewed but not edited.

In the following example, a Browse window is opened with the cust_id and company fields. The cust_id field is read-only and cannot be changed.

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE FIELDS cust_id:R, company
: nColumnWidth

Specifies the display size for a field in columns. The value of :nColumnWidth doesn't affect the size of the field in the table; it only alters the way the field appears in the Browse window.
:V = lExpression1[:F] [:E = cMessageText]

Lets you perform field-level data validation within the Browse window. If lExpression1 evaluates to true (.T.) when you move the cursor from a field, the data input into the field is considered correct and the cursor moves to the next field. If lExpression1 evaluates to false (.F.), the data input is considered incorrect, the cursor remains in the field and an error or exception is raised. If lExpression1 evaluates to 0, the data input is considered incorrect and the cursor remains in the field but no error message appears. The verify option is not executed for memo fields. By default, lExpression1 is evaluated only when the field is modified. To force verification, include the :F option. You can display your own error message by including the :E option described below.
:F

Determines whether the expression in the verify option is evaluated when you move the cursor out of a field or another window is activated. If :F is not included, lExpression1 is evaluated only if changes are made to the field. If :F is included, lExpression1 is evaluated even if the field isn't modified.
:E = cMessageText

If the validation expression :V = lExpression1 evaluates to true (.T), the cursor leaves the field normally. If the expression evaluates to false (.F.), the cursor remains in the field, and Visual FoxPro generates an error message. If the error option (:E) is included, cMessageText appears instead of the system error message. cMessageText appears only if SET NOTIFY is ON. The bell is sounded if SET BELL is ON. If :V = lExpression1 evaluates to 0, no message appears and the cursor remains in the field being validated. This option lets you display your own error messages in validation routines. The following example opens the products table and displays the product_id and prod_name fields. The product_id field is a numeric field that will accept up to five numbers. For purposes of this example, we consider a product_id greater than 100 to be invalid. :V specifies the validation criteria. :F forces the validation check to be performed whether the data is changed or not. :E replaces the Visual FoxPro system error message with a user-defined error message. In Visual FoxPro, the error message appears in the status bar at the bottom of the main Visual FoxPro window. Press ESC to close the Browse window.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
IF _WINDOWS OR _MAC
   SET STATUS BAR ON
ENDIF
USE products
BROWSE FIELDS in_stock :V = in_stock < 100 ;
   :F ;
   :E = 'The stock amount must be less than 100'
:P = cFormatCodes

If you include a FIELDS clause, you can also specify a picture option (:P) for each field in the list. The picture option lets you create a list of codes that controls the display and input of data for each field in a Browse window. cFormatCodes is the list of codes. The following example uses the picture option to allow only numeric data in a specific format to be entered in the unit_price field:
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
BROWSE FIELDS unit_price :P = '99,999.99'
See the Format Property and InputMask Property properties for more information about picture option codes.
:B = eLowerBound, eUpperBound[:F]

Specifies a set of boundaries between which data in a field must fall. The boundary expressions eLowerBound and eUpperBound must match the data type of the field. They cannot be user-defined functions. If the data entered doesn't fall between eLowerBound and eUpperBound, a system error message appears indicating the range within which the data must fall. By default, the data you enter is checked against the boundary values only if you make a change to the contents of the field. To force checking against the boundary values, include the forced validation option (:F). The following example ensures that the value in the in_stock field falls between 1 and 100. Press ESC to close the Browse window.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
BROWSE FIELDS in_stock :B = 1, 100    :F
:H = cHeadingText

Replaces the default field names with your own headings, which you specify with cHeadingText. By default, field names are used as the column headings in the Browse window. The following example provides user-defined headings for the displayed fields.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
BROWSE FIELDS prod_name :H = 'Product Name:', ;
   unit_price :H = 'Price per Unit:'
:W = lExpression2

Determines whether the cursor can be moved to a field. If lExpression2 evaluates to false (.F.), moving the cursor to the field is prohibited. If lExpression2 evaluates to true (.T.), the cursor can be moved to the field. User-defined functions are supported in lExpression2. If moving the cursor to all fields is prohibited, the current record is marked read-only. This occurs only when every field contains a WHEN clause that evaluates to false.

SET SKIP Support SET SKIP lets you establish a one-to-many relationship between two tables. For each record in the parent table, there can be multiple related records in the child table. If you create a one-to-many relationship, you may use BROWSE to view records from both the parent and child tables.

The parent record appears once, along with the first matching record from the child table. Any subsequent matching records are displayed in the rows following the parent record and first matching child record. The fill character for repeated parent information depends on the current Browse window font.

If the record pointer is positioned on a parent record, you can move the pointer through the parent records in the Browse window by pressing CTRL+DOWN ARROW to move to the next parent record or CTRL+UP ARROW to move to the previous parent record. For more information on creating one-to-many relationships, see SET SKIP.

The FIELDS clause field list contains records from both the parent and child tables. The names of fields are prefaced with their table alias (orders or customer) and a period.

Copy Code
CLEAR
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer ORDER cust_id IN 0   && Parent table
USE orders ORDER cust_id IN 0  && Child table
SELECT customer     && Back to parent work area
SET RELATION TO cust_id INTO orders     && Establish relationship
SET SKIP TO orders  && One-to-many relationship
WAIT WINDOW 'Scroll to see shipping dates for each customer' NOWAIT
BROWSE FIELDS customer.cust_id :H='Customer Number', ;
   customer.city :H='Customer City', orders.shipped_on

Useful Functions Several Visual FoxPro functions return useful information about a Browse window.

Function | Description
VARREAD( ) | Returns the name of the field the cursor is in for the active Browse window.
RECNO( ) | Returns the record number of the selected record in the active Browse window.

See Also

Tasks

How to: Add Records to Tables

Other Resources

CHANGE Command
EDIT Command
Grid Control
SET SKIP Command
WTITLE( ) Function
Commands
Language Reference


BUILD APP Command

Visual FoxPro 9.0 Language Reference
BUILD APP Command
See Also

Creates a standard application (.app) file from a Visual FoxPro project.

Note:
Before using the BUILD APP command, make sure that the project contains all files needed for the application. If required files are missing during the build, Visual FoxPro generates an error. For more information, see Working with Projects.

BUILD APP APPFileName FROM ProjectName [RECOMPILE]

Parameters

APPFileName

Specifies the file name of the application to build. The default file name extension is .app.
Note:
If an executable (.exe) file exists with the same root file name as the .app file you create, the .exe file is deleted.

FROM ProjectName

Specifies the name of the project from which the application is built.
[RECOMPILE]

Specifies that the project be compiled before the application file is built. All program and format files; form, label, report, and visual class library source code; and stored procedures in databases in the project are compiled.

See Also

Other Resources

How to: Build Applications
BUILD EXE Command
CREATE PROJECT Command
MODIFY PROJECT Command
BUILD PROJECT Command
Build Method
Commands
Language Reference


BUILD DLL Command

Visual FoxPro 9.0 Language Reference
BUILD DLL Command
See Also

Creates a single-threaded Windows dynamic-link library (.dll), or Automation server, using class definitions from a Visual FoxPro project.

BUILD DLL DLLFileName FROM ProjectName [RECOMPILE]

Parameters

DLLFileName

Specifies the file name of the dynamic-link library to build. The default file name extension is .dll.
FROM ProjectName

Specifies the name of the project from which the dynamic-link library is built. The project must contain a class designated as OLEPUBLIC or an error message is displayed. To designate a class as OLEPUBLIC in program code, include the OLEPUBLIC keyword in DEFINECLASS. To designate a class as OLEPUBLIC in the Class Designer, choose Class Info from the Class Menu and select the OLE Public check box.
[RECOMPILE]

Specifies that the project be compiled before the dynamic-link library is built. All program and format files; form, label, report, and visual class library source code; and stored procedures in databases in the project are compiled.

Remarks

BUILD DLL registers the server automatically in the Server Classes list on the Servers tab of the Project Information dialog box.

See Also

Other Resources

How to: Build Applications
Automation and COM Servers
BUILD EXE Command
Build Method
BUILD PROJECT Command
CREATE PROJECT Command
MODIFY PROJECT Command
Commands
Language Reference


BUILD EXE Command

Visual FoxPro 9.0 Language Reference
BUILD EXE Command
See Also

Creates an executable (.exe) file from a Visual FoxPro project.

Note:
The .exe file operates with the Visual FoxPro dynamic-link (.dll) libraries, VFPVersionNumberR.dll and VFPVersionNumberRENU.dll, which you need to distribute with your application to provide a complete Visual FoxPro run-time environment for your application. VersionNumber represents the version number of Visual FoxPro that you use to create the .exe file. These files are located in the ..\Program Files\Common Files\Microsoft Shared\VFP directory.

For more information, see VFP9R.DLL Run-Time Library, VFP9T.DLL Run-Time Library, Preparation for Distributing Applications, and Managing Files in an International Application.

BUILD EXE EXEFileName FROM ProjectName [RECOMPILE]

Parameters

EXEFileName

Specifies the name of the executable file to create. The default file name extension is .exe.
Note:
If an application (.app) file exists with the same root file name as the .exe file you create, the .app file is deleted.

FROM ProjectName

Specifies the name of the project from which the executable file is built.
[RECOMPILE]

Specifies that the project be compiled before the executable file is built. All program and format files; form, label, report, and visual class library source code; and stored procedures in databases in the project are compiled.

Remarks

If the .exe file contains OLEPUBLIC class definitions, BUILD EXE automatically registers the OLEPUBLIC class definitions in the system registry. OLEPUBLIC class definitions appear in the Server Classes list box on the Servers tab of the Project Information dialog box. BUILD EXE creates also registration (.vbr) and type library (.tlb) files with the same name as the .exe file. The .vbr file makes it possible for you to register class definitions in the system registry when the .exe file is moved to a different computer. The .tlb file is for use with object browsers. For more information about registering OLEPUBLIC class definitions in an executable file, see Sharing Information and Adding OLE.

Visual FoxPro includes support for applications that are generated by the build process to detect whether they are running on a Terminal Server and prevents loading of unnecessary dynamic-link library (.dll) files that can impact performance.

See Also

Other Resources

How to: Build Applications
BUILD DLL Command
BUILD APP Command
BUILD MTDLL Command
BUILD PROJECT Command
Build Method
Commands
Language Reference


BUILD MTDLL Command

Visual FoxPro 9.0 Language Reference
BUILD MTDLL Command
See Also

Creates a multithreaded Windows dynamic-link library (.dll), or Automation server, using class definitions from a project.

BUILD MTDLL MTDLLFileName FROM ProjectName [RECOMPILE]

Parameters

MTDLLFileName

Specifies the file name of the dynamic-link library to build. The default file name extension is .dll.
FROM ProjectName

Specifies the name of the project from which the dynamic-link library is built. The project must contain a class designated as OLEPUBLIC or an error message is displayed. To designate a class as OLEPUBLIC in program code, include the OLEPUBLIC keyword in DEFINE CLASS. To designate a class as OLEPUBLIC in the Class Designer, choose Class Info from the Class Menu and select the OLE Public check box.
[RECOMPILE]

Specifies that the project be compiled before the dynamic-link library is built. All program and format files; form, label, report, and visual class library source code; and stored procedures in databases in the project are compiled.

Remarks

BUILD MTDLL registers the server automatically in the Server Classes list on the Servers tab of the Project Information dialog box.

The Visual FoxPro runtime that creates multithreaded .dll files creates in-process servers only. Many user input commands and functions are not supported. For more information, see Interoperability and the Internet.

See Also

Other Resources

How to: Build Applications
Automation and COM Servers
BUILD DLL Command
BUILD EXE Command
BUILD PROJECT Command
Build Method
CREATE PROJECT Command
MODIFY PROJECT Command
Commands
Language Reference


BUILD PROJECT Command

Visual FoxPro 9.0 Language Reference
BUILD PROJECT Command
See Also

Creates a Visual FoxPro project table (.pjx) file by opening, processing, and including one or more specified program, menu, report, label, form, or library files in the project. A Visual FoxPro project consists of a .pjx file and a project memo (.pjt) file. You can also use BUILD PROJECT to rebuild a project.

BUILD PROJECT ProjectFileName [RECOMPILE]
   [FROM ProgramName1 | MenuName1 | ReportName1 | LabelName1 |
            FormName1 | LibraryName1 [, ProgramName2 | MenuName2 |
            ReportName2 | LabelName2 | FormName2 | LibraryName2 ...]]

Parameters

ProjectFileName

Specifies the name of the project file to create.
[RECOMPILE]

Compiles all files in the project. If RECOMPILE is omitted, only the files that have been modified are compiled when the project is built.
[FROM ProgramName1| MenuName1| ReportName1| LabelName1| FormName1| LibraryName1]

Specifies the files to include in the project. You can specify one or more program, menu, report, label, form, or library files. By default, the first executable program or menu file in the FROM clause is the master program file.
Tip:
To rebuild a project, omit the FROM clause. Visual FoxPro refreshes the files in the specified project.

Remarks

A Visual FoxPro project keeps track of files in the project as well as the dependencies, references, and relationships between them. After you specify files to include in a project, Visual FoxPro ensures that the application project is based on the latest source files. Each file included in the project contains a time and date stamp so you can refresh the project when you make changes to files in the project or when dependencies change. This practice helps ensure that any applications created from a project always use the most recent source files. When Visual FoxPro encounters a program, menu, or form file when creating a project using BUILD PROJECT, it locates the corresponding compiled file and compares the time and date stamp of the two files. If the time and date stamp of the source file is later than that of the compiled file, Visual FoxPro recompiles the source file.

When you use BUILD PROJECT, Visual FoxPro reports unresolved references and other errors, which do not prevent the project from being created. This makes it possible for you to build a project even when all the necessary pieces have not yet been created or are not available. You can correct unresolved references or other errors later by refreshing the project file or by manually modifying the information stored in the project file using MODIFY PROJECT.

You can create the following redistributable application files from projects: application (.app) files, executable (.exe) files, or dynamic-link library (.dll) files. However, before you create redistributable application files, you should test your project. For more information, see How to: Test a Project. For more information on building redistributable application files, see Compiling an Application.

See Also

Other Resources

Working with Projects
CREATE PROJECT Command
MODIFY PROJECT Command
BUILD APP Command
BUILD EXE Command
BUILD DLL Command
BUILD MTDLL Command
Build Method
EXTERNAL Command
Commands
Language Reference


CALCULATE Command

Visual FoxPro 9.0 Language Reference
CALCULATE Command
See Also Example

Performs financial and statistical operations on fields in a table or on expressions involving fields.

CALCULATE eExpressionList [Scope] [FOR lExpression1] [WHILE lExpression2]
   [TO VarList | TO ARRAY ArrayName] [NOOPTIMIZE]
   [IN nWorkArea | cTableAlias]

Parameters

eExpressionList

Specifies the expressions that can contain any combination of the following functions:
AVG(nExpression)
CNT( ) or COUNT( )
MAX(eExpression)
MIN(eExpression)
NPV(nExpression1, nExpression2 [, nExpression3])
STD(nExpression)
SUM(nExpression)
VAR(nExpression)
Functions in the expression list eExpressionList are separated by commas. These functions are specific to CALCULATE and are described in detail later in this section. They should not be confused with similarly named independent functions. For example, CALCULATE MIN( ) is not the same as MIN( ).
Scope

Specifies a range of records used in the calculation. Only the records that fall within the range of records are included in the calculation. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information, see Scope Clauses. Commands that include Scope operate only on the table in the active work area. The default scope for CALCULATE is ALL records.
FOR lExpression1

Specifies that only the records that satisfy the logical condition lExpression1 are included in the calculation. Including a FOR clause conditionally includes records in the calculation, filtering out undesired records. Rushmore Query Optimization optimizes a CALCULATE ... FOR query if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For information on Rushmore optimizable expressions, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies a condition whereby records are included in the calculation as long as the logical expression lExpression2 evaluates to true (.T.).
TO VarList

Specifies one or more variables to which the results of the calculation are stored. If a variable you specify does not exist, Visual FoxPro automatically creates the variable with the name you specify.
TO ARRAY ArrayName

Specifies an array name to which the results of the calculation can be stored. If the array name you specify does not exist, Visual FoxPro automatically creates an array with the name you specify. If the array exists and is not large enough to contain all the results of the calculation, Visual FoxPro automatically increases the size of the array to accommodate the information. If an existing array is larger than necessary, additional elements are left unchanged. Results are stored to the array elements in the order they are specified in the CALCULATE command.
NOOPTIMIZE

Disables Rushmore optimization of CALCULATE. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
AVG( nExpression)

Computes the arithmetic mean of nExpression. Only records meeting the Scope and/or optional FOR or WHILE conditions are included in the result.
CNT( ) or COUNT( )

Returns the number of records in the table. Only records meeting the Scope and/or optional FOR or WHILE conditions are included in the result.
MAX( eExpression)

Returns the highest or latest value of eExpression. Within the MAX( ) clause, you can specify any character, date, datetime, numeric, float, integer, double, or currency field, or any expression using fields of these types. Only records meeting the Scope and/or optional FOR or WHILE conditions are included in the result.
MIN( eExpression)

Returns the lowest or earliest value of eExpression. Any character, date, datetime, numeric, float, integer, double, or currency field, or any valid expression using fields of these types, can be included in eExpression. Only records meeting the Scope and/or optional FOR or WHILE conditions are included in the result.
NPV( nExpression1, nExpression2[, nExpression3])

Computes the net present value of a series of future cash flows discounted at a constant periodic interest rate. nExpression1 specifies the interest rate expressed as a decimal value. nExpression2 specifies a field, field expression, or a numeric expression representing a series of cash flows. Each cash flow can be either positive or negative. In cases where nExpression2 is a field, the value for each record in the field is considered a cash flow. nExpression3 specifies an optional initial investment. If the initial investment is not included, then the initial investment is assumed to occur at the end of the first period. This initial investment is the first record in the field and is negative to represent a cash outflow. Only records meeting the Scope and/or optional FOR or WHILE conditions are included in the result.
STD( nExpression)

Computes the standard deviation of nExpression. The standard deviation measures the degree to which the values of fields or expressions involving fields differ from the average of all the values. The smaller the standard deviation, the less the values vary from the average. Only records meeting the Scope and/or optional FOR or WHILE conditions are included in the result.
SUM( nExpression)

Totals the values of nExpression. Only records meeting the Scope and/or optional FOR or WHILE conditions are included in the result.
VAR( nExpression)

Computes the variance from the average of nExpression. The variance is the standard deviation squared. The smaller the variance, the less the values vary from the average. Only records meeting the Scope and/or optional FOR or WHILE conditions are included in the result.
IN nWorkArea| cTableAlias

Specifies the workarea or table alias affected by the CALCULATE command. Use this clause to specify a workarea or a table outside the current work area.

Remarks

Records containing the null value are not included in the operations that CALCULATE performs.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE orders  && Open Orders table

SET TALK ON
CLEAR
CALCULATE AVG(order_amt), MIN(order_amt), MAX(order_amt)
CALCULATE STD(order_amt), VAR(order_amt) TO gnStd, gnVar

See Also

Other Resources

AVERAGE Command
COUNT Command
DIMENSION Command
FV( ) Function
MAX( ) Function
MIN( ) Function
PAYMENT( ) Function
PV( ) Function
SUM Command
Commands
Language Reference


CANCEL Command

Visual FoxPro 9.0 Language Reference
CANCEL Command
See Also Example

Ends execution of the current Visual FoxPro program file.

CANCEL

Remarks

Control returns to the Command window when Visual FoxPro is being used interactively. If a distributed run-time application is running, CANCEL terminates the application and control returns to Windows. If a program is executing in Visual FoxPro during design time, CANCEL terminates the program and control returns to the Command window.

Executing CANCEL releases all private variables.

Example

The following example simulates a program execution loop. Each time through the loop you are asked if you want to continue. If you press the Cancel button, CANCEL stops program execution.
Copy Code
DO WHILE .T.
   IF MESSAGEBOX("Do you want to continue?",36) <> 6
      CANCEL
   ENDIF
ENDDO

See Also

Other Resources

QUIT Command
RESUME Command
RETURN Command
SUSPEND Command
Cancel Property
SQLCANCEL( ) Function


CD | CHDIR Command

Visual FoxPro 9.0 Language Reference
CD | CHDIR Command
See Also Example

Changes the default Visual FoxPro directory to the directory you specify.

CD cPath | CHDIR cPath

Parameters

cPath

Specifies one of the following:
  • A drive designator

  • A drive designator with a directory

  • A child directory

  • Any of the above using MS-DOS shorthand notation ( \ or ..). When you include .. to change to the parent directory, you must include a space between CD or CHDIR and the two periods.

Remarks

Use CD or CHDIR to specify the default Visual FoxPro directory. Visual FoxPro searches for files in the default Visual FoxPro directory. If Visual FoxPro cannot find a file in the default directory, it then searches the Visual FoxPro path if one has been specified. Use SET PATH to specify the Visual FoxPro path.

If you create a file and do not specify where to place it, the file is placed in the default Visual FoxPro directory.

You can locate hidden or system directories using CD and CHDIR. For more information, see FILE( ) Function and DIRECTORY( ) Function.

The CD and CHDIR commands are not supported in either single or multithreaded DLL servers. These commands change the default directory of the entire process, so all threads which are part of the process are affected. Use the SET PATH command in DLL servers, in place of SET DEFAULT.

Example

The following example uses SET DEFAULT to change the default Visual FoxPro directory to the startup directory. It uses MKDIR to create a new directory named mytestdir, and CHDIR changes to the mytestdir directory. GETDIR( ) shows you the directory structure in the Select Directory dialog box. You can then use SET DEFAULT to move your position back to the startup directory, RMDIR to remove the newly created directory, and GETDIR( ) to display the original directory structure.
Copy Code
SET DEFAULT TO HOME()
MKDIR mytestdir
CHDIR mytestdir  = GETDIR()
SET DEFAULT TO HOME()
RMDIR mytestdir  = GETDIR()

See Also

Other Resources

DIR or DIRECTORY Command
DIRECTORY( ) Function
GETDIR( ) Function
HOME( ) Function
MD | MKDIR Command
RD | RMDIR Command
SET DEFAULT Command
SET PATH Command
SYS(5) - Default Drive
SYS(2003) - Current Directory
SYS(2004) - Visual FoxPro Start Directory
Commands
Language Reference


CHANGE Command

Visual FoxPro 9.0 Language Reference
CHANGE Command
See Also

Displays fields for editing.

CHANGE [FIELDS FieldList] [Scope]
[FOR lExpression1] [WHILE lExpression2]
[FONT cFontName [, nFontSize [, nFontCharSet]]] [STYLE cFontStyle]
[FREEZE FieldName]
[KEY eExpression1 [, eExpression2]] [LAST | NOINIT] [LPARTITION]
[NAME ObjectName] [NOAPPEND] [NOCAPTION] [NOCLEAR] [NODELETE]
[NOEDIT | NOMODIFY] [NOLINK] [NOMENU] [NOOPTIMIZE] [NORMAL] [NOWAIT]
[PARTITION nColumnNumber [LEDIT] [REDIT]] [PREFERENCE PreferenceName]
[REST] [SAVE] [TIMEOUT nSeconds] [TITLE cTitleText]
[VALID [:F] lExpression3 [ERROR cMessageText]] [WHEN lExpression4]
[WIDTH nFieldWidth] [WINDOW WindowName1]
[IN [WINDOW] WindowNam2 | IN SCREEN | IN MACDESKTOP]]
[COLOR SCHEME nSchemeNumber | COLOR ColorPairList]

Parameters

The parameters for CHANGE are the same as those for EDIT. See EDIT Command.

Remarks

CHANGE works just like EDIT.

See Also

Other Resources

BROWSE Command
WTITLE( ) Function
Commands
Language Reference


CLEAR Commands

Visual FoxPro 9.0 Language Reference
CLEAR Commands
See Also

Releases the specified item or items from memory.

CLEAR [ALL | CLASS ClassName | CLASSLIB ClassLibraryName | DEBUG | DLLS
   [cAliasNameList]| EVENTS | ERROR |FIELDS | GETS | MACROS | MEMORY
   | MENUS | POPUPS | PROGRAM | PROMPT | READ [ALL] | RESOURCES
   [FileName] | TYPEAHEAD | WINDOWS]

Parameters

ALL

Releases from memory all variables and arrays and the definitions of all user-defined menu bars, menus, and windows. CLEAR ALL also closes any tables, including all associated index, format and memo files, and selects work area 1. CLEAR ALL also releases from memory all external shared library functions registered with DECLARE - DLL. CLEAR ALL does not release system variables, and does not clear the compiled program buffer. Use CLEAR PROGRAM to clear the compiled program buffer. Issuing CLEAR ALL within an event or method for an active control or object generates a Visual FoxPro error message. An object type variable cannot be released from memory when its associated control or object is active.
CLASS ClassName

Clears a class definition from memory. When an instance of a class is created, Visual FoxPro keeps the class definition in memory after the instance is released. Use CLEAR CLASS to clear a class definition from memory after its instance is released.
CLASSLIB ClassLibraryName

Clears from memory all class definitions contained in a visual class library. If instances of classes in the class library exist, the class definitions are not cleared from memory. However, all class definitions that do not have instances are cleared from memory.
DEBUG

Clears all breakpoints in the Debugger and restores the Debugger windows (Call Stack, Trace, Watch, etc.) to their default positions. If Clear Debug is issued when the Debugger is closed, the Debugger is opened with the Debugger windows in their default positions. Works in either fox or debugger frame mode.
DLLS cAliasNameList

Clears from memory external shared libraries registered with DECLARE - DLL. cAliasNameList is a comma separated list of function aliases to remove from memory as in the following example:
Copy Code
CLEAR DLLS  "RegCloseKey","RegOpenKey"
If you used no alias in the declaration, cAliasNameList is the same as the function name. If you specify no cAliasNameList, all DLLS are removed from memory. You can use the ADLLS( ) Function to determine which DLLs are loaded. See DECLARE - DLL Command for more information about registering external shared library functions.
ERROR

Resets the Visual FoxPro error structures as if no error had occurred. The following functions are reset to their default values: AERROR( ) Function (reset to zero). ERROR( ) Function (reset to zero). MESSAGE( ) Function (reset to the empty string). MESSAGE( ) Function (reset to the empty string). SYS(2018) - Error Message Parameter (reset to the empty string). Avoid using CLEAR ERROR within a TRY...CATCH...FINALLY Command, particularly if you are using TRY...CATCH...FINALLY Command to rethrow an error. The Exception object may no longer be valid.
EVENTS

Stops event processing started with READ EVENTS. When CLEAR EVENTS is executed, program execution continues on the program line immediately following READ EVENTS.
FIELDS

Releases a list created with SET FIELDS and executes SET FIELDS OFF. CLEAR FIELDS differs from SET FIELDS TO in that it releases all field lists for all work areas, not just the field list for the current work area. Also, SET FIELDS TO does not implicitly issue a SET FIELDS OFF.
GETS

Releases all pending @ ... GET controls. Issuing CLEAR also releases all pending @ ... GET controls.
Note:
GETS is included for backward compatibility.

MACROS

Releases from memory all keyboard macros, including any SET FUNCTION key assignments. Macros can be saved to a macro file or to a memo field with SAVE MACROS and restored later with RESTORE MACROS. You can also restore the default macros with RESTORE MACROS.
MEMORY

Releases from memory all public and private memory variables and arrays. System variables aren't released.
MENUS

Releases all menu bar definitions from memory.
POPUPS

Releases from memory all menu definitions created with DEFINE POPUP.
PROGRAM

Clears the compiled program buffer. Visual FoxPro keeps a buffer of the most recently executed programs. In rare cases, Visual FoxPro might not recognize changes made to program files on disk. CLEAR PROGRAM forces Visual FoxPro to read the programs from disk, rather than from the program buffer. The most common reason Visual FoxPro might not recognize changes made to program files is your using an external or terminate-and-stay-resident (TSR) editor to modify a program file. With this exception, you should not have to use CLEAR PROGRAM.
PROMPT

Releases menu items created with @ ... PROMPT.
READ [ALL]

Included for backward compatibility. Use CLEAR EVENTS instead.
RESOURCES [ FileName]

Specifies the name of a cached bitmap, picture, font, cursor, or icon file to be cleared from memory. If no file name is specified, all bitmap, picture, font, cursor and icon files are removed from memory. When Visual FoxPro displays a bitmap, picture, cursor, icon, or font resource, the resource is cached to optimized performance. If a resource of the same name is used (for example, a different bitmap with the same name as one already cached), Visual FoxPro does not reload the resource. Clearing a resource file is therefore particularly useful for removing a graphic image from memory and forcing Visual FoxPro to reload an image of the same name from disk. For example, a report might display graphic images from a database, all of which are named TEMP; however, because they all have the same name, Visual FoxPro will not reload each new graphic unless the existing one has been cleared from memory using the CLEAR RESOURCES command. If a particular resource is still in use by Visual FoxPro, then it may not able to be cleared using the CLEAR RESOURCES command.
TYPEAHEAD

Clears the keyboard type-ahead buffer. CLEAR TYPEAHEAD is useful when you want to prevent input into a field or prevent a response to a prompt before the field or prompt is displayed.
WINDOWS

Releases from memory all user-defined window definitions and clears the windows from the main Visual FoxPro window or the active user-defined window. Use SAVE WINDOW to save window definitions in a file or memo field for later use. Issuing CLEAR WINDOWS releases any system variable references to forms. For example, the following commands create a system variable reference for a form, and then display information about the variable:
Copy Code
goMyForm = CREATEOBJECT('FORM')
DISPLAY MEMORY LIKE goMyForm  && Displays GOMYFORM  O  FORM
Issuing CLEAR WINDOWS releases the system variable reference and the variable now contains the null value:
Copy Code
CLEAR WINDOWS
DISPLAY MEMORY LIKE goMyForm  && Displays GOMYFORM  O  .NULL.

Remarks

CLEAR erases the main Visual FoxPro window or the current user-defined window, and releases from memory all pending @ ... GET controls. You can include CLEAR in format files.

See Also

Other Resources

@ ... CLEAR Command
CLOSE Command
DECLARE -DLL Command
READ Command
READ EVENTS Command
RELEASE Command
RELEASE CLASSLIB Command
RELEASE WINDOWS Command
Commands
Language Reference


CLOSE Commands

Visual FoxPro 9.0 Language Reference
CLOSE Commands
See Also

Closes various file types.

CLOSE [ALL | ALTERNATE | DATABASES [ALL] | DEBUGGER | FORMAT | INDEXES
   | PROCEDURE | TABLES [ALL]]

Parameters

ALL

Closes all open databases, tables, and indexes in the current and any inactive data sessions and selects work area 1. CLOSE ALL also closes any files opened with the FCREATE( ) and FOPEN( ) low-level file functions, and any procedure files opened with SET PROCEDURE. CLOSE ALL does not close a file opened with SET PRINT. CLOSE ALL also closes the following:
  • Form Designer

  • Project Manager

  • Label Designer

  • Report Designer

  • Query Designer

CLOSE ALL does not close these:
  • Command window

  • Debug window

  • Help

  • Trace window

CLOSE ALTERNATE

Closes an alternate file opened with SET ALTERNATE.
CLOSE DATABASES [ALL]

Closes the current database in the current data session and its tables. If there is no current database, all open free tables, indexes, and format files in all work areas in the current data session are closed, and work area 1 is selected.
Note:
Using CLOSE DATABASES in the Command window does not close a database if the database was opened in the Project Manager by expanding its node or when a form is running in its own data session. Under these circumstances, the database remains open until the Project Manager closes the database or until the form using the database closes.

The ALL keyword specifies to close the following items in current and all inactive data sessions and that work area 1 is selected:
  • All open databases and their tables, except for currently selected databases in other data sessions or databases and their tables that are open in other data sessions.

  • All open free tables.

  • All indexes and format files in all work areas.

CLOSE DEBUGGER

Closes the Visual FoxPro debugger.
CLOSE FORMAT

Closes a format file in the current work area opened with SET FORMAT.
CLOSE INDEXES

Closes all open index files (both single-entry .idx and independent compound .cdx files) in the current work area. A structural compound index (a .cdx file automatically opened with the table) is not closed.
CLOSE PROCEDURE

Closes a procedure file opened with SET PROCEDURE.
CLOSE TABLES [ALL]

Closes all tables in the currently selected database. CLOSE TABLES closes all free tables in all work areas if a database isn't open. Include ALL to close all tables in all databases, and all free tables. All databases remain open. CLOSE TABLES should not be issued when a transaction is in progress; Visual FoxPro will generate an error message.

See Also

Other Resources

ADD TABLE Command
CLOSE MEMO Command
CREATE DATABASE Command
Close Method


CLOSE MEMO Command

Visual FoxPro 9.0 Language Reference
CLOSE MEMO Command
See Also

Closes one or more memo editing windows.

CLOSE MEMO MemoFieldName1 [, MemoFieldName2 ...] | ALL

Parameters

MemoFieldName1[, MemoFieldName2...]

Specifies the name of the memo field whose memo editing window you want to close. To close a set of memo editing windows, include a list of memo field names with the field names separated by commas. You can close the memo editing window of a memo field in a table open in another work area by including the table alias.
ALL

Closes all memo editing windows for all memo fields in any open tables.

Remarks

CLOSE MEMO closes memo editing windows opened with MODIFY MEMO, or opened from a Browse window or Edit window. CLOSE MEMO saves any changes you made to the memo fields.

Closing a table containing the memo field or fields also saves any changes you made and closes the memo windows.

See Also

Other Resources

BROWSE Command
MODIFY MEMO Command
APPEND MEMO Command
COPY MEMO Command
Commands
Language Reference


COMPILE Command

Visual FoxPro 9.0 Language Reference
COMPILE Command
See Also

Compiles one or more specified source files and creates an object file for each source file. There are two versions of the syntax.

COMPILE [DATABASE | FORM | CLASSLIB | LABEL | REPORT] cFileName | cFileSkeleton | ? [ALL]
COMPILE cFileName | cFileSkeleton | ? [ENCRYPT] [NODEBUG] [AS nCodePage]

Parameters

DATABASE

Compiles one or more database (.dbc) files specified by cFileName or cFileSkeleton. Choosing DATABASE compiles source code for stored procedures that are saved with the database and stores it in an additional memo field. You can use the DATABASE option to compile stored procedures outside the Database Designer.
Note:
COMPILE DATABASE packs memo fields in the database memo file (.dct) to remove unused space from the memo file. Records marked for deletion in the database table are not removed from the table.

FORM

Compiles one or more form definition files (.scx) specified by cFileName or cFileSkeleton. Choosing FORM compiles source code for the data environment that is saved with the form and stores in an additional memo field. Visual FoxPro automatically compiles forms when they are saved in the Form Designer. You can use the FORM option to compile a form outside the Form Designer.
Note:
Form source code is stored in memo fields in the Form table. COMPILE FORM compiles the memo fields into object code and stores it in an additional memo field. Visual FoxPro executes the object code in the additional memo field when you use the DO FORM command. For more information, see DO FORM Command.

CLASSLIB

Compiles one or more visual class library (.vcx) files specified by cFileName or cFileSkeleton. Source code for a visual class library is stored in memo fields in the visual class library table. Choosing CLASSLIB compiles the memo fields into object code and stores it in an additional memo field.
LABEL

Compiles one or more label definition files (.lbx) specified by cFileName or cFileSkeleton. Choosing LABEL compiles source code for the data environment saved with the label file and stores it in an additional memo field.
REPORT

Compiles one or more report definition files (.frx) specified by cFileName or cFileSkeleton. Choosing REPORT compiles source code for the data environment saved with the report file and stores it in an additional memo field.
cFileName

Specifies the target file to compile. If you specify one of the listed options, the following table describes the values for cFileName that correspond to the option you choose.

Option cFileName

DATABASE

Name of the database containing the stored procedures to compile.

You can compile stored procedures in a database that is not open.

FORM

Name of the form to compile.

CLASSLIB

Name of the class library to compile.

LABEL

Name of the report to compile.

REPORT

Name of the report to compile.
If you do not specify one of the listed options, such as FORM or REPORT, the following list shows other files you can specify for cFileName.
  • Program (.prg)

  • Form (.spr)

  • Menu (.mpr)

  • Query (.qpr)

  • Format (.fmt)

cFileSkeleton

Specifies a set or subset of files that match a file skeleton that can contain wildcard characters such as an asterisk (*) or question mark (?). For example, to compile all database files that begin with the letter A, use the following command:
Copy Code
COMPILE DATABASE A*
To compile all program files that have the .prg file name extension in the current directory or folder, use the following command:
Copy Code
COMPILE *.PRG
?

Displays the Compile dialog box so you can browse and choose a file to compile.
ALL

For older cross-platform report (.frx) and label (.lbx) files, compiles all records for all Visual FoxPro platforms in the form table and is available only for the REPORT and LABEL options. If you omit ALL, only records for the current Visual FoxPro platform are compiled. For example, suppose you have an .frx file containing only Windows and Macintosh records. When executing the COMPILE command on a computer with Windows, omitting ALL compiles only Windows records.
ENCRYPT

Encrypts compiled Visual FoxPro program files and is not available when using the DATABASE, FORM, CLASSLIB, LABEL, and REPORT options. ENCRYPT prevents access to the original source programs. For additional source code protection, always include this option when compiling programs intended for distribution.
NODEBUG

Reduces the size of the compiled file by two bytes per source file line and is not available when using the DATABASE, FORM, CLASSLIB, LABEL, and REPORT options. The two bytes reduced in the compiled file are a reference to the corresponding line in the source file. Removing these two bytes does not affect the program's performance, but it does reduce the compiled file size and conserves disk space.
Note:
When you include NODEBUG, you cannot view execution of the program in the Trace window or return the source code for a line that causes an error by using MESSAGE(1). For more information, see MESSAGE( ) Function.

AS nCodePage

Specifies the code page for which a program file is compiled and is not available when using the DATABASE, FORM, CLASSLIB, LABEL, and REPORT options. The compilation code page you specify overrides the global compilation code page specified with SET CPCOMPILE.

Remarks

Visual FoxPro executes only object files, so if a source file has not been compiled, it is automatically compiled into an object file when you run the program. The source file remains unchanged. A separate compiled object file is created with the same root name as the source file, but with a different extension. The following table lists example source file extensions and compiled file extensions for each file type.

File type | Source extension | Compiled extension
Program file | PRG | FXP
Menu code | MPR | MPX
Query | QPR | QPX
Format | FMT | PRX

The compiler detects any syntax errors in the source file. If SET LOGERRORS is set to ON when the file is compiled, Visual FoxPro saves compilation error messages to a text file. The error log file has the same root name as the compiled file and has an .err file name extension. If SET LOGERRORS is set to OFF, the error log file is not created. For more information, see SET LOGERRORS Command.

If a form has an #INCLUDE header (.h) file, and the .h file is moved from its original directory, a compilation error occurs and is listed in the error log (.err) file. You can run the form, but if you modify it, you cannot save it until you correct the path to the .h file.

To correct the path for a moved header (.h) file

  1. Open the form using the MODIFY FORM command.

  2. On the Form menu, choose IncludeFile.

  3. In the IncludeFile dialog box, browse to or type the new path for the .h file.

For more information, see #INCLUDE Preprocessor Directive, MODIFY FORM Command, and Include File Dialog Box.

Examples

The following example uses CLOSE DATABASES to close all open databases and uses COMPILE DATABASE to compile all the stored procedures in the Visual FoxPro sample database, TestData.dbc.

Copy Code
CLOSE DATABASES
COMPILE DATABASE (HOME(2) + 'Data\TestData')

See Also

Other Resources

File Extensions and File Types
Compiling Source Code
Commands
Language Reference


CONTINUE Command

Visual FoxPro 9.0 Language Reference
CONTINUE Command
See Also Example

Continues the previous LOCATE.

CONTINUE

Remarks

CONTINUE is used after LOCATE succeeds in finding a record, to continue the LOCATE operation. CONTINUE moves the record pointer to the next record for which the logical expression specified in the previous LOCATE evaluates to True (.T.).

CONTINUE can be repeated until the end of the file is encountered, or until the end of the scope you specified with LOCATE is reached.

If CONTINUE succeeds in finding a record, RECNO( ) returns the record number of the record, FOUND( ) returns a value of True (.T.), and EOF( ) returns a value of False (.F.).

If CONTINUE doesn't succeed in finding a record, RECNO( ) returns the number of records in the table plus one, FOUND( ) returns False (.F.), and EOF( ) returns True (.T.).

Example

In the following example, all customers from France are counted and the total is displayed. All records are found using one LOCATE command followed by a CONTINUE command within a loop.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table
SET TALK OFF
STORE 0 TO gnCount

LOCATE FOR ALLTRIM(UPPER(country)) = 'FRANCE'
DO WHILE FOUND( )
   gnCount = gnCount + 1
   CONTINUE
ENDDO
? 'Total customers from France: '+ LTRIM(STR(gnCount))

See Also

Other Resources

EOF( ) Function
FOUND( ) Function
LOCATE Command
SEEK Command
Commands
Language Reference


COPY FILE Command

Visual FoxPro 9.0 Language Reference
COPY FILE Command
See Also

Duplicates any type of file.

COPY FILE FileName1 TO FileName2

Remarks

COPY FILE creates a duplicate of the file whose name is specified in FileName1. You can use COPY FILE to copy any type of file. The file to be copied cannot be open. You must include the extensions for both the source file name FileName1 and destination file name FileName2.

FileName1 and FileName2 can contain wildcard characters such as * and ?. For example, to create backup copies of all program files with the extension .prg in the current directory, issue COPY FILE *.PRG TO *.BAK.

If you use COPY FILE to create a backup of a table that has a memo field, a structural index or both, be sure to copy the .fpt and .cdx files as well.

See Also

Other Resources

DELETE FILE Command
RENAME Command
RENAME TABLE Command
Commands
Language Reference


COPY INDEXES Command

Visual FoxPro 9.0 Language Reference
COPY INDEXES Command
See Also

Creates compound index tags from single-entry .idx index files.

COPY INDEXES IndexFileList | ALL   [TO CDXFileName]

Parameters

IndexFileList

Specifies the single-entry .idx index files whose index expressions are used to create the tags. Separate the index file names with commas. The name assigned to each tag is the root name of the corresponding single-entry index file. If you create a tag from an index file that has the same name as an existing tag, a dialog is displayed (if SAFETY is ON) asking if you would like to overwrite the tag.
ALL

Specifies to create index tags from all open single-entry index files.
TO CDXFileName

Creates tags in a non-structural compound index file. Specify the name of the non-structural compound index file with CDXFileName. If a non-structural compound index file with the specified name doesn't exist, Visual FoxPro automatically creates it.

Remarks

A compound index file is an index file containing separate index entries called tags. Each tag is identified by its unique tag name. The default extension for a compound index file is .cdx.

You must first open the table and single-entry index files before using COPY INDEXES. The index expressions from the single-entry index files are used to create the new tags.

If you omit the TO clause, the new tags are added to the structural compound index file that is automatically opened with the table. If a structural compound index file doesn't exist for the table, COPY INDEXES creates one.

Use COPY TAG to create a single-entry index file from compound index file tags.

See Also

Other Resources

CDX( ) Function
COPY TAG Command
DELETE TAG Command
INDEX Command
TAG( ) Function
USE Command
Commands
Language Reference


COPY MEMO Command

Visual FoxPro 9.0 Language Reference
COPY MEMO Command
See Also Example

Copies the contents of the specified memo field in the current record to a text file.

COPY MEMO MemoFieldName TO FileName   [ADDITIVE]   [AS nCodePage]

Parameters

MemoFieldName

Specifies the name of the memo field copied to the text file.
TO FileName

Specifies the name of a new or existing text file to which the memo field is copied. If you do not provide an extension in FileName, a .txt extension is assigned. You can also include a path with the file name.
ADDITIVE

Appends the contents of the memo field to the end of the specified text file. If you omit ADDITIVE, the memo field contents replace the contents of the text file.
AS nCodePage

Specifies the code page for the text file COPY MEMO creates. Visual FoxPro copies the contents of the specified memo field, and, as it copies the data, automatically converts the data to the code page you specify for the text file. If you specify a value for nCodePage that is not supported, Visual FoxPro generates an error message. You can use GETCP( ) for nCodePage to display the Code Page dialog box, allowing you to specify a code page for the file Visual FoxPro creates. If AS nCodePage is omitted or is 0, no code page conversion occurs.

Example

In the following example, the contents of the memo field named notes are copied to a file called Test.txt. The memo field is then copied again and appended to the end of the text file.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE employee && Opens Employee table
COPY MEMO notes TO test.txt
WAIT WINDOW 'Memo contents now in test.txt' NOWAIT
MODIFY FILE test.txt
COPY MEMO notes TO test.txt ADDITIVE
WAIT WINDOW 'Memo contents added again to test.txt' NOWAIT
MODIFY FILE test.txt
DELETE FILE test.txt

See Also

Other Resources

APPEND MEMO Command
COPY FILE Command
COPY TO Command
MODIFY MEMO Command
Commands
Language Reference


COPY PROCEDURES Command

Visual FoxPro 9.0 Language Reference
COPY PROCEDURES Command
See Also Example

Copies stored procedures in the current database to a text file.

COPY PROCEDURES TO FileName   [AS nCodePage] [ADDITIVE]

Parameters

FileName

Specifies the name of a text file to which the stored procedures are copied. If the file doesn't exist, Visual FoxPro automatically creates it.
AS nCodePage

Specifies the code page for the text file to which the stored procedures are copied. Visual FoxPro copies the stored procedures, and, as it does so, automatically converts the stored procedures to the code page you specify. If you specify a value for nCodePage that is not supported, Visual FoxPro generates an error message. You can use GETCP( ) for nCodePage to display the Code Page dialog box, allowing you to specify a code page for the text file to which the stored procedures are copied. If you omit AS nCodePage or if AS nCodePage is 0, no code page conversion occurs.
ADDITIVE

Appends the stored procedures to the end of the specified text file. If you omit ADDITIVE, the stored procedures replace the contents of the text file.

Remarks

Use COPY PROCEDURES with APPEND PROCEDURES to programmatically modify stored procedures in a database. A database must be open and current when COPY PROCEDURES is issued; otherwise Visual FoxPro generates an error message.

Example

The following example opens the testdata database, and uses COPY PROCEDURES to copy the procedures to a temporary text file named Myproc.txt. MODIFY FILE is used to open the temporary text file, which will be empty if there are no stored procedures in the database.

If there are no stored procedures in the database, you can run the example in the APPEND PROCEDURES topic to add a procedure to database.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')

COPY PROCEDURES TO myproc.txt && Copy stored procedures to a file
MODIFY FILE myproc.txt  && Open the file
DELETE FILE myproc.txt  && Erase the file

See Also

Other Resources

APPEND PROCEDURES Command
CREATE TRIGGER Command
DISPLAY PROCEDURES Command
MODIFY PROCEDURE Command
SET DATABASE Command
Commands
Language Reference


COPY STRUCTURE Command

Visual FoxPro 9.0 Language Reference
COPY STRUCTURE Command
See Also Example

Creates a new, empty table with the same structure as the currently selected table.

COPY STRUCTURE TO TableName   [FIELDS FieldList]
[[WITH] CDX | [WITH] PRODUCTION]
[DATABASE cDatabaseName [NAME cTableName]]

Parameters

TableName

Specifies the name of the new, empty table to create. In Visual FoxPro, null value support and the code page for the new, free table are identical to the currently selected table.
FIELDS FieldList

Specifies that only the fields whose names are specified in the FieldList are copied to the new table. If you omit FIELDS FieldList, all fields are copied to the new table.
[WITH] CDX | [WITH] PRODUCTION

Creates a structural index file for the new table that is identical to the structural index file of the existing table. The tags and index expressions from the original structural index file are copied to the new structural index file. The CDX and PRODUCTION clauses are identical. In Visual FoxPro, a primary index for the currently selected table is converted to a candidate index for the new empty table.
DATABASE cDatabaseName

Specifies the name of an existing database to which the new table is added. Note that the table and field properties are not copied to the database.
NAME cTableName

Specifies the name of the table as it appears in the database.

Example

In the following example, the customer table is opened, its structure is copied to a table called backup and backup is opened. APPEND FROM then appends records to the backup table from the customer table, and a Browse window is opened for the backup table.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

COPY STRUCTURE TO backup
USE backup
APPEND FROM customer FOR country = 'UK'
BROWSE FIELDS contact, country
USE
DELETE FILE backup.dbf

See Also

Other Resources

COPY STRUCTURE EXTENDED Command
CREATE Command
DISPLAY STRUCTURE Command
Commands
Language Reference


COPY STRUCTURE EXTENDED Command

Visual FoxPro 9.0 Language Reference
COPY STRUCTURE EXTENDED Command
See Also Example

Creates a new table with fields containing the structure of the currently selected table.

COPY STRUCTURE EXTENDED TO FileName
   [DATABASE DatabaseName [NAME LongTableName]] [FIELDS FieldList]

Parameters

FileName

Specifies the new table to create.
DATABASE DatabaseName

Specifies a database to which the new table is added.
NAME LongTableName

Specifies a long name for the new table. Long names can contain up to 128 characters and can be used instead of short file names in the database.
FIELDS FieldList

Specifies that only the fields in FieldList are included in a record in the new table. If you omit FIELDS FieldList, all fields have a record in the new table.

Remarks

Information about each field in the currently selected table is copied to a record in the new table. The structure of the new table has a fixed format and consists of 18 fields. The following table lists the names of the fields and their contents.

Field | Field type | Contents
FIELD_NAME | Character | Field names from selected table (128 characters wide)
FIELD_TYPE | Character | Field types: Blob Character Currency Date DateTime Double Float General Integer Logical Memo Numeric Varchar and Varchar (Binary) Varbinary
FIELD_LEN | Numeric | Field widths
FIELD_DEC | Numeric | Number of decimal places in numeric fields
FIELD_NULL | Logical | Field null value support
FIELD_NOCP | Logical | Code page translation not allowed (character and memo fields only)
FIELD_DEFA | Memo | Field default values
FIELD_RULE | Memo | Field validation rules
FIELD_ERR | Memo | Field validation text
TABLE_RULE | Memo | Table validation rule
TABLE_ERR | Memo | Table validation text
TABLE_NAME | Character | Long table name (first record only)
INS_TRIG | Memo | Insert trigger expression (first record only)
UPD_TRIG | Memo | Update trigger expression (first record only)
DEL_TRIG | Memo | Delete trigger expression (first record only)
TABLE_CMT | Memo | Table comment (first record only)
FIELD_NEXT | Numeric | Next value for AUTOINC field, if enabled.
FIELD_STEP | Numeric | Step value for AUTOINC field. If value is 0, autoincrementing is not enabled for the field.

The width of the FIELD_NAME field is 10 characters in previous versions of Visual FoxPro, FoxPro for Windows, and FoxPro for MS-DOS. To use CREATE FROM with a table created by COPY STRUCTURE EXTENDED in Visual FoxPro 5.0 and earlier, you must change the width of the FIELD_NAME field to 10 characters. Some field types are not supported in Visual FoxPro 3.0 and earlier versions.

If fields in the source table use autoincrementing, FIELD_STEP is a nonzero value.

You can modify the newly created table and use the CREATE FROM command to create a new table with a different structure. The COPY STRUCTURE and CREATE FROM commands allow you to programmatically change the structure of a table.

Example

The following example displays the structure of the Orders table, copies the structure extended to a Temp table, browses Temp, creates a table called Backup from Temp, and displays the structure of Backup.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Orders  && Opens Orders table.
CLEAR
DISPLAY STRUCTURE

WAIT WINDOW 'Structure of the Orders table' NOWAIT
COPY STRUCTURE EXTENDED TO Temp
USE Temp
WAIT WINDOW 'The Temp table - 1 row per field in orders' NOWAIT
BROWSE
CREATE Backup FROM Temp
USE Backup
DISPLAY STRUCTURE
WAIT WINDOW 'Backup.dbf has the same structure as Orders' NOWAIT
USE
DELETE FILE Temp.dbf
DELETE FILE Backup.dbf

See Also

Other Resources

AFIELDS( ) Function
Autoincrementing Field Values in Tables
CREATE FROM Command
COPY STRUCTURE Command
Commands
Language Reference


COPY TAG Command

Visual FoxPro 9.0 Language Reference
COPY TAG Command
See Also

Creates a single-entry index (.idx) file from a tag in a compound index file.

COPY TAG TagName [OF CDXFileName]   TO IndexFileName

Parameters

TagName

Specifies the tag used to create the single-entry .idx file.
OF CDXFileName

Specifies the compound index file containing the tag. Include this clause if there are tags with the same names in the open compound index files. If you omit OF CDXFileName, Visual FoxPro looks for the tag first in the structural index file. If it isn't found there, Visual FoxPro searches all the open non-structural compound index files.
TO IndexFileName

Specifies the name of the single-entry .idx file to create.

Remarks

Use COPY TAG to create a new single-entry .idx file from a tag in a .cdx compound index file.

The compound index file from which you create the single-entry .idx file must be open. Structural compound index files are automatically opened when you open a table. Non-structural compound indexes must be explicitly opened with USE ... INDEX or SET INDEX. For more information about compound index files, see INDEX.

Use COPY INDEX to create tags in compound index files from single-entry .idx files.

See Also

Other Resources

CDX( ) Function
COPY INDEXES Command
DELETE TAG Command
INDEX Command
TAG( ) Function
USE Command
Commands
Language Reference


COPY TO ARRAY Command

Visual FoxPro 9.0 Language Reference
COPY TO ARRAY Command
See Also Example

Copies data from the currently selected table to an array.

COPY TO ARRAY ArrayName
   [FIELDS FieldList | FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton]
   [Scope] [FOR lExpression1] [WHILE lExpression2] [NOOPTIMIZE]

Parameters

ArrayName

Specifies the array to which data from the table is copied.
FIELDS FieldList

Specifies that only the fields specified in FieldList are copied to the array. If you omit FIELDS FieldList, all fields are copied to the array if the array has enough columns.
FIELDS LIKE Skeleton

Specifies that fields that match the field skeleton Skeleton are copied to the array.
FIELDS EXCEPT Skeleton

Specifies that all fields except those that match the field skeleton Skeleton are copied to the array.
Scope

Specifies a range of records copied to the array. Only the records within the range are copied. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see the Scope Clauses online topic.
FOR lExpression1

Specifies that only the records that satisfy the logical condition lExpression1 are copied to the array. To conditionally copy records to the array, include the FOR clause to filter out undesired records.
WHILE lExpression2

Specifies a condition where records are copied to the array while the logical expression lExpression2 evaluates to True (.T.).
NOOPTIMIZE

Disables Rushmore Query Optimization of COPY TO ARRAY. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

Remarks

Rushmore optimizes a COPY TO ARRAY query that includes FOR lExpression1 if lExpression1 is an optimizable expression. For the best performance, use an optimizable expression in the FOR clause. For information on Rushmore optimizable expressions, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

COPY TO ARRAY and SCATTER are similar. COPY TO ARRAY copies multiple records to an array, while SCATTER copies just one record into an array or a set of memory variables. Both COPY TO ARRAY and SCATTER create a new array if an array with the name you specify does not exist.

To copy a single record to an array, you can specify a one-dimensional array. The one-dimensional array you specify should have the same number of elements as fields in the table, not counting memo fields. Memo and Blob fields are ignored in COPY TO ARRAY.

If you specify a one-dimensional array, the first field of a record is stored to the first element of the array, the second field is stored to the second element of the array, and so on. If the one-dimensional array has more elements than the table has fields, any remaining elements remain unchanged. If the array has fewer elements than the table has fields, any remaining fields are ignored.

To copy multiple records or an entire table to an array, specify a two-dimensional array. The number of rows in the array is the number of records the array can hold, and the number of columns in the array is the number of fields the array can hold.

Each record is stored in one row of the array, and each field of the record is stored in one column of the array. For each record, the first field is stored to the first column of the array, the second field is stored to the second column of the array, and so on. If the array has more columns than the table has fields, any remaining columns aren't changed. If the array has fewer columns than the table has fields, any remaining fields aren't stored to the array.

Each successive row in the array is filled with the contents of the next record in the table. If the array has more rows than the table has records, any remaining rows aren't changed. If the array has fewer rows than the table has records, any remaining records aren't stored to the array.

Data can be copied from arrays to new table records with APPEND FROM ARRAY. Data can also be copied from either an array or a set of memory variables to records in a table with GATHER.

The field skeleton Skeleton supports wildcards. For example, to specify that all fields that begin with the letters A and P are copied to the array, use the following:

Copy Code
COPY TO ARRAY aMyArray FIELDS LIKE A*,P*

The LIKE clause can be combined with the EXCEPT clause:

Copy Code
COPY TO ARRAY aMyArray FIELDS LIKE A*,P* EXCEPT PARTNO*

Turning on autoincrementing has no effect on the COPY TO ARRAY command. Only the record values are copied to the array.

Example

In the following example, the Customer table is opened. A two-dimensional array is then created and the first three records from Customer are copied to the array. DISPLAY MEMORY shows the data stored in the array.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer  && Opens Customer table.

DIMENSION gaTemp(3,10)
COPY NEXT 3 TO ARRAY gaTemp
DISPLAY MEMORY LIKE gaTemp

See Also

Other Resources

APPEND FROM ARRAY Command
DECLARE Command
DIMENSION Command
GATHER Command
PUBLIC Command
SCATTER Command
STORE Command
Commands
Language Reference


COPY TO Command

Visual FoxPro 9.0 Language Reference
COPY TO Command
See Also Example

Creates a new file from the contents of the currently selected table.

COPY TO FileName [DATABASE DatabaseName [NAME LongTableName]]
   [FIELDS FieldList | FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton]
   [Scope] [FOR lExpression1] [WHILE lExpression2]
   [ [WITH] CDX ] | [ [WITH] PRODUCTION ] [NOOPTIMIZE]
   [ [TYPE] [ FOXPLUS | FOX2X | DIF | MOD | SDF | SYLK | WK1 | WKS | WR1
   | WRK | CSV | XLS | XL5 | DELIMITED [ WITH Delimiter | WITH BLANK
   | WITH TAB | WITH CHARACTER Delimiter ] ] ] [AS nCodePage]

Parameters

FileName

Specifies the name of the new file to create. If you do not include a file extension, COPY TO assigns the default extension for the specified file type. If you do not specify a file type, COPY TO creates a new Visual FoxPro table and assigns the default .dbf extension to the table file name.
DATABASE DatabaseName

Specifies a database to which the new table is added.
NAME LongTableName

Specifies a long name for the new table. Long names can contain up to 128 characters and can be used instead of short file names in the database.
FIELDS FieldList

Specifies which fields are copied to the new file. If you omit FIELDS FieldList, all fields are copied to the file. If the file you are creating is not a table, memo fields are not copied to the new file, even if memo field names are included in the field list.
FIELDS LIKE Skeleton

Specifies that fields from the original table that match the field skeleton Skeleton are included in the new file that COPY TO creates.
FIELDS EXCEPT Skeleton

Specifies that all fields except those that match the field skeleton Skeleton are included in the new file that COPY TO creates.
Scope

Specifies a range of records to copy to a file. Only the records within the range are copied. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see Scope Clauses.
FOR lExpression1

Specifies that COPY TO copies only the records for which the logical condition lExpression1 evaluates to True (.T.) to the file. To conditionally copy records, include the FOR lExpression1 clause to filter out undesired records.
WHILE lExpression2

Specifies a condition where records are copied while the logical expression lExpression2 evaluates to True (.T.).
[WITH] CDX | [WITH] PRODUCTION

Creates a structural index file for the new table that is identical to the structural index file of the existing table. The tags and index expressions from the original structural index file are copied to the new structural index file. The CDX and PRODUCTION clauses are identical. However, do not include CDX or PRODUCTION if you are copying to a file other than a new Visual FoxPro table.
NOOPTIMIZE

Disables Rushmore Query Optimization for COPY TO. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
TYPE

Specifies the file type if the file you create is not a Visual FoxPro table. Although you must specify a file type, you do not need to include the TYPE keyword.
FOXPLUS

Visual FoxPro memo files have a different structure than Microsoft FoxBASE+™ memo files. If your source Visual FoxPro table contains a memo field, include the FOXPLUS clause to create a table that can be used in FoxBASE+. The Visual FoxPro memo field cannot contain binary data because FoxBASE+ does not support binary data in memo fields.
FOX2X

Creates a new table that can be opened in earlier versions of FoxPro (versions 2.0, 2.5, and 2.6). For Numeric, Float, Integer, Double, and Currency type fields, null values in the source table are converted to zero in the new table. For other field types, null values in the source table are converted to blanks in the new table. For further information about blank values, see ISBLANK( ). The following table lists the Visual FoxPro field types that are converted to different field types in the new table when the FOX2X argument is included.

Visual FoxPro field type FoxPro 2.x field type

Blob

Memo

Currency

Float

DateTime

Date

Double

Float

Integer

Numeric

Varbinary

Memo

Varchar

Memo
DIF

Creates a VisiCalc® .dif (Data Interchange Format) file. Fields from the Visual FoxPro table become vectors (columns) and records become tuples (rows). The new file name is assigned a .dif extension if you do not include an extension in FileName.
MOD

Creates a Microsoft Multiplan® version 4.01 file. The new Microsoft Multiplan file name is assigned a .mod extension if an extension is not included.
SDF

Creates an SDF (System Data Format) file. An SDF file is an ASCII text file in which records have a fixed length and end with a carriage return and line feed. Fields are not delimited. The SDF file name is assigned a .txt file extension if you do not include an extension. The SET CENTURY setting is ignored when creating SDF files with COPY TO. If SDF files include date data, it should be in YYYYMMDD format to allow effective reconversion into Visual FoxPro tables. If date information is stored in ambiguous formats, you should make sure that the dates are in YYYYMMDD format before you perform the COPY TO operation.
SYLK

Creates a SYLK (Symbolic Link) interchange file. SYLK files are used in Microsoft MultiPlan. Each field from the currently selected table becomes a column in the spreadsheet, and each record becomes a row. SYLK file names have no extension.
WK1

Creates a Lotus® 1-2-3® version 2.x spreadsheet file. Each field from the currently selected table becomes a column in the spreadsheet and each record becomes a row. A .wk1 file name extension is assigned to the new spreadsheet.
WKS

Creates a Lotus 1-2-3 version 1a spreadsheet file. Each field from the currently selected table becomes a column in the spreadsheet and each record becomes a row. A .wks file name extension is assigned to the new spreadsheet.
WR1

Creates a Lotus Symphony® version 1.1 or 1.2 spreadsheet file. Each field from the currently selected table becomes a column in the spreadsheet and each record becomes a row. A .wr1 file name extension is assigned to the new spreadsheet.
WRK

Creates a Lotus Symphony version 1.0 spreadsheet file. Each field from the currently selected table becomes a column in the spreadsheet and each record becomes a row. A .wr1 file name extension is assigned to the new spreadsheet.
CSV

Creates a comma separated value file. A CSV file has the field names as the first line in the file, and the field values in the remainder of the file are separated with commas.
XLS

Creates a Microsoft Excel version 2.0 worksheet file. Each field from the currently selected table becomes a column in the spreadsheet, and each record becomes a row. If you do not include a file extension, an .xls extension is assigned to the new worksheet.
Note:
Though you can export a maximum of 65,535 rows, which includes one row reserved for the field header, versions of Excel earlier than 8.0 (Excel 97) display only the first 16,384 rows and cannot import files containing more than 32,767 rows.

XL5

Creates a Microsoft Excel version 5.0 workbook file. Each field from the currently selected table becomes a column in the spreadsheet, and each record becomes a row. If you do not include a file extension, an .xls extension is assigned to the new workbook.
Note:
Though you can export a maximum of 65,535 rows, which includes one row reserved for the field header, versions of Excel earlier than 8.0 (Excel 97) display only the first 16,384 rows and cannot import files containing more than 32,767 rows.

DELIMITED

Creates a delimited file. A delimited file is an ASCII text file in which each record ends with a carriage return and line feed. The default field separator is a comma. Because character data can include commas, character fields are additionally delimited with double quotation marks. Unless you specify otherwise, a .txt extension is assigned to all newly created DELIMITED files.
DELIMITED WITH Delimiter

Creates a delimited file with character fields delimited by a character other than a quotation mark. The character that delimits character fields is specified with Delimiter.
DELIMITED WITH BLANK

Creates a delimited file with fields separated by spaces instead of commas.
DELIMITED WITH TAB

Creates a delimited file with fields separated by tabs instead of commas.
DELIMITED WITH CHARACTER Delimiter

Creates a delimited file with all fields enclosed by the character specified with Delimiter. If Delimiter is a semicolon (;), used in Visual FoxPro to indicate command line continuation, enclose the semicolon in quotation marks. You can also specify the BLANK and TAB keywords for Delimiter. You can combine the WITH Delimiter clause with the WITH CHARACTER clause. For example, the following command creates a text file with character fields enclosed by underscores and all fields delimited from each other with semicolons:
Copy Code
COPY TO mytxt.txt DELIMITED WITH _ WITH CHARACTER ';'
AS nCodePage

Specifies the code page for the table or file that COPY TO creates. Visual FoxPro copies the contents of the currently selected table, and, as it copies the data, automatically converts the data to the code page you specify for the new table or file. If possible, Visual FoxPro marks the newly created table or file with the code page you specify. If you omit AS nCodePage, the newly created table or file is converted to the current Visual FoxPro code page.

Remarks

The field skeleton Skeleton supports wildcards. For example, to specify that all fields that begin with the letters A and P are included in the new file, use the following:

Copy Code
COPY TO mytable FIELDS LIKE A*,P*

The LIKE clause can be combined with the EXCEPT clause:

Copy Code
COPY TO mytable FIELDS LIKE A*,P* EXCEPT PARTNO*

Rushmore Query Optimization optimizes COPY TO with a FOR lExpression1 clause if lExpression1 is an optimizable expression. For the best performance, use an optimizable expression in the FOR lExpression1 clause. For information on Rushmore optimizable expressions, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

If an index order is set, records are copied in master index order.

If you specify a value for nCodePage that is not supported, Visual FoxPro generates an error message. You can use the GETCP( ) function for nCodePage to display the Code Page dialog box, allowing you to specify a code page for the table or file Visual FoxPro creates.

The COPY TO command preserves autoincrementing settings except under the following conditions:

  • When the field list specified using COPY TO...FIELDS does not include the field that uses autoincrementing.

  • When using the TYPE clause in the COPY TO command, regardless of the type specified by the clause.

The target table begins autoincrementing starting with the NextValue of the source table. For example, suppose the NextValue in the source table is 1000 with a Step value of 1. The first row of the target table then has an autoincrementing field value of 1001; the second row has a value of 1002, and so on.

When using the COPY TO command, be aware that the SET VARCHARMAPPING Command will impact calculated fields (character expressions of variable length) set by the SET FIELDS Command.

Example

In the following example, the Customer table is opened and the next three records are copied to a new DELIMITED data file called Temp.txt.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer  && Opens Customer table.

COPY NEXT 3 TO Temp TYPE DELIMITED
WAIT WINDOW 'This is the delimited text file' NOWAIT
MODIFY FILE Temp.txt
DELETE FILE Temp.txt

See Also

Other Resources

APPEND FROM Command
COPY FILE Command
GETCP( ) Function
EXPORT Command
IMPORT Command
RENAME TABLE Command
Commands
Language Reference


COUNT Command

Visual FoxPro 9.0 Language Reference
COUNT Command
See Also Example

Counts table records.

COUNT   [Scope] [FOR lExpression1] [WHILE lExpression2]   [TO VarName]
   [NOOPTIMIZE]

Parameters

Scope

Specifies a range of records to be included in the count. The default scope for COUNT is ALL records. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. Commands that include Scope operate only on the table in the active work area. For more information on scope clauses, see Scope Clauses.
FOR lExpression1

Specifies that only the records that satisfy the logical condition lExpression1 are counted. Including FOR lets you conditionally count records, filtering out undesired records. Rushmore Query Optimization will optimize a COUNT FOR query if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For more information on optimizable expressions, see SET OPTIMIZE Command and Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies a condition whereby records are counted for as long as the logical expression lExpression2 evaluates to True (.T.).
TO VarName

Specifies the variable or array to which the record count is stored. If the variable you specify doesn't exist, Visual FoxPro creates it.
NOOPTIMIZE

Disables Rushmore optimization of COUNT. For more information see SET OPTIMIZE Command and Using Rushmore Query Optimization to Speed Data Access.

Remarks

COUNT counts the records within a scope of records for which the FOR or WHILE conditions are true. If SET TALK is ON, the record count is displayed.

Records marked for deletion are included in the count if SET DELETE is OFF.

For a discussion of how null values affect COUNT, see the Behavior of Null Values in Commands and Functions topic.

Example

The following example counts and displays the number of customers in Paris.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

CLEAR
COUNT FOR UPPER(city) = 'PARIS'
DISPLAY FIELDS company, contact FOR UPPER(city) = 'PARIS'

See Also

Other Resources

CALCULATE Command
SET DELETED Command
SET TALK Command
Commands
Language Reference


CREATE CLASS Command

Visual FoxPro 9.0 Language Reference
CREATE CLASS Command
See Also

Opens the Class Designer, allowing you to create a new class definition.

CREATE CLASS ClassName | ? [OF ClassLibraryName1 | ?]
[AS cBaseClassName [FROM ClassLibraryName2]] [NOWAIT]

Parameters

ClassName

Specifies the name of the class definition to create.
?

Displays the New Class dialog box, from which you can specify the name of the class definition to create.
OF ClassLibraryName1

Specifies the name of the .vcx visual class library to create. If the .vcx visual class library already exists, the class definition is added to it. A .vcx file extension is assumed for the visual class library. Be sure to include the file extension if the visual class library you specify has a file extension other than .vcx.
?

Displays the New Class dialog box, from which you can specify the name of a new or existing .vcx visual class library to which the class definition is added.
AS cBaseClassName

Specifies the class on which the class definition is based. You can specify any Visual FoxPro base class except Column and Header. You can also specify a user-defined class if you include the FROM ClassLibraryName2 clause that specifies the name of the visual class library (.vcx) file containing the user-defined class. If you omit AS cBaseClassName, the class definition is based on the Visual FoxPro FormSet base class.
FROM ClassLibraryName2

Specifies the name of the .vcx visual class library containing the user-defined class specified with cBaseClassName.
NOWAIT

Continues program execution after the Class Designer has been opened. The program doesn't wait for the Class Designer to be closed, but continues execution on the program line immediately following the line that contains CREATE CLASS NOWAIT. If you omit NOWAIT, when CREATE CLASS is issued in a program, the Class Designer is opened and program execution pauses until the Class Designer is closed. Including NOWAIT has no effect on CREATE CLASS when it is issued in the Command window.

Remarks

Use CREATE CLASS to create a class definition and save it in a .vcx visual class library. You can open the .vcx visual class library with SET CLASSLIB, allowing you to access the class definitions within the .vcx visual class library.

See Also

Other Resources

ADD CLASS Command
_BROWSER System Variable
CREATE CLASSLIB Command
DEFINE CLASS Command
_INCLUDE System Variable
MODIFY CLASS Command
RELEASE CLASSLIB Command
Session Object
SET CLASSLIB Command
Commands
Language Reference


CREATE CLASSLIB Command

Visual FoxPro 9.0 Language Reference
CREATE CLASSLIB Command
See Also Example

Creates a new, empty visual class library (.vcx) file.

CREATE CLASSLIB ClassLibraryName

Parameters

ClassLibraryName

Specifies the name of the visual class library to create. If a visual class library with the name you specify already exists and SET SAFETY is ON, Visual FoxPro asks if you'd like to overwrite the existing visual class library. If SET SAFETY is OFF, the existing file is automatically overwritten. If you don't specify an extension for the file name, Visual FoxPro automatically assigns a .vcx extension.

Remarks

Class definitions can be added to a visual class library with ADD CLASS and CREATE CLASS.

Example

The following example uses CREATE CLASSLIB to create a visual class library named myclslib. A class named myform based on the Visual FoxPro Form base class is created and is stored in the myclslib visual class library. SET CLASSLIB is used to open the myclslib visual class library so that classes within it can be used.
Copy Code
CREATE CLASSLIB myclslib     && Creates a new .VCX visual class library
CREATE CLASS myform OF myclslib AS "Form"  && Creates new class
SET CLASSLIB TO myclslib ADDITIVE     && Opens MyClsLib.VCX

See Also

Other Resources

ADD CLASS Command
_BROWSER System Variable
CREATE CLASS Command
DEFINE CLASS Command
MODIFY CLASS Command
RELEASE CLASSLIB Command
SET CLASSLIB Command
Commands
Language Reference


CREATE COLOR SET Command

Visual FoxPro 9.0 Language Reference
CREATE COLOR SET Command
See Also

Creates a color set from the current color settings.

CREATE COLOR SET ColorSetName

Parameters

ColorSetName

Specifies the name of the color set to create.

Remarks

Every color pair in every color scheme is saved in the color set you create. A color set name can be up to 24 characters long in Visual FoxPro, (10 characters in earlier FoxPro versions) and can contain numbers and underscores, but it cannot begin with a number.

Once you have created a color set, you can load it with SET COLOR SET.

Color sets are saved in the Visual FoxPro resource file. If a color set exists with the same name you specify, it is overwritten.

See Also

Other Resources

SET COLOR OF SCHEME Command
SET COLOR SET Command
SET COLOR TO Command
Commands
Language Reference


CREATE Command

Visual FoxPro 9.0 Language Reference
CREATE Command
See Also

Opens the Table Designer so you can create a Visual FoxPro table.

CREATE [FileName | ?]

Parameters

[ FileName| ?]

Specifies the name of the table to create or opens the Create dialog box so you can browse for a location to save the table and specify the name of the table to create.

Remarks

If a database is open when you create a table, the table is added automatically to the database.

When running on the Windows operating system, you cannot create a table with the name of an MS-DOS device, such as CON, NUL, PRN, and COM1. Avoid using hyphens in a table name because hyphenated table names do not appear in the Data Session window and can cause confusion with the alias pointer (->).

After opening the Table Designer, you need to define attributes for the fields in the table. After you create the table structure, you can add records to the table. For more information, see Creating Tables.

The SQL CREATETABLE command makes it possible to specify fields and their attributes programmatically. For more information, see CREATE TABLE - SQL Command.

See Also

Other Resources

ALTER TABLE - SQL Command
CREATE DATABASE Command
MODIFY STRUCTURE Command
Commands
Language Reference


CREATE CONNECTION Command

Visual FoxPro 9.0 Language Reference
CREATE CONNECTION Command
See Also Example

Creates a named connection and stores it in the current database.

CREATE CONNECTION [ConnectionName | ?]   [DATASOURCE cDataSourceName]
   [USERID cUserID] [PASSWORD cPassWord]   [DATABASE cDatabaseName]
| CONNSTRING cConnectionString]

Parameters

ConnectionName

Specifies the name of the connection to create.
?

Displays the Connection Designer from which you can create and save a connection.
DATASOURCE cDataSourceName

Specifies the name of the ODBC data source for the connection.
USERID cUserID

Specifies your user identification for the ODBC data source.
PASSWORD cPassWord

Specifies your password for the ODBC data source.
DATABASE cDatabaseName

Specifies a database on the server to which the connection is made.
CONNSTRING cConnectionString

Specifies a connection string for the ODBC data source. The connection string can be used instead of explicitly including the ODBC data source, the user identification, and the password.

Remarks

If you omit the optional arguments, the Connection Designer appears, allowing you to interactively create a connection.

Example

The following example assumes an ODBC data source called MyFoxSQLNT is available. The testdata database is opened, and a connection named Myconn is created. DISPLAY CONNECTIONS is used to display the named connections in the database. The connection is then removed from the database with DELETE CONNECTION.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
CREATE CONNECTION Myconn DATASOURCE "MyFoxSQLNT" USERID "<userid>" PASSWORD "<password>"

CLEAR
DISPLAY CONNECTIONS  && Displays named connections in the database
DELETE CONNECTION Myconn  && Removes the connection just created

See Also

Other Resources

DELETE CONNECTION Command
DBGETPROP( ) Function
DISPLAY CONNECTIONS Command
LIST CONNECTIONS Command
MODIFY CONNECTION Command
OPEN DATABASE Command
RENAME CONNECTION Command
Commands
Language Reference


CREATE CURSOR - SQL Command

Visual FoxPro 9.0 Language Reference
CREATE CURSOR - SQL Command
See Also Example

Creates a temporary table that exists until closed.

CREATE CURSOR alias_name
...[CODEPAGE=nCodePage]
   (fname1 cFieldType [(nFieldWidth [, nPrecision])] [NULL | NOT NULL]
   [CHECK lExpression [ERROR cMessageText]]
   [AUTOINC [NEXTVALUE NextValue [STEP StepValue]]]
   [DEFAULT eExpression] [UNIQUE [COLLATE cCollateSequence]]
   [NOCPTRANS] [, fname2 ...])
   | FROM ARRAY ArrayName

Parameters

alias_name

Specifies the name of the temporary table to create. The alias_name parameter can be a name expression.
nCodePage

Specifies the code page to use. For a list of code pages, see Code Pages Supported by Visual FoxPro.
fname

Specifies the name of a field in the temporary table. Each fname can be a name expression.
cFieldType

Specifies a single letter or a long name indicating the field's data type.
nFieldWidth

Specifies the width of the field specified with fname. Some data types require that you specify a value for nFieldWidth.
nPrecision

Specifies the number of decimal places for the specified data type. Some data types require that you specify a value for nPrecision. The following table shows the possible values for cFieldType, nFieldWidth, and nPrecision.

cFieldType nFieldWidth nPrecision Description

W, Blob

-

-

Blob

C, Char, Character

n

–

Character field of width n

Y, Currency

–

–

Currency

D, Date

–

–

Date

T, DateTime

–

–

DateTime

B, Double

–

d

Double

G, General

–

–

General

I, Int, Integer

–

–

Integer

L, Logical

–

–

Logical

M, Memo

–

–

Memo

N, Num, Numeric

n

d

Numeric field of width n with d decimal places

F, Float

n

d

Floating Numeric field of width n with d decimal places

Q, Varbinary

n

-

Varbinary field of width n

V, Varchar

n

-

Varchar field of width n
The nFieldWidth and nPrecision parameters are ignored for W, Y, D, T, G, I, L, and M types. If nPrecision is not included for the N, F, or B types, the nPrecision parameter defaults to zero (no decimal places).
NULL | NOT NULL

Specifies whether null values are allowed in the field. NULL permits null values, while NOTNULL does not allow null values.
CHECK lExpression

Specifies a validation rule for the field. The lExpression parameter must evaluate to a logical expression and can be a user-defined function or a stored procedure.
ERROR cMessageText

Specifies an error message. Visual FoxPro displays this message when the validation rule specified in the CHECK clause generates an error. The message displays only when data is changed within a Browse window or Edit window.
AUTOINC [NEXTVALUE NextValue [STEP StepValue]]

Enables autoincrementing for the field. NextValue specifies the start value and can be a positive or a negative integer value ranging from 2,147,483,647 to -2,147,483,647. The default value is 1. You can set NextValue using the Next Value box on the Fields tab in the Table Designer. StepValue specifies the increment value for the field and can be a positive, nonzero integer value ranging from 1 to 255. The default value is 1. You can set StepValue using the Step box on the Fields tab in the Table Designer. Autoincrementing values cannot be null (.NULL.).
Note:
Tables containing automatically incrementing field values append table-buffered records approximately 35% slower than tables without automatically incrementing field values, which might affect performance. When using table buffering, the table header is locked when the record is appended.

DEFAULT eExpression

Specifies a default value for the field. The data type of eExpression must be the same as the specified field's data type. If you use the AUTOINC clause to turn on autoincrementing for a field and specify a default value, Visual FoxPro stores the default value in the table but does not use it. Visual FoxPro uses the default value if you use the ALTER TABLE - SQL command to remove autoincrementing for the field.
UNIQUE

Creates a candidate index for the field. The candidate index tag has the same name as the field. For more information about candidate indexes, see Visual FoxPro Index Types.
COLLATE cCollateSequence

Specifies a collation sequence other than the default setting, MACHINE. The cCollateSequence parameter must be a valid Visual FoxPro collation sequence. For more information about setting collation sequences, see Optimizing International Applications and SET COLLATE Command.
NOCPTRANS

Prevents translation to a different code page for Character, Memo, and Varchar fields. You can specify NOCPTRANS only for Character, Memo, and Varchar fields.
FROM ARRAY ArrayName

Specifies the name of an existing array whose contents are the name, type, precision, and scale for each field in the temporary table. You can use the FROM ARRAY clause instead of specifying individual fields. For the proper format of the contents of the array, see AFIELDS( ) Function. Autoincrementing is turned on when the step value is greater than 0.

Remarks

You can manipulate a temporary table created with CREATE CURSOR like any other table — you can browse and index it, and you can append and modify records. The temporary table opens in the lowest numbered available (unused) work area and can be accessed by its alias. Each field in the temporary table is defined with a name, type, precision, and scale. These definitions can be obtained from the command itself or from an array. The temporary table opens exclusively, regardless of the setting of SET EXCLUSIVE.

If you omit NULL and NOT NULL, the current setting of SET NULL determines if null values are allowed in the field. However, if you omit NULL and NOT NULL and include the PRIMARY KEY or UNIQUE clause, Visual FoxPro disregards the current setting of SET NULL, and the field defaults to NOT NULL.

Null values and duplicate records are not permitted in a field used for a candidate index. However, Visual FoxPro does not generate an error if you create a candidate index for a field that supports null values. Visual FoxPro generates an error if you attempt to enter a null or duplicate value into a field used for a candidate index.

Note:
Candidate indexes, created by including the UNIQUE option (provided for ANSI compatibility) in CREATE TABLE – SQL or ALTER TABLE – SQL commands, are not the same as indexes created in the INDEX command with the UNIQUE option. An index created in the INDEX command using the UNIQUE option allows duplicate index keys; candidate indexes do not allow duplicate index keys. For more information about the UNIQUE option in the INDEX command, see INDEX Command.

If the table is converted to another code page, the fields for which NOCPTRANS has been specified are not translated.

CREATE CURSOR...FROM ARRAY recognizes all the fields available in the AFIELDS( ) function and turns on autoincrementing in the cursor when the Step value is greater than zero.

Example

The following example creates a cursor with the alias "employee." A blank record is appended, filled, and displayed with the BROWSE command.

Copy Code
CLOSE DATABASES
CLEAR
CREATE CURSOR employee ;
 (EmpID N(5), Name Character(20), Address C(30), City C(30), ;
  PostalCode C(10), OfficeNo C(8) NULL, Specialty Memo)
DISPLAY STRUCTURE
WAIT WINDOW "Press a key to add a record."

INSERT INTO employee (EmpId, Name, Address, City, PostalCode, ;
   OfficeNo, Specialty);
   VALUES (1002, "Dr. Bonnie Doren", "University of Oregon", "Eugene", ;
   "98403", "", "Secondary Special Education")
BROWSE

* At this point you can copy this record to a permanent table.
CLOSE ALL   && Once the cursor closes, all data is flushed from memory.
CLEAR

The following example uses NOCPTRANS to prevent translation to a different code page. The example creates a cursor named "mycursor" that contains two character fields and two memo fields. The second character field, "char2," and the second memo field, "memo2," include NOCPTRANS to prevent translation.

Copy Code
CREATE CURSOR mycursor (char1 C(10), char2 C(10) NOCPTRANS,;
   memo1 M, memo2 M NOCPTRANS)

See Also

Other Resources

AFIELDS( ) Function
CREATE Command
CREATE QUERY Command
CREATE TABLE - SQL Command
INSERT - SQL Command
MODIFY QUERY Command
SELECT - SQL Command
Commands
Language Reference


CREATE DATABASE Command

Visual FoxPro 9.0 Language Reference
CREATE DATABASE Command
See Also Example

Creates and opens a database.

CREATE DATABASE [DatabaseName | ?]

Parameters

[ DatabaseName| ?]

Specifies the name of the database to create or opens the Create dialog box so you can specify a name for the database and the location where you want to save the database. Omitting arguments for these parameters also opens the Create dialog box. Database files are saved with a .dbc file name extension.
Note:
If the SET SAFETY command is set to ON, and the database name that you specify has the same path and name as an existing database, Visual FoxPro prompts you to specify a different path or name for the database.

Remarks

A database (.dbc) file is created with an associated database memo (.dct) file and database index (.dcx) file.

The database opens exclusively, regardless of the setting of SET EXCLUSIVE. Because CREATE DATABASE opens the database after it has been created, you do not need to call a subsequent OPEN DATABASE command.

Using CREATE DATABASE does not add the database automatically to a project even when the Project Manager is open. You must explicitly add a database to an application project to include it. For more information, see

Example

This example creates a database named people. A table named friends is created and is automatically added to the database. DISPLAY TABLES is used to display the tables in the database, and DISPLAY DATABASES is used to display information about the tables in the database.
Copy Code
CREATE DATABASE people
CREATE TABLE friends (FirstName C(20), LastName C(20))
CLEAR
DISPLAY TABLES  && Displays tables in the database
DISPLAY DATABASES  && Displays table information

See Also

Other Resources

How to: Create Databases
ADD TABLE Command
CLOSE DATABASES Command
DELETE DATABASE Command
MODIFY DATABASE Command
OPEN DATABASE Command
SET DATABASE Command
Commands
Language Reference


CREATE FORM Command

Visual FoxPro 9.0 Language Reference
CREATE FORM Command
See Also

Opens the Form Designer.

CREATE FORM [FormName | ?] [AS cClassName FROM cClassLibraryName | ?]
   [NOWAIT] [SAVE] [DEFAULT] [[WINDOW WindowName1] [IN [WINDOW]
            WindowName2 | IN SCREEN]]

Parameters

FormName

Specifies the file name for the form. If you don't specify an extension for the file name, Visual FoxPro automatically assigns an .scx extension. If a form file with the name you specify already exists, you are asked if you want to overwrite the existing file (if SET SAFETY is set to ON).
?

Displays the Create dialog box from which you can choose a form or enter the name of a new form to create.
AS cClassNameFROM cClassLibraryName| ?

Creates a new form from a form class in a .vcx visual class library. cClassName specifies the name of the user-defined form class from which the new form is created. An error is generated if cClassName isn't based on a form. cClassLibraryName specifies the name of the .vcx visual class library containing the form class specified with cClassName. Include ? to display the Open dialog box, allowing you to specify the visual class library.
NOWAIT

Continues program execution after the Form Designer has been opened. The program doesn't wait for the Form Designer to be closed, but continues execution on the program line immediately following the line that contains CREATE FORM NOWAIT. If you omit NOWAIT, when CREATE FORM is issued in a program, the Form Designer is opened and program execution pauses until the Form Designer is closed. Including NOWAIT has no effect on CREATE FORM when it is issued in the Command window.
SAVE

When issued in a program, leaves the Form Designer open after another window is brought forward. Including the SAVE option has no effect when issued from the Command window.
DEFAULT

Specifies that the Form Designer is opened with the default Visual FoxPro form template, overriding a default form template specified on the Forms tab of the Options dialog. For additional information about form templates, see Creating Forms.
WINDOW WindowName1

Specifies a window whose characteristics the Form Designer takes on. For example, if the window is created with the FLOAT option of DEFINE WINDOW, the Form Designer can be moved. The window need not be active or visible, but it must be defined. The Form Designer has a default size that can be larger than the window from which it takes its characteristics. In this case, the Form Designer still assumes the characteristics of the window in which it is placed. The upper-left corner of the Form Designer is placed at the same coordinates as the upper-left corner of the window, and extends beyond the window's borders.
IN [WINDOW] WindowName2

Specifies a parent window in which the Form Designer is opened. The Form Designer doesn't assume the characteristics of the parent window and cannot be moved outside the parent window. If the parent window is moved, the Form Designer moves with it. The parent window must first be defined with DEFINE WINDOW, and must be visible, to access the Form Designer.
IN SCREEN

Specifies that the Form Designer is explicitly opened in the main Visual FoxPro window, after the Form Designer has been placed in a parent window. The Form Designer is placed in a parent window by including the IN WINDOW clause.

Remarks

Issuing CREATE FORM without any additional arguments opens a new form in the Form Designer. When you exit the Form Designer, you are prompted to save the form with a different name.

See Also

Other Resources

_BROWSER System Variable
COMPILE Command
DO FORM Command
GETPEM( ) Function
_INCLUDE System Variable
MODIFY FORM Command
PEMSTATUS( ) Function
Session Object
SYS(1269) - Property Information
SYS(1270) - Object Location
SYS(1271) - Object's .SCX File
SYS(1272) - Object Hierarchy
Commands
Language Reference


CREATE FROM Command

Visual FoxPro 9.0 Language Reference
CREATE FROM Command
See Also Example

Creates a table from a table created by the COPY STRUCTURE EXTENDED command.

CREATE [FileName1 [DATABASE DatabaseName [NAME LongTableName]]]
   FROM [FileName2]

Parameters

FileNam e1

Specifies the name of the new table to create.
DATABASE DatabaseName

Specifies a database to which the new table is added.
NAME LongTableName

Specifies a long name for the new table. Long names can contain up to 128 characters and can be used in place of short file names in the database.
FROM [ FileName2]

Specifies the table, created either manually or with COPY STRUCTURE EXTENDED, from which the new table is created.

Remarks

This variation of CREATE assumes that the table specified in FileName2 has been created either manually with COPY STRUCTURE EXTENDED. A new table FileName1 is created with the structure described in FileName2. The newly created table becomes the active table.

If you do not include either FileName1 or FileName2, or both, a dialog box appears. In this dialog box, you can specify the file to create or the FROM file, or both.

Note:
All records in FileName2, including those marked for deletion, are used to create FileName1.

CREATE FROM turns on autoincrementing for fields when the FIELD_STEP field in the table created by COPY STRUCTURE EXTENDED contains a valid value. The autoincrementing value and step values are retained from the original table.

Example

The following example displays the structure of the "Orders" table, copies the structure extended file to the "Temp" table, browses "Temp", creates a table called "Backup" from "Temp", and displays the structure of "Backup".
Copy Code
CLOSE DATABASES
CLEAR
SET PATH TO (HOME(2) + 'Data\')     && Sets path to database.
USE Orders
DISPLAY STRUCTURE
WAIT WINDOW 'Structure of the Orders table' NOWAIT
COPY STRUCTURE EXTENDED TO Temp
USE Temp
WAIT WINDOW 'Temp table has 1 row per field in Orders' NOWAIT
BROWSE
CREATE Backup FROM Temp
USE Backup
DISPLAY STRUCTURE
WAIT WINDOW 'Backup.dbf has the same structure as Orders' NOWAIT
USE
DELETE FILE Temp.dbf
DELETE FILE Backup.dbf

See Also

Other Resources

COPY STRUCTURE EXTENDED Command
COPY STRUCTURE Command
CREATE Command
Commands
Language Reference


CREATE LABEL Command

Visual FoxPro 9.0 Language Reference
CREATE LABEL Command
See Also

Opens the Label Designer to create a label in standard label format or to design a custom label.

CREATE LABEL [FileName | ?] [NOWAIT] [SAVE] [WINDOW WindowName1]
   [IN [WINDOW] WindowName2 | IN SCREEN] [PROTECTED]

Parameters

[ FileName| ?]

Specifies a file name for the label or displays the Create dialog box so you can type the name of the label file to create. The default file name extension for labels is .lbx.
Note:
Calling CREATE LABEL without arguments opens the Label Designer and assigns the label file with the default name of LabelVersionNumber. When you close the Label Designer, Visual FoxPro prompts you to save changes to the label and provide a different name.

[NOWAIT]

Continues program execution after the Label Designer opens. The program does not wait for the Label Designer to close but continues program execution on the immediate following line. If you omit NOWAIT, the Label Designer opens, and program execution pauses until the Label Designer closes. When calling CREATE LABEL with NOWAIT in the Command window, NOWAIT has no effect.
[SAVE]

Specifies that the Label Designer remain open after activating another window. If you omit SAVE, the Label Designer closes when you activate another window. When calling CREATE LABEL with SAVE in the Command window, SAVE has no effect.
[WINDOW WindowName1]

Specifies a window whose characteristics the Label Designer inherit. For example, if the window specified was created with the FLOAT option of DEFINE WINDOW, you can move the Label Designer. The specified window must be defined, but it does not need to be active or visible.
Note:
The Label Designer has a default size that can be larger than the specified window. In this case, the Label Designer still inherits the characteristics of the window with the upper-left corner of the Label Designer placed at the same coordinates as the upper-left corner of the specified window but extends beyond the specified window's borders.

[IN [WINDOW] WindowName2| IN SCREEN]

Specifies to open the Label Designer in a parent window or in the main Visual FoxPro window after placing the Label Designer in a parent window. The Label Designer does not assume the characteristics of the parent window and cannot move outside the parent window. If the parent window is moved, the Label Designer moves with it.
Note:
You must first define the parent window using DEFINE WINDOW and make it visible for access by the Label Designer.

[PROTECTED]

This clause is ignored by the Label Designer by default, because a newly created label layout will not have any protection flags set. However, a report builder can be written to take specific action if this clause is present in the collection of command line parameters. For example, the default Report Builder respects this clause by hiding the Protection tab of the Report Properties dialog box. See Understanding Report Builder Events for more information.

Remarks

You can also create labels using a wizard. For more information, see How to: Create Labels.

See Also

Other Resources

Label Designer
LABEL Command
MODIFY LABEL Command
Working with Reports
Commands


CREATE MENU Command

Visual FoxPro 9.0 Language Reference
CREATE MENU Command
See Also

Opens the Menu designer in Visual FoxPro.

CREATE MENU [FileName | ?] [NOWAIT] [SAVE] [WINDOW WindowName1]
   [IN [WINDOW] WindowName2 | IN SCREEN

Parameters

FileName

Specifies the file name for the menu table. If you don't specify an extension for the file name, Visual FoxPro automatically assigns an .mnx extension.
?

Displays the Create dialog box that prompts you to name the menu being created.
NOWAIT

Continues program execution after the Menu designer is opened. The program doesn't wait for the Menu designer to be closed, but continues execution on the program line immediately following the line that contains CREATE MENU NOWAIT. If you omit NOWAIT, when CREATE MENU is issued in a program, the Menu designer is opened and program execution pauses until the Menu designer is closed. If you issue CREATE MENU from the Command window and include NOWAIT, the New Menu dialog is not displayed. The New Menu dialog lets you specify the type of menu (standard or shortcut) created.
SAVE

Leaves the Menu designer open after another window is activated. If you omit SAVE, the Menu designer is closed when another window is activated. Including SAVE has no effect when issued from the Command window.
WINDOW WindowName1

Specifies a window whose characteristics the Menu designer takes on. For example, if the window is created with the FLOAT option of DEFINE WINDOW, the Menu designer can be moved. The window need not be active or visible, but it must be defined. The Menu designer has a default size that can be larger than the window from which it takes its characteristics. In this case, the Menu designer still assumes the characteristics of the window in which it is placed. The upper-left corner of the Menu designer is placed at the same coordinates as the upper-left corner of the window, and extends beyond the window's borders.
IN [WINDOW] WindowName2

Specifies a parent window in which the Menu designer is opened. The Menu designer doesn't assume the characteristics of the parent window and cannot be moved outside the parent window. If the parent window is moved, the Menu designer moves with it. The parent window must first be defined with DEFINE WINDOW, and must be visible, to access the Menu designer.
IN SCREEN

Specifies that the Menu designer is opened explicitly in the main Visual FoxPro window, after the Menu designer has been placed in a parent window. The Menu designer is placed in a parent window by including the IN WINDOW clause.

Remarks

Issuing CREATE MENU without any additional arguments opens the Menu designer within which you can define a menu system. The name MENU1 is temporarily assigned to the menu definition table. When you exit the Menu designer, you can save the menu definition under a different name.

See Also

Reference

_MENUDESIGNER System Variable

Other Resources

DEFINE MENU Command
MODIFY MENU Command
Menu Designer
Designing Menus and Toolbars
Commands
Language Reference


CREATE PROJECT Command

Visual FoxPro 9.0 Language Reference
CREATE PROJECT Command
See Also

Opens the Project Manager so you can create a project.

CREATE PROJECT [FileName | ?] [NOWAIT] [SAVE] [WINDOW WindowName1]
   [IN [WINDOW] WindowName2 | IN SCREEN [NOSHOW] [NOPROJECTHOOK]

Parameters

FileName

Specifies the file name for the project table. If you don't specify an extension for the file name, Visual FoxPro automatically assigns a .pjx extension.
?

Displays the Create dialog box that prompts you to name the project being created.
NOWAIT

Continues program execution after the Project Manager is opened. The program doesn't wait for the Project Manager to be closed, but continues execution on the program line immediately following the line that contains CREATE PROJECT NOWAIT. If you omit NOWAIT when CREATE PROJECT is issued in a program, the Project Manager is opened and program execution pauses until the Project Manager is closed. Including NOWAIT has no effect on CREATE PROJECT when it is issued in the Command window.
SAVE

Leaves the Project Manager open after another window is activated. If you omit SAVE, the Project Manager is closed when another window is activated. Including SAVE has no effect when issued from the Command window.
WINDOW WindowName1

Specifies a window whose characteristics the Project Manager takes on. For example, if the window is created with the FLOAT option of DEFINE WINDOW, the Project Manager can be moved. The window need not be active or visible, but it must be defined. The Project Manager has a default size that can be larger than the window from which it takes its characteristics. In this case, the Project Manager still assumes the characteristics of the window in which it is placed. The upper-left corner of the Project Manager is placed at the same coordinates as the upper-left corner of the window, and extends beyond the window's borders.
IN [WINDOW] WindowName2

Specifies a parent window in which the Project Manager is opened. The Project Manager doesn't assume the characteristics of the parent window and cannot be moved outside the parent window. If the parent window is moved, the Project Manager moves with it. The parent window must first be defined with DEFINE WINDOW, and must be visible, to access the Project Manager.
IN SCREEN

Specifies that the Project Manager is explicitly opened in the main Visual FoxPro window, after the Project Manager has been placed in a parent window. The Project Manager is placed in a parent window by including the IN WINDOW clause.
NOSHOW

Specifies that the Project Manager is hidden (its Visible property is set to False (.F.)) when it is opened. To display the Project Manager, set the Project Manager's Visible property to True (.T.). NOSHOW allows you to manipulate a project before displaying it in the Project Manager. Note that to avoid confusion with the NOSHADOW keyword, you cannot abbreviate NOSHOW to less than five characters.
NOPROJECTHOOK

Specifies that a ProjectHook object not be created when the Project Manager is opened. Include NOPROJECTHOOK for projects that will not be manipulated programmatically through the Project Manager hooks. Note that a Project object is still created whenever a project file (.pjx) is opened.

Remarks

A project is a table that keeps track of all files that are required to create an application, as well as all dependencies, references, and connections among the files. A project table has a .pjx extension and an associated memo file with a .pjt extension. In a project, you specify all the pieces that are required for an application, and Visual FoxPro ensures that compiled files are based on the latest source files.

A project table can be opened with USE and manipulated like any other Visual FoxPro table.

Issuing the command CREATE PROJECT without any additional arguments displays the Create dialog, allowing you to specify a name for the project.

See Also

Other Resources

BUILD APP Command
BUILD PROJECT Command
MODIFY PROJECT Command
Compiling an Application
Commands
Language Reference


CREATE QUERY Command

Visual FoxPro 9.0 Language Reference
CREATE QUERY Command
See Also

Opens the Query designer.

CREATE QUERY [FileName | ?] [NOWAIT]

Parameters

FileName

Specifies the file name for the query. If you don't specify an extension for the file name, Visual FoxPro automatically assigns a .qpr extension.
?

Displays the Create dialog box that prompts you to name the query being created.
NOWAIT

Continues program execution after the Query Designer is opened. The program doesn't wait for the Query Designer to be closed, but continues execution on the program line immediately following the line that contains CREATE QUERY NOWAIT. If you omit NOWAIT when CREATE QUERY is issued in a program, the Query Designer is opened and program execution pauses until the Query Designer is closed. NOWAIT is effective only from within a program. It has no effect on CREATE QUERY when issued from the Command window.

Remarks

CREATE QUERY opens the Query designer so you can interactively create a query.

A SQL SELECT command is used to retrieve data from tables. SELECT is very powerful and can replace a series of Visual FoxPro commands. Because one SQL SELECT performs the function of a series of Visual FoxPro commands, SELECT optimizes program performance.

Think of SELECT as a way to pose a query to Visual FoxPro to obtain information from tables. SELECT allows you to specify the information you want without telling Visual FoxPro how to retrieve the information. Visual FoxPro determines the best way to retrieve the information.

After you create a query, the query is stored as a Visual FoxPro program file with a .qpr extension. A query program can be executed with DO. You must include the query file extension when executing a query with DO, as shown in the following example.

Copy Code
DO my_query.qpr

Issuing the command CREATE QUERY without any additional arguments opens a new query window. The name QUERY1 is assigned to the query. When you exit the Query window, you can save the query with a different name.

See Also

Other Resources

MODIFY QUERY Command
SELECT - SQL Command
Query Designer
Commands
Language Reference


CREATE REPORT - Quick Report Command

Visual FoxPro 9.0 Language Reference
CREATE REPORT - Quick Report Command
See Also

Creates a report without opening the Report Designer.

CREATE REPORT FileName | ? FROM Source [FORM | COLUMN]
 [FIELDS FieldList] [ALIAS] [NOOVERWRITE] [WIDTH nColumns]

Parameters

FileName| ?

Specifies the file name for the report or displays the Create dialog box so you can type the name of the report file to create. The default file name extension for reports is .frx.
FROM Source

Specifies the name of the table to create the report from, which does not need to be open, or the alias of an open table. For example:
Copy Code
LOCAL lcFile
USE ? ALIAS temp
lcFile = PUTFILE("Report name","myreport.frx")
IF NOT EMPTY(lcFile)
   CREATE REPORT (lcFile) ;
      FROM (ALIAS())
ENDIF
Tip:
Note that this code does not check EMPTY(ALIAS()) before using Quick Report syntax. If no table is open in the current workarea, Visual FoxPro displays the open table dialog.

[FORM | COLUMN]

Specifies to create the report with the fields and their names arranged from top to bottom in the Detail band or with the fields arranged from left to right across the page in the Detail band. When specifying COLUMN, the field names are placed in the Page Header band.
Note:
If you omit FORM and COLUMN, the report defaults to COLUMN format.

[FIELDS FieldList]

Specifies the fields in the table that appear in the report. Use commas to separate the fields in FieldList.
[ALIAS]

Specifies to add the table alias to the field names in the report.
[NOOVERWRITE]

Specifies not to overwrite an existing report. If a report already exists with the file name specified with FileName1, the report is not created.
[WIDTH nColumns]

Specifies the width of the report page in columns.

Remarks

You can also create reports in Report Designer by using another version of CREATE REPORT. For more information, see CREATE REPORT Command.

You can also create reports using a wizard. For more information, see How to: Create Reports.

Depending on the setting of the _REPORTBUILDER system variable, this command may display additional dialogs as the report builder augments the quick report process. For more information, see _REPORTBUILDER System Variable .

See Also

Other Resources

MODIFY REPORT Command
REPORT Command
Report Designer
Working with Reports
Commands
Language Reference


CREATE REPORT Command

Visual FoxPro 9.0 Language Reference
CREATE REPORT Command
See Also

Opens the Report Designer to create a report in standard report format or to design a custom report.

CREATE REPORT [FileName | ?] [NOWAIT] [SAVE] [WINDOW WindowName1]
   [IN [WINDOW] WindowName2 | IN SCREEN] [PROTECTED]

Parameters

[ FileName| ?]

Specifies the file name for the report or displays the Create dialog box so you can type the name of the report file to create. The default file name extension for reports is .frx.
Note:
If the report file you specify already exists, Visual FoxPro prompts you to overwrite the existing file if the SET SAFETY command is set to ON. Calling CREATE REPORT without arguments opens the Report Designer and assigns the report file with the default name of ReportVersionNumber. When you close the Report Designer, Visual FoxPro prompts you to save changes to the report and provide a different name.

[NOWAIT]

Continues program execution after the Report Designer opens. The program does not wait for the Report Designer to close but continues program execution on the immediate following line. If you omit NOWAIT, the Report Designer opens, and program execution pauses until the Report Designer closes. When calling CREATE REPORT with NOWAIT in the Command window, NOWAIT has no effect.
[SAVE]

Specifies that the Report Designer remain open after activating another window. If you omit SAVE, the Report Designer closes when you activate another window. When calling CREATE REPORT with SAVE in the Command window, SAVE has no effect.
[WINDOW WindowName1]

Specifies a window whose characteristics the Report Designer inherit. For example, if the window specified was created with the FLOAT option of DEFINE WINDOW, you can move the Report Designer. The specified window must be defined, but it does not need to be active or visible.
Note:
The Report Designer has a default size that can be larger than the specified window. In this case, the Report Designer still inherits the characteristics of the window with the upper-left corner of the Report Designer placed at the same coordinates as the upper-left corner of the specified window but extends beyond the specified window's borders.

[IN [WINDOW] WindowName2| IN SCREEN]

Specifies to open the Report Designer in a parent window or in the main Visual FoxPro window after placing the Label Designer in a parent window. The Report Designer does not assume the characteristics of the parent window and cannot move outside the parent window. If the parent window is moved, the Report Designer moves with it.
Note:
You must first define the parent window using DEFINE WINDOW and make it visible for access by the Report Designer.

[PROTECTED]

This clause is ignored by the Report Designer by default, because a newly created report layout will not have any protection flags set. However, a report builder can be written to take specific action if this clause is present in the collection of command line parameters. For example, the default Report Builder will respect this clause by hiding the Protection tab of the Report Properties dialog box. See Understanding Report Builder Events for more information.

Remarks

You can also create reports using a wizard. For more information, see How to: Create Reports. You can also create quick reports without opening the Report Designer using another version of CREATE REPORT. For more information, see CREATE REPORT - Quick Report Command.

See Also

Other Resources

Report Designer
REPORT FORM Command
MODIFY REPORT Command
Working with Reports
Commands
Language Reference


CREATE SQL VIEW Command

Visual FoxPro 9.0 Language Reference
CREATE SQL VIEW Command
See Also Example

Opens the View Designer so you can create a SQL view.

CREATE [SQL] VIEW [ViewName] [REMOTE]
   [CONNECTION ConnectionName [SHARE] | CONNECTION DataSourceName]
   [AS SQLSELECTStatement]

Parameters

CREATE [SQL] VIEW

Creates a SQL view.
[ViewName]

Specifies the name of the view to create.
[REMOTE]

Specifies to create a view using tables from a remote data source, or a remote view. Omitting REMOTE creates a view using local tables.
[CONNECTION ConnectionName[SHARE] | CONNECTION DataSourceName]

Specifies the name of a previously defined connection or an existing data source to connect with when opening the view.
Note:
When you use the CONNECTION clause and specify the name of a connection or data source, Visual FoxPro first searches the current database for a connection with the name you specified. If the specified connection cannot be found, Visual FoxPro searches for an established ODBC data source with the specified name. Therefore, if your current database contains a named connection with the same name as an ODBC data source on your system, Visual FoxPro uses the named connection.

Tip:
If you use a CONNECTION clause with the CREATE SQL VIEW command, you do not need to include the REMOTE keyword. Visual FoxPro identifies the view as a remote view from the inclusion of the CONNECTION keyword.

The SHARE keyword specifies that Visual FoxPro use a new statement handle for the shared connection, if available. If a shared connection is not available, Visual FoxPro creates a shared connection when the view opens, which you might be able to share with other views.
[AS SQLSELECTStatement]

Specifies a SQL SELECT statement for the view. SQLSELECTStatement must be a valid SQL SELECT statement and should not be enclosed in quotation marks ("").
Tip:
For local views, preface the view or table name in the SQL SELECT statement with the name of the database and an exclamation point (!). By qualifying the table or view name with the database name and exclamation point, Visual FoxPro searches for the table in all open databases and in the default search path for the table. However, if you do not qualify a table with a database name in a view definition, the database must be open before you can use the view. For more information, see SELECT - SQL Command.

Remarks

A SQL view makes it possible for you to retrieve data from specific fields in one or more related tables as a table that you can update. For more information, see Working with Views.

Example

The following example closes all open databases and opens the Northwind sample database. CREATE SQL VIEW creates a local SQL view named MyView using a SQL SELECT statement that selects all records from the Customers table where the Country field contains "Mexico". MODIFY VIEW displays the view in the View Designer so you can edit the view. After you close the View Designer, DELETE VIEW deletes the view.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Northwind\Northwind')
CREATE SQL VIEW MyView AS SELECT * FROM Northwind!Customers;
   WHERE Country="Mexico"
MODIFY VIEW MyView
DELETE VIEW MyView

For more information, see CLOSE Commands, OPEN DATABASE Command, MODIFY VIEW Command, and DELETE VIEW Command.

See Also

Other Resources

Commands
Language Reference


CREATE TABLE - SQL Command

Visual FoxPro 9.0 Language Reference
CREATE TABLE - SQL Command
See Also

Creates a table using the specified fields or from an array.

CREATE TABLE | DBF TableName1 [NAME LongTableName] [FREE]
    [CODEPAGE = nCodePage]
    ( FieldName1 FieldType [( nFieldWidth [, nPrecision] )] [NULL | NOT NULL]
    [CHECK lExpression1 [ERROR cMessageText1]]
    [AUTOINC [NEXTVALUE NextValue [STEP StepValue]]] [DEFAULT eExpression1]
    [PRIMARY KEY | UNIQUE [COLLATE cCollateSequence]]
    [REFERENCES TableName2 [TAG TagName1]] [NOCPTRANS]
    [, FieldName2 ... ]
    [, PRIMARY KEY eExpression2 TAG TagName2 |, UNIQUE eExpression3 TAG TagName3
    [COLLATE cCollateSequence]]
    [, FOREIGN KEY eExpression4 TAG TagName4 [NODUP]
    [COLLATE cCollateSequence]
    REFERENCES TableName3 [TAG TagName5]] [, CHECK lExpression2 [ERROR cMessageText2]] )
    | FROM ARRAY ArrayName

Parameters

CREATE TABLE | DBF TableName1

Creates a table or .dbf. The TableName1 parameter specifies the name of the table. The TABLE and DBF options are identical.
nCodePage

Specifies the code page to use. For a list of code pages, see Code Pages Supported by Visual FoxPro.
NAME LongTableName

Specifies a long name for the table. You can specify a long table name only when a database is open because long table names are stored in databases. Long names can contain up to 128 characters and can be used in place of short file names in the database.
FREE

Specifies that the table is to not be added to an open database. You do not need to use FREE if a database is not open.
FieldName1, FieldType, nFieldWidth,nPrecision

Specifies the field name, field type, field width, and field precision (number of decimal places) respectively. A single table can contain up to 255 fields. If one or more fields allow null values, the limit decreases by one field to 254 fields. The FieldType parameter is a single letter or long name indicating the field's data type. You can specify nFieldWidth, nPrecision, or both for some field types. The following table lists the values for FieldType and whether you can specify nFieldWidth and nPrecision.

FieldType nFieldWidth nPrecision Data type

W, Blob

-

-

Blob

C, Char, Character

n

–

Character field of width n

Y, Currency

–

–

Currency

D, Date

–

–

Date

T, DateTime

–

–

DateTime

B, Double

–

d

Double

G, General

–

–

General

I, Int, Integer

–

–

Integer

L, Logical

–

–

Logical

M, Memo

–

–

Memo

N, Num, Numeric

n

d

Numeric field of width n with d decimal places

F, Float

n

d

Floating Numeric field of width n with d decimal places

Q, Varbinary

n

-

Varbinary field of width n

V, Varchar

n

-

Varchar field of width n
The nFieldWidth and nPrecision parameters are ignored for the W, Y, D, T, G, I, L, and M field types. If nPrecision is not included for the N or F types, the nPrecision parameter defaults to zero (no decimal places). If nPrecision is not included for the B type, the nPrecision parameter defaults to the number of decimal places specified by the setting of the SET DECIMALS command.
NULL | NOT NULL

Specifies whether null values are allowed in the field. NULL permits null values, while NOT NULL does not allow null values. If one or more fields can contain null values, the maximum number of fields the table can contain is reduced from 255 to 254.
CHECK lExpression1

Specifies a validation rule for the field. The lExpression1 parameter must evaluate to a logical expression and can be a user-defined function or a stored procedure. Visual FoxPro checks the validation rule specified in the CHECK clause when a blank record is appended.
ERROR cMessageText1

Specifies an error message. Visual FoxPro displays this message when the validation rule specified with the CHECK clause generates an error. The message displays only when data is changed within a Browse window or Edit window.
AUTOINC [NEXTVALUE NextValue [STEP StepValue]]

Enables autoincrementing for the field. NextValue specifies the start value and can be a positive or a negative integer value ranging from -2,147,483,647 to 2,147,483,647. The default value is 1. You can set NextValue using the Next Value spin box in Fields tab of the Table Designer. StepValue specifies the increment value for the field and can be a positive, nonzero integer value ranging from 1 to 255. The default value is 1. You can set StepValue using the Step spin box in the Fields tab of the Table Designer. Autoincrementing values cannot be NULL.
Note:
Tables containing automatically incrementing field values append table-buffered records approximately 35% slower than tables without automatically incrementing field values, which might affect performance. When using table buffering, the table header is locked when the record is appended.

DEFAULT eExpression1

Specifies a default value for the field specified in FieldName1. The data type of eExpression1 must be the same as the specified field's data type. If you use the AUTOINC clause to turn on autoincrementing for a field and specify a default value, Visual FoxPro stores the default value in the table but does not use it. Visual FoxPro uses the default value if you use the SQL ALTER TABLEcommand to remove autoincrementing for the field.
PRIMARY KEY | UNIQUE

PRIMARY KEY creates a primary index for the field specified in FieldName1. UNIQUE creates a candidate index for the field specified in FieldName1. The primary index tag or candidate index tag have the same name as the field. For more information about primary and candidate indexes, see Visual FoxPro Index Types.
COLLATE cCollateSequence

Specifies a collation sequence other than the default setting, MACHINE. The cCollateSequence parameter must be a valid Visual FoxPro collation sequence.
Tip:
You can also use the SET COLLATE command before creating an index. For more information about setting collation sequences, see Optimizing International Applications and SET COLLATE Command.

REFERENCES TableName2 [TAG TagName1]

Specifies the parent table to which a persistent relationship is established. The parent table cannot be a free table. The TagName1 parameter clause specifies an index tag name for the parent table in TableName2. Index tag names can contain up to 10 characters. If you omit the TAGclause, the relationship is established using the primary index key of the parent table. If the parent table does not have a primary index, Visual FoxPro generates an error.
NOCPTRANS

Prevents translation to a different code page for Character, Memo, and Varchar fields. You can specify NOCPTRANS only for character and memo fields. This creates what appears to be Character (Binary), Memo (Binary), and Varchar (Binary) data types in the Table Designer.
FieldName2 ...

Specifies one or more additional fields and attributes.
PRIMARY KEY eExpression2 TAG TagName2

Specifies any field or combination of fields in the table for creating a primary index. You cannot use this PRIMARY KEY clause if you previously created a primary index for a field because a table can have only one primary index. If you include more than one PRIMARY KEY clause in a CREATE TABLE statement, Visual FoxPro generates an error. The TagName2 parameter specifies a name for the primary index tag in eExpression2. Index tag names can contain up to 10 characters.
UNIQUE eExpression3 TAG TagName3

Specifies any field or combination of fields in the table for creating a candidate index. A table can have multiple candidate indexes. However, if you previously created a primary index with one of the PRIMARY KEY options, you cannot include the field that was specified for the primary index. The TagName3 parameter specifies a name for the candidate index tag in eExpression3. Index tag names can contain up to 10 characters.
FOREIGN KEY eExpression4 TAG TagName4 [ NODUP ]

Creates a foreign (non-primary) index, specifies the index key expression, and establishes a relationship to a parent table. You can create multiple foreign indexes for the table, but foreign index expressions must specify different fields in the table. The TagName4 parameter specifies the name for the foreign index key tag. Index tag names can contain up to 10 characters. NODUP creates a candidate foreign index.
REFERENCES TableName3 TAG TagName5

Specifies the parent table to which a persistent relationship is established. The TagName5 parameter specifies the name of the index tag for the parent table in TableName3 and establishes a relation based on the index tag. Index tag names can contain up to 10 characters. If you omit the TAG clause, the relationship is established by default using the primary index key of the parent table.
CHECK lExpression2

Specifies the table validation rule. The lExpression2 parameter must evaluate to a logical expression and can be a user-defined function or a stored procedure.
ERROR cMessageText2

Specifies an error message for the table validation rule in lExpression2. Visual FoxPro displays this message when the table validation rule generates an error. The message displays only when data is changed within a Browse window or Edit window.
FROM ARRAY ArrayName

Specifies the name of an existing array whose contents are the name, type, precision, and scale for each field in the table. You can use the FROM ARRAY clause instead of specifying individual fields in the SQL CREATE TABLE statement. For the proper format of the contents of the array, see AFIELDS( ) Function. Autoincrementing is turned on when StepValue is greater than 0.

Remarks

The new table opens in the lowest numbered available (unused) work area and can be accessed by its alias. The new table opens exclusively, regardless of the current setting of the SET EXCLUSIVE command.

If a database is open and you do not include the FREE clause, the new table is added to the database. You cannot create a new table with the same name as a table in the database.

If the table is converted to another code page, the fields for which NOCPTRANS has been specified are not translated.

If a database is not open when you create the new table, including the NAME, CHECK, DEFAULT, FOREIGN KEY, PRIMARY KEY, or REFERENCES clauses generates an error.

Tables created in the Visual FoxPro OLE DB Provider using CREATE TABLE are placed in the default folder of the calling application, unless you specify another location.

Note:
The CREATE TABLE syntax uses commas to separate certain CREATE TABLE options. You must place the NULL, NOT NULL, CHECK, DEFAULT, PRIMARY KEY, and UNIQUE clauses within the parentheses containing the column definitions.

If you omit NULL and NOT NULL, the current setting of the SET NULL command determines if null values are allowed in the field. However, if you omit NULL and NOT NULL but include the PRIMARY KEY or UNIQUE clause, Visual FoxPro disregards the current setting of SET NULL, and the field defaults to NOT NULL.

Visual FoxPro generates an error if the validation rule specified in the CHECK clause does not allow for a blank field value in an appended record.

Null values and duplicate records are not permitted in a field used for a primary or candidate index. However, Visual FoxPro does not generate an error if you create a primary or candidate index for a field that supports null values. Visual FoxPro generates an error if you attempt to enter a null or duplicate value into a field used for a primary or candidate index.

Note:
Candidate indexes that you create by including the UNIQUE option, which is provided for ANSI compatibility, in SQL CREATE TABLE or ALTER TABLEcommands are not the same as indexes created using the INDEX command with the UNIQUE option. An index created in the INDEX command using the UNIQUE option allows duplicate index keys; candidate indexes do not allow duplicate index keys. For more information about the UNIQUE option in the INDEX command, see INDEX Command. The term CANDIDATE is a synonym of UNIQUE and can be used instead if you choose.

For NextValue, an empty value is interpreted as 0 and causes incrementing to begin with 0 + StepValue.

The StepValue incremental value is always positively added. If you want to use a negative automatically incrementing series, you should begin with a negative NextValue and step towards 0 using the StepValue increment value. For example, if NextValue equals -2147483647, the first step produces a value of -2147483646.

CREATE TABLE recognizes all the fields available in the AFIELDS( ) function and turns on autoincrementing in the table when StepValue is greater than zero.

Examples

Example 1

The following example creates a new database named MyData1 and usesCREATE TABLE to create three tables: Salesman, Customer, and Orders. The FOREIGN KEY and REFERENCES clauses in the second CREATE TABLE command create a persistent one-to-many relationship between the Salesman and Customer tables. The DEFAULT clauses in the third CREATE TABLE command establish default values, and the CHECK and ERROR clauses establish business rules for entering data into specific fields. The MODIFY DATABASE command displays the relationship between the three tables.

Copy Code
CLOSE DATABASES
CLEAR
CREATE DATABASE mydata1

* Create a Salesman table with a primary key.
CREATE TABLE Salesman ;
   (SalesID c(6) PRIMARY KEY, ;
   SaleName Character(20))

* Create a Customer table and relate it to the Salesman table.
CREATE TABLE Customer ;
   (SalesID c(6), ;
   CustId i PRIMARY KEY, ;
   CustName c(20) UNIQUE,   ;
   SalesBranch c(3), ;
   FOREIGN KEY SalesId TAG SalesId REFERENCES Salesman)

* Create an Orders table related to Customer with its own primary
* key and some business rules such as defaults and checks.
CREATE TABLE Orders ;
   (OrderId i PRIMARY KEY, ;
      CustId i REFERENCES customer TAG CustId, ;
      OrderAmt y(4), ;
      OrderQty i ;
      DEFAULT 10 ;
      CHECK (OrderQty > 9) ;
      ERROR "Order Quantity must be at least 10", ;
         DiscPercent n(6,2) NULL ;
      DEFAULT .NULL., ;
      CHECK (OrderAmt > 0) ERROR "Order Amount must be > 0" )

* Display new database, tables, and relationships.
MODIFY DATABASE

* Delete example files.
SET SAFETY OFF && Suppress verification message.
CLOSE DATABASES     && Close database before deleting.
DELETE DATABASE mydata1 DELETETABLES

Example 2

The following example uses NOCPTRANS to prevent translation to a different code page. The example creates a table named MyTable that contains two character fields and two memo fields. The second character field, "char2", and the second memo field, "memo2", include NOCPTRANS to prevent translation.

Copy Code
CREATE TABLE MyTable (char1 C(10), char2 C(10) NOCPTRANS,;
   memo1 M, memo2 M NOCPTRANS)

Example 3

The following example creates a Customer table with a field called MyField that has Integer data type and uses automatically incrementing field values:

Copy Code
CREATE TABLE Customer (MyField i AUTOINC NEXTVALUE 1 STEP 1, name c(40) )

See Also

Reference

CREATE Command

Other Resources

Autoincrementing Field Values in Tables
CREATE QUERY Command
INSERT – SQL Command
MODIFY QUERY Command
MODIFY STRUCTURE Command
OPEN DATABASE Command
SELECT – SQL Command
SET NOCPTRANS Command
SQL Commands Overview
Commands
Language Reference


CREATE TRIGGER Command

Visual FoxPro 9.0 Language Reference
CREATE TRIGGER Command
See Also Example

Creates a Delete, Insert, or Update trigger for a table.

CREATE TRIGGER ON TableName   FOR DELETE | INSERT |
UPDATE AS lExpression

Parameters

TableName

Specifies the table in the current database for which a trigger is created.
FOR DELETE | INSERT | UPDATE

Specifies the type of trigger Visual FoxPro creates. If a trigger of the type you specify already exists and SET SAFETY is ON, Visual FoxPro asks you if you would like to overwrite the existing trigger. If SET SAFETY is OFF, the existing trigger is automatically overwritten.
AS lExpression

Specifies the logical expression evaluated when the trigger occurs. lExpression can be a user-defined function or a stored procedure that returns a logical value. Stored procedures are created for a table with MODIFY PROCEDURE. A user-defined function or a stored procedure can use AERROR( ) to determine the name of the table for which the trigger occurred and the trigger type. If lExpression evaluates to true (.T.), the command or event that caused the trigger to occur is executed. If lExpression evaluates to false (.F.), the command or event that caused the trigger to occur is not executed. If an ON ERROR procedure is in effect, the ON ERROR procedure is executed instead of the command or event. If an ON ERROR procedure is not in effect, the command or event is not executed and Visual FoxPro generates an error message.

Remarks

Use CREATE TRIGGER to trap for events that cause records in a table to be deleted, added, or changed. Delete, Insert, or Update triggers can be created only for a table that has been added to a database. Use CREATE DATABASE to create a database, and ADD TABLE to add a table to a database.

The following table describes the events that cause a Delete, Insert, or Update trigger to occur.

Event Result

Delete Trigger
  • DELETE is issued.

  • A record is marked for deletion from the Table Menu in a Browse window or Edit window.

  • Note that issuing ZAP does not cause the Delete trigger to occur.

Insert Trigger
  • APPEND FROM is issued.

  • APPEND FROM ARRAY is issued.

  • APPEND BLANK is issued.

  • A record is appended from the Table Menu in a Browse window or Edit window.

  • IMPORT is issued.

  • INSERT – SQL is issued.

  • RECALL is issued.

  • A record is recalled from the Table Menu in a Browse window or Edit window.

Update Trigger
  • GATHER is issued.

    The following rules apply to triggers created with CREATE TRIGGER:

    • INSERT cannot be issued for a table with a trigger. However, INSERT – SQL can be used.

    • Issuing PACK does not cause any triggers to occur.

    • Issuing ZAP does not cause a Delete trigger to occur.

    • No trigger occurs if you update a record marked for deletion.

    • A trigger may not occur immediately, depending on the current buffering mode:

  • REPLACE is issued.

  • REPLACE FROM ARRAY is issued.

  • UPDATE – SQL is issued.

  • Other event that causes a record to be modified, such as when a Form changes the contents of a field.

If table buffering is in effect, the Update trigger occurs when TABLEUPDATE( ) is issued and each buffered record is updated in the table.

Example

The following example creates an Update trigger which prevents values greater than 50 from being entered in the maxordamt field in the customer table. An error message is generated when the first REPLACE command is executed because the value for the maxordamt field is greater than 50. The second REPLACE command does not generate an error because the value for the maxordamt field is less than or equal to 50.
Copy Code
CLOSE DATABASES

OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table

* Set trigger on maxordamt field to fail with values <= 50
CREATE TRIGGER ON customer FOR UPDATE AS maxordamt <= 50

ON ERROR  && Restore the system error handler

WAIT WINDOW "Press a key to test trigger with value of 60"+CHR(13);
 +"When you get the error message, press Ignore."
REPLACE maxordamt WITH 60    && Displays an error message
? maxordamt

WAIT WINDOW "Press a key to test with value of 50."
REPLACE maxordamt WITH 50    && Value is accepted
? maxordamt
DELETE TRIGGER ON customer FOR UPDATE  && Remove the trigger

See Also

Other Resources

ADD TABLE Command
AERROR( ) Function
CREATE DATABASE Command
DELETE TRIGGER Command
DISPLAY DATABASE Command
LIST DATABASE Command
OPEN DATABASE Command
Commands
Language Reference


CREATE VIEW Command

Visual FoxPro 9.0 Language Reference
CREATE VIEW Command
See Also

Creates a view file from the Visual FoxPro environment.

CREATE VIEW FileName

Parameters

FileName

Specifies the name of the view file to create.

Remarks

CREATE VIEW builds a new view file containing information about the Visual FoxPro environment. SET VIEW restores the environment saved to a view file by CREATE VIEW. View files created with CREATE VIEW are assigned a .vue extension.

The information saved in a view file includes:

  • All tables, index, alternate files, and format files currently open in all work areas

  • All fields contained in the SET FIELDS list

  • All established relations between open tables

  • All filters in effect for open tables

  • The DEFAULT and PATH settings

  • The procedure file setting

  • The current Help file

  • The current resource file

  • The SET SKIP status

  • The status bar state (ON or OFF)

View files are useful both in programs and while debugging. Only one command, SET VIEW TO FileName, needs to be executed to restore the entire environment. While debugging, the environment settings can be saved in a view file, testing can be performed, and the environment can be restored to continue program execution.

See Also

Other Resources

CREATE SQL VIEW Command
SET VIEW Command
SET SKIP Command
SET FIELDS Command
Commands
Language Reference


DEACTIVATE MENU Command

Visual FoxPro 9.0 Language Reference
DEACTIVATE MENU Command
See Also Example

Deactivates a user-defined menu bar and removes it from the screen; but does not remove the menu-bar definition from memory.

DEACTIVATE MENU MenuName1 [, MenuName2 ...] | ALL

Parameters

MenuName1[, MenuName2...]

Specifies the names of the menu bars to deactivate. You can deactivate a set of menu bars by including a list of menu bar names separated by commas.
ALL

Deactivates all active menus.

Remarks

DEACTIVATE MENU removes an active menu bar or set of menu bars from the main Visual FoxPro window or a user-defined window without removing the menu bar definition from memory. A menu bar can be reactivated with ACTIVATE MENU and the menu bar name.

Tip:
When you include the system menu bar (_MSYSMENU) in an application, you do not need to define, activate, or deactivate the menu bar. Instead, issue SET SYSMENU AUTOMATIC.

To release a specific menu bar or a set of menu bars from memory, use RELEASE MENUS. You can release all menu bars from memory with CLEAR MENUS or CLEAR ALL.

Program control is returned to the program line immediately following the line that activated the menu bar unless DEFINE MENU BAR is used to create the menu bar or ACTIVATE MENU NOWAIT is used to activate the menu bar.

Example

The following example uses DEACTIVATE MENU to deactivate a menu and remove it from the screen. The current system menu bar is saved to memory with SET SYSMENU SAVE, and all the system menu titles are removed with SET SYSMENU TO.

Two menu titles are created with DEFINE PAD, and DEFINE POPUP creates a menu for each menu title. DEFINE BAR creates menu items on each of the menus. When a menu title is chosen, ON PAD uses ACTIVATE POPUP to activate the corresponding menu. ACTIVATE MENU displays and activates the menu bar.

When an item is chosen from a menu, the CHOICE procedure is executed. CHOICE displays the name of the chosen item and the name of the menu containing the item. Program control continues on the line after ACTIVATE MENU.

Finally, the menu is deactivated and removed from the screen and is then released from memory with RELEASE MENUS EXTENDED.
Copy Code
*** Name this program DEACMENU.PRG ***
CLEAR
SET SYSMENU SAVE
SET SYSMENU TO
ON KEY LABEL ESC KEYBOARD CHR(13)
DEFINE MENU example BAR AT LINE 1
DEFINE PAD convpad OF example PROMPT '\<Conversions' COLOR SCHEME 3 ;
   KEY ALT+C, ''
DEFINE PAD cardpad OF example PROMPT 'Card \<Info' COLOR SCHEME 3 ;
   KEY ALT+I, ''
ON PAD convpad OF example ACTIVATE POPUP conversion
ON PAD cardpad OF example ACTIVATE POPUP cardinfo
DEFINE POPUP conversion MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF conversion PROMPT 'Ar\<ea' ;
   KEY CTRL+E, '^E'
DEFINE BAR 2 OF conversion PROMPT '\<Length' ;
   KEY CTRL+L, '^L'
DEFINE BAR 3 OF conversion PROMPT 'Ma\<ss' ;
   KEY CTRL+S, '^S'
DEFINE BAR 4 OF conversion PROMPT 'Spee\<d' ;
   KEY CTRL+D, '^D'
DEFINE BAR 5 OF conversion PROMPT '\<Temperature' ;
   KEY CTRL+T, '^T'
DEFINE BAR 6 OF conversion PROMPT 'T\<ime' ;
   KEY CTRL+I, '^I'
DEFINE BAR 7 OF conversion PROMPT 'Volu\<me' ;
   KEY CTRL+M, '^M'
ON SELECTION POPUP conversion DO choice IN deacmenu WITH PROMPT( ), POPUP( )
DEFINE POPUP cardinfo MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF cardinfo PROMPT '\<View Charges' ;
   KEY ALT+V, ''
DEFINE BAR 2 OF cardinfo PROMPT 'View \<Payments' ;
   KEY ALT+P, ''
DEFINE BAR 3 OF cardinfo PROMPT 'Vie\<w Users' ;
   KEY ALT+W, ''
DEFINE BAR 4 OF cardinfo PROMPT '\-'
DEFINE BAR 5 OF cardinfo PROMPT '\<Charges '
ON SELECTION POPUP cardinfo;
   DO choice IN deacmenu WITH PROMPT( ), POPUP( )

ACTIVATE MENU example
DEACTIVATE MENU example
RELEASE MENU example EXTENDED
SET SYSMENU NOSAVE
SET SYSMENU TO DEFAULT
ON KEY LABEL ESC

PROCEDURE choice
PARAMETERS mprompt, mpopup
WAIT WINDOW 'You chose ' + mprompt + ;
   ' from popup ' + mpopup NOWAIT

See Also

Other Resources

ACTIVATE MENU Command
CLEAR ALL Command
CLEAR MENUS Command
CREATE MENU Command
DEFINE MENU Command
HIDE MENU Command
RELEASE Command
SHOW MENU Command
Commands
Language Reference


DEACTIVATE POPUP Command

Visual FoxPro 9.0 Language Reference
DEACTIVATE POPUP Command
See Also

Deactivates a menu created with DEFINE POPUP.

DEACTIVATE POPUP MenuName1 [, MenuName2 ...] | ALL

Parameters

MenuName1[, MenuName2...]

Specifies the names of the menu or menus to deactivate. You can deactivate a set of menus by including a list of menu names separated by commas.
ALL

Deactivates all active menus.

Remarks

DEACTIVATE POPUP removes an active menu or set of menus from the main Visual FoxPro window or a user-defined window without removing the menu definition from memory. A menu can be reactivated using ACTIVATE POPUP and the menu name.

Use RELEASE POPUPS with the menu name to release a specific menu or a set of menus from memory. You can release all menus from memory with CLEAR POPUPS or CLEAR ALL.

Program control is returned to the line immediately following the line that activated the menu unless ACTIVATE POPUP NOWAIT is used to activate the menu.

See Also

Other Resources

ACTIVATE POPUP Command
CLEAR ALL Command
CLEAR POPUPS Command
CREATE MENU Command
DEFINE POPUP Command
HIDE POPUP Command
RELEASE POPUPS Command
SHOW POPUP Command
Commands
Language Reference


DEACTIVATE WINDOW Command

Visual FoxPro 9.0 Language Reference
DEACTIVATE WINDOW Command
See Also Example

Deactivates user-defined windows or Visual FoxPro system windows and removes them from the screen, but not from memory.

DEACTIVATE WINDOW WindowName1 [, WindowName2 ...] | ALL

Parameters

WindowName1[, WindowName2...]

Specifies one or more windows to deactivate. You can specify Visual FoxPro system windows such as the Command window or a Browse window.
ALL

Deactivates all active windows. To display the main FoxPro window again, choose Visual FoxPro Screen from the Window menu or issue ACTIVATE WINDOW SCREEN or SHOW WINDOW SCREEN.

Remarks

More than one user-defined window can be placed in the main Visual FoxPro window at the same time, but output is directed only to the most recently activated user-defined window. When more than one user-defined window is present, deactivating the current user-defined output window clears the contents of the window, removes the window from the screen and sends subsequent output to the previously activated user-defined window. If there is no output window, output is directed to the main Visual FoxPro window.

Use CLEAR WINDOWS or RELEASE WINDOWS to remove windows from both the screen and memory.

To deactivate a system window and or a toolbar (in Visual FoxPro), enclose the entire system window or toolbar name in quotation marks. For example, to deactivate the Report Controls toolbar in Visual FoxPro, issue the following command:

Copy Code
DEACTIVATE WINDOW "Report Controls"

Historically in prior versions of Visual FoxPro, the Data Session window has always been referred to as the View window. Additionally, language used to control this window, such as HIDEWINDOW, ACTIVATEWINDOW, WONTOP( ), also refers to this window as the View window. Visual FoxPro continues to refer to the View window for the DEACTIVATEWINDOW command.

Example

In the following example, a window named wOutput1 is defined and activated. After a record from the customer table is displayed, the program waits for the user to press a key and then deactivates the window.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

CLEAR
DEFINE WINDOW wOutput1 FROM 2,1 TO 13,75 TITLE 'Output' ;
   CLOSE FLOAT GROW ZOOM
ACTIVATE WINDOW wOutput1

DISPLAY
WAIT WINDOW 'Press a key to deactivate the window'
DEACTIVATE WINDOW wOutput1
RELEASE WINDOW wOutput1

See Also

Other Resources

ACTIVATE WINDOW Command
CLEAR WINDOWS Command
DEFINE WINDOW Command
HIDE WINDOW Command
RELEASE WINDOWS Command
SHOW WINDOW Command
Commands
Language Reference


DEBUG Command

Visual FoxPro 9.0 Language Reference
DEBUG Command
See Also

Opens the Visual FoxPro debugger.

DEBUG

Remarks

The debugger Environment setting (FoxPro Frame or Debugger Frame) determines if the debugger is placed on the Visual FoxPro desktop or in a separate window. Toggle this setting in the Debugging tab of the Options dialog box.

If you issue DEBUG when the debugger is open, the debugger becomes the active window.

See Also

Other Resources

CLOSE DEBUGGER Command
Debug Tab, Options Dialog Box
DEBUGOUT Command
SET DEBUG Command
Commands
Language Reference


DEBUGOUT Command

Visual FoxPro 9.0 Language Reference
DEBUGOUT Command
See Also Example

Directs the result of one or more expressions to the Debug Output window.

DEBUGOUT eExpression1 [, eExpression2] ...

Parameters

eExpression1 [, eExpression2] ...

Specifies one or more expressions to evaluate and display in the Debug Output window. You can specify multiple expressions of different types. If the expression you specify is an object or object reference, Visual FoxPro automatically converts it to the string, "(Object)", to provide the character equivalent. In the following example, the _VFP system variable is returned as "(Object)" and passed to DEBUGOUT:
Copy Code
DEBUGOUT 123, _VFP, "Hello"

Remarks

Use DEBUGOUT to identify when a procedure or function is executed. For example, you can place DEBUGOUT at the beginning of a procedure to display a message in the Debug Output window, indicating that the procedure has begun executing.

Note:
You can abbreviate DEBUGOUT to a minimum of only six characters, which distinguishes it from the DEBUG command.

When you pass multiple expressions, a comma appears as a space. A carriage return line feed (CRLF) is added at the end of the line.

DEBUGOUT is disregarded in applications you distribute.

Example

The following example illustrates how DEBUGOUT can accept multiple expressions:
Copy Code
DEBUGOUT "test", 1, 2, 3, 4, DATE( ), _VFP

See Also

Other Resources

DEBUG Command
Debug Output Window
SET DEBUG Command
Commands
Language Reference


DECLARE - DLL Command

Visual FoxPro 9.0 Language Reference
DECLARE - DLL Command
See Also Example

Registers a function in an external shared library. Libraries are 32-bit dynamic link library (.DLL) files.

DECLARE [cFunctionType] FunctionName IN LibraryName [AS AliasName]
   [cParamType1 [@] ParamName1, cParamType2 [@] ParamName2, ...]

Parameters

cFunctionType

Indicates the data type of the return value from the shared library, if any. If the function does not return a value, omit cFunctionType. cFunctionType can assume the following values:

cFunctionType Description

SHORT

16-bit integer

INTEGER

32-bit integer

SINGLE

32-bit floating point

DOUBLE

64-bit floating point

LONG

32-bit long integer

STRING

Character string

OBJECT

IDispatch object type
FunctionName

Specifies the name of the shared library function to register in Visual FoxPro. Function names passed in this parameter are case-sensitive.
Note:
A DLL function name may not be the same as stated in the Win32 API manual. For example, the MessageBox function should be named MessageBoxA (for single-byte character), and MessageBoxW (for UNICODE). If Visual FoxPro cannot locate the DLL function you specify with FunctionName, the letter A is appended to the end of the function name and Visual FoxPro searches again for the function with the new name.

If the shared library function you specify has the same name as a Visual FoxPro function or is not a legal Visual FoxPro name, use the AS clause to assign an alias to the function when you register it, as described later in this topic. You can also use OBJECT as a return value, such as "DECLARE OBJECT myfunc IN some DLL ..." although COM conventionally does not have any APIs of this form. For example:
Copy Code
DECLARE INTEGER AccessibleObjectFromWindow IN oleacc.dll ;
integer, integer, string , object @
IN LibraryName

Specifies the name of the external shared library containing the function specified with FunctionName. If you specify WIN32API for the LibraryName, Visual FoxPro searches for the 32-bit Windows .dll function in Kernel32.dll, Gdi32.dll, User32.dll, Mpr.dll, and Advapi32.dll.
AS AliasName

Specifies an alias name for a shared library function name that has the same name as a Visual FoxPro function or is not a legal Visual FoxPro name. AliasName should not be a Visual FoxPro reserved word or the name of a shared library function already registered with Visual FoxPro. If you assign alias to the function, use the alias when calling the shared library function. AliasName is not case-sensitive.
cParameterType1[@] ParamName1, cParameterType2[@] ParamName2, ...

Specifies the parameter types passed to the shared library function. cParameterType is required and specifies the data type of any parameters that the shared library function expects to have passed to it. cParameterType may be one of the following:

cParameterType Description

INTEGER

32-bit integer

SINGLE

32-bit floating point

DOUBLE

64-bit floating point

LONG

32-bit long integer

STRING

Character string
Visual FoxPro generates an error if the parameters are not of the type the shared library function expects. Null values can be passed as empty character strings. To pass a parameter by reference when you call the function, you must include the at sign (@) after the parameter cParameterType in this command, and before the corresponding variable in the calling function. If you do not include @ in DECLARE, in the calling function, or in both, the parameter is passed by value. For information about shared library functions that require @ to pass parameters by reference, see the programmer's guide for your operating system or environment (for example, refer to the Microsoft Win32 Programmer's Guide for information on passing parameters to Windows DLLs).
Note:
The parameter names ParamName1, ParamName2, and so on, are optional, and are not used by Visual FoxPro or the shared library function. You can include them as a reminder of the names and types of parameters the function receives.

Remarks

Before you can call a shared library function from within Visual FoxPro, you must issue DECLARE with the name of the function, the name of the shared library containing the function, and the parameter types the function expects to receive.

For backward compatibility, Visual FoxPro allows calls to external API libraries using the SET LIBRARY command. (Using SET LIBRARY, you can access functions in Foxtools.fll.) However, using DECLARE is the preferred method to register shared library functions.

Though Visual FoxPro adds the OBJECT cFunctionType to this command primarily to support some ActiveX Accessibility API routines, you can use it generically with other Windows API routines.

For further information about calling shared library functions, see the programmer's guide for your operating system or environment (for example, refer to the Microsoft Win32 Programmer's Guide for information on calling DLLs).

Issue DISPLAY STATUS or LIST STATUS to display the names of registered functions. Issue CLEAR ALL or CLEAR DLLS to remove registered functions from memory.

Example

This example for Windows returns the window handle for Visual FoxPro or zero if you switch to another Windows application. When the WAIT window is displayed, you have 5 seconds to press ALT+TAB to switch to a different Windows application, or you can leave Visual FoxPro as the active application.
Copy Code
CLEAR
DECLARE INTEGER GetActiveWindow IN win32api
WAIT WINDOW "You can switch to another application now" TIMEOUT 5
? GetActiveWindow( )

See Also

Other Resources

CALL Command
CLEAR Command
DISPLAY DLLS Command
DISPLAY STATUS Command
LIST DLLS Command
LOAD Command
SET LIBRARY Command
Commands
Language Reference


DECLARE Command

Visual FoxPro 9.0 Language Reference
DECLARE Command
See Also

Creates a one- or two-dimensional array.

Note:
DECLARE is identical in operation and similar in syntax to the DIMENSION command. For more information, see DIMENSION Command.

DECLARE ArrayName1 (nRows1 [, nColumns1])
   [, ArrayName2 (nRows2 [, nColumns2])] ...

Remarks

You can use either brackets or parentheses to enclose the expressions in DECLARE. For example, the following two commands create identical arrays:

Copy Code
DIMENSION gaArrayOne(10), gaArrayTwo[2,4], gaArrayThree(3,3)
DIMENSION gaArrayOne[10], gaArrayTwo(2,4), gaArrayThree[3,3]

When the size of an array is increased or decreased when SET COMPATIBLE is set to ON or DB4, the value of each element in the array is reinitialized to .F.

Note:
Visual FoxPro arrays are one-based - the first element, row, or column of an array is specified with the number 1. (Arrays in other programming languages may be zero-based; the first element, row, or column of an array is specified with the number 0.)

See Also

Other Resources

APPEND FROM ARRAY Command
COPY TO ARRAY Command
GATHER Command
PRIVATE Command
PUBLIC Command
SCATTER Command
SET COMPATIBLE Command
STORE Command
Commands
Language Reference


DEFINE BAR Command

Visual FoxPro 9.0 Language Reference
DEFINE BAR Command
See Also Example

Creates a menu item on a menu created with DEFINE POPUP.

DEFINE BAR nMenuItemNumber1 | SystemItemName OF MenuName
   PROMPT cMenuItemText [PICTURE cFileName] [PICTRES cMenubarName]
   [BEFORE nMenuItemNumber2 | AFTER nMenuItemNumber3]
   [FONT cFontName [, nFontSize [, nFontCharSet]]] [STYLE cFontStyle]
   [KEY KeyLabel [, cKeyText]] [MARK cMarkCharacter]
   [MESSAGE cMessageText] [SKIP [FOR lExpression]]
   [COLOR SCHEME nSchemeNumber | COLOR ColorPairList]
   [MRU] [INVERT]

Parameters

nMenuItemNumber1

Specifies the menu item number. The menu item number makes it possible for you to reference the menu item in other commands and functions.
SystemItemName

Specifies a menu item on the Visual FoxPro system menu. For example, to provide access to the Print menu item, issue the following:
Copy Code
DEFINE BAR _MFI_PRINT OF popMyPopup PROMPT "Print..."
Not all Visual FoxPro system menu items are available. Use SYS(2013) to return a list of the Visual FoxPro system menu names that are available.
OF MenuName

Specifies the name of the menu on which the menu items are placed.
PROMPT cMenuItemText

Specifies the caption that appears on the menu item. You can create a separator bar by specifying a backslash and a dash (\-) for cMenuItemText. A separator bar is used to separate item groups on a menu. For example, including the following command in a menu definition creates a separator bar between the third and fifth menu items:
Copy Code
DEFINE BAR 4 OF popMyPopup PROMPT '\-'
You can create multi-column menus by specifying a backslash and a vertical bar (\|) at the beginning of cMenuItemText. The menu item starts a new column, and subsequent menu items are placed in the same column until another menu item beginning with \| is encountered. For example, including the following command in a menu definition creates a new column in the menu:
Copy Code
DEFINE BAR 4 OF popMyPopup PROMPT '\|Start a new column'
You can create an access key for a menu item by placing a backslash and a less-than sign (\<) before the character to be the access key. For example:
Copy Code
DEFINE POPUP popReceive
DEFINE BAR 1 OF popReceive PROMPT '\<Invoices'
DEFINE BAR 2 OF popReceive PROMPT 'In\<quiry'
ACTIVATE POPUP popReceive
The user can press the I key to choose Invoices from the Receive menu and press the Q key to choose Inquiry from the same menu.
PICTURE cPictureName

Enables you to use an existing image with the menu bar. You can specify cPictureName in a relative path.
PICTRES cMenubarName

Specifies a system menu bar name as a resource for a menu. If cPictureName = "", then contents of Resname field of the .mnx table structure is treated as filename for use in DEFINE BAR...PICTURE. This functionality was introduced in Visual FoxPro 7.0.
Note:
You must include a MARGIN clause in the appropriate DEFINE POPUP command in order for the PICTURE or PICTRES clauses to function properly.

BEFORE nMenuItemNumber2

Places a menu item before the menu item specified with nMenuItemNumber2.
AFTER nMenuItemNumber3

Places a menu item after the menu item specified with nMenuItemNumber3.
Note:
In order for BEFORE or AFTER to have an effect, you must include the RELATIVE clause when you create the menu with DEFINE POPUP.

You can also include _MFIRST and _MLAST in the BEFORE and AFTER clauses. If you include_MFIRST in the BEFORE clause, the menu item is the first item on the menu. If you include_MFIRST in the AFTER clause, the menu item is the second item on the menu. If you include_MLAST in the AFTER clause, the menu item is the last item on the menu. If you include_MLAST in the BEFORE clause, the menu item is the next-to-last item on the menu. Menus created with DEFINE POPUP RELATIVE do not reserve space for undefined menu items. For example, if you define items 1, 2, 4, and 5 on a menu, a space for item 3 is not reserved. You can later insert item 3. The menu expands to accommodate it. The following program displays the differences in the order and placement of the items on each type of menu:
Copy Code
   * DEFINE POPUP... relative example
   DEFINE POPUP popRelatYes RELATIVE FROM 1,1
   DEFINE BAR 4  OF popRelatYes PROMPT '4444'
   DEFINE BAR 3  OF popRelatYes PROMPT '3333'
   DEFINE BAR 2  OF popRelatYes PROMPT '2222'
   DEFINE BAR 1  OF popRelatYes PROMPT '1111'
   DEFINE BAR 6  OF popRelatYes PROMPT '6666' BEFORE 4

   * DEFINE POPUP... non-relative example
   DEFINE POPUP popRelatNo FROM 1,10
   DEFINE BAR 4 OF popRelatNo PROMPT '4444'
   DEFINE BAR 3 OF popRelatNo PROMPT '3333'
   DEFINE BAR 2 OF popRelatNo PROMPT '2222'
   DEFINE BAR 1 OF popRelatNo PROMPT '1111'
   DEFINE BAR 6 OF popRelatNo PROMPT '6666'
   ACTIVATE POPUP popRelatYes NOWAIT
             && Display "relative" poup
   ACTIVATE POPUP popRelatNo
             && Display "non-relative" popup
FONT cFontName[, nFontSize [, nFontCharSet]]

Specifies a font for the menu item. cFontName specifies the name of the font, and nFontSize specifies the point size. You can specify a language script with nFontCharSet. See the GETFONT( ) Function for a list of available language script values. For example, the following command creates a menu item in 12-point Courier font:
Copy Code
DEFINE BAR 1 OF popReceive PROMPT '\<Invoices' FONT 'Courier', 12
If the font you specify is not available, a font with similar font characteristics is substituted. If you include the FONT clause but omit the point size nFontSize, a 10-point font is used.
STYLE cFontStyle

Specifies a font style for the menu item. If you omit the STYLE clause, the normal font style is used. If the font style you specify is not available, the normal font style is used. The font styles you can specify with cFontStyle are as follows:

Character Font style

B

Bold

I

Italic

N

Normal

Q

Opaque

–

Strikeout

T

Transparent

U

Underline
You can include more than one character to specify a combination of font styles. For example, the following command specifies Bold Italic:
Copy Code
   DEFINE BAR 1 OF popReceive PROMPT '\<Invoices' STYLE 'BI'
KEY KeyLabel[, cKeyText]

Specifies an access key or key combination for a menu item. The menu does not have to be activated in order for the menu item to be chosen, unlike when you assign an access key using a backslash and a less-than sign (\<). For a list of available keys and key combinations and their key label names, see ON KEY LABEL.
Note:
If a keyboard macro is already defined with the same key label, the keyboard macro takes precedence, and the menu item cannot be chosen with the specified key or key combination.

Include cKeyText to replace the key label with your own text. You can use any character in the cKeyText parameter; for example, you can use the text "^B" to indicate a key label of CTRL+B. For example, including KEY CTRL+B places the text CTRL+B on the menu to the right of the menu item name, but specifying KEY CTRL+B, "^B" places the text ^+B on the menu. You can suppress the display of a key label by specifying an empty string for cKeyText.
MARK cMarkCharacter

Specifies a mark character that appears to the left of the menu item. MARK can be included to change the default mark character to a character specified with cMarkCharacter. If cMarkCharacter includes more than one character, only the first character is used as the mark character. The default mark character is a check. The MARK clause is ignored and the default mark character is used if the menu containing the menu item is integrated into the Visual FoxPro system menu. Also, the MARK clause is ignored if FoxFont is not the font for the main Visual FoxPro window or the user-defined window in which the menu containing the menu item is placed.
Note:
Specifying a mark character does not mark a menu item. Use SET MARK OF to mark a menu item.

Mark characters specified in DEFINE BAR take precedence over mark characters specified with MARK in DEFINE POPUP. SET MARK OF is used to toggle mark characters on or off, and can also be used to specify a mark character for an individual menu item or for all menu items.
MESSAGE cMessageText

Displays a message when the user selects a menu item. The message is placed in the graphical status bar. If the graphical status bar is turned off with SET STATUS BAR OFF, the message is centered on the last line of the main Visual FoxPro window.
SKIP [FOR lExpression]

Specifies a condition whereby if lExpression evaluates to true (.T.), the menu item is disabled, preventing the user from choosing it; if false (.F.), the menu item is enabled. A disabled menu item appears in the disabled colors. You can also disable a menu item by placing a backslash (\) before the text of the prompt. For example:
Copy Code
DEFINE BAR 1 OF popReceive PROMPT '\Invoices'
A menu item disabled with SKIP or \ cannot be selected.
COLOR SCHEME nSchemeNumber

Specifies the colors for an individual menu item, overriding the default colors or the colors specified with DEFINE POPUP.
COLOR ColorPairList

Specifies the colors for an individual menu item, overriding the default colors or the colors specified with DEFINE POPUP. You can specify the colors of all menu items, mark characters, and messages. By default, the colors of menu items are determined by color scheme 2 of the current color set.
MRU

Specifies that the menu displays vertical chevrons indicating a Most Recently Used type menu. You must provide script that dynamically handles the menus and adds any new menu bars. For menus invoked with the MRU keyword, Visual FoxPro imposes a 1-2 second delay before triggering the ON SELECTION BAR command. A user can click on the menu bar to immediately trigger the ON SELECTION BAR command. If you use the MRU keyword, Visual FoxPro ignores PROMPT and other keywords associated with the bar.
Copy Code
DEFINE BAR 4 OF popMyPopup MRU
INVERT

Specifies that the menu displays with a sunken effect.
Copy Code
DEFINE BAR 4 OF popMyPopup PROMPT '\|Start a new column' ;
   PICTRES _med_copy INVERT

Remarks

DEFINE BAR is used with DEFINE POPUP to create menus. A menu is created and assigned a name with DEFINE POPUP. Menu items are placed on the menu with a series of DEFINE BAR commands.

If you use the Menu Designer to create your menu, you may not have to use these commands at all. The Menu Designer automatically creates the commands for your menu. The Menu Designer uses the Visual FoxPro system menu, which you can then modify by adding your own menu items. For more information on creating menus, see Designing Menus and Toolbars.

You can also create a menu that contains records or fields from a table or a list of files available on disk. For more information, see the PROMPT FIELD, PROMPT STRUCTURE and PROMPT FILES clauses in DEFINE POPUP.

Use ON BAR to create a cascading submenu for a menu item.

Example

The following example uses DEFINE BAR to create items on menus. The current system menu bar is first saved to memory with SET SYSMENU SAVE, and then all system menu titles are removed with SET SYSMENU TO.

Two new system menu titles are created with DEFINE PAD, and DEFINE POPUP is used to create a drop-down menu for each menu title. DEFINE BAR is used to create items on each of the menus. When a menu title is chosen, ON PAD uses ACTIVATE POPUP to activate the corresponding menu.

When an item is chosen from a menu, ON SELECTION POPUP uses PROMPT( ) and POPUP( ) to pass the item number and menu name to the CHOICE procedure. CHOICE displays the prompt of the chosen item and the name of the menu containing the item. If Exit is chosen from the Card Info menu, the original Visual FoxPro system menu is restored.
Copy Code
   *** Name this program DEFINBAR.PRG ***
   CLEAR
   SET SYSMENU SAVE
   SET SYSMENU TO
   DEFINE PAD convpad OF _MSYSMENU PROMPT '\<Conversions' COLOR SCHEME 3 ;
      KEY ALT+C, ''
   DEFINE PAD cardpad OF _MSYSMENU PROMPT 'Card \<Info' COLOR SCHEME 3 ;
      KEY ALT+I, ''
   ON PAD convpad OF _MSYSMENU ACTIVATE POPUP conversion
   ON PAD cardpad OF _MSYSMENU ACTIVATE POPUP cardinfo
   DEFINE POPUP conversion MARGIN RELATIVE COLOR SCHEME 4
   DEFINE BAR 1 OF conversion PROMPT 'Ar\<ea' KEY CTRL+E, '^E'
   DEFINE BAR 2 OF conversion PROMPT '\<Length' ;
      KEY CTRL+L, '^L'
   DEFINE BAR 3 OF conversion PROMPT 'Ma\<ss' ;
      KEY CTRL+S, '^S'
   DEFINE BAR 4 OF conversion PROMPT 'Spee\<d' ;
      KEY CTRL+D, '^D'
   DEFINE BAR 5 OF conversion PROMPT '\<Temperature' ;
      KEY CTRL+T, '^T'
   DEFINE BAR 6 OF conversion PROMPT 'T\<ime' ;
      KEY CTRL+I, '^I'
   DEFINE BAR 7 OF conversion PROMPT 'Volu\<me' ;
      KEY CTRL+M, '^M'
   ON SELECTION POPUP conversion;
      DO choice IN definbar WITH PROMPT( ), POPUP( )
   DEFINE POPUP cardinfo MARGIN RELATIVE COLOR SCHEME 4
   DEFINE BAR 1 OF cardinfo PROMPT '\<View Charges' ;
      KEY ALT+V, ''
   DEFINE BAR 2 OF cardinfo PROMPT 'View \<Payments' ;
      KEY ALT+P, ''
   DEFINE BAR 3 OF cardinfo PROMPT 'Vie\<w Users' KEY ALT+W, ''
   DEFINE BAR 4 OF cardinfo PROMPT '\-'
   DEFINE BAR 5 OF cardinfo PROMPT '\<Charges '
   DEFINE BAR 6 OF cardinfo PROMPT '\-'
   DEFINE BAR 7 OF cardinfo PROMPT 'E\<xit '
   ON SELECTION POPUP cardinfo;
      DO choice IN definbar WITH PROMPT( ), POPUP( )
   PROCEDURE choice
   PARAMETERS mprompt, mpopup
   WAIT WINDOW 'You chose ' + mprompt + ;
      ' from popup ' + mpopup NOWAIT
   IF mprompt = 'Exit'
      SET SYSMENU TO DEFAULT
   ENDIF

See Also

Other Resources

ACTIVATE POPUP Command
DEACTIVATE POPUP Command
DEFINE POPUP Command
HIDE POPUP Command
RELEASE BAR Command
SET MESSAGE Command
SHOW POPUP Command
Commands
Language Reference


DEFINE CLASS Command

Visual FoxPro 9.0 Language Reference
DEFINE CLASS Command
See Also

Creates a user-defined class or subclass and specifies the properties, events, and methods for the class or subclass.

Caution:
Modifying read-only properties from base classes generates an error message.

The full syntax for the DEFINE CLASS main clauses appears as follows:

DEFINE CLASS ClassName1 AS ParentClass [OF ClassLibrary] [OLEPUBLIC]
   [[PROTECTED | HIDDEN] PropertyName1, PropertyName2 ...]
   [[.]Object.]PropertyName = eExpression ...]
   [PEMName_COMATTRIB = nFlags | DIMENSION PEMName_COMATTRIB[numElements]
      [PEMName_COMATTRIB[1] = nFlags
              PEMName_COMATTRIB[2] = cHelpString
              PEMName_COMATTRIB[3] = cPropertyCapitalization
              PEMName_COMATTRIB[4] = cPropertyType
              PEMName_COMATTRIB[5] = nOptionalParams]]
   [ADD OBJECT [PROTECTED] ObjectName AS ClassName2 [NOINIT] [WITH cPropertylist]]
   [IMPLEMENTS cInterfaceName [EXCLUDE] IN TypeLib | TypeLibGUID | ProgID ]
   [[PROTECTED | HIDDEN] FUNCTION | PROCEDURE Name[_ACCESS |_ASSIGN]
      ([cParamName | cArrayName[] [AS Type][@]]) [AS Type]
      [HELPSTRING cHelpString] | THIS_ACCESS(cMemberName) [NODEFAULT]
            cStatements
   [ENDFUNC | ENDPROC]
ENDDEFINE

Remarks

The following code shows a summary of the main clauses:

Copy Code
DEFINE CLASS Clause
   [Property_Definition_Clause]
   [PEMName_COMATTRIB Clause]
   [ADD OBJECT Clause]
   [IMPLEMENTS Clause]
   [Function_Procedure_Definition_Clause]
ENDDEFINE

The following sections describe detailed syntax and parameters for each clause of the DEFINE CLASS command:

  • DEFINE CLASS Clause

  • Property Definition Clause

  • PEMName_COMATTRIB Clause

  • ADD OBJECT Clause

  • IMPLEMENTS Clause

  • Function or Procedure Definition Clause

Code for user-defined classes is stored in a program (.prg) file, similar to procedures.

Note:
You cannot follow procedures in a .prg file with normal executable program code. Only class definitions, other procedures, and user-defined functions can follow the first DEFINE CLASS, PROCEDURE or FUNCTION statement in the file. For more information, see User-Defined Procedures and Functions.

You cannot place class definitions created with DEFINE CLASS within structured programming commands, for example, IF ... ENDIF or DO CASE ... ENDCASE, or in loops, such as DO WHILE ... ENDDO or FOR ... ENDFOR.

To instantiate, or create instances of, the class you defined, use the CREATEOBJECT( ) function. You can access public properties and call method and event functions and procedures outside the class definition as shown in the following example:

Copy Code
myObject = CREATEOBJECT('MyClass')
myObject.myPropertyName =
myObject.myMethodName( argument1, argument2, ... )
myObject.myEventName

Protected or hidden properties, methods, and events have restricted access as defined by the PROTECTED and HIDDEN keywords. For more information, see DEFINE CLASS Command - Property Definition Clause and DEFINE CLASS Command - Function or Procedure Definition Clause.

Visual FoxPro converts AS Type clause values automatically when other COM servers use them. When you type the AS clause in code, IntelliSense functionality in Visual FoxPro displays the type information for COM servers.

The following table shows the data type information that is displayed.

VFP defined type | COM Typelib conversion | IntelliSense displays
Array | SAFEARRAY(type) | Array
BinaryMemo | VARIANT | —
Boolean | VARIANT_BOOL | Logical
Byte | unsigned char | Number
Character * | BSTR | String
Currency * | CURRENCY | Currency
Date | DATE | Date
DateTime | DATE | Date
Decimal * | wchar_t | Number
Double | double | Number
Float | VARIANT | —
Integer | long | Number
Logical | VARIANT_BOOL | Logical
Long | long | Number
Memo | VARIANT | —
Number | double | Number
Object | IDispatch* | Object
Short | long | Number
Single * | single | Number
String | BSTR | String
Variant | VARIANT | —
Void | void | VOID

You can view code for Access and Assign methods in the Trace window of the Debugger window. However, you cannot execute Access and Assign methods from the Watch and Local windows of the Debugger window. For more information, see Access and Assign methods, Trace Window, and Debugger Window.

A safe array is a one- or multi-dimensional array of a single data type, which can be of type VARIANT, allowing you to create arrays of mixed types. The safe array stores its lower bound, which does not have to be zero, and its size. Safe arrays allow locking and unlocking so you can be sure that the pointer you receive to the data is valid.

Examples

Example 1

The following example creates a class named MyForm from the Form base class and creates a protected property named Version. The class also contains another property called Caption, which is not protected. The class definition initializes the default values of Version and Caption to the strings "1.0" and "My Form", respectively.

Copy Code
DEFINE CLASS MyForm AS Form
   PROTECTED Version
   Version = "1.0"
   Caption = "My Form"
ENDDEFINE

Example 2

The following example creates the form frmOLETest from a Form base class and uses the AddObject method to add an object named OCXTest based on the BlueOLEControl class created by DEFINE CLASS and specifies the OLE class for the Listview ActiveX control. The .Object keyword is used to specify a value for the BackColor property of the control before it is created.

Copy Code
PUBLIC frmOLETest
frmOLETest = CREATEOBJECT('Form')
frmOLETest.Visible = .T.

frmOLETest.AddObject('OCXTest', 'BlueOLEControl', 'MSComctlLib.ListViewCtrl')
frmOLETest.OCXTest.View = 2
frmOLETest.OCXTest.ListItems.Add(1,'one','Item One')
frmOLETest.OCXTest.ListItems.Add(2,'two','Item Two')

DEFINE CLASS BlueOLEControl AS OLEControl
   * Set property for Outline ActiveX control.
   .Object.Backcolor = 16776960

   * Set properties for the OLE Container control.
   Visible = .T.
   Height = 100
   Width = 200
ENDDEFINE

For more information, see AddObject Method.

Example 3

The following example demonstrates how to define an array of type library attributes using the DIMENSION PEMName_COMATTRIB clause:

Copy Code
#INCLUDE foxpro.h
DEFINE CLASS myOLEClass AS Custom OLEPUBLIC
   MyProperty = 5.2
   * Set COM attributes for MyProperty.
   DIMENSION MyProperty_COMATTRIB[4]
   myProperty_COMATTRIB[1] = COMATTRIB_READONLY
   myProperty_COMATTRIB[2] = "Help text displayed in object browser"
   myProperty_COMATTRIB[3] = "MyProperty"  && Proper capitalization.
   myProperty_COMATTRIB[4] = "Float"        && Data type
ENDDEFINE

However, if you want to set only the nFlags element, you do not need to create an array:

Copy Code
#INCLUDE foxpro.h
DEFINE CLASS myOLEClass AS Custom OLEPUBLIC
   MyProperty = "Test"
   * Set the only the nFlags attribute for MyProperty.
   myProperty_COMATTRIB = COMATTRIB_READONLY
ENDDEFINE

Example 4

The following example creates a class named MyForm from the Form base class and adds a command button from the CommandButton base class and a check box from the CheckBox base class:

Copy Code
DEFINE CLASS MyForm AS Form
   ADD OBJECT cmdButton1 AS CommandButton
   ADD OBJECT chkBox1 AS CheckBox
ENDDEFINE

As another example, the following code creates a class called MyForm, adds a command button and check box to the class, and specifies values for the Caption properties of the command button and check box.

Copy Code
DEFINE CLASS MyForm AS Form
   ADD OBJECT cmdButton1 AS CommandButton WITH Caption = "Yes"
   ADD OBJECT chkBox1 AS CheckBox WITH Caption = "Click Me"
ENDDEFINE

Example 5

The following example creates a class named MyPublisherClass as a Custom class, uses the OLEPUBLIC keyword to specify that Automation clients can access the class when included in an Automation server, uses the IMPLEMENTS clause to inherit the class definition inherit from the Publisher class definition in the type library, MyBookStore.dll, and includes the method ShowPrice from the Publisher interface.

Copy Code
DEFINE CLASS MyPublisherClass AS Custom OLEPUBLIC
   IMPLEMENTS Publisher IN "MyBookStore.dll"
   PROCEDURE Publisher_ShowPrice(cGetID AS Long) AS Short
   ENDPROC
ENDDEFINE

Example 6

The following example creates a class named MyForm from the Form base class and contains a procedure for a Click event definition. The form created from the class contains a Click method that displays a dialog box when you click the form.

Copy Code
DEFINE CLASS MyForm AS Form
   PROCEDURE Click
      = MESSAGEBOX('MyForm has been clicked!')
   ENDPROC
ENDDEFINE

As another example, the following code contains a procedure for one of the objects added to the class. This event procedure overrides the default Click event for the command button:

Copy Code
DEFINE CLASS MyForm AS Form
   ADD OBJECT MyButton AS CommandButton
   ADD OBJECT chkBox1 AS CheckBox
   PROCEDURE MyButton.Click
      = MESSAGEBOX('This is my click event procedure')
   ENDPROC
ENDDEFINE

Example 7

The following example shows how you can specify strong typing using PROCEDURE cArrayName[] [AS Type][@][AS Type] clause so that arrays can be correctly written as safe arrays to a type library:

Copy Code
DEFINE CLASS mySession AS Session OLEPUBLIC
    PROCEDURE GetWidgets1(aWidgets[])
    ENDPROC
    PROCEDURE GetWidgets2(aWidgets[] AS Integer)
    ENDPROC
    PROCEDURE GetWidgets3(aWidgets[] AS Integer @)
    ENDPROC
    PROCEDURE GetRS(oRS[] AS ADODB.Recordset @)
    ENDPROC
ENDDEFINE

As another example, the following code demonstrates how you can specify strong complex typing by defining a type based on a COM class:

Copy Code
DEFINE CLASS mySession AS Session OLEPUBLIC
   PROCEDURE GetRS() AS ADODB.Recordset
      x=CREATEOBJECT("ADODB.Recordset")
      RETURN X
   ENDPROC
   PROCEDURE SetRS(oRS AS ADODB.Recordset @)
      oRS=CREATEOBJECT("ADODB.Recordset")
   ENDPROC
ENDDEFINE

See Also

Other Resources

:: Scope Resolution Operator
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
DODEFAULT( ) Function
EVENTHANDLER( ) Function
GETOBJECT( ) Function
MODIFY CLASS Command
RELEASE CLASSLIB Command
Commands


DEFINE CLASS Command - DEFINE CLASS Clause

Visual FoxPro 9.0 Language Reference
DEFINE CLASS Command - DEFINE CLASS Clause
See Also Example

Specifies the name of the class to create and the parent class used to create the new class. You can also make it possible for Automation clients to access the class when included in an Automation server.

DEFINE CLASS ClassName1 AS ParentClass [OF ClassLibrary] [OLEPUBLIC]
[Other DEFINE CLASS clauses]

Parameters

DEFINE CLASS ClassName1 AS ParentClass

Specifies the name of the class to create and the parent class to use as the base class. The parent class can be a Visual FoxPro base class, such as the Form class, or another user-defined class or subclass. You can also create subclasses from the Exception and Session classes in addition to the Visual FoxPro base classes.
Note:
If you specify Custom as ParentClass, Visual FoxPro creates a non-visual user-defined class. If you specify Session as ParentClass, Visual FoxPro creates a non-visual user defined class that maintains its own private data session. The ADD OBJECT clause is not available when you specify Session as ParentClass because a Session object is not a container. For more information, see Session Object.

For more information about Visual FoxPro base classes, see Base Classes in Visual FoxPro. You can also use the AS clause to implement strong typing. IntelliSense functionality is available for object and variable references only when they are strongly typed. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.
[OF ClassLibrary]

Makes it possible for you to specify a class library for AS ParentClass without needing to explicitly specify the path to the class library containing it as when using the SET CLASSLIB or SET PROCEDURE commands. ClassLibrary can be a class library (.vcx), program (.prg), or compiled program (.fxp) file. The specified ClassLibrary can contain a relative path as long as Visual FoxPro can locate the library along its usual class library searching paths. If Visual FoxPro cannot find the specified ClassLibrary when you attempt to instantiate an instance of the class, Visual FoxPro generates an error. Visual FoxPro adds ClassLibrary to the project during the build process automatically if the program containing the class is included in the project. When using the OF ClassLibrary clause, be sure that the current program does not have same class name as that specified in the OF ClassLibrary clause.
Note:
If an OF <ProgramFile> reference is used in a program that is bound inside of an executable application, the <ProgramFile> name should have an .fxp file name extension and not a .prg extension.

[OLEPUBLIC]

Specifies that Automation clients can access the class when included in an Automation server.
Note:
If you include the OLEPUBLIC keyword for a class whose base class is Session, the type library generated for an executable (.exe) or dynamic-link library (.dll) contains only your custom properties and methods. All intrinsic properties, methods, and events of the Session base class are excluded from the type library. This behavior is supported in Visual FoxPro 7.0 and later.

If you add a program with a class definition created as OLEPUBLIC to a project, you can create an .exe or a .dll file containing the class interactively using the Project Manager, the BUILD EXE, BUILD DLL, or BUILD MTDLL commands. The .exe or .dll registers with the operating system automatically and becomes available to any Automation client. For more information, see How to: Create Automation Servers, How to: Build Applications, BUILD EXE Command, BUILD DLL Command, or BUILD MTDLL Command.
ENDDEFINE

Indicates the end of the class definition.

Remarks

The following code shows a summary of the main clauses of the DEFINE CLASS command:

Copy Code
DEFINE CLASS Clause
   [Property_Definition_Clause]
   [PEMName_COMATTRIB Clause]
   [ADD OBJECT Clause]
   [IMPLEMENTS Clause]
   [Function_Procedure_Definition_Clause]
ENDDEFINE

For more information and full syntax, see DEFINE CLASS Command. For more information about a particular clause of the DEFINE CLASS command, see the following topics:

  • Property Definition Clause

  • PEMName_COMATTRIB Clause

  • ADD OBJECT Clause

  • IMPLEMENTS Clause

  • Function or Procedure Definition Clause

Example

The following example creates a class named MyForm from the Form base class and creates a protected property named Version. The class also contains another property called Caption, which is not protected. The class definition initializes the default values of Version and Caption to the strings "1.0" and "My Form", respectively.
Copy Code
DEFINE CLASS MyForm AS Form
   PROTECTED Version
   Version = "1.0"
   Caption = "My Form"
ENDDEFINE

See Also

Other Resources

:: Scope Resolution Operator
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
DODEFAULT( ) Function
EVENTHANDLER( ) Function
GETOBJECT( ) Function
MODIFY CLASS Command
RELEASE CLASSLIB Command
Commands


DEFINE CLASS Command - Property Definition Clause

Visual FoxPro 9.0 Language Reference
DEFINE CLASS Command - Property Definition Clause
See Also Example

Defines properties and their values for the class definition.

[[PROTECTED | HIDDEN] PropertyName1, PropertyName2 ...]
[[.]Object.]PropertyName = eExpression ...]

Parameters

[PROTECTED | HIDDEN] PropertyName1, PropertyName2 ...]

Specifies one or more class properties to create. Properties are named attributes of the class and define characteristics and behaviors for the class. Use commas to separate each property or declare each property on a separate line.
Note:
All property definitions must appear before function or procedure definitions.

The PROTECTED keyword prevents access and changes to the specified properties from outside of the class definition. Methods and events in the class or subclass definition can access protected properties. The HIDDEN keyword prevents access and changes to the specified properties from outside of the class definition. However, only methods and events in the class definition, not subclasses, can access hidden properties.
Tip:
You can create subclasses with Access and Assign methods if you do not include the HIDDEN keyword.

[[.]Object.] PropertyName= eExpression ...]

Assigns default values to class properties. Using .Object. indicates that Visual FoxPro should apply the value to an ActiveX control property when creating it. For more information, see the Examples section.

Remarks

The following code shows a summary of the main clauses of the DEFINE CLASS command:

Copy Code
DEFINE CLASS Clause
   [Property_Definition_Clause]
   [PEMName_COMATTRIB Clause]
   [ADD OBJECT Clause]
   [IMPLEMENTS Clause]
   [Function_Procedure_Definition_Clause]
ENDDEFINE

For more information and full syntax, see DEFINE CLASS Command. For more information about a particular clause of the DEFINE CLASS command, see the following topics:

  • DEFINE CLASS Clause

  • PEMName_COMATTRIB Clause

  • ADD OBJECT Clause

  • IMPLEMENTS Clause

  • Function or Procedure Definition Clause

Example

The following example creates the form frmOLETest from a Form base class and uses the AddObject method to add an object named OCXTest based on the BlueOLEControl class created by DEFINE CLASS and specifies the OLE class for the Listview ActiveX control. The .Object keyword is used to specify a value for the BackColor property of the control before it is created.
Copy Code
PUBLIC frmOLETest
frmOLETest = CREATEOBJECT('Form')
frmOLETest.Visible = .T.

frmOLETest.AddObject('OCXTest', 'BlueOLEControl', 'MSComctlLib.ListViewCtrl')
frmOLETest.OCXTest.View = 2
frmOLETest.OCXTest.ListItems.Add(1,'one','Item One')
frmOLETest.OCXTest.ListItems.Add(2,'two','Item Two')

DEFINE CLASS BlueOLEControl AS OLEControl
   * Set property for Outline ActiveX control.
   .Object.Backcolor = 16776960

   * Set properties for the OLE Container control.
   Visible = .T.
   Height = 100
   Width = 200
ENDDEFINE

For more information, see AddObject Method.

See Also

Other Resources

:: Scope Resolution Operator
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
DODEFAULT( ) Function
EVENTHANDLER( ) Function
GETOBJECT( ) Function
MODIFY CLASS Command
RELEASE CLASSLIB Command
Commands


DEFINE CLASS Command - PEMName_COMATTRIB Clause

Visual FoxPro 9.0 Language Reference
DEFINE CLASS Command - PEMName_COMATTRIB Clause
See Also Example

Specifies type library attributes and values for PEMName_COMATTRIB properties or methods. The features described in this section applies only to OLEPUBLIC classes and is used to specify additional information, such as a description or read-only attribute, about the property or method that you want written to the COM type library.

Note:
Unlike Access and Assign methods, PEMName_COMATTRIB properties are marked as hidden automatically and are not accessible in Visual FoxPro. They are strictly for use by Visual FoxPro during the build process when writing to a COM type library.

[PEMName_COMATTRIB = nFlags | DIMENSION PEMName_COMATTRIB[numElements]
   [PEMName_COMATTRIB[1] = nFlags
        PEMName_COMATTRIB[2] = cHelpString
        PEMName_COMATTRIB[3] = cPropertyCapitalization
        PEMName_COMATTRIB[4] = cPropertyType
        PEMName_COMATTRIB[5] = nOptionalParams]]

Parameters

[ PEMName_COMATTRIB = nFlags| DIMENSION PEMName_COMATTRIB[numElements]

Specifies an nFlags value for a PEMName property or method or uses the DIMENSION command to create a property array that contains type library attributes for the PEMName property. When creating an array, numElements specifies the number of elements in the array up to 5. The following table describes the elements in the array.

COMATTRIB element Description Type

1

Attribute flags.

Number

2

Help string.

String

3

Capitalization.

String

4

Property type.

String

5

Number of parameters.

Note:
If you specify fewer than the actual number of parameters, the number greater than those declared are optional.

Number
Note:
For invalid values or types in the PEMName_COMATTRIB array, Visual FoxPro generates an error. Empty elements use default values.

nFlags

Specifies attribute flags for the PEMName property or method as it appears in the type library. The following table describes the valid flags.

nFlags value #DEFINE Description

0x1 (1)

COMATTRIB_RESTRICTED

The property or method should not be accessible from macro languages. This flag is intended for system-level functions or functions that type browsers should not display.

COMATTRIB_RESTRICTED means that macro-oriented programmers should not be allowed to access this member. These members are usually treated as _HIDDEN by tools such as Visual Basic, with the main difference being that code cannot bind to those members.

0x40 (64)

COMATTRIB_HIDDEN

The property or method should not be displayed to the user, although it exists and is bindable.

COMATTRIB_HIDDEN means that the property should never be shown in object browsers, property browsers, and so on. This function is useful for removing items from an object model. Code can bind to the member, but the user will never know that the member exists.

0x400 (1024)

COMATTRIB_NONBROWSABLE

The property or method appears in an object browser but not in a properties browser.

COMATTRIB _NONBROWSABLE means that the property should not be displayed in a properties browser. It is used in circumstances in which an error would occur if the property were shown in a properties browser. Early and late binding impose differing access restrictions. Early-binding clients will not be able to write to a read-only property, nor read from a write-only property because there will not be an entry in the vtable. Late-binding clients can still access a propertyget on a write-only or a propertyput on a read-only PEMName.

0x100000

COMATTRIB_READONLY

The property is read-only. Applies only to Properties. Equivalent to a PropertyGet.

Note:
Using both COMATTRIB_READONLY and COMATTRIB_WRITEONLY is equivalent to using neither.

0x200000

COMATTRIB_WRITEONLY

The property is write-only. Applies only to Properties. Equivalent to a PropertyLet.

Note:
Using both COMATTRIB_READONLY and COMATTRIB_WRITEONLY is equivalent to using neither.
PEMName_COMATTRIB[2] = cHelpString

Specifies a string value to store in the type library for the PEMName property. For methods, use the HELPSTRING cHelpString clause.
PEMName_COMATTRIB[3] = cPropertyCapitalization

Specifies the property name as a string value as it should appear in the type library. All capitalization is preserved. If this setting is omitted, Visual FoxPro writes the property to the type library in all uppercase.
PEMName_COMATTRIB[4] = cPropertyType

Specifies the property data type as a string value as it appears in the type library and functions the same as the AS Type clause. Applies to Properties only.
PEMName_COMATTRIB[5] = nOptionalParms]]

Specifies the number of optional parameters in a method. For example, if this value is 2 for a method with 5 parameters, then the last 3 are optional. Applies to Methods only. For late-binding clients, default values for optional parameters will still be False (.F.), and the PCOUNT( ) function accurately reflects the true number of passed parameters. For early-bound clients, default values for optional parameters will always be set to an empty string (""), and PCOUNT( ) will always return the total number of parameters for the method, not the number passed in.

Remarks

The following code shows a summary of the main clauses of the DEFINE CLASS command:

Copy Code
DEFINE CLASS Clause
   [Property_Definition_Clause]
   [PEMName_COMATTRIB Clause]
   [ADD OBJECT Clause]
   [IMPLEMENTS Clause]
   [Function_Procedure_Definition_Clause]
ENDDEFINE

For more information and full syntax, see DEFINE CLASS Command. For more information about a particular clause of the DEFINE CLASS command, see the following topics:

  • DEFINE CLASS Clause

  • Property Definition Clause

  • ADD OBJECT Clause

  • IMPLEMENTS Clause

  • Function or Procedure Definition Clause

Example

The following example demonstrates how to define an array of type library attributes using the DIMENSION PEMName_COMATTRIB clause:

Copy Code
#INCLUDE foxpro.h
DEFINE CLASS myOLEClass AS Custom OLEPUBLIC
   MyProperty = 5.2
   * Set COM attributes for MyProperty.
   DIMENSION MyProperty_COMATTRIB[4]
   myProperty_COMATTRIB[1] = COMATTRIB_READONLY
   myProperty_COMATTRIB[2] = "Help text displayed in object browser"
   myProperty_COMATTRIB[3] = "MyProperty"  && Proper capitalization.
   myProperty_COMATTRIB[4] = "Float"        && Data type
ENDDEFINE

However, if you want to set only the nFlags element, you do not need to create an array:

Copy Code
#INCLUDE foxpro.h
DEFINE CLASS myOLEClass AS Custom OLEPUBLIC
   MyProperty = "Test"
   * Set the only the nFlags attribute for MyProperty.
   myProperty_COMATTRIB = COMATTRIB_READONLY
ENDDEFINE

See Also

Other Resources

:: Scope Resolution Operator
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
DODEFAULT( ) Function
EVENTHANDLER( ) Function
GETOBJECT( ) Function
MODIFY CLASS Command
RELEASE CLASSLIB Command
Commands


DEFINE CLASS Command - ADD OBJECT Clause

Visual FoxPro 9.0 Language Reference
DEFINE CLASS Command - ADD OBJECT Clause
See Also Example

Adds objects from other classes to the class definition.

[ADD OBJECT [PROTECTED] ObjectName AS ClassName2 [NOINIT] [WITH cPropertylist]]

Parameters

[ADD OBJECT [PROTECTED] ObjectName AS ClassName2

Specifies to add an object from a Visual FoxPro base class, user-defined class or subclass, or an ActiveX custom control to the class definition. The PROTECTED keyword prevents access and changes to the object's properties from outside the class or subclass definition.
[NOINIT]

Specifies to not execute the Init method of the object when adding it.
[WITH cPropertyList]]

Specifies a list of properties and their values for the object that you add to the class definition. For more information, see the Examples section.

Remarks

The following code shows a summary of the main clauses of the DEFINE CLASS command:

Copy Code
DEFINE CLASS Clause
   [Property_Definition_Clause]
   [PEMName_COMATTRIB Clause]
   [ADD OBJECT Clause]
   [IMPLEMENTS Clause]
   [Function_Procedure_Definition_Clause]
ENDDEFINE

For more information and full syntax, see DEFINE CLASS Command. For more information about a particular clause of the DEFINE CLASS command, see:

  • DEFINE CLASS Clause

  • Property Definition Clause

  • PEMName_COMATTRIB Clause

  • IMPLEMENTS Clause

  • Function or Procedure Definition Clause

Example

The following example creates a class named MyForm from the Form base class and adds a command button from the CommandButton base class and a check box from the CheckBox base class:

Copy Code
DEFINE CLASS MyForm AS Form
   ADD OBJECT cmdButton1 AS CommandButton
   ADD OBJECT chkBox1 AS CheckBox
ENDDEFINE

As another example, the following code creates a class called MyForm, adds a command button and check box to the class, and specifies values for the Caption properties of the command button and check box.

Copy Code
DEFINE CLASS MyForm AS Form
   ADD OBJECT cmdButton1 AS CommandButton WITH Caption = "Yes"
   ADD OBJECT chkBox1 AS CheckBox WITH Caption = "Click Me"
ENDDEFINE

See Also

Other Resources

:: Scope Resolution Operator
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
DODEFAULT( ) Function
EVENTHANDLER( ) Function
GETOBJECT( ) Function
MODIFY CLASS Command
RELEASE CLASSLIB Command
Commands


DEFINE CLASS Command - IMPLEMENTS Clause

Visual FoxPro 9.0 Language Reference
DEFINE CLASS Command - IMPLEMENTS Clause
See Also Example

Specifies to inherit the interface from another COM component.

[IMPLEMENTS cInterfaceName [EXCLUDE] IN TypeLib | TypeLibGUID | ProgID ]

Parameters

[IMPLEMENTS cInterfaceName [EXCLUDE] IN TypeLib | TypeLibGUID | ProgID]

Specifies that the class definition inherit the interface or class definition of another COM component. You can include multiple IMPLEMENTS statements.
Note:
Certain technologies, such as Microsoft COM+ Events, require the COM component to implement the interface of the event class being bound to.

The EXCLUDE keyword excludes the implemented interface from type library. The IN clause specifies the location of the interface for the COM component. You can specify the type library of the COM object using TypeLib, the GUID of the type library using TypeLibGUID, or the ProgID of the program that initializes the COM object. When you use TypeLibGUID, include the major and minor version designation as shown in the following example:
Copy Code
IMPLEMENTS IDict1 IN {04BCEF93-7A77-11D0-9AED-CE3E5F000000}#1.0
Tip:
The TypeLib parameter is the least recommended way to specify the type library because this requires a file name whose path might differ from computer to computer. If you are distributing your .dll, consider using TypeLibGUID or ProgID instead.

Note:
When you use the IMPLEMENTS clause, you must include all methods of that interface in the class definition. You must use the interface name exactly as it appears in the type library. However, for interface names preceded by an underscore (_), such as in the ADODB RecordSet class, the underscore is optional. Preface the method name with the interface name, for example, Publisher_ShowPrice. This convention helps avoid conflict between two interfaces that contain methods that have the same name when you include multiple IMPLEMENTS statements in a class definition. As properties are essentially stored as two methods inside a type library, for example, Put and Get, the class definition must include both methods.

Tip:
To save time, you can use the Visual FoxPro Object Browser to drag and drop interface definitions to your code. Along with the IMPLEMENTS statement, all the implemented methods with their proper parameter signatures are written automatically for you. For more information, see Object Browser.

Remarks

The following code shows a summary of the main clauses of the DEFINE CLASS command:

Copy Code
DEFINE CLASS Clause
   [Property_Definition_Clause]
   [PEMName_COMATTRIB Clause]
   [ADD OBJECT Clause]
   [IMPLEMENTS Clause]
   [Function_Procedure_Definition_Clause]
ENDDEFINE

For more information and full syntax, see DEFINE CLASS Command. For more information about a particular clause of the DEFINE CLASS command, see the following topics:

  • DEFINE CLASS Clause

  • Property Definition Clause

  • PEMName_COMATTRIB Clause

  • ADD OBJECT Clause

  • Function or Procedure Definition Clause

Example

The following example creates a class named MyPublisherClass as a Custom class, uses the OLEPUBLIC keyword to specify that Automation clients can access the class when included in an Automation server, uses the IMPLEMENTS clause to inherit the class definition inherit from the Publisher class definition in the type library, MyBookStore.dll, and includes the method ShowPrice from the Publisher interface.
Copy Code
DEFINE CLASS MyPublisherClass AS Custom OLEPUBLIC
   IMPLEMENTS Publisher IN "MyBookStore.dll"
   PROCEDURE Publisher_ShowPrice(cGetID AS Long) AS Short
   ENDPROC
ENDDEFINE

See Also

Other Resources

:: Scope Resolution Operator
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
DODEFAULT( ) Function
EVENTHANDLER( ) Function
GETOBJECT( ) Function
MODIFY CLASS Command
RELEASE CLASSLIB Command
Commands


DEFINE CLASS Command - Function or Procedure Definition Clause

Visual FoxPro 9.0 Language Reference
DEFINE CLASS Command - Function or Procedure Definition Clause
See Also

Defines method and event functions and procedures for the class definition.

[[PROTECTED | HIDDEN] FUNCTION | PROCEDURE Name[_ACCESS |_ASSIGN]
   ([cParamName | cArrayName[] [AS Type][@]]) [AS Type]
   [HELPSTRING cHelpString] | THIS_ACCESS(cMemberName) [NODEFAULT]
      cStatements
[ENDFUNC | ENDPROC]]

Parameters

[[PROTECTED | HIDDEN] FUNCTION | PROCEDURE Name[_ACCESS | _ASSIGN]

Specifies events and methods to create for the class definition. Events and methods are created as functions or procedures. You can create an event function or procedure to respond to an event. For more information, see User-Defined Procedures and Functions, FUNCTION Command, and PROCEDURE Command.
Note:
Calling event functions and procedures execute the code defined for those functions and procedures and does not call the event itself.

For more information about events in Visual FoxPro, see Understanding the Event Model. You can create a method function or procedure, which acts on the object created with the class definition.
Note:
You must declare each protected method on a separate line.

The _ACCESS or _ASSIGN suffixes specify to create an Access or Assign method for a property with the same name. By default, Access and Assign methods are protected, so you cannot access or make changes to an Access or Assign method from outside of the class. For more information, see Access and Assign Methods and How to: Create Access and Assign Methods.
Note:
Arrays are passed to Access and Assign methods in the same manner as standard Visual FoxPro procedures. For more information, see Passing Data to Parameters.

([ cParamName| cArrayName[] [AS Type][@]]) [AS Type]

Specifies one or more parameters to use for passing arguments to the class method or event or specifies the name of an array used to create a type library.
Note:
When specifying an array, you must use brackets ([]) notation. DEFINE CLASS does not recognize parentheses (()) notation.

For parameters, the first AS Type clause specifies the data type of the parameter. For arrays, the first AS Type clause specifies a type that must be a valid COM data type. For more information, see the table in the Remarks section. The type can also be a reference to a COM CoClass ProgID such as ADODB.RecordSet. You can specify ProgIDs with or without quotation marks (""). If you use a valid COM CoClass ProgID for an AS Type clause, Visual FoxPro includes it in the type library. For example, the following method defintion:
Copy Code
PROCEDURE Test(oRS AS ADODB.Recordset @) AS ADODB.Recordset
Creates an entry in the type library:
Copy Code
Recordset Test([in, out] Recordset** oRS);
Note:
For arrays, you cannot specify a reference to a ProgID that is generated from the type library. For example, you cannot reference a class that is contained in the same COM server.

If you specify an array with a type for the first AS Type clause, Visual FoxPro creates a SAFEARRAY with the specified type. If you specify an array without a type for the first AS Type clause, Visual FoxPro creates a SAFEARRAY of Variant data types. If you specify an invalid type, Visual FoxPro defaults to using Variant type. For more information about safe arrays, see the Remarks section. The at sign (@) specifies that arguments or arrays are passed to the function or procedure by reference.
Note:
By default, data pass to parameters in user-defined procedures by reference and to user-defined functions by value. To pass an entire array, you must pass it by reference. For more information, see Passing Data to Parameters.

Note:
You can use the first AS clause to implement strong typing, make IntelliSense functionality available, and for class definition information stored in a type library (OLEPUBLIC). However, Visual FoxPro does not enforce type checking during compilation or code execution so you must make sure to use valid data types. For arrays, strong typing is used primarily for type library creation and is not enforced at run time. By using the cArrayName[] [AS Type][@] clause, you can specify strong typing for arrays so they can be correctly written as safe arrays to a type library. Strict typing is also recommended for use with the interface methods specified by the IMPLEMENTS clause. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.

The second AS Type clause indicates the type of the function's return value.
Note:
You cannot specify arrays as return types. For example, while the following code is valid, it writes out the return type of the type library as VARIANT and not a SAFEARRAY:

Copy Code
PROCEDURE GetWidgets() AS aWidgets[]
ENDPROC
Tip:
If the method does not return a value, use AS VOID as the return value. This is required for certain technologies such as Microsoft COM+ Services Queued Components.

If you want parameters and their types to appear in the type library, you must use inline parameter syntax instead of the LPARAMETERS command to declare the parameters, for example:
Copy Code
FUNCTION myMeth(parm1 AS Integer @, parm2 AS String) AS Integer
ENDFUNC
[HELPSTRING cHelpString]

Specifies a string to add to the type library as a description of the method's functionality to display in an object browser or IntelliSense.
THIS_ACCESS( cMemberName)

Specifies to create a THIS_ACCESS procedure or function to execute when the value of an object member changes or is queried. For more information, see Access and Assign Methods and How to: Create Access and Assign Methods.
[NODEFAULT]

Prevents Visual FoxPro from performing default event or method processing for Visual FoxPro events and methods. For more information, see NODEFAULT Command.
cStatements

Specifies the code to execute when calling the function or procedure for the class event or method.
Tip:
You can specify that event and method functions and procedures can accept values by including a PARAMETERS or LPARAMETERS statement as the first executable line of the function or procedure. For more information, see PARAMETERS Command and LPARAMETERS Command.

[ENDFUNC | ENDPROC]]

Indicates the end of the function or procedure. Unlike most Visual FoxPro keywords, you cannot abbreviate ENDFUNC and ENDPROC because they can conflict with the with the ENDFOR and ENDPRINTJOB keywords.

Remarks

The following code shows a summary of the main clauses of the DEFINE CLASS command:

Copy Code
DEFINE CLASS Clause
   [Property_Definition_Clause]
   [PEMName_COMATTRIB Clause]
   [ADD OBJECT Clause]
   [IMPLEMENTS Clause]
   [Function_Procedure_Definition_Clause]
ENDDEFINE

For more information and full syntax, see DEFINE CLASS Command. For more information about a particular clause of the DEFINE CLASS command, see the following topics:

  • DEFINE CLASS Clause

  • Property Definition Clause

  • PEMName_COMATTRIB Clause

  • ADD OBJECT Clause

  • IMPLEMENTS Clause

Examples

Example 1

The following example creates a class named MyForm from the Form base class and contains a procedure for a Click event definition. The form created from the class contains a Click method that displays a dialog box when you click the form.

Copy Code
DEFINE CLASS MyForm AS Form
   PROCEDURE Click
      = MESSAGEBOX('MyForm has been clicked!')
   ENDPROC
ENDDEFINE

Example 2

The following example shows how you can specify strong typing using PROCEDURE cArrayName[] [AS Type ][@][AS Type] clause so that arrays can be correctly written as safe arrays to a type library:

Copy Code
DEFINE CLASS mySession AS Session OLEPUBLIC
    PROCEDURE GetWidgets1(aWidgets[])
    ENDPROC
    PROCEDURE GetWidgets2(aWidgets[] AS Integer)
    ENDPROC
    PROCEDURE GetWidgets3(aWidgets[] AS Integer @)
    ENDPROC
    PROCEDURE GetRS(oRS[] AS ADODB.Recordset @)
    ENDPROC
ENDDEFINE

As another example, the following code demonstrates how you can specify strong complex typing by defining a type based on a COM class:

Copy Code
DEFINE CLASS mySession AS Session OLEPUBLIC
   REFERENCE "ADODB.Recordset"
   PROCEDURE GetRS() AS ADODB.Recordset
      x=CREATEOBJECT("ADODB.Recordset")
      RETURN X
   ENDPROC
   PROCEDURE SetRS(oRS AS ADODB.Recordset @)
      oRS=CREATEOBJECT("ADODB.Recordset")
   ENDPROC
ENDDEFINE

See Also

Other Resources

:: Scope Resolution Operator
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
DODEFAULT( ) Function
EVENTHANDLER( ) Function
GETOBJECT( ) Function
MODIFY CLASS Command
RELEASE CLASSLIB Command
Commands


DEFINE MENU Command

Visual FoxPro 9.0 Language Reference
DEFINE MENU Command
See Also Example

Creates a menu bar.

DEFINE MENU MenuBarName [BAR [AT LINE nRow]]
   [IN [WINDOW] WindowName | IN SCREEN]
      [FONT cFontName [, nFontSize [, nFontCharSet]]]
   [STYLE cFontStyle] [KEY KeyLabel] [MARK cMarkCharacter]
   [MESSAGE cMessageText] [NOMARGIN]
   [COLOR SCHEME nSchemeNumber | COLOR ColorPairList]

Parameters

MenuBarName

Specifies the name of the menu bar to create. The menu bar name allows you to reference the menu bar in other commands and functions.
BAR [AT LINE nRow]

Creates a menu bar that behaves like the Visual FoxPro system menu bar. The menu bar has these characteristics:
  • A horizontal menu bar one line high is drawn across the width of the main Visual FoxPro window or the user-defined window it is placed in.

  • The placement of the menu titles on the menu bar is handled automatically.

  • If the size or number of menu titles you define exceeds the size of the screen or a window in which the menu bar is placed, the menu bar scrolls.

The row number is specified with nRow.
IN [WINDOW] WindowName

Places a menu bar in a user-defined window. Specify the name of the window in which you want to place the menu bar with WindowName. If you omit IN WINDOW, the menu bar is placed in the main Visual FoxPro window by default unless there is an active user-defined window. If there is an active user-defined window, the menu bar is placed in the active window. This clause is supported only in top-level forms which can be set with ShowWindow=2 or Desktop=.T.
IN SCREEN

Explicitly places the menu bar in the main Visual FoxPro window.
FONT cFontName[, nFontSize [, nFontCharSet]]

Specifies a default font for all menu titles in the menu bar. You can override the default font for an individual menu title by including the FONT clause in DEFINE PAD. cFontName specifies the name of the font, and nFontSize specifies the point size. You can specify a language script with nFontCharSet. See the GETFONT( ) Function for a list of available language script values. For example, the following command creates a menu bar with menu titles in 12-point Courier font:
Copy Code
DEFINE MENU mnuExample FONT 'Courier', 12
If the font you specify is not available, a font with similar font characteristics is substituted. If you include the FONT clause but omit the point size nFontSize, a 10-point font is used. The FONT clause is ignored for menu titles added to the Visual FoxPro system menu _MSYSMENU. Note that the Menu Designer uses the Visual FoxPro system menu.
STYLE cFontStyle

Specifies a default font style for all the menu titles in the menu bar. You can override the default style for individual menu titles by including the STYLE clause in DEFINE PAD. If you omit the STYLE clause, or if the font style you specify is not available, the Normal font style is used. The font styles you can specify with cFontStyle are as follows:

Character Font style

B

Bold

I

Italic

N

Normal

Q

Opaque

-

Strikeout

T

Transparent

U

Underline
You can include more than one character to specify a combination of font styles. For example, the following command specifies Bold Italic:
Copy Code
DEFINE MENU mnuExample STYLE 'BI'
The STYLE clause is ignored for menu titles added to the Visual FoxPro system menu _MSYSMENU. The Menu Designer uses the Visual FoxPro system menu.
KEY KeyLabel

Specifies the key or key combination used to activate the menu bar. For a list of available keys and key combinations and their key label names, see ON KEY LABEL. Including the KEY clause is equivalent to issuing the following command:
Copy Code
ON KEY LABEL KeyLabel ACTIVATE MENU MenuName
Note:
If a keyboard macro is already defined with the same key label, the keyboard macro takes precedence, and the menu bar cannot be activated with the specified key or key combination.

MARK cMarkCharacter

Specifies a mark character that appears to the left of the menu titles on the menu bar. MARK can be included to change the default mark character to a character specified with cMarkCharacter. If cMarkCharacter includes more than one character, only the first character is used as the mark character. The default mark character is a check. The MARK clause is ignored and the default mark character is used if the menu bar is the Visual FoxPro system menu. Also, the MARK clause is ignored if FoxFont isn't the font for the main Visual FoxPro window or the user-defined window in which the menu bar is placed.
Note:
Specifying a mark character doesn't mark the menu names on a menu bar. Use SET MARK OF to mark the menu titles on a menu bar with the character you specify.

Mark characters specified with DEFINE PAD take precedence over mark characters specified with the MARK clause in DEFINE MENU. SET MARK OF is used to toggle mark characters on or off, and can also be used to specify a mark character for an individual menu item or for all menu items.
MESSAGE cMessageText

Displays a message when the user selects a menu title. The message is placed in the graphical status bar. If the graphical status bar is turned off with SET STATUS BAR OFF, the message is centered on the last line of the main Visual FoxPro window.
NOMARGIN

Removes the spaces that are placed to the left and right of each menu name by default.
COLOR SCHEME nSchemeNumber

Specifies the colors for an individual menu bar.
COLOR ColorPairList

Specifies the colors for an individual menu bar. By default, the colors of menu items are determined by color scheme 2 of the current color set.

Remarks

Use DEFINE MENU to create the menu bar for your application's menu system. Use DEFINE PAD to create each of the menu titles (pads) on the menu bar. Use ON PAD ... ACTIVATE to specify which menu is displayed under each menu title. Use DEFINE POPUP to create the menus under each menu title. Use ACTIVATE MENU to activate the entire menu system.

If you use the Menu Designer to create your menu, you may not have to use these commands at all. The Menu Designer automatically creates the commands for your menu. The Menu Designer uses the Visual FoxPro system menu, which you can then modify by adding your own menu items.

For more information on creating menus, see Menu System Creation.

Example

The following example uses DEFINE MENU to create a user-defined menu system. The current system menu bar is first saved to memory with SET SYSMENU SAVE, and then the system menu titles are cleared with SET SYSMENU TO.

DEFINE MENU creates the menu bar, and two menu titles are created with DEFINE PAD. DEFINE POPUP creates a menu for each menu title. DEFINE BAR creates items on each of the menus. When a menu title is chosen, ON PAD uses ACTIVATE POPUP to activate the corresponding menu. ACTIVATE MENU displays and activates the menu bar.

When an item is chosen from a menu, the CHOICE procedure is executed. CHOICE displays the name of the chosen item and the name of the menu containing the item.
Copy Code
*** Name this program DEFIMENU.PRG ***
CLEAR
SET SYSMENU SAVE
SET SYSMENU TO
ON KEY LABEL ESC KEYBOARD CHR(13)
DEFINE MENU example BAR AT LINE 1
DEFINE PAD convpad OF example PROMPT '\<Conversions' COLOR SCHEME 3 ;
   KEY ALT+C, ''
DEFINE PAD cardpad OF example PROMPT 'Card \<Info' COLOR SCHEME 3 ;
   KEY ALT+I, ''
ON PAD convpad OF example ACTIVATE POPUP conversion
ON PAD cardpad OF example ACTIVATE POPUP cardinfo
DEFINE POPUP conversion MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF conversion PROMPT 'Ar\<ea' ;
   KEY CTRL+E, '^E'
DEFINE BAR 2 OF conversion PROMPT '\<Length' ;
   KEY CTRL+L, '^L'
DEFINE BAR 3 OF conversion PROMPT 'Ma\<ss' ;
   KEY CTRL+S, '^S'
DEFINE BAR 4 OF conversion PROMPT 'Spee\<d' ;
   KEY CTRL+D, '^D'
DEFINE BAR 5 OF conversion PROMPT '\<Temperature' ;
   KEY CTRL+T, '^T'
DEFINE BAR 6 OF conversion PROMPT 'T\<ime' ;
   KEY CTRL+I, '^I'
DEFINE BAR 7 OF conversion PROMPT 'Volu\<me' ;
   KEY CTRL+M, '^M'
ON SELECTION POPUP conversion DO choice IN defimenu WITH PROMPT( ), POPUP( )
DEFINE POPUP cardinfo MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF cardinfo PROMPT '\<View Charges' ;
   KEY ALT+V, ''
DEFINE BAR 2 OF cardinfo PROMPT 'View \<Payments' ;
   KEY ALT+P, ''
DEFINE BAR 3 OF cardinfo PROMPT 'Vie\<w Users' ;
   KEY ALT+W, ''
DEFINE BAR 4 OF cardinfo PROMPT '\-'
DEFINE BAR 5 OF cardinfo PROMPT '\<Charges '
ON SELECTION POPUP cardinfo;
   DO choice IN defimenu WITH PROMPT( ), POPUP( )

ACTIVATE MENU example
DEACTIVATE MENU example
RELEASE MENU example EXTENDED
SET SYSMENU TO DEFAULT
ON KEY LABEL ESC
PROCEDURE choice
PARAMETERS mprompt, mpopup
WAIT WINDOW 'You chose ' + mprompt + ;
    ' from popup ' + mpopup NOWAIT

See Also

Other Resources

ACTIVATE MENU Command
CNTPAD( ) Function
CREATE MENU Command
DEACTIVATE MENU Command
DEFINE PAD Command
GETPAD( ) Function
HIDE MENU Command
MRKPAD( ) Function
ON PAD Command
ON SELECTION PAD Command
PRMPAD( ) Function
RELEASE MENUS Command
RELEASE PAD Command
SET MARK OF Command
SET SYSMENU Command
SHOW MENU Command
Commands
Language Reference


DEFINE PAD Command

Visual FoxPro 9.0 Language Reference
DEFINE PAD Command
See Also Example

Creates a menu title (pad) on a user-defined menu bar or the Visual FoxPro system menu bar.

DEFINE PAD MenuTitle1 OF MenuBarName PROMPT cMenuTitleText
   [AT nRow, nColumn] [BEFORE MenuName2 | AFTER MenuName3]
   [NEGOTIATE cContainerPosition [, cObjectPosition]]
   [FONT cFontName [, nFontSize [, nFontCharSet]]] [STYLE cFontStyle]
   [KEY KeyLabel [, cKeyText]] [MARK cMarkCharacter]
   [SKIP [FOR lExpression]] [MESSAGE cMessageText]
   [COLOR SCHEME nSchemeNumber | COLOR ColorPairList]

Parameters

MenuTitle1

Specifies the menu title to create. The menu title allows you to reference the menu title in other commands and functions.
OF MenuBarName

Specifies the name of the menu bar in which the menu title is placed.
PROMPT cMenuTitleText

Specifies the text that appears in the menu title. You can create an access key for a menu title by placing a backslash and a less-than sign (\<) before the character you would like to be the access key. In the following example, the user can press the I key to choose Invoices from the Receive menu and press the Q key to choose Inquiry from the same menu:
Copy Code
DEFINE MENU mnuReceive
DEFINE PAD padInvoice OF mnureceive PROMPT "\<Invoices"
DEFINE PAD padInquire OF mnureceive PROMPT "In\<quiry"
ACTIVATE MENU mnuReceive
AT nRow, nColumn

Specifies where the menu title appears on the menu bar. nRow, nColumn are the coordinates of the left side of the menu title in the main Visual FoxPro window or in a user-defined window. If you omit the AT clause, the left side of the first menu title is placed in row 0 of the main Visual FoxPro window or user-defined window. The next menu title is placed to the right of the first name on row 0, and so on.
Note:
You cannot include AT to specify a location for menu titles in menu bars created with the BAR clause in DEFINE MENU.

BEFORE MenuName2

Places the menu title on the menu bar to the left of the menu title specified with MenuName2. The order the menu titles are accessed from the keyboard corresponds to the location of the menu titles in the menu bar.
AFTER MenuName3

Places the menu title on the menu bar to the right of the menu title specified with MenuName3. The order the menu titles are accessed from the keyboard corresponds to the location of the menu titles in the menu bar. You must first create the menu title you specify in a BEFORE or AFTER clause. If you don't create the menu title first, the placement of the menu title on the menu bar is determined by the order in which it is created or by a location specified with the AT clause. For menu bars created without BAR, BEFORE or AFTER determines the order the menu titles are accessed from the keyboard. The location of a menu title is determined by the location specified with the AT clause. Run the following two examples and note the differences in menu title placement and access order when menu titles are defined with and without the AT clause:
Copy Code
*** Program Example 1 without ATs ***
DEFINE MENU mnuBefAft
DEFINE PAD padOne OF mnuBefAft PROMPT '1111'
DEFINE PAD padTwo OF mnuBefAft PROMPT '2222'
DEFINE PAD padThree OF mnuBefAft PROMPT '3333'
DEFINE PAD padFour  OF mnuBefAft PROMPT '4444' BEFORE padTwo
ACTIVATE MENU mnuBefAft

*** Program Example 2 with ATs ***
DEFINE MENU mnuBefAft
DEFINE PAD padOne OF mnuBefAft PROMPT '1111' AT 1,5
DEFINE PAD padTwo OF mnuBefAft PROMPT '2222' AT 1,15
DEFINE PAD padThree OF mnuBefAft PROMPT '3333' AT 1,25
DEFINE PAD padFour  OF mnuBefAft PROMPT '4444' BEFORE padTwo AT 1,35
WAIT WINDOW 'Press ESC to erase menu' NOWAIT
ACTIVATE MENU mnuBefAft
NEGOTIATE cContainerPosition[, cObjectPosition]

cContainerPosition specifies the location of the menu title in the Visual FoxPro menu bar when OLE visual editing occurs for an ActiveX control contained in a Visual FoxPro form. 'The settings for cContainerPosition are:

Setting Description

NONE

The menu title is not displayed.

LEFT

The menu title is placed to the left of the File Group.

MIDDLE

The menu title is placed to the left of the Container Group, after the Edit menu.

RIGHT

The menu title is placed to the left of the Window Group.
The settings for cObjectPosition are:

Setting Description

NONE

The menu title is not displayed.

LEFT

The menu title is placed to the right of the File Group.

MIDDLE

The menu title is placed to the right of the Container Group, after the Edit menu.

RIGHT

The menu title is placed on the Help menu.
If you omit the NEGOTIATE clause, the menu title is removed from the menu bar when OLE visual editing occurs; NONE is the default for both cContainerPosition and cObjectPosition.
FONT cFontName[, nFontSize [, nFontCharSet]]

Specifies a font for the menu title. cFontName specifies the name of the font, and nFontSize specifies the point size. You can specify a language script with nFontCharSet. See the GETFONT( ) Function for a list of available language script values. For example, the following command creates a menu title in 12-point Courier font:
Copy Code
DEFINE PAD padPageAccts OF mnuReceive FONT 'Courier', 12
If the font you specify is not available, a font with similar font characteristics is substituted. If you include the FONT clause but omit the point size nFontSize, a 10-point font is used. The FONT clause is ignored for menu titles added to the Visual FoxPro system menu _MSYSMENU. Note that the Menu Designer uses the Visual FoxPro system menu.
STYLE cFontStyle

Specifies a font style for the menu title. If you omit the STYLE clause, or if the font style you specify is not available, the Normal font style is used. The font styles you can specify with cFontStyle are as follows:

Character Font style

B

Bold

I

Italic

N

Normal

Q

Opaque

-

Strikeout

T

Transparent

U

Underline
You can include more than one character to specify a combination of font styles. For example, the following command specifies Bold Italic:
Copy Code
DEFINE PAD padPageAccts OF mnuReceive STYLE 'BI'
The STYLE clause is ignored for menu titles added to the Visual FoxPro system menu _MSYSMENU. Note that the Menu Designer uses the Visual FoxPro system menu.
KEY KeyLabel[, cKeyText]

Specifies an access key or key combination for a menu title. For a list of available keys and key combinations and their key label names, see ON KEY LABEL.
Note:
If a keyboard macro is already defined with the same key label, the keyboard macro takes precedence, and the menu title cannot be chosen with the specified key or key combination.

The key label is placed to the right of menu titles in menu bars created without the BAR clause. The key label isn't displayed in menu bars created with the BAR clause or for menu titles in the Visual FoxPro system menu bar. Include cKeyText to replace the key label with your own text. You can use any character in the cKeyText parameter; for example, you can use the text "^B" to indicate a key label of CTRL+B. For example, including KEY CTRL+B places the text CTRL+B on the menu to the right of the menu item name, but specifying KEY CTRL+B, "^B" places the text ^+B on the menu. You can suppress the display of a key label by specifying an empty string for cKeyText.
MARK cMarkCharacter

Specifies a mark character that appears to the left of the menu title. MARK can be included to change the default mark character to a character specified with cMarkCharacter. If cMarkCharacter includes more than one character, only the first character is used as the mark character. The default mark character is a check. The MARK clause is ignored and the default mark character is used if the menu bar containing the menu title is the Visual FoxPro system menu. Also, the MARK clause is ignored if FoxFont isn't the font for the main Visual FoxPro window or the user-defined window in which the menu bar containing the menu title is placed. Mark characters specified with DEFINE PAD take precedence over mark characters specified with the MARK clause in DEFINE MENU. SET MARK OF is used to toggle marks on or off and can also be used to specify a mark character for an individual menu title or for all menu titles.
Note:
Specifying a mark character doesn't mark the menu title. Use SET MARK OF to mark a menu title with the character you specify.

SKIP [FOR lExpression]

Specifies a condition whereby if lExpression evaluates to true (.T.), the menu title is disabled, preventing the user form choosing it. If lExpression evaluates to false (.F.), the menu title is enabled. You can also disable a menu item by placing a backslash (\) before the text of the menu title text. For example:
Copy Code
DEFINE PAD padPageAccts OF mnuReceive PROMPT '\Age Accounts'
The menu title padPageAccts is displayed dimmed, indicating that it cannot be chosen. A disabled menu title can be displayed but can't be selected. However, a message specified with the MESSAGE clause is displayed.
MESSAGE cMessageText

Displays a message when the user selects a menu title. The message is placed in the graphical status bar. If the graphical status bar is turned off with SET STATUS BAR OFF, the message is centered on the last line of the main Visual FoxPro window.
COLOR SCHEME nSchemeNumber

Specifies the colors for an individual menu title, overriding the default colors or the colors specified with DEFINE MENU.
COLOR ColorPairList

Specifies the colors for an individual menu title, overriding the default colors or the colors specified with DEFINE MENU. By default, the colors of menu titles in menu bars are determined by color scheme 2 of the current color set.

Remarks

You must create each menu title placed on the menu bar with its own DEFINE PAD command. A menu bar must be defined with DEFINE MENU before you can place menu titles on it, and you must include the menu bar name in DEFINE PAD.

If you use the Menu Designer to create your menu, you may not have to use these commands at all. The Menu Designer automatically creates the commands for your menu. The Menu Designer uses the Visual FoxPro system menu, which you can then modify by adding your own menu items. For more information on creating menus, see Menu System Creation.

Example

The following example uses DEFINE PAD to place menu titles in the Visual FoxPro system menu bar. The current system menu bar is first saved to memory with SET SYSMENU SAVE, and then all system menu titles are removed with SET SYSMENU TO.

Several system menu titles are created with DEFINE PAD. When a menu title is chosen, the CHOICE procedure is executed. CHOICE displays the name of the chosen menu title and the name of the menu bar, and toggles the menu titles' mark character on and off. If the Exit menu title is chosen, the original Visual FoxPro system menu is restored.
Copy Code
*** Name this program DEFINPAD.PRG ***
CLEAR
SET TALK OFF
SET SYSMENU SAVE
SET SYSMENU TO
PUBLIC markpad
markpad = .T.
DEFINE PAD syspad  OF _MSYSMENU PROMPT '\<System'  COLOR SCHEME 3 ;
   KEY ALT+S, ''
DEFINE PAD editpad OF _MSYSMENU PROMPT '\<Edit'  COLOR SCHEME 3 ;
   KEY ALT+E, ''
DEFINE PAD recordpad OF _MSYSMENU PROMPT '\<Record'  COLOR SCHEME 3 KEY ALT+R, ''
DEFINE PAD windowpad OF _MSYSMENU PROMPT '\<Window'  COLOR SCHEME 3 ;
   KEY ALT+W, ''
DEFINE PAD reportpad OF _MSYSMENU PROMPT 'Re\<ports' COLOR SCHEME 3 ;
   KEY ALT+P, ''
DEFINE PAD exitpad OF _MSYSMENU PROMPT 'E\<xit'  COLOR SCHEME 3 ;
   KEY ALT+X, ''
ON SELECTION MENU _MSYSMENU ;
   DO choice IN definpad WITH PAD( ), MENU( )
PROCEDURE choice
PARAMETER mpad, mmenu
WAIT WINDOW 'You chose ' + mpad + ;
   ' from menu ' + mmenu NOWAIT
SET MARK OF PAD (mpad) OF _MSYSMENU TO ;
   ! MRKPAD('_MSYSMENU', mpad)
markpad = ! markpad
IF mpad = 'EXITPAD'
   SET SYSMENU TO DEFAULT
ENDIF

See Also

Other Resources

ACTIVATE MENU Command
CREATE MENU Command
DEACTIVATE MENU Command
DEFINE MENU Command
GETPAD( ) Function
HIDE MENU Command
MRKPAD( ) Function
ON PAD Command
ON SELECTION PAD Command
PRMPAD( ) Function
RELEASE PAD Command
SET MARK OF Command
SET MESSAGE Command
SET SYSMENU Command
SHOW MENU Command
Commands
Language Reference


DEFINE POPUP Command

Visual FoxPro 9.0 Language Reference
DEFINE POPUP Command
See Also Example

Creates a menu.

DEFINE POPUP MenuName [FROM nRow1, nColumn1] [TO nRow2, nColumn2]
   [IN [WINDOW] WindowName | IN SCREEN]
      [FONT cFontName [, nFontSize] [, nFontCharSet]] [STYLE cFontStyle]
     [FOOTER cFooterText] [KEY KeyLabel] [MARGIN]
   [MARK cMarkCharacter] [MESSAGE cMessageText] [MOVER] [MULTISELECT]
   [PROMPT FIELD FieldName | PROMPT FILES [LIKE FileSkeleton]
      | PROMPT STRUCTURE] [RELATIVE] [SCROLL] [SHORTCUT]
   [TITLE cMenuTitleText] [RTLJUSTIFY]
   [COLOR SCHEME nSchemeNumber | COLOR ColorPairList]

Parameters

MenuName

Specifies the name of the menu to create.
FROM nRow1, nColumn1 TO nRow2, nColumn2

Specifies where the menu is placed. nRow1, nColumn1 specifies coordinates for the upper-left corner of the menu. If you omit the FROM clause, Visual FoxPro places the upper-left corner of the menu in the first row and first column of the main Visual FoxPro window or a user-defined window. To create a menu with a specific size, you can also include TO nRow2, nColumn2 to specify the location of the lower-right corner of the menu. If you include FROM nRow1, nColumn1 and omit TO nRow2, nColumn2, Visual FoxPro automatically sizes the menu. The menu is as wide as the longest menu item in it (if the items are created with DEFINE BAR) and as long as needed to display all of the menu items. The menu length is limited by the size of the main Visual FoxPro window or user-defined window in which the menu is placed. If a menu isn't large enough to contain all of the menu items, a scroll bar appears so that you can scroll through the menu items.
IN [WINDOW] WindowName

Places a menu in a user-defined window you specify with WindowName. If you omit this clause, the menu is placed on the main Visual FoxPro window by default unless there is an active user-defined window. If there is an active user-defined window, the menu is placed in the active window.
IN SCREEN

Explicitly places a menu in the main Visual FoxPro window.
FONT cFontName[, nFontSize [, nFontCharSet]]

Specifies a default font for the menu. You can override the default font for an individual menu item by including the FONT clause in DEFINE BAR. cFontName specifies the name of the font, and nFontSize specifies the point size. You can specify a language script with nFontCharSet. See the GETFONT( ) Function for a list of available language script values. For example, the following command creates a menu in 12-point Courier font:
Copy Code
DEFINE POPUP popMyPopup FONT 'Courier', 12
If the font you specify is not available, a font with similar font characteristics is substituted. If you include the FONT clause but omit the point size nFontSize, a 10-point font is used.
STYLE cFontStyle

Specifies a default font style for the menu. You can override the default style for an individual menu item by including the FONT clause in DEFINE BAR. If you omit the STYLE clause, or if the font style you specify is not available, the Normal font style is used. The font styles you can specify with cFontStyle are listed in the following table:

Character Font style

B

Bold

I

Italic

N

Normal

Q

Opaque

-

Strikeout

T

Transparent

U

Underline
You can include more than one character to specify a combination of font styles. For example, the following command specifies Bold Italic:
Copy Code
DEFINE MENU popMyPopup STYLE 'BI'
FOOTER cFooterText

Creates a footer with the text specified with cFooterText centered in the bottom border of the menu.
KEY KeyLabel

Specifies an access key or key combination for a menu. For a list of available keys and key combinations and their key label names, see ON KEY LABEL. Including KEY is equivalent to issuing the following command:
Copy Code
ON KEY LABEL KeyLabel ACTIVATE POPUP MenuName
Note:
If a keyboard macro is already defined with the same key label, the keyboard macro takes precedence, and the menu cannot be activated with the specified key or key combination.

MARGIN

Places an extra space to the left and right of each menu item. Mark characters are displayed in the space to the left of an item, and arrows indicating additional cascading submenus are available and are displayed to the right of menu items. If you omit MARGIN, the mark characters overwrite the first character of the menu item names; hierarchical arrows overwrite the last character of the menu items.
Note:
You must include this clause if you want to use the DEFINE BAR ... PICTURE or PICTRES clauses.

MARK cMarkCharacter

Specifies a character that appears to the left of an item on the menu. The default mark character is a check mark. The MARK clause is ignored and the default mark character is used if the menu is integrated into the Visual FoxPro system menu. Also, the MARK clause is ignored if FoxFont isn't the font for the main FoxPro window or the user-defined window in which the menu is placed. MARK can be included to change the default mark character to a character specified with cMarkCharacter. If cMarkCharacter includes more than one character, only the first character is used as the mark character.
Note:
Specifying a mark character doesn't mark a menu item. Use SET MARK OF to mark a menu item.

The MARK clause sets the mark character for all items on the menu. Mark characters specified with DEFINE BAR commands take precedence over mark characters specified with the MARK clause in DEFINE POPUP. SET MARK OF is used to toggle mark characters on or off and can also be used to specify a mark character for an individual menu item or for all menu items.
MESSAGE cMessageText

Displays a message when you select a menu item. The message is placed in the graphical status bar. If the character-based status bar is turned on with SET STATUS ON, the message is centered on the last line of the main Visual FoxPro window.
MOVER

Places a double-headed arrow
in the Mover box to the left of the selected item in the menu. You can drag the double-headed arrow to move an item to another position on the menu. GETBAR( ) can be used to determine where each item is positioned on the menu. You cannot rearrange items in a menu created with a PROMPT clause.
MULTISELECT

Allows the user to select multiple items from a menu at the same time. When the user chooses an item from a menu, the mark character is placed to the left of the item. You cannot make multiple selections from a menu created with a PROMPT clause. MRKBAR( ) can be used to determine which items are chosen from the menu. If you include MULTISELECT in DEFINE POPUP, you can include MARGIN to reserve space in each item for the mark character. In the following example, a menu named popFruits is created. MULTISELECT is included to create a menu that allows multiple items to be chosen. Each of the four items has a different mark character. When a user chooses items from the menu, the items are marked and a routine named yourchoice displays the chosen items.
Copy Code
CLEAR
ACTIVATE SCREEN
DEFINE POPUP popFruits FROM 5,5 ;
   MULTISELECT MARGIN            && Create multi-choice menu
DEFINE BAR 1 OF popFruits ;
   PROMPT '\<Apples'  MARK CHR(3)    && First item
DEFINE BAR 2 OF popFruits ;
   PROMPT '\<Bananas' MARK CHR(4)    && Second item
DEFINE BAR 3 OF popFruits ;
   PROMPT '\<Grapes'  MARK CHR(5) && Third item
DEFINE BAR 4 OF popFruits ;
   PROMPT '\<Lemons'  MARK CHR(6)    && Fourth item
@ 12,5 SAY 'Your choices:'
ON SELECTION POPUP popFruits DO yourchoice    && Choice routine
ACTIVATE POPUP popFruits
PROCEDURE yourchoice            && Executed when choice is made
@ 13,5 CLEAR
FOR gnCount = 1 TO CNTBAR('popFruits')      && Loop for # of items
   IF MRKBAR('popFruits', gnCount) = .T.      && Option is marked,
      ? PRMBAR('popFruits', gnCount) AT 5      && display caption
   ENDIF
NEXT
PROMPT FIELD FieldName

Specifies the field name from an open table whose records become the items on the menu. The menu contains an item for each record in the table. When the menu is activated, the tables' work area is selected.
Tip:
You can take advantage of Rushmore Query Optimization if you set a filter on the field specified with PROMPT FIELD used in the menu. For more information on Rushmore Query Optimization, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access in Optimizing Applications.

FieldName can also contain multiple field names and expressions concatenated with the addition operator (+). FieldName can also be the name of the field in a table open in another work area or a user-defined function. There is no limit to the number of entries that can appear in a menu created with PROMPT FIELD.
PROMPT FILES [LIKE FileSkeleton]

Creates a menu that displays the names of files available in the current directory. LIKE FileSkeleton allows you to specify the files that are displayed in the menu using wildcards. For example, to create a menu that displays the names of tables in the default drive and directory, include the following command:
Copy Code
PROMPT FILES LIKE *.DBF
You can create a menu that displays the names of files on other drives and in other directories or folders by including a drive or volume specification, a directory specification, or both. For example, to create a menu that displays the names of program files in a directory called PROGRAMS on drive C, include the following command:
Copy Code
PROMPT FILES LIKE C:\PROGRAMS\*.PRG
PROMPT STRUCTURE

Displays the names of the fields in the current table on the menu according to the table's field structure. When the menu is activated, the table's work area is selected.
RELATIVE

Specifies the order in which items are placed on a menu. If you create a menu without the RELATIVE clause, an item is positioned on a menu in an order dictated by the item's bar number. Space on the menu is reserved for undefined items. For example, if the first and third items are defined and the menu is activated, a blank line reserved for the second item is placed on the menu. If you create a menu with RELATIVE, the items appear on the menu in the order in which they are defined. Space in the menu isn't reserved for undefined items. Defining a menu with RELATIVE also lets you make use of BEFORE and AFTER clauses in DEFINE BAR to position items on a menu relative to other items. If a menu is created without RELATIVE, including BEFORE or AFTER in DEFINE BAR generates an error. Run the following two program examples and compare the placement of the items on each menu.
Copy Code
*** RELATIVE Example  ***
DEFINE POPUP popRelatYes RELATIVE FROM 1,1
DEFINE BAR 4  OF popRelatYes PROMPT '4444'
DEFINE BAR 3  OF popRelatYes PROMPT '3333'
DEFINE BAR 2  OF popRelatYes PROMPT '2222'
DEFINE BAR 1  OF popRelatYes PROMPT '1111'
DEFINE BAR 6  OF popRelatYes PROMPT '6666' BEFORE 4
ACTIVATE POPUP popRelatYes
*** NON-RELATIVE Example ***
DEFINE POPUP popRelatNo FROM 1,1
DEFINE BAR 4  OF popRelatNo PROMPT '4444'
DEFINE BAR 3  OF popRelatNo PROMPT '3333'
DEFINE BAR 2  OF popRelatNo PROMPT '2222'
DEFINE BAR 1  OF popRelatNo PROMPT '1111'
DEFINE BAR 6  OF popRelatNo PROMPT '6666'
ACTIVATE POPUP popRelatNo
SCROLL

Places a scroll bar to the right of the menu you create. The scroll bar is displayed only when there are more items than can fit on the menu, or if the menu is too long to fit in the main Visual FoxPro window or the user-defined window in which it is placed.
SHORTCUT

Creates a shortcut menu. A shortcut menu typically appears when a selection, toolbar, or taskbar button is clicked with the right mouse button. The shortcut menu lists commands that pertain to the screen region on which the mouse was right-clicked. You can include MROW( ) and MCOL( ) in the FROM clause to activate the popup at the location where the mouse is clicked.
TITLE cMenuTitleText

Displays a title in the center of the top border of the menu. cTitleText specifies the menu title.
RTLJUSTIFY

Specifies that the text in the popup is justified in a right to left direction. The RTLJUSTIFY clause is intended for use with fonts that support bi-directional alignments. Issue SET SYSMENU TO LTRJUSTIFY to return the menu system to default left to right justification. This option is only available when Windows is configured to a Middle-Eastern locale.
COLOR SCHEME nSchemeNumber

Specifies the colors for all elements of a menu. By default, the colors of menus created with DEFINE POPUP are controlled by color scheme 2.
COLOR ColorPairList

Specifies the colors for all elements of a menu.

Remarks

To place a set of menu items that you define on a menu, use a series of DEFINE BAR commands. To place records, files, or fields in a menu, use the PROMPT FIELD, PROMPT FILES, or PROMPT STRUCTURE options of DEFINE POPUP.

When the menu is displayed and activated with ACTIVATE POPUP, you can choose one of the items on the menu. Depending on the item chosen, a routine can be executed or another menu can be displayed and activated. A menu that displays another menu when an item is chosen is called a cascading submenu. For more information on creating submenus, see ON BAR.

If you use the Menu Designer to create your menu, you may not have to use these commands at all. The Menu Designer automatically creates the commands for your menu. The Menu Designer uses the Visual FoxPro system menu, which you can then modify by adding your own menu items.

For more information on creating menus, see Menu System Creation.

Example

The following example uses DEFINE POPUP to create menus that are activated when a menu title in the menu bar is chosen. The current system menu bar is first saved to memory with SET SYSMENU SAVE, and then all system menu titles are removed with SET SYSMENU TO.

Two new system menu titles are created with DEFINE PAD, and DEFINE POPUP creates a drop-down menu for each menu title. DEFINE BAR creates items on each of the menus. When a menu title is chosen, ON PAD uses ACTIVATE POPUP to activate the corresponding menu.

When an item is chosen from a menu, ON SELECTION POPUP uses PROMPT( ) and POPUP( ) to pass the item number and menu name to the CHOICE procedure. CHOICE displays the text of the chosen item and the name of the menu containing the item. If the Exit item is chosen from the Card Info menu, the original Visual FoxPro system menu is restored.
Copy Code
*** Name this program DEFINPOP.PRG ***
CLEAR
SET SYSMENU SAVE
SET SYSMENU TO
DEFINE PAD convpad OF _MSYSMENU PROMPT '\<Conversions' COLOR SCHEME 3 ;
   KEY ALT+C, ''
DEFINE PAD cardpad OF _MSYSMENU PROMPT 'Card \<Info' COLOR SCHEME 3 ;
   KEY ALT+I, ''
ON PAD convpad OF _MSYSMENU ACTIVATE POPUP conversion
ON PAD cardpad OF _MSYSMENU ACTIVATE POPUP cardinfo
DEFINE POPUP conversion MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF conversion PROMPT 'Ar\<ea' KEY CTRL+E, '^E'
DEFINE BAR 2 OF conversion PROMPT '\<Length' ;
   KEY CTRL+L, '^L'
DEFINE BAR 3 OF conversion PROMPT 'Ma\<ss' ;
   KEY CTRL+S, '^S'
DEFINE BAR 4 OF conversion PROMPT 'Spee\<d' ;
   KEY CTRL+D, '^D'
DEFINE BAR 5 OF conversion PROMPT '\<Temperature' ;
   KEY CTRL+T, '^T'
DEFINE BAR 6 OF conversion PROMPT 'T\<ime' ;
   KEY CTRL+I, '^I'
DEFINE BAR 7 OF conversion PROMPT 'Volu\<me' ;
   KEY CTRL+M, '^M'
ON SELECTION POPUP conversion;
   DO choice IN definpop WITH PROMPT( ), POPUP( )
DEFINE POPUP cardinfo MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF cardinfo PROMPT '\<View Charges' ;
   KEY ALT+V, ''
DEFINE BAR 2 OF cardinfo PROMPT 'View \<Payments' ;
   KEY ALT+P, ''
DEFINE BAR 3 OF cardinfo PROMPT 'Vie\<w Users' ;
   KEY ALT+W, ''
DEFINE BAR 4 OF cardinfo PROMPT '\-'
DEFINE BAR 5 OF cardinfo PROMPT '\<Charges '
DEFINE BAR 6 OF cardinfo PROMPT '\-'
DEFINE BAR 7 OF cardinfo PROMPT 'E\<xit '
ON SELECTION POPUP cardinfo;
   DO choice IN definpop WITH PROMPT( ), POPUP( )
PROCEDURE choice
PARAMETERS mprompt, mpopup
WAIT WINDOW 'You chose ' + mprompt + ;
   ' from popup ' + mpopup NOWAIT
IF mprompt = 'Exit'
   SET SYSMENU TO DEFAULT
ENDIF

See Also

Other Resources

ACTIVATE POPUP Command
CNTBAR( ) Function
CREATE MENU Command
DEFINE BAR Command
GETBAR( ) Function
HIDE POPUP Command
MOVE POPUP Command
MRKBAR( ) Function
ON SELECTION BAR Command
POPUP( ) Function
PRMBAR( ) Function
PROMPT( ) Function
RELEASE POPUPS Command
SET MARK OF Command
SET MESSAGE Command
SIZE POPUP Command
SHOW POPUP Command
Commands
Language Reference


DEFINE WINDOW Command

Visual FoxPro 9.0 Language Reference
DEFINE WINDOW Command
See Also Example

Creates a window and specifies its attributes.

DEFINE WINDOW WindowName1 FROM nRow1, nColumn1 TO nRow2, nColumn2
   | AT nRow3, nColumn3 SIZE nRow4, nColumn4
   [IN [WINDOW] WindowName2 | IN SCREEN | IN DESKTOP [NAME ObjectName]
      [FONT cFontName [, nFontSize [, nFontCharSet]]] [STYLE cFontStyle]
      [FOOTER cFooterText] [TITLE cTitleText] [HALFHEIGHT]
      [DOUBLE | PANEL | NONE | SYSTEM | cBorderString]
      [CLOSE | NOCLOSE] [FLOAT | NOFLOAT] [GROW | NOGROW] [MDI | NOMDI]
      [MINIMIZE | NOMINIMIZE] [ZOOM | NOZOOM] [ICON FILE FileName1]
      [FILL cFillCharacter | FILL FILE FileName2]
      [COLOR SCHEME nSchemeNumber   | COLOR ColorPairList]]

Parameters

WindowName1

Specifies the name of the window to create. Window names can be up to 254 characters long in Visual FoxPro. They must begin with a letter or underscore, and cannot begin with a number. They can contain any combination of letters, numbers and underscores.
FROM nRow1, nColumn1TO nRow2, nColumn2

Specifies the position and size of the user-defined window on the main Visual FoxPro window. FROM nRow1, nColumn1 specifies the position of the upper-left corner of the user-defined window on the main Visual FoxPro window. TO nRow2, nColumn2 specifies the position of the lower-right corner of the user-defined window on the main Visual FoxPro window. A window can be defined with coordinates that lie outside the Visual FoxPro window border and can be larger than the main Visual FoxPro window. The window's location and size are determined by the font of the window's parent. The window's parent can be another user-defined window or the main Visual FoxPro window.
AT nRow3, nColumn3SIZE nRow4, nColumn4

Specifies the position and size of a user-defined window. AT nRow3, nColumn3 specifies the position of the upper-left corner of the user defined window on the main Visual FoxPro window. This position is determined by the current font of the window's parent. Because the AT clause is identical to the FROM clause in all respects, the two clauses can be used interchangeably. SIZE nRow4, nColumn4 specifies in rows and columns the size of the user-defined window and ensures that text displayed in a specific font will fit in the window you create. You can specify a font and font style for a user-defined window by including the FONT and STYLE clauses. If you specify a font for the window and include the SIZE clause, its size is determined by the window's font height and width. If you don't specify a font for a window, the window's font is the default system font, 10-point FoxFont.
IN [WINDOW] WindowName2

Places a user-defined window in a parent window. The user-defined window becomes a child window and cannot be moved outside the parent window. If the parent window is moved, the child window moves with it. When a child window is placed in a parent window, the child window coordinates specified with the FROM and TO clauses or the AT and SIZE clauses are relative to the parent window, not the main Visual FoxPro window. In the following example, a parent window, wParent, is created. A child window, wChild, is placed in the parent window.
Copy Code
CLEAR
DEFINE WINDOW wParent ;
   FROM 1, 1 TO 20, 30 ;
   TITLE "Parent"         && Parent window.
ACTIVATE WINDOW wParent
DEFINE WINDOW wChild ;
   FROM 1, 1 TO 20, 20 ;
   TITLE "Child" ;
   IN WINDOW wParent       && Child window.
ACTIVATE WINDOW wChild
ACTIVATE SCREEN
WAIT WINDOW 'Press a key to clear the windows'
RELEASE WINDOW wParent, wChild
CLEAR
IN SCREEN

Explicitly places a user-defined window on the main Visual FoxPro window. If you omit IN SCREEN, the user-defined window is placed on the main Visual FoxPro window by default. You can include the IN WINDOW clause in ACTIVATE WINDOW to place the window in another user-defined window and override this IN SCREEN clause.
IN DESKTOP

Places a user-defined window on the Microsoft Windows desktop, outside the main Visual FoxPro window. The position of the window is relative to the Windows desktop, and the current font of the main Visual FoxPro window.
NAME ObjectName

Creates an object reference for the window, allowing you to manipulate the window with object-oriented properties available for the form object. For additional information about object-oriented programming in Visual FoxPro, see Object-Oriented Programming. For additional information about the form object properties you can specify for a window created with the NAME clause, see the Form Object topic.
FONT cFontName[, nFontSize [, nFontCharSet]]

Specifies a font for text placed in the window. cFontName specifies the name of the font and nFontSize specifies the point size. If you omit nFontSize, a 9-point font is used. You can specify a language script with nFontCharSet. See the GETFONT( ) Function for a list of available language script values. For example, this command creates a window that displays output directed to the window in a 16-point Courier font:
Copy Code
DEFINE WINDOW wDisplayFont FROM 2,2 TO 12,22 FONT 'Courier', 16
If you omit the FONT clause, a 10-point FoxFont is used. If the font you specify is not available, a font with similar font characteristics is substituted.
STYLE cFontStyle

Specifies a font style for text placed in the window. cFontStyle specifies the font. If you omit the STYLE clause, or if the font style you specify is not available, the Normal font style is used. The following table lists font styles and their corresponding characters.

Character Font style

B

Bold

I

Italic

N

Normal

Q

Opaque

-

Strikeout

T

Transparent

U

Underline
You can include more than one character to specify a combination of font styles. In Visual FoxPro, the following commands specify the style Bold Italic:
Copy Code
DEFINE WINDOW wDisplayStyle FROM 2, 2 TO 12, 22 STYLE 'BI'
FOOTER cFooterText

Included for backwards compatibility. Ignored in Visual FoxPro Windows versions.
TITLE cTitleText

Assigns a title with the TITLE clause. cTitleText specifies the title's text and is centered in the top border of the window. If the title is wider than the window, the title is truncated.
HALFHEIGHT

Creates a window with a half-height title bar. This provides compatibility for windows created in previous versions of FoxPro that are imported into Visual FoxPro. When you use DEFINE WINDOW to create a window, a half-height title bar is used, unless you include the SYSTEM keyword or you include a FONT clause. If you include the HALFHEIGHT keyword, a half-height title bar is used regardless of whether the SYSTEM or FONT clause is included.
DOUBLE | PANEL | NONE | SYSTEM | cBorderString

Specifies a border style for a user-defined window. The default border is a single line.

Argument Description

DOUBLE

Specifies a double-line border around the window.

PANEL

Specifies a wide border around the window.

NONE

Suppresses the border entirely.

SYSTEM

Specifies the user-defined window to look like a system window. When you include certain other clauses (GROW, ZOOM, and so on), the appropriate window controls are placed in the window's border.

cBorderString

Specifies a custom border. For more information on defining a custom border, see SET BORDER.
Including DOUBLE or a custom border string creates a window with the PANEL border. Including the CLOSE, FLOAT, GROW, ZOOM, or MINIMIZE clauses places the appropriate controls on the window even if the SYSTEM window definition clause is not included.
CLOSE

Allows the user to close a user-defined window using the keyboard or mouse. Closing a window removes it from the main Visual FoxPro window or a parent user-defined window and removes its definition from memory. If you omit CLOSE, you cannot close the window using the interface; the window must be closed using a command in a program or in the Command window.
NOCLOSE

Prevents the window from being closed except by a command in a program or in the Command window.
FLOAT

Allows the window to be moved using the keyboard or mouse. If you omit FLOAT, you cannot move the window except using the MOVE WINDOW command in a program or in the Command window.
NOFLOAT

Prevents the window from being moved except by using the MOVE WINDOW command in a program or in the Command window.
GROW

Allows you to resize a user-defined window using the keyboard or mouse. If you omit GROW, you cannot size the window except using the SIZE WINDOW command in a program or in the Command window.
NOGROW

Prevents the window from being resized except by the SIZE WINDOW command in a program or in the Command window.
MDI

Creates a user-defined window that is MDI-compliant. MDI (multiple document interface) is a specification that allows multiple document windows and determines their structure and behavior. If you omit MDI, the window you create isn't MDI-compliant. When an MDI-compliant window is maximized:
  • The window assumes the size of the main Visual FoxPro window. The window's controls disappear and its pop-up menu icon appears in the Visual FoxPro system menu bar. The window's Restore button is also placed in the Visual FoxPro system menu bar.

  • The window title is placed in the Visual FoxPro title bar and is separated from the Visual FoxPro title by a hyphen.

  • If you activate another MDI-compliant window, it is automatically maximized.

NOMDI

Creates a window that isn't MDI-compliant.
MINIMIZE

Allows you to minimize a user-defined window using the keyboard or mouse.
NOMINIMIZE

Prevents the window from being minimized.
ZOOM

Allows the window to be maximized using the keyboard or mouse. You can also restore the window to its original size.
NOZOOM

Prevents the window from being maximized.
ICON FILE FileName

Specifies the icon that displays when the window is minimized. You must include the MINIMIZE keyword in DEFINE WINDOW. You can specify only an icon (.ico) file; you cannot specify a bitmap (.bmp) file.
FILL FILE FileName2

Specifies wallpaper (the background) for the window. The window is tiled with the specified FileName2. You specify a .bmp bitmap file.
COLOR SCHEME nSchemeNumber

Specifies the colors for the user-defined window. By default, the colors of windows created with DEFINE WINDOW are controlled by color scheme 1.
COLOR ColorPairList

Specifies the colors for the user-defined window.

Remarks

After user-defined windows are created with DEFINE WINDOW, they can be displayed in the main Visual FoxPro window with ACTIVATE WINDOW or SHOW WINDOW. The number of user-defined windows you can create is limited only by the amount of available memory and system resources.

Activated windows remain in the main Visual FoxPro window until DEACTIVATE WINDOW or HIDE WINDOW is issued. DEACTIVATE WINDOW and HIDE WINDOW remove windows from the main Visual FoxPro window but don't remove the window definitions from memory. Windows can be placed back in the main Visual FoxPro window with ACTIVATE WINDOW or SHOW WINDOW.

Use CLEAR WINDOWS or RELEASE WINDOWS to remove windows from the main Visual FoxPro window and window definitions from memory. Windows whose definitions have been removed from memory must be recreated with DEFINE WINDOW in order to be redisplayed.

Example

In the following example, a window named output is created and activated. The program waits for you to press a key and then hides the window. The program waits for you to press a key again and then redisplays the window.
Copy Code
CLEAR
DEFINE WINDOW output FROM 2,1 TO 13,75 TITLE 'Output' ;
   CLOSE FLOAT GROW ZOOM
ACTIVATE WINDOW output
WAIT WINDOW 'press any key to hide window output'
HIDE WINDOW output
WAIT WINDOW 'press any key to show window output'
SHOW WINDOW output
WAIT WINDOW 'press any key to release window output'
RELEASE WINDOW  output

See Also

Other Resources

ACTIVATE WINDOW Command
DEACTIVATE WINDOW Command
Fonts Overview
Form Object
HIDE WINDOW Command
MODIFY WINDOW Command
MOVE WINDOW Command
RELEASE WINDOWS Command
SET BORDER Command
SHOW WINDOW Command
Commands
Language Reference


DELETE - SQL Command

Visual FoxPro 9.0 Language Reference
DELETE - SQL Command
See Also

Marks records for deletion.

Note:
Records marked for deletion are not physically removed from the table until the PACK command is issued. You can recall (unmark) records for deletion by using the RECALL command. For more information, see PACK Command and RECALL Command.

DELETE [Target] FROM [FORCE] Table_List [[, Table_List ...] | [JOIN [ Table_List]]]
   [WHERE FilterCondition1 [AND | OR FilterCondition2 ...]]

Parameters

DELETE [Target]

Specifies a target table, cursor, table or cursor alias, or file for the delete operation. If the FROM specifies more than one table, you must include the Target parameter. Target can have the following syntaxes:
  • [DatabaseName!]TableName

    DatabaseName! specifies the name of a database containing the table if the table is in a noncurrent database. If the table is in a noncurrent database, you must include the name of the database. Use an exclamation point (!) as a delimiter immediately following the database name and preceding the table name.

    TableName specifies the name of a table for the delete operation.

  • Alias

    Alias specifies an alias that matches a table in the FROM clause or a cursor in the current data session for the delete operation.

  • FileName

    FileName specifies the name of a file for the delete operation.

FROM [FORCE] Table_List[[, Table_List...] | [JOIN [Table_List]]]

Specifies one or more tables containing the data for the delete operation. The FROM clause has the same syntax as in the SQL SELECT command except for the following restrictions:
  • The target table or cursor cannot be included in an OUTER join as a secondary table or cursor.

  • It should be possible to evaluate all other JOIN operations before performing a JOIN operation on the target table.

  • The target cursor cannot be the result from a subquery.

For more information, see SELECT - SQL Command. FORCE specifies that the tables in Table_List are joined in the order they appear in the FROM clause.
Note:
If FORCE is omitted, Visual FoxPro attempts to optimize the delete operation. However, the delete operation might be executed faster by including the FORCE keyword to disable Visual FoxPro delete optimization.

Table_List can have the following syntaxes:
  • [DatabaseName!]Table [[AS] Local_Alias]

    DatabaseName! specifies the name of a database containing the table if the table is in a noncurrent database. If the table is in a noncurrent database, you must include the name of database. Use an exclamation point (!) as a delimiter immediately following the database name and preceding the table name.

    Table specifies the name of the table or cursor you want to retrieve data from. If no table is open, Visual FoxPro displays the Open dialog box so you can specify the file location. After the table opens, it remains open when the query is complete.

    Local_Alias specifies a temporary name for the table specified in Table. If you specify a local alias, you must use the local alias instead of the table name throughout the DELETE statement. The alias can represent a table or a cursor.

    JOIN provides the capability for specifying one or more secondary tables. There is no hard-coded limit on the number of tables, aliases, or JOIN clauses per DELETE statement.

  • (Subquery) AS Subquery_Alias

    Subquery specifies a SELECT statement within another SELECT statement. For more information about subqueries in SELECT statements, see SELECT - SQL Command - FROM Clause.

WHERE FilterCondition1 [AND | OR FilterCondition2...]

Specifies one or more filter conditions that records must meet to be deleted. There is no limit to the number of filter conditions in the WHERE clause. To reverse the value of a logical expression, use the NOT operator. To check for an empty field, use the EMPTY( ) function. For more information, see EMPTY( ) Function.

Remarks

If the SET DELETED command is set to ON, records marked for deletion are ignored by all commands that include a scope. For more information, see SET DELETED Command.

To determine the number of records updated, check the value of the _TALLY system variable immediately after executing the SQL DELETE command. For more information, see _TALLY System Variable.

Tip:
When marking multiple records for deletion in a table opened for shared access, SQL DELETE uses record locking, unlike the DELETE command. This reduces record contention in multiuser situations but might reduce performance. For maximum performance, open the table for exclusive use or use the FLOCK( ) function to lock the table. For more information, see DELETE Command and FLOCK( ) Function.

Example 1

Description

The following example uses the OPEN DATABASE command to open the Visual FoxPro sample database, TestData.dbc. The USE command opens the Customer table in TestData.dbc. The SQL DELETE statement marks those records for deletion where the Country field contains "USA". The CLEAR command erases the main Visual FoxPro window. The LIST command lists all records marked for deletion. Following the LIST command, if the PACK command was called, the marked records would be deleted.

The RECALL ALL command unmarks all the records marked for deletion. The COUNT command verifies the number of records marked for deletion by counting them. WAIT WINDOW displays that number of records that were marked for deletion.

Code

Copy Code
CLOSE DATABASES
CLEAR
OPEN DATABASE HOME(2)+"Data\TestData"
USE Customer
DELETE FROM Customer WHERE country = "USA"
CLEAR
LIST FIELDS company, country FOR DELETED( )
WAIT WINDOW "Records currently marked for deletion"+CHR(13) + ;
   "Press any key to revert..."
RECALL ALL
CLEAR
COUNT FOR DELETED( )=.T. TO nDeleted
WAIT WINDOW ALLTRIM(STR(nDeleted)) + " records marked for deletion."

Comments

For more information, see OPEN DATABASE Command, USE Command, LIST Commands, CLEAR Commands, COUNT Command, and WAIT Command.

Example 2

Description

The following code shows a correlated delete in which records in a MyProducts cursor are marked for deletion based on the value of the Discontinued Field in the MSRPList cursor. The WHERE clause specifies the criteria for matching records and the condition evaluated for marking the records.

Code

Copy Code
CLOSE DATABASES ALL
CREATE CURSOR MyProducts (ProdID I , OurPrice Y NULL)
INSERT INTO MyProducts VALUES (1,1.10) && matches but is not marked for deletion
INSERT INTO MyProducts VALUES (2,2.20) && matches and is marked
INSERT INTO MyProducts VALUES (3,3.30) && matches and is marked

CREATE CURSOR MSRPList (ProdID I , ProdCategory I Null, MSRP Y, Discontinued L)
INSERT INTO MSRPList VALUES (1, 9, 1.00, .f.)
INSERT INTO MSRPList VALUES (2, 8, 2.00, .t.)
INSERT INTO MSRPList VALUES (3, 7, 3.00, .t.)

DELETE  MyProducts FROM MSRPList ;   WHERE MSRPList.ProdID = MyProducts.ProdID;      AND MSRPList.discontinued = .t.

SELECT MyProducts
BROWSE

Comments

For more information and another example, see SQL Language Improvements.

See Also

Other Resources

INSERT - SQL Command
UPDATE - SQL Command
SQL Commands and Functions
Commands
Language Reference


DELETE Command

Visual FoxPro 9.0 Language Reference
DELETE Command
See Also Example

Marks records for deletion.

DELETE [Scope] [FOR lExpression1] [WHILE lExpression2]
   [IN nWorkArea | cTableAlias] [NOOPTIMIZE]

Parameters

Scope

Specifies a range of records to mark for deletion. The default scope for DELETE is the current record (NEXT 1). The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. 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 marked for deletion. Rushmore Query Optimization optimizes a query created with DELETE ... FOR if lExpression1 is an optimizable expression and the table is indexed on DELETED( ). For best performance, use an optimizable expression in the FOR clause. For information on Rushmore optimizable expressions, see SET OPTIMIZE, and Using Rushmore Query Optimization to Speed Data Access in Optimizing Applications.
WHILE lExpression2

Specifies a condition whereby records are marked for deletion for as long as lExpression2 evaluates to true (.T.).
IN nWorkArea

Specifies the work area of the table in which records are marked for deletion.
IN cTableAlias

Specifies the alias of the table in which records are marked for deletion. If you omit nWorkArea and cTableAlias, records are marked for deletion in the table in the currently selected work area.
NOOPTIMIZE

Disables Rushmore optimization of DELETE.

Remarks

Records marked for deletion aren't physically removed from the table until PACK is issued. Records marked for deletion can be recalled (unmarked) with RECALL.

Example

The following example opens the customer table in the testdata database. DELETE is used to mark all records for deletion where the country field contains USA. All the records marked for deletion are displayed. RECALL ALL is used to unmark all the records marked for deletion.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

DELETE FOR country = 'USA'  && Mark for deletion
CLEAR
LIST FIELDS company, country FOR DELETED( ) && List marked records
RECALL ALL  && Unmark all records marked for deletion

See Also

Other Resources

DELETE - SQL Command
DELETED( ) Function
PACK Command
RECALL Command
SET DELETED Command
Commands
Language Reference


DELETE CONNECTION Command

Visual FoxPro 9.0 Language Reference
DELETE CONNECTION Command
See Also Example

Deletes a named connection from the current database.

DELETE CONNECTION ConnectionName

Parameters

ConnectionName

Specifies the name of the named connection to delete from the current database.

Remarks

Deleting a named connection definition does not close any active connections.

DELETE CONNECTION requires exclusive use of the database. To open a database for exclusive use, include EXCLUSIVE in OPEN DATABASE.

Example

The following example assumes an ODBC data source called MyFoxSQLNT is available. The testdata database is opened, and a connection named Myconn is created. DISPLAY CONNECTIONS is used to display the named connections in the database. The connection is then removed from the database with DELETE CONNECTION.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')

CREATE CONNECTION Myconn DATASOURCE "MyFoxSQLNT" USERID "<userid>" PASSWORD "<password>"
DISPLAY CONNECTIONS    && Displays named connections in the database
DELETE CONNECTION Myconn  && Removes the connection just created

See Also

Other Resources

CREATE CONNECTION Command
MODIFY CONNECTION Command
RENAME CONNECTION Command
Commands
Language Reference


DELETE DATABASE Command

Visual FoxPro 9.0 Language Reference
DELETE DATABASE Command
See Also Example

Deletes a database from disk.

DELETE DATABASE DatabaseName | ? [DELETETABLES] [RECYCLE]

Parameters

DatabaseName

Specifies the name of the database to delete from disk. The database you specify cannot be open. DatabaseName can include the path to the database with the database name.
?

Displays the Delete dialog box from which you can specify the name of the database to delete from disk.
DELETETABLES

Deletes the tables contained in the database from disk and the database containing the tables.
RECYCLE

Specifies that the database isn't immediately deleted from disk and is placed in the Windows Recycle Bin.

Remarks

Always use DELETE DATABASE to delete a database from disk. Unlike the file manipulation utility of the operating system, DELETE DATABASE removes references to the database from the tables in the database.

If SET SAFETY is ON, Visual FoxPro asks if you'd like to delete the database you specify. If SET SAFETY is OFF, the database is automatically deleted from disk.

Example

This example creates a database named people. A table named friends is created and is automatically added to the database. DISPLAY TABLES is used to display the tables in the database, and DISPLAY DATABASES is used to display information about the tables in the database.

DELETE DATABASE is used with the DELETETABLES option to remove the database and its friends table from disk.
Copy Code
CLOSE ALL
CREATE DATABASE people
CREATE TABLE friends (FirstName C(20), LastName C(20))
CLEAR
DISPLAY TABLES  && Displays tables in the database
DISPLAY DATABASES  && Displays table information
CLOSE ALL
DELETE DATABASE people DELETETABLES

See Also

Other Resources

ADD TABLE Command
CLOSE DATABASES Command
DBC( ) Function
DBGETPROP( ) Function
DBSETPROP( ) Function
DISPLAY TABLES Command
OPEN DATABASE Command
REMOVE TABLE Command
Commands
Language Reference


DELETE FILE Command

Visual FoxPro 9.0 Language Reference
DELETE FILE Command
See Also Example

Erases a file from a disk.

DELETE FILE [FileName | ?] [RECYCLE]

Parameters

FileName

Specifies the file to delete.
Tip:
FileName can contain wildcard characters such as * and ?. For example, to delete backup files with the extension .bak in the current directory, issue DELETE FILE *.BAK. If FileName contains spaces, enclose the entire file name in quotes.

?

Displays the Delete dialog box so you can choose a file to delete.
RECYCLE

Specifies that the file is not immediately deleted from disk and is placed in the Windows Recycle Bin.
Caution:
Any file deleted with this command cannot be retrieved. Even when the SET SAFETY command is set to ON, you are not warned before the file is deleted.

Remarks

The file you want to delete cannot be open when DELETE FILE is issued. The file name must include a path if it is on a different drive or volume, or in a different directory from the default. A file name extension must be included.

If the file you want to delete represents a table that is part of a database, you need to remove the table from the database before deleting the file. You can use the REMOVE TABLE command before using the DELETE FILE command. If you delete a table that has an associated .FPT memo file, be sure to delete the memo file.

This command does not generate an error if the specified file does not exist.

The DELETE FILE command is the same as the ERASE command.

Example

In the following example, the structure of Customer.dbf and all records in which the country equals USA are copied to a table named backup. The data in backup is then copied to a text file, temp, which is opened and then deleted once closed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

COPY STRUCTURE TO backup
USE backup
APPEND FROM customer FOR country = 'USA'
COPY TO temp TYPE DELIMITED

WAIT WINDOW 'Press Esc to close and erase temp.txt' NOWAIT
MODIFY FILE temp.txt NOEDIT
DELETE FILE temp.txt
? IIF(FILE('temp.txt'),'File not deleted','File deleted')
USE
DELETE FILE backup.dbf

See Also

Other Resources

ERASE Command
REMOVE TABLE Command
SET SAFETY Command
Commands
Language Reference


DELETE TAG Command

Visual FoxPro 9.0 Language Reference
DELETE TAG Command
See Also

Removes a tag or tags from a compound index (.cdx) file. There are two versions of the syntax.

DELETE TAG TagName1 [OF CDXFileName1] [, TagName2 [OF CDXFileName2]]...
DELETE TAG ALL [OF CDXFileName]

Parameters

TagName1 [OF CDXFileName1] [, TagName2 [OF CDXFileName2]] ...

Specifies a tag to remove from a compound index file. You can delete multiple tags with one DELETE TAG by including a list of tag names separated by commas. If two or more tags with the same name exist in the open index files, you can remove a tag from a specific index file by including OF CDXFileName.
ALL [OF CDXFileName]

Removes every tag from a compound index file. If the current table has a structural compound index file, all tags are removed from the index file, the index file is deleted from the disk, and the flag in the table's header indicating the presence of an associated structural compound index file is removed. Use ALL with OF CDXFileName to remove all tags from an open compound index file other than the structural compound index file.

Remarks

Compound index files, created with INDEX, contain tags corresponding to index entries. DELETE TAG is used to remove a tag or tags from open compound index files. You can delete only tags from compound index files open in the current work area. If you remove all the tags from a compound index file, the file is deleted from the disk.

Visual FoxPro looks first for a tag in the structural compound index file (if one is open). If the tag isn't in the structural compound index file, Visual FoxPro then looks for the tag in the other open compound index files.

Visual FoxPro issues a warning if you attempt to delete a primary or candidate index tag and SET SAFETY is ON.

See Also

Other Resources

COPY INDEXES Command
COPY TAG Command
INDEX Command
TAG( ) Function
Commands
Language Reference


DELETE TRIGGER Command

Visual FoxPro 9.0 Language Reference
DELETE TRIGGER Command
See Also Example

Removes a Delete, Insert, or Update trigger for a table from the current database.

DELETE TRIGGER ON TableName FOR DELETE | INSERT | UPDATE

Parameters

TableName

Specifies the name of table for which the trigger is deleted.
FOR DELETE | INSERT | UPDATE

Specifies the trigger to delete. Include FOR DELETE to remove the Delete trigger, FOR INSERT to remove the Insert trigger, and FOR UPDATE to remove the Update trigger.

Remarks

Use CREATE TRIGGER to create a Delete, Insert, or Update trigger for a table.

Example

The following example creates an Update trigger, which prevents values greater than 50 from being entered in the maxordamt field in the customer table. DISPLAY DATABASE is used to display the Update trigger. DELETE TRIGGER is then used to remove the Update trigger, and DISPLAY DATABASE is issued again to verify the removal of the Update trigger.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')  && Open testdata database
USE CUSTOMER  && Open customer table

CREATE TRIGGER ON customer FOR UPDATE AS maxordamt <= 50
CLEAR
DISPLAY DATABASE
DELETE TRIGGER ON customer FOR UPDATE
DISPLAY DATABASE

See Also

Other Resources

ADD TABLE Command
AERROR( ) Function
CREATE DATABASE Command
CREATE TRIGGER Command
DISPLAY DATABASE Command
LIST DATABASE Command
OPEN DATABASE Command
Commands
Language Reference


DELETE VIEW Command

Visual FoxPro 9.0 Language Reference
DELETE VIEW Command
See Also Example

Deletes a SQL view from the current database.

DELETE VIEW ViewName

Parameters

ViewName

Specifies the name of the view deleted from the current database.

Remarks

Use CREATE SQL VIEW to create a SQL view and add the view to the current database. If a SQL view is opened and then deleted, the cursors containing the SQL view results are not closed.

DELETE VIEW requires exclusive use of the database. To open a database for exclusive use, include EXCLUSIVE in OPEN DATABASE.

Example

The following example opens the testdata database. CREATE SQL VIEW is used to create a local SQL view named myview. The View Designer is displayed, making it possible for you to specify tables and conditions for the SQL view. After you save the SQL view, DISPLAY DATABASE is used to display information about the SQL view. DELETE VIEW is then used to delete the local SQL view named myview.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')

CREATE SQL VIEW myview
CLEAR
DISPLAY DATABASE
DELETE VIEW myview

See Also

Other Resources

CREATE SQL VIEW Command
OPEN DATABASE Command
Commands
Language Reference


DIMENSION Command

Visual FoxPro 9.0 Language Reference
DIMENSION Command
See Also Example

Creates a one-dimensional or two-dimensional array of variables.

Note:
DIMENSION is identical in operation and similar in syntax to the DECLARE command. For more information, see DECLARE Command.

DIMENSION ArrayName1(nRows1 [, nColumns1]) [AS cType]
   [, ArrayName2(nRows2 [, nColumns2])] ...

Parameters

ArrayName1

Specifies the name of the array.
Tip:
You can create multiple arrays with a single DIMENSION command by including additional array names, for example, ArrayName2, ArrayName3, and so on.

nRows1 [, nColumns1]

Specifies the size of the array to create.
Note:
You must specify a size for each array you create with DIMENSION. Array sizes can be limited by available memory, which affects performance, especially for very large arrays. Make sure your computer has enough memory to accommodate the upper limits of your arrays.

To create a one-dimensional array, include only nRows1. In this scenario, DIMENSION uses nRows1 to create the number of rows in a one-dimensional array with a single column. For example, the following command creates a one-dimensional array named gaArrayOne that contains ten rows and one column:
Copy Code
DIMENSION gaArrayOne(10)
To create a two-dimensional array, include both nRows1 and nColumns1. In this scenario, nRows1 specifies the number of rows in the array, and nColumns1 specifies the number of columns. The following example creates a two-dimensional array named gaArrayTwo containing two rows and four columns:
Copy Code
DIMENSION gaArrayTwo(2,4)
AS cType

Specifies a data type for the array. Using the AS cType clause, you can define and specify a data type other than Variant for arrays. The AS cType syntax does not appear in IntelliSense during design time; it is meant for use only at run time. For an example, see Example 4 in the Example section. The AS cType clause applies only when passing an array to a COM component. Otherwise, Visual FoxPro disregards the AS cType clause. If you specify a data type that is not a valid COM data type, Visual FoxPro automatically defaults to VARIANT type. Data specified as VARIANT can only be passed by reference and not by strongly typed values. The following table lists valid COM type mappings.

VFP defined type IntelliSense Quick Info COM friendly name COM Typelib .NET system type XSD (SOAP) type

Boolean

Logical

Boolean

VARIANT_BOOL (VT_BOOL)

System.Boolean

boolean

Byte

Number

Byte

unsigned char (VT_UI1)

System.Byte

Character *

String

String

BSTR (VT_BSTR)

System.String

string

Currency *

Currency

Currency

CURRENCY (VT_CY)

Date

Date

Date

DATE (VT_DATE)

System.DateTime

dateTime

DateTime

Date

Date

DATE (VT_DATE)

System.DateTime

dateTime

Decimal *

Number

wchar_t (VT_DECIMAL)

System.UInt16

Double

Number

Double

double (VT_R8)

System.Double

double

Float

Variant

VARIANT (VT_VARIANT)

System.Object

anyType

Integer

Number

Long

long (VT_I4)

System.Int32

int

Logical

Logical

Boolean

VARIANT_BOOL (VT_BOOL)

System.Boolean

boolean

Long

Number

Long

long (VT_I4)

System.Int32

int

Memo

Variant

VARIANT (VT_VARIANT)

System.Object

anyType

Number

Number

Double

double (VT_R8)

System.Double

double

Object

Object

Object

IDispatch* (VT_DISPATCH)

System.Object

Short

Number

Long

long (VT_I4)

System.Int32

int

Single *

Number

Single

single (VT_R4)

System.Single

String

String

String

BSTR (VT_BSTR)

System.String

string

Variant

Variant

VARIANT (VT_VARIANT)

System.Object

anyType

Void

VOID

Void

void (VT_VOID)

System.IntPtr

Array

Array

SAFEARRAY(type)

Type[]

Base64Binary

Remarks

You can use either brackets or parentheses to enclose expressions in DIMENSION. For example, the following two lines of code create identical arrays:

Copy Code
DIMENSION gaArrayOne(10), gaArrayTwo[2,4], gaArrayThree(3,3)
DIMENSION gaArrayOne[10], gaArrayTwo(2,4), gaArrayThree[3,3]

Array Elements The size of an array determines how many elements the array contains. Each array element can store a single piece of information. To determine the total number of elements an array contains, multiply the number of rows (nRows1) in the array by the number of columns (nColumns1) in the array.

Array elements can contain any type of data and are initialized to False (.F.) when the array is first created. You can initialize all the elements in an array to the same value with the STORE command if the SETCOMPATIBLE command is set to FOXPLUS or OFF (default). The following example stores the string "initial" to all the elements in the array gaArray:

Copy Code
DIMENSION gaArray(10,3)
STORE 'initial' TO gaArray

For more information about limits on the number of elements in arrays, see Visual FoxPro System Capacities.

Note:
Visual FoxPro arrays are one-based - the first element, row, or column of an array is specified with the number 1. (Arrays in other programming languages may be zero-based; the first element, row, or column of an array is specified with the number 0.)

Array Subscripts You can access and manipulate specific elements in an array by using the array name and array subscripts, or indexes. An array subscript is a unique number that identifies the position of the element in the array. The subscript or subscripts for the first element in an array is always 1.

If the array is one-dimensional, the array uses one subscript to identify the row number of the array. For example, the subscript for the element in the third row of a one-dimensional array is 3.

If the array is two-dimensional, the array uses two subscripts to identify elements in the array. The first subscript indicates the row location of the element, and the second subscript indicates the column location. For example, the subscripts for the element in the third row and fourth column of a two-dimensional array are (3,4). You can also reference two-dimensional arrays using a single subscript.

To return the single subscript from a pair of array row and column subscripts, use AELEMENT( ). To return the row and column subscripts from a single subscript, use ASUBSCRIPT( ) function.

For more information about subscripts, see ASUBSCRIPT( ) Function.

Redimensioning Arrays You can change the size and dimensions of an array by calling DIMENSION again. The size of an array can be increased or decreased; one-dimensional arrays can be converted to two dimensions, and two-dimensional arrays can be reduced to one dimension.

Note:
If a two-dimensional array is redimensioned with fewer rows or columns, the number of elements is decreased by element number, not by row or column number. For example, a 10 by 10 array redimensioned to 10 by 7 loses all element data for elements 71 and higher. For more information, see AELEMENT( ) Function.

If the number of elements in an array is increased, the contents of all the elements in the original array are copied to the newly redimensioned array. The additional array elements are initialized to False (.F.).

When the size of an array is increased or decreased when SET COMPATIBLE is set to ON or DB4, the value of each element in the array is reinitialized to .F.

Typed Arrays You can pass a typed array by reference or by value. You should not explicitly specify Visual FoxPro objects, such as CommandButton. Instead, use Object:

Copy Code
DIMENSION aObjects[] AS CommandButton   && Not supported
DIMENSION aObjects[] AS Object   && Recommended
Note:
If the COM server is a Visual FoxPro server, you can specify a valid Visual FoxPro object. However, non Visual FoxPro servers will not recognize this type.

You should use COMARRAY( ) to control other settings for how arrays are passed to COM servers, for example, zero-based, byref, and so on.

Note:
When passing arrays to servers running the Microsoft .NET Framework, you must explicitly call COMARRAY(<object>, 10) to pass a zero-based array by reference. The interop marshaling code provided by the .NET Framework expects a byref array but receives a byval array instead and fails.

Typed arrays of Single (scaler) are not supported for COM servers other than Visual FoxPro COM servers. You cannot pass Currency types to servers running the Microsoft .NET Framework.

When servers running the Microsoft .NET Framework return System.Decimal and System.UInt16 types, they are converted to wchart_t, which maps to the Visual FoxPro Decimal data type.

Example

Example 1

The following example demonstrates the result of increasing the size of a one-dimensional array.

Note:
If you type these commands in the Command window, the array will be PUBLIC. However, the array will be PRIVATE if you copy them into a program and run it.

If the number of elements in an array is decreased, the elements and any data they contain are deleted. When a one-dimensional array is redimensioned to two dimensions, the contents of the original one-dimensional array are copied to the new array in an element-to-row order.

Copy Code
DIMENSION marray(2)
STORE 'A' TO marray(1)
STORE 'B' TO marray(2)
CLEAR
DISPLAY MEMORY LIKE marray
DIMENSION marray(4)
DISPLAY MEMORY LIKE marray
WAIT WINDOW

Example 2

In the following example, a one-dimensional array is converted to a two-dimensional array. The contents of the elements of the one-dimensional array are copied to the first row of the new array, followed by the second row and so on. The additional elements are initialized to False (.F.).

When a two-dimensional array is converted to one dimension, the contents of the original two-dimensional array are copied to the new array in a row-to-element order. The first element in the first row becomes the first element in the one-dimensional array, the second element in the first row becomes the second element, and so on.

Use ADEL( ) or AINS( ) to delete or insert array elements, rows and columns. Use APPEND FROM ARRAY, COPY TO ARRAY, SCATTER, and GATHER to transfer data between table records and arrays.

Copy Code
DIMENSION marrayone(4)
STORE 'E' TO marrayone(1)
STORE 'F' TO marrayone(2)
STORE 'G' TO marrayone(3)
STORE 'H' TO marrayone(4)
CLEAR
DISPLAY MEMORY LIKE marrayone
DIMENSION marrayone(2,3)
DISPLAY MEMORY LIKE marrayone
WAIT WINDOW

Example 3

In the following example, a two-dimensional array is created and loaded with data. The array elements and the data they contain are displayed.

Copy Code
DIMENSION sample(2,3)
STORE 'Goodbye' TO sample(1,2)
STORE 'Hello' TO sample(2,2)
STORE 99 TO sample(6)
STORE .T. TO sample(1)
CLEAR
DISPLAY MEMORY LIKE sample

Example 4

In the following example, an array is created in Visual FoxPro and is then passed by reference to a Visual Basic COM server, which expects a strong type of Long. Previously, calling FillIntArray would fail because aMyArray has Variant type. However, after including a definition in the Visual Basic class that defines the array as type Variant, calling FillIntArray works as shown:

Copy Code
* Visual FoxPro code
DIMENSION aMyArray [10] AS Long
lo.FillIntArray(@aMyArray, 100)   && Passing to Visual Basic COM Server

' Add following Visual Basic code to .CLS file and compile
' to COM component
Public Sub FillIntArray(ByRef aInts() As Long, iCount As Long)
   ReDim aInts(1 to 100)
   Dim ii As Interger
   For ii = 1 to 100
      AInts(ii) = ii
   Next
End Sub

See Also

Other Resources

ADEL( ) Function
AELEMENT( ) Function
AINS( ) Function
ALEN( ) Function
ASUBSCRIPT( ) Function
DECLARE Command
EXTERNAL Command
PRIVATE Command
PUBLIC Command
SET COMPATIBLE Command


DIR or DIRECTORY Command

Visual FoxPro 9.0 Language Reference
DIR or DIRECTORY Command
See Also Example

Displays information about the files in a directory.

DIR | DIRECTORY [ON Drive] [[LIKE] [Path] [FileSkeleton]]
   [TO PRINTER [PROMPT] | TO FILE FileName]

Parameters

ON Drive

Specifies the name of the drive on which the directory is located.
[[LIKE] [Path] [FileSkeleton]]

Specifies the path to the directory containing the files. The path can include the drive name if you omit ON Drive. Include FileSkeleton to display information about file types other than tables. FileSkeleton is a file specification skeleton that supports wildcards. For example, to list all program files in the current directory, issue the following command:
Copy Code
DIR *.PRG
In Visual FoxPro, you can issue the following command to list all files without extensions:
Copy Code
DIR *.
TO PRINTER [PROMPT]

Directs output from DIRECTORY to a printer. In Microsoft Visual FoxPro, you can include the optional PROMPT clause to display a print dialog box before printing starts. In this dialog box you can adjust printer settings, including the number of copies and page numbers to print. The printer settings that you can adjust depend on the currently installed printer driver. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from DIRECTORY to the file specified with FileName. If the file already exists and SET SAFETY is ON, you are asked if you want to overwrite the file.

Remarks

Use DIR to display information about files.

DIR without the LIKE clause or a skeleton displays the following:

  • Names of all tables in the directory.

  • Number of records in each table.

  • Date each table was last updated.

  • Size of each table in bytes (tables in the original Microsoft FoxBASE format are noted as such).

  • If each table is part of a database.

  • The total size in bytes the tables occupy on disk (not including associated .fpt memo files).

  • Number of tables displayed.

  • Total number of bytes remaining on the disk.

The table information for the default drive and directory is displayed unless otherwise specified with Drive or Path or both.

Example

Copy Code
CLEAR
DIR  && Display tables in the current directory
DIR *.CDX && Display index files in the current directory
DIR A*.DBF  && Display tables that begin with A
DIR *.*  && Display all files, including those without extensions

See Also

Other Resources

DISPLAY FILES Command
DIRECTORY( ) Function
Commands
Language Reference


DISPLAY Command

Visual FoxPro 9.0 Language Reference
DISPLAY Command
See Also Example

Displays record contents and expression results for the current table in the main Visual FoxPro window or a user-defined window.

DISPLAY [[FIELDS] FieldList] [Scope] [FOR lExpression1]
   [WHILE lExpression2] [OFF] [NOCONSOLE] [NOOPTIMIZE]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]

Parameters

[[FIELDS] FieldList]

Specifies the fields to display. If you omit the FIELDS clause, all fields from the table display by default.
Note:
Memo field contents do not display unless the memo field name is explicitly included in the field list. The displayed width of memo fields is determined by the SET MEMOWIDTH command. For more information, see SET MEMOWIDTH Command.

[Scope]

Specifies a range of records to display. Only those records that fall within the scope range display. The default scope for DISPLAY is the current record (NEXT 1). For more information about scope clauses, see Scope Clauses.
Note:
Commands that include Scope operate only on the table in the active work area.

[FOR lExpression1]

Specifies to display only those records that satisfy the logical condition lExpression1. Expressions can consist of combinations of literals, memory variables, array elements, fields, and memo fields. If lExpression1 can be optimized, Rushmore Query Optimization optimizes a query created with DISPLAY ... FOR. For best performance, use an expression that can be optimized in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
[WHILE lExpression2]

Specifies a condition to display records as long as the logical expression lExpression2 evaluates to True (.T.).
[OFF]

Suppresses display of record numbers. If you omit OFF, the record number displays preceding each record.
[NOCONSOLE]

Suppresses output to the main Visual FoxPro window or to the active user-defined window.
[NOOPTIMIZE]

Disables Rushmore optimization for DISPLAY. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
[TO PRINTER [PROMPT]

Directs output from DISPLAY to a printer. The PROMPT keyword specifies to display a Print dialog box before printing starts. The printer settings that you can adjust depend on the currently installed printer driver.
TO FILE FileName [ADDITIVE]]

Directs output from DISPLAY to the file specified with FileName. If the file already exists, and SET SAFETY is ON, Visual FoxPro prompts you to choose whether to overwrite the file. The ADDITIVE keyword appends output to the end of the specified file. If you omit ADDITIVE, Visual FoxPro overwrites the file with the value of the expression.

Remarks

DISPLAY is similar to the LIST command except that DISPLAY displays information one screen at a time and pauses between screens. LIST displays the same information without pausing. To view the next screen, press any key or click anywhere in the Visual FoxPro window. For more information, see LIST Commands.

Tip:
To display field names and expressions, set the SET HEADINGS command to ON. For more information, see SET HEADINGS Command.

DISPLAY shows data for Varbinary fields in hexadecimal format and is limited to 256 characters, which includes the prefix 0h and 127 hexadecimal encoded bytes. For more information, see Varbinary Data Type.

Example

The following example opens the Visual FoxPro sample database, TestData.dbc, using the OPEN DATABASE command and the Customer table using the USE command. The example clears the main Visual FoxPro window using the CLEAR command and displays the contents of the first record using the DISPLAY command.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer
CLEAR
DISPLAY FIELD cust_id, company, contact OFF NEXT 10

See Also

Other Resources

DISPLAY CONNECTIONS Command
DISPLAY DATABASE Command
DISPLAY DLLS Command
DISPLAY FILES Command
DISPLAY MEMORY Command
DISPLAY OBJECTS Command
DISPLAY PROCEDURES Command
DISPLAY STATUS Command
DISPLAY STRUCTURE Command
DISPLAY TABLES Command
DISPLAY VIEWS Command
Commands
Language Reference


DISPLAY CONNECTIONS Command

Visual FoxPro 9.0 Language Reference
DISPLAY CONNECTIONS Command
See Also Example

Displays information about the named connections in the current database.

DISPLAY CONNECTIONS [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]] [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs output from DISPLAY CONNECTIONS to a printer. In Visual FoxPro, you can include the optional PROMPT clause to display a Print dialog box before printing starts. Place PROMPT immediately after TO PRINTER.
TO FILE FileName

Directs output from DISPLAY CONNECTIONS to the file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

DISPLAY CONNECTIONS displays the connection names, datasource, and connection string in the current database. Use DBGETPROP( ) to return additional information about connections in the current database.

Example

The following example assumes an ODBC data source called MyFoxSQLNT is available. The testdata database is opened, and a connection named Myconn is created. DISPLAY CONNECTIONS is used to display the named connections in the database.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')

CREATE CONNECTION Myconn DATASOURCE "MyFoxSQLNT" USERID "<userid>" PASSWORD "<password>"
CLEAR
DISPLAY CONNECTIONS     && Displays named connections in the database

See Also

Other Resources

DISPLAY Command
CREATE CONNECTION Command
DELETE CONNECTION Command
DBGETPROP( ) Function
LIST CONNECTIONS Command
RENAME CONNECTION Command
Commands
Language Reference


DISPLAY DATABASE Command

Visual FoxPro 9.0 Language Reference
DISPLAY DATABASE Command
See Also Example

Displays information about the current database.

DISPLAY DATABASE [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]] [NOCONSOLE]

Parameters

[TO PRINTER [PROMPT]

Directs output about the current database to a printer. The PROMPT keyword clause displays a Print dialog box before printing starts.
TO FILE FileName [ADDITIVE]]

Directs output to a file specified by FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro prompts you to decide whether to overwrite the file. The ADDITIVE keyword appends output to the end of the specified file. If you omit ADDITIVE, the contents of the file are overwritten.
[NOCONSOLE]

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

To return additional information about the current database, use the DBGETPROP( ) function. For more information, see DBGETPROP( ) Function.

Example

The following example creates a database named people. A table named friends is created and is automatically added to the database. DISPLAY TABLES is used to display the tables in the database, and DISPLAY DATABASES is used to display information about the tables in the database.
Copy Code
CREATE DATABASE people
CREATE TABLE friends (FirstName C(20), LastName C(20))
CLEAR
DISPLAY TABLES  && Displays tables in the database
DISPLAY DATABASES  && Displays table information

See Also

Other Resources

DISPLAY Command
LIST DATABASE Command
DELETE DATABASE Command
DISPLAY FILES Command
Commands
Language Reference


DISPLAY DLLS Command

Visual FoxPro 9.0 Language Reference
DISPLAY DLLS Command
See Also

Displays information about shared library functions registered in Visual FoxPro with DECLARE – DLL.

DISPLAY DLLS [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]] [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs output from DISPLAY DLLS to a printer. In Visual FoxPro, you can include the optional PROMPT clause to display a Print dialog box before printing starts. Place PROMPT immediately after TO PRINTER.
TO FILE FileName

Directs output from DISPLAY DLLS to the file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

See Also

Other Resources

DISPLAY Command
DECLARE – DLL Command
LIST DLLS Command
DISPLAY FILES Command
Commands
Language Reference


DISPLAY FILES Command

Visual FoxPro 9.0 Language Reference
DISPLAY FILES Command
See Also Example

Displays information about files.

DISPLAY FILES [ON Drive] [LIKE FileSkeleton]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]

Parameters

ON Drive

Specifies the drive or volume on which the files reside.
LIKE FileSkeleton

Specifies a condition whereby Visual FoxPro displays information only about files that match the skeleton pattern FileSkeleton. The skeleton pattern can contain wildcards such as ? and *.
TO PRINTER [PROMPT]

Directs output from DISPLAY FILES to a printer. In Visual FoxPro, you can include the optional PROMPT clause to display a dialog box before printing starts. In this dialog box, you can adjust printer settings, including the number of copies and page numbers to print. The printer settings that you can adjust depend on the currently installed printer driver. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from DISPLAY FILES to the file specified with FileName. If the file already exists and SET SAFETY is ON, you are asked if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.

Remarks

Use DISPLAY FILES to display information about files residing on a disk. You can display information about all files on a specified drive, volume, directory, or folder, or only files that match a skeleton pattern containing wildcards such as ? and *.

Issuing DISPLAY FILES without any arguments displays information about tables in the current directory. The information displayed includes the following:

  • Table name.

  • Number of records in the table.

  • Date and time of the last update to the table.

  • The size of each table in bytes.

  • If each table is part of a database.

Example

The following example displays the names of the databases in the ...\Samples\Data directory.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')

CLEAR
DISPLAY FILES LIKE *.DBC

See Also

Other Resources

DISPLAY Command
DIR or DIRECTORY Command
LIST Command
DISPLAY DATABASE Command
Commands
Language Reference


DISPLAY MEMORY Command

Visual FoxPro 9.0 Language Reference
DISPLAY MEMORY Command
See Also Example

Displays the current contents of variables and arrays.

DISPLAY MEMORY [LIKE FileSkeleton]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]] [NOCONSOLE]

Parameters

[LIKE FileSkeleton]

Displays information about variables and arrays that match the skeleton pattern FileSkeleton. If you include LIKE FileSkeleton, Microsoft Visual FoxPro displays only the contents of variables and arrays that match FileSkeleton. FileSkeleton supports wildcards such as ? and *. For example, to display all variables that begin with the letter A, issue:
Copy Code
DISPLAY MEMORY LIKE A*
[TO PRINTER [PROMPT]

Directs output from DISPLAY MEMORY to a printer. You can include the optional PROMPT clause to display a dialog box before printing starts. In this dialog box, you can adjust printer settings, including the number of copies and page numbers to print. The printer settings that you can adjust depend on the currently installed printer driver. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName[ADDITIVE]]

Directs output from DISPLAY MEMORY to the file specified with FileName. If the file already exists and SET SAFETY is ON, you are prompted to overwrite the file. ADDITIVE specifies to append output to the end of the specified file. If you omit ADDITIVE, the file is overwritten with the value of the expression.
[NOCONSOLE]

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

DISPLAY MEMORY displays the name, type, contents, scope, and status of all currently defined variables and variable arrays. It includes the number of variables defined, the number of bytes used, and the number of additional variables available. DISPLAY MEMORY also displays information about system variables, menus, menu bars, menu titles, and windows.

Note:
The number of bytes used represents memory used by character type variables. Character type variables are the only type of variables that require additional memory beyond that allocated by the variable count specified with the MVCOUNT configuration item.

Example

In the following example, several variables are created and assigned values. DISPLAY MEMORY first displays all variables that begin with "sam" and then displays all variables that contain five letters and end with "exit."
Copy Code
STORE 'Goodbye' TO sample1
STORE 'Hello' TO sample2
STORE .T. TO texit
STORE .F. TO mexit

CLEAR
DISPLAY MEMORY LIKE sam*
DISPLAY MEMORY LIKE ?exit

See Also

Other Resources

DISPLAY Command
DECLARE Command
DIMENSION Command
LIST Command
STORE Command
Commands
Language Reference


DISPLAY OBJECTS Command

Visual FoxPro 9.0 Language Reference
DISPLAY OBJECTS Command
See Also Example

Displays information about an object or a group of objects.

DISPLAY OBJECTS [LIKE cObjectSkeleton]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]] [NOCONSOLE]

Parameters

LIKE cObjectSkeleton

Displays information about a subset of objects. cObjectSkeleton is an object specification skeleton that supports wildcards (* and ?). For example, to display all objects that begin with A, use the following command:
Copy Code
DISPLAY OBJECTS LIKE A*
TO PRINTER [PROMPT]

Directs output from DISPLAY OBJECTS to a printer. You can include the optional PROMPT clause to display a Print dialog box before printing starts. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from DISPLAY OBJECTS to the file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

DISPLAY OBJECTS displays the following information about all existing objects:

  • Properties and their values.

  • Methods.

  • Member objects and the class or subclass on which they are based.

  • Class or subclass on which objects are based.

  • Class hierarchy for the objects.

DISPLAY OBJECTS fills the entire main Visual FoxPro window or user-defined window with information and then pauses. Press any key or click anywhere to see the next set of information. DISPLAY is similar to LIST, except that LIST displays the same information in a continuous stream without pausing.

Example

The following example uses DEFINE CLASS and CREATEOBJECT( ) to create two custom classes named FormChild and FormGrandChild from the Visual FoxPro Form base class. DISPLAY OBJECTS displays information about the objects and their properties.
Copy Code
CLEAR
frmMyForm = CREATEOBJECT("FormGrandChild")
DISPLAY OBJECTS LIKE frm*
RELEASE frmMyForm

DEFINE CLASS FormChild AS FORM
ENDDEFINE

DEFINE CLASS FormGrandChild AS FormChild
ENDDEFINE

See Also

Reference

Image Control (Visual FoxPro)
OLE Bound Control
OLE Container Control

Other Resources

DISPLAY Command
LIST OBJECTS Command
DISPLAY MEMORY Command
Commands
Language Reference


DISPLAY PROCEDURES Command

Visual FoxPro 9.0 Language Reference
DISPLAY PROCEDURES Command
See Also Example

Displays the names of procedures stored in the current database.

DISPLAY PROCEDURES [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]
   [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs information returned from DISPLAY PROCEDURES to a printer. You can include PROMPT to display a Print dialog box before printing starts. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from DISPLAY PROCEDURES to the file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

Stored procedures are created with APPEND PROCEDURES, COPY PROCEDURES, or MODIFY PROCEDURE.

Example

The following example opens the testdata database, and uses DISPLAY PROCEDURES to display the stored procedures (if any) in the database. If there are no stored procedures in the database, you can run the example for the APPEND PROCEDURES topic to add a procedure to the database.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')

CLEAR
DISPLAY PROCEDURES  && Displays stored procedures in the database

See Also

Other Resources

DISPLAY Command
APPEND PROCEDURES Command
COPY PROCEDURES Command
CREATE DATABASE Command
DISPLAY DATABASE Command
LIST PROCEDURES Command
MODIFY PROCEDURE Command
Commands
Language Reference


DISPLAY STATUS Command

Visual FoxPro 9.0 Language Reference
DISPLAY STATUS Command
See Also

Displays the status of the Visual FoxPro environment.

DISPLAY STATUS [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]] [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs output from DISPLAY STATUS to a printer. You can include the optional PROMPT clause to display a print dialog box before printing starts. In this dialog box, you can adjust printer settings, including the number of copies and page numbers to print. The printer settings that you can adjust depend on the currently installed printer driver. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from DISPLAY STATUS to the file specified with FileName. If the file already exists and SET SAFETY is ON, you are asked if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

This form of DISPLAY lists information about the current Visual FoxPro environment. The categories of information and the information in each category are as follows.

Table and index file information:

  • Open tables

  • Open memo files

  • Table aliases

  • Table code pages

  • Table relations

  • Active indexes

  • Index file keys

  • The controlling index file or tag

  • Open structural compound files

  • Open compound index tags

  • The shared attribute status of each open table

  • The currently locked records in each table

  • The EXCLUSIVE use setting

  • The LOCK setting

  • The MULTILOCKS setting

  • The SET REFRESH value

  • The SET REPROCESS value

Open low-level file information:

  • Open low-level files

  • The file handle number for each low-level file

  • The file pointer position for each low-level file

  • Read/write attributes for each low-level file

Additional Visual FoxPro environment information:

  • The procedure file in use

  • The processor type

  • The Visual FoxPro path

  • The Visual FoxPro default directory

  • The print destination

  • The margin setting

  • The current work area

  • SET command settings

  • Binary modules currently loaded

  • DDE information in Visual FoxPro

  • Current code page

  • Current collating sequence

  • Compiler code page

  • Current date format

  • Keyboard macro key combination

  • How UDF parameters are passed

  • Textmerge options

  • External registered shared library functions (DLLs)

See Also

Other Resources

DISPLAY Command
LIST Command
DISPLAY STRUCTURE Command
DISPLAY PROCEDURES Command
Commands
Language Reference


DISPLAY STRUCTURE Command

Visual FoxPro 9.0 Language Reference
DISPLAY STRUCTURE Command
See Also Example

Displays the structure of a table file. The name of each field in the table is displayed with its type and width.

DISPLAY STRUCTURE [IN nWorkArea | cTableAlias]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]] [NOCONSOLE]

Parameters

IN nWorkArea | cTableAlias

Displays the structure of the table in a work area other than the current work areas. nWorkArea specifies the work area number and cTableAlias specifies the table alias.
TO PRINTER [PROMPT]

Directs output from DISPLAY STRUCTURE to a printer. You can include the optional PROMPT clause to display a dialog box before printing starts. In this dialog box, you can adjust printer settings, including the number of copies and page numbers to print. The printer settings that you can adjust depend on the currently installed printer driver. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from DISPLAY STRUCTURE to the file specified with FileName. If the file already exists and SET SAFETY is ON, you are asked if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

DISPLAY STRUCTURE also displays the following:

  • The total width of all fields.

  • The number of decimal places in the field if the field has Numeric, Double, or Float type.

  • Null value support for each field.

  • If the field is an autoincrementing field, the Next and Step values in the last two columns.

  • The current number of records in the table and the date it was last updated.

  • The memo field block size if the table has an associated memo field.

  • The code page of the table.

  • If the table is associated with a structural compound index, and if a tag, or index entry, in the structural compound index has the same name as a field in the table, DISPLAY STRUCTURE displays the order of the tag, ascending or descending, and the collation sequence for the tag next to the field name. For more information about structural compound indexes and tags, see INDEX Command.

If the SET FIELDS is used to limit access to fields in the table, an angle bracket (>) appears beside the names of fields that can be accessed.

Example

In the following example, the customer table in the testdata database is opened. DISPLAY STRUCTURE is used to display the table structure.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

CLEAR
DISPLAY STRUCTURE

See Also

Other Resources

DISPLAY Command
LIST Command
DISPLAY TABLES Command
DISPLAY STATUS Command
Commands
Language Reference


DISPLAY TABLES Command

Visual FoxPro 9.0 Language Reference
DISPLAY TABLES Command
See Also Example

Displays names and information about all the tables contained in the current database.

DISPLAY TABLES [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]] [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs output from DISPLAY TABLES to a printer. You can include PROMPT to display a Print dialog box before printing starts. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from DISPLAY TABLES to the file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

The information returned is a subset of the information shown using DISPLAY STATUS. However, the information displayed using DISPLAY TABLES contains only table-related information and displays the information regardless of whether the tables are open or not.

The following information is displayed:

  • Table name

  • Table path

Example

The following example opens the customer table in the testdata database. DISPLAY TABLES is used to display information about the tables in the database.
Copy Code
CLOSE DATABASES
SET PATH TO (HOME(2) + 'Data\')   && Sets path to database
OPEN DATABASE testdata  && Open testdata database

CLEAR
DISPLAY TABLES  && Displays information about tables in the database

See Also

Other Resources

DISPLAY Command
ADD TABLE Command
CLOSE DATABASES Command
CREATE DATABASE Command
LIST TABLES Command
OPEN DATABASE Command
REMOVE TABLE Command
Commands
Language Reference


DISPLAY VIEWS Command

Visual FoxPro 9.0 Language Reference
DISPLAY VIEWS Command
See Also Example

Displays information about SQL views in the current database and indicates whether the SQL views are based on local or remote tables.

DISPLAY VIEWS [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]] [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs output from DISPLAY VIEWS to a printer. You can include PROMPT to display the Print dialog box before printing starts. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from DISPLAY VIEWS to the file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

Use DBGETPROP( ) to return additional information about SQL views in the current database.

SQL views are created with CREATE SQL VIEW.

Example

The following example opens the testdata database. CREATE SQL VIEW is used to create a local SQL view named myview. The View Designer is displayed, making it possible for you to specify tables and conditions for the SQL view. After you save the SQL view you create, information about the SQL views in the database is displayed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
CREATE SQL VIEW myview

CLEAR
DISPLAY VIEWS

See Also

Other Resources

DISPLAY Command
CREATE DATABASE Command
CREATE SQL VIEW Command
DBGETPROP( ) Function
DISPLAY DATABASE Command
LIST VIEWS Command
Commands
Language Reference


DO CASE ... ENDCASE Command

Visual FoxPro 9.0 Language Reference
DO CASE ... ENDCASE Command
See Also Example

Executes the first set of commands whose conditional expression evaluates to true (.T.).

DO CASE
   CASE lExpression1
   [Commands]
   [CASE lExpression2
   [Commands]]
   ...
   [CASE lExpressionN
   [Commands]]
   [OTHERWISE
   [Commands]]
ENDCASE

Parameters

CASE lExpression1 Commands...

When the first true (.T.) CASE expression is encountered, the set of commands following it is executed. Execution of the set of commands continues until the next CASE or ENDCASE is reached. Execution then resumes with the first command following ENDCASE. If a CASE expression is false (.F.), the set of commands following it up to the next CASE clause is ignored. Only one set of commands is executed. These are the first commands whose CASE expression evaluates to true (.T.). Any succeeding true (.T.) CASE expressions are ignored.
OTHERWISE Commands

If all of the CASE expressions evaluate to false (.F.), OTHERWISE determines if an additional set of commands is executed.
  • If you include OTHERWISE, the commands following OTHERWISE are executed and execution skips to the first command following ENDCASE.

  • If you omit OTHERWISE, execution skips to the first command following ENDCASE.

Remarks

DO CASE is used to execute a set of Visual FoxPro commands based on the value of a logical expression. When DO CASE is executed, successive logical expressions are evaluated; the values of the expressions determine which set of commands is executed.

Comments can be placed after DO CASE and ENDCASE on the same line. The comments are ignored during program compilation and execution.

Example

In this example, Visual FoxPro evaluates each CASE clause until the MONTH variable is found in one of the lists. The appropriate string is stored to the variable rpt_title and the DO CASE structure is exited.
Copy Code
STORE CMONTH(DATE( )) TO month  && The month today

DO CASE  && Begins loop

   CASE INLIST(month,'January','February','March')
      STORE 'First Quarter Earnings' TO rpt_title

   CASE INLIST(month,'April','May','June')
      STORE 'Second Quarter Earnings' TO rpt_title

   CASE INLIST(month,'July','August','September')
      STORE 'Third Quarter Earnings' TO rpt_title

   OTHERWISE
      STORE 'Fourth Quarter Earnings' TO rpt_title
ENDCASE  && Ends loop
WAIT WINDOW rpt_title NOWAIT

See Also

Other Resources

DO WHILE ... ENDDO Command
EXIT Command
FOR EACH ... ENDFOR Command
FOR ... ENDFOR Command
IF ... ENDIF Command
IIF( ) Function
SCAN ... ENDSCAN Command
Commands
Language Reference


DO Command

Visual FoxPro 9.0 Language Reference
DO Command
See Also

Executes a Visual FoxPro program or procedure.

Tip:
You can execute a program that executes another program that executes another program and so on by including additional nested DO commands in a program file. For more information about program nesting levels, see Visual FoxPro System Capacities.

DO ProgramName1 | ProcedureName [IN ProgramName2] [WITH ParameterList]

Parameters

ProgramName1

Specifies the name of the program to execute. If you do not include an extension with the program you execute, Visual FoxPro looks for and executes versions of the program in the following order:
  • Executable (.exe)

  • Application (.app)

  • Compiled (.fxp)

  • Program (.prg)

To execute a specific menu program, form program, or query using the DO command, you must include the file extension (.mpr, .spr, or .qpr).
ProcedureName

Specifies the name of the procedure to execute. Visual FoxPro first looks for the procedure in the currently executing program. If the procedure is not located there, Visual FoxPro then looks for the procedure in the procedure files opened with SETPROCEDURE. You can include the IN ProgramName2 clause to tell Visual FoxPro to look for the procedure in a file you specify. Multiple procedures within an executable (.exe) version or an application (.app) can have the same name. When you use the DO command to start a procedure in an executable version or in an application, Visual FoxPro searches only the main program of the executable version or application for the specified procedure.
IN ProgramName2

Executes a procedure in the program file specified with ProgramName2. When the file is located, the procedure is executed. If the program file cannot be located, the message "File does not exist" appears. If the program file is located but the specified procedure isn't in the program file, the message "Procedure is not found" appears.
WITH ParameterList

Specifies parameters to pass to the program or procedure. The parameters listed in ParameterList can be expressions, memory variables, literals, fields, or user-defined functions. By default, parameters are passed to programs and procedures by reference. You can pass a parameter by value by placing it in parentheses. See SET UDFPARMS for a discussion of passing parameters by value or reference. The maximum number of parameters you can pass to a program or procedure is 26. For more information on parameter passing, see LPARAMETERS and PARAMETERS.

Remarks

When you use DO to run a program, the commands contained in the program file are executed until one of the following occurs:

  • RETURN is encountered.

  • CANCEL is executed.

  • Another DO is issued.

  • The end of the file is reached.

  • QUIT is executed.

When program execution is complete, control is returned to one of the following:

  • Program that called DO

  • Command window

  • Operating system

If you choose Do from the Program menu and execute a program in a directory on a drive other than the current directory or drive, Visual FoxPro automatically changes the default directory and drive to the directory and drive containing the program.

You can also modify how an application searches for data and resources such as functions, procedures, executable files, and so on using SYS(2450) - Application Search Path Order.

See Also

Other Resources

CLEAR Command
LPARAMETERS Command
PARAMETERS Command
PARAMETERS( ) Function
PRIVATE Command
PROCEDURE Command
PUBLIC Command
SET DEFAULT Command
SET DEVELOPMENT Command
SET PATH Command
SET PROCEDURE Command
Commands
Language Reference


DO FORM Command

Visual FoxPro 9.0 Language Reference
DO FORM Command
See Also Example

Runs a compiled form or form set created with the Form Designer.

DO FORM FormName | ? [NAME VarName [LINKED]] [WITH cParameterList]
   [TO VarName] [NOREAD] [NOSHOW]

Parameters

FormName

Specifies the name of the form or form set to run.
?

Displays the Do dialog box from which you can choose a form or form set to run.
NAME VarName [LINKED]

Specifies a variable or array element with which you can reference the form or form set. If you specify a variable that doesn't exist, Microsoft Visual FoxPro automatically creates it. If you specify an array element, the array must exist before you issue DO FORM. If the variable or array element you specify already exists, its contents are overwritten. If you omit the NAME clause, Visual FoxPro creates an object type variable with the same name as the form or form set file. Include LINKED to link the form to the variable associated with it so that the form is released when the variable goes out of scope. If you don't include LINKED, a form can still be active, even though there is no object variable associated with the form.
WITH cParameterList

Specifies the parameters passed to the form or form set. If a form set is run, the parameters are passed to the form set's Init method if the form set's WindowType property is set to ModeLess (0) or Modal (1). The parameters are passed to the Load method if the form set's WindowType property is set to Read (2) or ReadModal (3).
TO VarName

Specifies a variable to hold a value returned from the form. If the variable doesn't exist, Visual FoxPro automatically creates it. Use the RETURN command in the Unload event procedure of the form to specify the return value. If you do not include a return value, the default value of true (.T.) is returned. If you use TO, the WindowType property of the form must be set to 1 (Modal). If the form Init event procedure returns .F., preventing the form from being instantiated, the Unload event procedure will not return a value to VarName.
NOREAD

Specifies that the form set is created and displayed, even though controls are not activated until READ is issued. NOREAD is ignored if the form set object's WindowType property is not set to 2 (Read).
NOSHOW

Specifies that the form's Show method isn't called when the form is run. When you include NOSHOW and run the form, the form is not visible until the form's Visible property is set to true (.T.) or the form's Show method is called.

Remarks

DO FORM executes the Show method for the form or form set.

The WindowType property settings of Read (2) or ReadModal (3) are included for backward compatibility, and are available only for forms converted from previous versions of FoxPro.

Example

The following example runs the stop watch (Swatch.scx) control sample.
Copy Code
DO FORM (HOME(2) + 'Solution\Controls\Timer\Swatch.scx')

See Also

Other Resources

Commands
COMPILE Command
CREATE FORM Command
MODIFY FORM Command


DO WHILE ... ENDDO Command

Visual FoxPro 9.0 Language Reference
DO WHILE ... ENDDO Command
See Also Example

Executes a set of commands within a conditional loop.

DO WHILE lExpression
      Commands
   [LOOP]
   [EXIT]
ENDDO

Parameters

lExpression

Specifies a logical expression whose value determines whether the commands between DO WHILE and ENDDO are executed. As long as lExpression evaluates to true (.T.), the set of commands are executed.
Commands

Specifies the set of Visual FoxPro commands to be executed as long as lExpression evaluates to true (.T.).
LOOP

Returns program control directly back to DO WHILE. LOOP can be placed anywhere between DO WHILE and ENDDO.
EXIT

Transfers program control from within the DO WHILE loop to the first command following ENDDO. EXIT can be placed anywhere between DO WHILE and ENDDO.

Remarks

Commands between DO WHILE and ENDDO are executed for as long as the logical expression lExpression remains true (.T.). Each DO WHILE statement must have a corresponding ENDDO statement.

Comments can be placed after DO WHILE and ENDDO on the same line. The comments are ignored during program compilation and execution.

Example

In the following example, the number of products in stock priced over $20 is totaled in the DO WHILE loop until the end of the file (EOF) is encountered. The DO WHILE loop is exited and the total is displayed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE products  && Opens Products table
SET TALK OFF
gnStockTot = 0

DO WHILE .T.  && Begins loop
   IF EOF( )
      EXIT
   ENDIF
   IF unit_price < 20
      SKIP
      LOOP
   ENDIF
   gnStockTot = gnStockTot + in_stock
   SKIP
ENDDO     && Ends loop

CLEAR
? 'Total items in stock valued over 20 dollars:'
?? gnStockTot

See Also

Other Resources

DO CASE ... ENDCASE Command
FOR EACH ... ENDFOR Command
FOR ... ENDFOR Command
IF ... ENDIF Command
IIF( ) Function
Commands
Language Reference
SCAN ... ENDSCAN Command


DOCK Command

Visual FoxPro 9.0 Language Reference
DOCK Command
See Also Example

Docks an Integrated Development Environment (IDE) tool window or toolbar to the Visual FoxPro desktop window or another IDE window. There are two versions of the syntax.

Note:
DOCK WINDOW is not supported during run time.

DOCK WINDOW WindowName1 | NAME ObjectName1 POSITION nPosition [ WINDOW WindowName2 | NAME ObjectName2 ]
DOCK WINDOW WindowName1 WINDOW WindowName2

Parameters

WindowName1

Specifies the name of the window or toolbar to dock. For a user-defined toolbar, you can use the Caption property as its name. If you specify an undockable window as the window to be docked, it becomes dockable internally. For example:
Copy Code
WDOCKABLE("Command", .F.)
DOCK WINDOW Command
? WDOCKABLE("Command")  && Returns .T.
If you want to dock a single window that is currently bound inside a tabbed or linked container to the main Visual FoxPro window, you must first undock it from the container, for example, by using POSITION -1 or WDOCKABLE(, .F. ). A tabbed or linked container is a set of tabbed or linked windows.
NAME ObjectName1

Specifies an object reference for a valid dockable form to dock. If ObjectName1 is docked, Visual FoxPro undocks and redocks it as specified.
Note:
If ObjectName1 is undefined or not valid, Visual FoxPro generates an error.

POSITION nPosition

Specifies the docking position of the window or toolbar. The following table lists the possible values for nPosition.

nPosition Docking position

-3

Undock inner container.

-2

Undock outer container.

-1

Undock window.

Note:
When you specify a value of -1 for POSITION, you cannot include the WINDOW clause. Otherwise, a syntax error occurs.

0

Top

1

Left

2

Right

3

Bottom

If nPosition is set between 0 and 3, the window is link-docked, for example, it appears attached to the side of another window.

4

Tabbed

If nPosition is set to 4, the window is tab-docked, for example, it appears as a tabbed window.

Note:
If you specify a value of 4 for POSITION, you must specify a WINDOW clause. Otherwise, an error occurs.
Note:
Tab and link docking is not supported for debugger windows inside the Debug Frame. You can control the Frame setting in the Options dialog box. Toolbars do not support linked or tabbed docking.

If a tabbed or linked container is docked, you can undock that container if you specify a value of -2 or -3 for any of the windows in the container, according to the following details:
  • If you pass a value of -2, the entire container is undocked if the container is docked to the Visual FoxPro desktop.

  • If you pass a value of -3, only the inner container that is part of an larger outer container is undocked. This applies only to tab-docked containers bound inside link-docked containers. If the window specified is not part of an inner tab-docked container, Visual FoxPro treats the value of -3 as a value of -2 and undocks entire outer container.

  • If the window specified is not part of a container, Visual FoxPro undocks it as if you passed a value of -1.

If the window or container is already undocked, Visual FoxPro does nothing. For more information about linked and tabbed docking, see How to: Dock Windows.
WINDOW WindowName2

Specifies the name of the target window or toolbar to dock with. If you omit the WindowName2 parameter, the window is docked to the Visual FoxPro desktop window.
Note:
Visual FoxPro disregards the WINDOW keyword for toolbars. You can dock toolbars only to the desktop. No other window can be docked to a toolbar.

You can use the WINDOW clause for linked and tabbed docking. DOCK WINDOW uses a tab-docking position as the default if you use DOCK WINDOW...WINDOW without including a POSITION clause. To dock an entire tabbed or linked container to the Visual FoxPro desktop window, call DOCK WINDOW with any of the windows in the container and omit the WINDOW clause. If you specify an undockable window as the docking target, Visual FoxPro generates "Function argument value, type, or count is invalid (Error 11)". For example:
Copy Code
DOCK WINDOW Command WINDOW Standard   && Generates an error.
NAME ObjectName2

Specifies an object reference for a valid dockable form to dock with. If ObjectName2 is docked, Visual FoxPro undocks and redocks it as specified.
Note:
If ObjectName2 is undefined or not valid, Visual FoxPro generates an error.

Remarks

The following IDE windows and toolbars are supported by DOCK WINDOW:

  • All system toolbars

  • Call Stack

  • Command

  • Data Session (View)

  • Document View

  • Locals

  • Output

  • Properties

  • Trace

  • Watch

Both system and user-defined toolbars are supported by DOCK WINDOW.

Note:
The specified window must first exist on the Visual FoxPro desktop; otherwise, an error occurs.

In prior versions of Visual FoxPro, the Data Session window is always referred to as the View window. Additionally, language used to control this window, such as HIDE WINDOW, ACTIVATE WINDOW, WONTOP( ), also refers to this window as the View window. Visual FoxPro continues to refer to the View window for the DOCK WINDOW command.

DOCK WINDOW always forces the window, if it exists, to become dockable and changes the setting for the Visible property of the window to True (.T.).

You can dock multiple windows that are docked as a group to another window by specifying one of the docked windows. However, if the docking target exists in the same container as the specified window, only that window is docked. This prevents cyclical relations. For example, the following code redocks the Command window to the right side of the Properties window:

Copy Code
DOCK WINDOW Command POSITION 4 WINDOW Properties
DOCK WINDOW Command POSITION 2 WINDOW Properties

Compare this example to the following code, which docks the Command and View windows to the Properties window as tabbed windows:

Copy Code
DOCK WINDOW Command POSITION 4 WINDOW View
DOCK WINDOW Command POSITION 4 WINDOW Properties
Tip:
Deleting or editing the FoxUser.dbf resource file, which contains your user settings, restores your default window settings.

Example

The following example uses the DOCK WINDOW command to dock the Command window to the Visual FoxPro desktop window and uses ADOCKSTATE( ) to obtain the dock state of the Command window.

First, make sure the Command window is open. After docking the Command window, you can see that the Standard toolbar and Command windows are docked to the Microsoft Visual FoxPro desktop window. The position of the toolbars or windows in the array returned by ADOCKSTATE( ) can vary depending on the order in which the toolbars or windows are docked.

Copy Code
CLEAR
DOCK WINDOW Command POSITION 0
dockNum = ADOCKSTATE(dockState)
? dockNum   && Returns 2 only if Command window and
            && Standard toolbar exist.
? dockState(1,1)  && Outputs "Standard".
? dockState(1,4)  && Outputs "Microsoft Visual FoxPro".
? dockState(2,1)  && Outputs "COMMAND".
? dockState(2,4)  && Outputs "Microsoft Visual FoxPro".

See Also

Other Resources

ADOCKSTATE( ) Function
WDOCKABLE( ) Function
Dock Method
DockPosition Property
Docked Property
BeforeDock Event
AfterDock Event
UnDock Event


DOEVENTS Command

Visual FoxPro 9.0 Language Reference
DOEVENTS Command
See Also

Executes all pending Windows events.

Note:
You cannot call DOEVENTS using parentheses (()), for example, "DOEVENTS( )".

You can use DOEVENTS for simple tasks such as making it possible for the user to cancel a process after it starts, for example, searching for a file. Long-running processes that yield control of the processor are better performed using a Timer control or delegating the task to a COM Server executable (.exe). In this situation, the task can continue independently of your application, and the operating system takes care of multitasking and time allocation.

Caution:
Any time you temporarily yield control of the processor in an event procedure, make sure the procedure is not run again from a different part of code before the first call ends. Doing so might cause unpredictable results. In addition, do not use DOEVENTS if other applications might interact with your procedure in unforeseen ways during the time you have yielded control of the processor.

DOEVENTS [FORCE]

Parameters

FORCE

Pauses Visual FoxPro code execution until a Windows event occurs, such as moving the mouse.
Note:
Using the FORCE keyword can impact performance. Therefore, use caution when calling DOEVENTS FORCE in a tight code loop, such as a DO WHILE loop.

Remarks

When the AutoYield property is set to False (.F.), and program code is executing, Window events are placed in a queue. DOEVENTS executes all pending Windows events and processes any user code associated with the Windows events. If no events are in the queue, Visual FoxPro disregards DOEVENTS and continues program execution.

See Also

Other Resources

AutoYield Property
Events
Commands
Language Reference


DROP TABLE Command

Visual FoxPro 9.0 Language Reference
DROP TABLE Command
See Also

Removes a table from the current database and deletes it from disk.

DROP TABLE TableName | FileName | ? [RECYCLE]

Return Value

TableName

Specifies the table to remove from the current database and delete from disk.
FileName

Specifies a free table to delete from disk.
?

Displays the Remove dialog from which you can choose a table to remove from the current database and delete from disk.
RECYCLE

Specifies that the table isn't immediately deleted from disk and is placed in the Microsoft Windows Recycle Bin.

Remarks

When DROP TABLE is issued, all primary indexes, default values, and validation rules associated with the table are also removed. DROP TABLE also affects other tables in the current database if those tables have rules or relations associated with the table being removed. The rules and relations are no longer valid when the table is removed from the database.

Any table deleted with this command cannot be retrieved. Even if SET SAFETY is set to ON, you are not warned before the table is deleted.

See Also

Other Resources

ADD TABLE Command
CLOSE DATABASES Command
CREATE DATABASE Command
FREE TABLE Command
OPEN DATABASE Command
Commands
Language Reference


DROP VIEW Command

Visual FoxPro 9.0 Language Reference
DROP VIEW Command
See Also

Deletes a SQL view from the current database.

DROP VIEW ViewName

Return Value

ViewName

Specifies the name of the view deleted from the current database.

Remarks

DROP VIEW is identical to DELETE VIEW; DROP VIEW is the ANSI SQL standard syntax for deleting a SQL view.

Use CREATE SQL VIEW to create a SQL view and add the view to the current database. If a SQL view is opened and then deleted, the cursors containing the SQL view results are not closed.

See Also

Other Resources

CREATE SQL VIEW Command
DELETE VIEW Command
OPEN DATABASE Command
Commands
Language Reference


EDIT Command

Visual FoxPro 9.0 Language Reference
EDIT Command
See Also Example

Displays fields for editing.

EDIT [FIELDS FieldList] [Scope] [FOR lExpression1] [WHILE lExpression2]
   [FONT cFontName[, nFontSize [, nFontCharSet]]] [STYLE cFontStyle] [FREEZE FieldName]
   [KEY eExpression1[, eExpression2]] [LAST | NOINIT] [LPARTITION]
   [NAME ObjectName] [NOAPPEND] [NOCAPTION] [NODELETE] [NOEDIT | NOMODIFY]
   [NOLINK] [NOMENU] [NOOPTIMIZE] [NORMAL] [NOWAIT]
   [PARTITION nColumnNumber [LEDIT] [REDIT]]
   [PREFERENCE PreferenceName] [REST] [SAVE] [TIMEOUT nSeconds]
   [TITLE cTitleText] [VALID [:F] lExpression3 [ERROR cMessageText]]
   [WHEN lExpression4] [WIDTH nFieldWidth] [WINDOW WindowName1]
   [IN [WINDOW] WindowName2 | IN SCREEN [COLOR SCHEME nSchemeNumber]

Parameters

FIELDS FieldList

Specifies the fields that appear in the Edit window. The fields are displayed in the order specified in FieldList. You can include fields from other related tables in the field list. When you include a field from a related table, preface the field name with its table alias and a period. If you omit FIELDS, all fields in the table are displayed in the order they appear in the table structure. The field list can specify any combination of fields or calculated fields, including fields from tables open in other work areas. The syntax of the field list is:
Copy Code
FieldName1
   [:R]
   [:nColumnWidth]
   [:V = lExpression1 [:F] [:E = cMessageText]]
   [:P = cFormatCodes]
   [:B = eLowerBound, eUpperBound [:F]]
   [:H = cHeadingText]
   [:W = lExpression2]
   [, FieldName2 [:R]...]

Calculated Fields

The field list can contain statements for creating calculated fields. A calculated field contains read-only data created with an expression. This expression may take any form but it must be a valid Visual FoxPro expression.

The syntax of the statement you use to create a calculated field is:

CalculatedFieldName = eExpression

This example creates a calculated field called location:

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
EDIT FIELDS location = ALLTRIM(city) + ', ' + country

The FIELDS clause field list includes eight options, which enable special handling of fields displayed in the Edit window.

: nColumnWidth

Specifies the display size for a field in columns. The value of :nColumnWidth doesn't affect the size of the field in the table; it alters only the way the field appears in the Edit window.
:R

In the following example, an Edit window is opened with the cust_id and company fields. The cust_id field is read-only and cannot be changed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
EDIT FIELDS cust_id:R, company
:V = lExpression1

Specifies a verify option that performs field-level data validation within the Edit window. If lExpression1 evaluates to true (.T.) when you move the cursor from the field, the data input into the field is considered correct and the cursor moves to the next field. If lExpression1 evaluates to false (.F.), the data input is considered incorrect, the cursor remains in the field and an error or exception is raised. If lExpression1 evaluates to 0, the data input is considered incorrect and the cursor remains in the field, but no error message is displayed. By default, lExpression1 is evaluated only when the field is modified. To force verification, include the :F option. You can display your own error message by including the :E option. The verify option isn't executed for memo fields.
:F

Specifies a forced validation option that determines if the expression in the verify option (lExpression1) is evaluated when you move the cursor from a field or another window is activated. If :F is not included, lExpression1 is evaluated only if changes are made to the field. If :F is included, lExpression1 is evaluated, even if the field isn't modified.
:E = cMessageText

Displays an error message specified with cMessageText instead of the default system message. If the validation expression :V = lExpression1 evaluates to true (.T.), the cursor leaves the field normally. If the expression evaluates to false (.F.), the cursor remains in the field and the error message appears. If the validation expression :V = lExpression1 evaluates to 0, no message is displayed and the cursor remains in the field being validated. This lets you display your own error messages in validation routines. The error message is displayed only if SET NOTIFY is ON. The bell is sounded if SET BELL is ON. The following example opens the products table and displays the product_id and prod_name fields. Enter a value greater than 100 in the product_id field to perform the field validation. :V specifies the validation criteria. :F forces the validation check to be performed whether the data is changed or not. :E replaces the Visual FoxPro system error message with a user-defined error message. In Visual FoxPro, the error message is displayed in the status bar at the bottom of the main Visual FoxPro window. Press ESC to close the Edit window.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
IF _WINDOWS OR _MAC
   SET STATUS BAR ON
ENDIF
USE products
EDIT FIELDS in_stock :V = in_stock < 100 ;
   :F ;
   :E = 'The stock amount must be less than 100'
:P = cFormatCodes

Specifies a picture option that lets you create an editing template specified with cFormatCodes that controls the display and input of data for each field in an Edit window. For more information on using picture editing codes, see the Format and InputMask properties. The following example uses the picture option to allow only numeric data in a specific format to be entered in the unit_price field:
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
EDIT FIELDS unit_price :P = '99,999.99'
:B = eLowerBound, eUpperBound[:F]

Specifies a set of boundaries between which data must fall. The boundary expressions eLowerBound and eUpperBound must match the data type of the field and cannot be the names of user-defined functions. If the data entered doesn't fall between eLowerBound and eUpperBound, a system message is displayed indicating the range between which the data must fall. By default, the data you enter is checked against the boundary values only if you make a change to the contents of the field. To force checking against the boundary values, include the forced validation option (:F). The following example ensures that the value in the in_stock field is between 1 and 100. Press ESC to close the Edit window.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
EDIT FIELDS in_stock :B = 1, 100 :F
:H = cHeadingText

Specifies a heading option (:H) that allows you to replace the default field names with your own headings, which you specify with cHeadingText. By default, field names are placed to the left side of the fields in the Edit window. The following example provides user-defined headings for the displayed fields.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
EDIT FIELDS prod_name :H = 'Product Name:', ;
   unit_price :H = 'Price per Unit:'
:W = lExpression2

Specifies a WHEN option that allows you to conditionally prohibit the cursor from being moved to a field based on the value of the logical expression lExpression. (:W) evaluates lExpression. If lExpression2 evaluates to false (.F.), you can't move the cursor to the field. If lExpression2 evaluates to true (.T.), you can move the cursor to the field. User-defined functions are supported in lExpression2. Moving the cursor to all fields is prohibited if the current field is marked read-only. This occurs only when every field contains a WHEN clause that evaluates to false.
Scope

Specifies a range of records that are displayed in the Edit window. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. Commands that include Scope operate only on the table in the active work area. The default scope for EDIT is ALL records. For more information, see the Scope Clauses online topic.
FOR lExpression1

Specifies that only the records that satisfy the logical condition lExpression1 are displayed in the Edit window. Using this argument allows you to filter out undesired records. Rushmore Query Optimization optimizes an EDIT FOR query if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies a condition whereby records are displayed in the Edit window for as long as the logical expression lExpression2 evaluates to true (.T.).
FONT cFontName[, nFontSize [, nFontCharSet]]

Specifies the Edit window's font and font size. The character expression cFontName specifies the name of the font, and the numeric expression nFontSize specifies the font size. You can specify a language script with nFontCharSet. See the GETFONT( ) Function for a list of available language script values. For example, the following clause specifies 16-point Courier font for the fields displayed in an Edit window:
Copy Code
FONT 'Courier',16
If you include the FONT clause but omit the font size nFontSize, a 10-point font is used in the Edit window. If you omit the FONT clause, 8-point MS Sans Serif is used. If the font you specify is not available, a font with similar font characteristics is substituted.
STYLE cFontStyle

Specifies the Edit window's font style in Visual FoxPro. If you omit the STYLE clause, the Normal font style is used. If the font style you specify is not available, a font style with similar characteristics is substituted.

Character Font style

B

Bold

I

Italic

N

Normal

O

Outline

Q

Opaque

S

Shadow

-

Strikeout

T

Transparent

U

Underline
You can include more than one character to specify a combination of font styles. The following example opens an Edit window and uses an underlined font:
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Opens customer table
IF _WINDOWS
   EDIT FIELDS contact FONT 'System', 15  STYLE 'NU'
ENDIF
IF _MAC
   EDIT FIELDS contact FONT 'Geneva', 14  STYLE 'NU'
ENDIF
FREEZE FieldName

Allows changes to be made to only one field specified with FieldName in the Edit window. The remaining fields are displayed and cannot be edited.
KEY eExpression1[, eExpression2]

Limits the scope of records that are displayed in the Edit window. With KEY, you can specify an index key value (eExpression1) or a range of key values (eExpression1 , eExpression2) for the records displayed in the Edit window. The table must be indexed, and the index key value or values included in the KEY clause must be the same data type as the index expression of the master index file or master tag. In the following example, only records with postal codes falling within the range of 10,000 to 30,000 are displayed in the Edit window:
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
SET ORDER TO postalcode
EDIT KEY '10000', '30000'
LAST | NOINIT

Saves any configuration changes made to the appearance of an Edit window. The changes are saved in the FoxUser.dbf file and can include changes to the field list, the size of each field, and the location and size of the Edit window. For more information on this file, see SET RESOURCE. If you issue EDIT with the LAST clause, the Edit window opens in the same configuration that was last saved in the FoxUser.dbf file. This restores the previous Edit window configuration created with the last EDIT. If the last EDIT command issued in the Command window included a long list of clauses, issue EDIT LAST to avoid having to retype the command. Any Edit window configuration changes you make in the current session aren't saved if you exit EDIT by pressing CTRL+Q.
LPARTITION

Places the cursor in the first field in the left partition of the Edit window. An Edit window can be split into left and right partitions by including the PARTITION clause. By default, the cursor is placed in the first field in the right partition when the Edit window is opened. The cursor is placed in the right partition of the Edit window if you include LPARTITION without the PARTITION clause.
NAME ObjectName

Creates an object reference for the Edit window, allowing you to manipulate the Edit window with object-oriented properties available for the Grid control. For additional information about object-oriented programming in Visual FoxPro, see Object-Oriented Programming. For additional information about the Grid control properties that you can specify for an Edit window created with the NAME clause, see the Grid Control topic.
NOAPPEND

Prevents the user from adding records to the table by pressing CTRL+Y or choosing Append Mode from the View menu.
Note:
Including NOAPPEND doesn't prevent you from appending a record from within a routine (created with VALID, WHEN, or ON KEY LABEL) while in the Edit window.

NOCAPTION

Specifies to always use the field name of a table or view for the column headers, even when the database contains a friendly caption for the table. This clause applies only to tables or views in a database.
NODELETE

Prevents records from being marked for deletion from within an Edit window. By default, a record can be marked for deletion by pressing CTRL+T, choosing Toggle Deletion Mark from the Table menu or clicking in the leftmost column of the record to be deleted.
Note:
Including NODELETE doesn't prevent you from marking a record for deletion from within a routine (created with VALID, WHEN or ON KEY LABEL) while in the Edit window.

NOEDIT | NOMODIFY

Prevents a user from modifying the table. NOEDIT and NOMODIFY are identical. If you include either clause, you can browse or search the table, but you cannot edit it. However, you can append and delete records.
NOLINK

Unlinks partitions in the Edit window. By default, the left and right partitions of the Edit window are linked; when you scroll through one partition, the other partition scrolls.
NOMENU

Removes the Table menu title in Visual FoxPro from the system menu bar, preventing access to the Edit menu.
NOOPTIMIZE

Disables Rushmore Query Optimization of EDIT. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access .
NORMAL

Opens the Edit window with its normal default settings, such as its colors, size, position, title, and control options (GROW, FLOAT, ZOOM, and so on). If you omit NORMAL and the current output window is a user-defined window with its own settings, the Edit window assumes those user-defined settings as well.
NOWAIT

Continues program execution immediately after the Edit window is opened. The program doesn't wait for the Edit window to be closed but continues executing on the program line immediately following the program line containing EDIT NOWAIT. If you omit NOWAIT, when EDIT is issued from within a program, an Edit window is opened and program execution pauses until the Edit window is closed. NOWAIT is available only from within a program. Including NOWAIT when issuing EDIT from the Command window has no effect.
PARTITION nColumnNumber

Splits an Edit window into left and right partitions with nColumnNumber specifying the column number of the split bar. For example, if nColumnNumber is 20, the split bar is placed in column 20 of the Edit window.
LEDIT

Specifies that the left partition of the Edit window appears in Browse mode.
REDIT

Specifies that the right partition of the Edit window appears in Browse mode. The following examples opens an Edit window with the split bar placed in column 20 and the right partition open in Browse mode. Include both keywords to open both partitions in Browse mode.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Opens customer table

EDIT PARTITION 30 REDIT
PREFERENCE PreferenceName

Saves an Edit window's attributes and options for later use. Unlike LAST, which restores the Edit window as it appeared in the previous session, PREFERENCE saves an Edit window's attributes indefinitely in the FoxUser.dbf resource file. Preferences can be retrieved at any time. For more information about the FoxUser.dbf resource file, see SET RESOURCE. Issuing EDIT with the specified preference name PreferenceName for the first time creates an entry in the FoxUser.dbf file that saves the Edit window configuration. Issuing EDIT later with the same preference name restores the Edit window to that preference state. When the Edit window is closed, the preference state is updated. Preference names can be up to 10 characters long, must begin with a letter or an underscore, and can contain any combination of letters, numbers, and underscores. Once you have a preference the way you like it, you can prevent it from being changed. Close the Edit window, issue SET RESOURCE OFF, open the FoxUser.dbf file as a table, and change the field containing the preference to read-only by changing the value of the logical field READONLY to true (.T.). For more information about the FoxUser.dbf resource file, see SET RESOURCE.
REST

Prevents the record pointer from being moved from its current position to the top of the table. By default, EDIT positions the record pointer at the top of the table.
SAVE

Keeps the Edit window and any of its memo field text-editing windows active and visible (open). You can then return to the Edit window after cycling through other open windows with the keyboard or the mouse. SAVE is available only from within a program. SAVE has no effect when included with EDIT in the Command window because EDIT SAVE is always the default in the interactive mode.
TIMEOUT nSeconds

Specifies how long an Edit window waits for input. The numeric expression nSeconds specifies how many seconds can elapse without any input before the Edit window automatically closes. TIMEOUT is available only from within a program; it has no effect when you issue EDIT from the Command window. In the following example, the Edit window is closed if no input occurs in 10 seconds.
Copy Code
DEFINE WINDOW wEdit FROM 1,1 TO 24,40 ;
   CLOSE ;
   GROW ;
   COLOR SCHEME 10
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
EDIT WINDOW wEdit ;
   FIELDS phone :H = 'Phone Number:' , ;
   company :H = 'Company:' ;
   TIMEOUT 10
RELEASE WINDOW wEdit
TITLE cTitleText

Overrides the default table name or alias that appears in the Edit window title bar with the title you specify with cTitleText. Otherwise, the name or alias of the table being browsed appears in the title bar. If you issue EDIT WINDOW to place the Edit window in a user-defined window, the Edit window's title replaces the user-defined window's title.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
EDIT;
   TITLE 'My Edit Window' ;
   FIELDS phone :H = 'Phone Number' , ;
   company :H = 'Company:'
VALID lExpression3

Performs record-level validation in an Edit window. The VALID clause is executed only if a change is made to the record and you move the cursor to another record. The VALID clause is not executed if the only change is to a memo field. If VALID returns true (.T.), you can move the cursor to another record. If VALID returns false (.F.), the cursor remains in the current field and Visual FoxPro displays an error message. You can display your own error message when VALID returns false by including the ERROR clause. The character expression cMessageText is displayed as the error message. If VALID returns 0, the cursor remains in the current field, and an error message isn't displayed. The VALID clause shouldn't be confused with the verify option (:V), which enables field-level validation.
:F

Forces the VALID clause to execute before the user moves the cursor to the next record. In this case, VALID is executed even if the record isn't changed.
ERROR cMessageText

Specifies an error message that overrides the system default and whose contents you define with cMessageText. Visual FoxPro displays your error message when VALID returns false (.F.).
WHEN lExpression4

Evaluates a condition when the user moves the cursor to another record. If lExpression4 evaluates to true (.T.), the user can modify the record moved to. If lExpression4 evaluates to false (.F.) or 0, the record the user moves to becomes read-only and cannot be modified. The WHEN clause isn't executed when another window is activated.
WIDTH nFieldWidth

Limits the number of characters displayed for all fields in a partition of the Edit window to nFieldWidth. Including the WIDTH clause doesn't change the size of fields in the table itself; it alters only the way the fields are displayed in the Edit window. If a width has been specified for an individual field with the FIELDS clause, it overrides the width specified with the WIDTH clause for that field.
WINDOW WindowName1

Specifies a user-defined window whose characteristics the Edit window assumes. For example, if the user-defined window is created with the FLOAT clause, the Edit window can be moved. The specified window doesn't have to be active or visible, but it must be defined.
IN [WINDOW] WindowName2

Specifies the parent window within which the Edit window is opened. The Edit window doesn't assume the characteristics of the parent window. An Edit window activated inside a parent window cannot be moved outside the parent window. If the parent window is moved, the Edit window moves with it. To access the Edit window, the parent window must first be defined with DEFINE WINDOW and must be active and visible.
IN SCREEN

Explicitly places an Edit window in the main Visual FoxPro window when a user-defined window is active.
COLOR SCHEME nSchemeNumber

Specifies the number of a color scheme used for the Edit window's colors. In Visual FoxPro, the Edit window assumes the color scheme established using the Color Control Panel.

Remarks

EDIT allows you to edit the selected table within a window. EDIT behaves identically to CHANGE.

If you press ESC to exit the Edit window, changes made to the last field you modified are discarded. However, if you move to another record after modifying a field, your changes to the field are saved.

In a program, use DEACTIVATE WINDOW to save your changes and close an Edit window. Include the name of the Edit window in DEACTIVATE WINDOW. For more information on Edit window names, see WTITLE( ).

SET SKIP Support

SET SKIP lets you establish a one-to-many relationship between two tables (see the example). For each record in the parent table, there can be multiple related records in the child table. If you create a one-to-many relationship, you can use EDIT to view records from both the parent and child tables.

The parent record appears once, along with the first matching record from the child table. Any subsequent matching records are displayed in the rows following the parent record and first matching child record. In FoxPro for MS-DOS, shaded blocks are displayed in any column containing information from the parent table beyond the first matching record. In Visual FoxPro, the fill character for repeated parent information depends on the current Edit window font.

For more information, see SET SKIP.

COL( ) and ROW( ) Support

Use COL( ) and ROW( ) to return the current screen row and column position of the cursor in an Edit window. If an Edit window is opened in the main Visual FoxPro window, the returned cursor position is relative to the main Visual FoxPro window, not to the Edit window itself. If an Edit window is opened in a user-defined window, COL( ) and ROW( ) return the cursor position relative to the user-defined window.

Example

The following example uses SET SKIP to create a one-to-many relationship between two tables. There is a single record in the parent table (customer) for each invoice created. The child table (orders) contains multiple records for each record in the parent table.

After the relationship is created, an Edit window displaying records from both the parent and child tables is opened.
Copy Code
CLEAR
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer ORDER cust_id IN 0   && Parent table
USE orders ORDER cust_id IN 0  && Child table
SELECT customer     && Back to parent work area
SET RELATION TO cust_id INTO orders     && Establish relationship
SET SKIP TO orders  && One-to-many relationship
WAIT WINDOW 'Scroll to see shipping dates for each customer' NOWAIT
EDIT FIELDS customer.cust_id :H='Customer Number', ;
   customer.city :H='Customer City', orders.shipped_on

See Also

Other Resources

Commands
BROWSE Command
Grid Control
SET SKIP Command
WTITLE( ) Function
COL( ) Function
ROW( ) Function


EJECT Command

Visual FoxPro 9.0 Language Reference
EJECT Command
See Also Example

Sends a formfeed to the printer.

EJECT

Remarks

EJECT advances the printer to the top of the next page. EJECT sends a formfeed to the printer if the _PADVANCE system memory variable is set to FORMFEED. If _PADVANCE is set to LINEFEEDS, EJECT issues linefeeds to advance to the top of the next page.

EJECT resets PCOL( ) and PROW( ) values to the current column and row position of the printer's print head, but doesn't affect the value of the _PAGENO or _PLINENO system variables.

Example

In the following example, the company and phone fields in the customer table are printed. (Make sure a printer is attached and turned on for this example.) When the number of rows printed is greater than 62, the page is ejected.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Opens customer table

SET DEVICE TO PRINTER
SET PRINT ON
DO WHILE NOT EOF( )
   @ PROW( )+1,10 SAY 'Company: ' + company
   @ PROW( )+1,10 SAY 'Phone: ' + phone
   @ PROW( )+1,1  SAY ''
   IF PROW( ) > 62
      EJECT
   ENDIF
   SKIP
ENDDO
SET PRINT OFF
SET DEVICE TO SCREEN

See Also

Other Resources

Commands
EJECT PAGE Command
ON PAGE Command
SET DEVICE Command
SET PRINTER Command
PCOL( ) Function
PROW( ) Function
System Variables Overview


EJECT PAGE Command

Visual FoxPro 9.0 Language Reference
EJECT PAGE Command
See Also

Sends a conditional page advance to the printer.

EJECT PAGE

Remarks

Use EJECT PAGE to advance streaming output. The advance depends on the value of _PADVANCE and if an ON PAGE routine is in effect.

If _PADVANCE is set to FORMFEED and an ON PAGE routine isn't in effect, EJECT PAGE performs the following:

  • Sends a formfeed to the printer if the printer is online.

  • Sends linefeeds, as determined by the system memory variables _PLENGTH and _PLINENO, to the screen or to an alternate file or to both.

  • Increments _PAGENO by 1.

  • Sets _PLINENO to 0.

  • If the system memory variable _PADVANCE is set to LINEFEEDS, and if an ON PAGE routine is in effect and _PLINENO is less than the page line number specified in the ON PAGE routine, EJECT PAGE sends to the printer, to the main Visual FoxPro window, or to an alternate file or to both, as many linefeeds as needed to advance to the top of the next page.

If an ON PAGE routine is not in effect, or if _PADVANCE is set to LINEFEEDS and _PLINENO is greater than the page line number specified with ON PAGE, EJECT PAGE does the following:

  • Sends linefeeds, as determined by the system memory variables _PLENGTH and _PLINENO, to the printer, the main Visual FoxPro window, or to the alternate file or to both.

  • Increments _PAGENO by 1.

  • Sets _PLINENO to 0.

See Also

Other Resources

Commands
EJECT Command
ON PAGE Command
SET ALTERNATE Command
SET DEVICE Command
SET PRINTER Command
PCOL( ) Command
PROW( ) Command
System Variables Overview


END TRANSACTION Command

Visual FoxPro 9.0 Language Reference
END TRANSACTION Command
See Also

Ends the current transaction and saves any changes made to tables, table memo files, or index files included in a transaction.

END TRANSACTION

Remarks

Any updates to the database that were made between the previous BEGIN TRANSACTION and the END TRANSACTION are committed. If the transaction is the first or only transaction (that is, the transaction isn't nested), the changes are written to disk.

If a transaction is nested, END TRANSACTION causes all cached updates to be folded into the next higher transaction level. Nesting transactions has the potential to overwrite changes made to data at a higher transaction level.

If END TRANSACTION generates an error (for example, there is insufficient disk space to write changes to disk), changes made during the transaction are cancelled and the transaction ends.

See Also

Reference

MAKETRANSACTABLE( ) Function
ISTRANSACTABLE( ) Function

Other Resources

Commands
BEGIN TRANSACTION Command
ROLLBACK Command
TXNLEVEL( ) Function


ERASE Command

Visual FoxPro 9.0 Language Reference
ERASE Command
See Also Example

Deletes a file from disk.

Caution:
Exercise caution when using ERASE. Any file erased with this command cannot be retrieved. You are not warned before the file is erased, even if SET SAFETY is ON.

ERASE FileName | ? [RECYCLE]

Parameters

FileName

Specifies the file to be erased. Include the path with the file name if the file is on a different drive or directory from the current drive or directory. FileName can contain wildcard characters such as * and ?, for example, to erase backup files with ERASE *.BAK. If FileName contains spaces, enclose the entire file name in quotes.
?

Displays the Delete dialog box, from which you can choose a file to erase.
RECYCLE

Specifies that the file is no't immediately deleted from disk, but rather placed in the Windows Recycle Bin.

Remarks

This command does not generate an error if the specified file does not exist.

The DELETE FILE command is the same as the ERASE command.

Example

In the following example, the structure of CUSTOMER.DBF and all records in which the country is USA are copied to a table named backup. The data in backup is then copied to a text file, temp, which is opened and then deleted when it is closed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Opens customer table

COPY STRUCTURE TO backup
USE backup
APPEND FROM customer FOR country = 'USA'
COPY TO temp TYPE DELIMITED

WAIT WINDOW 'Press Esc to close and erase temp.txt' NOWAIT
MODIFY FILE temp.txt NOEDIT
ERASE temp.txt
? IIF(FILE('temp.txt'),'File not deleted','File deleted')
USE
ERASE backup.dbf

See Also

Other Resources

Commands
DELETE FILE Command
SET SAFETY Command
APPEND FROM Command


ERROR Command

Visual FoxPro 9.0 Language Reference
ERROR Command
See Also

Generates a Visual FoxPro error.

You can use the ERROR command to test error handling routines or to display custom error messages.

ERROR nErrorNumber | nErrorNumber, cMessageText1 | [cMessageText2]

Parameters

nErrorNumber

Specifies the number of the error to generate. The standard Visual FoxPro error message is used when an error number is specified. For a list of Visual FoxPro error messages and their error numbers, see Error Messages A-Z.
cMessageText1

Specifies the text displayed in an error message that supplies additional information about the error. For example, if you reference a memory variable that does not exist, Visual FoxPro supplies the name of the memory variable in the error message.
cMessageText2

Specifies the text displayed in the error message. When cMessageText2 is specified instead of nErrorNumber, Visual FoxPro error number 1098 (user-defined error) is generated. To move a portion of the error message to the next line, use a carriage return (CHR(13)) in cMessageText2.

Remarks

If an ON ERROR error-handling routine is in effect when ERROR is issued, Visual FoxPro executes the ON ERROR routine. If an error occurs for an object, the object's Error event is executed.

If you issue ERROR from the Command window and an ON ERROR error-handling routine is not in effect, Visual FoxPro displays the error message. If ERROR is issued in a program and an ON ERROR error-handling routine is not in effect, Visual FoxPro displays the error message and allows you to cancel or suspend the program or ignore the error.

Note:
The Error event does not occur if an ON ERROR routine is on the call stack.

Examples

The following example generates three error messages. The first line of code displays the error "Variable not found" (Error 12):

Copy Code
ERROR 12

The second line of code generates Error 12 again but includes the variable name MyVariable and displays "Variable 'MyVariable' not found":

Copy Code
ERROR 12, 'MyVariable'

The third line of code displays a user-defined error message (Error 1098) "My error message."

Copy Code
ERROR 'My error message'

See Also

Other Resources

Commands
Error Messages
ON ERROR Command
AERROR( ) Function
Debugging and Error-Handling Language


EXIT Command

Visual FoxPro 9.0 Language Reference
EXIT Command
See Also Example

Exits a DO WHILE, FOR, SCAN, or TRY…CATCH…FINALLY structure.

EXIT

Remarks

The EXIT command transfers control from within the structure to the command immediately following the structure.

Example

In the following example, the number of products in stock priced over 20 dollars is totaled in the DO WHILE loop until the end of the file (EOF) is encountered. The DO WHILE loop is exited and the total is displayed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE products  && Opens Products table
SET TALK OFF
gnStockTot = 0

DO WHILE .T.     && Beginning of loop
   IF EOF( )
      EXIT
   ENDIF
   IF unit_price < 20
      SKIP
      LOOP
   ENDIF
   gnStockTot = gnStockTot + in_stock
   SKIP
ENDDO  && End of loop

CLEAR
? 'Total items in stock valued over 20 dollars:'
?? gnStockTot

See Also

Reference

TRY...CATCH...FINALLY Command

Other Resources

DO WHILE ... ENDDO Command
FOR EACH ... ENDFOR Command
FOR ... ENDFOR Command
SCAN ... ENDSCAN Command
Commands
Language Reference


EXPORT Command

Visual FoxPro 9.0 Language Reference
EXPORT Command
See Also

Copies data from a Visual FoxPro table to a file in a different format.

EXPORT TO FileName [TYPE]
   DIF | MOD | SYLK | WK1 | WKS | WR1 | WRK | XLS | XL5
   [FIELDS FieldList] [Scope] [FOR lExpression1] [WHILE lExpression2]
   [NOOPTIMIZE] [AS nCodePage]

Parameters

FileName

Specifies the name of the file to which Visual FoxPro exports data. If you do not include an extension with the file name, the default extension for the specified file type is assigned.
TYPE

Specifies the type of file to be created. The TYPE keyword is optional, but you must specify one of the following file types.

File type Description

DIF

Each field from a Visual FoxPro table becomes a vector (column) and each record becomes a tuple (row) in a DIF (Data Interchange Format) file, used by VisiCalc. The new file name is assigned a .DIF extension if an extension isn't included in FileName.

MOD

Use the MOD clause to export to a file in Microsoft Multiplan version 4.01 MOD format. The new file name is assigned a .MOD extension if you don't include an extension in FileName.

SYLK

A Symbolic Link interchange format (used by Microsoft Multiplan) in which each field from a Visual FoxPro table becomes a column in the spreadsheet and each record becomes a row. By default, SYLK file names have no extension.

WK1

Include this option to create a Lotus 1-2-3 spreadsheet from a Visual FoxPro table. A .WK1 extension is assigned to the spreadsheet file name for use with Lotus 1-2-3 revision 2.x. Each field from the table becomes a column in the new spreadsheet, and each record in the table becomes a spreadsheet row.

WKS

Include this option to create a Lotus 1-2-3 spreadsheet from a Visual FoxPro table. A .WKS extension is assigned to the spreadsheet file name for use with Lotus 1-2-3 revision 1-A. Each field from the table becomes a column in the new spreadsheet, and each record becomes a row in the spreadsheet.

WR1

Include this option to create a Lotus Symphony spreadsheet from a Visual FoxPro table. A .WR1 extension is assigned to the spreadsheet for use with Symphony version 1.01. Each field from the table becomes a column in the new spreadsheet, and each record in the table becomes a row in the spreadsheet.

WRK

Include this option to create a Lotus Symphony spreadsheet from a Visual FoxPro table. A .WRK extension is assigned to the spreadsheet file name for use with Symphony version 1.10. Each field from the table becomes a column in the new spreadsheet, and each record in the table becomes a row in the spreadsheet.

XLS

Include this option to create a Microsoft Excel worksheet from a Visual FoxPro table. Each field in the selected table becomes a column in the worksheet, and each table record becomes a row. An .xls file name extension is assigned to the newly created worksheet file unless you specify a different extension. You can export a maximum of 65,535 rows, which includes one row reserved for the field header.

XL5

Include this option to create a Microsoft Excel version 5.0 worksheet file from a Visual FoxPro table. Each field from the currently selected table becomes a column in the spreadsheet and each record becomes a row. An .xls extension is assigned to the new worksheet if you do not include a file extension. You can export a maximum of 65,535 rows, which includes one row reserved for the field header.
FIELDS FieldList

Specifies which fields are copied to the new file. If you omit the FIELDS clause, all fields are copied to the new file. Memo and general fields are not copied to the new file even if their names are included in the field list.
Scope

Specifies a range of records to copy to the new file. Scope Specifies a range of records to copy to the new file. Only the records that fall within the range are copied to the new file. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see the Scope Clauses online topic. Commands that include Scope operate only on the table in the active work area. The default scope for EXPORT is all records.
FOR lExpression1

Specifies that only records that satisfy the logical condition lExpression1 are copied to the new file. Using this argument makes it possible for you to filter out undesired records. Rushmore Query Optimization optimizes an EXPORT ... FOR lExpression1 command if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies a condition whereby records are copied to the new file for as long as the logical expression lExpression2 evaluates to true (.T.).
NOOPTIMIZE

Disables Rushmore Query Optimization of EXPORT. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
AS nCodePage

Specifies the code page for the file EXPORT creates. Visual FoxPro copies the contents of the currently selected table, and, as it copies the data, automatically converts the data to the code page you specify for the new file. If possible, Visual FoxPro marks the newly created file with the code page you specify. If you specify a value for nCodePage that is not supported, Visual FoxPro generates an error message. You can use GETCP( ) for nCodePage to display the Code Page dialog box, making it possible for you to specify a code page for the file Visual FoxPro creates. If you omit AS nCodePage, no code page conversion occurs. If possible, Visual FoxPro marks the newly created file with the code page of the table from which the data is copied. If nCodePage is 0, no code page conversion occurs and the newly created file is not marked with a code page.

Remarks

Use EXPORT to use Visual FoxPro data in other software packages.

If the table you are exporting from is indexed, the new file is created in the indexed order.

See Also

Other Resources

APPEND FROM Command
COPY TO Command
GETCP( ) Function
IMPORT Command
SET OPTIMIZE Command
Using Rushmore Query Optimization to Speed Data Access
Commands
Language Reference


EXTERNAL Command

Visual FoxPro 9.0 Language Reference
EXTERNAL Command
See Also

Alerts the Project Manager to an undefined reference.

EXTERNAL FILE FileList | ARRAY ArrayList
   | CLASS | FORM | LABEL | LIBRARY | MENU
   | PROCEDURE | QUERY | REPORT | SCREEN | TABLE

Parameters

FILE FileList

Specifies that the file you include in an indirect file reference or macro substitution is a stand-alone file, such as a text file, .BMP bitmap file, and so on. FileList may contain a list of file names separated by commas.
ARRAY ArrayList

When an array is created in a program and then used in a lower-level program, include ARRAY with the array name in the lower-level program. ArrayList may contain a list of array names separated by commas. In the following example, the first program creates an array named gaInvoice. The array is initialized and a lower-level program named dispinvo is called. dispinvo displays the contents of the array created in the higher-level program. The command EXTERNAL ARRAY GAINVOICE is included to alert the Project Manager.
Copy Code
DIMENSION gaInvoice(4)
STORE 'Paid' TO gaInvoice
DO dispinvo
*** Program dispinvo ***
PROCEDURE dispinvo
EXTERNAL ARRAY gaInvoice
? gaInvoice(1)
? gaInvoice(2)
? gaInvoice(3)
? gaInvoice(4)
RETURN
*** End of dispinvo program ***
When an array is passed to a user-defined function or procedure, the corresponding array in the user-defined function or procedure must be identified to the Project Manager. Include the ARRAY option with the name of the array included in the PARAMETER statement.
Copy Code
DIMENSION gaArrayOne(2)      && Create an array
EXTERNAL ARRAY gaArrayTwo   && Name of the array used in the UDF
SET TALK OFF
STORE 10 TO gaArrayOne(1)
STORE  2 TO gaArrayOne(2)
= ADDTWO(@gaArrayOne)      && Pass the array by reference to a UDF
FUNCTION ADDTWO
PARAMETER gaArrayTwo
CLEAR
gaArrayTwo(1) = gaArrayTwo(1) + 2
gaArrayTwo(2) = gaArrayTwo(2) + 2
? gaArrayTwo(1)
? gaArrayTwo(2)
CLASS

Specifies that the file you include in an indirect file reference or macro substitution is a visual class library.
Copy Code
EXTERNAL CLASS myvclass  && CLASS myvclass must exist
STORE 'myvclass' TO gcClassFile
MODIFY CLASS (gcClassFile)
FORM

If a Form definition file is included in an indirect file reference or macro substitution, include FORM and the Form file name. FORM is identical to SCREEN.
Copy Code
EXTERNAL FORM dataentr  && FORM dataentr must exist
STORE 'dataentr' TO gcFormFile
DO FORM (gcFormFile)
LABEL

Specifies that the file you include in an indirect file reference or macro substitution is a label definition file.
Copy Code
EXTERNAL LABEL Maillabl     && LABEL FORM Maillabl must exist
STORE 'Maillabl' TO gcLabelFile
LABEL FORM (gcLabelFile) PREVIEW
LIBRARY

Include LIBRARY when a library file is referenced by indirect file referencing or macro substitution in SET LIBRARY.
Copy Code
EXTERNAL LIBRARY regress  && LIBRARY regress must exist
STORE 'regress' TO gcStatFunc
SET LIBRARY TO (gcStatFunc)
MENU

If a menu definition file is included in an indirect file reference or macro substitution, include MENU and the menu file name.
Copy Code
EXTERNAL MENU pickfile  && MENU pickfile must exist
STORE 'pickfile' TO gcSysMenPad
MODIFY MENU (gcSysMenPad)
PROCEDURE

Identifies an external procedure or user-defined function.
Copy Code
EXTERNAL PROCEDURE delblank     && PROCEDURE delblank must exist
STORE 'delblank' TO gcTrimBlanks
DO (gcTrimBlanks) WITH 'A B C D E'
QUERY

Specifies that the file you include in an indirect file reference or macro substitution is a query file.
Copy Code
EXTERNAL QUERY sales  && QUERY sales must exist
STORE 'sales.qpr' TO gcSalesFile
DO (gcSalesFile)
REPORT

Specifies that the file you include in an indirect file reference or macro substitution is a report definition file.
Copy Code
EXTERNAL REPORT overdue     && REPORT overdue must exist
STORE 'overdue' TO gcReportFile
REPORT FORM (gcReportFile) PREVIEW
SCREEN

If a form definition file is included in an indirect file reference or macro substitution, include SCREEN and the screen file name. SCREEN is identical to FORM.
Copy Code
EXTERNAL SCREEN dataentr  && SCREEN dataentr must exist
STORE 'dataentr' TO gcScreenFile
MODIFY SCREEN (gcScreenFile)
TABLE

Specifies that the file you include in an indirect file reference or macro substitution is a Visual FoxPro table.
Copy Code
EXTERNAL TABLE customer && Table customer must exist
STORE 'customer' TO gcMyTable
USE (gcMyTable)

Remarks

Use EXTERNAL to include files and to resolve undefined references in a project created by the Project Manager. EXTERNAL is used only by the Project Manager and is ignored during program execution.

For more information on creating projects with the Project Manager, see Compiling an Application.

Files whose names you specify with EXTERNAL are included in a project by the Project Manager. You must include CLASS, FILE, FORM, LABEL, LIBRARY, MENU, PROCEDURE, QUERY, REPORT, SCREEN, or TABLE before the file name or a set of file names separated with commas to tell the Project Manager the type of files to include in the project.

The Project Manager must also be alerted to file names contained in a name expression or macro substitution. This ensures that all necessary files are included in a project when the project is built. It must also be alerted to arrays that are created in another procedure or user-defined function.

For more information on name expressions and macro substitution, see & Command. Whenever possible, use a name expression instead of macro substitution to improve performance.

See Also

Other Resources

BUILD APP Command
BUILD PROJECT Command
Project Manager
Commands
Language Reference


FLUSH Command

Visual FoxPro 9.0 Language Reference
FLUSH Command
See Also

Saves table and index changes to disk.

You can use FLUSH to explicitly save to disk all changes that you make to all open tables and indexes. You can also save changes to a specific table by specifying a work area, table alias, or path and name of a currently opened file.

FLUSH [[IN nWorkArea | cTableAlias] | [cFileSpec]] [FORCE]

Parameters

[IN nWorkArea | cTableAlias] | [cFileSpec]

Specifies the work area number, table alias, or the name of a currently opened file name, for example, an index file or a file opened using the FOPEN( ) function. When specifying a file name, include the path, for example, C:\MyApp\MyTable.dbf.
Note:
If you specify cFileSpec, only changes to the specified file are saved unless cFileSpec is the name of a table (.dbf) file in which case FLUSH applies to the table memo (.fpt) file and all open indexes for that table, even if the table is open in another data session.

If you do not specify nWorkArea, cTableAlias, or cFileSpec, FLUSH applies to all open tables and indexes in the current data session.
FORCE

Calls the Windows API FlushFileBuffers function for all affected files but does not apply to temporary files and files opened as read-only. For more information, see the MSDN online documentation.

Remarks

Visual FoxPro automatically saves changes to disk when performing the following operations:

  • Closing a table using the USE, CLOSE ALL, or CLOSE DATABASES command. Only the information for the file or files you close is saved to disk.

  • Unlocking a record or file. Only the information for the unlocked record or file is saved to disk.

See Also

Other Resources

FFLUSH( ) Function
SET AUTOSAVE Command
Commands
Language Reference


FOR EACH ... ENDFOR Command

Visual FoxPro 9.0 Language Reference
FOR EACH ... ENDFOR Command
See Also

Executes a set of commands for each element in a Visual FoxPro array or collection.

FOR EACH Var [AS Type [OF Class Library]] IN Group [FOXOBJECT]
      Commands
   [EXIT]
   [LOOP]
ENDFOR | NEXT [Var]

Parameters

Var

A variable or array element used to iterate through the elements of Group.
Type

A base class, class name, or type library. (For Intellisense only)
Class Library

Class library containing the base class, class name, or type library specified with Type. (For Intellisense only)
Group

A Visual FoxPro array, an OLE array, a Visual FoxPro collection, or an OLE collection.
FOXOBJECT

Specifies that the variable or array element Var will contain only native (not COM) Visual FoxPro objects.
Commands

Specifies the Visual FoxPro commands to be executed for each element in Group. Commands can include any number of commands.
EXIT

Transfers control from within the FOR EACH ... ENDFOR loop to the command immediately following ENDFOR. You can place EXIT anywhere between FOR EACH and ENDFOR.
LOOP

Returns control directly back to the FOR EACH clause without executing the statements between LOOP and ENDFOR. LOOP can be placed anywhere between FOR EACH and ENDFOR.

Examples

The following examples demonstrate how FOR EACH is used to enumerate elements in a Visual FoxPro array, an OLE array, and a set command buttons assigned to an object array.

In the following example, a Visual FoxPro variable array is created and FOR EACH is used to display the contents of each element in the array.

Copy Code
DIMENSION cMyArray(3)
cMyArray[1] = 'A'
cMyArray[2] = 'B'
cMyArray[3] = 'C'

FOR EACH cMyVar IN cMyArray
   ? cMyVar
ENDFOR

In the following example, an instance of Microsoft Excel is created, and a new workbook is added. FOR EACH is used to display the name of each worksheet in the workbook. This example requires that Microsoft Excel be properly installed on the machine on which the example is run.

Copy Code
oExcel = CREATE("Excel.Application")
oExcel.Workbooks.ADD

FOR EACH oMyVar IN oExcel.sheets
   ? oMyVar.name
NEXT oMyVar

In the following example, five command buttons are placed on a form. FOR EACH is used to display the buttons on the form and specify the captions, font styles and positions of each button.

Copy Code
PUBLIC oMyObject
oMyObject = CREATEOBJECT("frmTest")
oMyObject.SHOW

DEFINE CLASS frmTest AS FORM
Height = 200
DIMENSION MyArray[5]
   PROCEDURE Init

      FOR i = 1 to 5
         THIS.AddObject('THIS.MyArray[i]',;
            'COMMANDBUTTON')
      ENDFOR

      ****** FOR EACH - NEXT ******
      FOR EACH oButton IN THIS.MyArray
         oButton.Visible = .T.
      NEXT

      ****** FOR EACH - NEXT element  ******
      FOR EACH oButton IN THIS.MyArray
         oButton.FontBold = .T.
      NEXT obutton

      j = 1
      ****** FOR EACH - ENDFOR ******
      FOR EACH oButton IN THIS.MyArray
         oButton.top = j * 30
         j = j + 1
      ENDFOR

      ****** FOR EACH - ENDFOR element ******
      FOR EACH oButton IN THIS.MyArray
         oButton.FontItalic = .T.
      ENDFOR obutton

      j = 1
      ****** EXIT  ******
      FOR EACH oButton IN THIS.MyArray
         oButton.Caption = "test" + str(j)
         j = j+1
         IF j > 3
            EXIT
         ENDIF
      NEXT

      j = 1
      ****** LOOP  ******
      FOR EACH oButton IN THIS.MyArray
         IF j > 3
            LOOP
         ENDIF
         j = j + 1
         oButton.Left = 25
      NEXT
   ENDPROC
ENDDEFINE

See Also

Other Resources

FOR ... ENDFOR Command
DO CASE ... ENDCASE Command
DO WHILE ... ENDDO Command
IF ... ENDIF Command
SCAN ... ENDSCAN Command
EXIT Command
LOOP Command
Commands
Language Reference


FOR ... ENDFOR Command

Visual FoxPro 9.0 Language Reference
FOR ... ENDFOR Command
See Also Example

Executes a set of commands a specified number of times.

FOR VarName = nInitialValue TO nFinalValue [STEP nIncrement]
      Commands
   [EXIT]
   [LOOP]
ENDFOR | NEXT

Parameters

VarName

Specifies the name of the variable to act as the counter. The counter keeps track of the number of times the Visual FoxPro commands execute inside the FOR ... ENDFOR loop. The variable does not need to exist before executing FOR ... ENDFOR.
nInitialValueTO nFinalValue

Specifies the initial and final values of the counter. Both nInitialValue and nFinalValue can be array elements.
[STEP nIncrement]

Specifies the amount to increment or decrement the counter value. If nIncrement is negative, the counter value is decremented. If you omit the STEP clause, VarName increments by 1.
Commands

Specifies the Visual FoxPro commands to execute. Commands can include any number of commands.
[EXIT]

Transfers control from within the FOR ... ENDFOR loop to the command immediately following ENDFOR. You can place EXIT anywhere between FOR and ENDFOR. For more information, see EXIT Command.
[LOOP]

Returns control to the FOR clause without executing the statements between the LOOP and ENDFOR keywords. The counter value increments or decrements as if ENDFOR was reached. For more information, see LOOP Command.
ENDFOR

Specifies the end of the FOR ... ENDFOR loop.
NEXT

Specifies the location to continue program execution after the counter value exceeds nFinalValue.

Remarks

The Visual FoxPro commands that appear in the FOR loop execute until ENDFOR or NEXT is reached. The value in the counter VarName then increments or decrements by the value of nIncrement. The value of the counter is then compared with nFinalValue. If the counter is less than or equal to nFinalValue, the commands following the FOR clause execute again. If the counter is greater than nFinalValue, the FOR ... ENDFOR loop exits, and program execution continues with the first command following ENDFOR or NEXT.

Note:
The values of nInitialValue, nFinalValue, and nIncrement are read only initially. However, changing the value of the counter VarName inside the loop affects the number of times the loop is executed. Changing the value of nFinalValue in a FOR loop has no effect.

Example

Example 1

In the following example, the FOR ... ENDFOR loop displays the numbers 1 through 10 using the ? command:

Copy Code
FOR gnCount = 1 TO 10
   ? gnCount
ENDFOR

For more information, see ? | ?? Command.

Example 2

The following example opens Customer table in the Visual FoxPro sample TestData database, located in the Microsoft Visual FoxPro directory ..\Samples\Data. The FOR ... ENDFOR loop specifies an initial value of 1, an increment value of 2, and a final value of 10. The GOTO command moves the record pointer to the record number specified by the variable gnCount and the DISPLAY command displays the name of the company from the Company field in the table. The FOR ... ENDFOR loop displays all odd-numbered records from the first 10 records.

Copy Code
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer
FOR gnCount = 1 TO 10 STEP 2
   GOTO gnCount
   DISPLAY Company
ENDFOR

For more information, see GO | GOTO Command and DISPLAY Command.

See Also

Other Resources

DO CASE ... ENDCASE Command
DO WHILE ... ENDDO Command
FOR EACH ... ENDFOR Command
SCAN ... ENDSCAN Command
Commands
Language Reference


FREE TABLE Command

Visual FoxPro 9.0 Language Reference
FREE TABLE Command
See Also

Removes a database reference from a table.

FREE TABLE TableName

Parameters

TableName

Specifies the name of the table from which the database reference is removed.

Remarks

If a database is accidentally deleted from disk, references to the database remain in the tables formerly contained in the database. FREE TABLE removes the database references from a table, making it possible for you to open the table or add the table to a different database.

Caution:
FREE TABLE should never be issued to remove a table from a database if the database exists on disk. If the database exists on disk, FREE TABLE may render the database unusable. Use REMOVE TABLE instead. Unlike FREE TABLE, REMOVE TABLE removes all references from the database to primary indexes, default values, and validation rules associated with the table.

See Also

Other Resources

ADD TABLE Command
CREATE DATABASE Command
OPEN DATABASE Command
REMOVE TABLE Command
Commands
Language Reference


FUNCTION Command

Visual FoxPro 9.0 Language Reference
FUNCTION Command
See Also Example

Creates a user-defined function in a program file. There are two versions of the syntax.

FUNCTION FunctionName
   [ LPARAMETERS parameter1 [ ,parameter2 ] , ... ]
      Commands
   [ RETURN [ eExpression ] ]
[ENDFUNC]
FUNCTION FunctionName( [ parameter1 [ AS para1type ][ ,parameter2 [ AS para2type ] ],...] ) [ AS returntype ]
      Commands
   [ RETURN [ eExpression ] ]
[ENDFUNC]

Parameters

FUNCTION FunctionName

Designates the beginning of a user-defined function and specifies the name of the function. FunctionName can contain up to 254 characters.
[ LPARAMETERS parameter1 [, parameter2] , ... ]

Assigns data from the calling program to local variables or arrays. You can also use the PARAMETERS keyword instead of LPARAMETERS to accept privately scoped parameters. You can pass a maximum of 26 parameters to a function. For more information, see LPARAMETERS Command and PARAMETERS Command.
( [ parameter1[ AS para1type][ , parameter2[ AS para2type] ],...] )

Assigns data from the calling program to local variables or arrays. You can use the AS para1type clause to specify the data type of the variable.
Note:
Including the parameters inside parentheses (()) immediately following the function name indicates that the parameters are locally scoped to the function.

[ AS returntype]

Specifies the data type of the return value. You can use the AS clause to implement strong typing. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.
Commands

Specifies the Visual FoxPro commands to execute when executing the function.
[ RETURN [ eExpression] ]

Returns control to the calling program or to another program. eExpression can specify a return value.
Note:
You can include the RETURN command anywhere in the function to return control to the calling program or to another program and to define a value returned by the function. If you do not include the RETURN command, Visual FoxPro executes an implicit RETURN automatically when the function quits. If the RETURN command does not include a return value or if an implicit RETURN is executed, Visual FoxPro assigns True (.T.) as the return value. For more information, see RETURN Command.

[ ENDFUNC ]

Indicates the end of the FUNCTION structure.
Note:
The ENDFUNC keyword is optional because the function quits when it encounters another FUNCTION command, a PROCEDURE command, or the end of the program file. You cannot include normal executable program code following user-defined functions in a program file. Only other user-defined functions, procedures, and class definitions can follow the first FUNCTION or PROCEDURE command in the file.

Remarks

By default, parameters are passed to functions by value. For information about passing parameters to functions by reference, see SET UDFPARMS.

When you issue the DO command with a function name, Visual FoxPro searches for the function in the following order:

  1. The file containing the DO command.

  2. Procedure files opened with SET PROCEDURE.

    For more information, see SET PROCEDURE Command.

  3. Program files in the execution chain.

    Visual FoxPro searches program files in order from the most recently executed program to the first program executed.

  4. A standalone program file.

If a matching program file is found, Visual FoxPro executes the program. Otherwise, Visual FoxPro generates an error message.

To execute a function in a specific file, include the IN clause in the DO command.

For information about using the FUNCTION command when creating classes, see DEFINE CLASS.

Example

This example creates a custom object class called Hello and adds a function method called SayHello. The SayHello method returns the character string "Hello World", which is displayed by the MESSAGEBOX function. Note: The class definition code is placed after the program code that instantiates the object.
Copy Code
Local oHello
oHello=CREATEOBJECT("Hello")
=MESSAGEBOX(oHello.SayHello(),48)
RELEASE oHello

* Class definition code
DEFINE CLASS Hello AS CUSTOM
 FUNCTION SayHello
  RETURN "Hello World"
 ENDFUNC
ENDDEFINE

See Also

Other Resources

PROCEDURE Command
PARAMETERS( ) Function
Commands


GATHER Command

Visual FoxPro 9.0 Language Reference
GATHER Command
See Also Example

Replaces the data in the current record of the currently selected table with data from an array, a set of variables, or an object.

GATHER FROM ArrayName | MEMVAR | NAME ObjectName
   [FIELDS FieldList | FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton]
   [MEMO]

Parameters

FROM ArrayName

Specifies the array whose data replaces the data in the current record. The contents of the elements of the array, starting with the first element, replace the contents of the corresponding fields of the record. The contents of the first array element replace the first field of the record; the contents of the second array element replace the second field, and so on. If the array has fewer elements than the table has fields, the additional fields are ignored. If the array has more elements than the table has fields, the additional array elements are ignored.
MEMVAR

Specifies the variables or array from which data is copied to the current record. Data is transferred from the variable to the field that has the same name as the variable. The contents of a field are not replaced if a variable doesn't exist with the same name as the field.
Tip:
You can create variables with the same names as fields by including MEMVAR or BLANK in SCATTER.

NAME ObjectName

Specifies an object whose properties have the same names as fields in the table. The contents of each field are replaced by the value of the property with the same names as the fields. The contents of a field are not replaced if a property doesn't exist with the same name as the field.
FIELDS FieldList

Specifies the fields whose contents are replaced by the contents of the array elements or variables. Only the field specified with FieldList has its contents replaced.
FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton

You can selectively replace fields with the contents of array elements or variables by including the LIKE or EXCEPT clause or both. If you include LIKE Skeleton, Visual FoxPro replaces the fields that match Skeleton. If you include EXCEPT Skeleton, Visual FoxPro replaces all fields except those that match Skeleton. Skeleton supports wildcards (* and ?). For example, to replace all fields that begin with the letters A and P, use:
Copy Code
GATHER FROM gamyarray FIELDS LIKE A*,P*
MEMO

Specifies that the contents of memo or Blob fields are replaced with the contents or array elements or variables. If you omit MEMO, memo and Blob fields are skipped when GATHER replaces the contents of fields with the contents of an array or variable. General and picture fields are always ignored in GATHER, even if you include the MEMO keyword.

Example

This example uses GATHER to copy data to a new record in a table. After the table Test is created, SCATTER is used to create a set of variables based on the fields in the table. Each field is then assigned a value and a new blank record is added to the table.

Copy Code
CREATE TABLE Test FREE ;
   (Object C(10), Color C(16), SqFt n(6,2))
SCATTER MEMVAR BLANK
m.Object="Box"
m.Color="Red"
m.SqFt=12.5
APPEND BLANK
GATHER MEMVAR
BROWSE

The following example uses GATHER along with the NAME clause to copy data to a new record in a table. After the table Test is created, SCATTER is used to create an object with properties based on the fields in the table. The object's properties are then assigned values and a new blank record is added to the table.

Copy Code
CREATE TABLE Test FREE ;
   (Object C(10), Color C(16), SqFt n(6,2))

SCATTER NAME oTest BLANK
oTest.Object="Box"
oTest.Color="Red"
oTest.SqFt=12.5
APPEND BLANK
GATHER NAME oTest
RELEASE oTest
BROWSE

See Also

Other Resources

APPEND FROM ARRAY Command
COPY TO ARRAY Command
DIMENSION Command
SCATTER Command
Commands
Language Reference


GETEXPR Command

Visual FoxPro 9.0 Language Reference
GETEXPR Command
See Also Example

Displays the Expression Builder dialog box so you can create an expression and store the expression to a variable or array element.

GETEXPR [cCaptionText] TO MemVarName
   [TYPE cExpressionType [; cErrorMessageText]]
   [DEFAULT cDefaultExpression]

Parameters

cCaptionText

Specifies the caption that appears in the Expression Builder. The caption can be used to remind the user of what kind of expression to build.
TO MemVarName

Specifies the variable or array element in which the expression is stored. If the variable doesn't already exist, Visual FoxPro creates it. GETEXPR won't create an array element. If you exit the Expression Builder by pressing ESC or by choosing Cancel, the empty string is stored to the variable or array element. If a default expression is created with the DEFAULT clause, the default expression is stored to the variable if you exit the Expression Builder by pressing ESC or choosing Cancel.
TYPE cExpressionType [; cErrorMessageText]

Specifies the expression type. The following table lists the character to specify in cExpressionType for each expression type:

cExpressionType Expression type

C

Character

D

Date

T

DateTime

N

Numeric

F

Float

I

Integer

B

Double

Y

Currency

L

Logical
You can specify the error message cErrorMessageText to be displayed if the expression isn't valid. If cErrorMessageText is included with cExpressionType, cExpressionType and cErrorMessageText must be separated by a semicolon (;). The combination of cExpressionType, the semicolon, and cErrorMessageText must be enclosed in single or double quotes in matching pairs.
DEFAULT cDefaultExpression

Makes it possible for you to display the initial default expression in the Expression Builder. You can accept the default expression or overwrite it with your own expression specified with cDefaultExpression. cDefaultExpression is stored to the variable or array element if you exit the Expression Builder by pressing ESC or choosing Cancel.

Example

In the following example, GETEXPR is used to get a LOCATE expression of the proper type. If LOCATE is successful, the company name is displayed; otherwise, a message is displayed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

GETEXPR 'Enter condition to locate ' TO gcTemp;
   TYPE 'L' DEFAULT 'COMPANY = ""'
LOCATE FOR &gcTemp
IF FOUND( )
   DISPLAY
ELSE
   ? 'Condition ' + gcTemp + ' was not found '
ENDIF

See Also

Other Resources

_GETEXPR System Variable
GETFILE( ) Function
GETPICT( ) Function
LOCFILE( ) Function
PUTFILE( ) Function
Commands
Language Reference


GO | GOTO Command

Visual FoxPro 9.0 Language Reference
GO | GOTO Command
See Also Example

Moves the record pointer to the specified record number. There are multiple versions of the syntax.

GO [RECORD] nRecordNumber [IN nWorkArea | IN cTableAlias]
GO TOP | BOTTOM [IN nWorkArea | IN cTableAlias]
GOTO [RECORD] nRecordNumber [IN nWorkArea | IN cTableAlias]
GOTO TOP | BOTTOM [IN nWorkArea | IN cTableAlias]

Parameters

RECORD nRecordNumber

Specifies the physical record number to move the record pointer to. You can omit GO or GOTO entirely and specify just the record number. If you specify just the record number, you can move the record pointer only within the current work area.
IN nWorkArea

Specifies the work area of the table in which the record pointer is moved.
IN cTableAlias

Specifies the alias of the table in which the record pointer is moved.
TOP

Positions the record pointer on the first record in the table. If the table has an ascending index in use, the first record is the record with the lowest key value. If the index is in descending order, the first record is the record with the highest key value.
BOTTOM

Positions the record pointer on the last record in the table. If the table has an ascending index in use, the last record is the record with the highest key value. If the index is in descending order, the last record is the record with the lowest key value.

Remarks

GO and GOTO can be used interchangeably. These commands operate on the table in the current work area unless you specify another work area with the IN clause.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Opens Products table
USE customer IN 0  && Opens Customer table
GO BOTTOM IN products
CLEAR
? RECNO('products')
GO TOP
? RECNO( )     && Displays 1
GO 5
? RECNO( )     && Displays 5

See Also

Other Resources

RECNO( ) Function
SELECT Command
SKIP Command
Commands
Language Reference


HELP Command

Visual FoxPro 9.0 Language Reference
HELP Command
See Also

Opens the Help window.

HELP   [Topic | ID nContextID] [IN [WINDOW] WindowName | IN [WINDOW]
   SCREEN | IN [WINDOW] [NOWAIT]

Parameters

Topic

Specifies the Help topic to display. If you include just a partial spelling of a topic title, Visual FoxPro opens the Help window and displays the topic with the closest matching title.
ID nContextID

Specifies the Help topic to display, based on the topic's context ID. When you are using graphical style Help, nContextID is a context number in the MAP section of the help project file.
IN [WINDOW] WindowName

Opens the Help window within a parent window. The Help window doesn't assume the characteristics of the parent window it is placed in. If the Help window is activated inside a parent window, it cannot be moved outside the parent window. If the parent window is moved, the Help window moves with it. Before you can open the Help window from within a parent window, the parent window must first be defined with DEFINE WINDOW.
IN [WINDOW] SCREEN

Explicitly places the Help window on the main Visual FoxPro window.
NOWAIT

In graphical style Help, the NOWAIT argument has no effect, and program execution always continues after the HELP command has been issued.

Remarks

See Also

Reference

SET HELP Command
SET TOPIC Command

Other Resources

Commands
Language Reference


HIDE MENU Command

Visual FoxPro 9.0 Language Reference
HIDE MENU Command
See Also

Hides one or more active user-defined menu bars.

HIDE MENU MenuBarName1 [, MenuBarName2 ...] | ALL [SAVE]

Parameters

MenuBarName1 [, MenuBarName2 ...]

Specifies the name of the menu bar or a list of menu bars (separated by commas) to hide.
ALL

Hides all defined menu bars.
SAVE

Places an image of a menu bar on the screen or in a window. Placing an image of a menu bar on the screen is useful during program development and testing. Menu bar images can be cleared from the main Visual FoxPro window or a user-defined window with CLEAR.

Remarks

HIDE MENU removes the specified menu bar, a set of menu bars, or all menu bars from the main Visual FoxPro window or from a user-defined window without removing the menu definition from memory. Before a menu bar can be hidden, it must first be created with DEFINEMENU. Hiding a menu bar isn't the same as deactivating it. When a menu bar is hidden, it stays resident in memory and can be displayed in the main Visual FoxPro window or in a user-defined window with ACTIVATE MENU or SHOW MENU.

See Also

Reference

ACTIVATE MENU Command
DEFINE MENU Command
DEFINE PAD Command
SHOW MENU Command

Other Resources

Commands (Visual FoxPro)
Language Reference (Visual FoxPro)


HIDE POPUP Command

Visual FoxPro 9.0 Language Reference
HIDE POPUP Command
See Also

Hides one or more active menus created with DEFINE POPUP.

HIDE POPUP MenuName1 [, MenuName2 ...] | ALL [SAVE]

Parameters

MenuName1 [, MenuName2 ...]

Specifies the name of the menu or a list of menus (separated by commas) to hide.
ALL

Hides all defined menus.
SAVE

Places an image of a menu in the main Visual FoxPro window or in a user-defined window. Placing an image of a menu on the screen is useful during program development and testing. Menu images can be cleared from the main Visual FoxPro window or from a user-defined window with CLEAR.

Remarks

HIDE POPUP removes the specified menu, a set of menus, or all menus from the main Visual FoxPro window or from a user-defined window without removing the menu definitions from memory. Before a menu can be hidden, it must first be created with DEFINE POPUP. Hiding a menu isn't the same as deactivating it. When a menu is hidden, it stays resident in memory and can be displayed in the main Visual FoxPro window or in a user-defined window with ACTIVATE POPUP or SHOW POPUP.

See Also

Other Resources

ACTIVATE POPUP Command
DEFINE BAR Command
DEFINE POPUP Command
SHOW POPUP Command
Commands
Language Reference


HIDE WINDOW Command

Visual FoxPro 9.0 Language Reference
HIDE WINDOW Command
See Also Example

Hides an active user-defined window or Microsoft Visual FoxPro system window.

HIDE WINDOW WindowName1 [, WindowName2 ... ] | ALL | SCREEN
   [ IN [WINDOW] WindowNameN | IN [WINDOW] SCREEN | IN [WINDOW]
   [BOTTOM | TOP | SAME]

Parameters

WindowName1[, WindowName2...]

Specifies the name of the window or a list of windows (separated by commas) to hide. If you issue HIDE WINDOW without any arguments, the active window is hidden. In Visual FoxPro, you can specify the name of a toolbar to hide. See SHOW WINDOW for a list of Visual FoxPro toolbar names.
ALL

Hides all windows.
SCREEN

Hides the main Visual FoxPro window. To display the main Visual FoxPro window again, issue ACTIVATE WINDOW SCREEN or SHOW WINDOW SCREEN.
IN [WINDOW] WindowNameN

Hides the window within a parent window.
IN [WINDOW] SCREEN

Explicitly hides a window in the main Visual FoxPro window.
BOTTOM | TOP | SAME

Specifies where windows are hidden with respect to other windows. BOTTOM places a window behind all other windows. TOP (the default) places a window in front of all other windows. SAME hides a window without affecting its front-to-back placement. To preserve the relative positions of multiple hidden windows when they are redisplayed with SHOW WINDOW ALL, include the SAME keyword when you hide the windows.

Remarks

HIDE WINDOW removes a window or a set of windows from the main Visual FoxPro window or from a user-defined window. You can use HIDE WINDOW to hide system windows, such as the Command window, the Data Session window, and so on.

Hiding a window isn't the same as closing it. When a window is hidden, it stays resident in memory and remains active. Output can be sent to a hidden window, but you cannot see it.

Releasing a window removes it from memory. Windows removed from memory must be defined again to be redisplayed. A window can be displayed with ACTIVATE WINDOW or SHOW WINDOW.

To hide a system window and or a toolbar (in Visual FoxPro), enclose the entire system window or toolbar name in quotation marks. For example, to hide the Report Controls toolbar in Visual FoxPro, issue the following command:

Copy Code
HIDE WINDOW "Report Controls"

Historically in prior versions of Visual FoxPro, the Data Session window has always been referred to as the View window. Additionally, language used to control this window, such as HIDE WINDOW, ACTIVATE WINDOW, WONTOP( ), also refers to this window as the View window. Visual FoxPro continues to refer to the View window for the HIDE WINDOW command.

Example

In the following example, a window named wOutput1 is defined and activated. The program waits for you to press a key and then hides the window. The program waits for you to press a key again and then displays the window. Pressing a key a third time removes the window from the screen and from memory.
Copy Code
DEFINE WINDOW wOutput1 FROM 6,1 TO 19,75 TITLE 'Output' ;
   CLOSE FLOAT GROW ZOOM
ACTIVATE WINDOW wOutput1

WAIT WINDOW 'Press a key to hide this window'
HIDE WINDOW wOutput1

WAIT WINDOW 'Press a key to see the window again'
SHOW WINDOW wOutput1

WAIT WINDOW 'Press a key to remove the window from memory'
DEACTIVATE WINDOW wOutput1
RELEASE WINDOW wOutput1

See Also

Other Resources

ACTIVATE WINDOW Command
DEACTIVATE WINDOW Command
DEFINE WINDOW Command
RELEASE WINDOW Command
SHOW WINDOW Command
Commands
Language Reference


IF ... ENDIF Command

Visual FoxPro 9.0 Language Reference
IF ... ENDIF Command
See Also Example

Conditionally executes a set of commands based on the value of a logical expression.

IF lExpression [THEN]
      Commands
[ELSE
      Commands]
ENDIF

Parameters

lExpression

Specifies the logical expression that is evaluated. If lExpression evaluates to true (.T.), any commands following IF or THEN and preceding ELSE or ENDIF (whichever occurs first) are executed.
  • If lExpression is false (.F.) and ELSE is included, any commands after ELSE and before ENDIFare executed.

  • If lExpression is false (.F.) and ELSE isn't included, all commands between IF and ENDIF are ignored. In this case, program execution continues with the first command following ENDIF.

Remarks

You can nest an IF ... ENDIF block within another IF ... ENDIF block.

Comments preceded by && can be placed on the same line after IF, THEN, ELSE, and ENDIF. These comments are ignored during compilation and program execution.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer     && Open customer table

GETEXPR 'Enter condition to locate ' TO gcTemp;
   TYPE 'L' DEFAULT 'COMPANY = ""'
LOCATE FOR &gcTemp  && Enter LOCATE expression
IF FOUND( )  && Was it found?
   DISPLAY  && If so, display the record
ELSE  && If not found
   ? 'Condition ' + gcTemp + ' was not found '   && Display a message
ENDIF
USE

See Also

Other Resources

DO CASE ... ENDCASE Command
DO WHILE ... ENDDO Command
FOR EACH ... ENDFOR Command
FOR ... ENDFOR Command
IIF( ) Function
SCAN ... ENDSCAN Command
Commands
Language Reference


INSERT - SQL Command

Visual FoxPro 9.0 Language Reference
INSERT - SQL Command
See Also

Appends a new record to the end of a table that contains the specified field values. The INSERT SQL command has three syntaxes:

  • Use the first syntax to insert specified values into specified fields in a table.

  • Use the second syntax to insert the contents of elements from an array, memory variable, or property of an object that match the field names in the table.

  • Use the third syntax to insert rows from an SQL SELECT command into the specified fields in the table.

INSERT INTO dbf_name [(FieldName1 [, FieldName2, ...])]
   VALUES (eExpression1 [, eExpression2, ...])
INSERT INTO dbf_name FROM ARRAY ArrayName | FROM MEMVAR | FROM NAME ObjectName
INSERT INTO dbf_name [(FieldName1 [, FieldName2, ...])]
   SELECT SELECTClauses [UNION UnionClause SELECT SELECTClauses ...]

Parameters

INSERT INTO dbf_Name

Specifies the name of the table for appending a new record. dbf_Name can include a path and can be a name expression.
[( FieldName1 [, FieldName2 [, ...]])]

Specifies the names of the fields in the new record into which the values are inserted.
VALUES (eExpression1 [, eExpression2 [, ...]])

Specifies the field values to be inserted into the new record. If you omit the field names, you must specify the field values in the order defined by the table structure. If eExpression is a field name, it must include the table alias. If SET NULL is ON, INSERT attempts to insert null values into any fields not specified in the VALUES clause.
FROM Source

Specifies to insert data from an array, memory variable, or Visual FoxPro object. The following list describes valid items for Source:
  • ARRAY

    ArrayName specifies the array whose data is inserted into the new record.

    Starting with the first element, the contents of the elements of the array are inserted into the corresponding fields of the record. The contents of the first array element are inserted into the first field of the new record; the contents of the second array element are inserted into the second field, and so on.

    When you include the FROM ARRAY clause, Visual FoxPro disregards any default values for fields.

  • MEMVAR

    MEMVAR specifies that the contents of memory variables are inserted into fields with the same names as the variables. If a variable does not exist with the same name as the field, the field is left empty.

  • NAME

    ObjectName specifies a valid Visual FoxPro object, whose property names match the field names in the table for which you want to insert a new record containing the object's property values. You can specify any valid Visual FoxPro object, which you would typically create using the SCATTER...NAME command. For more information, see SCATTER Command.

    If the table has a field that does match an object property, Visual FoxPro disregards the field and leaves it blank as if calling the APPEND BLANK command.

    If the type of an object's property does not match the field type in the table, Visual FoxPro generates a data type mismatch message.

    Note:
    Use caution when specifying objects derived from Visual FoxPro classes because many native properties have types that might differ from the fields you are working with and cannot be changed.

    If an autoincrementing field exists in the table, you cannot have an object property that matches the autoincrementing field unless you set the SET AUTOINCERROR command to OFF for the data session. Otherwise, Visual FoxPro generates an error. If you use SCATTER...NAME to create the object while SET AUTOINCERROR is set to ON, you can use the REMOVEPROPERTY( ) function to remove any autoincrementing properties to avoid generating an error. For more information, see SET AUTOINCERROR Command and REMOVEPROPERTY( ) Function.

An array, memory variable, or an object is not supported in the Visual FoxPro OLE DB Provider.
SELECT SELECTClauses [UNION UnionClause SELECT SELECTClauses ...]

Retrieves data from specified fields in a table or cursor, using one or more SQL SELECT statements, for insertion into another table or cursor. However, the SELECT statement cannot contain any non-SQL clauses such as the following: INTO, TO, and PREFERENCE clauses; NOFILTER, READWRITE, NOCONSOLE, PLAIN, and NOWAIT options. To combine additional SQL SELECT statements with the first SQL SELECT statement, use the UNION clause. For syntax of the SQL SELECT command, which contains the UNION clause, see SELECT - SQL Command.
Note:
When you use SQL INSERT with a SELECT statement, make sure that the data you insert is compatible with the data types in the table into which you are inserting. Visual FoxPro attempts to convert the data types in the cursor created by SQL SELECT into the data types in the corresponding table or cursor column into which the data is inserted. If the inserted data is not compatible, precision might be lost, Date data types are converted to Character data types, and so on.

Remarks

If the table you specify is open, SQL INSERT appends the new record to the table. If the table is open in a work area other than the current work area, it is not selected after the record is appended; the current work area remains selected.

If the table you specify is not open, Visual FoxPro opens it in a new work area, and the new record is appended to the table. The new work area is not selected; the current work area remains selected.

While the SQL INSERT command is executing, the current work area becomes the area into which the new record is inserted. In other words, when the SQL INSERT command is executed, it is in the context of the table being inserted into regardless of the current work area before the command was issued.

After executing the INSERT command, Visual FoxPro positions the record pointer on the new record.

Visual FoxPro updates the _TALLY system variable with the number of rows inserted if you include a SQL SELECT statement. For more information, see _TALLY System Variable.

Examples

Example 1

The following example opens the Employee table and adds one record.

Copy Code
USE employee
INSERT INTO employee (emp_no, fname, lname, officeno) ;
   VALUES (3022, "John", "Smith", 2101)

Example 2

The following example uses the USE command to open the Customer table in the TestData.dbc database and the SCATTER command to copy the contents of the current record into variables. COPY STRUCTURE copies the table structure to a new table named Cust2.

INSERT inserts a new record into the Cust2 table from memory variables. SELECT retrieves the data from Cust2, and BROWSE displays the new record.

To clean up, the USE command with no table specified closes the table in the current work area, and DELETE removes Cust2.

Copy Code
CLOSE DATABASES
CLEAR
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer
SCATTER MEMVAR
COPY STRUCTURE TO Cust2
INSERT INTO Cust2 FROM MEMVAR
SELECT CUST2
BROWSE
USE
DELETE FILE cust2.dbf

Example 3

The following example inserts data from the OrdersArchive table from a SELECT statement performed on the Orders table.

Copy Code
INSERT INTO OrdersArchive (order_id, order_date, ship_name) ;
   SELECT order_id, order_date, ship_name FROM Orders ;
      WHERE order_date >= (DATE()-30)

See Also

Reference

MODIFY QUERY Command
_TALLY System Variable

Other Resources

Commands
CREATE QUERY Command
CREATE TABLE – SQL Command


IMPORT Command

Visual FoxPro 9.0 Language Reference
IMPORT Command
See Also

Imports data from an external file format to create a new Visual FoxPro table.

IMPORT FROM FileName   [DATABASE DatabaseName [NAME LongTableName]]
   [TYPE] FW2 | MOD | PDOX | RPD | WK1    | WK3 | WKS | WR1 | WRK | XLS
    | XL5 [SHEET cSheetName]   | XL8 [SHEET cSheetName]   [AS nCodePage]

Parameters

FileName

Specifies the name of the file from which to import data. If you don't include an extension with the file name, the default extension for the specified file type is assumed.
DATABASE DatabaseName

Specifies a database to which the new table is added.
NAME LongTableName

Specifies a long name for the new table. Long names can contain up to 128 characters and can be used in place of short file names in the database.
TYPE

The keyword TYPE is optional, but you must include one of the following file types:

File type Description

FW2

Include FW2 to import FW2 files, created by Framework II.

MOD

Include MOD to import MOD files, created by Microsoft Multiplan version 4.1.

PDOX

Include PDOX to import Paradox files. Database files in Paradox versions 3.5 and 4.0 by Borland can be imported by including the PDOX option.

RPD

Include RPD to import RPD files, created by RapidFile.

WK1 | WK3 | WKS

Include WK1 to import data from a Lotus 1-2-3 spreadsheet. Columns from the spreadsheet become fields in the table and the spreadsheet rows become records in the table. A WK1 extension is assigned to spreadsheets created in Lotus 1-2-3 revision 2.x; a WK3 extension is assigned to spreadsheets created in Lotus 1-2-3 revision 3.x; and a .wks extension is assigned to spreadsheets created in Lotus 1-2-3 revision 1-A.

WR1 | WRK

Include WR1 to import data from a Lotus Symphony spreadsheet. Columns from the spreadsheet become fields in the table and the spreadsheet rows become records in the table. A WR1 extension is assigned to spreadsheets created in Symphony version 1.10, and a .wrk extension is assigned to spreadsheets created in Symphony version 1.1.

XLS

Include XLS to import data from Microsoft Excel worksheets versions 2.0, 3.0, and 4.0. Columns from the worksheet become fields in the table and the worksheet rows become records in the table. Worksheet files created in Microsoft Excel have an .xls extension.

XL5 [SHEET cSheetName]

Include XL5 to import data from Microsoft Excel version 5.0. Columns from the worksheet become fields in the table and the worksheet rows become records in the table. Worksheet files created in Microsoft Excel have an .xls extension.

If you omit the SHEET clause, the data in Sheet1 is imported. To import data from a specific sheet, include the SHEET keyword and specify the sheet name with cSheetName.

XL8 [SHEET cSheetName]

Include XL8 to import data from Microsoft Excel 97. Columns from the worksheet become fields in the table and the worksheet rows become records in the table. Worksheet files created in Microsoft Excel have an .xls extension.

If you omit the SHEET clause, the data in Sheet1 is imported. To import data from a specific sheet, include the SHEET keyword and specify the sheet name with cSheetName.
AS nCodePage

Specifies the code page of the imported file. Visual FoxPro copies the contents of the imported file and, as it copies the data, automatically converts the data to the current Visual FoxPro code page. If you specify a value for nCodePage that is not supported, Visual FoxPro displays an error message. You can use GETCP( ) for nCodePage to display the Code Page dialog box, allowing you to specify a code page for the imported file. If you omit AS nCodePage and Visual FoxPro cannot determine the code page of the imported file, Visual FoxPro copies the contents of the imported file and, as it copies the data, automatically converts the data to the current Visual FoxPro code page. If you omit AS nCodePage and Visual FoxPro can determine the code page of the imported file, Visual FoxPro automatically converts the data in the imported file from the data's code page to the current Visual FoxPro code page. Use CPCURRENT( ) to determine the current Visual FoxPro code page. If nCodePage is 0, Visual FoxPro assumes the code page of the imported file is the same as the current Visual FoxPro code page and no code page conversion occurs.

Remarks

Most software packages store their data in file formats that cannot be opened directly in Visual FoxPro. IMPORT creates a new Visual FoxPro table from data stored in file formats that Visual FoxPro cannot directly read.

A new table is created with the same name as the file from which the data is imported. A .dbf extension is assigned to the newly created table.

See Also

Other Resources

APPEND FROM Command
COPY TO Command
EXPORT Command
GETCP( ) Function
Commands
Language Reference


INDEX Command

Visual FoxPro 9.0 Language Reference
INDEX Command
See Also Example

Creates an index file containing one or more indexes for displaying and accessing table records in a specified order.

Note:
You cannot create primary indexes with the INDEX command. If you want to create a primary index using the Visual FoxPro language, use the SQL CREATE TABLE or ALTER TABLE commands.

Caution:
Replacing an index key field changes the relative position for the current record in the index. Therefore, use caution if you perform an operation such as REPLACE ALL or SCAN ... ENDSCAN while changing the index for the scope. This also applies to REPLACE operations on indexes created with a FOR clause.

INDEX ON eExpression TO IDXFileName | TAG TagName [BINARY]
   [COLLATE cCollateSequence] [OF CDXFileName] [FOR lExpression]
   [COMPACT] [ASCENDING | DESCENDING] [UNIQUE | CANDIDATE] [ADDITIVE]

Parameters

eExpression

Specifies an index expression that determines the order in which Visual FoxPro displays and processes records. eExpression can be a simple expression, such as the name of one or more fields from the current table, or a more complex expression containing Visual FoxPro functions, constants, and so on. Visual FoxPro generates index keys based on eExpression and stores them in an index file that you specify. The index file does not affect the physical order of how records are stored in the table.
Note:
For a standalone index (.idx) file, the length of an index key must be between 1 and 100 characters. For a compound index (.cdx) file, the length of an index key must be between 1 and 240 characters.

With some collating sequences, or when using double-byte character set (DBCS) characters, each character in the index expression uses two characters in the index key. In these cases, the length of the index expression is limited to 50 or 120 characters, respectively.
Caution:
Using RECNO( ) in the index expression for a table buffered cursor corrupts the index and causes an endless loop.

For more information about index expressions, see Index Creation Based on Expressions and Considerations for Creating Index Expressions.
TO IDXFileName

Specifies the name of a standalone index (.idx) file for storing a single index key as generated by eExpression.
Tip:
You can override the default index file name extension by including a different extension or by changing the default index extension in the Visual FoxPro configuration file. When creating index files, observe standard Windows rules for naming files, which include long file names.

For more information about index files, see Visual FoxPro Index Files.
TAG TagName

Specifies the name, or tag, for the index generated by eExpression and stored in a compound index (.cdx) file. Tag names must begin with a letter or an underscore (_) and can consist of any combination of up to 10 letters, digits, or underscore characters.
Note:
The number of tags in a .cdx file is limited only by available memory and disk space. If a .cdx file for the table already exists and is open, issuing INDEX with TAG TagName adds a tag to the open .cdx file. If you create an index tag without specifying the name of the index file, Visual FoxPro adds the tag automatically to the table's structural .cdx file.

For more information about index files, see Visual FoxPro Index Files.
[COLLATE cCollateSequence]

Specifies a collation sequence other than the default setting, MACHINE. cCollateSequence must be a valid Visual FoxPro collation sequence. For more information about setting collation sequences, see Optimizing International Applications and SET COLLATE Command.
[OF CDXFileName]

Specifies the name of a nonstructural compound index (.cdx) file for storing the index, or tag, as generated by eExpression. Omitting this clause creates a structural .cdx file, while including this clause creates a nonstructural .cdx file. For more information about index files, see Visual FoxPro Index Files.
[FOR lExpression]

Specifies a filter expression that selects only those records that match the filter expression for display and access.
Tip:
If lExpression can be optimized, Rushmore technology optimizes the FOR clause in the INDEX command. For best performance, use an expression that can be optimized in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

For more information about filter expressions, see How to: Filter Data.
[COMPACT]

Creates a compact index (.idx) file. Compact .idx files are small and more quickly accessible.
Note:
When creating a compound index (.cdx) file, it is not necessary to include COMPACT. Compound index files are always compact.

For more information, see How to: Create Less Frequently Used Indexes.
[ASCENDING | DESCENDING]

Specifies an order for displaying and accessing records indexed by a compound index (.cdx) file. ASCENDING specifies an ascending order for displaying and accessing records. By default, Visual FoxPro displays and accesses records in ascending order. However, you can include ASCENDING as a reminder of how records are displayed. DESCENDING specifies a descending order for displaying and accessing records.
Note:
You cannot use DESCENDING when creating standalone index (.idx) files; however, you can specify a descending order for an .idx file using the SET INDEX and SET ORDER commands. For more information, see SET INDEX Command and SET ORDER Command.

[UNIQUE | CANDIDATE]

Creates a unique or candidate index. UNIQUE stores the matching index key only for the first record that matches the specified index expression. The index key is stored as the only key in a standalone (.idx) file or as an index tag in a compound index (.cdx) file. Any other index keys for records that match the index expression are excluded from the index file.
Note:
Using UNIQUE does not prevent duplicate records from being entered in the table. It only prevents duplicate index keys from being added to the index file. When a duplicate record is changed so that its index key is changed for an active UNIQUE index or index tag, the index or index tag is updated. However, Visual FoxPro cannot display or access the next duplicate record with the original index key until you use the REINDEX command to reindex the file. For more information, see REINDEX Command.

Using UNIQUE is identical to executing SET UNIQUE ON before issuing INDEX or REINDEX. For more information, see SET UNIQUE Command. CANDIDATE stores an index tag to a structural compound index (.cdx) file only; otherwise, Visual FoxPro generates an error message.
Note:
Candidate indexes do not permit duplicate values in fields. If you create a candidate index for one or more fields that contain duplicate values, Visual FoxPro generates an error.

For more information about candidate indexes, see Visual FoxPro Index Types. For more information about index files, see Visual FoxPro Index Files.
[ADDITIVE]

Keeps open any previously opened index files. Omitting the ADDITIVE clause closes any previously opened index files except the structural compound index (.cdx) files.
Note:
The number of index files that you can keep open is limited only by memory and system resources. In Visual FoxPro, the FILES setting in the Windows Config.sys configuration file determines the total number of files you can open.

[BINARY]

Creates a binary index. For more information about binary indexes, see Visual FoxPro Index Types.
Note:
When specifying an index expression for eExpression, you must specify a valid logical expression that does not evaluate to a null value. If the index expression for a binary index is changed so that it evaluates to a null value, Visual FoxPro generates an error.

When using binary indexes, you cannot use the FOR clause to specify a filter expression or the ASCENDING, DESCENDING, UNIQUE, or CANDIDATE keywords. Visual FoxPro does not support the SET ORDER command when setting to a binary index tag. If you attempt to set order to a binary tag, Visual FoxPro generates an error, and the current order remains at its prior setting. Visual FoxPro does not support SEEK operations or standalone single-key (.idx) indexes with binary indexes.

Remarks

A structural .cdx file can become dissociated from its table if the index file cannot be located, is deleted, or renamed. When you open a table that has a dissociated structural .cdx file, a dialog box appears. When you click Cancel in the dialog box, the table does not open.

Caution:
Clicking Ignore opens the table; however, it also removes the table header flag that indicates that an associated structural (.cdx) file exists.

Tip:
To reassaociate the structural .cdx file, issue the following command and specify the name of the table as TableName and the name of the dissociated structural .cdx file as CDXFileName.

Copy Code
USE TableName INDEX CDXFileName

If the table has been modified, make sure to index the table again.

To report the number of records indexed during the indexing process, set the SET TALK command to ON. To specify the record interval displayed during indexing, use the SET ODOMETER command. For more information, see SET TALK Command and SET ODOMETER Command.

To obtain information about open index files, use the DISPLAY STATUS Command. DISPLAY STATUS lists the names of all open index files, their types, their index expressions, and the name of the master, or controlling, index file or tag. The number of index files that you can open is limited only by memory and system resources.

Example

Example 1

The following example closes all databases with the CLOSE DATABASES command and opens the Visual FoxPro sample database, TestData.dbc, with the OPEN DATABASE command and the Customer table with the USE command.

The INDEX command creates a standalone index (.idx) file named Complist based on the Company field. The CLEAR command clears the Visual FoxPro main window, and the DISPLAY STATUS command displays information about the index file, Complist.

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer
INDEX ON Company TO Complist
CLEAR
DISPLAY STATUS

Example 2

The following example closes all databases with the CLOSE DATABASES command and opens the Visual FoxPro sample database, TestData.dbc, with the OPEN DATABASE command and the Customer table with the USE command.

The INDEX command creates a standalone index (.idx) file named CityComp from a substring of the first five characters of the City field and the first six characters of the Company field using the SUBSTR( ) function. This index file orders records in the table primarily according to the City field and secondarily according to the Company field. Visual FoxPro clears the main Visual FoxPro window with the CLEAR command, and the DISPLAY STATUS command displays information about the index file, CityComp.

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer
INDEX ON SUBSTR(City,1,5) + SUBSTR(Company,1,6) TO CityComp
CLEAR
DISPLAY STATUS

Example 3

The following example closes all databases with the CLOSE DATABASES command, and opens the Visual FoxPro sample database, TestData.dbc, with the OPEN DATABASE command and the Customer table with the USE command.

The INDEX commands create a structural compound index (.cdx) file with two tags: one based on the Address field named Address and one based on the Company field named Company. If a structural compound index file was previously created for the table, the two tags are added to the existing file.

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer
INDEX ON company TAG company
INDEX ON address TAG address
CLEAR
DISPLAY STATUS

See Also

Other Resources

Commands
Working with Table Indexes
CANDIDATE( ) Function
PRIMARY( ) Function
UNIQUE( ) Function
ATAGINFO( ) Function
CDX( ) Function
COPY INDEXES Command
COPY TAG Command
DELETE TAG Command
DESCENDING( ) Function
FOR( ) Function
INDEXSEEK( ) Function
KEY( ) Function
MDX( ) Function
NDX( ) Function
ORDER( ) Function
SORT Command
SYS(14) - Index Expression
SYS(21) - Controlling Index Number
SYS(22) - Controlling Tag or Index Name
SYS(2021) - Filtered Index Expression
TAG( ) Function
TAGCOUNT( ) Function


KEYBOARD Command

Visual FoxPro 9.0 Language Reference
KEYBOARD Command
See Also

Places the specified character expression in the keyboard buffer.

Characters remain in the buffer until Visual FoxPro looks for keyboard input. At that point, the characters are read and output as if they were entered directly from the keyboard. You can use KEYBOARD to create self-running demonstration systems that showcase your applications.

KEYBOARD cKeyboardValue [PLAIN] [CLEAR]

Parameters

cKeyboardValue

Specifies the character expression that is placed in the keyboard buffer. The character expression can be a character string, a key label, a set of key labels, or a user-defined function that returns a character expression. For a listing of key labels, see ON KEY LABEL.
Note:
If cKeyboardValue is a key label, it must be enclosed in braces and single or double quotation marks. For example:

Copy Code
KEYBOARD "{CTRL+LEFTARROW}"
To insert a pause in the keyboard buffer, you can also include the PAUSE nSeconds option as part of the argument for cKeyboardValue where nSeconds specifies the number of seconds to pause. For example, the following lines of code insert a pause of five seconds between the strings "Hello," and "World":
Copy Code
KEYBOARD "Hello,{PAUSE 5} World"
PLAIN

If you have keyboard macros defined or active ON KEY LABEL commands, you can include PLAIN to bypass these key assignments. PLAIN fills the keyboard with the literal key character, not the key assignment. For example, if you have assigned a command to the A key with ON KEY LABEL and A is included in cKeyboardValue, use PLAIN to place the letter A in the keyboard buffer. The ON KEY LABEL command assigned to A is not executed.
CLEAR

Empties the keyboard buffer before the keyboard buffer is filled with cKeyboardValue.

Remarks

You can fill the keyboard buffer with up to 128 characters. Once the keyboard buffer is full, additional characters are ignored.

See Also

Other Resources

CHRSAW( ) Function
ON KEY LABEL Command
PLAY MACRO Command
SET FUNCTION Command
Commands
Language Reference


LABEL Command

Visual FoxPro 9.0 Language Reference
LABEL Command
See Also

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 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 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.

See Also

Reference

ReportListener Object
SET REPORTBEHAVIOR Command
REPORT FORM Command
The Preview Container API

Other Resources

Working with Reports
Commands
Language Reference


LIST Commands

Visual FoxPro 9.0 Language Reference
LIST Commands
See Also

Displays table or environment information without pausing the main Visual FoxPro or user-defined window. There are multiple versions of the syntax.

LIST [FIELDS FieldList] [Scope] [FOR lExpression1]
   [WHILE lExpression2] [OFF] [NOCONSOLE] [NOOPTIMIZE]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]
LIST FILES [ON Drive] [LIKE FileSkeleton]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]
LIST MEMORY [LIKE FileSkeleton] [NOCONSOLE]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]
LIST STATUS [NOCONSOLE]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]
LIST STRUCTURE [IN nWorkArea | cTableAlias] [NOCONSOLE]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]

Remarks

The LIST commands are identical to the DISPLAY commands except for the following differences:

  • LIST displays information without pausing, whereas DISPLAY displays the first screen of information and then pauses. For more information, see DISPLAY Command.

  • ADDITIVE clause appends to the end of the named file. If you omit ADDITIVE, the file is overwritten with the value of the expression.

  • The scope for LIST defaults to ALL records.

  • LIST does not display records flagged for deletion when SET DELETED is ON. For more information, see SET DELETED Command.

See Also

Other Resources

LIST CONNECTIONS Command
LIST DATABASE Command
LIST DLLS Command
LIST OBJECTS Command
LIST PROCEDURES Command
LIST TABLES Command
LIST VIEWS Command
Commands
Language Reference


LIST CONNECTIONS Command

Visual FoxPro 9.0 Language Reference
LIST CONNECTIONS Command
See Also Example

Continuously displays information about the named connections in the current database.

LIST CONNECTIONS [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]   [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs output from LIST CONNECTIONS to a printer. In Visual FoxPro, you can include the optional PROMPT clause to display a Print dialog box before printing starts. Place PROMPT immediately after TO PRINTER.
TO FILE FileName

Directs output from LIST CONNECTIONS to the file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

The information displayed includes the names of named connections, datasources, and connection strings in the current database. Use DBGETPROP( ) to return additional information about connections in the current database.

Example

The following example assumes an ODBC data source called MyFoxSQLNT is available. The testdata database is opened, and a connection named Myconn is created. LIST CONNECTIONS is used to list the named connections in the database.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')

CREATE CONNECTION Myconn DATASOURCE "MyFoxSQLNT" USERID "<userid>" PASSWORD "<password>"
CLEAR
LIST CONNECTIONS     && Lists named connections in the database

See Also

Other Resources

CREATE CONNECTION Command
DELETE CONNECTION Command
DBGETPROP( ) Function
DISPLAY CONNECTIONS Command
RENAME CONNECTION Command
Commands
Language Reference


LIST DATABASE Command

Visual FoxPro 9.0 Language Reference
LIST DATABASE Command
See Also Example

Continuously displays information about the current database.

LIST DATABASE [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]   [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs output from LIST DATABASE to a printer. In Visual FoxPro, you can include the optional PROMPT clause to display a Print dialog box before printing starts. Place PROMPT immediately after TO PRINTER.
TO FILE FileName

Directs output from LIST DATABASE to the file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

Use DBGETPROP( ) to return additional information about the current database.

Example

This example creates a database named people. A table named friends is created and is automatically added to the database. DISPLAY TABLES is used to display the tables in the database, and LIST DATABASES is used to list information about the tables in the database.
Copy Code
CREATE DATABASE people
CREATE TABLE friends (FirstName C(20), LastName C(20))
CLEAR
DISPLAY TABLES  && Displays tables in the database
LIST DATABASE  && Lists table information

See Also

Other Resources

DISPLAY DATABASE Command
CREATE DATABASE Command
DBGETPROP( ) Function
Commands
Language Reference


LIST DLLS Command

Visual FoxPro 9.0 Language Reference
LIST DLLS Command
See Also

Continuously displays information about shared library functions registered in Visual FoxPro with DECLARE - DLL.

LIST DLLS [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]   [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs output from LIST DLLS to a printer. In Visual FoxPro, you can include the optional PROMPT clause to display a Print dialog box before printing starts. Place PROMPT immediately after TO PRINTER.
TO FILE FileName

Directs output from LIST DLLS to the file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or the active user-defined window.

See Also

Other Resources

DECLARE - DLL Command
DISPLAY DLLS Command
SET SAFETY Command
Commands
Language Reference


LIST OBJECTS Command

Visual FoxPro 9.0 Language Reference
LIST OBJECTS Command
See Also Example

Continuously displays information about an object or a group of objects.

LIST OBJECTS   [LIKE cObjectSkeleton]
   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]   [NOCONSOLE]

Parameters

LIKE cObjectSkeleton

Displays information about a subset of objects. cObjectSkeleton is an object specification skeleton that supports wildcards (* and ?). For example, to continuously display all objects that begin with A, use the following command:
Copy Code
LIST OBJECTS LIKE A*
TO PRINTER [PROMPT]

Directs output from LIST OBJECTS to a printer. You can include the optional PROMPT clause to display a Print dialog box before printing starts. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from LIST OBJECTS to the disk file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

LIST OBJECTS displays the following information about all existing objects:

  • Properties and their values.

  • Methods.

  • Member objects and the class or subclass on which they are based.

  • Class or subclass on which objects are based.

  • Class hierarchy for the objects.

LIST OBJECTS fills the entire main Visual FoxPro window without pausing.

Example

The following example uses DEFINE CLASS and CREATEOBJECT( ) to create two custom classes named FormChild and FormGrandChild from the Visual FoxPro Form base class. LIST OBJECTS lists information about the objects and their properties.
Copy Code
CLEAR
frmMyForm = CREATEOBJECT("FormGrandChild")
LIST OBJECTS LIKE frm*
RELEASE frmMyForm

DEFINE CLASS FormChild AS FORM
ENDDEFINE

DEFINE CLASS FormGrandChild AS FormChild
ENDDEFINE

See Also

Other Resources

DISPLAY OBJECTS Command
DEFINE CLASS Command
CREATEOBJECT( ) Function
Commands
Language Reference


LIST PROCEDURES Command

Visual FoxPro 9.0 Language Reference
LIST PROCEDURES Command
See Also Example

Continuously displays the names of stored procedures in the current database.

LIST PROCEDURES   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]   [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs the information returned from LIST PROCEDURES to a printer. You can include PROMPT to display a Print dialog box before printing starts. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from LIST PROCEDURES to the disk file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

Stored procedures are created with MODIFY PROCEDURES.

Example

The following example opens the testdata database and uses LIST PROCEDURES to list the stored procedures (if any) in the database.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')

CLEAR
LIST PROCEDURES  && Lists stored procedures in the database

See Also

Other Resources

APPEND PROCEDURES Command
COPY PROCEDURES Command
CREATE DATABASE Command
DISPLAY DATABASE Command
DISPLAY PROCEDURES Command
MODIFY PROCEDURE Command
Commands
Language Reference


LIST TABLES Command

Visual FoxPro 9.0 Language Reference
LIST TABLES Command
See Also Example

Displays without pausing all tables and information about the tables contained in the current database.

LIST TABLES   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]
   [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs the information returned from LIST TABLES to a printer. You can include PROMPT to display a Print dialog box before printing starts. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from LIST TABLES to the disk file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

The information returned includes the table names and paths and is a subset of the information shown using LIST STATUS. However, the information displayed using LIST TABLES contains only table-related information and displays the information regardless of whether the tables are open.

Example

The following example opens the customer table in the testdata database. LIST TABLES is used to list information about the tables in the database.
Copy Code
CLOSE DATABASES
SET PATH TO (HOME(2) + 'data\')   && Sets path to database
OPEN DATABASE testdata  && Open testdata database
CLEAR
LIST TABLES  && Lists information about tables in the database

See Also

Other Resources

ADD TABLE Command
CLOSE DATABASES Command
CREATE DATABASE Command
DISPLAY TABLES Command
OPEN DATABASE Command
REMOVE TABLE Command
Commands
Language Reference


LIST VIEWS Command

Visual FoxPro 9.0 Language Reference
LIST VIEWS Command
See Also Example

Displays without pausing information about SQL views in the current database.

LIST VIEWS   [TO PRINTER [PROMPT] | TO FILE FileName [ADDITIVE]]   [NOCONSOLE]

Parameters

TO PRINTER [PROMPT]

Directs the information returned from LIST VIEWS to a printer. You can include PROMPT to display a Print dialog box before printing starts. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs output from LIST VIEWS to the disk file specified with FileName. If the file already exists and SET SAFETY is ON, Visual FoxPro displays a prompt asking if you want to overwrite the file.
ADDITIVE

Appends to the end of the named file. If you omit ADDITIVE, then the file is overwritten with the value of the expression.
NOCONSOLE

Suppresses output to the main Microsoft Visual FoxPro window or to the active user-defined window.

Remarks

LIST VIEWS displays the names of SQL views in the current database, and indicates if the SQL views are based on local or remote tables. Use DBGETPROP( ) to return additional information about SQL views in the current database.

SQL views are created with CREATE SQL VIEW.

Example

The following example opens the testdata database. CREATE SQL VIEW is used to create a local SQL view named myview. The View Designer is displayed, allowing you to specify tables and conditions for the SQL view. After you save the SQL view you create, information about the SQL views in the database is listed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
CREATE SQL VIEW myview

CLEAR
LIST VIEWS

See Also

Other Resources

Commands
CREATE DATABASE Command
CREATE SQL VIEW Command
DBGETPROP( ) Function
DISPLAY DATABASE Command
DISPLAY VIEWS Command


LOCAL Command

Visual FoxPro 9.0 Language Reference
LOCAL Command
See Also

Creates local variables and variable arrays. There are two versions of the syntax.

LOCAL Var1 [ AS type [ OF ClassLib ] ] | [ ArrayName1( nRows1 [, nColumns1 ] ) [ AS type [ OF ClassLib ] ] ]
    [, Var2 [ AS type [ OF ClassLib ] ] | [, ArrayName2( nRows2 [, nColumns2 ] ) [ AS type [ OF ClassLib ] ] ]
LOCAL [ ARRAY ] ArrayName1( nRows1 [, nColumns1 ] ) [ AS type [OF ClassLib ] ]
    [, ArrayName2( nRows2 [, nColumns2 ] ) [ AS type [ OF ClassLib ] ] ]

Parameters

LOCAL VarList

Specifies one or more local variables to create. Use commas to separate multiple items in VarList. The single letters A through J and M are reserved and cannot be used as variable names.
[ ARRAY ] ArrayName1( nRows1[, nColumns1 ] ) [, ArrayName2( nRows2[, nColumns2 ] ) ] ...

Specifies one or more local arrays to create. For more information about arrays, see DIMENSION Command.
[ AS type[ OF ClassLib] ]

Specifies the data type of the variable or array and the class library containing the type description of type on which this variable or array is based. When you specify a valid class name, Visual FoxPro uses the type library, if you specify a ProgID, or instantiates an object to get a list of properties, methods, and events. If the specified class name is not found, Visual FoxPro displays a list box of available classes. You can use the AS clause to implement strong typing. IntelliSense functionality is available for object and variable references only when they are strongly typed. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.

Remarks

You can use and modify local variables and variable arrays only within the procedure or function in which they are created and cannot be accessed by higher or lower-level programs. After the procedure or function containing the local variables and arrays completes execution, local variables and arrays are released.

Variables and arrays created with LOCAL are initialized to False (.F.).

You must declare any variables or arrays that you want local prior to assigning values to them. If you assign a value to a variable or array in a program and later declare it as local using LOCAL, Visual FoxPro generates a syntax error.

You can pass local variables by reference.

You cannot abbreviate LOCAL because LOCAL and LOCATE have the same first four letters.

See Also

Other Resources

PRIVATE Command
PUBLIC Command
Commands


LOCATE Command

Visual FoxPro 9.0 Language Reference
LOCATE Command
See Also Example

Sequentially searches the table for the first record that matches the specified logical expression.

LOCATE [FOR lExpression1]   [Scope]   [WHILE lExpression2]   [NOOPTIMIZE]

Parameters

FOR lExpression1

Sequentially searches the current table for the first record that matches the logical expression lExpression1. Rushmore Query Optimization optimizes a query created with LOCATE FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
Scope

Specifies a range of records to locate. Only the records that fall within the range are located. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. Commands that include Scope operate only on the table in the active work area. The default scope for LOCATE is ALL records.
WHILE lExpression2

Specifies a condition whereby records are searched for as long as the logical expression lExpression2 evaluates to true (.T.).
NOOPTIMIZE

Disables Rushmore Query Optimization of LOCATE. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

Remarks

The table doesn't have to be indexed.

If you use the LOCATE command without the FOR expression, Visual FoxPro positions the record pointer at the first logical record. This is faster than using GO TOP when a filter is in use or when DELETED is ON.

If LOCATE finds a matching record, you can use RECNO( ) to return the number of the matching record. If a matching record is found, FOUND( ) returns true (.T.), and EOF( ) returns false (.F.). If SET TALK is ON, the record number of the matching record is displayed.

After LOCATE finds a matching record, you can issue CONTINUE to search the remainder of the table for additional matching records. When CONTINUE is executed, the search process resumes, starting with the record immediately following the matching record. You can issue CONTINUE repeatedly until the end of the scope or the end of the table is reached.

If a match isn't found, RECNO( ) returns the number of records in the table plus 1, FOUND( ) returns false (.F.), and EOF( ) returns true (.T.).

LOCATE and CONTINUE are specific to the current work area. If another work area is selected, the original search process can be continued when the original work area is reselected.

Example

In the following example, records for customers from Germany are located. The total count is then displayed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Open Customer table
SET TALK OFF

STORE 0 TO gnCount
LOCATE FOR ALLTRIM(UPPER(customer.country)) = 'GERMANY'
DO WHILE FOUND( )
   gnCount = gnCount + 1
   ? company
   CONTINUE
ENDDO

? 'Total companies Germany: '+ LTRIM(STR(gnCount))

See Also

Other Resources

Commands
CONTINUE Command
EOF( ) Function
FIND Command
FOUND( ) Function
INDEXSEEK( ) Function
RECNO( ) Function
SEEK Command
SEEK( ) Function
SET OPTIMIZE Command


LOOP Command

Visual FoxPro 9.0 Language Reference
LOOP Command
See Also

Returns program control directly to the beginning of a looping structure.

LOOP

Remarks

You can place LOOP anywhere between DO WHILE and ENDDO, anywhere between FOR and ENDFOR or FOR EACH and ENDFOR, or anywhere between SCAN and ENDSCAN.

The LOOP command returns control directly to the DO WHILE, FOR, or FOR EACH clause without executing the statements between LOOP and ENDDO or ENDFOR. The counter is incremented or decremented as if the END... statement were reached.

See Also

Other Resources

Commands
DO WHILE ... ENDDO Command
FOR ... ENDFOR Command
FOR EACH ... ENDFOR Command
SCAN ... ENDSCAN Command
EXIT Command


LPARAMETERS Command

Visual FoxPro 9.0 Language Reference
LPARAMETERS Command
See Also

Assigns data passed from a calling program to local variables or arrays.

LPARAMETERS Parameter1 [AS type [OF ClassLib]]
   [, Parameter2 [AS type [OF ClassLib]]]

Parameters

LPARAMETERS ParameterList

Specifies one or more local variable or array names to assign data from the calling program. Use commas to separate multiple parameters in ParameterList. You can pass a maximum of 26 parameters.
Note:
The LPARAMETERS statement must specify at least as many parameters as used by the call to the program, procedure, or function containing the LPARAMETERS statement. If more variables or arrays are listed in the LPARAMETERS statement than are passed by the calling program, the remaining variables or arrays in the LPARAMETERS statement are initialized to False (.F.).

[ AS type [OF ClassLib] ]

Specifies the data type of the local variable or array and the class library containing the type description of type which this variable or array is based on. You can use the AS clause to implement strong typing. IntelliSense functionality is available for object and variable references only when they are strongly typed. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.

Remarks

When LPARAMETERS is used with a program, procedure, or user-defined function called with the DO command, it must be the first executable statement in the called program, procedure, or user-defined function.

By default, the WITH clause in the DO command passes variables and arrays by reference to procedures. By default, Visual FoxPro passes arguments by value to user-defined functions.

Note:
To pass entire arrays to functions, you must pass them by reference. If you do not pass arrays to functions by reference, only the first element passes to the function. For more information, see How to: Pass Data to Parameters by Reference.

For more information, see Passing Data to Parameters and Parameters in Procedures and Functions.

See Also

Other Resources

PARAMETERS Command
FUNCTION Command
PROCEDURE Command
DO Command
PARAMETERS( ) Function
PCOUNT( ) Function
Commands


MD | MKDIR Command

Visual FoxPro 9.0 Language Reference
MD | MKDIR Command
See Also Example

Creates a new directory or subdirectory on disk.

MD cPath | MKDIR cPath

Parameters

cPath

Specifies a directory or a path (with a drive designator and directories). If cPath is a directory without a drive designator, the directory is created as a subdirectory of the current Microsoft Visual FoxPro default directory.

Remarks

Visual FoxPro generates an error message if you attempt to create a directory that already exists.

Example

The following example uses MKDIR to create a new directory named mytstdir, then CHDIR is used to change to the new directory. GETDIR( ) is used to display the directory structure, and then RMDIR is used to remove the newly created directory. GETDIR( ) is used to display the directory structure again.
Copy Code
SET DEFAULT TO HOME( )  && Restore Visual FoxPro directory
MKDIR mytstdir  && Create a new directory
CHDIR mytstdir  && Change to the new directory
= GETDIR( )  && Display the Select Directory dialog box
SET DEFAULT TO HOME( )  && Restore Visual FoxPro directory
RMDIR mytstdir  && Remove the new directory
= GETDIR( )  && Display the Select Directory dialog box

See Also

Other Resources

Commands
CD | CHDIR Command
DIRECTORY Command
DIRECTORY( ) Function
GETDIR( ) Function
HOME( ) Function
RD | RMDIR Command
SET DEFAULT Command
SET PATH Command
SYS(5) - Default Drive
SYS(2003) - Current Directory
SYS(2004) - Visual FoxPro Start Directory


MENU Command

Visual FoxPro 9.0 Language Reference
MENU Command
See Also

Included for backward compatibility. Use the Menu Designer instead.

See Also

Other Resources

Language Reference


MODIFY CLASS Command

Visual FoxPro 9.0 Language Reference
MODIFY CLASS Command
See Also

Opens the Class Designer, making it possible for you to modify an existing class definition or create a new class definition.

MODIFY CLASS ClassName [OF ClassLibraryName1]
   [AS cBaseClassName [FROM ClassLibraryName2]]
   [NOWAIT] [METHOD MethodName] [SAVE]

Parameters

ClassName

Specifies the name of the class definition to modify or create.
OF ClassLibraryName1

Specifies the name of the .vcx visual class library containing the class definition. If you are creating a new class definition and the .vcx visual class library already exists, the class definition is added to it. A .vcx file extension is assumed for the visual class library. Be sure to include the file extension if the visual class library you specify has a file extension other than .vcx. If the .vcx visual class library you specify is currently in the SET CLASSLIB search list, the visual class library is removed from the search list.
AS cBaseClassName

Specifies the class on which the class definition is based. You can specify any Visual FoxPro base class except Column and Header. You can also specify a user-defined class if you include the FROM ClassLibraryName2 clause that specifies the name of the visual class library (.vcx) file containing the user-defined class. If you omit AS cBaseClassName, the class definition is based on the Visual FoxPro FormSet base class.
FROM ClassLibraryName2

Specifies the name of the .vcx visual class library containing the user-defined class specified with cBaseClassName.
METHOD MethodName

Specifies an event or method for which the Code window is opened in the Class Designer. The METHOD clause makes it possible for you to immediately begin editing event or method code in the Class Designer. MethodName supports the Visual FoxPro object syntax. For example, to immediately edit the Click event code for a text box named txtFirstName in the class named MyClass in a visual class library named MyClassLibrary, use the following command:
Copy Code
MODIFY CLASS MyClass OF MyClassLibrary METHOD txtFirstName.Click
If you only include an event or method name in the METHOD clause, the Code window is opened for the class's event or method. For example, to immediately edit the Click event code for a class named MyClass in a visual class library named MyClassLibrary, use the following command:
Copy Code
MODIFY CLASS MyClass OF MyClassLibrary METHOD Click
NOWAIT

Continues program execution after the Class Designer is opened. The program doesn't wait for the Class Designer to be closed, but continues execution on the program line immediately following the line that contains MODIFY CLASS NOWAIT. If you omit NOWAIT when MODIFY CLASS is issued in a program, the Class Designer is opened and program execution pauses until the Class Designer is closed. NOWAIT is effective only from within a program. It has no effect on MODIFY CLASS when issued from the Command window. If NOWAIT is included with the METHOD clause, be sure to place NOWAIT before the METHOD clause or NOWAIT will be ignored.
SAVE

Leaves the Class Designer open after another window is activated. If you omit SAVE, the Class Designer is closed when another window is activated. Including SAVE has no effect when issued from the Command window.

Remarks

Use MODIFY CLASS to modify an existing class definition or to create a new class definition and save it in a .vcx visual class library. You can open the .vcx visual class library with SET CLASSLIB, making it possible for you to access the class definitions within the .vcx visual class library.

See Also

Other Resources

Commands
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
RELEASE CLASSLIB Command
SET CLASSLIB Command


MODIFY COMMAND Command

Visual FoxPro 9.0 Language Reference
MODIFY COMMAND Command
See Also

Opens an editing window so you can modify or create a program file.

MODIFY COMMAND [FileName | ?] [NOEDIT] [NOMENU] [NOWAIT]
   [RANGE nStartCharacter, nEndCharacter] [[WINDOW WindowName1]
   [IN [WINDOW] WindowName2 | IN SCREEN]] [AS nCodePage] [SAME]
   [SAVE]

Parameters

FileName

Specifies the file name for the program to open or create. If you don't specify an extension for a new program file, Visual FoxPro automatically assigns a .prg extension. MODIFY COMMAND supports a file skeleton that contains the asterisk (*) and question mark (?) wildcards. An editing window is opened for each program whose file name matches the file skeleton. If you omit the file name, an editing window opens for a file initially named Prog1.prg. When you close the editing window, you can save the file with a different name.
?

Displays the Open dialog box. Choose one of the existing programs or enter the name of a new program to create.
NOEDIT

Specifies that the program file can't be changed, but can be viewed and copied to the Clipboard.
NOMENU

Removes the Format menu title from the Visual FoxPro system menu bar, preventing changes to font, font size, line spacing, and indentation.
NOWAIT

Continues program execution after the editing window is opened. The program doesn't wait for the editing window to be closed, but continues execution on the program line immediately following the line that contains MODIFY COMMAND NOWAIT. If you omit NOWAIT when MODIFY COMMAND is used in a program, an editing window is opened and program execution pauses until the editing window is closed. NOWAIT is effective only from within a program. It has no effect on MODIFY COMMAND when issued from the Command window. An implicit NOWAIT occurs if you open more than one editing window with a single MODIFY COMMAND command. For example:
Copy Code
MODIFY COMMAND *.PRG.
RANGE nStartCharacter, nEndCharacter

Specifies a range of characters selected when the editing window is opened. Characters are selected starting at the position specified with nStartCharacter up to (but not including) the character position of nEndCharacter. If nStartCharacter is equal to nEndCharacter, no characters are selected, and the cursor is placed at the position specified with nStartCharacter.
WINDOW WindowName1

Specifies a window whose characteristics the editing window takes on. For example, if the window is created with the FLOAT option of DEFINE WINDOW, the editing window can be moved. The window need not be active or visible, but it must be defined.
IN [WINDOW] WindowName2

Specifies a parent window in which the editing window is opened. The editing window doesn't assume the characteristics of the parent window and cannot be moved outside the parent window. If the parent window is moved, the editing window moves with it. The parent window must first be defined with DEFINE WINDOW, and must be visible, to access the editing window.
IN SCREEN

Explicitly opens the editing window in the main Visual FoxPro window, after it has been placed in a parent window. An editing window is placed in a parent window by including the IN WINDOW clause.
AS nCodePage

Automatically converts accented characters in a program file created on another Visual FoxPro platform. The numeric expression nCodePage specifies the code page of the Visual FoxPro platform on which the program file was created. The file is saved in this code page unless you choose Save As from the File menu to save the file in a different code page.
SAME

Prevents the editing window from coming forward as the active window. If the editing window is hidden, it is displayed but doesn't become the active window.
SAVE

Leaves the editing window open after another window is activated. If you omit SAVE, the editing window is closed when another window is activated. Including SAVE has no effect when issued from the Command window.

Remarks

When modifications are made to a program file, the updated file is written to disk. In Visual FoxPro, a backup file with a .bak extension is created if you select the Make Backup Copy check box on the Edit Properties dialog box, which appears when you choose Properties from the Edit menu.

The built-in Visual FoxPro editor is used unless you specify an external editor with TEDIT in your configuration file.

See Also

Other Resources

Commands
* Command
&& Command
DO Command
MODIFY FILE Command
NOTE Command
EDITSOURCE( ) Function


MODIFY CONNECTION Command

Visual FoxPro 9.0 Language Reference
MODIFY CONNECTION Command
See Also Example

Displays the Connection Designer, making it possible for you to interactively modify an existing named connection stored in the current database.

MODIFY CONNECTION [ConnectionName | ?]

Parameters

ConnectionName

Specifies the name of the connection to modify.
?

Displays the Open dialog box from which you can choose an existing named connection to modify.

Remarks

If you omit the optional arguments, the Open dialog box is displayed, making it possible for you to specify an existing named connection to modify. The Connection Designer is displayed after you choose a named connection to modify.

Example

The following example assumes an ODBC data source called MyFoxSQLNT is available. The testdata database is opened, and a connection named Myconn is created. MODIFY CONNECTION is used to displays the Connection Designer so you can modify the connection.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')

CREATE CONNECTION Myconn DATASOURCE "MyFoxSQLNT" USERID "<userid>" PASSWORD "<password>"
MODIFY CONNECTION Myconn && Displays named connections in the database

See Also

Other Resources

Commands
CREATE CONNECTION Command
DELETE CONNECTION Command
OPEN DATABASE Command
RENAME CONNECTION Command


MODIFY DATABASE Command

Visual FoxPro 9.0 Language Reference
MODIFY DATABASE Command
See Also Example

Opens the current database in the Database Designer so you can visually modify the database.

MODIFY DATABASE [DatabaseName | ?] [NOWAIT] [NOEDIT]

Parameters

[DatabaseName | ?]

Specifies the name of the database to modify or displays the Open dialog box so you can browse for and select a database.
[NOWAIT]

Continues program execution after the Database Designer opens. The program does not wait for the Database Designer to close but continues execution on the program line immediately following the line that contains MODIFY DATABASE NOWAIT. Omitting NOWAIT pauses program execution until the Database Designer closes.
Note:
NOWAIT is valid only from within a program. When included with MODIFY DATABASE in the Command window, NOWAIT has no effect.

[NOEDIT]

Prevents changes to the database.

Remarks

Calling MODIFY DATABASE triggers the dbc_Activate event. For more information, see dbc_Activate Event.

For more information, see Database Designer and How to: Open Databases.

Example

The following example closes all open databases, sets a path to the Visual FoxPro ..\Samples\Northwind directory, and opens the Northwind sample database in the Database Designer:
Copy Code
CLOSE DATABASES
SET PATH TO (HOME(2) + 'Northwind\')
MODIFY DATABASE Northwind

See Also

Other Resources

Commands
CLOSE DATABASES Command
CREATE DATABASE Command
DELETE DATABASE Command
OPEN DATABASE Command


MODIFY FILE Command

Visual FoxPro 9.0 Language Reference
MODIFY FILE Command
See Also

Opens an editing window so you can modify or create a text file.

MODIFY FILE [FileName | ?] [NOEDIT] [NOMENU] [NOWAIT]
   [RANGE nStartCharacter, nEndCharacter] [[WINDOW WindowName1]
   [IN [WINDOW] WindowName2 | IN SCREEN]] [AS nCodePage] [SAME] [SAVE]

Parameters

FileName

Specifies the file name for the text file. If you don't specify an extension for a new text file, Visual FoxPro automatically assigns a .txt extension. MODIFY FILE supports a file skeleton that can contain the asterisk (*) and question mark (?) wildcards. An editing window is opened for each text file whose name matches the file skeleton. If you omit the file name, an editing window opens for a file initially named FILE1. When you close the editing window, you can save the file with a different name.
?

Displays the Open dialog box, from which you can choose a text file.
NOEDIT

Specifies that the text file can't be changed, but can be viewed and copied to the Clipboard.
NOMENU

Removes the Format menu title from the Visual FoxPro system menu bar, preventing changes to font, font size, line spacing, and indentation.
NOWAIT

Continues program execution after the editing window is opened. The program doesn't wait for the editing window to be closed, but continues execution on the program line immediately following the line that contains MODIFY FILE NOWAIT. If you omit NOWAIT when MODIFY FILE is issued in a program, the editing window is opened and program execution pauses until the editing window is closed. NOWAIT is effective only from within a program. It has no effect on MODIFY FILE when issued from the Command window. An implicit NOWAIT occurs if you open more than one editing window with a single MODIFY FILE command. For example:
Copy Code
MODIFY FILE *.TXT
RANGE nStartCharacter, nEndCharacter

Specifies a range of characters selected when you open an editing window. Characters are selected starting at the position specified with nStartCharacter up to (but not including) the character position of nEndCharacter. If nStartCharacter is equal to nEndCharacter, no characters are selected, and the cursor is placed at the position specified with nStartCharacter.
WINDOW WindowName1

Specifies a window whose characteristics the editing window takes on. For example, if the window is created with the FLOAT option of DEFINE WINDOW, the editing window can be moved. The window need not be active or visible, but it must be defined.
IN [WINDOW] WindowName2

Specifies a parent window in which the editing window is opened. The editing window doesn't assume the characteristics of the parent window and cannot be moved outside the parent window. If the parent window is moved, the editing window moves with it. The parent window must first be defined with DEFINE WINDOW, and must be visible in order to access the editing window.
IN SCREEN

Explicitly opens the editing window in the main Visual FoxPro window, after it has been placed in a parent window. An editing window is placed in a parent window by including the IN WINDOW clause.
AS nCodePage

Automatically converts accented characters in a text file created on another Visual FoxPro platform. The numeric expression nCodePage specifies the code page of the Visual FoxPro platform on which the text file was created. The file is saved in this code page unless you choose Save As from the File menu to save the file in a different code page.
SAME

Prevents the editing window from coming forward as the active window. If the editing window is hidden, it is displayed but doesn't become the active window.
SAVE

Leaves the editing window open after another window is activated. If you omit SAVE, the editing window is closed when another window is activated. Including SAVE has no effect when issued from the Command window.

Remarks

When modifications are made to a text file, the updated file is written to disk. In Visual FoxPro, a backup file with a .bak extension is created if you select the Make Backup Copy check box on the Edit Properties dialog box, which appears when you choose Properties from the Edit menu. In previous versions of FoxPro, a backup file with a .bak extension is created if you select the Backup check box in the Preferences dialog box, which appears when you choose Preferences from the Edit menu.

The Visual FoxPro editor is used unless you specify an external editor with TEDIT in your configuration file.

See Also

Other Resources

Commands
* Command
&& Command
DO Command
MODIFY COMMAND Command
NOTE Command


MODIFY FORM Command

Visual FoxPro 9.0 Language Reference
MODIFY FORM Command
See Also Example

Opens the Form Designer so you can modify or create a Form.

MODIFY FORM [FormName | ?][NOWAIT][METHOD MethodName]
   [NOENVIRONMENT][SAVE]
   [[WINDOW WindowName1] [IN [WINDOW] WindowName2 | IN SCREEN]]

Parameters

FormName

Specifies the file name for the Form. If you don't specify an extension for the file name, Visual FoxPro automatically assigns an .scx extension.
?

Displays the Open dialog box from which you can choose an existing Form or enter the name of a new Form to create.
NOWAIT

Continues program execution after the Form Designer has been opened. The program doesn't wait for the Form Designer to be closed, but continues execution on the program line immediately following the line that contains MODIFY FORM NOWAIT. If you omit NOWAIT, when MODIFY FORM is issued in a program the Form Designer is opened and program execution pauses until the Form Designer is closed. NOWAIT is effective only from within a program. It has no effect on MODIFY FORM when issued from the Command window. If NOWAIT is included with the METHOD clause, be sure to place NOWAIT before the METHOD clause or NOWAIT will be ignored.
METHOD MethodName

Specifies an event or method for which the Code window is opened in the Form Designer. The METHOD clause makes it possible for you to immediately begin editing event or method code in the Form Designer. MethodName supports the Visual FoxPro object syntax. For example, to immediately edit the Click event code for a text box named txtFirstName in a form named frmAddress, use the following command:
Copy Code
MODIFY FORM frmAddress METHOD txtFirstName.Click
If you only include an event or method name in the METHOD clause, the Code window is opened for the form's event or method. For example, to immediately edit the Click event code for a form named frmAddress, use the following command:
Copy Code
MODIFY FORM frmAddress METHOD Click
NOENVIRONMENT

Included for backward compatibility with 2.x screens, preventing the environment saved with the screen from being restored. In Visual FoxPro, the data environment associated with a Visual FoxPro form is restored by setting the data environment AutoOpenTables property to true (.T.), which is the default. To make sure that the form environment is closed when the form is releases, set the data environment AutoCloseTables property to true (.T.), which is also the default. When you create or modify forms, you can save the current Visual FoxPro data environment with the form definition file. Saving the Visual FoxPro data environment places additional records in the form definition table for all open tables and index files, the index order, and any relationships between the tables.
SAVE

When issued in a program, leaves the Form Designer open after another window is brought forward. Including the SAVE option has no effect when issued from the Command window.
WINDOW WindowName1

Specifies a window whose characteristics the Form Designer takes on. For example, if the window is created with the FLOAT option of DEFINE WINDOW, the Form Designer can be moved. The window need not be active or visible, but it must be defined. The Form Designer has a default size that can be larger than the window from which it takes its characteristics. In this case, the Form Designer still assumes the characteristics of the window in which it is placed. The upper-left corner of the Form Designer is placed at the same coordinates as the upper-left corner of the window, and extends beyond the window's borders.
IN [WINDOW] WindowName2

Specifies a parent window in which the Form Designer is opened. The Form Designer doesn't assume the characteristics of the parent window and cannot be moved outside the parent window. If the parent window is moved, the Form Designer moves with it. The parent window must first be defined with DEFINE WINDOW, and must be visible, to access the Form Designer.
IN SCREEN

Specifies that the Form Designer is explicitly opened in the main Visual FoxPro window, after the Form Designer has been placed in a parent window. The Form Designer is placed in a parent window by including the IN WINDOW clause.

Remarks

Issuing MODIFY FORM without any arguments displays the Open dialog box. You can save the form with a different name when you close the Form Designer.

Example

The following example open the stop watch (SWATCH.SCX) control sample in the Form Designer.
Copy Code
MODIFY FORM (HOME(2) + 'solution\controls\timer\swatch.scx')

See Also

Other Resources

Commands
COMPILE Command
CREATE FORM Command
DO FORM Command


MODIFY GENERAL Command

Visual FoxPro 9.0 Language Reference
MODIFY GENERAL Command
See Also

Opens editing windows for general fields in the current record.

MODIFY GENERAL GeneralField1 [, GeneralField2 ...] [NOMODIFY]
   [NOWAIT] [[WINDOW WindowName1] [IN [WINDOW] WindowName2 | IN SCREEN]]

Parameters

GeneralField1 [, GeneralField2 ...]

Specify the names of the general fields to open. To open an editing window for a general field in a table open in a noncurrent work area, include the table alias with the field name. You can open multiple general fields in the current record by including a list of general fields separated by commas.
NOMODIFY

Specifies that the OLE object contained in the general field can't be changed, but can be viewed and copied to the Clipboard.
NOWAIT

Continues program execution after the general field editing window is opened. The program doesn't wait for the editing window to be closed, but continues execution on the program line immediately following the line that contains MODIFY GENERAL NOWAIT. If you omit NOWAIT when MODIFY GENERAL is issued in a program, an editing window is opened and program execution pauses until the editing window is closed. NOWAIT is effective only from within a program. It has no effect on MODIFY GENERAL when issued from the Command window.
WINDOW WindowName1

Specifies a window whose characteristics the general field editing window takes on. For example, if the window is created with the FLOAT option of DEFINE WINDOW, the general field editing window can be moved. The window need not be active or visible, but it must be defined.
IN [WINDOW] WindowName2

Specifies a parent window in which the general field editing window is opened. The general field window doesn't assume the characteristics of the parent window and cannot be moved outside the parent window. If the parent window is moved, the general field window moves with it. The parent window must first be defined with DEFINE WINDOW, and must be visible, to access the general field window.
IN SCREEN

Explicitly opens the general field window in the main Visual FoxPro window, after it has been placed in a parent window. A general field editing window is placed in a parent window by including the IN WINDOW clause.

Remarks

When an editing window is open, you can insert, modify, or delete an OLE object.

For more information, see How to: Add OLE Objects to Applications.

See Also

Other Resources

Commands
@ ... SAY - Pictures & OLE Objects
APPEND GENERAL Command


MODIFY LABEL Command

Visual FoxPro 9.0 Language Reference
MODIFY LABEL Command
See Also

Opens the Label Designer to create or modify a label.

MODIFY LABEL [FileName | ?]
   [[WINDOW WindowName1] [IN [WINDOW] WindowName2 | IN SCREEN]]
   [NOENVIRONMENT] [NOWAIT] [PROTECTED] [SAVE]

Parameters

[FileName | ?]

Specifies the file name for the label or displays the Open dialog box so you can select an existing label file or type the name of the label file to create. The default file name extension for labels is .lbx.
Note:
If the label file you specify does not exist or cannot be found, MODIFY LABEL creates a new label file. Calling MODIFY LABEL without arguments displays the Open dialog box. Choosing New opens the Label Designer and creates a new label file with the default name of LabelNumber. When you close the Label Designer, Visual FoxPro prompts you to save changes to the label and provide a different name.

[[WINDOW WindowName1]

Specifies a window whose characteristics the Label Designer inherits. For example, if the window specified was created with the FLOAT option of DEFINE WINDOW, you can move the Label Designer. The specified window must be defined, but it does not need to be active or visible.
Note:
The Label Designer has a default size that can be larger than the specified window. In this case, the Label Designer still inherits the characteristics of the window with the upper-left corner of the Label Designer placed at the same coordinates as the upper-left corner of the specified window but extends beyond the specified window's borders.

[IN [WINDOW] WindowName2 | IN SCREEN]]

Specifies opening the Label Designer in a parent window or in the main Visual FoxPro window after placing the Label Designer in a parent window. The Label Designer does not assume the characteristics of the parent window and cannot move outside the parent window. If the parent window is moved, the Label Designer moves with it.
Note:
You must first define the parent window using DEFINE WINDOW and make it visible for access by the Label Designer.

[NOENVIRONMENT]

Prevents saving the Visual FoxPro data environment with the label and is 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.

[NOWAIT]

Continues program execution after the Label Designer opens. The program does not wait for the Label Designer to close but continues program execution on the immediate following line. If you omit NOWAIT, the Label Designer opens, and program execution pauses until the Label Designer closes. When calling MODIFY LABEL with NOWAIT in the Command window, NOWAIT has no effect.
[PROTECTED]

Specifies that the Label Designer should open in “protected” mode, which disables or suppresses certain features of the Designer. Intended to be used in applications to expose end-user editing of label forms in a safer, controlled fashion where some potentially harmful editing actions cannot take place.
[SAVE]

Specifies that the Label Designer remain open after activating another window. If you omit SAVE, the Label Designer closes when you activate another window. When calling MODIFY LABEL with SAVE in the Command window, SAVE has no effect.

Remarks

You can edit labels using the Visual FoxPro user interface. For more information, see How to: Edit Reports and Labels. You can also create labels using a wizard. For more information, see How to: Create Labels.

See Also

Other Resources

Label Designer
LABEL Command
CREATE LABEL Command
Working with Reports
Commands


MODIFY MEMO Command

Visual FoxPro 9.0 Language Reference
MODIFY MEMO Command
See Also Example

Opens an editing window for a Memo field or Blob field in the current record.

You can view or change the contents of the Memo field; however, the Blob field displays in the editing window as read-only.

MODIFY MEMO MemoField1 [, MemoField2 ...] [NOEDIT] [NOMENU]
   [NOWAIT] [RANGE nStartCharacter, nEndCharacter]
   [[WINDOW WindowName1] [IN [WINDOW] WindowName2 | IN SCREEN]]
   [SAME] [SAVE]

Parameters

MemoField1 [, MemoField2 ...]

Specifies the names of one or more Memo fields to edit.
Tip:
To open an editing window for a Memo field in a table open in another work area, include the table alias with the field name.

NOEDIT

Specifies that the opened Memo field cannot be changed; instead, it can be viewed and copied to the Clipboard.
NOMENU

Hides the Format menu on the Visual FoxPro system menu bar to prevent formatting changes to the Memo field.
NOWAIT

Continues execution of the program opening the editing window.
Note:
NOWAIT applies only when used in a Visual FoxPro program (.prg). It has no effect when executing MODIFY MEMO in the Command window.

The program does not wait for the editing window to close but continues execution on the program line immediately following the line containing MODIFY MEMO NOWAIT. If you omit NOWAIT, an editing window opens and program execution pauses until the editing window closes.
RANGE nStartCharacter, nEndCharacter

Specifies a range of characters to appear selected when the editing window opens. Starting at the position specified with nStartCharacter, characters are selected up to but not including the character position of nEndCharacter. If nStartCharacter is equal to nEndCharacter, no characters are selected, and the cursor is placed at the position specified with nStartCharacter.
WINDOW WindowName1

Specifies a window whose characteristics that the editing window uses. For example, if the window is created with the FLOAT option of the DEFINE WINDOW command, the editing window can be moved. The window specified must only be defined; it does not need to be active or visible.
IN [WINDOW] WindowName2

Specifies a parent window in which to open the editing window.
Note:
The parent window must first be defined with the DEFINE WINDOW command and must be visible in order to access the editing window.

The editing window does not assume the characteristics of the parent window and cannot be moved outside the parent window. If the parent window is moved, the editing window moves with it.
IN SCREEN

Opens the editing window explicitly in the main Visual FoxPro window, after placing the editing window in a parent window. You can place an editing window in a parent window by including the IN WINDOW clause.
SAME

Prevents the editing window from appearing as the active window in the foreground. If the editing window is hidden, it displays but does not become the active window.
SAVE

Keeps the editing window open after activating another window. If you omit SAVE, the editing window closes when another window activates.
Note:
Including SAVE has no effect when used in the Command window.

Remarks

In a table that is opened for shared access on a network, the current record is automatically locked when editing begins in one of its Memo fields.

Note:
In distributed run-time applications, syntax coloring in Memo field editing windows is disabled. For more information, see How to: Display and Print Source Code in Color.

Example

The following example uses the Visual FoxPro sample database, TestData, and MODIFY MEMO with the NOEDIT and RANGE options to open a Memo field named Notes for the first record of the Employee table. The memo field opens in an editing window as read-only and displays the first 10 characters as selected.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE employee  && Opens Employee table
MODIFY MEMO Notes NOEDIT RANGE 1,10

See Also

Other Resources

Commands
CLOSE MEMO Command
APPEND MEMO Command
COPY MEMO Command


MODIFY MENU Command

Visual FoxPro 9.0 Language Reference
MODIFY MENU Command
See Also

Opens the Menu designer so you can modify or create a menu system.

MODIFY MENU [FileName | ?] [[WINDOW WindowName1]
   [IN [WINDOW] WindowName2 | IN SCREEN]] [NOWAIT] [SAVE]

Parameters

FileName

Specifies the file name for the menu. If you don't specify an extension for the file name, Visual FoxPro automatically assigns an .mnx extension.
?

Displays the Open dialog box, from which you can choose an existing menu file or enter the name of a new menu to create.
WINDOW WindowName1

Specifies a window whose characteristics the Menu Designer takes on. For example, if the window is created with the FLOAT option of DEFINE WINDOW, the Menu Designer can be moved. The window need not be active or visible, but it must be defined.
IN [WINDOW] WindowName2

Specifies a parent window in which the Menu Designer is opened. The Menu Designer doesn't assume the characteristics of the parent window and cannot be moved outside the parent window. If the parent window is moved, the Menu Designer moves with it. The parent window must first be defined with DEFINE WINDOW, and must be visible, to access the Menu Designer.
IN SCREEN

Explicitly opens the Menu Designer in the main Microsoft Visual FoxPro window, after it has been placed in a parent window. The Menu Designer is placed in a parent window by including the IN WINDOW clause.
NOWAIT

Continues program execution after the Menu Designer is opened. The program doesn't wait for the Menu Designer to be closed, but continues execution on the program line immediately following the line that contains MODIFY MENU NOWAIT. If you omit NOWAIT when MODIFY MENU is issued in a program, the Menu Designer is opened and program execution pauses until the Menu Designer is closed. NOWAIT is effective only from within a program. It has no effect on MODIFY MENU when issued from the Command window. If you issue MODIFY MENU from the Command window without a menu name and include NOWAIT, the Open dialog is not displayed. The New Menu dialog makes it possible for you to specify the type of menu (standard or shortcut) created.
SAVE

Leaves the Menu Designer open after another window is activated. If you omit SAVE, the Menu Designer is closed when another window is activated. Including SAVE has no effect when issued from the Command window.

Remarks

For more information on creating menus, see Menu System Creation.

See Also

Reference

CREATE MENU Command
_MENUDESIGNER System Variable

Other Resources

Commands
DEFINE BAR Command
DEFINE MENU Command
DEFINE PAD Command
DEFINE POPUP Command
SET SYSMENU Command


MODIFY PROCEDURE Command

Visual FoxPro 9.0 Language Reference
MODIFY PROCEDURE Command
See Also Example

Opens the Visual FoxPro text editor, making it possible for you to create new stored procedures for the current database, or modify existing stored procedures in the current database.

MODIFY PROCEDURE [NOWAIT]

Parameters

NOWAIT

Continues program execution after the procedure editor for the current database opens. The program doesn't wait for the editor to close, but continues execution on the program line immediately following the line that contains MODIFY PROCEDURE NOWAIT. Without the NOWAIT clause, MODIFY PROCEDURE opens a procedure editor and program execution pauses until you close the editor.

Remarks

A database must be open before you can create or modify stored procedures. Stored procedures are typically specified in Delete, Insert, or Update triggers created for a database with CREATE TRIGGER.

Stored procedures in the current database can be executed like other Visual FoxPro procedures in an open procedure file or program. See PROCEDURE for a description of the order and location in which Visual FoxPro searches for procedures.

Example

The following example opens the testdata database and uses MODIFY PROCEDURE to open the Visual FoxPro text editor, making it possible for you to create new stored procedures or modify existing stored procedures.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')

MODIFY PROCEDURE  && Opens the Visual FoxPro text editor

See Also

Other Resources

Commands
CREATE TRIGGER Command
DISPLAY PROCEDURES Command
OPEN DATABASE Command
PROCEDURE Command


MODIFY PROJECT Command

Visual FoxPro 9.0 Language Reference
MODIFY PROJECT Command
See Also

Opens the Project Manager so you can modify or create a project file.

MODIFY PROJECT [FileName | ?] [NOWAIT] [SAVE] [NOSHOW] [NOPROJECTHOOK]

Parameters

No parameters

Displays the Open dialog box.
[FileName | ?]

Specifies the file name for the project or displays the Open dialog box so you can open an existing project (.pjx) file or type the name of a new project to create. If you do not specify an extension for the file name, Visual FoxPro automatically assigns a .pjx file name extension.
[NOWAIT]

Continues program execution after the Project Manager is opened. The program doesn't wait for the Project Manager to be closed, but continues execution on the program line immediately following the line that contains MODIFY PROJECT NOWAIT. Omitting NOWAIT when MODIFY PROJECT is issued in a program opens the Project Manager and pauses program execution until the Project Manager closes. NOWAIT is effective only from within a program. It has no effect on MODIFY PROJECT when issued from the Command window.
[SAVE]

Leaves the Project Manager open after another window is activated. If you omit SAVE, the Project Manager is closed when another window is activated. Including SAVE has no effect when issued from the Command window.
[NOSHOW]

Specifies that the Project Manager is hidden with its Visible property is set to False (.F.) when it opens. To display the Project Manager, set the Project Manager's Visible property to true (.T.). NOSHOW makes it possible for you to manipulate a project before displaying it in the Project Manager.
Note:
To avoid confusion with the NOSHADOW, you cannot abbreviate NOSHOW to less than five characters.

[NOPROJECTHOOK]

Specifies not to create a ProjectHook object when the Project Manager opens. Include NOPROJECTHOOK for projects that will not be manipulated programmatically through the Project Manager hooks.
Note:
A Project object is still created whenever a project file (.pjx) is opened.

Remarks

In a project, you specify all the source files that are required for a final application, and then Visual FoxPro makes sure the generated application is based on the latest source files.

A project file is a table that keeps track of all the source files such as programs, forms, menus, libraries, reports, labels, tables, indexes, and format files. A project also keeps track of all the dependencies, references, and connections among the files.

Note:
Shared libraries (.fll, .dll, and CFM files) cannot be included in projects.

A project file has a .pjx file name extension and an associated memo file with a .pjt extension.

For information about the Project Manager, see Compiling an Application .

See Also

Other Resources

Commands
BUILD APP Command
BUILD EXE Command
BUILD PROJECT Command
COMPILE Command
CREATE PROJECT Command


MODIFY QUERY Command

Visual FoxPro 9.0 Language Reference
MODIFY QUERY Command
See Also

Opens the Query designer so you can modify or create a query.

MODIFY QUERY [FileName | ?] [[WINDOW WindowName1] [IN SCREEN]
   [NOWAIT] [SAVE] [AS nCodePage]

Parameters

FileName

Specifies the file name for the query. If you don't specify an extension for the file name, Visual FoxPro automatically assigns a .qpr extension.
?

Displays the Open dialog box from which you can choose an existing query or enter the name of a new query to create.
WINDOW WindowName1

Specifies a window whose characteristics the Query Designer takes on. For example, if the window is created with the FLOAT option of DEFINE WINDOW, the Query Designer can be moved. The window need not be active or visible, but it must be defined.
IN SCREEN

Explicitly opens the Query Designer in the main Visual FoxPro window, after it has been placed in a parent window. The Query Designer is placed in a parent window by including the IN WINDOW clause.
NOWAIT

Continues program execution after the Query Designer is opened. The program doesn't wait for the Query Designer to be closed, but continues execution on the program line immediately following the line that contains MODIFY QUERY NOWAIT. If you omit NOWAIT when MODIFY QUERY is issued in a program, the Query Designer is opened and program execution pauses until the Query Designer is closed. NOWAIT is effective only from within a program. It has no effect on MODIFY QUERY when issued from the Command window.
SAVE

Leaves the Query Designer open after another window is activated. If you omit SAVE, the Query Designer is closed when another window is activated. Including SAVE has no effect when issued from the Command window.
AS nCodePage

Specifies the code page of the query. Include AS nCodePage if the query was created with a code page other than the current Visual FoxPro code page. When the query is opened, Visual FoxPro automatically converts the query to the current Visual FoxPro code page. You can use GETCP( ) for nCodePage to display the Code Page dialog box, making it possible for you to specify a code page for the query. The query is saved in its original code page when it is closed. If you omit the AS nCodePage clause or nCodePage is 0, the query is not converted to the current Visual FoxPro code page. If you specify a value for nCodePage that is not supported, Visual FoxPro generates an error message. In Visual FoxPro, queries can be added to a project, and you can specify the query's code page from within the Project Container. The Project Container keeps track of the query's code page. However, if you use MODIFY QUERY to open a query outside of the Project Container, you should include AS nCodePage to specify the query's code page.

Remarks

For more information about creating queries, see How to: Create Queries.

Issuing MODIFY QUERY without any arguments displays the Open dialog box. If you choose New from this dialog box, the name QUERY1 is assigned to the query. You can save the query with a different name when you exit the Query Designer.

After you have created a query, the query is stored as a Visual FoxPro program file with a .qpr extension. You can execute a query program with DO, but you must include the .qpr extension with the query file name.

See Also

Other Resources

Commands
CREATE QUERY Command
DO Command
GETCP( ) Function


MODIFY REPORT Command

Visual FoxPro 9.0 Language Reference
MODIFY REPORT Command
See Also

Opens the Report Designer to create or modify a report.

MODIFY REPORT [FileName | ?]
   [[WINDOW WindowName1] [IN [WINDOW] WindowName2 | IN SCREEN]]
   [NOENVIRONMENT] [NOWAIT] [PROTECTED] [SAVE]

Parameters

[FileName | ?]

Specifies the file name for the report or displays the Open dialog box so you can select an existing report file or type the name of the report file to create. The default file name extension for reports is .frx.
Note:
If the report file you specify does not exist or cannot be found, MODIFY REPORT creates a new report file. Calling MODIFY REPORT without arguments displays the Open dialog box. Choosing New opens the Report Designer and creates a new report file with the default name of ReportNumber. When you close the Report Designer, Visual FoxPro prompts you to save changes to the report and provide a different name.

[[WINDOW WindowName1]

Specifies a window whose characteristics the Report Designer inherits. For example, if the window specified was created with the FLOAT option of DEFINE WINDOW, you can move the Report Designer. The specified window must be defined, but it does not need to be active or visible.
Note:
The Report Designer has a default size that can be larger than the specified window. In this case, the Report Designer still inherits the characteristics of the window with the upper-left corner of the Report Designer placed at the same coordinates as the upper-left corner of the specified window but extends beyond the specified window's borders.

[IN [WINDOW] WindowName2 | IN SCREEN]]

Specifies opening the Report Designer in a parent window or in the main Visual FoxPro window after placing the Report Designer in a parent window. The Report Designer does not assume the characteristics of the parent window and cannot move outside the parent window. If the parent window is moved, the Report Designer moves with it.
Note:
You must first define the parent window using DEFINE WINDOW and make it visible for access by the Report Designer.

[NOENVIRONMENT]

Prevents saving the Visual FoxPro data environment with the report and is included for backward compatibility with 2.x reports. For more information, see Controlling Data in Reports.
Tip:
You can restore the data environment associated with a Visual FoxPro report by setting the data environment's AutoOpenTables property to True (.T.). To make sure that the report environment closes when the report finishes printing, set the AutoCloseTables property to True (.T.). For more information, see AutoOpenTables Property and AutoCloseTables Property.

[NOWAIT]

Continues program execution after the Report Designer opens. The program does not wait for the Report Designer to close but continues program execution on the immediate following line. If you omit NOWAIT, the Report Designer opens, and program execution pauses until the Report Designer closes. When calling MODIFY REPORT with NOWAIT in the Command window, NOWAIT has no effect.
[PROTECTED]

Specifies that the Report Designer should open in “protected” mode, which disables or suppresses certain features of the Report Designer. Intended to be used in applications to expose end-user editing of report forms in a safer, controlled fashion where some potentially harmful editing actions cannot take place.
[SAVE]

Specifies that the Report Designer remain open after activating another window. If you omit SAVE, the Report Designer closes when you activate another window. When calling MODIFY REPORT with SAVE in the Command window, SAVE has no effect.

Remarks

You can also edit reports using the Visual FoxPro user interface. For more information, see How to: Edit Reports and Labels. You can also create reports using a wizard. For more information, see How to: Create Reports.

See Also

Other Resources

Report Designer
REPORT Command
CREATE REPORT Command
Working with Reports
Commands


MODIFY STRUCTURE Command

Visual FoxPro 9.0 Language Reference
MODIFY STRUCTURE Command
See Also

Displays the Table designer, making it possible for you to modify the structure of a table.

MODIFY STRUCTURE

Remarks

In previous versions of FoxPro, MODIFY STRUCTURE opens the Table Structure dialog box.

If a table isn't open in the currently selected work area, the Open dialog box is displayed, making it possible for you to choose a table to modify.

Changes you can make to a table's structure include adding and deleting fields; modifying field names, sizes, and data types; adding, deleting, or modifying index tags; and specifying null value support for fields.

Caution:
Changing a field from one data type to another may not transfer the contents of the field correctly, or at all. For example, if you convert a field of date type to a numeric type, the field contents do not transfer.

Visual FoxPro automatically makes a backup copy of the current table before you change the table's structure. When the modifications are complete, the data contained in the backup copy of the table is appended to the newly modified table structure. If the table has a memo field, a memo backup file is also created. The table backup file has a .bak extension, and the memo backup file has a .tbk extension.

If you accept the structure changes and then interrupt the data-copying process, the new file will not contain all the records in the original table.

Remember that Visual FoxPro creates a .bak file for the original table file and, if the table has a memo field, a .tbk copy of the original memo file. If you have any problems with MODIFY STRUCTURE, you can delete the new file or files and rename the .bak file and .tbk file, if any, to the original file extensions (.dbf and .fpt).

When you modify the structure of a table that has a memo field, the blocksize of the memo file is set to the current blocksize setting. You can specify the memo file blocksize with SET BLOCKSIZE.

See Also

Other Resources

Commands
ALTER TABLE - SQL Command
CREATE Command
CREATE TABLE - SQL Command
SET BLOCKSIZE Command
How to: Edit Table Structure


MODIFY VIEW Command

Visual FoxPro 9.0 Language Reference
MODIFY VIEW Command
See Also

Displays the View Designer, making it possible for you to modify an existing SQL view.

MODIFY VIEW ViewName [REMOTE][NOWAIT]

Parameters

ViewName

Specifies the name of the view to modify.
REMOTE

Specifies that the view is a remote view that uses remote tables. If you omit REMOTE, you can modify a view using local tables.
NOWAIT

Continues program execution after the VIEW Designer opens. The program doesn't wait for the VIEW Designer to close, but continues execution on the program line immediately following the line that contains MODIFY VIEW ... NOWAIT. Without the NOWAIT clause, MODIFY VIEW opens the VIEW Designer and program execution pauses until you close the Designer.

Remarks

SQL views are created with CREATE SQL VIEW.

See Also

Other Resources

Commands
CREATE SQL VIEW Command
OPEN DATABASE Command


MODIFY WINDOW Command

Visual FoxPro 9.0 Language Reference
MODIFY WINDOW Command
See Also Example

Modifies a user-defined window or the main Visual FoxPro window.

MODIFY WINDOW WindowName | SCREEN
[FROM nRow1, nColumn1 TO nRow2, nColumn2
   | AT nRow3, nColumn3 SIZE nRow4, nColumn4]
   [FONT cFontName [, nFontSize [, nFontCharSet]]] [STYLE cFontStyle]
   [TITLE cTitleText] [HALFHEIGHT] [DOUBLE | PANEL | NONE | SYSTEM]
   [CLOSE | NOCLOSE] [FLOAT | NOFLOAT] [GROW | NOGROW]
   [MINIMIZE | NOMINIMIZE] [ZOOM | NOZOOM] [ICON FILE FileName1]
   [FILL FILE FileName2]
   [COLOR SCHEME nSchemeNumber | COLOR ColorPairList]

Parameters

WindowName

Specifies which user-defined window to modify. The window you specify must first be created with DEFINE WINDOW.
SCREEN

Specifies the main Visual FoxPro window as the window to modify. Do not abbreviate SCREEN or Visual FoxPro generates an error message. To return the main Visual FoxPro window to its startup configuration, issue the following command without any additional clauses:
Copy Code
MODIFY WINDOW SCREEN
Tip:
Use MODIFY WINDOW SCREEN NOCLOSE to prevent accidentally terminating Visual FoxPro prematurely.

For more information about the MODIFY WINDOW clauses, see DEFINE WINDOW.

Remarks

MODIFY WINDOW changes the attributes of an existing user-defined window (a window created with DEFINE WINDOW) or the main Visual FoxPro window. MODIFY WINDOW can't be used to change the attributes of Visual FoxPro system windows (such as the Command window and Browse window).

Use MODIFY WINDOW to change the location, default font, title, border, controls, icon, wallpaper, and color of a user-defined window or the main Visual FoxPro window. You can change any of these attributes by including the optional clauses for the MODIFY WINDOW command. (Note that if you change colors, you must use CLEAR to apply the color changes.)

For example, include the FROM and TO or AT and SIZE clauses to specify a new location or size for a user-defined window or the main Visual FoxPro window. To prevent a user-defined window or the main Visual FoxPro window from being moved, include the NOFLOAT keyword.

Example

The following example changes the contents of the title bar of the main Visual FoxPro window.
Copy Code
MODIFY WINDOW SCREEN TITLE 'My Application'

See Also

Other Resources

Commands
DEFINE WINDOW Command
_SCREEN System Variable


MOUSE Command

Visual FoxPro 9.0 Language Reference
MOUSE Command
See Also Example

Performs the equivalent of clicking, double-clicking, or moving the mouse, or performs a drag operation.

MOUSE [CLICK | DBLCLICK] [AT nRow1, nColumn1]
| DRAG TO nRow2, nColumn2, nRow3, nColumn3 ...][PIXELS]
[WINDOW cWindowName][LEFT | MIDDLE | RIGHT][SHIFT] [CONTROL] [ALT]

Parameters

CLICK | DBLCLICK

Specifies that the mouse is clicked or double-clicked. If you omit the AT clause, the mouse is clicked or double-clicked at the current mouse pointer position.
AT nRow1, nColumn1

Specifies where the mouse is clicked, double-clicked, or the position to which the mouse pointer is moved. If you omit CLICK or DBLCLICK, the mouse pointer is moved to the position specified with nRow1, nColumn1. Unless you specify a WINDOW, the position specified by nRow1, nColumn1 is relative to the main Microsoft Visual FoxPro window, and the position is determined by the font of the main Visual FoxPro window. Most fonts can be displayed in a wide variety of sizes, and some are proportionally spaced. A row corresponds to the height of the current font; a column corresponds to the average width of a letter in the current font. You cannot use the AT clause to choose a Visual FoxPro menu title. Use SYS(1500) – Activate a System Menu Item instead to choose a menu title.
DRAG TO nRow2, nColumn2, nRow3, nColumn3...]

Specifies that the mouse pointer is dragged to a position or a set of positions. When the mouse pointer is dragged, a mouse button is pressed and held down until the mouse pointer reaches the destination position; then the mouse button is released. If you omit the LEFT, MIDDLE, and RIGHT clauses, the left (primary) mouse button is pressed and held down by default. The DRAG clause accepts multiple sets of nRow, nColumn coordinates, allowing the mouse pointer to be dragged to several positions. If CLICK or DBLCLICK is included, the mouse is clicked or double-clicked at its current position; then the mouse pointer is dragged to the specified position.
PIXELS

Specifies that the position you include in the AT and DRAG TO clause is in pixels. If PIXELS is omitted, the position is determined by the font of the main Visual FoxPro window or the window specified with cWindowName. Most fonts can be displayed in a wide variety of sizes, and some are proportionally spaced. A row corresponds to the height of the current font; a column corresponds to the average width of a letter in the current font.
WINDOW cWindowName

Specifies the window to which the coordinates in the AT and DRAG TO clauses are relative. If you don't include WINDOW and the name of an active window, the coordinates in the AT and DRAG TO clauses are relative to the main Visual FoxPro window. To specify a system window or a toolbar, enclose the entire system window or toolbar name in quotation marks.
LEFT | MIDDLE | RIGHT

Specifies which mouse button is pressed when the mouse is clicked, double-clicked, or dragged. If you omit the LEFT, MIDDLE, and RIGHT clauses, the MOUSE commands acts as if you had clicked the left (primary) mouse button.
[SHIFT] [CONTROL] [ALT]

Specifies a key that is pressed when the mouse is clicked, double-clicked, or dragged. In Visual FoxPro for Windows, SHIFT specifies the SHIFT key, CONTROL specifies the CTRL key, and ALT specifies the ALT key. You can specify any combination of SHIFT, CONTROL, and ALT.

Remarks

MOUSE is typically used to automate interactive application testing or to create demonstration programs.

Example

In the following example, the first command clicks the mouse at row and column 3 of the main Visual FoxPro window. The second command clicks the mouse at row and column 3 of the main Visual FoxPro window, and then drags the mouse pointer to the tenth row and column of the main Visual FoxPro window. The third command drags the mouse pointer from its current position to row and column 20. The fourth command double-clicks the mouse at its current position, and then drags the mouse pointer to row and column 30. The last command drags the mouse pointer from its current position to row and column 10, then to row and column 20, and then to row and column 30.
Copy Code
MOUSE CLICK AT 3,3
MOUSE CLICK AT 3,3 DRAG TO 10,10
MOUSE DRAG TO 20,20
MOUSE DBLCLICK DRAG TO 30,30
MOUSE DRAG TO 10,10,20,20,30,30

See Also

Other Resources

Commands
MCOL( ) Function
MDOWN( ) Function
MROW( ) Function
SYS(1500) - Activate a System Menu Item


MOVE POPUP Command

Visual FoxPro 9.0 Language Reference
MOVE POPUP Command
See Also Example

Moves a user-defined menu created with DEFINE POPUP to a new location.

MOVE POPUP MenuName TO nRow1, nColumn1 | BY nRow2, nColumn2

Parameters

MenuName

Specifies the menu to move. In Visual FoxPro, you cannot move the system menu.
TO nRow1, nColumn1

Moves the menu to a location, specified by nRow1, nColumn1, in a user-defined window or in the main Visual FoxPro window.
BY nRow2, nColumn2

Moves the menu to a location relative to its current position. nRow2 specifies the number of rows to move the menu (down if nRow2 is positive, up if negative). The numeric expression nColumn2 specifies the number of columns to move the menu (to the right if nColumn2 is positive, to the left if negative).

Remarks

A menu can be moved to a specific position or relative to its current position. If a menu has been defined, it can be moved; it doesn't have to be active or visible.

Example

The following example defines and activates a menu, then moves and changes its size.
Copy Code
CLOSE DATABASE
CLEAR
DEFINE POPUP popMovIn FROM 2,2 TO 7, 14 PROMPT FILES LIKE *.PRG ;
   TITLE 'Programs'
ACTIVATE POPUP popMovIn NOWAIT
=CHRSAW(2)
MOVE POPUP popMovIn BY 5,5     && Move menu down
=CHRSAW(2)
SIZE POPUP popMovIn BY 5,5     && Enlarge the menu
=CHRSAW(2)
SIZE POPUP popMovIn BY -5,-5     && Shrink the menu
=CHRSAW(2)
MOVE POPUP popMovIn BY -5,-5     && Move menu up
=CHRSAW(2)
DEACTIVATE POPUP popMovIn
RELEASE POPUP popMovIn

See Also

Other Resources

Commands
ACTIVATE POPUP Command
DEFINE POPUP Command
SIZE POPUP Command


MOVE WINDOW Command

Visual FoxPro 9.0 Language Reference
MOVE WINDOW Command
See Also Example

Moves a user-defined window created with DEFINE WINDOW, or a Visual FoxPro system window (such as the Command window or Browse window) to a new location.

MOVE WINDOW WindowName TO nRow1, nColumn1   | BY nRow2, nColumn2 | CENTER

Parameters

WindowName

Specifies the name of the window to move.
TO nRow1, nColumn1

Moves the window to a location, specified by nRow1, nColumn1, in the main Visual FoxPro window or in a user-defined window.
BY nRow2, nColumn2

Moves a window to a location relative to its current position. The numeric expression nRow2 specifies the number of rows to move the window (down if nRow2 is positive, up if negative). The numeric expression nColumn2 specifies the number of columns to move the window (to the right if nColumn2 is positive, to the left if negative).
CENTER

Centers a window in the main Visual FoxPro window or in its parent window.

Remarks

A window can be moved to a specific position or relative to its current position. If a window is defined, it can be moved; it doesn't have to be active or visible.

To move a system window and or a toolbar (in Visual FoxPro), enclose the entire system window or toolbar name in quotation marks. For example, to move the Report Controls toolbar (when it isn't docked) in Visual FoxPro, issue the following command:

Copy Code
MOVE WINDOW "Report Controls" BY 1,1

Historically in prior versions of Visual FoxPro, the Data Session window has always been referred to as the View window. Additionally, language used to control this window, such as HIDE WINDOW, ACTIVATE WINDOW, WONTOP( ), also refers to this window as the View window. Visual FoxPro continues to refer to the View window for the MOVE WINDOW command.

Example

In the following example, after the window named wEnter is defined and activated, the window is moved.
Copy Code
DEFINE WINDOW wEnter FROM 10,4 TO 15,54 SYSTEM ;
   TITLE "Nomadic Window"
ACTIVATE WINDOW wEnter
WAIT WINDOW 'Press any key to move the window'
MOVE WINDOW wEnter TO 20,15
WAIT WINDOW 'Press any key to center the window'
MOVE WINDOW wEnter CENTER
WAIT WINDOW 'Press any key to release the window'
RELEASE WINDOW wEnter

See Also

Reference

DOCK Command

Other Resources

Commands
ACTIVATE WINDOW Command
WAIT Command
DEFINE WINDOW Command
WDOCKABLE( ) Function


NODEFAULT Command

Visual FoxPro 9.0 Language Reference
NODEFAULT Command
See Also

Prevents Visual FoxPro from performing its default event or method processing for Visual FoxPro events and methods.

NODEFAULT

Remarks

You can use NODEFAULT anywhere within the event or method procedure. You can also use NODEFAULT in an event or method procedure in the Form Designer. For example, including NODEFAULT in the KeyPress event procedure or function prevents Visual FoxPro from inserting the key press into the Visual FoxPro keyboard buffer. Therefore, you can create a KeyPress procedure so that you can test which key is pressed before the key is sent to the keyboard buffer.

See Also

Other Resources

DEFINE CLASS Command
Run Method
BeforeRowColChange Event
Add Method
OLEDragDrop Event
OLESetData Event
OLEGiveFeedback Event
OLECompleteDrag Event
QueryRunFile Event
BeforeBuild Event
QueryAddFile Event
QueryRemoveFile Event
QueryUnload Event
OLEStartDrag Event
QueryModifyFile Event
Commands
Language Reference


NOTE Command

Visual FoxPro 9.0 Language Reference
NOTE Command
See Also Example

Indicates the beginning of a nonexecuting comment line in a program file.

NOTE [Comments]

Parameters

Comments

Specifies the comment.

Remarks

Place a semicolon (;) at the end of each comment line that continues on a following line.

Example

Copy Code
NOTE  Initialize the page number;
   variable.
STORE 1 to gnPageNum
* Set up the loop
DO WHILE gnPageNum <= 25  && loop 25 times
   gnPageNum = gnPageNum + 1
ENDDO  && DO WHILE gnPageNum <= 25

See Also

Other Resources

Commands
&& Command
* Command
MODIFY COMMAND Command
MODIFY FILE Command


ON BAR Command

Visual FoxPro 9.0 Language Reference
ON BAR Command
See Also Example

Specifies a menu or menu bar that is activated when you choose a specific menu item from a menu.

ON BAR nMenuItemNumber OF MenuName1   [ACTIVATE POPUP MenuName2
   | ACTIVATE MENU MenuBarName]

Parameters

nMenuItemNumber OF MenuName1

Specifies the menu item number and menu of the menu item that activates another menu or menu bar. Each item in a menu can have another menu or menu bar assigned to it. A menu item with a menu or menu bar assigned to it has an arrow placed to the right of the menu item. The arrow indicates that choosing that menu item activates an additional menu or menu bar. An additional space for the cascading submenu arrow is placed to the right of each item if you define the menu with DEFINE POPUP ... MARGIN. If you create the menu without the MARGIN clause, the cascading submenu arrow might overwrite the last character of the menu item.
ACTIVATE POPUP MenuName2

Specifies the name of the menu to activate when the menu item is chosen. Use ON BAR without ACTIVATE POPUP to release a menu from a menu item.
ACTIVATE MENU MenuBarName

Specifies the name of the menu bar to activate when the menu item is chosen. Use ON BAR without ACTIVATEMENU to release a menu bar from a menu item.

Remarks

A menu that displays and activates another menu is called a cascading submenu. Use ON SELECTION BAR or ON SELECTION POPUP to execute a command when an item is chosen from a menu.

The menus and menu bar can be user-defined (created with DEFINE POPUP and DEFINE MENU) or part of the Visual FoxPro menu system.

Example

The following example demonstrates a system of cascading submenus. A menu bar named mnuDinner is created with two menu bar titles. Each title uses ON PAD to activate the menu named popMainCourse or popDessert. The menus named popMainCourse and popDessert each have additional menus named popBurger, popPizza and popPie assigned to their item lists with three ON BAR commands. The popOlives and popPie items have additional menus assigned with two ON BAR commands.

When you make a selection, ON SELECTION POPUP ALL executes a procedure named yourchoice that activates a window and displays your choice. The choice is determined with POPUP( ) and PROMPT( ), which return the name of the menu and the contents (text) of the menu item.
Copy Code
DEFINE WINDOW wOrder FROM 10,0 TO 13,39
DEFINE MENU mnuDinner
DEFINE PAD padOne OF mnuDinner PROMPT '\<Main Course' KEY ALT+M, ''
DEFINE PAD padTwo OF mnuDinner PROMPT '\<Dessert'   KEY ALT+D, ''
ON PAD padOne OF mnuDinner ACTIVATE POPUP popMainCourse
ON PAD padTwo OF mnuDinner ACTIVATE POPUP dessert
DEFINE POPUP popMainCourse MARGIN MESSAGE ;
   'We have burgers and pizza today'
DEFINE BAR 1 OF popMainCourse PROMPT '\<Hamburgers'
DEFINE BAR 2 OF popMainCourse PROMPT '\<Pizza'
ON BAR 1 OF popMainCourse ACTIVATE POPUP burger
ON BAR 2 OF popMainCourse ACTIVATE POPUP pizza
DEFINE POPUP burger MARGIN MESSAGE ;
   'What would you like on your burger?'
DEFINE BAR 1 OF burger PROMPT '\<Ketchup'
DEFINE BAR 2 OF burger PROMPT '\<Mustard'
DEFINE BAR 3 OF burger PROMPT '\<Onions'
DEFINE BAR 4 OF burger PROMPT '\<Pickles'
DEFINE POPUP pizza MARGIN MESSAGE ;
   'Here are the available toppings'
DEFINE BAR 1 OF pizza PROMPT '\<Anchovies'
DEFINE BAR 2 OF pizza PROMPT '\<Green Peppers'
DEFINE BAR 3 OF pizza PROMPT '\<Olives'
DEFINE BAR 4 OF pizza PROMPT '\<Pepperoni'
ON BAR 3 OF pizza ACTIVATE POPUP olives
DEFINE POPUP olives MARGIN
DEFINE BAR 1 OF olives PROMPT '\<Black' MESSAGE 'Black olives?'
DEFINE BAR 2 OF olives PROMPT '\<Green' MESSAGE 'Green olives?'
DEFINE POPUP dessert MARGIN MESSAGE 'Our dessert offerings'
DEFINE BAR 1 OF dessert PROMPT '\<Brownies'
DEFINE BAR 2 OF dessert PROMPT '\<Cookies'
DEFINE BAR 3 OF dessert PROMPT '\<Ice Cream'
DEFINE BAR 4 OF dessert PROMPT '\<Pie'
ON BAR 4 OF dessert ACTIVATE POPUP pie
DEFINE POPUP pie MARGIN MESSAGE 'What kind of pie?'
DEFINE BAR 1 OF pie PROMPT '\<Blueberry'
DEFINE BAR 2 OF pie PROMPT '\<Cherry'
DEFINE BAR 3 OF pie PROMPT '\<Peach'
DEFINE BAR 4 OF pie PROMPT '\<Rhubarb'
ON SELECTION POPUP ALL DO yourchoice
ACTIVATE MENU mnuDinner
PROCEDURE yourchoice
ACTIVATE WINDOW wOrder
CLEAR
DO CASE
   CASE POPUP( ) = 'BURGER'
      @ 0,0 SAY 'A ' + POPUP( ) + ' order:'
      @ 1,0 SAY 'You ordered a burger with ' + LOWER(PROMPT( ))
   CASE POPUP( ) = 'PIZZA'
      @ 0,0 SAY 'A ' + POPUP( ) + ' order:'
      @ 1,0 SAY 'You ordered a pizza with ' + LOWER(PROMPT( ))
   CASE POPUP( ) = 'OLIVES'
      @ 0,0 SAY 'A ' + POPUP( ) + ' order:'
      @ 1,0 SAY 'You ordered a pizza with ' ;
         + LOWER(PROMPT( )) + ' olives'
   CASE POPUP( ) = 'DESSERT'
      @ 0,0 SAY 'A ' + POPUP( ) + ' order:'
      @ 1,0 SAY 'You ordered ' + LOWER(PROMPT( )) + ' for dessert'
   CASE POPUP( ) = 'PIE'
      @ 0,0 SAY 'A ' + POPUP( ) + ' order:'
      @ 1,0 SAY 'You ordered ' + LOWER(PROMPT( )) + ' pie'
ENDCASE
WAIT WINDOW
DEACTIVATE WINDOW wOrder
RETURN

See Also

Other Resources

Commands
ACTIVATE MENU Command
DEFINE BAR Command
DEFINE MENU Command
DEFINE POPUP Command
ON SELECTION BAR Command
ON SELECTION POPUP Command


ON ERROR Command

Visual FoxPro 9.0 Language Reference
ON ERROR Command
See Also Example

Specifies a valid expression or Visual FoxPro command to execute when an error occurs in code at run time.

ON ERROR [Command]

Parameters

[Command]

Specifies a valid Visual FoxPro command or expression to execute. Typically, ON ERROR uses the DO command to specify an error-handling procedure or program. For more information, see DO Command. To restore the Visual FoxPro system error handler, use ON ERROR without an argument.

Remarks

If the error-handling procedure includes the RETRY command, the program executes the line that caused the error instead of continuing on the immediate following line. For more information, see RETRY Command.

You cannot nest ON ERROR commands; calling the ON ERROR command in procedure specified by an ON ERROR procedure restores the Visual FoxPro system error handler.

Tip:
If ON ERROR specifies a procedure, you can pass the error number, the error message, the program line number, and the program name to the procedure by including the ERROR( ), MESSAGE( ), LINENO( ), and PROGRAM( ) functions. You can use this information to determined and correct the cause of the error. For more information, see ERROR( ) Function, LINENO( ) Function, MESSAGE( ) Function, and PROGRAM( ) Function.

Example

The following example uses the ON ERROR command with the DO command to specify an error-handling procedure named errHandler. The DO command also uses the ERROR( ), MESSAGE( ), PROGRAM( ), and LINENO( ) functions to pass additional error information to the errHandler procedure. The USE command specifies a table that does not exist and generates an error. The errHandler error handler executes when the error occurs and displays the error information passed to errHandler. ON ERROR without arguments restores the default Visual FoxPro system error handler.

Copy Code
ON ERROR DO errHandler WITH ;
   ERROR( ), MESSAGE( ), MESSAGE(1), PROGRAM( ), LINENO( )
USE nodatabase
ON ERROR  && Restores system error handler.

PROCEDURE errHandler
   PARAMETER merror, mess, mess1, mprog, mlineno
   CLEAR
   ? 'Error number: ' + LTRIM(STR(merror))
   ? 'Error message: ' + mess
   ? 'Line of code with error: ' + mess1
   ? 'Line number of error: ' + LTRIM(STR(mlineno))
   ? 'Program with error: ' + mprog
ENDPROC

See Also

Other Resources

Error Handler Priority
Handling Run-Time Errors
Debugging and Error-Handling Language
Error Messages
Commands


ON ESCAPE Command

Visual FoxPro 9.0 Language Reference
ON ESCAPE Command
See Also Example

Specifies a command that executes when you press the ESC key during program or command execution.

ON ESCAPE   [Command]

Parameters

Command

Specifies the Visual FoxPro command to execute. After the command executes, program execution resumes on the line immediately following the program line that was executing when you pressed ESC. However, if a procedure specified with ON ESCAPE includes RETRY, the program line that was executing when you pressed ESC executes again.

Remarks

Typically, ON ESCAPE uses DO to execute a procedure.

If both ON ESCAPE and ON KEY are in effect and you press ESC, Visual FoxPro executes the command specified with ON ESCAPE.

Use ON ESCAPE without a command to cause no command to execute when ESC is pressed (the default).

Note:
Visual FoxPro doesn't execute an ON ESCAPE routine if SET ESCAPE is OFF.

Example

The following example sets up an infinite loop but defines an ON ESCAPE routine to exit it.
Copy Code
SET ESCAPE ON
ON ESCAPE DO stopit
WAIT WINDOW 'Press ESC to stop loop' NOWAIT
glMoreLoop = .T.

DO WHILE glMoreLoop
ENDDO
RETURN

PROCEDURE stopit
glMoreLoop = .F.
RETURN

See Also

Reference

ON ESCAPE Command

Other Resources

Commands
INKEY( ) Function
DO Command


ON EXIT BAR Command

Visual FoxPro 9.0 Language Reference
ON EXIT BAR Command
See Also

Included for compatibility with dBASE.

See Also

Other Resources

Language Reference


ON EXIT MENU Command

Visual FoxPro 9.0 Language Reference
ON EXIT MENU Command
See Also

Included for compatibility with dBASE.

See Also

Other Resources

Language Reference


ON EXIT PAD Command

Visual FoxPro 9.0 Language Reference
ON EXIT PAD Command
See Also

Included for compatibility with dBASE.

See Also

Other Resources

Language Reference


ON EXIT POPUP Command

Visual FoxPro 9.0 Language Reference
ON EXIT POPUP Command
See Also

Included for compatibility with dBASE.

See Also

Other Resources

Language Reference


ON KEY LABEL Command

Visual FoxPro 9.0 Language Reference
ON KEY LABEL Command
See Also Example

Specifies a command that executes when you press a specific key or key combination or click the mouse button.

ON KEY [LABEL KeyLabelName] [Command]

Parameters

LABEL KeyLabelName

Specifies the key label name assigned to the key. The KeyLabelName is the letter or digit on the key or a special name assigned to the key. The following table lists the special key label names. Visual FoxPro key label assignments

For this key Specify this KeyLabelName value
ArrowLeft screenshot

LEFTARROW
ArrowRight screenshot

RIGHTARROW
ArrowUp screenshot

UPARROW
ArrowDown screenshot

DNARROW

HOME

HOME

END

END

PAGE UP

PGUP

PAGE DOWN

PGDN

DEL

DEL

BACKSPACE

BACKSPACE

SPACEBAR

SPACEBAR

INS

INS

TAB

TAB

SHIFT+TAB

BACKTAB

Left Brace

LBRACE

Right Brace

RBRACE

ENTER

ENTER

F1 to F12

F1, F2, F3 ...

CTRL+F1 to CTRL+F12

CTRL+F1, CTRL+F2 ...

SHIFT+F1 to SHIFT+F12

SHIFT+F1, SHIFT+F2 ...

ALT+F1 to ALT+F12

ALT+F1, ALT+F2, ALT+F3 ...

ALT+0 to ALT+9

ALT+0, ALT+1, ALT+2 ...

ALT+A to ALT+Z

ALT+A, ALT+B, ALT+C ...

CTRL+LEFT ARROW

CTRL+LEFTARROW

CTRL+RIGHT ARROW

CTRL+RIGHTARROW

CTRL+HOME

CTRL+HOME

CTRL+END

CTRL+END

CTRL+PAGE UP

CTRL+PGUP

CTRL+PAGE DOWN

CTRL+PGDN

CTRL+A TO CTRL+Z

CTRL+A, CTRL+B, CTRL+C ...

CTRL+0

CTRL+0

RIGHT MOUSE BUTTON

RIGHTMOUSE

LEFT MOUSE BUTTON

LEFTMOUSE

MOUSE BUTTON

MOUSE

ESC

ESC
Command

Specifies the command that executes when you press the specified key or key combination or click the mouse button. You can include parameter or parameter expressions with the command that you assign to the key, as in the following example:
Copy Code
ON KEY LABEL ALT+V WAIT WINDOW "Version: " + VERSION()
You can include variables in the assignment, but they must be public. For example:
Copy Code
PUBLIC message
message = "Default drive: " + SYS(5)
ON KEY LABEL ALT+D WAIT WINDOW message

Remarks

ON KEY LABEL typically uses DO to execute a procedure.

ON KEY LABEL executes the command immediately during the execution of READ, BROWSE, EDIT, CHANGE, and user-defined menus. If a program is executing when you press the key or click the mouse button, Visual FoxPro executes the current program line and then executes the ON KEY LABEL command. Any ON KEY LABEL key assignments created in a program remain in effect after the program is run. You can also create key assignments in the Command window.

To restore the behavior of a specific key to normal, issue ON KEY LABEL KeyLabelName. To restore all keys to their default behavior, issue ON KEY.

Tip:
To prevent recursive calls during the execution of an ON KEY LABEL procedure, include PUSH KEY CLEAR early in the procedure to disable all active ON KEY LABEL commands. Issue POP KEY at the end of the procedure to enable the ON KEY LABEL commands.

The ON KEY LABEL key assignments aren't in effect in the Visual FoxPro system menu bar, system menus, dialog boxes, alerts, and so on. The key assignments are effective in the Visual FoxPro system windows — the Visual FoxPro text editor, the Command window, the Trace window, and so on.

Unlike ON KEY, there can be multiple active ON KEY LABEL commands. For example, you can assign a command to each of the arrow keys and a mouse button.

Executing an ON KEY LABEL resets PARAMETERS( ) to 0. For more information, see PARAMETERS( ).

In Visual FoxPro, certain events cannot be trapped because they are under the control of Windows. In particular, ON KEY LABEL MOUSE, ON KEY LABEL LEFTMOUSE, and ON KEY LABEL RIGHTMOUSE are not executed when you click a Windows control such as a Control menu, scroll bar, or the like. Also, CTRL+0 is supported in ON KEY LABEL in Visual FoxPro, allowing you to redefine the key combination used to enter a null value into a field.

Note that ON KEY LABEL operates outside of the scope of a form; the KeyPress event can be used within forms to execute code when a key is pressed.

Example

The following example displays a message when an arrow key is pressed.
Copy Code
CLEAR
PUBLIC msg
msg = CHR(13) + CHR(13) + "Press F9 to " + ;
   "restore default key definition."
ON KEY LABEL RIGHTARROW Wait Window "Right Arrow " + msg NOWAIT
ON KEY LABEL LEFTARROW Wait Window "Left Arrow " + msg NOWAIT
ON KEY LABEL UPARROW Wait Window "Up Arrow " + msg NOWAIT
ON KEY LABEL DNARROW Wait Window "Down Arrow " + msg NOWAIT

* Press F9 to clear the ON KEY LABEL assignments
ON KEY LABEL F9 ON KEY

See Also

Other Resources

Commands
INKEY( ) Function
KeyPress Event
ON( ) Function
POP KEY Command
PUSH KEY Command


ON PAD Command

Visual FoxPro 9.0 Language Reference
ON PAD Command
See Also

Specifies the menu or menu bar that is activated when you choose a specific menu title.

ON PAD MenuTitleName OF MenuBarName1   [ACTIVATE POPUP MenuName
   | ACTIVATE MENU MenuBarName2

Parameters

MenuTitleName OF MenuBarName1

Specifies the menu title to which a menu or menu bar is assigned.
ACTIVATE POPUP MenuName

Specifies the menu to activate when the menu title is chosen. Use ON PAD MenuTitleName OF MenuBarName1 without ACTIVATE POPUP to release a menu from a menu title. If you specify the system menu bar _MSYSMENU for MenuBarName1, MenuName cannot specify a menu that is created with the DEFINE POPUP PROMPT clause.
ACTIVATE MENU MenuBarName2

Specifies the name of the menu bar to activate when the menu title is chosen. Use ON PAD MenuTitleName OF MenuBarName1 without ACTIVATE MENU to release a menu bar from a menu name.

Remarks

Use ON SELECTION PAD to execute a command when a menu title is chosen.

See Also

Other Resources

Commands
ACTIVATE MENU Command
DEFINE MENU Command
ON SELECTION MENU Command
ON SELECTION PAD Command


ON PAGE Command

Visual FoxPro 9.0 Language Reference
ON PAGE Command
See Also

Specifies a command that executes when printed output reaches a specified line number in a report or when you issue EJECT PAGE.

ON PAGE   [AT LINE nLineNumber [Command]]

Parameters

AT LINE nLineNumber [Command]

Specifies the command to execute at the designated line number. The specified command executes when _PLINENO, the system variable that keeps track of the current line number in a report, becomes greater than the line number specified with nLineNumber. The command specified with ON PAGE also executes when you issue EJECT PAGE. For more information, see EJECT PAGE.

Remarks

ON PAGE typically uses DO to execute a procedure for handling page breaks, headers, and footers.

Executing ON PAGE without the AT LINE clause clears the ON PAGE command.

See Also

Other Resources

Commands
EJECT PAGE Command
DO Command
_PLINENO System Variable


ON SELECTION BAR Command

Visual FoxPro 9.0 Language Reference
ON SELECTION BAR Command
See Also

Specifies a command that executes when you choose a specific menu item.

ON SELECTION BAR nMenuItemNumber OF MenuName   [Command]

Parameters

nMenuItemNumber OF MenuName [Command]

Specifies the menu item's bar number, the menu name, and the command to execute for the specified menu item.

Remarks

Typically, ON SELECTION BAR uses DO to execute a procedure or program. When you create and activate a menu, place ON SELECTION BAR between DEFINE POPUP and ACTIVATE POPUP.

You can also use ON SELECTION BAR with a Visual FoxPro system menu.

Use ON SELECTION POPUP to execute a command when you choose any menu item on a menu. Use ON BAR to activate a menu or menu bar when you choose a specific menu item.

Use ON SELECTION BAR nMenuItemNumber OF MenuName without a command to release a command assigned to a menu item.

See Also

Other Resources

Commands
DEFINE BAR Command
DEFINE POPUP Command
ON BAR Command
ON SELECTION POPUP Command


ON SELECTION MENU Command

Visual FoxPro 9.0 Language Reference
ON SELECTION MENU Command
See Also Example

Specifies a command that executes when you choose any menu title on a menu bar.

ON SELECTION MENU MenuBarName | ALL [Command]

Parameters

MenuBarName

Specifies the name of the menu bar to which you assign a command. The command executes when you choose any menu title from the menu bar. You can specify the name of a user-defined menu bar created with DEFINE MENU or the Microsoft Visual FoxPro system menu bar _MSYSMENU.
ALL

Executes a command when you choose any menu title from any menu bar.
Command

Specifies the command to execute when you choose a menu title. Use ONSELECTION MENU without a command to release a command assigned to a menu bar.

Remarks

When you create and activate a menu bar, place ON SELECTION MENU between DEFINE MENU and ACTIVATE MENU.

Use ON SELECTION PAD to execute a command when you choose a specific menu item. ON SELECTION PAD takes precedence over ON SELECTION MENU. Use ON PAD to activate a menu or menu bar when you choose a specific menu title.

Use ON SELECTION MENU without a command to release a command assigned to a menu bar.

Example

In the following example, ON SELECTION MENU is used to execute a procedure when a menu title is chosen from the Visual FoxPro system menu bar.

The current system menu bar is saved to memory with SET SYSMENU SAVE and all system menu titles are removed with SET SYSMENU TO.

DEFINE PAD creates several system menu titles. When you choose a menu title, the choice procedure assigned to the menu bar with ON SELECTION MENU executes. The choice procedure displays the name of the menu title you choose and the name of the menu bar. If you choose the Exit menu title, the original Visual FoxPro system menu is restored.
Copy Code
*** Name this program ONMENU.PRG ***
CLEAR
SET SYSMENU SAVE
SET SYSMENU TO
DEFINE PAD padSys OF _MSYSMENU PROMPT '\<System' COLOR SCHEME 3 ;
   KEY ALT+S, ''
DEFINE PAD padEdit OF _MSYSMENU PROMPT '\<Edit' COLOR SCHEME 3 ;
   KEY ALT+E, ''
DEFINE PAD padRecord OF _MSYSMENU PROMPT '\<Record' COLOR SCHEME 3 ;
   KEY ALT+R, ''
DEFINE PAD padWindow OF _MSYSMENU PROMPT '\<Window' COLOR SCHEME 3 ;
   KEY ALT+W, ''
DEFINE PAD padReport OF _MSYSMENU PROMPT 'Re\<ports' COLOR SCHEME 3 KEY ALT+P, ''
DEFINE PAD padExit OF _MSYSMENU PROMPT 'E\<xit' COLOR SCHEME 3 ;
   KEY ALT+X, ''
ON SELECTION MENU _MSYSMENU ;
   DO choice IN onmenu WITH PAD( ), MENU( )
PROCEDURE choice
PARAMETER gcPad, gcMenu
WAIT WINDOW 'You chose ' + gcPad + ;
   ' from menu ' + gcMenu NOWAIT
IF gcPad = 'PADEXIT'
   SET SYSMENU TO DEFAULT
ENDIF

See Also

Other Resources

Commands
ACTIVATE MENU Command
DEFINE MENU Command
ON PAD Command
ON SELECTION PAD Command


ON SELECTION PAD Command

Visual FoxPro 9.0 Language Reference
ON SELECTION PAD Command
See Also

Specifies a command that executes when you choose a specific menu title on a menu bar.

ON SELECTION PAD MenuTitleName OF MenuBarName [Command]

Parameters

MenuTitleName OF MenuBarName

Specifies the menu title name to which the command is assigned.
Command

Specifies the Visual FoxPro command to execute when you choose the specified menu title.

Remarks

When you choose the specified menu title, Visual FoxPro executes the command you specify with ON SELECTION PAD. Typically, ON SELECTION PAD uses DO to execute a procedure or program when you choose a specific menu title from the menu bar. When you create and activate the menu bar, place ON SELECTION PAD between DEFINE MENU and ACTIVATE MENU.

Use ON SELECTION MENU to execute a command when you choose any menu title on a menu bar. Use ON PAD to activate a menu or menu bar when you choose a specific menu title on a menu bar.

Use ON SELECTION PAD without a command to release a command assigned to the menu title.

See Also

Other Resources

Commands
ACTIVATE MENU Command
DEFINE MENU Command
DEFINE PAD Command
ON PAD Command
ON SELECTION MENU Command


ON SELECTION POPUP Command

Visual FoxPro 9.0 Language Reference
ON SELECTION POPUP Command
See Also

Specifies a command that executes when you choose any menu item from a specified menu or from all menus.

ON SELECTION POPUP MenuName | ALL [Command]

Parameters

MenuName

Specifies the menu to which the command is assigned.
ALL

If you include ALL instead of a menu name, Visual FoxPro executes the command when you choose a menu item from any menu.
Command

Specifies the command to execute when you choose a menu item.

Remarks

When you choose any menu item from a menu, Visual FoxPro executes the command you specify with ON SELECTION POPUP. When you create and activate the menu, place ON SELECTION POPUP between DEFINE POPUP and ACTIVATE POPUP.

Use ON SELECTION BAR to execute a command when you choose a specific menu item. ON SELECTION BAR takes precedence over ON SELECTION POPUP. Use ON BAR to activate a menu or menu bar when you choose a specific menu item.

Use ON SELECTION POPUP without a command to release a command assigned to a menu item with a previous ON SELECTION POPUP.

See Also

Other Resources

Commands
ACTIVATE POPUP Command
DEFINE BAR Command
DEFINE POPUP Command
ON BAR Command


ON SHUTDOWN Command

Visual FoxPro 9.0 Language Reference
ON SHUTDOWN Command
See Also

Specifies a command that executes when you try to exit Visual FoxPro, or Microsoft Windows.

ON SHUTDOWN [Command]

Parameters

Issue ON SHUTDOWN without Command to release the current ON SHUTDOWN command.

Remarks

The command you specify in ON SHUTDOWN is executed if you try to exit Visual FoxPro. If you try to exit Microsoft Windows while Visual FoxPro is open, control is returned to Visual FoxPro and the command you specify in ON SHUTDOWN is executed.

The ONSHUTDOWN command is typically a DO command that executes a routine to display a dialog box. The dialog box asks if you are sure you want to exit the current application and Visual FoxPro. If you want to exit the application, the routine can close open files, clean up the Visual FoxPro environment and then execute QUIT. If you don't want to exit the current application, the routine can return control back to the application.

See Also

Other Resources

Commands
QUIT Command
EXIT Command
ON EXIT MENU Command


OPEN DATABASE Command

Visual FoxPro 9.0 Language Reference
OPEN DATABASE Command
See Also Example

Opens a database.

OPEN DATABASE [FileName | ?] [EXCLUSIVE | SHARED] [NOUPDATE] [VALIDATE]

Parameters

FileName

Specifies the name of the database to open. If you do not specify an extension for the file name, Visual FoxPro automatically assigns a .dbc extension. If you omit FileName, the Open dialog box is displayed. You can specify a path name as part of the database name.
Note:
Visual FoxPro will not recognize a path name properly if a disk or directory name contains an exclamation point (!).

?

Displays the Open dialog box from which you can choose an existing database or enter the name of a new form to create.
EXCLUSIVE

Opens the database in exclusive mode. If you open the database exclusively, other users cannot access it and will receive an error if they try to gain access. If you do not include EXCLUSIVE or SHARED, the current SET EXCLUSIVE setting determines how the database is opened.
SHARED

Opens the database in shared mode. If you open the database for shared use, other users have access to it. If you do not include EXCLUSIVE or SHARED, the current SET EXCLUSIVE setting determines how the database is opened.
NOUPDATE

Specifies that no changes can be made to the database. In other words, the database is read-only. If you omit NOUPDATE, the database is opened with read/write access. Tables contained in the database are not affected by NOUPDATE. To prevent changes to a table in the database, include NOUPDATE in USE when you open the table.
VALIDATE

Specifies that Visual FoxPro ensures that references in the database are valid. Visual FoxPro checks to see that tables and indexes referenced in the database are available on disk. Visual FoxPro also checks to see that referenced fields and index tags exist in the tables and indexes.

Remarks

While the database is open, all tables contained in it are available. However, the tables are not implicitly opened. You must open them with USE.

When USE executes, Visual FoxPro looks for the table within the current database. If the table is not found, Visual FoxPro then looks for a table outside the database. This means that if a table in a database has the same name as a table outside the database, the table in the database is found first.

You cannot open a database that is open exclusively by another user.

If you open a database twice in succession without closing the database, the database retains the same settings specified with the first DATABASE OPEN command. To change the settings, you need to close the database and then issue the DATABASE OPEN command with new settings. For example, if you open a database and specify EXCLUSIVE, the ISEXCLUSIVE function returns True (.T). If you run the DATABASE OPEN command using the same database and specify SHARED the ISEXCLUSIVE function still returns True (.T.). To open the database as shared, you need to close the database and then issue the DATABASE OPEN command using the SHARED keyword.

Example

In the following example, OPEN DATABASE is used to open the testdata database. DISPLAY DATABASE is used to display information about the tables in the database.
Copy Code
CLOSE DATABASES
SET PATH TO (HOME(2) + 'Data\')     && Sets path to database
OPEN DATABASE testdata  && Open testdata database
DISPLAY DATABASE  && Displays table information

See Also

Other Resources

Commands
ADD TABLE Command
CLOSE DATABASES Command
CREATE DATABASE Command
DBUSED( ) Function
DISPLAY DATABASE Command
FREE TABLE Command
LIST DATABASE Command
REMOVE TABLE Command


PACK Command

Visual FoxPro 9.0 Language Reference
PACK Command
See Also

Permanently removes all records marked for deletion in the current table and reduces the size of the table memo (.fpt) file associated with the table.

Note:
You must first open the table exclusively before using the PACK command.

PACK [MEMO | DBF] [Tablename ] [IN nWorkarea | cTableAlias]

Parameters

MEMO

Removes unused space from the memo file but does not remove records marked for deletion from the table. Information in memo fields is stored in an associated table memo (.fpt) file, which as the same file name as the table.
DBF

Removes records marked for deletion from the table but doesn't affect the memo file.
Tablename

Specifies the table to pack. Visual FoxPro opens the specified table, then packs, and closes it.
IN nWorkArea | cTableAlias

Specifies the work area or table alias affected by the PACK command. Use this clause to specify a work area or a table outside the current work area.

Remarks

When you use PACK, Microsoft Visual FoxPro copies all records not marked for deletion to a temporary table. After PACK is finished executing, Visual FoxPro deletes the original table from disk and renames the temporary table with the original table name. If you press the ESC key to cancel PACK, the temporary table is deleted, and the original table remains unchanged. The original table is also recovered if you run out of disk space while PACK is executing.

When you issue PACK without the MEMO and DBF clauses, PACK affects both the table and the memo file.

PACK requires exclusive use of the table. For more information about opening a table exclusively on a network, see SET EXCLUSIVE.

If the current table has one or more indexes open, PACK rebuilds the index files.

Caution:
Be careful to mark only records that you no longer need. There is no way to retrieve deleted records after using PACK.

If you omit the IN clause, PACK works in the current work area.

When you use PACK with a table containing autoincrementing fields, the resulting table is not reincremented, that is, existing values are preserved, and gaps exist where deleted records were removed. For more information, see Autoincrementing Field Values in Tables.

If no deleted records exist, PACK does not modify the table or its index.

See Also

Other Resources

Commands
DELETE – SQL Command
DELETE Command
DELETED( ) Function
RECALL Command
SET EXCLUSIVE Command


PACK DATABASE Command

Visual FoxPro 9.0 Language Reference
PACK DATABASE Command
See Also Example

Removes records marked for deletion from the current database.

PACK DATABASE

Remarks

A database contains records marked for deletion after a table or view is removed from the database, or if the structure of a table in the database is modified.

The database must be opened exclusively, and no table or view in the database can be open.

Example

In the following example, PACKDATABASE is used to pack the testdata database, removing records marked for deletion.
Copy Code
CLOSE DATABASES
SET PATH TO (HOME(2) + 'data\')     && Sets path to database
OPEN DATABASE testdata  && Open the database
PACK DATABASE && Pack the current database

See Also

Other Resources

Commands
CLOSE DATABASES Command
DELETE DATABASE Command
MODIFY DATABASE Command
OPEN DATABASE Command
SET DATABASE Command
VALIDATE DATABASE Command


PARAMETERS Command

Visual FoxPro 9.0 Language Reference
PARAMETERS Command
See Also Example

Assigns data from a calling program to private variables or arrays.

PARAMETERS Parameter1 [ AS type [ OF ClassLib ] ]
   [, Parameter2 [ AS type [ OF ClassLib ] ] ]

Parameters

PARAMETERS ParameterList

Specifies one or more variable or array names to assign data to. Use commas to separate multiple parameters in ParameterList. Generally, you can pass a maximum of 26 parameters; however, in some circumstances, you can pass 27 parameters.
Note:
The PARAMETERS statement must specify at least as many parameters as used by the call to the program, procedure, or function containing the PARAMETERS statement. If more variables or arrays are listed in the PARAMETERS statement than are passed by the calling program, the remaining variables or arrays in the PARAMETERS statement are initialized to False (.F.).

[ AS type [ OF ClassLib] ]

Specifies the data type of the variable or array and the class library containing the type description of type on which this variable or array is based. You can use the AS clause to implement strong typing. IntelliSense functionality is available for object and variable references only when they are strongly typed. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.

Remarks

When PARAMETERS is used with a program, procedure, or user-defined function called with the DO command, it must be the first executable statement in the called program, procedure, or user-defined function.

By default, the WITH clause in the DO command passes variables and arrays to procedures by reference. By default, Visual FoxPro passes arguments by value to user-defined functions.

Note:
To pass entire arrays to functions, you must pass them by reference. If you do not pass arrays to functions by reference, only the first element passes to the function. For more information, see How to: Pass Data to Parameters by Reference.

For more information, see Passing Data to Parameters and Parameters in Procedures and Functions.

Example

The following example passes parameters to an error-handling routine.
Copy Code
ON ERROR DO errhand WITH ERROR( ), MESSAGE( ), ;
   MESSAGE(1),PROGRAM( ),LINENO( )
USE nodatabase
ON ERROR         && restores system error-handling routine

PROCEDURE errhand
PARAMETERS gnError, gcMess, gnMess1, gcProg, gnLineNo
? 'Error number: ' + LTRIM(STR(gnError))
? 'Error message: ' + gcMess
? 'Line of code with error: ' + gnMess1
? 'Line number of error: '+ LTRIM(STR(gnLineNo))
? 'Program with error: ' + gcProg

See Also

Other Resources

LPARAMETERS Command
FUNCTION Command
PROCEDURE Command
DO Command
PCOUNT( ) Function
PARAMETERS( ) Function
Commands


PLAY MACRO Command

Visual FoxPro 9.0 Language Reference
PLAY MACRO Command
See Also

Executes a keyboard macro.

PLAY MACRO MacroName [TIME nDelay]

Parameters

MacroName

Specifies the name of the keyboard macro to play.
TIME nDelay

Specifies the time interval between the delivery of each keystroke in a keyboard macro. The delay time must be between 0 and 10 seconds. nDelay can evaluate to a number with a decimal fraction. For example, if you specify nDelay equal to 1.5, keystrokes from the macro will be played with a one-and-a-half-second delay between each keystroke.

Remarks

You can save a series of keystrokes as a keyboard macro by choosing Macros from the Tools menu. PLAY MACRO plays this series of keystrokes. Playing keyboard macros within programs lets you create self-running demo programs.

If you issue PLAY MACRO from the Command window, it executes immediately. If PLAY MACRO is issued in a program, execution is delayed until the program executes a command that allows keyboard input. Examples of commands that wait for input are @ ... GET, BROWSE, CHANGE, and EDIT.

If a series of PLAY MACRO commands is pending in a program, Visual FoxPro doesn't execute the commands in the order in which they are issued. Macros are played in reverse order — the first PLAY MACRO executes last, the last PLAY MACRO executes first — in their bottom-to-top order within the program.

See Also

Other Resources

Commands
CLEAR Commands
ON KEY LABEL Command
RESTORE MACROS Command
SAVE MACROS Command


POP KEY Command

Visual FoxPro 9.0 Language Reference
POP KEY Command
See Also

Restores ON KEY LABEL assignments that were placed on the stack with PUSH KEY.

POP KEY [ALL]

Parameters

ALL

Clears all current key assignments defined with ON KEY LABEL and clears all key assignments defined with ON KEY LABEL from the stack.

Remarks

POP KEY, when used with PUSH KEY, lets you save a set of key assignments created with ON KEY LABEL commands, make changes to the key assignments with more ON KEY LABEL commands, and then restore the original key assignments.

Key assignments take up memory, so every POP KEY should have a corresponding PUSH KEY to make sure your application's memory usage does not grow unnecessarily.

For more information on placing ONKEYLABEL commands on the stack, see PUSH KEY Command.

See Also

Other Resources

Commands
ON KEY LABEL Command
ON( ) Function


POP MENU Command

Visual FoxPro 9.0 Language Reference
POP MENU Command
See Also Example

Restores the specified menu bar definition that was placed on the stack with PUSH MENU.

POP MENU MenuBarName [TO MASTER]

Parameters

MenuBarName

Specifies the name of the menu bar whose definition is pulled off the stack. The specified menu bar can be user-defined or the Visual FoxPro system menu bar.
TO MASTER

Restores the first menu bar definition pushed onto the stack, and then clears the stack.

Remarks

When used with PUSH MENU, POP MENU lets you save a menu bar definition, make changes to the menu bar definition, and then restore the menu bar definition to its original state.

Menu bars are placed on and removed from the stack in last-in, first-out order.

Menu definitions take up memory, so every POP MENU should have a corresponding PUSH MENU to make sure your application's memory usage does not grow unnecessarily.

Example

In the following example, the system menu bar definition is pushed to the stack and then modified. The original system menu definition is then restored by popping it off the stack.
Copy Code
PUSH MENU _MSYSMENU
SET SYSMENU TO _MFILE, _MEDIT
POP MENU _MSYSMENU

See Also

Other Resources

Commands
ACTIVATE MENU Command
DEFINE MENU Command
POP POPUP Command
PUSH MENU Command
PUSH POPUP Command


POP POPUP Command

Visual FoxPro 9.0 Language Reference
POP POPUP Command
See Also Example

Restores the specified menu definition that was placed on the stack with PUSH POPUP.

POP POPUP MenuName

Parameters

MenuName

Specifies the name of the menu whose definition is pulled off the stack. The menu can be a user-defined menu created with DEFINE MENU or a Visual FoxPro system menu.

Remarks

When used with PUSH POPUP, POP POPUP makes it possible for you to save a menu definition, make changes to the menu definition, and then restore the menu definition to its original state.

Menu definitions are placed on and removed from the stack in a last-in, first-out order.

Menu definitions take up memory, so every POP POPUP should have a corresponding PUSH POPUP to make sure your application's memory usage does not grow unnecessarily.

Example

In the following example, a menu named popExam is created. Menu definition is pushed to the stack and then one of the menu items is modified. The original menu definition is then restored by popping it off the stack.
Copy Code
DEFINE POPUP popExam FROM 5,5
DEFINE BAR 1 OF popExam PROMPT 'One'
DEFINE BAR 2 OF popExam PROMPT 'Two'
DEFINE BAR 3 OF popExam PROMPT 'Three'
DEFINE BAR 4 OF popExam PROMPT 'Four'
ACTIVATE POPUP popExam NOWAIT

PUSH POPUP popExam
WAIT 'Popup pushed' WINDOW
RELEASE BAR 2 OF popExam
WAIT 'This is the modified popup' WINDOW

POP POPUP popExam
WAIT 'Popup popped, original popup restored' WINDOW
DEACTIVATE POPUP popExam
RELEASE POPUP popExam

See Also

Other Resources

Commands
ACTIVATE POPUP Command
DEFINE POPUP Command
POP MENU Command
PUSH MENU Command
PUSH POPUP Command


PRINTJOB ... ENDPRINTJOB Command

Visual FoxPro 9.0 Language Reference
PRINTJOB ... ENDPRINTJOB Command
See Also

Activates the settings for print job system variables.

PRINTJOB
      Commands
ENDPRINTJOB

Parameters

Commands

Specifies the Visual FoxPro commands that are executed until the print job is completed.

Remarks

PRINTJOB ... ENDPRINTJOB initializes the printer and certain system variables that affect printed output. It can send control codes to the printer, eject a page from the printer before and/or after a print job, initialize the printer column number, and control the number of copies printed.

PRINTJOB performs these tasks:

  • Sends starting printer control codes, stored in the system variable _PSCODE, to the printer. For more information on printer control codes, see the System Variables Overview topic and your printer manual.

  • Ejects a page if the system variable _PEJECT is set to BEFORE or to BOTH.

  • Sets the system variable _PCOLNO to 0. _PCOLNO stores the printer column number.

ENDPRINTJOB performs these tasks:

  • Sends ending printer control codes, stored in the system variable _PECODE, to the printer. You can reset the printer to the configuration it had before PRINTJOB was issued.

  • Ejects a page if the system variable _PEJECT is set to AFTER or to BOTH.

  • Loops back to PRINTJOB to print another copy of the report if the _PCOPIES system variable is set to a value higher than 1 (the default). The value of the system variable _PCOPIES determines the number of copies. When the number of copies printed equals the value of _PCOPIES, Visual FoxPro exits the loop. Program control then begins with the command immediately following ENDPRINTJOB.

PRINTJOB and ENDPRINTJOB may be executed only from within a program. You may not nest PRINTJOB ... ENDPRINTJOB commands.

See Also

Other Resources

Commands
ON PAGE Command
Printing
PRINTSTATUS( ) Function


PRIVATE Command

Visual FoxPro 9.0 Language Reference
PRIVATE Command
See Also Example

Hides specified variables or arrays that were defined in a calling program from the current program. There are two versions of the syntax.

PRIVATE VarList
PRIVATE ALL[LIKE Skeleton | EXCEPT Skeleton]

Parameters

VarList

Specifies the variables or arrays to be declared private. The single letters A through J and M are reserved and cannot be used as variable names.
ALL LIKE Skeleton

Causes PRIVATE to hide all variables and arrays whose names match Skeleton, which can contain the question mark (?) and asterisk (*) wildcards.
ALL EXCEPT Skeleton

Causes PRIVATE to hide all variables or arrays unless their names match Skeleton, which can contain the question mark (?) and asterisk (*) wildcards.

Remarks

Items within VarList are separated by commas. The hiding of variables created in higher-level programs enables variables of the same name as the private variables to be manipulated in the current program without affecting the values of the hidden variables. Once the program containing PRIVATE has completed execution, all variables and arrays that were declared private are again available.

PRIVATE doesn't create variables; it simply hides variables declared in higher-level programs from the current program.

Example

Copy Code
*** Program example demonstrating PRIVATE ***
SET TALK OFF
val1 = 10
val2 = 15

DO down
? val1, val2  && Displays 10, 100

PROCEDURE down
PRIVATE val1
val1 = 50
val2 = 100
? '   Val1   Val2'
? val1, val2  && Displays 50, 100
RETURN

See Also

Other Resources

Commands
DIMENSION Command
FUNCTION Command
LOCAL Command
LPARAMETERS Command
PARAMETERS Command
PARAMETERS( ) Function
PROCEDURE Command
PUBLIC Command


PROCEDURE Command

Visual FoxPro 9.0 Language Reference
PROCEDURE Command
See Also Example

Creates a user-defined procedure in a program file. There are two versions of the syntax.

PROCEDURE ProcedureName
   [ LPARAMETERS parameter1 [ ,parameter2 ] ,... ]
      Commands
   [ RETURN [ eExpression ] ]
[ENDPROC]
PROCEDURE ProcedureName( [ parameter1 [ AS para1type ][ ,parameter2
[AS para2type ] ] ,...] ) [ AS returntype ]
      Commands
   [ RETURN [ eExpression ] ]
[ENDPROC]

Parameters

PROCEDURE ProcedureName

Designates the beginning of a user-defined procedure and specifies the name of the procedure. ProcedureName must begin with a letter or underscore and can contain up to 254 characters with any combination of letters, numbers, and underscores.
[ LPARAMETERS parameter1 [ , parameter2] ,... ] ]

Assigns data from the calling program to local variables or arrays. You can also use the PARAMETERS keyword instead of LPARAMETERS to accept privately scoped parameters. You can pass a maximum of 26 parameters to a procedure. For more information, see LPARAMETERS Command and PARAMETERS Command.
( [ parameter1[ AS para1type][ , parameter2[ AS para2type] ],...] )

Assigns data from the calling program to local variables or arrays. You can use the AS para1type clause to specify the data type of the variable.
Note:
Including the parameters inside parentheses (()) immediately following the procedure name indicates that the parameters are locally scoped to the procedure.

[ AS returntype]

Specifies the data type of the return value. You can use the AS clause to implement strong typing. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.
Commands

Specifies the Visual FoxPro commands to execute when executing the function.
[ RETURN [ eExpression] ]

Returns control to the calling program or to another program. eExpression can specify a return value.
Note:
You can include the RETURN command anywhere in the procedure to return control to the calling program or to another program and to define a value returned by the procedure. If you do not include the RETURN command, Visual FoxPro executes an implicit RETURN automatically when the procedure quits. If the RETURN command does not include a return value or if an implicit RETURN is executed, Visual FoxPro assigns True (.T.) as the return value. For more information, see RETURN Command.

[ ENDPROC ]

Indicates the end of the PROCEDURE structure.
Note:
The ENDPROC keyword is optional because the function quits when it encounters another PROCEDURE command, a FUNCTION command, or the end of the program file.You cannot include normal executable program code following user-defined procedures in a program file. Only other user-defined procedures, functions, and class definitions can follow the first PROCEDURE or FUNCTION command in the file.

Remarks

By default, parameters are passed to procedures by value. For information about passing parameters to procedures by reference, see SET UDFPARMS Command.

When you issue the DO command with a procedure name, Visual FoxPro searches for the procedure in the following order:

  1. The file containing the DO command.

  2. The current database.

  3. Procedure files opened with SET PROCEDURE.

    For more information, see SET PROCEDURE Command.

  4. Program files in the execution chain.

    Visual FoxPro searches program files in order from the most recently executed program to the first program executed.

  5. A standalone program file.

If a matching program file is found, Visual FoxPro executes the program. Otherwise, Visual FoxPro generates an error message.

To execute a procedure in a specific file, include the IN clause in the DO command.

For information about use of the PROCEDURE command when creating classes, see DEFINE CLASS Command.

Example

The following example illustrates how a procedure can be called to accomplish a discrete task such as making an entry in a log file. The procedure opens the log file (which is assumed to exist in the example), constructs an entry based in information passed in parameters, writes the entry out, and closes the file. The procedure is called with a DO command similar to the one at the top of the program.

Copy Code
DO MakeLogEntry WITH "Logged in", "jsmith"

PROCEDURE MakeLogEntry
 PARAMETERS message, username
 pnHandle = FOPEN("LOG2.TXT",2)     && Assume the file exists
 pnSize = FSEEK(pnHandle,0,2)           && Move to end of file
 logEntry = dtoc(date())+","+time()+","+username+","+message
 =FPUTS(pnHandle, logEntry)
 =FCLOSE(pnHandle)  && Close file
ENDPROC

The following example shows how a procedure can be called to return a value.

Copy Code
SET CENTURY ON
? longdate(({^1998-02-16}))  && Displays Monday, February 16, 1998

PROCEDURE longdate
 PARAMETER mdate
 RETURN CDOW(mdate) + ", " + MDY(mdate)
ENDPROC

See Also

Reference

SYS(16) - Executing Program File Name

Other Resources

FUNCTION Command
PARAMETERS( ) Function
Commands


PUBLIC Command

Visual FoxPro 9.0 Language Reference
PUBLIC Command
See Also Example

Defines global variables or arrays. There are two versions of the syntax.

PUBLIC MemVarList
PUBLIC [ ARRAY ] ArrayName1( nRows1 [ , nColumns1 ] ) [, ArrayName2( nRows2 [, nColumns2 ] ) ] ...
   [AS type [OF ClassLib]]

Parameters

PUBLIC MemVarList

Specifies one or more memory variables to initialize and designate as global. Use commas to separate multiple items in MemVarList. The single letters A through J and M are reserved and cannot be used as variable names.
PUBLIC [ ARRAY ] ArrayName1( nRows1 [, nColumns1 ] ) [, ArrayName2( nRows2 [, nColumns2] )] ...

Specifies one or more arrays to initialize and designate as global. For more information about arrays, see DIMENSION Command.
[ AS type [OF ClassLib] ]

Specifies the data type of the variable or array and the class library containing the type description of type on which this variable or array is based. You can use the AS clause to implement strong typing. IntelliSense functionality is available for object and variable references only when they are strongly typed. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.

Remarks

You can use and modify global variables and arrays from any program executed during the current Visual FoxPro session.

Variables and arrays created with PUBLIC are initialized to False (.F.) except for the public variables FOX and FOXPRO, which are initialized to True (.T.). Depending on the version of Visual FoxPro you are running, you can use the public variables FOX and FOXPRO to conditionally execute code.

Note:
The public variables FOX and FOXPRO were used in earlier versions to detect previous versions of FoxBASE and FoxPro, respectively.

You must declare any variables or arrays that you want public prior to assigning values to them. If you assign a value to a variable or array in a program and later declare it as public using PUBLIC, Visual FoxPro generates a syntax error.

Variables or arrays that you create from the Command window are automatically public.

Example

Copy Code
SET TALK OFF
PUBLIC val1,val2
val1 = 10
val2 = 15

DO down
? val1
? val2

RELEASE ALL     && Releases private variables only
DISPLAY MEMORY LIKE val?
RELEASE val1,val2  && Public variables must be released explicitly
DISPLAY MEMORY LIKE val?

PROCEDURE down
PRIVATE val1
val1 = 50
val2 = 100
? val1
? val2
RETURN

See Also

Other Resources

LOCAL Command
PRIVATE Command
Commands


PUSH KEY Command

Visual FoxPro 9.0 Language Reference
PUSH KEY Command
See Also

Places all current ON KEY LABEL command settings on a stack in memory.

PUSH KEY [CLEAR]

Parameters

CLEAR

Clears all current key assignments from memory.

Remarks

PUSH KEY, when used with POP KEY, makes it possible for you to save key assignments defined with ON KEY LABEL commands, change these assignments, and then restore the previous assignments.

For example, you may want to use a new set of ON KEY LABEL commands when you open a Browse window. Before you open the Browse window, use PUSH KEY to save the current ON KEY LABEL key assignments in memory. You can then add or change ON KEY LABEL assignments specifically for the Browse window. After you close the Browse window, your previous ON KEY LABEL key assignments can be restored from memory with POP KEY.

ON KEY LABEL settings are placed on and removed from the stack in a last-in, first-out order.

DISPLAY STATUS and LIST STATUS show the current key assignments defined with ON KEY LABEL commands. Key assignments take up memory, so every PUSH KEY should have a corresponding POP KEY to make sure your application's memory usage does not grow unnecessarily.

See Also

Other Resources

Commands
ON KEY LABEL Command
ON( ) Function
POP KEY Command


PUSH MENU Command

Visual FoxPro 9.0 Language Reference
PUSH MENU Command
See Also Example

Places a menu bar definition in a stack of menu bar definitions in memory.

PUSH MENU MenuBarName

Parameters

MenuBarName

Specifies the name of the menu bar whose definition is placed on the stack. The menu bar can be user-defined or the Visual FoxPro system menu bar.

Remarks

When used with POP MENU, PUSH MENU makes it possible for you to save a menu bar definition, make changes to the menu bar definition, and then restore the menu bar definition to its original state.

Menu bar definitions are placed on and removed from the stack in last-in, first-out order. Menu definitions take up memory, so every PUSH MENU should have a corresponding POP MENU to make sure your application's memory usage does not grow unnecessarily.

Example

In the following example, the Visual FoxPro system menu bar is pushed to the stack and then modified. The original system menu bar is then restored by popping it off the stack.
Copy Code
WAIT WINDOW 'Press a key to push the system menu bar'
PUSH MENU _MSYSMENU
WAIT WINDOW 'Press a key to change the system menu bar'
SET SYSMENU TO _MFILE, _MEDIT
WAIT WINDOW 'Press a key to restore the system menu bar'
POP MENU _MSYSMENU

See Also

Other Resources

Commands
ACTIVATE MENU Command
DEFINE MENU Command
SET SYSMENU Command


PUSH POPUP Command

Visual FoxPro 9.0 Language Reference
PUSH POPUP Command
See Also Example

Places a menu definition on a stack of menu definitions in memory.

PUSH POPUP MenuName

Parameters

MenuName

Specifies the name of the menu whose definition is placed on the stack. The menu can also be a Visual FoxPro system menu.

Remarks

When used with POP POPUP, PUSH POPUP makes it possible for you to save a menu definition, make changes to the menu definition, and then restore the menu definition to its original state.

Menu definitions are placed on and removed from the stack in last-in, first-out order. Menu definitions take up memory, so every PUSH POPUP should have a corresponding POP POPUP to make sure your application's memory usage does not grow unnecessarily.

Example

In the following example, a menu named popExam is created. The menu definition is pushed to the stack and then modified. The original menu is then restored by popping it off the stack.
Copy Code
DEFINE POPUP popExam FROM 5,5
DEFINE BAR 1 OF popExam PROMPT 'One'
DEFINE BAR 2 OF popExam PROMPT 'Two'
DEFINE BAR 3 OF popExam PROMPT 'Three'
DEFINE BAR 4 OF popExam PROMPT 'Four'
ACTIVATE POPUP popExam NOWAIT
PUSH POPUP popExam
WAIT 'Original Popup' WINDOW
RELEASE BAR 2 OF popExam
WAIT 'Modified Popup. Original Popup is pushed to a stack.' WINDOW
POP POPUP popExam
WAIT 'Original Popup restored' WINDOW
DEACTIVATE POPUP popExam
RELEASE POPUP popExam

See Also

Other Resources

Commands
ACTIVATE POPUP Command
DEFINE POPUP Command
POP POPUP Command


QUIT Command

Visual FoxPro 9.0 Language Reference
QUIT Command
See Also

Ends the current Visual FoxPro session and returns control to the operating system.

QUIT

Remarks

Always use QUIT to terminate a Visual FoxPro session. If you turn the computer off without issuing QUIT, open files might become damaged and data lost, and temporary work files that would normally be deleted may be left on disk.

See Also

Other Resources

Commands
CANCEL Command
RESUME Command
RUN Command
SUSPEND Command


RD | RMDIR Command

Visual FoxPro 9.0 Language Reference
RD | RMDIR Command
See Also Example

Removes a directory or folder from disk.

RD cPath | RMDIR cPath

Parameters

cPath

Specifies the name and location of the directory or folder to remove from disk.

Remarks

Visual FoxPro generates an error message if you attempt to remove a directory or folder that is not empty.

Example

The following example uses MKDIR to create a new directory named mytstdir, then CHDIR is used to change to the new directory. GETDIR( ) is used to display the directory structure, and then RMDIR is used to remove the newly created directory. GETDIR( ) is used to display the directory structure again.
Copy Code
SET DEFAULT TO HOME( )  && Restore Visual FoxPro directory
MKDIR mytstdir  && Create a new directory
CHDIR mytstdir  && Change to the new directory
= GETDIR( )  && Display the Select Directory dialog box
SET DEFAULT TO HOME( )  && Restore Visual FoxPro directory
RMDIR mytstdir  && Remove the new directory
= GETDIR( )  && Display the Select Directory dialog box

See Also

Other Resources

Commands
CD | CHDIR Command
GETDIR( ) Function
HOME( ) Function
MD | MKDIR Command
SET DEFAULT Command
SET PATH Command
SYS(5) – Default Drive
SYS(2003) – Current directory
SYS(2004) – Visual FoxPro Start Directory


READ Command

Visual FoxPro 9.0 Language Reference
READ Command
See Also

Included for backward compatibility. Use the Form Designer instead.

See Also

Other Resources

Language Reference


READ EVENTS Command

Visual FoxPro 9.0 Language Reference
READ EVENTS Command
See Also

Starts event processing.

READ EVENTS

Remarks

When READ EVENTS is issued, Visual FoxPro starts event processing.

Issue CLEAR EVENTS to stop event processing. When CLEAR EVENTS is issued, program execution continues with the line immediately following READ EVENTS.

Note that only one READ EVENTS can be active at a time. If a READ EVENTS is in effect, any subsequent READ EVENTS commands have no effect.

See Also

Other Resources

Commands
CLEAR Command
Form Designer
DOEVENTS Command


RECALL Command

Visual FoxPro 9.0 Language Reference
RECALL Command
See Also Example

Unmarks records marked for deletion in the selected table.

RECALL [Scope] [FOR lExpression1] [WHILE lExpression2] [NOOPTIMIZE]
   [IN nWorkArea | cTableAlias]

Parameters

Scope

Specifies a range of records to recall. The default scope for RECALL is the current record (NEXT 1). Only the records that fall within the range specified are recalled. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see Scope Clauses.
FOR lExpression1

Specifies that only the records for which lExpression1 evaluates to true (.T.) are recalled. This option allows you to filter out undesired records. Rushmore Query Optimization optimizes a RECALL FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies a condition whereby records are recalled for as long as lExpression2 evaluates to true (.T.).
NOOPTIMIZE

Prevents Rushmore optimization of RECALL For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
IN nWorkArea | cTableAlias

Specifies the workarea or table alias affected by the RECALL command. Use this clause to specify a workarea or a table outside the current work area.

Remarks

You can use RECALL to recover records, provided you have not issued PACK or ZAP.

Caution:
Once a file has been packed, all records marked for deletion are gone forever.

You can mark records for deletion by issuing DELETE or DELETE – SQL, or by choosing Delete Records from the Table menu when a Browse or Edit window is active. You can recall records by issuing RECALL, or by choosing Recall Records from the Record menu when a Browse or Edit window is active.

If you omit the IN clause, the RECALL command operates in the current work area.

Example

The following example opens the customer table in the testdata database. DELETE – SQL is used to mark all records for deletion where the country field contains USA. All the records marked for deletion are displayed. RECALL ALL is used to unmark all the records marked for deletion.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Opens Customer table

DELETE FROM customer WHERE country = 'USA'  && Mark for deletion
CLEAR
LIST FIELDS company, country FOR DELETED( ) && List marked records
RECALL ALL  && Unmark all records marked for deletion

See Also

Other Resources

Commands
DELETE Command
DELETE – SQL Command
PACK Command
SET DELETED Command
ZAP Command


REINDEX Command

Visual FoxPro 9.0 Language Reference
REINDEX Command
See Also Example

Rebuilds open index files.

REINDEX updates all index files open in the selected work area.

REINDEX [COMPACT]

Parameters

COMPACT

Converts regular single index (.idx) files to compact .idx files.

Remarks

Index files become outdated when you open a table without opening its corresponding index files and make changes to the index files' key fields. When index files become outdated, you can update them by reindexing.

Visual FoxPro recognizes each index file type: compound index (.cdx) files, structural .cdx files, and single index (.idx) files), and reindexes them accordingly. It updates all tags in .cdx files and updates structural .cdx files, which automatically open with the table.

Tip:
To speed network traffic during a REINDEX operation, you can use SYS(3050) - Set Buffer Memory Size to set buffer memory to a size large enough to store the entire table. During the first pass, the table is paged locally, and later passes will not attempt to read paged data from the remote computer.

Any index files created with the UNIQUE keyword of the INDEX command or with SET UNIQUE ON retain their UNIQUE status when reindexed.

To REINDEX outdated index files, issue these commands:

Copy Code
USE TableName INDEX OutdatedIndexNames
REINDEX

Example

In the following example, ISEXCLUSIVE( ) verifies that the customer table was opened for exclusive use. The table is not reindexed since the one in the current work area was not opened for exclusive use.
Copy Code
cExclusive = SET('EXCLUSIVE')
SET EXCLUSIVE OFF
SET PATH TO (HOME(2) + 'Data\')
OPEN DATA testdata  && Opens the test databsase
USE Customer     && Not opened exclusively
USE Employee IN 0 EXCLUSIVE    && Opened exclusively in another work area

IF ISEXCLUSIVE( )
 REINDEX  && Can only be done if table opened exclusively
ELSE
  WAIT WINDOW 'The table has to be exclusively opened'
ENDIF

SET EXCLUSIVE &cExclusive

See Also

Other Resources

INDEX Command
Commands
SET INDEX Command
SET EXCLUSIVE Command
SET UNIQUE Command
SYS( ) Functions Overview
USE Command


RELEASE BAR Command

Visual FoxPro 9.0 Language Reference
RELEASE BAR Command
See Also

Removes a specified menu item or all menu items on a menu from memory.

RELEASE BAR nMenuItemNumber OF MenuName | ALL OF MenuName

Parameters

nMenuItemNumber OF MenuName

Specifies a menu item in a user-defined menu to remove from memory. To remove a menu item from a Microsoft Visual FoxPro system menu, include the internal Visual FoxPro system menu item name in nMenuItemNumber. For more information, see the System Menu Names online topic.
ALL OF MenuName

Specifies that every menu item on a user-defined menu is removed from memory. ALL cannot be used to remove menu items from a Visual FoxPro system menu.

See Also

Other Resources

Commands
DEFINE BAR Command
RELEASE PAD Command
System Menu Names


RELEASE CLASSLIB Command

Visual FoxPro 9.0 Language Reference
RELEASE CLASSLIB Command
See Also Example

Closes .vcx visual class libraries containing class definitions.

RELEASE CLASSLIB ClassLibraryName1 | ALIAS AliasName1
   [, ClassLibraryName2 | ALIAS AliasName2 ...]
   [IN APPFileName | EXEFileName]

Parameters

ClassLibraryName1 | ALIAS AliasName1

Specifies the name or alias of a visual class library file to close.
ClassLibraryName2 | ALIAS AliasName2 ...

Specifies the names or aliases of additional visual class library files to close.
IN APPFileName | EXEFileName

Specifies a Visual FoxPro application file (.app) or executable file (.exe) containing the visual class library.

Remarks

.Vcx visual class libraries are opened with SET CLASSLIB. Once the library is open, the class definitions within the visual class library are available to programs and from the Command window.

To close all open visual class libraries, issue SET CLASSLIB TO without any additional arguments.

Example

The following example uses CREATE CLASSLIB to create a visual class library named myclslib. A class named myform based on the Visual FoxPro Form base class is created and is stored in the myclslib visual class library. SET CLASSLIB is used to open the myclslib visual class library so that classes within it can be used. RELEASE CLASSLIB is then used to close the myclslib visual class library.
Copy Code
CREATE CLASSLIB myclslib     && Creates a new .VCX visual class library
CREATE CLASS myform OF myclslib AS "Form"  && Creates new class
SET CLASSLIB TO myclslib ADDITIVE     && Opens MyClsLib.VCX
RELEASE CLASSLIB myclslib

See Also

Other Resources

Commands
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
MODIFY CLASS Command
REMOVE CLASS Command
RENAME CLASS Command
SET CLASSLIB Command


RELEASE Command

Visual FoxPro 9.0 Language Reference
RELEASE Command
See Also

Removes variables and arrays from memory. There are several versions of the syntax.

RELEASE MemVarList
RELEASE ALL [EXTENDED]
RELEASE ALL [LIKE Skeleton | EXCEPT Skeleton]

Parameters

RELEASE MemVarList

Specifies the variables and arrays released from memory. Separate the variables and array names with commas.
RELEASE ALL

Releases from memory all variables and arrays.
EXTENDED

When issued in a program, specifies that all public variables are released. RELEASE ALL does not release public variables when issued in a program.
LIKE Skeleton | EXCEPT Skeleton

Releases from memory all variables and arrays that match the specified skeleton, or all variables and arrays except those that match the specified skeleton. Skeleton can include the wildcards ? and *. RELEASE ALL LIKE and RELEASE ALL EXCEPT do not release public variables when issued in a program.

See Also

Other Resources

Commands
CLEAR MEMORY Command
DIMENSION Command
PRIVATE Command
PUBLIC Command
STORE Command


RELEASE LIBRARY Command

Visual FoxPro 9.0 Language Reference
RELEASE LIBRARY Command
See Also

Removes a single external API library from memory.

RELEASE LIBRARY LibraryName

Parameters

LibraryName

Specifies the name of the API library to remove from memory.

Remarks

Issue SET LIBRARY TO to remove all API libraries from memory. An external API routine library is loaded into memory with SET LIBRARY. For more information on API routine libraries, see SET LIBRARY.

See Also

Other Resources

Commands
SET LIBRARY Command
API Library Routines A-Z
API Library Routines by Category


RELEASE MENUS Command

Visual FoxPro 9.0 Language Reference
RELEASE MENUS Command
See Also

Removes user-defined menu bars from memory.

RELEASE MENUS [MenuBarNameList [EXTENDED]]

Parameters

MenuBarNameList

Specifies the menu bars to be released from memory. Separate the menu bar names with commas.
EXTENDED

Releases a menu bar and all its subordinate menus, menu titles, menu items, and all associated ON SELECTION BAR, ON SELECTION MENU, ON SELECTION PAD, and ON SELECTION POPUP commands.

Remarks

An active menu bar must first be deactivated with DEACTIVATE MENU before it can be released from memory.

If RELEASE MENUS is issued without any additional arguments, all user-defined menu bars are removed from memory.

See Also

Other Resources

Commands
DEFINE MENU Command
ON SELECTION BAR Command
DEACTIVATE MENU Command
ON SELECTION MENU Command
ON SELECTION PAD Command
ON SELECTION POPUP Command


RELEASE PAD Command

Visual FoxPro 9.0 Language Reference
RELEASE PAD Command
See Also Example

Removes a specific menu title or all menu titles from memory.

RELEASE PAD MenuTitleName OF MenuBarName | ALL OF MenuBarName

Parameters

MenuTitleName OF MenuBarName

Specifies the menu title to remove from memory. You can remove a menu title from the Visual FoxPro system menu bar by specifying its name in MenuTitleName. For example, the command RELEASE PAD _MEDIT OF _MSYSMENU removes the Edit menu title from the Visual FoxPro system menu bar.
ALL OF MenuBarName

Specifies that every menu title in a user-defined menu bar is removed from memory. The ALL clause cannot be used to remove menu titles from the Visual FoxPro system menu bar.

Example

The following example removes the Window menu title from the system menu bar.
Copy Code
PUSH MENU _MSYSMENU
RELEASE PAD _MSM_WINDO OF _MSYSMENU  && Removes Window menu title

WAIT WINDOW 'Press a key to restore the default menu'
POP MENU _MSYSMENU  && Restore default Visual FoxPro menu system

See Also

Other Resources

Commands
DEFINE PAD Command
RELEASE BAR Command
System Menu Names


RELEASE POPUPS Command

Visual FoxPro 9.0 Language Reference
RELEASE POPUPS Command
See Also

Removes a specific menu or all menus from memory.

RELEASE POPUPS [MenuNameList [EXTENDED]]

Parameters

MenuNameList

Specifies the menus to release from memory. Separate the menu names with commas. Visual FoxPro system menus that appear under the Visual FoxPro system menu bar can also be released. To release a Visual FoxPro system menu, include the internal name of the system menu (_MFILE, _MEDIT, _MDATA, and so on). Use SET SYSMENU TO DEFAULT to restore the default system menu bar and system menus.
EXTENDED

Releases a menu, its items, and all commands associated with ON SELECTION POPUP and ON SELECTION BAR.

Remarks

An active menu must be deactivated with DEACTIVATE POPUP before it can be released from memory.

If RELEASE POPUPS is issued without any additional arguments, all user-defined menus are removed from memory.

See Also

Other Resources

Commands
DEFINE POPUP Command
System Menu Names
SET SYSMENU Command


RELEASE PROCEDURE Command

Visual FoxPro 9.0 Language Reference
RELEASE PROCEDURE Command
See Also

Closes procedure files opened with SET PROCEDURE.

RELEASE PROCEDURE FileName1 [, FileName2 ...]

Parameters

FileName1 [, FileName2 ...]

Specifies the name of the procedure file or a set of procedure files to close.

Remarks

Procedure files are opened with SET PROCEDURE. Once the file is open, the procedures within the file are available to programs and from the Command window.

To close all open procedure files, issue SET PROCEDURE TO without any additional arguments.

See Also

Other Resources

Commands
SET PROCEDURE Command
RELEASE BAR Command
RELEASE Command


RELEASE WINDOWS Command

Visual FoxPro 9.0 Language Reference
RELEASE WINDOWS Command
See Also

Removes user-defined windows or Visual FoxPro system windows from memory.

RELEASE WINDOWS [WindowNameList]

Parameters

WindowNameList

Specifies the windows released from memory. WindowNameList can include both user-defined windows and Visual FoxPro system windows. Separate the window names with commas. If WindowNameList isn't included, the active user-defined window is released.

Remarks

RELEASE WINDOWS can be used to remove Visual FoxPro system windows from the main Visual FoxPro window from or a parent, user-defined window.

The following list includes system windows that can be released from the main Visual FoxPro window or from a parent window.

  • Command

  • Data Session (use RELEASE WINDOW "View")

  • Debug

  • Debug Output

  • Document View

  • Locals

  • Trace

  • Watch

  • View

To release a system window and/or a toolbar (in Visual FoxPro), enclose the entire system window or toolbar name in quotation marks. For example, to release the Report Controls toolbar in Visual FoxPro, issue the following command:

Copy Code
RELEASE WINDOW "Report Controls"

Historically in prior versions of Visual FoxPro, the Data Session window has always been referred to as the View window. Additionally, language used to control this window, such as HIDE WINDOW, ACTIVATE WINDOW, WONTOP( ), also refers to this window as the View window. Visual FoxPro continues to refer to the View window for the RELEASE WINDOWS command.

Use ACTIVATE WINDOW to place a system window in the main Visual FoxPro window or in a user-defined window.

See Also

Other Resources

Commands
ACTIVATE WINDOW Command
DEFINE WINDOW Command


REMOVE CLASS Command

Visual FoxPro 9.0 Language Reference
REMOVE CLASS Command
See Also

Removes a class definition from a .vcx visual class library.

REMOVE CLASS ClassName OF ClassLibraryName

Parameters

ClassName

Specifies the name of the class definition to remove from the visual class library.
OF ClassLibraryName

Specifies the name of the .vcx visual class library containing the class definition to remove. If no file extension is included in ClassLibraryName, a .vcx extension is assumed.

Remarks

Exercise care when removing class definitions — the class definition you remove may be a parent class on which other classes are based.

See Also

Other Resources

Commands
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
MODIFY CLASS Command
RELEASE CLASSLIB Command
RENAME CLASS Command
SET CLASSLIB Command


REMOVE TABLE Command

Visual FoxPro 9.0 Language Reference
REMOVE TABLE Command
See Also Example

Removes a table from the current database.

REMOVE TABLE TableName | ? [DELETE] [RECYCLE]

Parameters

TableName | ?

Specifies the table to remove from the current database or displays the Remove dialog box so you can choose a table in the current database to remove.
[DELETE]

Removes the table from the database and deletes it permanently from disk.
Caution:
Tables deleted using the DELETE keyword cannot be retrieved. Visual FoxPro does not confirm deletion or provide a warning even if the SET SAFETY command is set to ON.

[RECYCLE]

Specifies to delay deleting the table from disk and moves it to the Windows Recycle Bin.

Remarks

REMOVE TABLE removes all primary indexes, default values, and validation rules associated with the table. If SET SAFETY is set to ON, Visual FoxPro prompts you to confirm removing the table from the database.

When a table is removed from the database, it becomes a free table and can be added to another database.

Caution:
REMOVE TABLE affects other tables in the current database if those tables have rules or relations associated with the table being removed. The rules and relations are no longer valid when the table is removed from the database.

Example

The following example creates two databases named mydbc1 and mydbc2, and a table named table1. The table is added to mydbc1 when it is created. The table is then closed and removed from mydbc1. ADD TABLE is then used to add the table to mydbc2. RENAME TABLE is used to change the name of the table from table1 to table2.
Copy Code
CREATE DATABASE mydbc1
CREATE DATABASE mydbc2
SET DATABASE TO mydbc1
CREATE TABLE table1 (cField1 C(10), n N(10))  && Adds table to mydbc1
CLOSE TABLES     && A table must be closed to remove it from a database
REMOVE TABLE table1
SET DATABASE TO mydbc2
ADD TABLE table1
RENAME TABLE table1 TO table2

See Also

Reference

INDBC( ) Function

Other Resources

How to: Remove a Table from a Database
Commands
CLOSE Commands
DROP TABLE Command


RENAME CLASS Command

Visual FoxPro 9.0 Language Reference
RENAME CLASS Command
See Also Example

Renames a class definition contained in a .VCX visual class library.

RENAME CLASS ClassName1 OF ClassLibraryName TO ClassName2

Parameters

ClassName1

Specifies the name of the class definition that is renamed.
OF ClassLibraryName

Specifies the name of the .vcx visual class library containing the class definition to rename. If you don't specify a file extension in ClassLibraryName, Visual FoxPro automatically assigns a .vcx extension.
TO ClassName2

Specifies the new name of the class definition.

Remarks

Visual FoxPro does not update other class definitions within the visual class library that reference the renamed class definition — be careful when renaming class definitions.

Example

The following example uses CREATE CLASSLIB to create a visual class library named myclslib. A class named myform based on the Visual FoxPro Form base class is created with CREATE CLASS and is stored in the myclslib visual class library. RENAME CLASS is used to change the class name from myform to yourform.
Copy Code
CREATE CLASSLIB myclslib     && Creates a new .VCX visual class library
CREATE CLASS myform OF myclslib AS "Form"  && Creates new class
RENAME CLASS myform OF myclslib TO yourform  && Change class name

See Also

Other Resources

Commands
ADD CLASS Command
CREATE CLASS Command
MODIFY CLASS Command
RELEASE CLASSLIB Command
REMOVE CLASS Command
SET CLASSLIB Command


RENAME Command

Visual FoxPro 9.0 Language Reference
RENAME Command
See Also Example

Changes the name of a file to a new name.

Note:
Do not use RENAME to change the name of a table in a database; RENAME does not change the name of the table in the database. Instead, use RENAME TABLE to change the name of a table in a database. For more information, see RENAME TABLE Command.

RENAME FileName1 TO FileName2

Parameters

FileName1 TO FileName2

Specifies the file name to change and the new file name. Include a file extension for each file.
Note:
If the file extensions are not included, the default extension .dbf is assumed. To rename a file that does not have an extension, include a period (.) after the file name. If you rename a free table that has an associated .fpt memo file, be sure to rename the memo file.

Remarks

FileName1 and FileName2 can contain wildcard characters such as * and ?. For example, to rename all program files with the extension .prg in the current directory or folder to backup files with extension .bak, issue RENAME *.prg TO *.bak.

If the files are not on the default path, include paths with either or both file names.

If FileName1 and FileName2 are in different directories or folders, FileName1 is moved into the directory or folder of FileName2.

When you issue RENAME, FileName2 cannot already exist and FileName1 must exist and cannot be open.

Example

The following example shows how to switch file names between two files. Visual FoxPro will generate an error if you attempt to rename a file to a name which already exists (this is shown by the Try…Catch statement). The example uses multiple RENAME calls with an extra temporary file to accomplish the name switching.
Copy Code
STRTOFILE("File 1", "tmpFile1.txt")
STRTOFILE("File 2", "tmpFile2.txt")
TRY
RENAME tmpFile1.txt TO tmpFile2.txt
CATCH TO oError
? oError.Message
ENDTRY
RENAME tmpFile2.txt TO tmpFile2.bkup
RENAME tmpFile1.txt TO tmpFile2.txt
RENAME tmpFile2.bkup TO tmpFile1.txt
MODIFY FILE tmpFile1.txt NOWAIT
MODIFY FILE tmpFile2.txt NOWAIT

See Also

Other Resources

Commands
COPY FILE Command
COPY TO Command
RENAME CLASS Command


RENAME CONNECTION Command

Visual FoxPro 9.0 Language Reference
RENAME CONNECTION Command
See Also Example

Renames a named connection in the current database.

RENAME CONNECTION ConnectionName1 TO ConnectionName2

Parameters

ConnectionName1

Specifies the name of the connection to be renamed.
ConnectionName2

Specifies the new name of the connection.

Remarks

The database containing the named connection must be opened exclusively and must be current before the connection can be renamed. To open a database for exclusive use, include EXCLUSIVE in OPEN DATABASE.

Example

The following example assumes an ODBC data source called MyFoxSQLNT is available. The testdata database is opened, and a connection named Myconn1 is created. DISPLAY CONNECTIONS is used to display the named connections in the database.

RENAME CONNECTION is then used to change the newly created connection name to Myconn2. DISPLAY CONNECTIONS is used again to display the connection with its new name. The newly renamed connection is then removed from the database with DELETE CONNECTION.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
CREATE CONNECTION Myconn1 DATASOURCE "MyFoxSQLNT" USERID "<userid>" PASSWORD "<password>"

CLEAR
DISPLAY CONNECTIONS  && Displays named connections in the database
RENAME CONNECTION Myconn1 TO Myconn2
DISPLAY CONNECTIONS  && Displays connection with new name

DELETE CONNECTION Myconn2  && Removes the connection just renamed

See Also

Other Resources

Commands
DELETE CONNECTION Command
DBGETPROP( ) Function
DISPLAY CONNECTIONS Command
LIST CONNECTIONS Command
MODIFY CONNECTION Command
OPEN DATABASE Command


RENAME TABLE Command

Visual FoxPro 9.0 Language Reference
RENAME TABLE Command
See Also Example

Renames a table in the current database.

RENAME TABLE TableName1 TO TableName2

Parameters

TableName1

Specifies the name of the table to be renamed.
TableName2

Specifies the new name of the table.

Remarks

You cannot use RENAME TABLE to change the name of a free table; use RENAME instead.

Example

The following example creates two databases named mydbc1 and mydbc2, and a table named table1. The table is added to mydbc1 when it is created. The table is then closed and removed from mydbc1. ADD TABLE is then used to add the table to mydbc2. RENAME TABLE is used to change the name of the table from table1 to table2.
Copy Code
CLOSE DATABASES
CREATE DATABASE mydbc1
CREATE DATABASE mydbc2
SET DATABASE TO mydbc1
CREATE TABLE table1 (cField1 C(10), n N(10))  && Adds table to mydbc1
CLOSE TABLES     && A table must be closed to remove it from a database
REMOVE TABLE table1
SET DATABASE TO mydbc2
ADD TABLE table1
RENAME TABLE table1 TO table2

See Also

Other Resources

Commands
ADD TABLE Command
CLOSE DATABASES Command
CREATE DATABASE Command
COPY FILE Command
COPY TO Command
OPEN DATABASE Command
RENAME Command


RENAME VIEW Command

Visual FoxPro 9.0 Language Reference
RENAME VIEW Command
See Also Example

Renames a SQL view in the current database.

RENAME VIEW ViewName1 TO ViewName2

Parameters

ViewName1

Specifies the name of the SQL view to be renamed.
ViewName2

Specifies the new name of the SQL view.

Remarks

The database containing the SQL view must be opened exclusively and must be current before the SQL view can be renamed. To open a database for exclusive use, include EXCLUSIVE in OPEN DATABASE.

Example

The following example opens the testdata database. CREATE SQL VIEW is used to create a local SQL view named myview, which is created from a SELECT - SQL statement that selects all records from the customer table. RENAME VIEW is used to change the name of the view from myview to yourview.

The View Designer is displayed, allowing modify the newly renamed SQL view. After the View Designer is closed, the SQL view is erased.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')

CREATE SQL VIEW myview AS SELECT * FROM customer  && Create the view
RENAME VIEW myview TO yourview  && Change the view name
MODIFY VIEW yourview  && Open the View designer
DELETE VIEW yourview  && Delete the view

See Also

Reference

RENAME VIEW Command

Other Resources

Commands
CREATE SQL VIEW Command
DELETE VIEW Command
DISPLAY VIEWS Command
LIST VIEWS Command
MODIFY VIEW Command
OPEN DATABASE Command
SELECT - SQL Command
USE Command


REPLACE Command (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
REPLACE Command (Visual FoxPro)
See Also Example

Updates table records.

REPLACE FieldName1 WITH eExpression1 [ADDITIVE]
   [, FieldName2 WITH eExpression2 [ADDITIVE]] ... [Scope]
   [FOR lExpression1] [WHILE lExpression2] [IN nWorkArea | cTableAlias]
   [NOOPTIMIZE]

Parameters

FieldName1 WITH eExpression1[, FieldName2 WITH eExpression2... ]

Specifies that the data in FieldName1 be replaced with the value of the expression eExpression1; that the data in FieldName2 be replaced with the value of the expression eExpression2; and so on. When the expression value is longer than the width of a numeric field, REPLACE forces the value to fit by carrying out the following steps:
  • First, REPLACE truncates decimal places and rounds the remaining decimal portion of the field.

  • If the value still doesn't fit, REPLACE stores the field contents using scientific notation.

  • If the value still doesn't fit, REPLACE replaces the field contents with asterisks.

ADDITIVE

Appends to the end of the memo fields replacements to memo fields. ADDITIVE applies to replacements in memo fields only. If you omit ADDITIVE, the memo field is overwritten with the value of the expression.
Scope

Specifies a range of records to replace. The default scope for REPLACE is the current record (NEXT 1). Only the records that fall within the range are replaced. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see Scope Clauses.
FOR lExpression1

Specifies that the designated fields be replaced only in records for which lExpression1 evaluates to true (.T.). Including FOR makes it possible for you to conditionally replace records, filtering out those you don't want replaced. Rushmore Query Optimization optimizes REPLACE FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies a condition whereby fields are replaced for as long as the logical expression lExpression2 evaluates to true (.T.).
IN nWorkArea

Specifies the work area of the table in which records are updated.
IN cTableAlias

Specifies the alias of the table in which records are updated. If you omit nWorkArea and cTableAlias, records are updated in the table in the currently selected work area.
NOOPTIMIZE

Prevents Rushmore optimization. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

Remarks

REPLACE replaces data in a field with the value in an expression. Fields in unselected work areas must be prefaced with their alias.

Note:
If the IN clause is omitted, no replacement occurs if the record pointer is at the end of the file in the current work area and you specify a field in another work area.

Example

The following example creates a table with 10 records. REPLACE is used to place random values into a field. MIN( ) and MAX( ) displays the maximum and minimum values in the table.
Copy Code
CLOSE DATABASES
CREATE TABLE Random (cValue N(3))
FOR nItem = 1 TO 10  && Append 10 records,
   APPEND BLANK
   REPLACE cValue WITH 1 + 100 * RAND( )  && Insert random values
ENDFOR

CLEAR
LIST  && Display the values
gnMaximum = 1  && Initialize minimum value
gnMinimum = 100  && Initialize maximum value
SCAN
   gnMinimum = MIN(gnMinimum, cValue)
   gnMaximum = MAX(gnMaximum, cValue)
ENDSCAN
? 'The minimum value is: ', gnMinimum  && Display minimum value
? 'The maximum value is: ', gnMaximum  && Display maximum value

See Also

Other Resources

Commands
GATHER Command
INSERT - SQL Command
SCATTER Command


REPLACE FROM ARRAY Command

Visual FoxPro 9.0 Language Reference
REPLACE FROM ARRAY Command
See Also

Updates data in fields with values from a variable array.

REPLACE FROM ARRAY ArrayName [FIELDS FieldList] [Scope]
   [FOR lExpression1] [WHILE lExpression2] [NOOPTIMIZE]

Parameters

ArrayName

Specifies the name of the array whose values replace the field data.
FIELDS FieldList

Specifies that only the fields in FieldList be replaced by the contents of the array. Fields in unselected work areas must be prefaced with their table alias.
Scope

Specifies a range of records to replace with the contents of the array. The default scope for REPLACE FROM ARRAY is the current record (NEXT 1). Only the records that fall within the range are replaced. Replacement occurs until the end of the scope or the end of the array is reached. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see Scope Clauses.
FOR lExpression1

Specifies that fields be replaced only in records for which lExpression1 evaluates to true (.T.). Including FOR makes it possible for you to conditionally replace records, filtering out those you don't want. Replacement occurs in each record for which lExpression1 is true (.T.), or until the end of the array is reached. Rushmore Query Optimization optimizes REPLACE FROM ARRAY FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access .
WHILE lExpression2

Specifies a condition whereby fields in records are replaced by the contents of the array for as long as the logical expression lExpression2 evaluates to true (.T.).
NOOPTIMIZE

Prevents Rushmore optimization. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access .

Remarks

Memo and general fields are ignored in REPLACE FROM ARRAY. To import data into these fields, use GATHER and APPEND GENERAL.

Starting with the first element, the elements of the array replace the corresponding fields of the record. The first array element replaces the first field of the record, the second array element replaces the second field, and so on.

If the array has fewer elements than the table has fields, the additional fields are ignored. If the array has more elements than the table has fields, the additional array elements are ignored.

Note:
No replacement occurs if the record pointer is at the end of the file in the current work area and you specify a field in another work area.

See Also

Other Resources

Commands
APPEND FROM ARRAY Command
APPEND GENERAL Command
COPY TO ARRAY Command
GATHER Command
REPLACE Command
SCATTER Command
SET OPTIMIZE Command


REPORT FORM Command

Visual FoxPro 9.0 Language Reference
REPORT FORM Command
See Also

Displays or prints a report specified by a report definition (.frx) file, for example, created with the CREATE REPORT or MODIFY REPORT command.

The REPORT FORM command can interpret Visual FoxPro label files (lbx format) as well as report files. You can also use REPORT FORM to run character-based report files created in FoxPro for MS-DOS.

REPORT FORM FileName1 | ? [ENVIRONMENT] [Scope]
   [FOR lExpression1] [WHILE lExpression2] [NOOPTIMIZE]
   [RANGE nStartPage [, nEndPage]]
   [HEADING cHeadingText] [SUMMARY] [NORESET] [PLAIN]
   [NOCONSOLE | OFF] [PDSETUP]
   [NAME ObjectName]
   [OBJECT oReportListener | TYPE iExpression]
   [TO OutputDestination [NODIALOG]]
   [PREVIEW [PreviewDestination] [NOWAIT] [WINDOW WindowName]]

Parameters

FileName1 | ?

Specifies the name of a report definition (.frx) file or displays the Open dialog box so you can choose an .frx file. By default, the report displays in the current output window.
Note:
The default file name extension for a report definition file is .frx. If the .frx file is not in the default directory or folder, you must include file name with the path. Starting with Visual FoxPro 7.0, FileName1 is included in the status message, which appears when you include the TO clause. To suppress the status message, see the description for the TO clause.

[ENVIRONMENT]

Opens and restores all tables and relations in the data environment associated with the report even when AutoOpenTables is set to False (.F.).
Note:
The ENVIRONMENT keyword is included for backward compatibility, for example, reports converted from earlier versions of FoxPro, such as 2.x reports.

To restore the data environment associated with a Visual FoxPro report, set the data environment's AutoOpenTables property to True (.T.) (default). To make sure that the report environment is closed when the report has finished printing, set the data environment's AutoCloseTables property to True (.T.) (default). For more information, see AutoOpenTables Property and AutoCloseTables Property.
[Scope]

Specifies a range of records to include in the report. Only the records that fall within the scope range are included in the report.
Note:
When you include a Scope clause, the scope operates only on the table in the active work area.

The following table lists possible values for Scope.

Scope Description

ALL

Include all records. (Default)

NEXT nRecords

Include the next nRecords number of records beginning with the current record.

RECORD nRecordNumber

Include only the specified record.

REST

Include a range of records beginning with the current record and ending with the last record.
For more information on scope clauses, see Scope Clauses.
[FOR lExpression1]

Prints data only in those records for which the logical expression specified by lExpression1 evaluates to Tue (.T.). By including the FOR clause, you can exclude records you do not want to print.
Tip:
If lExpression1 is an optimizable expression, Rushmore Query Optimization optimizes REPORT FORM with the FOR clause. For best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access .

[WHILE lExpression2]

Prints data only while the logical expression specified by lExpression2 evaluates to True (.T.).
[NOOPTIMIZE]

Prevents Rushmore optimization for REPORT FORM. For more information, see SET OPTIMIZE 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.
Note:
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 REPORT FORM command or some subset of that page range, using the ReportListener.CommandClauses's PrintPageCurrent, PrintRangeFrom, and PrintRangeTo members. For more information, see OnPreviewClose Method.

[HEADING cHeadingText]

Specifies text to place as an additional heading on each page of the report. If you include the HEADING clause and PLAIN keyword, the PLAIN keyword takes precedence.
[SUMMARY]

Suppresses detail line printing so that only totals and subtotals print.
[NORESET]

Specifies that the _PAGENO and _PAGETOTAL system variables are not reset. The page count for the current report begins at the current values of these two variables. For more information, see _PAGENO System Variable and _PAGETOTAL System Variable.
Note:
If you use the NORESET and RANGE keywords together, you must calculate beforehand which pages to print.

[PLAIN]

Suppresses page headings except at the beginning of the report.
[NOCONSOLE | OFF]

Suppresses displaying the report in the main Visual FoxPro window or a user-defined window when printing the report or sending it to a file.
Note:
When you use Visual FoxPro 9.0's object-assisted output mode, REPORT FORM does not display the contents of your report 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 report content or other user feedback based on their contents. For more information, see CommandClauses Property.

[PDSETUP]

Loads a printer driver setup. You can include PDSETUP to use a printer driver setup for printing character-based reports created in FoxPro for MS-DOS. PDSETUP is ignored when you print graphics-based reports created in Visual FoxPro.
[NAME ObjectName]

Specifies an object variable name for the data environment associated with the report.
Note:
The data environment and the objects in the data environment have properties and methods, such as the AddObject method, 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 the name of the report file, which can be referenced in code associated with events, by default.
[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. The OBJECT clause on an individual REPORT FORM command takes precedence over the current setting of SET REPORTBEHAVIOR. For more information, see ReportListener Object, ListenerType Property, and OutputType Property (Visual FoxPro).
[TO OutputDestination [NODIALOG]]

Specifies an output destination for the report. To suppress status messages that appear at run time, include the NODIALOG keyword.
Note:
In output-assisted output mode, NODIALOG sets the ReportListener object's QuietMode property to .T. for the duration of the report run. For more information, see QuietMode Property.

The following table describes the possible values of OutputDestination.

OutputDestination Description

[PRINTER [PROMPT] [NOPAGEEJECT] [NOEJECT]]

Sends the report to the printer.

To display the Print dialog box before printing starts, include the PROMPT keyword. In object-assisted mode, the options enabled in the Print dialog box are affected by the ReportListener.CommandClauses.PrintPageCurrent member value.

To specify that Visual FoxPro does not force a sheet eject at the end of a report and leaves the print job open, include the NOPAGEEJECT keyword. The next report printed is added to the open print job.

You must make sure that the last report run does not have a NOPAGEEJECT clause so the print job can be closed.

NOPAGEEJECT is valid only during program execution. It is disregarded when issued in the Command window. Changing between page orientations, such as landscape to portrait, between reports is not supported.

You can chain multiple reports using NOPAGEEJECT and have page numbers continue from one report to the next. This is a useful technique for tasks such as faxing reports.

The REPORT FORM command also allows a NOEJECT keyword, which Visual FoxPro no longer supports but was used in older DOS versions of FoxPro and FoxBASE+. This keyword does not perform any function but does not trigger an error.

[FILE] FileName2 [[ADDITIVE] ASCII]

Specifies the name of a text file to send the report to. The default file name extension for file created is .txt.

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 report. To create an ASCII text file from the report definition file, SET REPORTBEHAVIOR 80 and include the ASCII keyword.

Note:
When you include the ASCII keyword, you can process a report on a computer that has no printer driver setups installed. Without the ASCII keyword, a REPORT FORM command issued on a computer that has no printer driver setups installed generates an error.

An ASCII file contains only text. If the report is a character-based layout definition created in FoxPro for MS-DOS, dashes, and plus signs may be included to represent lines and shapes. Otherwise, any font or color settings, graphics, lines, rectangles, or rounded rectangles in the report definition file do not appear in the ASCII text file. You can specify the number of characters to place on each line and the number of lines to place on each page by using the _ASCIICOLS and _ASCIIROWS system variables. The default values for these system variables correspond to a standard portrait page. For more information, see _ASCIICOLS System Variable and _ASCIIROWS System Variable.

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.

[PREVIEW [ PreviewDestination] [NOWAIT][WINDOW WindowName]]

Displays the report in preview window instead of printing the report. 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 report.

If you include IN WINDOW <WindowName>, the report 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

When you use Visual FoxPro's object-assisted output mode, all the clauses of the REPORT 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 report run, or assign these values to your ReportListener object before running your report. The CommandClauses Property topic gives you more information about how each clause is represented in the CommandClauses member object.

Examples

Example 1

The following example shows how to run a batch report print job with two reports. Visual FoxPro runs through the set of reports twice to obtain a total page count, which is stored in the _PAGETOTAL system variable for enabling Page X of Y expressions in the report layouts.

Note:
You can ensure that the report runs through twice by including _PAGETOTAL in your report expressions. If you do not need _PAGETOTAL but would like the two passes to run for other calculations, you can use object-assisted output mode and set the ReportListener TwoPassProcess property to .T.. For more information, see TwoPassProcess Property.

NORESET specifies that page numbers continue printing with the next report. NOPAGEEJECT specifies that the first page of the second report continue printing on the reverse side of the last page of the first report.

Copy Code
REPORT FORM myReport1.frx TO PRINTER NOPAGEEJECT
REPORT FORM myReport2.frx TO PRINTER NORESET
MESSAGEBOX("You printed " + ;
   TRANSFORM(_PAGETOTAL)+" pages.")

Example 2

The following example shows how you can view a preview before sending the report to a printer.

Copy Code
REPORT FORM myReport1.frx TO PRINTER PROMPT NODIALOG PREVIEW

To make the preview window modeless, the following code includes the NOWAIT keyword:

Copy Code
REPORT FORM myReport1.frx PREVIEW NOWAIT

To preview the results in a specific window, the following code includes the WINDOW clause to specify a window named MyWindow that you previously created with the DEFINE WINDOW command:

Copy Code
REPORT FORM myReport1.frx PREVIEW WINDOW MyWindow

Example 3

The following example shows how to send a report to an ASCII file. The _ASCIIROWS and _ASCIICOLS system variables define the number of lines and characters per line on the ASCII page. The REPORT FORM command prints a report named MyReport.frx to an ASCII file name MyFile.txt.

Copy Code
SET REPORTBEHAVIOR 80
_ASCIIROWS = nLines
_ASCIICOLS = nChars
REPORT FORM MyReport.frx TO FILE MyFile.txt ASCII

See Also

Reference

ReportListener Object
SET REPORTBEHAVIOR Command
LABEL Command
The Preview Container API

Other Resources

Commands
CREATE REPORT Command
MODIFY REPORT Command
DataEnvironment Object


RESTORE FROM Command

Visual FoxPro 9.0 Language Reference
RESTORE FROM Command
See Also Example

Retrieves variables and variable arrays saved in a variable file or a memo field and places them into memory.

RESTORE FROM FileName | MEMO MemoFieldName   [ADDITIVE]

Parameters

FileName

Specifies the variable file from which the variables and arrays are restored. Variable files are assigned a .mem extension.
MEMO MemoFieldName

Specifies the memo field from which variables and arrays are restored.
ADDITIVE

Prevents any variables or arrays currently in memory from being erased. If the number of variables or arrays being added with ADDITIVE plus the number of existing variables exceeds the variable limit, Microsoft Visual FoxPro brings as many variables and arrays as possible into memory from the variable file or memo field. If you restore a variable or array that has the same name as an existing variable or array, the value in the existing variable or array is overwritten with the value of the restored variable or array.

Remarks

When RESTORE FROM is issued in a program, all PUBLIC and PRIVATE variables and arrays are restored as PRIVATE; all LOCAL variables and arrays are restored as LOCAL. If RESTORE is issued in the Command window, PUBLIC and PRIVATE variables and arrays are restored as PUBLIC; LOCAL variables and arrays are restored as LOCAL.

RESTORE FROM clears any variables or arrays currently in memory unless you include the ADDITIVE keyword. RESTORE FROM does not affect system variables.

Note that object type variables cannot be restored from a variable file or memo field.

Example

In the following example, two variables are created. They are saved to a variable file and restored without clearing the existing variables.
Copy Code
gnVal1 = 50
gcVal2 = 'Hello'
SAVE TO temp
CLEAR MEMORY

gdVal3 = DATE( )
RESTORE FROM temp ADDITIVE
CLEAR
DISPLAY MEMORY LIKE g*

See Also

Other Resources

Commands
DIMENSION Command
PUBLIC Command
PRIVATE Command
RELEASE Command
SAVE TO Command
STORE Command


RESTORE MACROS Command

Visual FoxPro 9.0 Language Reference
RESTORE MACROS Command
See Also

Restores to memory keyboard macros saved in a keyboard macro file or memo field.

RESTORE MACROS   [FROM FileName | FROM MEMO MemoFieldName]

Parameters

FROM FileName

Specifies the macro file from which macros are restored. Macro files have an .fky extension, and this extension is assumed if you don't specify one. If you have assigned a different extension to the file, you must include this extension in FileName.
FROM MEMO MemoFieldName

Specifies the memo field from which macros are restored.

Remarks

Use SAVE MACRO to store keyboard macros to a keyboard macro file or a memo field.

By default, restoring macros from a file or memo field is additive — the restored macros are appended to the existing set of macros in memory. If a macro name in the file or memo field is the same as an existing macro name, the macro in the file or memo field overwrites the existing macro.

If issued without a file name or memo field name, RESTORE MACROS clears all macros from memory and restores the default macros. The default macros are restored from the keyboard macro file named Default.fky. If Default.fky cannot be found, Visual FoxPro restores the F2 through F9 keys to the standard Visual FoxPro startup settings.

See Also

Other Resources

Commands
CLEAR Command
PLAY MACRO Command
SAVE MACROS Command


RESTORE SCREEN Command

Visual FoxPro 9.0 Language Reference
RESTORE SCREEN Command
See Also

Restores the main Visual FoxPro window or a user-defined window previously saved to the screen buffer, a variable, or an array element.

RESTORE SCREEN   [FROM VarName]

Parameters

FROM VarName

Specifies the name of a variable or array element from which you want to restore the screen or window image.

Remarks

Use SAVE SCREEN to place the current main Visual FoxPro window or active user-defined window in the screen buffer, a variable, or an array element.

Variables or array elements containing stored screen or window images have an S data type when you view the variables or array elements with DISPLAY or LIST MEMORY. The main Visual FoxPro window or user-defined windows saved to variables or array elements can also be saved to and restored from variable files with SAVE TO and RESTORE FROM.

If issued without the FROM clause, RESTORE SCREEN restores the main Visual FoxPro window or user-defined window from the screen buffer.

See Also

Other Resources

Commands
RESTORE FROM Command
SAVE SCREEN Command
SAVE TO Command


RESTORE WINDOW Command

Visual FoxPro 9.0 Language Reference
RESTORE WINDOW Command
See Also Example

Restores to memory window definitions and window statuses saved to a window file or memo field.

RESTORE WINDOW WindowNameList | ALL FROM FileName
 | FROM MEMO MemoFieldName

Parameters

WindowNameList

Specifies one or more windows to be restored. Separate the window names with commas.
ALL

Restores all window definitions in the window file or memo field.
FROM FileName

Specifies the window file from which windows are restored. A window file has a .win extension. If the file was given another extension when it was saved, you must include this extension in FileName.
FROM MEMO MemoFieldName

Specifies the memo field from which the windows are restored.

Remarks

Use SAVE WINDOW to store window definitions in a window file or in a memo field.

Any windows in memory with the same names as those restored are overwritten. A window's status (hidden, active, and so on) when it is saved is preserved when it is restored.

Example

In the following example, a window named wOutput1 is defined and saved to a variable. All windows are cleared and the window named wOutput1 is restored and activated.
Copy Code
CLEAR
DEFINE WINDOW wOutput1 FROM 2,1 TO 13,75 TITLE 'Output' ;
   CLOSE FLOAT GROW ZOOM
SAVE WINDOW wOutput1 TO temp
CLEAR WINDOWS
RESTORE WINDOW wOutput1 FROM temp
ACTIVATE WINDOW wOutput1
WAIT "The window wOutput1 has been restored" WINDOW
RELEASE WINDOW wOutput1

See Also

Other Resources

Commands
ACTIVATE WINDOW Command
DEFINE WINDOW Command
SAVE WINDOWS Command


RESUME Command

Visual FoxPro 9.0 Language Reference
RESUME Command
See Also

Continues execution of a suspended program.

RESUME

Remarks

Use SUSPEND to suspend program execution. The suspended program restarts at the line where execution was suspended.

SUSPEND and RESUME are valuable debugging tools. You can suspend a program to examine the current status of the Visual FoxPro environment, including memory variables, window, menu bar, or menu definitions.

Caution:
To prevent commands that are executed when a program is suspended from interfering with subsequent program output, issue CLEAR to clear the main Visual FoxPro window or the active user-defined window before you resume program execution.

See Also

Other Resources

Commands
CANCEL Command
CLEAR Command
RETURN Command
SUSPEND Command


RETRY Command

Visual FoxPro 9.0 Language Reference
RETRY Command
See Also

Executes the last command from the memory stack and then returns control to the calling program. RETRY is similar to RETURN, except RETURN executes the next line in the calling program.

RETRY

Remarks

RETRY is useful in error-handling routines. It is frequently used to execute a command until a record- or file-locking function succeeds in locking the record or file. You can use SET REPROCESS to control retries of a record- or file-locking function. SET REPROCESS is preferable in most network situations.

See Also

Other Resources

Commands
ON ERROR Command
RETURN command
SET REPROCESS Command


RETURN Command

Visual FoxPro 9.0 Language Reference
RETURN Command
See Also

Returns program control to a calling program.

RETURN [eExpression | oObjectName | TO MASTER | TO ProcedureName]

Parameters

eExpression

Specifies an expression returned to the calling program. If you omit RETURN or the return expression, true (.T.), it is automatically returned to the calling program.
oObjectName

Specifies the object to which focus is assigned. Applies only to Valid Event.
TO MASTER

Returns control to the highest-level calling program.
TO ProcedureName

Specifies the procedure to which control is returned.

Remarks

RETURN terminates execution of a program, procedure, or function and returns control to the calling program, the highest-level calling program, another program, or the Command window.

Visual FoxPro releases PRIVATE variables when RETURN is executed.

RETURN is usually placed at the end of a program, procedure, or function to return control to a higher-level program. However, an implicit RETURN is executed if you omit RETURN.

You can direct where focus is assigned using the optional oObjectName parameter in the RETURN command of the Valid Event. The object specified must be a valid Visual FoxPro object. If the specified object is disabled or cannot receive focus, then focus is assigned to the next object in the tab order. If an invalid object is specified, Visual FoxPro keeps the focus at the current object. You can now set focus to objects on another visible form or on a non-visible Page or Pageframe control.

Example 1

Description

In the following example, the function longdate returns a character string that is suitable for printing from a date.

Code

Copy Code
SET CENTURY ON
? longdate({^1998-02-16})  && Displays Monday, February 16, 1998

FUNCTION longdate
PARAMETER mdate
RETURN CDOW(mdate) + ', ' + MDY(mdate)

Example 2

Description

You can return arrays directly from a class method using the @ operator. Returning arrays from a class method allows Visual FoxPro COM components to communicate with other COM components such as those written in Visual Basic or Visual C++. This can affect methods implemented from an interface using the IMPLEMENTS clause.

Because such arrays must be in scope after the method call, LOCAL and PRIVATE arrays are invalid in these declarations. You must use either a PUBLIC or a member array. This array support does not work with the STORE TO command.

In the following example, the class t1 has a function GetMyArray returns an array.

Code

Copy Code
DEFINE CLASS t1 AS custom OLEPUBLIC
   DIMENSION Arrayelement[3]
   FUNCTION GetMyArray() AS array
      this.Arrayelement[1] = 1
      this.Arrayelement[2] = 2
      this.Arrayelement[3] = 3
      RETURN @THIS.Arrayelement
   ENDFUNC
ENDDEFINE

See Also

Other Resources

Commands
DO Command
FUNCTION Command
LPARAMETERS Command
PARAMETERS Command
PARAMETERS( ) Function
PRIVATE Command
PROCEDURE Command
PUBLIC Command


ROLLBACK Command

Visual FoxPro 9.0 Language Reference
ROLLBACK Command
See Also Example

Cancels any changes made during the current transaction.

ROLLBACK

Remarks

ROLLBACK restores the original tables, table memo files, and index files to the state they were in before the transaction began.

When you modify records in a database that is part of a transaction, other users on the network do not have access (read or write) to the records until you end the transaction.

When other users on the network try to access records you have modified, they must wait until you end your transaction. They receive the message "Record not available ... please wait" until the records become available. Because of this, it is important to keep the length of the transaction to a minimum or conduct the transaction during times when others do not need access.

ROLLBACK undoes any changes made during the current transaction. If the transaction is nested, only the modifications made since the previous BEGIN TRANSACTION are undone. Program execution continues with the next statement.

If any record or file locks were placed, they are released.

Example

In the following example, the customer table in the testdata database is opened. Optimistic table buffering is set for the customer table. The contents of the cust_id and company fields are displayed, and then the contents of the company field are replaced within the buffered data.

BEGIN TRANSACTION is issued to start a transaction. A TABLEUPDATE is used to write the changes to the table. The new contents are displayed, and ROLLBACK is issued to restore the original contents of the company field. The cust_id and company fields are displayed again with the company field containing its original values.
Copy Code
CLOSE DATABASES
CLEAR

* Transactions are only supported within a DBC
OPEN DATABASE (HOME(2) + 'Data\testdata')

SET MULTILOCKS ON      && Required for buffering

USE customer
=CURSORSETPROP("Buffering",5)
? 'The original company field'
LIST FIELDS cust_id, company NEXT 5
REPLACE ALL company WITH "***" && Change field contents

BEGIN TRANSACTION
   =TABLEUPDATE(.T.)
   GO TOP
   ? 'The modified company field'
   LIST FIELDS cust_id, company NEXT 5
ROLLBACK           && Restore original field contents

=TABLEREVERT(.T.)
GO TOP
? 'The restored company field'
LIST FIELDS cust_id, company NEXT 5

See Also

Reference

MAKETRANSACTABLE( ) Function
ISTRANSACTABLE( ) Function

Other Resources

Commands
BEGIN TRANSACTION Command
END TRANSACTION Command
TXNLEVEL( ) Function


RUN | ! Command

Visual FoxPro 9.0 Language Reference
RUN | ! Command
See Also

Executes external operating commands or programs.

RUN [/N] WindowsCommand | ProgramName
! [/N] WindowsCommand | ProgramName

Parameters

WindowsCommand

Specifies a Windows executable command to execute.
ProgramName

Specifies the Windows program or application to run.
/N

Specifies NOWAIT. Include /N to execute another Windows-based application.

Remarks

You can issue RUN from within the Command window or from within a program.

Note:
To use RUN, Command.com or Cmd.exe must be located where the COMSPEC environment variable can find it.

Caution:
Do not use RUN to run disk reorganization programs such as CHKDSK from within Visual FoxPro. These programs modify the contents of your disk in a manner that may prevent Visual FoxPro from operating properly.

RUN and Visual FoxPro

The RUN command (without /N parameter) uses the following sequence order to determine which program to use when executing the specified RUN command:

  • Named PIF file - if the program you specify in RUN does not have an extension, Visual FoxPro first looks for a Program Information File (PIF) with the name you specify. If the PIF file is found, the program specified in the PIF is executed with the PIF parameters.

  • FOXRUN.PIF file - if a Named PIF file can not be found, the RUN command searches for the default Foxrun.pif file. If this file is found, the program specified in Foxrun.pif is executed with the PIF parameters.

  • COMSPEC Environment Variable - if no PIF file is found which meets the above criteria, the RUN command uses the SHELL program specified by the Windows operating system COMSPEC environment variable. This variable typically points to Cmd.exe, however, in older operating systems such as Windows 98, it will point to Command.com.

Note:
For Visual FoxPro 9, the Foxrun.pif file is no longer installed in the Visual FoxPro root directory so that it is no longer used by default. The default behavior for Visual FoxPro 9 is that a RUN command (without /N parameter) should use the SHELL program specified by the COMSPEC environment variable. Foxrun.pif is now installed in the Visual FoxPro Tools directory if needed.

A PIF lets you run other programs under Windows. You can specify parameters for the program, such as whether the program is run in a window or on the full screen, the amount of memory allocated for the program, and so on.

If intended to be used, Foxrun.pif must be in the same directory as VFPVersionNumber.exe where VersionNumber represents the version number of this release of Visual FoxPro.

Unless needed, a PIF file should be avoided since the RUN command automatically use Command.com to call the program specified in the PIF file. For example, if your PIF file specified Cmd.exe as the program to run, Visual FoxPro would actually have Command.com call Cmd.exe to execute the specified RUN command, which may not be the desired behavior. It is preferable to have the RUN command directly use the SHELL program specified by the operating system's COMSPEC environment variable.

Note:
With Windows XP, you can view and edit the COMSPEC environment variable by right-clicking on your computer desktop's My Computer icon and selecting the Properties dialog box (Advanced tab).

/N

/N means NOWAIT. Include the letter N to execute another Windows-based application and return control immediately to Visual FoxPro. For example, the following statement opens the Windows Character Map accessory:

Copy Code
! /N CHARMAP.EXE

The following example opens the Windows Display Properties dialog box:

Copy Code
! /N CONTROL COLOR

A Windows-based application executed with RUN /N or ! /N behaves the same way the application does when you open it through the Windows Explorer or by selecting Run from the Start menu. You can switch between the application and Visual FoxPro or FoxPro for Windows using the standard Windows operations.

You can include an optional numeric value immediately after /N to specify how the Windows-based application is opened. Do not include any spaces between /N and the numeric value. The following table lists the numeric value you can include and describes the state of the Windows-based application when opened.

Value | Application attributes
1 | Active and normal size.
2 | Active and minimized.
3 | Active and maximized.
4 | Inactive and normal size.
7 | Inactive and minimized.

Running External Programs in Visual FoxPro

By default, Foxrun.pif runs the specified external program in a window. In Visual FoxPro, the FoxPro Run Command window is closed after the external program or command is finished executing.

You can use the Windows PIF editor to customize Foxrun.pif. You can edit the PIF to specify if the Inactive FoxPro Run Command window is left open or is closed (the default in Visual FoxPro) with the Close Window on Exit check box. You can also open external programs in a full screen by selecting Full Screen; allocate memory for the program; and so on.

Windows 2000 Logo Certification

If you plan to submit your application for Windows Logo certification, you should not use the RUN command because it can potentially violate the System Group Policy requirements. Instead, you should use DECLARE DLL with ShellExecuteEx.API.

See Also

Other Resources

Commands
GETENV( ) Function
_SHELL System Variable


SAVE MACROS Command

Visual FoxPro 9.0 Language Reference
SAVE MACROS Command
See Also Example

Saves a set of keyboard macros to a keyboard macro file or to a memo field.

SAVE MACROS TO FileName | TO MEMO MemoFieldName

Parameters

TO FileName

Specifies the file to which the macros are saved. Keyboard macro file names can contain a maximum of eight characters and must begin with a letter or an underscore; they cannot begin with a number. The subsequent characters can be any combination of letters, numbers, and underscores. The file is assigned an .fky extension. If you assign an extension other than .fky, you must include that extension in RESTORE MACROS.
TO MEMO MemoFieldName

Specifies the memo field to which the macros are saved. The table containing the memo field must be open; however, it does not have to be in the selected work area. To save macros to a table in another work area, include the table's alias when specifying the memo field.

Remarks

When you quit Visual FoxPro, the macros you have created are lost unless you use SAVE MACROS to store them to a keyboard macro file or to a memo field.

Example

The following example saves the current set of macros to a file called Mymacros.fky.
Copy Code
SAVE MACROS TO mymacros

See Also

Other Resources

Commands
CLEAR Commands
PLAY MACRO Command
RESTORE MACROS Command


SAVE SCREEN Command

Visual FoxPro 9.0 Language Reference
SAVE SCREEN Command
See Also

Saves an image of the main Visual FoxPro window or an active user-defined window to the screen buffer, a variable, or an array element.

SAVE SCREEN [TO VarName]

Parameters

TO VarName

Specifies the variable or array element to which the screen or window image is saved.

Remarks

Use RESTORE SCREEN to redisplay images saved to the screen buffer, a variable, or an array element.

Variables or array elements containing an image of the main Visual FoxPro window or user-defined window have an S data type when you view the variables or array elements with DISPLAY or LIST MEMORY.

If issued without the TO VarName clause, SAVE SCREEN saves the main Visual FoxPro window or user-defined window to the screen buffer.

See Also

Other Resources

Commands
RESTORE FROM Command
RESTORE SCREEN Command
SAVE TO Command


SAVE TO Command

Visual FoxPro 9.0 Language Reference
SAVE TO Command
See Also Example

Stores current variables and arrays to a variable file or memo field.

Note:
Object type variables cannot be saved to a variable file or memo field. The SAVE TO command does not support saving arrays exceeding 65,000 elements.

SAVE TO FileName | MEMO MemoFieldName
   [ALL LIKE Skeleton | ALL EXCEPT Skeleton]

Parameters

FileName

Specifies the variable file that the variables and arrays are saved to. For a variable file, the default file name extension is .mem.
MEMO MemoFieldName

Specifies the memo field in which the variables and arrays are saved.
ALL LIKE Skeleton

Specifies that all variables and arrays, which match the specified Skeleton, be saved. The skeleton can include the question mark (?) and asterisk (*) wildcards.
ALL EXCEPT Skeleton

Specifies that all variables and arrays except those that match the specified Skeleton be saved. The skeleton can include the question mark (?) and asterisk (*) wildcards.

Remarks

To place variables and arrays back into memory from a variable file or memo field, use the RESTORE FROM command. For more information, see RESTORE FROM Command.

The variable file or memo field is marked with the current code page.

Example

In the following example, two variables are created. They are saved to a variable file and restored without clearing the existing variables.
Copy Code
gnVal1 = 50
gcVal2 = 'Hello'
SAVE TO temp
CLEAR MEMORY

gdVal3 = DATE( )
RESTORE FROM temp ADDITIVE
CLEAR
DISPLAY MEMORY LIKE g*

See Also

Other Resources

Commands
PRIVATE Command
PUBLIC Command
RELEASE Command


SAVE WINDOWS Command

Visual FoxPro 9.0 Language Reference
SAVE WINDOWS Command
See Also Example

Saves all or specified window definitions to a window file or memo field.

SAVE WINDOWS WindowNameList | ALL TO FileName | TO MEMO MemoFieldName

Parameters

WindowNameList

Specifies one or more windows to be saved. Separate the window names with commas.
ALL

Saves all window definitions to the window file or memo field.
TO FileName

Specifies the window file to which the window definitions are saved. If you don't specify an extension when naming the file, the default extension of .win is assigned. If you specify another extension when you save the window definitions to a file, you must include the extension when you restore the window definitions from the file.
TO MEMO MemoFieldName

Specifies the memo field to which the window definitions are saved. The table containing the memo field must be open; however, it does not have to be in the currently selected work area. To save window definitions to a table in another work area, include the table's alias when specifying the memo field.

Remarks

Use RESTORE WINDOW to restore window definitions from a window file or memo field. The status of each window is also saved. For example, if a window is hidden when it is saved to a file or memo field, it remains hidden when it is restored.

Example

In the following example, a window named wOutput1 is created, and the window definition is saved to the file Temp.win. All windows are cleared and wOutput1 is restored from the file and activated.
Copy Code
CLEAR
DEFINE WINDOW wOutput1 FROM 2,1 TO 13,75 TITLE 'Output' ;
   CLOSE FLOAT GROW ZOOM
ACTIVATE WINDOW wOutput1
@ 1,1 SAY 'This is the contents of the window'
SAVE WINDOWS wOutput1 TO temp
CLEAR WINDOWS
WAIT WINDOW 'The window has been saved - Press a key'

RESTORE WINDOW wOutput1 FROM temp
ACTIVATE WINDOW wOutput1
WAIT WINDOW 'The window has been restored - Press a key'

DEACTIVATE WINDOW wOutput1
RELEASE WINDOW wOutput1
DELETE FILE temp.win

See Also

Other Resources

Commands
DEFINE WINDOW Command
RESTORE SCREEN Command
RESTORE WINDOW Command
SAVE SCREEN Command


SCAN ... ENDSCAN Command

Visual FoxPro 9.0 Language Reference
SCAN ... ENDSCAN Command
See Also Example

Moves the record pointer through the currently selected table and executes a block of commands for each record that meets the specified conditions.

SCAN [NOOPTIMIZE] [Scope] [FOR lExpression1] [WHILE lExpression2]
   [Commands]
   [LOOP]
   [EXIT]
ENDSCAN

Parameters

NOOPTIMIZE

Prevents Rushmore Query Optimization of SCAN. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
Scope

Specifies a range of records to be scanned. Only the records within the range are scanned. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see the Scope Clauses online topic. The default scope for SCAN is all records (ALL).
FOR lExpression1

Executes commands only for records for which lExpression1 evaluates to true (.T.). Including the FOR clause lets you filter out records you don't want scanned. Rushmore optimizes a query created with SCAN ... FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies a condition whereby the commands are executed for as long as lExpression2 evaluates to true (.T.).
Commands

Specifies the Visual FoxPro commands to be executed.
LOOP

Returns control directly back to SCAN. LOOP can be placed anywhere between SCAN and ENDSCAN.
EXIT

Transfers program control from within the SCAN ... ENDSCAN loop to the first command following ENDSCAN. EXIT can be placed anywhere between SCAN and ENDSCAN.
ENDSCAN

Indicates the end of the SCAN procedure.

Remarks

SCAN automatically advances the record pointer to the next record that meets the specified conditions and executes the block of commands.

You can place comments after ENDSCAN on the same line. The comments are ignored during program compilation and execution.

SCAN ... ENDSCAN ensures that, upon reaching ENDSCAN, Visual FoxPro reselects the table that was current when the SCAN ... ENDSCAN loop began.

Example

The following example uses a SCAN ... ENDSCAN loop to display all the companies in Sweden.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table
CLEAR

SCAN FOR UPPER(country) = 'SWEDEN'
   ? contact, company, city
ENDSCAN

See Also

Other Resources

Commands
DO CASE ... ENDCASE Command
DO WHILE ... ENDDO Command
FOR EACH ... ENDFOR Command
FOR ... ENDFOR Command


SCATTER Command

Visual FoxPro 9.0 Language Reference
SCATTER Command
See Also

Copies data from the current record to a set of variables, to an array, or an object.

SCATTER and COPY TO ARRAY behave similarly. SCATTER copies only a single and current record into an array or a set of variables and automatically creates the array or variables if they do not already exist. COPY TO ARRAY copies multiple records into an array. For more information, see COPY TO ARRAY Command.

To copy variables or array elements to table records, use the GATHER Command.

SCATTER [FIELDS FieldNameList | FIELDS LIKE Skeleton
   | FIELDS EXCEPT Skeleton] [MEMO] [BLANK]
   TO ArrayName | TO ArrayName | MEMVAR
   | NAME ObjectName [ADDITIVE]

Parameters

FIELDS FieldNameList

Specifies the fields whose values are to be copied to the variables or the array. SCATTER disregards memo fields by default; however, you can include memo fields in the field list by following the field list with the MEMO keyword. However, SCATTER disregards general fields even when you include the MEMO keyword. Omitting FIELDS FieldNameList copies values from all fields.
FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton

Copies fields matching or excluding Skeleton to variables or an array. You can include the LIKE or EXCEPT clause or both. To copy values of fields matching Skeleton to variables or an array, use LIKE Skeleton. To copy values of all fields except those matching Skeleton to variables or an array, use EXCEPT Skeleton. Skeleton supports wildcard characters. For example, to copy the values from all fields that begin with the letters A and P to variables or an array, use the following lines of code:
Copy Code
SCATTER FIELDS LIKE A*,P* TO myArray
The LIKE clause can be combined with the EXCEPT clause:
Copy Code
SCATTER FIELDS LIKE A*,P* EXCEPT PARTNO* TO myArray
MEMO

Specifies that the field list include one or more memo fields.
Note:
Your computer must have sufficient memory to scatter large memo fields to variables or to an array. Visual FoxPro generates an error message if your computer lacks sufficient memory. SCATTER does not copy data from a memo field if it is too large to fit in memory nor does it copy from any additional memo fields in the field list. If SCATTER does not succeed for a memo field, the value of the variable or array element is set to False (.F.).

TO ArrayName

Specifies an array to which the record contents are copied. Starting with the first field, SCATTER copies the contents of each field into each element of the array in sequential order. If the array you specify contains more elements than the number of fields, the extra array elements remain unchanged. SCATTER automatically creates a new array if the array does not already exist, or if it contains fewer elements than the number of fields. The array elements have the same size and data types as the corresponding fields.
TO ArrayName

Creates an array with empty elements, which are the same size and type as the fields in the table.
MEMVAR

Scatters the data to a set of variables instead of an array. SCATTER creates one variable for each field in the table and fills each variable with data from the corresponding field in the current record, assigning to the variable the same name, size, and type as its field. SCATTER creates a variable for each field in the field list if a field list is included. To reference a variable that has the same name as a field in the current table, preface the variable name with the m. qualifier.
Caution:
Do not include the word TO with MEMVAR. Visual FoxPro creates an array named MEMVAR if you include the word TO.

Include the BLANK keyword to create a set of empty variables. Each variable is assigned the same name, data type, and size as its field. If a field list is included, a variable is created for each field in the field list.
NAME ObjectName [ADDITIVE]

Creates an object whose properties have the same names as fields in the table. To copy the value of each field in the table to each object property, do not include the BLANK keyword. To leave the properties empty, include the BLANK keyword. For a description of what the empty properties contain, based on the corresponding field type, see EMPTY( ) Function. Properties are not created for general fields that exist in the table. To update the property values of an existing and valid Visual FoxPro object specified by ObjectName, but not COM objects, with values from the current record, include the ADDITIVE keyword. If the object does not exist, Visual FoxPro creates the object automatically. You cannot use the ADDITIVE keyword without the NAME clause. Doing so generates an error. Using BLANK with ADDITIVE omits the values for existing properties that have matching field names.

Remarks

If properties corresponding to field names do not exist for the object, SCATTER...NAME ADDITIVE automatically creates them. However, SCATTER might not create all the necessary properties because some might be marked as Hidden or Protected. If Visual FoxPro cannot create or set a property, it generates an error. For example, you can have a field name that matches a native Visual FoxPro object property name as long as the field and property data types are the same. However, Visual FoxPro generates an error if the field name matches a method, event, or object name.

You can avoid problems by using an object created by SCATTER...NAME and not one derived from a Visual FoxPro class. Unlike when SCATTER is used with only NAME, Visual FoxPro does not overwrite the existing object to create a new object.

SCATTER...NAME ADDITIVE does not generate an error when a read-only property cannot be set for a field in the table. However, the value of the property remains unchanged.

To reference a property in an object that has the same name as an open table, preface the property name with the m. qualifier. The following example displays the value of the Company field in the Customer table followed by the value of the Company property for the Customer object:

Copy Code
USE Customer
SCATTER NAME Customer
? Customer.Company  && Returns the table value
? m.Customer.Company  && Returns the object property value

Examples

Example 1

This example uses SCATTER to create a set of variables based on the fields in the test table. Each field is then assigned a value and a new blank record is added to the table. The data is copied to the table using the GATHER command.

Copy Code
CREATE TABLE Test FREE ;
   (Object C(10), Color C(16), SqFt n(6,2))

SCATTER MEMVAR BLANK
m.Object="Box"
m.Color="Red"
m.SqFt=12.5
APPEND BLANK
GATHER MEMVAR
BROWSE

Example 2

This example uses SCATTER along with the NAME clause to create an object with properties based on the fields in the table. The object's properties are then assigned values and a new blank record is added to the table. The data is copied to the new record using GATHER with the NAME clause.

Copy Code
CREATE TABLE Test FREE ;
   (Object C(10), Color C(16), SqFt n(6,2))

SCATTER NAME oTest BLANK
oTest.Object="Box"
oTest.Color="Red"
oTest.SqFt=12.5
APPEND BLANK
GATHER NAME oTest
RELEASE oTest
BROWSE

Example 3

Suppose you have two or more tables or cursors and wish to create an object that combines the data from those cursors. The following example selects the Customer table and uses SCATTER...NAME to create the oCustomer object and its properties from fields in the Customer table. SCATTER...NAME...ADDITIVE then updates the values from the ReportDate and Rating fields in the CreditHistory table and the CookieText and SessionId fields in the MySessionTable table in the oCustomer object or creates those properties if they do not exist.

Copy Code
SELECT Customer
SCATTER NAME oCustomer
SELECT CreditHistory
SCATTER FIELDS ReportDate, Rating NAME oCustomer ADDITIVE
SELECT MySessionTable
SCATTER FIELDS CookieText, SessionId NAME oCustomer ADDITIVE

See Also

Other Resources

Commands
ALINES( ) Function
APPEND FROM ARRAY Command
DECLARE Command
DIMENSION Command
GATHER Command


SCROLL Command

Visual FoxPro 9.0 Language Reference
SCROLL Command
See Also Example

Scrolls an area of the main Visual FoxPro window or a user-defined window up, down, left, or right.

SCROLL nRow1, nColumn1, nRow2, nColumn2, nRowsScrolled
    [, nColumnsScrolled]

Parameters

nRow1, nColumn1, nRow2, nColumn2

Specifies the rectangular region where scrolling occurs in the main Visual FoxPro window or in the active user-defined window. nRow1, nColumn1 specifies the upper-left corner of the region, and nRow2, nColumn2 specifies the lower-right corner.
nRowsScrolled

Specifies the number of rows up or down to scroll inside the rectangular region. If the numeric expression nRowsScrolled is positive, Visual FoxPro scrolls up the number of rows. If nRowsScrolled is negative, Visual FoxPro scrolls down the number of rows. If nRowsScrolled is 0 and you omit nColumnsScrolled, Visual FoxPro clears the rectangular region.
nColumnsScrolled

Specifies the number of columns left or right to scroll inside the rectangular region. If the numeric expression nColumnsScrolled is positive, Visual FoxPro scrolls to the right the number of columns. If nColumnsScrolled is negative, Visual FoxPro scrolls to the left the number of columns. If you include both nRowsScrolled and nColumnsScrolled, Visual FoxPro scrolls the area diagonally.

Example

The following command scrolls a small rectangular region:
Copy Code
CLEAR
@ 4, 1 FILL TO 10, 8 COLOR GR+/B
WAIT WINDOW 'Press key to scroll left top corner'
SCROLL 0, 0, 5, 5, -2, 1

See Also

Other Resources

Commands
MOVE WINDOW Command
ScrollBars Property
@ ... SCROLL Command


SEEK Command

Visual FoxPro 9.0 Language Reference
SEEK Command
See Also Example

Searches a table for the first occurrence of a record whose index key matches a general expression, then moves the record pointer to the matching record.

Note:
Visual FoxPro does not support seek operations for binary indexes.

SEEK eExpression   [ORDER nIndexNumber | IDXIndexFileName
    | [TAG] TagName [OF CDXFileName]    [ASCENDING | DESCENDING]]
   [IN nWorkArea | cTableAlias]

Parameters

eExpression

Specifies the index key for which SEEK searches. eExpression can be null.
ORDER nIndexNumber

Specifies the number of the index file or tag that is used to search for the index key. nIndexNumber refers to the index files as they are listed in USE or SET INDEX. Open .idx files are numbered first in the order in which they appear in USE or SET INDEX. Tags in the structural .cdx file (if one exists) are then numbered in the order in which they were created. Finally, tags in any open independent .cdx files are numbered in the order in which they were created. See SET ORDER Command for more information about index numbering.
ORDER IDXIndexFileName

Specifies an .idx file that is used to search for the index key.
ORDER [TAG] TagName [OF CDXFileName]

Specifies a tag of a .cdx file that is used to search for the index key. The tag name can be from a structural .cdx file or any open independent .cdx file. If identical tag names exist in open independent .cdx files, use OF CDXFileName to specify the .cdx file containing the tag.
Note:
The .idx file takes precedence if duplicate .idx file and tag names exist.

ASCENDING

Specifies that the table is searched in ascending order.
DESCENDING

Specifies that the table is searched in descending order.
IN nWorkArea

Specifies the work area number of the table that is searched.
IN cTableAlias

Specifies the alias of the table that is searched. If you omit IN nWorkArea and IN cTableAlias, the table in the currently selected work area is searched.

Remarks

You can use SEEK only with indexed tables, and you can search only on the index key. The match must be exact unless SET EXACT is set to OFF.

If SEEK finds a record with a matching index key, RECNO( ) returns the record number of the matching record, FOUND( ) returns true (.T.), and EOF( ) returns false (.F.).

If a matching key isn't found, RECNO( ) returns the number of records in the table plus 1, FOUND( ) returns false (.F.), and EOF( ) returns true (.T.).

If SET NEAR is on, the record pointer is positioned immediately after the record with the closest index key. If SET NEAR is off, the record pointer is positioned at the end of the file. In either case, RECNO() returns the record number of the closest record.

Example

In the following example, the Customer table is opened and indexed on the Company field. SEEK is used to find the index key expression that matches the value contained in the variable gcSeekVal.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer ORDER company  && Opens Customer table

SET EXACT OFF
STORE 'B' TO gcSeekVal
SEEK gcSeekVal

IF FOUND( )
   DISPLAY FIELDS company, contact
ENDIF

See Also

Other Resources

Commands
EOF( ) Function
FOUND( ) Function
INDEX Command
INDEXSEEK( ) Function
LOCATE Command
RECNO( ) Function
SEEK( ) Function
SET EXACT Command
SET NEAR Command


SELECT - SQL Command

Visual FoxPro 9.0 Language Reference
SELECT - SQL Command
See Also

Retrieves data from one or more tables. When you use SQL SELECT to create a query, Visual FoxPro parses the query and retrieves the specified data from the tables. You can create a SQL SELECT query from the Command window, in a Visual FoxPro program, or using the Query Designer. Please review the Considerations for SQL SELECT Statements help topic for more information on using SQL SELECT.

The full syntax for the SQL SELECT command appears as follows:

SELECT [ALL | DISTINCT] [TOP nExpr [PERCENT]] Select_List_Item [, ...]
   FROM [FORCE] Table_List_Item [, ...]
      [[JoinType] JOIN DatabaseName!]Table [[AS] Local_Alias]
      [ON JoinCondition [AND | OR [JoinCondition | FilterCondition] ...]
   [WITH (BUFFERING = lExpr)]
   [WHERE JoinCondition | FilterCondition [AND | OR JoinCondition | FilterCondition] ...]
   [GROUP BY Column_List_Item [, ...]] [HAVING FilterCondition [AND | OR ...]]
   [UNION [ALL] SELECTCommand]
   [ORDER BY Order_Item [ASC | DESC] [, ...]]
   [INTO StorageDestination | TO DisplayDestination]
   [PREFERENCE PreferenceName] [NOCONSOLE] [PLAIN] [NOWAIT]

Remarks

The following code shows a summary of the main clauses:

Copy Code
SELECT Select_List
   FROM Table_List
   [WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [UNION Clause]
   [HAVING Conditions]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

The following sections describe the detailed syntax and parameters for each clause of the SQL SELECT command:

  • SELECT Clause

  • FROM Clause

  • SELECT - SQL Command - WITH Clause

  • WHERE Clause

  • GROUP BY Clause

  • HAVING Clause

  • UNION Clause

  • ORDER BY Clause

  • INTO or TO Clause

  • Additional Display Options

When you issue SET TALK ON and SET NOTIFY ON before executing SELECT, Visual FoxPro displays the length of time the query took to execute and the number of records in the results. _TALLY contains the number of records in the query results. For more information, see SET TALK Command, SET NOTIFY Command, and _TALLY System Variable.

Note:
The length of time might not display if the query execution time is very short.

SELECT does not respect the current filter condition specified with SET FILTER. For more information, see SET FILTER Command.

Examples

The following code examples show many ways of retrieving data with the SQL SELECT command and use the sample TestData.dbc database included in Visual FoxPro.

Example 1

The following example displays data from field in a table using the FROM clause. The example displays all the company names in the Company field from the Customer table:

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT customer.company ;
   FROM customer

Example 2

The following example displays all records from a query in a specified column using the AS Column_Name clause. The example displays all names in the City field from the Customer table in uppercase using the UPPER( ) function and in column called CityList.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT UPPER(city) AS CityList FROM customer

Example 3

The following example displays unique data from a query using the DISTINCT option with a join condition in the WHERE clause. The example displays the Company, Order_Date, and Shipped_On fields for only those records with unique data in the Customer and Orders tables. The SELECT statement specifies local aliases for the tables to distinguish the same field name, Cust_ID, in both tables.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT DISTINCT TAlias1.company, TAlias2.order_date, ;
   TAlias2.shipped_on ;
   FROM customer TAlias1, orders TAlias2 ;
   WHERE TAlias1.cust_id = TAlias2.cust_id

Example 4

The following example displays three fields from two tables, but only those records meeting join and filter conditions in the WHERE clause. The example joins the Customer and Orders table on the Cust_ID field and displays the Company, Order_Date, and Shipped_On fields for only those records that have an order date earlier than 02/16/1994. The SELECT statement specifies local aliases for the tables to distinguish the same field name, Cust_ID, in both tables.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT TAlias1.company, TAlias2.order_date, TAlias2.shipped_on ;
   FROM customer TAlias1, orders TAlias2 ;
   WHERE TAlias1.cust_id = TAlias2.cust_id ;
   AND TAlias2.order_date < {^1994-02-16}

Example 5

The following example organizes results of a query using the ORDER BY Order_Item clause. The example displays the Country, PostalCode, and Company fields for those records in the Customer table in ascending order, by default.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT country, postalcode, company ;
   FROM customer ;
   ORDER BY country, postalcode, company

Example 6

The following example stores the contents of a query into a table using INTO TABLE TableName clause. The example stores the contents of the Company, Order_Date, and Shipped_On fields from the Customer and Order tables, which are joined on the Cust_ID field, in a third table called CustShip. The example then opens a Browse window for the new table. The SELECT statement specifies local aliases for the tables to distinguish the same field name, Cust_ID, in both tables.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT TAlias1.company, TAlias2.order_date, TAlias2.shipped_on ;
   FROM customer TAlias1, orders TAlias2 ;
   WHERE TAlias1.cust_id = TAlias2.cust_id ;
   INTO TABLE custship.dbf
BROWSE

See Also

Reference

SET ENGINEBEHAVIOR Command
SYS(3054) - Rushmore Query Optimization Level
SYS(3099) - SQL Data Engine Compatibility Mode
Filter Conditions for Queries and Views
Considerations for SQL SELECT Statements

Concepts

Join Conditions for Tables, Queries, and Views

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
CREATE TABLE - SQL Command
MODIFY QUERY Command


Considerations for SQL SELECT Statements

Visual FoxPro 9.0
Considerations for SQL SELECT Statements
See Also

When creating queries and views with SQL SELECT statements, be aware of the following considerations, conventions, and restrictions.

  • User-Defined Functions in SQL SELECT Statements

  • Aggregate Functions

  • Rules Applied to Column Names

  • UNION Operations

User-Defined Functions in SQL SELECT Statements

You can specify expressions containing user-defined functions for Select_Item in SQL SELECT statements. However, note the following recommendations and restrictions when using user-defined functions in SQL SELECT statements:

  • Use API and user-defined functions written in C or assembly language instead of performing high-volume manipulations with user-defined functions. The speed at which user-defined functions are executed can limit the speed of operations performed with SQL SELECT.

  • Assume nothing about the Visual FoxPro input/output (I/O) or table environment when using user-defined functions in SQL SELECT. In general, you do not know which work area is selected, the name of the current table, or even the names of the fields being processed. The value of these variables depends on the precise location in the optimization process where the user-defined function is called.

  • Do not change the Visual FoxPro I/O or table environment in user-defined functions called in SQL SELECT. In general, the results can be unpredictable.

  • Use the argument list that is passed to the function when it is called as the only reliable way to pass values to user-defined functions in SQL SELECT.

  • Understand that "forbidden" manipulations might provide results in one version of Visual FoxPro but might not work in later versions.

Outside of these restrictions, user-defined functions are acceptable in SQL SELECT statements. However, remember that using SQL SELECT in general might slow performance.

For more information about user-defined functions, see User-Defined Procedures and Functions.

Aggregate Functions

You can use aggregate functions with a Select_Item that is a field or an expression involving a field or within a filter condition in the HAVING clause. However, you cannot nest aggregate functions.

The following table lists aggregate functions you can use in SQL SELECT statements.

Aggregate function | Description
AVG( ) | Averages a column of numeric data.
COUNT( ) or CNT( ) | Counts the number of select items in a column. COUNT(*) counts the number of rows in the query output.
MIN( ) | Determines the smallest value of Select_Item in a column.
MAX( ) | Determines the largest value of Select_Item in a column.
SUM( ) | Totals a column of numeric data.

The following example creates a query that displays output column names as described:

Copy Code
CLEAR ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT AVG(TAlias1.order_amt), MIN(TAlias1.order_amt) ;
   FROM Orders AS TAlias1

For more information about the aggregate functions you can use with SELECT statements, see MIN( ) Function, MAX( ) Function, and the CALCULATE Command, which contains information about the AVG( ), COUNT( ) or CNT( ), and SUM( ) functions.

Rules Applied to Column Names

The following rules apply when you specify a column with the AS clause to display results in a separate column:

  • If Select_Item is a field with a unique name, the output column name is the field's name.

  • If more than one Select_Item has the same name, an underscore (_) and a letter are appended to the end of the output column name.

    For example, if a SQL SELECT statement specifies to display the Cust_ID fields for two tables, Customer and Orders, the column names displayed are FieldName_a and FieldName_b, or in this example, Cust_ID_a and Cust_Id_b. The following example creates a query that displays column names as described:

    Copy Code
    CLEAR ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT TAlias1.cust_id, TAlias2.cust_id ;
   FROM Customer AS TAlias1, Orders AS TAlias2 ;
   WHERE TAlias1.cust_id = TAlias2.cust_id
    In a free table, if more than one SQL SELECT item has the same name, and the name has 10 or more characters, the name is truncated to add a number. For example, an output column name such as Department would appear as Department and Departmen2.

  • If Select_Item is an expression, the output column name appears as Exp_1. Additional output column names appear as Exp_2, Exp_3, and so on. The following example creates a query that displays output column names as described:

    Copy Code
    CLEAR ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT TAlias1.postalcode+"-1234", TAlias2.postalcode+"-5678" ;
   FROM Customer AS TAlias1, Orders AS TAlias2 ;
   WHERE TAlias1.cust_id = TAlias2.cust_id
  • If an aggregate function, such as COUNT( ), is used with Select_Item, the output column is named Cnt_FieldName. If more than one Select_Item is used with aggregate functions, the output columns are named AggregateFunction_FieldName with the aggregate function names abbreviated as needed. The following example creates a query that displays output column names as described:

    Copy Code
    CLEAR ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT COUNT(order_id), SUM(order_net)FROM Orders
    For more information about aggregate functions, see Aggregate Functions.

UNION Operations

When performing UNION operations between SQL SELECT statements using the UNION clause, be aware of the following considerations and restrictions:

  • You cannot use UNION to combine subqueries.

  • The SELECT statements must have the same number of columns in their query output.

  • Only the final SELECT statement can have an ORDER BY clause, which must refer to output columns by number. If an ORDER BY clause is included, it affects the entire result.

  • When two columns of different data types are involved in a UNION operation, the data type with the lower precedence is converted to the data type with the higher precedence.

Data Type Conversion and Precedence in UNION Operations

Prior to Visual FoxPro 8.0, you needed to perform explicit data type conversion when performing UNION operations in SQL SELECT statements between two fields of different types. However, Visual FoxPro supports implicit data type conversion for the data types that support it.

Explicit data type conversion requires you to use Visual FoxPro conversion functions, such as CTOD( ), while implicit conversions do not require you to use such conversion functions.

When Visual FoxPro combines two columns of different data types in a UNION operation, the data type with the lower precedence is converted to the data type with the higher precedence. For field properties, NULL takes higher precedence over NOT NULL.

The following table shows all the explicit and implicit data type conversions permitted for Visual FoxPro table data types.

Data type | Implicit conversion | Explicit conversion
Character | Character (Binary) | CTOD( ), CTOT( ), VAL( ), CTOBIN( )
Character (Binary) |  |
Currency |  | MTON( )
Date | DateTime | DTOC( ), DTOS( ), DTOT( )
DateTime |  | TTOC( ), TTOD( )
Double |  | STR( ), VAL( )
Float | Numeric | NTOM( ), STR( ), INT( )
Integer | Numeric, Float, Double, Currency | BINTOC( )
Logical |  |
Numeric | Float | NTOM( ), STR( ), INT( )

The following table illustrates implicit conversion results from a UNION operation between two fields.

Data type 1 | Data type 2 | Data type expected
Character (N) | Character (X) | Character (MAX(N,X))
Character (N) | Character Binary (X) | Character Binary (MAX(N,X))
Character (N) | Memo | Memo
Character Binary (N) | Character Binary (X) | Character Binary (MAX(N,X))
Character Binary (N) | Memo | Memo
Currency | Currency | Currency
Date | Date | Date
Date | DateTime | DateTime
DateTime | DateTime | DateTime
Double (N) | Float (X,Y) | Float (MAX(MAX(8,Y),2))
Double (N) | Integer | Double (N)
Double (N) | Numeric (X,Y) | Double (MAX(MAX(8,Y),2))
Double (X) | Double (Y) | Double (MAX(X,Y))
Float (N,M) | Double (X) | Float (20, MAX(M,X))
Float (N,M) | Float (X,Y) | Float (MAX(N,M), MAX(X,Y))
Float (N,M) | Numeric (X,Y) | Float (MAX (N,X), MAX(M,Y))
Integer | Currency | Currency
Integer | Double (X) | Double (X)
Integer | Float (X,Y) | Float (MAX(11,X), Y)
Integer | Integer | Integer
Integer | Numeric (X,Y) | Numeric (MAX(11,X), Y)
Logical | Logical | Logical
Numeric (N,M) | Double (X) | Numeric (20, MAX(M,X))
Numeric (N,M) | Float (X,Y) | Float (MAX(N,X), MAX(M,Y))
Numeric (N,M) | Numeric (X,Y) | Numeric (MAX(N,X), MAX(M,Y))
Varchar (X) | Character (Y) | Varchar (MAX(X,Y))
Varchar Binary (X) | Character Binary (Y) | Varchar Binary (MAX(X,Y))

For more information about data types and conversion functions, see Data and Field Types and Data Conversion Functions.

See Also

Other Resources

General Reference
SELECT - SQL Command
Working with Queries
Working with Views


Filter Conditions for Queries and Views

Visual FoxPro 9.0
Filter Conditions for Queries and Views
See Also

In SQL SELECT statements, filter conditions specify filter criteria that records retrieved from a SQL SELECT statement must meet to be included in query or view results. When creating queries and views with SQL SELECT statements to retrieve data, you can use filter conditions in the ON and WHERE clauses to extract only those records that meet the filter conditions. For example, you can use filter conditions to retrieve only those records where a field's values are less than a filter value, such as a date.

You can specify filter conditions similar to specifying join conditions but using filter values from a single table and customize filter conditions using comparison operators to control how those field values compare to those filter values. Join conditions compare a field value in one table to a field value in another other table instead of a filter value in the same table.

For the syntax of filter conditions in SQL SELECT statements, see SELECT - SQL Command.

This topic contains the following sections:

  • Parts of Filter Conditions

  • Filter Comparison Operators

  • Filter Options and Values

  • Wildcard Characters in Filter Conditions

Parts of Filter Conditions

The following list contains parts of filter conditions that you can specify:

  • Table fields to compare

  • Filter comparison operators, such as > or !=

  • Filter options, such as ANY or LIKE, and values, such as field values, expressions, value sets, and subqueries

Filter Comparison Operators

In addition to using the syntax of join conditions for one table to specify a filter, you can use comparison operators, such as =, <=, and >, to compare a field value to a filter value. The comparison operators you can use are the same as those available for comparison operators in join conditions.

The following table lists the comparison operators available for filter conditions.

Operator | Description
= | Equal
== | Exactly equal
LIKE | SQL LIKE
<>, !=, # | Not equal
> | Greater than
>= | Greater than or equal to
< | Less than
<= | Less than or equal to

The following example illustrates the use of the less than (<) operator in the filter condition, TAlias2.order_date < {^1994-02-16}, using the syntax, FieldName Comparison Expression, and displays only those company names in the Company field from the Customer table that have matching orders in the Orders table with order dates in the Order_Date field earlier than 02/16/1994.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT TAlias1.company, TAlias2.order_date ;
   FROM customer TAlias1, orders TAlias2 ;
   WHERE TAlias1.cust_id = TAlias2.cust_id ;
      AND TAlias2.order_date < {^1994-02-16}

Filter Options and Values

You can use filter options in addition to comparison operators so you can customize your filter condition to choose subsets of records. When using these options, the syntax of the filter condition can be one of the following:

  • FieldName Comparison Expression | ALL (Subquery) | ANY (Subquery) | SOME (Subquery)

    -OR-

  • FieldName [NOT] LIKE cExpression | IS [NOT] NULL | [NOT] BETWEEN Start_Range AND End_Range | [NOT] IN Value_Set | [NOT] IN (Subquery)

    -OR-

  • [NOT] EXISTS (Subquery)

The following table describes options available for filter conditions.

Option Description

ALL (Subquery)

FieldName values must meet comparison for all values generated by the subquery for inclusion in the query results.

ANY (Subquery) | SOME (Subquery)

FieldName values must meet comparison for at least one of the values generated by the subquery for inclusion in the query results.

LIKE "cExpression"

FieldName values must match the character expression cExpression, which can contain SQL wildcard characters, such as percent (%) and underscore (_), for inclusion in the query results.

The % character represents any sequence of unknown characters in the string. The _ character represents a single unknown character in the string. If you want to specify a wildcard character as a literal, use the ESCAPE clause. For more information, see Wildcard Characters in Filter Conditions below.

The LIKE "cExpression%" filter condition is fully optimized.

IS NULL

FieldName value must be null for inclusion in the query results.

BETWEEN Start_Range AND End_Range

FieldName values must be within a specified range of values for inclusion in the query results.

IN (Value_Set)

FieldName must contain one of the values or expressions specified in Value_Set for inclusion in the query results. When listing items in the value set, separate each item with commas.

Note:
The number of values or expressions you can specify for Value_Set is affected by the setting of SYS(3055) – FOR and WHERE Clause Complexity.

Tip:
Visual FoxPro stops evaluating values and expressions in the Value_Set list when the first match is found. Therefore, if the IN clause is not Rushmore optimized, you can improve performance by placing values most likely to match in the beginning of the Value_Set list.

IN (Subquery)

FieldName must contain one of the values returned by Subquery for inclusion in the query results.

EXISTS (Subquery)

Query contains results only when at least one row is returned from the subquery. The EXISTS clause evaluates to True (.T.) or False (.F.).

Note:
The EXISTS (Subquery) clause evaluates to True (.T.) unless the subquery evaluates to the empty set.

The following small code examples illustrate various ways of specifying filter options and values.

  • The following filter condition uses the syntax FieldName Comparison ALL (Subquery) and includes only those values that are less than all values generated by the subquery. Specifically, this condition specifies that the query include only those company names that come alphabetically before those whose country field contains "UK" in the Customer table.

    Copy Code
    company < ALL (SELECT company FROM customer WHERE country = "UK")
  • The following filter condition uses the syntax FieldName LIKE cExpression and includes only those values that match cExpression. Specifically, this condition specifies that the query include only those records where the Country field in the Customer table contains values matching "UK".

    Copy Code
    customer.country LIKE "UK"
  • The following filter condition uses the syntax FieldName BETWEEN Start_Range AND End_Range and includes only those values within the specified range of values. Specifically, this condition specifies that the query include only those postal codes in the Customer table that fall between "90000" and "99999."

    Copy Code
    customer.postalcode BETWEEN "90000" AND "99999"
  • The following filter condition uses the syntax FieldName IN (Value_Set) and includes only those values that are one of those specified in Value_Set. Specifically, this condition specifies that the query include only those postal codes in the Customer table that are "98052", "98072", and "98034."

    Copy Code
    customer.postalcode IN ("98052","98072","98034")
  • The following filter condition uses the syntax FieldName IN (Subquery) and includes only those values that are among those returned by the subquery. Specifically, this condition specifies that the query include only those customer ID numbers in the Customer table that are in the set of customer ID numbers in the Orders table that match orders whose City field contains "Seattle".

    Copy Code
    customer.cust_id IN ;
   (SELECT orders.cust_id FROM orders WHERE orders.city="Seattle")
  • The following filter condition uses the syntax, EXISTS (Subquery), and includes results only when at least one row is returned from the subquery. Specifically, this condition specifies that the query contain results only when at least one record is returned from the subquery. The subquery specifies to select all records from the Orders table in which the postal code in the Customer table matches the postal code in the Orders table.

    Copy Code
    EXISTS (SELECT * FROM orders ;
   WHERE customer.postalcode = orders.postalcode)

The following complete example uses the EXISTS (Subquery) clause to create a query that contains results only when at least one record is returned from the subquery. The subquery specifies to retrieve company names from the Customer table only if at least one record in which the postal code in the Customer table matches the postal code in the Orders table.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT company FROM customer TAlias1 ;
   WHERE EXISTS (SELECT * FROM orders TAlias2 ;
     WHERE TAlias1.postalcode = TAlias2.postalcode)

Wildcard Characters in Filter Conditions

You can perform searches using wildcard characters in filter condition expressions in the WHERE clause of a SQL SELECT statement by using the percent (%) and underscore (_) characters. The % character represents any sequence of unknown characters in the string. The _ character represents a single unknown character in the string.

However, if you want to specify a filter condition expression that retrieves data containing wildcard characters, use the ESCAPE clause to treat the wildcard characters as literal characters. In the ESCAPE clause, you can specify a character that, when placed immediately before the wildcard character, indicates that the wildcard character be treated as a literal character.

The following examples illustrate how to perform searches using wildcard characters.

  • The following example uses the LIKE cExpression option to display all records meeting a filter condition using the WHERE FilterCondition clause. The example creates a query that displays all records from the Customer table with a company name that begins with an uppercase letter C and is of unknown length by specifying the percent (%) wildcard character.

    Copy Code
    CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT * FROM customer WHERE company LIKE "C%"
  • The following example uses the LIKE cExpression option to display all records meeting a filter condition using the WHERE FilterCondition clause. The example creates a query that display all records from the Customer table with a country name that begins with an uppercase letter U and is followed by one unknown character by specifying the underscore (_) wildcard character.

    Copy Code
    CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT * FROM customer WHERE country LIKE "U_"

The following examples show how to create queries on data containing wildcard characters, such as percent (%) and underscore (_).

  • The following example uses the ESCAPE clause to specify that the backslash (\) is the escape character. The backslash is inserted immediately preceding the percent character to indicate that it should be treated as a literal.

    Note:
    The sample tables included with Visual FoxPro do not contain the percent character; therefore, this example returns no results.

    Copy Code
    CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT * FROM customer WHERE company LIKE "10\%" ESCAPE "\"
  • The following example uses the ESCAPE clause to specify that the dash (-) character is the escape character. However, in the example, the dash character is specified as an escape character and a literal character. The example returns all records where the company name begins with a dash character.

    Note:
    The sample tables included with Visual FoxPro do not contain the dash character in the company name; therefore, this example returns no results.

    Copy Code
    CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT * FROM customer WHERE company LIKE "--" ESCAPE "-"

See Also

Other Resources

General Reference
How to: Optimize Filters and Joins
Working with Queries
Working with Views
Query and View Designers
CREATE SQL VIEW Command
SELECT - SQL Command


Join Conditions for Tables, Queries, and Views

Visual FoxPro 9.0
Join Conditions for Tables, Queries, and Views
See Also

Visual FoxPro supports SQL-92 Join syntax, allowing you to create queries that link rows in two or more tables by comparing the values in specified fields. When retrieving data from tables to create queries and views, you can use join operations and join conditions to control how records are compared and which ones are returned and specify relationships between tables, usually based on the primary and foreign keys. Specifying joins on fields other than the primary and foreign keys can be useful in specific instances; however, most queries do not use joins on non-key fields.

This topic contains the following sections:

  • Parts of Join Operations

  • Join Types

  • Join Sequence

  • Join Conditions

  • Join Considerations

You can specify join operations and join conditions for queries and views in the Query and View designers and by using the Visual FoxPro language. For more information, see Join Tab, Query and View Designers and SELECT - SQL Command.

Parts of Join Operations

The following list contains parts of join operations that you can set between tables in queries and views:

  • Table fields in the join.

  • Join type between tables or between table fields in a query or view.

  • Join sequence.

  • Join conditions between fields using operators such as Between, Equal (=), Greater Than (>), and Less Than (<).

Join Types

Because SQL is based on mathematical set theory, each table can be represented as a circle in a Venn diagram. The ON clause in the SQL SELECT statement that specifies join conditions determines the point of overlap for those circles and represents the set of rows that match. For example, in an inner join, the overlap occurs within the interior or "inner" portion of the two circles. An outer join includes not only those matched rows found in the inner cross section of the tables, but also the rows in the outer part of the circle to the left or right of the intersection.

You can expand or narrow the results of your search by specifying the type of join you want between tables. The following table describes join types you can specify.

Join type | Description
Inner | Retrieve only those records from tables on both sides of the join that match the join condition between fields involved in the join. Inner joins are the most common type of join.
Left (outer) | Retrieve all records from the table on the left side of the join and only those records that match the join condition from the table on the right side of the join.
Right (outer) | Retrieve only those records from the table on the left side of the join condition that match the join condition but all records from the right side of the join condition.
Full | Retrieve all records from tables on both sides of the join condition regardless of whether records match the join condition.

Exactly Matching Records in Results

If you want to retrieve only those records that match the join condition from the tables on both sides of the operation, use an inner join.

For example, suppose you want to create a query containing only those companies that have orders and display only those order numbers for those companies. The following code example creates a query that retrieves only those company names from the Customer table that have orders in the Orders table and the order numbers for only those companies. The example uses an inner join to display only those records from both tables that match the join condition based on the Cust_ID field.

Note:
The SELECT statement uses local table aliases to distinguish the same field name, Cust_ID, in both tables and an ORDER BY clause to organize the results by company name in ascending order.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT TAlias1.company, TAlias2.order_ID ;
   FROM customer AS TAlias1 ;
   INNER JOIN orders AS TAlias2 ;
      ON TAlias1.cust_id = TAlias2.cust_id ;
   ORDER BY TAlias1.company ASC

Multiple Join Operations

You can specify more than one join operation to include data from other tables.

For example, suppose you want to create a query containing only those companies that have orders, only those order numbers for those companies, and the employees who took the orders. The following code example creates a query that retrieves only those company names from the Customer table that have orders in the Orders table, the order numbers for only those companies, and those names belonging to employees who took those orders. The example uses two inner join clauses to display only those records from the three tables that match on the Cust_ID and Emp_ID fields.

Note:
The SELECT statement uses local table aliases to distinguish the common field names, Cust_ID and Emp_ID, in the tables.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT TAlias1.company, TAlias2.order_ID, ;
   TAlias3.first_name, TAlias3.last_name ;
   FROM customer AS TAlias1 ;
   INNER JOIN orders AS TAlias2 ;
      ON TAlias1.cust_id = TAlias2.cust_id ;
   INNER JOIN employee AS TAlias3 ;
      ON TAlias2.emp_id = TAlias3.emp_id ;
   ORDER BY TAlias1.company ASC

Nonmatching Records in Results

If you want to include any rows that do not match the join conditions in your results, you can use a left outer, right outer, or full join between tables. When you use an outer join, the empty fields of the nonmatching rows return null values.

For example, suppose you want to create a query containing a list of all customers, regardless of whether they have placed an order, and order numbers for those customers who have placed orders. The following code example uses a left outer join to display all the records from a field in one table and those records in another table that match on the join condition.

Note:
The syntax in the example uses a LEFT JOIN clause because the OUTER keyword is optional.

This example creates a query against the Visual FoxPro sample database, TestData.dbc, that retrieves all company names from the Customer table and only those records in the Orders table that have customer ID numbers that match in both tables. However, not all the records that match have order numbers for all the companies in the Customer table.

Note:
The SELECT statement uses local table aliases to distinguish the same field name, Cust_ID, in both tables.

Copy Code
CLOSE ALL
CLOSE DATABASES

OPEN DATABASE (HOME(2) + 'Data\TestData')

SELECT TAlias1.company, TAlias2.order_id ;

   FROM customer TAlias1 ;

   LEFT JOIN orders TAlias2 ;

      ON TAlias1.cust_id = TAlias2.cust_id

All but one of the company names in the query have order numbers in the Order_ID column of the query. Wenna Wines contains contains a null value in the Order_ID column.

For more information about join types you can set between tables in the Query Designer and View Designer, see Join Condition Dialog Box.

Join Sequence

When you need data from multiple tables, the results you want and the join type you select affect the position and join sequence in which you place the tables in your query. You can specify the order in which tables are joined in the Query and View designers or in the JOIN clause of the SQL SELECT statement.

For example, suppose you want all the records from a field in one table and only those records in another table that match on the join condition. You could use the LEFT JOIN operation and place the first table on the left side and the second table on the right side of the JOIN clause. However, if you selected a RIGHT JOIN operation, you would need to reverse the order of these two tables to obtain the same results.

The following code example creates a query that displays three sets of results, but all of them retrieve all values from the field in the first table and only those values from the field in the second table that meet the join condition. The join condition is specified by the ON clause.

Note:
The SELECT statement uses local table aliases to distinguish the same field name, Cust_ID, in both tables.

Copy Code
CLOSE ALL
CLOSE DATABASES

OPEN DATABASE (HOME(2) + 'Data\TestData')

For the first SQL SELECT statement, the query retrieves all the names from the Company field in the Customer table and only those order numbers from the Order_ID field in the Orders table that match on the Cust_ID field.

SELECT TAlias1.company, TAlias2.order_id ;

   FROM customer TAlias1 ;

   LEFT JOIN orders TAlias2 ;

      ON TAlias1.cust_id = TAlias2.cust_id

For the second SQL SELECT statement, the LEFT JOIN operation is replaced with a RIGHT JOIN operation, but the sequence of tables has not changed. However, the result set is different. The query retrieves all the order numbers from the Order_ID field in the Orders table for those records that match on the Cust_ID field in both tables. In this example, no order number should exist without a matching customer record, so no null values appear in the Company column. However, only those names from the Company field in the Customer table appear where the Cust_ID field in the Customer table matches the Cust_ID field in the Orders table.

SELECT TAlias1.company, TAlias2.order_id ;

   FROM customer TAlias1 ;

   RIGHT JOIN orders TAlias2 ;

      ON TAlias1.cust_id = TAlias2.cust_id

For the third SQL SELECT statement, the RIGHT JOIN operation remains but the sequence of tables is reversed. However, the results are the same as the first SQL SELECT statement.

SELECT TAlias1.company, TAlias2.order_id ;

   FROM orders TAlias2 ;

   RIGHT JOIN customer TAlias1 ;

      ON TAlias1.cust_id = TAlias2.cust_id

For more information, see Join Tab, Query and View Designers and SELECT - SQL Command.

Join Conditions

Join conditions specify conditions on which the tables in a SQL SELECT statement are joined. For example, you can use join conditions to compare values in two tables that have common fields and return only those records where those fields have the same values.

Note:
If you include more than one table in a query, you should specify a join condition for every table after the first.

You can customize the join condition for queries and views by using comparison operators to control how records are compared and which ones are returned, similar to using a filter condition. However, join conditions compare the field value in one table to the field value in another other table, while filter conditions compare a field value to a filter value. For information about filter conditions, see Filter Conditions for Queries and Views.

For example, you can use the equal (=) operator when querying two tables joined on their respective customer ID fields, such as Customer.cust_id = Orders.cust_id. This query retrieves only those records on which these two fields match and meet any other filter you set in the query. As another example, if you are using a date field in a join, you can use a comparison condition operator to include only records before or after a certain date.

The following table lists the comparison operators available for join conditions.

Operator | Description
= | Equal
== | Exactly equal
LIKE | SQL LIKE operation
<>, !=, # | Not equal
> | Greater than
>= | Greater than or equal to
< | Less than
<= | Less than or equal to

You can specify join conditions with either the ON clause or the WHERE clause of a SQL SELECT statement but not both.

For example, suppose you want all the records from a field in one table and only those values for two fields in another table that meet a join condition and a filter condition. The following code example uses the ON clause to specify a join condition, which includes a filter condition specified by the AND clause.

This example creates a query that retrieves all the names in the Company field from the Customer table and only those records that match on the Cust_ID field in the Orders table. However, not all records that match in the Orders table contain dates in the Order_Date and Shipped_On fields that pass the filter criteria, having an order date earlier than 02/16/1994. If a company does not have order dates that meet the filter condition, the Order_Date and Shipped_On columns show null values.

Note:
The SELECT statement uses local table aliases to distinguish the same field name, Cust_ID, in both tables.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT TAlias1.company, TAlias2.order_date, TAlias2.shipped_on ;
   FROM customer TAlias1 ;
   LEFT JOIN orders TAlias2 ;
      ON TAlias1.cust_id = TAlias2.cust_id ;
         AND TAlias2.order_date < {^1994-02-16}

For more information about the join conditions you can set for queries and views, see SELECT - SQL Command and Join Tab, Query and View Designers.

Join Conditions in the WHERE Clause

When writing SQL SELECT statements, you can specify join conditions in the WHERE clause along with filter conditions. When specifying filters for queries and views in the Query and View designers, the Filter tab inserts a WHERE clause into the SQL SELECT statement generated for the query or view. You can specify a join condition in the Filter tab or edit the WHERE clause in the SQL SELECT statement by viewing and editing it in the SQL window. For remote views, a join condition always appears in the WHERE clause.

For example, suppose you want customer order information, including all information about the customer and the employee who took the order. The following code example uses the WHERE clause to specify a join condition matching records on the Cust_ID field in the Customer and Orders tables and, in addition, a join condition matching the employee number in the Emp_ID field for the Orders and Employee tables.

This example retrieves only those customer records in the Customer table that match orders in the Orders table with employee records in the Employee table.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT * FROM customer TAlias1, orders TAlias2, employee TAlias3 ;
   WHERE TAlias1.cust_id = TAlias2.cust_id ;
   AND TAlias2.emp_id = TAlias3.emp_id

For more information about the WHERE clause, see Filter Tab, Query and View Designers and SELECT - SQL Command.

Join Considerations

When creating join operations, be aware of the following considerations:

  • If you include two tables in a query and do not specify a join condition, every record in the first table is joined with every record in the second table as long as the filter conditions are met. Such a query can produce lengthy results.

  • Use caution when using functions such as DELETED( ), EOF( ), FOUND( ), RECCOUNT( ), and RECNO( ), which support an optional alias or work area. Including an alias or work area in these functions might yield unexpected results. SQL SELECT does not use your work areas; it performs the equivalent of USE ... AGAIN. Single-table queries that use these functions without an optional alias or work area return proper results. However, multiple-table queries that use these functions, even without an optional alias or work area, might return unexpected results.

  • Use caution when joining tables that contain empty fields because Visual FoxPro matches empty fields. For example, suppose you perform a join on the Customer.zip and Invoice.zip fields in the Customer and Invoice tables in the sample database, TestData.dbc. If the Customer table contains 100 empty zip codes, and the Invoice table contains 400 empty zip codes, the query output contains 40,000 extra records resulting from the empty fields. To eliminate empty records from the query output, use the EMPTY( ) function.

See Also

Other Resources

General Reference
How to: Optimize Filters and Joins
Working with Queries
Working with Views
Query and View Designers
CREATE SQL VIEW Command
SELECT - SQL Command


SELECT - SQL Command - SELECT Clause

Visual FoxPro 9.0 Language Reference
SELECT - SQL Command - SELECT Clause
See Also

The SQL SELECT clause specifies the fields, constants, and expressions to display in the query results.

For the complete syntax, see SELECT - SQL Command.

The detailed syntax for the SELECT clause is as follows:

SELECT [ALL | DISTINCT] [TOP nExpr [PERCENT]] Select_List_Item [AS Column_Name] [, ...]

Parameters

[ALL | DISTINCT]

Display all rows in the query results, by default, or exclude duplicates of any rows from the query results. You can use DISTINCT only once per SELECT clause.
Note:
Visual FoxPro does not support using the DISTINCT clause in SQL SELECT statements that contain Memo, General, or Blob fields. Instead, for Memo fields, you can wrap a Memo field expression inside a function such as PADR( ) or ALLTRIM( ). For more information, see PADL( ) | PADR( ) | PADC( ) Functions and ALLTRIM( ) Function.

[TOP nExpr [PERCENT]]

Specifies that the query result contain a specific number of rows or a percentage of rows of the query result. For nExpr, you can specify 1 to 32,767 rows, or, if you include the PERCENT option, you can specify 0.01 to 99.99 percent. Visual FoxPro sorts records first and then extracts the TOP nExpr [PERCENT] records.
Note:
When you include the TOP clause, you must include an ORDER BY clause. The ORDER BY clause specifies the columns for which the TOP clause determines the number of rows to include in the query result.

Note:
The setting of the SET ENGINEBEHAVIOR command affects the results and performance of the TOP clause. For more information, see SET ENGINEBEHAVIOR Command.

PERCENT rounds up the number of rows returned in the result to the next highest integer.
Note:
Rows with identical values for the columns specified in the ORDER BY clause are included in the query result. Therefore, a query result can contain more rows than specified with nExpr. For example, if you specify 10 for nExpr, the query result can contain more than 10 rows when more than 10 rows have identical values as specified with ORDER BY.

Select_List_Item

Specifies one or more items to match and include in the query results. Each item in the list generates one column in the query results. Select_List_Item can specify the following items:
  • A constant value that appears in every row of the query results.

  • An expression that can contain user-defined functions or subqueries.

  • [Alias.]Select_Item

    Alias specifies a table alias when you are retrieving two or more Select_Item fields with the same name from multiple tables. Using a table alias prevents columns from being duplicated. A space between [Alias.] and Select_Item is permitted.

    Select_Item can also be a field from a table in the FROM clause.

  • (Subquery)

    Subquery specifies a SQL SELECT statement within another SQL SELECT statement and must be enclosed within parentheses (()).

    There is no limit on the number of subqueries per SQL SELECT statement. There is no limit on the nesting depth for subqueries in a SQL SELECT statement.

    You can use correlated subqueries up to the immediate parent. A correlated subquery uses fields in the parent query, and the subquery is executed for each candidate row in the parent query.

    Subqueries can contain TOP nExpr clauses for noncorrelated subqueries, multiple join conditions, and GROUP BY clauses. If a subquery does not return any records, it returns NULL.

    Note:
    If you include the TOP nExpr clause in a subquery, you must include an ORDER BY clause for that subquery.

You can use aggregate functions with a Select_List_Item that is a field or an expression involving a field. When specifying aggregate functions associated with Select_Item, use the following syntax:
Copy Code
AggregateFunction([Alias.]Select_Item)
For more information about using user-defined functions, aggregate functions, and rules applying to column names, see Considerations for SQL SELECT Statements.
[AS Column_Name]

Specifies a name for a column in the query output. Column_Name can be an expression, but it cannot contain characters that are not permitted, for example, spaces, in table field names.
Tip:
When Select_List_Item is an expression or contains a field function, specifying Column_Name is useful when you want to give the column a meaningful name.

Remarks

The following code shows a summary of the main clauses of the SELECT - SQL Command:

Copy Code
SELECT Select_List
   FROM Table_List
...[WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [HAVING Conditions]
   [UNION Clause]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

For more information about a particular clause of the SQL SELECT command, see the following topics:

  • FROM Clause

  • SELECT - SQL Command - WITH Clause

  • SELECT - SQL Command - WHERE Clause

  • GROUP BY Clause

  • HAVING Clause

  • UNION Clause

  • ORDER BY Clause

  • INTO or TO Clause

  • Additional Display Options

Examples

Example 1

The following example displays unique data from a query using the DISTINCT option with a join condition in the WHERE clause. The example displays the Company, Order_Date, and Shipped_On fields for only those records with unique data in the Customer and Orders tables. The SELECT statement specifies local aliases for the tables to distinguish the same field name, Cust_ID, in both tables.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT DISTINCT TAlias1.company, TAlias2.order_date, ;
   TAlias2.shipped_on ;
   FROM customer TAlias1, orders TAlias2 ;
   WHERE TAlias1.cust_id = TAlias2.cust_id

Example 2

The following example displays all records from a query in a specified column using the AS Column_Name clause. The example displays all names in the City field from the Customer table in uppercase using the UPPER( ) function and in column called CityList.

Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT UPPER(city) AS CityList FROM customer

See Also

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
CREATE TABLE - SQL Command
MODIFY QUERY Command


SELECT - SQL Command - WITH Clause

Visual FoxPro 9.0
SELECT - SQL Command - WITH Clause
See Also

The WITH clause allows you to apply a single command to existing SELECT statements without modifying those statements.

For the complete syntax, see SELECT - SQL Command.

[WITH (BUFFERING = lExpr) ]

Parameters

lExpr

Logical data type. The following table lists the values for lExpr.

lExpr Setting

True (.T.)

Data in the SQL-SELECT statement is based on buffered data, if available.

False (.F.)

(Default) Data in the SQL-SELECT statement is based on data written to disk only.

Remarks

The following code shows a summary of the main clauses of the SELECT - SQL Command:

Copy Code
SELECT Select_List
   FROM Table_List
...[WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [UNION Clause]
   [HAVING Conditions]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

For more information about a particular clause of the SQL SELECT command, see the following topics:

  • SELECT Clause

  • FROM Clause

  • WHERE Clause

  • GROUP BY Clause

  • HAVING Clause

  • UNION Clause

  • ORDER BY Clause

  • INTO or TO Clause

  • Additional Display Options

If you set BUFFERING to True (.T.), you can query data from a local buffered cursor, which may include records that have been updated but not committed. Otherwise, your results include only records committed to disk.

If the cursor uses row buffering, then current record is committed before the statement is executed.

If the cursor uses table buffering, then the modified current record is saved into the buffer.

The WITH clause to specify BUFFERING is supported on local Visual FoxPro data only and not on data from back-end databases.

If you set BUFFERING to False (.F.), then your SELECT statement pulls data from cursor on disk (which may be different to what is in buffer). If you do not include the BUFFERING statement, then your results are based on the setting for SET SQLBUFFERING Command. By default, your queries pull data from disk. A SELECT statement WITH BUFFERING set to True (.T.) overrides the SET SQLBUFFERING setting.

The WITH BUFFERING option is effective in the following cases:

  • The work area does not have an alias specified to support the cursor referenced in the statement.

  • The cursor is not buffered.

  • The cursor acts as the target for update or delete operations.

Example 1

Description

The following example shows a simple statement referencing a single table. You need to have a work area that has the alias "Customers" in order for the WITH clause to be effective.

Code

Copy Code
SELECT * FROM customers WITH (BUFFERING=.T.)

Example 2

Description

The following example shows that each table referenced in the FROM clause needs a WITH BUFFERING clause.

Code

Copy Code
SET MULTILOCKS ON
CREATE TABLE Table1 (Field1 N(10), Field2 N(10))
CREATE TABLE Table2 (Field3 N(10), Field4 N(10))

CURSORSETPROP("Buffering", 5, "Table1")
CURSORSETPROP("Buffering", 5, "Table2")

INSERT INTO Table1 VALUES (1, 1)
INSERT INTO Table2 VALUES (0, 100)

SELECT Table1.*, Table2.* ;
   FROM FORCE Table1 ;
      JOIN Table2 ;
      ON Field1>=Field3 AND Field2>0 AND Field4<100

REPLACE Field4 WITH 99 IN Table2

SELECT Table1.*, Table2.* ;
   FROM FORCE Table1 ;
      JOIN Table2 ;
      ON Field1>=Field3 AND Field2>0 AND Field4<100

SELECT Table1.*, Table2.* ;
   FROM FORCE Table1 WITH (BUFFERING=.T.) ;
      JOIN Table2 WITH (BUFFERING=.T.) ;
      ON Field1>=Field3 AND Field2>0 AND Field4<100

See Also

Concepts

Buffering Data

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
MODIFY QUERY Command


SELECT - SQL Command - FROM Clause

Visual FoxPro 9.0 Language Reference
SELECT - SQL Command - FROM Clause
See Also Example

The FROM clause specifies one or more tables containing the data that the query retrieves from.

For the complete syntax, see SELECT - SQL Command.

The detailed syntax for the FROM clause is as follows:

FROM [FORCE] Table_List_Item [, ...]
      [[JoinType] JOIN DatabaseName!]Table [[AS] Local_Alias]
      [ON JoinCondition [AND | OR [JoinCondition | FilterCondition] ...]

Parameters

[FORCE]

FORCE specifies that the tables in the table list are joined in the order they appear in the FROM clause.
Note:
If FORCE is omitted, Visual FoxPro attempts to optimize the query. However, the query might be executed faster by including the FORCE keyword to disable Visual FoxPro query optimization.

Table_List_Item [, ...]

Specifies one or more tables that contain the data the query retrieves from. Table_List_Item can have the following syntaxes:
  • [DatabaseName!]Table [[AS] Local_Alias]

    DatabaseName! specifies the name of a database containing the table if the table is in a noncurrent database. If the table is in a noncurrent database, you must include the name of database. Use an exclamation point (!) as a delimiter immediately following the database name and preceding the table name.

    Table specifies the name of the table you want to retrieve data from. If no table is open, Visual FoxPro displays the Open dialog box so you can specify the file location. After the table opens, it remains open when the query is complete.

    Local_Alias specifies a temporary name for the table specified in Table. If you specify a local alias, you must use the local alias instead of the table name throughout the SELECT statement.

    There is no limit on the number of tables and aliases per SELECT statement. You can also specify multiple tables by using one or more JOIN clauses.

  • (Subquery) AS Subquery_Alias

    Subquery specifies a SELECT statement within another SELECT statement.

    Note:
    In the FROM clause, each subquery requires an alias.

    Subqueries in the FROM clause do not have the restrictions that apply to subqueries in filter conditions and can use any SQL SELECT clauses, including UNION clauses. All subqueries in the FROM clause are executed before the main SELECT statement is evaluted.

[[ JoinType] JOIN DatabaseName!] Table[[AS] Local_Alias]

Specifies a JOIN clause for retrieving data from more than one table. Visual FoxPro supports nested joins.
Note:
There is no limit on the number of joins per SELECT statement.

Note:
The following table describes the different types of joins you can specify with JoinType.

JoinType | Description
INNER | Query result contains only rows from a table that match one or more rows in another table. (Default)
LEFT [OUTER] | Query result contains all rows from the table to the left of the JOIN keyword and only matching rows from the table to the right of the JOIN keyword. The OUTER keyword is optional; include it to clarify that an outer join is created.
RIGHT [OUTER] | Query result contains all rows from the table to the right of the JOIN keyword and only matching rows from the table to the left of the JOIN keyword. The OUTER keyword is optional; it can be included to clarify that an outer join is created.
FULL [OUTER] | Query result contains all matching and nonmatching rows from both tables. The OUTER keyword is optional; you can include it to clarify that an outer join is created.

For more information about the [DatabaseName!]Table [[AS] Local_Alias] clause, see the FROM clause. For more information about join operations, see Join Conditions for Tables, Queries, and Views.

[ON JoinCondition| FilterCondition[AND | OR [ JoinCondition| FilterCondition] ...]

Specifies conditions on which tables in a SQL SELECT statement are joined or results are filtered. Join conditions can also include filter conditions. For multiple join or filter conditions, you must use the AND or OR operator to connect those conditions. You can include subqueries and nested subqueries in the ON clause.
Note:
If you include more than one table in a query, you should specify a join condition for every table after the first.

JoinCondition specifies conditions that can contain the following:
  • A comparison condition between fields from different tables, for example:

    FieldName1 Comparison FieldName2

    FieldName1 specifies a field name from one table, and FieldName2 specifies a field name from another table.

  • A comparison condition containing expressions involving fields from different tables, for example:

    Table1.Field1 + Table2.Field1 Comparison Table3.Field1

  • A user-defined function, for example:

    MyUDF(Table1.Field1, Table2.Field1)

The following table lists the operators available for Comparison.

Comparison Description

=

Equal

Note:
When you use the equal (=) operator with strings, it functions differently depending on the setting of SET ANSI. When SET ANSI is set to OFF, Visual FoxPro compares strings only to the end of the shorter string. When SET ANSI is set to ON, Visual FoxPro follows ANSI standards for string comparisons. For more information, see SET ANSI and SET EXACT.

==

Exactly equal

LIKE

SQL LIKE operation

<>, !=, #

Not equal

>

Greater than

>=

Greater than or equal to

<

Less than

<=

Less than or equal to
For more information about join conditions, see Join Conditions for Tables, Queries, and Views. FilterCondition specifies a logical expression that describes filter criteria that records must meet to be included in the query results. You can include multiple filter conditions in a query by connecting them with the AND or OR operator. To reverse the value of a logical expression, use the NOT operator. To check for an empty field, use the EMPTY( ) function. FilterCondition can use the syntaxes described for JoinCondition except the fields specified are in the same table. In addition, FilterCondition can specify the following syntaxes:
  • FieldName Comparison Expression

    -OR-

  • FieldName [NOT] LIKE cExpression | IS [NOT] NULL | [NOT] BETWEEN Start_Range AND End_Range | [NOT] IN Value_Set

For more information about valid operators for Comparison, see the description for JoinCondition. The following table describes other options available when specifying FilterCondition.

Option Description

Expression

FieldName values must meet comparison with an expression for inclusion in the query results.

LIKE "cExpression"

FieldName values must match the character expression, cExpression, which can contain SQL wildcard characters, such as percent (%) and underscore (_), for inclusion in the query results.

The % character represents any sequence of unknown characters in the string. The _ character represents a single unknown character in the string. You can use the ESCAPE clause to specify wildcard characters as literals.

The LIKE "sometext%" filter condition is fully optimized.

IS NULL

FieldName value must be null for inclusion in the query results.

BETWEEN Start_Range AND End_Range

FieldName values must be within a specified range of values for inclusion in the query results.

IN (Value_Set)

FieldName must contain one of the values or expressions specified in Value_Set for inclusion in the query results. When listing items in the value set, separate each item with commas.

Note:
The number of values or expressions you can specify for Value_Set is affected by the setting of SYS(3055) – FOR and WHERE Clause Complexity.

Tip:
Visual FoxPro might stop evaluating values and expressions in the Value_Set list when the first match is found. Therefore, if the IN clause is not Rushmore optimized, you can improve performance by placing values most likely to match in the beginning of the Value_Set list.

For more information and examples about filter conditions, see Filter Conditions for Queries and Views.

Remarks

The following code shows a summary of the main clauses of the SELECT - SQL Command:

Copy Code
SELECT Select_List
   FROM Table_List
...[WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [UNION Clause]
   [HAVING Conditions]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

For more information about a particular clause of the SQL SELECT command, see the following topics:

  • SELECT Clause

  • SELECT - SQL Command - WITH Clause

  • SELECT - SQL Command - WHERE Clause

  • GROUP BY Clause

  • HAVING Clause

  • UNION Clause

  • ORDER BY Clause

  • INTO or TO Clause

  • Additional Display Options

Example

The following example displays data from field in a table using the FROM clause. The example displays all the company names in the Company field from the Customer table:
Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT customer.company ;
   FROM customer

See Also

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
CREATE TABLE - SQL Command
MODIFY QUERY Command


SELECT - SQL Command - WHERE Clause

Visual FoxPro 9.0 Language Reference
SELECT - SQL Command - WHERE Clause
See Also Example

The WHERE clause specifies join and filter conditions that determine the rows that the query returns. Join operations in the WHERE clause function the same as JOIN operations in the FROM clause.

Note:
Including the EVALUATE( ) function in the WHERE clause of a SQL query can return incorrect data.

For the more information, see SELECT - SQL Command.

The detailed syntax for the WHERE clause is as follows:

[WHERE JoinCondition | FilterCondition [AND | OR JoinCondition | FilterCondition] ...]

Parameters

JoinCondition

Specifies conditions on which the tables in a SQL SELECT statement are joined. For multiple join conditions, you must use the AND or OR operator to connect those conditions. For more information about JoinCondition, see the ON clause in the FROM clause.
FilterCondition

Specifies criteria that records must meet to be included in the query results. For more information about FilterCondition, see the ON clause in the FROM clause.

Remarks

JoinCondition or FilterCondition can be an IN clause. The IN clause is of the form IN (Value_Set) where Value_Set is Expr1[, Expr2[, ...[ ,ExprN]]]. In Visual FoxPro 9.0 the IN clause is evaluated in a different manner than previous versions; see Changes in Functionality for the Current Release for more information.

The following demonstrates the format of the IN clause.

Copy Code
CLOSE DATABASES ALL
CREATE CURSOR MyCursor(Field1 I, Field2 I)
INSERT INTO MyCursor values(1,6)
INSERT INTO MyCursor values(2,5)
INSERT INTO MyCursor values(3,4)

SELECT * FROM MyCursor WHERE MyCursor. Field1 ;
IN (1,2,3,4,5)

The following code shows a summary of the main clauses of the SELECT - SQL Command:

Copy Code
SELECT Select_List
   FROM Table_List
...[WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [UNION Clause]
   [HAVING Conditions]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

For more information about a particular clause of the SQL SELECT command, see the following topics:

  • SELECT Clause

  • FROM Clause

  • SELECT - SQL Command - WITH Clause

  • GROUP BY Clause

  • HAVING Clause

  • UNION Clause

  • ORDER BY Clause

  • INTO or TO Clause

  • Additional Display Options

You can create filter conditions that search for data containing SQL SELECT wildcard characters, such as percent (%) and underscore (_), by using the ESCAPE clause in the WHERE clause. In the ESCAPE clause, you can specify a character that, when placed immediately before the wildcard character, indicates that the wildcard character be treated as a literal character. For more information and examples, see Filter Conditions for Queries and Views.

Example

The following example displays three fields from two tables, but only those records meeting join and filter conditions in the WHERE clause. The example joins the Customer and Orders table on the Cust_ID field and displays the Company, Order_Date, and Shipped_On fields for only those records that have an order date earlier than 02/16/1994. The SELECT statement specifies local aliases for the tables to distinguish the same field name, Cust_ID, in both tables.
Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT TAlias1.company, TAlias2.order_date, TAlias2.shipped_on ;
   FROM customer TAlias1, orders TAlias2 ;
   WHERE TAlias1.cust_id = TAlias2.cust_id ;
   AND TAlias2.order_date < {^1994-02-16}

See Also

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
CREATE TABLE - SQL Command
MODIFY QUERY Command


SELECT - SQL Command - GROUP BY Clause

Visual FoxPro 9.0 Language Reference
SELECT - SQL Command - GROUP BY Clause
See Also

The GROUP BY clause specifies one or more columns used to group rows returned by the query. Columns referenced in the SQL SELECT statement list, except for aggregate expressions, must be included in the GROUP BY clause. You cannot group by Memo, General, or Blob fields.

For the complete syntax, see SELECT - SQL Command.

The detailed syntax for the GROUP BY clause is as follows:

[GROUP BY Column_List_Item [, ...] ]

Parameters

Column_List_Item

Specifies one or more columns used to group rows returned by the query.

Column_List_Item can be one of the following:

  • A field in a table in the FROM clause or a subquery.

  • A table alias from the SQL SELECT list.

  • A numeric expression indicating the location of the column in the result table. The leftmost column is number 1.

Remarks

The following code shows a summary of the main clauses of the SELECT - SQL Command:

Copy Code
SELECT Select_List
   FROM Table_List
...[WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [HAVING Conditions]
   [UNION Clause]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

For more information about a particular clause of the SQL SELECT command, see the following topics:

  • SELECT Clause

  • FROM Clause

  • SELECT - SQL Command - WITH Clause

  • SELECT - SQL Command - WHERE Clause

  • HAVING Clause

  • UNION Clause

  • ORDER BY Clause

  • INTO or TO Clause

  • Additional Display Options

See Also

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
CREATE TABLE - SQL Command
MODIFY QUERY Command


SELECT - SQL Command - UNION Clause

Visual FoxPro 9.0 Language Reference
SELECT - SQL Command - UNION Clause
See Also

The UNION clause combines the results from two or more SQL SELECT statements into a single result set containing rows from all the queries in the UNION operation.

Note:
When one of the columns is of Memo, General, or Blob type, performing unions of differing column types is not allowed.

For the complete syntax, see SELECT - SQL Command.

The detailed syntax for the UNION clause is as follows:

[UNION [ALL] SELECTCommand]

Parameters

[UNION [ALL] SELECTCommand]

Specifies another SELECT statement. By default, UNION eliminates duplicate rows from the combined result set.
Note:
The ALL keyword includes duplicate rows in the combined result set.

Remarks

The following code shows a summary of the main clauses of the SELECT - SQL Command:

Copy Code
SELECT Select_List
   FROM Table_List
...[WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [HAVING Conditions]
   [UNION Clause]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

For more information about a particular clause of the SQL SELECT command, see the following topics:

  • SELECT Clause

  • FROM Clause

  • SELECT - SQL Command - WITH Clause

  • SELECT - SQL Command - WHERE Clause

  • GROUP BY Clause

  • HAVING Clause

  • ORDER BY Clause

  • INTO or TO Clause

  • Additional Display Options

You can use the UNION clause to simulate an outer join. You can specify multiple UNION clauses; there is no limit on the number of UNION clauses per SELECT statement.

Visual FoxPro supports implicit data type conversion for data types that support it. For more information as well as rules and considerations concerning UNION clauses, see Considerations for SQL SELECT Statements.

See Also

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
CREATE TABLE - SQL Command
MODIFY QUERY Command


SELECT - SQL Command - HAVING Clause

Visual FoxPro 9.0 Language Reference
SELECT - SQL Command - HAVING Clause
See Also

The HAVING clause specifies conditions that determines the groups included in the query. If the SQL SELECT statement does not contain aggregate functions, you can use a SQL SELECT statement that contains a HAVING clause without a GROUP BY clause.

Tip:
The HAVING clause without a GROUP BY clause acts like the WHERE clause. If the HAVING clause contains no aggregate functions, use the WHERE clause for faster performance.

Note:
The HAVING clause should appear before an INTO clause; otherwise, a syntax error occurs.

For the complete syntax, see SELECT - SQL Command.

The detailed syntax for the HAVING clause is as follows:

HAVING FilterCondition [AND | OR ...]

Parameters

FilterCondition

Specifies criteria that groups must meet for inclusion in the query results. The HAVING clause can include multiple filter conditions connected by AND or OR operators. To reverse the value of a logical expression, use NOT.
Note:
Filter conditions in the HAVING clause cannot contain subqueries. You can use local aliases and aggregate functions in the HAVING clause. For more information on aggregate functions in the HAVING clause, see Considerations for SQL SELECT Statements.

Note:
For more information about FilterCondition, see the ON clause in the FROM clause.

Remarks

The following code shows a summary of the main clauses of the SELECT - SQL Command:

Copy Code
SELECT Select_List
   FROM Table_List
...[WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [HAVING Conditions]
   [UNION Clause]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

For more information about a particular clause of the SQL SELECT command, see the following topics:

  • SELECT Clause

  • FROM Clause

  • SELECT - SQL Command - WITH Clause

  • SELECT - SQL Command - WHERE Clause

  • GROUP BY Clause

  • UNION Clause

  • ORDER BY Clause

  • INTO or TO Clause

  • Additional Display Options

See Also

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
CREATE TABLE - SQL Command
MODIFY QUERY Command


SELECT - SQL Command - ORDER BY Clause

Visual FoxPro 9.0 Language Reference
SELECT - SQL Command - ORDER BY Clause
See Also Example

The ORDER BY clause specifies one or more items used to sort the final query result set and the order for sorting the results.

Note:
If you do not specify an order in the ORDER BY clause, query results appear in no order.

For the complete syntax, see SELECT - SQL Command.

The detailed syntax for the ORDER BY clause appears as follows:

[ORDER BY Order_Item [ASC | DESC] [, ...]]

Parameters

[ORDER BY Order_Item

Specifies the item used to sort the final query result set.
  • A field in a FROM table or a subquery. You cannot specify a Blob or General type field.

    Note:
    If the ORDER BY clause is applied to a UNION operation, the field should also be a Select_Item in the last SELECT clause, not a subquery.

  • A field alias from the SELECT list.

    Note:
    If the ORDER BY clause is applied to a UNION operation, the alias should be a Select_Item in the last SELECT clause.

  • A numeric expression indicating the location of the column in the result table. The leftmost column is number 1.

[ASC]

Specifies an ascending order for the query results. ASC is the default order for ORDER BY.
[DESC]

Specifies a descending order for the query results.

Remarks

The following code shows a summary of the main clauses of the SELECT - SQL Command:

Copy Code
SELECT Select_List
   FROM Table_List
...[WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [HAVING Conditions]
   [UNION Clause]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

For more information about a particular clause of the SQL SELECT command, see the following topics:

  • SELECT Clause

  • FROM Clause

  • SELECT - SQL Command - WITH Clause

  • SELECT - SQL Command - WHERE Clause

  • GROUP BY Clause

  • HAVING Clause

  • UNION Clause

  • INTO or TO Clause

  • Additional Display Options

Example

The following example organizes results of a query using the ORDER BY Order_Item clause. The example displays the Country, PostalCode, and Company fields for those records in the Customer table in ascending order, by default.
Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT country, postalcode, company ;
   FROM customer ;
   ORDER BY country, postalcode, company

See Also

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
CREATE TABLE - SQL Command
MODIFY QUERY Command


SELECT - SQL Command - INTO or TO Clause

Visual FoxPro 9.0 Language Reference
SELECT - SQL Command - INTO or TO Clause
See Also Example

The INTO or TO clauses specify output options that determine the location for storing or sending the final query results from a SQL SELECT statement.

For more information, see SELECT - SQL Command.

The detailed syntax for the INTO or TO clause is as follows:

[INTO StorageDestination | TO DisplayDestination ]

Parameters

[INTO StorageDestination]

Stores the query results in an array, cursor, or table.
Note:
If you do not include the INTO clause, query results are displayed in a Browse window by default. To direct the query results to the printer or a file, use the TO clause.

The following table describes locations in which you can store the query results using the INTO clause.

StorageDestination Description

ARRAY ArrayName

Stores query results in a memory variable array.

Note:
If the query selects zero records, the array is not created.

CURSOR CursorName [NOFILTER | READWRITE]

Stores query results in a temporary cursor.

Note:
If you specify the name of an open table, Visual FoxPro generates an error message. After SELECT is executed, the temporary cursor remains open and is active and read-only unless you specify the READWRITE option. When you close this temporary cursor, it is deleted. Cursors can exist as a temporary file on the drive or volume specified by SORTWORK.

NOFILTER creates a cursor that can be used in subsequent queries.

Note:
Including NOFILTER can reduce query performance because it creates a temporary table on disk. When the cursor is closed, the temporary table is deleted from disk.

READWRITE specifies that the temporary cursor is modifiable. If the source table or tables use auto-incrementing, the cursor created with READWRITE does not inherit those settings. You can create more than one structural index on a cursor using the READWRITE argument.

TABLE TableName [DATABASE DatabaseName [NAME LongTableName]]

Stores query results in a table.

Caution:
If you specify a table that is open, and SET SAFETY is set to OFF, Visual FoxPro overwrites the table without warning.

If you do not specify an extension, Visual FoxPro gives the table a .dbf extension. The table remains open and active after SELECT is executed.

DATABASE DatabaseName specifies a database you can add the table to.

NAME LongTableName specifies a long name for the table. Long names can contain up to 128 characters and can be used in place of short file names in the database.
[TO DisplayDestination]

Sends the query results to a file, printer, main Visual FoxPro window, or an active user-defined window.
Note:
Visual FoxPro disregards the TO clause if you also include the INTO clause in the same query.

The following table describes locations that you can send the query results using the TO clause.

DisplayDestination Description

FILE FileName [ADDITIVE]

Specifies an ASCII text file that you can direct the query results to.

ADDITIVE appends query output to the existing contents of the text file specified by FileName.

PRINTER [PROMPT]

Directs query output to a printer.

PROMPT displays a printer dialog box before printing begins. You can adjust printer settings in the dialog box. The printer settings that you can adjust depend on the currently installed printer driver.

SCREEN

Directs query output to the main Visual FoxPro window or an active user-defined window.

Remarks

The following code shows a summary of the main clauses of the SELECT - SQL Command:

Copy Code
SELECT Select_List
   FROM Table_List
...[WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [UNION Clause]
   [HAVING Conditions]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

For more information about a particular clause of the SQL SELECT command, see the following topics:

  • SELECT Clause

  • FROM Clause

  • SELECT - SQL Command - WITH Clause

  • SELECT - SQL Command - WHERE Clause

  • GROUP BY Clause

  • HAVING Clause

  • UNION Clause

  • ORDER BY Clause

  • Additional Display Options

Example

The following example stores the contents of a query into a table using INTO TABLE TableName clause. The example stores the contents of the Company, Order_Date, and Shipped_On fields from the Customer and Order tables, which are joined on the Cust_ID field, in a third table called CustShip. The example then opens a Browse window for the new table. The SELECT statement specifies local aliases for the tables to distinguish the same field name, Cust_ID, in both tables.
Copy Code
CLOSE ALL
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT TAlias1.company, TAlias2.order_date, TAlias2.shipped_on ;
   FROM customer TAlias1, orders TAlias2 ;
   WHERE TAlias1.cust_id = TAlias2.cust_id ;
   INTO TABLE custship.dbf
BROWSE

See Also

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
CREATE TABLE - SQL Command
MODIFY QUERY Command


SELECT - SQL Command - Additional Display Options

Visual FoxPro 9.0 Language Reference
SELECT - SQL Command - Additional Display Options
See Also

You can specify additional display options for the final query results from a SQL SELECT statement.

For the complete syntax, see SELECT - SQL Command.

The detailed syntax for the Additional Display Options is as follows:

[PREFERENCE PreferenceName] [NOCONSOLE] [PLAIN] [NOWAIT]

Parameters

[PREFERENCE PreferenceName]

Saves the attributes and options of the Browse window for later use when query results are sent to a browse window.
Note:
You can retrieve preferences at any time. The attributes, or preferences, are saved indefinitely in the FoxUser.dbf resource file.

The first time you use the PREFERENCE clause in a SELECT statement, it creates the preference. Issuing a SELECT statement later with the same preference name restores the Browse window to that preference state. When the Browse window is closed, the preference is updated. If you close a Browse window by pressing CTRL+Q or CTRL+W, changes you made to the Browse window are not saved to the resource file.
[NOCONSOLE]

Prevents display of query results sent to a file, the printer, or the main Visual FoxPro window.
[PLAIN]

Prevents column headings from appearing in the query output that is displayed.
Note:
You can use the PLAIN clause regardless of whether a TO clause is included. If an INTO clause is included, Visual FoxPro disregards the PLAIN option.

[NOWAIT]

Continues program execution after the Browse window is opened and query results are directed to it. The program does not wait for the Browse window to close but continues execution on the program line immediately following the SELECT statement.
Note:
If an INTO clause is included, Visual FoxPro disregards the NOWAIT option.

For example, when you include the TO SCREEN clause to direct output to the main Visual FoxPro window or to a user-defined window, output pauses when the main Visual FoxPro window or user-defined window is full of query results. To see the next set of query results, press a key. However, if you include NOWAIT, the query results scroll off the main Visual FoxPro window or the user-defined window without pausing for a key press.

Remarks

The following code shows a summary of the main clauses of the SELECT - SQL Command:

Copy Code
SELECT Select_List
   FROM Table_List
...[WITH (BUFFERING = lExpr)]
   [WHERE Conditions]
   [GROUP BY Column_List]
   [HAVING Conditions]
   [UNION Clause]
   [ORDER BY Column_List]
   [INTO Clause | TO Clause ]
   [Additional_Display_Options]

For more information about a particular clause of the SQL SELECT command, see the following topics:

  • SELECT Clause

  • FROM Clause

  • SELECT - SQL Command - WITH Clause

  • SELECT - SQL Command - WHERE Clause

  • GROUP BY Clause

  • HAVING Clause

  • UNION Clause

  • ORDER BY Clause

  • INTO or TO Clause

  • Additional Display Options

See Also

Other Resources

Working with Queries
Working with Views
CREATE QUERY Command
Query and View Designers
CREATE TABLE - SQL Command
MODIFY QUERY Command


SELECT Command

Visual FoxPro 9.0 Language Reference
SELECT Command
See Also Example

Activates the specified work area.

SELECT nWorkArea | cTableAlias

Parameters

nWorkArea

Specifies a work area to activate. If nWorkArea is 0, the lowest-numbered unused work area is activated.
cTableAlias

Specifies a work area containing an open table to activate. cTableAlias is the alias of the open table. You can also include a letter from A through J for cTableAlias to activate one of the first ten work areas.

Remarks

By default, work area number 1 is active when you start Visual FoxPro.

Note:
Fields in tables open in any work area can be included in Visual FoxPro commands and functions. Use the following formats to access fields in a table open in a work area other than the current one: alias.field or alias -> field.

Example

The following example demonstrates ways of selecting work areas.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
SELECT 1     && Work area 1
USE customer  && Opens Customer table

SELECT 2     && Work area 2
USE orders  && Opens Orders table

SELECT customer     && Work area 1
BROWSE

SELECT B     && Work area 2
BROWSE

See Also

Other Resources

Commands
ALIAS( ) Function
SELECT( ) Function
USE Command


SET Command Overview

Visual FoxPro 9.0 Language Reference
SET Command Overview
See Also

The SET command performs different operations when used with various keywords.

SET [ [cSetCommand] [ON | OFF] | TO [eSetting] ]

Remarks

When no arguments are passed, SET opens the Data Session window. The Data Session window provides an easy way to open tables, establish relations, or change different Microsoft Visual FoxPro settings. For more information, see Data Session Window.

The following table lists other operations that the SET command performs.

SET command | Description
SET ALTERNATE Command | Directs screen or printer output created with the ?, ??, DISPLAY, or LIST commands to a text file.
SET ANSI Command | Determines how comparisons between strings of different lengths are made with the = operator in Visual FoxPro SQL commands.
SET ASSERTS Command | Specifies if ASSERT commands are evaluated or ignored.
SET AUTOINCERROR Command | Specifies whether attempts to update values in a field using autoincrementing generate an error or fail silently and proceed.
SET AUTOSAVE Command | Determines whether Visual FoxPro flushes data buffers to disk when you exit a READ or return to the Command window.
SET BELL Command | Turns the computer bell on or off and sets the bell attributes.
SET BLOCKSIZE Command | Specifies how Visual FoxPro allocates disk space for the storage of memo fields.
SET BROWSEIME Command | Specifies if the Input Method Editor is opened when you navigate to a text box in a Browse window.
SET CARRY Command | Determines whether Visual FoxPro carries data forward from the current record to a new record created with INSERT, APPEND, and BROWSE.
SET CENTURY Command | Determines whether Microsoft Visual FoxPro displays the century portion of date expressions and how Visual FoxPro interprets dates that specify only 2 digit years.
SET CLASSLIB Command | Opens a visual class library (.vcx) containing class definitions.
SET CLOCK Command | Determines whether Visual FoxPro displays the system clock and specifies the clock location on the main Visual FoxPro window.
SET COLLATE Command | Specifies a collation sequence for character fields in subsequent indexing and sorting operations.
SET COLOR OF SCHEME Command | Specifies the colors of a color scheme or copies one color scheme to another color scheme.
SET COLOR SET Command | Loads a previously defined color set.
SET COMPATIBLE Command | Controls compatibility with Microsoft FoxBASE+ and other FoxPro languages.
SET CONFIRM Command | Specifies whether the user can exit a text box by typing past the last character in the text box.
SET CONSOLE Command | Enables or disables output to the main Visual FoxPro window or to the active user-defined window from within programs.
SET COVERAGE Command | Turns code coverage on or off, or specifies a text file to which code coverage information is directed.
SET CPCOMPILE Command | Specifies the code page for compiled programs.
SET CPDIALOG Command | Specifies whether the Code Page dialog box is displayed when a table is opened.
SET CURRENCY Command | Defines the currency symbol and specifies its position in the display of numeric, currency, float, and double expressions.
SET CURSOR Command | Determines whether the insertion point is displayed when Visual FoxPro waits for input.
SET DATABASE Command | Specifies the current database.
SET DATASESSION Command | Activates the specified form's data session.
SET DATE Command | Specifies the format for the display of Date and DateTime expressions.
SET DEBUG Command | Included for backward compatibility. Makes the Debug and Trace windows either available or unavailable from the Visual FoxPro menu system in versions prior to 5.0.
SET DEBUGOUT Command | Directs debugging output to a file.
SET DECIMALS Command | Specifies the number of decimal places displayed in numeric expressions.
SET DEFAULT Command | Specifies the default drive and directory.
SET DELETED Command | Specifies whether Visual FoxPro processes records marked for deletion and whether they are available for use in other commands.
SET DEVELOPMENT Command | Causes Visual FoxPro to compare the creation date and time of a program with those of its compiled object file when the program is run.
SET DEVICE Command | Directs output from @ ... SAY to the screen, a printer, or a file.
SET Display Command | Included for backward compatibility.
SET DOHistory Command | Included for backward compatibility.
SET ECHO Command | Opens the Trace window for program debugging. Included for backward compatibility.
SET ENGINEBEHAVIOR Command | Enables SQL data engine compatibility with Visual FoxPro 7.0, 8.0, or 9.0.
SET ESCAPE Command | Determines whether pressing the ESC key interrupts program and command execution.
SET EVENTLIST Command | Specifies events to track in the Debug Output window or in a file specified with SET EVENTTRACKING.
SET EVENTTRACKING Command | Turns event tracking on or off or specifies a text file to which event tracking information is directed.
SET EXACT Command | Specifies the rules Visual FoxPro uses when comparing two strings of different lengths.
SET EXCLUSIVE Command | Specifies whether Visual FoxPro opens table files for exclusive or shared use on a network.
SET FDOW Command | Specifies the first day of the week.
SET FIELDS Command | Specifies which fields in a table can be accessed.
SET FILTER Command | Specifies a condition that records in the current table must meet to be accessible.
SET FIXED Command | Specifies if the number of decimal places used in the display of numeric data is fixed.
SET FULLPATH Command | Specifies if CDX( ), DBF( ), MDX( ), and NDX( ) return the path in a file name.
SET FUNCTION Command | Assigns an expression (keyboard macro) to a function key or key combination.
SET FWEEK Command | Specifies the requirements for the first week of the year.
SET HEADINGS Command | Determines whether column headings are displayed for fields and whether file information is included when TYPE is issued to display the contents of a file.
SET HELP Command | Enables or disables Microsoft Visual FoxPro online Help or specifies a Help file.
SET HOURS Command | Sets the system clock to a 12- or 24-hour time format.
SET INDEX Command | Opens one or more index files for use with the current table.
SET KEY Command | Specifies access to a range of records based on their index keys.
SET KEYCOMP Command | Controls Visual FoxPro keystroke navigation.
SET LIBRARY Command | Opens an external API (application programming interface) library file.
SET LOCK Command | Enables or disables automatic file locking in certain commands.
SET LOGERRORS Command | Determines whether Visual FoxPro sends compilation error messages to a text file.
SET MACKEY Command | Specifies a key or key combination that displays the Macro Key Definition dialog box.
SET MARGIN Command | Sets the left printer margin and affects all output directed to the printer.
SET MARK OF Command | Specifies a mark character for menu titles or menu items, or displays or clears the mark character.
SET MARK TO Command | Specifies a delimiter for the display of date expressions.
SET MEMOWIDTH Command | Specifies the displayed width of memo fields and character expressions.
SET MESSAGE Command | Defines a message for display in the main Visual FoxPro window or in the graphical status bar, or specifies the location of messages for user-defined menu bars and menu commands.
SET MULTILOCKS Command | Determines whether you can lock multiple records using LOCK( ) or RLOCK( ).
SET NEAR Command | Determines where the record pointer is positioned after FIND or SEEK unsuccessfully searches for a record.
SET NOCPTRANS Command | Prevents translation to a different code page for selected fields in an open table.
SET NOTIFY Command | Enables or disables the display of certain system messages.
SET NULL Command | Determines how null values are supported by the ALTER TABLE, CREATE TABLE and INSERT - SQL commands.
SET NULLDISPLAY Command | Specifies the text displayed for null values.
SET ODOMETER Command | Specifies the reporting interval of the record counter for commands that process records.
SET OLEOBJECT Command | Specifies whether Visual FoxPro searches the OLE Registry when an object cannot be located.
SET OPTIMIZE Command | Enables or disables Rushmore Query Optimization.
SET ORDER Command | Designates a controlling index file or tag for a table.
SET PALETTE Command | Specifies whether the Visual FoxPro default color palette is used.
SET PATH Command | Specifies a path for file searches.
SET PDSETUP Command | Loads a printer driver setup or clears the current printer driver setup.
SET POINT Command | Determines the decimal point character used in the display of numeric and currency expressions.
SET PRINTER Command | Enables or disables output to the printer, or routes output to a file, port, or network printer.
SET PROCEDURE Command | Opens a procedure file.
SET READBORDER Command | Determines whether borders are placed around text boxes created with @ ... GET.
SET REFRESH Command | Determines whether and how often a Browse window is updated with changes made to records by other users on the network.
SET RELATION Command | Establishes a relationship between two open tables.
SET RELATION OFF Command | Breaks an established relationship between the parent table in the currently selected work area, and a related child table.
SET REPORTBEHAVIOR Command | Specifies the kind of report engine processing Visual FoxPro uses when executing traditional REPORT FORM and LABEL commands.
SET REPROCESS Command | Specifies how many times and for how long Visual FoxPro attempts to lock a file or record after an unsuccessful locking attempt.
SET RESOURCE Command | Updates or specifies a resource file.
SET SAFETY Command | Determines whether Visual FoxPro displays a dialog box before overwriting an existing file, or whether table or field rules, default values, and error messages are evaluated when changes are made in the Table Designer or with ALTER TABLE.
SET SECONDS Command | Specifies whether seconds are displayed in the time portion of a DateTime value.
SET SEPARATOR Command | Specifies the character used to separate each group of three digits to the left of the decimal point in displaying numeric and currency expressions.
SET SKIP Command | Creates a one-to-many relationship among tables.
SET SKIP OF Command | Enables or disables a menu, menu bar, menu title, or menu item for user-defined menus or the Microsoft Visual FoxPro system menu.
SET SPACE Command | Determines whether a space is displayed between fields or expressions when you use the ? or ?? command.
SET SQLBUFFERING Command | Determines whether data in a SQL SELECT statement is based on buffered data or data written to disk.
SET STATUS Command | Displays or removes the character-based status bar.
SET STATUS BAR Command | Displays or removes the graphical status bar.
SET STEP Command | Opens the Trace window and suspends program execution for debugging.
SET STRICTDATE Command | Specifies if ambiguous Date and DateTime constants generate errors.
SET SYSFORMATS Command | Specifies whether Visual FoxPro for Windows system settings are updated with the current Microsoft Windows system settings.
SET SYSMENU Command | Enables or disables the Visual FoxPro system menu bar during program execution, and allows you to reconfigure it.
SET TABLEPROMPT Command | Enables or disables file open dialog from appearing when table cannot be located during execution of a data command such as SELECT - SQL Command.
SET TABLEVALIDATE Command | Specifies the level of table validation to perform.
SET TALK Command | Determines whether Visual FoxPro displays command results.
SET TEXTMERGE Command | Enables or disables the evaluation of fields, variables, array elements, functions, or expressions that are surrounded by text-merge delimiters, and lets you specify text-merge output.
SET TEXTMERGE DELIMITERS Command | Specifies the text-merge delimiters.
SET TOPIC Command | Specifies the Help topic or topics to open when you invoke the Visual FoxPro Help system.
SET TOPIC ID Command | Specifies the Help topic to display when you invoke the Visual FoxPro Help system. The Help topic is based on the topic's context ID.
SET TRBETWEEN Command | Enables or disables tracing between breakpoints in the Trace Window.
SET TYPEAHEAD Command | Specifies the maximum number of characters that can be stored in the type-ahead buffer.
SET UDFPARMS Command | Specifies if Microsoft Visual FoxPro passes parameters to a user-defined function (UDF) by value or by reference.
SET UNIQUE Command | Specifies whether records with duplicate index key values are maintained in an index file.
SET VARCHARMAPPING Command | Controls mapping of Character expressions to Varchar data types in result sets of queries and views.
SET VIEW Command | Opens or closes the Data Session window or restores the Visual FoxPro environment from a view file.
SET VOLUME Command | Maps MS-DOS drive designators (A:, B:, C:, and so on) to volumes or folders in FoxPro for Macintosh.
SET WINDOW of Memo Command | Included for backward compatibility.

See Also

Other Resources

Commands
Commands that Scope to a Data Session


SET ALTERNATE Command

Visual FoxPro 9.0 Language Reference
SET ALTERNATE Command
See Also

Directs screen or printer output created with ?, ??, DISPLAY, or LIST to a text file.

SET ALTERNATE ON | OFF
-or-
SET ALTERNATE TO [FileName [ADDITIVE]]

Parameters

ON

Directs output to the text file.
OFF

(Default) Disables output to the text file.
TO FileName

Creates the text file, which is assigned the default extension .txt unless you include a different extension with the file name. If you use SET ALTERNATE TO without FileName, the last file you created using SET ALTERNATE TO FileName is closed.
ADDITIVE

Appends output to the end of the file specified with FileName. If you omit ADDITIVE, the contents of the file are overwritten.

See Also

Reference

? | ?? Command
DISPLAY Command
LIST Commands

Other Resources

Commands
SET PRINTER Command
ACTIVATE SCREEN Command
SET Command Overview


SET ANSI Command

Visual FoxPro 9.0 Language Reference
SET ANSI Command
See Also Example

Specifies whether to pad a shorter string with spaces when making a SQL string comparison or binary expression with zero (0) bytes when making a binary expression comparison in SQL commands using the equal sign operator (=).

Note:
In the Visual FoxPro OLE DB Provider, you cannot query the value of ANSI using the SET command though SET ANSI is supported.

SET ANSI ON | OFF

Parameters

ON

Pads the shorter string or binary expression with spaces or zero (0) bytes needed, respectively, to make it equal to the length of the longer string or expression. When SET ANSI is set to ON, the two strings or expressions are compared character for character for their entire lengths.
OFF

Specifies that the shorter string not be padded with spaces or binary expression not be padded with zero (0) bytes. (Default) When SET ANSI is set to OFF, the two strings are compared character for character until the end of the shorter string is reached.

Remarks

SET ANSI has no effect on the double equal sign (==) operator. When you use the == operator, the shorter string or binary expression is always padded with spaces or zero (0) bytes, respectively, for the comparison. For more information, see Relational Operators.

SET ANSI is scoped to the current data session.

SET ANSI and the Query Designer Visual FoxPro builds a SELECT - SQL command in the Query Designer when you create a query. When creating Join and Filter conditions, if you choose the Equal or Exactly Like options, the = or == operator is included in the generated SELECT. The SET ANSI setting can affect the results of queries you create and perform in the Query Designer.

String Order In SQL commands, the left-to-right order of the two strings in a comparison is irrelevant — switching a string from one side of the = or == operator to the other doesn't affect the result of the comparison.

Example

In the following example, when SET ANSI is set to ON, the result is False (.F.) because when padded, 'Tom' becomes 'Tom ', and the strings 'Tom ' and 'Tommy' do not match character for character:

Copy Code
'Tommy' = 'Tom'

The == operator uses this method for comparisons in Visual FoxPro SQL commands.

In the following example, when SET ANSI is set to ON, the result is True (.T.) because the comparison stops after 'Tom':

Copy Code
'Tommy' = 'Tom'

See Also

Other Resources

String and Value Comparison in Visual FoxPro
SET EXACT Command
SET Command Overview


SET ASSERTS Command

Visual FoxPro 9.0 Language Reference
SET ASSERTS Command
See Also

Specifies if ASSERT commands are evaluated or ignored.

SET ASSERTS ON | OFF

Parameters

ON

Specifies that Visual FoxPro executes ASSERT commands.
OFF

Specifies that Visual FoxPro ignores ASSERT commands. (Default)

Remarks

If you choose the Ignore All button in the message box following an assert, SETASSERTS is set to OFF.

See Also

Other Resources

Commands
ASSERT Command
Debugging Before Bugs Exist
SET Command Overview


SET AUTOINCERROR Command

Visual FoxPro 9.0 Language Reference
SET AUTOINCERROR Command
See Also

Specifies whether attempts to update or insert values in a field with automatically incrementing values generate errors.

Note:
A cursor inherits the current setting of SET AUTOINCERROR when opened. Changing the value of SET AUTOINCERROR during a session does not change the setting for any cursors already opened. To change the setting of an open cursor, use the CURSORSETPROP( ) function.

SET AUTOINCERROR ON | OFF

Parameters

ON

Generates an error when updating or inserting a value in a field that uses automatically incrementing field values. The ON setting is the default for a global or private data sessions.
OFF

Does not generate an error when updating or inserting a value in a field that uses automatically incrementing field values and disregards the value specified for the field, which uses the appropriate incremented value.

Remarks

The OFF setting provides greater utility when using tables that contain autoincrementing fields with certain language operations such as the APPEND FROM and INSERT INTO commands where you need to otherwise specify a fields list and omit those fields that use autoincrementing from the operation.

SET AUTOINCERROR is scoped to the data session.

See Also

Other Resources

Commands
Autoincrementing Field Values in Tables


SET AUTOSAVE Command

Visual FoxPro 9.0 Language Reference
SET AUTOSAVE Command
See Also

Determines whether Visual FoxPro flushes data buffers to disk when you exit a READ or return to the Command window.

SET AUTOSAVE ON | OFF

Parameters

ON

Specifies that buffers be flushed to disk whenever you exit a READ or return to the Command window.
OFF

Specifies that buffers be flushed to disk only if five minutes have elapsed since the last flush occurred, and only when you exit a READ or return to the Command window. OFF is the default for SET AUTOSAVE.

Remarks

Flushing buffers may reduce the chance of data loss if your computer loses power.

SET AUTOSAVE is scoped to the current data session.

See Also

Other Resources

Commands
FFLUSH( ) Function
FLUSH Command
SET DATASESSION Command
SET Command Overview


SET BELL Command

Visual FoxPro 9.0 Language Reference
SET BELL Command
See Also Example

Turns the computer bell on or off and sets the bell attributes.

SET BELL ON | OFF
-or-
SET BELL TO [cWAVFileName]

Parameters

ON

(Default) Turns the bell on.
OFF

Turns the bell off.
TO cWAVFileName

Specifies a waveform sound to play when the bell is rung. cWAVFileName can include a path to the waveform sound. Issue SET BELL TO without cWAVFileName to restore the default waveform sound.

Remarks

SET BELL enables or disables the sounding of the bell during editing when you reach the end of a field or enter invalid data.

Example

The following example plays the Ding.wav.
Copy Code
SET BELL TO (ADDBS(GETENV('windir')))+"MEDIA\DING.WAV"
?? CHR(7)

See Also

Other Resources

Commands
Sound Player
SET Command


SET BLOCKSIZE Command

Visual FoxPro 9.0 Language Reference
SET BLOCKSIZE Command
See Also

Specifies how Visual FoxPro allocates disk space for the storage of memo fields.

SET BLOCKSIZE TO nBytes

Parameters

nBytes

Specifies the block size in which disk space for memo fields is allocated. If nBytes is 0, disk space is allocated in single bytes (blocks of 1 byte). If nBytes is an integer between 1 and 32, disk space is allocated in blocks of nBytes bytes multiplied by 512. If nBytes is greater than 32, disk space is allocated in blocks of nBytes bytes. If you specify a block size value greater than 32, you can save substantial disk space.

Remarks

The default value for SET BLOCKSIZE is 64. To reset the block size to a different value after the file has been created, set it to a new value and then use COPY to create a new table. The new table has the specified block size.

SET BLOCKSIZE is scoped to the current data session.

See Also

Other Resources

Commands
COPY FILE Command
MODIFY STRUCTURE Command
PACK Command
SET DATASESSION Command
SET Command


SET BROWSEIME Command

Visual FoxPro 9.0 Language Reference
SET BROWSEIME Command
See Also

Specifies if the Input Method Editor is opened when you navigate to a text box in a Browse window.

SET BROWSEIME ON | OFF

Parameters

ON

(Default for Traditional Chinese Windows) Opens the Input Method Editor when you navigate to a text box in a Browse window.
OFF

(Default for Korean Windows) The Input Method Editor isn't opened when you navigate to a text box in a Browse window.

Remarks

SET BROWSEIME corresponds to the Browse IME control check box on the General tab of the Options dialog box.

This command has no effect if you are not working in a double-byte character set (DBCS) environment.

See Also

Other Resources

Commands
How to: Enter International Data
IMEMode Property
IMESTATUS( ) Function
SET Command


SET CARRY Command

Visual FoxPro 9.0 Language Reference
SET CARRY Command
See Also

Determines whether Visual FoxPro carries data forward from the current record to a new record created with INSERT, APPEND, and BROWSE.

SET CARRY ON | OFF
-or-
SET CARRY TO [FieldList [ADDITIVE]]

Parameters

ON

Brings data from all fields in all work areas forward from the current record to a new record.
OFF

(Default) Prevents data from all fields from being passed to a new record.
TO [ FieldList[ADDITIVE]]

FieldList specifies the fields from which data is carried forward. Separate the field names with commas. ADDITIVE specifies that the fields in the field list be added to the current set of fields being carried forward. Issuing SET CARRY TO implicitly performs SET CARRY ON. Use SET CARRY TO without FieldList to restore the default setting (all fields are carried forward).

Remarks

Use SET CARRY to enable data to be carried forward from the current record to a new record or to prevent data from being carried forward. Fields that generally remain unchanged during an editing session can be brought forward for each new record. For example, a field containing the current date can be brought forward for each new record so a new date doesn't have to be entered again. Note that the contents of Memo and General type fields are not carried forward.

Modifying the structure of a table with an active SET CARRY TO <fieldlist> calls an implicit SET CARRY TO. This results in the field list containing all of the fields in the table. If you modify the structure of a table, you must reissue the SET CARRY TO <fieldlist> to reset the field list.

SET CARRY affects only the table open in the currently selected work area.

SET CARRY is scoped to the current data session.

See Also

Other Resources

Commands
INSERT Command
SET DATASESSION Command
APPEND Command
BROWSE Command
SET Command


SET CENTURY Command

Visual FoxPro 9.0 Language Reference
SET CENTURY Command
See Also

Determines whether Microsoft Visual FoxPro displays the century portion of date expressions and how Visual FoxPro interprets dates that specify only 2 digit years.

SET CENTURY ON | OFF | TO [nCentury [ROLLOVER nYear]]

Parameters

ON

Specifies a four-digit year in a format that includes 10 characters (including date delimiters).
Note:
To provide year 2000 compliance, it's recommended that you always set SET CENTURY to ON.

OFF

(Default) Specifies a two-digit year in a format that includes eight characters and assumes the twentieth century for date calculations.
TO nCentury

A number from 1 to 99 that specifies the current century. When a date has a two digit year, nCentury determines in which century the year occurs. The ROLLOVER value determines whether the year is in nCentury or the century following nCentury.
ROLLOVER nYear

A number from 0 to 99 that specifies the year equal to and above which is the current century and below which is the next century. The default value for nYear is the last two digits of the current year plus 50 years - if the current year is 1998, nYear is 48, the last two digits of 2048 (1998 + 50). Note that the rollover value only determines the century for a date entered without a century portion - an ambiguous date format that is not recommended. For example, if the current year is 1998 and nYear is the default (48), any date entered without a century portion and a year of 48 or greater is considered to be in the current century (the 20th century). Any date entered without a century portion but with a year before 48 is considered to be in the next century (the 21st century).

Remarks

Use SET CENTURY to specify how date variables and functions are displayed.

Issue SET CENTURY TO without any additional arguments to restore the default century to the current century and ROLLOVER to the default value of the current year plus 50 years. In Visual FoxPro 5.0, issuing SET CENTURY TO without any additional arguments sets the century to 19 and ROLLOVER to zero.

SET CENTURY is scoped to the current data session. New data sessions are initialized to the default values as specified above, ignoring the value of SET CENTURY for the current data session.

SET CENTURY TO ROLLOVER is available in Visual FoxPro 5.0 and later, and makes it possible for you to control the assumed year for dates used when the setting is SET CENTURY OFF. It also allows for a rollover value since many applications contain dates that span multiple centuries.

Note:
SET CENTURY OFF always implies dates in the 20th century. However, the SET CENTURY TO syntax takes precedence over this setting. So, with Visual FoxPro 5.0 and later, the SET CENTURY ON/OFF setting only controls the number of digits displayed.

The value of SET CENTURY TO is scoped to the current data session.

In Visual FoxPro 5.0, issuing SET CENTURY TO without additional parameters sets the century to the current century –1 and rollover to zero if the two-digit year of the system date is less than 50. Century is set to the current century if the two-digit system date is greater than 50. For example, if the current year were 1998, nYear would be 48, the last two digits of 2048 (1998 + 50).

See Also

Other Resources

Commands
DATE( ) Function
SET DATASESSION Command
SET STRICTDATE Command
SET SYSFORMATS Command
YEAR( ) Function
SET Command


SET CLASSLIB Command

Visual FoxPro 9.0 Language Reference
SET CLASSLIB Command
See Also Example

Opens a .vcx visual class library containing class definitions.

SET CLASSLIB TO ClassLibraryName [IN APPFileName | EXEFileName]
   [ADDITIVE] [ALIAS AliasName]

Parameters

TO ClassLibraryName

Specifies the name of the .vcx visual class library to open. If ClassLibraryName does not include a fully qualified path, Visual FoxPro first searches for the visual class library in the default Visual FoxPro directory, and then in the directories in the Visual FoxPro path. The default Visual FoxPro directory is specified with SET DEFAULT, and the Visual FoxPro search path is specified with SET PATH. Issuing SET CLASSLIB TO without ClassLibraryName closes all open visual class libraries. Use RELEASE CLASSLIB to close an individual visual class library.
IN APPFileName| EXEFileName

Specifies a Visual FoxPro application file (.app) or executable file (.exe) containing the visual class library.
ADDITIVE

Opens the .vcx visual class library without closing any currently open .vcx visual class libraries. If this clause is omitted, all open .vcx visual class libraries are closed.
ALIAS AliasName

Specifies an alias for the visual class library. The visual class library can be referenced by its alias. For example, the following commands open a .vcx visual class library named MyClass, assign it the alias MyCntrls, and then create a control named MyButton.
Copy Code
SET CLASSLIB TO MyClass ALIAS MyCntrls
mMyButton = CREATEOBJ('MyCntrls.MyButton')

Remarks

When CREATEOBJECT( ), ADD OBJECT in DEFINE CLASS, or the AddObject method is issued, Visual FoxPro searches for the class definition defining the object specified in these commands in the following locations and order:

  1. The Visual FoxPro base classes.

  2. Class definitions in memory in the order they are loaded.

  3. Class definitions in the current program.

  4. Class definitions in the .vcx class libraries opened with SET CLASSLIB.

  5. Class definitions in procedure files opened with SET PROCEDURE.

  6. Class definitions in the Visual FoxPro program execution chain.

  7. The OLE Registry if SET OLEOBJECT is set to ON.

If the class definition containing the object cannot be located, Visual FoxPro generates an error message.

Example

The following example uses CREATE CLASSLIB to create a visual class library named myclslib. A class named myform based on the Visual FoxPro Form base class is created and is stored in the myclslib visual class library. SET CLASSLIB is used to open the myclslib visual class library so that classes within it can be used.
Copy Code
CREATE CLASSLIB myclslib     && Creates a new .VCX visual class library
CREATE CLASS myform OF myclslib AS "Form"  && Creates new class
SET CLASSLIB TO myclslib ADDITIVE     && Opens MyClsLib.VCX

See Also

Other Resources

Commands
ADD CLASS Command
AddObject Method
CREATE CLASS Command
CREATE CLASSLIB Command
CREATEOBJECT( ) Function
MODIFY CLASS Command
RELEASE CLASSLIB Command
SET PROCEDURE Command
SET OLEOBJECT Command
SET Command


SET CLOCK Command

Visual FoxPro 9.0 Language Reference
SET CLOCK Command
See Also

Determines whether Visual FoxPro displays the system clock and specifies the clock location on the main Visual FoxPro window.

SET CLOCK ON | OFF | STATUS
-or-
SET CLOCK TO [nRow, nColumn]

Parameters

ON

Displays the clock in the upper-right corner of the main Visual FoxPro window.
OFF

(Default) Removes the clock from the status bar or from the main Visual FoxPro window.
STATUS

Displays the clock in the graphical status bar. Issue SET STATUS BAR ON to display the graphical status bar.
TO [ nRow, nColumn]

Using row and column coordinates, specifies where the clock is displayed in the main Visual FoxPro window. Use SET CLOCK TO without the coordinates to display the clock in its default position in the upper-right corner of the main Visual FoxPro window. If you place the clock in the graphical status bar with SET CLOCK STATUS and you specify a location in the main Visual FoxPro window with TO nRow, nColumn, Visual FoxPro removes the clock from the graphical status bar and places it at the location you specify.

See Also

Other Resources

Commands
SET BRSTATUS Command
SET HOURS Command
SET STATUS Command
SET Command


SET COLLATE Command

Visual FoxPro 9.0 Language Reference
SET COLLATE Command
See Also

Specifies a collation sequence for character fields in subsequent indexing and sorting operations.

SET COLLATE TO cSequenceName

Parameters

cSequenceName

Specifies a collation sequence. The following table lists collation sequence options that are available.

cSequenceName Language

ARABIC

Arabic

CZECH

Czech

DUTCH

Dutch

GENERAL

English, French, German, Modern Spanish, Portuguese, and other Western European languages

GERMAN

German phone book order (DIN)

GREEK

Greek

HEBREW

Hebrew

HUNGARY

Hungarian

ICELAND

Iceland

JAPANESE

Japanese

KOREAN

Korean

MACHINE

Machine (the default collation sequence for earlier FoxPro versions)

NORDAN

Norwegian, Danish

PINYIN

Simplified Chinese

POLISH

Polish

RUSSIAN

Russian

SLOVAK

Slovak

SPANISH

Traditional Spanish

STROKE

Simplified and traditional Chinese

SWEFIN

Swedish, Finnish

THAI

Thai

TURKISH

Turkish

UNIQWT

Unique Weight
Note:
When you specify the SPANISH option, "ch" is a single letter that sorts between "c" and "d", and "ll" sorts between "l" and "m". If you specify a collation sequence option as a literal character string, be sure to enclose the option in quotation marks:

Copy Code
SET COLLATE TO "SWEFIN"
MACHINE is the default collation sequence option and is the sequence FoxPro users are familiar with. Characters are ordered as they appear in the current code page. The MACHINE collation sequence provides the best performance. Using a collating sequence other than MACHINE may reduce performance primarily in comparison and indexing operations, and may create larger index files. GENERAL might be preferable for U.S. and Western European users. Characters are ordered as they appear in the current code page. In FoxPro versions earlier than 2.5, you might have used UPPER( ) or LOWER( ) on character fields when you created indexes. In FoxPro versions later than 2.5, you can specify the GENERAL collation sequence option and omit the UPPER( ) conversion instead. If you specify a collation sequence option other than MACHINE, and if you create an .idx file, a compact .idx is always created. Use SET("COLLATE") to return the current collation sequence. If you include the following line in your Visual FoxPro configuration file, a collation sequence is specified when you start Visual FoxPro:
Copy Code
COLLATE = cSequenceName
This is identical to issuing the following command:
Copy Code
SET COLLATE TO cSequenceName

Remarks

SET COLLATE allows you to order tables containing accented characters for any of the supported languages. Changing the setting of SET COLLATE doesn't affect the collating sequence of previously opened indexes. Visual FoxPro automatically maintains existing indexes, providing the flexibility to create many different types of indexes, even for the same field.

For example, if an index is created with SET COLLATE set to GENERAL, and the SET COLLATE setting is later changed to SPANISH, the index retains the GENERAL collation sequence.

SET COLLATE is scoped to the current data session.

When using the SET COLLATE TO command, you may receive the error "Collating sequence <sequencename> is not found." This occurs when you attempt to use a collating sequence that is not supported by the current code page. To prevent this error, you must specify a compatible code page in your Visual FoxPro configuration file. For instance, you may see the error "Collating sequence 'CZECH' is not found" when issuing the command SET COLLATE TO 'CZECH'. To enable support for the Czech collating sequence, add the following line to your config.fpw file and restart Visual FoxPro:

Copy Code
CODEPAGE = 1250

For additional information on code pages and Visual FoxPro's international support, see Code Pages Supported by Visual FoxPro in Developing International Applications.

For more information on configuring Visual FoxPro, see Customizing the Visual FoxPro Environment and Special Terms for Configuration Files.

See Also

Other Resources

Commands
IDXCOLLATE( ) Function
SET DATASESSION Command
Code Pages Supported by Visual FoxPro
Special Terms for Configuration Files
SYS(2300) - Add or Remove Code Page
CREATE TABLE - SQL Command
ALTER TABLE - SQL Command
INDEX Command
SET Command


SET COLOR OF SCHEME Command

Visual FoxPro 9.0 Language Reference
SET COLOR OF SCHEME Command
See Also

Specifies the colors of a color scheme or copies one color scheme to another color scheme.

SET COLOR OF SCHEME nScheme1 TO   [SCHEME nScheme2 | ColorPairList]

Parameters

nScheme1

Specifies the number of the color scheme you want to change. This can be a value from 1 through 24.
Note:
In Visual FoxPro, color schemes 13 through 15 are reserved for internal use. Do not use these color schemes.

TO [SCHEME nScheme2]

Specifies the number of a color scheme to which color scheme nScheme1 is changed.
TO [ ColorPairList]

Specifies up to 10 color pairs you would like to change in your color scheme. You can selectively change colors in a color scheme by including a comma for each color pair that you don't want to change. For example, to change the third color pair in color scheme 1 to bright white and blue and leave the rest of the color settings unchanged, use this command:
Copy Code
SET COLOR OF SCHEME 1 TO , , W+/B*
A color pair can also be specified with a set of six RGB (red, green, and blue) color values separated by commas. To change the third color pair in color scheme 1 to bright white and blue and leave the rest of the color settings unchanged, you can use this command:
Copy Code
SET COLOR OF SCHEME 1 TO , , RGB(255,255,255,0,0,255)

Remarks

Not all interface elements can be controlled by color schemes — system windows, such as the View and Command windows, the system menu bar, and so on are always controlled by the Control Panel color settings. Issuing SET COLOR OF SCHEME nScheme1 TO without including an optional clause restores the colors from the current color scheme.

See Also

Other Resources

Commands
CREATE COLOR SET Command
SET COLOR SET Command
SET Command


SET COLOR SET Command

Visual FoxPro 9.0 Language Reference
SET COLOR SET Command
See Also

Loads a previously defined color set.

SET COLOR SET TO [ColorSetName]

Parameters

ColorSetName

Specifies the color set to load.

Remarks

You can create color sets with SET COLOR OF SCHEME and save them with CREATE COLOR SET.

If you issue SET COLOR SET without an optional clause, the current color set remains loaded.

See Also

Other Resources

Commands
CREATE COLOR SET Command
SET COLOR OF SCHEME Command
SET Command


SET COMPATIBLE Command

Visual FoxPro 9.0 Language Reference
SET COMPATIBLE Command
See Also

Controls compatibility with Microsoft FoxBASE+ and other FoxPro languages.

SET COMPATIBLE FOXPLUS | OFF | DB4 | ON [PROMPT | NOPROMPT]

Parameters

FOXPLUS | OFF

(Default) These two keywords can be used interchangeably. Each allows programs created in FoxBASE+ to run in Microsoft Visual FoxPro without changes.
DB4 | ON

These two keywords can be used interchangeably. Including either keyword affects the behavior of the commands and functions listed below.
PROMPT | NOPROMPT

These options determine whether Visual FoxPro displays a dialog box when you open a dBASE table containing a memo field. Include the PROMPT option to display the Convert Memos dialog box. If you open a dBASE IV table containing a memo field, Visual FoxPro by default displays the Convert Memos dialog box, which enables you to convert the dBASE memo file to a Visual FoxPro format. You must convert the memo file to a Visual FoxPro format to open the table in Visual FoxPro. If you include NOPROMPT, the Convert Memos dialog box is not displayed when you open a dBASE IV table containing a memo field. The dBASE memo file is automatically converted to a Visual FoxPro format.

Remarks

Commands and functions affected by SET COMPATIBLE include LIKE( ), PLAY MACRO, SELECT( ), and STORE (when STORE is used with arrays).

SET COMPATIBLE does not create compatibility with other commands, functions, or features not supported in Visual FoxPro. For example, it does not make it possible for you to open a report form created in other products with the Report Designer.

The following table lists the commands affected by SET COMPATIBLE.

Commands

@ ... GET with a RANGE clause | PLAY MACRO
@ ... SAY with CHR(7) | READ with an @ ... GET VALID clause
@ ... SAY scrolling | Nested READs
@ ... SAY when STATUS is ON | READ
ACTIVATE SCREEN | RUN | !
ACTIVATE WINDOW | SET COLOR TO
APPEND MEMO | SET BORDER
BROWSE | SET FIELDS
DECLARE | SET MESSAGE
DIMENSION | SET MEMOWIDTH
GO | GOTO with SET TALK ON | SET PRINTER to <file>
FSIZE( ) | STORE
INKEY( ) | SUM
LASTKEY( ) | TRANSFORM( ) with a numeric PICTURE clause
LIKE( ) | SELECT( )
Menu commands | SYS(2001, "COLOR")

See Also

Other Resources

SET KEYCOMP Command
Backward-Compatible Language Elements
SET Command Overview
Commands
Language Reference


SET CONFIRM Command

Visual FoxPro 9.0 Language Reference
SET CONFIRM Command
See Also

Specifies whether the user can exit a text box by typing past the last character in the text box.

SET CONFIRM ON | OFF

Parameters

ON

Specifies that the user cannot exit a text box by typing past the last character in the text box. To exit the text box, the user can press ENTER, TAB, or any of the arrow keys to move from a text box to another control. SET CONFIRM ON also affects menu items and menu titles created with DEFINE BAR and DEFINE PAD. If the user types the first letter of the menu item or menu title, the item or title is selected but is not chosen. To choose the menu item or title when it is selected, the user should press ENTER or the SPACEBAR.
OFF

Specifies that the user can exit a text box by typing past the last character in the text box. The insertion point, when it reaches the last character in a text box, moves to the next control, and the bell is sounded (if SET BELL is set to ON). OFF is the default value of SET CONFIRM. SET CONFIRM OFF also affects menu items and menu titles. If SET CONFIRM is set to OFF, the user can choose an item from a menu or a menu title in a menu bar by pressing the key corresponding to the first letter of the menu item or title. (When SET CONFIRM is set to ON, this action only selects the menu item or title.)

Remarks

SET CONFIRM has no effect on access keys for menu items and menu titles. If a menu item or menu title is created with an access key, the menu item or title can be chosen by pressing the corresponding access key.

You can create text boxes using the Form Designer.

SET CONFIRM is scoped to the current data session.

See Also

Other Resources

TextBox Control
SET DATASESSION Command
SET Command Overview
Form Designer
Commands
Language Reference


SET CONSOLE Command

Visual FoxPro 9.0 Language Reference
SET CONSOLE Command
See Also

Enables or disables output to the main Visual FoxPro window or to the active user-defined window from within programs.

SET CONSOLE ON | OFF

Parameters

ON

Sends all output to the main Visual FoxPro window or to the active user-defined window. (Default)
OFF

Suppresses output to the main Visual FoxPro window or to the active user-defined window.

Remarks

SET CONSOLE is set to ON when you are using Visual FoxPro interactively, and it cannot be changed to OFF from the Command window. You can change the setting to OFF only from within a program.

SET CONSOLE affects some interactive Visual FoxPro dialog boxes. For example, if SET CONSOLE is set to OFF and you issue BROWSE when no table is open, Visual FoxPro displays an error message. If SET CONSOLE is set to ON in the same circumstances, Visual FoxPro displays the Open dialog box.

SET CONSOLE does not affect output from @ ... SAY. Output from @ ... SAY is controlled by the SET DEVICE setting.

Note:
An error always sets SET CONSOLE to ON.

See Also

Other Resources

SET Command Overview
Commands


SET COVERAGE Command

Visual FoxPro 9.0 Language Reference
SET COVERAGE Command
See Also

Turns code coverage on or off, or specifies a text file to which code coverage information is directed.

SET COVERAGE TO [FileName [ADDITIVE]]

Parameters

TO FileName

Specifies the name of a text file to which code coverage information is directed. Issue SET COVERAGE TO without a file name to close the text file. If the file you specify does not exist, Visual FoxPro automatically creates and opens it.
ADDITIVE

Appends the code coverage information to the end of the text file specified with FileName. If you omit ADDITIVE, the code coverage information replaces the contents of the text file.

Remarks

You can use SET COVERAGE at design time and at runtime in Visual FoxPro 9.0. Coverage.app, the Coverage Profile application included with Visual FoxPro, cannot be included with your distributed runtime applications. See Distributable and Restricted Visual FoxPro Features and Files for more information about files and applications that can be included with your Visual FoxPro distributed applications.

For more information about code coverage options, see Coverage Dialog Box. For more information about the Visual FoxPro Coverage Profiler, see Coverage Profiler Application.

See Also

Other Resources

_COVERAGE System Variable
SET EVENTTRACKING Command
SET Command Overview
How to: Log Code Coverage
Commands
Language Reference


SET CPCOMPILE Command

Visual FoxPro 9.0 Language Reference
SET CPCOMPILE Command
See Also

Specifies the code page for compiled programs.

SET CPCOMPILE TO [nCodePage]

Parameters

nCodePage

Specifies the compilation code page with nCodePage. For additional information on code pages and Visual FoxPro's international support, see Code Pages Supported by Visual FoxPro in Developing International Applications. Issue SET CPCOMPILE TO without nCodePage to reset the compilation code page to the current code page. Use CPCURRENT( ) to determine the current code page.

Remarks

Use SET CPCOMPILE to compile programs for a specific code page. The code page you specify with SET CPCOMPILE is used for programs compiled automatically by Visual FoxPro, programs compiled from the Compile dialog, and programs compiled with the COMPILE command. However, you can include the AS clause in the COMPILE command to override the code page you specify with SET CPCOMPILE.

See Also

Other Resources

COMPILE Command
CPCURRENT( ) Function
SET Command Overview
Code Pages Supported by Visual FoxPro
Commands
Language Reference


SET CPDIALOG Command

Visual FoxPro 9.0 Language Reference
SET CPDIALOG Command
See Also

Specifies whether the Code Page dialog box is displayed when a table is opened.

SET CPDIALOG ON | OFF

Parameters

ON

(Default) Displays the Code Page dialog box when you open a table and the following conditions are true:
  • The table is opened exclusively.

  • The table is not marked with a code page.

OFF

Does not display the Code Page dialog box when a table is opened.

Remarks

The Code Page dialog box makes it possible for you to specify a code page for tables created in earlier FoxPro versions and other products that create Visual FoxPro tables. The table is marked with the code page you choose.

When creating an application, issue SET CPDIALOG ON to ensure that the tables included in your application are marked with the proper code page. In your completed application, be sure that SET CPDIALOG is OFF.

You can also interactively specify whether the Code Page dialog box is displayed with the Prompt for Code Page check box in the Data tab of the Options dialog box. The Options dialog box is displayed by choosing Options from the Tools menu.

Note:
For additional information on code pages and Visual FoxPro's international support, see Code Pages Supported by Visual FoxPro in Developing International Applications.

See Also

Other Resources

CPCURRENT( ) Function
CPCONVERT( ) Function
CPDBF( ) Function
GETCP( ) Function
USE Command
SET Command Overview
Commands
Language Reference


SET CURRENCY Command

Visual FoxPro 9.0 Language Reference
SET CURRENCY Command
See Also Example

Defines the currency symbol and specifies its position in the display of numeric, currency, float, and double expressions.

SET CURRENCY TO [cCurrencySymbol]
-or-
SET CURRENCY LEFT | RIGHT

Parameters

cCurrencySymbol

Specifies a character string representing the currency symbol; can be one to nine characters long. Issue SET CURRENCY TO without cCurrencySymbol to reset the currency symbol to the default dollar sign ($). You can also specify a currency symbol using Alt+nnn. Specify the Euro currency symbol () with Alt+0128 if you have installed supporting Windows fonts. You also can set the default currency symbol in the Regional tab of the Options dialog box.
LEFT

(Default) Positions the currency symbol to the left of the currency value.
RIGHT

Positions the currency symbol to the right of the currency value.

Remarks

The currency symbol is displayed in output created with @ ... SAY and in text boxes created with @ ... GET when the $ code is included in the FUNCTION or PICTURE clause.

SET CURRENCY is scoped to the current data session.

Example

The following example displays the DM currency symbol on either side of the currency value. If you use PICTURE to display the currency symbol, be sure to include @ before the dollar sign.
Copy Code
STORE SET('CURRENCY') TO gcCurrPosit
STORE 1234.56 TO gnDollarAmnt
CLEAR
SET CURRENCY TO 'DM'
@ 2,2 SAY gnDollarAmnt PICTURE '@$99,999.99'
IF gcCurrPosit = 'LEFT'
   SET CURRENCY RIGHT
ELSE
   SET CURRENCY LEFT
ENDIF
@ 4,2 SAY gnDollarAmnt FUNCTION '$99,999.99'

See Also

Other Resources

SET DATASESSION Command
SET DECIMALS Command
SET SEPARATOR Command
SET SYSFORMATS Command
SET Command Overview
Commands
Language Reference


SET CURSOR Command

Visual FoxPro 9.0 Language Reference
SET CURSOR Command
See Also

Determines whether the insertion point is displayed when Visual FoxPro waits for input.

SET CURSOR ON | OFF

Parameters

ON

(Default) Causes the insertion point to be displayed during a pending @ ... GET, @ ... EDIT, WAIT, or INKEY( ).
OFF

Prevents the insertion point from being displayed during a pending @ ... GET, @ ... EDIT, WAIT, or INKEY( ).

Remarks

SET CURSOR, similar to SYS(2002), enables you to turn the insertion point on or off.

See Also

Other Resources

INKEY( ) Function
SET( ) Function
SYS(2002) – Turn Insertion Point On or Off
WAIT Command
SET Command Overview
Commands
Language Reference


SET DATABASE Command

Visual FoxPro 9.0 Language Reference
SET DATABASE Command
See Also Example

Sets an open database as the current database or sets no current database.

SET DATABASE TO [DatabaseName]

Parameters

[ DatabaseName]

Specifies the name of an open database to set as the current database. Omitting DatabaseName or specifying an empty string sets the current database to no database.

Remarks

SET DATABASE is scoped to the current data session. Though you can have many databases open at the same time, you can set only one as the current database. Commands and functions that operate on a database operate on the current database.

For more information, see How to: Set the Current Database and How to: Open Databases.

Example

The following example creates two databases named mydbc1 and mydbc2, and a table named table1. SET DATABASE is used to make mydbc1 the current database, and table1 is added to mydbc1 when it is created. The table is then closed and removed from mydbc1. SET DATABASE is used to make mydbc1 the current database, and ADD TABLE is then used to add the table to mydbc2. RENAME TABLE is used to change the name of the table from table1 to table2.
Copy Code
CREATE DATABASE mydbc1
CREATE DATABASE mydbc2
SET DATABASE TO mydbc1
CREATE TABLE table1 (cField1 C(10), n N(10))  && Adds table to mydbc1
CLOSE TABLES
REMOVE TABLE table1
SET DATABASE TO mydbc2
ADD TABLE table1
RENAME TABLE table1 TO table2

For more information, see CREATE DATABASE Command, CREATE TABLE - SQL Command, CLOSE DATABASES Command, REMOVE TABLE Command, ADD TABLE Command, and RENAME TABLE Command.

See Also

Other Resources

DELETE DATABASE Command
MODIFY DATABASE Command
SET DATASESSION Command
SET Command Overview
Commands
Language Reference


SET DATASESSION Command

Visual FoxPro 9.0 Language Reference
SET DATASESSION Command
See Also

Activates the specified form's data session.

SET DATASESSION TO [nDataSessionNumber]

Parameters

nDataSessionNumber

Specifies a form's data session to activate. If you omit nDataSessionNumber, data session 1 (the Global data session) is activated.

Remarks

By default, data session 1, the Global data session, is active when you start Visual FoxPro.

A form's DataSession property determines whether the form has its own unique data session when the form is created. If a form's DataSession property is set to 2, the form has its own data session; otherwise, a data session is not created for the form. You can use the form's read-only DataSessionId property to determine the form's data session number.

A data session is closed when the form that created the data session is released.

SET DATASESSION typically is used to debug forms. Care should be taken when issuing this command when a form is active, because tables in non-current datasessions are not accessible.

The following SET commands scope to the current data session:

SET Commands

SET ANSI | SET AUTOSAVE
SET BLOCKSIZE | SET CARRY
SET CENTURY | SET COLLATE
SET CONFIRM | SET CURRENCY
SET DATABASE | SET DATE
SET DECIMALS | SET DELETED
SET DELIMITERS | SET EXACT
SET EXCLUSIVE | SET FIELDS
SET FIXED | SET HOURS
SET LOCK | SET MARK TO
SET MEMOWIDTH | SET MULTILOCKS
SET NEAR | SET NULL
SET POINT | SET REPROCESS
SET SAFETY | SET SECONDS
SET SEPARATOR | SET SYSFORMATS
SET TALK | SET UNIQUE

See Also

Other Resources

AUSED( ) Function
CREATE FORM Command
DataSession Property
DataSessionId Property
SET Command Overview
Commands that Scope to a Data Session
Commands
Language Reference


SET DATE Command

Visual FoxPro 9.0 Language Reference
SET DATE Command
See Also

Specifies the format for the display of Date and DateTime expressions.

SET DATE [TO] AMERICAN | ANSI | BRITISH | FRENCH | GERMAN | ITALIAN
 | JAPAN | TAIWAN | USA | MDY | DMY | YMD| SHORT | LONG

Remarks

Here are the settings and the resulting date formats:

Setting | Format
AMERICAN | mm/dd/yy
ANSI | yy.mm.dd
BRITISH/FRENCH | dd/mm/yy
GERMAN | dd.mm.yy
ITALIAN | dd-mm-yy
JAPAN | yy/mm/dd
TAIWAN | yy/mm/dd
USA | mm-dd-yy
MDY | mm/dd/yy
DMY | dd/mm/yy
YMD | yy/mm/dd
SHORT | Short date format determined by the Windows Control Panel short date setting.
LONG | Long date format determined by the Windows Control Panel long date setting.
Note:
When SET DATE is set to SHORT or LONG, a date before {^1601-01-01} is invalid and generates an error.

The default date setting is AMERICAN.

The SET DATE setting also determines how the date appears in datetime expressions.

If DATE is set to SHORT or LONG, the SET CENTURY, SET MARK, SET HOURS, and SET SECONDS settings are ignored.

SET DATE is scoped to the current data session.

See Also

Other Resources

DATE( ) Function
DATETIME( ) Function
SET CENTURY Command
SET DATASESSION Command
SET MARK TO Command
SET SYSFORMATS Command
SET Command Overview
Commands
Language Reference


SET DEBUGOUT Command

Visual FoxPro 9.0 Language Reference
SET DEBUGOUT Command
See Also

Directs debugging output to a file.

SET DEBUGOUT TO [FileName [ADDITIVE]]

Parameters

FileName

Specifies the name of the file to which debugging output is directed. If the file you specify does not exist, it is automatically created. If the file you specify already exists, its contents are overwritten unless you include the ADDITIVE clause. Issue SET DEBUGOUT TO to stop direction of debugging output to the file and close the file.
ADDITIVE

Specifies that debugging output is appended to the end of the file specified with FileName.

Remarks

Debugging output that is directed to the file includes ASSERT messages, output from the DEBUGOUT command, and events that are specified with SET EVENTLIST or in the Event Tracking Dialog Box. See the Event Tracking dialog box topic for more information about specifying events to track interactively.

See Also

Other Resources

ASSERT Command
DEBUG Command
DEBUGOUT Command
SET EVENTLIST Command
SET EVENTTRACKING Command
SET Command Overview
Commands
Language Reference


SET DECIMALS Command

Visual FoxPro 9.0 Language Reference
SET DECIMALS Command
See Also

Specifies the number of decimal places displayed in numeric expressions.

SET DECIMALS TO [nDecimalPlaces]

Parameters

nDecimalPlaces

Specifies the minimum number of decimal places to display. The default is two decimal places. The maximum number of decimal places is 18; the minimum is zero.

Remarks

SET DECIMALS specifies the minimum number of decimal places used to display the results of division, multiplication, and trigonometric and financial functions.

SET DECIMALS is scoped to the current data session.

See Also

Other Resources

SET DATASESSION Command
SET FIXED Command
SET SYSFORMATS Command
SET Command Overview
Commands
Language Reference


SET DEFAULT Command

Visual FoxPro 9.0 Language Reference
SET DEFAULT Command
See Also

Specifies the default drive and directory.

SET DEFAULT TO [cPath]

Parameters

cPath

Specifies one of the following:
  • A drive designator

  • A drive designator with a directory name

  • A child directory name

  • Any of the above using Microsoft MS-DOS shorthand notation ( \ or ..)

Remarks

SET DEFAULT changes the default directory to the directory you specify.

Microsoft® Visual FoxPro® searches for a file in the default Visual FoxPro directory. The default directory is the one from which you start Visual FoxPro. However, you can specify a different default directory in your Visual FoxPro configuration file or in a startup program. If Visual FoxPro cannot find a file in the default directory, it then searches the Visual FoxPro path if one has been specified. Use SET PATH to specify the Visual FoxPro path.

If you create a file and do not specify where to place it, the file is placed in the default Visual FoxPro directory.

The SET DEFAULT command is not supported in either single or multithreaded DLL servers. This command changes the default directory of the entire process, so all threads which are part of the process are affected. Use the SET PATH command in DLL servers, in place of CD and CHDIR.

Tip:
SYS(5) returns the default drive. SYS(2003) returns the default directory with no drive designator. SYS(5) + SYS(2003) returns the default drive and the directory.

You can change the default drive to drive A using either of the following commands:

Copy Code
SET DEFAULT TO A
SET DEFAULT TO A:

You can specify a specific directory:

Copy Code
SET DEFAULT TO A:\sales
SET DEFAULT TO C:\sales\data

You can specify a child directory. If the root directory on drive C is the default Visual FoxPro directory, issue the following command to change the default directory to C:\Sales:

Copy Code
SET DEFAULT TO sales

You can use MS-DOS shorthand notation. If the current directory is C:\Sales\Data, issue the following command to make the root directory the default directory:

Copy Code
SET DEFAULT TO \

You can also move the default directory one directory toward the root directory with the following command:

Copy Code
SET DEFAULT TO ..

See Also

Other Resources

CD | CHDIR Command
MD | MKDIR Command
RD | RMDIR Command
SET PATH Command
SET Command Overview
SYS(5) – Default Drive
SYS(2003) – Current Directory
Commands
Language Reference


SET DELETED Command

Visual FoxPro 9.0 Language Reference
SET DELETED Command
See Also

Specifies whether Visual FoxPro processes records marked for deletion and whether they are available for use with other commands.

SET DELETED ON | OFF

Parameters

ON

Specifies that commands that operate on records, including records in related tables, using a scope ignore records that are marked for deletion.
OFF

Specifies that commands that operate on records, including records in related tables, using a scope can access records marked for deletion. (Default)
Note:
Calling SQL SELECT with SET DELETED OFF includes records fitting the specified criteria in the result set and sets those records as available for processing. That is, SET DELETED OFF is not set for the records in the result set.

Remarks

Queries that use DELETED( ) to test the status of records can be optimized using Rushmore Query Optimization technology if the table is indexed on DELETED( ).

For more information on optimizing queries, see Using Rushmore Query Optimization to Speed Data Access.

You can mark records for deletion by issuing DELETE – SQL or DELETE, or by choosing Delete Records... from the Table menu from within a Browse or Edit window.

You can recall records by issuing RECALL or by choosing Recall Records... from the Table menu from within a Browse or Edit window.

Note:
SET DELETED is ignored if the default scope for the command is the current record or if you include a scope of a single record. The exception exists with the SEEK command, in which case, SET DELETED is always respected. INDEX and REINDEX always ignore SET DELETED and index all records in the table.

SET DELETED is scoped to the current data session.

See Also

Other Resources

DELETE Command
DELETE – SQL Command
DELETED( ) Function
PACK Command
RECALL Command
SET DATASESSION Command
SET Command Overview
Commands
Language Reference


SET DEVELOPMENT Command

Visual FoxPro 9.0 Language Reference
SET DEVELOPMENT Command
See Also

Causes Visual FoxPro to compare the creation date and time of a program with those of its compiled object file when the program is run.

SET DEVELOPMENT ON | OFF

Parameters

ON

(Default) Specifies that Visual FoxPro recompile the source program before it executes if it is more current than its compiled object program. This option ensures that the most current version of a program is executed.
OFF

Specifies that Visual FoxPro not compare the source and compiled versions of the program. If SET DEVELOPMENT is set to OFF, you might not always be executing the most current version of a program.

Remarks

SET DEVELOPMENT needs to be set to ON when programs are modified outside of Visual FoxPro. Using an external editor may require you to issue CLEAR PROGRAM before you execute the modified program. For more information, see CLEAR PROGRAM. Use SET DEVELOPMENT OFF for optimum performance.

SET DEVELOPMENT also determines whether the Trace window is opened when an error occurs within a Form that is running. If SET DEVELOPMENT is ON, the Trace window is opened with the program line that caused the error selected. If SET DEVELOPMENT is OFF, the Trace window is not opened when an error occurs in a Form.

See Also

Other Resources

COMPILE Command
MODIFY COMMAND Command
MODIFY FILE Command
SET Command Overview
Commands
Language Reference


SET DEVICE Command

Visual FoxPro 9.0 Language Reference
SET DEVICE Command
See Also

Directs output from @ ... SAY to the screen, a printer, or a file.

SET DEVICE TO SCREEN | TO PRINTER [PROMPT] | TO FILE FileName

Parameters

TO SCREEN

Directs @ ... SAY output to the main Visual FoxPro window or to the active user-defined window.
TO PRINTER [PROMPT]

Directs @ ... SAY output to the printer. A page eject is issued when the coordinates in @ ... SAY specify a location on the page higher than the location specified by the coordinates in the previous @ ... SAY. You can include the optional PROMPT clause to display a dialog box before printing starts. In this dialog box, the user can adjust printer settings, including the number of copies to print and page numbers. The currently installed printer driver determines which printer settings the user can adjust. Place PROMPT immediately after TO PRINTER.
TO FILE FileName

Specifies a file to which @ ... SAY sends output.

Remarks

@ ... SAY output can be sent to the main Visual FoxPro window, the active user-defined window, the printer, or a file.

See Also

Other Resources

SYS(101) – Device Setting
@ ... SAY Command
PROMPT( ) Function
SET Command Overview
Commands
Language Reference


SET ECHO Command

Visual FoxPro 9.0 Language Reference
SET ECHO Command
See Also

Opens the Trace window for program debugging. Included for backward compatibility.

SET ECHO ON | OFF

Parameters

ON

Displays the source code for the program that is executing in the Trace window. The line currently executing is highlighted.
OFF

(Default) Closes the Trace window in FoxPro versions earlier than 2.0. From within a program, the Trace window can be closed with DEACTIVATE WINDOW TRACE.

Remarks

You can also use the Trace window to set breakpoints, which suspend program execution.

For more information about the Trace window, see Trace Window.

See Also

Other Resources

RESUME Command
SET STEP Command
SUSPEND Command
SET Command Overview
Commands
How to: Use the Debugger


SET ENGINEBEHAVIOR Command

Visual FoxPro 9.0 Language Reference
SET ENGINEBEHAVIOR Command
See Also

Enables SQL data engine compatibility with Visual FoxPro 7.0, 8.0, and 9.0.

SET ENGINEBEHAVIOR 70 | 80 | 90

Parameters

70

Specifies that Visual FoxPro treat SQL commands with behavior as in versions prior to Visual FoxPro 8.0.
80

Specifies that Visual FoxPro treat SQL commands with behavior as in Visual FoxPro 8.0. The following table describes behavior for the SQL SELECT statement.

SQL SELECT clause Behavior

DISTINCT

You cannot use the DISTINCT clause with Memo or General fields. Instead, wrap a Memo field inside a function such as PADR( ) or ALLTRIM( ).

For more information, see PADL( ) | PADR( ) | PADC( ) Functions and ALLTRIM( ) Function.

UNION

The UNION clause does not support Memo fields unless the ALL clause is included in the SQL SELECT statement.

GROUP BY

The GROUP BY clause must list every field in the SELECT list except for fields contained in an aggregate function, such as the COUNT( ) function. In addition, the GROUP BY clause must also list every field in a HAVING clause except for fields contained in an aggregate function.

For example, the following code raises an error because the field company is not listed in the GROUP BY clause.

Copy Code
SELECT company, country FROM Customer GROUP BY country

You can include an aggregate function in the SELECT list without having it in the GROUP BY clause.

For example, the following code uses the COUNT( ) function on the field company without having the field company in the GROUP BY clause.

SELECT COUNT(company), country FROM Customer GROUP BY country

HAVING

A SQL SELECT statement can contain the HAVING clause without the GROUP BY clause as long as the SQL SELECT statement does not contain any aggregate functions.

For example, the following code filters query results by specifying the country field must equal "Sweden".

Copy Code
SELECT customerid FROM customers HAVING country="Sweden"

LIKE

SQL SELECT statements do not automatically remove trailing spaces from values compared with the LIKE operation. In versions prior to Visual FoxPro 8.0, both values in the LIKE operation were trimmed from the right prior to evaluation.

For example, the following code assumes that you have a table named table1, and the table has three rows that contain values of "1.", "12 ", and "123", respectively.

Copy Code
SELECT * FROM table1 WHERE column1 LIKE "1__"

Visual FoxPro 7.0 and earlier returns one row with the value of "123". Visual FoxPro 8.0 returns three rows with the values, "1 ", "12 ", and "123".

If the beginning of the filter condition matches the pattern of the expression in the LIKE operation, and the rest of the filter condition contains trailing spaces, the LIKE operation ignores the trailing spaces and returns True (.T.). Trailing spaces in the pattern are not ignored.
90

Specifies that Visual FoxPro treat SQL commands with standard Visual FoxPro 9.0 behavior. (Default) The following table describes behavior for the SQL SELECT statement.

SQL SELECT clause Behavior

TOP nExpr

When this setting is enabled, including the TOP nExpr[PERCENT] clause in the SQL SELECT command returns no more than nExpr[PERCENT] records. In addition, the SQL engine uses available memory more efficiently and speeds evaluation for the TOP clause without the PERCENT keyword when working with large result sets, low memory conditions, or both.

GROUP BY

When using aggregate functions, such as MAX( ), in the SQL SELECT command without a GROUP BY clause, and no matching records are found, Visual FoxPro returns a result set with a single record and _TALLY set to 1. In versions prior to Visual FoxPro 9.0, no records are returned, and _TALLY is set to 0.

ORDER BY

A SELECT … DISTINCT … ORDER BY command will generate an error if the specified ORDER BY field is not in the SELECT field list.

Copy Code
CREATE CURSOR foo (f1 int, f2 int)
SELECT DISTINCT f1 FROM foo ORDER BY f2 INTO CURSOR res

HAVING

A SELECT … DISTINCT … HAVING command will generate an error if the specified HAVING field is not in the SELECT field list.

Copy Code
CREATE CURSOR foo (f1 int, f2 int)
SELECT DISTINCT f1 from foo HAVING f2>1 INTO CURSOR res

Remarks

The scope of SET ENGINEBEHAVIOR is global.

Using SET ENGINEBEHAVIOR set to 70 might lead to ambiguous results from SQL SELECT commands when the DISTINCT and UNION clauses are used with memos and the GROUP BY clause, the HAVING clause without a GROUP BY clause, and when using the LIKE clause.

When SET ENGINEBEHAVIOR is set to 70 or 80, results from the TOP clause in the SQL SELECT command can include more than nExpr records when rows with identical values for columns specified by the ORDER BY clause exist. For example, suppose you specified 10 rows for nExpr. If more than 10 rows with identical values exist in the columns specified in the ORDER BY clause, the query result might contain more than 10 rows.

See Also

Other Resources

SET Command Overview
SELECT - SQL Command
SYS(3099) - SQL Data Engine Compatibility Mode


SET ESCAPE Command

Visual FoxPro 9.0 Language Reference
SET ESCAPE Command
See Also

Determines whether pressing the ESC key interrupts program and command execution.

SET ESCAPE ON | OFF

Parameters

ON

(Default) Allows command and program execution to be interrupted when the user presses ESC. If the user presses ESC during the execution of a command or program while the insertion point is in the Command window, the following message appears:
Copy Code
*** INTERRUPTED ***
If the user presses ESC during command or program execution, processing completes at the current program line, and an alert appears with the following three options:
  • (Default) Choose Cancel to immediately stop program execution and return to the Command window.

  • Choose Suspend to pause program execution and return to the Command window. This option is useful for debugging a program. Choosing Resume from the Program menu or issuing RESUME in the Command window restarts the program at the line at which it was paused.

  • Choose Ignore to continue program execution at the line at which it was paused.

OFF

Prevents command and program execution from being interrupted when the user presses ESC.

See Also

Other Resources

ON ESCAPE Command
ON KEY LABEL Command
RESUME Command
SET Command Overview
Commands
Language Reference


SET EVENTLIST Command

Visual FoxPro 9.0 Language Reference
SET EVENTLIST Command
See Also

Specifies events to track in the Debug Output Window or in a file specified with SET EVENTTRACKING.

SET EVENTLIST TO [EventName1 [, EventName2 ...] [ADDITIVE]]

Parameters

EventName1[, EventName2...]

Specifies the names of the events to track. You can include any number of event names separated by commas.
ADDITIVE

Specifies that the events EventName1, EventName2 ... are added to the set of events currently being tracked. If ADDITIVE is omitted, only the events EventName1, EventName2 ... are tracked.

Remarks

Issue SET EVENTLIST TO without any event names to remove all events from the set of events being tracked. You can also specify events to track in the Event Tracking dialog box.

See Also

Other Resources

SET DEBUGOUT Command
SET EVENTTRACKING Command
SET Command Overview
Commands
Language Reference


SET EVENTTRACKING Command

Visual FoxPro 9.0 Language Reference
SET EVENTTRACKING Command
See Also

Turns event tracking on or off or specifies a text file to which event tracking information is directed.

SET EVENTTRACKING ON | OFF | PROMPT | TO [FileName [ADDITIVE]]

Parameters

ON

Turns event tracking on and directs event tracking information to the text file specified with FileName.
OFF

Turns event tracking off and stops directing event tracking information to the text file.
PROMPT

Displays the Event Tracking dialog box, allowing the user to specify which events are tracked.
TO FileName

Specifies the name of a text file to which event tracking information is directed. SET EVENTTRACKING must be ON to direct event tracking information to a text file. Issue SET EVENTTRACKING TO without a file name to close the text file. If the file you specify doesn't exist, Microsoft Visual FoxPro automatically creates and opens it.
ADDITIVE

Appends the event tracking information to the end of the text file specified with FileName. If you omit ADDITIVE, the event tracking information replaces the contents of the text file.

Remarks

Use SET EVENTLIST or the Event Tracking dialog box to specify the events that are tracked.

Starting with Visual FoxPro 7, the event log format differs from earlier versions. The new format adds a timestamp (to allow for profiling) to the event information already displayed in each line.

See Also

Other Resources

SET COVERAGE Command
SET Command Overview
Commands
Language Reference


SET EXACT Command

Visual FoxPro 9.0 Language Reference
SET EXACT Command
See Also

Specifies rules that Visual FoxPro uses when comparing two strings of different lengths.

Note:
Unlike SET ANSI, SET EXACT does not apply to Visual FoxPro SQL commands. For more information, see SET ANSI Command.

SET EXACT ON | OFF

Parameters

ON

Specifies that expressions must match character for character when comparing character data, or byte for byte when comparing binary data, to be equivalent.
Note:
To match the length of the longer expression, the shorter of the two expressions is padded to the right with spaces or zero (0) bytes. However, any trailing spaces or zero bytes in the expressions are disregarded in the comparison.

OFF

Specifies that expressions must match character for character when comparing character data, or byte for byte when comparing binary data, until the end of the expression on the right side is reached to be equivalent. (Default)

Remarks

If both strings are the same length, SET EXACT has no effect.

SET EXACT is scoped to the current data session.

See Also

Other Resources

String and Value Comparison in Visual FoxPro
SET ANSI Command
SET Command Overview
= Command
Commands
Language Reference


SET EXCLUSIVE Command

Visual FoxPro 9.0 Language Reference
SET EXCLUSIVE Command
See Also

Specifies whether Visual FoxPro opens table files for exclusive or shared use on a network.

SET EXCLUSIVE ON | OFF

Parameters

ON

(The default for the global data session.) Limits accessibility of a table opened on a network to the user who opened it. The table isn't accessible to other users on the network. Unlike FLOCK( ), SET EXCLUSIVE ON also prevents all other users from having read-only access. A file can also be opened on a network for exclusive use by including the EXCLUSIVE clause with the USE command. It isn't necessary to perform record or file locking on a table opened for exclusive use. Opening a table for exclusive use ensures that the file can't be changed by other users. For some commands, execution isn't possible until a table is opened for exclusive use. These commands are INSERT, INSERT BLANK, MODIFY STRUCTURE, PACK, REINDEX, and ZAP.
OFF

(The default for a private data session.) Allows a table opened on a network to be shared and modified by any user on the network. For additional information about record and file locking and sharing tables on a network, see Programming for Shared Access.

Remarks

Changing the setting of SET EXCLUSIVE doesn't change the status of previously opened tables. For example, if a table is opened with SET EXCLUSIVE set to ON, and SET EXCLUSIVE is later changed to OFF, the table retains its exclusive-use status.

SET EXCLUSIVE is scoped to the current data session.

See Also

Other Resources

FLOCK( ) Function
RLOCK( ) Function
SET DATASESSION Command
USE Command
SET Command Overview
Commands
Language Reference


SET FDOW Command

Visual FoxPro 9.0 Language Reference
SET FDOW Command
See Also Example

Specifies the first day of the week.

SET FDOW TO [nExpression]

Parameters

nExpression

Specifies the first day of the week. The following table lists the values nExpression can assume and the corresponding first day of the week.

Nexpression Day of the week

1

Sunday

2

Monday

3

Tuesday

4

Wednesday

5

Thursday

6

Friday

7

Saturday
If you omit nExpression, the first day of the week is reset to Sunday (1).

Remarks

The first day of the week can also be set with the Week Starts On list box in the Regional tab of the Options dialog.

Example

Copy Code
STORE SET('FDOW') TO gnFdow  && Save current value
SET FDOW TO 1  && Sets first day of the week to Sunday, the default
SET FDOW TO 7  && Sets first day of the week to Saturday
SET FDOW TO &gnFdow  && Restore original day

See Also

Other Resources

CDOW( ) Function
DAY( ) Function
DOW( ) Function
SET FWEEK Command
SYS( ) Functions Overview
WEEK( ) Function
SET Command Overview
Commands
Language Reference


SET FIELDS Command

Visual FoxPro 9.0 Language Reference
SET FIELDS Command
See Also

Specifies which fields in a table can be accessed. There are two versions of the syntax.

SET FIELDS ON | OFF | LOCAL | GLOBAL
SET FIELDS TO [[FieldName1 [, FieldName2 ...]]
    | ALL [LIKE Skeleton | EXCEPT Skeleton]]

Parameters

ON

Specifies that only the fields in the field list can be accessed.
OFF

(Default) Specifies that all the fields in the current table can be accessed.
LOCAL

Specifies that only the fields in the current work area listed in the fields list can be accessed.
GLOBAL

Specifies that all fields in the field list, including fields in other work areas, can be accessed. SET FIELDS GLOBAL lets you access fields in other work areas without issuing SET COMPATIBLE TO DB4.
TO [ FieldName1[, FieldName2...]]

Specifies the names of fields that can be accessed in the current table. You must include an alias with the field name in the following cases:
  • When the field is in a table that is open in a work area other than the currently selected work area.

  • When the field names are the same in two or more tables.

You can include fields from tables that are open in other work areas if the fields are prefaced with their table aliases. However, these fields cannot be accessed unless you issue SET FIELDS GLOBAL or SET COMPATIBLE DB4. The field list can contain statements for creating calculated fields. A calculated field contains read-only data created with an expression. This expression can take any form, but it must be a valid FoxPro expression. Calculated fields cannot be accessed unless you issue SET FIELDS GLOBAL or SET COMPATIBLE DB4. The format of the statement you use to create a calculated field is:
Copy Code
<calculated field name> = <expr>
This example creates a calculated field called LOCATION:
Copy Code
CLOSE DATABASES
USE customer
SET FIELDS TO LOCATION = ALLTRIM(city) + ', ' + state
CITY and STATE are the names of fields from the selected table.
ALL

Allows access to all the fields in the current table.
ALL LIKE Skeleton| EXCEPT Skeleton

You can selectively access fields by including the LIKE or EXCEPT clause or both. If you include LIKE Skeleton, you can access fields that match Skeleton. If you include EXCEPT Skeleton, you can access all fields except those that match Skeleton. The skeleton Skeleton supports wildcards such as * and ?. For example, to access fields that begin with the letters A and P, issue the following:
Copy Code
SET FIELDS TO ALL LIKE A*,P*
The LIKE clause can be combined with the EXCEPT clause:
Copy Code
SET FIELDS TO ALL LIKE A*,P* EXCEPT PARTNO*

Remarks

SET FIELDS TO is additive — issuing SET FIELDS TO with a field list adds the specified fields to those that are currently accessible.

Issuing SET FIELDS TO implicitly performs SET FIELDS ON. Issue SET FIELDS TO without including either a field list or ALL to remove all fields from the field list for the current table.

SET FIELDS is scoped to the current data session.

See Also

Other Resources

SET FILTER Command
SET DATASESSION Command
SET COMPATIBLE Command
SET Command Overview
Commands
Language Reference


SET FILTER Command

Visual FoxPro 9.0 Language Reference
SET FILTER Command
See Also

Specifies a condition that records in the current table must meet to be accessible.

SET FILTER TO [lExpression] [IN nWorkArea | cTableAlias]

Parameters

lExpression

Specifies the condition that records must satisfy. If the current table is indexed on a field or fields specified in lExpression, Rushmore Query Optimization technology can optimize queries based on the field or fields.
IN nWorkArea| cTableAlias

Specifies the work area or table alias affected by the SET FILTER command. Use this clause to specify a work area or a table outside the current work area.

Remarks

Once SET FILTER is issued, only the records that satisfy the condition specified by the logical expression lExpression are available in the table. All commands that access the table respect the SET FILTER condition. A separate filter can be set for every open table.

The condition specified by SET FILTER isn't evaluated until the record pointer is moved in the table.

Issuing SET FILTER TO without lExpression turns off the filter for the current table.

SELECT – SQL does not respect the current filter condition.

Note:
When using SET FILTER to filter data in a grid, use the SET KEY command to increase grid performance.

See Also

Other Resources

FILTER( ) Function
SELECT – SQL Command
SET Command Overview
How to: Create and Use Table Aliases
Commands
Language Reference


SET FIXED Command

Visual FoxPro 9.0 Language Reference
SET FIXED Command
See Also

Specifies if the number of decimal places used in the display of numeric data is fixed.

SET FIXED ON | OFF

Parameters

ON

Uses the SET DECIMALS setting to determine the number of decimal places displayed in results. The default number of decimal places is 2.
OFF

(Default) Allows the number of decimal places displayed in results to depend on the specific constants, variables, and operators used in a numeric expression. The contents of fields are displayed with the declared number of decimal places.

Remarks

SET FIXED is scoped to the current data session.

See Also

Other Resources

SET DECIMALS Command
SET DATASESSION Command
SET Command Overview
Numeric Data Type
Commands
Language Reference


SET FULLPATH Command

Visual FoxPro 9.0 Language Reference
SET FULLPATH Command
See Also

Specifies if CDX( ), DBF( ), MDX( ), and NDX( ) return the path in a file name.

SET FULLPATH ON | OFF

Parameters

ON

(Default) Specifies that CDX( ), DBF( ), MDX( ), and NDX( ) return the drive designator, path, and file name.
OFF

Specifies that only the drive designator and file name are returned.

See Also

Other Resources

CDX( ) Function
DBF( ) Function
MDX( ) Function
NDX( ) Function
SET Command Overview
Commands
Language Reference


SET FUNCTION Command

Visual FoxPro 9.0 Language Reference
SET FUNCTION Command
See Also

Assigns an expression (keyboard macro) to a function key or key combination.

SET FUNCTION nFunctionKeyNumber | KeyLabelName TO [eExpression]

Parameters

nFunctionKeyNumber

Specifies the number of the function key assigned to the macro. For example, use SET FUNCTION 2 to specify the F2 function key.
KeyLabelName

Specifies a key combination, including a function key, to which to assign the macro. Visual FoxPro supports key combinations that include function keys. You can use the CTRL or SHIFT key in combination with a function key to create additional programmable keys. For a list of key label expressions, see ON KEY LABEL.
TO [ eExpression]

Specifies the series of keystrokes stored to the function key or key combination. Visual FoxPro interprets a semicolon (;) in the expression as a carriage return. Function key definitions can be cleared with CLEAR MACROS.

See Also

Other Resources

CLEAR MACROS Command
FKLABEL( ) Function
FKMAX( ) Function
ON KEY LABEL Command
SET Command Overview
Commands
Language Reference


SET FWEEK Command

Visual FoxPro 9.0 Language Reference
SET FWEEK Command
See Also Example

Specifies the requirements for the first week of the year.

SET FWEEK TO [nExpression]

Parameters

nExpression

Specifies a value, which determines the requirements for the first week of the year. The following table lists the values nExpression can assume and the corresponding requirements for the first week of the year:

nExpression First week requirement

1

(Default) The first week contains January 1st.

2

The larger half (four days) of the first week is in the current year.

3

The first week has seven days.
If you omit nExpression, the first week of the year is reset to 1 (the first week contains January 1st).

Remarks

The first week of the year can also be set with the First Week of Year list box in the Regional tab of the Options dialog.

Example

Copy Code
STORE SET('FWEEK') TO gnFweek  && Save current value
SET FWEEK TO 1  && First week contains January 1st
SET FWEEK TO 3  && First week has seven days
SET FWEEK TO &gnFweek  && Restore original setting

See Also

Other Resources

CDOW( ) Function
DAY( ) Function
DOW( ) Function
SET FDOW Command
SYS( ) Functions Overview
WEEK( ) Function
SET Command Overview
Commands
Language Reference


SET HEADINGS Command

Visual FoxPro 9.0 Language Reference
SET HEADINGS Command
See Also

Determines whether column headings are displayed for fields and whether file information is included when TYPE is issued to display the contents of a file.

SET HEADINGS ON | OFF

Parameters

ON

(Default) Specifies that the field names are displayed. If TYPE is issued to display the contents of a file, Visual FoxPro inserts a form feed, the path and name of the file, and the date at the beginning of the displayed output.
OFF

Specifies that the field names are not displayed. If TYPE is issued to display the contents of a file, Visual FoxPro does not insert additional information about the file at the beginning of the displayed output.

Remarks

SET HEADINGS specifies whether a field name appears as a column heading above each field in the output of AVERAGE, CALCULATE, DISPLAY, LIST, and SUM.

See Also

Other Resources

AVERAGE Command
CALCULATE Command
DISPLAY Command
LIST Command
SUM Command
TYPE Command
SET Command Overview
Commands
Language Reference


SET HELP Command

Visual FoxPro 9.0 Language Reference
SET HELP Command
See Also

Enables or disables the Microsoft Visual FoxPro Help file or specifies another Help file. There are two versions of the syntax.

SET HELP ON | OFF
SET HELP [TO [FileName]] [COLLECTION [cCollectionURL]] [SYSTEM]

Parameters

ON

Displays the Help window when you press F1 or issue HELP in the Command window. (Default)
OFF

Makes Visual FoxPro online Help unavailable.
TO [ FileName]

Specifies a Help file that is displayed when you press F1 or issue HELP. You can specify a .dbf-style Help file, a WinHelp (.hlp) file, or an HTML (.chm) help file. Beginning with Visual FoxPro 7.0, if you issue SET HELP TO without including a file name, Visual FoxPro looks for the default help file.
COLLECTION [ cCollectionURL]

Specifies the name of an HTML Help collection to be used as Help source.
SYSTEM

Specifies that a collection name is used as the Help source.

Remarks

You can use SET HELP to provide a tailored online Help file within a custom application or to switch between the different Help files in Visual FoxPro.

The Visual FoxPro Help file, dv_FoxHelp.chm, is installed by default with the Visual FoxPro product. If you perform a complete installation of the Microsoft Developer's Network (MSDN) library, or if you perform a custom installation of the MSDN library and you specify to install the Visual FoxPro documentation, the Visual FoxPro Help file is installed.

The following table describes the registry values for Help settings:

Setting | Registry key | Registry value
SET HELP ON | OFF | HelpOn | 0 or 1
SET HELP TO cfilename | HelpTo | cFileName
SET HELP COLLECTION cCollectionURL | HelpCollection | cCollectionURL
SET HELP SYSTEM | HelpSystem | 0 or 1

You can also use the Help File option on the File Locations tab of the Options dialog box to interactively specify a Help file.

See Also

Other Resources

Commands
HELP Command
SET TOPIC Command
SET Command Overview
Language Reference


SET HOURS Command

Visual FoxPro 9.0 Language Reference
SET HOURS Command
See Also

Sets the system clock to a 12- or 24-hour time format.

SET HOURS TO [12 | 24]

Parameters

TO 12

(Default) Specifies a 12-hour format.
TO 24

Specifies a 24-hour format.

Remarks

Use SET HOURS TO without 12 or 24 to return to the default 12-hour format.

TIME( ) always returns a value in 24-hour format and isn't affected by SET HOURS. The value returned by DATETIME( ) is determined by the current SET HOURS setting.

SET HOURS is scoped to the current data session.

See Also

Other Resources

DATETIME( ) Function
SECONDS( ) Function
SET CLOCK Command
SET SYSFORMATS Command
TIME( ) Function
SET Command Overview
Commands
Language Reference


SET INDEX Command

Visual FoxPro 9.0 Language Reference
SET INDEX Command
See Also

Opens one or more index files for use with the current table.

SET INDEX TO [IndexFileList | ? ] [ORDER nIndexNumber
 | IDXIndexFileName | [TAG] TagName [OF CDXFileName] [ASCENDING
 | DESCENDING]] [ADDITIVE]

Parameters

IndexFileList

Specifies one or more index files to open. Use commas to separate multiple index files in the list. The index file list can contain any combination of .idx and .cdx index file names; you don't have to include the file name extensions unless another .idx or .cdx file exists with the same name. The first index file in the index file list becomes the controlling index file, which controls how records are accessed and displayed. The records are displayed and accessed in physical record order if the first index file is a .cdx file and SET ORDER TO TAG has not been issued.
?

Displays the Open dialog box from which you can open a single .idx file.
ORDER nIndexNumber

Specifies a controlling index file or tag. The numeric expression nIndexNumber specifies the index files as they appear in the index file list. .Idx files are numbered first in the order in which they appear in the index file list. Tags in the structural .cdx file (if one exists) are numbered in the order in which the tags were created. Finally, tags in any independent .cdx files are numbered in the order in which they were created. See SET ORDER for a further discussion of the numbering of index files and tags. If nIndexNumber is 0, records in the table are displayed and accessed in physical record order, but the index files remain open. ORDER 0 enables you to update open index files while accessing records in physical order. ORDER with no additional arguments is identical to ORDER 0. Visual FoxPro generates an error message if nIndexNumber is greater than the number of .idx files and .cdx file tags.
ORDER IDXIndexFileName

Specifies an .idx file as the controlling index file.
ORDER [TAG] TagName[OF CDXFileName]

Specifies a tag (TagName) of a .cdx file to be the controlling tag. The tag name can be from the structural .cdx file or any open independent .cdx file. If tags with the same name exist in open independent .cdx files, use OF CDXFileName to specify the .cdx file the tag is in.
ASCENDING | DESCENDING

Specifies whether table records are displayed and accessed in ascending or descending order. The index files or tags aren't changed in any way; only the order in which the records are displayed and accessed is changed. Include the ASCENDING or DESCENDING clause immediately after the ORDER clause.
ADDITIVE

Specifies that previously opened index files, except for a structural compound index, are left open when you issue SET INDEX to open an additional index file or files for a table. Without ADDITIVE, the previously opened files would be closed.

Remarks

Records in a table that has an index file or files open can be displayed and accessed in an order determined by one of the index files. Both single index (.idx) and compound (.cdx) index files can be opened with SET INDEX. If a table has a structural .cdx file, the file is opened automatically when the table is opened.

Only one .idx file (the controlling index file) or tag from a .cdx file (the controlling tag) controls the order in which records in the table are displayed or accessed. Certain commands (SEEK, for example) use the controlling index file or tag to search for records.

Issuing SET INDEX TO without additional arguments closes all open index files (except a structural .cdx file) in the current work area.

See Also

Other Resources

CLOSE INDEXES Command
INDEX Command
SET ORDER Command
USE Command
SET Command Overview
Commands
Language Reference


SET KEY Command

Visual FoxPro 9.0 Language Reference
SET KEY Command
See Also

Specifies access to a range of records based on their index keys.

SET KEY TO [eExpression1 | RANGE eExpression2 [, eExpression3]]
   [IN cTableAlias | nWorkArea]

Parameters

eExpression1

Allows access to a set of records with identical index keys. eExpression1 is a single index key value. All records with index keys that match eExpression1 are accessible.
RANGE eExpression2[, eExpression3]

Allows access to a set of records with index keys that fall within a range of index key values. eExpression2 allows access to records with index keys equal to or greater than eExpression2. eExpression3 (preceded by a comma) allows access to records with index keys equal to or less than eExpression3. Including both eExpression2 and eExpression3 (separated by a comma) allows access to records with index keys equal to or greater than eExpression2 and equal to or less than the eExpression3. For example, the CUSTOMER table includes a character field containing postal codes. If the table is indexed on the postal code field, you can specify a range of postal codes with SET KEY. In the following example, only records with postal codes falling within the range of 40000 to 43999 appear in a Browse window:
Copy Code
CLOSE DATABASES
USE customer
SET ORDER TO postalcode
SET KEY TO RANGE '40000', '43999'
BROWSE
IN cTableAlias| nWorkArea

Allows access to a range of records for a table open in a specific work area. cTableAlias specifies the work area alias and nWorkArea specifies the work area number. If no table has the alias you specify, Visual FoxPro generates an error message. If you omit the work area alias and number, SET KEY operates on the table in the currently selected work area.

Remarks

Use SET KEY to limit the range of records you can access in a table. The table must be indexed, and the index key value or values you include must be the same data type as the index expression of the master index file or master tag.

Issue SET KEY TO without any additional arguments to restore access to all records in the table.

See Also

Other Resources

INDEX Command
KEY( ) Function
SET FILTER Command
SET Command Overview
Commands
Language Reference


SET KEYCOMP Command

Visual FoxPro 9.0 Language Reference
SET KEYCOMP Command
See Also

Controls Visual FoxPro keystroke navigation.

SET KEYCOMP TO DOS | WINDOWS

Remarks

SET KEYCOMP determines the keystrokes and keystroke combinations you use to move through the Visual FoxPro interface by accessing controls such as buttons, list boxes, menus, and so on. The effect of SET KEYCOMP depends on the control.

Use SET KEYCOMP when you want to use keystrokes that are familiar to you.

To navigate in Microsoft Windows using MS-DOS keystrokes, issue the following:

Copy Code
SET KEYCOMP TO DOS

You can specify the DOS or WINDOWS (default) option.

You can specify a startup SET KEYCOMP setting in your Visual FoxPro configuration file, Config.fpw. For example, the following line, when placed in your configuration file, has the effect of SET KEYCOMP TO DOS:

Copy Code
KEYCOMP = DOS

This section describes how the DOS and WINDOWS options affect Visual FoxPro.

Default buttons |
DOS | The default button in a dialog box has the focus; its appearance does not change. It is chosen when you press CTRL+ENTER.
WINDOWS | The default button in a dialog box can change appearance when you move among controls. It can be dimmed, or it has the focus (is surrounded by a bold border) to indicate it is the current default. It is chosen when you press ENTER. Pressing ENTER always performs the default button's action.

For an illustration of how the default button changes appearance in a dialog box, issue SET KEYCOMP TO WINDOWS, choose Open from the File menu, and then press TAB to move through the Open dialog box.

Access keys |
DOS | An access key for a control is a single key. If you aren't in a control that has keyboard steering (a combo box or a list box), you can press the access key to choose it.
WINDOWS | An access key for a control can be a single key or a key combination. If the current control has keyboard steering (a combo box or a list box), you can press ALT plus the access key to choose the control. To choose other controls, you can press the access key or ALT plus the access key.

Combo boxes |
DOS | When a combo box has the focus, you can open it by pressing ENTER or the SPACEBAR. Keyboard steering within a combo box is not available until the combo box is open.
WINDOWS | When a combo box has the focus, you can open it by pressing the SPACEBAR, ALT+UP ARROW, or ALT+DOWN ARROW. Keyboard steering within a combo box is available when the combo box has the focus, and when it is open. For example, a selected combo box contains a list of available drives. If drives A, B, and C are available and drive B is currently displayed, you can choose drive C without opening the combo box by pressing C or the DOWN ARROW key. Drive C is chosen and you move to the next control.

Option buttons |
DOS | Press the TAB key when a group of option buttons is selected to move among the option buttons.
WINDOWS | Press the TAB key when a group of option buttons is selected to move from the option buttons to the next control. To move among a set of option buttons, press the UP ARROW and DOWN ARROW keys.

Browse window |
DOS | A field is not selected upon entry into the field.
WINDOWS | A field is automatically selected upon entry into the field.

See Also

Other Resources

SET COMPATIBLE Command
SET Command Overview
Automating Keystroke Tasks with Macros
Commands
Language Reference


SET LIBRARY Command

Visual FoxPro 9.0 Language Reference
SET LIBRARY Command
See Also

Opens an external API (application programming interface) library file.

SET LIBRARY TO [FileName [ADDITIVE]]

Parameters

FileName

Specifies the file name of the API library or procedure file to open. Visual FoxPro assume an .fll extension for libraries. If the library has an .fll extension, you don't have to include the extension with the file name. If a library has an extension other than .fll, you must include the extension with the file name.
Caution:
When using SET LIBRARY, be aware of the following:

  • You cannot use API libraries built for one platform on another platform. For example, libraries created for FoxPro for MS-DOS cannot be used in Visual FoxPro; libraries created for Visual FoxPro cannot be used in FoxPro for MS-DOS.

  • You cannot use API libraries built for one version on another version. For example, you cannot use libraries built for FoxPro version 2.6 in Visual FoxPro. You must recompile and link.

Visual FoxPro assumes a .prg extension for a procedure file. When you execute a procedure with DO ProcedureName, Visual FoxPro searches for the procedure in the following files in this order:
  • The file containing DO ProcedureName.

  • A procedure file opened with SET PROCEDURE (if one is set).

  • The programs in the execution chain. Visual FoxPro searches program files beginning with the most recently executed program and continuing back to the first executed program.

  • A procedure file opened with SET LIBRARY (if one is set).

  • A stand-alone program file. If Visual FoxPro finds a program file with the same name as the file name specified with DO, the program is executed. If it doesn't find a matching program file name, Visual FoxPro generates an error message.

ADDITIVE

Opens additional API libraries. Include ADDITIVE after the file name in successive SET LIBRARY commands. Visual FoxPro ignores ADDITIVE when you use SET LIBRARY to open a procedure file.

Remarks

Use SET LIBRARY to open external Application Program Interface (API) libraries or a procedure file.

API routine libraries extend the capabilities of the Visual FoxPro language and user interface. Once an external API library is opened, you can use the API functions as if they were Visual FoxPro functions. Use DISPLAY STATUS or LIST STATUS to display the library's available functions.

You can use existing API libraries or create your own API libraries.

In Visual FoxPro, the preferred way to register functions in shared libraries is to use the DECLARE - DLL command.

To remove all API libraries from memory, use SET LIBRARY TO without including FileName or ADDITIVE. To remove an individual library from memory, use RELEASE LIBRARY LibraryName.

If you specify a procedure file, the procedures within the procedure file are made available to all programs and are also available interactively through the Command window.

Note:
The ability of Visual FoxPro to open a procedure file with SET LIBRARY provides compatibility with dBASE IV. Using SET LIBRARY to open a procedure file will close all open API libraries. Using SET LIBRARY to open API libraries will close a procedure file opened with SET LIBRARY. Use SET PROCEDURE to open a procedure file and prevent API libraries from being closed.

For additional information about procedure files, see PROCEDURE and SET PROCEDURE.

See Also

Other Resources

CALL Command
DISPLAY STATUS Command
LIST Command
LOAD Command
RELEASE LIBRARY Command
SET Command Overview
Commands
Language Reference


SET LOCK Command

Visual FoxPro 9.0 Language Reference
SET LOCK Command
See Also

Enables or disables automatic file locking in certain commands.

SET LOCK ON | OFF

Parameters

ON

Specifies that the commands listed below automatically lock the table when they execute. This provides read-only access to other users on the network and ensures that you are using the most current data.
OFF

(Default) Enables shared access of tables with commands listed below. Use SET LOCK OFF if you don't need the most current information from a table.

Remarks

Visual FoxPro doesn't place a lock on a file when executing commands that require read-only access to a table. These commands include the following:

Commands |
AVERAGE | JOIN (both files)
CALCULATE | LIST
COPY TO | LABEL
COPY TO ARRAY | REPORT
COUNT | SORT
DISPLAY (with a scope) | SUM
INDEX | TOTAL

While they are executed, these commands don't change the contents of a table, and access to the table is available to other users on the network. Thus, the table can be changed while you are executing one of these commands. For example, you might begin printing a report by using REPORT before another user changes a record included in the report. Your report now contains outdated information.

SET LOCK is scoped to the current data session.

See Also

Other Resources

FLOCK( ) Function
LOCK( ) Function
RLOCK( ) Function
SET DATASESSION Command
SET MULTILOCKS Command
SET Command Overview
Commands
Language Reference


SET LOGERRORS Command

Visual FoxPro 9.0 Language Reference
SET LOGERRORS Command
See Also

Determine whether to send Visual FoxPro compilation error messages to a text file.

You can use SET LOGERRORSto save compilation error messages to a text file when compiling programs.

SET LOGERRORS ON | OFF

Parameters

ON

Specifies to create a compilation error (.err) file using the same name as the compiled program. (Default) If an .err file with the same name exists, it is overwritten.
OFF

Specifies not to create a compilation error (.err) file when compiling a program.

Remarks

Note:
If the program compiles without error and an .err file exists with the same name as the compiled program, the .err file is deleted.

See Also

Other Resources

How to: View and Save Build Messages
COMPILE Command
SET Command Overview
SYS(2018) - Error Message Parameter
Commands
Language Reference


SET MACKEY Command

Visual FoxPro 9.0 Language Reference
SET MACKEY Command
See Also

Specifies a key or key combination that displays the Macro Key Definition dialog box.

SET MACKEY TO [KeyLabelName]

Parameters

KeyLabelName

Specifies the key or key combination that displays the Macro Key Definition dialog box. See ON KEY LABEL for the key labels to use.

Remarks

Use SET MACKEY to change the default key combination for displaying the Macro Key Definition dialog box. Choose Macros from the Tools menu to display this dialog box.

See Also

Other Resources

CLEAR Command
ON KEY LABEL Command
PLAY MACRO Command
RESTORE MACROS Command
SAVE MACROS Command
SET Command Overview
Commands
Language Reference


SET MARGIN Command

Visual FoxPro 9.0 Language Reference
SET MARGIN Command
See Also

Sets the left printer margin and affects all output directed to the printer.

SET MARGIN TO nColumns

Parameters

nColumns

Specifies the left margin in columns. The default is 0 columns; the maximum is 256.

Remarks

If you use SET MARGIN to adjust the left margin, the value specified with SET MARGIN is stored to the system variable _PLOFFSET. You can also set the left margin by storing a value directly to _PLOFFSET. The value of the system variable _LMARGIN also affects the left margin setting.

Note:
The left margin setting specified in SET MARGIN does not affect reports created with the Report Designer or Label Designer and then run with a REPORT FORM or LABEL command. The Left Margin setting in the Report Page Setup dialog box in the Report Designer determines the offset from the left edge of the paper. For more information, see Report Page Setup Dialog Box and Page Layout Tab, Report Properties Dialog Box (Report Builder).

See Also

Other Resources

_LMARGIN System Variable
_PLOFFSET System Variable
_RMARGIN System Variable
SET Command Overview
Commands
Language Reference


SET MARK OF Command

Visual FoxPro 9.0 Language Reference
SET MARK OF Command
See Also

Displays or clears the mark character for menu titles or menu items. There are several versions of the syntax.

SET MARK OF MENU MenuBarName TO lExpression1
SET MARK OF POPUP MenuName1 TO lExpression2
SET MARK OF BAR nMenuItemNumber OF MenuName2 TO lExpression3

Parameters

MENU MenuBarName TO lExpression1

Specifies the name of the menu bar for which to display or clear the mark character. The lExpression1 parameter specifies a logical expression to evaluate in order to determine whether to display or clear the mark character for every menu title on the menu bar. If lExpression1 evaluates to True (.T.), the mark character displays next to every menu title. If lExpression1 evaluates to False (.F.), the mark character is cleared from every menu name.
POPUP MenuName1TO lExpression2

Specifies the name of the menu for which to display or clear the mark character. The lExpression2 parameter specifies a logical expression to evaluate in order to determine whether to display or clear the mark characters for all menu items. If lExpression2 evaluates to True (.T.), the mark characters are displayed. If lExpression2 evaluates to False (.F.), the mark characters are cleared.
BAR nMenuItemNumberOF MenuName2TO lExpression3

Specifies the number of the menu item and the name of the menu containing the menu item for which to display or clear the mark character. The lExpression3 parameter specifies a logical expression to evaluate in order to determine whether to display or clear the mark character for the menu item. If lExpression3 evaluates to True (.T.), the mark character is displayed. If lExpression3 evaluates to False (.F.), the mark character is cleared.

Remarks

The mark character is always a check mark. You cannot specify a mark character for menu titles or menu items.

You cannot mark menu items created with any of the PROMPT clauses, such as FIELD, FILES, or STRUCTURE, for the DEFINE POPUP command.

To determine if a menu title has a mark character displayed, use MRKPAD( ). For more information, MRKBAR( ) Function. To determine if a menu item has a mark character displayed, use MRKBAR( ). For more information, see MRKPAD( ) Function.

For an example using SET MARK OF, see CNTBAR( ).

See Also

Other Resources

CNTPAD( ) Function
DEFINE BAR Command
DEFINE MENU Command
DEFINE PAD Command
SET Command Overview
Commands
Language Reference


SET MARK TO Command

Visual FoxPro 9.0 Language Reference
SET MARK TO Command
See Also

Specifies a delimiter for the display of date expressions.

SET MARK TO [cDelimiter]

Parameters

cDelimiter

Specifies the character you want to use as the date delimiter.

Remarks

SET MARK TO specifies the character that separates the month, day, and year in displayed dates.

Use SET MARK TO without cDelimiter to reset the delimiter to the default forward slash ( / ).

SET MARK TO is scoped to the current data session.

See Also

Other Resources

SET DATASESSION Command
SET DATE Command
SET SYSFORMATS Command
SET Command Overview
Commands
Language Reference


SET MEMOWIDTH Command

Visual FoxPro 9.0 Language Reference
SET MEMOWIDTH Command
See Also

Specifies the displayed width of memo fields and character expressions.

SET MEMOWIDTH TO nColumns

Parameters

nColumns

Specifies a width between 8 and 8192 columns. The default width for output is 50 columns. If you issue SET COMPATIBLE ON or SET COMPATIBLE DB4, the default width is changed to 80 columns. If you specify a value for nColumns greater than 8192, width is set to 8192.

Remarks

SET MEMOWIDTH specifies the width of output sent to the main Microsoft Visual FoxPro window or a user-defined window by commands such as ? | ??, DISPLAY, or LIST. It affects the output width of memo fields and character expressions longer than 254 characters. It also affects the values returned by the ATCLINE( ), ATLINE( ), MEMLINE( ), and MLINE( ) functions.

Note that for ? and ?? the displayed width will not exceed 256 characters.

If output is directed to the main Visual FoxPro window, the width of the output is determined by the font for the main Visual FoxPro window. If output is directed to a user-defined window, the width of the output is determined by the font for the user-defined window.

SET MEMOWIDTH is scoped to the current data session.

See Also

Other Resources

ATCLINE( ) Function
ATLINE( ) Function
MEMLINES( ) Function
MLINE( ) Function
SET DATASESSION Command
SET Command Overview
Commands
Language Reference


SET MESSAGE Command

Visual FoxPro 9.0 Language Reference
SET MESSAGE Command
See Also

Defines a message for display in the main Visual FoxPro window or in the graphical status bar, or specifies the location of messages for user-defined menu bars and menu commands. There are several versions of the syntax.

SET MESSAGE TO [cMessageText]
SET MESSAGE TO [nRow [LEFT | CENTER | RIGHT]]
SET MESSAGE WINDOW [WindowName]

Parameters

TO [ cMessageText]

Specifies the message to display.
TO [ nRow[LEFT | CENTER | RIGHT]]

Specifies the placement of messages in the main Visual FoxPro window. nRow specifies the row on which messages are displayed. If nRow is 0, no messages are displayed. LEFT, CENTER, and RIGHT specify the horizontal screen placement of messages. Visual FoxPro ignores a message location specified with SET MESSAGE when the graphical status bar is displayed.
WINDOW [ WindowName]

Specifies the window in which messages are displayed. To remove a message from the window and display it on the screen, issue SET MESSAGE WINDOW.

Remarks

SET MESSAGE lets you create a message. It also lets you specify where to display messages created with DEFINE BAR, DEFINE MENU, DEFINE PAD, or DEFINE POPUP.

By default, messages are placed on the last line of the main Visual FoxPro window if the character-based status bar is displayed. If the graphical status bar is displayed, messages are placed in the status bar.

The SET MESSAGE line is reset to the last line of the main Visual FoxPro window whenever SET DISPLAY is issued.

SET MESSAGE TO without any arguments places messages in the graphical status bar.

See Also

Other Resources

SET DISPLAY Command
SET STATUS Command
SET STATUS BAR Command
SET Command Overview
Commands
Language Reference


SET MULTILOCKS Command

Visual FoxPro 9.0 Language Reference
SET MULTILOCKS Command
See Also

Determines whether you can lock multiple records using LOCK( ) or RLOCK( ).

SET MULTILOCKS ON | OFF

Parameters

ON

Allows you to attempt locking a set of records. Include a set of record numbers in LOCK( ) or RLOCK( ) to try to lock multiple records.
OFF

(Default) Allows you to attempt locking a single record with LOCK( ) or RLOCK( ).

Remarks

When a table is opened for shared use on a network, you can attempt to lock more than one record in a table file. The SET MULTILOCKS setting determines whether you can attempt to lock either a single record or a set of records. Records can be locked with the LOCK( ) or RLOCK( ) function.

Note:
Switching SET MULTILOCKS from ON to OFF or from OFF to ON implicitly issues UNLOCK ALL — all record locks in all work areas are released.

SET MULTILOCKS is scoped to the current data session.

MULTILOCKS must be ON to before row or table buffering can be enabled with CURSORSETPROP( ). See CURSORSETPROP( ) for additional information about row and table buffering.

If you select the Enable Data Buffering check box in the Work Area Properties dialog box (which is displayed when you choose the Properties button in the Data Session window), MULTILOCKS is automatically set to ON for the current data session. However, clearing the Enable Data Buffering check box does not set MULTILOCKS to OFF for the current data session.

For more information about record and file locking and sharing tables on a network, see the LOCK( ) and RLOCK( ) functions, and Programming for Shared Access.

See Also

Other Resources

SET DATASESSION Command
SET Command Overview
Commands
Language Reference


SET NEAR Command

Visual FoxPro 9.0 Language Reference
SET NEAR Command
See Also

Determines where the record pointer is positioned after FIND or SEEK unsuccessfully searches for a record.

SET NEAR ON | OFF

Parameters

ON

Positions the record pointer on the closest matching record if a record search using FIND or SEEK is unsuccessful. With this setting, RECNO( ) returns the record number of the closest matching record, FOUND( ) returns false (.F.), and EOF( ) returns false (.F.).
OFF

(Default) Positions the record pointer at the end of the table if a record search using FIND or SEEK is unsuccessful. With this setting, RECNO( ) returns the number of records in the table plus 1, FOUND( ) returns false (.F.), and EOF( ) returns true (.T.).

Remarks

A search is unsuccessful when no record meets the search criteria.

Issuing RECNO( ) with an argument of 0 returns the record number of the closest matching record if a search is unsuccessful, regardless of the setting of SET NEAR.

SET NEAR is scoped to the current data session.

See Also

Other Resources

EOF( ) Function
FIND Command
FOUND( ) Function
RECNO( ) Function
SEEK Command
SET DATASESSION Command
SET Command Overview
Commands
Language Reference


SET NOCPTRANS Command

Visual FoxPro 9.0 Language Reference
SET NOCPTRANS Command
See Also

Prevents translation to a different code page for selected fields in an open table.

SET NOCPTRANS TO [FieldName1 [, FieldName2 ...]]

Parameters

TO [ FieldName1[, FieldName2...]]

Specifies the fields that should not be translated to another code page. Issue SET NOCPTRANS TO without a set of fields to return to the default translation (established by the CODEPAGE configuration item) for all character and memo fields in a table. Use SET("NOCPTRANS") to return the fields specified in the last SET NOCPTRANS command you issued. Use the CHR( ) function to ensure that individual characters don't get translated.

Remarks

Because Microsoft Visual FoxPro can be configured to automatically translate character and memo fields into other code pages, the SET NOCPTRANS command is available to prevent the automatic translation of fields containing binary data. For example, a memo field may contain a Microsoft Word document. When you access the Word document, you would like the document in its original, untranslated form. Use SET NOCPTRANS to specify that the memo field not be translated.

You don't need to use SET NOCPTRANS to access binary data if the character or memo field containing the binary data has not been translated. You can ensure that character and memo fields are not translated by omitting the CODEPAGE configuration item from your Visual FoxPro configuration file.

For additional information on code pages and Visual FoxPro's international support, see Code Pages Supported by Visual FoxPro in Developing International Applications.

See Also

Other Resources

CPCONVERT( ) Function
CPCURRENT( ) Function
CPDBF( ) Function
MODIFY COMMAND Command
MODIFY FILE Command
SET Command Overview
Commands
Language Reference


SET NOTIFY Command

Visual FoxPro 9.0 Language Reference
SET NOTIFY Command
See Also

Enables or disables the display of certain system messages. The following are examples of system messages affected by SET NOTIFY:

  • "Expression is valid" in the Expression Builder dialog box

  • "Do Canceled," which appears when program execution is canceled

SET NOTIFY [CURSOR] ON | OFF

Parameters

CURSOR

Specifies whether data-related messages should appear in the status bar.
ON

Enables the display of certain system messages. (Default)
OFF

Disables the display of certain system messages.

Remarks

System messages display in the graphical, not character-based, status bar at the bottom of the main Visual FoxPro window.

When SET NOTIFY CURSOR is set to OFF, Visual FoxPro suppresses all data-related messages from displaying in the status bar. These messages include alias, data source, record pointer, record count and exclusive/record unlocked status.

The setting of SET NOTIFY CURSOR does not affect SET NOTIFY.

You can use SET("NOTIFY",1) to return the current value of SET NOTIFY CURSOR.

SET NOTIFY disables the display of messages that appear even if SET TALK is OFF.

See Also

Reference

SET TALK Command

Other Resources

SET MESSAGE Command
SET( ) Function
WAIT Command
UIEnable Event
SET Command Overview
Commands
Language Reference


SET NULL Command

Visual FoxPro 9.0 Language Reference
SET NULL Command
See Also Example

Determines how null values are supported by the ALTER TABLE, CREATE TABLE and INSERT - SQL commands.

SET NULL ON | OFF

Parameters

ON

Specifies that all columns in a table created with ALTER TABLE and CREATE TABLE will allow null values. You can override null value support for columns in the table by including the NOT NULL clause in the columns' definitions. Also, specifies that INSERT - SQL will attempt to insert null values into any columns not included in the INSERT - SQL VALUE clause. INSERT - SQL can successfully insert null values only into columns that allow null values.
Note:
If you add support for null values to one or more columns in a table, the limit on the number of columns for that table is reduced from 255 to 254.

OFF

(Default) Specifies that all columns in a table created with ALTER TABLE and CREATE TABLE will not allow null values. You can designate null value support for columns in ALTER TABLE and CREATE TABLE by including the NULL clause in the columns' definitions. Also specifies that INSERT - SQL will insert blank values into any columns not included in the INSERT - SQL VALUE clause.

Remarks

SET NULL affects only how null values are supported by ALTER TABLE, CREATE TABLE and INSERT - SQL. Other commands are unaffected by SET NULL. SET NULL is scoped to the current data session.

Example

The following example demonstrates how SET NULL affects support for null values. The first table, employee, is created with SET NULL ON, so its fields support null values. REPLACE is used to place a null value in the cLastName field. The second table, staff, is created with SET NULL OFF, so its fields do not support null values. REPLACE is used to place zero in the cLastName field.
Copy Code
CLOSE DATABASES
SET NULL ON        && Fields will support null values
CREATE TABLE employee (cLastName C(20), ySalary Y(12,2))
APPEND BLANK       && Add a new blank record
REPLACE cLastName WITH .NULL.  && cLastName supports null values

SET NULL OFF       && Fields will not support null values
CREATE TABLE staff (cLastName C(20), ySalary Y(12,2))
APPEND BLANK       && Add a new blank record
REPLACE cLastName WITH 0   && Doesn't support null values

See Also

Other Resources

ALTER TABLE Command
CREATE TABLE Command
INSERT - SQL Command
ISNULL( ) Function
NVL( ) Function
SET DATASESSION Command
SET Command Overview
Commands
Language Reference


SET NULLDISPLAY Command

Visual FoxPro 9.0 Language Reference
SET NULLDISPLAY Command
See Also

Specifies the text displayed for null values.

SET NULLDISPLAY TO [cNullText]

Parameters

cNullText

Specifies the text that is displayed for null values. If cNullText is omitted, the default null value text, .NULL., is restored and displayed for null values.

Remarks

By default, Visual FoxPro displays .NULL. for null values in objects, Browse windows, DISPLAY output, LIST output, and so on. Use SET NULLDISPLAY to change the default null value text to a different character string. SET NULLDISPLAY changes the default null value text for all objects for which the NullDisplay property is the empty string.

Use the NullDisplay property to change the default null value text to a different character string for an individual object.

See Also

Other Resources

CREATE TABLE - SQL Command
SQL NullDisplay Property
SET NULL Command
SET Command Overview
Commands
Language Reference


SET ODOMETER Command

Visual FoxPro 9.0 Language Reference
SET ODOMETER Command
See Also

Specifies the reporting interval of the record counter for commands that process records.

SET ODOMETER TO [nRecords]

Parameters

TO [ nRecords]

Specifies the reporting interval in number of records. The value of nRecords can range from 1 to 32,767 records. The default value is 100 records.

Remarks

Use SET ODOMETER to change the interval at which commands display information about the number of records processed.

For example, COPY TO displays the number of records that are copied to a new file while the command is executing. The record counter can be turned off by issuing SET TALK OFF.

See Also

Other Resources

SET TALK Command
_TALLY System Variable
COPY TO Command
SET Command Overview
Commands
Language Reference


SET OLEOBJECT Command

Visual FoxPro 9.0 Language Reference
SET OLEOBJECT Command
See Also

Specifies whether Visual FoxPro searches the registry when an object cannot be located.

SET OLEOBJECT ON | OFF

Parameters

ON

(Default) Specifies that Visual FoxPro search the registry when an object cannot be located.
OFF

Specifies that Visual FoxPro does not search the registry when an object cannot be located.

Remarks

When an object is created with CREATEOBJECT( ) or GETOBJECT( ), Visual FoxPro searches for the object in the following locations and order:

  1. The Visual FoxPro base classes.

  2. Class definitions in memory in the order they are loaded.

  3. Class definitions in the current program.

  4. Class definitions in the .vcx class libraries opened with SET CLASSLIB.

  5. Class definitions in procedure files opened with SET PROCEDURE.

  6. Class definitions in the Visual FoxPro program execution chain (For Details, See DO Command).

  7. The registry.

When Visual FoxPro searches for an object, the registry is searched last. Visual FoxPro loads COM object support before it searches the registry, increasing the amount of memory required by Visual FoxPro and reducing the amount of memory available to other applications.

If you are developing an application that does not require COM support, issue SET OLEOBJECT OFF to prevent Visual FoxPro from searching the registry when an object cannot be located.

SET OLEOBJECT does not affect COM objects in Forms or General fields. Visual FoxPro always loads COM object support when a Form containing a COM object is opened for modification or is instantiated, or a table with a general field is opened.

Because GETOBJECT( )activates a COM object, Visual FoxPro generates an error when GETOBJECT( ) is issued and SET OLEOBJECT is OFF.

See Also

Other Resources

CREATEOBJECT( ) Function
GETOBJECT( ) Function
DO Command
SET Command Overview
Commands
Language Reference


SET OPTIMIZE Command

Visual FoxPro 9.0 Language Reference
SET OPTIMIZE Command
See Also

Enables or disables Rushmore Query Optimization.

SET OPTIMIZE ON | OFF

Parameters

ON

(Default) Enables Rushmore optimization.
OFF

Disables Rushmore optimization.

Remarks

Visual FoxPro uses a technology called Rushmore Query Optimization to optimize data retrieval. Table commands that support a FOR clause use Rushmore technology to enhance their performance. When you issue a command that is optimizable, Rushmore determines which records match the FOR criterion. The command is executed on records in the table that match the Rushmore recordset.

In rare cases, you should disable Rushmore optimization. If a command that benefits from Rushmore optimization modifies a query's index keys, the Rushmore recordset may become outdated. You can disable Rushmore optimization to ensure that you have the most current information from the table.

You can use SET OPTIMIZE to globally enable or disable Rushmore technology. Every command that uses Rushmore has a NOOPTIMIZE clause you can include to disable Rushmore optimization for the command.

For more information, see Using Rushmore Query Optimization to Speed Data Access.

Below are the commands whose performance is optimized by Rushmore:

Commands |
AVERAGE | INDEX
BLANK | LABEL
BROWSE | LIST
CALCULATE | LOCATE
CHANGE | RECALL
COPY TO | REPLACE
COPY TO ARRAY | REPLACE FROM ARRAY
COUNT | REPORT
DELETE | SCAN
DISPLAY | SORT
EDIT | SUM
EXPORT | TOTAL

See Also

Other Resources

INDEX Command
SET ORDER Command
SET Command Overview
Using Rushmore Query Optimization to Speed Data Access
Commands
Language Reference


SET ORDER Command

Visual FoxPro 9.0 Language Reference
SET ORDER Command
See Also

Designates a controlling index file or tag for a table.

Note:
Visual FoxPro does not support SET ORDER for binary indexes.

SET ORDER TO [nIndexNumber | IDXIndexFileName | [TAG] TagName
   [OF CDXFileName] [IN nWorkArea | cTableAlias]
   [ASCENDING | DESCENDING]]

Parameters

nIndexNumber

Specifies the number of the controlling index file or tag. nIndexNumber refers to the index files as they are listed in USE or SET INDEX. Open .idx files are numbered first in the order in which they appear in USE or SET INDEX. Tags in the structural .cdx file (if one exists) are then numbered in the order in which they were created. Finally, tags in any open independent .cdx files are numbered in the order in which they were created. The following example illustrates how different index file types and tags are numbered. (The file names are for illustration only and don't necessarily exist.) A table named video.dbf is opened with three indexes (title.idx, costs.cdx, and rating.idx) in the first work area with this command:
Copy Code
USE video INDEX title.idx, costs.cdx, rating.idx IN 1
The video table has a structural compound index file (video.cdx) with two tags, NUMBERSOLD and YEARSOLD. The structural .cdx file is automatically opened when video is opened. Since .idx files are numbered first, issue SET ORDER TO 1 to make title.idx the controlling index and SET ORDER TO 2 to make rating.idx the controlling index:
Copy Code
SET ORDER TO 1
Controlling index: C:\FOX30\TITLE.IDX
SET ORDER TO 2
Controlling index: C:\FOX30\RATING.IDX
The tags in video.cdx are numbered next:
Copy Code
SET ORDER TO 3
Controlling index: C:\FOX30\VIDEO.CDX  Tag: NUMBERSOLD
SET ORDER TO 4
Controlling index: C:\FOX30\VIDEO.CDX  Tag: YEARSOLD
Finally, the tags in the independent file, costs.cdx, are numbered:
Copy Code
SET ORDER TO 5
Controlling index: C:\FOX30\COSTS.CDX  Tag: RENTALCOST
SET ORDER TO 6
Controlling index: C:\FOX30\COSTS.CDX  Tag: BUYCOST
nIndexNumber can also be 0. If you issue SET ORDER TO 0, all index files remain open and are updated when records are added, deleted or modified. However, the records in the table are displayed and accessed in record number order and not in an indexed order. Issuing SET ORDER TO without additional arguments is identical to issuing SET ORDER TO 0. If nIndexNumber is greater than the number of .idx files and .cdx file tags, Visual FoxPro generates an error message.
IDXIndexFileName

Specifies an .idx file as the controlling index file.
[TAG] TagName[OF CDXFileName]

Specifies a tag of a .cdx file as the controlling tag. The tag name can be from a structural .cdx file or any open independent .cdx file. If identical tag names exist in open independent .cdx files, use OF CDXFileName to specify the .cdx file containing the tag.
Note:
The .idx file takes precedence if duplicate .idx file and tag names exist.

IN nWorkArea| cTableAlias

Designates a controlling index file or tag for a table open in a work area other than the currently selected work area. nWorkArea specifies the work area number and cTableAlias specifies the alias for a table.
ASCENDING | DESCENDING

Displays and allows access to table records in ascending or descending order. Including ASCENDING or DESCENDING doesn't change the index file or tag in any way.

Remarks

A table can have many index files open simultaneously. However, only one single-index (.idx) file (the controlling index file) or tag from a compound index (.cdx) file (the controlling tag) determines the order in which the records in a table are displayed or accessed. SET ORDER makes it possible for you to designate the controlling index file or tag. Certain commands (SEEK, for example) use the controlling index file or tag to search for records.

You can open index files with a table by including the INDEX clause in the USE command. If a table has an associated structural .cdx file, that file is automatically opened with the table. After a table has been opened, you can open and close index files for the table using SET INDEX.

By default, SET ORDER designates the controlling index or controlling tag for the table open in the currently selected work area.

See Also

Other Resources

INDEX Command
ORDER( ) Function
DESCENDING( ) Function
SET INDEX Command
SET Command Overview
Commands
Language Reference


SET PALETTE Command

Visual FoxPro 9.0 Language Reference
SET PALETTE Command
See Also

Specifies whether the Visual FoxPro default color palette is used.

SET PALETTE ON | OFF

Parameters

ON

(Default) Restores the default Visual FoxPro color palette.
OFF

Replaces the Visual FoxPro default color palette with color palettes from the .bmp graphics and OLE objects.

Remarks

OLE objects and .bmp graphics can contain color palettes that determine how the graphics and objects appear when they are displayed. The color palette of the first graphic or object displayed is used for all subsequent graphics or objects. Since a single color palette is used for all the graphics and objects, the colors of some of the graphics and objects may be changed in an unexpected manner.

The default Visual FoxPro color palette is designed to improve the display appearance of multiple .bmp graphics and OLE objects.

See Also

Other Resources

@ ... SAY Command
MODIFY GENERAL Command
SET COLOR TO Command
SET Command Overview
Commands
Language Reference


SET PATH Command

Visual FoxPro 9.0 Language Reference
SET PATH Command
See Also

Specifies a path for file searches.

SET PATH TO [Path] [ADDITIVE]

Parameters

TO [ Path]

Specifies the directories you want Visual FoxPro to search. Use commas or semicolons to separate the directories.
Note:
Visual FoxPro will not recognize a path name properly if a disk or directory name contains an exclamation point (!).

On all FoxPro platforms, functions that return path information, such as CURDIR( ), DBF( ), and SYS(2003), use Microsoft MS-DOS path-naming conventions in their return values.
ADDITIVE

Appends additional paths to the end of the current path.

Remarks

Issue SET PATH TO without Path to restore the path to the default directory. Use SET DEFAULT to specify the default directory and CURDIR( ) to return the current default directory.

SET PATH is not scoped to the current data session; changes you make to the default path using the SET PATH command affect all data sessions.

SET PATH is limited to a maximum of 4095 characters.

When using the ADDITIVE parameter, paths must be included either as a quoted string or valid expression. If you use macro substitution, it must be properly quoted as in following examples:

Copy Code
xx = ["Folder2"]
SET PATH TO &xx ADDITIVE
** or **
xx = "Folder2"
SET PATH TO '&xx' ADDITIVE

See Also

Other Resources

CD | CHDIR Command
GETFILE( ) Function
LOCFILE( ) Function
MD | MKDIR Command
RD | RMDIR Command
SET DEFAULT Command
SET DATASESSION Command
SET Command Overview
Commands
Language Reference


SET PDSETUP Command

Visual FoxPro 9.0 Language Reference
SET PDSETUP Command
See Also

Loads a printer driver setup or clears the current printer driver setup.

SET PDSETUP TO [[cPrinterDriverSetup [, Parameter1[, Parameter2 ...]]]
   [WITH Parameter3 [, Parameter4 ...]]]

Parameters

cPrinterDriverSetup

Specifies the name of the printer driver setup to load. When you load a printer driver setup, the name of the setup is stored in the _PDSETUP system variable, and a special variable array, _PDPARMS, can be created. (_PDPARMS is discussed in detail under the WITH clause in this topic.) If the printer driver setup name you specify with cPrinterDriverSetup doesn't exist in your resource file, the current printer driver setup application is executed so you can create a setup with this name. If the current printer driver setup application is Genpd.app, the Printer Setup Editing dialog box appears so you can create the setup. If the setup name begins with a dash (-), the _GENPD program won't be executed, but the name following the dash is stored in _PDSETUP. If you issue SET PDSETUP TO without cPrinterDriverSetup, the current printer driver setup is cleared, the empty string is stored in _PDSETUP, and the _PDPARMS array is cleared from memory.
Parameter1[, Parameter2...]

Specifies any number of optional parameters. These parameters are passed to the printer setup interface application and can be of any type (character, numeric, logical, and so on). The first line in your printer setup interface application must be an LPARAMETERS or PARAMETERS statement to accept the parameters passed from SET PDSETUP. If you are using Genpd.app, don't include these optional parameters. Genpd.app doesn't accept parameters passed from SET PDSETUP, so including them generates an error.
WITH Parameter3[, Parameter4...]

Creates the special _PDPARMS printer array. Each parameter you specify with Parameter3, Parameter4, and so forth becomes an element in _PDPARMS. The first parameter (Parameter3) is stored to the first element of _PDPARMS, the second parameter (Parameter4) is stored to the second element, and so on. These parameters may be of any type (character, numeric, logical, and the like). If you are using Genpd.app, any parameters you include are overwritten by the application.

Remarks

In Visual FoxPro, a printer driver setup is used when you print character-based reports created in FoxPro for MS-DOS.

A printer driver setup consists of a combination of settings, including the printer driver program and information such as page orientation, default font size and font style, margins, and so on. Printer driver setups are stored in your FoxPro for MS-DOS resource file, FoxUser.dbf, and can be created interactively and assigned a name in the Printer Setup Editing dialog box.

A printer driver setup can also be loaded or cleared with the _PDSETUP system variable.

When you issue SET PDSETUP, the current printer setup interface application is executed. The interface application is passed the name of the printer driver setup included in SET PDSETUP. The interface application can also be specified with the _GENPD system variable. The default interface application is Genpd.app, the printer setup interface application included with FoxPro for MS-DOS.

See Also

Other Resources

_GENPD System Variable
_PDRIVER System Variable
_PDSETUP System Variable
SET PRINTER Command
SET Command Overview
Commands
Language Reference


SET POINT Command

Visual FoxPro 9.0 Language Reference
SET POINT Command
See Also Example

Determines the decimal point character used in the display of numeric and currency expressions.

SET POINT TO [cDecimalPointCharacter]

Parameters

cDecimalPointCharacter

Specifies the character for the decimal point.

Remarks

Use SET POINT to change the decimal point from the default, which is a period (.). Issue SET POINT TO without cDecimalPointCharacter to reset the decimal point to a period. Although you can set the displayed decimal point to a different character, you must use a period as the decimal point in calculations.

SET POINT is scoped to the current data session.

Example

Copy Code
gnX = 1.25
gcNewPoint = '_'
SET POINT TO gcNewPoint
? gnX
SET POINT TO      && Reset the decimal point to a period (.)
? gnX

See Also

Other Resources

SET DATASESSION Command
SET DECIMALS Command
SET FIXED Command
SET SEPARATOR Command
SET SYSFORMATS Command
SET Command Overview
Commands
Language Reference


SET PRINTER Command

Visual FoxPro 9.0 Language Reference
SET PRINTER Command
See Also

Enables or disables output to the printer or routes output to a file, port, or network printer. There are several versions of the syntax.

Tip:
To direct output to a file, a port for a different local printer, or a network printer, use SET PRINTER TO with the specified arguments. To reset output to the default MS-DOS PRN print utility, use SET PRINTER TO without arguments.

SET PRINTER ON [PROMPT] | OFF
SET PRINTER FONT cFontName [, nFontSize [, nFontCharSet]] [STYLE cFontStyle]
SET PRINTER TO [FileName [ADDITIVE] | PortName]
SET PRINTER TO [DEFAULT | NAME WindowsPrinterName]
SET PRINTER TO NAME \\ServerName\PrinterName

Parameters

ON [PROMPT]

Enables output to the printer. PROMPT displays the Print dialog box before printing starts. In the Print dialog box, you can adjust printer settings. The currently installed printer driver determines which printer settings you can adjust.
Note:
When SET PRINTER is set to ON, output formatted with the @ ... SAY command is not routed to the printer. To direct output from @ ... SAY to the printer, use the SET DEVICE TO PRINTER command. For more information, see SET DEVICE Command.

OFF

Disables output to the printer. (Default)
FONT cFontName[, cFontSize [, nFontCharSet]]

Specifies a default font for printer output. cFontName specifies the name of the font, and cFontSize specifies the point size. You can specify a language script with nFontCharSet. See the GETFONT( ) Function for a list of available language script values. For example, the following command specifies 16-point Courier font as the default printer font:
Copy Code
SET PRINTER FONT 'Courier', 16
If the font you specify is not available, a font with similar font characteristics is substituted.
STYLE cFontStyle

Specifies a default font style for printer output. If you omit the STYLE clause, the normal font style is used. If the font style you specify is not available, a font style with similar characteristics is substituted. The following table lists font styles you can specify with cFontStyle.

cFontStyle Font style

B

Bold

I

Italic

N

Normal

O

Outline

Q

Opaque

S

Shadow

–

Strikeout

T

Transparent

U

Underline
You can include more than one character to specify a combination of font styles. For example, the following command specifies 16-point Courier Bold Italic:
Copy Code
SET PRINTER FONT 'Courier', 16 STYLE 'BI'
TO [ FileName[ADDITIVE] | PortName]

Specifies a file or port to which output is directed. FileName specifies a file name to which output is directed. ADDITIVE appends output to the existing contents of the file. Omitting ADDITIVE overwrites the existing contents of the file. PortName sends output to a different local printer.
TO [DEFAULT | NAME WindowsPrinterName]

Sends printer output to the default Windows printer or to a specific Windows printer.
Note:
Windows printer names are stored in the Win.ini file.

TO NAME \\ ServerName\ PrinterName

Spools printer output to a network printer.
Note:
This clause is supported only for versions of Visual FoxPro running on Windows 2000 or later.

ServerName is the network name assigned to the print server. This name is assigned by the network administrator and must be unique. PrinterName is a name that is assigned to the printer and by the network administrator.

Remarks

When you direct output to a network printer, output prints or collects in a print spooler until a new SET PRINTER command is issued. For additional information about printing on your network, consult your network documentation.

Note:
This command does not function in Unattended Server Mode.

You can use the GETPRINTER( ) or APRINTERS( ) functions to determine the names of the currently installed printers. For example, the following command displays the Windows Printer dialog box and makes the printer you select the printer to which printed output is directed:

Copy Code
SET PRINTER TO NAME GETPRINTER( )

For more information, see APRINTERS( ) Function and GETPRINTER( ) Function.

See Also

Other Resources

PRINTSTATUS( ) Function
SET Command Overview
Commands
Language Reference


SET PROCEDURE Command

Visual FoxPro 9.0 Language Reference
SET PROCEDURE Command
See Also

Opens a procedure file.

SET PROCEDURE TO [FileName1 [, FileName2, ...]] [ADDITIVE]

Parameters

FileName1[, FileName2, ...]

Specifies the sequence in which files are to be opened. SET PROCEDURE can take more than one file name, making it possible for you to open several procedure files at once. This option makes it possible for you to create stand-alone libraries of functions and specify them separately.
ADDITIVE

Opens additional procedure files without closing currently open procedure files.

Remarks

Issuing SET PROCEDURE TO without any file names closes all open procedure files. Use RELEASE PROCEDURE to close individual files.

When you execute a procedure, the procedure files are searched if the procedure isn't located in the currently executing program.

For more information about procedure files, see PROCEDURE Command and DO Command.

If a COM dynamic-link library (DLL) which uses SET PROCEDURE TO is instantiated more than once, the Init method of the second instance may fail with one of the following messages:

OLE error code 0x80004005: Unspecified error.

OLE error code 0x80020009: Exception occurred.

To instantiate an OLEPUBLIC class, Visual FoxPro must be able to find all the code for the class. There is an internal SET PROCEDURE/SET CLASSLIB to detect all the related code; if you try to change this setting, an error occurs. To prevent this, use SET PROCEDURE TO with the ADDITIVE keyword.

See Also

Other Resources

PROCEDURE Command
RELEASE PROCEDURE Command
LIST PROCEDURES Command
SET Command Overview
Commands
Language Reference


SET READBORDER Command

Visual FoxPro 9.0 Language Reference
SET READBORDER Command
See Also Example

Determines whether borders are placed around text boxes created with @ ... GET.

SET READBORDER ON | OFF

Parameters

ON

Places a single-line border around all text boxes created with @ ... GET. If SET READBORDER is set to ON when the first text box is created, all subsequent text boxes created in the same READ level also have borders.
OFF

(Default) Specifies that a border isn't placed around text boxes created with @ ... GET. If SET READBORDER is set to OFF when the first text box is created, all subsequent text boxes created in the same READ level do not have borders.

Remarks

SET READBORDER specifies whether single-line borders are placed around text boxes created with @ ... GET.

Example

In the following example, the first three text boxes created with @ ... GET have borders. The third text box has a border, even though SET READBORDER was SET to OFF before it was created. The fourth text box does not have a border, since READBORDER was SET to OFF and it is encompassed in a different READ from the first three text boxes.
Copy Code
SET READBORDER ON
@ 2,2 GET gnW DEFAULT 1   && 1st READ
@ 4,2 GET gnX DEFAULT 1   && 1st READ
SET READBORDER OFF
@ 6,2 GET gnY DEFAULT 1   && 1st READ
READ
@ 8,2 GET gnZ DEFAULT 2   && 2nd READ
READ

See Also

Other Resources

READ Command
READ EVENTS Command
@ ... GET - Text Boxes Command
SET Command Overview
Commands
Language Reference


SET REFRESH Command

Visual FoxPro 9.0 Language Reference
SET REFRESH Command
See Also

Determines whether to and how frequently to update a browse window or memo editing window, or to refresh local memory buffers with changes from other users on the network.

SET REFRESH TO nSeconds1 [, nSeconds2]

Parameters

nSeconds1

Specifies the number of seconds between updating the display for a browse window or memo editing window. nSeconds1 can be an integer value from 0 (default) to 3,600 seconds. Setting nSeconds1 to 0 does not update the records that you are viewing.
Note:
Fractional values are truncated. If you specify a value other than 0 for nSeconds1 and omit nSeconds2, then nSeconds2 is set to the same value as nSeconds1. However, if you specify 0 seconds for nSeconds1 and omit nSeconds2, then nSeconds2 is set to 5 seconds.

[, nSeconds2]

Specifies the number of seconds between refreshing the local memory buffers with current data from the network. The default value is 5 seconds. Setting nSeconds2 to 0 does not refresh the buffers.
Tip:
You can improve performance by increasing the value of nSeconds2. You can also set this option in the Data tab of the Options dialog box.

The following table describes values for nSeconds2.

nSeconds2 Description

-1

Always read data from disk.

0

Always use data in memory buffer but do not refresh buffer.

.001 to 3,600

Refresh local memory buffers every number of seconds specified. Fractional values are accepted.

Note:
For display purposes, Visual FoxPro rounds the value of nSeconds2 to the closest millisecond.

Remarks

Because tables can be opened for shared use on a network, it is possible that other users on the network are editing the records you are viewing in a browse window. By setting SET REFRESH, you can control the time interval between updates to the browse window. When you set the SET REFRESH command to a nonzero value and other users change records you are viewing, the records are updated when the refresh interval elapses.

SET REFRESH affects records displayed in a browse window opened with the BROWSE, CHANGE, or EDIT commands. Memo fields opened for editing in a browse window, for example, using the MODIFY MEMO command, are also updated. For more information, see BROWSE Command, CHANGE Command, EDIT Command, and MODIFY MEMO Command.

Visual FoxPro buffers portions of tables in memory on your workstation. SET REFRESH can specify how often data that is buffered locally on your workstation is refreshed.

See Also

Other Resources

Programming for Shared Access
SET Command Overview
Commands


SET RELATION Command

Visual FoxPro 9.0 Language Reference
SET RELATION Command
See Also

Establishes a relationship between open tables so that moving the record pointer in the parent table moves the record pointer in the child table.

SET RELATION TO [eExpression1 INTO nWorkArea1 | cTableAlias1
   [, eExpression2 INTO nWorkArea2 | cTableAlias2 ...]
   [IN nWorkArea | cTableAlias] [ADDITIVE]]

Parameters

eExpression1

Specifies the relational expression that creates a relationship between the parent and child tables. The relational expression is usually the index expression of the controlling index of the child table. If eExpression1 is numeric, it is evaluated when the record pointer in the parent table is moved. The record pointer in the child table is then moved to record number eExpression1. Omitting arguments for SET RELATION removes all relationships in the currently selected work area. You can remove a specific parent-child relationship using SET RELATION OFF. For more information, see SET RELATION OFF Command.
INTO nWorkArea1| cTableAlias1

Specifies the work area number or table alias of the child table.
eExpression2INTO nWorkArea2| cTableAlias2...

Specifies a relational expression and the work area number or a child table alias so you can create an additional relationship between the parent table and child tables. Precede each relationship definition with a comma.
IN nWorkArea

Specifies the work area of the parent table.
IN cTableAlias

Specifies the alias of the parent table. The IN clause makes it possible for you to create a relationship without first selecting the parent table's work area. If you omit nWorkArea and cTableAlias, the parent table must be open in the currently selected work area.
ADDITIVE

Preserves all existing relationships in the current work area and creates the specified relationship. Omitting ADDITIVE breaks any relationships in the current work area and creates the specified relationship.

Remarks

Before you can create a relationship, the tables must be open in different work areas. The child table must be indexed on the common field unless the relational expression is numeric. The index for the child table can be a single-entry (.idx) index, a structural compound (.cdx) index, or an non-structural compound index. If the index is a compound index, specify the proper index tag to order the records in the child table using the SET ORDER command.

Note:
If you call SET RELATION with a nonnumeric relational expression and the child table has not been ordered with an index, Visual FoxPro generates an error message.

You can typically create relationships between tables that have a common field. You can create multiple relations between a single parent table and various child tables using a single SET RELATION command.

Note:
If a matching record is not found in the child table, the record pointer in the child table is positioned at the end of the table.

If the child table has an active index, the data type of eExpression1 must be the same as the child table's active index key. If the child table does not have an active index, then eExpression1 must have a numeric data type, in which case it represents a record number to move to in the child table.

Examples

Example 1

The following example creates a relationship between a customer table and an orders table where one customer record in the customer table can have many order records in the orders table. By creating a relationship using a common field, you can see all the orders for any customer. This example creates relationship using the Cust_ID field in the customer table and the Cust_ID index tag in the orders table. The index in the orders table organizes records by customer.

The following code uses the USE command to open the customer table as the parent table in work area 1 and open the orders table as the child table in work area 2. The SELECT command selects the work area for the orders table. The SET ORDER command specifies the order of the orders table using the Cust_ID index tag:

Copy Code
USE Customer IN 1
USE Orders IN 2
SELECT Orders
SET ORDER TO TAG Cust_ID

The following code uses the SELECT command to select the work area for the customer table. SET RELATION creates the relationship between the parent table and the controlling index in the child table:

Copy Code
SELECT Customer
SET RELATION TO Cust_ID INTO Orders

The following code opens the customer table in a browse window, selects the work area of the orders table and opens a browse window for the orders table:

Copy Code
BROWSE NOWAIT
SELECT Orders
BROWSE NOWAIT

When you move the record pointer in the customer table, the record pointer in the orders table also moves. Opening the Data Session window displays the relationship created between the two tables.

Example 2

The following example creates a relationship within a single table, or a self-referential relationship. By opening the same table with two different aliases in different work areas, you can create a relationship in the same table by using the two aliases. The following code selects the work area of the table with the SELECT command and opens the table with the Manager alias with the USE command. The SELECT command then selects the same work area and opens the table again with the Employee alias with the USE command and the AGAIN keyword. The tables open in two different work areas:

Copy Code
SELECT 0
USE Employees ALIAS Manager
SELECT 0
USE Employees AGAIN ALIAS Employee

The following code creates an index on the based on the Reports_To field with the index tag Mgr_ID for the table using the INDEX command and sets the order in the table to that index using the SET ORDER command. The index created organizes records by manager.

Copy Code
INDEX ON Reports_To TAG Mgr_ID
SET ORDER TO Mgr_ID

The following code selects the Manager alias as the parent using the SELECT command.

SET RELATION creates the relationship between the parent table and the controlling index tag in the child table. The controlling index in the child table organizes records by employee.

Copy Code
SELECT Manager
SET RELATION TO Emp_ID INTO Employee

The following code opens the table with the Manager alias in a browse window, selects the work area of the table with the Employee alias and opens a browse window for the table:BROWSESELECT EmployeeBROWSE

When you move the record pointer in the manager table, the record pointer in the employee table also moves and displays only those employees who report to the selected manager.

See Also

Other Resources

How to: Set Temporary Relationships Between Tables
INDEX Command
RELATION( ) Function
SET ORDER Command
TARGET( ) Function
SET Command Overview
Commands


SET RELATION OFF Command

Visual FoxPro 9.0 Language Reference
SET RELATION OFF Command
See Also

Breaks an established relationship between the parent table in the currently selected work area, and a related child table.

SET RELATION OFF INTO nWorkArea | cTableAlias

Parameters

INTO nWorkArea| cTableAlias

Specifies the child table's work area number or table alias.

See Also

Other Resources

RELATION( ) Function
SELECT Command
SET RELATION Command
SET SKIP Command
TARGET( ) Function
SET Command Overview
Commands
Language Reference


SET REPORTBEHAVIOR Command

Visual FoxPro 9.0
SET REPORTBEHAVIOR Command
See Also

Configures how Visual FoxPro processes REPORT FORM and LABEL FORM commands.

SET REPORTBEHAVIOR 80 | 90

Parameters

80

Specifies that Visual FoxPro executes report rendering commands (such as REPORT FORM or LABEL FORM) similarly to versions prior to Visual FoxPro 9.0. (Default)

90

Specifies that when Visual FoxPro executes a command that requires report rendering, it will use the application specified by the _REPORTOUTPUT system variable to obtain an instance of a ReportListener class to perform the rendering.

Remarks

The SET REPORTBEHAVIOR command allows your existing reporting code to take full advantage of the new GDI+ report rendering engine with one command.

SET REPORTBEHAVIOR has no effect on REPORT FORM and LABEL FORM commands that have a ReportListener instance specified via an OBJECT clause.

SET REPORTBEHAVIOR 90 is respected by the Report Designer and Label Designer in that they will use a ReportListener to perform the rendering when you select Print Preview from the Report menu.

The scope of SET REPORTBEHAVIOR is global.

See Also

Reference

REPORT FORM Command
ReportListener Object
_REPORTOUTPUT System Variable


SET REPROCESS Command

Visual FoxPro 9.0 Language Reference
SET REPROCESS Command
See Also Example

Specifies how many times and for how long Visual FoxPro attempts to lock a file or record after an unsuccessful locking attempt.

SET REPROCESS TO nAttempts [SECONDS] [SYSTEM] | TO AUTOMATIC [SYSTEM]

Parameters

TO nAttempts [SECONDS]

Specifies the number of times Visual FoxPro attempts to lock a record or file after an initial unsuccessful attempt. The default value is 0, the maximum value is 32,000. SECONDS specifies that Visual FoxPro attempts to lock a file or record for nAttempts seconds. It's available only when nAttempts is greater than zero. For example, if nAttempts is 30, Visual FoxPro attempts to lock a record or file up to 30 times. If you also include SECONDS (SET REPROCESS TO 30 SECONDS), Visual FoxPro continuously attempts to lock a record or file for up to 30 seconds. A system message ("Waiting for lock ... ") appears if SET STATUS is set to ON. If an ON ERROR routine is in effect and attempts by a command to lock the record or file are unsuccessful, the ON ERROR routine is executed. However, if a function attempts the lock, an ON ERROR routine isn't executed and the function returns false (.F.). If an ON ERROR routine is not in effect, a command attempts to lock the record or file, and the lock cannot be placed, an appropriate alert appears (for example, "Record is in use by another"). If a function attempts to place the lock, the alert is not displayed and the function returns false (.F.). If nAttempts is 0 (the default value) and you issue a command or function that attempts to lock a record or file, Visual FoxPro tries to lock the record or file indefinitely. Visual FoxPro displays the system message, "Attempting to lock... Press Escape to Cancel," while attempting to lock the record or file. The lock is placed and the system message is cleared if the record or file becomes available for locking while you wait. If a function attempted to place the lock, the function returns true (.T.). If you press ESC in response to the system message, an appropriate alert appears (for example, "Record is in use by another"). If a function attempts to place the lock, the alert is not displayed and the function returns false (.F.). If an ON ERROR routine is in effect and a command is attempting to lock the record or file, the ON ERROR routine takes precedence over additional attempts to lock the record or file. The ON ERROR routine is immediately executed. Visual FoxPro does not attempt additional record or file locks and does not display the system message. If nAttempts is –1, Visual FoxPro attempts to lock the record or file indefinitely. You cannot cancel the locking attempts by pressing the ESC key, and an ON ERROR routine is not executed. Setting nAttempts to -2 is equivalent to using the TO AUTOMATIC clause. Visual FoxPro displays the "Waiting for lock ... " system message only if SET STATUS is set to ON. If a lock has been placed by another user on the record or file you are attempting to lock, you must wait until the user releases the lock.
TO AUTOMATIC

Specifies that Visual FoxPro attempts to lock the record or file indefinitely (equivalent to setting nAttempts to –2). This clause is similar to setting nAttempts to -1, except that it includes the facility to quit the attempt to lock a record or file. The "Attempting to lock ... Press Escape to Cancel" system message appears while Visual FoxPro attempts to lock the record or file. The lock is placed and the system message is cleared if the record or file becomes available for locking while you wait. If a function is used to place the lock, the function returns true (.T.). If an ON ERROR routine is not in effect and you press ESC in response to the system message, an appropriate alert appears (for example, "Record is in use by another"). If a function attempts to place the lock, the alert isn't displayed and the function returns false (.F.). If an ON ERROR routine is in effect and ESC is pressed, the ON ERROR routine is executed. If a function attempts to place the lock, an ON ERROR routine is not executed and the function returns false (.F.).
SYSTEM

Specifies that SET REPROCESS applies to the system data session, which controls Tables used internally, such as a database, FoxUser, .scx files, and so on. For more information about record and file locking and sharing tables on a network, see Programming for Shared Access.

Remarks

The first attempt to lock a record or file is not always successful. Frequently, a record or file is locked by another user on the network. SET REPROCESS determines whether Visual FoxPro makes additional attempts to lock the record or file when the initial attempt is unsuccessful. You can specify either how many times additional attempts are made or for how long the attempts are made. An ON ERROR routine affects how unsuccessful lock attempts are handled.

SET REPROCESS is scoped to the current data session. SET REPROCESS SYSTEM is scoped to the system data session.

Note:
Changes made in the Data tab of the Tools Options dialog box affect only the current session.

Example

Copy Code
SET ("REPROCESS")      && Returns the current session setting
SET("REPROCESS",1)   && Returns the system session setting

* In the config.fpw file, the following code changes the default session.
REPROCESS = 100

See Also

Reference

SYS(3051) - Set Lock Retry Interval
SYS(3052) - Override SET REPROCESS Locking

Other Resources

FLOCK( ) Function
SET DATASESSION Command
SET Command Overview
Programming for Shared Access
Commands
Language Reference


SET RESOURCE Command

Visual FoxPro 9.0 Language Reference
SET RESOURCE Command
See Also

Updates or specifies a resource file. The resource file is a Visual FoxPro table that contains information on system and user-defined resources such as keyboard macros, preferences, system window locations and sizes, diary entries, and so on. There are two versions of the syntax.

SET RESOURCE ON | OFF
SET RESOURCE TO [FileName]

Parameters

ON

Specifies that changes made to the Visual FoxPro environment are saved to the resource file. (Default)
OFF

Specifies that changes made to the Visual FoxPro environment are not saved to the resource file.
TO [ FileName]

Specifies that changes made to the Visual FoxPro environment are saved to a resource file (FileName) other than the default FoxUser.dbf resource file. Issue SET RESOURCE TO without a resource file name to open the default FoxUser.dbf resource file. Issuing SET RESOURCE TO performs an implicit SET RESOURCE ON.

See Also

Other Resources

SYS(2005) - Current Resource File
Resource Files in Applications
SET Command Overview
Commands
Language Reference


SET SAFETY Command

Visual FoxPro 9.0 Language Reference
SET SAFETY Command
See Also

Determines whether Visual FoxPro displays a dialog box before overwriting an existing file, or whether table or field rules, default values, and error messages are evaluated when changes are made in the Table Designer or with ALTER TABLE.

SET SAFETY ON | OFF

Parameters

ON

(Default) Specifies that a dialog box is displayed before you overwrite an existing file. The dialog box gives you the option of overwriting the existing file. For the Table Designer, specifies that table or field rules, default values, and error messages are evaluated when you save changes to a table's structure. Data validation occurs for new or modified validation rules after you save the table structure changes. If a validation rule contains a UDF (user-defined function), the UDF isn't evaluated and the validation rule is ignored. For ALTER TABLE, table or field rules, default values, and error messages are evaluated when ALTER TABLE changes the table's structure. Data validation occurs for new or modified validation rules when ALTER TABLE changes the table's structure. If a validation rule contains a UDF (user-defined function), the UDF isn't evaluated and the validation rule is ignored.
OFF

Specifies that a dialog box isn't displayed before an existing file is overwritten. Note that for in-process .dll automation servers the default setting of SET SAFETY is OFF. For the Table Designer, specifies that table or field rules, default values, and error messages are not evaluated when you save changes to a table's structure. However, data validation occurs for new or modified validation rules after you save the table structure changes. For ALTER TABLE, table or field rules, default values, and error messages are not evaluated when ALTER TABLE changes the table's structure. Data validation does not occur for new or modified validation rules after ALTER TABLE changes the table's structure.

Remarks

SET SAFETY is scoped to the current data session.

See Also

Other Resources

ALTER TABLE - SQL Command
MODIFY STRUCTURE Command
SET DATASESSION Command
SET TALK Command
SET Command Overview
Commands
Language Reference


SET SECONDS Command

Visual FoxPro 9.0 Language Reference
SET SECONDS Command
See Also Example

Specifies whether seconds are displayed in the time portion of a DateTime value.

SET SECONDS ON | OFF

Parameters

ON

(Default) Specifies that seconds are displayed in DateTime values.
OFF

Specifies that seconds are not displayed in DateTime values.

Remarks

SET SECONDS is scoped to the current data session.

Example

The following example demonstrates the effect of the SET SECONDS setting on the time value returned by DATETIME( ). When SET SECONDS is ON, the time value is displayed with the seconds portion. When SET SECONDS is OFF, the time value is displayed without the seconds portion.
Copy Code
SET SECONDS ON
CLEAR
? DATETIME( )  && Displays time value with the seconds portion

SET SECONDS OFF  && Displays time value without the seconds portion
? DATETIME( )

See Also

Reference

SET SECONDS Command

Other Resources

CTOT( ) Function
DATE( ) Function
DATETIME( ) Function
DTOT( ) Function
HOUR( ) Function
MINUTE( ) Function
SEC( ) Function
SECONDS( ) Function
TIME( ) Function
SET Command Overview
Commands
Language Reference


SET SEPARATOR Command

Visual FoxPro 9.0 Language Reference
SET SEPARATOR Command
See Also Example

Specifies the character that separates each group of three digits to the left of the decimal point when displaying a formatted numeric or currency value.

Syntax

Copy Code
SET SEPARATOR TO [expC]

Parameters

exprC

Specifies the character for the numeric place separator.

Remarks

Use SET SEPARATOR to change the numeric place separator from the default, for example a comma (,). Issue SET SEPARATOR without its argument to reset the value to its default.

Tip:
If you use the command SET SYSFORMATS ON, the character for the numeric place separator is set by the Windows Regional Options Control Panel. Using this command will re-set the character to your regional default until the next time you issue a SET SEPARATOR exprC command.

SET SEPARATOR is scoped to the current data session.

Example

Copy Code
SET SEPARATOR TO && reset to default
_Screen.AddObject("t","textbox")
_Screen.t.InputMask = "9,999.99"
_screen.t.Value = 1000
_Screen.t.Visible = .T.
WAIT WINDOW "Note the value in the textbox: looks like 1,000.00"

* now change the separator:
SET SEPARATOR TO "#"
WAIT WINDOW "Note the value in the textbox: looks like 1#000.00"

* now indicate that you want regional defaults:
SET SYSFORMATS ON
WAIT WINDOW ;
   "Note the value in the textbox: looks like 1,000.00 again" ;
    + CHR(13) + ;
   "because SET SYSFORMATS ON was issued."

? SET("SEPARATOR")
WAIT WINDOW ;
   "Note the value of SET('SEPARATOR') now also reflects the default."

SET SEPARATOR TO "#"
WAIT WINDOW ;
   "The textbox changes again." ;
    + CHR(13) + ;
   "Although SET SYSFORMATS is still ON, SET SEPARATOR is more recent."

See Also

Reference

SET SYSFORMATS Command
SET POINT Command
SET DECIMALS Command
InputMask Property
TRANSFORM( ) Function

Concepts

Format Expressions for Field Controls

Other Resources

SET DATASESSION Command
SET Command Overview
Commands
Language Reference


SET SKIP Command

Visual FoxPro 9.0 Language Reference
SET SKIP Command
See Also Example

Creates a one-to-many relationship among tables.

SET SKIP TO [TableAlias1 [, TableAlias2] ...]

Parameters

TO TableAlias1[, TableAlias2] ...

Specifies the aliases of multiple child tables. These are used to create a one-to-many relationship with a parent table. Use commas to separate the aliases. In commands that support a scope (DISPLAY, LIST, and so on), records in the parent table are repeated for each corresponding record in the child table. Use SET SKIP TO without additional arguments to remove the one-to-many relationship from the parent table open in the currently selected work area. Any one-to-one relationships remain in effect. One-to-one relationships can be removed with SET RELATION TO.

Remarks

Using SET RELATION, you can establish relations between tables open in different work areas. When the record pointer is moved in the parent table, the record pointer in the child table moves to the first corresponding record. The relational expression in SET RELATION determines where the record pointer moves in the child table. A one-to-one relation is created — for each record in the parent table, the record pointer moves to the first matching record in the child table. If a matching record can't be found in the child table, the record pointer in the child table moves to the end of the table.

Frequently, a child table contains multiple records that correspond to one record in the parent table. SET SKIP lets you establish a one-to-many relationship between one record in the parent table and multiple records in the child table. When you skip through the parent table, the record pointer remains on the same parent record until the record pointer moves through all related records in the child table.

To establish a one-to-many relationship, first create the relationship between the parent and child table with SET RELATION. Then, issue SET SKIP to create a one-to-many relationship.

Example

This example below finds all occurrences in three tables where each item in the first field are the same. It does this by using scanning the first table, which has a relation into a second, which table has a relation into a third. The first table then does a SET SKIP for the other two tables. A SET SKIP on the second table has no effect. It affects only the table being scanned (replaced, etc.). In the example, eight matches are found.
Copy Code
CLOSE DATABASES
* Creates parent table with values a and b in Name field
CREATE TABLE Parent FREE (Name C(1), Val C(10))
INSERT INTO Parent VALUES ('a', 'Parent.a1')
INSERT INTO Parent VALUES ('b', 'Parent.b1')

SELECT 0     && Child1 will have two a's and two b's
CREATE TABLE Child1 FREE (Name1 C(1), Val C(10))
INSERT INTO Child1 VALUES ('a', 'Child1.a1')
INSERT INTO Child1 VALUES ('b', 'Child1.b1')
INSERT INTO Child1 VALUES ('b', 'Child1.b2')
INSERT INTO Child1 VALUES ('a', 'Child1.a2')
INDEX ON Name1 TAG tagName   && The tag name is irrelevant

SELECT 0  && Child2 will have two a's and two b's
CREATE TABLE Child2 FREE (Name2 C(1), Val C(10))
INSERT INTO Child2 VALUES ('b', 'Child1.b1')
INSERT INTO Child2 VALUES ('b', 'Child1.b2')
INSERT INTO Child2 VALUES ('a', 'Child1.a1')
INSERT INTO Child2 VALUES ('a', 'Child1.a2')
INDEX ON Name2 TAG tagName     && The tag name is irrelevant

SELECT Child1
SET RELATION TO Name1 INTO Child2
SELECT Parent
SET RELATION TO Name INTO Child1
SET SKIP TO Child1, Child2 && Parent gets both skips.
           && Otherwise, only four record triplets
           && would be listed.
SCAN ALL  && There will be eight triplets: four a's and four b's
   ? Parent.Val, Child1.Val, Child2.Val
ENDSCAN

See Also

Other Resources

RELATION( ) Function
SET RELATION Command
SKIP Command
Commands
Language Reference


SET SKIP OF Command

Visual FoxPro 9.0 Language Reference
SET SKIP OF Command
See Also

Enables or disables a menu, menu bar, menu title, or menu item for user-defined menus or the Microsoft Visual FoxPro system menu. There are several versions of the syntax.

SET SKIP OF MENU MenuBarName1 lExpression1
SET SKIP OF PAD MenuTitleName OF MenuBarName2 lExpression2
SET SKIP OF POPUP MenuName1 lExpression3
SET SKIP OF BAR nMenuItemNumber | SystemItemName OF MenuName2
      lExpression4

Parameters

MENU MenuBarName1lExpression1

Enables or disables the Visual FoxPro system menu bar or user-defined menu bar created with DEFINE MENU. For example, the Visual FoxPro system menu bar _MSYSMENU can be disabled with this command:
Copy Code
SET SKIP OF MENU _MSYSMENU .T.
It can be enabled with this command:
Copy Code
SET SKIP OF MENU _MSYSMENU .F.
PAD MenuTitleNameOF MenuBarName2lExpression2

Enables or disables a Visual FoxPro system menu title or a user-defined menu title created with DEFINE PAD. For example, the Visual FoxPro Edit menu title can be disabled with this command:
Copy Code
SET SKIP OF PAD _MSM_EDIT OF _MSYSMENU .T.
The menu title can be enabled with this command:
Copy Code
SET SKIP OF PAD _MSM_EDIT OF _MSYSMENU .F.
POPUP MenuName1lExpression3

Enables or disables a Visual FoxPro system menu or a user-defined menu created with DEFINE POPUP. For example, the Visual FoxPro Edit menu can be disabled with this command:
Copy Code
SET SKIP OF POPUP _MEDIT .T.
The menu can be enabled with this command:
Copy Code
SET SKIP OF POPUP _MEDIT .F.
BAR nMenuItemNumber| SystemItemNameOF MenuName2lExpression4

Enables or disables a menu item on a Visual FoxPro system menu or a user-defined menu item created with DEFINE BAR. For example, the New command on the Visual FoxPro File menu can be disabled with this command:
Copy Code
SET SKIP OF BAR _MFI_NEW OF _MFILE .T.
where SystemItemName specifies the menu command _MFI_NEW, MenuName2 specifies the menu _MFILE, and lExpression4 specifies the logical expression .T.. The menu command can be enabled with this command:
Copy Code
SET SKIP OF BAR _MFI_NEW OF _MFILE .F.
Use nMenuItemNumber to specify a menu item created with DEFINE BAR.

Remarks

For a complete listing of the internal names of Visual FoxPro system menu components, see System Menu Names. You can also use SYS(2013) to return the system menu internal names.

If the logical expression lExpression evaluates to true (.T.), the menu, menu bar, menu name, or menu item included in SET SKIP OF is disabled, appears dimmed, and can't be selected. If lExpression evaluates to false (.F.), the menu, menu bar, menu name, or menu item is enabled and can be selected.

See Also

Other Resources

CREATE MENU Command
DEFINE BAR Command
DEFINE MENU Command
DEFINE PAD Command
DEFINE POPUP Command
SKPBAR( ) Function
Commands
Language Reference


SET SPACE Command

Visual FoxPro 9.0 Language Reference
SET SPACE Command
See Also

Determines whether a space is displayed between fields or expressions when you use the ? or ?? command.

SET SPACE ON | OFF

Parameters

ON

(Default) Inserts a space between fields and expressions.
OFF

Removes all spaces between fields or expressions and runs them together.

See Also

Other Resources

? | ?? Command
SPACE( ) Function
Commands
Language Reference


SET SQLBUFFERING Command

Visual FoxPro 9.0 Language Reference
SET SQLBUFFERING Command
See Also

Specifies if data in a SQL - SELECT statement is based on buffered data or data written to disk.

SET SQLBUFFERING ON | OFF

Parameters

ON

Specifies that the SQL - SELECT statement uses local buffered data if available. If data is not buffered, then data from disk is used.
OFF

(Default) Specifies that the SQL - SELECT statement uses data from disk.

Remarks

This SET command is scoped to the current data session. If you want more control at the table level, use the WITH (BUFFERING = ON | OFF) clause in the SQL - SELECT statement. It overrides the SET SQLBUFFERING statement.

You can use SET(“SQLBUFFERING”) to query the current setting.

See Also

Reference

SET Command Overview
SELECT - SQL Command
SELECT - SQL Command - WITH Clause


SET STATUS BAR Command

Visual FoxPro 9.0 Language Reference
SET STATUS BAR Command
See Also

Displays or removes the graphical status bar.

SET STATUS BAR ON | OFF

Parameters

ON

(Default) Issue SET STATUS BAR ON to display the graphical status bar.
OFF

Issue SET STATUS BAR OFF to remove the graphical status bar.

See Also

Other Resources

SET STATUS Command
StatusBarText Property
SET NOTIFY Command
StatusBar Property
Commands
Language Reference


SET STATUS Command

Visual FoxPro 9.0 Language Reference
SET STATUS Command
See Also

Displays or removes the character-based status bar.

SET STATUS ON | OFF

Parameters

ON

If SET STATUS is ON, the character-based status bar is displayed showing the name of the program currently executing (if any) the alias of the active table, the current record pointer position, the number of records in the table, and the state of the Insert, NumLock and CapsLock keys. The record or file lock status is also shown in the status bar when the table is opened for shared use. The status bar is updated each time you execute a command that changes status information.
OFF

(Default) Issue SET STATUS OFF to remove the status bar.

See Also

Other Resources

SET STATUS BAR Command
StatusBarText Property
NUMLOCK( ) Function
CAPSLOCK( ) Function
Commands
Language Reference


SET STEP Command

Visual FoxPro 9.0 Language Reference
SET STEP Command
See Also

Opens the Trace window and suspends program execution for debugging.

SET STEP ON

Parameters

ON

Opens the Trace window and suspends program execution.

Remarks

SET STEP is used to debug programs. You can insert SET STEP ON in a program at the point where you'd like to execute individual commands.

For information about the Trace Window, see Testing and Debugging Applications .

You can pass parameters to a program and then trace its execution by following these steps:

  1. Open the Trace window.

  2. From the Trace window's Program menu, choose Open and select the program to trace.

  3. Set a breakpoint on the first executable line of the program.

  4. In the Command window, DO the program WITH the parameters.

See Also

Other Resources

SET ECHO Command
Commands
Language Reference


SET STRICTDATE Command

Visual FoxPro 9.0 Language Reference
SET STRICTDATE Command
See Also

Specifies if ambiguous Date and DateTime constants generate errors.

SET STRICTDATE TO [0 | 1 | 2]

Parameters

0

Specifies that strict date format checking is off. This setting provides compatibility with earlier versions of Visual FoxPro. 0 is the default setting for the Visual FoxPro runtime and ODBC driver. When STRICTDATE is set to 0, invalid Date and DateTimes evaluate to the empty date.
1

Specifies that all Date and DateTime constants be in the strict date format. Any Date or DateTime constant that is not in the strict format or evaluates to an invalid value generates an error, either during compilation, at runtime, or during an interactive Visual FoxPro session. 1 is the default setting for an interactive Visual FoxPro session.
2

Identical to setting STRICTDATE to 1, but also generates a compilation error (2033 – CTOD and CTOT can produce incorrect results) whenever CTOD( ) and CTOT( ) functions appear in code. Because the values returned by CTOD( ) and CTOT( ) rely on SET DATE and SET CENTURY to interpret the date string they contain, they are prone to year 2000 noncompliance errors. Use DATE( ) and DATETIME( ) with the optional numeric arguments to create Date and DateTime constants and expressions. This setting is most useful during debugging sessions to trap for code that may contain year 2000 compliance errors.

Remarks

Note that the StrictDateEntry property isn't affected by the setting of SET STRICTDATE.

See Also

Other Resources

COMPILE Command
SET LOGERRORS Command
Commands
Language Reference


SET SYSFORMATS Command

Visual FoxPro 9.0 Language Reference
SET SYSFORMATS Command
See Also

Specifies whether Visual FoxPro for Windows system settings are updated with the current Microsoft Windows system settings.

SET SYSFORMATS ON | OFF

Parameters

ON

Specifies that the Visual FoxPro system settings are updated when the Windows system settings are changed. SET SYSFORMAT ON is identical to choosing the Use System Settings check box on the International tab of the Options dialog. Note that issuing SET SYSFORMAT ON changes the SET DATE setting to SHORT. The settings are used for the duration of the current data session, or, if issued during the default data session, for the duration of the Visual FoxPro session.
OFF

(Default) Specifies that the Visual FoxPro system settings are not updated when the Windows system settings are changed. The Visual FoxPro default settings are not restored.

Remarks

The Windows system settings are specified in International option of the Windows Control Panel.

When SET SYSFORMATS is ON, the following SET commands can be used to override the current system settings. However, changing the Windows system settings when SET SYSFORMATS is ON overrides these SET commands:

  • SET CENTURY

  • SET CURRENCY

  • SET DATE

  • SET DECIMALS

  • SET HOURS

  • SET MARK TO

  • SET POINT

  • SET SEPARATOR

When Visual FoxPro is started, the Visual FoxPro system settings are the default settings of these SET commands. To use the Windows system settings when Visual FoxPro is started, place the following line in your Visual FoxPro Config.fpw configuration file:

Copy Code
SYSFORMATS = ON

SET SYSFORMATS is scoped to the current data session.

See Also

Other Resources

SET CENTURY Command
SET CURRENCY Command
SET DATASESSION Command
SET DATE Command
SET DECIMALS Command
SET HOURS Command
SET MARK TO Command
SET POINT Command
SET SEPARATOR Command
Commands
Language Reference


SET SYSMENU Command

Visual FoxPro 9.0 Language Reference
SET SYSMENU Command
See Also

Enables or disables the Visual FoxPro system menu bar during program execution, and allows you to reconfigure it.

SET SYSMENU ON | OFF | AUTOMATIC | TO [MenuList] | TO [MenuTitleList]
   | TO [DEFAULT] | TO LTRJUSTIFY | TO RTLJUSTIFY | SAVE | NOSAVE

Parameters

ON

Enables the main Visual FoxPro menu bar during program execution when Visual FoxPro is waiting for keyboard input during commands such as BROWSE, READ, and MODIFY COMMAND.
OFF

Disables the main Visual FoxPro menu bar during program execution. The OFF parameter must be run from a program (.prg) in order to take effect. For example, the following code when run from a program will disable the main Visual FoxPro menu bar.
Copy Code
SET SYSMENU OFF
WAIT
AUTOMATIC

Makes the main Visual FoxPro menu bar visible during program execution. The menu bar is accessible and menu items are enabled and disabled as appropriate for the current command. AUTOMATIC is the default setting.
TO [MenuList] | TO [MenuTitleList]

Specifies a subset of menus or menu titles for the main Visual FoxPro menu bar. The menu or menu title list can contain any combination of menus or menu titles separated by commas. The internal names for the menus and menu titles are listed in the System Menu Names topic. For example, the following command removes all menus from the main Visual FoxPro menu bar except the File and Window menus:
Copy Code
SET SYSMENU TO _MFILE, _MWINDOW
Use RELEASE BAR to specify the menu items available in the menus.
TO [DEFAULT]

Restores the main menu bar to its default configuration. If you have modified the main menu bar or its menus, issue SET SYSMENU TO DEFAULT to restore it. You can specify a default configuration with SET SYSMENU SAVE.
TO LTRJUSTIFY | TO RTLJUSTIFY

Include the TO LTRJUSTIFY clause to order the menu commands in a left to right order. Include the TO RTLJUSTIFY clause to order the menu commands in a right to left order. These options are only available when Windows is configured to a Middle-Eastern locale.
Note:
You can include the RTLJUSTIFY option in the DEFINE POPUP Command to create a menu system with right to left justification.

SAVE

Makes the current menu system the default configuration. If you modify the menu system after issuing SET SYSMENU SAVE, you can restore the previous configuration by issuing SET SYSMENU TO DEFAULT.
NOSAVE

Resets the menu system to the default Visual FoxPro system menu. However, the default Visual FoxPro system menu is not displayed until you issue SET SYSMENU TO DEFAULT.

Remarks

SET SYSMENU controls the main Visual FoxPro menu bar during program execution and lets you selectively remove menu titles and menus from and restore them to the main Visual FoxPro menu system.

Issuing SET SYSMENU TO without additional arguments disables the main Visual FoxPro menu bar.

See Also

Other Resources

POP MENU Command
PUSH MENU Command
RELEASE Command
SYS(2013) – System Menu Name String
Commands
Language Reference


SET TABLEPROMPT Command

Visual FoxPro 9.0 Language Reference
SET TABLEPROMPT Command
See Also

Enables or disables display of the Open Dialog Box (Visual FoxPro) in commands that allow the user to select a table (or view) if one is not open.

SET TABLEPROMPT ON | OFF

Parameters

ON

(Default) The Open dialog box is displayed when no table or view is open, and a command is executed that requires an open table or view. The Visual FoxPro SELECT - SQL command looks for tables in all work areas in the current session. Other commands only look for a table in the current work area unless a work area is explicitly specified. The following are some of the commands affected by the TABLEPROMPT setting.

SELECT - SQL Command

DELETE - SQL Command

INSERT - SQL Command

UPDATE - SQL Command

BROWSE Command

GO | GOTO Command

INDEX Command

PACK Command

REPLACE Command (Visual FoxPro)

REPORT FORM Command

SET FILTER Command

SKIP Command

ZAP Command

OFF

The Open dialog box is suppressed when no table or view is open, and a command is executed that requires an open table or view. The command will fail and an error will be generated. Typical errors are File "name" does not exist (Error 1) and No table is open in the current work area (Error 52).

Remarks

You can use SET("TABLEPROMPT") to determine the current setting. You can also specify a startup value for TABLEPROMPT in the Config.fpw, the Visual FoxPro configuration file.

This feature is supported in COM server scenarios (MTDLL and DLL) where users do not have access to a user interface. SET TABLEPROMPT provides similar support in Visual FoxPro. You can use SYS(2335) - Unattended Server Mode to control modal states for COM servers.

See Also

Reference

Open Dialog Box (Visual FoxPro)
GETFILE( ) Function
Special Terms for Configuration Files


SET TABLEVALIDATE Command

Visual FoxPro 9.0 Language Reference
SET TABLEVALIDATE Command
See Also

Specifies the level of table validation to perform. Use SET TABLEVALIDATE when you want a lower level of table integrity checking than the default setting.

Note:
You must first open the table exclusively before using the SET TABLEVALIDATE command.

SET TABLEVALIDATE TO [nLevel]

Parameters

nLevel

Specifies the level of table validation as the sum of the bit values.
Note:
The default setting for nLevel is 3.

The following table describes the bits and bit values that you can add to obtain a setting for nLevel.

Bit number Bit value (additive) Description

0

0

Do not perform table validation.

0

1

Validate record count when opening a table.

Note:
The table (.dbf) header is locked during validation. This operation can result decreased scalability when tables open as shared, for example, when issuing the USE command with the SHARED keyword or calling the SQL SELECT, UPDATE, INSERT, or DELETE commands against a closed table, and SET EXCLUSIVE is set to OFF.

1

2

Validate record count when appending or inserting records and writing them to disk.

2

4

Suppress "File is in use (Error 3)" if table header cannot be locked when opening the table. Requires setting the first bit to validate record count when opening a table.

Note:
When opening a table, the USE command attempts to lock the table header only once. If the header is locked, Visual FoxPro performs a strict header check, similar to SET TABLEVALIDATE set to 1. Otherwise, Visual FoxPro suppresses the "File is in use" error and performs a header check in the manner of versions prior to Visual FoxPro 8.0.

3

8

Check .dbf header before saving append operation to disk and modifying header.

Remarks

SET TABLEVALIDATE does not have repair functionality; it performs only integrity checks as specified by nLevel.

SET TABLEVALIDATE does not perform table validation on temporary files or cursors.

You can set SET TABLEVALIDATE in Config.fpw as follows:

Copy Code
TABLEVALIDATE = nLevel

If a table opens exclusively, and SET TABLEVALIDATE is set to 8 or greater, the setting is disregarded.

See Also

Other Resources

SET Command Overview
USE Command
SELECT - SQL Command
INSERT - SQL Command
UPDATE - SQL Command
DELETE - SQL Command
Programming for Shared Access
Commands


SET TALK Command

Visual FoxPro 9.0 Language Reference
SET TALK Command
See Also

Determines whether Visual FoxPro displays command results.

SET TALK ON | OFF | WINDOW [WindowName] | NOWINDOW

Parameters

ON

(Default) Allows talk to be sent to the main Visual FoxPro window, the system message window, the graphical status bar, or a user-defined window. If SET TALK is set to OFF and is then changed to ON, the talk is directed to the same location it was sent to before you issued SET TALK OFF.
OFF

Prevents talk from being sent to the main Visual FoxPro window, the system message window, the graphical status bar, or a user-defined window. Note that for in-process .dll automation servers the default setting of SET TALK is OFF.
WINDOW [ WindowName]

WindowName specifies a user-defined window to which talk is directed. You must create the user-defined window before directing talk to it. Talk is directed to the Visual FoxPro system window if the window you specify doesn't exist.
NOWINDOW

Directs talk to the main Visual FoxPro window.

Remarks

Some table processing commands return information, or "talk," about their status while they execute. These commands include:

Commands

APPEND FROM | PACK
AVERAGE | REINDEX
CALCULATE | REPLACE
COPY TO | SELECT - SQL
COUNT | SORT
DELETE | SUM
INDEX | TOTAL

Talk can be directed to the main Visual FoxPro window, the graphical status bar, or a user-defined window. Talk can also be turned off.

The SET TALK reporting interval can be specified with SET ODOMETER. The default value for SET ODOMETER is 100. Note that execution speed can be degraded when SET TALK is set to ON, because the main Visual FoxPro window or user-defined window must be frequently updated. If you just need the total number of records processed by a command, you can issue SET TALK OFF and display the _TALLY system variable once the command has completed executing.

SET TALK is scoped to the current data session.

See Also

Other Resources

DEFINE WINDOW Command
SET DATASESSION Command
SET NOTIFY Command
SET ODOMETER Command
SYS(103) - Talk Setting
_TALLY System Variable
Commands
Language Reference


SET TEXTMERGE Command

Visual FoxPro 9.0 Language Reference
SET TEXTMERGE Command
See Also

Enables or disables the evaluation of fields, variables, array elements, functions, or expressions that are surrounded by text-merge delimiters, and lets you specify text-merge output.

SET TEXTMERGE [ON | OFF] [TO [FileName] MEMVAR VarName [ADDITIVE]]
   [WINDOW WindowName] [SHOW | NOSHOW]

Parameters

ON

Specifies that any fields, variables, array elements, functions, or expressions surrounded by the text-merge delimiters be evaluated and output when placed after \ or \\, or between TEXT and ENDTEXT. The following short program example demonstrates how the contents of the variable gcTodayDate and the DATE( ) and TIME( ) functions are evaluated when SET TEXTMERGE is set to ON. The variable gcTodayDate, DATE( ), and TIME( ) are evaluated because they are enclosed by the text-merge delimiters and SET TEXTMERGE is set to ON.
Copy Code
CLEAR
SET TALK OFF
STORE 'Today is: ' TO gcTodayDate
SET TEXTMERGE ON
\<<gcTodayDate>>
\\<<DATE( )>>
\The time is:
\\ <<TIME( )>>
Here is the output from the program above when run on January 1:
Copy Code
Today is: 01/01/98
The time is: 10:55:19
OFF

(Default) Specifies that any fields, variables, array elements, functions, or expressions be literally output along with the text-merge delimiters surrounding them. Note the difference in output when SET TEXTMERGE is set to OFF in the previous example:
Copy Code
CLEAR
SET TALK OFF
STORE 'Today is: ' TO gcTodayDate
SET TEXTMERGE OFF
\<<gcTodayDate>>
\\<<DATE( )>>
\The time is:
\\ <<TIME( )>>
Here is the output from this program:
Copy Code
<<gcTodayDate>><<DATE( )>>
The time is: <<TIME( )>>
TO [ FileName]

Specifies that output from \, \\, and TEXT ... ENDTEXT be directed to a text file in addition to the main Visual FoxPro window, which is the default. You can also direct the output to a text file by including FileName. If a file with that name doesn't exist, a new file is created. If a file with the same name already exists and SET SAFETY is set to ON, you are given the option of overwriting the existing file. The text file is opened as a low-level file, and its file handle is stored to the _TEXT system variable. You can close the file by issuing SET TEXTMERGE TO without additional arguments. If the file handle of another file was previously stored in _TEXT, that file is closed.
MEMVAR VarName

Specifies a variable to contain data from TEXTMERGE output. Because SET TEXTMERGE is a global setting and can span several procedures or methods, it is possible for MEMVAR VarName to lose scope. The command will function even when the variable is out of scope, but will return no content. You can control scooping of MEMVAR VarName by declaring the variable PUBLIC or PRIVATE. This clause can also create recursive behavior, which you can control with the SET TEXTMERGE TO command, as in the following example:
Copy Code
USE LABELS
STORE "" to myVar, myVar2

SET TEXT ON NOSHOW
SET TEXTMERGE TO MEMVAR myVar && TEXTMERGE begins on the next line.

\Hey Now
\<<date()>>

SCAN
   \  <<name>>
ENDSCAN

* Remove comments from SET TEXTMERGE TO line to eliminate recursive
* error with myVar and myVar2.
* SET TEXTMERGE TO

TEXT TO myVar2
<b> Here's some HTML. </b>
This is HTML
   <<date()>>
ENDTEXT

SET TEXTMERGE OFF
USE

CLEAR
? myVar  && But has also stored the TEXTMERGE contents to variables
? myVar2
ADDITIVE

Specifies that output from \, \\, and TEXT ... ENDTEXT be appended to an existing file or memory variable. For more information on directing text-merge output to a file, see _TEXT System Variable.
WINDOW WindowName

Specifies that output from \, \\, and TEXT ... ENDTEXT be directed to a user-defined window rather than the main Visual FoxPro window, which is the default. WindowName specifies the name of the window to which you want to direct output. The window must be created with DEFINE WINDOW before output can be sent to it. The window doesn't have to be active or visible.
SHOW | NOSHOW

(Default) SHOW displays text-merge output. NOSHOW suppresses display of text-merge output. By default, output generated by \, \\, and TEXT ... ENDTEXT is sent to the main Visual FoxPro window or an active user-defined window.

Remarks

The \, \\, and TEXT ... ENDTEXT commands are used to merge text with the contents of tables, variables, array elements, and the results of functions and expressions. If a field, variable, array element, function, or expression is surrounded by text-merge delimiters (by default, << and >>), it can be evaluated and merged with text. This text-merge capability lets you produce letters, programs, and templates that create programs.

SET TEXTMERGE determines how fields, variables, array elements, functions, or expressions surrounded by text-merge delimiters are evaluated. It also lets you direct text-merge output to the main Visual FoxPro window, a user-defined window, or a file.

Memo fields can be used to nest merged text. If a memo field contains field names, variables, array elements, functions, or expressions surrounded by the current text-merge delimiters, these are evaluated and output with the contents of the memo field. The memo field name must also be enclosed in text-merge delimiters.

See Also

Other Resources

\ | \\ Command
_PRETEXT System Variable
SET TEXTMERGE DELIMITERS Command
TEXTMERGE( ) Function
TEXT ... ENDTEXT Command
Commands
Language Reference


SET TEXTMERGE DELIMITERS Command

Visual FoxPro 9.0 Language Reference
SET TEXTMERGE DELIMITERS Command
See Also

Specifies the set of text-merge delimiter characters to use other than the default.

SET TEXTMERGE DELIMITERS [TO cLeftDelimiter [, cRightDelimiter]]

Parameters

[TO cLeftDelimiter[, cRightDelimiter]]

Specifies the delimiters to use. You can specify a maximum number of two delimiter characters. The default delimiter characters are the double angle brackets (<< and >>).
Note:
If you specify only one set of delimiter characters with cLeftDelimiter, both the left and right delimiter characters are set to cLeftDelimiter. If you specify both sets of delimiter characters with cLeftDelimiter and cRightDelimiter, the first set of delimiter characters is set to cLeftDelimiter and the second set of delimiter characters is set to cRightDelimiter.

Tip:
To restore the default delimiter characters, call SET TEXTMERGE DELIMITERS without arguments.

Remarks

You can display the current delimiters used with the DISPLAY STATUS command.

For more information about text-merge delimiter characters, see SET TEXTMERGE Command.

See Also

Other Resources

\ | \\ Command
_PRETEXT System Variable
SET TEXTMERGE Command
_TEXT System Variable
Commands
Language Reference


SET TOPIC Command

Visual FoxPro 9.0 Language Reference
SET TOPIC Command
See Also

Specifies the Help topic or topics to open when you invoke the Visual FoxPro Help system.

SET TOPIC TO [cHelpTopicName | lExpression]

Parameters

cHelpTopicName

Specifies the name of the Help topic you want to display.
lExpression

A logical expression that is the basis for opening a specific topic or topics.

Remarks

See Also

Other Resources

HELP Command
SET HELP Command
SET TOPIC ID Command
Commands
Language Reference


SET TOPIC ID Command

Visual FoxPro 9.0 Language Reference
SET TOPIC ID Command
See Also

Specifies the Help topic to display when you invoke the Visual FoxPro Help system. The Help topic is based on the topic's context ID.

SET TOPIC ID TO nHelpContextID

Parameters

nHelpContextID

Specifies the Help topic to display, based on a numerical context ID. nHelpContextID is a context number in the MAP section of the Help project file.

See Also

Other Resources

SET HELP Command
SET TOPIC Command
Commands
Language Reference


SET TRBETWEEN Command

Visual FoxPro 9.0 Language Reference
SET TRBETWEEN Command
See Also

Enables or disables tracing between breakpoints in the Trace Window.

SET TRBETWEEN ON | OFF

Parameters

ON

Specifies that every line of program code be displayed and highlighted in the Trace window as it is executed. Issuing SET TRBETWEEN ON is identical to enabling the Trace Between Breaks command in the Trace window's Program menu.
OFF

(Default) Specifies that only the last line at which program execution was paused be highlighted in the Trace window. Issuing SET TRBETWEEN OFF is identical to disabling the Trace Between Breaks command.

Remarks

The Trace window displays the source code for a program as the program executes. The executing program line is highlighted. When the Trace window is open, you can set breakpoints that cause program execution to stop.

The Trace window can also be opened by issuing ACTIVATE WINDOW TRACE, SET ECHO ON, or SET STEP ON.

See Also

Other Resources

ACTIVATE WINDOW Command
SET ECHO Command
SET STEP Command
SET Command Overview
Commands
Language Reference


SET TYPEAHEAD Command

Visual FoxPro 9.0 Language Reference
SET TYPEAHEAD Command
See Also

Specifies the maximum number of characters that can be stored in the type-ahead buffer.

SET TYPEAHEAD TO nCharacters

Parameters

nCharacters

Specifies the maximum number of characters to store in the type-ahead buffer. No characters are held in the type-ahead buffer if you issue SET TYPEAHEAD TO 0. This statement deactivates INKEY( ) and ON KEY.

Remarks

The type-ahead buffer can store as many as 32,000 characters until they are ready to be processed. The default value for SET TYPEAHEAD is 20.

See Also

Other Resources

INKEY( ) Function
ON KEY Command
TYPE Command
SET Command Overview
Commands
Language Reference


SET UDFPARMS Command

Visual FoxPro 9.0 Language Reference
SET UDFPARMS Command
See Also Example

Specifies whether Visual FoxPro passes variables by value or by reference to parameters in procedures and user-defined functions (UDFs).

SET UDFPARMS TO VALUE | REFERENCE

Parameters

TO VALUE

Pass variables to parameters by value. When passing variables by value, the procedure or function can change the value in the variable; however, the original value of the variable in the calling program does not change. (Default)
Note:
Using SET UDFPARMS TO VALUE does not affect the WITH clause in the DO command, which, by default, passes arguments to parameters by reference.

TO REFERENCE

Pass variables to parameters by reference. When passing variables by reference, the procedure or function can change the value in the variable, which changes the original value of the variable in the calling program.

Remarks

Regardless of the setting of SET UDFPARMS, you can force passing of variables by value or reference. For more information, see How to: Pass Parameters by Reference and How to: Pass Parameters by Value.

Example

The following example illustrates the difference between passing variables by value and by reference.

Copy Code
*** Pass variable by value. ***
CLEAR
SET TALK OFF
WAIT 'Press a key to pass by value' WINDOW
SET UDFPARMS TO VALUE
STORE 1 TO gnX

*** The value of gnX does not change. ***
@ 2,2 SAY 'UDF value: ' + STR(plusone(gnX))
@ 4,2 SAY 'Value of gnX: ' + STR(gnX)

*** Pass variable by reference ***
WAIT 'Press a key to pass by reference' WINDOW
CLEAR
SET UDFPARMS TO REFERENCE
STORE 1 TO gnX
*** The value of gnX changes. ***
@ 2,2 SAY 'UDF value: ' + STR(plusone(gnX))
@ 4,2 SAY 'Value of X: ' + STR(gnX)
SET UDFPARMS TO VALUE

*** This is a UDF that adds one to a number ***
FUNCTION plusone
PARAMETER gnZ
gnZ = gnZ + 1
RETURN gnZ
*** End of UDF ***

The following is the above example with variables passed by value and reference through the use of parentheses and @, respectively.

Copy Code
*** Pass variable by value ***
CLEAR
SET TALK OFF
WAIT 'Press a key to pass by value' WINDOW
STORE 1 TO gnX
@ 2,2 SAY 'UDF value: ' + STR(plusone((gnX)))
@ 4,2 SAY 'Value of gnX: ' + STR(gnX)

*** Pass variable by reference ***
WAIT 'Press a key to pass by reference' WINDOW
CLEAR
STORE 1 TO gnX
@ 2,2 SAY 'UDF value: ' + STR(plusone(@gnX))
@ 4,2 SAY 'Value of gnX: ' + STR(gnX)

*** This is a UDF that adds one to a number ***
FUNCTION plusone
PARAMETER gnZ
gnZ = gnZ + 1
RETURN gnZ
*** End of UDF ***

See Also

Other Resources

Passing Data to Parameters
Parameters in Procedures and Functions
SET Command Overview
Commands


SET UNIQUE Command

Visual FoxPro 9.0 Language Reference
SET UNIQUE Command
See Also

Specifies whether records with duplicate index key values are maintained in an index file.

SET UNIQUE ON | OFF

Parameters

ON

Specifies that any record with a duplicate index key value not be included in the index file. Only the first record with the original index key value is included in the index file.
OFF

(Default) Specifies that records with duplicate index key values be included in the index file.

Remarks

An index file retains its SET UNIQUE setting when you issue REINDEX. For more information, see INDEX and REINDEX.

SET UNIQUE is scoped to the current data session.

See Also

Other Resources

UNIQUE( ) Function
ATAGINFO( ) Function
SET DATASESSION Command
SET Command Overview
Commands
Language Reference


SET VARCHARMAPPING Command

Visual FoxPro 9.0 Language Reference
SET VARCHARMAPPING Command
See Also

Specifies how character data expressions are mapped to query result sets.

SET VARCHARMAPPING ON | OFF

Parameters

ON

Character data expressions are mapped to Varchar Field Type in query result sets.
OFF

(Default) Character data expressions are mapped to character type fields in query result sets.

Remarks

The VARCHARMAPPING setting determines how character data expressions are mapped into query result sets created with the SELECT - SQL Command and the Query and View Designers.

In scenarios where you want a query result to use fixed length character fields, SET VARCHARMAPPING to OFF so character fields are not mapped to variable length varchar type fields.

In the following example, the absence of character data expressions implies the character data should be preserved in its original format, include padding to maintain the fixed length of the character fields. In this case you should SET VARCHARMAPPING to OFF. SET VARCHARMAPPING to OFF to mimic the behavior in Visual FoxPro 8.0 and earlier versions.

Copy Code
SELECT * FROM customers
***   -or-
SELECT companyname, contactname FROM customers

In the next example, the presence of character data expressions means the query result set will contain character data of variable length. Here you may want the result set to use variable length Varchar type fields to prevent the results from being padded with extra characters. In this case you should SET VARCHARMAPPING to ON.

Copy Code
SELECT ALLTRIM(companyname), ALLTRIM(contactname) FROM customers

The VARCHARMAPPING setting also controls mapping of field expressions using PADL( ) | PADR( ) | PADC( ) Functions where the second parameter is not constant.

Copy Code
SELECT LEN(PADR(field1,field2)) FROM customers INTO CURSOR tmpcusts

The VARCHARMAPPING setting is scoped to the current data session. This command is supported both at design time and at run time, and can also be set in Config.fpw, the Visual FoxPro configuration file. See Special Terms for Configuration Files for information on setting VARCHARMAPPING in Config.fpw.

If you are using calculated fields such as those created by using the SET FIELDS Command, the VARCHARMAPPING setting will affect how this field is treated. If the calculated field evaluates to a character expression of variable length, such as following example, the field will be treated as a Varchar type if SET VARCHARMAPPING is ON. This can impact subsequent usage of that field such as with the COPY TO Command.

Copy Code
SET VARCHARMAPPING ON
SET SAFETY OFF
CLOSE DATABASES ALL
USE HOME(2) + 'Northwind\Customers'
SET FIELDS GLOBAL
SET FIELDS TO cField = ALLTRIM(CompanyName)
COPY TO crsTemp
SET FIELDS LOCAL
SET FIELDS OFF
SET FIELDS TO
SELECT 0
USE crsTemp
LIST STRUCTURE

See Also

Reference

Visual FoxPro Data and Field Types
SELECT - SQL Command

Other Resources

Query and View Designers


SET VIEW Command

Visual FoxPro 9.0 Language Reference
SET VIEW Command
See Also

Opens or closes the Data Session window or restores the Visual FoxPro environment from a view file.

SET VIEW ON | OFF
-or-
SET VIEW TO FileName | ?

Parameters

ON

Opens the Data Session window.
OFF

(Default) Closes the Data Session window.
TO FileName

Restores the Visual FoxPro environment to the state it was in when the view file specified with FileName was created. View files are created with CREATE VIEW.
?

Displays the Open dialog box, from which you can open a view file.

Remarks

For more information on view files, see CREATE VIEW.

See Also

Other Resources

SET Command Overview
Data Session Window
Commands
Language Reference


SHOW MENU Command

Visual FoxPro 9.0 Language Reference
SHOW MENU Command
See Also Example

Displays one or more user-defined menu bars without activating them.

SHOW MENU MenuBarName1 [, MenuBarName2 ...] | ALL   [PAD MenuTitleName]
   [SAVE]

Parameters

MenuBarName1 [, MenuBarName2 ...]

Specifies the name of one or more menu bars to display.
ALL

Displays all currently defined menu bars.
PAD MenuTitleName

Specifies a menu title to be highlighted on a menu bar.
SAVE

Retains an image of the specified menu bars without activating them. You can clear the menu bar images with CLEAR.

Remarks

The menu bars are displayed but cannot be used. Before they can be displayed, you must first create the menu bars with DEFINE MENU.

Example

Copy Code
CLEAR
DEFINE MENU mnuExample BAR AT LINE 2
DEFINE PAD padConv OF mnuExample PROMPT '\<Conversions' COLOR SCHEME 3 ;
   KEY ALT+C, ''
DEFINE PAD padCard OF mnuExample PROMPT 'Card \<Info' COLOR SCHEME 3 ;
   KEY ALT+I, ''
SHOW MENU mnuExample

See Also

Other Resources

ACTIVATE MENU Command
CREATE MENU Command
DEFINE MENU Command
Commands
Language Reference


SHOW POPUP Command

Visual FoxPro 9.0 Language Reference
SHOW POPUP Command
See Also

Displays one or more menus defined with DEFINEPOPUP without activating them.

SHOW POPUP MenuName1 [, MenuName2 ...] | ALL    [SAVE]

Parameters

MenuName1 [, MenuName2 ...]

Specifies the name of one or more menus to display.
ALL

Displays all currently defined menus.
SAVE

Retains an image of the specified menus without activating them. The menu images can be cleared with CLEAR.

Remarks

The menus are displayed but cannot be used. Before they can be shown, the menus must first be created with DEFINEPOPUP.

See Also

Other Resources

ACTIVATE POPUP Command
DEFINE POPUP Command
DEACTIVATE POPUP Command
CLEAR Commands
Commands
Language Reference


SHOW WINDOW Command

Visual FoxPro 9.0 Language Reference
SHOW WINDOW Command
See Also Example

Displays one or more user-defined windows or Visual FoxPro system windows without activating them.

SHOW WINDOW WindowName1 [, WindowName2 ...] | ALL | SCREEN
   [IN [WINDOW] WindowName3   [REFRESH]   [TOP | BOTTOM | SAME]   [SAVE]

Parameters

WindowName1 [, WindowName2...]

Specifies the name of one or more windows to display.
ALL

Displays all user-defined windows.
SCREEN

Displays the main Visual FoxPro window when it is hidden. You can also choose Screen from the Window menu to display the main Visual FoxPro window. You can hide the main Visual FoxPro window by clicking its close box or issuing DEACTIVATE WINDOW SCREEN, HIDE WINDOW SCREEN, or RELEASE WINDOW SCREEN.
IN [WINDOW] WindowName3

Displays the window inside a parent window specified with WindowName3. The window does not assume the characteristics of the parent window. A window displayed inside a parent window cannot be moved outside the parent window. If the parent window is moved, the child window moves with it. The parent window specified with WindowName3 must first be created with DEFINE WINDOW.
IN SCREEN

Explicitly displays the window in the main Visual FoxPro window instead of in another window. Windows are placed in the main Visual FoxPro window by default.
REFRESH

Redraws a Browse window. This option is useful on a network to ensure that you are browsing the most current version of a table. The work area for the Browse window table is selected. Memo-editing windows are refreshed with changes made to the memo field by other users on a network. SET REFRESH determines the interval between memo-editing-window refreshes. Refer to SET REFRESH for additional information on how data is refreshed in tables opened for shared use on a network.
TOP

Places the specified window in front of all other windows.
BOTTOM

Places the specified window behind all other windows.
SAME

Places the specified window back into a stack of windows in the same position the window occupied before it was deactivated. SAME affects only windows that have been previously displayed or activated and then cleared from the main Visual FoxPro window with DEACTIVATE WINDOW.
SAVE

Keeps an image of the window in the main Visual FoxPro window or in another window after the window is released. Normally, windows are removed from the main Visual FoxPro window after they are released. The window image can be cleared from the main Visual FoxPro window or a window with CLEAR.

Remarks

SHOW WINDOW controls the display and front-to-back screen placement of windows. If a window is hidden or has not been activated, SHOW WINDOW displays the window without activating it. If one or more windows are currently displayed, SHOW WINDOW lets you change the front-to-back order of the windows.

You can also display system windows, such as the Command window.

In Visual FoxPro, you can use SHOW WINDOW to display the Visual FoxPro toolbars. Use HIDE WINDOW to remove a toolbar from the FoxPro window. Toolbars must be active before they can be displayed. The following table lists the Visual FoxPro toolbars names to use in SHOW WINDOW and HIDE WINDOW. Enclose the toolbar name in quotation marks.

Toolbar Names |  |
Color Palette | Layout | Report Designer
Database Designer | Print Preview | Standard
Form Controls | Query Designer | View Designer
Form Designer | Report Controls |

To show a system window, enclose the entire system window name in quotation marks.

You cannot specify where output is directed to user-defined windows with SHOW WINDOW. Use ACTIVATE WINDOW to direct output to a user-defined window created with DEFINE WINDOW.

Historically in prior versions of Visual FoxPro, the Data Session window has always been referred to as the View window. Additionally, language used to control this window, such as HIDE WINDOW, ACTIVATE WINDOW, WONTOP( ), also refers to this window as the View window. Visual FoxPro continues to refer to the View window for the SHOW WINDOW command.

Example

The following example, a window named wOutput1 is created and displayed. Since SHOW WINDOW is used to display the window, output cannot be directed to the window until it is activated.
Copy Code
CLEAR
DEFINE WINDOW wOutput1 FROM 2,1 TO 13,75 TITLE 'Output' ;
   CLOSE FLOAT GROW ZOOM
SHOW WINDOW wOutput1

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
CLEAR Commands
Commands
Language Reference


SIZE POPUP Command

Visual FoxPro 9.0 Language Reference
SIZE POPUP Command
See Also Example

Changes the size of a menu created with DEFINE POPUP.

SIZE POPUP MenuName TO nRow1, nColumn1 | BY nRow2, nColumn2

Parameters

MenuName

Specifies the name of the menu whose size you want to change.
TO nRow1, nColumn1

Changes the size of a menu to a specific size. nRow1 and nColumn1 specify the new row and column coordinates, respectively, of the lower-right corner of the menu.
BY nRow2, nColumn2

Changes the size of a menu relative to its current size. nRow2 and nColumn2 specify the change in size of the menu in rows and columns, relative to the current row and column coordinates of the lower-right corner of the menu.

Remarks

If a user-defined menu has been created, its size can be changed; it doesn't have to be active or visible.

Example

This example creates a menu containing files with a .prg extension and moves, enlarges, and shrinks the menu before closing it.
Copy Code
CLEAR
DEFINE POPUP popMovIn FROM 2,2 TO 7, 14 PROMPT FILES LIKE *.PRG ;
   TITLE 'Programs'
ACTIVATE POPUP popMovIn NOWAIT
=CHRSAW(2)
MOVE POPUP popMovIn BY 5,5     && Move popup down
=CHRSAW(2)
SIZE POPUP popMovIn BY 5,5  && Enlarge the popup
=CHRSAW(2)
SIZE POPUP popMovIn BY -5,-5  && Shrink the popup
=CHRSAW(2)
MOVE POPUP popMovIn BY -5,-5  && Move popup up
=CHRSAW(2)
DEACTIVATE POPUP popMovIn
RELEASE POPUP popMovIn

See Also

Other Resources

ACTIVATE POPUP Command
CLEAR Commands
DEFINE POPUP Command
Commands
Language Reference


SIZE WINDOW Command

Visual FoxPro 9.0 Language Reference
SIZE WINDOW Command
See Also

Changes the size of a window created with DEFINE WINDOW or a Visual FoxPro system window.

SIZE WINDOW WindowName TO nRow1, nColumn1 | BY nRow2, nColumn2

Parameters

WindowName

Specifies the name of the window whose size you want to change. To change the size of a system window, enclose the entire system window name in quotation marks. For example, to increase the size of the Command window by 1 row and 1 column, issue the following command:
Copy Code
SIZE WINDOW 'Command Window' BY 1,1
You can only change the size of the Command, Debug, and Trace windows.
TO nRow1, nColumn1

Changes the size of a window to a specific size. nRow1 and nColumn1 specify the new row and column coordinates, respectively, of the lower-right corner of the window relative to the upper-left corner of the window.
BY nRow2, nColumn2

Changes the size of a window relative to its current size. nRow2 and nColumn2 specify the change in size of the window in rows and columns, relative to the current row and column coordinates of the lower-right corner of the window.

Remarks

If a user-defined window has been created, its size can be changed; it doesn't have to be active or visible.

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
ZOOM WINDOW Command
Commands
Language Reference


SKIP Command

Visual FoxPro 9.0 Language Reference
SKIP Command
See Also Example

Moves the record pointer forward or backward in a table.

SKIP   [nRecords]   [IN nWorkArea | cTableAlias]

Parameters

nRecords

Specifies the number of records to move the record pointer. Issuing SKIP without nRecords advances the record pointer to the next record. The record pointer moves toward the end of the file nRecords records if nRecords evaluates to a positive number. The record pointer moves toward the beginning of the file nRecords records if nRecords evaluates to a negative number. If the record pointer is positioned on the last record of a table and SKIP with no arguments is executed, RECNO( ) returns a value 1 greater than the number of records in the table and EOF( ) returns true (.T.). If the record pointer is positioned on the first record of a table and SKIP –1 is executed, RECNO( ) returns 1 and BOF( ) returns true (.T.).
IN nWorkArea | cTableAlias

Moves the record pointer in a table in a specific work area. nWorkArea specifies the work area number and cTableAlias specifies a table or work area alias.

Remarks

If the table has a master controlling index tag or index file, SKIP moves the record pointer to the record determined by the index sequence.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Opens Customer table
CLEAR

SKIP 4 IN 'customer'
? RECNO('customer')  && Displays 5
GO BOTTOM
SKIP -5
? RECNO( )

See Also

Other Resources

GO | GOTO Command
SET SKIP Command
CLEAR Commands
Commands
Language Reference


SORT Command

Visual FoxPro 9.0 Language Reference
SORT Command
See Also

Sorts records in the currently selected table and outputs the sorted records to a new table.

SORT TO TableName ON FieldName1 [/A | /D] [/C]
   [, FieldName2 [/A | /D] [/C] ...]   [ASCENDING | DESCENDING]
   [Scope] [FOR lExpression1] [WHILE lExpression2]
   [FIELDS FieldNameList   | FIELDS LIKE Skeleton
   | FIELDS EXCEPT Skeleton]   [NOOPTIMIZE]

Parameters

TableName

Specifies the name of the new table containing the sorted records. Visual FoxPro assumes a .dbf file name extension for tables. A .dbf extension is automatically assigned if the file name you include doesn't have an extension.
ON FieldName1

Specifies the field in the currently selected table on which the sort is based. The contents and data type of the field determine the order of the records in the new table. By default, the sort is done in ascending order. You can't sort on memo or general fields. The following example sorts a table on the cust_id field. The customer table is opened and sorted, creating a new table named temp. The records in temp are ordered by the cust_id field.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Opens Customer table
CLEAR
LIST FIELDS company, cust_id NEXT 3
SORT TO temp ON cust_id
USE temp
LIST FIELDS company, cust_id NEXT 3
WAIT WINDOW 'Now sorted on CUST_ID' NOWAIT
You can include additional field names (FieldName2, FieldName3) to further order the new table. The first field FieldName1 is the primary sort field, the second field FieldName2 is the secondary sort field, and so on.
[/A | /D] [/C]

For each field you include in the sort, you can specify an ascending or descending sort order. /A specifies an ascending order for the field. /D specifies a descending order. /A or /D can be included with any type of field. By default, the field sort order for character fields is case sensitive. If you include the /C option after the name of a character field, case is ignored. You can combine the /C option with the /A or /D option. For example, /AC or /DC. In the following example, a new table named clients is created. The orders table is sorted on the order_date field in ascending order and the freight field in descending order.
Copy Code
USE orders
SORT TO clients ON order_date/A,freight/D
ASCENDING

Specifies an ascending order for all fields not followed by /D.
DESCENDING

Specifies a descending order for all fields not followed by /A. If you omit either ASCENDING or DESCENDING, the sort order is ascending by default.
Scope

Specifies a range of records to sort. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. The default scope for SORT is ALL records.
FOR lExpression1

Specifies that only the records in the current table for which the logical condition lExpression1 evaluates to true (.T.) are included in the sort. Including FOR lets you conditionally sort records, filtering out undesired records. Rushmore Query Optimization optimizes a SORT ... FOR command if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. A discussion of expressions that Rushmore can optimize appears in Optimizing Applications.
WHILE lExpression2

Specifies a condition whereby records from the current table are included in the sort for as long as the logical expression lExpression2 evaluates to true (.T.).
FIELDS FieldNameList

Specifies fields from the original table to include in the new table that SORT creates. If you omit the FIELDS clause, all fields from the original table are included in the new table.
FIELDS LIKE Skeleton

Specifies that fields from the original table that match the field skeleton Skeleton are included in the new table that SORT creates.
FIELDS EXCEPT Skeleton

Specifies that all fields except those that match the field skeleton Skeleton are included in the new table that SORT creates. The field skeleton Skeleton supports wildcards. For example, to specify that all fields that begin with the letters A and P are included in the new table, use the following:
Copy Code
SORT TO mytable ON myfield FIELDS LIKE A*,P*
The LIKE clause can be combined with the EXCEPT clause:
Copy Code
SORT TO mytable ON myfield FIELDS LIKE A*,P* EXCEPT PARTNO*
NOOPTIMIZE

Disables Rushmore optimization of SORT. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

Remarks

One or more specified fields in the current table determine the order in which the records appear in the new table.

Caution:
Be sure you have enough disk space for the new table and the temporary work files created during the sort. The disk space needed to perform a sort can be as much as three times the size of the source table. The amount of available disk space can be determined with DISKSPACE() and SYS(2020). If you run out of disk space during a sort, Visual FoxPro displays an error message, and the temporary work files are deleted.

Character-type fields that contain numbers and spaces might not sort in the order you expect. Numeric fields fill from right to left, with empty spaces to the left. In contrast, character fields fill from left to right, with empty spaces to the right.

For example, if two records in a table contain a character field with 1724 in one record and 18 in the other, and the table is sorted on this field in ascending order, the record containing 1724 appears before the record containing 18. This is because Visual FoxPro reads each character in the character fields from left to right, and because 17 (in 1724) is less than 18 (in 18), it puts 1724 first. To avoid this problem, always precede lower numbers with leading zeros (0018) or make the field numeric.

See Also

Other Resources

COPY FILE Command
DISKSPACE( ) Function
INDEX Command
SYS(2020) - Default Disk Size
Commands
Language Reference


STORE Command

Visual FoxPro 9.0 Language Reference
STORE Command
See Also Example

Stores data to a variable, to an array, or to an array element.

STORE eExpression TO VarNameList | ArrayNameList-or-
VarName | ArrayName = eExpression

Parameters

eExpression

Specifies an expression whose value is stored to the variable, array, or array element. If the variable doesn't exist, it is created and initialized to eExpression. An array must be previously defined with DIMENSION. STORE replaces the value in an existing variable, array, or array element with the new value.
VarNameList

Specifies a list of variables or array elements to which eExpression is stored. Separate the names or array elements with commas.
ArrayNameList

Specifies a list of names of existing arrays to which eExpression is stored. Separate array names with commas. STORE initializes every element in the arrays to the specified value if SET COMPATIBLE is OFF. STORE stores the specified value to memory variables of the specified names if SET COMPATIBLE is ON, overwriting any existing arrays that have those names.

Remarks

An alternative to STORE is the equal sign (=) assignment operator. The variable, array, or array element must be on the left side of the equal sign and its value on the right side.

Dates can be stored directly to variables, arrays, or array elements by using braces:

Copy Code
STORE {^1998-12-25} TO gdXMas

The maximum number of variables or arrays you can create is listed in the System Capacities topic. The limit can be increased or decreased in your Visual FoxPro configuration file. For more information on configuring Visual FoxPro, see Customizing the Visual FoxPro Environment.

Example

Copy Code
STORE DATE( ) TO gdDate
STORE 50 TO gnNumeric
STORE 'Hello' TO gcCharacter
STORE .T. TO glLogical
STORE $19.99 TO gyCurrency

DIMENSION gaMyArray(2,2)
SET COMPATIBLE OFF
STORE 2 TO gaMyArray

CLEAR
DISPLAY MEMORY LIKE g*

See Also

Other Resources

DIMENSION Command
SET COMPATIBLE Command
System Capacities
Commands
Language Reference


SUM Command

Visual FoxPro 9.0 Language Reference
SUM Command
See Also Example

Totals all or specified numeric fields in the currently selected table.

SUM [eExpressionList]   [Scope] [FOR lExpression1] [WHILE lExpression2]
   [TO MemVarNameList | TO ARRAY ArrayName]   [NOOPTIMIZE]

Parameters

eExpressionList

Specifies one or more fields or field expressions to total. If you omit the field expression list, all numeric fields are totaled.
Scope

Specifies a range of records to include in the total. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see Scope Clauses. The default scope for SUM is ALL records.
FOR lExpression1

Specifies that only the records for which the logical condition lExpression1 evaluates to true (.T.) are included in the total. Including FOR makes it possible for you to conditionally total records, filtering out undesired records. Rushmore Query Optimization optimizes a SUM ... FOR command if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For more information on Rushmore optimization, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies a condition whereby records from the current table are included in the total for as long as the logical expression lExpression2 evaluates to true (.T.).
TO MemVarNameList

Stores each total to a variable. If you specify a variable in MemVarNameList that doesn't exist, Visual FoxPro automatically creates it. Separate the variable names in the list with commas.
TO ARRAY ArrayName

Stores totals to a variable array. If the array you specify in SUM doesn't exist, Visual FoxPro automatically creates it. If the array exists and is too small to contain all the totals, the size of the array is automatically increased to accommodate the totals.
NOOPTIMIZE

Disables Rushmore optimization of SUM. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

Example

The following example displays the totals of the in_stock and on_order fields in the products table, along with a sum of the two totals.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Opens Products table

SUM in_stock, on_order, in_stock+on_order ;
   TO gnInStock, gnOnOrder, gnUnits

CLEAR
?
? 'Total in stock : ', gnInStock  && Displays 3119.00
? 'Total on order:  ', gnOnOrder  && Displays 780.00
? 'Total # units :  ', gnUnits  && Displays 3899.00

See Also

Other Resources

AVERAGE Command
CALCULATE Command
COUNT Command
SET OPTIMIZE Command
Using Rushmore Query Optimization to Speed Data Access
Commands
Language Reference


SUSPEND Command

Visual FoxPro 9.0 Language Reference
SUSPEND Command
See Also

Pauses program execution and returns to interactive Visual FoxPro.

SUSPEND

Remarks

While a program is paused, you can execute intervening commands, check variable values, open the Trace and Debug windows, and so on.

All variables created while the program is paused are PRIVATE.

Use RESUME to restart execution of a suspended program. Program execution continues with the line following the line containing SUSPEND.

See Also

Other Resources

CANCEL Command
RESUME Command
PRIVATE Command
Commands
Language Reference


TEXT ... ENDTEXT Command

Visual FoxPro 9.0 Language Reference
TEXT ... ENDTEXT Command
See Also Example

Sends lines of text specified by TextLines to the current output device or memory variable. Visual FoxPro sends lines of text to the current output device until it encounters an ENDTEXT statement or until the program ends.

The current output device can include the main Visual FoxPro window, a user-defined window, a printer, a text file, or a low-level file.

TEXT [TO VarName [ADDITIVE] [TEXTMERGE] [NOSHOW] [FLAGS nValue] [PRETEXT eExpression]]
      TextLines
ENDTEXT

Parameters

TextLines

Specifies text to send to the current output device. TextLines can consist of text, memory variables, array elements, expressions, functions, or any combination of these.
Note:
Visual FoxPro evaluates expressions, functions, memory variables, and array elements specified with TextLines only if you set SET TEXTMERGE to ON and enclose them with the delimiters specified by SET TEXTMERGE DELIMITERS. If SET TEXTMERGE is OFF, Visual FoxPro outputs expressions, functions, memory variables, and array elements as string literals along with their delimiters.

For example, Visual FoxPro evaluates and outputs the current date when you specify the DATE( ) function as TextLines only if SET TEXTMERGE is ON, and TextLines contains the function and the appropriate delimiters, such as <<DATE( )>>. If SET TEXTMERGE is OFF, Visual FoxPro outputs <<DATE( )>> as a string literal. If you place comments within TEXT...ENDTEXT or after the single backslash character (\) or double backslash characters (\\), Visual FoxPro outputs the comments.
TO VarName

Specifies the memory variable name to use for passing the contents of the TEXT...ENDTEXT. This variable can already exist. If the variable has not yet been declared, Visual FoxPro automatically creates it as a private variable. The TO clause operates regardless of how SET TEXTMERGE is set. If SET TEXTMERGE is set to a file, and the TO statement is included, Visual FoxPro outputs both the file and variable.
ADDITIVE

Determines whether the contents of the TO variable are overwritten or added to existing contents.
Note:
If the contents of TO VarName is not a string, Visual FoxPro always overwrites the contents in VarName.

TEXTMERGE

Enables evaluation of contents surrounded by delimiters without setting SET TEXTMERGE to ON.
NOSHOW

Disables display of the text merge to the screen.
FLAGS nValue

Specifies a numerical value that determines if output is suppressed to an output file, or if blank lines preceding any text are included in the output.

Value (additive) Description

1

Suppresses output to the file specified with the _TEXT System Variable.

2

When the NOSHOW clause is included, preserves blank lines preceding text that appears within TEXT...ENDTEXT. Setting nValue to 2 will separate current TEXT...ENDTEXT output from previous TEXT...ENDTEXT output with a line feed.

Note:
Combining an nValue setting of 2 and PRETEXT of 4 will separate current TEXT…ENDTEXT output from previous TEXT…ENDTEXT output with a line feed while removing empty lines in the TEXT...ENDTEXT output.
PRETEXT eExpression

Specifies a character string to insert before each line of the text merge contents between TEXT...ENDTEXT or a numeric expression. The following table describes behaviors of the PRETEXT clause depending on the expression specified by eExpression.

eExpression PRETEXT behavior

Character expression

Insert the expression before each line of the text merge contents appearing between the TEXT...ENDTEXT statement. When using PRETEXT with TEXT...ENDTEXT, eExpression is limited to a maximum length of 255 characters.

eExpression overrides the contents of the _PRETEXT system variable. When eExpression contains an expression that needs to be evaluated, for example, a user-defined function (UDF), Visual FoxPro evaluates it only once when the TEXT command first appears.

Numeric expression

Specify additive flag values to determine behavior for the text merge contents appearing between the TEXT...ENDTEXT statement.

For example, a value of 7 specifies that Visual FoxPro eliminate all white space including spaces, tabs, and carriage returns. A value falling outside of the range of 0-15 produces an error.

Note:
Specifying a value of zero does not eliminate white space.

When eExpression is a numeric expression, you can use the _PRETEXT system variable to insert additional text after Visual FoxPro eliminates white space.
The following table lists numeric additive flags that you can use in eExpression to specify additional behavior.

Value (Additive) Description

1

Eliminate spaces before each line.

2

Eliminate tabs before each line.

4

Eliminate carriage returns, for example, blank lines, before each line.

8

Eliminate line feeds.
Note:
Unlike the _PRETEXT system variable, the PRETEXT clause does not have global scope and applies only to the TEXT...ENDTEXT statement in which it appears.

Characters removed using the PRETEXT clause apply only to text within the TEXT...ENDTEXT statement and not to evaluated text merged from cExpression. In the following example, the spaces in the memory variable, myvar, are not removed when merged with the text in TEXT...ENDTEXT:
Copy Code
myvar = "   AAA"
TEXT TO x NOSHOW ADDITIVE TEXTMERGE PRETEXT 7
Start Line
<<myvar>>
      BBB
   CCC
ENDTEXT

Remarks

By default, TEXT ... ENDTEXT sends output to the main Visual FoxPro window or the active window. To suppress output to the main Visual FoxPro window or the active window, issue SET CONSOLE OFF. To send output to a printer or a text file, use SET PRINTER. To send output from TEXT ... ENDTEXT to a low-level file that you created or opened using FCREATE( ) or FOPEN( ), store the file handle returned by FCREATE( ) or FOPEN( ) to the _TEXT system variable, which you can use to direct output to the corresponding low-level file.

Note:
The text merge process usually includes any white space that might appear before each line in a TEXT...ENDTEXT statement. However, the inclusion of white space might cause the text merge to fail, for example, when XML is used in a Web browser. You must remove such white space to avoid incorrectly formatted XML.

Nesting TEXT...ENDTEXT statements is not recommended, especially if using the PRETEXT clause because the nested statements can affect the format of the outer statements.

Example

Example 1

The following example demonstrates creating a low-level file called myNamesFile.txt and storing its file handle in the _TEXT system variable. The program exits if the myNamesFile.txt file cannot be created.

Visual FoxPro opens the customer table and outputs the names of the first ten contacts to myNamesFile.txt. Visual FoxPro outputs the text and results of the functions to the text file. The example uses MODIFY FILE to open myNamesFile.txt.
Copy Code
CLEAR
CLOSE DATABASES
SET TALK OFF
SET TEXTMERGE ON
STORE FCREATE('myNamesFile.txt') TO _TEXT
IF _TEXT = -1
   WAIT WINDOW 'Cannot create an output file. Press a key to exit.'
   CANCEL
ENDIF

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer

TEXT
         CONTACT NAMES
   <<DATE( )>>    <<TIME( )>>
ENDTEXT
WAIT WINDOW 'Press a key to generate the first ten names.'
SCAN NEXT 10
   TEXT
      <<contact>>
   ENDTEXT
ENDSCAN
CLOSE ALL
MODIFY FILE myNamesFile.txt
ERASE myNamesFile.txt

Example 2

The following example shows a custom procedure that uses TEXT...ENDTEXT to store an XML DataSet to a variable. In the example, all spaces, tabs, and carriage returns are eliminated.

Copy Code
PROCEDURE myProcedure
   DO CASE
   CASE nValue = 1
      TEXT TO myVar NOSHOW TEXT PRETEXT 7
         <?xml version="1.0" encoding="utf-8"?>
         <DataSet xmlns="http://tempuri.org">
         <<ALLTRIM(STRCONV(leRetVal.item(0).xml,9))>>
         </DataSet>
      ENDTEXT
   OTHERWISE
   ENDCASE
ENDPROC

See Also

Other Resources

FOPEN( ) Function
_PRETEXT System Variable
SET TEXTMERGE Command
SET TEXTMERGE DELIMITERS
_TEXT System Variable
Commands
Language Reference


TOTAL Command

Visual FoxPro 9.0 Language Reference
TOTAL Command
See Also

Computes totals for numeric fields in the currently selected table.

TOTAL TO TableName ON FieldName   [FIELDS FieldNameList]   [Scope]
   [FOR lExpression1]   [WHILE lExpression2]   [NOOPTIMIZE]

Parameters

TableName

Specifies the name of the table that will contain the totals. If the specified table does not exist, Visual FoxPro creates it. If the table exists and SET SAFETY is ON, Visual FoxPro asks if you would like to overwrite the existing table. If SET SAFETY is OFF, you are not prompted, and the output table is overwritten.
FieldName

Specifies the field on which the totals are grouped. The table must be sorted on this field, or an open index or index tag must have this field as its key expression.
FIELDS FieldNameList

Specifies the fields to be totaled. Separate the field names in the list with commas. If you omit the FIELDS clause, all numeric fields are totaled by default.
Scope

Specifies a range of records to total. The default scope for TOTAL is ALL records. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. 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 in the totals. Rushmore Query Optimization optimizes a query created with TOTAL ... FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.
WHILE lExpression2

Specifies a condition whereby records from the current table are included in the totals for as long as the logical expression lExpression2 evaluates to true (.T.).
NOOPTIMIZE

Disables Rushmore optimization of TOTAL. For more information, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

Remarks

The table in the currently selected work area must be sorted or indexed. A separate total is calculated for each set of records with a common field value or unique index key value. The results are placed into records in a second table. One record is created in the second table for each common field value or unique index key value.

Numeric overflow can occur if the numeric fields in the second table are not wide enough to contain the totals. Visual FoxPro conserves the most significant portions of the totals when numeric overflow occurs. When a field is too small to accept a total:

  • Decimal places are truncated, and the remaining decimal portion of the total is rounded.

  • If the total still does not fit, scientific notation is used if the total field contains seven or more digits.

  • Finally, asterisks replace the field contents.

See Also

Other Resources

AVERAGE Command
CALCULATE Command
INDEX Command
SORT Command
SUM Command
Commands
Language Reference


TRY...CATCH...FINALLY Command

Visual FoxPro 9.0 Language Reference
TRY...CATCH...FINALLY Command
See Also Example

Provides a structure to handle errors and exceptions that can occur while running a block of code.

For more information about structured error handling using the TRY...CATCH...FINALLY command, see Structured Error Handling.

TRY
     [ tryCommands ]
[ CATCH [ TO VarName ] [ WHEN lExpression ]
     [ catchCommands ] ]
[ THROW [ eUserExpression ] ]
[ EXIT ]
[ FINALLY
     [ finallyCommands ] ]
ENDTRY

Parameters

TRY

Indicates the beginning of the TRY...CATCH...FINALLY structure.
[ tryCommands ]

Specifies statements where an error might occur.
[CATCH]

Indicates the beginning of a CATCH block, which handles the appropriate error. You can specify a CATCH statement without arguments, which evaluates to CATCH WHEN .T. (True).
Tip:
If you want to have a TRY...CATCH...FINALLY structure that catches all errors, make sure you have a CATCH statement that always evaluates to True (.T.).

You can specify any number of CATCH statements, including none.
[TO VarName]

Specifies a memory variable and not an object reference that stores a reference to the Exception object created. VarName can be only a simple memory variable, not an object property reference. You can explicitly set VarName to any value in the TRY...CATCH...FINALLY structure. The value does not change as long as another CATCH statement does not run, which resets VarName to NULL. VarName can have local, public, or private scope, which depends on how the variable is declared. If VarName has not been previously declared, it has private scope. The Exception object created has the same scope as VarName. When VarName goes out of scope, is released, or is reset, the Exception object is also released. When a CATCH TO VarName clause executes, Visual FoxPro always sets the VarName to a new Exception object regardless of its previous setting, though VarName retains its scope. Therefore, the contents of VarName are always overwritten regardless of what it previously referenced.
[WHEN lExpression]

Specifies an optional logical expression to evaluate when the program encounters the CATCH statement. The expression must evaluate to True (.T.) for the corresponding catchCommands to run. The argument for lExpression can contain a reference to the VarName Exception object so that you can query the resulting error and handle it accordingly. If a WHEN clause evaluates to False (.F.), Visual FoxPro releases the Exception object and resets the VarName to NULL. You can test whether VarName is set to a type or to NULL by using the VARTYPE( ) function.
[ catchCommands ] ]

Specifies statements to run when the program encounters the corresponding CATCH statement.
[THROW [ eUserExpression ] ]

Creates a new Exception object to be caught by a CATCH statement. You can call THROW from any code block in a TRY...CATCH...FINALLY structure. However, you can use THROW anywhere in code where an error handler exists to catch the exception. You cannot call THROW from the Command window.
Caution:
Calling the THROW command outside the TRY...CATCH...FINALLY structure and without an appropriate error handler causes your program to quit.

Note:
Run-time applications should enclose a THROW command with an outer TRY...CATCH...FINALLY structure. Visual FoxPro disregards any THROW statements appearing in a CATCH WHEN lExpression clause.

The eUserExpression parameter specifies an expression of any type and sets the exception's UserValue property. You can pass an object of any type because the exception's UserValue property stores only the object reference. When you include eUserExpression with the THROW clause, Visual FoxPro sets the exception's ErrorNo property value to 2071, which corresponds to the error, "User Thrown Error (Error 2071)".
Note:
You should pass a value for eUserExpression, which sets the exception's UserValue property, so you can chain multiple Exception objects. For more information about chaining Exception objects, see the Example section.

If you omit eUserExpression, Visual FoxPro escalates the original Exception object, if it exists. If the Exception object does not exist, Visual FoxPro throws a new Exception object with an ErrorNo property value of 2071. If you omit eUserExpression, and the THROW clause escalates the Exception object to an outer TRY...CATCH block, the outer TRY...CATCH block catches the same Exception object. Values returned by the ERROR( ), MESSAGE( ), and AERROR( ) functions might not be reliable when used in a structured exception handler, so, you should use the Exception object instead. If an outer TRY...CATCH statement is in effect when THROW is called from a CATCH or FINALLY block, Visual FoxPro assigns VarName in the CATCH TO clause to the object reference for the Exception object generated by the thrown exception. If no outer TRY...CATCH statement is in effect, Visual FoxPro escalates the exception to an ON ERROR or Error event, if one exists; otherwise, Visual FoxPro calls its system error handler. If you want to rethrow the original exception that was caught by the CATCH TO VarName clause, you can call THROW VarName to rethrow the exception.
Note:
Rethrowing the original exception produces another new Exception object, at the outer CATCH statement, that has a UserValue property containing an object reference to the original exception.

If THROW encounters an error when evaluating an expression, Visual FoxPro escalates the error in the usual way.
[EXIT]

Include in a TRY, CATCH, or FINALLY block to immediately stop processing code in a code block. If EXIT appears in the TRY or CATCH block, the program resumes execution at the FINALLY statement, if one exists. If EXIT appears in the FINALLY block or if FINALLY does not exist, the program resumes execution immediately following the ENDTRY statement. For more information, see EXIT Command.
[ FINALLY

Indicates the beginning of the FINALLY block, which you use to clean up any resources allocated by the TRY block and always runs except when the CANCEL and QUIT commands are used.
[ finallyCommands ]

Specifies statements to run in the FINALLY block after either finding no errors in the TRY block or running statements in a CATCH block.
ENDTRY

Indicates the end of the TRY...CATCH...FINALLY structure. Each TRY...CATCH...FINALLY structure must end with an ENDTRY keyword. As with other Visual FoxPro control statements, you can add comments prefaced by double ampersand (&&) characters after this ENDTRY.
Note:
If you do not include the ENDTRY statement at the end of the TRY...CATCH...FINALLY structure, Visual FoxPro generates an error when you compile your code. Although you can still execute code with compile errors, you should not do so in this scenario because it causes Visual FoxPro to stop responding.

Remarks

You cannot explicitly transfer program execution to a CATCH or FINALLY code block.

Visual FoxPro determines scope for variables on a procedural, not block, basis. That is, variables declared in a TRY block are visible from a FINALLY block within the same TRY...CATCH...FINALLY structure. However, in a nested structure, variables that are declared in a TRY, CATCH, or FINALLY block have local scope.

You should not initialize variables or set up critical code inside the TRY block because the code is not guaranteed to run. If an error occurs at a particular line of code in the TRY block, all subsequent lines in the TRY block do not run.

Any errors that occur in an object's Error event must be handled by the object and are not escalated to an ON ERROR routine or TRY...CATCH...FINALLY handler. However, you can use a TRY...CATCH...FINALLY structure in the Error event to catch errors from an Error event. For more information, see Error Event.

Using the COMRETURNERROR( ) function in a CATCH block ends all further processing and returns control of the program directly to the Component Object Model (COM) client. Therefore, if you have a FINALLY block, it does not run. For more information, see COMRETURNERROR( ) Function.

Avoid using the SET TEXTMERGE TO MEMVAR command within a TRY...CATCH...FINALLY structure because the memory variable will be lost if an error occurs in the statement.

To determine a course of action and the error handler in effect, use the SYS(2410) - Error Handler function in your TRY...CATCH...FINALLY code, for example, with a DO CASE structure, depending on the type of handler that handles the exception. For more information, see SYS(2410) - Error Handler.

You can use TRY...CATCH...FINALLY to handle errors that occur in menu and timer events and with commands such as ON KEY LABEL if the structure is properly wrapped. The following example illustrates how the READ EVENTS command retains control of the program within the TRY...CATCH...FINALLY structure so that you trap menu events. Error trapping is controlled by the position of TRY...CATCH...FINALLY on the call stack.

Copy Code
TRY
   DO myMenu.mpr
   DO FORM myForm
   myForm.AddObject("tm1","mytimer")
   READ EVENTS
CATCH TO oException
   IF oException.ErrorNo = 1
      STRTOFILE("Error occurred at: " + TRANSFORM(DATETIME());
         + CHR(13),"C:\Errors.log",.T.)
   ENDIF
FINALLY
   CLEAR EVENTS
ENDTRY

For more information, see READ EVENTS Command and ON KEY LABEL Command.

Visual FoxPro supports Set Next Statement debugging functionality only within a single code block. For example, when executing code in a TRY block, you can use Set Next Statement only to another line within the TRY block. You cannot jump to another line of code in a CATCH or FINALLY block. For more information, see Debugger Keyboard Shortcuts and Menus.

Visual FoxPro generates the appropriate system messages under the following conditions:

  • A mismatch or error occurs with the TRY...CATCH...FINALLY structure.

  • An unhandled exception occurs.

  • A command that is not permitted for a specific block appears in a TRY, CATCH, or FINALLY block. For more information, see Structured Error Handling.

  • A user-thrown error occurs.

Similar to other error handling in Visual FoxPro, exceptions that occur in TRY...CATCH...FINALLY exception handlers set the SET CONSOLE command to ON. For more information, see SET CONSOLE Command.

Example

The following example illustrates how to nest TRY...CATCH statements, use the THROW clause, and handle Exception objects.

Copy Code
LOCAL x AS Integer, y AS Integer, result AS Integer
LOCAL oErr AS Exception, oErr1 AS Exception
TRY
   x = 1
   TRY
      USE nothing
      GO TOP
      y = nothing.col1
   CATCH TO oErr
      oErr.UserValue = "Nested CATCH message: Unable to handle"
      ?[: Nested Catch! (Unhandled: Throw oErr Object Up) ]
      ?[  Inner Exception Object: ]
      ?[  Error: ] + STR(oErr.ErrorNo)
      ?[  LineNo: ] + STR(oErr.LineNo)
      ?[  Message: ] + oErr.Message
      ?[  Procedure: ] + oErr.Procedure
      ?[  Details: ] + oErr.Details
      ?[  StackLevel: ] + STR(oErr.StackLevel)
      ?[  LineContents: ] + oErr.LineContents
      ?[  UserValue: ] + oErr.UserValue
      THROW oErr
   FINALLY
      ?[: Nested FINALLY executed ]
      IF USED("nothing")
         USE IN nothing
      ENDIF
   ENDTRY
   result = x-y
CATCH TO oErr1
   ?[: Outer CATCH! ]
      ?[  Outer Exception Object: ]
      ?[  Error: ] + STR(oErr1.ErrorNo)
      ?[  LineNo: ] + STR(oErr1.LineNo)
      ?[  Message: ] + oErr1.Message
      ?[  Procedure: ] + oErr1.Procedure
      ?[  Details: ] + oErr1.Details
      ?[  StackLevel: ] + STR(oErr1.StackLevel)
      ?[  LineContents: ] + oErr1.LineContents
      ?[  ->UserValue becomes inner exception THROWn from nested TRY/CATCH ]
      ?[     Error: ] + STR(oErr1.UserValue.ErrorNo)
      ?[     Message: ] + oErr1.UserValue.Message
      ?[     Procedure: ] + oErr1.UserValue.Procedure
      ?[     Details: ] + oErr1.UserValue.Details
      ?[     StackLevel: ] + STR(oErr1.UserValue.StackLevel)
      ?[     LineContents: ] + oErr1.UserValue.LineContents
      ?[     UserValue: ] + oErr1.UserValue.UserValue
   result = 0
FINALLY
   ?[: FINALLY statement executed ]
ENDTRY
RETURN result

The following example shows how you might want to chain Exception objects:

Copy Code
TRY
   TRY
      x=y      && The y variable does not exist and causes an error.
   CATCH TO oException2
      THROW CREATEOBJECT("myException")
   ENDTRY
CATCH TO oException1
ENDTRY

? 2, oException2.ErrorNo, oException2.UserValue
? 1, oException1.ErrorNo, oException1.UserValue.UserValue

DEFINE CLASS myException AS Exception
UserValue = "My custom error handler"
PROCEDURE Init
   STRTOFILE("An error occurred at: " + TRANSFORM(DATETIME());
 + CHR(13),"c:\errs.log",.T.)
ENDPROC
ENDDEFINE

See Also

Other Resources

Commands
Exception Class
UserValue Property
VARTYPE( ) Function
ErrorNo Property
ERROR( ) Function
MESSAGE( ) Function
AERROR( ) Function
SYS(2018) - Error Message Parameter


TYPE Command

Visual FoxPro 9.0 Language Reference
TYPE Command
See Also

Displays the contents of a file.

TYPE FileName1   [AUTO]   [WRAP]
   [TO PRINTER [PROMPT] | TO FILE FileName2]   [NUMBER]

Parameters

FileName1

Specifies the name of the file to display. The name must include a file extension.
AUTO

Turns automatic indentation on. When you also include WRAP, TYPE automatically indents wrapped text in each paragraph by the same amount it indents the first line of the paragraph. For example:
  • Wrapped lines are aligned with the tab when a paragraph begins with a tab.

  • Wrapped lines are aligned with the tab when a paragraph begins with a number (or other text) followed by a tab and text.

  • Wrapped lines are indented by the same amount as the first line when the first line of a paragraph is indented with spaces.

WRAP

Enables word wrap so that a word that is too long to fit at the end of a line is automatically moved to the next line.
TO PRINTER [PROMPT]

Directs output to the printer. You can include the optional PROMPT clause to display a print dialog before printing starts. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName2

Directs output to the file specified with FileName2.
NUMBER

Places line numbers at the beginning of each line in the output.

Remarks

TYPE displays the contents of files. This display can be directed to the main Visual FoxPro window, the active user-defined window, a printer, or another file.

When SET HEADINGS is ON, Visual FoxPro inserts a form feed, the path and name of the file, and the date at the beginning of output produced with TYPE. If SET HEADINGS is OFF, this information isn't included.

In FoxPro for MS-DOS, if a printer driver setup is loaded and you direct output from TYPE to a file or a printer, TYPE displays the file contents using the settings from the printer driver setup.

See Also

Other Resources

SET HEADINGS Command
WordWrap Property
PROMPT( ) Function
Type Property
Commands
Language Reference


UNLOCK Command

Visual FoxPro 9.0 Language Reference
UNLOCK Command
See Also Example

Releases a record lock, multiple record locks, or a file lock from a table, or releases all record and file locks from all open tables.

UNLOCK    [RECORD nRecordNumber]   [IN nWorkArea | cTableAlias]   [ALL]

Parameters

RECORD nRecordNumber

Releases the record lock on record number nRecordNumber. You can specify 0 for nRecordNumber to unlock a table header locked with LOCK("0", <alias>) or RLOCK("0", <alias>). Issuing UNLOCK RECORD nRecordNumber for a record in a table with a file lock releases the file lock.
IN nWorkArea | cTableAlias

Releases a record lock (or locks) or a file lock from a table in a specific work area. nWorkArea specifies a work area number and cTableAlias specifies a table alias. If you don't include nWorkArea or cTableAlias, UNLOCK releases a record lock (or locks) or a file lock from the table in the currently selected work area.
ALL

Releases all record and file locks in all work areas. For more information about record and file locking and sharing tables on a network, see Programming for Shared Access.

Remarks

Record and file locks can be removed from a table only by the user who issued the locks. UNLOCK cannot unlock a table opened for exclusive use.

A record lock (or locks) or a file lock is released from the table in the current work area if you issue UNLOCK without any additional arguments.

If relations are established between tables, releasing a record lock (or locks) or a file lock from one of the tables doesn't release locks from the related records or files. You must explicitly release the record or file locks in each of the related files. You can release all locks on any related tables by issuing UNLOCK ALL (this also releases locks in unrelated files).

Example

Copy Code
CLOSE DATABASES
SET REPROCESS TO 3 AUTOMATIC
STORE '1,2,3,4' TO gcRecList     && Lock records 1 through 4
gcOldExc = SET('EXCLUSIVE')     && Save the EXCLUSIVE setting
SET EXCLUSIVE OFF  && Allow sharing of tables

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table
SELECT 0
USE employee  && Opens Employee table

? LOCK('1,2,3,4', 'customer')  && Lock the first 4 records in customer
? RLOCK(gcRecList, 'employee') && Lock the first 4 records in employee

UNLOCK IN customer
UNLOCK IN employee
SET EXCLUSIVE &gcOldExc  && Restore original EXCLUSIVE setting

See Also

Other Resources

FLOCK( ) Function
LOCK( ) Function
RLOCK( ) Function
Programming for Shared Access
Commands
Language Reference


UPDATE - SQL Command

Visual FoxPro 9.0 Language Reference
UPDATE - SQL Command
See Also

Updates records in a table with new values.

Note:
The SQL UPDATE command can update records for a single table only.

UPDATE Target
   SET Column_Name1 = eExpression1 [, Column_Name2 = eExpression2 ...]
   [FROM [FORCE] Table_List_Item [[, ...] | [JOIN [ Table_List_Item]]]
   WHERE FilterCondition1 [AND | OR FilterCondition2 ...]

Parameters

UPDATE Target

Specifies a target table, cursor, table or cursor alias, or file to update. You can include multiple sources of data for the update operation in the FROM clause. Target can have the following syntaxes:
  • [DatabaseName!]TableName

    DatabaseName! specifies the name of a database containing the table if the table is in a noncurrent database. If the table is in a noncurrent database, you must include the name of the database. Use an exclamation point (!) as a delimiter immediately following the database name and preceding the table name.

    TableName specifies the name of a table for the update operation.

  • Alias

    Alias specifies an alias that matches a table in the FROM clause or a cursor in the current data session for the update operation.

  • FileName

    FileName specifies the name of a file for the update operation.

SET Column_Name1= eExpression1 [, Column_Name2 = eExpression2 ...]

Specifies the columns in the table to update and their new values. If you omit the WHERE clause, every row in the table is updated with the same value. If you want to use an object property in an expression, you need to specify a memory variable and then use that variable in the expression. For example, you can specify x = oColField("iid").Value and then use the SET clause set iid = x in your UPDATE - SQL command. If you use the object property, that is objectname.property, directly in the expression, the command uses it as an alias and fails. You can include one subquery in the SET clause to specify an expression. If the subquery does not return any results, it returns NULL. For syntax and information about subqueries, see SELECT - SQL Command - FROM Clause.
Note:
If you use a subquery in the SET clause, you cannot use subqueries in the WHERE clause. A subquery in the SET clause must meet exactly the same requirements as subqueries used in comparison operations.

[FROM [FORCE] Table_List_Item[[, ...] | [JOIN [ Table_List_Item]]]

Specifies one or more tables containing the data for the update operation. The FROM clause has the same syntax as in the SQL SELECT command except for the following restrictions:
  • The target table or cursor cannot be included in an OUTER join as a secondary table or cursor.

  • It should be possible to evaluate all other JOIN operations before performing a JOIN operation on the target table.

  • The target cursor cannot be the result from a subquery.

For more information, see SELECT - SQL Command. FORCE specifies that the tables in the table list are joined in the order they appear in the FROM clause.
Note:
If FORCE is omitted, Visual FoxPro attempts to optimize the update operation. However, the update operation might be executed faster by including the FORCE keyword to disable Visual FoxPro update optimization.

Table_List_Item can have the following syntaxes:
  • [DatabaseName!]Table [[AS] Local_Alias]

    DatabaseName! specifies the name of a database containing the table if the table is in a noncurrent database. If the table is in a noncurrent database, you must include the name of database. Use an exclamation point (!) as a delimiter immediately following the database name and preceding the table name.

    Table specifies the name of the table or cursor you want to update data from. If no table is open, Visual FoxPro displays the Open dialog box so you can specify the file location. After the table opens, it remains open when the query is complete.

    Local_Alias specifies a temporary name for the table specified in Table. If you specify a local alias, you must use the local alias instead of the table name in the UPDATE statement. The alias can represent a table or a cursor.

    JOIN provides the capability for specifying one or more secondary tables. There is no hard coded limit on the number of tables, aliases, or JOIN clauses per UPDATE statement.

  • (Subquery) AS Subquery_Alias

    A subquery specifies a SELECT statement within another SELECT statement. For more information about subqueries in SELECT statements, see the FROM clause in SELECT - SQL Command.

WHERE FilterCondition1 [AND | OR FilterCondition2 ...]]

Specifies one or more filter conditions that records must meet to be updated with new values. There is no limit to the number of filter conditions in the WHERE clause. To reverse the value of a logical expression, use the NOT operator. To check for an empty field, use the EMPTY( ) function. For more information, see EMPTY( ) Function.

Remarks

To determine the number of records updated, check the value of the _TALLY system variable immediately after executing the SQL UPDATE command. For more information, see _TALLY System Variable.

Tip:
When updating multiple records in a table opened for shared access, SQL UPDATE uses record locking, unlike the REPLACE command. This reduces record contention in multiuser situations but might reduce performance. For maximum performance, open the table for exclusive use or use the FLOCK( ) function to lock the table. For more information, see FLOCK( ) Function.

In the SET clause, Visual FoxPro processes assignment sequentially. If you issue the command, UPDATE table1 SET field1 = field2, field2=field1, the values of the two fields are not swapped, rather the values of F1 and F2 are the same.

Legacy Code Examples

Example 1

The following example uses the OPEN DATABASE command to open the Visual FoxPro sample database and USE command to open the open the Customer table in TestData.dbc. The SQL UPDATE statement updates all the values in the MaxOrdAmt field to "25".

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer
UPDATE Customer SET MaxOrdAmt = 25
BROWSE FIELDS Company, MaxOrdAmt

For more information, see USE Command and BROWSE Command.

Example 2

The following example uses OPEN DATABASE command to open the Visual FoxPro sample database, TestData.dbc. The SQL SELECT command retrieves data from the Products table in TestData.dbc, stores it in a table, MyProductsList, and displays the new table.

The CREATE CURSOR command creates the MyUpdateTable with a Prod_Unit field containing an integer value of 10 and displays the table.

The SQL UPDATE command updates the In_Stock field for MyProductsList with the value from MyUpdateTable for the product name, "Chai". The SQL SELECT command returns and displays a query for MyProductsList showing the updated In_Stock field for the product, "Chai".

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
SELECT in_stock, prod_name ;
    FROM Products ;
    INTO TABLE MyProductsList.dbf
BROWSE
CREATE CURSOR MyUpdateTable (prod_unit I(10))
INSERT INTO MyUpdateTable (prod_unit) VALUES (10)
BROWSE
UPDATE MyProductsList ;
    SET MyProductsList.in_stock = MyUpdateTable.prod_unit ;
    FROM MyUpdateTable ;
    WHERE MyProductsList.prod_name = "Chai"
SELECT * FROM MyProductsList

For more information, see OPEN DATABASE Command, BROWSE Command, CREATE CURSOR - SQL Command, and INSERT - SQL Command.

Code Examples

Example 3

The following example shows a subquery used as an expression in the SET clause of the UPDATE statement. The query updates all records in the products table. If there is no matching productID in the mfg_msrp table, the field unitprice is set to NULL.

Copy Code
UPDATE products ;
   SET unitprice = ;
       (SELECT (msrp*.90) ;
          FROM mfg_msrp ;
         WHERE mfg_msrp.productID = products.productID ;
           AND mfg_msrp.discontinued = .f.)

Example 4

The following example shows a correlated update which only touches records that match the filter conditions in the WHERE clause.

Copy Code
UPDATE products ;
   SET unitprice = mfg_msrp.msrp*.90 ;
  FROM mfg_msrp ;
 WHERE mfg_msrp.productID = products.productID;
   AND mfg_msrp.discontinued = .f.

Example 5

The following an example of a correlated update in which the update results include only the first match found for a record. Other matches for the record are ignored. The example code specifies two cursors. The first is the target for the updates. The second is the source of the updates and contains two changes for the first record in the target cursor and one update that does not match any records in the target cursor. In the results, the value of the first record shows the first match of .50 and not 10.00, the value of the second match.

Copy Code
CLOSE DATABASES ALL
CREATE CURSOR MyProducts (ProdID I , ProdCategory I NULL, MSRP Y NULL)
INSERT INTO MyProducts VALUES (1,9,1.00)
INSERT INTO MyProducts VALUES (2,8,2.00)
INSERT INTO MyProducts VALUES (3,7,3.00)

CREATE CURSOR MyUpdates (ProdID I , MSRP Y)
INSERT INTO MyUpdates VALUES (1,.50) && Matches and updates.
INSERT INTO MyUpdates VALUES (2,20.00) && Matches and updates.
INSERT INTO MyUpdates VALUES (4,40.00) && No match
INSERT INTO MyUpdates VALUES (1,10.00)&& 2nd match but no update.

UPDATE MyProducts SET MSRP=MyUpdates.MSRP FROM MyUpdates WHERE MyProducts.ProdID=MyUpdates.ProdID

SELECT MyProducts
BROWSE

See Also

Other Resources

Commands
DELETE - SQL Command
SQL Commands and Functions
Commands
Language Reference


USE Command

Visual FoxPro 9.0 Language Reference
USE Command
See Also Example

Opens a table and its associated index files or opens a SQL view.

USE [[DatabaseName!] TableName | SQLViewName | ?]
   [IN nWorkArea | cTableAlias] [ONLINE] [ADMIN] [AGAIN]
   [NOREQUERY [nDataSessionNumber]] [NODATA]
   [INDEX IndexFileList | ? [ORDER [nIndexNumber | IDXFileName
   | [TAG] TagName [OF CDXFileName] [ASCENDING | DESCENDING]]]]
   [ALIAS cTableAlias] [EXCLUSIVE] [SHARED] [NOUPDATE]
   [CONNSTRING cConnectionString | nStatementHandle ]

Parameters

[DatabaseName!]TableName

Specifies the name of the table to open. To open a table not in the current database, precede the table name with the database name followed immediately by an exclamation point (!).
Tip:
On Microsoft Windows 98 and later, spaces are significant in file names; therefore, avoid using extraneous spaces in TableName and DatabaseName. If a table or database name contains spaces, enclose the name in quotation marks (" " or ' ').

Tip:
To access a table associated with or not associated with a database, specify the full path. However, you can increase performance by using only the table name.

Note:
If you do not include a database name, Visual FoxPro can open tables only in the current database. Visual FoxPro does not recognize path names correctly if a disk or directory name contains an exclamation point.

SQLViewName

Specifies the name of a SQL view in the current database to open. SQLViewName can also be the name of an offline view created with the CREATEOFFLINE( ) function. For more information, see CREATEOFFLINE( ) Function. You can create a SQL view using CREATE SQL VIEW.
?

Displays the Use dialog box so you can choose a table.
IN nWorkArea

Specifies the work area in which to open the table. To close a table in a specific work area, call USE without the table name but include the IN clause and the work area number. The IN clause supports 0 as a work area. Including 0 opens a table in the lowest available work area. For example, if tables are open in work areas 1 through 10, the following command opens the customer table in work area 11:
Copy Code
USE customer IN 0
IN cTableAlias

Specifies the alias of the table to open in the work area of a table that is currently open. The alias of the open table is specified with cTableAlias. If you omit nWorkArea and cTableAlias, the table is opened in the currently selected work area.
ONLINE

Opens an offline view created with CREATEOFFLINE( ). You can specify the name of the offline view in SQLViewName. You can use TABLEUPDATE( ) to update data on the server. The offline view must be opened exclusively. Before opening the offline view with USE, include the EXCLUSIVE clause in USE or SET EXCLUSIVE to ON. You cannot open or close an offline view in ONLINE mode from within a transaction.
ADMIN

Opens an offline view created with CREATEOFFLINE( ) but does not update the data on the server with the changes made to the offline view. Opening an offline view with the ADMIN keyword allows you to make changes to the offline view without updating the data on the server. You cannot open or close an offline view in ADMIN mode from within a transaction.
AGAIN

To open a table concurrently in multiple work areas, you can do one of the following:
  • Select another work area and issue USE with the table name and the AGAIN clause.

  • Issue USE with the table name and the AGAIN clause, and specify a different work area with the IN clause.

When you open a table again in another work area, the table in the new work area takes on the attributes of the table in the original work area. For example, if a table is opened for read-only or exclusive access and is opened again in another work area, the table is opened for read-only or exclusive access in the new work area. Index files opened for the original table are available for the table you open again if you don't open indexes when you open the table again. The index order is set to 0 in the work areas where the table is opened again. You can open indexes that were not opened with the original table. This sets the index order to 0 for the original table. A table opened again is assigned the default alias of the work area. You can include an alias every time you open a table in multiple work areas as long as the aliases are unique. In Visual FoxPro for Windows, opening a table again in another work area doesn't consume an additional file handle.
NOREQUERY [nDataSessionNumber]

Specifies that data from a remote SQL view is not downloaded again. NOREQUERY is available only for SQL views and is typically used when you open a SQL view again by including the AGAIN clause. Including the NOREQUERY clause increases performance for large data sets because the data does not need to be downloaded again. nDataSessionNumber can be included to specify that data for a remote SQL view in a specific data session isn't downloaded again. If nDataSessionNumber is omitted, data isn't downloaded for the view open in the current data session.
NODATA

Download the structure of a SQL view without data. NODATA provides the fastest method for determining the structure of a SQL view.
Note:
Opening a view with NODATA always opens a new cursor for the view. When you use NODATA, Visual FoxPro creates a WHERE clause for the view that always returns a value of false. Because no records on the data source meet the WHERE clause condition, no rows are selected for the remote data source cursor. Therefore, Visual FoxPro retrieves the structure of the view quickly because it does not wait for the remote data source to build a potentially large cursor.

Tip:
Using NODATA is more efficient than setting the MaxRecords property to 0 on your view or cursor using DBSETPROP( ) or CURSORSETPROP( ) respectively. When you use the MaxRecords property, you must wait while the remote data source builds a cursor for the view containing all data rows that meet the view's normal WHERE clause conditions. Rows from the full remote view cursor are then downloaded according to the setting of the MaxRecords property. For more information, see DBSETPROP( ) Function and CURSORSETPROP( ) Function.

INDEX IndexFileList

Specifies a set of indexes to open with the table. If a table has a structural compound index file, the index file is automatically opened with the table. IndexFileList can contain any combination of names of single-entry .idx and compound .cdx index files. You don't have to include the file name extensions for index files unless an .idx and a .cdx index file in the index file list have the same name. The first index file named in the index file list is the master controlling index file, which controls how records in the table are accessed and displayed. However, if the first index file is a .cdx compound index file, records in the table are displayed and accessed in physical record order.
INDEX ?

Displays the Open dialog with a list of available index files to choose from.
ORDER [nIndexNumber]

Specifies a master controlling single-entry .idx index file or compound .cdx index file tag other than the first index file or index tag specified in IndexFileList. .Idx index files are numbered first, in the order in which they appear in the index file list. Tags in the structural compound index file (if one exists) are then numbered in the order in which the tags were created. Finally, tags in any independent compound index files are numbered in the order in which they were created. You can also use SET ORDER to specify the controlling index file or tag. See SET ORDER for a further discussion of the numbering of index files and tags. If nIndexNumber is 0, records in the table are displayed and accessed in physical record order, and the indexes remain open. Including ORDER 0 enables open index files to be updated while presenting the file in record number order. Including ORDER without nIndexNumber is identical to including ORDER 0.
ORDER [IDXFileName]

Specifies a single-entry .idx index file as the master controlling index file.
ORDER [TAG TagName] [OF CDXFileName]

Specifies a master controlling tag in a compound .cdx index file. The tag name can be from the structural compound index file or any open compound index file. If identical tag names exist in open compound index files, include OF CDXFileName and specify the name of the compound index file containing the desired tag.
ASCENDING

Specifies that the table records are accessed and displayed in ascending order.
DESCENDING

Specifies that the table records are accessed and displayed in descending order. Including ASCENDING or DESCENDING doesn't change the index file or tag; it alters only the order in which records are displayed and accessed.
ALIAS cTableAlias

Creates an alias for the table that you can use with other commands and functions. An alias must begin with a letter or an underscore and can consist of up to 254 letters, digits, or underscores.
Note:
Visual FoxPro automatically creates an alias if the alias you provide contains an unsupported alias character.

When a table is opened, it is automatically assigned an alias, which is the table name if ALIAS is omitted. However, you can create a different alias for the table by including ALIAS and a new alias. In earlier versions of FoxPro versions, an alias must begin with a letter or an underscore and can contain up to 10 letters, digits or underscores. Visual FoxPro assigns a default alias if a conflict between alias occurs or if you use the AGAIN keyword to open a table simultaneously in multiple work areas without specifying an alias when you open the table in each work area.
EXCLUSIVE

Opens a table for exclusive use on a network. For more information on the exclusive use of tables, see SET EXCLUSIVE.
SHARED

Opens a table for shared use on a network. SHARED allows you to open a table for shared use even when EXCLUSIVE is set ON.
NOUPDATE

Prevents changes to the table and its structure.
CONNSTRING cConnectionString | nStatementHandle

Specifies a connection string for the ODBC data source. The cConnectionString parameter can represent parameters normally passed using either SQLCONNECT( ) or SQLSTRINGCONNECT( ). The nStatementHandle parameter specifies a memory variable representing an existing statement handle from an existing connection. When you use cConnectionString, Visual FoxPro passes the connection string to the remote view that you specify with SQLViewName, which then uses the connection string to connect to the specified data source instead of using any previously defined connection string. Passing an empty string ("") displays the ODBC Data Source dialog box and makes it possible for the user to select a data source.
Note:
If you specify incomplete data in the connection string, the data source displays a login dialog box for any needed login information. If you omit the optional CONNSTRING cConnectionString clause, the remote view uses the currently defined default connection. For more information about data source connection strings, see your ODBC driver documentation.

Visual FoxPro supports overriding the default connection for a remote view and requires the nStatementHandle parameter for supporting shared connections.

Remarks

If you issue USE without a table name, and a table file is open in the currently selected work area, Visual FoxPro closes the table. Visual FoxPro also closes a table when another table is opened in the same work area. You cannot have more than one table open in a work area at one time.

When used with a noncurrent database, the USE command opens the database automatically but does not set the database as the current database. When the table closes, the database remains open.

Example

The following example opens three tables in three different work areas. The Data Session window is opened to show where the tables are open and to show the alias for each table.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
ACTIVATE WINDOW View
USE customer IN 0  && Opens Customer table
USE employee IN 0  && Opens Employee table
USE products IN 0  && Opens Products table

See Also

Other Resources

How to: Open Tables in Databases
Managing Views
Commands
Language Reference


VALIDATE DATABASE Command

Visual FoxPro 9.0 Language Reference
VALIDATE DATABASE Command
See Also Example

Ensures that the locations of tables and indexes in the current database are correct.

VALIDATE DATABASE [RECOVER] [NOCONSOLE]
   [TO PRINTER [PROMPT] | TO FILE FileName]

Parameters

RECOVER

Displays dialogs that make it possible for you to locate tables and indexes that are not in the locations contained in the database. Beginning with Visual FoxPro 7, the RECOVER clause is supported in programs.
NOCONSOLE

Suppresses error message output to the main Visual FoxPro window or to the active user-defined window.
TO PRINTER [PROMPT]

Directs error message output from VALIDATE DATABASE to a printer. PROMPT displays a Print dialog box before printing starts. Place the PROMPT keyword immediately after TO PRINTER.
TO FILE FileName

Directs error message output to the file specified with FileName. If the file already exists and SET SAFETY is ON, you are asked if you want to overwrite the file.

Remarks

VALIDATE DATABASE ensures that the database contains the proper locations of tables and indexes, that tables in the database contain the proper fields, and that index tags in the database exist.

VALIDATE DATABASE operates on the current database. The database must be opened for exclusive use by including the EXCLUSIVE keyword when you issue OPEN DATABASE.

Example

The following example opens the testdata database and uses VALIDATE DATABASE to ensure that the locations of tables and indexes in the database are correct.
Copy Code
CLOSE DATABASES
SET PATH TO (HOME(2) + 'Data\') && Sets path to database
OPEN DATABASE testdata EXCLUSIVE && Open testdata database

VALIDATE DATABASE

See Also

Other Resources

CREATE DATABASE Command
MODIFY DATABASE Command
OPEN DATABASE Command
USE Command
Commands
Language Reference


WAIT Command

Visual FoxPro 9.0 Language Reference
WAIT Command
See Also

Displays a message and pauses Visual FoxPro execution until the user presses a key or clicks the mouse.

WAIT [cMessageText] [TO VarName] [WINDOW [AT nRow, nColumn]] [NOWAIT]
   [CLEAR | NOCLEAR] [TIMEOUT nSeconds]

Parameters

cMessageText

Specifies a custom message to display. You can specify any valid Visual FoxPro function, object, or data type instead of cMessageText. If you omit cMessageText, Visual FoxPro displays the default message. If cMessageText is an empty string (""), Visual FoxPro does not display a message and waits until a key is pressed before continuing program execution. The length of cMessageText can be up to 255 characters.
Note:
Visual FoxPro converts object references to the string, "(Object)". If the function you specify evaluates to a noncharacter value, Visual FoxPro automatically uses the TRANSFORM( ) function to provide the character equivalent. In the following example, a character type date is returned and passed to WAIT WINDOW:

Copy Code
WAIT DATE() WINDOW AT 20,20 TIMEOUT 10
TO VarName

Saves the key pressed to a variable or an array element. If the variable or an array element you specify with VarName does not exist, it is created. The empty string is stored in VarName if you press ENTER or a nonprintable key or key combination, or click the mouse.
WINDOW

Displays the message in a system message window located in the upper-right corner of the main Visual FoxPro window. The window can be temporarily hidden by pressing the CTRL or SHIFT key. Beginning with Visual FoxPro 7, core font attributes including font name, font size and font style are derived from the font characteristics specified in the Appearance tab of the Windows Display Control Panel.
AT nRow, nColumn

In Visual FoxPro, specifies the position of the message window on the screen.
NOWAIT

Continues program execution immediately after the message is displayed. The program does not wait for the message to be removed from the main Visual FoxPro window, but continues executing on the program line immediately following the program line containing WAIT NOWAIT. If you omit NOWAIT, program execution pauses until the message is removed from the main Visual FoxPro window by pressing a key or clicking the mouse.
CLEAR

Removes a Visual FoxPro system window or a WAIT message window from the main Visual FoxPro window from within a program. For example, talk from indexing, sorting, and so on is directed to a Visual FoxPro system window if you issue SET TALK WINDOW. The window can be removed interactively if you press a key or move the mouse. Issue WAIT CLEAR to remove the window from within a program.
NOCLEAR

Specifies that a WAIT message window remains on the main Visual FoxPro window until WAIT CLEAR or another WAIT WINDOW command is issued, or a Visual FoxPro system message is displayed.
TIMEOUT nSeconds

Specifies the number of seconds that can elapse without input from the keyboard or the mouse before the WAIT is terminated. nSeconds specifies the number seconds, the fractional seconds that are permitted, that elapse. If TIMEOUT is not the last clause in WAIT, Visual FoxPro generates a syntax error message.

Remarks

If a WAIT message is displayed in Visual FoxPro for Windows, pressing the SHIFT or CTRL keys hides all windows including the WAIT message.

See Also

Other Resources

TRANSFORM( ) Function
ACCEPT Command
CLEAR Command
ReadTimeout Property
Commands
Language Reference


WITH ... ENDWITH Command

Visual FoxPro 9.0 Language Reference
WITH ... ENDWITH Command
See Also Example

Specifies multiple properties for an object.

WITH ObjectName [AS <Type> [OF <Class Library>]]
   [.cStatements]
ENDWITH

Parameters

ObjectName

Specifies the name of the object. ObjectName can be the name of the object or a reference to the object.
Type

A base class, class name, or type library. (For Intellisense only)
Class Library

Class library containing the base class, class name, or type library specified with Type. (For Intellisense only.)
.cStatements

cStatements can consist of any number of Microsoft Visual FoxPro commands used to specify properties for ObjectName. Place a period before cStatement to denote that it is a property of ObjectName.

Remarks

WITH ... ENDWITH provides a convenient way to specify a number of properties for a single object. Note that you can also execute methods from within a WITH ... ENDWITH structure.

Example

The following example creates a custom class name Employee. After the Employee class has been created with CREATEOBJECT( ), WITH ... ENDWITH is used to set multiple properties for the class. The properties values are then displayed.
Copy Code
moemployee = CREATEOBJECT('employee')

WITH moemployee
   .First_Name = 'John'
   .Last_Name = 'Smith'
   .Address = '16 Maple Lane'
   .HireDate = {^1998-02-16}
ENDWITH

CLEAR
? moemployee.First_Name + ' '
?? moemployee.Last_Name
? moemployee.Address
? moemployee.HireDate

DEFINE CLASS employee AS CUSTOM
      First_Name = SPACE(20)
      Last_Name = SPACE(20)
      Address = SPACE(30)
      HireDate = {  -  -  }
ENDDEFINE

See Also

Other Resources

:: Scope Resolution Operator
ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
CREATEOBJECT( ) Function
GETOBJECT( ) Function
MODIFY CLASS Command
RELEASE CLASSLIB Command
SET CLASSLIB Command
Commands
Language Reference


ZAP Command

Visual FoxPro 9.0 Language Reference
ZAP Command
See Also

Removes all records from a table, leaving just the table structure.

ZAP   [IN nWorkArea | cTableAlias]

Parameters

IN nWorkArea

Specifies the work area of the table in which all records are removed.
IN cTableAlias

Specifies the alias of the table in which all records are removed. If you omit nWorkArea and cTableAlias, all records are removed in the table in the currently selected work area.

Remarks

Issuing ZAP is equivalent to issuing DELETE ALL followed by PACK, but ZAP is much faster.

If SET SAFETY is ON, Microsoft Visual FoxPro asks if you would like to remove the records from the current table.

Issuing ZAP does not cause a Delete trigger to occur. For more information about creating triggers for a table, see CREATE TRIGGER Command.

Caution:
Records zapped from the current table cannot be recalled.

See Also

Other Resources

DELETE Command
PACK Command
Commands
Language Reference


ZOOM WINDOW Command

Visual FoxPro 9.0 Language Reference
ZOOM WINDOW Command
See Also Example

Changes the size and position of a user-defined window or a Visual FoxPro system window.

ZOOM WINDOW WindowName MIN | MAX | NORM
   [AT nRow1, nColumn1 | FROM AT nRow1, nColumn1
   [SIZE AT nRow2, nColumn2 | TO nRow2, nColumn2]]

Parameters

WindowName

Specifies the name of the window whose size you want to change.
MIN

Reduces the window to minimum size. In Visual FoxPro for Windows, the window is reduced to an icon. All system windows can be reduced to a minimum size in Visual FoxPro for Windows. Visual FoxPro system windows must be open in the main Visual FoxPro window or a user-defined window before they can be minimized. A user-defined window can be minimized after it is defined. It doesn't have to be activated before you change its size.
MAX

Expands a window to fill the main Visual FoxPro window, the Windows desktop, or a user-defined window. If a child window is placed in a parent window and the child window is maximized, it fills the parent window. If any of the additional ZOOM WINDOW clauses (AT, SIZE, TO, or FROM) are included with MAX, MAX is ignored. Only user-defined windows defined with ZOOM can be expanded to maximum size.
NORM

Returns a window to its original size after it has been minimized or maximized. NORM can also be used to move a window without changing its size. Use ZOOM WINDOW NORM without any additional clauses to return a minimized or maximized window to its original size and location.
AT nRow1, nColumn1 | FROM nRow2, nColumn2

You can specify the placement of a window by including the AT or FROM clause. ZOOM WINDOW WindowName NORM AT AT nRow1, nColumn1 restores a minimized or maximized window to its original size and places it at the specific location. The AT nRow1, nColumn1 coordinates specify where the upper-left corner of the window is placed. A window's location can also be changed with MOVE WINDOW. In Visual FoxPro for Windows, if NORM is included, the upper-left corner of the window is placed in the main Visual FoxPro window at the location specified with AT nRow1, nColumn1. If MIN is included, AT and FROM are ignored and the window is displayed as an icon in the lower portion of the main Visual FoxPro window. If MAX is included, AT and FROM are ignored and the window is expanded to fill the main Visual FoxPro window. In Visual FoxPro for Windows, if the window is created with the IN DESKTOP clause, the upper-left corner of the window is placed in the Windows desktop at the location specified with AT nRow1, nColumn1. If MIN is included, AT and FROM are ignored and the window is displayed as an icon in the lower portion of the Windows desktop. If MAX is included, AT and FROM are ignored and the window is expanded to fill the Windows desktop.
SIZE AT nRow2, nColumn2 | TO nRow2, nColumn2

You can also specify a window size for a window by including SIZE or TO. If SIZE is included, the window size is nRow2 rows high and nColumn2 columns wide. If the TO clause is included, the upper-left corner of the window remains in its current position and the lower-right corner of the window is placed at the position specified with nRow2, nColumn2.

Remarks

In Visual FoxPro for Windows, windows can be reduced to a minimum size, enlarged to fill the entire main Visual FoxPro window, or sized anywhere in between.

If you create a user-defined window with DEFINE WINDOW and the IN DESKTOP clause in Visual FoxPro for Windows, the window you create can be enlarged to fill the entire desktop.

In Visual FoxPro for Windows, windows can be zoomed directly from minimum to maximum size and vice versa.

When zooming a window, you can specify where to place the resized window in the main Visual FoxPro window or a user-defined window.

To zoom a system window, enclose the entire system window name in quotation marks. For example, to maximize the Command window, issue the following command:

Copy Code
ZOOM WINDOW 'Command Window' MAX

You can use ZOOM WINDOW to resize all system windows.

Example

In the following example, a Browse window is opened for the customer table. The Browse window is minimized. The Browse window is then returned to its default size. It is then minimized again at a specific location. The Browse window is then enlarged to a specific size and is maximized.
Copy Code
CLEAR ALL
CLEAR
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\Testdata')
USE customer  && Opens Customer table
BROWSE NORMAL NOWAIT

IF _DOS OR _WINDOWS
   ZOOM WINDOW customer MIN
   WAIT WINDOW TIMEOUT 3 ;
      'MIN clause - This window will timeout. Please wait.'
ENDIF

ZOOM WINDOW customer NORM
WAIT WINDOW TIMEOUT 3 ;
   'NORM clause - This window will timeout. Please wait.'

IF _DOS OR _WINDOWS
   ZOOM WINDOW customer MIN AT 10,10
   WAIT WINDOW TIMEOUT 3 ;
      'MIN AT 10,10 clause - This window will timeout. Please wait.'
ENDIF

ZOOM WINDOW customer NORM AT 1,1 SIZE 22,25
WAIT WINDOW TIMEOUT 3 ;
   'NORM & SIZE clauses - This window will timeout. Please wait.'
ZOOM WINDOW customer NORM FROM 10,10 TO 22,70
WAIT WINDOW TIMEOUT 3 ;
   'NORM & TO clauses - This window will timeout. Please wait.'
ZOOM WINDOW customer MAX
WAIT WINDOW TIMEOUT 3 'MAX clause - This window will timeout. Please wait.'
CLEAR ALL

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
SIZE WINDOW Command
Commands
Language Reference


Objects, Collections, and Classes

Visual FoxPro 9.0 Language Reference
Objects, Collections, and Classes
See Also

For information about backward compatible-only language reference, see Backward-Compatible Language Elements.

Application Object

CheckBox Control

Collection Class

Column Object

ComboBox Control

CommandButton Control

CommandGroup Control

Container Object

Control Object

Cursor Object

CursorAdapter Class

Custom Object

DataEnvironment Object

DataObject Object

EditBox Control

Empty Class

Exception Class

Fields Collection (XMLTable)

File Object

Files Collection

Form Object

FormSet Object

FoxCode Object Reference

Grid Control

Header Object

Hyperlink Object

Image Control

Label Control

Line Control

ListBox Control

Member Classes

Objects Collection

OLE Bound Control

OLE Container Control

OptionButton Control

OptionGroup Control

Page Object

PageFrame Control

Project Object

ProjectHook Object

Projects Collection

Relation Object

ReportListener Object

Separator Object

Server Object

Servers Collection

Session Object

Shape Control

Spinner Control

Tables Collection (XMLAdapter)

TextBox Control

THIS Object Reference

THISFORM Object Reference

THISFORMSET Object Reference

Timer Control

ToolBar Object

Visual FoxPro Foundation Classes A-Z

XMLAdapter Class

XMLField Class

XMLTable Class

See Also

Other Resources

Language Reference


Application Object

Visual FoxPro 9.0 Language Reference
Application Object
See Also Example

An object created for each instance of Visual FoxPro that exposes a set of Visual FoxPro properties and methods.

Application.PropertyName[ = eValue]
-or-
Application.Method

Parameters

PropertyName

Specifies a property for the application object.
eValue

Specifies a value for the property.
Method

Specifies a method to execute for the application object.

Remarks

Applies To: Projects Collection

Visual FoxPro is an automation server, allowing other applications such as Microsoft Excel or Visual Basic to remotely start and manipulate Visual FoxPro through properties and methods. The Application object is also available from within an instance of Visual FoxPro.

The syntax used by an application to create an instance of an automation server such as Visual FoxPro is typically unique to the application. Consult the application's documentation for the proper syntax to create an instance of an automation server and then manipulate the instance through the properties and methods.

The Objects Collection can be accessed through the Application object.

Example

You can start another instance of Visual FoxPro from within Visual FoxPro with the following command:

Copy Code
oNewInstance = CREATEOBJECT('VisualFoxPro.Application')

A new instance of Visual FoxPro is not visible when it is created; the following command makes the new instance visible:

Copy Code
oNewInstance.Visible = .T.

See Also

Other Resources

Application Object Properties, Methods and Events
CREATEOBJECT( ) Function
_VFP System Variable
Objects Collection
Objects, Collections, and Classes
Language Reference


Application Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Application Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

ActiveForm | ActiveProject | Application
AutoYield | Caption | DefaultFilePath
EditorOptions | FullName | Height
HWND | LanguageOptions | Left
Name | Objects Collection | OLERequestPendingTimeout
OLEServerBusyRaiseError | OLEServerBusyTimeout | Parent
ProcessID | Projects Collection | ServerName
StartMode | StatusBar | ThreadID
Top | Version | VFPXMLProgID
Visible | Width |

Methods

DataToClip | DoCmd | Eval
Help | Quit | RequestData
SETVAR |  |

See Also

Other Resources

Application Object
Visual FoxPro Framework Application Object
Projects Collection


CheckBox Control

Visual FoxPro 9.0 Language Reference
CheckBox Control
See Also

Creates a check box.

CheckBox

Remarks

You can use a check box to switch between three states, True (.T.), False (.F.), and Null (.NULL.). The CheckBox Value property determines the current state of the check box.

The following table illustrates the three possible states that a check box can have.

Display Value property Description

FoxCheckBox 1 button

0 or .F. (Default)

Not selected.

FoxCheckbox 2 button

1 or .T.

Selected.

FoxCheckBox 3 button

2 or .NULL.

Selected but dimmed.

This state makes it possible for the application user to decline from selecting the check box. However, the application user can clear and then select the check box.

Tip:
After interacting with the check box, the user can return the check box to the original null state by pressing CTRL+0.

The CheckBox Value property reflects the data type of the last assignment. For example, if you set the property to True (.T.) or False (.F.), the type is Logical until you set the property to a Numeric value.

If you set the CheckBox ControlSource property of the check box to a logical field in a table, the check box displays as follows:

  • As selected when the value in the current record is True (.T.).

  • As not selected when the value in the current record is False (.F.).

  • As selected but dimmed if the value in the current record is null (.NULL.).

    Note:
    If the ControlSource property is a field in a table that does not accept a null value, pressing CTRL+0 generates an error.

To specify the text that appears next to a check box, use the Caption property. To specify a picture for a check box, use the Picture property.

For additional information about CheckBox controls, see How to: Use Check Boxes to Specify States.

See Also

Other Resources

CheckBox Control Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


CheckBox Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
CheckBox Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alignment | Anchor Property | Application
AutoSize | BackColor | BackStyle
BaseClass | Caption | Centered
Class | ClassLibrary | ColorScheme
ColorSource | Comment | ControlSource
DisabledBackColor | DisabledForeColor | DisabledPicture
DownPicture | DragIcon | DragMode
Enabled | FontBold | FontCharSet
FontCondense | FontExtend | FontItalic
FontName | FontOutline | FontShadow
FontStrikethru | FontUnderline | ForeColor
Height | HelpContextID | Left
MouseIcon | MousePointer | Name
OLEDragMode | OLEDragPicture | OLEDropEffects
OLEDropHasData | Parent | ParentClass
Picture | PictureMargin | PicturePosition
PictureSpacing | ReadOnly | RightToLeft
SpecialEffect | StatusBarText | Style
TabIndex | TabStop | Tag
TerminateRead | Themes | ToolTipText
Top | Value | Visible
WhatsThisHelpID | Width | WordWrap

Methods

AddProperty | CloneObject | Drag
Move | OLEDrag | ReadExpression
ReadMethod | Refresh | ResetToDefault
SaveAsClass | SetFocus | ShowWhatsThis
WriteExpression | WriteMethod | ZOrder

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
ErrorMessage | GotFocus | Init
InteractiveChange | KeyPress | LostFocus
Message | MiddleClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | ProgrammaticChange
RightClick | UIEnable | Valid
When |  |

See Also

Other Resources

CheckBox Control
Using Controls
Caption Property
Objects, Collections, and Classes


Class Browser Object Members

Visual FoxPro 9.0 Language Reference
Class Browser Object Members
See Also

You can reference the member objects of the Class Browser. The reference to the Class Browser window itself is _oBrowser. For more information, see How to: Customize the Class Browser and Class Browser Window.

The following table lists the names of the member objects and reflects the order that the member objects appear in the Class Browser.

Class Browser object | Object name
Class description edit box | edtClassDesc
Class member edit box | edtMemberDesc
Open command button | cmdOpen
Add Additional File command button | cmdAdd
View Class Code command button | cmdExport
Find command button | cmdFind
New Class command button | cmdSubclass
Rename command button | cmdRename
Redefine command button | cmdRedefine
Remove command button | cmdRemove
Clean Up Library command button | cmdCleanup
Class Icon image | imgClassIcon
Class Icon button | cmdClassIcon
Type label for the Type combo box | lblClassType
Type combo box | cboClassType
Class List 3D effect control | txtClassList3D
Class List OLE container | oleClassList
Member List OLE container | oleMembers
Member List 3D effect control | txtMembers3D
Object Member list box | lstMembers*
Methods list box | lstClassList*
Class Description edit box | edtClassDesc
Member Description edit box | edtMemberDesc

* These objects exist only when lOutlineOCX is False (.F.).

See Also

Other Resources

Class Browser Buttons
Class Browser Methods
Class Browser Properties
Objects, Collections, and Classes


Collection Class

Visual FoxPro 9.0 Language Reference
Collection Class
See Also Example

You can use collections to group a set of related items, usually objects, which can be of any type. Collections provide a mechanism for working with objects stored in containers and include standard ways for accessing and iterating through objects in a collection. The Collection class functions as a true container class, even though it does not include the AddObject method like the Form and PageFrame classes.

The Collection class is a base class that you can subclass in program (.prg) or visual class library (.vcx) files.

Collection

Remarks

The position of an item in a collection can vary and change when changes occur in the collection.

Collections support the enumerations of items performed with the FOREACH command based on the position of items. You can control the position of these items by using the eBeforeItem or eAfterItem parameters associated with the Add method for collection objects. You can use an index value of 1, or one-based enumeration, to refer to the first item in a collection, or you can use a key value by setting the KeySort property. Collections are one-based for consistency and compatibility with other internal Visual FoxPro collections.

Make sure that either all the items in a collection have keys or none of them have keys. Deciding whether all items have keys or do not have keys provides more efficient item searching when using the Item method for collection objects and the FOR EACH command.

You can use a collection in a Visual FoxPro Component Object Model (COM) server that other COM Servers can access.

You can hide the Add and Remove methods for collection objects from public use by subclassing the collection object and marking the subclassed members as Hidden or Protected. If you do so, you need to add the collection members in the Init event or via some other method.

Items that are added to collections have the same scope as any other memory variable.

Because Collection objects support default methods, for example, Item (Collection Class), you need to be aware of the search order for these methods. A Collection object method takes precedence over a standard user-defined function (UDF) call. The following list shows the order in which Visual FoxPro searches for a function name:

  • Visual FoxPro native function

  • Collection object default method

  • UDF defined in the local program (.prg) file

  • UDF defined in calling program (.prg) files

  • Named program in the application (.app or .exe) file

  • Named program along the SET PATH list

When Visual FoxPro releases a collection, which contains object references, it also releases any objects in the collection if they are not referenced elsewhere. Make sure to release objects and any references to those objects from a collection before removing them completely from memory.

Visual FoxPro does not support intrinsic type safety. Therefore, to enforce type safety with collections, you must provide it for the class.

A native Visual FoxPro collection is designed such that the Item method makes it possible for you to run user-defined code. The Visual FoxPro Debugger does not support the evaluation of object members that are implemented as method calls. Therefore, you cannot evaluate the items in a collection.

Note:
To help debug a collection, you might write code such as the following examples, which add a member array named "Items" to reference each of the collection items:

Copy Code
LOCAL oCol AS Collection

oCol=CREATEOBJECT("collection")
oCol.Add(123)
oCol.Add("AAA")
oCol.Add(CREATEOBJECT("custom"))
oCol.Add(CREATEOBJECT("session"))
oCol.Add(CREATEOBJECT("collection"))
oCol.Item(5).Add(456)
oCol.Item(5).Add("BBB")
oCol.Item(5).Add(CREATEOBJECT("session"))
oCol.Item(5).Add(CREATEOBJECT("collection"))
oCol.Item(5).Item(4).Add(789)
oCol.Item(5).Item(4).Add("CCC")
oCol.Item(5).Item(4).Add(CREATEOBJECT("session"))
oCol.Item(5).Item(4).Add(CREATEOBJECT("Collection"))

DebugCollection(oCol)

DEBUG
SUSPEND

PROCEDURE DebugCollection(oCollection)
   IF oCollection.Count=0
      RETURN
   ENDIF
   oCollection.AddProperty("Items[1]")
   DIMENSION oCollection.Items[oCollection.Count]
   FOR i = 1 TO oCollection.Count
      oCollection.Items[m.i]=oCollection.Item[m.i]
      IF VARTYPE(oCollection.Item[m.i])="O" AND ;
         oCollection.Item[m.i].BaseClass="Collection"
         IF oCollection=oCollection.Item[m.i]
            LOOP
         ENDIF
         DebugCollection(oCollection.Item[m.i])
      ENDIF
   ENDFOR
ENDPROC

Example

At run time, the following example creates forms and a collection, adds forms to the collection using the Collection class Add method, displays the name of each form in the collection, and displays the number of forms in the collection:

Copy Code
loForm1 = CREATEOBJECT("Form")
loForm2 = CREATEOBJECT("Form")
loCol = CREATEOBJECT("Collection")
loCol.Add(loForm1)
loCol.Add(loForm2)
FOR EACH loObj IN loCol
   ? loObj.Name
ENDFOR
? loCol.Count

The following example defines a Form class which adds text boxes, buttons objects, and a collection to the form. When added to the form at run time, the collection class adds all the objects on the form to itself. The example then iterates through the collection to adjust the position of the control and prints its name to the screen.

Copy Code
LOCAL loForm, loItem, lnTop
loForm = CREATEOBJECT("myForm")
lnTop=0
FOR EACH loItem IN loForm.myCollection
   TRY
      loItem.Top = lnTop
      lnTop=lnTop+20
      ? loItem.Name
   CATCH
   ENDTRY
ENDFOR
loForm.Show(1)

DEFINE CLASS myForm AS Form
   AllowOutput=.F.
   AutoCenter=.T.
   ADD OBJECT myTextBox1 AS TextBox
   ADD OBJECT myTextBox2 AS TextBox
   ADD OBJECT myButton1 AS CommandButton
   ADD OBJECT myButton2 AS CommandButton
   ADD OBJECT myCollection AS col1
ENDDEFINE

DEFINE CLASS col1 AS Collection
   PROCEDURE Init
      FOR i = 1 TO THISFORM.Objects.Count
         THIS.Add(THISFORM.Objects(m.i))
      ENDFOR
   ENDPROC
ENDDEFINE

For other examples using the Add, Remove, and Item methods of the Collection class, see Add Method (Collection Class), Remove Method (Collection Class), and Item Method (Collection Class).

See Also

Other Resources

Objects, Collections, and Classes
Collection Object Properties, Methods, and Events
FOR EACH ... ENDFOR Command
Automation and COM Servers


Collection Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Collection Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

BaseClass | Class | ClassLibrary
Count | Comment | KeySort
Name | Parent | ParentClass
Tag |  |

Methods

Add (Collection Class) | AddProperty | GetKey
Item (Collection Class) | ReadExpression | ReadMethod
Remove (Collection Class) | ResetToDefault | SaveAsClass
WriteExpression | WriteMethod |

Events

Destroy

Error

Init

See Also

Other Resources

Collection Class


Column Object

Visual FoxPro 9.0 Language Reference
Column Object
See Also

Creates a Column object in a Grid control. A grid column can contain data from a field in a table or the value of an expression. A column can also contain controls.

Grid.Column

Remarks

To specify the data appearing in the column, use the column's DataSource property.

You can specify the number of columns in a grid with the grid's ColumnCount property.

You can add controls to a column in a grid by using the AddObject method in the Init event of the form that contains the grid. To set the active control in the grid's column, use the column's CurrentControl property. To specify the source of the control's data, set the control's ControlSource property.

Note:
You cannot access headers and controls for a column until the Init event for the grid occurs.

For additional information about creating columns in a grid, see Grid Control and Using Controls.

Hiding Columns To hide a column in a grid, set the Visible property for the column to False (.F.). You can still set the Value property of any control in the column. For example, you can still change the value of Column.Text1.Value by specifying a new value, even when the column is hidden.

Visual FoxPro processes uncommitted changes in a hidden column as usual and at the appropriate time according to BufferMode property of the form. For example, hiding a column does not cause nor prevent pending updates from being committed to that column.

When you hide a column that has focus, focus does not automatically move from the hidden column to the next or previous column. In essence, no column has focus. If you want to move focus to another cell, column, or control, you must manually move the focus, for example, by pressing the TAB key or using the mouse.

When you hide all columns in a grid, only the record-pointer portion of the grid along the left side remains visible.

Setting the AllowAutoColumnFit property and using the AutoFit method does not affect hidden columns. For more information, see AllowAutoColumnFit Property and AutoFit Method.

See Also

Other Resources

Column Object Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Header Object
Objects, Collections, and Classes
Language Reference


Column Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Column Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alignment | Application | BackColor
BaseClass | Bound | Class
ClassLibrary | ColumnOrder | Comment
ControlCount | Controls | ControlSource
CurrentControl | DynamicAlignment | DynamicBackColor
DynamicCurrentControl | DynamicFontBold | DynamicFontItalic
DynamicFontName | DynamicFontOutline | DynamicFontShadow
DynamicFontSize | DynamicFontStrikeThru | DynamicFontUnderline
DynamicForeColor | DynamicInputMask | Enabled
FontBold | FontCharSet | FontCondense
FontExtend | FontItalic | FontName
FontOutline | FontShadow | FontSize
FontStrikeThru | FontUnderline | ForeColor
Format | HeaderClass | HeaderClassLibrary
InputMask | MouseIcon | MousePointer
Movable | Name | Objects
Parent | ParentClass | ReadOnly
Resizable | SelectOnEntry | Sparse
StatusBarText | Tag | ToolTipText
Visible | Width |

Methods

AddObject | AddProperty | AutoFit
Move | ReadExpression | ReadMethod
Refresh | RemoveObject | ResetToDefault
SaveAsClass | SetAll | SetFocus
WriteExpression | WriteMethod | ZOrder

Events

Destroy | Error | Init
MouseEnter | MouseLeave | MouseMove
MouseWheel | Moved | Resize

See Also

Other Resources

Column Object
ColumnCount Property
Grid Control
Using Controls
Objects, Collections, and Classes
Language Reference


ComboBox Control

Visual FoxPro 9.0 Language Reference
ComboBox Control
See Also

Creates a combo box, which initially displays a single item. However, when you select the combo box, it displays a list of items that you can choose an item from. A combo box combines the features of a text box and a list box. You can enter information in the text box portion or select an item from the list box portion of the control.

Tip:
The Style property determines the type of list that the ComboBox control contains. To create a drop-down combo box, which displays a drop-down list and edit box, set the Style property to 0. To create a drop-list box, which displays a drop-down list only, set the Style property to 2.

To show or hide the list in a combo box, select the control and press ALT+DOWN ARROW.

For information about creating ComboBox controls, see Form Designer and Using Controls.

ComboBox

Remarks

The following table lists properties commonly set at design time.

Property | Description
ColumnCount | Determines the number of columns in the list.
ControlSource | Specifies where to store the value that the user chooses from the list.
MoverBars | Specifies whether to display mover bars to the left of the items in the list so that a user can rearrange the item order.
Multiselect | Specifies whether the user can select more than one item in the list.
RowSource | Specifies the source of the values displayed in the list.
RowSourceType | Specifies the type of the source of the values displayed in the list.

The following table lists methods commonly used.

Method | Description
AddItem | Adds an item to the list when RowSourceType is set to 0.
RemoveItem | Removes an item from the list when RowSourceType is set to 0.
Requery | Updates the list if the values in the source specified by RowSource have changed.

The backslash ("\") is treated as a special character when used in the expression for an item. The following rules apply for this character

  • You can disable an item in a list box or combo box by adding a single backslash to the beginning of the expression.

  • Any multiple of two backslashes used in the expression is displayed as a single backslash. For example, one or two backslashes used together display as one, and three or four backslashes together display as two. The following example code contains a list box item containing a Universal Naming Convention (UNC) path. The code displays in the list box as \\MyServer\MyMachine\MyFolder.

    Copy Code
    MyForm.List1.AddItem("\\\\MyServer\\MyMachine\\MyFolder")
  • If the expression begins with multiple backslashes, the item is not disabled. If you want to disable an item that begins with multiple backslashes, add a backslash and a close bracket (]) to the beginning of the item. For example, the following would disable the UNC path item in the list box.

    Copy Code
    MyForm.List1.AddItem("\]\\\MyServer\\MyMachine\\MyFolder")
  • To include a separator line use a backslash followed by a hyphen as the item to add to the list box. For example, the following code adds a separator line to a list box.

    Copy Code
    MyForm.List1.AddItem("\-")

You can also use an ActiveX control that adds extra characteristics, such as a Checkbox control, to the ListView or TreeView controls.

See Also

Other Resources

ComboBox Control Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


ComboBox Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
ComboBox Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alignment | Anchor | Application
BackColor | BaseClass | BorderColor
BorderStyle | BoundColumn | BoundTo
Class | ClassLibrary | ColorScheme
ColorSource | ColumnCount | ColumnLines
ColumnWidths | Comment | ControlSource
DisabledBackColor | DisabledForeColor | DisabledItemBackColor
DisabledItemForeColor | DisplayCount Property | DisplayValue
DragIcon | DragMode | Enabled
FirstElement | FontBold | FontCharSet
FontCondense | FontExtend | FontItalic
FontName | FontOutline | FontShadow
FontSize | FontStrikeThru | FontUnderline
ForeColor | Format | Height
HelpContextID | HideSelection | IMEMode
IncrementalSearch | InputMask | ItemBackColor
ItemData | ItemForeColor | ItemIDData
ItemTips | Left | List
ListCount | ListIndex | ListItem
ListItemID | Margin | MaxLength
MouseIcon | MousePointer | Name
NewIndex | NewItemID | NullDisplay
NumberOfElements | OLEDragMode | OLEDragPicture
OLEDropEffects | OLEDropHasData Property | OLEDropMode
OLEDropTextInsertion | Parent | ParentClass
Picture | PictureSelectionDisplay | ReadOnly
RightToLeft | RowSource | RowSourceType
Selected | SelectedBackColor | SelectedForeColor
SelectedID | SelectedItemBackColor | SelectedItemForeColor
SelectOnEntry | SelLength | SelStart
SelText | Sorted | SpecialEffect
StatusBarText | Style | TabIndex
TabStop | Tag | Text Property
TerminateRead | Themes | ToolTipText
Top | TopIndex | TopItemID
Value | Visible | WhatsThisHelpID
Width |  |

Methods

AddItem | AddListItem | AddProperty
Clear | CloneObject | Drag
IndexToItemID | ItemIDToIndex | Move
OLEDrag | ReadExpression | ReadMethod
Refresh | RemoveItem | RemoveListItem
Requery | ResetToDefault | SaveAsClass
SetFocus | SetViewPort | ShowWhatsThis
WriteExpression | WriteMethod | ZOrder

Events

Click | DblClick | Destroy
DownClick | DragDrop | DragOver
DropDown | Error | ErrorMessage
GotFocus | Init | InteractiveChange
KeyPress | LostFocus | Message
MiddleClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | OLECompleteDrag | OLEDragDrop
OLEDragOver | OLEGiveFeedBack | OLESetData
OLEStartDrag | ProgrammaticChange | RangeHigh
RangeLow | RightClick | UIEnable
UpClick | Valid | When

See Also

Other Resources

ComboBox Control
Form Designer
Using Controls
Objects, Collections, and Classes
Language Reference


CommandButton Control

Visual FoxPro 9.0 Language Reference
CommandButton Control
See Also Example

Creates a single command button.

CommandButton

Remarks

A command button is typically used to start an event that performs an action such as closing a form, moving to a different record, printing a report, and so on. Use the CommandGroup control to create a set of command buttons that you can manipulate individually or as a group.

Use the Caption property to specify the text that appears on a command button. Use the Picture property to specify a picture for a command button.

You can choose a command button by clicking it, and, if the Default property is set to True (.T.), by pressing the ENTER key when the command button is selected. If the Cancel property of the command button is set to True (.T.), you can choose the command button by pressing the ESC key.

For additional information about command buttons, see Form Designer and Using Controls.

Example

The following example demonstrates how command buttons can be added to a form. The Caption property is used to specify the text on the command buttons and the text indicating each button's access key sequence. The Cancel property is used to specify a button that is chosen when you press ESC.

The AddObject method is used to add three command buttons to the form, allowing you to change the direction in which a Line control slants or to close the form.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('shpLine','Line')  && Add a Line control to the form
frmMyForm.AddObject('cmdCmndBtn1','cmdMyCmndBtn1')  && Up Cmnd button
frmMyForm.AddObject('cmdCmndBtn2','cmdMyCmndBtn2')  && Down Cmnd button
frmMyForm.AddObject('cmdCmndBtn3','cmdMyCmndBtn3')  && Quit Cmnd button

frmMyForm.shpLine.Visible = .T.  && Make Line control visible
frmMyForm.shpLine.Top = 20  && Specify Line control row
frmMyForm.shpLine.Left = 125  && Specify Line control column

frmMyForm.cmdCmndBtn1.Visible =.T.  && Up Command button visible
frmMyForm.cmdCmndBtn2.Visible =.T.  && Down" Command button visible
frmMyForm.cmdCmndBtn3.Visible =.T.  && Quit Command button visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmndBtn1 AS CommandButton  && Create Command button
   Caption = 'Slant \<Up'  && Caption on the Command button
   Left = 50  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='/'  && Slant up
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn2 AS CommandButton  && Create Command button
   Caption = 'Slant \<Down'  && Caption on the Command button
   Left = 200  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='\'  && Slant down
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn3 AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 150  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

See Also

Other Resources

CommandButton Control Properties, Methods and Events
CommandGroup Control
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


CommandButton Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
CommandButton Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alignment | Anchor | Application
AutoSize | BackColor | BaseClass
Cancel | Caption | ClassLibrary
Class | ColorScheme | ColorSource
Comment | Default | DisabledBackColor
DisabledForeColor | DisabledPicture | DownPicture
DragIcon | DragMode | Enabled
FontBold | FontCharSet | FontCondense
FontExtend | FontItalic | FontName
FontOutline | FontShadow | FontSize
FontStrikeThru | FontUnderline | ForeColor
Height | HelpContextID | Left
MouseIcon | MousePointer | Name
OLEDragMode | OLEDragPicture | OLEDropEffects
OLEDropHasData Property | OLEDropMode | ParentClass
Parent | Picture | PictureMargin
PicturePosition | PictureSpacing | RightToLeft
SpecialEffect | StatusBarText | Style
TabIndex | TabStop | Tag
TerminateRead | Themes | ToolTipText
Top | Visible | VisualEffect
WhatsThisHelpID | Width | WordWrap

Methods

AddProperty | CloneObject | Drag
Move | OLEDrag | ReadExpression
ReadMethod | Refresh | ResetToDefault
SaveAsClass | SetFocus | ShowWhatsThis
WriteExpression | WriteMethod | ZOrder

Events

Click | Destroy | DragDrop
DragOver | Error | ErrorMessage
GotFocus | Init | KeyPress
LostFocus | Message | MiddleClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
OLECompleteDrag | OLEDragDrop | OLEDragOver
OLEGiveFeedBack | OLESetData | OLEStartDrag
RightClick | UIEnable | Valid
When |  |

See Also

Other Resources

CommandButton Control
CommandGroup Control
Form Designer
Using Controls
Objects, Collections, and Classes
Language Reference


CommandGroup Control

Visual FoxPro 9.0 Language Reference
CommandGroup Control
See Also

Creates a group of command buttons.

CommandGroup

Remarks

Use the CommandGroup control to create a set of command buttons that you can manipulate individually or as a group. Use the CommandButton control to create an individual command button.

Use the ButtonCount property to specify the number of command buttons in the group, and the Caption property to specify a label for the command button group.

For additional information about command button groups, see the Form Designer topic and Using Controls.

See Also

Other Resources

CommandGroup Control Properties, Methods and Events
CommandButton Control
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


CommandGroup Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
CommandGroup Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Anchor | Application | AutoSize
BackColor | BackStyle | BaseClass
BorderColor | BorderStyle | ButtonCount
Buttons | Class | ClassLibrary
ColorSource | Comment | ControlSource
DragIcon | DragMode | Enabled
Height | HelpContextID | Left
MemberClass | MemberClassLibrary | MouseIcon
MousePointer | Name | Objects
OLEDragMode | OLEDragPicture | OLEDropEffects
OLEDropHasData Property | OLEDropMode | Parent
ParentClass | SpecialEffect | StatusBarText
TabIndex | Tag | TerminateRead
Themes | ToolTipText | Top
Value | Visible | WhatsThisHelpID
Width |  |

Methods

AddObject | AddProperty | CloneObject
Drag | Move | NewObject
OLEDrag | ReadExpression | ReadMethod
Refresh | RemoveObject | ResetToDefault
SaveAsClass | SetAll | ShowWhatsThis
WriteExpression | WriteMethod | ZOrder

Events

Click | DblClick | DragDrop
DragOver | Error | ErrorMessage
Init | InteractiveChange | Message
MiddleClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | OLECompleteDrag | OLEDragDrop
OLEDragOver | OLEGiveFeedBack | OLESetData
OLEStartDrag | ProgrammaticChange | RightClick
UIEnable | Valid | When

See Also

Other Resources

CommandGroup Control
CommandButton Control
Objects, Collections, and Classes
Language Reference


Container Object

Visual FoxPro 9.0 Language Reference
Container Object
See Also

Creates an object that can contain other objects.

Container

Remarks

Container objects can contain other objects and allow access to the objects contained within them. For example, if you create a container object that contains two list boxes and two command buttons, and then add the container object to a form, the list boxes and command buttons can be manipulated at design time and at run time.

For more information about container objects and how they differ from other objects and controls, see Object-Oriented Programming.

See Also

Other Resources

Container Object Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


Container Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Container Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Anchor | ActiveControl | Application
BackColor | BackStyle | BaseClass
BorderColor | BorderWidth | Class
ClassLibrary | ColorSource | Comment
ControlCount | Controls | DragIcon
DragMode | Enabled | ForeColor
Height | HelpContextID | Left
MouseIcon | MousePointer | Name
Objects Collection | OLEDragMode | OLEDragPicture
OLEDropEffects | OLEDropHasData | OLEDropMode
Parent | ParentClass | Picture
SpecialEffect | StatusBarText | TabIndex
TabStop | Tag | ToolTipText
Top | Visible | WhatsThisHelpID
Width |  |

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
GotFocus | Init | LostFocus
MiddleClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Moved | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | Resize
RightClick | UIEnable |

Methods

AddObject | AddProperty | Drag
Draw | Move | NewObject
OLEDrag | ReadExpression | ReadMethod
Refresh | RemoveObject | ResetToDefault
SaveAsClass | SetAll | SetFocus
ShowWhatsThis | WriteExpression | Zorder

See Also

Other Resources

Container Object
Objects, Collections, and Classes
Language Reference


Control Object (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Control Object (Visual FoxPro)
See Also

Creates a control object that can contain other protected objects.

Control

Remarks

Control objects can contain other objects, but, unlike container objects, do not allow access to the objects contained within them. For example, if you create a control object that consists of two ListBoxes and two CommandButtons, and then add the control object to a form, the ListBoxes and CommandButtons cannot be manipulated individually at design time or at run time.

For more information about control objects and how they differ from other objects and controls, see Object-Oriented Programming.

See Also

Other Resources

Control Object Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
ListBox Control
CommandButton Control
Objects, Collections, and Classes
Language Reference


Control Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Control Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

ActiveControl | Anchor | Application
BackColor | BackStyle | BaseClass
BorderColor | BorderWidth | Class
ClassLibrary | ColorSource | Comment
ControlCount | Controls | DragIcon
DragMode | Enabled | ForeColor
Height | HelpContextID | Left
MouseIcon | MousePointer | Name
Objects | OLEDragMode | OLEDragPicture
OLEDropEffects | OLEDropHasData | OLEDropMode
Parent | ParentClass | Picture
SpecialEffect | StatusBarText | TabIndex
TabStop | Tag | ToolTipText
Top | Visible | WhatsThisHelpID
Width |  |

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
GotFocus | Init | LostFocus
MiddleClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Moved | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | Resize
RightClick | UIEnable |

Methods

AddProperty | Drag | Draw
Move | OLEDrag | ReadExpression
ReadMethod | Refresh | ResetToDefault
SaveAsClass | SetFocus | ShowWhatsThis
WriteExpression | ZOrder |

See Also

Other Resources

Control Object
Objects, Collections, and Classes
Language Reference


Cursor Object

Visual FoxPro 9.0 Language Reference
Cursor Object
See Also

Created when a table or view is added to the data environment for a form, form set, or report.

Cursor

Remarks

The cursor object makes it possible for you to specify or determine properties for the table or view when the form, FormSet or report is run.

Note that setting a cursor object property at run time generates an error (with the exception of the Filter and Order properties, which can be set at run time). For a new property setting to take effect, you must call the CloseTables and OpenTables methods for the data environment. Also, if you change the Order property at run time of a cursor that is involved in a one-to-many relationship, the one-to-many relationship is broken.

See Also

Other Resources

Cursor Object Properties, Methods and Events
DataEnvironment Object
Relation Object
How to: Set the Data Environment
Objects, Collections, and Classes
Language Reference


Cursor Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Cursor Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alias | Application | BufferModeOverride
CursorSource | Comment | Database
Exclusive | Filter | Name
NoDataOnLoad | Order | OrderDirection
ReadOnly | Tag |

Events

Destroy

Error

Init

Methods

AddProperty | ReadExpression | ReadMethod
ResetToDefault | WriteExpression |

See Also

Other Resources

Cursor Object
CURSORGETPROP( ) Function
DataEnvironment Object
Relation Object
Objects, Collections, and Classes
Language Reference


CursorAdapter Class

Visual FoxPro 9.0 Language Reference
CursorAdapter Class
See Also

Supports handling a wide range of data sources as native Visual FoxPro cursors. These data source types include the following:

  • Native

  • Open Database Connectivity (ODBC)

  • ActiveX Data Object (ADO)

  • Extensible Markup Language (XML)

CursorAdapter

Remarks

The cursor opened by a CursorAdapter object is always a buffered cursor and defaults to Optimistic Row Buffering.

For more detailed information about the CursorAdapter class, see Data Access Management Using CursorAdapters.

See Also

Reference

GETCURSORADAPTER( ) Function

Other Resources

Objects, Collections, and Classes
CursorAdapter Object Properties, Methods, and Events
Cursor Object
Relation Object
TABLEUPDATE( ) Function


CursorAdapter Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
CursorAdapter Object Properties, Methods, and Events
See Also

The following properties, methods, and events support extended cursor functionality and the use of data sources at the data environment and CursorAdapter level.

Properties

ADOCodePage | Alias | AllowDelete
AllowInsert | AllowSimultaneousFetch | AllowUpdate
BaseClass | BatchUpdateCount | BreakOnError
BufferModeOverride | Class | ClassLibrary
Comment | CompareMemo | ConflictCheckCmd
ConflictCheckType | ConversionFunc | CursorSchema
CursorStatus | DataSource | DataSourceType
DeleteCmd | DeleteCmdDataSource | DeleteCmdDataSourceType
FetchAsNeeded | FetchMemo | FetchMemoCmdList
FetchMemoDataSource | FetchMemoDataSourceType | FetchSize
Flags | InsertCmd | InsertCmdDataSource
InsertCmdDataSourceType | InsertCmdRefreshCmd | InsertCmdRefreshFieldList
InsertCmdRefreshKeyFieldList | KeyFieldList | MapBinary
MapVarchar | MaxRecords | Name
NoData | Parent | ParentClass
Prepared | RefreshAlias | RefreshCmd
RefreshCmdDataSource | RefreshCmdDataSourceType | RefreshIgnoreFieldList
RefreshTimeStamp | SelectCmd | SendUpdates
Tables | Tag | TimestampFieldList
UpdatableFieldList | UpdateCmdDataSource | UpdateCmdDataSourceType
UpdateCmd | UpdateCmdRefreshCmd | UpdateCmdRefreshFieldList
UpdateCmdRefreshKeyFieldList | UpdateGram | UpdateGramSchemaLocation
UpdateNameList | UpdateType | UseCursorSchema
UseDeDataSource | UseMemoSize | UseTransactions
WhereType |  |

Methods

AddProperty | AutoOpen | CursorAttach
CursorDetach | CursorFill | CursorRefresh
ReadExpression | ReadMethod | RecordRefresh
ResetToDefault | SaveAsClass Method | WriteExpression
WriteMethod Method |  |

Events

AfterCursorAttach | AfterCursorClose | AfterCursorDetach
AfterCursorFill | AfterCursorRefresh | AfterCursorUpdate
AfterDelete | AfterInsert | AfterRecordRefresh
AfterUpdate | BeforeCursorAttach | BeforeCursorClose
BeforeCursorDetach | BeforeCursorFill | BeforeCursorRefresh
BeforeCursorUpdate | BeforeDelete | BeforeInsert
BeforeRecordRefresh | BeforeUpdate | Destroy
Error | Init |

See Also

Reference

GETCURSORADAPTER( ) Function

Other Resources

CursorAdapter Class


Custom Object

Visual FoxPro 9.0 Language Reference
Custom Object
See Also

Creates a custom, user-defined object.

Custom

Remarks

A custom, user-defined class can be created with DEFINE CLASS, or with the Class Designer. Issue CREATE CLASS to display the Class Designer.

Custom, user-defined classes are classes with properties, events, and methods, but with no visual representation. The same general rules that apply to defining other types of classes apply to defining custom classes.

See Object-Oriented Programming for additional information about creating custom objects as non-visual classes.

See Also

Other Resources

Custom Object Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


Custom Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Custom Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Application | BaseClass | Class
ClassLibrary | Comment | ControlCount
Controls | Height | HelpContextID
Left | Name | Objects
Parent | ParentClass | Picture
Tag | Top | WhatsThisHelpID
Width |  |

Events

Destroy

Error

Init

Methods

AddObject | AddProperty | NewObject
ReadExpression | ReadMethod | RemoveObject
ResetToDefault | SaveAsClass | ShowWhatsThis
WriteExpression | WriteMethod |

See Also

Other Resources

Custom Object
Object-Oriented Programming
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
CursorToXML( ) Function
Objects, Collections, and Classes
Language Reference


DataEnvironment Object

Visual FoxPro 9.0 Language Reference
DataEnvironment Object
See Also

Created when you create a form, form set, or report. A DataEnvironment object functions as a container for the Cursor, CursorAdapter, and Relation objects associated with the form, form set, or report.

Note:
You can set only the following DataEnvironment properties at run time: DataSource, DataSourceType, InitialSelectedAlias, Name, OpenViews, and Tag. For a new property setting to take effect, you must call the CloseTables and OpenTables methods for the DataEnvironment object. Setting any other DataEnvironment properties at run time generates an error.

DataEnvironment

Remarks

You can define and subclass the DataEnvironment class. From a form, you can save the existing data environment as a visual class library (.vcx) file by selecting the form, choosing Save As Class from the File menu, and selecting DataEnvironment. All DataEnvironment properties, methods, and events are available as appropriate in the Properties window after you open the Class Designer. However, you can access the Data Environment Designer only from the Form Designer, not from the Class Designer.

At design time, you can add a preexisting DataEnvironment class to a form from a class library toolbar or in code using the AddObject method. However, Visual FoxPro considers the DataEnvironment class added in either manner as a member class, not a native data environment.

You can use the Form DEClass and DEClassLibrary properties to specify and load an external DataEnvironment class at design time or run time. Visual FoxPro supports the DEClass and DEClassLibrary properties for form (.scx), visual class library (.vcx), and program (.prg) files but not for form sets or in the Report Designer.

For more information, see the DEClass and DEClassLibrary properties. For more information about the data environment for forms and form sets, see Creating Forms.

See Also

Other Resources

Objects, Collections, and Classes
DataEnvironment Object Properties, Methods and Events
Form Object
AddObject Method
Cursor Object
CursorAdapter Class
Objects, Collections, and Classes
Language Reference


DataEnvironment Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
DataEnvironment Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Application | AutoCloseTables | AutoOpenTables
Comment | DataSource | DataSourceType
InitialSelectedAlias | Name | Objects
OpenViews | Tag |

Events

AfterCloseTables | BeforeOpenTables | Destroy
Error | Init |

Methods

AddObject | AddProperty | CloseTables
OpenTables | ReadExpression | ReadMethod
RemoveObject | ResetToDefault | SaveAsClass
WriteExpression |  |

See Also

Other Resources

DataEnvironment Object
Creating Forms
Objects, Collections, and Classes
Language Reference


DataObject Object

Visual FoxPro 9.0 Language Reference
DataObject Object
See Also

Container for data being transferred from an OLE drag source to an OLE drop target. Available at run time only.

oDataObject

Remarks

The DataObject object is a container for data being transferred from an OLE drag source to an OLE drop target, and exists only for the duration of an OLE drag-and-drop event. The DataObject object cannot be created programmatically and references to it become invalid once the OLE drag-and-drop operation is complete. The DataObject is passed as the oDataObject parameter in the OLEDragDrop, OLEDragOver, OLESetData, and OLEStartDrag events.

The DataObject can store multiple sets of data, each in a different format. Use the GetFormat and GetData methods to determine the data formats and data on the DataObject. Use the SetFormat, SetData, or ClearData methods to add data formats and data to the DataObject, or clear all data formats and data from the DataObject.

See Also

Other Resources

DataObject Object Properties, Methods and Events
OLE Drag-and-Drop Overview
OLEDragDrop Event
OLEDragOver Event
OLESetData Event
OLEStartDrag Event
Objects, Collections, and Classes
Language Reference


DataObject Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
DataObject Object Properties, Methods, and Events
See Also

The following table lists the methods reference topics for this object.

Methods

ClearData | SetData
GetData | SetFormat
GetFormat |

See Also

Other Resources

DataObject Object


EditBox Control

Visual FoxPro 9.0 Language Reference
EditBox Control
See Also

Creates an edit box.

EditBox

Remarks

You can use an edit box to edit the values in fields of Memo type and in variables, array elements, and fields with Character type. You can use an edit box to view the contents of a field of Blob type; however, the contents are read-only. The edit box displays Blob type data as hexadecimal values without the 0h prefix. For more information, see Visual FoxPro Data and Field Types.

All standard Visual FoxPro editing features, such as cut, copy, and paste are available for an edit box. The text in the edit box scrolls vertically, and text wraps horizontally.

For additional information about creating and using controls, see Using Controls.

See Also

Other Resources

EditBox Control Properties, Methods and Events
Objects, Collections, and Classes
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command


EditBox Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
EditBox Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

AddLineFeeds | Alignment | AllowTabs
Anchor | Application | BackColor
BackStyle | BaseClass | BorderColor
BorderStyle | ClassLibrary | Class
ColorScheme | ColorSource | Comment
ControlSource | DisabledBackColor | DisabledForeColor
DragIcon | DragMode | EnableHyperlinks
Enabled | FontBold | FontCharSet
FontCondense | FontExtend | FontItalic
FontName | FontOutline | FontShadow
FontSize | FontStrikeThru | FontUnderline
ForeColor | Format | Height
HelpContextID | HideSelection | IMEMode
IntegralHeight | Left | Margin
MaxLength | MouseIcon | MousePointer
Name | NullDisplay | OLEDragMode
OLEDragPicture | OLEDropEffects | OLEDropHasData
OLEDropMode | OLEDropTextInsertion | ParentClass
Parent | PasswordChar | ReadOnly
RightToLeft | ScrollBars | SelectedBackColor
SelectedForeColor | SelectOnEntry | SelLength
SelStart | SelText | SpecialEffect
StatusBarText | TabIndex | TabStop
Tag | TerminateRead | Text
ToolTipText | Top | Value
Visible | WhatsThisHelpID | Width

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
ErrorMessage | GotFocus | Init
InteractiveChange | KeyPress | LostFocus
Message | MiddleClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | ProgrammaticChange
RightClick | UIEnable | Valid
When |  |

Methods

AddProperty | CloneObject | Drag
Move | OLEDrag | ReadExpression
ReadMethod | Refresh | ResetToDefault
SaveAsClass | SetFocus | ShowWhatsThis
WriteExpression | WriteMethod | ZOrder

See Also

Other Resources

EditBox Control


Empty Class

Visual FoxPro 9.0 Language Reference
Empty Class
See Also

Creates an empty class that instantiates and releases quickly for use with business objects.

Empty

Remarks

The Empty base class contains no intrinsic properties, methods or events. You cannot subclass or add custom methods and events to the Empty class. However, at run time, you can add custom properties using the ADDPROPERTY( ) function or the SCATTER NAME...ADDITIVE command.

The Empty class is typically used in the following scenarios:

  • When adding properties to or removing properties from a running instance of the class using the ADDPROPERTY( ) and REMOVEPROPERTY( ) functions.

  • When using the SCATTER...NAME command with the ADDITIVE clause to populate contents from the current record.

See Also

Other Resources

Objects, Collections, and Classes
ADDPROPERTY( ) Function
REMOVEPROPERTY( ) Function
SCATTER Command


Exception Class (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Exception Class (Visual FoxPro)
See Also Example

When an error occurs in the TRY block within a TRY...CATCH...FINALLY error handling structure, Visual FoxPro creates an Exception object automatically and uses the VarName memory variable specified in the CATCH TO clause to store a reference to the exception. The THROW command also generates an Exception object. However, if no TRY...CATCH...FINALLY structure traps the thrown exception, Visual FoxPro escalates the exception another error handler or Visual FoxPro's global error handler.

You can define and subclass the Exception class.

Exception

Remarks

Visual FoxPro supports the Exception class only in program (.prg) files.

Exception objects do not support all the various error information, including Component Object Model (COM), Open Database Connectivity (ODBC), and database triggers, that you can usually obtain from the AERROR( ) function. However, you can access AERROR( ) information inside the TRY...CATCH block.

Example

Copy Code
oError = CREATEOBJECT("exception")

See Also

Other Resources

Objects, Collections, and Classes
Exception Object Properties, Methods, and Events
TRY...CATCH...FINALLY Command
Structured Error Handling


Exception Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Exception Object Properties, Methods, and Events
See Also

All properties, methods, and events for Exception objects are read/write at run time.

Properties

BaseClass | Class | ClassLibrary
Comment | Details | ErrorNo
LineContents | LineNo | Message
Name | Parent | ParentClass
Procedure | StackLevel | Tag
UserValue |  |

Methods

AddProperty | ReadExpression | ReadMethod
ResetToDefault | SaveAsClass | WriteExpression
WriteMethod |  |

Events

Destroy

Error

Init

See Also

Other Resources

Exception Class
TRY...CATCH...FINALLY Command
Structured Error Handling


Fields Collection (XMLTable)

Visual FoxPro 9.0 Language Reference
Fields Collection (XMLTable)
See Also

Each XMLTable object contains, at most, a single Fields collection containing XMLField objects. Each XMLField represents the structure of a field that is meaningful to Visual FoxPro.

When an XMLAdapter object analyzes XML by executing its LoadXML or Attach methods, it factors the contained XML schema into one or more XMLTable objects and corresponding XMLField objects. Visual FoxPro translates the XML schema for each field, creates corresponding XMLField objects, and adds them to the XMLTable Fields collection.

XMLTable.Fields

See Also

Other Resources

Objects, Collections, and Classes
XMLTable Object Properties, Methods, and Events
XMLAdapter Class
LoadXML Method
Attach Method
XMLTable Class
XMLField Class


File Object (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
File Object (Visual FoxPro)
See Also

Instantiated when a file is added to a project.

File

Remarks

A file object is created and instantiated for each file added to a project. A file object provides an object reference to the file in the project, and allows you to determine information about the file and manipulate it through the File object properties and methods.

A project's files collection is composed of all the file objects in the project.

Note that a file object is a COM object, so assigning a file object reference to a memory variable creates a memory variable of class "Unknown Type."

See Also

Other Resources

File Object Properties, Methods and Events
Files Collection
How to: Add Files to a Project
Objects, Collections, and Classes
Language Reference


File Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
File Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

CodePage | Description | Exclude
FileClass | FileClassLibrary | LastModified
Name | ReadOnly | SCCStatus
Type |  |

Methods

AddToSCC | CheckIn | CheckOut
GetLatestVersion | Modify | Remove
RemoveFromSCC | Run | UndoCheckOut

See Also

Other Resources

File Object
Files Collection
How to: Add Files to a Project
Objects, Collections, and Classes
Language Reference


Files Collection (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Files Collection (Visual FoxPro)
See Also

A collection of file objects in a project.

Files

Remarks

The files collection consists of all the files in a project. Each file is an object that can be manipulated with the file object properties and methods.

Files in a file collection can be referenced by index number or name. For example, the following code opens the file that was first added to a project:

Copy Code
_VFP.ActiveProject.Files(1).Modify( )

The following code opens an editing window for Main.prg:

Copy Code
_VFP.ActiveProject.Files('Main.prg').Modify( )

Note that it isn't necessary to include the path with a file name.

For more information about the files collection and projects, see Project Manager Hooks under Development Productivity Tools.

See Also

Other Resources

Files Collection Properties, Methods and Events
File Object
Project Manager Hooks
Objects, Collections, and Classes
Language Reference


Files Collection Properties and Methods

Visual FoxPro 9.0 Language Reference
Files Collection Properties and Methods
See Also

Properties

Count

Methods

Add

Item

See Also

Other Resources

Files Collection
File Object
Project Manager Hooks
Development Productivity Tools
Objects, Collections, and Classes
Language Reference


Form Object

Visual FoxPro 9.0 Language Reference
Form Object
See Also

Creates a form to which you can add controls.

Form

Remarks

Forms have properties that determine their appearance, such as position, size, and color, and their behavior, for example, whether they are sizable. You can also use the Form Designer to design a form.

Forms can respond to events initiated by a user or triggered by the system. For example, you can write code in a form's Click event procedure that changes the color of the form when you click it. You can use methods to manipulate forms. For example, you can use the Move method to change a form's location and size. From within a program, you can use the Hide and Show methods to make forms transparent or visible at run time.

For additional information about creating forms, see Creating Forms.

See Also

Other Resources

Form Object Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
FormSet Object Command
DataEnvironment Object
Objects, Collections, and Classes
Language Reference


Form Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Form Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

ActiveControl | ActiveForm | AllowOutput
AlwaysOnBottom | AlwaysOnTop | Application
AutoCenter | BackColor | BaseClass
BindControls | BorderStyle | BufferMode
Caption | Class | ClassLibrary
ClipControls | Closable | ColorSource
Comment | ContinuousScroll | ControlBox
ControlCount | Controls | CurrentX
CurrentY | DataEnvironment | DataSession
DataSessionID | DefOLELCID | DEClass
DEClassLibrary | Desktop | Dockable
Docked | DockPosition | DrawMode
DrawStyle | DrawWidth | Enabled
FillColor | FillStyle | FontBold
FontCharSet | FontCondense | FontExtend
FontItalic | FontName | FontOutline
FontShadow | FontSize | FontStrikeThru
FontUnderline | ForeColor | HalfHeightCaption
Height | HelpContextID | HScrollSmallChange
hWnd | Icon | KeyPreview
Left | LockScreen | MacDesktop
MaxButton | MaxHeight | MaxLeft
MaxTop | MaxWidth | MDIForm
MinButton | MinHeight | MinWidth
MouseIcon | MousePointer | Movable
Name | Objects | OLEDragMode
OLEDragPicture | OLEDropEffects | OLEDropHasData
OLEDropMode | Parent | ParentClass
Picture | ReleaseType | RightToLeft
ScaleMode | ScrollBars | ShowInTaskbar
ShowTips | ShowWindow | SizeBox
TabIndex | TabStop | Tag
Themes | TitleBar Property | Top
ViewPortHeight | ViewPortLeft | ViewPortTop
ViewPortWidth | Visible | VScrollSmallChange
WhatsThisButton | WhatsThisHelpID | Width
WindowType | WindowState | ZoomBox

Methods

AddObject | AddProperty | Box
Circle | Cls | Dock
Draw | GetDockState | Hide
Line | Move | NewObject
OLEDrag | Point | Print
PSet | ReadExpression | ReadMethod
Refresh | Release | RemoveObject
ResetToDefault | SaveAs | SaveAsClass
SetAll | SetViewPort | Show
ShowWhatsThis | TextHeight | TextWidth
WhatsThisMode | WriteExpression | WriteMethod
ZOrder |  |

Events

Activate | AfterDock | BeforeDock
Click | DblClick | Deactivate
Destroy | DragDrop | DragOver
Error | GotFocus | Init
KeyPress | Load | LostFocus
MiddleClick | MouseDown | MouseMove
MouseUp | MouseWheel | Moved
OLECompleteDrag | OLEDragDrop | OLEDragOver
OLEGiveFeedBack | OLESetData | OLEStartDrag
Paint | QueryUnload | Resize
RightClick | Scrolled | Undock
Unload |  |

See Also

Other Resources

Form Object
Objects, Collections, and Classes
Language Reference


FormSet Object

Visual FoxPro 9.0 Language Reference
FormSet Object
See Also

Creates a form set.

FormSet

Remarks

A form set is a container object that contains a set of forms. Form sets are similar to screen sets used in previous FoxPro versions.

For additional information about creating form sets, see How to: Extend Forms with Form Sets.

See Also

Other Resources

FormSet Object Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Form Object
Objects, Collections, and Classes
Language Reference


FormSet Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
FormSet Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

ActiveForm | Application | AutoRelease
BaseClass | Buffermode | Class
ClassLibrary | Comment | DataEnvironment
DataSession | DataSessionID | FormCount
Forms | Name | Objects
Parent | ParentClass | ReadBackColor
ReadCycle | ReadForeColor | ReadLock
ReadMouse | ReadSave | ReadTimeOut
Tag | Visible | WindowList
WindowType |  |

Events

Activate | Deactivate | Destroy
Error | Init | Load
ReadActivate | ReadDeactivate | ReadShow
ReadValid | ReadWhen | Unload

Methods

AddObject | AddProperty | Hide
NewObject | ReadExpression | ReadMethod
Refresh | Release | RemoveObject
ResetToDefault | SaveAs | SaveAsClass
SetAll | Show | WriteExpression
WriteMethod |  |

See Also

Other Resources

FormSet Object
How to: Extend Forms with Form Sets
Objects, Collections, and Classes
Language Reference


FoxCode Object Reference

Visual FoxPro 9.0 Language Reference
FoxCode Object Reference
See Also

Provides metadata for use by scripts in the Data field of IntelliSense items in the IntelliSense table.

FoxCode.PropertyName [= eValue]

Parameters

PropertyName

Specifies a FoxCode object property.
eValue

Specifies a value for the property. The following table describes the properties and values available.

PropertyName eValue

Abbrev

Specifies contents of the Abbrev field.

Case

Specifies contents of the Case field.

Cmd

Specifies contents of the Cmd field.

CursorLocChar

Specifies a special character denoting the location to position the cursor after script runs. (Default character is a tilde (~).)

Data

Specifies contents of the Data field.

DefaultCase

Specifies default letter casing setting in the IntelliSense table as derived from the Version record, whose Type is set to "V".

Expanded

Specifies contents of the Expanded field.

Filename

Specifies the name of file being edited.

FullLine

Specifies full text from the line currently typed.

Icon

Specifies the icon to use with Items array.

Items

Specifies an array to use for populating a list box that displays following running a script. Requires ValueType set to "L".

Items[1,1] – Text to display in list Items[1,2] – Value tip for item

The only required element is the first element for each row in the Items array. By default, the array is sorted in ascending order so incremental seek operations can be performed. Users can use the ItemSort property to turn this functionality off and use a natural sort order.

ItemScript

Specifies the script to use with Items array.

ItemSort

Specifies whether to sort Items array (Default is set to .T.)

Location

Specifies type of editor to edit:

0 – Command Window

1 – Program

8 – Menu Editor

10 – Code Editor

12 – Stored Procedure

Menuitem

Specifies the menu item selected if user is running a script with ValueType set to "L". Can be used in a subsequent script.

ParamNum

Specifies parameter number of the function for script call made within a function.

Save

Specifies contents of the Save field.

Source

Specifies contents of the Source field.

Timestamp

Specifies contents of the Timestamp field.

Tip

Specifies contents of the Tip field.

Type

Specifies contents of the Type field.

UniqueId

Specifies contents of the UniqueId field.

User

Specifies contents of the User field.

UserTyped

Specifies the text the user typed. Does not include the activator key or any leading spaces or tabs. To include activator key, leading spaces or tabs, use FullLine property instead.

ValueTip

Specifies Quick Info tip to display when ValueType is set to "T".

ValueType

Specifies handler for action following script execution:

L – Displays a drop-down list box populated from the Items array.

V – Displays a list of values.

T – Displays a Quick Info Tip window from ValueTip.

Remarks

The Data field of records in the IntelliSense table, specified by the _FOXCODE system variable, generally contains script code. For more information, see IntelliSense Table Structure.

The FoxCode object reference is typically stored in a variable called oFoxcode in IntelliSense scripts. For more information, see How to: Create IntelliSense Scripts.

See Also

Other Resources

_FOXCODE System Variable
Objects, Collections, and Classes


Grid Control

Visual FoxPro 9.0 Language Reference
Grid Control
See Also Example

Creates a grid.

Grid

Remarks

A grid is a container object that displays data in rows and columns, and is similar in appearance to a Browse window. A grid is also a container object that contains column objects. A column can contain a Header object and controls. Because a grid and its columns, headers, and controls each have their own set of properties, you have complete control over each element of the grid. You can create a grid interactively using the Grid Builder.

For additional information about creating grids, see Using Controls.

Example

The following example places a Grid control on a form. The customer table is opened and its contents are displayed in the grid. The Caption property is used to specify a different header caption (Customer ID) for the CUST_ID field. A command button is placed on the form to close the form.

The SetAll method is used with the DynamicBackColor property to specify the background colors for the records. If the number of a record displayed in the grid is even, the record's DynamicBackColor is white, otherwise its DynamicBackColor is green.
Copy Code
CLOSE ALL  && Close tables and databases
OPEN DATABASE (HOME(2) + 'data\testdata')

USE customer  IN 0  && Opens Customer table

frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the window pop-up menu

frmMyForm.AddObject('cmdCommand1','cmdMyCmdBtn')  && Add Command button
frmMyForm.AddObject('grdGrid1','Grid')  && Add Grid control

frmMyForm.grdGrid1.Left = 25  && Adjust Grid position

frmMyForm.grdGrid1.SetAll("DynamicBackColor", ;
   "IIF(MOD(RECNO( ), 2)=0, RGB(255,255,255) ;
   , RGB(0,255,0))", "Column")  && Alternate white and green records

frmMyForm.grdGrid1.Visible = .T.  && Grid control visible
frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible
frmMyForm.grdGrid1.Column1.Header1.Caption = 'Customer ID'

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close form
      CLOSE ALL  && Close table and database
ENDDEFINE

See Also

Other Resources

Grid Control Properties, Methods and Events
Column Object
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Header Object
Objects, Collections, and Classes
Language Reference


Grid Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Grid Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

ActiveColumn | ActiveRow | AllowAddNew
AllowAutoColumnFit | AllowCellSelection | AllowHeaderSizing
AllowRowSizing | Anchor | Application
BackColor | BaseClass | ChildOrder
ClassLibrary | Class | ColumnCount
Columns | Comment | DeleteMark
DragIcon | DragMode | Enabled
FontBold | FontCharSet | FontCondense
FontExtend | FontItalic | FontName
FontOutline | FontShadow | FontSize
FontStrikeThru | FontUnderline | ForeColor
GridLineColor | GridLines | GridLineWidth
HeaderHeight | Height | HelpContextID
HighLight | HighlightBackColor | HighlightForeColor
HighlightStyle | HighLightRow | HighlightRowLineWidth
LeftColumn | Left | LinkMaster
LockColumns | LockColumnsLeft | MemberClass
MemberClassLibrary | MouseIcon | MousePointer
Name | Objects | OLEDragMode
OLEDragPicture | OLEDropEffects | OLEDropHasData
OLEDropMode | Optimize | PanelLink
Panel | ParentClass | Parent
Partition | ReadOnly | RecordMark
RecordSource | RecordSourceType | RelationalExpr
RelativeColumn | RelativeRow | RightToLeft
RowColChange | RowHeight | ScrollBars
SelectedItemBackColor | SelectedItemForeColor | SplitBar
StatusBarText | TabIndex | TabStop
Tag | Themes | ToolTipText
Top | Value | View
Visible | WhatsThisHelpID | Width

Methods

ActivateCell | AddColumn | AddObject
AddProperty | AutoFit | CloneObject
DeleteColumn | DoScroll | Drag
GridHitTest | Move | OLEDrag
ReadExpression | ReadMethod | Refresh
RemoveObject | ResetToDefault | SaveAsClass
SetAll | SetFocus | WriteExpression
WriteMethod | Zorder |

Events

AfterRowColChange | BeforeRowColChange | Click
DblClick | Deleted | Destroy
DragDrop | DragOver | Error
Init | KeyPress | MiddleClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
OLECompleteDrag | OLEDragDrop | OLEDragOver
OLEGiveFeedBack | OLESetData | OLEStartDrag
Resize | RightClick | Moved
Scrolled | UIEnable | Valid
When |  |

See Also

Other Resources

Grid Control
Objects, Collections, and Classes
Language Reference


Header Object

Visual FoxPro 9.0 Language Reference
Header Object
See Also Example

Creates a header for a column in a Grid control. Each column in a grid contains a header. A header displays the caption and an image at the top of a column, and it can respond to events. For additional information about creating headers in grids, see Using Controls.

Header

Remarks

Resizing grid column headers does not trigger the Click event for the column header. This affects column separators.

Example

The following example uses the Header object with the Caption property to change the caption of the first header in a grid.

A Grid control is placed on a form and the customer table is opened and its contents displayed in the grid. The Header object and the Caption property are used to specify a different header caption (Customer ID) for the first header in the grid.

The SetAll method is used with the DynamicBackColor property to specify the background colors for the records. If the number of a record displayed in the grid is even, the record's DynamicBackColor is white, otherwise its DynamicBackColor is green. A command button is placed on the form to close the form.
Copy Code
CLOSE ALL  && Close tables and databases
OPEN DATABASE (HOME(2) + 'data\testdata')

USE customer  IN 0  && Opens Customer table

frmMyForm = CREATEOBJECT('form')  && Create a form
frmMyForm.Closable = .f.  && Disable the window pop-up menu

frmMyForm.AddObject('cmdCommand1','cmdMyCmdBtn')  && Add Command button
frmMyForm.AddObject('grdGrid1','Grid')  && Add Grid control

frmMyForm.grdGrid1.Left = 25  && Adjust Grid position

frmMyForm.grdGrid1.SetAll("DynamicBackColor", ;
   "IIF(MOD(RECNO( ), 2)=0, RGB(255,255,255) ;
   , RGB(0,255,0))", "Column")  && Alternate white and green records

frmMyForm.grdGrid1.Visible = .T.  && Grid control visible
frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible
frmMyForm.grdGrid1.Column1.Header1.Caption = 'Customer ID'

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close form
      CLOSE ALL  && Close table and database
ENDDEFINE

See Also

Other Resources

Header Object Properties, Methods and Events
Column Object
CREATE FORM Command
CREATE CLASS Command
DEFINE CLASS Command
Grid Control
Objects, Collections, and Classes
Language Reference


Header Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Header Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alignment | Anchor | Application
BackColor | BaseClass | Caption
Class | ClassLibrary | Comment
FontBold | FontCharSet | FontCondense
FontExtend | FontItalic | FontName
FontOutline | FontShadow | FontSize
FontStrikeThru | FontUnderline | ForeColor
MouseIcon | MousePointer | Name
Parent | ParentClass | Picture
StatusBarText | Tag | ToolTipText
WordWrap |  |

Events

Click | DblClick | Destroy
Error | Init | MiddleClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
RightClick |  |

Methods

AddProperty | ReadExpression | ReadMethod
Refresh | ResetToDefault | SaveAsClass
WriteExpression | WriteMethod |

See Also

Other Resources

Header Object
HEADER( ) Function
HeaderHeight Property
Objects, Collections, and Classes
Language Reference


Hyperlink Object

Visual FoxPro 9.0 Language Reference
Hyperlink Object
See Also

Creates a Hyperlink object.

Hyperlink

Remarks

A Hyperlink object provides navigational capabilities for Visual FoxPro applications hosted in containers such as Microsoft Internet Explorer.

Note that the Hyperlink object is supported only in Microsoft Internet Explorer. Use the Visual FoxPro Hyperlink Button, Hyperlink Image, or Hyperlink Label foundation classes in the Using the Component Gallery for browser independent navigational capabilities.

See Also

Other Resources

Hyperlink Object Properties, Methods and Events
Hyperlink Button Foundation Class
Hyperlink Image Foundation Class
Hyperlink Label Foundation Class
Using the Component Gallery
Objects, Collections, and Classes
Language Reference


Hyperlink Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Hyperlink Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Application | BaseClass | Class
ClassLibrary | Comment | Name
Parent | ParentClass | Tag

Events

Destroy

Error

Init

Methods

AddProperty | SaveAsClass
ResetToDefault | ReadMethod
ReadExpression | WriteExpression

See Also

Other Resources

Hyperlink Object
Hyperlink Button Foundation Class
Hyperlink Image Foundation Class
Hyperlink Label Foundation Class
Using the Component Gallery
Objects, Collections, and Classes
Language Reference


Image Control (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Image Control (Visual FoxPro)
See Also

Creates an Image control that displays a GDI+ compliant picture.

Image

Remarks

An Image control is a graphical control that displays bitmaps that can't be changed directly. However, because an Image control has a full set of properties, events, and methods that other controls have, an Image control can respond to events and can be changed dynamically at run time.

For additional information about creating Images, see Using Controls.

See Also

Other Resources

Image Control Properties, Methods, and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


Image Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Image Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Anchor | Application | BackStyle
BaseClass | BorderColor | BorderStyle
Class | ClassLibrary | ColorSource
Comment | DragIcon | DragMode
Enabled | Height | HelpContextID
Left | MousePointer | Name
OLEDragMode | OLEDragPicture | OLEDropEffects
OLEDropHasData Property | OLEDropMode | Parent
ParentClass | Picture | PictureVal
RotateFlip | StatusBarText | Stretch
Tag | Themes | ToolTipText
Top | Visible | WhatsThisHelpID
Width |  |

Methods

AddProperty | CloneObject | Drag
Move | OLEDrag | ReadExpression
ReadMethod | ResetToDefault | SaveAsClass
WriteExpression | WriteMethod | Zorder

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
Init | MiddleClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | RightClick
UIEnable |  |

See Also

Other Resources

Image Control
Objects, Collections, and Classes
Language Reference


Label Control (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Label Control (Visual FoxPro)
See Also

Creates a label that displays text.

Label

Remarks

A Label control is a graphical control that displays text that can't be changed directly. However, because a Label control has a full set of properties, events, and methods that other controls have, the Label control can respond to events and can be changed dynamically at run time.

To assign an access key to a label, include a backslash and a less-than sign ("\<") in the caption immediately preceding the character you want to designate as the access key. When the label is displayed, the character is underlined. Pressing the access key for a label activates the next control in the tab order. Use the TabIndex property to assign a tab order to a label.

Captions are displayed differently depending on the object.

256 is the maximum number of characters for the Caption property for a Label control.

For additional information about creating Label controls, see Using Controls.

See Also

Other Resources

Label Control Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


Label Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Label Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alignment | Anchor | Application
AutoSize | BackColor | BackStyle
BaseClass | BorderStyle | Caption
Class | ClassLibrary | ColorScheme
ColorSource | Comment | DisabledBackColor
DisabledForeColor | DragIcon | DragMode
Enabled | FontBold | FontCharSet
FontCondense | FontExtend | FontItalic
FontName | FontOutline | FontShadow
FontSize | FontStrikeThru | FontUnderline
ForeColor | Height | HelpContextID
Left | MouseIcon | MousePointer
Name | OLEDragMode | OLEDragPicture
OLEDropEffects | OLEDropHasData | OLEDropMode
Parent | ParentClass | RightToLeft
Rotation | StatusBarText | Style
TabIndex | Tag | ToolTipText
Top | Visible | WhatsThisHelpID
Width | WordWrap |

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
Init | MiddleClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | RightClick
UIEnable |  |

Methods

AddProperty | CloneObject | Drag
Move | OLEDrag | ReadExpression
ReadMethod | Refresh | ResetToDefault
SaveAsClass | UIEnable | WriteExpression
WriteMethod | ZOrder |

See Also

Other Resources

Label Control
Using Controls
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


Line Control

Visual FoxPro 9.0 Language Reference
Line Control
See Also Example

Creates a control that displays a horizontal, vertical, or diagonal line.

Line

Remarks

A Line control is a graphical control that displays a horizontal, vertical, or diagonal line that can't be changed directly. However, because a Line control has a full set of properties, events, and methods that other controls have, the Line control can respond to events and can be changed dynamically at run time.

For additional information about creating lines, see the Form Designer topic and Using Controls.

Example

The following example demonstrates how a Line control can be added to a form and how you can use the LineSlant property to specify the direction in which the line slants.

The AddObject method is used to add a Line control to a form. Three command buttons are added to the form, allowing you to change the direction in which the line slants or to close the form.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('shpLine','Line')  && Add a Line control to the form
frmMyForm.AddObject('cmdCmndBtn1','cmdMyCmndBtn1')  && Up Cmnd button
frmMyForm.AddObject('cmdCmndBtn2','cmdMyCmndBtn2')  && Down Cmnd button
frmMyForm.AddObject('cmdCmndBtn3','cmdMyCmndBtn3')  && Quit Cmnd button

frmMyForm.shpLine.Visible = .T.  && Make Line control visible
frmMyForm.shpLine.Top = 20  && Specify Line control row
frmMyForm.shpLine.Left = 125  && Specify Line control column

frmMyForm.cmdCmndBtn1.Visible =.T.  && Up Command button visible
frmMyForm.cmdCmndBtn2.Visible =.T.  && Down" Command button visible
frmMyForm.cmdCmndBtn3.Visible =.T.  && Quit Command button visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmndBtn1 AS COMMANDBUTTON  && Create Command button
   Caption = 'Slant \<Up'  && Caption on the Command button
   Left = 50  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='/'  && Slant up
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn2 AS CommandButton  && Create Command button
   Caption = 'Slant \<Down'  && Caption on the Command button
   Left = 200  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='\'  && Slant down
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn3 AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 150  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

See Also

Other Resources

Line Control Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


Line Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Line Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Anchor | Application | BaseClass
BorderColor | BorderStyle | BorderWidth
Class | ClassLibrary | ColorSource
Comment | DragIcon | DragMode
DrawMode | Enabled | Height
HelpContextID | Left | LineSlant
MousePointer | Name | OLEDragMode
OLEDragPicture | OLEDropEffects | OLEDropHasData
OLEDropMode | Parent | ParentClass
PolyPoints | Rotation | StatusBarText
Tag | ToolTipText | Top
Visible | WhatsThisHelpID | Width

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
Init | MiddleClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | RightClick
UIEnable |  |

Methods

AddProperty | CloneObject | Drag
Move | OLEDrag | ReadExpression
ReadMethod | ResetToDefault | SaveAsClass
WriteExpression | WriteMethod | ZOrder

See Also

Other Resources

Line Control
Line Method
LineSlant Property
Objects, Collections, and Classes
Language Reference


ListBox Control

Visual FoxPro 9.0 Language Reference
ListBox Control
See Also Example

Creates a list box that displays a list of items that you can select one or more items from. A list box is similar to a combo box; however, a combo box initially displays a single item. For more information about combo boxes, see ComboBox Control.

For more information about creating ListBox controls, see Form Designer and Using Controls.

ListBox

Remarks

The following table lists properties commonly set at design time.

Property | Description
ColumnCount | Determines the number of columns in the list.
ControlSource | Specifies where to store the value that the user chooses from the list.
MoverBars | Specifies whether to display mover bars to the left of the items in the list so that a user can rearrange the item order.
Multiselect | Specifies whether the user can select more than one item in the list.
RowSource | Specifies the source of the values displayed in the list.
RowSourceType | Specifies the type of the source of the values displayed in the list.

The following table lists methods commonly used.

Method | Description
AddItem | Adds an item to the list when RowSourceType is set to 0.
RemoveItem | Removes an item from the list when RowSourceType is set to 0.
Requery | Updates the list if the values in the source specified by RowSource have changed.

The backslash ("\") is treated as a special character when used in the expression for an item. The following rules apply for this character:

  • You can disable an item in a list box or combo box by adding a single backslash to the beginning of the expression.

  • Any multiple of two backslashes used in the expression is displayed as a single backslash. For example, one or two backslashes used together will display as one, and three or four backslashes together will display as two. The following example code contains a list box item containing a Universal Naming Convention (UNC) path. The code would display in the list box as \\MyServer\MyMachine\MyFolder.

    Copy Code
    MyForm.List1.AddItem("\\\\MyServer\\MyMachine\\MyFolder")
  • If the expression begins with multiple backslashes, the item is not disabled. If you want to disable an item that begins with multiple backslashes, add a backslash and a close bracket (]) to the beginning of the item. For example, the following would disable the UNC path item in the list box:

    Copy Code
    MyForm.List1.AddItem("\]\\\MyServer\\MyMachine\\MyFolder")
  • To include a separator line, use a backslash followed by a hyphen as the item to add to the list box. For example, the following code adds a separator line to a list box:

    Copy Code
    MyForm.List1.AddItem("\-")

You can also use an ActiveX control that adds extra characteristics, such as a CheckBox, to the ListView or TreeView controls.

Example

The following example creates a ListBox control. The source of the items that appear in the list box is an array specified with the RowSourceType and RowSource properties.

The MultiSelect property for the list box is set to true (.T.), allowing you to make multiple selections from the list. The item or items you choose are displayed by using the ListCount, Selected, and List properties (which determine the number of items in the list and the items you chose).
Copy Code
CLEAR

DIMENSION gaMyListArray(10)
FOR gnCount = 1 to 10  && Fill the array with letters
   STORE REPLICATE(CHR(gnCount+64),6) TO gaMyListArray(gnCount)
NEXT

frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .f.  && Disable the Control menu box

frmMyForm.Move(150,10)  && Move the form

frmMyForm.AddObject('cmbCommand1','cmdMyCmdBtn')  && Add "Quit" Command button
frmMyForm.AddObject('lstListBox1','lstMyListBox')  && Add ListBox control

frmMyForm.lstListBox1.RowSourceType = 5  && Specifies an array
frmMyForm.lstListBox1.RowSource = 'gaMyListArray' && Array containing listbox items

frmMyForm.cmbCommand1.Visible =.T.  && "Quit" Command button visible
frmMyForm.lstListBox1.Visible =.T.  && "List Box visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
      CLEAR  && Clear main Visual FoxPro window
ENDDEFINE

DEFINE CLASS lstMyListBox AS ListBox  && Create ListBox control
   Left = 10  && List Box column
   Top = 10  && List Box row
   MultiSelect = .T.  && Allow selecting more than 1 item

PROCEDURE Click
   ACTIVATE SCREEN
   CLEAR
   ? "Selected items:"
   ? "---------------"
   FOR nCnt = 1 TO ThisForm.lstListBox1.ListCount
      IF ThisForm.lstListBox1.Selected(nCnt)  && Is item selected?
         ? SPACE(5) + ThisForm.lstListBox1.List(nCnt) && Show item
      ENDIF
   ENDFOR

ENDDEFINE

See Also

Other Resources

Objects, Collections, and Classes
ListBox Control Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command


ListBox Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
ListBox Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Anchor | Application | AutoHideScrollBar
BaseClass | BorderColor | BoundColumn
BoundTo | Class | ClassLibrary
ColorScheme | ColorSource | ColumnCount
ColumnLines | ColumnWidths | Comment
ControlSource | DisabledBackColor | DisabledForeColor
DisabledItemBackColor | DisabledItemForeColor | DisplayValue
DragIcon | DragMode | Enabled
FirstElement | FontBold | FontCharSet
FontCondense | FontExtend | FontItalic
FontName | FontOutline | FontShadow
FontSize | FontStrikeThru | FontUnderLine
Height | HelpContextID | IncrementalSearch
IntegralHeight | ItemBackColor | ItemData
ItemForeColor | ItemIDData | ItemTips
Left | List | ListCount
ListIndex | ListItem | ListItemID
MouseIcon | MousePointer | MoverBars
MultiSelect | Name | NewIndex
NewItemID | NullDisplay | NumberOfElements
OLEDragMode | OLEDragPicture | OLEDropEffects
OLEDropHasData | OLEDropMode | Parent
ParentClass | Picture | RightToLeft
RowSource | RowSourceType | Selected
SelectedID | SelectedItemBackColor | SelectedItemForeColor
Sorted | SpecialEffect | StatusBarText
TabIndex | TabStop | Tag
TerminateRead | Themes | ToolTipText
Top | TopIndex | TopItemID
Value | Visible | WhatsThisHelpID
Width |  |

Methods

AddItem | AddListItem | AddProperty
Clear | CloneObject | Drag
IndexToItemID | ItemIDToIndex | Move
MoveItem | OLEDrag | ReadExpression
ReadMethod | Refresh | RemoveItem
RemoveListItem | Requery | ResetToDefault
SaveAsClass | SetFocus | WriteExpression
WriteMethod | ZOrder |

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
ErrorMessage | GotFocus | Init
InteractiveChange | KeyPress | LostFocus
Message | MiddleClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | OnMoveItem
ProgrammaticChange | RangeHigh | RangeLow
RightClick | UIEnable | Valid
When |  |

See Also

Other Resources

ListBox Control
ListCount Property
Form Designer
Using Controls


Member Classes (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Member Classes (Visual FoxPro)
See Also

You can define and create subclasses for member objects of certain container objects. The following table lists these members and their parent containers:

Member | Container
Page | PageFrame
CommandButton | CommandGroup
OptionButton | OptionGroup
Column | Grid
Header | Column

Using member classes, you can define consistent behavior for all members of a specific class. For example, you can define a particular behavior in the Activate event of a Page class to be used in a specific PageFrame class or object. All member pages for that page frame inherit the same code or behavior.

To set the default custom class for member objects, set the MemberClassLibrary and MemberClass properties for the PageFrame, CommandGroup, OptionGroup, and Grid container classes. These properties specify the member class and class library you want to use. When these properties are set, new member objects inherit from the specified member class. For Column objects, use the HeaderClassLibrary and HeaderClass properties to specify a custom Header class.

Caution:
Do not change the Name property for a member class in a program (.prg) -based class definition at design time. Doing so can result in generating the message, "Class definition name is not found."

Remarks

In general, member objects must be contained within a parent container object to be used visually. Parent containers can contain only member objects. For example, a Page object must be in a PageFrame object to display on a Form object and a PageFrame object must have at least one Page object to be visible on a Form object. There are two exceptions:

  • You can use command buttons in other containers without requiring a CommandGroup.

  • Column objects can contain other controls but only one Header.

Member objects exist only as children of the parent container, which contains only members belonging to a specific base class. For example, the existence of a Page object requires the prior existence of its parent PageFrame container object. A PageFrame object can contain only pages and not command buttons.

You can associate an event when adding a new member object using the member object's count property _ASSIGN method. The member object's Init event occurs when member objects are added. However, you cannot pass parameters to the Init event of a newly created member object because members are created dynamically when the parent container's count property changes. If you need to pass parameters, you can use the container's AddObject method.

Note:
On an .scx form, if you add instantiation code to the member class's Init event, Visual FoxPro disregards that code and only the Init code for the member class definition runs. However, with visual class library (.vcx) forms, Visual FoxPro creates a true subclass. You can safely add instantiation code for other events such as Click.

Any property values accessed in the member class's Init event belong to those of the original member class. Any values that might have been overridden in the subclass are applied after instantiating the member class.

These behaviors apply only to .scx forms. After the Init event occurs, the member class is treated the same on .scx and .vcx forms.

See Also

Other Resources

Objects, Collections, and Classes
Page Object
PageFrame Control
CommandButton Control
CommandGroup Control
OptionButton Control
OptionGroup Control
Grid Control
Column Object
Header Object
MemberClass Property
MemberClassLibrary Property
HeaderClass Property
HeaderClassLibrary Property
Init Event
AddObject Method


Objects Collection

Visual FoxPro 9.0 Language Reference
Objects Collection
See Also

An array to access objects in an Application object.

ApplicationObject.Objects(nIndex)

Return Value

nIndex

Uniquely identifies an object in the Application object. Note that nIndex might not correspond to the order in which the objects were created.

Remarks

Applies To: Application Object | _VFP System Variable | _SCREEN System Variable | Column Object | CommandGroup Control | Container Object | Control Object | Custom Object | DataEnvironment Object | Form Object | FormSet Object | Grid Control | OptionGroup Control | Page Object | PageFrame Control | ToolBar Object

The Objects collection can be used to determine the current objects for an Application object. The Column, CommandGroup, Container, Control, Custom, DataEnvironment, Form, FormSet, Grid, Page, PageFrame, OptionGroup, and Toolbar objects have collections, and these collections may appear in the Debug window.

See Also

Other Resources

Objects, Collections, and Classes
Forms Property


OLE Bound Control

Visual FoxPro 9.0 Language Reference
OLE Bound Control
See Also

Creates an OLE bound control.

OLEBoundControl

Remarks

On a form or report, an OLE bound control lets you display the contents of an OLE object (such as from Microsoft Word or Microsoft Excel) in a General field of a table.

Unlike OLE container controls, insertable OLE objects do not have their own set of events. Also, OLE bound controls, unlike OLE container controls, are bound to a General field in a Visual FoxPro table.

For additional information about OLE objects in Visual FoxPro, see Sharing Information and Adding OLE.

See Also

Other Resources

Objects, Collections, and Classes
OLE Bound Control Properties, Methods and Events
APPEND GENERAL Command
CREATE FORM Command
CREATE CLASS Command
CREATEBINARY( ) Function
DEFINE CLASS Command
MODIFY GENERAL Command
OLE Container Control


OLE Bound Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
OLE Bound Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Anchor | Application | AutoActivate
AutoSize | AutoVerbMenu | BaseClass
ClassLibrary | Class | Comment
ControlSource | DocumentFile | DragIcon
DragMode | Enabled | Height
HelpContextId | HostName | Left
MousePointer | Name | Object
OLEClass | OLELCID | OLETypeAllowed
ParentClass | Sizable | StatusBarText
Stretch | TabIndex | TabStop
Tag | ToolTipText | Top
Visible | WhatsThisHelpID | Width

Events

Destroy | DragDrop | DragOver
Error | GotFocus | Init
LostFocus | Moved | Resize
UIEnable |  |

Methods

AddProperty | CloneObject | DoVerb
Drag | Move | Refresh
ResetToDefault | SaveAsClass | SetFocus
ZOrder |  |

See Also

Other Resources

OLE Bound Control
OLE Container Control


OLE Container Control

Visual FoxPro 9.0 Language Reference
OLE Container Control
See Also Example

Creates an OLE container control.

OLEControl

Remarks

An OLE container control lets you add OLE objects to your applications. OLE objects include ActiveX Controls (.ocx files) and insertable OLE objects created in other applications such as Microsoft Word and Microsoft Excel. Unlike ActiveX Controls (.ocx files), insertable OLE objects do not have their own set of events. OLE container controls, unlike OLE bound controls, are not bound to a General field in a Visual FoxPro table.

Note that the type of ActiveX control placed in an OLE container control determines the properties, events, and methods available for the ActiveX control

For additional information about OLE objects in Visual FoxPro, see Sharing Information and Adding OLE.

Example

The following example adds an OLE Container control to a form, and uses the OleClass and DocumentFile properties to specify Microsoft Excel as the Automation server and a Microsoft Excel worksheet as the file to edit.

The DocumentFile property specifies a worksheet named Book1.xls in the EXCEL directory on drive C. This example will not work properly if the file and directory specified in the DocumentFile property do not exist; it may be necessary to modify the DocumentFile property to specify an existing directory and worksheet file.

* The DoVerb method is used to activate the worksheet for editing.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the window pop-up menu

frmMyForm.AddObject('cmdCommand1','cmdMyCmdBtn')  && Add Command button
frmMyForm.AddObject("oleObject","oleExcelObject")  && Add OLE object

frmMyForm.cmdCommand1.Visible=.T.  && Display the "Quit" Command button

frmMyForm.oleObject.Visible=.T.  && Display the OLE control
frmMyForm.oleObject.Height = 50  && OLE control height

frmMyForm.Show  && Display the Form

frmMyForm.oleObject.DoVerb(-1)  && -1 for Edit

READ EVENTS  && Start event processing

DEFINE CLASS oleExcelObject as OLEControl
   OleClass ="Excel.Sheet"  && Server name
   DocumentFile = "C:\EXCEL\BOOK1.XLS"  && This file must exist
ENDDEFINE

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close form
ENDDEFINE

See Also

Reference

ActiveX Controls Overview

Other Resources

Objects, Collections, and Classes
OLE Container Control Properties, Methods and Events
APPEND GENERAL Command
CREATE FORM Command
CREATE CLASS Command
CREATEBINARY( ) Function
DEFINE CLASS Command
MODIFY GENERAL Command
OLE Bound Control


OLE Container Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
OLE Container Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Align | Anchor | Application
AutoActivate | AutoSize | AutoVerbMenu
BaseClass | Cancel | Class
ClassLibrary | Comment | ControlSource
Default | DocumentFile | DragIcon
DragMode | Enabled | Height
HelpContextID | HostName | Left
MouseIcon | MousePointer | Name
Object | OLEClass | OLELCID
OLETypeAllowed | Parent | ParentClass
Sizable | Stretch | TabIndex
TabStop | Tag | Top
Visible | WhatsThisHelpID | Width

Events

Destroy | DragDrop | DragOver
Error | GotFocus | Init
LostFocus | Moved | Resize
UIEnable |  |

Methods

AddProperty | CloneObject | DoVerb
Drag | Move | Refresh
ResetToDefault | SaveAsClass | SetFocus
ShowWhatsThis | Zorder |

See Also

Other Resources

OLE Container Control
Sharing Information and Adding OLE


OptionButton Control

Visual FoxPro 9.0 Language Reference
OptionButton Control
See Also

Creates a single option button.

You can use a group of option buttons to provide a selection of predetermined choices. For more information about creating a group of option buttons, see the OptionGroup Control and Using Controls.

OptionButton

Remarks

Although you can add an option button to any container, when added to an OptionGroup container, the button is synchronized with other option buttons in that OptionGroup so that only one button can be selected at a time.

When you set the Style property for an OptionButton control to Graphical, the OptionButton control appears like a CommandButton control and can contain both graphics and text. For more information, see Style Property.

See Also

Other Resources

OptionButton Control Properties, Methods and Events
Objects, Collections, and Classes
CREATE FORM Command
CREATE CLASS Command
DEFINE CLASS Command


OptionButton Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
OptionButton Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alignment | Anchor | Application
AutoSize | BackColor | BackStyle
BaseClass | Caption | Class
ClassLibrary | ColorScheme | ColorSource
Comment | ControlSource | DisabledBackColor
DisabledForeColor | DisabledPicture | DownPicture
DragIcon | DragMode | Enabled
FontBold | FontCharSet | FontCondense
FontExtend | FontItalic | FontName
FontOutline | FontShadow | FontSize
FontStrikeThru | FontUnderLine | ForeColor
Height | HelpContextID | Left
MousePointer | Name | OLEDragMode
OLEDragPicture | OLEDropEffects | OLEDropHasData
OLEDropMode | Parent | ParentClass
Picture | PictureMargin | PicturePosition
PictureSpacing | RightToLeft | SpecialEffect
StatusBarText | Style | TabIndex
TabStop | Tag | TerminateRead
Themes | ToolTipText | Top
Value | Visible | WhatsThisHelpID
Width | WordWrap |

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
ErrorMessage | GotFocus | Init
KeyPress | LostFocus | Message
MiddleClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | OLECompleteDrag | OLEDragDrop
OLEDragOver | OLEGiveFeedBack | OLESetData
OLEStartDrag | RightClick | Valid
When |  |

Methods

AddProperty | CloneObject | Drag
Move | OLEDrag | ReadExpression
ReadMethod | Refresh | ResetToDefault
SaveAsClass | SetFocus | WriteExpression
WriteMethod | ZOrder |

See Also

Other Resources

OptionButton Control
How to: Set Option Button Properties


OptionGroup Control

Visual FoxPro 9.0 Language Reference
OptionGroup Control
See Also Example

Creates a group of option buttons.

OptionGroup

Remarks

Option button groups are containers that contain option buttons. A group of option buttons makes it possible for you to make a choice from a set of buttons. Choosing an option button makes your choice current and releases a previous choice. A bullet next to the option button indicates the current choice. For example, option buttons can be used to direct output to a file, a printer, or a window.

For additional information about creating groups of option buttons, see Using Controls.

Example

The following example creates an OptionGroup control and places the control on a form. The OptionGroup control has three buttons, and depending on the option button you click, a circle, ellipse, or square is displayed. The Buttons and Caption properties are used to specify the text displayed next to each option button.

The Shape control is used to create the circle, ellipse, and square. The OptionGroup control's Click event uses a DO CASE ... ENDCASE structure and the Value property to display the appropriate shape when you click an option button.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('cmdCommand1','cmdMyCmndBtn')  && Add Command button
frmMyForm.AddObject('opgOptionGroup1','opgMyOptGrp') && Add Option Group
frmMyForm.AddObject('shpCircle1','shpMyCircle')  && Add Circle Shape
frmMyForm.AddObject('shpEllipse1','shpMyEllipse')  && Add Ellipse Shape
frmMyForm.AddObject('shpSquare','shpMySquare')  && Add Box Shape

frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible

frmMyForm.opgOptionGroup1.Buttons(1).Caption = "\<Circle"
frmMyForm.opgOptionGroup1.Buttons(2).Caption = "\<Ellipse"
frmMyForm.opgOptionGroup1.Buttons(3).Caption = "\<Square"
frmMyForm.opgOptionGroup1.SetAll("Width", 100) && Set Option group width
frmMyForm.opgOptionGroup1.Visible = .T.  && Option Group visible
frmMyForm.opgOptionGroup1.Click  && Show the circle

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS opgMyOptGrp AS OptionGroup  && Create an Option Group
   ButtonCount = 3  && Three Option buttons
   Top = 10
   Left = 10
   Height = 75
   Width = 100

   PROCEDURE Click
      ThisForm.shpCircle1.Visible = .F.  && Hide the circle
      ThisForm.shpEllipse1.Visible = .F.  && Hide the ellipse
      ThisForm.shpSquare.Visible = .F.  && Hide the square

      DO CASE
         CASE ThisForm.opgOptionGroup1.Value = 1
            ThisForm.shpCircle1.Visible = .T. && Show the circle
         CASE ThisForm.opgOptionGroup1.Value = 2
            ThisForm.shpEllipse1.Visible = .T.  && Show the ellipse
         CASE ThisForm.opgOptionGroup1.Value = 3
            ThisForm.shpSquare.Visible = .T.  && Show the square
      ENDCASE
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

DEFINE CLASS shpMyCircle AS SHAPE  && Create a circle
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 99
   BackColor = RGB(255,0,0)  && Red
ENDDEFINE

DEFINE CLASS shpMyEllipse AS SHAPE  && Create an ellipse
   Top = 35
   Left = 200
   Width = 100
   Height = 50
   Curvature = 99
   BackColor = RGB(0,128,0)  && Green
ENDDEFINE

DEFINE CLASS shpMySquare AS SHAPE  && Create a square
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 0
   BackColor = RGB(0,0,255)  && Blue
ENDDEFINE

See Also

Other Resources

Objects, Collections, and Classes
OptionGroup Control Properties, Methods and Events
CREATE FORM Command
CREATE CLASS Command
DEFINE CLASS Command
OptionButton Control


OptionGroup Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
OptionGroup Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Anchor | Application | AutoSize
BackColor | BackStyle | BaseClass
BorderColor | BorderStyle | ButtonCount
Buttons | Class | ClassLibrary
Comment | ColorSource Property | ControlSource
DragIcon | DragMode | Enabled
Height | HelpContextID | Left
MemberClass | MemberClassLibrary | MouseIcon
MousePointer | Name | Objects
OLEDragMode | OLEDragPicture | OLEDropEffects
OLEDropHasData | OLEDropMode | Parent
ParentClass | SpecialEffect | StatusBarText
TabIndex | Tag | TerminateRead
Themes | ToolTipText | Top
Value | Visible | WhatsThisHelpID
Width |  |

Methods

AddObject | AddProperty | CloneObject
Drag | Move | OLEDrag
ReadExpression | ReadMethod | Refresh
RemoveObject | ResetToDefault | SaveAsClass
SetAll | WriteExpression | WriteMethod
ZOrder |  |

Events

Click | DblClick | DragDrop
DragOver | Error | ErrorMessage
Init | InteractiveChange | Message
MiddleClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | OLECompleteDrag | OLEDragDrop
OLEDragOver | OLEGiveFeedBack | OLESetData
OLEStartDrag | ProgrammaticChange | RightClick
UIEnable | Valid | When

See Also

Other Resources

OptionGroup Control


Page Object

Visual FoxPro 9.0 Language Reference
Page Object
See Also

Creates a page in a PageFrame control.

You can use pages to create tabbed forms or dialog boxes. A page frame contains a set of pages. For additional information about creating pages and page frames, see "Adding Page Frames to a Form" in Controls for Extending Forms.

Page

Remarks

You can refer to a page in a page frame by name as in the following example:

Copy Code
myFrame.MyPage1

You can also refer to a page by its index number using the PageFrame Pages property. This is consistent with the control collections in other Visual FoxPro containers.

Copy Code
myFrame.Pages(2).Enabled = .T.

This index does not necessarily equal the PageOrder property. You might have three pages with PageOrders of 2, 3, and 5. You can refer to these pages as follows:

Copy Code
myFrame.Pages(1)
myFrame.Pages(2)
myFrame.Pages(3)

Only the active page is refreshed when the Form Refresh method occurs for the form on which the page is located.

See Also

Other Resources

Page Object Properties, Methods and Events
Objects, Collections, and Classes
CREATE FORM Command
CREATE CLASS Command
DEFINE CLASS Command
PageFrame Control


Page Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Page Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

ActiveControl | Application | BackColor
BackStyle | BaseClass | Caption
Class | ClassLibrary | ColorSource
Comment | ControlCount | Controls
DragIcon | DragMode | Enabled
FontBold | FontCharSet | FontCondense
FontExtend | FontItalic | FontName
FontOutline | FontShadow | FontSize
FontStrikeThru | FontUnderline | ForeColor
HelpContextID | MouseIcon | MousePointer
Name | Objects | OLEDragMode
OLEDragPicture | OLEDropEffects | OLEDropHasData
OLEDropMode | PageOrder | Parent
ParentClass | Picture | Tag
ToolTipText | WhatsThisHelpID |

Events

Activate | Click | DblClick
Deactivate | Destroy | DragDrop
DragOver | Error | Init
MiddleClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | OLECompleteDrag | OLEDragDrop
OLEDragOver | OLEGiveFeedBack | OLESetData
OLEStartDrag | RightClick |

Methods

AddObject | AddProperty | CloneObject
Drag | OLEDrag | ReadExpression
ReadMethod | Refresh | RemoveObject
ResetToDefault | SaveAsClass | SetAll
SetFocus | WriteExpression | WriteMethod
ZOrder |  |

See Also

Other Resources

Page Object
Controls for Extending Forms


PageFrame Control

Visual FoxPro 9.0 Language Reference
PageFrame Control
See Also

Creates a page frame to contain Page objects.

A page frame is a container object that contains pages, which can contain controls.

Note:
For a page frame to be visible, it must be added to a form.

PageFrame

Remarks

The page frame defines global characteristics of the page: size and positioning, border style, which page is active, and so on. The page frame determines the location of the pages and how much of each page is visible. Pages are positioned at the top left corner of the page frame. If the page frame is moved, the pages move with the page frame.

A page frame contains individual pages that are named Page1, Page2, Page3, and so on by default.

Note:
Only the active page is refreshed when the Form Refresh method occurs for the form on which the page is located.

The PageFrame Themes property provides a gradient effect on Page objects, so a label, option button, or similar control with text does not appear correctly if the BackStyle property of the control is set to Opaque. You can remedy this situation by setting BackStyle to Transparent.

For additional information about creating pages and page frames, see "Adding Page Frames to a Form" in Controls for Extending Forms.

See Also

Other Resources

Objects, Collections, and Classes
PageFrame Control Properties, Methods and Events
CREATE FORM Command
CREATE CLASS Command
DEFINE CLASS Command
Page Object


PageFrame Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
PageFrame Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

ActivePage | Anchor | Application
BaseClass | BorderColor | BorderWidth
Class | ClassLibrary | ColorSource
Comment | DragIcon | DragMode
Enabled | HelpContextID | Height
Left | MemberClass | MemberClassLibrary
MouseIcon | MousePointer | Name
Objects | OLEDragMode | OLEDragPicture
OLEDropEffects | OLEDropHasData | OLEDropMode
PageCount | PageHeight | Pages
PageWidth | Parent | ParentClass
RightToLeft | SpecialEffect | StatusBarText
TabIndex | TabOrientation | Tabs
TabStop | TabStyle | Tag
Themes | ToolTipText | Top
Visible | WhatsThisHelpID | Width

Methods

AddObject | AddProperty | CloneObject
Drag | Move | OLEDrag
ReadExpression | ReadMethod | Refresh
RemoveObject | ResetToDefault | SaveAsClass
SetAll | WriteExpression | WriteMethod
Zorder |  |

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
Init | MiddleClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | Moved
OLECompleteDrag | OLEDragDrop | OLEDragOver
OLEGiveFeedBack | OLESetData | OLEStartDrag
Resize | RightClick | UIEnable

See Also

Other Resources

PageFrame Control
Controls for Extending Forms


Parent Object Reference

Visual FoxPro 9.0 Language Reference
Parent Object Reference
See Also

References the container object of a control. Not available at design time; read-only at run time.

Control.Parent

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | CommandGroup | Container | Control | CursorAdapter Class | Custom | EditBox | Exception Class | Form | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | Project Object | ProjectHook Object | Separator | Session Object | Shape | Spinner | TextBox | Timer | ToolBar

Use the Parent keyword to access the properties, methods, or controls of a control's container object. You can also use the Parent object reference to access the container object of a page or form.

The Parent keyword is useful in an application in which you pass controls as arguments. For example, you can pass a control variable to a general procedure and use the Parent object reference to access its container object.

You can also use the Parent object reference for objects in a control class that have been placed on an unknown form.

See Also

Other Resources

Objects, Collections, and Classes
BaseClass Property


Project Object (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Project Object (Visual FoxPro)
See Also

Instantiated when a project is created or opened, providing programmatic access to project properties and methods.

Project

Remarks

A project object is instantiated when you issue CREATE PROJECT, MODIFY PROJECT, BUILD APP, BUILD DLL, BUILD EXE, BUILD MTDLL, or BUILD PROJECT.

Note that the project object and its properties and methods are not available in the ProjectHook object Init event. Project object property values you set or methods you invoke in the ProjectHook object Init event are ignored.

Note that a project object is a COM object, so assigning a project object reference to a memory variable creates a memory variable of class "Unknown Type."

For more information about projects, see Project Manager Hooks.

See Also

Other Resources

Project Object Properties, Methods, and Events
ActiveProject Property
Objects, Collections, and Classes
File Object
Files Collection
Projects Collection
ProjectHook Object
Server Object
Servers Collection


Project Object Properties, Methods, and Events (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Project Object Properties, Methods, and Events (Visual FoxPro)
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Application | AutoIncrement | BaseClass
BuildDateTime | Debug | Encrypted
Files Collection | HomeDir | Icon
MainFile | Name | Parent
ProjectHook | ProjectHookClass | ProjectHookLibrary
SCCProvider | ServerHelpFile | ServerProject
TypeLibCLSID | TypeLibDesc | TypeLibName
VersionComments | VersionCompany | VersionCopyright
VersionDescription | VersionLanguage | VersionNumber
VersionProduct | VersionTrademarks | Visible

Methods

Build | CleanUp | Close
Refresh | SetMain |

See Also

Other Resources

Project Object
ProjectHook Object Properties, Methods, and Events
ProjectHook Object


ProjectHook Object

Visual FoxPro 9.0 Language Reference
ProjectHook Object
See Also

Instantiated whenever a project is opened, providing programmatic access to project events.

ProjectHook

Remarks

A ProjectHook object is a Visual FoxPro base class that is instantiated by default whenever a project is opened. (You can include the NOPROJECTHOOK clause in CREATE PROJECT and MODIFY PROJECT to prevent a ProjectHook object from being instantiated for the project.)

The ProjectHook object allows programmatic access to events that occur in a project. For example, you can execute code whenever a file is added to a project. Note that you can specify a default project hook class for new projects in the Projects tab, of the Options dialog box or you can specify a default project hook class for an individual project in the Project Information dialog box. At runtime, you can use the ProjectHook property to specify a project hook class for a project as in the following example:

Copy Code
MODIFY PROJECT MyProject
_VFP.Projects('MyProject.pjx').ProjectHook = ;
   NewObject('MyProjectHook', 'MyClass.vcx')

A ProjectHook base class can be created with CREATE CLASS, CREATEOBJECT( ), or NEWOBJECT( ).

For more information about projects, see Project Manager Hooks.

See Also

Other Resources

ProjectHook Object Properties, Methods, and Events
CREATE CLASS Command
CREATEOBJECT( ) Function
Objects, Collections, and Classes
File Object
Files Collection
NEWOBJECT( ) Function
ProjectHook Property
Projects Collection
Project Object
Server Object
Servers Collection


ProjectHook Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
ProjectHook Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Application | BaseClass | Class
ClassLibrary | Comment | Name
OLEDropEffects | OLEDropHasData | OLEDropMode
Parent | ParentClass | Tag

Events

Activate | AfterBuild | BeforeBuild
Deactivate | Destroy | Error
Init | OLEDragDrop | OLEDragOver
OLEGiveFeedBack | QueryAddFile | QueryModifyFile
QueryNewFile | QueryRemoveFile | QueryRunFile
SCCDestroy | SCCInit |

Methods

AddProperty | ReadExpression | ReadMethod
ResetToDefault | SaveAsClass | WriteExpression

See Also

Other Resources

ProjectHook Object


Projects Collection (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Projects Collection (Visual FoxPro)
See Also

A collection of project objects.

Projects

Remarks

Applies To: _VFP System Variable | Application Object

A projects collection provides access to project objects, making it possible for you to manipulate a project and files and servers within the project.

Items in projects collection can be referenced by index number or by name. For example, the following code rebuilds the most recently opened project:

Copy Code
_VFP.Projects(1).Build( )

The following code rebuilds the project named MyProject:

Copy Code
_VFP.Projects('MyProject.pjx').Build( )

For more information about the projects collection, see Project Manager Hooks.

See Also

Other Resources

Projects Collection Properties, Methods, and Events
Objects, Collections, and Classes
File Object
Files Collection
Project Object
ProjectHook Object
Server Object
Servers Collection


Projects Collection Properties, Methods, and Events (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Projects Collection Properties, Methods, and Events (Visual FoxPro)
See Also

The following tables list the properties and methods reference topics for this object.

Properties

Count

Methods

Item

See Also

Other Resources

Projects Collection


Relation Object

Visual FoxPro 9.0 Language Reference
Relation Object
See Also

Created when you establish relationships from within the Data Environment Designer for a form, form set, or report.

Relation

Remarks

The Relation object allows you to determine or specify how two tables are related.

Setting a Relation object property at run time generates an error. For a new property setting to take effect, you must call the CloseTables and OpenTables methods for the data environment.

For more information about the data environment for Forms and FormSets, see How to: Set the Data Environment.

See Also

Other Resources

Relation Object Properties, Methods and Events
Objects, Collections, and Classes
Cursor Object
DataEnvironment Object


Relation Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Relation Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Application | ChildAlias | ChildOrder
Comment | Name | OneToMany
ParentAlias | RelationalExpr | Tag

Events

Destroy

Error

Init

Methods

AddProperty | ReadExpression | ReadMethod
ResetToDefault | WriteExpression |

See Also

Other Resources

Relation Object
RELATION( ) Function
Cursor Object
DataEnvironment Object


ReportListener Object

Visual FoxPro 9.0
ReportListener Object
See Also

ReportListener objects provide object assistance to REPORT FORM and LABEL FORM commands. As the Report Engine processes your report or label data and layout, it sends information to a ReportListener object, rather than sending the output to a printer or preview device directly. The ReportListener "listens" for these instructions and handles the responsibility of evaluating and rendering the content of your report appropriately for your output device.

The ReportListener class is specifically designed for two-way communication with the Report Engine throughout the output generation process. Using a ReportListener, you can:

  • Write code for each element-rendering and band event as the report generation process moves forward through the report record scope.

  • Alter the position of layout elements being rendered, or their contents.

  • Provide feedback to the user about the report run.

  • Make requests of the report engine for page images, to be displayed on-screen or saved to disk.

  • Manage a private data session, holding information from the report or label definition table (.frx or .lbx), to investigate attributes of report objects and bands.

  • Communicate directly with the device to which the Report System renders output.

  • Investigate all the clauses of the REPORT FORM command, and alter some of these clauses dynamically.

ReportListener

Remarks

Visual FoxPro gives you several different ways to attach a ReportListener to REPORT FORM or LABEL FORM commands:

  • Use the OBJECT clause on the command. For more information, see REPORT FORM Command.

  • Use the OBJECT TYPE <N> clause, specifying a numeric ListenerType for the type of output you would like to create. The Report Engine requests a ReportListener of the appropriate ListenerType from the Report Output Application. For more information, see ListenerType Property and Report Output Application.

  • Use SET REPORTBEHAVIOR 90 to enable object assistance on all REPORT FORM and LABEL FORM commands. For more information, see SET REPORTBEHAVIOR Command.

Using ReportListeners, you can send output to multiple output devices in one report run, and you can add output types, such as HTML, that Visual FoxPro reports do not support natively. For more information, see ReportListener Foundation Classes and Extending Reports at Run Time.

See Also

Reference

ReportListener Object Properties, Methods, and Events

Other Resources

Objects, Collections, and Classes


ReportListener Object Properties, Methods, and Events

Visual FoxPro 9.0
ReportListener Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and collections reference topics for this object.

Properties

AllowModalMessages | BaseClass | Class
ClassLibrary | CommandClauses | Comment
CurrentDataSession | CurrentPass | DynamicLineHeight
FRXDataSession | GDIPlusGraphics | ListenerType
Name | OutputPageCount | OutputType
PageNo | PageTotal | ParentClass
PreviewContainer | PrintJobName | QuietMode
SendGDIPlusImage | Tag | TwoPassProcess

Events

AdjustObjectSize | AfterBand | AfterReport
BeforeBand | BeforeReport | Destroy
Error | EvaluateContents | Init
LoadReport | UnloadReport |

Methods

AddProperty | CancelReport | ClearStatus
DoMessage | DoStatus | GetPageHeight
GetPageWidth | IncludePageInOutput | OnPreviewClose
OutputPage | ReadExpression | ReadMethod
Render | ResetToDefault | SaveAsClass
SupportsListenerType | UpdateStatus | WriteExpression
WriteMethod |  |

See Also

Reference

ReportListener Object


Separator Object

Visual FoxPro 9.0 Language Reference
Separator Object
See Also

Creates a Separator object that places space between controls in a toolbar.

Separator

Remarks

Controls in a toolbar are placed immediately next to each other unless you include a Separator between the controls. A Separator is a special object that adds space between the controls and creates a group of controls.

For additional information about creating toolbars and separators, see Designing Menus and Toolbars.

See Also

Other Resources

Separator Object Properties, Methods and Events
Objects, Collections, and Classes
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Toolbar Object


Separator Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Separator Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Application | BaseClass | Class
ClassLibrary | Comment | Enabled
Name | Parent | ParentClass
Style | Tag | Visible

Events

Destroy

Error

Init

Methods

AddProperty | ReadExpression | ReadMethod
ResetToDefault | SaveAsClass | WriteExpression
ZOrder |  |

See Also

Other Resources

Separator Object


Server Object

Visual FoxPro 9.0 Language Reference
Server Object
See Also

An object reference to a server in a project.

Server

Remarks

A server object is created and instantiated for each server in a project after building an executable file (.exe) or dynamic link library (.dll) from the project. The server object provides an object reference to a server in the project, and makes it possible for you to determine information about the server and manipulate it through the server object properties.

A project's servers collection is composed of all the server objects in the project.

Note that a server object is a COM object, so assigning a server object reference to a memory variable creates a memory variable of class "Unknown Type."

See Also

Other Resources

Server Object Properties, Methods and Events
Objects, Collections, and Classes
File Object
Files Collection
Project Object
Projects Collection
ProjectHook Object
Servers Collection


Server Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Server Object Properties, Methods, and Events
See Also

The following table lists the properties reference topics for this object.

Properties

CLSID | Description | HelpContextID
Instancing | ProgID | ServerClass
ServerClassLibrary |  |

See Also

Other Resources

Server Object


Servers Collection

Visual FoxPro 9.0 Language Reference
Servers Collection
See Also

A collection of server objects.

Servers

Remarks

A Servers collection provides access to server objects, making it possible for you to manipulate servers within the project.

For more information about the servers collection and projects, see Project Manager Hooks.

For information about creating custom Automation servers, see How to: Create Automation Servers.

See Also

Other Resources

Servers Collection Properties, Methods and Events
Objects, Collections, and Classes
File Object
Files Collection
Project Object
Projects Collection
ProjectHook Object
Server Object


Servers Collection Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Servers Collection Properties, Methods, and Events
See Also

The following tables list the properties and methods reference topics for this object.

Properties

Count

Methods

Item

See Also

Other Resources

Servers Collection


Session Object

Visual FoxPro 9.0 Language Reference
Session Object
See Also

Creates a custom, user-defined object that manages its own data session.

DEFINE CLASS ClassName1 AS Session

Remarks

You can create this custom, user-defined class only using the DEFINE CLASS command. You can, however, add this object to a form or other container programmatically.

Custom, user-defined classes are classes with properties, events, and methods, but with no visual representation. The same general rules that apply to defining other types of classes apply to defining custom classes. Use the Session object for efficient memory management and to ensure safe behavior of multiple object instances in multi-tiered applications.

See Object-Oriented Programming for additional information about creating custom objects as non-visual classes.

Beginning with Visual FoxPro 7.0, the default values for a Visual FoxPro data session are as follows:

Setting | Value
EXCLUSIVE | ON
SAFETY | OFF
TALK | OFF

The default values for a form with a private data session are as follows:

Setting | Value
EXCLUSIVE | OFF
SAFETY | ON
TALK | ON

A form that uses the default data session, also uses the settings that exist for that session because the session was created before the form.

When the Session object represents a COM Server, all intrinsic properties are treated as private.

See Also

Other Resources

Session Object Properties, Methods and Events
Objects, Collections, and Classes
DEFINE CLASS Command
Object-Oriented Programming
How to: Add User-Defined Objects to a Form
Commands that Scope to a Data Session


Session Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Session Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Application | BaseClass | Class
ClassLibrary | Comment | DataSession
DataSessionID | Name | Parent
ParentClass | Tag |

Methods

AddProperty | ReadExpression | ReadMethod
ResetToDefault | WriteExpression |

Events

Destroy

Error

Init

See Also

Other Resources

Session Object
DEFINE CLASS Command
Object-Oriented Programming
How to: Add User-Defined Objects to a Form
Commands that Scope to a Data Session


Shape Control

Visual FoxPro 9.0 Language Reference
Shape Control
See Also Example

Creates a Shape control that displays a box, circle, or ellipse.

ShapeButton screenshot foxpro
Shape

Remarks

A Shape control is a graphical control that displays a box, circle, or ellipse that cannot be changed directly. However, because a Shape control has a full set of properties, events, and methods that other controls have, the Shape control can respond to events and can be changed dynamically at run time.

The Curvature property determines what shape is displayed and can vary from 0 to 99. 0 specifies no curvature and creates square corners; 99 specifies maximum curvature and creates circles and ellipses.

For additional information about creating shapes, see the Form Designer topic and Using Controls.

Example

The following example demonstrates how the Shape control can be used to display a circle, ellipse, or square on a form.

A form is created, and a set of option buttons and a command button are placed on the form. When you click one of the option buttons, the corresponding shape is displayed on the form. The Visible property is set to true (.T.) to display a shape; it is set to false (.F.) to hide the shape before another shape is displayed. The Height, Width, and Curvature properties of each shape determine the type of shape (circle, ellipse, or square) created.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('cmdCommand1','cmdMyCmndBtn')  && Add Command button
frmMyForm.AddObject('opgOptionGroup1','opgMyOptGrp') && Add Option Group
frmMyForm.AddObject('shpCircle1','shpMyCircle')  && Add Circle Shape
frmMyForm.AddObject('shpEllipse1','shpMyEllipse')  && Add Ellipse Shape
frmMyForm.AddObject('shpSquare','shpMySquare')  && Add Box Shape

frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible

frmMyForm.opgOptionGroup1.Buttons(1).Caption = "\<Circle"
frmMyForm.opgOptionGroup1.Buttons(2).Caption = "\<Ellipse"
frmMyForm.opgOptionGroup1.Buttons(3).Caption = "\<Square"
frmMyForm.opgOptionGroup1.SetAll("Width", 100) && Set Option group width
frmMyForm.opgOptionGroup1.Visible = .T.  && Option Group visible
frmMyForm.opgOptionGroup1.Click  && Show the circle

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS opgMyOptGrp AS OptionGroup  && Create an Option Group
   ButtonCount = 3  && Three Option buttons
   Top = 10
   Left = 10
   Height = 75
   Width = 100

   PROCEDURE Click
      ThisForm.shpCircle1.Visible = .F.  && Hide the circle
      ThisForm.shpEllipse1.Visible = .F.  && Hide the ellipse
      ThisForm.shpSquare.Visible = .F.  && Hide the square

      DO CASE
         CASE ThisForm.opgOptionGroup1.Value = 1
            ThisForm.shpCircle1.Visible = .T. && Show the circle
         CASE ThisForm.opgOptionGroup1.Value = 2
            ThisForm.shpEllipse1.Visible = .T.  && Show the ellipse
         CASE ThisForm.opgOptionGroup1.Value = 3
            ThisForm.shpSquare.Visible = .T.  && Show the square
      ENDCASE
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

DEFINE CLASS shpMyCircle AS Shape  && Create a circle
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 99
   BackColor = RGB(255,0,0)  && Red
ENDDEFINE

DEFINE CLASS shpMyEllipse AS Shape  && Create an ellipse
   Top = 35
   Left = 200
   Width = 100
   Height = 50
   Curvature = 99
   BackColor = RGB(0,128,0)  && Green
ENDDEFINE

DEFINE CLASS shpMySquare AS Shape  && Create a square
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 0
   BackColor = RGB(0,0,255)  && Blue
ENDDEFINE

See Also

Other Resources

Shape Control Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


Shape Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Shape Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Anchor | Application | BackColor
BackStyle | BaseClass | BorderColor
BorderStyle | BorderWidth | Class
ClassLibrary | ColorScheme | ColorSource
Comment | Curvature | DragIcon
DragMode | DrawMode | Enabled
FillColor | FillStyle | Height
HelpContextID | Left | MouseIcon
MousePointer | Name | OLEDragMode
OLEDragPicture | OLEDropEffects | OLEDropHasData
OLEDropMode | Parent | ParentClass
PolyPoints | Rotation | SpecialEffect
Tag | ToolTipText | Top
Visible | WhatsThisHelpID | Width

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
Init | MiddleClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | RightClick
UIEnable |  |

Methods

AddProperty | CloneObject | Drag
Move | OLEDrag | ReadExpression
ReadMethod | Refresh | ResetToDefault
SaveAsClass | ShowWhatsThis | WriteExpression
WriteMethod | ZOrder |

See Also

Other Resources

Shape Control


Spinner Control

Visual FoxPro 9.0 Language Reference
Spinner Control
See Also

Creates a spinner.

Spinner

Remarks

A spinner allows a user to choose from a range of numeric values by 'spinning' through the values by clicking the up or down arrows on the spinner or by typing a value into the spinner box.

The KeyBoardHighValue and SpinnerHighValue properties specify the maximum numeric values that can be entered from the keyboard into the spinner box and by clicking the arrow buttons on the spinner.

The KeyBoardLowValue and SpinnerLowValue properties specify the minimum numeric values that can be entered from the keyboard into the spinner box and by clicking the arrow buttons on the spinner.

For additional information about creating spinners, see the Form Designer topic and Using Controls.

See Also

Other Resources

Spinner Control Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


Spinner Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Spinner Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alignment | Anchor | Application
BackColor | BaseClass | BorderColor
BorderStyle | Class | ClassLibrary
ColorScheme | ColorSource | Comment
ControlSource | DisabledBackColor | DisabledForeColor
DragIcon | DragMode | Enabled
FontBold | FontCharSet | FontCondense
FontExtend | FontItalic | FontName
FontOutline | FontShadow | FontSize
FontStrikeThru | FontUnderline | ForeColor
Format | Height | HelpContextID
HideSelection | Increment | InputMask
KeyboardHighValue | KeyboardLowValue | Left
Margin | MouseIcon | MousePointer
Name | NullDisplay | OLEDragMode
OLEDragPicture | OLEDropEffects | OLEDropHasData
OLEDropMode | OLEDropTextInsertion | Parent
ParentClass | ReadOnly | RightToLeft
SelectedBackColor | SelectedForeColor | SelectOnEntry
SelLength | SelStart | SelText
SpecialEffect | SpinnerHighValue | SpinnerLowValue
StatusBarText | TabIndex | TabStop
Tag | TerminateRead | Text
Themes | ToolTipText | Top
Value | Visible | WhatsThisHelpID
Width |  |

Events

Click | DblClick | Destroy
DownClick | DragDrop | DragOver
Error | ErrorMessage | GotFocus
Init | InteractiveChange | KeyPress
LostFocus | Message | MiddleClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
OLECompleteDrag | OLEDragDrop | OLEDragOver
OLEGiveFeedBack | OLESetData | OLEStartDrag
ProgrammaticChange | RangeHigh | RangeLow
RightClick | UIEnable | UpClick
Valid | When |

Methods

AddProperty | CloneObject | Drag
Move | OLEDrag | ReadExpression
ReadMethod | Refresh | ResetToDefault
SaveAsClass | SetFocus | ShowWhatsThis
WriteExpression | WriteMethod | ZOrder

See Also

Other Resources

Spinner Control


Tables Collection (XMLAdapter)

Visual FoxPro 9.0 Language Reference
Tables Collection (XMLAdapter)
See Also

The Tables collection in an XMLAdapter object contains one or more XMLTable objects and describes XML as a Visual FoxPro cursors along with any relational information. To create a new XMLTable object and add it to the Tables collection, or populate the Tables collection with one or more tables, use the XMLAdapter LoadXML, AddTableSchema, or Attach methods.

XMLAdapter.Tables

Remarks

Applies To: XMLAdapter Class

See Also

Other Resources

Objects, Collections, and Classes
XMLAdapter Object Properties, Methods, and Events
XMLTable Class
AddTableSchema Method


TextBox Control (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
TextBox Control (Visual FoxPro)
See Also

Creates a text box.

TextBox

Remarks

You can use a text box to edit the contents of a memory variable, array element, or field. You can view the contents of a Blob field using a text box in a Grid control; however, the data in the Blob field is read-only. In grids, Blob type fields display the string "blob" if they are empty, and the string "Blob" if they contain data. You can double-click the Blob field in the grid, and an editing window displays the data as read-only.

All standard Visual FoxPro editing features are available for text boxes except when viewing Blob field data.

Tip:
If you use a text box to edit a Date or DateTime value, and you select the entire value, you can increment or decrement the value by one day by pressing the PLUS SIGN (+) or MINUS SIGN (-).

To specify how values are entered and displayed in the text box, use the InputMask and Format properties. To enable auto-completion, see the AutoComplete Property.

The following table lists text box properties that are commonly set at design time.

Property | Description
Alignment | Specifies alignment for the contents of a text box.
ControlSource | Specifies the table field or variable whose value is displayed in the text box.
InputMask | Specifies the data entry rule that each character entered must follow.
SelectOnEntry | Determines whether the contents of the text box are selected automatically when the text box receives the focus.
TabStop | Specifies whether the user can tab to the control. If TabStop is set to False (.F.), the user can still select the text box by clicking it.

For additional information about creating text boxes, see the Form Designer topic and Using Controls.

See Also

Other Resources

TextBox Control Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Form Designer
Using Controls
Objects, Collections, and Classes
Language Reference


TextBox Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
TextBox Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alignment | Anchor | Application
AutoComplete | AutoCompTable | AutoCompSource
BackColor | BackStyle | BaseClass
BorderColor | BorderStyle | Century
Class | ClassLibrary | ColorScheme
ColorSource | Comment | ControlSource
DateFormat | DateMark | DisabledBackColor
DisabledForeColor | DragIcon | DragMode
Enabled | EnableHyperlinks | FontBold
FontCharSet | FontCondense | FontExtend
FontItalic | FontName | FontOutline
FontShadow | FontSize | FontStrikeThru
FontUnderline | ForeColor | Format
Height | HelpContextID | HideSelection
Hours | IMEMode | InputMask
IntegralHeight | Left | Margin
MaxLength | MemoWindow | MouseIcon
MousePointer | Name | NullDisplay
OLEDragMode | OLEDragPicture | OLEDropEffects
OLEDropHasData | OLEDropMode | OLEDropTextInsertion
OpenWindow | Parent | ParentClass
PasswordChar | ReadOnly | RightToLeft
Seconds | SelectedBackColor | SelectedForeColor
SelectOnEntry | SelLength | SelStart
SelText | SpecialEffect | StatusBarText
StrictDateEntry | Style | TabIndex
TabStop | Tag | TerminateRead
Text | Themes | ToolTipText
Top | Value | Visible
WhatsThisHelpID | Width |

Events

Click | DblClick | Destroy
DragDrop | DragOver | Error
ErrorMessage | GotFocus | Init
InteractiveChange | KeyPress | LostFocus
Message | MiddleClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | ProgrammaticChange
RangeHigh | RangeLow | RightClick
UIEnable | Valid | When

Methods

AddProperty | CloneObject | Drag
Move | OLEDrag | ReadExpression
ReadMethod | Refresh | ResetToDefault
SaveAsClass | SetFocus | ShowWhatsThis
WriteExpression | WriteMethod | ZOrder

See Also

Other Resources

TextBox Control


THIS Object Reference

Visual FoxPro 9.0 Language Reference
THIS Object Reference
See Also Example

Provides a reference to the current object in event code or in a class definition.

THIS.PropertyName | ObjectName

Parameters

PropertyName

Specifies a property to set or get for the object.
ObjectName

Specifies an object in the class.

Remarks

THIS provides a convenient way of referring to the current object when writing event-handling programs in a form. For example, this Click Event program for a command button sets the button's caption to the current time:

Copy Code
this.caption = time()

Using THIS instead of explicitly referring to the current object by name (for example, thisform.command1.caption) makes program code portable between objects, because it avoids the object's name, and automatically encapsulates the object's parent class.

THIS also allows you to reference a property or an object in a class definition. Methods in a class definition block can use THIS to specify a property or object that will exist when the class is created.

Because multiple instances of objects share the same method code, THIS always refers to the instance in which the code is executing. If there are multiple instances of an object, and one of the object's methods is called, THIS refers to the correct object.

Example

The following example creates a subclass called MyForm, based on the Form class. A method called ChangeBackColor is created. ChangeBackColor uses THIS to refer to MyForm.
Copy Code
DEFINE CLASS MyForm AS FORM
 CAPTION = "This Form"
 HEIGHT = 15
 WIDTH = 20

 PROCEDURE ChangeBackColor
 PARAMETER NewColor
  THIS.BACKCOLOR = NewColor
 ENDPROC
ENDDEFINE

See Also

Other Resources

THISFORM Object Reference
THISFORMSET Object Reference
BackColor, ForeColor Properties
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference


THISFORM Object Reference

Visual FoxPro 9.0 Language Reference
THISFORM Object Reference
See Also

Provides a reference to the current form in form event code or in a class definition.

THISFORM.PropertyName | ObjectName

Parameters

PropertyName

Specifies a property for the form.
ObjectName

Specifies an object in the form.

Remarks

THISFORM provides a convenient way of referring to the current form when writing event-handling programs in a form. For example, this Click Event program for a command button sets the button's caption to the current time:

Copy Code
thisform.command1.caption = time()

Using THISFORM instead of explicitly referring to the current form by name (for example, form1.command1.caption) makes program code portable between forms.

When creating class definitions, THISFORM also provides a means of referring to the current form within a method. THISFORM lets you reference an object on the form or property without using multiple Parent properties.

See Also

Other Resources

THIS Object Reference
THISFORMSET Object Reference
Click Event
Objects, Collections, and Classes
Language Reference


THISFORMSET Object Reference

Visual FoxPro 9.0 Language Reference
THISFORMSET Object Reference
See Also

Provides a reference to the current form set in event code or in a class definition.

THISFORMSET.PropertyName | ObjectName

Parameters

PropertyName

Specifies a property for the form set.
ObjectName

Specifies an object in the form set.

Remarks

THISFORMSET provides a convenient way of referring to the current form set when writing event-handling programs in a form. Using THISFORMSET instead of explicitly referring to the current form by name (for example, form1.command1.caption) makes program code portable between forms.

When creating class definitions, THISFORMSET also provides a means of referring to the current form set within a method. THISFORMSET lets you reference an object on the form or property without using multiple Parent properties.

See Also

Other Resources

THIS Object Reference
THISFORM Object Reference
Object Reference Creation
Objects, Collections, and Classes
Language Reference


Timer Control

Visual FoxPro 9.0 Language Reference
Timer Control
See Also

Creates a timer that can run code at regular intervals.

Timer

Remarks

The Timer control, which is invisible to the user, is useful for background processing. A typical use for the timer is checking the system clock to determine if it is time to run a program or application.

If a Timer control has its Enabled property set to True (.T.) and immediately sets the property False (.F.) after a single execution, it may generate its Timer event multiple times. This occurs when the Interval property is less than or approximately the same as the execution time for the Timer event. This can be corrected by increasing the value of the Interval property or decreasing the execution time of the Timer event.

For additional information about creating timers, see Using Controls.

See Also

Other Resources

Timer Control Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Form Designer
Objects, Collections, and Classes
Language Reference


Timer Control Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
Timer Control Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Application | BaseClass | Class
ClassLibrary | Comment | Enabled
Height | Interval | Left
Name | Parent | ParentClass
Tag | Top | Width

Events

Destroy | Error | Init
Timer |  |

Methods

AddProperty | CloneObject | ReadExpression
ReadMethod | Reset | ResetToDefault
SaveAsClass | WriteExpression | WriteMethod

See Also

Other Resources

Timer Control
Form Designer
Objects, Collections, and Classes
Language Reference


ToolBar Object

Visual FoxPro 9.0 Language Reference
ToolBar Object
See Also Example

Creates a custom toolbar.

ToolBar

Remarks

Use the ToolBar object to create your own toolbars for your applications.

The following list describes the properties of a custom toolbar:

  • Toolbars are always on top.

  • Toolbars automatically dock when they are moved to the edge of the main Visual FoxPro window.

  • When toolbars are not docked, they have a half-height title bar.

  • When the size of a toolbar is changed, the controls are arranged to fit.

  • You can move a toolbar by clicking and dragging in any area of the toolbar that is not a control.

  • Many controls placed on the toolbar do not receive the focus when they are chosen.

  • Access keys in controls placed in a toolbar are disabled.

Although any control can be placed on a toolbar, some controls, such as a list box, may be too large to fit properly in a docked toolbar. These controls can be programmatically removed from the toolbar when the toolbar is docked and replaced with a smaller version of the same control or a different control.

For additional information about creating toolbars, see Designing Menus and Toolbars.

Example

The following example demonstrates how you can create a toolbar from the Toolbar class. Visual FoxPro rearranges the buttons when the toolbar is resized. When the ToolBar object is created, Visual FoxPro automatically places the controls from left to right in the order they are added to the class definition, ignoring the controls' Top and Left properties.
Copy Code
PUBLIC tbrDesktop
tbrDesktop = CREATEOBJ('myToolBar')
tbrDesktop.Show

DEFINE CLASS myToolBar AS Toolbar
   ADD OBJECT btnBold AS CommandButton
   ADD OBJECT sep1 AS Separator
   ADD OBJECT btnItalics AS CommandButton

   btnBold.Height = 20
   btnBold.Width = 50
   btnBold.Caption = "Bold"
   btnItalics.Height = 20
   btnItalics.Width = 50
   btnItalics.Caption = "Italic"
   btnItalics.FontBold = .F.

   Left = 1
   Top = 1
   Width = 25

   Caption = "Desktop Attributes"

   PROCEDURE Activate
      this.btnBold.FontBold = _SCREEN.FontBold
      this.btnItalics.FontItalic = _SCREEN.FontItalic
   ENDPROC

   PROCEDURE btnBold.Click
      _SCREEN.FontBold = !_SCREEN.FontBold
      This.FontBold =_SCREEN.FontBold
   ENDPROC

   PROCEDURE btnItalics.CLICK
      _SCREEN.FontItalic = !_SCREEN.FontItalic
      This.FontItalic = _SCREEN.FontItalic
   ENDPROC
ENDDEFINE

See Also

Other Resources

ToolBar Object Properties, Methods and Events
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Separator Object
Objects, Collections, and Classes


ToolBar Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
ToolBar Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

ActiveControl | Application | BackColor
BaseClass | Caption | Class
ClassLibrary | Comment | ColorSource
ControlBox | ControlCount | Controls
DataSession | DataSessionID | Docked
DockPosition | Enabled | ForeColor
Height | HelpContextID | HWnd
KeyPreview | Left | LockScreen
MouseIcon | MousePointer | Movable
Name | Objects | OLEDragMode
OLEDragPicture | OLEDropEffects | OLEDropHasData
OLEDropMode | Parent | ParentClass
ScaleMode | ShowTips | ShowWindow
Sizable | Tag | Themes
Top | Visible | WhatsThisHelpID
Width |  |

Events

Activate | AfterDock | BeforeDock
Click | DblClick | Deactivate
Destroy | DragDrop | DragOver
Error | Init | MiddleClick
MouseDown | MouseMove | MouseUp
MouseWheel | Moved | OLECompleteDrag
OLEDragDrop | OLEDragOver | OLEGiveFeedBack
OLESetData | OLEStartDrag | Paint
Resize | RightClick | UnDock

Methods

AddObject | AddProperty | CloneObject
Dock | Hide | Move
NewObject | OLEDrag | ReadExpression
ReadMethod | Refresh | Release
RemoveObject | ResetToDefault | SaveAsClass
SetAll | Show | ShowWhatsThis
WriteExpression | ZOrder |

See Also

Other Resources

ToolBar Object
CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Separator Object
Objects Collection
Objects, Collections, and Classes
Language Reference


XMLAdapter Class

Visual FoxPro 9.0 Language Reference
XMLAdapter Class
See Also

XMLAdapter is a "two-way" class. You can import XML and its contained schema to create tables, or you can create and generate XML from tables.

An XMLAdapter object stores object references to XML Schema and Document Object Model (DOM) nodes. It does not store actual XML schema information or content. An XMLAdapter object contains a Tables collection that contains one or more XMLTable objects and describes XML as Visual FoxPro cursors along with any relational information. Each XMLTable object can also contain a child XMLTable, and, at most, a Fields collection with one or more XMLField objects.

Note:
The XMLAdapter class requires Microsoft XML Core Services (MSXML) 4.0 Service Pack 1 (SP1) or later.

Using the XMLAdapter class, you can perform the following tasks:

  • Interpret the following schema formats when you use the XMLAdapter LoadXML and Attach methods.:

    • W3C XML Schemas (XS), W3C XML Schemas (XS) as used with .NET DataSets and SQL-XML

    • Microsoft XML Data Reduced Schema (XDR) as implemented by SQL-XML

    • ADO Recordset Schemas

      Note:
      The XMLAdapter LoadXML method might not correctly interpret other XML schema formats as produced by other products.

  • Retrieve XML and its associated schema from an XML source. XMLAdapter factors the contained schema into an XMLTable and its corresponding XMLField objects using the XMLAdapter LoadXML or Attach methods.

  • Create a cursor based on the schema and populate it with data represented by an XMLTable object when you use the XMLTable ToCursor method.

  • Represent changes from a .NET DiffGram to local or remote tables when you use the XMLTable ApplyDiffgram method.

  • Add one or more XMLTable objects to the XMLAdapter Tables collection or specify that the XMLAdapter LoadXML, Attach, or AddTableSchema methods perform this for you.

  • Use the XMLAdapter ToXML method to generate an XML document in W3C XML Schema format from one or more cursors or tables referenced by the XMLAdapter object.

XMLAdapter

Remarks

If you use an XMLAdapter object to convert XDR schema to XSD schema, you must change the XMLAdapter XMLNamespace property; otherwise, the XML parser cannot reload the XML. The following example illustrates this scenario:

Copy Code
TEXT TO cXML NOSHOW
<xml xmlns:s='uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882'
   xmlns:dt='uuid:C2F41010-65B3-11d1-A29F-00AA00C14882'
   xmlns:rs='urn:schemas-microsoft-com:rowset'
   xmlns:z='#RowsetSchema'>
<s:Schema id='RowsetSchema'>
   <s:ElementType name='row' content='eltOnly'>
      <s:AttributeType name='xmlfield' rs:number='1'
         rs:writeunknown='true' rs:nullable='true'>
   <s:datatype dt:type='number' rs:dbtype='currency' dt:maxLength='8'
      rs:scale='4' rs:precision='6' />
</s:AttributeType>
      <s:extends type='rs:rowbase'/>
   </s:ElementType>
</s:Schema>
<rs:data>
   <z:row xmlfield='12.12'/>
</rs:data>
</xml>
ENDTEXT

CLOSE DATABASES ALL
CLEAR

LOCAL oXMLAdapter as XMLAdapter
oXMLAdapter = NEWOBJECT('XMLAdapter')
oXMLadapter.LoadXML(cXML)
IF oXMLAdapter.Tables.Item(1).Fields.Item(1).DataType <> "Y" THEN
   ? 'Failed'
ELSE
   oXMLAdapter.Tables.Item(1).ToCursor()
   oXMLAdapter.XMLNamespace=""
   oXMLAdapter.ReleaseXML(.F.)
   oXMLAdapter.XMLSchemaLocation='c:\myxmlfile.xsd'
   oXMLAdapter.ToXML('c:\myxmlfile.xml',,.T.)
   oXMLadapter2 = NEWOBJECT('xmladapter')
   oXMLAdapter2.XMLSchemaLocation='c:\myxmlfile.xsd'
   oXMLAdapter2.LoadXML('c:\myxmlfile.xml',.T.,.T.)
ENDIF

When the schema is missing or not available, you can specify a schema that Visual FoxPro can use by setting the XMLAdapter XMLSchemaLocation property. You must specify this property before calling LoadXML. When Visual FoxPro executes LoadXML, Visual FoxPro looks for the schema in the following order:

  • Inline schema

  • External schema as specified in the XML document

  • Schema as specified by the XMLSchemaLocation property

The following code creates an XMLAdapter object with a Tables collection that remains empty until you load valid XML into the XMLAdapter object:

Copy Code
oMyAdapter=CREATEOBJECT("xmladapter")

The XML and XML schema data you retrieve using the XMLAdapter LoadXML method remains in memory until they are replaced by a subsequent call to LoadXML or when they are specifically released when you call the XMLAdapter ReleaseXML method.

Nested Tables The following table describes how XMLAdapter treats nested tables as either individual tables or as a whole table depending on the XML data source.

XML data source Description

ADO.NET DataSet

XMLAdapter considers each nested table as a separate table, which you can convert to a Visual FoxPro cursor. When the XML schema is analyzed, the XMLAdapter LoadXML and Attach methods create an individual XMLTable object for each nested table and adds it to the Tables collection. You can then use the XMLTable ToCursor, ChangesToCursor, and ApplyDiffgram methods to obtain data for each table.

SQL XML

XMLAdapter considers each nested table as inseparable from the parent table. When data is retrieved, the final result of a join operation between those tables is represented as a single result. If multiple levels of nesting exist, such as a child table containing a child table and so on, this single result contains data from a join operation between all tables in the hierarchy.

The XMLAdapter LoadXML and Attach methods create XMLTable objects for all tables. However, only the XMLTable object for the top-level parent table is added to the Tables collection. This XMLTable object represents the parent table and provides access to the single and final result from the join operation through the XMLTable ToCursor method. XMLTable objects for child tables are linked to their parents through the ChildTable and ParentTable properties. However, no way exists to obtain data from individual tables in the chain.

See Also

Other Resources

Objects, Collections, and Classes
XMLAdapter Object Properties, Methods, and Events
Tables Collection (XMLAdapter)
XMLTable Class
Fields Collection (XMLTable)
XMLField Class
LoadXML Method
Attach Method
ToCursor Method
ReleaseXML Method
ApplyDiffgram Method
XMLSchemaLocation Property


XMLAdapter Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
XMLAdapter Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and collections reference topics for this object.

Objects and Collections

Tables Collection (XMLAdapter)

Properties

CodePage | DeclareXMLPrefix | DisableEncode
ForceCloseTag | FormattedOutput | IsDiffGram
IsLoaded | IXMLDomElement | MapBinary
MapN19_4ToCurrency | MapVarchar | NoCpTrans
PreserveWhiteSpace | RespectCursorCP | RespectNesting
SelectionNamespaces | SOM | Unicode
UseCodePage | UTF8Encoded | WrapCharInCDATA
WrapMemoInCDATA | XMLConstraints | XMLName
XMLNameIsXPath | XMLNamespace | XMLPrefix
XMLSchemaLocation |  |

Methods

AddTableSchema | Attach | LoadXML
ReleaseXML | ToXML |

See Also

Other Resources

XMLAdapter Class


XMLField Class

Visual FoxPro 9.0 Language Reference
XMLField Class
See Also

In an XMLTable object, the Fields collection contains XMLField objects. Each XMLField object represents the structure of a field that is meaningful to Visual FoxPro.

The information in each XMLField object provides the details needed, such as the correct data type, size, and other information, to create each field in the cursor. When Visual FoxPro generates XML from a cursor, XMLField objects provide the information to create the XML document and schema.

XMLField

See Also

Other Resources

Objects, Collections, and Classes
XMLField Object Properties, Methods, and Events
XMLTable Class
Fields Collection (XMLTable)


XMLField Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
XMLField Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this object.

Properties

Alias | DataType | DisableEncode
FractionDigits | IsAttribute | IsBase64
IsBinary | IsNull | Keyfield
MaxLength | NoCpTrans | Unicode
WrapInCDATA | XMLName | XMLNameIsXPath
XMLTable | XMLType | XSDfractionDigits
XSDmaxLength | XSDtotalDigits | XSDtype

See Also

Other Resources

XMLField Class


XMLTable Class

Visual FoxPro 9.0 Language Reference
XMLTable Class
See Also

The Tables collection in an XMLAdapter object contains XMLTable objects and describes XML as Visual FoxPro cursors along with any relational information. Each XMLTable object can also contain a child XMLTable and, at most, a Fields collection containing XMLField objects.

XMLTable

Remarks

To retrieve XML and factor the contained XML Schema into an XMLTable and its corresponding XMLField objects, use the XMLAdapter LoadXML or Attach methods. You can then populate a cursor with data represented by the XMLTable object using the XMLTable ToCursor method. You can manually add an XMLTable object to an XMLAdapter Tables collection, or you can use the XMLAdapter AddTableSchema method to perform the same task.

See Also

Other Resources

Objects, Collections, and Classes
XMLTable Object Properties, Methods, and Events
XMLAdapter Class
Fields Collection (XMLTable)
XMLField Class
LoadXML Method
Attach Method
ToCursor Method
Tables Collection (XMLAdapter)
AddTableSchema Method


XMLTable Object Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
XMLTable Object Properties, Methods, and Events
See Also

The following tables list the properties, methods, and collections reference topics for this object.

Objects and Collections

Fields Collection

Properties

Alias | ChildTable | DeclareXMLPrefix
FirstNestedTable | NestedInto | NextSiblingTable
ParentTable | XMLAdapter | XMLConstraints
XMLName | XMLNameIsXPath | XMLNamespace
XMLPrefix |  |

Methods

ApplyDiffgram | ChangesToCursor | Nest
ToCursor | Unnest Method |

See Also

Other Resources

XMLTable Class


Visual FoxPro Foundation Classes A-Z

Visual FoxPro 9.0 Language Reference
Visual FoxPro Foundation Classes A-Z

In This Section

About Dialog Box Foundation Class

ActiveX Calendar Foundation Class

Application Registry Foundation Class

Array Handler Foundation Class

Cancel Button Foundation Class

Clock Foundation Class

Common Dialog Box Foundation Class

Common System Folders Foundation Class

Conflict Catcher Foundation Class

Cookies Foundation Class

Cross Tab Foundation Class

Crypto API Foundation Class

Data Edit Buttons Foundation Class

Data Navigation Buttons Foundation Class

Data Navigation Object Foundation Class

Data Session Manager Foundation Class

Data Validation Foundation Class

DBF to HTML Foundation Class

Distinct Values Combo Foundation Class

Error Object Foundation Class

Field Mover Foundation Class

File Version Foundation Class

Filter Dialog Box Button Foundation Class

Filter Dialog Box Foundation Class

Filter Expression Dialog Box Foundation Class

Find (Findnext) Buttons Foundation Class

Find Button Foundation Class

Find Dialog Box Foundation Class

Find Files/Text Foundation Class

Find Object Foundation Class

Font Combobox Foundation Class

Fontsize Combobox Foundation Class

Format Toolbar Foundation Class

FRX to HTML Foundation Class

FRX Cursor Foundation Class

FRX Device Helper Foundation Class

GDI Plus API Wrapper Foundation Classes

Get File and Directory Foundation Class

GoTo Dialog Box Button Foundation Class

GoTo Dialog Box Foundation Class

Graph By Record Foundation Class

Graph Object Foundation Class

Help Button Foundation Class

Hyperlink Button Foundation Class

Hyperlink Image Foundation Class

Hyperlink Label Foundation Class

INI Access Foundation Class

Item Locator Foundation Class

Keywords Dialog Box Foundation Class

Launch Button Foundation Class

Locate Button Foundation Class

Lookup Combobox Foundation Class

Mail Merge Object Foundation Class

Messagebox Handler Foundation Class

Microsoft Agent Utility Foundation Class

MouseOver Effects Foundation Class

Mover Foundation Class

Navigation Shortcut Menu Foundation Class

Navigation Toolbar Foundation Class

Object State Foundation Class

ODBC Registry Foundation Class

Offline Switch Foundation Class

OK Button Foundation Class

Output Control Foundation Class

Output Dialog Box Foundation Class

Output Object Foundation Class

Password Dialog Box Foundation Class

Pivot Table Foundation Class

Pool Manager Foundation Class

Preview Report Foundation Class

QBF Foundation Class

Registry Access Foundation Class

Regular Expressions Foundation Class

ReportListener Foundation Classes

Resize Object Foundation Class

RTF Controls Foundation Class

Run Form Button Foundation Class

SCX to HTML Foundation Class

SendMail Buttons Foundation Class

SetAllX Extension Foundation Class

Shell Execute Foundation Class

Shortcut Menu Class Foundation Class

Simple Edit Buttons Foundation Class

Simple Navigation Buttons Foundation Class

Simple Picture Navigation Buttons Foundation Class

Sort Dialog Box Button Foundation Class

Sort Dialog Box Foundation Class

Sort Mover Foundation Class

Sort Object Foundation Class

Sort Selector Foundation Class

Sound Player Foundation Class

Splash Screen Foundation Class

SQL Pass Through Foundation Class

Stop Watch Foundation Class

String Library Foundation Class

Super Mover Foundation Class

System Metrics Foundation Class

System Toolbar Foundation Class

Table Mover Foundation Class

Text Preview Foundation Class

Thermometer Foundation Class

Trace Aware Timer Foundation Class

Type Library Foundation Class

URL Combo Foundation Class

URL Open Dialog Box Foundation Class

User Privileges Foundation Class

VCR Buttons Foundation Class

VCR Picture Navigation Buttons Foundation Class

Video Player Foundation Class

Web Browser Control Foundation Class

Window Handler Foundation Class

XML Web Services Foundation Classes

Related Sections

Guidelines for Using Visual FoxPro Foundation Classes

Foundation Class Samples

Objects, Collections, and Classes


About Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
About Dialog Box Foundation Class
See Also

This class is a simple About dialog box template for custom applications. The dialog box includes a button that accesses system information using the Registry class.

Category | Misc Forms
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Dialogs
Class | _aboutbox
Base Class | Form
Class Library | _dialogs.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\dialogs.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Add to Project. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. If you choose Create a new form, Visual FoxPro displays the Open dialog box so you can specify the name of the form, then creates and opens the form in the Form Designer. Specify values for the labels, then save and call the form from your application.

Properties, Events, Methods | Description
cMSINFODir property | Specifies the path of Msinfo.exe. Default: ""
GetRegisteredCompany method | A stub routine to return the registered company. To use, replace the lblUserCorp.Caption value.
GetRegisteredOwner method | A stub routine to return registered owner. To use, replace the lblUserName.Caption value.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


ActiveX Calendar Foundation Class

Visual FoxPro 9.0 Language Reference
ActiveX Calendar Foundation Class
See Also

This class uses the ActiveX calendar control that can be bound to a date field for a form or other container.

Category | Date/Time
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data/Time
Class | _olecalendar
Base Class | OLEcontrol
Class Library | _datetime.vcx
Parent Class | _olecontrol
Sample | ...\Samples\Solution\Ffc\datacal.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the appropriate Date_column value. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
Date_column property | Specifies a date type field to which to link the calendar. Default: ""
RefreshDisplay method | Updates the calendar display with the value in the column specified in the Date_column property. Syntax: RefreshDisplay( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Application Registry Foundation Class

Visual FoxPro 9.0 Language Reference
Application Registry Foundation Class
See Also

This class provides a set of registry functions that return application-specific information such as version and location.

Category | System Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _filereg
Base Class | Custom
Class Library | _registry.vcx
Parent Class | registry
Sample | ...\Samples\Solution\WinAPI\regfile.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class on the form. You can then specify the appropriate values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
GetAppPath method | Checks and returns path of the application associated with a particular extension. Syntax: GetAppPath(cExtension, cExtnKey, cAppKey, lServer) Return: GetApplication(cExtnKey, @cAppKey, lServer) Arguments: cExtension specifies the extension of the application.cExtnKey specifies the registry key of the application.cAppKey specifies the application path.lServer specifies whether the extension is a server application.
GetLatestVersion method | Returns latest version for a specified application. Syntax: Getlatestversion(cClass, cExtnKey, cAppKey, lServer) Return: cExtnKey, @cAppKey, lServer Arguments: cClass specifies the class key of the application.cExtension specifies the extension of the application.cExtnKey specifies the registry key of the application.cAppKey specifies the application path.lServer specifies whether this is a server application.
GetApplication method | Retrieves the application key. Syntax: Getapplication(cExtnKey, cAppKey, lServer) Return: @cAppKey Arguments: cExtension specifies the extension of the application.cExtnKey specifies the registry key of the application.cAppKey specifies the application path.lServer specifies whether the extension is not a full application.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Array Handler Foundation Class

Visual FoxPro 9.0 Language Reference
Array Handler Foundation Class
See Also

This class provides methods for handling certain array operations that are not performed by Visual FoxPro array functions, including inserting and deleting specific array elements, and scanning an array by column.

Category | Data Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _arraylib
Base Class | Custom
Class Library | _utility.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\arrays.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
AColScan method | Scans the column nColumn, of array aSearch for the value specified in sExpr. Syntax: AcolScan(@aSearch, sExpr, nColumn, lRetRow) Return: none Arguments: aSearch specifies the array to analyze.sExpr specifies the expression to seek.nColumn specifies the column of the array in which to seek sExpr.lRetRow specifies whether the method returns the row number in which sExpr was found.
DelAitem method | Deletes an array element. Syntax: DelAitem(@aArray, wziRow) Return: none Arguments: aArray specifies the name of the array being processed.wziRow specifies the item to be deleted.
InsAitem method | Inserts an array element. Syntax: InsAitem(@aArray, sContents, iRow) Return: none Arguments: aArray specifies the name of the array being processed.sContents specifies a string value to be added to aArray.iRow specifies the row in which to insert the value in sContents.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Cancel Button Foundation Class

Visual FoxPro 9.0 Language Reference
Cancel Button Foundation Class
See Also

This class releases a form and discards any outstanding buffered data.

Category | Misc Buttons
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | _cmdCancel
Base Class | CommandButton
Class Library | _miscbtns.vcx
Parent Class | _cmdOK
Sample | ...\Samples\Solution\Ffc\buttons.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places a button on your form. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Clock Foundation Class

Visual FoxPro 9.0 Language Reference
Clock Foundation Class
See Also

This class is a simple clock control for a form or container.

Category | Date/Time
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Date/Time
Class | _clock
Base Class | Container
Class Library | _datetime.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Controls\Timer\clock.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the object in your form where you can specify the appropriate nTimeFormat value. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
nTimeFormat property | Toggles between short (for 0) and long (for non-zero values) formats as specified in the Control Panel. Default : 0

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Common Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
Common Dialog Box Foundation Class
See Also

You can use system Open and Save file dialog boxes that mimic the latest Windows ones in your applications. For example, you can have a Places bar on the left side of the dialog box.

Category | System Dialog boxes
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Dialogs
Class | _comdlg
Base Class | Custom
Class Library | _system.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\Getfilex.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class, or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
aFileNames array | Array of filenames returned from dialog box. Default: .F.
aFileList array | Array of file extension filters passed to dialog box. Default: .F.
cCustomFilter property | Custom filter the user created while using dialog box. Default: none
cDefaultExtension property | Default file extension to display. Default: none
cFileName property | Name of file selected or initially set as default. Default: none
cFilePath property | Path from which files were selected. Default: none
cFileTitle property | File title property of the selected file(s). Default: none
cInitialDirectory property | Initial directory from which to display files. Default: none
cTitleBar property | Caption for dialog box title bar. Default: none
lAllowMultiSelect property | Specifies whether to allow multiple files. Default: .F.
lFileMustExist property | Specifies whether to allow only existing files to be entered. Default: .F.
lHideReadOnly property | Specifies whether to hides read-only files from list. Default: .T.
lNewExplorer | Specifies whether to use new explorer user interface and features such as Places bar. Default: .T.
lNoChangeDir property | Specifies whether to prevent changing of displayed directory. Default: .F.
lNoNetworkButton property | Specifies whether to prevent including a network button in the dialog box. Default: .F.
lNoPlacesBar property | Specifies whether to prevent a Places bar in the dialog box. Default: .F.
lNoValidate property | Specifies that files are not validated in the dialog box. Default: .F.
lSaveDialog box property | Specifies whether to use Save dialog box instead of Open one. Default: .F.
nFileCount property | Specifies the number of files selected from the dialog box. Default: 0
nFilterIndex property | Specifies which of the filters were selected from the dialog box. Default: 0
AddFilter method | Specifies the file extension filters to use when displaying the dialog box. Syntax: AddFilter(cDescription, cSkeleton) Return: none Arguments: cDescription provides a description of the filter. cSkeleton specifies the file extension filter skeleton.
ClearFilters method | Clears all file extension filters. Syntax: ClearFilters( ) Return: none Arguments: cUser specifies name of user to check
ShowDialog box method | Displays dialog box with various options such as filters. Syntax: ShowDialog box( ) Return: none Arguments: none
TestDialog box method | Test script for displaying a dialog box. Syntax: TestDialog box( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Common System Folders Foundation Class

Visual FoxPro 9.0 Language Reference
Common System Folders Foundation Class
See Also

This class gives you the location of common system windows such as the My Documents folder and the Application Data folder. These are commonly needed in applications that provide Windows 2000 Logo compliancy. See SHGetFolderPath in MSDN for more details.

Category | System Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _commonfolder
Base Class | Custom
Class Library | _system.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\Logo.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
GetFolder method | Returns path to specified system folder. Syntax: GetFolder(nFolderID, lCreateNew) Return: name of folder Arguments: nFolderID ID reference to the folder. Refer to the class method for common IDs as specified in SHGetFolderPath in MSDN. lCreateNew specifies whether to create folder when one does not exist

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Conflict Catcher Foundation Class

Visual FoxPro 9.0 Language Reference
Conflict Catcher Foundation Class
See Also

This class provides a dialog box that displays, conflicting rows encountered during editing sessions under optimistic buffering. The original, current, and new values are presented for resolution. You can use this class with either row or table buffering.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _conflicts
Base Class | Form
Class Library | _dataquery.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\Conflicts.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Add to Project. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. If you choose Create a new form from the selected class, Visual FoxPro displays the Open dialog box so you can specify the name of the form, then creates and opens the form in the Form Designer. You need to SET MULTILOCKS ON and enable buffering.

Properties, Events, Methods | Description
CursorAlias property | Specifies the alias to check for conflicts. Default: ""
lAutoCheck property | Specifies whether checking begins on startup. Default: .T.
StartCheck method | Checks for conflicts in the buffered data of the alias. Syntax: StartCheck( ) Return: none Arguments: none
ConflictAlias property | Internal to the class.
lRowConflict property | Internal to the class.
aConflicts[1,0] property | Internal to the class.
NextConflict method | Internal to the class.
CheckSource method | Internal to the class.
Alert method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Cookies Foundation Class

Visual FoxPro 9.0 Language Reference
Cookies Foundation Class
See Also

This is a simple Web class for handling cookies between Web pages. This class is designed primarily for use with Microsoft Internet Information Servers such as FoxISAPI.

Category | Internet
Default Catalog | Visual FoxPro Catalog\Foundation Classes \Internet
Class | _cookie
Base Class | Custom
Class Library | _internet.vcx
Parent Class | _custom

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form where you can specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
cCookie property | Name of the current cookie. Def ault: ""
CookieTable property | Name of the cookies table. Default: Cookies.dbf
DBFAlias property | Alias of the cookies table. Default: ""
MakeCookie method | Generates a unique cookie based on the system datetime. Syntax: MakeCookie( ) Return: none Arguments: none
GetCookie method | Gets a cookie from HTML server. Syntax: GetCookie(cStr) Return: none Arguments: cStr specifies the name of the cookie to be retrieved.
WriteCookieInfo method | Writes the cookie's information to the cookies table. Syntax: WriteCookieInfo( ) Return: none Arguments: none
FixURL method | Reads the URL and evaluates %-markers for reading the cookie. Syntax: FixURL(m.cStr) Return: Arguments: m.cStr specifies the name of the cookie to be retrieved.
GetVal method | Retrieves a value from the target string, cStr. Syntax: GetVal(cStr, cVal) Return: cVal Arguments: cStr specifies the name of the string to be searched for the value. cVal cVal specifies the value to be sought in the string, cStr.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Cross Tab Foundation Class

Visual FoxPro 9.0 Language Reference
Cross Tab Foundation Class
See Also

This class uses the Cross-Tab Wizard engine to generate a cross tab report when placed on a form.

Category | Automation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Automation
Class | _xtab
Base Class | Custom
Class Library | _utility.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\Automate.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form in a data environment, Visual FoxPro opens a builder so you can specify the appropriate lDisplayNulls, lTotalRows, nTotalOption, and lBrowseAfter values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cOutfile property | The name of the output file. Default: xtabquery
lCursorOnly property | Specifies whether the input datasource is cursor. Default: .T.
lCloseTable property | Specifies whether to close the source datasource after the cross tab is generated. Default: .T.
lShowThem property | Specifies whether to show thermometer during cross tab generation. Default: .T.
nRowField property | Specifies the field position in the datasource of the cross tab rows. Default: 1
nColField property | Species the field position in the datasource of the cross tab columns. Default: 2
nDataField property | Specifies the field position in the datasource of the cross tab data. Default: 3
lTotalRows property | Specifies whether to total rows in the cross tab output. Default: .F.
nTotalOption property | Specifies the Totaling option to perform: Default: 0
lDisplayNulls property | Specifies whether to display null values in the cross tab output. Default: .F.
lBrowseAfter property | Specifies whether to open a Browse window on the cross tab output. Default: .T.
RunXtab method | Generates a cross tab. Syntax: RunXtab( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Crypto API Foundation Class

Visual FoxPro 9.0 Language Reference
Crypto API Foundation Class
See Also

This advanced class gives you detailed access to Windows Crypto API routines. You can use it to encrypt information in your applications, including text, files, and data fields. Routines exist for stream, block, symmetrical, private and public key encryption, as well as file signing.

Category | System Dialog Boxes
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _cryptapi
Base Class | Custom
Class Library | _crypt.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\Crypto.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

For information about properties, events, and methods, refer to class and sample for details.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Data Edit Buttons Foundation Class

Visual FoxPro 9.0 Language Reference
Data Edit Buttons Foundation Class
See Also

This is a complete set of edit buttons that includes Top, Previous, Next, Bottom, Find, Print, Add Delete, Edit, and Save buttons. The Form Wizard uses this class.

Category | Data Editing
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | picbtns
Base Class | CommandGroup
Class Library | wizbtns.vcx
Parent Class | txtbtns
Sample | ...\Samples\Solution\Ffc\dataedit.scx

Remarks

You can use this class on simple forms with a single table or for 1-to-Many relationship forms using fields for a parent table and a grid for the child table.

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you add the class to a form, Visual FoxPro places the buttons on the form. You can specify a data source and provide input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass. The txtbtns parent class contains additional properties you can set.

Properties, Events, Methods | Description
WizBMPpath property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Data Navigation Buttons Foundation Class

Visual FoxPro 9.0 Language Reference
Data Navigation Buttons Foundation Class
See Also

This class is a set of navigation buttons that includes Top, Next, Prev, and Bottom buttons. It also contains the DataChecker class to check for conflicts during navigation betweeen records.

Category | Data Navigation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Navigation
Class | _datanavbtns
Base Class | Container
Class Library | _datanav.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Forms\single.scx

Remarks

To use, drop the class on a project or form in a data environment or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, you should provide input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cSkipTable property | The table within which to move the pointer. Default: ""
lEnableDisableOnInit property | Specifies whether the navigation buttons are enabled when they are first loaded. Default: .T.
RecordPointerMoved method | Called each time the record pointer is moved, providing a new event for the class. Syntax: RecordPointerMoved( ) Return: none Arguments: none
EnableDisableButtons method | Enables or disables buttons based on the record pointer location. Syntax: EnableDisableButtons( ) Return: none Arguments: none
BeforeRecordPointerMoved method | Called before the record pointer is moved to determine if the table contains records. Syntax: BeforeRecordPointerMoved( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Data Navigation Object Foundation Class

Visual FoxPro 9.0 Language Reference
Data Navigation Object Foundation Class
See Also

This is non-visual navigation object that can be used by other controls to navigate records in a datasource such as a table or view.

Category | Data Navigation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Navigation
Class | _tablenav
Base Class | Custom
Class Library | _table.vcx
Parent Class | _table
Sample | ...\Samples\Solution\Ffc\datanav.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a project, you can choose between adding the class or creating a subclass. When you add the class to a form, Visual FoxPro displays the class icon on the form so you can add data navigation objects then reference appropriate class methods on the form in the Form Designer.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
lCycle property | Controls movement when the record pointer reaches the end or beginning of the file. Default: .F.
GoBottom method | Moves record pointer to last record. Syntax: GoBottom( ) Return: none Arguments: none
GoRecord method | Moves record pointer to a specified record number. Syntax: GoRecord( ) Return: none Arguments: tiRecord
GoNext method | Moves the record pointer to the next record using SKIP 1. If this movement positions the pointer at EOF( ), behavior is determined by the lCycle property. Syntax: GoNext( ) Return: none Arguments: none
GoPrevious method | Moves record pointer to the previous record using SKIP –1 if the pointer is not already at BOF( ). If this movement positions the pointer at BOF( ), behavior is determined by the lCycle property. Syntax: GoNext( ) Return: none Arguments: none
GoTop method | Moves record pointer to first record. Syntax: GoTop( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Data Session Manager Foundation Class

Visual FoxPro 9.0 Language Reference
Data Session Manager Foundation Class
See Also

This class is used to manage data sessions and handle data updates in all forms or formsets in the current data session. It enables an Application object to easily iterate through sessions to provide Windows-closing behavior during Exit or Shutdown. It also provides generic QueryUnload behavior for forms and formsets, and generic session-wide Update and Revert code. You can use it to evaluate whether any data has been changed in a session before you use your own conflict handling procedure.

Category | Application
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Application
Class | _datassession
Base Class | Custom
Class Library | _app.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\environ.scx

Remarks

This class works with free tables as well as tables in databases. Observe the transactions limit (5).

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods Description

iDataChangedMode property

Specifies the type of data change performed.

Default: 0

iSavedSessionID property

Specifies integer value representing the ID of the saved session.

Default: 1

lSuccess property

Specifies whether the data operation (update) was successful.

Default: .T.

lUseTransactions property

Specifies whether to wrap the updating routine in a transaction.

Note:
Only tables in a database container (.dbc) are affected in transactions.

Default: .T.

DataChanged method

Checks if data has changed.

Syntax: DataChanged( )

Return: none

Arguments: none

DataFlush method

Ensures that the active control will have its current contents "recognized" even if you choose to update from a toolbar button while a grid has the focus.

Syntax: DataFlush( )

Return: none

Arguments: none

GetActiveControlRef method

Returns the truly active control, loRealActiveControl, in cases where the current active control is a Grid.

Syntax: GetActiveControlRef(toActiveControl)

Return: loRealActiveControl

Arguments: toActiveControl specifies the current control.

GetMessageBoxTitle method

Returns a portion of the titlebar text specifying the name of the message.

Syntax: GetMessageBoxTitle( )

Return: cTitlebarText

Arguments: none

QueryUnload method

Provides dialog boxes to manage data change decisions.

Syntax: QueryUnload(tlDataChangeAlreadyConfirmed, toForm, tlNoShow)

Return: liResult

Arguments: tlDataChangeAlreadyConfirmed specifies whether data has been changed. toForm specifies the form.tlNoShow specifies whether to display the form.liResult specifies the MESSAGEBOX or value.

RestoreSessionID method

Restores the data session.

Syntax: RestoreSessionID

Return: none

Arguments: none

Revert method

Reverts the session to original data.

Syntax: Revert(tlUserChoiceAlreadyConfirmed, tlDataChangeAlreadyConfirmed, toForm, tlNoShow)

Return: none

Arguments: tlUserChoiceAlreadyConfirmed specifies whether to display a confirmation dialog box.tlDataChangeAlreadyConfirmed specifies whether to display a confirmation dialog box.toForm specifies the form.tlNoShow specifies whether to display the form.

SetSessionID method

Sets the data session.

Syntax: SetSessionID( )

Return: none

Arguments: none

Update method

Updates data.

Syntax: Update(tlUserChoiceAlreadyConfirmed, tlDataChangeAlreadyConfirmed, toForm, tlNoShow)

Return: none

Arguments: tlUserChoiceAlreadyConfirmed specifies whether to display a confirmation dialog box.tlDataChangeAlreadyConfirmed specifies whether to display a confirmation dialog box.toForm specifies the form.tlNoShow specifies whether to display the form.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Data Validation Foundation Class

Visual FoxPro 9.0 Language Reference
Data Validation Foundation Class
See Also

This class traps for data conflicts on buffered data.

Category | Data Editing
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _datachecker
Base Class | Custom
Class Library | _datanav.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\conflicts.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, you need to specify the appropriate property values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
HandleRecord method | Compares the current value, old value, and original value on disk of each field, displaying a message box if a change or conflict is detected. Syntax: HandleRecord(lnScope) Return: nReturn Arguments: lnScope specifies the degree of validation: nReturn specifies the action taken:
String method | Called by the HandleRecord method, returns a character equivalent of the passed value. Returns only a notification for memo fields. Syntax: String(luValue) Return: none Arguments: luValue specifies the value to be checked.
VerifyChanges method | Prompts a user to save all changes made to a table or record. Syntax: VerifyChanges( ) Return: none Arguments: none
VerifyEachChange method | Prompts a user to confirm each change made. Syntax: VerifyEachChange( ) Return: none Arguments: none
CheckcConflicts method | Notifies a user when data has changed after record editing started. Syntax: CheckcConflicts( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


DBF to HTML Foundation Class

Visual FoxPro 9.0 Language Reference
DBF to HTML Foundation Class
See Also

This class converts a Visual FoxPro cursor (.DBF) to HTML. Hooks control the scope, visual layout and HTML generation. For more information on creating Web pages from Visual FoxPro tables, see Genhtml.prg.

Category | Internet
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Internet
Class | _dbf2html
Base Class | Custom
Class Library | _internet.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\dohtml.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can accept the current values or specify the appropriate cSource, cOutFile, and nGenOutput values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cSource property | Specifies the source file from which to generate HTML. Default: ""
nGenOutput property | _GENHTML output options. Default: 2
cOutFile property | Specifies the name of the HTML file to output. Default: ""
lAutoNameOutput property | Specifies whether _GENHTML should automatically name the output file based on the source. Default: .T.
lUseCurrentAlias property | Specifies whether to use the current alias as the source. Default: .T.
cScope property | Specifies the scope (for example, NEXT or ALL) for the output. Default: ""
cStyle property | Specifies the visual style as listed in the ID field of Genhtml.dbf. Default: ""
GenHTML method | Generates HTML code by calling the Genhtml.prg program using properties specified in cSource, cOutput, and nGenOutput. Syntax: GenHTML( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Distinct Values Combo Foundation Class

Visual FoxPro 9.0 Language Reference
Distinct Values Combo Foundation Class
See Also

This class performs a lookup of unique values in the ControlSource field to populate a combobox.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _cbodistinctvalues
Base Class | ComboBox
Class Library | _dataquery.vcx
Parent Class | _combobox
Sample | ...\Samples\Solution\Ffc\datalook2.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you drop the class on a form, Visual FoxPro places a combobox on the form. You need to specify an appropriate value for the ControlSource property. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Error Object Foundation Class

Visual FoxPro 9.0 Language Reference
Error Object Foundation Class
See Also

This class is a generic error handler that works for both object and procedural code. This class is used with an application framework generated by the Application Wizard.

Category | Application
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Application
Class | _error
Base Class | Custom
Class Library | _app.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\error.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can then specify the appropriate property values and access its functionality from input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
GetMessageBoxTitle method | Returns the truly active control, loRealActiveControl, in cases where the current active control is a Grid. Syntax: GetActiveControlRef(toActiveControl) Return: ERROR_MESSAGEBOX_TITLE_LOC Arguments: none
cCurrentMessage property. | Specifies the error message. Default: ""
cCurrentMethod property | Specifies the method in which the error occurred. Default: ""
iCurrentError property | Specifies the error number. Default: 0
iCurrentLine property | Specifies the line in which the error occurred. Default: 0
cCurrentClass property | Specifies the error classification that the error object specifies for this particular error number. Default: ""
lServer property | Checks _VFP.StartMode to determine whether any sort of modal feedback should be avoided because of the way Visual FoxPro was started. Default: (BETWEEN(_VFP.StartMode,1,3)))
cLogAlias property | Specifies the name of the log alias. Default: ""
cLogDBF property | Specifies the name of log file (DBF) that is built by the _error object. Default: ""
lUserCancelled property | Allows the outside program to perform any necessary cleanup operations before release. Default: .F.
HandleMain method | The routine that handles the error. Syntax: HandleMain(tiError, tcMethod, tiLine) Return: none Arguments: tiError specifies the error number.tcMethod specifies the name of the current method.tiLine specifies the number of the current line.
OKToReport method | Abstract class to evaluate whether to report error. Syntax: OKToReport( ) Return: none Arguments: none
isTrivial method | Specifies whether an error is a trivial error. Syntax: IsTrivial(tlWantDialog box) Return: none Arguments: tlWantDialog box specifies an optional dialog box to display.
isFatal method | Specifies whether an error is a fatal error. Syntax: isFatal( ) Return: none Arguments: tlWantDialog box specifies an optional dialog box to display.
GetMessageBoxTitle method | This is meant for your subclass or instance to fill out with application-specific information. Syntax: GetMessageBoxTitle( ) Return: none Arguments: none
DisplayErrorLog method | Displays the error log. Syntax: DisplayErrorLog( ) Return: none Arguments: none
OKToContinue method | Evaluates an error to determine whether to continue program execution. Syntax: OKToContinue( ) Return: none Arguments: none
SetLog method | Determines the name of or creates the error log table and alias. Syntax: SetLog( ) Return: cLogAlias. The error log table has the following format:CREATE TABLE (THIS.cLogDBF) ; (errstamp t, ; listing m,; usernotes m) Arguments: none
cCurrentErrorParam property | Internal to the class.
aErrorClass[1,3] property | Internal to the class.
aErrors[1,6] property | Internal to the class.
*FillArrays . | Internal to the class.
LogErrorReport method | Internal to the class.
GetErrorAttribute method | Internal to the class
isGoodErrorLog method | Internal to the class.
UserHandlesError method | Internal to the class.
UserCancelled method | Internal to the class.
FillLogRecord method | Internal to the class.
DoErrorLogUI method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Field Mover Foundation Class

Visual FoxPro 9.0 Language Reference
Field Mover Foundation Class
See Also

This is a super mover list box class that automatically loads fields from the current data source when you drop it on a form.

Category | Movers
Default Catalog | Visual FoxPro Catalog\Foundation Classes\User Controls
Class | _fieldmover
Base Class | Container
Class Library | _mover.vcx
Parent Class | _supermover
Sample | ...\Samples\Solution\Ffc\movers.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can accept or specify the appropriate SkipGeneral, SkipMemo, and AllowReadOnly values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
AllowReadOnly property | Allows for a read-only datasource. Default: .F.
AutoInit property | Automatically run when loaded. Default: .T.
CurrentAlias property | The current alias determined by ALIAS( ). Default: ""
CurrentDBC property | The current database file. Default: ""
CursorType property | Specifies the type of cursor. Default: 3
DBCTable property | Name of the table in the database. Default: ""
MultiTable property | Specifies whether to support multiple tables. Default: .F.
SkipGeneral property | Specifies whether General fields are included in the list. Default: .F.
SkipMemo property | Specifies whether Memo fields are included in the list. Default: .F.
TableType property | Returns the table type - SYS(2029). Default: 0
AcolScan method | Scans a specific column in the array. Syntax: AcolScan(@wztarr, wztexpr, wztcol) Return: none Arguments: wztarr specifies the array to scan.wztexpr specifies the target expression for which to scan.wztcol specifies the column to scan.
AddToArray method | Adds sContents to the array, aAddToArray, at iRow. Syntax: AddToArray(@aAddToArray, sContents, iRow) Return: none Arguments: aAddToArray specifies the array to which to add an item.sContents specifies the addition to the array.iRow specifies in which array row to insert sContents.
Alert method | Displays a messagebox. Syntax: Alert(pMessage) Return: none Arguments: pMessage specifies the message to be displayed by MESSAGEBOX( ).
FieldChange method | Triggered when fields selected changes. Syntax: FieldChange(nButton) Return: none Arguments: nButton specifies the button pressed.
GetTableData method | Retrieves fields from a table. aWizFlist contains the list of fields, aCalcFields contains the list of calculated fields, aPickFields contains the list of selected fields. Syntax: GetTableData( ) Return: aWizFList, aCalcFields, aPickFields Arguments: none
InitData method | Initializes data. Syntax: InitData( ) Return: none Arguments: none
InitVars method | Initializes variables used by movers. Syntax: InitVars( ) Return: none Arguments: none
JustStem method | Retrieves the filename stem. Syntax: JustStem(m.filename) Return: m.filename Arguments: m.filename specifies the filename from which the stem is extracted.
SetDataProps method | Sets data properties of the data source. Syntax: SetDataProps( ) Return: none Arguments: none
UpdateStatusbar method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples
Super Mover Foundation Class


File Version Foundation Class

Visual FoxPro 9.0 Language Reference
File Version Foundation Class
See Also

Retrieves information from the version resource of a file and stores it in an array.

Category | File Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _fileversion
Base Class | Custom
Class Library | _utility.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\WinAPI\getver.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class on the form. You can then specify the appropriate values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
cFileName property | The name of the target file. Default: ""
aVersion[12,0] property | Array containing the file version information. Default: .F.
GetVersion method | Retrieves version information for cFileName. Syntax: GetVersion( ) Return: none Arguments: none
DisplayVersion method | Displays the version information for cFileName. Syntax: DisplayVersion( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Filter Dialog Box Button Foundation Class

Visual FoxPro 9.0 Language Reference
Filter Dialog Box Button Foundation Class
See Also

This class is a button that, when clicked, displays a dialog box that enables you to filter data in a particular field.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | _filterbutton
Base Class | CommandButton
Class Library | _table2.vcx
Parent Class | _dialog boxbutton
Sample | ...\Samples\Solution\Ffc\datasort.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places a button on the form. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
lExprDialog box property | Internal to the class.
cExprClass property | Internal to the class.
cFilterClass property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Filter Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
Filter Dialog Box Foundation Class
See Also

This class is a dialog box that uses an existing filter object to allow you to filter data in a particular field.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _filterdialog
Base Class | Form
Class Library | _table.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\datasort.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Create Form or Add to Project. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. When you drop the class on a project or choose Create a new form from the selected class in the shortcut menu, Visual FoxPro displays an Open dialog box so you can specify the name of the form. Then Visual FoxPro creates and opens the form in the Form Designer.

_FilterDialog enables you to use Visual FoxPro expressions to build a complex filter using booleans, nested conditions, and so on, limited to the fields available in currently-open tables. It automatically provides delimiters for various field types. It suggests which expressions might be optimizable by checking available tags on the current table. The field list places "*" in front of field names that have usable index tags.

Like _FilterExpr, _FilterDialog needs at least one open table on which it can set a filter. Unlike _FilterExpr, _FilterDialog is not necessarily modal, however it is modal when _FilterExpr calls it. FilterDialog determines the current table in the Init event. FilterDialog never changes data sessions.

When called by _FilterExpr, _FilterDialog determines what filter the user has already specified in the _FilterExpr edit box and displays that expression as its initial set of conditions. When _FilterDialog is called directly, it checks the current alias for a filter, using SET("FILTER"), and shows any current filter as its initial conditions.

The _FilterDialog SetUpFilter( ) method uses the conditions listed in the dialog box and creates a filter expression, then applies the NORMALIZE( ) function to the expression. The result is stored in the cFilter property. When you click OK, SetupFilter( ) runs. _FilterDialog calls the _FilterExpr.SetFilter method if it is called by an instance of _FilterExpr; otherwise it uses _table to determine if navigation is allowed, sets the filter directly, and refreshes the display if the filter is set.

_FilterDialog is a standalone object and does not require the existence of _FilterExpr to build a filter. However, when called by _FilterExpr, the two dialog boxes work together to build a filter, by specifying an expression in _FilterExpr and by making choices in _FilterDialog. For more information on the Filter Expression class, see Filter Expression Dialog Box Foundation Class.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods Description

cFilter property

Contains the filter expression processed in the SetupFilter method.

Default: ""

SetupFilter method

This method takes the conditions listed in the dialog box and creates them into a filter expression, then applies the NORMALIZE( ) function to the expression.

Syntax: SetupFilter(tcValue)

Return: cFilter

Arguments: tcValue specifies an expression to use as the filter.cFilter is the value contained in the cFilter property.

cOldexact property

Internal to the class.

iBact property

Internal to the class.

iQptr property

Internal to the class.

iQuerymax property

Internal to the class.

iSelect property

Internal to the class.

oCaller property

Internal to the class.

aDBFs[1,0] property

Internal to the class.

aTags[1,0] property

Internal to the class.

aQuery[1,0] property

Internal to the class.

aFLDs[1,0] property

Internal to the class.

SetAction method

Internal to the class.

QReset method

Internal to the class.

QSet method

Internal to the class.

FSet method

Internal to the class.

NoBrack method

Internal to the class.

Brackets method

Internal to the class.

SetTags method

Internal to the class.

OnTag method

Internal to the class.

NoTag method

Internal to the class.

EditQuery method

Internal to the class.

SetRowsources method

Internal to the class.

SetInitialQueryParts method

Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples
Filter Expression Dialog Box Foundation Class


Filter Expression Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
Filter Expression Dialog Box Foundation Class
See Also

This class creates an advanced filter expression dialog box.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _filterexpr
Base Class | Form
Class Library | _table.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\datasort.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Create Form or Add to Project. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. When you drop the class on a project or choose Create a new form from the selected class in the shortcut menu, Visual FoxPro displays an Open dialog box so you can specify the name of the form. Visual FoxPro then creates and opens the form in the Form Designer.

_FilterExpr is a modal dialog box that enables you to specify a filter expression, or to construct a filter expression using one of two subsidiary dialog boxes.

The lAdvanced property toggles _FilterExpr between two modes, standard and advanced. In standard mode, the Build expression button uses an instance of the _FilterDialog class to build a simple expression. In advanced mode, the button uses the value in the _GETEXPR system variable.

The cFilter property contains the current contents of the filter expression the user builds. The edit box bound to the cFilter property can contain up to 254 characters.

If _FilterExpr doesn't find a table on which to act, it returns false (.F.) before leaving the Init event; otherwise it restores these settings in its Unload method. When _FilterExpr instantiates, if ALIAS( ) is empty, it looks for an open table in the current data session of the currently selected form or formset.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Descriptionbox b
cFilter property | Contains the filter expression processed in the SetupFilter method. Default: (SPACE(254))
lAdvanced property | This is used to toggle _FilterExpr between two modes, _FilterDialog false (.F) and GETEXPR true (.T.). Default: .F.
iOldSession property | The old data session. Default: 0
iOldSelect property | The old work area. Default: 0
SetFilter method | Sets the value of cFilter. This method is primarily useful when _FilterDialog is called modally to do further work on the expression to be built. Syntax: SetFilter(tcValue) Return: cFilter Arguments: tcValue specifies an expression to use as the filter.cFilter is the filter expression.
SetFilterOnTable method | If the current table allows navigation, this method applies the current filter to the current alias, issues a LOCATE, and then invokes the RefreshLastWindowAfterChange( ) method to get the filter for the next available window in your application. Syntax: SetFilterOnTable( ) Return: none Arguments: none
cFilter_Access method | Internal to the class. Removes carriage returns, line feeds, and tabs from the filter expression and replaces these characters with spaces.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Find (Findnext) Buttons Foundation Class

Visual FoxPro 9.0 Language Reference
Find (Findnext) Buttons Foundation Class
See Also

This class provides a generic find/findnext buttonset.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _findnextbuttons
Base Class | Container
Class Library | _table.vcx
Parent Class | _findbutton
Sample | ...\Samples\Solution\Ffc\dataqry.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the appropriate values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

When placed on a form or other container, this class locates a record using a Find object based on specified criteria. For details, see Find Button or _findbutton in the _table.vcx class library in the Class Browser.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples
Find Button Foundation Class


Find Button Foundation Class

Visual FoxPro 9.0 Language Reference
Find Button Foundation Class
See Also

This class provides a generic Find button, uses the Find object, and locates a record based on specific criteria.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _findbutton
Base Class | Container
Class Library | _table.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Ffc\dataqry.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the appropriate cFindString, lMatchCase, lSkipMemo, and lWraparound values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
cAlias property | Specifies the data source in which to search. Default: ""
cFindString property | Specifies the string for which to search. Default: ""
LFindAgain | Specifies whether the file is traversed to find successive instances of cFindString. Default: .F.
lMatchCase property | Specifies the case-sensitivity of the search. Default: .F.
lSkipMemos property | Specifies whether to ignore Memo fields in the search. Default: .F.
lWrapAround property | Specifies whether to continue searching from the beginning if the end of file (EOF) is reached. Default: .F.
DoFind method | Performs a search. Syntax: DoFind( ) Return: none Arguments: none
SkipField method | Removes the field, tcSkipField, from the search. Syntax: SkipField( ) Return: none Arguments: tcSkipField specifies the field to ignore during the search.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Find Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
Find Dialog Box Foundation Class
See Also

This class provides a generic Find dialog box with simple options such as field choice. This class uses the Find object.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _finddialog
Base Class | Form
Class Library | _table.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\dataqry.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Create Form or Add to Project. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. When you drop the class on a project or choose Create a new form from the selected class in the shortcut menu, Visual FoxPro displays an Open dialog box so you can specify the name of the form, then creates and opens the form in the Form Designer.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
cAlias property | Specifies the data source in which to search. Default: ""
cFindString property | Specifies the string for which to search. Default: ""
lAdvanced property | Specifies whether to display the advanced options in the dialog box. Default: .F.
lFindAgain | Specifies whether the file is traversed to find successive instances of cFindString. Default: .F.
lMatchCase property | Specifies the case-sensitivity of the search. Default: .F.
lSkipMemos property | Specifies whether to eliminate Memo fields from the search. Default: .F.
lWrapAround property | Specifies whether to continue searching from the beginning if end of file reached. Default: .F.
DOFind method | Prforms a search. Syntax: DoFind( ) Return: none Arguments: none
SkipField method | Removes the field, tcSkipField, from the search. Syntax: SkipField( ) Return: none Arguments: SkipField specifies the field to ignore during the search.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Find Files/Text Foundation Class

Visual FoxPro 9.0 Language Reference
Find Files/Text Foundation Class
See Also

This wrapper class uses the FILER.DLL COM object to search for files. It is a simplified version of the filer form.

Category | File Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _filer
Base Class | Custom
Class Library | _utility.vcx
Parent Class | _custom

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the appropriate cFileExpression, cSearchPath, cSearchText, lIgnoreCase, lSubFolder, and lWholeWords values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
cFileExpression property | Specifies a file skeleton for the search. This expression can include wildcards such as ? and *. Default: ""
cSearchPath property | Specifies the directory in which to begin searching for files. Default: ""
cSearchText property | Specifies the text string to search for within files. Default: ""
lIgnoreCase property | Specifies whether to ignore case during the search. Default: .T.
lPromptDir property | Specifies whether to prompt the user for a search path if none is entered. Default: .T.
lSubFolder property | Specifies whether to search in subfolders for files. Default: .T.
lWholeWords property | Specifies whether to search for whole word matches. Default: .F.
oFiles property | Specifies a collection of files returned by the Find search. Defa ult: .F.
Find method | Searches for files that meet the criteria specified by the properties. Syntax: Find( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Find Object Foundation Class

Visual FoxPro 9.0 Language Reference
Find Object Foundation Class
See Also

This class creates a generic object that locates a record based on specified critereria. The class also provides an optional Find Next method.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _tablefind
Base Class | Custom
Class Library | _table.vcx
Parent Class | _table
Sample | ...\Samples\Solution\Ffc\dataqry.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify appropriate cFindString, lMatchCase, lSkipMemo, lWrapAround values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
cFields property | Specifies the list of fields to search. Default: ""
cFindString property | Specifies the string for which to search. Default: ""
lFindAgain | Specifies whether the file is traversed to find successive instances of cFindString. Default: .F.
lMatchCase property | Specifies whether to use case-sensitivity in the search. Default: .F.
lSkipMemos property | Specifies whether to ignore Memo fields in the search. Default: .F.
lWrapAround property | Specifies whether to continue searching from the beginning if end of file (EOF) is reached. Default: .F.
SkipField method | Removes tcSkipField from the search. Syntax: SkipField( ) Return: none Arguments: tcSkipField specifies the field to ignore during the search.
aMemos [1] property | Internal to the class.
iMemos property | Internal to the class.
cControlCharacter property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Font Combobox Foundation Class

Visual FoxPro 9.0 Language Reference
Font Combobox Foundation Class
See Also

This class is a combobox that lists available fonts when placed on a form. It is also used by the tbrEditing and rtfControls classes of _format.scx.

Category | Text Formatting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Text Formatting
Class | _cbofontname
Base Class | ComboBox
Class Library | _format.vcx
Parent Class | _combobox
Sample | ...\Samples\Solution\Toolbars\format.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places a combobox on the form so you can specify appropriate font values for objects in the active form. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Fontsize Combobox Foundation Class

Visual FoxPro 9.0 Language Reference
Fontsize Combobox Foundation Class
See Also

This class is a combobox that lists available font sizes. It is also used by the tbrEditing and RTFControls classes of _format.scx.

Category | Text Formatting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Text Formatting
Class | _cbofontsize
Base Class | ComboBox
Class Library | _format.vcx
Parent Class | _combobox
Sample | ...\Samples\Solution\Toolbars\format.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places a combobox on the form so you can specify appropriate font size values for objects in the active form. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
nSmallestFont property | For scalable fonts, specifies the smallest allowable fontsize. Default: 8
nLargestFont property | For scalable fonts, specifies the largest allowable fontsize. Default: 48

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Format Toolbar Foundation Class

Visual FoxPro 9.0 Language Reference
Format Toolbar Foundation Class
See Also

This class, when placed on a form, provides a toolbar for applying font formatting to text in the active control.

Category | Text Format
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Text Formatting
Class | _tbrediting
Base Class | Toolbar
Class Library | _format.vcx
Parent Class | _toolbars
Sample | ...\Samples\Solution\Toolbars\format.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Add to Project. When you add the class to a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
nAppliesTo property | Specifies the scope of the formatting. Default: 1

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


FRX to HTML Foundation Class

Visual FoxPro 9.0 Language Reference
FRX to HTML Foundation Class
See Also

This class converts a Visual FoxPro report (.FRX) to HTML.

Category | Internet
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Internet
Class | _frx2html
Base Class | Custom
Class Library | _internet.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\dohtml.scx

Remarks

The class includes properties to control the scope and HTML generation. For more information, see Genhtml.prg.

Note:
In Visual FoxPro 9, Genhtml.prg's FRX processing uses the ReportListener class you have registered with the current Report Output Application to provide HTML output. For more information, refer to ReportListener Foundation Classes.

To use this class, drag the class to a project or form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the cSource, cOutFile, nGenOutput, and lAutonameOutput property values. When you drop the class on a project, you can choose to add the class or create a subclass.

Properties, events, and methods | Description
cOutFile property | Specifies the name of the HTML file to create. Default: ""
cSource property | Specifies the source file from which to generate HTML. Default: ""
nGenOutput property | _GENHTML output options: Default: 20 = Generate output file.
lAutoNameOutput property | Specifies whether _GENHTML should automatically name the output file based on the source. Default: .T.
cScope property | Specifies the scope (for example, NEXT or ALL) for the output. Default: ""
GenHTML method | Generates HTML code by calling the Genhtml.prg program using properties specified in cSource, cOutput, and nGenOutFile. Syntax: GenHTML( ) Return: none Arguments: none

See Also

Reference

Visual FoxPro Foundation Classes A-Z
Genhtml.prg

Concepts

Guidelines for Using Visual FoxPro Foundation Classes

Other Resources

Foundation Class Samples
Report Output Application


FRX Cursor Foundation Class

Visual FoxPro 9.0
FRX Cursor Foundation Class
See Also Example

This class provides methods to translate and manipulate various values in Label (lbx) and Report (frx) files.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\Output Helper Classes
Class | frxCursor
Base Class | Custom
Class Library | _FrxCursor.vcx
Parent Class | Custom

Remarks

This class exposes the algorithms used by ReportOutput.APP, ReportBuilder.APP, and ReportPreview.APP to interpret various printing values and Report (frx) and Label (lbx) table values.

It is primarily useful for developers extending Visual FoxPro reporting functionality. For more information, see Extending Report Functionality in Visual FoxPro.

FrxCursor helps you handle many details of the Report and Label file format that are otherwise obscure and, in many cases, very complex. The topic Understanding and Extending Report Structure will give you important details on this file format.

Important
Many methods of this class use a measurement unit known as a FRU. FRUs are FoxPro report units, specified as 1/10000 inch. This unit is the internal unit used by the Visual FoxPro Report Designer to store layout measurements and position. The methods of FrxCursor help you convert FRUs into units you can use more easily in other environments.

Properties, Events, Methods Description

binStringToInt method

Returns the numeric equivalent of binary data encoded as a string of bytes.

Syntax: binStringToInt(cBytes)

Return: integer

Arguments:

cBytes provides the string of bytes for which the method returns the numeric equivalent. For example:

? oFrxCursor.BinStringToInt("ABC")

* displays 4407873

An example of this method being called can be found in Report Protection Flags.

binToInt method

Converts a string of 1's and 0's into an integer.

Syntax: binToInt(cString)

Return: integer

Arguments:

cString provides the string of 1's and 0's for which the method returns the integer equivalent. For example:

Copy Code
? oFrxCursor.BinToInt(;
   "00000000000000000000000001111011")
* displays 123

charsetToLocale method

Converts a given fontcharset value to a candidate locale Id for use with the STRCONV() function. Parameters: nCharSet

Syntax: charsetToLocale(nCharSet)

Return: integer

Arguments:

nCharSet provides the fontcharset value to be converted.

createBandCursor method

Creates a cursor with alias "bands" from the FRX cursor, containing useful info about the bands in the report.

Syntax: createBandCursor([cFrxAlias]

Return: logical

Arguments:

cFrxalias provides the alias of the open Report table (frx) from which the "bands" cursor data should be derived. If the argument is omitted, the method assumes an alias of "FRX".

createCalcResetOnCursor method

Creates a cursor (alias "reset_on") containing records of information for each option in the Report Designer's Calculation Reset combobox. Refer to the Calculate Tab, Report Control Properties Dialog Box (Report Builder) topic for information on the available values.

Syntax: createCalcResetOnCursor( )

Return: logical

Arguments: none.

createDefaultPrintEnvCursor method

Creates a one-record cursor with the same structure as the FRX, with the default printer environment data loaded into EXPR, TAG, and TAG2 fields.

Syntax: createDefaultPrintEnvCursor( [cFrxAlias

[, cDestAlias ]])

Return: logical

Arguments:

cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived.

cDestAlias provides the alias for the one-record cursor the method creates.

The default aliases are "FRX" and "defPrnEnv."

Note:
The FRX source cursor's structure can have custom fields along with the standard Report table structure, and these fields will be duplicated in the resulting target (defPrnEnv) structure. Refer to Understanding and Extending Report Structure for more information.

createGroupCursor method

Creates a cursor with the alias "groups," derived from the FRX cursor, containing useful info about the report data grouping.

Syntax: createGroupCursor( [cFrxAlias])

Return: logical

Arguments:

cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived.

createObjectCursor method

Creates a cursor with the alias "objects" from the FRX cursor, containing useful info about the layout objects in the report. Calls the createBandCursor method if necessary.

Syntax: createObjectCursor( [cFrxAlias[,cDestAlias [,iOption[,lRuntime]]]])

Return: logical

Arguments:

cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived. The default is "frx".

cDestAlias specifies the destination alias of the cursor which will be created. The default is "objects".

iOption has the following possible values:

iOption = 0 Default value if the argument is not included. Method includes all objects in frx, ignoring grouped items.

iOption = 1 Includes only selected/CURPOS=.T. records in the cursor.

iOption = 2 Includes all objects, showing grouped items as a single group record.

iOption = 3 Provides a breakdown of grouped records. Note that some records included in a group may be marked deleted(). You can use SET DELETED ON to omit these records.

lRuntime specifies that the object cursor should use report run-time values for each object's start band and end band. The default value is .F. which specifies that the band location values are correct as determined by the Report Designer layout engine. The report run-time engine uses different algorithms to determine which band a report layout element starts and ends in.

createVariableCursor method

Creates a cursor with the alias "vars" derived from the FRX cursor, containing useful info about the report variables defined in the report.

Syntax: createVariableCursor( [cFrxAlias])

Return: logical

Arguments: cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived.

fruToPixels method

Returns the size in pixels of a given number of FRUs.

Syntax: fruToPixels(iValue)

Return: numeric (number of Pixels)

Arguments:

iValue is an integer value providing the number of FRUs to be converted to a number of pixels.

getBandFor method

Returns an object representing the start or end band for a given object record. Since an object can span multiple report layout bands, this method provides either the start or end band in which the object is anchored. It uses the vertical offset position of the layout object to determine the correct bands.

Syntax: getBandFor(cUniqueID [,lStart])

Return: band object (the object represents the data in the FRX describing the relevant band)

Arguments:

cUniqueID is the FRX UniqueID value of the object for which you want band information. lStart indicates whether you want the start or end band.

getFruTextHeight method

Returns the height in FRUs of a text string displayed using a font with specified attributes.

Syntax: getFruTextHeight(cText,cTypeFace,iSize[, cStyle])

Return: integer value in FRUs.

Arguments:

cText is the string you want to measure.

cTypeFace is the name of the font.

iSize is the point size of the font.

cStyle provides the styles you want to apply to the string, using the same values you would pass to the GETFONT( ) function. For more information, For more information, see AFONT( ) Function.

getFruTextWidth method

Returns the width in FRUs of a text string displayed using a font with specified attributes.

Syntax: getFruTextWidth(cText,cTypeFace,iSize[, cStyle])

Return: integer value in FRUs.

Arguments:

cText is the string you wish to measure. cTypeFace is the name of the font.

iSize is the point size of the font.

cStyle provides the styles you want to apply to the string, using the same values you would pass to the GETFONT( ) function. For more information, For more information, see AFONT( ) Function

getFrxTimeStamp method

Returns a time stamp for a given date/time, formulated according to the standards used in Visual FoxPro system tables (frx and lbx files, for reports and labels).

Syntax: getFrxTimeStamp([vDateTime]) Return: integer

Arguments:

vDateTime is an optional argument of either Date or DateTime type. If you omit the argument, the method uses the current DATETIME( ) value.

getMetadataDomDoc method

Returns an MSXml.DomDocument object containing the XML report memberdata for the current record in the FRX. If the STYLE field for the current record is empty, this method returns an empty template document of the appropriate XML schema.

Syntax: getMetadataDomDoc( [cFrxAlias])

Return: MSXml.DomDocument object, or NULL if the FRX alias is not USED().

Arguments:

cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived.

getObjectsInBand method

Returns a Collection of UNIQUEID values for each object that is contained by the specified Band.

Syntax: getObjectsInBand( cBandID [,lRecno])

Return: Object of Collection type, holding either UNIQUEID values for the selected layout objects or RECNO() values for the layout objects.

Arguments:

cFrxAlias provides the alias of the open Report table (frx) from which the structure is derived.

lRecno indicates which type of values you want to have in the Collection. If you pass a second parameter of .T., the collection is of FRX Record Numbers rather than the values in the UNIQUEID field.

getReportAttribute method

Returns a given attribute of the report header.

Syntax: getReportAttribute( cAttributeType, [,lAlternate])

Return: a Report attribute based on the argument supplied in the method call.

Arguments:

cAttributeType indicates the type of Report attribute value you want to receive.

The following cAttributeType values are supported (case-insensitive):

"UNITS" Returns an integer value indicating the units, as stored in the Frx.RULER field.

Note:
This argument value can also return an associated string, representing the units, if you include the lAlternate argument with a value of .T.. For example, the following method call results in a return value of "Inches": oFrxCursor.getReportAttribute("UNITS",1)

"MULTICOLUMN" Returns a logical value.

"COLUMNCOUNT" Returns an integer value.

"PROTECTION" Returns a binary character string, which can be parsed to evaluate the different types of Report protection associated with this report on a global level. For more information, see Setting Protection for Reports

getSelectedObjectCount method

Returns the number of currently selected objects (objects with the CURPOS field value set to .T.) in the FRX cursor.

Syntax: getSelectedObjectCount( )

Return: integer.

Arguments: none.

getTargetTypeText method

Returns a description of an FRX object's type, given the type and code values as stored in the FRX OBJTYPE and OBJCODE fields.

Syntax: getTargetTypeText(iType[,iCode])

Return: String.

Arguments:

iType provides the object's OBJTYPE value. If you omit this argument, or if you provide a value that is not one of the known OBJTYPE values, this method returns the string Unknown Target type.

iCode provides the subsidiary OBJCODE value, used for FRX records with more than one type of record using the same OBJTYPE (primarily layout band records).

getTimeStampString method

Converts a Visual FoxPro time stamp into a readable string.

Syntax: getTimeStampString(iDateTimeStamp)

Return: String.

Arguments: iDateTimeStamp is an integer in the format used by Visual FoxPro to store datetime stamps in system files (frx and lbx files, for reports and labels). For example:

Copy Code
? oFrxCursor.GetTimeStampString(819103384)
* displays: 06/18/04 04:52:48 PM

Tip You can also use this method to examine the datetime stamp values in Visual FoxPro class libraries (vcx files).

getUnitValueFromFru method

Returns a given unit value for a given value in FRUs, depending on the units.

Syntax: getUnitValueFromFru(nFruValue, iUnits)

Return: numeric.

Arguments:

nFruValue is a number of FRUs, which may have decimal places.

iUnits is an integer indicating the type of unit for which you want to receive the converted value. This value is determined by the integer values used in a report (frx) or label (lbx) table to specify ruler units. See Understanding and Extending Report Structure for more information.

hasBand method

Returns .T. if the report contains a band of the given type you specify.

Syntax: hasBand(iObjCode)

Return: logical.

Arguments:

iObjCode is an integer indicating the type of optional band for which you are checking.

Tip Use this method to check for band types that do not occur in every report. For example, you can check for the existence of a Group band or a Summary band.

hasDetailHeader method

Returns .T. if the specified detail band record has an associated detail header record.

Syntax: hasDetailHeader(cDetailBandID)

Return: logical.

Arguments:

cDetailBandID is a string matching the Frx.UNIQUEID field value for the detail band you are investigating.

Tip Detail Header and Detail Footer bands are optional. If you receive a .T. value for a Detail band, however, you can be certain that both Detail Header and Detail Footer bands are present; these bands are always paired.

hasProtectionFlag method

Returns .T. if the specified binary data has a specific flag set.

Syntax: hasProtectionFlag(cBytes,iFlag)

Return: logical.

Arguments:

cBytes is a string evaluated by this method as a series of bytes.

iFlag is the bit value representing a type of report protection for which you are checking the report or report layout object.

insertBand method

Inserts a band of a given type into the currently selected work area. This method assumes that a valid FRX cursor is already selected and that its record pointer is located at the correct location for the insert operation.

Syntax: insertBand(iObjCode)

Return: logical.

Arguments:

iObjCode indicates the type of band record you want to insert in the FRX table.

insertDataEnvRecord method

Inserts a data environment object record into an FRX cursor. This method assumes that the record pointer is appropriately located.

Syntax: insertDataEnvRecord(cID,cName,cExpr,cCode)

Return: logical.

Arguments:

cID is the unique ID value for the new record's UniqueID column.

cName is the value for the new record's Name column.

cExpr is a list of name-value pairs to be included in the new record's Expr column.

cCode is the text of method code to be included in the new record's Tag column.

insertDetailBand method

Inserts a Detail band into the currently selected work area. This method assumes that a valid FRX cursor is already selected and that its record pointer is located at the correct location for a Detail band record.

Syntax: insertDetailBand()

Return: logical.

Arguments: none.

insertDetailHeaderFooter method

Inserts a Detail Header and Detail Footer band into an FRX cursor in the currently selected work area. This method assumes that a valid FRX cursor is already selected, and that its record pointer is located on a Detail band record that does not currently have Detail Header and Detail Footer bands.

Syntax: insertDetailHeaderFooterBand()

Return: logical.

Arguments: none.

insertSummaryBand method

Inserts a Summary band into the currently selected work area. This method assumes that a valid FRX cursor is already selected and that that the FRX cursor does not already have a Summary band record.

Syntax: insertSummaryBand(lNewPage, lPageHeader, lPageFooter)

Return: logical.

Arguments:

lNewPage indicates whether the Summary band should start a new page.

If the Summary band starts a new page, lPageHeader indicates whether the Summary page should have a Page Header band and lPageFooter indicates whether the Summary page should have a Page Footer band.

insertTitleBand method

Inserts a Title band into the currently selected work area. This method assumes that a valid FRX cursor is already selected and the FRX does not already have a Title band.

Syntax: insertTitleBand(lNewPage)

Return: logical.

Arguments:

lNewPage indicates whether the Summary band should start a new page.

intToBin method

Converts an integer into a string of 1's and 0's.

Syntax: intToBin(iInteger)

Return: String.

Arguments:

iInteger provides the integer for which the method returns a string of 1's and 0's. For example:

Copy Code
? oFrxCursor.IntToBin(123)
* displays
* 00000000000000000000000001111011

intToBinString method

Returns a binary value encoded as a string of bytes for the integer you specify.

Syntax: intToBinString(iInteger)

Return: String (cBytes).

Arguments:

iInteger provides the integer for which the method returns a string of 1's and 0's. For example:

Copy Code
? oFrxCursor.IntToBinString(4407873)
* displays ABC

An example of this method being called can be found in Report Protection Flags.

pixelsToFru method

Returns the size in FRUs of a given number of pixels.

Syntax: pixelsToFru(iValue)

Return: numeric (number of FRUs)

Arguments:

iValue is an integer value providing the number of pixels to be converted to a number of FRUs.

popPrintEnv method

Restores the printer environment from a previously saved cursor. This method assumes that the previously saved cursor is currently selected.

Syntax: popPrintEnv()

Return: logical.

Arguments: none.

pushPrintEnvToCursor method

Saves the current printer environment to a cursor, which is created by this method.

Syntax: pushPrintEnvToCursor(cSavedInAlias)

Return: logical.

Arguments: cSavedInAlias provides the alias of the cursor you want to create, and to which you want the printer environment saved.

screenDPI property

The DPI of the Report Designer. In VFP9 this is hard coded to 96, regardless of the actual display's DPI.

Default: 96

setColumnCount method

Adds or removes columns (and column header/footer records) from the FRX cursor. This method assumes the FRX cursor is selected.

Syntax: setColumnCount(iColumns)

Return: logical.

Arguments: iColumns sets the number of columns for the report layout.

stripQuotes method

Returns a string with embraced string delimiters removed.

Syntax: stripQuotes(cString)

Return: string.

Arguments: cString is the value from which you want to strip delimiters.

Note:
This method strips delimiting double-quotation marks (") and single-quotation marks (') but does not strip square brackets ([ and ]). It is designed to remove the delimiters that may have been placed in an FRX column's value by the native Report Designer. If square brackets delimit the value, the Report Designer did not add them.

synchObjectPositions method

Resets non-deleted objects in the FRX relative to the start of the band they are in after bands have been resized or repositioned in the layout. This method assumes that FrxCursor's bands and objects cursors have been created, that the currently selected table is a cursor of FRX structure, and that the method does not need to restore the record pointer after processing the records in the cursor.

Syntax: synchObjectPositions()

Return: logical.

Arguments: none.

Example

This example changes the width of a field in a Report table record, to accommodate a different expression in this field.

It uses the FrxCursor.getFruTextWidth() method to determine the correct width for the new contents of the field. Then it uses the FrxCursor.getFrxTimeStamp() method to update the timestamp for this record.
Copy Code
#DEFINE OBJTYPE_FIELD           8
LOCAL iWidth, oFrxCursor
oFrxCursor = NEWOBJECT("FrxCursor", "_FrxCursor")
USE My.FRX
LOCATE FOR objtype = OBJTYPE_FIELD AND ;
           UPPER(ALLTRIM(Expr)) == "DATE()"
IF FOUND()
   iWidth = FrxCursor.getFruTextWidth(TRANSFORM(DATETIME()), ;
                                       fontface,fontsize)
   REPLACE Expr WITH "DATETIME()", ;
           Width WITH iWidth, ;
           Timestamp WITH FrxCursor.getFrxTimeStamp()
ENDIF

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Extending Reports at Design Time


FRX Device Helper Foundation Class

Visual FoxPro 9.0
FRX Device Helper Foundation Class
See Also Example

This class provides methods to read and write printer device information in the Visual FoxPro environment.

Category | System Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\Output Helper Classes
Class | frxDeviceHelper
Base Class | Custom
Class Library | _frxcursor.vcx
Parent Class | Custom

Remarks

This class exposes the algorithms used by ReportOutput.APP, ReportBuilder.APP, and ReportPreview.APP to interpret various printing values and Report (frx) and Label (lbx) table values.

It is primarily useful for developers extending Visual FoxPro reporting functionality. For more information, see Extending Report Functionality in Visual FoxPro.

Properties, Events, Methods Description

ActualX property

Physical width of page in device units.

Default: 0

ActualY property

Physical length of page in device units.

Default: 0

DpiX property

Logical pixels-per-inch in the X dimension.

Default: 0

DpiY property

Logical pixels-per-inch in the Y dimension.

Default: 0

LoadDeviceInfo method

Parses out print device parameters into member properties given specific device information.

Syntax: LoadDeviceInfo([cDriver, cDevice, cDEVMODE])

Return: logical value representing success

Arguments:

cDriver specifies the printer driver , as stored in a Report table (frx) EXPR field.

cDevice specifies the printer name, as stored in a Report table (frx) EXPR field.

cDEVMODE is a string representing a structure that holds additional printer information, as stored in a Report table TAG2 field.

Remarks: If you omit the optional arguments, this method loads information for the current VFP default printer.

LoadFromFrx method

Loads printer device parameters from an FRX cursor header record. Restores current record number and selected workarea afterwards.

Syntax: LoadDeviceInfo([cFrxAlias])

Return: logical value representing success

Arguments:

cFRXAlias holds the alias of a Report table (frx) currently in use in the environment. This method assumes an alias of "FRX" if you omit the optional cFRXAlias argument.

mmX property

Horizontal page size in millimeters.

Default: 0

mmY property

Vertical page size in millimeters.

Default: 0

OffsetX property

Physical printable page left margin.

Default: 0

OffsetY property

Physical printable page top margin.

Default: 0

Orientation property

Page orientation (0=Portrait, 1=Landscape).

Default: 0

PrintableX property

Horizontal page width in pixels.

Default: 0

PrintableY property

Vertical page length in pixels.

Default: 0

ErrorMessage property

Contains error text if the LoadDeviceInfo() method returns false.

Default: ""

Example

In this example, an instance of the frxDeviceHelper class displays information about resolution in dots (pixels) per inch for the current VFP default printer.

Copy Code
oDeviceHelper = NEWOBJECT( "frxDeviceHelper" )
IF oDeviceHelper.LoadDeviceInfo()
    ? oDeviceHelper.DpiX
    ? oDeviceHelper.DpiY
ELSE
    ? oDeviceHelper.ErrorMessage
ENDIF

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus API Wrapper Foundation Classes

Visual FoxPro 9.0
GDI Plus API Wrapper Foundation Classes
See Also

The GDI Plus API Wrapper Foundation class library, _GDIPLUS.vcx, contains a collection of classes that wrap GDI+ Flat API functionality for use in Visual FoxPro. You can use these classes to add GDI+ features to forms and reports.

_GDIPLUS.vcx Class Library

Class | Description
GDI Plus Base Foundation Class | The abstract base class for all other _GDIPLUS classes. Provides some basic utility methods.
GDI Plus Bitmap Foundation Class | Encapsulates a GDI+ bitmap, which consists of the pixel data for a graphics image and its attributes. A Bitmap object is an object used to work with images defined by pixel data.
GDI Plus Brush Foundation Class | The abstract base class for all Brush classes (for example, the gpSolidBrush and gpHatchBrush classes).
GDI Plus Color Foundation Class | Encapsulates a GDI+ color, consisting of 4 positive integers (0..255) for red, green, blue and alpha components.
GDI Plus Font Foundation Class | Defines a particular format for text, including font face, size, and style attributes.
GDI Plus FontFamily Foundation Class | Designates attributes shared by a group of related fonts.
GDI Plus Graphics Foundation Class | Encapsulates a GDI+ drawing surface. Provides methods for drawing on a window or other canvas.
GDI Plus HatchBrush Foundation Class | A brush object which fills with a hatch pattern.
GDI Plus Image Foundation Class | Encapsulates a GDI+ image, and serves as the base class for specific image types (for example, the gpBitmap class).
GDI Plus Object Foundation Class | The abstract base class for all GDI+ objects. Provides management of GDI+ handles and the outcome of GDI+ operations.
GDI Plus Pen Foundation Class | A pen object, which is used to draw lines and curves.
GDI Plus Point Foundation Class | Encapsulates an ordered pair of x- and y-coordinates that defines a point in a two-dimensional plane.
GDI Plus Rectangle Foundation Class | Encapsulates a set of four numbers that represent the location and size of a rectangle.
GDI Plus Size Foundation Class | Stores an ordered pair of numbers, typically the width and height of a rectangle.
GDI Plus SolidBrush Foundation Class | A brush object which fills with a solid color.
GDI Plus StringFormat Foundation Class | Object which encapsulates text layout information (such as alignment and line spacing) and display manipulations (such as ellipsis insertion and national digit substitution).

Remarks

Microsoft Windows GDI+ exposes a flat application programming interface (API) that consists of about 600 functions, which are implemented in Gdiplus.dll and declared in Gdiplusflat.h. These functions are described in the MSDN Library GDI+ Flat API reference topic.

The classes in this Visual FoxPro Library have names that correspond roughly to wrapper classes that perform the same function in the .NET Framework, so you can find additional helpful information and examples by reading material covering the equivalent .NET classes. For example, to learn about gpHatchBrush, you can read about the .NET HatchBrush class.

When you use GDI+ functions, you usually display the results on a target drawing surface, often referred to as a device, or canvas. You specify your target drawing surface by providing the GpGraphics object with a handle previously assigned to this surface, or the means to obtain such a handle. When you are manipulating screen displays, you can create this handle from a window handle, such as a form Window Manipulation Routines. When you are creating report output, you can use the ReportListener's GDIPlusGraphics Property.

See Also

Reference

ReportListener Object

Concepts

Using GDI+ in Reports

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Base Foundation Class

Visual FoxPro 9.0
GDI Plus Base Foundation Class
See Also

The gpBase class is the abstract base class for all other _GDIPLUS classes and provides some basic utility methods.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpBase
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | Custom (Custom Object)

Remarks

The following table lists public properties and methods added by this class to its parent class, Custom.

Properties and methods Description

AllowModalMessages Property

Determines whether the class is allowed to display modal dialog boxes to provide user feedback.

Default INLIST(_VFP.StartMode,0,4)

Remarks: Affects the UI that error handler presents when QuietOnError is false. If AllowModalMessages=.T., then a modal message box is shown and processing stops. If AllowModalMessages=.F., then a WAIT WINDOW ... NOWAIT command is used and processing continues.

AppName Property

Application name for use in user feedback.

Default "GDI+ FFC Library"

ClearErrors Method

Resets the object's error status.

Syntax: THIS.ClearErrors()

Return Values: None

Parameters: None.

Clone Method

Create a new object as an exact copy of an existing object.

Syntax: THIS.Clone()

Return Values: None

Parameters: toClone, required, object to make this object a clone of.

Remarks: This function has no meaning in the GpBase class. It is implemented in most subclasses. For objects that wrap an underlying GDI+ object, the underlying object is cloned as well.

GetErrorStatus Method

Indicates whether an error has occurred.

Syntax: lError = THIS.GetErrorStatus()

Return Values: Logical.

Parameters: None.

Remarks: Returns True (.T.) if an error has occurred since the last call to ClearError().

GetLastErrorMessage Method

Provides information about the last error that occurred.

Syntax: cErrorMessage = THIS.getLastErrorMessage()

Return Values: String. cErrorMessage is the text of the last error to occur.

Parameters: None.

Remarks: The value of cErrorMessage is only valid when GetErrorStatus() returns True (.T.).

GUIDToString Method

Converts GUID or CLSID from binary form to human-readable string representation.

Syntax: cGUIDString = THIS.GUIDToString(tqGUID)

Return Values: String, in standard {abcdefab-cdef–abcd-efab-cdefabcdefab} format. Returns null (.NULL.) if an error occurs.

Parameters:

tqQUID is the GUID or CLSID to be converted.

IgnoreErrors Property

Indicates whether errors should halt processing.

Default .F.

MakeGdipArrayF Method

Converts numeric values in a Visual FoxPro array to a binary string, representing a one- or two-dimensional array of float (single-precision) values, suitable for passing directly to native GDI or GDI+ functions.

Syntax: cArrayString = THIS.MakeGdipArrayF(taArray[, tnCols[, tnFirstCol]])

Return Values: Array represented in a string. Each value takes four bytes. The total length of the string is thus (ALEN(taArray,1) * tnCols*4). Returns null (.NULL.) if an error occurs.

Parameters:

taArray, required, is an array of number values. Must have at least tnCols.

tnCols, optional, is the number of columns to convert. Defaults to the number of values in the array.

tnFirstCol, optional, is the first column number to start the conversion. Defaults to 1.

MakeGdipArrayFFromCursor Method

Converts numeric values in a Visual FoxPro cursor to a binary string, representing a one- or two-dimensional array of float (single-precision) values, suitable for passing directly to native GDI or GDI+ functions.

Syntax: cArrayString = THIS.MakeGdipArrayFFromCursor(tcAlias, tnCols, tcExpr1[, tcExpr2[, tcExpr3[, tcExpr4[, tcExpr5[, tcExpr6[, tcExpr7[, tcExpr8]]]]]]])

Return Values: Array represented in a string. Each value takes four bytes. The total length of the string.is thus (RECCOUNT(tcAlias) * tnCols*4). Returns null (.NULL.) if an error occurs.

Parameters:

tcAlias, required, is the alias of a cursor. Must have at least tnCols fields.

tnCols, required, is the number of columns the array must have. At least tnCols expressions must be specified in the following parameters.

tcExpr1, required, is the expression for the first column (usually a field name).

tcExpr2, required if tnCols is >=2, is the expression for the second column (usually a field name).

tcExpr3, required if tnCols is >=3, is the expression for the third column (usually a field name).

tcExpr4, required if tnCols is >=4, is the expression for the fourth column (usually a field name).

tcExpr5, required if tnCols is >=5 is the expression for the fifth column (usually a field name).

tcExpr6, required if tnCols is >=6 is the expression for the sixth column (usually a field name).

tcExpr7, required if tnCols is >=7 is the expression for the seventh column (usually a field name).

tcExpr8, required if tnCols >= 8 is the expression for the eighth column (usually a field name).

MakeGdipPointF Method

Creates GDI+ PointF structure as string, from separate x,y parameters.

Syntax: cString = MakeGdipPointF(tX, tY)

Return Values: 8-byte string representing two float values. Returns null (.NULL.) on error.

Parameters:

tX, required, numeric, the X coordinate of the point.

tY, required, numeric, the Y coordinate of the point.

MakeGdipRectF Method

Creates GDI+ RectF structure as string, from separate x,y,w,h parameters.

Syntax: cString = MakeGdipRectF(tX, tY, tW, tH)

Return Values: 16-byte string representing four float values. Returns null (.NULL.) on error.

Parameters:

tX, required, numeric, the X coordinate of the point.

tY, required, numeric, the Y coordinate of the point.

tW, required, numeric, the Width value (horizontal dimension).

tH, required, numeric, the Height value (vertical dimension).

MakeGdipSizeF Method

Creates GDI+ SizeF structure as string, from separate x and y parameters.

Syntax: cString = MakeGdipSizeF(tW, tH)

Return Values: 8-byte string representing two float values. Returns null (.NULL.) on error.

Parameters:

tW, required, numeric, the Width value (horizontal dimension).

tH, required, numeric, the Height value (vertical dimension).

ObjFactory Method

Internal function to create _GDIPLUS objects. Used primarily by _GDIPLUS-derived objects' methods that return object values.

Syntax: oObject = ;

THIS.ObjFactory( tcContext, tcClassname [, p1,p2,p3...p10 ] )

Return Values: The created object. Returns null (.NULL.) on error.

Parameters:

tcContext, string, the context of the object creation, usually a value in the form "class.methodname".

tcClassName, string, the name of the class to instantiate. Always one of the base _GDIPLUS classes (such as "gprect").

Remarks: This function along with ObjFactoryHook() can be used to change the classes used by the GDI+ foundation classes. Refer to the GDIPLUS_CLASS_* constants defined in GDIPLUS.H for default values.

ObjFactoryHook Method

Allows modifications to the class that will be created by ObjFactory().

Syntax: THIS.ObjFactoryHook( tcContext, @rcClassName, @rcClassLibrary, @rcModule )

Return Values: none.

Parameters:

tcContext, string, context value passed to ObjFactory().

rcClassName, string, the class that will be created. Assign a value to this parameter to change the class that will be instantiated.

rcClassLibrary, string, the default class library in which the class to be created should be found.

rcModule, string, the module (.app, .dll or .exe file). By default will be an empty string ("").

QuietOnError Property

If True (.T.), causes error messages to be suppressed.

Default NOT INLIST(_VFP.StartMode,0,4)

StringToGUID Method

Converts a human-readable string representation of a GUID or CLSID to binary form.

Syntax: qGUID = THIS.StringToGUID(tcString)

Return Values: qQUID is the GUID or CLSID as a 16-byte varbinary value. Returns null (.NULL.) if an error occurs.

Parameters: tcString is a human-readable GUID or CLSID in standard {abcdefab-cdef–abcd-efab-cdefabcdefab} format.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Bitmap Foundation Class

Visual FoxPro 9.0
GDI Plus Bitmap Foundation Class
See Also

The gpBitmap class encapsulates a GDI+ bitmap, which consists of the pixel data for a graphics image and its attributes. A Bitmap object is an object used to work with images defined by pixel data.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpBitmap
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpImage (GDI Plus Image Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpImage.

Properties and methods Description

Create Method

Creates a bitmap object.

Syntax: ? THIS.Create(tnWidth, tnHeight[, tnPixelFormat])

Return Values: Logical, representing success or failure.

Parameters:

tnWidth, required, width of the new bitmap in pixels.

tnHeight, required, height of the new bitmap in pixels.

tnPixelFormat, optional, one of GDIPLUS_PIXELFORMAT_* constants, defaults to GDIPLUS_PIXELFORMAT_32bppARGB.

Remarks: This method is equivalent to the .NET constructor Bitmap(int, int, PixelFormat).

CreateFromFile Method

Creates a bitmap object by loading from a file.

Syntax: ? THIS.CreateFromFile(tcFileName[, tlUseEmbeddedColorMgmt])

Return Values: Logical, representing success or failure.

Parameters:

tcFileName, required, the name of the file to read.

tlUseEmbeddedColorMgmt, optional, indicates whether the color management info embedded in the file, rather than defaults, should be used for the resulting bitmap object.

Remarks: This method is equivalent to the .NET constructor Bitmap(string,bool). This method will always create a rasterized bitmap even if the source file is in a vector format. To retain the vector format in memory, use the GDI Plus Image Foundation Class (gpImage).

CreateFromGraphics Method

Creates a bitmap object from a graphics object specifying the bitmap's properties.

Syntax: ? THIS.CreateFromGraphics(toGraphics, tnWidth, tnHeight)

Return Values: Logical, representing success or failure.

Parameters:

toGraphics, required, instance of gpGraphics or GDI+ Graphics handle, from which to create the bitmap.

tnWidth, required, width of the new bitmap in pixels.

tnHeight, required, height of the new bitmap in pixels.

Remarks: This method is equivalent to the .NET constructor Bitmap(int, int, Graphics).

The pixel format of the bitmap cannot be set; it will default to GDIPLUS_PIXELFORMAT_32bppARGB.

GetPixel Method

Gets the color value of an individual pixel.

Syntax: nValue = THIS.GetPixel(tX, tY)

Return Values: Integer, ARGB color value of the pixel. Returns null (.NULL.) on failure.

Parameters:

tX, required, integer X-coordinate of pixel to get.

tY, required, integer X-coordinate of pixel to get.

Remarks: This method is equivalent to the .NET Bitmap.GetPixel(int, int).

SetPixel Method

Sets the color value of an individual pixel.

Syntax: THIS.SetPixel( tX, tY, tvColor )

Return Values: Logical, representing success or failure.

Parameters:

tX, required, integer X-coordinate of pixel to get.

tY, required, integer X-coordinate of pixel to get.

tvColor, required, GDI Plus Color Foundation Class object (gpColor) or integer ARGB color value.

Remarks: This method is equivalent to the .NET Bitmap.SetPixel(int, int,Color).

SetResolution Method

Sets the resolution of the Bitmap in dots per inch.

Syntax: THIS.SetResolution( tnDPIx, tnDPIy)

Return Values: Logical, representing success or failure.

Parameters:

tnDPIx, the horizontal resolution, in dots per inch, of the bitmap.

tnDPIy, the vertical resolution, in dots per inch, of the bitmap.

Remarks: This method is equivalent to the .NET Bitmap.SetResolution(float,float).

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Brush Foundation Class

Visual FoxPro 9.0
GDI Plus Brush Foundation Class
See Also

The gpBrush class is the abstract base class for all brush classes (for example, the gpSolidBrush and gpHatchBrush classes).

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpBrush
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpObject (GDI Plus Object Foundation Class)

Remarks

This class adds no new properties or methods to the set exposed by its parent, gpObject. It implements the Clone method.

Properties and methods | Description
Clone Method | Clones a brush object. A new GDI+ brush object is created of the same type and with the same property values as the source object. Syntax: ? THIS.Clone(toBrush) Return Values: Logical, representing success or failure. Parameters: toBrush, required, the brush object to clone.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Color Foundation Class

Visual FoxPro 9.0
GDI Plus Color Foundation Class
See Also

The gpColor class encapsulates a GDI+ color, consisting of 4 positive integers (each ranging from 0 to 255) for red, green, blue and alpha components.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpColor
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpBase (GDI Plus Base Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpBase. It also implements the Clone and Init methods.

Values listed as ARGB type in the table are composite colors represented in GDI+ native format. Bits 24-31 of these values hold the color's alpha component, bits 16-23 hold the red component, bits 8-15 hold green, and bits 0-7 hold blue.

Properties and methods Description

Alpha Property

Alpha (transparency) component of a color, with legal values ranging from 0 to 255.

Default: 0

Remarks: The value 0 represents complete transparency and the value 255 represents complete opacity.

ARGB Property

Color in native GDI+ (alpha,red,green,blue) format. The underlying GDI+ representation is a 32-bit signed integer, so legal values range from -2^31 to (2^31-1).

Default: 0

Blue Property

Blue component of a color, with legal values ranging from 0 to 255.

Default: 0

Clone Method

Clones a color object.

Syntax: ? THIS.Clone(toColor)

Return Values: Logical, representing success or failure.

Parameters:

toColor, required, the gpColor object to clone.

FoxRGB Property

Color in Visual FoxPro RGB format, opaque with bits 0-7 representing red, bits 8-15 representing green, and bits 16-23 representing blue.

Default: 0

Green Property

Green component of a color, with legal values ranging from 0 to 255.

Default: 0

Init Method

Constructs a color value during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpColor"[, tnRedOrARGB[, tnGreen[, tnBlue[, tnAlpha]]]])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tnRedOrARGB, required if immediate initialization of the color value is requested. An integer representing either the red component of the color value or the full ARGB-type composite color value.

tnGreen, optional, an integer representing the green component of the color value.

tnBlue, optional, an integer representing the blue component of the color value.

tnAlpha, optional, an integer representing the alpha component of the color value. The default is 255, or completely opaque.

Red Property

Red component of a color, with legal values ranging from 0 to 255.

Default: 0

Set Method

Set a color value using separate Red,Green,Blue, and Alpha components.

Syntax: THIS.Set(tnRed, tnGreen, tnBlue[, tnAlpha])

Return Values: None.

Parameters:

tnRed, required, an integer representing the red component of the color value.

tnGreen, required, an integer representing the green component of the color value.

tnBlue, required, an integer representing the blue component of the color value.

tnAlpha, optional, an integer representing the alpha component of the color value. The default is 255, or completely opaque.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Font Foundation Class

Visual FoxPro 9.0
GDI Plus Font Foundation Class
See Also

The gpFont class defines a particular format for text, including font face, size, and style attributes.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpFont
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpObject (GDI Plus Object Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpObject. It also implements the Clone and Init methods.

Values listed as em height in the table are equivalent to cell ascent (height of the font above the line) + cell descent (height of the font below the line) - internal leading of the font. Values listed as line spacing are equal to cell ascent + cell descent + external leading.

Properties and methods Description

Clone Method

Clones a font object.

Syntax: ? THIS.Clone(toFont)

Return Values: Logical, representing success or failure.

Parameters:

toFont, required, the gpFont object to clone.

Create Method

Creates a font object from a specified set of font attributes.

Syntax: ? THIS.Create(tvFontNameOrFamily, [tnSize [, tnStyle[, tnUnits]]])

Return Values: Logical, representing success or failure.

Parameters:

tvFontNameOrFamily, required, a gpFontFamily object or a string representing the name of a font.

tnSize, required, size in specified units.

tnStyle, optional, fontstyle attributes as specified in GDIPLUS_FontStyle_* constants. Default value is GDIPLUS_FontStyle_Regular.

tnUnits, optional, units for font size as specified in GDIPLUS_Unit_* constants. Default value is GDIPLUS_Unit_Point.

FontName Property

Font name, for example "Arial".

Default: Empty.

GetHeight Method

Get line spacing for a font for a given graphics object, using the units of that graphics object.

Syntax: nHeight = THIS.GetHeight(tvGraphics)

Return Values: Number, line-height. Returns null (.NULL.) on error.

Parameters:

tvGraphics, required, a gpGraphics object or a GDI+ graphics handle.

GetHeightGivenDPI Method

Get line spacing for a font given a value in dots per inch (DPI).

Syntax: nHeight = THIS.GetHeightGivenDPI(tnDPI)

Return Values: Number, line-height. Returns null (.NULL.) on error.

Parameters:

tnDPI, required, a number of dots per inch.

Init Method

Constructs a font object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpFont", tvFontNameOrFamily, [tnSize [, tnStyle[, tnUnits]]])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tvFontNameOrFamily, required if immediate creation of the object is requested. A gpFontFamily object or a string representing the name of a font.

tnSize, required, size in specified units.

tnStyle, optional, fontstyle attributes as specified in GDIPLUS_FontStyle_* constants. Default value is GDIPLUS_FontStyle_Regular.

tnUnits, optional, units for font size as specified in GDIPLUS_Unit_* constants. Default value is GDIPLUS_Unit_Point.

Size Property

The em size of the font using the units of this font object.

Default: Empty.

Style Property

Style information for this font object, using GDIPLUS_FontStyle_* constant values.

Default: Empty.

Unit Property

The unit of measure used by this font, using GDIPLUS_Unit_* constant values.

Default: Empty.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus FontFamily Foundation Class

Visual FoxPro 9.0
GDI Plus FontFamily Foundation Class
See Also

The gpFontFamily class designates attributes shared by a group of related fonts.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpFontFamily
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpObject (GDI Plus Object Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpObject. It also implements the Clone and Init methods.

Values listed as em height in the table are equivalent to cell ascent (height of the font above the line) + cell descent (height of the font below the line) - internal leading of the font. Values listed as line spacing are equal to cell ascent + cell descent + external leading.

Properties and methods Description

Clone Method

Clones a font family object.

Syntax: ? THIS.Clone(toFontFamily)

Return Values: Logical, representing success or failure.

Parameters:

toFontFamily, required, the gpFontFamily object to clone.

Create Method

Creates a font family object from a specified name.

Syntax: ? THIS.Create(tcName)

Return Values: Logical, representing success or failure.

Parameters:

tcName, required, the name of the font family.

FontName Property

Font family name, such as "Arial."

Default: Empty.

gdipFontCollectionHandle Property

Handle to GDI+ FontCollection object.

Default: 0.

Remarks: This class does not manage this handle at all, it merely uses it.

GetCellAscent Method

Provides cell ascent in design units of this font family in the specified style.

Syntax: nAscent =THIS.GetCellAscent([tnStyle])

Return Values: Number. Returns null (.NULL.) on failure.

Parameters:

tnStyle, optional, font style as specified in GDIPLUS_FontStyle_* constants. Default value is GDIPLUS_FontStyle_Regular.

GetCellDescent Method

Provides cell descent in design units of this font family in the specified style.

Syntax: nDescent =THIS.GetCellDescent([tnStyle])

Return Values: Number. Returns null (.NULL.) on failure.

Parameters:

tnStyle, optional, font style as specified in GDIPLUS_FontStyle_* constants. Default value is GDIPLUS_FontStyle_Regular.

GetEmHeight Method

Provides em height in design units of this font family in the specified style.

Syntax: nHeight =THIS.GetEmHeight([tnStyle])

Return Values: Number. Returns null (.NULL.) on failure.

Parameters:

tnStyle, optional, font style as specified in GDIPLUS_FontStyle_* constants. Default value is GDIPLUS_FontStyle_Regular.

GetGenericMonospace Method

Provides a generic monospace font family object.

Syntax: THIS.GetGenericMonospace()

Return Values: Logical, representing success or failure.

Parameters: None.

Remarks: Upon successful return from this method, the object represents a system standard font family, and all properties become read-only.

GetGenericSansSerif Method

Provides a generic sans serif font family object.

Syntax: THIS.GetGenericSansSerif()

Return Values: Logical, representing success or failure.

Parameters: None.

Remarks: Upon successful return from this method, the object represents a system standard font family, and all properties become read-only.

GetGenericSerif Method

Provides a generic serif font family object.

Syntax: THIS.GetGenericSerif()

Return Values: Logical, representing success or failure.

Parameters: None.

Remarks: Upon successful return from this method, the object represents a system standard font family, and all properties become read-only.

GetLineSpacing Method

Provides line spacing in design units of this font family in the specified style.

Syntax: nHeight =THIS.GetEmHeight([tnStyle])

Return Values: Number. Returns null (.NULL.) on failure.

Parameters:

tnStyle, optional, font style as specified in GDIPLUS_FontStyle_* constants. Default value is GDIPLUS_FontStyle_Regular.

GetName Method

Provides the name of this font family in the specified language.

Syntax: cName =THIS.GetName([tnLanguageID])

Return Values: String. Returns null (.NULL.) on failure.

Parameters:

tnLanguage, optional, Language Identifier. Default value is 0.

Init Method

Constructs a font family object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpFontFamily", tcFontFamilyName)

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tcFontFamilyName, required if immediate creation of the object is requested. A string representing the name of a font family.

IsStyleAvailable Method

Tests whether a requested font style can be natively provided in this font family.

Syntax: ? THIS.IsStyleAvailable(tnStyle)

Return Values: Logical.

Parameters:

tnStyle, required, font style as specified in GDIPLUS_FontStyle_* constants. Default value is GDIPLUS_FontStyle_Regular.

Remarks: Although technically correct, a False (.F.) return value from this function can be misleading. Windows can usually synthesize font styles when the specific style for a font is not available.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Graphics Foundation Class

Visual FoxPro 9.0
GDI Plus Graphics Foundation Class
See Also

The gpGraphics class encapsulates a GDI+ drawing surface. It provides methods for drawing on a window or other canvas.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpGraphics
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpObject (GDI Plus Object Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpObject.

Properties and methods Description

Clear Method

Clears entire drawing surface and fills with specified background color.

Syntax: THIS.Clear(tvColor)

Return Values: Logical, representing success or failure.

Parameters:

tvColor, required, a GDI Plus Color Foundation Class or ARGB color value.

ClipBounds Property

A clipping region represented as a GDI Plus Rectangle Foundation Class. Read-only.

Default: Empty.

Remarks: If the clipping region is infinite, this member returns a meaningless large rectangle. See VisibleClipBounds Property.

CompositingMode Property

Specifies how composited images are drawn to this graphics object with possible values indicated by GDIPLUS_CompositingMode_* constants. Read-write.

Default: Empty.

CompositingQuality Property

Specifies the rendering quality of composited images drawn to this graphics object with possible values indicated by GDIPLUS_CompositingQuality_* constants.

Default: Empty.

CreateFromHDC Method

Creates a graphics object for a given device context (HDC).

Syntax: THIS.CreateFromHDC(hDC)

Return Values: Logical, representing success or failure.

Parameters:

hDC, required, numeric, Windows Device Context handle.

CreateFromHWND Method

Creates a graphics object for a given window (HWND).

Syntax: THIS.CreateFromHWND(hWND[, tlICM])

Return Values: Logical, representing success or failure.

Parameters:

hWND, required, numeric, represents a handle to a window.

tlICM, optional, indicates whether to use image color management.

CreateFromImage Method

Creates a graphics object from the specified gpImage object, so you can draw on that image's surface.

Syntax: THIS.CreateFromImage(toImage)

Return Values: Logical, representing success or failure.

Parameters:

toImage, required, a gpImage object.

DpiX Property

Specifies the horizontal resolution of drawing surface in dots per inch. Read-only.

Default: Empty.

DpiY Property

Specifies the vertical resolution of drawing surface in dots per inch. Read-only.

Default: Empty.

DrawArc Method

Draws an arc representing a portion of an ellipse, given the bounding rectangle of the ellipse, start, and sweep angles.

Syntax: THIS.DrawArc(toPen,tX,tY,tnW, tnH, tnStart, tnSweep)

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

tnX, numeric, X-coordinate of top-left corner of bounding rectangle.

tnY, numeric, Y-coordinate of top-left corner of bounding rectangle.

tnW, numeric, width of bounding rectangle.

tnH, numeric, height of bounding rectangle.

tnStart, numeric, starting angle specified in degrees.

tnSweep, numeric, sweep angle specified in degrees.

DrawBezier Method

Draws a Bézier spline from four control points.

Syntax: THIS.DrawBezier(toPen,tX1,tY1, tX2,tY2, tX3,tY3, tX4,tY4)

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

tx1, numeric, X-coordinate of 1st control point.

ty1, numeric, Y-coordinate of 1st control point.

tx2, numeric, X-coordinate of 2nd control point.

ty2, numeric, Y-coordinate of 2nd control point.

tx3, numeric, X-coordinate of 3rd control point.

ty3, numeric, Y-coordinate of 3rd control point.

tx4, numeric, X-coordinate of 4th control point.

ty4, numeric, Y-coordinate of 4th control point.

DrawBeziers Method

Draws a series of Bézier splines, given a Visual FoxPro array of points.

Syntax: THIS.DrawBeziers(toPen, taPoints[, tnFirstCol])

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

taPoints, required, array containing coordinates of the end points. The array has one row for each point, and must have at least two columns, with taArray[i, tnFirstCol] containing the X-coordinate and taArray[i,tnFirstCol+1] containing the Y-coordinate.

tnFirstCol, optional, integer column index of the X-coordinate. Defaults to 1.

DrawBeziersFromCursor Method

Draws a series of Bézier splines, given a set of points defined in a Visual FoxPro cursor.

Syntax: ? THIS.DrawBeziersFromCursor(toPen, tcAlias, tcExprX, tcExprY)

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

tcAlias, required, alias of cursor containing coordinates of the points, one row for each point.

tcExprX, required, string, expression to evaluate for X-coordinate (must evaluate to numeric).

tcExprY, required, string, expression to evaluate for Y-coordinate (must evaluate to numeric).

DrawClosedCurve Method

Draws a closed curve through a set of points defined in a Visual FoxPro array.

Syntax: THIS.DrawClosedCurve(toPen, taPoints[, tnFirstCol])

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to draw with.

taPoints, required, array containing coordinates of the points. The array has one row for each point, and must have at least two columns, with taArray[i, tnFirstCol] containing the X-coordinate and taArray[i,tnFirstCol+1] containing the Y-coordinate.

tnFirstCol, optional. Integer column index of the X-coordinate. Defaults to 1.

DrawClosedCurveFromCursor Method

Draws a closed curve through a set of points defined in a Visual FoxPro cursor.

Syntax: THIS.DrawClosedCurveFromCursor(toPen, tcAlias, tcExprX, tcExprY)

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

tcAlias, required, alias of cursor containing coordinates of the points, one row for each point.

tcExprX, required, string, expression to evaluate for X-coordinate (must evaluate to numeric).

tcExprY, required, string, expression to evaluate for Y-coordinate (must evaluate to numeric).

DrawCurve Method

Draws a curve through a set of points defined in a Visual FoxPro array.

Syntax: THIS.DrawCurve(toPen, taPoints[, tnFirstCol])

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to draw with.

taPoints, required, Array containing coordinates of the points. The array has one row for each point, and must have at least two columns, with taArray[i, tnFirstCol] containing the X-coordinate and taArray[i,tnFirstCol+1] containing the Y-coordinate.

tnFirstCol, optional. Integer column index of the X-coordinate. Defaults to 1.

DrawCurveFromCursor Method

Draws a curve through a set of points defined in a Visual FoxPro cursor.

Syntax: THIS.DrawCurveFromCursor(toPen, tcAlias, tcExprX, tcExprY)

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

tcAlias, required, alias of cursor containing coordinates of the points, one row for each point.

tcExprX, required, string, expression to evaluate for X-coordinate (must evaluate to numeric).

tcExprY, required, string, expression to evaluate for Y-coordinate (must evaluate to numeric).

DrawEllipse Method

Draws an outlined ellipse specified by its bounding rectangle.

Syntax: THIS.DrawEllipse(toPen, tXOrRectangle[,tnY,tnW,tnH])

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

tXOrRectangle, either a gpRectangle object specifying bounding rectangle or a numeric value specifying the X-coordinate of top-left corner of bounding rectangle

tnY, numeric, Y-coordinate of top-left corner of bounding rectangle. Required if tXorRectangle is numeric.

tnW, numeric, width of bounding rectangle. Required if tXorRectangle is numeric.

tnH, numeric, height of bounding rectangle. Required if tXorRectangle is numeric.

DrawImageAt Method

Draws image at the specified location, using its original physical size.

Syntax: THIS.DrawImageAt(toImage, destPointOrX[,destY])

Return Values: Logical, representing success or failure.

Parameters:

toImage, required, the gpImage object (or an instance of a class derived from gpImage) to draw.

destPointOrX, either a gpPoint object indicating the point at which to draw image, or numeric value, the X-coordinate of location to draw image.

destY, numeric, Y-coordinate of location to draw image. Required if tPointOrX is numeric.

DrawImagePortionAt Method

Draws portion of an image at the specified location, using its original size.

Syntax: THIS.DrawImagePortionAt(toImage, destPoint,srcRectangle[, srcUnit])

Return Values: Logical, representing success or failure.

Parameters:

toImage, required, the gpImage object (or an instance of a class derived from gpImage) to draw.

destPoint, required, a gpPoint object specifying destination location.

srcRectangle, required, a gpRectangle object specifying the portion of image to draw.

srcUnit, optional, the unit of measure for the source image, as defined in GDIPLUS_Unit_* constants.

DrawImagePortionScaled Method

Draws portion of an image at the specified location and with the specified size.

Syntax: THIS.DrawImagePortionScaled(toImage, destRectangle,srcRectangle[, srcUnit[, imageAttribs]])

Return Values: Logical, representing success or failure.

Parameters:

toImage, required, the gpImage object (or an instance of a class derived from gpImage) to draw.

destRectangle, required, a gpRectangle object specifying destination location.

srcRectangle, required, a gpRectangle object specifying the portion of image to draw.

srcUnit, optional, the unit of measure for the source image, as defined in GDIPLUS_Unit_* constants.

imageAttribs, optional, an integer GDI+ handle for a GDI+ ImageAttributes object, or an instance of gpObject providing a wrapper for a GDI+ ImageAttributes object.

DrawImageScaled Method

Draws image at the specified location with the specified size.

Syntax: THIS.DrawImageScaled(toImage, destRectangleOrX, destY,destW,destH)

Return Values: Logical, representing success or failure.

Parameters:

toImage, required, the gpImage object (or an instance of a class derived from gpImage) to draw.

destRectangleOrX, required, either a gpRectangle object specifying the destination location or a numeric value, the X-coordinate of the destination location.

destY, numeric, Y-coordinate of location to draw image. Required if destRectangleOrX is numeric.

destW, numeric, desired width of image to be drawn. Required if destRectangleOrX is numeric.

destH, numeric, desired height of image to be drawn. Required if destRectangleOrX is numeric.

DrawLine Method

Draws a line between two points, in the specified pen.

Syntax: THIS.DrawLine(toPen, x1,y1,x2,y2)

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

x1, required, numeric, X-coordinate of start point.

y1, required, numeric, Y-coordinate of start point.

x2, required, numeric, X-coordinate of end point.

y2, required, numeric, Y-coordinate of end point.

DrawLines Method

Draws a sequence of connected lines, given the endpoints of each line in a Visual FoxPro array.

Syntax: THIS.DrawLines( toPen, taPoints [, tnFirstCol ] )

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

taPoints, required, an array containing coordinates of the end points. The array has one row for each point, and must have at least two columns, with taArray[i, tnFirstCol] containing the X-coordinate and taArray[i,tnFirstCol+1] containing the Y-coordinate.

tnFirstCol, optional, an integer column index of the X-coordinate. Defaults to 1.

DrawLinesFromCursor Method

Draws a sequence of connected lines, given the endpoints of each line in a Visual FoxPro cursor.

Syntax: THIS.DrawLinesFromCursor(toPen, tcAlias, tcExprX, tcExprY)

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

tcAlias, required, alias of cursor containing coordinates of the end points, one row for each point.

tcExprX, required, string, expression to evaluate for X-coordinate (must evaluate to numeric).

tcExprY, required, string, expression to evaluate for Y-coordinate (must evaluate to numeric).

DrawPie Method

Draws the outline of a pie slice.

Syntax: THIS.DrawPie(toPen, tXOrRectangle,tnYOrStart,tnWOrSweep,tnH[, tnStart, tnSweep])

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, the gpPen to use.

toXOrRectangle, a gpRectangle object specifying bounding rectangle or a numeric value specifying the X-coordinate of top-left corner of the bounding rectangle.

tnYOrStart, a numeric value, the Y-coordinate of top-left corner of bounding rectangle, if toXOrRectangle is numeric or the starting angle specified in degrees, if toXOrRectangle is a gpRectangle object.

tnWOrSweep, a numeric value, the width of the bounding rectangle, if toXOrRectangle is numeric, or the sweep angle specified in degrees, if toXOrRectangle is a gpRectangle object.

tnH, numeric, the height of bounding rectangle, when toXOrRectangle is numeric.

tnStart, numeric, the starting angle specified in degrees, when toXOrRectangle is numeric.

tnSweep, numeric, the sweep angle specified in degrees, when toXOrRectangle is numeric.

DrawPolygon Method

Draws a polygon defined by a set of points as specified in a Visual FoxPro array.

Syntax: THIS.DrawPolygon(toPen, taPoints[, tnFirstCol])

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, the gpPen to use.

taPoints, required, an array containing coordinates of the points. The array has one row for each point, and must have at least two columns, with taArray[i, tnFirstCol] containing the X-coordinate and taArray[i,tnFirstCol+1] containing the Y-coordinate.

tnFirstCol, optional, the integer column index of the X-coordinate. Defaults to 1.

DrawPolygonFromCursor Method

Draws a polygon defined by a set of points provided in a VisualFoxPro cursor.

Syntax: THIS.DrawPolygonFromCursor(toPen, tcAlias, tcExprX, tcExprY

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

tcAlias, required, alias of cursor containing coordinates of the points, one row for each point.

tcExprX, required, string, expression to evaluate for X-coordinate (must evaluate to numeric).

tcExprY, required, string, expression to evaluate for Y-coordinate (must evaluate to numeric).

DrawRectangle Method

Draw an outlined rectangle, defined either by a gpRectangle object, or by separate coordinate and dimension parameters.

Syntax: THIS.DrawRectangle(toPen, tXOrRectangle[,tnY,tnW,tnH])

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

tXOrRectangle, either a gpRectangle object specifying bounding rectangle or a numeric value specifying the X-coordinate of top-left corner of bounding rectangle

tnY, numeric, Y-coordinate of top-left corner of bounding rectangle. Required if tXorRectangle is numeric.

tnW, numeric, width of bounding rectangle. Required if tXorRectangle is numeric.

tnH, numeric, height of bounding rectangle. Required if tXorRectangle is numeric.

Remarks: All coordinates are in the current units of the gpGraphics object; see the PageUnit property entry.

DrawRectangles Method

Draws a set of outlined rectangles, given coordinates in a Visual FoxPro array.

Syntax: THIS.DrawRectangles(toPen, taRects[, tnFirstCol])

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, the gpPen to use.

taRects, required, an array containing coordinates of the points defining rectangles. The array has one row for each rectangle, and must have at least two columns, with taArray[i, tnFirstCol] containing the X-coordinate, taArray[i,tnFirstCol+1] containing the Y-coordinate, aArray[i, tnFirstCol+2] containing the width, and taArray[i,tnFirstCol+3] containing the height.

tnFirstCol, optional, the integer column index of the X-coordinate. Defaults to 1.

DrawRectanglesFromCursor Method

Draws a set of outlined rectangles, given coordinates in a Visual FoxPro cursor.

Syntax: THIS.DrawRectanglesFromCursor(toPen, tcAlias, tcExprX, tcExprY, tcExprW, tcExprH)

Return Values: Logical, representing success or failure.

Parameters:

toPen, required, gpPen to use.

tcAlias, required, alias of cursor containing coordinates of the points, one row for each rectangle.

tcExprX, required, string, expression to evaluate for X-coordinate (must evaluate to numeric).

tcExprY, required, string, expression to evaluate for Y-coordinate (must evaluate to numeric).

tcExprW, required, string, expression to evaluate for width (must evaluate to numeric).

tcExprH, required, string, expression to evaluate for height (must evaluate to numeric).

DrawStringA Method

Draws a string in specified font and position (ANSI version).

Syntax: THIS.DrawStringA( tcAnsiString, [toFont],tvRectPoint,[toStringFormat],[toBrush])

Return Values: Logical, representing success or failure.

Parameters:

tcAnsiString, required, the ANSI string to draw.

toFont, optional, a gpFont object specifying the font to use.

tvRectPoint, required, a gpRect object specifying the bounding rectangle, or a gpPoint object specifying the top left corner.

toStringFormat, optional, a gpStringFormat object.

toBrush, optional, a gpBrush object to use when drawing the text.

DrawStringW Method

Draws a string in specified font and position (Unicode Version)

Syntax: THIS.DrawStringW( tcUnicodeString,[toFont],tvRectPoint,[toStringFormat],[toBrush])

Return Values: Logical, representing success or failure.

Parameters:

tcUnicodeString, required, the Unicode string to draw.

toFont, optional, a gpFont object specifying the font to use.

tvRectPoint, required, a gpRect object specifying the bounding rectangle, or a gpPoint object specifying the top left corner.

toStringFormat, optional, a gpStringFormat object.

toBrush, optional, a gpBrush object to use when drawing the text.

FillClosedCurve Method

Fills a closed curve defined by a set of points in a Visual FoxPro array.

Syntax: ? THIS.FillClosedCurve(toBrush, taPoints[, tnFirstCol[, tnFillMode]])

Return Values: Logical, representing success or failure.

Parameters:

toBrush, required, the gpBrush to use.

taPoints, required, array containing coordinates of the end points. The array has one row for each point, and must have at least two columns, with taArray[i, tnFirstCol] containing the X-coordinate and taArray[i,tnFirstCol+1] containing the Y-coordinate.

tnFirstCol, optional, integer column index of the X-coordinate. Defaults to 1.

tnFillMode, optional, the fill mode as defined by the GDIPLUS_FillMode_* constants. Default value is GDIPLUS_FillMode_Alternate.

FillClosedCurveFromCursor Method

Fills a closed curve as defined by a set of points in a Visual FoxPro cursor.

Syntax: THIS.FillClosedCurveFromCursor(toBrush, tcAlias, tcExprX, tcExprY[, tnFillMode])

Return Values: Logical, representing success or failure.

Parameters:

toBrush, required, gpBrush to use.

tcAlias, required, alias of cursor containing coordinates of the points, one row for each point.

tcExprX, required, string, expression to evaluate for X-coordinate (must evaluate to numeric).

tcExprY, required, string, expression to evaluate for Y-coordinate (must evaluate to numeric).

tnFillMode, optional, the fill mode as defined by the GDIPLUS_FillMode_* constants. Default value is GDIPLUS_FillMode_Alternate.

FillEllipse Method

Draws a filled ellipse specified by its bounding rectangle.

Syntax: ? THIS.FillEllipse(toBrush, tXOrRectangle[,tnY,tnW,tnH])

Return Values: Logical, representing success or failure.

Parameters:

toBrush, required, gpBrush to use.

tXOrRectangle, either a gpRectangle object specifying bounding rectangle or a numeric value specifying the X-coordinate of top-left corner of bounding rectangle

tnY, numeric, Y-coordinate of top-left corner of bounding rectangle. Required if tXorRectangle is numeric.

tnW, numeric, width of bounding rectangle. Required if tXorRectangle is numeric.

tnH, numeric, height of bounding rectangle. Required if tXorRectangle is numeric.

FillPie Method

Draws a filled pie slice.

Syntax: ? THIS.FillPie(toBrush, tXOrRect,tnYOrStart,tnWOrSweep,tnH[, tnStart, tnSweep])

Return Values: Logical, representing success or failure.

Parameters:

toBrush, required, the gpBrush to use.

toXOrRectangle, a gpRectangle object specifying bounding rectangle or a numeric value specifying the X-coordinate of top-left corner of the bounding rectangle.

tnYOrStart, a numeric value, the Y-coordinate of top-left corner of bounding rectangle, if toXOrRectangle is numeric, or the starting angle specified in degrees, if toXOrRectangle is a gpRectangle object.

tnWOrSweep, a numeric value, the width of the bounding rectangle, if toXOrRectangle is numeric, or the sweep angle specified in degrees, if toXOrRectangle is a gpRectangle object.

tnH, numeric, the height of bounding rectangle, when toXOrRectangle is numeric.

tnStart, numeric, the starting angle specified in degrees, when toXOrRectangle is numeric.

tnSweep, numeric, the sweep angle specified in degrees, when toXOrRectangle is numeric.

FillPolygon Method

Fills a polygon defined by a set of points in a Visual FoxPro array.

Syntax: THIS.FillPolygon(toBrush, taPoints[, tnFirstCol[, tnFillMode]])

Return Values: Logical, representing success or failure.

Parameters:

toBrush, required, the gpBrush to use.

taPoints, required, an array containing coordinates of the points. The array has one row for each point, and must have at least two columns, with taArray[i, tnFirstCol] containing the X-coordinate and taArray[i,tnFirstCol+1] containing the Y-coordinate.

tnFirstCol, optional, the integer column index of the X-coordinate. Defaults to 1.

tnFillMode, optional, the fill mode as defined by the GDIPLUS_FillMode_* constants. Default value is GDIPLUS_FillMode_Alternate.

FillPolygonFromCursor Method

Fills a polygon defined by a set of points in a Visual FoxPro cursor.

Syntax: THIS.FillPolygonFromCursor(toBrush, tcAlias, tcExprX, tcExprY[, tnFillMode])

Return Values: Logical, representing success or failure.

Parameters:

toBrush, required, gpBrush to use.

tcAlias, required, alias of cursor containing coordinates of the points, one row for each point.

tcExprX, required, string, expression to evaluate for X-coordinate (must evaluate to numeric).

tcExprY, required, string, expression to evaluate for Y-coordinate (must evaluate to numeric).

tnFillMode, optional, the fill mode as defined by the GDIPLUS_FillMode_* constants. Default value is GDIPLUS_FillMode_Alternate.

FillRectangle Method

Fills a rectangle, defined either by a gpRectangle object, or by separate coordinates and dimension parameters.

Syntax: THIS.FillRectangle(toBrush, tXOrRect[,tnY,tnW,tnH])

Return Values: Logical, representing success or failure.

toBrush, required, gpBrush to use.

tXOrRectangle, either a gpRectangle object specifying bounding rectangle or a numeric value specifying the X-coordinate of top-left corner of bounding rectangle

tnY, numeric, Y-coordinate of top-left corner of bounding rectangle. Required if tXorRectangle is numeric.

tnW, numeric, width of bounding rectangle. Required if tXorRectangle is numeric.

tnH, numeric, height of bounding rectangle. Required if tXorRectangle is numeric.

FillRectangles Method

Fills a set of rectangles defined by coordinates in a Visual FoxPro array.

Syntax: THIS.FillRectangles(toBrush, taRects[, tnFirstCol])

Return Values: Logical, representing success or failure.

Parameters:

toBrush, required, the gpBrush to use.

taRects, required, an array containing coordinates of points defining the rectangles. The array has one row for each rectangle, and must have at least two columns, with taArray[i, tnFirstCol] containing the X-coordinate, taArray[i,tnFirstCol+1] containing the Y-coordinate, aArray[i, tnFirstCol+2] containing the width, and taArray[i,tnFirstCol+3] containing the height.

tnFirstCol, optional, the integer column index of the X-coordinate. Defaults to 1.

FillRectanglesFromCursor Method

Fills a set of rectangles defined in a Visual FoxPro cursor.

Syntax: THIS.FillRectanglesFromCursor(toBrush, tcAlias, tcExprX, tcExprY, tcExprW, tcExprH)

Return Values: Logical, representing success or failure.

Parameters:

toBrush, required, gpBrush to use.

tcAlias, required, alias of cursor containing coordinates of the points, one row for each rectangle.

tcExprX, required, string, expression to evaluate for X-coordinate (must evaluate to numeric).

tcExprY, required, string, expression to evaluate for Y-coordinate (must evaluate to numeric).

tcExprW, required, string, expression to evaluate for width (must evaluate to numeric).

tcExprH, required, string, expression to evaluate for height (must evaluate to numeric).

Flush Method

Forces immediate processing of all pending graphics operations.

Syntax: THIS.Flush(tnFlushIntention)

Return Values: Logical, representing success or failure.

Parameters:

tnFlushIntention, required, numeric values defined in GDIPLUS_FlushIntention_* constants.

GetHdc Method

Obtains a Windows device context handle to enable drawing on the gpGraphics surface with Windows GDI functions.

Syntax: hDC = THIS.GetHdc()

Return Values: Integer handle to the GDI device context, or null (.NULL.) on error.

Parameters: none.

Remarks: This method is equivalent to the .NET Graphics.GetHdc. The handle must be released with ReleaseHdc() after use.

InterpolationMode Property

Specifies the interpolation mode associated with this graphics object.

Default: Empty.

MeasureStringA Method

Measures ANSI text string when drawn with the specified font and formatting.

Syntax: THIS.MeasureStringA(tcAnsiString,[toFont,[tvLayoutArea, [toStringFormat,[@rnCharsFitted[,@rnLinesFilled]]]])

Return Values: a gpSize object indicating the bounding rectangle of the string. Returns null (.NULL.) on error.

Parameters:

tcAnsiString, required, the ANSI string to measure.

toFont, optional, a gpFont object specified font to measure in.

tvLayoutArea, optional, a gpRectangle or gpSize object to within which text should be laid out.

toStringFormat, optional, a gpStringFormat object

rnCharsFitted, optional, on return is set to the number of characters that fit into the layout rectangle.

rnLinesFilled, optional, on return is set to the number of lines that fit into the layout rectangle.

Remarks: Note that the area of the gpSize object provided as a return value may be larger than a layout rectangle supplied to the method as the tvLayoutArea parameter.

MeasureStringW Method

Measures Unicode text string when drawn with the specified font and formatting.

Syntax: THIS.MeasureStringW(tcUnicodeString,[toFont,[tvLayoutArea, [toStringFormat,[@rnCharsFitted[,@rnLinesFilled]]]])

Return Values: a gpSize object indicating the bounding rectangle of the string. Returns null (.NULL.) on error.

Parameters:

tcUnicodeString, required, the Unicode string to measure.

toFont, optional, a gpFont object specified font to measure in.

tvLayoutArea, optional, a gpRectangle or gpSize object to within which text should be laid out.

toStringFormat, optional, a gpStringFormat object

rnCharsFitted, optional, on return is set to the number of characters that fit into the layout rectangle.

rnLinesFilled, optional, on return is set to the number of lines that fit into the layout rectangle.

Remarks: Note that the area of the gpSize object provided as a return value may be larger than a layout rectangle supplied to the method as the tvLayoutArea parameter.

PageScale Property

Specifies the scaling between world units and page units.

Default: Empty.

PageUnit Property

Specifies the unit of measure used for page coordinates, as defined in GDIPLUS_Unit_* constants. Read-write.

Default: Empty.

PixelOffsetMode Property

Specifies how pixels are offset during rendering, using values indicated by GDIPLUS_PixelOffsetMode_* defined constants.

Default: 0.

ReleaseHdc Method

Releases a device context handle previously obtained with GetHDC() method.

Syntax: THIS.ReleaseHDC(tnHDC)

Return Values: Logical, representing success or failure.

Parameters:

tnHDC, required, integer device context handle.

Remarks: This method is equivalent to the .NET Graphics.ReleaseHdc.

RenderingOrigin Property

The rendering origin for dithering and for hatch brushes, represented as a gpPoint object. Read-write.

Default: Empty.

ResetTransform Method

Resets the world transform matrix (to no transformation).

Syntax: THIS.ResetTransform()

Return Values: Logical, representing success or failure.

Parameters: none.

Restore Method

Restores previously saved graphics state.

Syntax: ? THIS.Restore(tnGraphicsState)

Return Values: Logical, representing success or failure.

Parameters:

tnGraphicsState, required, an integer graphics state handle previously obtained through the Save() method.

RotateTransform Method

Prepends rotation by specified angle to this object's transformation matrix.

Syntax: THIS.RotateTransform(tnAngle[, tnMatrixOrder])

Return Values: Logical, representing success or failure.

Parameters:

tnAngle, required, a rotation angle in degrees.

tnMatrixOrder, optional, the order of insertion into transformation matrix, as specified in GDIPLUS_MatrixOrder_* defined constants.

Save Method

Saves current graphics state and returns a token (for later restore).

Syntax: THIS.Save(@rnGraphicsState)

Return Values: Logical, representing success or failure.

Parameters:

rnGraphicsState, required, on return is set to a graphics state handle which can be passed to the Restore() method.

ScaleTransform Method

Applies scaling to transformation matrix for this graphics object.

Syntax: THIS.ScaleTransform(tnScaleX, tnScaleY[, tnMatrixOrder])

Return Values: Logical, representing success or failure.

Parameters:

tnScaleX, required, the horizontal scaling factor.

tnScaleY, required, the vertical scaling factor.

tnMatrixOrder, optional, the order of insertion into transformation matrix, as specified in GDIPLUS_MatrixOrder_* defined constants.

SmoothingMode Property

Specifies rendering quality, with possible values indicated by GDIPLUS_SmoothingMode_* constants.

Default: Empty.

TextContrast Property

Specifies gamma correction value for rendering text.

Default: Empty.

TextRenderingHint Property

Specifies the rendering mode for text associated with this graphics object.

Default: Empty.

TranslateTransform Method

Adds translation by (x,y) to this graphics object's transformation matrix.

Syntax: THIS.TranslateTransform(tnOffsetX, tnOffsetY[, tnMatrixOrder])

Return Values: Logical, representing success or failure.

Parameters:

tnOffsetX, required, the horizontal offset value.

tnOffsetY, required, the vertical offset value.

tnMatrixOrder, optional, the order of insertion into transformation matrix, as specified in GDIPLUS_MatrixOrder_* defined constants

VisibleClipBounds Property

Visible clipping region represented as a gpRectangle object. Read-only.

Default: Empty.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus HatchBrush Foundation Class

Visual FoxPro 9.0
GDI Plus HatchBrush Foundation Class
See Also

The gpHatchBrush class provides a brush object which fills with a hatch pattern.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpHatchBrush
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpBrush (GDI Plus Brush Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpBrush. This class also implements the Init method.

Properties and methods Description

BackgroundColor Property

Specifies the color of the space between hatch lines, as an integer defining an ARGB value.

Default: Empty.

Create Method

Creates a hatchbrush object.

Syntax: ? THIS.Create(tnStyle[, tvForeColor[, tvBackColor]])

Return Values: Logical, representing success or failure.

Parameters:

tnStyle, required, the hatch pattern or style to be used. Use a constant as specified in the GDIPLUS_HatchStyle_* constant set.

tvForeColor, optional, an integer or gpColor object representing a color value for the brush forecolor (hatch lines).

tvBackColor, optional, an integer or gpColor object representing a color value for the brush backcolor (space between the hatch lines).

ForegroundColor Property

Specifies the color of the hatch lines, as an integer defining an ARGB value.

Default: Empty.

HatchStyle Property

Specifies the hatch style, or pattern. Use a constant as specified in the GDIPLUS_HatchStyle_* constant set.

Default: 0 (GDIPLUS_HatchStyle_Horizontal).

Init Method

Constructs a hatchbrush object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpHatchBrush"[,tnStyle[, tvForeColor[, tvBackColor]]])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tnStyle, required if immediate creation of the object is requested, representing the hatch pattern or style to be used. Use a constant as specified in the GDIPLUS_HatchStyle_* constant set.

tvForeColor, optional, an integer or gpColor object representing a color value for the brush forecolor (hatchlines).

tvBackColor, optional, an integer or gpColor object representing a color value for the brush backcolor (space between the hatchlines).

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Image Foundation Class

Visual FoxPro 9.0
GDI Plus Image Foundation Class
See Also

The gpImage class encapsulates a GDI+ image, and serves as the base class for specific image types (for example, the gpBitmap class).

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpImage
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpObject (GDI Plus Object Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpObject. This class also implements the Init and Clone methods.

Properties and methods Description

Clone Method

Clones an image object.

Syntax: THIS.Clone(toGpImage)

Return Values: Logical, representing success or failure.

Parameters:

toGpImage, required, the gpImage-based object to clone.

CreateFromFile Method

Creates an image object from a file.

Syntax: THIS.CreateFromFile(tcFileName [, tlUseEmbeddedColorMgmt])

Return Values: Logical, representing success or failure.

Parameters:

tcFileName, required, the image file from which to create the image object.

tlUseEmbeddedColorMgmt, optional, whether to use embedded color management.

Flags Property

Specifies attribute flags for this image as an integer computed as a combination of bit values, using the GDIPLUS_ImageFlags_* defined constants.

Default: Empty.

GetBounds Method

Gets a bounding rectangle in the specified units.

Syntax: THIS.GetBounds(tnUnits)

Return Values: an object of type gpRectangle, or null (.NULL.) on error.

Parameters:

tnUnits, required, specified according to the GDIPLUS_Unit_* set of constants.

GetDecoderCLSID Method

Gets the CLSID for the Decoder for a specific image format (for example, "image/jpeg").

Syntax: qCLSID = THIS.GetDecoderCSLID(tvSearchValue)

Return Values: Varbinary, CLSID of Decoder. Returns null (.NULL.) on error.

Parameters:

tvSearchValue, required. A string containing MIME type of image (eg "image/jpeg"), or a varbinary GUID of image format, as specified in GDIPLUS_IMAGEFORMAT_* constants.

Remarks: If no decoder is found for the specified image type, or if the image format MIME type or GUID supplied in tvSearchValue is invalid, then this function returns .NULL. and the GetStatus() method returns 0 ("no error").

GetEncoderCLSID Method

Gets the CLSID for the encoder for a specific image format (for example, "image/jpeg").

Syntax: qCLSID = THIS.GetEncoderCSLID(tvSearchValue)

Return Values: Varbinary, CLSID of encoder suitable for passing to SaveToFile() method. Returns null (.NULL.) on error.

Parameters:

tvSearchValue, required. A string containing MIME type of image (eg "image/jpeg"), or a varbinary GUID of image format, as specified in GDIPLUS_IMAGEFORMAT_* constants.

Remarks: If no encoder is found for the specified image type, or if the image format MIME type or GUID supplied in tvSearchValue is invalid, then this function returns .NULL. and the GetStatus() method returns 0 ("no error").

GetPropertyCount Method

Gets the number of properties stored in the metadata of this image object.

Syntax: nCount = THIS.GetPropertyCount()

Return Values: Integer, number of meta data properties (which could be zero). Returns null (.NULL.) on error.

Parameters: none.

GetPropertyIdList Method

Gets a list of all the properties stored in the image metadata, as a Visual FoxPro array.

Syntax: nCount = THIS.GetPropertyIdList(@raPropIDList)

Return Values: Integer, number of meta data properties (which could be zero). Returns null (.NULL.) on error. The property ID values are returned in the raPropIDList parameter array.

Parameters:

raPropIDList, required, array passed by reference. On return, this array is dimensioned to a 1-dimensional array, and each element of the array contains an integer property ID value.

GetPropertyItem Method

Retrieves the specified property from the image metadata.

Syntax: vPropertyValue = THIS.GetPropertyItem(tnPropID)

Returns: Property value, or null (.NULL.) if the property is not found or an error occurs. The data type depends on the property tag type, as follows:

Property types: | Returned in Visual FoxPro as:
byte, short, long, signed long | Numeric
String | ANSI string
rational, signed rational | String containing two numbers separated by a slash character. For example, one-third would be "1/3".

Property types not shown here are not supported.

Parameters:

tnPropID, required, integer, a property item ID as returned by GetPropertyIDList.

Remarks: If the requested property is not defined, this method returns null (.NULL.) and the GetStatus() method returns 19 (GDIPLUS_STATUS_PropertyNotFound).

GetThumbnailImage Method

Gets a thumbnail image from the image object, returned as a new gpImage object.

Syntax: oImage= THIS.GetThumbnailImage(tnWidth, tnHeight)

Return Values: gpImage object containing a thumbnail. Returns null (.NULL.) if an error occurs.

Parameters:

tnWidth, integer, required, desired width of thumbnail in pixels.

tnHeight, integer, required, desired width of thumbnail in pixels.

Remarks: Some image files have a thumbnail image embedded in the file. In such cases, this method retrieves the embedded thumbnail image and the tnWidth and tnHeight parameter values are ignored. If there is no embedded thumbnail image, this method creates a thumbnail image by scaling the main image to the size specified in the tnWidth and tnHeight parameters. If both of those parameters are 0, a system-defined size is used.

HorizontalResolution Property

Numeric, horizontal resolution in pixels-per-inch. Read-only.

Default: none.

ImageHeight Property

Height of this Image object. Read-only.

Default: none.

ImageWidth Property

Width of this Image object. Read-only.

Default: none.

Init Method

Constructs an Image object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpImage" [,tnHandle|tcFileName[, tlParam]])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tnHandle | tcFilename, required if immediate creation of the object is requested, a graphics handle or filename from which the image will be created.

tlParam, optional, indicates whether the class owns the graphics handle (if the first parameter is tnHandle) or whether color management should be used (if the first parameter is tcFileName).

PhysicalDimension Property

Provides the width and height of this image object, as an object of type gpSize. Read-only.

Default: none.

Remarks: If the image is a bitmap, the width and height are returned in pixels. If the image is a metafile, the width and height are returned in 0.01 millimeter units.

PixelFormat Property

Pixel format, according to the values specified in GP_PIXELFORMAT_* constants. Read-only.

Default: none.

Remarks: May not apply to some image objects, such as vector-format images.

RawFormat Property

Get the format of this image as a GUID of varbinary type. Read-only.

Default: none.

RotateFlip Method

Rotates and/or flips (mirrors) the image object.

Syntax: THIS.RotateFlip(tnRotateFlipType)

Return Values: Logical, representing success or failure.

Parameters:

tnRotateFlipType, required, integer. Specifies angle of rotation and/or type of flip, according to the values specified in the GDIPLUS_ROTATEFLIPTYPE_* defined constants.

SaveToFile Method

Saves the image object to a disk file, using specified encoder or image format and optional parameters.

Syntax: THIS.SaveToFile(tcFilename, tvCLSIDEncoder[, rvEncoderParams])

Return Values: Logical, representing success or failure.

Parameters:

tcFilename, required, string, the file name to which the image should be saved.

tvCLSIDEncoder, required, string or varbinary. The CLSID of the encoder to use, or a MIME type (eg "image/jpeg"). If a MIME type is specified, then the method dynamically looks up the CLSID of the appropriate Encoder.

rvEncoderParams, optional, parameters for the encoder. Either a comma-separated string in the form "param1=value1,param2=value2", or a two-column array (passed by reference) of encoder parameters and values.

Remarks: The encoder parameters are defined internally by globally unique IDs (GUIDS). This function understands a limited set of parameters by name:

Image type | Available parameters
JPEG | quality, transformation
TIFF | compression, colordepth, saveflag

To pass other parameters, use the array form of rvEncoderParams with the GUID of the parameter in the first column.

The following example saves an image to a JPEG file, using a quality of 80%.

Copy Code
lSuccess = oImage.SaveToFile( "example.jpg", ;
           "image/jpeg", "quality=80" )

VerticalResolution Property

Numeric, vertical resolution in pixels-per-inch. Read-only.

Default: none.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Object Foundation Class

Visual FoxPro 9.0
GDI Plus Object Foundation Class
See Also

The gpObject class is the abstract base class for all GDI+ objects. It provides management of GDI+ handles and the outcome of GDI+ operations.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpObject
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpBase (GDI Plus Base Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpBase.

Properties and methods | Description
GetHandle Method | Returns the underlying GDI+ handle for this object. Syntax: ? THIS.GetHandle() Return Values: Integer value representing handle. Returns null (.NULL.) if an error occurs. Parameters: None.
GetStatus Method | Returns the status code from the last GDI+ function called on this object. See the GP_STATUS_* defined constants. Syntax: ? THIS.GetStatus() Return Values: Integer value representing status code. Parameters: None.
SetHandle Method | Sets the native GDI+ handle if this has been obtained from an outside source. Syntax: ? THIS.SetHandle(tvNewHandle,tlOwnsHandle) Return Values: : Logical, representing success or failure. Parameters: tvHandle, required, the handle to assign. tlOwnsHandle, optional, defaults to false (.F.). Indicates whether this object owns the handle and can delete it when this object performs other cleanup.
Win32LastError Property | Returns the last Windows error code if GetStatus returns GP_STATUS_Win32Error. Default: 0.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Pen Foundation Class

Visual FoxPro 9.0
GDI Plus Pen Foundation Class
See Also

The gpPen class provides a pen object, which is used to draw lines and curves.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpPen
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpObject (GDI Plus Object Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpObject. This class also implements the Clone and Init methods.

Properties and methods Description

Alignment Property

Alignment of lines drawn with this pen on closed curves and polygons, according to the GP_PENALIGNMENT_* set of constants.

Clone Method

Clones a pen object.

Syntax: ? THIS.Clone(toGpPen)

Return Values: Logical, representing success or failure.

Parameters:

toGpPen, required, the gpPen-based object to clone.

Create Method

Constructs a pen object of a specified color.

Syntax: THIS.Create(tvColor[, tnWidth[, tnUnit]])

Return Values: Logical, representing success or failure.

Parameters:

tvColor, required, a gpColor object or numeric value representing a composite color value.

tnWidth, optional, pen width, defaults to 1.0.

tnUnit, optional, unit for tnWidth value, defaults to GDIPLUS_Unit_World.

CreateFromBrush Method

Creates a pen from an existing brush object.

Syntax: THIS.CreateFromBrush(toBrush[, tnWidth[, tnUnit]])

Return Values: Logical, representing success or failure.

Parameters:

toBrush, required, a gpBrush-derived object.

tnWidth, optional, pen width, defaults to 1.0.

tnUnit, optional, unit for tnWidth value, defaults to GDIPLUS_Unit_World.

DashCap Property

Sets the cap style at the end of dashes, for dashed lines, as specified by GDIPLUS_DashCap_* defined constants.

Default: GDIPLUS_DashCap_Flat.

DashOffset Property

Sets the distances from the start of a line to the beginning of a dash pattern.

Default: 0

DashStyle Property

Sets the style used for dashed lines, as specified by GDIPLUS_DashStyle_* defined constants.

Default: GDIPLUS_DashStyle_Solid.

EndCap Property

Sets the cap style at the end of lines drawn with this pen object, as specified by GDIPLUS_LineCap_* defined constants.

Default: GDIPLUS_LineCap_Flat.

Init Method

Constructs a pen object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpPen" [,tvColor[, tnWidth[, tnUnit]]])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tvColor, required if immediate creation of the object is requested, a gpColor object or numeric value representing a composite color value.

tnWidth, optional, pen width, defaults to 1.0.

tnUnit, optional, unit for tnWidth value, defaults to GDIPLUS_Unit_World.

LineJoin Property

Sets the join style for the ends of two consecutive lines drawn with this pen, as specified by GDIPLUS_LineJoin_* defined constants.

Default: GDIPLUS_LineJoin_Miter.

MiterLimit Property

The limit of the thickness of the join on a mitered corner (maximum allowed ratio of miter length to stroke width).

Default: 10.0.

PenColor Property

Indicates the color of this pen object, using an integer to specify an ARGB value.

Default: 0 (opaque black).

PenType Property

Sets the type of lines drawn with this pen object, as defined by GDIPLUS_PenType_* constants. Read-only.

Remarks: This property only applies to derivatives of gpPen, such as those created from brushes. Only solid pens (GDIPLUS_PenType_SolidColor) can be created with the stock gpPen Foundation class.

PenUnit Property

Indicates the unit for measuring width and other values, as specified by GDIPLUS_UNIT_* constants.

Default: GDIPLUS_Unit_World.

PenWidth Property

Sets the width of the pen object.

Default: 1.0.

StartCap Property

Sets the cap style at the start of lines drawn with this pen object, as specified by GDIPLUS_LineCap_* defined constants.

Default: GDIPLUS_LineCap_Flat.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Point Foundation Class

Visual FoxPro 9.0
GDI Plus Point Foundation Class
See Also

The gpPoint class encapsulates an ordered pair of x- and y-coordinates that defines a point in a two-dimensional plane.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpPoint
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpBase (GDI Plus Base Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpBase. This class also implements the Clone and Init methods.

Properties and methods Description

Clone Method

Clones a point object.

Syntax: ? THIS.Clone(toGpPoint)

Return Values: Logical, representing success or failure.

Parameters:

toGpPoint, required, the gpPoint-based object to clone.

Create Method

Creates a point object from specified coordinates.

Syntax: THIS.Create(tX,tY)

Return Values: Logical, representing success or failure.

Parameters:

tX, required, the X coordinate for the point to create.

tY, required, the Y coordinate for the point to create.

GdipPoint Property

String representing the GDI+ Point structure (composed of two 32-bit integers).

Default: Empty.

GdipPointF Property

String representing the GDI+ PointF structure (composed of two 32-bit single-precision float values).

Default: Empty.

Init Method

Constructs a Point object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpPoint" [,tX,tY])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tX, required if immediate creation of the object is requested, represents the X coordinate for the point.

tY, required if immediate creation of the object is requested, represents the Y coordinate for the point.

Set Method

Sets a point object from specified coordinates.

Syntax: THIS.Set(tX,tY)

Return Values: Logical, representing success or failure.

Parameters:

tX, required, the X coordinate for the point to set.

tY, required, the Y coordinate for the point to set.

X Property

The X-coordinate of the point.

Default: 0.

Y Property

The Y-coordinate of the point.

Default: 0.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Rectangle Foundation Class

Visual FoxPro 9.0
GDI Plus Rectangle Foundation Class
See Also

The gpRectangle class encapsulates a set of four numbers that represent the location and size of a rectangle.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpRectangle
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpBase (GDI Plus Base Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpBase. This class also implements the Clone and Init methods.

Properties and methods Description

Clone Method

Clones a rectangle object.

Syntax: ? THIS.Clone(toGpRectangle)

Return Values: Logical, representing success or failure.

Parameters:

toGpRectangle, required, the gpRectangle-based object to clone.

Create Method

Creates a rectangle object from specified coordinates.

Syntax: THIS.Create(tX,tY, tW, tH)

Return Values: Logical, representing success or failure.

Parameters:

tX, required, the X coordinate for the rectangle to create.

tY, required, the Y coordinate for the rectangle to create.

tW, required, the width for the rectangle to create.

tH, required, the height for the rectangle to create.

CreateFromPointSize Method

Creates a rectangle from a gpPoint object and a gpSize object.

Syntax: THIS.CreateFromPointSize(toPoint,toSize)

Return Values: Logical, representing success or failure.

Parameters:

toPoint, required, a point object representing the starting point of the rectangle to create.

toSize, required, a size object representing the width and height of the rectangle to create.

GdipPoint Property

String representing a GDI+ Point structure (composed of two 32-bit integers), providing the starting point of the rectangle.

Default: Empty.

GdipPointF Property

String representing a GDI+ PointF structure (composed of two 32-bit single-precision float values), providing the starting point of the rectangle.

Default: Empty.

GdipRect Property

String representing a GDI+ Rect structure (composed of four 32-bit integers), providing the starting point of the rectangle.

Default: Empty.

GdipRectF Property

String representing a GDI+ RectF structure (composed of four 32-bit single-precision float values), providing the starting point of the rectangle.

Default: Empty.

gdiRect Property

String representing the Win32 "RECT" structure (as values X, Y, X2, Y2).

Remarks: This property is useful when working with Windows GDI functions, which expect rectangles defined as the coordinates of two diagonally-opposite corners, rather than top, left, width and height values.

Default: Empty.

gpPoint Property

Starting or origin point of the rectangle represented as a gpPoint object.

Default: Empty.

gpSize Property

Width and Height of the rectangle as a gpSize object.

Default: Empty.

H Property

Height of the rectangle.

Default: 0.

Init Method

Constructs a rectangle object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpRectangle" [,tX_Rect_Point,tY_Size, tW, tH])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tX_Rect_Point, required if immediate creation of the object is requested, represents the X coordinate for the starting point of the rectangle, an existing gpRectangle-based object to be cloned, or a top-left point for the rectangle.

tY_Size, required if immediate creation of the object is requested and tX_Rect_Point is not an object of type gpRectangle, represents the Y coordinate for the starting point of the rectangle, if tX_Rect_Point was the point's X coordinate, or an object of type gpSize, if tX_Rec_Point was an object of type gpPoint.

tW, required if the first two parameters were coordinates, represents the width of the rectangle to create.

tH, required if the first two parameters were coordinates, represents the height of the rectangle to create.

Set Method

Sets a rectangle's coordinates from individual components.

Syntax: THIS.Set(tX, tY, tW, tH)

Return Values: Logical, representing success or failure.

Parameters:

tX, required, the X coordinate of the starting point of the rectangle to be set.

tY, required, the Y coordinate of the starting point of the rectangle to be set.

tW, required, the width of the rectangle to be set.

tH, required, the height of the rectangle to be set.

W Property

Width of the rectangle.

Default: 0.

X Property

X-coordinate of the starting point (top-left) of the rectangle.

Default: 0.

X2 Property

X-coordinate of the ending point (bottom-right) of the rectangle.

Default: 0.

Y Property

Y-coordinate of the starting point (top-left) of the rectangle.

Default: 0.

Y2 Property

Y-coordinate of the ending point (bottom-right) of the rectangle.

Default: 0.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus Size Foundation Class

Visual FoxPro 9.0
GDI Plus Size Foundation Class
See Also

The gpSize class stores an ordered pair of numbers, typically the width and height of a rectangle.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpSize
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpBase (GDI Plus Base Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpBase. This class also implements the Clone and Init methods.

Properties and methods Description

Clone Method

Clones a Size object.

Syntax: ? THIS.Clone(toGpSize)

Return Values: Logical, representing success or failure.

Parameters:

toGpSize, required, the gpSize-based object to clone.

Create Method

Creates a Size object from specified coordinates.

Syntax: THIS.Create(tW, tH)

Return Values: Logical, representing success or failure.

Parameters:

tW, required, the width for the rectangle to create.

tH, required, the height for the rectangle to create.

GdipSize Property

String representing the GDI+ Size structure (composed of two 32-bit integers).

Default: Empty.

GdipSizeF Property

String representing the GDI+ Size structure (composed of two 32-bit single-precision float values).

Default: Empty.

H Property

Height value for the Size object.

Default: 0.

Init Method

Constructs a Size object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpSize" [,tW_Size, tH])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tW_Size, required if immediate creation of the object is requested, represents the width for the Size object, or another Size object to be cloned.

tH, required if the first parameters was not a Size object to be cloned.

Set Method

Sets a Size object's coordinates from individual components.

Syntax: THIS.Set(tW, tH)

Return Values: Logical, representing success or failure.

Parameters:

tW, required, the width of the Size object.

tH, required, the height of the Size object.

W Property

Width value for the Width object.

Default: 0.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus SolidBrush Foundation Class

Visual FoxPro 9.0
GDI Plus SolidBrush Foundation Class
See Also

The gpSolidBrush class provides a brush object which fills with a solid color.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpSolidBrush
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpBrush (GDI Plus Brush Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpBrush. This class also implements the Init method.

Properties and methods Description

BrushColor Property

Specifies the color of a SolidBrush object as an integer representing an ARGB value.

Default: None.

Create Method

Creates a SolidBrush object in a specified color.

Syntax: THIS.Create(tvColor)

Return Values: Logical, representing success or failure.

Parameters:

tvColor, required, a gpColor-based object or a number representing a composite color value.

Init Method

Constructs a SolidBrush object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpSolidBrush" [, tvColor])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tvColor, required if immediate creation of the object is requested, a gpColor-based object or a number representing a composite color value.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


GDI Plus StringFormat Foundation Class

Visual FoxPro 9.0
GDI Plus StringFormat Foundation Class
See Also

The gpStringFormat class provides an object encapsulating text layout information (such as alignment and line spacing) and display manipulations (such as ellipsis insertion and national digit substitution).

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\GDIplus
Class | gpStringFormat
Base Class | Custom
Class Library | _GDIPLUS.vcx
Parent Class | gpObject (GDI Plus Object Foundation Class)

Remarks

The following table lists public properties and methods added by this class to its parent class, gpObject. This class also implements the Clone and Init methods.

Properties and methods Description

Alignment Property

Text horizontal alignment specified using values indicated by GDIPLUS_STRINGALIGNMENT_* constants.

Default: GDIPLUS_STRINGALIGNMENT_Near.

Remarks: In a left-to-right reading order environment, GDIPLUS_STRINGALIGNMENT_Near is equivalent to "left alignment," and GDIPLUS_STRINGALIGNMENT_Far is equivalent to "right alignment."

Clone Method

Clones a StringFormat object.

Syntax: ? THIS.Clone(toGpStringFormat)

Return Values: Logical, representing success or failure.

Parameters:

toGpStringFormat, required, the gpStringFormat-based object to clone.

Create Method

Creates a StringFormat object with optional flags and language information.

Syntax: THIS.Create([tnFlags[, tnLangID]])

Return Values: Logical, representing success or failure.

Parameters:

tnFlags, optional, initial value for the FormatFlags property.

tnLangID, optional, an integer language identifier.

FormatFlags Property

String formatting flags specified using a combination of bit values, using values defined by GDIPLUS_STRINGFORMATFLAGS_* constants.

Default: Empty.

GetGenericDefault Method

Constructs a StringFormat object equivalent to .NET's System.Drawing.StringFormat.GenericDefault.

Syntax: THIS.GetGenericDefault(tlMakeClone)

Return Values: Logical, representing success or failure.

Remarks: Upon successful return from this method the object represents a system standard string format, and all properties become read-only.

GetGenericTypographic Method

Constructs a StringFormat object with Generic Typographic properties set as they would be by .NET's System.Drawing.StringFormat. GenericTypographic.

Syntax: THIS.GetGenericTypographic(tlMakeClone)

Return Values: Logical, representing success or failure.

Remarks: Upon successful return from this method the object represents a system standard string format, and all properties become read-only.

HotkeyPrefix Property

HotkeyPrefix setting with values indicated by GDIPLUS_HOTKEYPREFIX_* constants.

Init Method

Constructs a StringFormat object during initialization if passed appropriate arguments.

Syntax: CREATEOBJECT("gpStringFormat" [, tnFlags[, tnLangID]])

Return Values: Logical, representing success or failure. If the method fails, the object does not instantiate.

Parameters:

tnFlags, optional, initial value for the FormatFlags property.

tnLangID, optional, an integer language identifier.

LineAlignment Property

Text line vertical alignment specified using values indicated by GDIPLUS_STRINGALIGNMENT_* constants.

Default: GDIPLUS_STRINGALIGNMENT_Near.

Remarks: In a top-to-bottom reading order environment, GDIPLUS_STRINGALIGNMENT_Near is equivalent to "top alignment," and GDIPLUS_STRINGALIGNMENT_Far is equivalent to "bottom alignment."

Trimming Property

Flags that specify how text is trimmed when it overflows the layout rectangle, using values indicated by GDIPLUS_STRINGTRIMMING_* constants.

Default: GDIPLUS_STRINGTRIMMING_None.

See Also

Reference

GDI Plus API Wrapper Foundation Classes

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


Get File and Directory Foundation Class

Visual FoxPro 9.0 Language Reference
Get File and Directory Foundation Class
See Also

This dialog box retrieves both a file and folder name. It is used to create new projects in directories of the same name.

Category | User Interface
Default Catalog | Visual FoxPro Catalog\Foundation Classes\User Controls
Class | _folder
Base Class | Container
Class Library | _controls.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Ffc\getproject.scx

Remarks

To use, drop the class on a project or form. When you drop the class on a project, you can choose between adding the class or creating a subclass. When you drop the class to a form, Visual FoxPro places the class controls including a Browse button on your form.

Properties, Events, Methods | Description
cLastProjectFile property | Internal to the class.
cExt property | Internal to the class.
TrimFile property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


GoTo Dialog Box Button Foundation Class

Visual FoxPro 9.0 Language Reference
GoTo Dialog Box Button Foundation Class
See Also

This class creates a button that displays the GoTo dialog box so you can navigate to a specific record.

Category | Data Navigation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | _gotobutton
Base Class | CommandButton
Class Library | _table2.vcx
Parent Class | _dialogbutton
Sample | ...\Samples\Solution\Ffc\Buttons.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you drop the class on a form, Visual FoxPro places a button on your form. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


GoTo Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
GoTo Dialog Box Foundation Class
See Also

This class creates a GoTo Record dialog box.

Category | Data Navigation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Navigatio n
Class | _gotodialog
Class Library | _table.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\datanav.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Create Form. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. When you drop the class on a project or choose Create a new form from the selected class in the shortcut menu, Visual FoxPro opens a builder so you can specify the name of the form, then creates and opens the form in the Form Designer.

_GoToDialog is a modal dialog box with a _TableNav member and a spinner to allow the user to specify a record number. When you click OK, the GoToRecord method navigates to the specified record, then runs the RefreshLastWindowAfterChange method to update the display. Note that GoToRecord( ) updates the display even if the table does not permit navigation, in case you revert a change.

_GoToDialog uses _TableNav to determine the current alias at startup. It then sets the spinner SpinnerLowValue and KeyboardLowValue to 1 and SpinnerHighValue and KeyboardHighValue to RECCOUNT( ). It also sets the spinner Value property appropriately.

Properties, Events, Methods | Description
RefreshUIAfterChange method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Graph By Record Foundation Class

Visual FoxPro 9.0 Language Reference
Graph By Record Foundation Class
See Also

This container class creates graphs at the record level, unlike the AutoGraph class, which creates graphs from an entire Visual FoxPro cursor. The class also includes a set of buttons to navigate between records and dynamically refresh the chart.

Category | Automation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Automation
Class | _graphbyrec
Base Class | Container
Class Library | _utility.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Ffc\automate.scx

Remarks

To use, drop the class on a project or form, or from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form in a data environment, Visual FoxPro opens a builder so you can specify the nChartType and cLblField values for the graph data points and axis labels. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
cLblField property | Specifies the caption for the record label. Default: ""
nChartType property | Specifies the chart type. The valid values are: Default: 4
lSeriesByRow property | Specifies whether to plot a series by row. Default: .T.
aDataFields[1] property | Specifies the array of data fields to graph. Default: .F.
SetupGraph method | Initializes graph controls. Syntax: SetupGraph( ) Return: none Arguments: none
RefreshGraph method | Refreshes the graph when the record pointer is moved. Syntax: RefreshGraph( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Graph Object Foundation Class

Visual FoxPro 9.0 Language Reference
Graph Object Foundation Class
See Also

Category | Automation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Automation
Class | autograph
Base Class | Custom
Class Library | autograph.vcx
Parent Class | automation
Sample | ...\Samples\Solution\Ffc\Automate.scx

Remarks

This custom class generates a chart by automating MS Graph using the core Graph Wizard engine.

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the cOutputfile, nChartType, lAddLegend, and lSeriesByRow values. You can also use the autograph class and supply values for fields, chart type, the preview form, and default name in program code. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
aDataFields[1,1] property | Specifies the name of a numeric field in the target table (the "Y" axis value). Default: .F.
cCategoryField property | Specifies a field in the target table (the "X" axis). Default: .F.
cOutFile property | Name of the output file if any. Default: ""
cTitle property | Title caption of the chart. Default: ""
lCurrRec property | Specifies whether to retain the current record number, if only graphing one record. Default:.F.
lAddedData property | Flags if data is already added for performance. Default: .F.
lAddLegend property | Adds a legend to the chart. Default: .T.
lAddTitle property | Adds a title to the chart. Default:.T.
lGraphRecord property | Specifies whether to graph the current record. The default graphs the entire cursor. Default: .F.
lKeepForm property | Specifies whether to use the user-supplied form and OLE control. Default: .F
lSeriesByRow property | Plots a series by row or column. Default: .T.
lShowNulls property | Displays null values in the chart. Default: .T.
lShowWhenDone property | Specifies whether to display a preview of the form. Default: .T.
lUse8Type property | Specifies whether to use the nChartType property. Default: .F.
lUseAutoformat property | Use the MS Graph autocharting gallery. Default:.F.
nAction property | Specifies the type of output action: Default: 1
nChartAutoformat property | Chart format for autoformat. Default: 2
nChartAutoGallery property | Gallery chart format for autoformat. Default: 1
nChartSubType property | Sub type of chart. Default: 1
nChartType property | Specifies the chart type. The valid values are: Default: 1
nGraphVersion property | Version of Graph being used. Default: 5
cDefNewField property | Internal to the class.
cGraphDBF property | Internal to the class.
cGraphField property | Internal to the class.
cGraphFldCol property | Internal to the class.
cGraphFldRow property | Internal to the class.
cGraphPrevClass property | Internal to the class.
cLastDataCol property | Internal to the class.
cLastDataRow property | Internal to the class.
cOLEServer property | Internal to the class.
cOpenAlias property | Internal to the class.
cOutGenField property | Internal to the class.
GraphPreview property | Internal to the class.
lAutograph property | Internal to the class.
lDontStripLegend property | Internal to the class.
lHadPreview property | Internal to the class.
lReplaceDBF property | Internal to the class.
lStripExcessLegend property | Internal to the class.
nDataCount property | Internal to the class.
nDataSeries property | Internal to the class.
nLastAction property | Internal to the class.
nTotalDataFlds property | Internal to the class.
oGraphRef property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Help Button Foundation Class

Visual FoxPro 9.0 Language Reference
Help Button Foundation Class
See Also

This class provides a button that, when clicked, displays a Help topic by searching for the HelpContextID specified in the control.

Category | Misc Buttons
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | _cmdHelp
Base Class | CommandButton
Class Library | _miscbtns.vcx
Parent Class | _commandbutton
Sample | ...\Samples\Solution\Ffc\buttons.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you add the class to a form, Visual FoxPro places a button on your form. You need to provide the appropriate value to replace the default value of HelpContextID. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Hyperlink Button Foundation Class

Visual FoxPro 9.0 Language Reference
Hyperlink Button Foundation Class
See Also

This class provides the functionality of the Hyperlink object and launches a Web Browser when you click a button.

Category | Internet
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Internet
Class | _hyperlinkcommandbutton
Base Class | CommandButton
Class Library | _hyperlink.vcx
Parent Class | _commandbutton
Sample | ...\Samples\Solution\Ffc\buttons.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the button name and the URL to use. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
cTarget property | Specifies the URL to use. Default: ""
GoBack method | Executes a hyperlink jump backward within the history list. Syntax: GoBack( ) Return: none Arguments: none
GoForward method | Executes a hyperlink jump forward within the history list. Syntax: GoForward( ) Return: none Arguments: none
cFrame property | Internal to the class.
cHyperlinkclass property | Internal to the class.
cHyperlinkClassLibrary property | Internal to the class.
cLocation property | Internal to the class.
lFormSynch property | Internal to the class.
lHyperlinkCreated property | Internal to the class.
lNewWindow property | Internal to the class.
lVisited property | Internal to the class.
nVisitedForecolor property | Internal to the class.
oHyperlink property | Internal to the class.
cTarget_assign method | Internal to the class.
Follow method | Internal to the class.
lVisited_assign( ) method | Internal to the class.
nVisitedForecolor_assign( ) method | Internal to the class.
oHyperlink_access( ) method | Internal to the class.
ShowVisitedForecolor( ) method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Hyperlink Image Foundation Class

Visual FoxPro 9.0 Language Reference
Hyperlink Image Foundation Class
See Also

This class provides the functionality of the Hyperlink object and launches a Web Browser when you click an image.

Category | Internet
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Internet
Class | _hyperlinkimage
Base Class | Image
Class Library | _hyperlink.vcx
Parent Class | _image
Sample | ...\Samples\Solution\Ffc\hyperlnk.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the image name and the URL to use. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
cTarget property | Specifies the URL to use. Default: ""
GoBack method | Executes a hyperlink jump backward within the history list. Syntax: GoBack( ) Return: none Arguments: none
GoForward method | Executes a hyperlink jump forward within the history list. Syntax: GoForward( ) Return: none Arguments: none
cFrame property | Internal to the class.
cHyperlinkClass property | Internal to the class.
cHyperlinkClassLibrary property | Internal to the class.
cLocation property | Internal to the class.
cTarget_assign method | Internal to the class.
Follow method | Internal to the class.
lFormsSynch property | Internal to the class.
lHyperlinkcreated property | Internal to the class.
lNewWindow property | Internal to the class.
lVisited property | Internal to the class.
oHyperlink property | Internal to the class.
oHyperlink_access method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Hyperlink Label Foundation Class

Visual FoxPro 9.0 Language Reference
Hyperlink Label Foundation Class
See Also

This class provides the functionality of the Hyperlink object and launches a Web Browser when you click a label.

Category | Internet
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Internet
Class | _hyperlinklabel
Base Class | Label
Class Library | _hyperlink.vcx
Parent Class | _label
Sample | ...\Samples\Solution\Ffc\hyperlnk.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the label and the URL (in cTarget) to use. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
cTarget property | Specifies the URL to use. Default: ""
GoBack method | Executes a hyperlink jump backward within the history list. Syntax: GoBack( ) Return: none Arguments: none
GoForward method | Executes a hyperlink jump forward within the history list. Syntax: GoForward( ) Retu rn: none Arguments: none
cFrame property | Internal to the class.
cHyperlinkClass property | Internal to the class.
cHyperlinkClassLibrary property | Internal to the class.
cLocation property | Internal to the class.
cTarget_assign method | Internal to the class.
Follow method | Internal to the class.
lFormsSynch property | Internal to the class.
lHyperlinkcreated property | Internal to the class.
lNewWindow property | Internal to the class.
lVisited property | Internal to the class.
oHyperlink property | Internal to the class.
oHyperlink_access method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


INI Access Foundation Class

Visual FoxPro 9.0 Language Reference
INI Access Foundation Class
See Also

This class provides a set of registry functions that access old INI-style file settings.

Category | System Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | oldinireg
Base Class | Custom
Class Library | Registry.vcx
Parent Class | registry

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
GetINIEntry method | Retrieves information from INI entry. Syntax: GetINIEntry(cValue, cSection, cEntry, cINIFile) Arguments: cValue specifies the value to be applied to cEntry.cSection specifies the section of the .ini file in which cEntry occurs.cEntry specifies the item to be assigned cValue.cINIFile specifies the name of the .ini file.
GetINISection method | Retrieves information from INI section. Syntax: GetINISection(@aSections, cSection, cINIFile) Arguments: aSections specifies an array of cSections included in the .ini file.cSection specifies the section of cINIfile file to retrieve.cINIFile specifies the name of the .ini file.
LoadINIFuncs method | Loads functions needed for reading .ini files. Syntax: LoadINIFuncs( ) Return: none Arguments: none
WriteINIEntry method | Writes a specific INI entry. Syntax: WriteINIEntry(cValue, cSection, cEntry, cINIFile) Arguments: cValue specifies the new value.cSection specifies the section of cINIfile file to retrieve.cINIFile specifies the name of the .ini file.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Item Locator Foundation Class

Visual FoxPro 9.0 Language Reference
Item Locator Foundation Class
See Also

This class provides a File Locator dialog box. It is designed to locate a file that your application needs but cannot find.

Category | Misc Forms
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Dialogs
Class | _locateitem
Base Class | Form
Class Library | _dialogs.vcx
Parent Class | _dialog
Sample | ...\Samples\Solution\Ffc\dialogs.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Create Form or Create Form. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. When you add the class to a form, Visual FoxPro displays an Open dialog box so you can specify the name of the form, then creates and opens the form in the Form Designer.

In the cDefaultFileName property, specify the file you want to retrieve. If the file is not located, the oLocateItem object opens a GetFile dialog box so you can locate the file.

Properties, Events, Methods | Description
cDefaultFileName property | The name of the file to locate. Default: .NULL.
cFilename property | The file name retrieved from the Locate button. When no file is found, the GetFile dialog box appears. Default: .NULL.
oLocateItem object | An object reference that contains the return value set to the cFileName property. Default: .F.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Keywords Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
Keywords Dialog Box Foundation Class
See Also

This class creates a dialog box that displays a specified list of keywords, like the Component Gallery keywords dialog box.

Category | Misc Forms
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Dialogs
Class | _keywords
Base Class | Form
Class Library | dialogs.vcx
Parent Class | _dialog
Sample | ...\Samples\Solution\Ffc\dialogs.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Create Form. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. When you drop the class on a project or choose Create a new form from the selected class in the shortcut menu, Visual FoxPro opens a builder so you can specify the name of the form, then creates and opens the form in the Form Designer.

By default, the dialog box uses the Component Gallery Keywords.dbf file. You can specify your own keywords file in the cTablename property. You can also provide a set of keywords in a comma-delimited list in the cKeywords property.

Properties, Events, Methods | Description
cKeywords property | Specifies a group of space-delimited keywords to seek in the table specified in cTablename. Default: ""
cTablename property | Specifies the name of a table that contains keywords. Default: (IIF(VERSION(2)=0,"",HOME( )+"gallery\")+"keywords.dbf"))
oKeywords object | The object that retrieves the list of keywords set to cKeywords property. Default: .F.
Apply method | Displays the keywords specified by the cKeywords property from the table specified in cTablename. Syntax: Apply( ) Return: none Arguments: none
lAddMode property | Internal to the class.
lUpdated property | Internal to the class.
cLastValue property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Launch Button Foundation Class

Visual FoxPro 9.0 Language Reference
Launch Button Foundation Class
See Also

This button launches an application using the RUN command.

Category | Misc Buttons
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | _cmdLaunch
Base Class | CommandButton
Class Library | _miscbtns.vcx
Parent Class | _commandbutton
Sample | ...\Samples\Solution\Ffc\buttons.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the appropriate cFileName value. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
cFileName property | Specifies the name of the file to launch. Default: ""

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Locate Button Foundation Class

Visual FoxPro 9.0 Language Reference
Locate Button Foundation Class
See Also

This button displays a dialog box to locate a record.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _locatebutton
Base Class | CommandButton
Class Library | _table2.vcx
Parent Class | _dialogbutton
Sample | ...\Samples\Solution\Ffc\dataqry.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you add the class to a form, Visual FoxPro places a button that opens the Locate dialog box. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Lookup Combobox Foundation Class

Visual FoxPro 9.0 Language Reference
Lookup Combobox Foundation Class
See Also

This class performs a lookup of values in a field to populate a combobox.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _cbolookup
Base Class | ComboBox
Class Library | _dataquery.vcx
Parent Class | _combobox
Sample | ...\Samples\Solution\Ffc\datalook2.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the appropriate Lookup_table, Order_column, Display_column, and Return_column values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
Display_column property | Specifies the column value from the Lookup_table to display in the drop-down list. Default: ""
Lookup_table property | Specifies the table in which to find the column containing the values to display in the drop down list. Default: ""
Return_column property | Specifies the column value (0, 1 or 2) to return to the Value property of the combo box. Default: ""
Order_column property | Specifies the column to order the records displayed in the drop down list (optional). Default: ""

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Mail Merge Object Foundation Class

Visual FoxPro 9.0 Language Reference
Mail Merge Object Foundation Class
See Also

This custom class uses the Mail Merge Wizard engine to generate a Microsoft Word Mail Merge document.

Category | Automation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Automation
Class | mailmerge
Base Class | Custom
Class Library | mailmrge.vcx
Parent Class | automation
Sample | ...\Samples\Solution\Ffc\Automate.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, specify the FROM table (cDataPath), the location and version of Word (cExe and cWordVersion), and other appropriate properties values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
aWPMrg[2,0] property | An array of procedures for handling various merge styles. Default: .F.
cDataFile property | A FoxPro 2.6 copy of a Visual FoxPro 3.0 or later table. Default: ""
cDataPath property | Specifies the path to the FROM table. Default: ""
cDataSrc property | Specifies the data source for the ODBC connection. Default: ""
cDocName property | Specifies the name of the existing .doc file. Default: ""
cExe property | Specifies the full path to the Microsoft Word application. Default: ""
cODBCSource property | Specifies the ODBC connection string. Default: ""
cSaveFile property | Specifies the file for holding merged data. Default: ""
CSQLstmt property | A SQL statement for extracting data. Default: ""
CSQLstmt2 property | Specifies an additional SQL statement, if cSQLStmt is greater than 255 characters (for Microsoft Word). Default: ""
cWordVersion property | Specifies the version of Microsoft Word that is installed (for example, '8'). Default: ""
lAlerted property | Specifies whether a failure alert was issued. Default: .F.
lEnglish property | Verifies whether Microsoft Word recognizes English Word Basic commands. Default: .F.
lHasVerWord property | Verifies the presence of Microsoft Word. Default: .F.
nNewDoc property | Indicates whether a new document will be used (see Mailmrge.h). Default: 1
nTemplate property | Specifies the main document type. Applies to Microfot Word only. See Mailmrge.h. Default: 1
nWordProc property | Specifies the selected word processor. See Mailmrge.h. Default: 1
SysCh property | Specifies a DDE channel. Default: -1
CheckVer method | Verifies the version of Microsoft Word being used. Internal to the class. Syntax: CheckVer( ) Return: none Arguments: none
GetMSW method | Retrieves the Microsoft Word command line from the registry. Syntax: GetMSW(m.cversion) Return: the full path to Microsoft Word Arguments: m.cversion specifies the version of Microsoft Word being used.
MrgCommaDel method | Generates a comma-delimited text file from data. Syntax: MrgCommaDel( ) Return: a comma-delimited file Arguments: none
MrgWord method | Determines the versions of Microsoft Word to be used in the merge. Syntax: MrgWord( ) Return: none Arguments: none
MSWerr method | The error handler for use while AppleScript is being run. Syntax: MSWerr( ) Return: none Arguments: none
GetSQLst method | Retrieves the SQL statement for extracting data. Internal to the class. Syntax: GetSQLst( ) Return: none Arguments: none
PrepData method | Determines the kind of data source that is being used for the mail merge and normalizes the data for processing, Internal to the class. Syntax: PrepData( ) Return: none Arguments: none
SaveSQL method | Generates a table of SQL results. Internal to the class. Syntax: SaveSQL( ) Return: none Arguments: none
WzMMData method | Copies data to a text file. Internal to the class. Syntax: WzMMData( ) Return: none Arguments: none
MakeFieldList | Internal to the class.
MailMergeWord8 | Internal to the class.
MailMergeWord6 | Internal to the class.
MSWmldlg | Internal to the class.
Startword | Internal to the class.
MailMergeMacWord6 | Internal to the class.
MMCleanup method | Closes files - Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Messagebox Handler Foundation Class

Visual FoxPro 9.0 Language Reference
Messagebox Handler Foundation Class
See Also

This class provides a simple wrapper around the MessageBox function so you can easily display a message box of a specified type with alternate contents.

Category | Misc Forms
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _msgbox
Base Class | Custom
Class Library | _dialogs.vcx
Parent Class | _custom

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, specify the appropriate values for the message (cMessage), the type of message box (nType), and other appropriate properties. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
cMessage property | Specifies the message box message text. Default: ""
nType property | Specifies the message box type. For options, see MessageBox( ). Default: 48
cTitle property | Specifies the message box title text. Default: _screen.caption
lBeep property | Specifies whether a beep occurs when message box is activated. Default: .F.
Show method | Displays a message box and returns the dialog box result. Syntax: Show(tcMessage, tnType, tcTitle, tlBeep) Return: this.Display( ) Arguments: tcMessage specifies the text that appears in the dialog box.tnType specifies the buttons and icons options, the default button, and the behavior of the dialog box.tcTitle specifies the text that appears in the title bar of the dialog box.tlBeep specifies whether an alert sound accompanies the display of the dialog box.
Set method | Sets the properties for the dialog box message, type, title, and alert sound. Internal to the class. Syntax: Set(tcMessage, tnType, tcTitle, tlBeep, tnParameters) Return: none Arguments: tcMessage specifies the text that appears in the dialog box.tnType specifies the buttons and icons options, the default button, and the behavior of the dialog box.tcTitle specifies the text that appears in the title bar of the dialog box.tlBeep specifies whether an alert sound accompanies display of the dialog box.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Microsoft Agent Utility Foundation Class

Visual FoxPro 9.0 Language Reference
Microsoft Agent Utility Foundation Class
See Also

This class gives you access to Microsoft Agent API routines so that you can integrate agents (similar to Office Assistants) such as Peedy the parakeet into your application.

Category | System Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _agent
Base Class | Custom
Class Library | _agent.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\Agent.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
ActiveAgent property | Provides a pointer to the active Agent character object. Default: .F.
AgentControl property | Provides a pointer to the agent object. Default: .F.
ErrorOccurred property | Set to True (.T.) when an error occurs on LOAD. Default: .F.
ErrorState property | Always set to LOAD.
GestureAt method | Causes the active agent to gesture at a given point. Syntax: GestureAt(tnX, tnY, tnCoords, toObj) Return: .F. if there is no ActiveAgent. Arguments: tnX specifies x coordinate.tnY specifies y coordinate.tnCoords whether coordinates are local or world.toObj specifies the object reference for LocalToWorld conversion.
Hide method | Hides the active agent. Syntax: Hide( ) Return: .F. if there is no ActiveAgent. Arguments: none
Interrupt method | Interrupts an animation. Syntax: Interrupt(toRequest) Return: .F. if there is no ActiveAgent. Arguments: toRequest specifies request object.
Load method | Loads an agent character from the specified location (can be a file or URL). Syntax: Load(tcAgentName, tcAgentLocation) Return: .F. if an error occurred. Arguments: tcAgentName specifies name of agent.tcAgentLocation specifies the agent file.
LocalToWorld method | Converts local coordinates to world coordinates. Syntax: LocalToWorld(tnAxis, tnPos, toObj) Return: converted value of tnPos. Arguments: tnAxis specifies the axis.tnPos specifies axis coordinate.toObj specifies object to which conversion is relative.
MoveBy method | Moves the active agent by the passed values in the x or y direction. Syntax: MoveBy(tnX, tnY, tnCoords, toObj) Return: .F. if there is no ActiveAgent. Arguments: tnX specifies x coordinate.tnY specifies y coordinate.tnCoords specifies whether coordinates are local or world.toObj object reference for LocalToWorld conversion.
MoveTo method | Moves the default agent or agent passed to the location specificed. Syntax: MoveTo(tnX, tnY, tnCoords, toObj) Return: .F. if there is no ActiveAgent. Arguments: tnX specifies x coordinate.tnY specifies y coordinate.tnCoords specifies whether coordinates are local or world.toObj object reference for LocalToWorld conversion.
Play method | Causes the active agent to play an animation. Syntax: Play(tcAnimation) Return: .F. if there is no ActiveAgent or a Request Object reference. Arguments: tcAnimation specifies animation to play.
SetActiveAgent method | Sets the active agent to the agent with the passed name. Syntax: SetActiveAgent(tcAgentName) Return: .T. if ActiveAgent is set. Arguments: tcAgentName specifies the name of the agent.
Show method | Displays the active agent. Syntax: Show(tnX, tnY, tnCoords, toObj) Return: .F. if there is no ActiveAgent. Arguments: tnX specifies x coordinatetnY specifies y coordinatetnCoords specifies whether coordinates are local or world.toObj object reference for LocalToWorld conversion.
Speak method | Causes the active agent to speak the passed phrase. Syntax: Speak(tcText) Return: .F. if there is no ActiveAgent or a Request Object reference. Arguments: tcText specifies text to speak.
Stop method | Stops a looping animation. Syntax: Stop( ) Return: .F. if there is no ActiveAgent. Arguments: none
Wait method | Waits for a request to complete. Syntax: Wait(toRequest) Return: .F. if there is no ActiveAgent. Arguments: toRequest specifies the requesting object.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


MouseOver Effects Foundation Class

Visual FoxPro 9.0 Language Reference
MouseOver Effects Foundation Class
See Also

This class highlights a control as the mouse is dragged over it.

Category | User Interface
Default Catalog | Visual FoxPro Catalog\Foundation Classes\User Controls
Class | _mouseoverfx
Base Class | Custom
Class Library | _ui.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\mousefx.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, specify the appropriate values for the highlight (iHighlightColor and nHighlightWidth), and other appropriate properties, then place a reference to the HighlightMe method in the MouseMove event of the control you want to affect. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods Description

nMargin property

Specifies the border between the control and the highlight.

Default: 2

iShadowColor property

Specifies the color code of the shadow.

Default: 0

lMouseoverHost property

Specifies whether the mouse is over the mousefx host.

Default: .T.

nHighlightWidth property

Specifies the width of the highlight.

Default: 2

iHighlightColor property

Specifies the color code of the highlight.

Default: 0

CancelHighlight method

Uses the value of lMouseoverHost to determine whether there is a highlighted object requiring change. Sets oCurrentCoolControl to .NULL. and Returns true (.T.) when lMouseOver indicates that the current control has just changed. Your subclasses can check this return value or the state of lMouseOverHost and oCurrentCoolControl to "subtract" their own special effects from cool controls at the appropriate times.

Syntax: CancelHighlight (toObject)

Return: lChange

Arguments: toObject specifies the object affected upon the MouseOver event. lChange specifies whether the current control has already changed.

HighlightMe method

Sets .oCurrentCoolControl, the current control, to the object reference specified by toObject. Returns true (.T.) when it has to act because the current control has just changed. Returns .F. if it doesn't need to act because there is no change in the current control. Your subclasses can use the oCurrentCoolControl property and the return value of this method to decide when they have to act, providing other special effects, perhaps specific for some special classes of "current controls".

Syntax: HighlightMe(toObject)

Return: lChange

Arguments: toObject specifies the object affected upon the MouseOver event.lChange specifies whether the current control has already changed.

oCurrentCoolControl property

Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Mover Foundation Class

Visual FoxPro 9.0 Language Reference
Mover Foundation Class
See Also

When placed on a project or form, this class provides a simple mover list box class with Move and Remove buttons.

Category | Movers
Default Catalog | Visual FoxPro Catalog\Foundation Classes\User Controls
Class | _mover
Base Class | Container
Class Library | _mover.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Ffc\movers.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class list box controls and move buttons on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
aChoices[1,0] property | The array of available choices in the left list box. Default: .F.
aSelections[1,0] property | The array of selected items in the right list box. Default: .F.
UseArrays property | Specifies whether to use arrays for the list boxes. Defa ult: .T.
InitChoices method | Initializes the choices array. Syntax: InitChoices(@aChoices) Return: none Arguments: aChoices specifies an array of initial choices.
InitSelections method | Initializes the selections array. Syntax: InitSelections(@aSelections) Re turn: none Arguments: aSelections specifies the array of initial selections.
GetSelections method | Retrieves the selected items. Syntax: GetSelections(@aSelections) Return: none Arguments: aSelections specifies the name of the array containing the target selections.
PopList method | The routine to populate list boxes. Syntax: PopList(@aListArray, oLstRef) Return: none Arguments: aListArray specifies the items with which to populate the list.oLstRef is a reference to the control object.
OldlSelectedItem property | Internal to the class.
OldrSelectedItem property | Internal to the class.
SortLeft property | Internal to the class.
Updated property | Internal to the class.
SizeToContainer method | Internal to the class.
ValidItem method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Navigation Shortcut Menu Foundation Class

Visual FoxPro 9.0 Language Reference
Navigation Shortcut Menu Foundation Class
See Also

This is a shortcut menu that can be dropped onto a form with items for common data navigation, sorting, filtering and finding options. You call this class from the RightClick event of a form.

Category | Menus
Default Catalog | Visual FoxPro Catalog\Foundation Classes\User Controls
Class | _navmenu
Base Class | Container
Class Library | _table2.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Ffc\datasort.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro prompts you to automatically add the necessary code to implement the shortcut menu. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cClass property | Specifies the class of the dialog box containing the shortcut menu. Default: ""
cClasslib property | Specifies the class library containing the class of the dialog box containing the shortcut menu. Default: ""
DoMenu method . | Runs a menu routine. Syntax: Domenu( ) Return: none Arguments: none
RefreshForm method | Refreshes the active form when data is updated. Syntax: RefreshForm( ) Return: none Arguments: none
DeleteRecord method | Deletes the current record. Syntax: DeleteRecord( ) Return: none Arguments: none
AddRecord method | Adds a new record. Syntax: AddRecord( ) Return: none Arguments: none
DoFilter method | Displays a filter dialog box. Syntax: DoFilter( ) Return: none Arguments: none
DoGoto method | Displays a GoTo dialog box. Syntax: DoGoto( ) Return: none Arguments: none
DoSort method | Displays a Sort dialog box. Syntax: DoSort( ) Return: none Arguments: none
DoDialog method | Displays a dialog box. Syntax: DoDialog( ) Return: none Arguments: none
SetMenu method | Specifies the menu contents through code containing AddMenuBar( ) expressions. Syntax: SetMenu( ) Return: none Arguments: none
DoFilter2 method | Displays an Advanced Filter dialog box. Syntax: DoFilter2( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Navigation Toolbar Foundation Class

Visual FoxPro 9.0 Language Reference
Navigation Toolbar Foundation Class
See Also

This class provides a set of data navigation buttons and other controls in a toolbar.

Category | Data Navigation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Navigation
Class | _navtoolbarclass
Base Class | Container
Class Library | _table2.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Ffc\datasort.scx

Remarks

To use, drop the class on a project or form in a data environment or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro automatically makes the connections. When you drop the class on a project, you can choose between adding the class or creating a subclass.

This class differs from navigation buttons by providing an output window as well as navigation buttons.

Properties, Events, Methods | Description
oToolbar property | Internal to the class.
cClassLib property | Internal to the class.
cClass property | Internal to the class.
nLastTop property | Internal to the class.
nLastLeft property | Internal to the class.
lDocked property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Object State Foundation Class

Visual FoxPro 9.0 Language Reference
Object State Foundation Class
See Also

This class determines the state of an object. It saves and/or restores object property settings automatically or explicitly.

Category | Application
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Application
Class | _objectstate
Base Class | Custom
Class Library | _app.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\environ.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods Description

aProperties[1,3] property

The array for saving/restoring properties of oObject.

Default: .F.

lAutomatic property

Specifies whether oObject properties are saved and restored. If this attribute is true (.T.), the _ObjectState object will restore all the attributes you've saved for its target object when the _ObjectState object is destroyed.

Default: .F.

oObject

Reference to the target object whose state is being saved.

Default: .NULL.

Restore method

Restores the value of a property for oObject if the value has changed. If tcWhichProperty is not passed, all saved properties of oObject are restored. This method is called with no argument in the _ObjectState.Destroy( ) event when _ObjectState.lAutomatic is true (.T.).

Syntax: Restore(tcWhichProperty)

Return: tcSave

Arguments: tcWhichProperty specifies the property to be restored.tcSave specifies the value to be restored.

Save method

Saves the current value of a property for oObject. You can use this instead of the tlSave argument of the Set method.

Syntax: Save(tcProperty, tcTypeValue)

Return: none

Arguments: tcProperty specifies the property being accessed.tcTypeValue specifies the value being saved for tcProperty.

Set method

Sets a property to a new value for oObject.

Syntax: Set(tcProperty, tvValue, tlSave)

Return: none

Arguments: tcProperty specifies the property to set.tvValue specifies the value tcProperty is to be set to.tlSave specifies whether the current value is retained for later restoration.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


ODBC Registry Foundation Class

Visual FoxPro 9.0 Language Reference
ODBC Registry Foundation Class
See Also

This class provides a set of registry functions that return ODBC-specific information such as drivers and data sources.

Category | System Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _odbcreg
Base Class | Custom
Class Library | registry.vcx
Parent Class | registry
Sample | ...\Samples\Solution\WinAPI\regodbc.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
LoadODBCFuncs method | Loads the ODBC registry functions. Syntax: LoadODBCFuncs( ) Return: none Arguments: none
GetODBCDrvrs method | Retrieves ODBC drivers. Syntax: GetODBCDrvrs(@aDrvrs, lDataSources) Return: nRetVal Arguments: aDrvrs specifies, in an array, the drivers to retrieve.lDataSources specifies whether to access datasources.
EnumODBCDrvrs method | Enumerates through ODBC drivers. Syntax: EnumODBCDrvrs(@aDrvrOpts, cODBCDriver) Return: aDrvrOpts, m.cSourceKey, HKEY_LOCAL_MACHINE, .F. Arguments: aDrvrOpts specifies available driver options.cODBCDriver specifies the driver name.
EnumODBCData method | Enumerates through ODBC data sources. Syntax: EnumODBCData(@aDrvrOpts, cDataSource) Return: aDrvrOpts, m.cSourceKey, HKEY_CURRENT_USER, .F. Arguments: aDrvrOpts specifies available driver options.cDataSource specifies the name of the data source.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Offline Switch Foundation Class

Visual FoxPro 9.0 Language Reference
Offline Switch Foundation Class
See Also

The Offline switch works in a database containing remote views. This class provides a set of buttons that toggle between use of online and offline data.

Category | Data Editing
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _offline
Base Class | Container
Class Library | _dataquery.vcx
Parent Class | container

Remarks

To use, drop the class on a project or form in a data environment or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class buttons on the form, and opens a builder so you can specify lUseCurrentDBC, lAllViews, lUpdateViews, and lRevertOnFail values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cDatabase property | Specifies the name of the database containing views to take offline. Default: .F.
cViews[1,0] property | Specifies the array of views to process. Default: .F.
lAllViews property | Specifies whether to automatically use all views in the database. Default: .F.
lRevertOnFail property | Specifies whether to revert all views if one fails when going offline. Default: .T.
lUpdateViews property | Specifies whether to update all views when going online. Default: .T.
lUseCurrentDBC property | Specifies whether to use the currently opened database at the start. Default: .T.
GoOffLine method | Takes the views specified in the cViews array offline. Syntax: GoOffline( ) Return: none Arguments: none
GoOnLine method | Takes the views specified in the cViews array online. Syntax: GoOnline( ) Return: none Arguments: none
CheckOffLine method | Checks to see if views are currently online/offline. Syntax: CheckOffline( ) Return: none Arguments: none
Alert method | Displays a message box containing cMessage. Syntax: Alert(cMessage) Return: m.cMessage Arguments: cMessage specifies the text of the alert message.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


OK Button Foundation Class

Visual FoxPro 9.0 Language Reference
OK Button Foundation Class
See Also

This class releases a form and updates any outstanding buffered data.

Category | Misc Buttons
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | _cmdOK
Base Class | CommandButton
Class Library | _miscbtns.vcx
Parent Class | _commanbutton
Sample | ...\Samples\Solution\Ffc\buttons.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you add the class to a form, Visual FoxPro places a button on your form. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Output Control Foundation Class

Visual FoxPro 9.0 Language Reference
Output Control Foundation Class
See Also

This class provides controls that prompt you for a reporting output option. Using the Report object, it also allows you to select which report to print.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output
Class | _outputchoices
Base Class | Container
Class Library | _reports.vcx
Parent Class | _output
Sample | ...\Samples\Solution\Ffc\output.scx

Remarks

To use, drop the class on a project or form in a data environment or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class on the form. You can then provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Output Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
Output Dialog Box Foundation Class
See Also

This class uses the Report object to display a dialog box that prompts the user for a reporting output option.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output
Class | _outputdialog
Base Class | Form
Class Library | _reports.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\output.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Create Form. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. If you choose Create a new form, Visual FoxPro opens a builder so you can specify the name of the form, then creates and opens the form in the Form Designer.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cAlias property | Specifies the name of the data source to output. Default: ""
cDestination property | Specifies the list of available destinations that changes dynamically depending on whether cReport, cAlias, or both, contain values. Default: ""
cDisplayFontName property | Specifies the name of an on-screen display of output; for example, when you issue BROWSE or when the _Showtext class is instantiated for text display. Default: .F.
cFieldList property | Specifies a comma-delimited list of fields or expressions. It affects only direct data sources (BROWSEs and LISTs). Default: ""
cHTMLClass property | Specifies an optional HTML class and class library passed to _GENHTML. Default: ""
cHTMLStyleID property | Specifies an optional HTML style passed to _GENHTML. Default: .F.
cReport property | Specifies the name of report or label to output. Default: ""
cScope property | Specifies a valid scope expression for output. Default: .F.
lAddSourceNameToDropdown property | Specifies whether some destinations display in the aDestinations array. Default: .F.
lPreventScopeChanges property | Specifies whether you can change output scope. Default: .F.
lPreventSourceChanges property | Specifies whether source changes for cAlias or cReport are prevented. Default: .F.
cAlias_access method | Internal to the class.
cAlias_assign method | Internal to the class.
cDestination_access method | Internal to the class.
cDestination_assign method | Internal to the class.
cDisplayFontName_access method | Internal to the class.
cDisplayFontName_assign method | Internal to the class.
cFieldList_access method | Internal to the class.
cFieldList_assign method | Internal to the class.
CheckOKButton method | Internal to the class.
cHTMLClass_access | Internal to the class.
cHTMLClass_assign | Internal to the class.
cHTMLStyleID_access | Internal to the class.
cHTMLStyleID_assign | Internal to the class.
cReport_access method | Internal to the class.
cReport_assign method | Internal to the class.
cScope_access method | Internal to the class.
cScope_assign method | Internal to the class.
lAddSourceNameToDropdown_access method | Internal to the class.
lAddSourceNameToDropdown_assign method | Internal to the class.
lPreventScopeChanges_assign method | Internal to the class.
lPreventSourceChanges_access method | Internal to the class.
lPreventSourceChanges_assign method | Internal to the class.
RespondToPermissionForScopeChanges method | Internal to the class.
RespondToPermissionForSourceChanges method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Output Object Foundation Class

Visual FoxPro 9.0 Language Reference
Output Object Foundation Class
See Also

This is a generic reporting object that provides a variety of report source and destination options from reports and labels or directly from a data source.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output
Class | _output
Base Class | Container
Class Library | _reports.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Ffc\output.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item Shortcut Menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
aDestinations[1,2] property | The array of destinations. Default: .F.
aOptions[1,2] property | The array of destination output options. Default: .F.
cAlias property | Specifies the data source that is used for non-report/label output formats. This property defaults to the current alias, if any. Default: ""
cDestination property | Specifies a list of available destinations that changes dynamically, depending on whether cReport, cAlias, or both contain values. The list of available destinations is stored in the aDestinations array. Default: "PRINTREPORT"
cDisplayFontName property | Specifies an on-screen font for output; for example, when you issue BROWSE or when the _Showtext class is instantiated for text display. Default: Courier New
cFieldList property | Specifies a comma-delimited list of fields or expressions. It affects only direct data sources (BROWSEs and LISTs). Default: ""
cHtmlClass property | Specifies an optional HTML class and class library passed to _GENHTML. Default: ""
cHtmlstyleid property | Specifies an optional HTML style passed to _GENHTML. Default: ""
cOption property | Specifies the list of available options that changes dynamically to fit the current cDestination. Default: WINDEFAULT
cReport property | Specifies a label or report form suitable for Visual FoxPro-formatted output. Default: ""
cScope property | Specifies a macro-expanded string to be added to the command that executes the actual output. It must be a valid scope such as "FOR lExpression". Default: ""
cTextfile property | Specifies the file name for all output destinations that go to disk, which include text files, printer-image files, and export formats. Default: ""
cVFPPrinterName property | Specifies the name of the current Visual FoxPro default printer as distinct from the Windows default printer. Default: ""
lAddSourceNameToDropdown property | Specifies whether some destinations display in the aDestinations array. Default: .T.
lPreventSourceChanges property | Prevents source changes for cAlias or cReport. Default: .F.
CopyTable method | Exports a table. Syntax: CopyTable( ) Return: none Arguments: none
GenHTML method | Generates HTML code by calling the Genhtml.prg program. Syntax: GenHTML( ) Return: none Arguments: none
Output method | Specifies the main method that is called to generate output based on settings. Syntax: Output(liSelect) Return: none Arguments: liSelect specifies the output destination.
OutputToScreen method | Outputs to the screen. Syntax: OutputToScreen( ) Return: none Arguments: none
SetDestinations method | Evaluates the current environment to populate an array of output destinations. Syntax: SetDestinations( ) Return: lSuccess Arguments: none
SetOptions method | Evaluates the current environment to populate an array of options for output destinations. Syntax: SetOptions( ) Return: lSuccess Arguments: none
cAlias_assign method | Internal to the class.
cDestination_assign method | Internal to the class.
cDisplayFontName_assign method | Internal to the class.
cOption_assign method | Internal to the class.
cReport_assign method | Internal to the class.
cScope_assign method | Internal to the class.
cVFPPrinterName_access method | Internal to the class.
lPreventSourceChanges_assign method | Internal to the class.
PrintList method | Internal to the class.
PrintReport method | Internal to the class.
SetOutputPrinter method | Internal to the class.
SetVFPPrinter method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Password Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
Password Dialog Box Foundation Class
See Also

This class is a simple password login dialog box for custom applications.

Category | Misc Forms
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Dialogs
Class | _login
Base Class | Form
Class Library | _dialogs.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\dialogs.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Create Form or Add to Project. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. If you choose Create a new form from the selected class, Visual FoxPro opens a builder so you can specify the name of the login form, then creates and opens the form in the Form Designer.

Properties, Events, Methods | Description
cAlias property | Specifies the alias of the password table. Default: ""
cFieldName property | Specifies the name of field containing the user name. Default: ""
cPassword property | Specifies the name of the field containing the user password. Default: ""
cTable property | Specifies the name of table containing the user password information. Default: ""

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Pool Manager Foundation Class

Visual FoxPro 9.0 Language Reference
Pool Manager Foundation Class
See Also

The Pool Manager Foundation Class manages a pool, or collection, of objects from a single class. When you need to use an object repeatedly for a short time, use the Pool Manager class.

Category | Class information
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Application
Class | _poolmanager
Base Class | Custom
Class Library | _poolmanager.vcx
Parent Class | Custom
Sample | ...\Samples\Solution\Ffc\_PoolManager.scx

Remarks

This class works best if creating an instance of the object takes more time than obtaining an existing instance. This is commonly the case for the following types of classes:

  • Non-lightweight classes like the Visual FoxPro Form class.

  • Classes that contain resource-intensive code in the Init event of the form.

  • Classes that make use of external resources such as a database connection, automation server, or XML Web service.

You can add the Pool Manager class to the Form or Class designers from the Toolbox or to a project. When you add the Pool Manager class to a project, you can add the class or create a subclass.

The Pool Manager class uses the Visual FoxPro Collection base class for storing object references. For more information, see Collection Class.

For more information on using foundation classes, see Guidelines for Using Visual FoxPro Foundation Classes.

Properties, Events, Methods Description

cClass property

Name of the pooled class. You can also set this property by passing it as the first parameter when creating the pool manager object.

Default: None

cClassLibrary property

Library that contains the pooled class. The cClassLibrary property can point to a visual class library or a program file.

You can change this property by passing it as the second parameter when creating the pool manager object.

Default: None

lRaiseEvent property

If True (.T.), raises the ObjectRequested and ObjectReturned events. If you do not need these events to increase performance, set this property to False (.F.).

Default: .T.

nObjectsCreated property

Incremented each time an object is created

Default: 0

Get method

Returns an object reference to a pooled object. All parameters are passed to the Init event of a newly created object and the ObjectRequested event.

Syntax: Get( Param1, Param2, ...)

Return: Object

Arguments: Must pass parameters by value and cannot pass arrays to a pooled object.

Free method

Returns an object to the pool, making it available to the next Get method call.

Syntax: Free(@oObject)

Return: None

Arguments: oObject is an object reference previously obtained from the Get method. The object can be passed by reference.

ObjectRequested event

Raised when an object is requested.

You can use this event to initialize an object based on the current parameters. When a pooled object binds to this event, the event is raised for every object, not just the object itself.

Syntax: ObjectRequested( oObject, Param1, Param2, ...)

Return: None

Arguments: oObject is a reference to the pooled object that is returned to the caller. All parameters from the Get method are passed to this event as additional parameters.

ObjectReturned event

Raised when an object is returned to the pool by calling the Free method. When a pooled object binds to this event, the event is raised for every object, not just the object itself.

Syntax: ObjectReturned(oObject)

Return: None

Arguments: oObject is a reference to the pooled object.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Pool Manager Sample
Foundation Class Samples


Pivot Table Foundation Class

Visual FoxPro 9.0 Language Reference
Pivot Table Foundation Class
See Also

This Custom class uses the PivotTable Wizard engine to generate an Excel pivot table from FoxPro data.

Category | Automation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Automation
Class | pivottable
Base Class | Custom
Class Library | pivtable.vcx
Parent Class | automation
Sample | ...\Samples\Solution\Ffc\Automate.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form in a data environment, Visual FoxPro opens a builder so you can specify the cPivFldCol, cPivFldRow, cPivFldPage, cPivFldData, lHasColumnTotals, and lHasRowTotals values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
CheckState property | Specifies whether to test the state of Microsoft Excel through an error routine. Default: .F.
cOutfile property | Specifies the name of the output file. Default: ""
cPivFldCol property | Specifies the name of the field that identifies each pivot table column. Default: ""
cPivFldData property | Specifies the name of the field reported as pivot table data. Default: ""
cPivFldPage property | Specifies the name of the field that determines the pivot table pages. Default: ""
cPivFldRow property | Specifies the name of the field whose values identify each pivot table row. Default: ""
lHasColumnTotals property | Specifies whether to total columns. Default: .F.
lHasRowTotals property | Specifies whether to total rows. Default: .F.
nAction property | Specifies the output action to perform. Output action: Default: 1
GetXLPath method | Queries the registry for the existence of Microsoft Excel. Syntax: GetXLPath( ) Return: none Arguments: none
MSQueryCheck method | Queries the registry for the existence of MS Query. Syntax: MSQueryCheck( ) Return: none Arguments: none
PivotOutput method | Creates a Microsoft Excel pivot table output. Syntax: PivotOutput( ) Return: none Arguments: none
aFldList[1,1] property | Internal to the class.
cFormName property | Internal to the class.
cFormSCX property | Internal to the class.
CheckFldLen method | Internal to the class.
GetDOSName method | Internal to the class.
lHasMSQry32 property | Internal to the class.
lHasNoTask property | Internal to the class.
lIsNumeric property | Internal to the class.
SkipError property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Preview Report Foundation Class

Visual FoxPro 9.0 Language Reference
Preview Report Foundation Class
See Also

This class provides a generic button to run a report directly or through the Output dialog box class.

Category | Misc Buttons
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | _cmdRunReport
Base Class | CommandButton
Class Library | _miscbtns.vcx
Parent Class | _commandbutton
Sample | ...\Samples\Solution\Ffc\buttons.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify the cFileName and lSetCaption values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cDialogClass property | Specifies the output dialog box class. Default: _OutputDialog
cDialogClasslib property | Specifies the output dialog box class library. Default: (IIF(VERSION(2)=0,"",HOME( )+"FFC\")+"_REPORTS.VCX"))
cFilename property | Specifies the name of the form to run. Default: ""
cOutputDialogAlias property | Specifies the name of the output dialog box alias. Default: ""
lOutputDialogPreventScope property | Specifies whether to prevent changing the scope in dialog box. Default: .F.
lOutputDialogPreventSource property | Specifies whether to prevent changing the alias/report in dialog box. Default: .F.
lPromptForReport property | Specifies whether to ask for a report name. Default: .T.
lSetCaption property | Specifies whether caption is automatically based on the value of cFilename. Default: .T.
lUseOutputDialog property | Specifies whether to display the foundation class Output dialog box. Default:.T.
ShowOutputDialog method | Displays the foundation class Output dialog box. Syntax: ShowOutputDialog( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples
Output Dialog Box


QBF Foundation Class

Visual FoxPro 9.0 Language Reference
QBF Foundation Class
See Also

This class provides a button set for Query-By-Form querying.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _qbf
Base Class | Container
Class Library | _dataquery.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Forms\qbf.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the QBF command buttons on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
QBF_Table property | Specifies the table on which to run the query. Default: ""
ParseCondition( )method | Specifies a filter based on a query. Syntax: ParseCondition(cCondition, cControlSource) Return: lcRetCondition Arguments: cControlSource specifies the data bound to the control.cCondition specifies the query expression.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Registry Access Foundation Class

Visual FoxPro 9.0 Language Reference
Registry Access Foundation Class
See Also

This class provides access to information in the Windows Registry.

Category | System Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | registry
Base Class | Custom
Class Library | registry.vcx
Parent Class | registry
Sample | ...\Samples\Solution\WinAPI\regfox.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
CloseKey method | Closes a registry key. Syntax: CloseKey( ) Return: none Arguments: none
DeleteKey method | Deletes a registry key. Syntax: DeleteKey(nUserKey, cKeyPath) Return: none Arguments: nUserKey specifies the Registry User key.cKeyPath specifies the Registry User key path.
DeleteKeyValue method | Deletes a value from a registry key. Syntax: DeleteKeyValue(cOptName, cKeyPath, nUserKey) Return: none Arguments: cOptName specifies the name of the Registry key option.cKeyPath specifies the path to the Registry key.nUserKey specifies the User key.
EnumKeys method | Enumerates through a registry key. Syntax: EnumKeys(@aKeyNames) Return: none Arguments: aKeyNames specifies the Registry keys to enumerate.
EnumKeyValues method | Enumerates through values of a registry key. Syntax: EnumKeyValues(@aKeyValues) Return: none Arguments: aKeyValues specifies the Registry User key values to enumerate.
EnumOptions method | Enumerates through all entries for a key and populates an array with values. Syntax: EnumOptions(@aRegOpts, cOptPath, nUserKey, lEnumKeys) Return: none Arguments: aRegOpts specifies the Registry key option.cOptPath specifies the path to the Registry key option.nUserKey specifies the User key ID. lEnumKeys specifies whether to enumerate other options, if they exist.
GetKeyValue method | Returns the value for a key. Syntax: GetKeyValue(cValueName, cKeyValue) Return: none Arguments: cValueName specifies the name of the value to retrieve.cKeyValue specifies the value of cValueName.
GetRegKey method | Returns a registry key setting. Syntax: GetRegKey(cOptName, cOptVal, cKeyPath, nUserKey) Return: none Arguments: cOptName specifies the name of the Registry key option.cOptVal specifies the value to apply to the option.cKeyPath specifies the Registry key path.nUserKey specifies the User key.
IsKey method | Returns whether a specified key exists. Syntax: IsKey(cKeyName, nRegKey) Return: none Arguments: cKeyName specifies the name of the user key to check, if it exists.nRegKey specifies the Registry key ID
OpenKey method | Opens a registry key. Syntax: Open(cLookUpKey, nRegKey, lCreateKey) Return: none Arguments: cLookUpKey specifies the name of the user key for which to search.nRegKey specifies the Registry key ID.lCreateKey specifies whether to create a new Registry key if the specified one does not exist.
SetKeyValue method | Sets the value of a registry key. Syntax: SetKeyValue(cValueName, cValue) Return: none Arguments: cValueName specifies the name of the value to set.cValue specifies the value to apply to cValueName.
SetRegKey method | Sets the registry key setting. Syntax: SetRegKey(cOptName, cOptVal, cKeyPath, nUserKey) Return: none Arguments: cOptName specifies the name of the Registry key option.cOptVal specifies the value to apply to the option.cKeyPath specifies the Registry key path.nUserKey specifies the User key ID.
cAppPathKey property | Internal to the class.
cIniDllFile property | Internal to the class.
cODBCDllFile property | Internal to the class.
cRegDllFile property | Internal to the class.
cVfpOptPath property | Internal to the class.
lCreateKey property | Internal to the class.
lHadError property | Internal to the class.
lLoaddedDlls property | Internal to the class.
lLoadedInis property | Internal to the class.
lLoadedOdbcs property | Internal to the class.
nCurrentKey property | Internal to the class.
nCurrentOS property | Internal to the class.
nUserKey property | Internal to the class.
LoadRegFuncs method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Regular Expressions Foundation Class

Visual FoxPro 9.0 Language Reference
Regular Expressions Foundation Class
See Also

Regular expressions are a concise and flexible notation for finding and replacing patterns of text. The Regular Expressions class gives you access to routines for using regular expressions in your applications.

Category | System Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _regexp
Base Class | Custom
Class Library | _regexp.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\Regexp.scx

Remarks

For information about the sample, see Search Text Using Regular Expressions. For general details about regular expressions, you can refer to MSDN.

To use the Regular Expressions Foundation Class, drop the class on a project or form, or from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
Matches array | Specifies the array containing the results of the string test. Default: .F.
Pattern property | Contains the pattern (regular expression). Default: *
Clear method | Clears all values. Syntax: Clear( ) Return: none Arguments:
Execute method | Tests the pattern against the string. Syntax: Execute(tcStr, tlCaseMatters) Return: number of matches Arguments: tcStr specifies string to search.tlCaseMatters specifies whether to ignore case.

See Also

Reference

Visual FoxPro Foundation Classes A-Z

Concepts

Guidelines for Using Visual FoxPro Foundation Classes

Other Resources

Foundation Class Samples


ReportListener Foundation Classes

Visual FoxPro 9.0
ReportListener Foundation Classes
See Also

The Visual FoxPro 9 Report System includes a number of new features designed for extensibility, including a new ReportListener base class. When you use ReportListener-based classes, the Visual FoxPro Report Engine executes your REPORT FORM or LABEL FORM command in a new, object-assisted, reporting mode.

The classes in the _REPORTLISTENER.vcx Foundation Class Library showcases these features, and provide easy access to the derived ReportListener classes delivered with the Report Output Application.

The ReportListener-based classes in this class library are identical to the classes built into the Report Output Application. However, they do not rely on REPORTOUTPUT.APP. When you want to leverage these classes in applications, you can include the _REPORTLISTENER.vcx class library from the Foundation Class (FFC) folder into your project and be assured that you have all the necessary files.

Tip:
Some of the classes in this library utilize helper classes you will find in a companion library, _FRXCURSOR.vcx, also included in the Foundation Class folder. When you build _REPORTLISTENER.vcx into your application, the Project Manager will take note of the reference to the _FRXCURSOR class library and include the appropriate files automatically.

In This Section

Class | Description
ReportListener Base Foundation Class | This class, _ReportListener, serves as the superclass for the other classes in _REPORTLISTENER.vcx, and provides core services, similar to the superclasses for other Visual FoxPro base classes available in _BASE.vcx.
ReportListener Utility and File-handling Foundation Class | The UtilityReportListener class provides run-time configuration options and file-handling.
ReportListener User Feedback Foundation Class | The UpdateListener class provides user feedback during report runs. The Report Output Application uses UpdateListener as its designated default ReportListener class for Print and Preview output (ListenerType values 0 and 1).
ReportListener XML Foundation Class | The XmlListener class provides XML output from a report run. The Report Output Application uses XmlListener as its designated default ReportListener class for XML output (ListenerType value 4).
ReportListener XML Display-Style Foundation Class | XmlDisplayListener tunes XmlListener's XML settings suitably for presentation output needs, and adds image-file-publishing functionality.
ReportListener HTML Foundation Class | HtmlListener applies custom specifications for HTML production to XmlDisplayListener's XML output. The Report Output Application uses HtmlListener as its designated default ReportListener class for HTML output (ListenerType value 5).
ReportListener Debug Foundation Class | The DebugListener class provides debugging output to help developers understand what happens during an object-assisted report run.

Related Sections

Extending Report Functionality in Visual FoxPro

Understanding the Report Output Application

Using VFP Report Output XML

See Also

Reference

Genhtml.prg
FRX Cursor Foundation Class
FRX Device Helper Foundation Class

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


ReportListener Base Foundation Class

Visual FoxPro 9.0
ReportListener Base Foundation Class
See Also Example

The _ReportListener class serves as the superclass for the other classes in _REPORTLISTENER.VCX, similar to the superclasses for other Visual FoxPro base classes available in _BASE.VCX.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners
Class | _ReportListener
Base Class | ReportListener
Class Library | _REPORTLISTENER.vcx
Parent Class | ReportListener (ReportListener Object)

Remarks

_ReportListener adds error handling similar to the _BASE classes and includes other core features specific to the responsibilities of ReportListener objects assisting the Report Engine during execution of a REPORT FORM or LABEL FORM command.

These responsibilities include:

  • DataSession handling. Object-Assisted Reporting requires potential manipulation of several different datasessions.

  • Assessment of report state. _ReportListener gives its descendant classes the ability to determine whether certain operations are safe to perform at a given moment. For example, during a report run, it is not safe to switch between different printers.

  • Chain of responsibility. _ReportListener implements a Chain of Responsibility pattern, also known as successorship, to allow multiple output formats during one report run.

  • Management of multiple reports. You can use _ReportListener as an object oriented wrapper for a REPORT FORM command or a collection of REPORT FORM commands in a sequence.

The following table lists public properties and methods added by this class to its parent class, ReportListener.

Properties and methods Description

addReport Method

Adds to the class's collection of ReportFileNames, optionally associating REPORT FORM clauses and a ReportListener for the specified report.

Syntax: addReport(cFRXName [, cClauses[, toListener]])

Return Values: None

Parameters:

cFRXName provides the name of the report or label file to run.

cClauses provides the optional clauses for this report run, including scope, range, and windowing instructions.

oListener provides an optional reference to be added by _ReportListener when executing this specific report.

appName Property

Holds an application name string for use in user feedback.

Default "VFP Report Listener"

Remarks: See REPORTLISTENERS_LOCS.H, which provides the localizable value to which this property is set in the class' Init method. Descendent classes in _REPORTLISTENERS.vcx override this setting with additional #DEFINEd values in REPORTLISTENERS_LOCS.H.

clearErrors Method

Resets the class's error status.

Syntax: clearErrors()

Return Values: None

Parameters: None.

Remarks: Some subclasses may not function normally after a report run fails. This method is useful for re-setting the state of _ReportListener before a subsequent report run.

getLastErrorMessage Method

Provides information about the last error that occurred.

Syntax: getLastErrorMessage()

Return Values: cErrorMessage

Parameters: None.

isSuccessor Property

Indicates whether this ReportListener is chained to one or more others to provide output during a report run. When .T., this ReportListener was not the object referenced in the REPORT FORM command OBJECT clauses.

Default .F.

lIgnoreErrors Property

Provides a flag to determine how this class handles activities subsequent to an error.

Default .F.

Remarks: This property ensures that _ReportListener and its descendant classes follow the _BASE error handling model.

prepareErrorMessage Method

Organizes common error information values (nError, cMethod, nLine, cName, cMessage, cCodeLine) into a coherent string for presentation to the user.

Syntax: prepareErrorMessage(nError, cMethod, nLine, cName, cMessage, cCodeLine)

Return Values: cErrorMessage

Parameters:

You can derive all the parameters to this method except cName from native Visual FoxPro error-handling functions or the equivalent properties of an object of Exception Class (Visual FoxPro). The cName parameter represents the name you would like to present in the error message string as identifying your application.

For example:

Copy Code
LOCAL oListener, oError
oListener = ;
NEWOBJECT("_ReportListener", ;
   "_REPORTLISTENER")
TRY
 * … run some commands here
CATCH TO oError
   IF NOT (ISNULL(oError))
      oListener.DoMessage(;
        oListener.PrepareErrorMessage(;
            oListener.ErrorNo, ;
            oListener.Procedure, ;
            oListener.LineNo, ;
            "My application", ;
            oError.Message, ;
            oError.LineContents))
   ENDIF
FINALLY
   * more commands here
ENDTRY

removeReports Method

Removes report filenames as well as associated clauses and ReportListener references from this class's various collections.

Syntax: removeReports()

Return Values: None

Parameters: None.

reportUsesPrivateDataSession Property

Provides a flag to indicate whether this report shares the data session from which it was executed or maintains a private data session.

Default .F.

runReports Method

Executes a series of REPORT FORM commands according to the instructions in the internal ReportFileNames, ReportClauses, and ReportListeners collections. Optionally clears collection after run and issues the REPORT FORM commands without OBJECT references. Syntax:.runReports([lRemoveReportsAfterRun[, lOmitListenerReferences]])

Return Values: None

Parameters:

lRemoveReportsAfterRun determines whether the class's internal collection of reports is cleared after the runReports method executes its sequence of REPORT FORM commands.

lOmitReferences determines whether the method includes OBJECT references on each REPORT FORM command.

Remarks: Specifying .T. as the second argument to this method takes precedence over any ReportListener reference the method might otherwise add to your REPORT FORM commands unilaterally. However, it does not necessarily mean your reports will run without ReportListener assistance. If you have used the command SET REPORTBEHAVIOR 90 before using this method, the Report Engine will still get a reference to a ReportListener of the appropriate type from Report Output Application and add it to your REPORT FORM commands. You may also have specified the OBJECT clause for one or more REPORT FORM commands when you added these commands into _ReportListener's collection of reports to run.

If you did not specify tlOmitReferences as .T., _ReportListener checks each REPORT FORM command before executing it to see if you have already included an OBJECT clause in your command. If you have done so, your OBJECT clause takes effect; ReportListener you have specified will be the object reference used for this command.

If you have not included an OBJECT clause, you may have stored in its internal ReportListener collection when you added this REPORT FORM command to its internal collection. _ReportListener adds this reference to your REPORT FORM command if necessary.

If you have not specified a ReportListener when adding the report, and have not specified lOmitReferences as .T.,_ReportListener adds a reference to itself in an OBJECT <ref> clause in the REPORT FORM command.

setSuccessorDynamicProperties Method

Provides a hook for the class to share information changed by the Report Engine with a succession of ReportListeners during a report run.

Syntax: setSuccessorDynamicProperties()

Return Values: None

Parameters: None.

Remarks: Abstract at this class level.

sharedGdiplusGraphics Property

Provides a read/write copy of the Engine's GDIPlusGraphics handle which the ReportListener can share with a succession chain.

Default 0

sharedOutputPageCount Property

Provides a read/write copy of the Engine's OutputPageCount property which the ReportListener can share with a succession chain.

Default 0

sharedPageHeight Property

Shares information gathered by the GetPageHeight method with other ReportListeners linked in a succession chain.

Default 0

sharedPageNo Property

Provides a read/write copy of the Engine's PageNo property which the ReportListener can share with a succession chain.

Default 0

sharedPageTotal Property

Provides a read/write copy of the Engine's PageTotal property which the ReportListener can share with a succession chain.

Default 0

sharedPageWidth Property

Shares information gathered by the GetPageWidth method with other ReportListeners linked in a succession chain.

Default 0

successor Property

Stores an object reference to the next ReportListener in a succession chain.

Default .NULL.

Remarks: See the topic on UpdateListener (ReportListener User Feedback Foundation Class) for an example of ReportListeners in a succession chain.

Example

The following code example shows how you can use _ReportListener to manage a collection of REPORT FORM commands. XmlListener is a subclass of _ReportListener, so it can use this capability. In this example, you chain two reports together to generate a single XML document.
Copy Code
LOCAL ox
ox = NEWOBJECT("XmlListener","_ReportListener")
ox.AddReport(GETFILE("frx"),"NOPAGEEJECT")
ox.AddReport(GETFILE("frx")
ox.RunReports(.T.)

See Also

Reference

ReportListener Object

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


ReportListener User Feedback Foundation Class

Visual FoxPro 9.0
ReportListener User Feedback Foundation Class
See Also Example

This class provides user-configurable feedback during the report runs. . The Report Output Application uses UpdateListener as its designated default ReportListener class for Print and Preview output (ListenerType values 0 and 1).

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners
Class | UpdateListener
Base Class | ReportListener
Class Library | _REPORTLISTENER.vcx
Parent Class | _ReportListener (ReportListener Base Foundation Class)

Remarks

UpdateListener's design has the following goals:

  • Ease of localization and customization. All the captions and messages UpdateListener displays during a report run, as well as the dimensions of its display window are exposed as public properties. UpdateListener dynamically validates any changes you make to its base configuration and adjusts its display elements to match.

  • Sophisticated feedback information about the report in progress. UpdateListener overrides the base ReportListener.UpdateStatus calls, which occur on each page, to display more finely-tuned information about report progress according to the report scope. Its feedback mechanism distinguishes between the initial calculation pass and the subsequent rendering pass, using the ReportListener.TwoPassProcess and ReportListener.CurrentPass properties. For more information, see ReportListener Object Properties, Methods, and Events.

  • Availability of report timing information. UpdateListener uses its reportStartRunDatetime and reportStopRunDatetime properties to display optional timing information during a report run, but you can also use them after the conclusion of the report run.

  • Ability to pause and continue report runs. UpdateListener handles Escape presses during report runs for this purpose during report runs. It saves and restores your keypress-handling code appropriately.

  • No dependencies on external classes. UpdateListener uses a single protected method, createTherm(), to create its feedback display window. There are no external library forms or classes; this class creates and configures the window entirely within the code of the createTherm() method.

Note:
This design goal stems from Report Output Application's use of UpdateListener as the default ReportListener for the traditional output formats for reports and labels (Print and Preview). Your subclass can override createTherm() and adapt the DoStatus() method code that writes to it.

The following table lists public properties added by this class to its parent class, _ReportListener. UpdateListener adds no public methods.

Properties Description

includeSeconds Property

Indicates whether the default user feedback message should include timing data.

Default .T.

initStatusText Property

Provides the user message shown when user feedback first appears.

Default "Initializing... "

Remarks: See REPORTLISTENERS_LOCS.H, which provides the localizable value to which this property is set in the class' Init method.

prepassStatusText Property

Provides a user feedback message for use when the report is in a pre-generation pass to calculate _PAGETOTAL.

Default "Running calculation prepass... "

Remarks: See REPORTLISTENERS_LOCS.H, which provides the localizable value to which this property is set in the class' Init method.

reportStartRunDatetime Property

A datetime value indicating when the last report generation run began.

Default DTOT({})

reportStopRunDatetime Property

A datetime value for use at the conclusion of a report run, empty during a report, storing when the last report generation run ended.

Default DTOT({})

runStatusText Property

Provides a user message shown during the course of a report run.

Default "Creating output..."

Remarks: See REPORTLISTENERS_LOCS.H, which provides the localizable value to which this property is set in the class' Init method.

secondsText Property

Provides the text message included to describe the time value in the default user feedback message during a report, when IncludeSeconds is .T.

Default SPACE(1) + "secs "

Remarks: See REPORTLISTENERS_LOCS.H, which provides the localizable value to which this property is set in the class' Init method.

thermCaption Property

Holds an evaluated expression for use in the user feedback message shown during a report run. If this expression includes "cMessage," the contents of the argument provided to DoStatus will be included in the result of the evaluation. This value overlays UpdateListener's progress bar.

Default [cMessage+ " "+ TRANSFORM(INT(THIS.PercentDone*100)) + "%" + IIF(NOT THIS.IncludeSeconds, "" , " "+TRANSFORM(IIF(THIS.IsRunning,DATETIME(), THIS.ReportStopRunDateTime)-THIS.ReportStartRunDateTime)+" " + THIS.SecondsText)]

Remarks: When you adjust this value, UpdateListener attempts to evaluate a result, including a "dummy" value for cMessage if necessary. If it cannot evaluate your result at the time you set the value of the property, it will retain the previous value.

thermFormCaption Property

Holds the value used to set the title of the user feedback form.

Default ""

Remarks: UpdateListener evaluates this value at the start of each report run. If you have set it to a non-empty value, UpdateListener does not adjust your setting.

If you do not supply a value, UpdateListener sets the value using the ReportListener.PrintJobName property. If its PrintJobName property is empty, it uses ReportListener.CommandClauses.File, the name of the running report file, instead. To the resulting value it adds a localizable string, by default "Press Esc to cancel... ", to indicate the user's ability to pause or cancel the report with this keystroke.

thermFormHeight Property

Holds the height of the user feedback form, in pixels.

Default 40

thermFormWidth Property

Holds the width of the user feedback form, in pixels.

Default 356

thermMargin Property

Holds the value (in pixels) used to determine the difference between the size of the user feedback window and the thermometer bar it displays.

Default 5

Example

The following example turns off the default feedback for an HTMLListener and chains it together with an UpdateListener for the same user feedback you would get for printing or previewing by default.

The code adjusts the feedback form's caption and instructs UpdateListener not to include seconds in the user feedback for this report. Then it briefly shows the feedback form, so you can check the results of these changes, using UpdateListener.initStatusText to supply a message.

The example code then runs a report, showing UpdateListener's feedback form to update the user about progress as the HTML file is generated.

After the report run, the code brings up the HTML file in a VisualFoxPro window for quick verification. It displays the timing results of the report run, leveraging _ReportListener's augmented version of the ReportListener.DoMessage method and HtmlListener.AppName to provide a title for the message window.
Copy Code
LOCAL oUpdate, oHtml
* create the ReportListeners:
oHtml = NEWOBJECT("HtmlListener","_REPORTLISTENER.VCX")
oUpdate = NEWOBJECT("UpdateListener","_REPORTLISTENER.VCX")

* customize them both:

oHtml.QuietMode = .T.

oUpdate.ThermFormCaption = "My Listener Demo"
oUpdate.IncludeSeconds = .F.
oUpdate.DoStatus(oUpdate.initStatusText)
WAIT WINDOW TIMEOUT 3 "Notice the window title... "

* make one the successor of the other:
oHtml.successor = oUpdate

* run the report:
REPORT FORM ? OBJECT oHtml

* show results:
MODIFY FILE (oHtml.TargetFileName) NOWAIT
oUpdate.DoMessage("Total Report Time: "  + ;
                  TRANSFORM(oUpdate.reportStopRunDatetime - ;
                            oUpdate.reportStartRunDatetime) + ;
                  Update.secondsText,0,oHTML.appName )

See Also

Reference

ReportListener Base Foundation Class
ReportListener Object

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


ReportListener Utility and File-handling Foundation Class

Visual FoxPro 9.0
ReportListener Utility and File-handling Foundation Class
See Also

The UtilityReportListener class adds run-time configuration options and file handling (filename verification, file writing) to the core services provided by its parent class, _ReportListener. This class also supplies access to an instance of FrxCursor, a class leveraged from the Report Builder Application, with appropriate error handling if it cannot be found.

Note:
UtilityReportListener does not require FrxCursor to function; it just provides transparent management of an instance of this class when requested by a subclass. It is up to subclasses to decide when and if they need this instance, and whether or not they can survive its absence if it is not available at run time.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners
Class | UtilityReportListener
Base Class | ReportListener
Class Library | _REPORTLISTENER.vcx
Parent Class | _ReportListener (ReportListener Base Foundation Class)

UtilityReportListener and its Configuration Table

UtilityReportListener reads records from a configuration table to initialize various ReportListener values and behavior. You can choose to have UtilityReportListener perform these tasks when the class initializes, at the start of each report run, or both. You can also call its setConfiguration method explicitly at other times.

UtilityReportListener's run-time configuration features leverage the same configuration table format as the Report Output Application uses to register custom ReportListeners for different ListenerType values. For information about how the Report Output Application uses this table, see Report Output Application.

Note:
The classes use the same configuration table format as Report Output Application, but not necessarily the same table. To determine the behavior you want for an instance of a class deriving from UtilityReportListener, use the properties and methods of the class to specify that behavior in the table the object uses, not the table Report Output Application uses.

If you instantiate this class outside the Report Output Application, and if the configuration table does not appear to be available, it creates the appropriate table structure. If the class is built into a module (APP, DLL, EXE), it creates this table in the same directory as the module; otherwise, it will create the table in the same directory as the class library (VCX).

UtilityReportListener and its subclasses use the OBJTYPE field in the configuration table to determine which records belong to them, and to what use the records should be put. These classes reserve a range of values in the OBJTYPE field, set at 1000 to 1999.

Each subclass uses a single value in this range, determined by UtilityReportListener's configurationObjType property, to designate records in the table it wishes to use for configuration purposes. UtilityReportListener uses a constant value in REPORTLISTENER.H to set its own value.

Configuration tasks can set any property or invoke any method in your UtilityReportListener subclass. Records in the configuration table with the correct configurationObjType value set class properties or invoke class method code according to the following configuration table usage.

Field | Usage | Remarks
OBJTYPE | THIS.ConfigurationObjType | Determines which records in the table UtilityReportListener reads to set configuration values or trigger configuration method code.
OBJCODE | Precedence | Determines the order in which UtilityReportListener executes the configuration records' instructions.
OBJNAME | Property or Method | UtilityReportListener checks OBJNAME for PEMSTATUS (existence and type).
OBJVALUE | Value or Arguments | If the OBJNAME value is a valid property name, UtilityReportListener uses this code to set the property value using OBJVALUE: STORE EVAL(ObjValue) TO (“THIS.”+ObjName) If the OBJNAME value is a valid method name for the class, UtilityReportListener executes this code: EVAL(“THIS.”+ObjName+”(“+ObjValue+”)”
OBJINFO | Not used | Reserved for user docs, comments. See the Tip below for an example.

UtilityReportlistener ignores records with blank OBJNAME or OBJVALUE, and records marked DELETED(), whether they have the correct OBJTYPE value or not.

Tip:
When UtilityReportListener generates a configuration table it provides two deleted records to show proper syntax for configuration records, using the following code:

Copy Code
INSERT INTO (ALIAS()) VALUES ;
  (OUTPUTCLASS_OBJTYPE_CONFIG,0,
   'DoMessage','"Welcome to the demo run!",64',
   'Sample initialization/config method call')
DELETE NEXT 1
INSERT INTO (ALIAS()) VALUES ;
  (OUTPUTCLASS_OBJTYPE_CONFIG,0,
   'TargetFileName','"xxx"',
   'Sample initialization/config property')
DELETE NEXT 1

Remarks

You will probably not instantiate this class directly; you will instantiate one of the classes that derive from it, such as HtmlListener. These derived classes take advantage of UtilityReportListener's base features, which are file-handling and access to an FrxCursor object instance. They also expose UtilityReportListener's configuration table feature so you can customize their behavior at run time, in many cases, without needing to specify these changes in your code or deriving subclasses from them.

The following table lists public properties and methods added by this class to its parent class, _ReportListener.

Properties and methods Description

configurationObjtype Property

Holds the reserved value used to indicate that a configuration table row provides dynamic configuration information at run time.

Default 1000

createConfigTable Method

Creates a configuration table on demand.

Syntax: createConfigTable(cDBF [, lOverWrite] )

Return Values: cDBF

Parameters:

cDBF is the fully-qualified filename of the configuration table.

lOverWrite indicates whether you want to overwrite the configuration table if it already exists.

frxCursor Property

Holds a reference to an FRXCursor helper object to aid in run-time calculations related to FRX metadata and structure.

Default .NULL.

getConfigTable Method

Assesses and provides the name of the current configuration table, optionally creating it on disk if it is not available.

Syntax: getConfigTable(lForceExternal)

Return Values: cDBF

Parameters:

If you set lForceExternal to .T., this indicates that you want to have an external table written to disk, even if the class can find a built-in version of the table in its code module (APP, EXE, or DLL).

getPathForExternals Method

Determines the location at which the current configuration table and any other required external files will be expected.

Syntax: getPathForExternals()

Return Values: cPath

Parameters: None

loadFrxCursor Property

Determines whether this class should dynamically load an instance of the helper class.

Default .F.

readConfiguration Property

Indicates the conditions under which SetConfiguration code will run.

0=never

1 = when the class instance Init runs

2 = when the class instance runs BeforeReport

3 = at both Init and BeforeReport

Default 0

setConfiguration Method

Checks the current configuration table for dynamic information in records of appropriate type, and executes these instructions if found.

Syntax: SetConfiguration()

Return Values: None

Parameters: None

targetFileExt Property

Provides the default file extension for file output.

Default "TXT"

targetFileName Property

Provides the filename to which output will be written. A unique name is generated for the class instance, which will be overwritten for successive report runs if not adjusted by the user.

Default FORCEPATH (SYS(2015),SYS(2023))

targetHandle Property

Provides a low-level file handle, to which output is written directly when the class provides raw data to the file, otherwise reserves the file during the report run so other applications do not write to it.

Default -1

verifyConfigTable Method

Ascertains that the format and contents of the configuration meet requirements, adjusting it if necessary.

Syntax: verifyConfigTable(cAlias [, cFailureMsgTable [, cFailureMsgIndexes]])

Return Values: logical

Parameters:

cAlias is the alias of the table you want to validate. The table must already be opened under this alias when you call the method.

cFailureMsgTable provides an optional alternative message to display if the nominated table cannot be verified as having valid configuration table format. If you do not supply this message, UtilityReportListener uses a string constant #DEFINEd in REPORTLISTENERS_LOCS.H.

cFailureMsgIndexes provides an optional alternative message to display if the table does not have appropriate indexes. If you do not supply this message, UtilityReportListener uses a string constant #DEFINEd in REPORTLISTENERS_LOCS.H.

verifyTargetFile Method

Assures that the nominated filename and its network location are available at the beginning of a file-based report run.

Syntax: verifyTargetFile()

Return Values: None

Parameters: None

See Also

Reference

ReportListener Base Foundation Class
ReportListener Object

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


ReportListener XML Foundation Class

Visual FoxPro 9.0
ReportListener XML Foundation Class
See Also Example

XmlListener provides the Report Output Application's default implementation of ListenerType 4 (XML output). Its properties include numerous settings you can use to adjust the VFP Report XML Schema to tune its output for different purposes. For example, if you send your report output XML to another application, for import into a database, you may not need the output from Page Header and Page Footer bands in your report. These portions of the report render at intervals based on the physical size of the original report layout page, and may not relate directly to rows of data in the report.

VFP Report XML includes data describing the original report or label file layout information (the frx or lbx table) as well as the run-time REPORT FORM command settings, printer instructions, open tables and relationships. This section of the XML structure is known as the VFP-RDL, or Visual FoxPro Report Definition Language. The schema elements for these items are different from the elements generated for the run-time expressions, lines, and other report layout controls as the Report Engine renders each record during a REPORT FORM command.

For full information on the VFP Reporting XML Schema, see Using VFP Report Output XML.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners
Class | XmlListener
Base Class | ReportListener
Class Library | _REPORTLISTENER.vcx
Parent Class | UtilityReportListener (ReportListener Utility and File-handling Foundation Class)

XmlListener and Report Continuation

XmlListener respects the NOPAGEEJECT keyword on REPORT FORM commands executed in a sequence, so a single VFP Report XML document can include details about multiple report runs.

The native NOPAGEEJECT keyword is only available from within programs (it has no effect when you issue a REPORT FORM command in the Command window). You can use the XmlListener's noPageEject property, rather than the standard keyword, if you want to try this capability out interactively.

Important
You must observe the same constraints when applying continuation to XML generation as you would use when printing. You are responsible to issue a final REPORT FORM without a NOPAGEEJECT clause to tell XmlListener to stop writing to the file, just as you would need the final REPORT FORM command to close the print queue. However, if you forget to do this, the Destroy method of the class will end the output job and close the file.

XmlListener handles the REPORT FORM command's RANGE clause. However, in report documents containing multiple reports through use of the continuation feature, it only handles RANGE if you do not also use the NORESET clause.

XmlListener's XML Generation Process

XmlListener uses a mix of techniques to provide its XML results. The Visual FoxPro XMLAdapter class provides the portion of the schema that describes FRX and report run-time metadata (the VFP-RDL). It also uses MSXML objects directly to enhance the VFP-RDL nodes. The class generates the data portion of the schema using a "raw" output process that sends data to a file using Visual FoxPro's low-level file functions, and taking full advantage of other native string-handling capabilities to handle normal encoding chores.

Tip:
You can recompile the class to adjust the MSXML objects XmlListener uses, and you can also opt to use MSXML objects consistently rather than the "raw" method it uses by default to provide the data portions of the output. Using MSXML objects throughout the processing can facilitate some scenarios in which your report output requires specialized encoding of binary data. To adjust the generation process, change the defined values in XmlListener's header file, REPORTLISTENERS.H. The default values are shown below:

Copy Code
#DEFINE OUTPUTXML_RAW             0
#DEFINE OUTPUTXML_DOM             1
#DEFINE XMLOUTPUT      OUTPUTXML_RAW
#DEFINE OUTPUTXML_DOMDOCUMENTOBJECT ;
  "Msxml2.FreeThreadedDOMDocument.4.0"
#DEFINE OUTPUTXML_DOMFREETHREADED_DOCUMENTOBJECT ;
  "Msxml2.FreeThreadedDOMDocument.4.0"
#DEFINE OUTPUTXML_XSLT_PROCESSOROBJECT ;
  "Msxml2.XSLTemplate.4.0"

XmlListener and XSLT

Once you have generated an XML document, you often have to move it from one format to another. XmlListener provides facilities for Extensible Stylesheet Language Transformations (XSLT). You can load XSLT documents and request that XmlListener supply the final result of your chosen transformation, rather than its native VFP Report XML schema document.

XmlListener and its Configuration Table

Like its superclass, UtilityReportListener, XmlListener leverages the same configuration table structure as the Report Output Application. It reserves a range of values in the OBJTYPE (1100 through 1199) as a way to look up XML node names for various reporting elements. Using the configuration structure to store node names is a way of localizing the XML elements for readability. For example, the default value of PH as a node name for Page Header bands might not be intuitive to a developer not working in English, or the developer might prefer a less terse notation. Because XmlListener can read your preferred values at run time, the VFP Report Xml schema should be regarded as a structural model; the actual node names at run time might be different.

XmlListener stores this information in the configuration table according to the scheme you see in the following table.

Field | Usage
OBJTYPE | Stores the original FRX table OBJTYPE value for the type of band or layout object the XML element describes, plus an offset of 1100. For example, a Picture layout control in an FRX has the OBJTYPE 17, so a record storing the XML node name for a Picture layout control has the value 1117.
OBJCODE | Has the same value as a record of the same type in the FRX. For example, a record storing the XML node name for a Detail Footer band has the same OBJCODE as a DetailFooter band record in the FRX.
OBJNAME | Not used by XmlListener
OBJVALUE | Stores the node name.
OBJINFO | Stores a descriptive value for the type of FRX record. For example, Detail Footer Band nodename .

If XMLListener is the subclass of UtilityReportListener that generates the configuration table at run time, or if it cannot find its required records in the pre-existing configuration table, it will include appropriate records for all the elements it needs. It also adds the specialized index keys it requires to the configuration table, if needed.

Remarks

XmlListener adds the public following properties and methods to its parent class, UtilityReportListener.

Properties and methods Description

applyUserTransform Property

Indicates whether XMLListener should automatically apply a user-defined XSLT transform at the conclusion of a report run.

Default .F.

Remarks: When you set this property to .T., the associated assign method checks to see if you have already filled the xsltProcessorUser property with an appropriate processor object. If not, it runs an internal method, getDefaultUserXslt, to load the xsltProcessorUser property. This internal method provides a hook for subclasses to supply their preferred XSLT document for use without requiring an external load procedure.

applyXslt Method

Provides generic facilities for applying XSLT to XML.

Syntax: applyXslt (vSource, vProcessor [, vParamCollection])

Return Values: cXmlResult

Parameters:

vSource can be the name of a file holding the source XML document, a string holding the XML document, or a DOM document object.

vProcessor can be the name of a file holding the XSLT processor document, a string holding the XSLT document, or an XSLT processor object.

vParamCollection is an optional object of Collection type. If it is available, this method adds the members of the collection to the XSLT processor instance as global parameters before applying the XSLT transformation to the source document. It uses the collection keys as parameter names, and the corresponding collection values as parameter values.

XmlListener provides a property, xsltParameters, you can use to hold the collection you build to hold these parameters between calls.

Remarks: Both the XML source and XSLT processor object types are defined in REPORTLISTENERS.H. You can edit this header file and recompile the class to choose different processing objects.

contAttr Property

Supplies the name of the attribute used to show continuation type for a layout object that can span bands or pages.

Default "c"

currentDocument Property

Holds information about the XML document for which output is currently being generated during a report run.

Default .NULL.

heightAttr Property

Supplies the name of the XML attribute used to show height for a layout object.

Default "h"

idAttribute Property

Supplies the name of the XML attribute used to provide the FRX record number for a layout object or page number of a formatting band (column or page) object.

Default "id"

idrefAttribute Property

Supplies the name of the XML attribute used to provide the current page for a layout object or FRX record number of a formatting band (column or page) object.

Default "idref"

includeBandsWithNoObjects Property

Indicates whether band-level information for bands with no contents should be included in the XML.

Default .F.

includeBreaksInData Property

Determines whether formatting bands (page and columns) should be included in output and, if so, using what structure.

 | Meaning
0 | Provide page band nodes positioned along with other bands in the datastream, wherever they happen to occur
1 | No pagebreak info, no page header and footer info
2 | Provide collection of pages with page headers and footers data

Default 0

includeDataSourcesInVfpRdl Property

Indicates whether information about the source tables, relations, indexes, etc. should be included in the VFPRDL metadata section of the report XML.

Default .F.

includeFormattingInLayoutObjects Property

Indicates whether formatting information such as positioning attributes should be included in the report XML.

Default .F.

leftAttr Property

Supplies the name of the XML attribute used to show leftmost position for a layout object.

Default "l"

noPageEject Property

Indicates whether the XML Listener should consider the current report run to be continued. Can be used without NOPAGEEJECT on the REPORT FORM command.

Default .F.

resetDocument Method

Resets the XML document after a report run.

Syntax: resetDocument()

Return Values: none

Parameters: none

topAttr Property

Supplies the name of the XML attribute used to show topmost position for a layout object.

Default "t"

verifyNCName Method

Provides generic method to validate strings as XML-standard NCNames.

Syntax: verifyNCName ( cName )

Return Values: lValid

Parameters:

cName is the string you are checking for validity as an NCName value.

Remarks: In XML, an NCName or non-colonized name is a legal value for either the namespace or the non-prefixed (local) name of a node. For example, in the node name xsl:template, both xsl and template are NCNames.

widthAttr Property

Supplies the name of the XML attribute used to show width for a layout object.

Default "w"

xmlMode Property

Determines what parts of the VFP Report XML schema are included in output.

Value | Meaning
0 | Data only
1 | VFP-RDL only
2 | Data and VFP-RDL

Default 2

xsltParameters Property

Holds an optional parameter collection passed to the ApplyXSLT method when XmlListener automatically applies a user XSLT transformation at the conclusion of a report run.

Default .NULL.

Remarks: The code example in ReportListener HTML Foundation Class uses xsltParameters explicitly, to set numberPrecision, one parameter of its default transformation. The class's code sets several other parameters of the default HTML transformation using xsltParameters. If you create xsltParameters as a collection object yourself, as shown in that example, the HtmlListener class will use this object, adding any required keys and values after checking to see if they already exist.

xsltProcessorRdl Property

Holds a Report Definition Language (RDL) -specific processor object.

Default .NULL.

Remarks: Reserved for future use. You can load an XSLT processor object to this property using the same techniques as described for the xslProcessorUser property.

xsltProcessorUser Property

Holds a user-definable processor object which, if filled and available at the end of a run, can be used automatically by XML Listener to transform the raw XML document to requirements.

Default .NULL.

Remarks: To change this document, you have several options:

  • Store a filename to the property, as shown in the example below.

  • Store an XSLT document contained in a string variable to the property.

  • Store an XSLT processor object, with its stylesheet already loaded, to the property. The appropriate object types are defined in XmlListener's header file, REPORTLISTENERS.H.

If you store the document as a string or a filename, XmlListener creates the processor object for you, and loads the stylesheet.

Example

In this example, the code tunes XmlListener's properties to suit a particular data transfer scenario (a customer list being transferred between a Visual FoxPro application and a CRM application hosted in a different environment).

The code provides the object's xsltProcessUser property with a suitable XSLT transformation document, using one of the three methods described in the table above for loading the processor object. It instructs the object to apply the XSLT transformation automatically after the report run. It then runs the report. The resulting XSLT fits the requirements of the CRM application and can be imported without further change.

Copy Code
oXml = NEWOBJECT("XmlListener","_REPORTLISTENER")
WITH oXml
  .xmlMode = 0 && data only,
               && no RDL is needed for this
               && particular transform
  .xsltProcessorUser = "Customer.xslt"
  .applyUserTransform = .T.
ENDWITH
REPORT FORM Customer OBJECT oXml
MODIFY FILE (oXml.TargetFileName)

See Also

Reference

ReportListener Utility and File-handling Foundation Class

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Report Output Application


ReportListener XML Display-Style Foundation Class

Visual FoxPro 9.0
ReportListener XML Display-Style Foundation Class
See Also

The XmlDisplayListener class tunes XmlListener's default VFP Report XML schema settings suitably for presentation output needs. For full information on the VFP Reporting XML Schema and its options, see Using VFP Report Output XML.

XmlDisplayListener also adds image-file-publishing capabilities:

  • You can copy the image files used in your report to a new location.

  • You can save images rendered during the report from general fields or image control references, which were not based on files, to files on disk.

These capabilities are useful when you are preparing reporting output to be published or packaged for display on the Web or for further processing by another publishing application.

See ReportListener HTML Foundation Class for sample code.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners
Class | XmlDisplayListener
Base Class | ReportListener
Class Library | _REPORTLISTENER.vcx
Parent Class | XmlListener (ReportListener XML Foundation Class)

XmlDisplayListener, General Fields, and Image Controls

When processing images that did not come from a file on disk, XmlDisplayListener always provides a copy on disk for your use. By default, these files are placed in the same location as your generated report output file, but you can set this location to a different folder, using the XmlDisplayListener.externalFileLocation property. The folder you nominate for this use must exist; otherwise, XmlDisplayListener ignores the instruction.

Tip:
When preparing to publish web documents, you will often want to set the location of the image files to a separate directory from the main output file. It is a good idea to set the location as a relative reference, such as ".\images." XmlDisplayListener understands these references to be relative to your main output file.

XmlDisplayListener must save a separate image to disk every time the report renders an image. Because these images may be different for every record in your report, it uses a generated filename convention to name the files. You can adjust these filenames by adding a base filename, to which XmlDisplayListener adds its generated portion as a suffix. This distinguishes your image files from other files from different report runs.

By default, the base class ReportListener does not send full image information to its derived classes. You must request the appropriate information, using the ReportListener.SendGDIPlusImage property.

At the start of a report run, XmlDisplayListener checks to see if there are any General fields in your report design. If it finds references to General fields, it sets .SendGDIPlusImage temporarily, if necessary, and restores the value later.

In Visual FoxPro 9, report designs can include expressions that reference Image controls, as well as general fields and image files on disk. If the Report Engine finds an expression representing an Image control object associated with an Image layout control while it processes your report, it uses the image information in the Image control's PictureVal property. For more information, see PictureVal Property.

XmlDisplayListener cannot know that your report layout expressions may represent Image controls (rather than indirect references to image files on disk) when it evaluates your FRX. For this reason, if you use expressions representing Image controls, unless there are also General fields in your report, you must set its XmlDisplayListener.SendGDIPlusImage explicitly. This explicit instruction will cause the ReportListener to provide the necessary image information as it renders your report. With this property set, XmlDisplayListener detects the GDPlusImage handle the first time it receives one and, if it has not done so earlier, it will set the other, associated attributes required to save the files to disk.

XmlDisplayListener and File-based images

By default, XmlDisplayListener simply references any file-based images on disk using the original filename and providing full path information to the source file. However, you can instruct XmlDisplayListener to publish a copy of your image files to its .externalFileLocation on disk, so you can move the image files with your main XML output file later. To tell XmlDisplayListener you wish to copy the image files, use its .copyImageFilesToExternalFileLocation property.

Remarks

XmlDisplayListener adds the following public properties to its parent class, XmlListener. XmlDisplayListener adds no public methods.

Properties and methods | Description
externalFileLocation Property | Optionally assigns a UNC or file system path, either relative or absolute, the XML result will assign to any external files, such as images, referenced in the main XML output file. Default ""
copyImageFilesToExternalFileLocation Property | Indicates whether file-based images should be copied to a common location from their original locations on your disk, for reference as image sources in the XML output. Default .F.
imageSrcAttr Property | Supplies the name of the XML attribute used to show filename copied, or generated for non-file based images, at run time. Default "img"
formattingChanges Property | Reference in which classes can store information about actions taken to apply changes to object formatting attributes dynamically during a report run. Default .NULL.

See Also

Reference

ReportListener XML Foundation Class
ReportListener Object

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


ReportListener HTML Foundation Class

Visual FoxPro 9.0
ReportListener HTML Foundation Class
See Also Example

HtmlListener provides the Report Output Application's default implementation of ListenerType 5 (HTML output) and Genhml.prg's default implement of HTML output from report and label files (frx and lbx tables).

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners
Class | HtmlListener
Base Class | ReportListener
Class Library | _REPORTLISTENER.vcx
Parent Class | XmlDisplayListener (ReportListener XML Display-Style Foundation Class)

Remarks

HtmlListener leverages XmlListener's ability to apply an XSLT transformation document to the base VFP Report XML document format automatically at the conclusion of a report run. For information on XmlListener's XSLT processing capabilities, see ReportListener XML Foundation Class.

HtmlListener adds no new properties or methods to its parent class, XmlDisplayListener. It sets the output file extension to "HTM" and its ApplyUserTransform property to .T. and augments the internal XmlListener method, getDefaultUserXslt, to supply an appropriate XSLT transformation document for HTML production.

The custom XSLT document included in HtmlListener handles all the details of reading the VFP-RDL for your original report or layout information, and reproduces this layout in HTML. Your user's printer at run time may have a different printable page size than the printer for which the report was originally rendered, and your user's browser may also add headers, footers, and margins, into this page layout. As a result, you should not rely on this format to print with appropriate page breaks from the browser; it is designed primarily for page display.

Tip:
You can use the RANGE clause on the REPORT FORM command to provide HTML data on a page-by-page basis, so it will print properly from the browser. Note that HtmlListener's default XSLT document supports the RANGE clause only for single reports, not multiple reports using the NOPAGEEJECT capability. Without RANGE, HtmlListener's default XSLT supports multiple reports in a single HTML document.

If you want exact, printable page copies, you can use the ReportListener class's OutputPage method to provide image files of individual report pages for printing purposes. See the ReportListener Object for more information.

However, you are not limited to faithful reproduction of the original report design. You can replace the default XSLT transformation with any other rendering of the original report data that suits you, customizing a single report result for different users on different target devices. Simply store a reference to a different XSLT transformation document into the XsltProcessorUser property. The sample code in ReportListener XML Foundation Class shows you how to change the contents of the document.

Example

This example sets HtmlListener's target output file and precision of numeric coordinates, and specifies that any image files rendered in the report should be copied to a subdirectory relative to its output file. This is an appropriate approach if the report will be published on a web server.

Note:
This example is designed to be used in a distributed application, so it does not include a path to the FFC class library. If you would like to run it as a program from the command line, un-comment the SET PATH statement.

After running a report, the example brings up the HTML output in a Visual FoxPro editing window for verification and then displays the current XsltProcessorUser document contents as text on the Visual FoxPro screen, for your reference.

Tip:
If you examine the contents of the XSLT document closely, you find that theStylesheet.xml property still shows the pre-compilation numberPrecision default value, 5, and the default values for all other parameters in this XSLT document. For example, externalFileLocation is a parameter in the XSLT document, and the value you assign in the example, ".\images", does not show in the Stylesheet.xml contents. XMLListener's applyXSLT method applies parameters' runtime values to the compiled Stylesheet instance, just before it applies the compiled transform document to your source XML.
Copy Code
LOCAL oHtml
* SET PATH TO (HOME() + "FFC") ADDITIVE
oHtml = NEWOBJECT("HtmlListener","_reportlistener.vcx")
oHtml.targetFileName = "c:\temp\myOutput.htm"
* The following lines of code set the precision of coordinates
* of most individual layout items as a number of decimal places
* (the XSLT's coordinates are in inches).
* The default number of decimal places is set in the XSLT to 5,
* but here the value is set to 6:
oHtml.xsltParameters = CREATEOBJECT("Collection")
oHtml.xsltParameters.Add(6,"numberPrecision")
* The following directory must exist *before*
* you assign the next property:
IF NOT DIRECTORY("c:\temp\images")
   MD c:\temp\images
ENDIF
* Assignment of the image directory as
* a relative reference ensures
* appropriate src attributes in the
* HTML document:
oHtml.externalFileLocation = ".\images"
oHtml.copyImageFilesToExternalFileLocation = .T.
REPORT FORM ? OBJECT oHtml
MODIFY FILE (oHtml.targetFileName)
ACTI SCREEN
? oHtml.XsltProcessorUser.Stylesheet.Xml

See Also

Reference

Genhtml.prg
ReportListener XML Display-Style Foundation Class

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Report Output Application


ReportListener Debug Foundation Class

Visual FoxPro 9.0
ReportListener Debug Foundation Class
See Also

The DebugListener class provides debugging output to help developers understand what happens during an object-assisted report run.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners
Class | DebugListener
Base Class | ReportListener
Class Library | _REPORTLISTENER.vcx
Parent Class | UtilityReportListener (ReportListener Utility and File-handling Foundation Class)

Remarks

DebugListener adds the following public properties and methods to its parent class, UtilityReportListener.

Properties and methods Description

doDebug Method

Provides debug information for a ReportListener event or method.

Syntax: DoDebug(p0, pCount, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11, p12

Return Values: none

Parameters:

p0 is a string representing the caller, used as an identifying label in each debug output line.

pCount is the value of PCOUNT() in the calling method, passed so doDebug knows how many parameters are significant for this debug output line.

p1 through p12 are the parameters received by the caller, passed to this method for debug output.

Remarks: DebugLister calls this method from every method of the ReportListener class relevant to a report run. Each call is the same, as follows:

Copy Code
THIS.DoDebug(PROGRAM(), PCOUNT(), p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11, p12)

A second debug output method, private to the class, provides debug information on the state of the CommandClauses object and ReportListener member properties in the LoadReport , BeforeReport, AfterReport, and UnloadReport events.

includeLoadandUnload Property

Indicates whether the debug information should include values from the LoadReport and UnloadReport events.

Default .T.

Remarks: You can set this value to .F. if you write LoadReport code that can return .F. to abnormally terminate the report run. You can also set this value to .F. if you do not need the additional data from the LoadReport and UnloadReport methods. For more information, see ReportListener Object.

verbose Property

Specifies whether the DebugListener should include extended information about parameter values of object type, as well as page, alias, and recno() information for each event or method.

Default .F.

See Also

Reference

ReportListener Utility and File-handling Foundation Class

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z


Resize Object Foundation Class

Visual FoxPro 9.0 Language Reference
Resize Object Foundation Class
See Also

This class causes objects dropped onto a form to resize and move with the Form's Resize event.

Category | User Interface
Default Catalog | Visual FoxPro Catalog\Foundation Classes\User Controls
Class | _resizable
Base Class | Custom
Class Library | _controls.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Forms\cresize.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, specify the AdjustControls method in the Resize event of the controls on the form. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
InitialResize property | Specifies whether controls have been adjusted before. Default: .T.
AdjustControls method | Adjusts the placement and size of contained objects after a Resize event. Syntax: AdjustControls( ) Return: none Arguments: none
Reset method | Resets the Timer control so that it starts counting from 0. Syntax: Reset( ) Return: none Arguments: none
InitialFormHeight property | Internal to the class.
InitialFormWidth property | Internal to the class.
aControlStats[1,5] property | Internal to the class.
AddToArray method | Internal to the class.
SetSize method | Internal to the class.
LoopThroughControls method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


RTF Controls Foundation Class

Visual FoxPro 9.0 Language Reference
RTF Controls Foundation Class
See Also

This class, when placed on a form, provides controls for applying font formatting to text in the active control.

Category | Text Format
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Text Formatting
Class | _rtfcontrols
Base Class | Container
Class Library | _format.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Toolbars\format.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a project, you can choose between adding the class or creating a subclass. When you add the class to a form, Visual FoxPro places the comboboxes and button controls on the form in the Form Designer.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Run Form Button Foundation Class

Visual FoxPro 9.0 Language Reference
Run Form Button Foundation Class
See Also

This class provides a generic button to run a form.

Category | Misc Buttons
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | _cmdRunForm
Base Class | CommandButton
Class Library | _miscbtns.vcx
Parent Class | _commandbutton
Sample | ...\Samples\Solution\Ffc\buttons.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can specify cFileName, the name of the form you want to run. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
cFilename property | Specifies the name of the form to run. Default: ""
lSetCaption property | Specifies whether the caption is automatically based on the value of cFilename. Default: .T.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


SCX to HTML Foundation Class

Visual FoxPro 9.0 Language Reference
SCX to HTML Foundation Class
See Also

This class converts a Visual FoxPro form (.scx) to HTML. This class provides properties to control the scope, visual layout, and HTML generation. For more information, see Genhtml.prg.

Category | Internet
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Internet
Class | _scx2html
Base Class | Custom
Class Library | _internet.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\dohtml.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro opens a builder so you can accept the current values or specify the appropriate cSource, cOutFile, and nGenOutput values. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cOutfile property | Specifies the name of the HTML file to output. Default: ""
cScope property | Specifies the scope (for example, NEXT or ALL, for the output). Default: ""
cSource property | Specifies the source .scx file from which to generate the HTML file. Default: ""
cStyle property | Specifies the visual style as listed in the ID field of Genhtml.dbf. Default: ""
lAutonameoutput property | Specifies whether _GENHTML automatically names the output file based on its source. Default: .T.
nGenOutput property | Specifies the _GENHTML output option: Default: 2
GenHTML method | Generates HTML code by calling the _GENHTML engine using properties specified in cSource, cOutFile, and nGenOutput. Syntax: GenHTML( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


SendMail Buttons Foundation Class

Visual FoxPro 9.0 Language Reference
SendMail Buttons Foundation Class
See Also

This class, which uses the MAPI ActiveX control, handles sending a mail message from a form. When dropped on a form, it can be used to send the current record directly to your mail application.

Category | Misc Buttons
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | _mailbtn
Base Class | Container
Class Library | _miscbtns.vcx
Parent Class | _container
Sample | ...\Samples\Solution\OLE\sendmail.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you drop the class on a form in a data environment, Visual FoxPro places a button on your form where it will access the current record of the active form. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
logSession property | Specifies whether log in to mail was successful. Default: .F.
SignOn method | Attempts to log in to mail. Syntax: SignOn( ) Return: none Arguments: none
AddTabs method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


SetAllX Extension Foundation Class

Visual FoxPro 9.0 Language Reference
SetAllX Extension Foundation Class
See Also

The SetAllX class is an extension of the Visual FoxPro SetAll( ) method available on many Visual FoxPro classes. Unlike the Visual FoxPro SetAll( ) method, you can specify a baseclass whose objects are affected.

Category | Object Extension
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _setallx
Base Class | Custom
Class Library | _setallx.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\Setallx.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
Setallx method | Extended version of SetAll( ) method. Syntax: SetAllX(toParent, tcProperty, tcExpr, tcBaseClassList, tlNoContainerMode, tlErrorWait) Return: logical Arguments: toParent provides a reference to the parent object.tcProperty specifies the property to set.tcExpr specifies value of property being set.tcBaseClassList specifies the baseclass that applies the changes.tlNoContainerMode prevents interation through the container.tlErrorWait specifies whether to wait for error.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Shell Execute Foundation Class

Visual FoxPro 9.0 Language Reference
Shell Execute Foundation Class
See Also

This class enables you to launch an application or document with its associated application from the current application.

Category | System utility
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _shellexecute
Class Library | _environ.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\Buttons.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
ShellExecute method | Attempts to run the file tcFileName in the directory, tcWorkDir. Syntax: ShellExecute(tcFileName, tcWorkDir, tcOperation) Return: nSuccess Arguments: tcFileName specifies the file to run.tcWorkDir specifies the path to the file to run.tcOperation specifies the operation to perform.nSuccess specifies the failure or the success of the run attempt using one of the following values: Values over 32 represent success, and return an instance handle for the running application.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Shortcut Menu Class Foundation Class

Visual FoxPro 9.0 Language Reference
Shortcut Menu Class Foundation Class
See Also

When placed on a project or form, this class dynamically creates shortcut popup menus.

Category | Menus
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Menus
Class | _shortcutmenu
Base Class | Custom
Class Library | _menu.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\newmenu.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cOnSelection property | Specifies the menu bar selection routine. Default: ""
cMenu property | Specifies the name of the shortcut menu. Default: ""
DeactivateMenu method | Deactivates the existing shortcut menu. Syntax: DeactivateMenu( ) Return: none Arguments: none
ActivateMenu method | Activates the existing shortcut menu. Syntax: ActivateMenu(tcParentMenu) Return: none Arguments: tcParentMenu specifies the name of the menu from which the shortcut is activated.
ClearMenu method | Releases the existing shortcut menu. Syntax: ClearMenu( ) Return: none Arguments: none
NewMenu method | Creates a new menu popup for the shortcut menu. Syntax: NewMenu( ) Return: none Arguments: none
AddMenubar method | Adds a new menu bar to the shortcut menu. Syntax: AddMember(tcPrompt, tcOnSelection, tcClauses, tnElementNumber, tlMark, tlDisabled, tlBold) Return: none Arguments: tcPrompt specifies the item label.tcOnSelection specifies the action performed by selecting the item.tcClauses specifies any command clause for the item.tnElementNumber specifies the location of the element in the array.tlMark specifies whether to use the default mark character.tlDisabled specifies whether the menu item is disabled.tlBold specifies whether the item is bold.
AddMenuSeparator method | Adds a separator to the shortcut menu. Syntax: AddMenuSeparator(tnElementNumber) Return: none Arguments: tnElementNumber specifies the position the separator occupies in the menu.
ShowMenu method | Displays the existing shortcut menu. Syntax: ShowMenu( ) Return: none Arguments: none
SetMenu method | Releases the current shortcut menu in order to create a new one. Syntax: SetMenu(toObject) Return: none Arguments: toObject specifies the name of the new shortcut menu.
aMenu[1,0] property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Simple Edit Buttons Foundation Class

Visual FoxPro 9.0 Language Reference
Simple Edit Buttons Foundation Class
See Also

When placed on a project or form, this class provides simple picture Add, Edit, Delete, Duplicate, Save, and Cancel buttons (as used by the Form Wizard).

Category | Data Editing
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | picformbtns
Base Class | Container
Class Library | wizbtns
Parent Class | gridbtns
Sample | ...\Samples\Solution\Ffc\dataedit2.scx

Remarks

Use for simple forms based on a single table or view. For more information, view gridbtns in the Wizbtns.vcx class library in the Class Browser.

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form in a data environment, Visual FoxPro places the class buttons on the form. You can then provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Simple Navigation Buttons Foundation Class

Visual FoxPro 9.0 Language Reference
Simple Navigation Buttons Foundation Class
See Also

When placed on a project or form, this class provides a simple pair of Next and Previous navigation buttons.

Category | Data Navigation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Navigation
Class | _nav2Buttons
Base Class | Container
Class Library | _table.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Forms\single.scx

Remarks

To use, drop the class on a project or form in a data environment or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the command buttons on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
lCycle property | Specifies whether pointer movement continues when the bottom or top of the file is encountered. Default: .F.
TableNav method | Handles record navigation. Syntax: TableNav(tcAction) Return: none Arguments: tcAction specifies a navigation action such as Next or Previous.
lCycle_access method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Simple Picture Navigation Buttons Foundation Class

Visual FoxPro 9.0 Language Reference
Simple Picture Navigation Buttons Foundation Class
See Also

When placed on a project or form, this class provides a pair of simple picture Next and Previous navigation buttons. For more details, open _nav2buttons in the _table.vcx class library in the Class Browser.

Category | Data Navigation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Navigation
Class | _nav2picbuttons
Base Class | Container
Class Library | _table2.vcx
Parent Class | _nav2buttons
Sample | ...\Samples\Solution\Ffc\datanav.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the command buttons on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Sort Dialog Box Button Foundation Class

Visual FoxPro 9.0 Language Reference
Sort Dialog Box Button Foundation Class
See Also

When placed on a project or form, this class provides a button that displays a dialog box that makes it possible for you to sort data in ascending or descending order on a particular field. For details, open _dialogbutton in the _table2.vcx class library in the Class Browser.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Buttons
Class | _sortbutton
Base Class | CommandButton
Class Library | _table2.vcx
Parent Class | _dialogbutton
Sample | ...\Samples\Solution\Ffc\datasort.scx

Remarks

To use, drop the class on a project or form in a data environment or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the button on the form. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Sort Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
Sort Dialog Box Foundation Class
See Also

This dialog box enables you to perform an ascending or descending data sort on a particular field.

Category | Data Query
Default Catalog | Visual FoxPro\Foundation Classes\ Data Query
Class | _sortdialog
Base Class | Form
Class Library | _table2.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\datasort.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Add to Project. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. If you choose Create a new form from the selected class, Visual FoxPro opens a builder so you can specify the name of the form, then creates and opens the form in the Form Designer. You need to provide an indexed table for the Sort dialog box.

Properties, Events, Methods | Description
DoSort method | Makes it possible for you to sort on the current field or to specify the field on which to order a table. Syntax: DoSort( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Sort Mover Foundation Class

Visual FoxPro 9.0 Language Reference
Sort Mover Foundation Class
See Also

This subclass of the mover list box class, when placed on a form, automatically handles sorting of data.

Category | Movers
Default Catalog | Visual FoxPro Catalog\Foundation Classes\User Controls
Class | _sortmover
Base Class | Container
Class Library | _mover.vcx
Parent Class | _mover
Sample | ...\Samples\Solution\Ffc\movers.scx

Remarks

Properties, Events, Methods | Description
CurrentAlias property | The current alias for field choices. Default: ""
CurrentDBC property | The current database for field choices. Default: ""
MaxFields property | Maximum number of fields allowed. Default: 3
ShowTags property | Specifies whether to show existing index tags in addition to fields. Default: .F.
aTags[1,1] property | Internal to the class.
TagName property | Internal to the class.
UpdateMover | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples
Mover Foundation Class


Sort Object Foundation Class

Visual FoxPro 9.0 Language Reference
Sort Object Foundation Class
See Also

This class, when placed on a form, enables you to sort a datasource.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _tablesort
Base Class | Custom
Class Library | _table.vcx
Parent Class | _table
Sample | ...\Samples\Solution\Ffc\datasort.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods Description

lDescending property

Specifies whether the sort order is ascending or descending.

Default: .F.

DoSort method

Makes it possible for you to sort on the current field or to specify the field on which to order a table or alias.

Syntax: DoSort([tcField] [,tcAlias] [,tcTag] [,tlDescending])

Return: none

Arguments: tcField specifies the field to sort on.tcAlias specifies the alias of the table to sort.tcTag specifies the index tag of the field, tcField.tlDescending specifies whether the sort is a descending sort.

GetSortTag method

Looks for an appropriate tag name by looking at key expressions in the table relevant to the field name.

Syntax: Getsorttag(tcField, tcAlias)

Return: lcTag

Arguments: tcField specifies the field to sort on.tcAlias specifies the alias of the table to sort.

RemoveSort method

Removes the current index tag.

Syntax: RemoveSort(tcAlias)

Return: none

Arguments: tcAlias specifies the alias of the table from which to remove the tag.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Sort Selector Foundation Class

Visual FoxPro 9.0 Language Reference
Sort Selector Foundation Class
See Also

This set of buttons, when placed on a project or form, performs an ascending or descending sort based on the current control.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _sortselect
Base Class | Container
Class Library | _table2.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Ffc\datasort.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the buttons on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods Description

DoSort method

Makes it possible for you to sort on the current field or to specify the field on which to order a table.

Syntax: DoSort([tcField] [,tcAlias] [,tcTag] [,tlDescending])

Return: none

Arguments: tcField specifies the field to sort on.tcAlias specifies the alias of the table to sort.tcTag specifies the index tag of the field, tcField.tlDescending specifies whether the sort is a descending sort.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Sound Player Foundation Class

Visual FoxPro 9.0 Language Reference
Sound Player Foundation Class
See Also

This class loads and plays a sound file, and provides access to the Media Control Interface (MCI).

Category | Multimedia
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Multimedia
Class | _soundplayer
Base Class | Container
Class Library | _multimedia.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Forms\mci_play.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you drop the class on a project, you can choose between adding the class or creating a subclass. When you choose an option from the shortcut menu or drop the class on a form, Visual FoxPro opens a builder so you can specify appropriate cFileName, lAutoOpen, lAutoPlay, lAutoRepeat, and cControlSource values.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cControlSource property | Specifies the source of data to which an object is bound. Default: ""
cFileName property | Specifies the name of the sound file to play. Default: ""
cMCIAlias property | Specifies the alias for the video file when calling MCI commands. If empty, the name of the file is used. Default: ""
cMCIErrorString property | Stores the error string from the last MCI command. Default: ""
lAutoOpen property | Specifies whether the video file specified should be automatically opened when the class is created. Default: .T.
lAutoPlay property | Specifies whether the video file should automatically play after opening. Default: .T.
lAutoRepeat property | Specifies whether video plays continuously. Default: .T.
nMCIError property | Specifies the result of the last MCI command executed. Default: 0
CloseSound method | Closes the loaded sound file and releases its resources. Syntax: CloseSound( ) Return: none Arguments: none
OpenSound method | Opens the sound file. Syntax: OpenSound( ) Return: none Arguments: none
PauseSound method | Pauses the currently playing sound. Syntax: PauseSound( ) Return: none Arguments: none
PlaySound method | Plays the loaded sound file. Syntax: PlaySound( ) Return: none Arguments: none
SetPosition method | Makes it possible for the user to set the position of the media file. Syntax: SetPosition (cPosition) Return: none Arguments: cPosition specifies Start, End, or a number representing milliseconds into the media file.
DoMCI method | Internal to the class.
GetMCIError method | Internal to the class.
ShowMCIError method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Splash Screen Foundation Class

Visual FoxPro 9.0 Language Reference
Splash Screen Foundation Class
See Also

This class, when placed in a project, provides a simple Splash Screen for custom applications.

Category | Misc Forms
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Dialogs
Class | _splash
Base Class | Form
Class Library | _dialogs.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\dialogs.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Create Form or Add to Project. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. When you choose Create a new form from the selected class, Visual FoxPro displays an Open dialog box so you can specify the name of the form, then creates and opens the form in the Form Designer.

Properties, Events, Methods | Description
nDuration property | Specifies the duration (in seconds) to display the screen. Default: 3

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


SQL Pass Through Foundation Class

Visual FoxPro 9.0 Language Reference
SQL Pass Through Foundation Class
See Also

This class is used for SQL Pass Through and makes it possible for you to execute stored procedures on a host database such as Microsoft SQL Server.

Category | Data Query
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Query
Class | _execsp
Base Class | Custom
Class Library | _dataquery.vcx
Parent Class | _custom

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you drop the class on a form, Visual FoxPro places the class icon on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

You need to add code that specifies parameter and connection information so the class can return a result set in a cursor.

Properties, Events, Methods | Description
LUseSQLSyntax | Specifies whether to use Server Exec syntax. Default: .F.
DoSQL method | Runs a SQL Pass Through statement. Syntax: DoSQL( ) Return: none Arguments: none
GetSQL method | Gets results from the SQL Pass Through statement. Syntax: GetSQL( ) Return: none Arguments: none
aParams[1,0] property | Internal to the class.
cCursorName property | Internal to the class.
cSpname property | Internal to the class.
cSQL property | Internal to the class.
hConnectHandle property | Internal to the class.
ProcessError method | Internal to the class.
SetParams method | Internal to the class.
SetSQL method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Stop Watch Foundation Class

Visual FoxPro 9.0 Language Reference
Stop Watch Foundation Class
See Also

This class, when placed on a form, provides a stop watch control.

Category | Date/Time
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Date/Time
Class | _stopwatch
Base Class | Container
Class Library | _datetime.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Controls\Timer\swatch.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the icon on the form where it will run on the active form. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
Increment method | Increments the stopwatch display. Syntax: Increment( ) Return: none Arguments: none
Reset method | Resets the stopwatch. Syntax: Reset( ) Return: none Arguments: none
Start method | Starts the stopwatch. Syntax: Start( ) Return: none Arguments: none
Stop method | Stops the stopwatch. Syntax: Stop( ) Return: none Arguments: none
UpdateDisplay method | Refreshes the display. Syntax: UpdateDisplay( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


String Library Foundation Class

Visual FoxPro 9.0 Language Reference
String Library Foundation Class
See Also

This class removes carriage return and line feed characters from a character string.

Category | Data Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _stringlib
Base Class | Custom
Class Library | _utility.vcx
Parent Class | _custom

Remarks

Properties, Events, Methods | Description
TrimCRLF method | Trims carriage return and line feed characters from a character string. Syntax: TrimCRLF (tcString, tlTrimLeft, tlTrimRight) Return: none Arguments: tcString specifies the string to trim.tlTrimLeftspecifies whether to trim the left side.tlTrimRightspecifies whether to trim the right side.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Super Mover Foundation Class

Visual FoxPro 9.0 Language Reference
Super Mover Foundation Class
See Also

This class, when placed on a form, provides a mover list box with Move, Remove, MoveAll, and RemoveAll buttons.

Category | Movers
Default Catalog | Visual FoxPro Catalog\Foundation Classes\User Controls
Class | _supermover
Base Class | Container
Class Library | _mover.vcx
Parent Class | supermover
Sample | ...\Samples\Solution\Ffc\movers.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a project, you can choose between adding the class or creating a subclass. When you add the class to a form in a data environment, Visual FoxPro adds the class list box and button controls to the form in the Form Designer so you can specify appropriate property values.

Properties, Events, Methods | Description
MaxItems property | Specifies the maximum number of items that can be selected. Default: 0
MaxMessage property | Specifies the message to display if maximum number of items is reached. Default: ""

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples
Mover Foundation Class


System Metrics Foundation Class

Visual FoxPro 9.0 Language Reference
System Metrics Foundation Class
See Also

Provides access to system metric information that might be useful in your applications as well as necessary for Windows 2000 Logo compliancy. System metrics such as mousewheel present, number of mouse buttons, and number of monitors are provided with the class, but any valid system metric can be queried.

Category | System Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _sysmetrics
Base Class | Custom
Class Library | _system.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\Logo.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
lMouseWheelPresent property | Returns .T. if MouseWheel is present on mouse.
nMonitors property | Returns the number of monitors attached to system.
nMouseButtons property | Returns the number of mouse buttons on the mouse.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


System Toolbar Foundation Class

Visual FoxPro 9.0 Language Reference
System Toolbar Foundation Class
See Also

This class is a manager class that handles and tracks System Toolbars so you can automatically remove the Visual FoxPro system toolbars in your application and later restore them. This class is used with the framework generated by the Application Wizard.

Category | Application
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Application
Class | _systoolbars
Base Class | Custom
Class Library | _app.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\environ.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a project, you can choose between adding the class or creating a subclass. When you add the class to a form, Visual FoxPro places the icon on the form. You can then specify the appropriate property values and provide any necessary objects.

If lAutomatic is true (.T.), as in a READEVENTS-type application, the class automatically hides all existing system toolbars when you instantiate it. It then automatically restores the system toolbars hidden when it went out of scope.

You can also call the HideSystemToolbars( ) and ShowSystemToolbars( ) methods manually.

Properties, Events, Methods | Description
lAutomatic property | Automatically hides and restores system toolbars for the application. Default: .F.
aSystemToolbars[1,0] property | The array of system toolbars. Default: .F.
Hidesystemtoolbars method | Manually hides system toolbars for the application. Syntax: Hidesystemtoolbars( ) Return: none Arguments: none
Showsystemtoolbars method | Manually shows system toolbars for the application. Syntax: Showsystemtoolbars( ) Return: none Arguments: none
Initializetoolbararray method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Table Mover Foundation Class

Visual FoxPro 9.0 Language Reference
Table Mover Foundation Class
See Also

This subclass of the field mover list box class automatically loads tables and fields from the current datasource.

Category | Movers
Default Catalog | Visual FoxPro Catalog\Foundation Classes\User Controls
Class | _tablemover
Base Class | Container
Class Library | _mover.vcx
Parent Class | _fieldmover
Sample | ...\Samples\Solution\Ffc\movers.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a project, you can choose between adding the class or creating a subclass. When you add the class to a form, Visual FoxPro opens a builder so you can accept or specify the appropriate cDBCTable, cDBCName, SkipGeneral, SkipMemo, AllowReadOnly, and AllowQuery values on the form in the Form Designer.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
AllowQuery property | Specifies whether to allow queries. Default: .F.
AllowViews property | Specifies whether to allow views. Default: .T.
ExclDBF property | Specifies the name of the table to exclude from the list. Default: ""
ViewNoData property | Specifies whether to show view information without retrieving data. Default: .T.
GetDBCAlias method | Retrieves the database file (.dbc) alias. Syntax: GetDBCAlias(cDBC) Return: none Arguments: cDBC specifies the database alias.
GetDBCData method | Retrieves database table fields. Syntax: GetDBCData(cDBCName) Return: data fields Arguments: cDBCName specifies the name of the database.
GetDBCName method | Retrieves the database name. Syntax: GetDBCName( ) Return: none Arguments: none
GetDBCTable method | Retrieves the database table. Syntax: GetDBCTable(cDBCTable) Return: none Arguments: cDBCTable specifies the short name of the table.
GetFreeData method | Retrieves free table fields. Syntax: GetFreeData( ) Return: none Arguments: none
MoverRefresh method | Refreshes movers. Syntax: MoverRefresh(lRefresh, lQuickPass, cSaveLstValue) Return: none Arguments: lRefresh specifies whether to repopulate listboxes and popups.lQuickPass specifies whether to restore if the environment is unchanged.cSaveLstValue specifies the value to restore.
OpenTable method | Opens the datasource. Syntax: OpenTable( ) Return: none Arguments: none
UseTable method | Handles what table is opened with USE and whether the table is opened exclusively. Syntax: UseTable(cGetDBF, lUseExcl) Return: none Arguments: cGetDBF specifies the table to use.lUseExcl specifies whether the table is opened exclusively.
ExclusiveSet method | Internal to the class.
RefreshCurrent method | Internal to the class.
TableChange method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples
Field Mover Foundation Class


Text Preview Foundation Class

Visual FoxPro 9.0 Language Reference
Text Preview Foundation Class
See Also

When used on a project or form, this class provides a simple text editor in a dialog box that also contains buttons to format or save text, and to close the editor.

Category | Reporting
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Output
Class | _showtext
Base Class | Form
Class Library | _reports.vcx
Parent Class | _form
Sample | ...\Samples\Solution\Ffc\output.scx

Remarks

The main purpose of this class is to provide a controllable preview window to other classes in _reports.vcx. Therefore this dialog box has no button to load a new file (though you can add one in a subclass) and it defaults to read only for its edit box.

To use,drop the class on a project or, from the Component Gallery Item shortcut menu, select Add to Project. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. When you choose Create a new form from the selected class, Visual FoxPro opens a builder so you can specify the name of the form, then creates and opens the form in the Form Designer.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cFixedFontName property | The font name for contents of the edit box.Default: Courier New
nFixedFontSze property | The font size for contents of the edit box. Default: 9
cSourceFile property | The name of the source file to view or edit. Default: ""
cTargetFile property | The name of the file to which you save the contents of the edit box. Default: ""
lFixedFontBold property | Specifies a bold font for contents of the edit box. Default: .F.
lFixedFontiItalic property | Specifies an italic font for contents of the edit box. Default: .F.
lSuppressCaptionChange property | Prevents the dialog box caption from changing as the source file changes. This is useful for displaying the contents of a temporary file. Default: .F.
SetFonts method | Applies the current font property characteristics to the edit box displaying the file. Syntax: SetFonts( ) Return: none Arguments: none
GetFixedFont method | Uses a common dialog box to display fonts. Restricted to fixed font items. Syntax: GetFixedFont( ) Return: none Arguments: none
cTargetfile_access method | Internal to the class.
cSourcefile_assign method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Thermometer Foundation Class

Visual FoxPro 9.0 Language Reference
Thermometer Foundation Class
See Also

This class, when placed on a form, provides a standard thermometer class.

Category | User Interface
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Dialogs
Class | _thermometer
Base Class | Form
Class Library | _therm.vcx
Parent Class | _thermometer
Sample | ...\Samples\Solution\Ffc\therm.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Add to Project. When you drop the class on a project, you can choose between adding the class, creating a subclass, or creating a form. If you choose Create a new form from the selected class, Visual FoxPro displays the Open dialog box so you can specify the name of the form, then creates and opens the form in the Form Designer. You need to specify appropriate property values in the Update method.

Properties, Events, Methods | Description
cCurrentTask property | Specifies the current task. Default: ""
iBasis property | Specifies the basis for calculating the percentage. Default: 0
iPercentage property | Specifies the percentage completion at which the display updates. Default: 0
iProgress property | Specifies the amount completed (iPercentage). Default: 0
Complete method | Displays 100% complete thermometer. Syntax: Complete(m.cTask) Return: none Arguments: m.cTask specifies what to display when progress is complete.
Update method | Updates the thermometer. Syntax: Update(iProgress, cTask) Return: none Arguments: iProgress specifies the progress increment.cTask specifies the message to be displayed.
cThermRef property | Internal to the class.
ShpThermBarMaxWidth property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Trace Aware Timer Foundation Class

Visual FoxPro 9.0 Language Reference
Trace Aware Timer Foundation Class
See Also

This is an application utility that detects whether the trace window is open and handles debug timing appropriately.

Category | Application
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Application
Class | _traceawaretimer
Base Class | Timer
Class Library | _app.vcx
Parent Class | _timer
Sample | ...\Samples\Solution\Ffc\environ.scx

Remarks

Although Visual FoxPro makes it possible for you to skip tracing timer events altogether when debugging, this isn't always an appropriate solution because sometimes the code in timer events is pertinent to what you're trying to debug. Instead, this timer determines whether any of the debugging window is visible and if so, sets a special slow interval.

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Form. When you add the class to a project, you can choose between adding the class or creating a subclass. When you add the class to a form, Visual FoxPro places an icon on the form. You can then specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

Properties, Events, Methods | Description
iRegularInterval property | Specifies the standard interval period. Stored during the Init event, and restored during Timer events if you've changed the Interval. Default: 0
iTraceInterval property | Specfies a slower interval period to use while debugging. Default: 10000

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Type Library Foundation Class

Visual FoxPro 9.0 Language Reference
Type Library Foundation Class
See Also

This class uses the TlbInf32 COM component to read type information from type libraries. The main routine ExportTypeLib creates a text file with Type library output.

Category | File Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _typelib
Base Class | Container
Class Library | _utility.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Winapi\typelib.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a project, you can choose between adding the class or creating a subclass. When you add the class to a form, Visual FoxPro places the class icon on the form. You can then specify the appropriate property values on the form in the Form Designer.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
aTypeAttr[1,0] property | Specifies the array for the TypeAttr structure. Default: .F.
aTypeFuncDesc[1,0] property | Specifies an array for the FuncDesc structure. Default: .F.
aTypeFuncDocs[3,0] property | Specifies an array for function documentation. Default: .F.
aTypeFuncNames[1,0] property | Specifies an array of function names. Default: .F.
aTypeFuncParms[1,0] property | Specifies an array of the function parameters. Default: .F.
aTypeInfoDocs[3,0] property | Specifies an array for TypeInfo documentation. Default: .F.
aTypeLibDocs[3,0] property | Specifies an array for TypeLib documentation. Default: .F.
FuncNamesCount property | Specifies the number of names for TypeInfo function. This is equivalent to total parameters+1. Default: .F.
TypeInfoCount property | Specifies the number of TypeInfos in TypeLib. Default: .F.
TypeInfoIndex property | An index reference to TypeInfo. Default: .F.
TypeLibHandle property | The handle to TypeLib. Default: .F.
TypeLibName property | Specifies the name of the type library. Default: .F.
ExportTypeLib method | Exports contents of a TypeLib to a text file. Syntax: ExportTypeLib(cExportFile, lViewFile) Return: m.exportfile Arguments: cExportFile specifies the file to export.lViewFile specifies whether to open the file in a viewer after export.
GetDataType method | Returns data type of function. Syntax: GetDataType(m.nvt) Return: name of data type Arguments: m.nvt specifies a data item reference.
GetFuncDesc method | Obtains TypeInfo function info and populates arrays. Syntax: GetFuncDesc(nFuncIndex) Return: TypeInfo arrays, aTypeFuncParms, aTypeFuncNames, aTypeFuncDocs Arguments: nFuncIndex specifies the index of the function.
GetTypeInfo method | Obtains TypeInfo and populates TypeInfo arrays. Syntax: GetTypeInfo(nTypeInfoNum) Return: none Arguments: nTypeInfoNum specifies a reference to the Typeinfo key.
GetTypeLib method | Obtains TypeLib info and populates arrays. Syntax: GetTypeLib( ) Return: none Arguments: none

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


URL Combo Foundation Class

Visual FoxPro 9.0 Language Reference
URL Combo Foundation Class
See Also

This class, when placed on a form, creates a combo box for entering a Web URL. It launches Internet Explorer and navigates to the site.

Category | Internet
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Internet
Class | _urlcombobox
Base Class | Combobox
Class Library | _internet.vcx
Parent Class | _combobox
Sample | ...\Samples\Solution\Ffc\hyperlnk.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you drop the class on a project, you can choose between adding the class or creating a subclass. When you dropn the class on a form, Visual FoxPro opens a builder so you can specify the appropriate cURL, cURLHistoryTable,and iURLHistory values on the form in the Form Designer. You can use the history table to supply one or more start locations for Web navigation.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
cURL property | The current URL. Default: ""
cURLHistoryTable property | Specifies the name of the URL history table that retains previously accessed URLs. Default: (IIF(VERSION(2)=0,"",HOME( ))+"URLHst ry.dbf"))
lInitialized property | Control initialized flag. Default: .F.
lURLHistory property | Saves URL history. Default: .T.
Navigate method | Requests the document based on URL address. Syntax: Navigate( ) Return: none Arguments: none
cHyperlinkClass property | Internal to the class.
cHyperlinkclasslibrary property | Internal to the class.
cTempFilePrefix property | Internal to the class.
lDropDown property | Internal to the class.
lFormNavigate property | Internal to the class.
lGotFocus property | Internal to the class.
lMoveFocus property | Internal to the class.
lRequestOnEnter property | Internal to the class.
oHyperlink property | Internal to the class.
Initialize method | Internal to the class.
oHyperlink_access method | Internal to the class.
OpenURLHistory method | Internal to the class.
ValidURL method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


URL Open Dialog Box Foundation Class

Visual FoxPro 9.0 Language Reference
URL Open Dialog Box Foundation Class
See Also

This dialog box, when placed on a form, provides a dropdown that stores the URL history list.

Category | Internet
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Internet
Class | _openaddressdialog
Basse Class | Form
Class Library | _internet.vcx
Parent Class | _dialog
Sample | ...\Samples\Solution\Ffc\hyperlnk.scx

Remarks

To use, drop the class on a project or, from the Component Gallery Item shortcut menu, select Add to Project or Create Form. When you add the class to a project, you can choose between adding the class or creating a subclass, or creating a form. When you create a form, Visual FoxPro displays an Open dialog box so you can specify the name of the form, then creates and opens the form in the Form Designer so you can specify appropriate Target and lShellExecute values.

Properties, Events, Methods | Description
lShellExecute property | Runs the target URL. Default: .T.
Target property | Specifies the name of the target URL. Default: ""
cFileExt property | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


User Privileges Foundation Class

Visual FoxPro 9.0 Language Reference
User Privileges Foundation Class
See Also

This class returns the User Access Rights of the currently logged on user. On Windows 2000, this would be Guest, Power User or Administrator. This information is commonly needed in applications that provide Windows 2000 Logo compliancy.

Category | System Utilities
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Utilities
Class | _userpriv
Base Class | Custom
Class Library | _system.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\Logo.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places the class icon on the form. You can specify the appropriate property values and provide any necessary input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classes for more information on using foundation classes.

Properties, Events, Methods | Description
GetUserPriv method | Returns path to specified system folder. Syntax: GetUserPriv(cUser) Return: access of user Arguments: cUser specifies name of user to check.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


VCR Buttons Foundation Class

Visual FoxPro 9.0 Language Reference
VCR Buttons Foundation Class
See Also

This set of record navigation buttons is a subclass of _nav2buttons that includes Top, Next, Prev, and Bottom navigation buttons.

Category | Data Navigation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Navigation
Class | _nav4buttons
Base Class | Container
Class Library | _table.vcx
Parent Class | _nav2buttons
Sample | ...\Samples\Solution\Ffc\datanav.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item Sshortcut menu, select Add to Project or Add to Form. When you add the class to a form in a data environment, you need to provide appropriate input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


VCR Picture Navigation Buttons Foundation Class

Visual FoxPro 9.0 Language Reference
VCR Picture Navigation Buttons Foundation Class
See Also

This is a set of data navigation buttons that displays VCR pictures on the Top, Next, Previous, and Bottom buttons.

Category | Data Navigation
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Data Navigation
Class | _nav4picbuttons
Base Class | Container
Class Library | _table2.vcx
Parent Class | _nav4buttons
Sample | ...\Samples\Solution\Ffc\datanav.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form in a data environment, you need to specify the appropriate input and output objects. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Video Player Foundation Class

Visual FoxPro 9.0 Language Reference
Video Player Foundation Class
See Also

This class loads and plays a video file, and provides access to the Media Control Interface (MCI).

Category | Multimedia
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Multimedia
Class | _videoplayer
Base Class | Container
Class Library | multimedia.vcx
Parent Class | _container
Sample | ...\Samples\Solution\Forms\mci_play.scx

Remarks

To use, drop the class on a project or form, or from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you drop the class on a project, you can choose between adding the class or creating a subclass. When you choose an option from the shortcut menu or drop the class on a form, Visual FoxPro opens a builder so you can specify appropriate cFileName, lAutoOpen, lAutoPlay, lAutoRepeat, and cControlSource values.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
AutoOpen property | Specifies whether the video file specified should be automatically opened when the class is created. Default: .T.
AutoPlay property | Specifies whether the video file should automatically play after opening. Default: .T.
AutoRepeat property | If true (.T.), specifies that the video file will play continuously. Default: .T.
cFileName property | Specifies the video file associated with the Video Frame. Default: ""
Controlsource property | Specifies the source of data to which an object is bound. Default: ""
MCIAlias property | Specifies the alias for the video file when calling MCI commands. If empty, the name of the file is used. Default: ""
MCIError property | Specifies the result of the last MCI command executed. Default: 0
MCIErrorString property | Stores the error string from the last MCI command executed. Default: ""
CloseVideo method | Closes the video file and releases all resources. Syntax: CloseVideo( ) Return: none Arguments: none
DoMCI method | Executes an MCI command. Syntax: DoMCI(cMCIcmd) Return: cRetString Arguments: cMCIcmd specifies the command to run.
PauseVideo method | Pauses a currently playing video. Syntax: PauseVideo( ) Return: none Arguments: none
PlayVideo method | Plays the currently loaded video. Syntax: PlayVideo( ) Return: none Arguments: none
SetPosition method | Makes it possible for the user to set the position of the media file. Syntax: SetPosition(cPosition) Return: none Arguments: cPosition specifies Start, End, or a number representing milliseconds into the media file.
GetMCIError method | Internal to the class.
OpenVideo method | Internal to the class.
ShowMCIError method | Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples
Play Multimedia Files Using MCI Commands Sample


Web Browser Control Foundation Class

Visual FoxPro 9.0 Language Reference
Web Browser Control Foundation Class
See Also

This subclass of the Microsoft Internet Explorer browser control provides hooks for Visual FoxPro code and can be added to a Visual FoxPro form.

Category | Internet
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Internet
Class | _Webbrowser4
Class Library | _webview.vcx
Parent Class | olecontrol
Sample | ...\Samples\Solution\Ffc\Webvwr.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a form, Visual FoxPro places an Internet Explorer logo on your form. You need to specify an appropriate URL in the Navigate method. When you drop the class on a project, you can choose between adding the class or creating a subclass.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods | Description
aHistory[1,2] property | URL address history array. Default: .F.
aParam[1,0] property | URL parameters array. Default: .F.
aScripts[1,0] property | Visual FoxPro scripts array. Default: .F.
cAlias property | Returns the table alias of the currently selected. Set automatically when using the OpenTable method. Default: ""
cBeforeURL property | Specifies the current URL before a document is fully retrieved. Default: ""
cBlankHTMLFile property | Specifies a blank .htm file. Default: Blank.htm
cDBF property | Returns the file name of currently selected table. Set automatically when using the OpenTable method. Default: ""
cDBFPath property | Returns the path of the currently selected table. Set automatically when using the OpenTable method. Default: ""
cFilename property | Returns the file name of the current document. Default: ""
cFilepath property | Returns the path of the current document. Default: ""
cLasturl property | Specifies the last URL. Default: ""
cNewURL property | Specifies the URL before the document is fully retrieved. Default: ""
cParam property | Specifies the URL parameter string. Default: ""
cParamdelimiter property | Specifies the URL parameter delimiter character. Default: &
cParseFileExt property | File extension list of the file to parse in pre-processing mode. Default: htm;html;asp
cProgramPath property | Specifies the Web browser control class path. Default: ""
cSourceFile property | Specifies the file name of current document. Default: ""
cSourceFilename property | Specifies the file name of current source document. Default: ""
cSourceFilepath property | Specifies the path of current source document. Default: ""
cSourceHTML property | Specifies the HTML text of the current source document. Defaul t: ""
cSourceURL property | Specifies the URL of the current source document. Default: ""
cTempFilename property | Specifies the file name of the temporary file document. Default: ""
cTempFilePrefix property | Prefix used for the file name of the temporary file document. Default: _temp
cURL property | Current URL. Default: ""
cUserID property | User ID, user-defined, not used internally. Default: ""
cUserName property | User name, user defined, not used internally. Default: ""
cVersion property | Specifies the version of the Web browser control subclass. Default: "Web Browser 04.01.0006"
cVFPScript property | Specifies the Visual FoxPro script program file name. Default: ""
cVFPScriptTable property | Specifies the Visual FoxPro script table file name. Default: ""
cVFPSprotocol property | Specifies the default Visual FoxPro script protocol string. Default: vps:
lBlankHTMLStartup property | Specifies whether the browser starts with a blank startup Web page. Default: .F.
lBusy property | Web browser busy mode. D efault: .F.
lDebug property | Specifies whether the Web browser runs in Debug mode. Default: .F.
lDesign property | Specifies whether the Web browser runs in design mode. Default: .F.
lDHTML property | Specifies whether the Web browser supports dynamic HTML. Default: .T.
lHistoryEnabled property | Specifies whether URL history tracking is enabled. Default: .F.
lParseSource property | Specifies whether Parse document source mode is enabled. Default: .F.
lRefresh property | Specifies whether the control is refreshed when the Refresh method runs. Default: .F.
lRefreshDeactivate property | Specifies whether auto-execution of the RefreshDeactivate method for the LostFocus event is enabled. Default: .F.
lRefreshMode property | Specifies whether Refresh document mode is enabled. Default: .F.
lRelease property | Specifies whether the object's Release method has been executed and the object is in the process of being released from memory. Default: .F.
lRunCodeMode property | Specifies whether Run code mode is enabled. Default: .F.
lVFPsScript property | Specifies whether Visual FoxPro script mode is enabled. Default: .F.
lViewSourceMode property | Specifies whether View source mode is enabled. Default: .F.
nDataSessionID property | Specifies the data session number of the table alias of the currently selected table that was set automatically when using the OpenTable method. Default: 0
nHistoryCount property | Specifies the length of the URL history array. Default: 0
nParamCount property | Specifies the length of the URL parameter array. Default: .F.
nRecno property | Specifies the current record number of the currently selected table that was set automatically when using the OpenTable method. Default: 0
nScriptCount property | Specifies the length of the Visual FoxPro script array. Default: 0
nUserLevel property | Specifies the user level, user defined, not used internally. Default: 0
oAction property | Specifies the user action object, user defined, not used internally. Default: .NULL.
oHost property | Specifies the host form – equivalent to THISFORM. Default: .NULL.
oSource property | Specifies the source object, user defined, not used internally. Default: .NULL.
oUser property | Specifies the user object, user defined, not used internally. Default: .NULL.
uResult property | Specifies the variant result value. Default: .T.
uReturn property | Specifies the variant return value. Default: .T.
uValue property | Specifies the variant value, user defined, not used internally. Default: .T.
AddProp method | Adds a new property. Syntax: AddProp(tcName, tcProperty, tuValue) Arguments: tcName specifies tcProperty specifies the name of the property.tuValue specifies the value to assign to the property.
BeforeNavigate method | Provides a BeforeNavigate event. Syntax: BeforeNavigate(URL, flags, targetframename, postdata, headers, cancel) Arguments: URL specifies the Web page to use.flags specifies whether to add the resource to the history list, to read or write from the cache, display the resource in a new window or a combination of these.targetframename specifies the name of the target frame.postdata specifies data to send to the HTTP Post transaction.headers specifies the HTTP headers to send.cancel specifies whether navigation was cancelled.
BeforeRetrieval method | Identifies the event to run before retrieval. Syntax: BeforeRetrieval(URL, flags, targetframename, postdata, headers, cancel) Arguments: URL specifies the Web page to use.flags specifies whether to add the resource to the history list, to read or write from the cache, display the resource in a new window or a combination of these.targetframename specifies the name of the target frame.postdata specifies data to send to the HTTP Post transaction.headers specifies the HTTP headers to send.cancel specifies whether navigation was cancelled.
BrowseTable method | Browse the currently selected based on cAlias. Syntax: BrowseTable(tcAlias, tcClauses)
CloseTable method | Close the currently selected based on cAlias. Syntax: CloseTable(tcAlias)
EditScript method | Edit a specific Visual FoxPro script. Syntax: EditScript(tcScriptName) Arguments: tcScriptName specifies the name of the Visual FoxPro script.
EditString method | Opens a string in an edit window. Syntax: EditString(tcString, tcTitle, tlNoEdit) Arguments: tcString specifies the string to edit.tcTitle specifies the name of the edit window.tlNoEdit specifies whether string is editable.
EraseTempFile method | Specifies whether to erase the current temporary file. Syntax: EraseTempFile( ) Ret urn: none Arguments: none
FileToString method | Returns the string contents of a file. Syntax: FileString(tcFileName) Arguments: tcFileName specifies the name of the file from which to extract the string.
FrameBeforeNavigate method | Provides a FrameBeforeNavigate event. Syntax: FrameBeforeNavigate(URL, flags, targetframename, postdata, headers, cancel) Arguments: URL specifies the Web page to use.flags specifies whether to add the resource to the history list, to read or write from the cache, display the resource in a new window or a combination of these.targetframename specifies the name of the target frame.postdata specifies data to send to the HTTP Post transaction.headers specifies the HTTP headers to send.cancel specifies whether navigation was cancelled.
GetHTML method | Returns the HTML of the current document. Syntax: GetHTML(tcName, tcAlias) Arguments: tcName specifies the name of the document to return.tcAlias specifies the alias of cVFPScriptTable.
GetSourceFile method | Returns the file name of the current source document. Syntax: GetSourceFile( ) Arguments: none
GetSourceHTML method | Returns the HTML of the current source document. Syntax: GetSourceHTML( ) Arguments: none
GoBack method | Executes a hyperlink jump backward within the history list. Syntax: GoBack( ) Return: none Arguments: none
GoForward method | Executes a hyperlink jump forward within the history list. Syntax: GoForward( ) Return: none Arguments: none
Msgbox method | Message box handler method. Syntax: Msgbox(tcMessage, tnType,tcTitle) Arguments: tcMessage specifies the message to display.tnType specifies the messagebox type.tcTitle specifies the title of the messagebox.
NavigateComplete method | Provides a NavigateComplete event. Syntax: NavigateComplete(URL) Arguments: URL specifies the Web page to navigate.
NewWindow method | Provides a NewWindow event. Syntax: NewWindow(URL, flags, targetframename, postdata, headers, processed) Arguments: URL specifies the Web page to use.flags specifies whether to add the resource to the history list, to read or write from the cache, display the resource in a new window or a combination of these.targetframename specifies the name of the target frame.postdata specifies data to send to the HTTP Post transaction.headers specifies the HTTP headers to send.cancel specifies whether navigation was cancelled.
OpenTable method | Opens the specified table and activates it as the current table by setting the cAlias property. Syntax: OpenTable(tcFileName, tcAlias,tlExclusive, tcFilter) Arguments: tcFileName specifies the name of the table to open.tcAlias the alias of the table.tlExclusive specifies whether to open the table EXCLUSIVE.tcFilter specifies a filter expression to use.
OpenVFPScript method | Opens the Visual FoxPro script table. Syntax: OpenVFPScript( )
ParseSource method | Parses the source code of the HTML document. Syntax: ParseSource(URL, flags, targetframename, postdata, headers, cancel) Arguments: URL specifies the Web page to use.flags specifies whether to add the resource to the history list, to read or write from the cache, display the resource in a new window or a combination of these.targetframename specifies the name of the target frame.postdata specifies data to send to the HTTP Post transaction.headers specifies the HTTP headers to send.cancel specifies whether navigation was cancelled.
RefreshDeactivate method | Use when losing focus of the Web browser control. Syntax: RefreshDeactivate( ) Arguments: none
RefreshMode method | Set refresh mode. Syntax: Refresh( ) Arguments: none
RefreshSource method | Refresh the source. Syntax: RefreshSource( ) Return: none Arguments: none
ReleaseHost method | Release the host form. Syntax: ReleaseHost( ) Arguments: none
RunAction method | Run action that is a specific method of the object referenced by the oAction property. Syntax: RunAction(tcMethod) Arguments: tcMethod specifies the method to run.
RunCode method | Run a specific block of Visual FoxPro code without compilation. Syntax: RunCode(tcCode) Arguments: tcCode specifies the Visual FoxPro code to run.
RunScript method | Run a specific Visual FoxPro script. Syntax: RunScript(tcScript, tcAlias) Arguments: tcScript specifies the script to run.tcAlias specifies the alias of the file containing tcScript.
SetBusyState method | Set busy state method. Syntax: SetBusyState(tlBusy) Arguments: tlBusy specifies whether a download is in process.
SetParam method | Set URL parameters method. Syntax: SetParam(tcParam) Arguments: tcParam
SkipRecord method | Skip record of currently selected table, based on cAlias. Syntax: SkipRecord(tnRecords) Arguments: tnRecords specifies the number of records to skip.
StringToFile method | Saves string contents to file. Syntax: StringToFile(tcText, tcFileName) Arguments: tcText specifies the text to save.tcFileName specifies the target file.
TrimExt method | Returns a file name without extension. Syntax: TrimExt(tcFileName, tlPlatformType) Return: cFilename Arguments: tcFileName specifies the filename to process.tlPlatformType specifies whether a file is from a DOS or Unix computer.
TrimFile method | Returns the path of the specified file name. Syntax: TrimFile(tcFileName, lPlatType) Arguments: tcFileName specifies the name of the target file.lPlatType specifies whether a file is from a DOS or Unix computer.
TrimPath method | Returns the file name without a path. Syntax: TrimPath(tcFileName, tlTrimExt, tlPlatformType) Arguments: tcFileName specifies name of the file.tlTrimExt specifies whether to remove the extension.tlPlatformType specifies whether a file is from a DOS or Unix computer.
ValidateURL method | Validates the URL. Syntax: ValidateURL(tcURL) Arguments: tcUrl specifies the Web page to validate.
ValidURL method | Returns the validated URL. Syntax: ValidURL(tcURL) Arguments: tcUrl specifies the Web page to return.
VFPS method | Executes a Visual FoxPro script based on the specified URL. Syntax: VFPS(tcCommand) Arguments: tcCommand specifies the Visual FoxPro expression to run.
VFPScript method | Executes a specific Visual FoxPro script. Syntax: VFPScript(tcName, tcAlias, tnCode) Arguments: tcName specifies the name of the file cVFPScript.tcAlias specifies the alias of cVFPScriptTable.tnCode specifies the Visual FoxPro code to run.
ViewSource method | View the source of the current document. Syntax: ViewSource(tlNoWait, tlNoEdit) Arguments: tlNoWait specifies whether the program pauses while the window displays.tlNoEdit specifies whether the viewed source is editable.
WaitWindow method | Wait window wrapper method. Syntax: WaitWindow(tcText, tlWait) Arguments: tcText specifies the text that displays in the Wait Window.tlWait specifies whether the program pauses while the window displays.
WildcardMatch method | Returns true (.T.) if the wild card string is matched to a specific string. Syntax: WildcardMatch(tcMatchExpList, tcExpressionSearched, tlMatchAsIs) Return: lMatch Arguments: tcMatchExpList specifies the search expression.tcExpressionSearched specifies the target expression.tlMatchAsIs specifies whether to enforce an exact string match.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


Window Handler Foundation Class

Visual FoxPro 9.0 Language Reference
Window Handler Foundation Class
See Also

This general purpose Window Handler class performs several common window operations such as cascading windows.

Category | Application
Default Catalog | Visual FoxPro Catalog\Foundation Classes\Application
Class | _windowhandler
Base Class | Custom
Class Library | _ui.vcx
Parent Class | _custom
Sample | ...\Samples\Solution\Ffc\whandler.scx

Remarks

To use, drop the class on a project or form or, from the Component Gallery Item shortcut menu, select Add to Project or Add to Form. When you add the class to a project, you can choose between adding the class or creating a subclass. When you add the class to a form, Visual FoxPro displays the icon on the form so you can specify appropriate properties values its available methods in the Form Designer.

See Guidelines for Using Visual FoxPro Foundation Classesfor more information on using foundation classes.

Properties, Events, Methods Description

IMDIWorkspaceColor property

Contains the Windows color for top-level frame window.

Default: 0

CascadeFormInstances method

Cascades forms.

Syntax: CascadeFormInstances(tcFormName, tlOmitAutoCenteredForms, tnStartTop, tnStartLeft, tnStartColumn)

Return: none

Arguments: tcFormName specifies the form or _screen in which to cascade forms.tlOmitAutoCenteredForms specifies whether to skip cascading for autocentered forms.tnStartTop specifies starting top coordinate.tnStartLeft specifies starting left coordinate.

GetCurrentTopFormRef method

Returns the current frame window. Use primarily for top-level form applications.

Syntax: GetCurrentTopFormReference( )

Return: loTopForm

Arguments: none

IMDIWorkspaceColor_access( )

Syntax: IMDIWorkspaceColor_access( )

Return: GetSysColor(12)

Argum ents: none

InvokeMenuItemInFrame method

Use to invoke menu items in top-level form applications to access certain system dialog boxes, such as the Find dialog box. Also use to implement a menu item in a dialog box that does not have a menu.

Syntax: InvokeMenuItemInFrame(tcAction)

Return: none

Arguments: tcAction specifies navigation action such as NEXT or PREVIOUS. You can also use the following actions: UNDO, REDO, CUT, COPY, PASTE, CLEAR, SELECTALL, FIND, FINDAGAIN, REPLACE.

ShowCurrentTopForm method

Internal to the class.

ShowWindowInFrame method

Internal to the class.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Visual FoxPro Foundation Class Samples


XML Web Services Foundation Classes

Visual FoxPro 9.0 Language Reference
XML Web Services Foundation Classes
See Also

The XML Web Service Foundation class libraries, _WS3Utils.vcx and _WS3Client.vcx, contain a collection of classes that serve as the Visual FoxPro XML Web service extensions for Microsoft SOAP Toolkit version 3.0. Use these classes to register XML Web services in compliance with those supported by the Toolkit. You can also publish Visual FoxPro COM Servers (.dll files) as XML Web services using these extensions.

_WS3Utils.vcx Class Library

Class | Description
Olecontrols | Tree view control used by the XML Web Service Builder.
Wsbasebuilder | Base form class used by the XML Web Service Builder.
Wsbuilder | Initial XML Web Service Builder dialog box.
Wsbuilder1 | XML Web Service – Operation Detail dialog box.
Wsbuilder2 | XML Web Service – Client Detail dialog box.
Wsbuilder3 | XML Web Service – Complex Types dialog box.
Wsbuilder4 | XML Web Service – Parameter Values dialog box.
Wsconfig | Dialog box used by the Web Services Publisher to specify a URL location for WSDL files.
Wsfoxcode | Class used to handle IntelliSense for an XML Web service when accessing in the editing window for a program.
Wsmanager | Class called by the XML Web Services pane in the Task Pane Manager to manage XML Web services.
Wsphook | Project hook class used by the XML Web Services Publisher to regenerate WSDL files when project is rebuilt.
Wspicker | Dialog box for selecting an XML Web service class to insert proxy code. This dialog box opens when you type the characters, ws, in an editing window for a program.
Wsproxy | Class used to generate proxy code when a XML Web service class is dragged and dropped from the Toolbox to an editing window for a program or called by typing the characters, ws, in the editing window.
Wspub | Visual FoxPro XML Web Services Publisher dialog box.
Wsreg | Visual FoxPro XML Web Services Registration dialog box.
Wstest | Dialog box called from the XML Web Services pane in the Task Pane Manager for testing an XML Web service.
Wstool | Visual FoxPro XML Web Services Publisher Advanced dialog box.
Wsuddi | Visual FoxPro XML Web Services Registration UDDI Search dialog box.
_webservices | Core engine class for publishing and registering XML Web services.

_WS3Client.vcx Class Library

Class | Description
Wshandler | Core client class used to communicate with a XML Web service. This class is used in the proxy code generated in the editing window of a program and when visually binding controls to XML Web services on a form.
Colbase | Class from which the XML Web service collection classes are derived.
Colclient | Class added to the ColClients clients collection.
Colclients | Operation clients collection class.
Coloperation | Class added to the Coloperations operations collection.
Coloperations | Operations collection class.
Colparm | Class added to the Colparms parameters collection.
Colparms | Operation parameters collection class
Wsparms | Dialog box that prompts a user to enter parameters for the XML Web service operation call.
Wsparmzoom | Zoom dialog box used by the input parameters dialog box.

Remarks

In the _WS3Utils.vcx class library, the core engine class, _WebServices, communicates directly with the Toolkit. The _WebServices class contains methods for publishing XML Web services, including those that read type library information from your server and those that generate the necessary XML Web service support files, for example, ASP listener and WSDL service description files. You can also register an external XML Web service using the methods provided.

The _WS3Utils.vcx class library contains other support classes for working with XML Web services. These classes are essentially form classes that assist the user in gathering information for registering and publishing XML Web services. They work in conjunction with the _WebServices class.

In the _WS3Client.vcx class library, the core class for using an XML Web service is WSHandler. This class handles all calls to the SOAP Toolkit 3.0 SOAP Client classes that connect to an XML Web service and call operations.

For more information about using foundation classes, see Guidelines for Using Visual FoxPro Foundation Classes.

See Also

Other Resources

Guidelines for Using Visual FoxPro Foundation Classes
Visual FoxPro Foundation Classes A-Z
Foundation Class Samples


Properties (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Properties (Visual FoxPro)
See Also

For information about backward compatible-only language reference, see Backward-Compatible Language Elements.

ActiveColumn Property

ActiveControl Property

ActiveForm Property

ActivePage Property

ActiveProject Property

ActiveRow Property

AddLineFeeds Property

ADOCodePage Property

Alias Property

Align Property

Alignment Property

AllowAddNew Property

AllowAutoColumnFit Property

AllowCellSelection Property

AllowDelete Property

AllowHeaderSizing Property

AllowInsert Property

AllowModalMessages Property

AllowOutput Property

AllowRowSizing Property

AllowSimultaneousFetch Property

AllowTabs Property

AllowUpdate Property

AlwaysOnBottom Property

AlwaysOnTop Property

Anchor Property

Application Property

AutoActivate Property

AutoCenter Property

AutoCloseTables Property

AutoComplete Property

AutoCompSource Property

AutoCompTable Property

AutoHideScrollBar Property

AutoIncrement Property

AutoOpenTables Property

AutoRelease Property

AutoSize Property

AutoVerbMenu Property

AutoYield Property

BackColor, ForeColor Properties

BackStyle Property

BaseClass Property

BatchUpdateCount Property

BindControls Property

BorderColor Property

BorderStyle Property

BorderWidth Property

Bound Property

BoundColumn Property

BoundTo Property

BreakOnError Property

BufferMode Property

BufferModeOverride Property

BuildDateTime Property

ButtonCount Property

Buttons Property

Cancel Property

Caption Property

Centered Property

Century Property

ChildAlias Property

ChildOrder Property

ChildTable Property

Class Property

ClassLibrary Property

ClipControls Property

ClosableProperty

CLSID Property

CodePage Property

ColorScheme Property

ColorSource Property

ColumnCount Property

ColumnLines Property

ColumnOrder Property

Columns Property

ColumnWidths Property

CommandClauses Property

Comment Property

CompareMemo Property

ConflictCheckCmd Property

ConflictCheckType Property

ContinuousScroll Property

ControlBox Property

ControlCount Property

Controls Property

ControlSource Property

ConversionFunc Property

Count Property

CurrentControl Property

CurrentDataSession Property

CurrentPass Property

CurrentX, Current Y Properties

CursorSchema Property

CursorSource Property

CursorStatus Property

Curvature Property

Database Property

DataSession Property

DataSessionID Property

DataSource Property

DataSourceType Property

DataType Property

DateFormat Property

DateMark Property

Debug Property

DeclareXMLPrefix Property

DEClass Property

DEClassLibrary Property

Default Property

DefaultFilePath Property

DefOLELCID Property

DeleteCmd Property

DeleteCmdDataSource Property

DeleteCmdDataSourceType Property

DeleteMark Property

Description Property

Desktop Property

Details Property

DisabledBackColor, DisabledForeColor Properties

DisabledItemBackColor, DisabledItemForeColor Properties

DisabledPicture Property

DisableEncode Property

DisplayCount Property

DisplayValue Property

Dockable Property

Docked Property

DockPosition Property

DocumentFile Property

DownPicture Property

DragIcon Property

DragMode Property

DrawMode Property

DrawStyle Property

DrawWidth Property

DynamicAlignment Property

DynamicBackColor, DynamicForeColor Properties

DynamicCurrentControl Property

DynamicFontBold, DynamicFontItalic, DynamicFontStrikethru, DynamicFontUnderline Properties

DynamicFontName Property

DynamicFontOutline Property

DynamicFontShadow Property

DynamicFontSize Property

DynamicInputMask Property

DynamicLineHeight Property

EditorOptions Property

Enabled Property

EnableHyperlinks Property

Encrypted Property

ErrorNo Property

Exclude Property

Exclusive Property

FetchAsNeeded Property

FetchMemo Property

FetchMemoCmdList Property

FetchMemoDataSource Property

FetchMemoDataSourceType Property

FetchSize Property

FileClass Property

FileClassLibrary Property

FillColor Property

FillStyle Property

Filter Property

FirstElement Property

FirstNestedTable Property

Flags Property

FontBold, FontItalic, FontStrikethru, FontUnderline Properties

FontCharSet Property

FontCondense, FontExtend Properties

FontName Property

FontOutline Property

FontShadow Property

FontSize Property

ForceCloseTag Property

Format Property

FormCount Property

FormattedOutput Property

Forms Property

FractionDigits Property

FRXDataSession Property

FullName Property

GDIPlusGraphics Property

GridLineColor Property

GridLines Property

GridLineWidth Property

HalfHeightCaption Property

HeaderClass Property

HeaderClassLibrary Property

HeaderHeight Property

Height Property

HelpContextID Property

HideSelection Property

Highlight Property

HighlightBackColor Property

HighlightForeColor Property

HighlightStyle Property

HighlightRow Property

HighlightRowLineWidth Property

HomeDir Property

Hours Property

HostName Property

HScrollSmallChange Property

HWnd Property

Icon Property

Increment Property

IncrementalSearch Property

InitialSelectedAlias Property

InputMask Property

InsertCmd Property

InsertCmdDataSource Property

InsertCmdDataSourceType Property

InsertCmdRefreshCmd Property

InsertCmdRefreshFieldList Property

InsertCmdRefreshKeyFieldList Property

Instancing Property

IntegralHeight Property

Interval Property

IMEMode Property

IsAttribute Property

IsBase64 Property

IsBinary Property

IsNull Property

IsDiffGram Property

IsLoaded Property

ItemBackColor, ItemForeColor Properties

ItemData Property

ItemIDData Property

ItemTips Property

IXMLDomElement Property

KeyboardHighValue, KeyboardLowValue Properties

KeyField Property

KeyFieldList Property

KeyPreview Property

KeySort Property

LanguageOptions Property

Left Property

LeftColumn Property

LineContents Property

LineNo Property

LineSlant Property

LinkMaster Property

List Property

ListCount Property

ListenerType Property

ListIndex Property

ListItem Property

ListItemID Property

LockColumns Property

LockColumnsLeft Property

LockScreen Property

MacDesktop Property

MainFile Property

MapN19_4ToCurrency Property

MapBinary Property

MapVarchar Property

Margin Property

MaxButton Property

MaxHeight Property

MaxLeft Property

MaxLength Property

MaxRecords Property

MaxTop Property

MaxWidth Property

MDIForm Property

MemberClass Property

MemberClassLibrary Property

MemoWindow Property

Message Property

MinButton Property

MinHeight Property

MinWidth Property

MouseIcon Property

MousePointer Property

Movable Property

MoverBars Property

MultiSelect Property

Name Property

NestedInto Property

NewIndex Property

NewItemID Property

NextSiblingTable Property

NoCpTrans Property

NoData Property

NoDataOnLoad Property

NullDisplay Property

NumberOfElements Property

Object Property

OLEClass Property

OLEDragMode Property

OLEDragPicture Property

OLEDropEffects Property

OLEDropHasData Property

OLEDropMode Property

OLEDropTextInsertion Property

OLELCID Property

OLERequestPendingTimeout Property

OLEServerBusyRaiseError Property

OLEServerBusyTimeout Property

OLETypeAllowed Property

OneToMany Property

OpenViews Property

OpenWindow Property

Optimize Property

Order Property

OrderDirection Property

OutputPageCount Property

OutputType Property (Visual FoxPro)

PageCount Property

PageHeight Property

PageNo Property

PageOrder Property

Pages Property

PageTotal Property

PageWidth Property

Panel Property

PanelLink Property

Parent Object Reference

ParentAlias Property

ParentClass Property

ParentTable Property

Partition Property

PasswordChar Property

Picture Property

PictureMargin Property

PicturePosition Property

PictureSpacing Property

PictureSelectionDisplay Property

PictureVal Property

Prepared Property

PolyPoints Property

PreserveWhiteSpace Property

PreviewContainer Property

PrintJobName Property

Procedure Property

ProcessID Property

ProgID Property

ProjectHook Property

ProjectHookClass Property

ProjectHookLibrary Property

QuietMode Property

ReadCycle Property

ReadLock Property

ReadMouse Property

ReadObject Property

ReadOnly Property

ReadSave Property

ReadTimeout Property

RecordMark Property

RecordSource Property

RecordSourceType Property

RefreshAlias Property

RefreshCmd Property

RefreshCmdDataSource Property

RefreshCmdDataSourceType Property

RefreshIgnoreFieldList Property

RefreshTimeStamp Property

RelationalExpr Property

RelativeColumn Property

RelativeRow Property

ReleaseType Property

Resizable Property

RespectCursorCP Property

RespectNesting Property

RightToLeft Property

RotateFlip Property

Rotation Property (Visual FoxPro)

RowColChange Property

RowHeight Property

RowSource Property

RowSourceType Property

ScaleMode Property

SCCProvider Property

SCCStatus Property

ScrollBars Property

Seconds Property

SelectCmd Property

Selected Property

SelectedID Property

SelectedItemBackColor Property

SelectedItemForeColor Property

SelectionNamespaces Property

SelectOnEntry Property

SelLength Property

SelStart Property

SelText Property

SendGDIPlusImage Property

SendUpdates Property

ServerClass Property

ServerClassLibrary Property

ServerHelpFile Property

ServerName Property

ServerProject Property

ShowTips Property

ShowInTaskbar Property

ShowWindow Property

Sizable Property

SizeBox Property

SOM Property

Sorted Property

Sparse Property

SpecialEffect Property

SpinnerHighValue, SpinnerLowValue Properties

SplitBar Property

StackLevel Property

StartMode Property

StatusBar Property

StatusBarText Property

Stretch Property

StrictDateEntry Property

Style Property

TabIndex Property

Tables Property

TabOrientation Property

Tabs Property

TabStop Property

TabStretch Property

TabStyle Property

Tag Property

TerminateRead Property

Text Property

Themes Property

ThreadID Property

TimestampFieldList Property

TitleBar Property

ToolTipText Property

Top Property

TopIndex Property

TopItemID Property

TwoPassProcess Property

Type Property

TypeLibCLSID Property

TypeLibDesc Property

TypeLibName Property

Unicode Property

UpdatableFieldList Property

UpdateCmd Property

UpdateCmdDataSource Property

UpdateCmdDataSourceType Property

UpdateCmdRefreshCmd Property

UpdateCmdRefreshFieldList Property

UpdateCmdRefreshKeyFieldList Property

UpdateGram Property

UpdateGramSchemaLocation Property

UpdateNameList Property

UpdateType Property

UseCodePage Property

UseCursorSchema Property

UseDeDataSource Property

UseMemoSize Property

UserValue Property

UseTransactions Property

UTF8Encoded Property

Value Property

Version Property

VersionComments Property

VersionCompany Property

VersionCopyright Property

VersionDescription Property

VersionNumber Property

VersionProduct Property

VersionTrademarks Property

VFPXMLProgID Property

ViewPortHeight Property

ViewPortLeft Property

ViewPortTop Property

ViewPortWidth Property

VScrollSmallChange Property

View Property

Visible Property

VisualEffect Property

WhatsThisButton Property

WhatsThisHelp Property

WhatsThisHelpID Property

WhereType Property

Width Property

WindowList Property

WindowState Property

WindowType Property

WordWrap Property

WrapCharInCDATA Property

WrapInCDATA Property

WrapMemoInCDATA Property

XMLAdapter Property

XMLConstraints Property

XMLName Property

XMLNameIsXPath Property

XMLNamespace Property

XMLPrefix Property

XMLSchemaLocation Property

XMLTable Property

XMLType Property

XSDfractionDigits Property

XSDmaxLength Property

XSDtotalDigits Property

XSDtype Property

ZoomBox Property

See Also

Other Resources

Language Reference


ActiveColumn Property

Visual FoxPro 9.0 Language Reference
ActiveColumn Property
See Also Example

Returns as an integer the column number that contains the active cell in a Grid control. Not available at design time; read-only at run time.

Grid.ActiveColumn

Remarks

Applies To: Grid Control

ActiveColumn returns zero if the grid doesn't have the focus.

Example

The following example shows the use of the ActiveColumn Grid property.
Copy Code
m.cTalk=SET("TALK")
SET TALK OFF

PUBLIC oTlb
oTlb = NEWOBJECT("tlbDemo")
oTlb.SHOW

PUBLIC oFrmDemo
oFrmDemo=NEWOBJECT("frmDemo")
oFrmDemo.SHOW

READ EVENTS

RELEASE oTlb
RELEASE oFrmDemo
SET TALK &cTalk

RETURN

DEFINE CLASS tlbDemo AS TOOLBAR

    HEIGHT = 31
    LEFT = 30
    TOP = 30
    WIDTH = 149
    NAME = "tlbDemo"
    CAPTION = "Example"
    CONTROLBOX = .F.

    ADD OBJECT cmdShowColumn AS COMMANDBUTTON WITH ;
        TOP = 5, ;
        LEFT = 5, ;
        HEIGHT = 22, ;
        WIDTH = 100, ;
        CAPTION = "ActiveColumn?", ;
        NAME = "cmdShowColumn"

    ADD OBJECT sepSeparator1 AS SEPARATOR WITH ;
        TOP = 5, ;
        LEFT = 80, ;
        HEIGHT = 0, ;
        WIDTH = 0, ;
        NAME = "sepSeparator1"

    ADD OBJECT cmdExit AS COMMANDBUTTON WITH ;
        TOP = 5, ;
        LEFT = 80, ;
        HEIGHT = 22, ;
        WIDTH = 34, ;
        CAPTION = "Exit", ;
        NAME = "cmdExit"

    PROCEDURE cmdShowColumn.CLICK
        DO ShowColumn
    ENDPROC

    PROCEDURE cmdExit.CLICK
        CLEAR EVENTS
    ENDPROC

ENDDEFINE

DEFINE CLASS frmDemo AS FORM

    CLOSABLE = .F.
    CAPTION = "ActiveColumn Example"
    NAME = "frmDemo"
    LEFT = 60
    TOP = 100

    ADD OBJECT grdNames AS GRID WITH ;
        COLUMNCOUNT = 3, ;
        DELETEMARK = .F., ;
        HEIGHT = 128, ;
        LEFT = 12, ;
        PANEL = 1, ;
        RECORDSOURCE = "names", ;
        SPLITBAR = .F., ;
        TABINDEX = 3, ;
        TOP = 48, ;
        WIDTH = 340, ;
        NAME = "grdNames", ;
        Column1.CONTROLSOURCE = "names.cname", ;
        Column1.WIDTH = 122, ;
        Column1.NAME = "Column1", ;
        Column2.CONTROLSOURCE = "names.nvalue", ;
        Column2.WIDTH = 100, ;
        Column2.NAME = "Column2", ;
        Column3.CONTROLSOURCE = "names.dbirth", ;
        Column3.WIDTH = 122, ;
        Column3.NAME = "Column3"

    PROCEDURE LOAD
        CREATE CURSOR names (cname C(40), nvalue N(19,2), dbirth D)
        INSERT INTO names VALUES('Thomas',12.5,{^1990-5-11})
        INSERT INTO names VALUES('Jerry',18.2,{^1993-1-28})
        INSERT INTO names VALUES('Andrew',9.2,{^1986-1-23})
        GO TOP
    ENDPROC

    PROCEDURE INIT
        THIS.grdNames.Column1.Header1.CAPTION = "Name"

        WITH THIS.grdNames.Column1.Text1
            .BORDERSTYLE = 0
            .MARGIN = 0
        ENDWITH

        THIS.grdNames.Column2.Header1.CAPTION = "Value"

        WITH THIS.grdNames.Column2.Text1
            .BORDERSTYLE = 0
            .MARGIN = 0
        ENDWITH

        THIS.grdNames.Column3.Header1.CAPTION = "Birthdate"

        WITH THIS.grdNames.Column3.Text1
            .BORDERSTYLE = 0
            .MARGIN = 0
        ENDWITH

    ENDPROC

ENDDEFINE

PROCEDURE ShowColumn
    WAIT WINDOW AT 4,30 "_SCREEN.ActiveForm.ActiveControl.ActiveColumn = "+TRANSFORM(_SCREEN.ActiveForm.ActiveControl.ActiveColumn) NOWAIT
ENDPROC

See Also

Other Resources

ActivateCell Method
ActiveRow Property
GridHitTest Method
Properties
Language Reference


ActiveControl Property

Visual FoxPro 9.0 Language Reference
ActiveControl Property
See Also Example

References the active control on an object. Not available at design time; read-only at run time.

Object.ActiveControl.Property[ = Value]

Return Value

Property

The property to return or set.
Value

The current or new property value.

Remarks

Applies To: Container Object | Form Object | Page Object | _SCREEN | ToolBar Object

This property is not available if all controls on the specified object are invisible or disabled.

If the object is active, the ActiveControl property references the control that has the focus. If the object is not active, an error occurs.

Example

The following example uses the ActiveControl property to show which control on a Form has focus. Note that Grids are containers, and they require code to determine the current ActiveControl within the Grid.
Copy Code
m.cTalk=SET("TALK")
SET TALK OFF

PUBLIC oTlb
oTlb = NEWOBJECT("tlbDemo")
oTlb.SHOW

PUBLIC oFrmDemo
oFrmDemo=NEWOBJECT("frmDemo")
oFrmDemo.SHOW

READ EVENTS

RELEASE oTlb
RELEASE oFrmDemo
SET TALK &cTalk

RETURN

DEFINE CLASS tlbDemo AS TOOLBAR

    HEIGHT = 31
    LEFT = 30
    TOP = 30
    WIDTH = 149
    NAME = "tlbDemo"
    CONTROLBOX = .F.

    ADD OBJECT cmdShowControl AS COMMANDBUTTON WITH ;
        TOP = 5, ;
        LEFT = 5, ;
        HEIGHT = 22, ;
        WIDTH = 100, ;
        CAPTION = "ActiveControl?", ;
        NAME = "cmdShowControl"

    ADD OBJECT sepSeparator1 AS SEPARATOR WITH ;
        TOP = 5, ;
        LEFT = 80, ;
        HEIGHT = 0, ;
        WIDTH = 0, ;
        NAME = "sepSeparator1"

    ADD OBJECT cmdExit AS COMMANDBUTTON WITH ;
        TOP = 5, ;
        LEFT = 80, ;
        HEIGHT = 22, ;
        WIDTH = 34, ;
        CAPTION = "Exit", ;
        NAME = "cmdExit"

    PROCEDURE cmdShowControl.CLICK
        DO ShowControl
    ENDPROC

    PROCEDURE cmdExit.CLICK
        CLEAR EVENTS
    ENDPROC

ENDDEFINE

DEFINE CLASS frmDemo AS FORM

    DOCREATE = .T.
    CAPTION = "Demo Form"
    NAME = "frmDemo"
    LEFT = 60
    TOP = 100

    ADD OBJECT cmdClose AS COMMANDBUTTON WITH ;
        TOP = 200, ;
        LEFT = 264, ;
        HEIGHT = 27, ;
        WIDTH = 84, ;
        CANCEL = .T., ;
        CAPTION = "Close", ;
        DEFAULT = .T., ;
        TABINDEX = 4, ;
        NAME = "cmdClose"

    ADD OBJECT grdNames AS GRID WITH ;
        COLUMNCOUNT = 2, ;
        DELETEMARK = .F., ;
        HEIGHT = 128, ;
        LEFT = 12, ;
        PANEL = 1, ;
        RECORDSOURCE = "names", ;
        SPLITBAR = .F., ;
        TABINDEX = 3, ;
        TOP = 48, ;
        WIDTH = 344, ;
        NAME = "grdNames", ;
        Column1.CONTROLSOURCE = "names.cname", ;
        Column1.WIDTH = 222, ;
        Column1.NAME = "Column1", ;
        Column2.CONTROLSOURCE = "names.nvalue", ;
        Column2.NAME = "Column2"

    ADD OBJECT txtName AS TEXTBOX WITH ;
        CONTROLSOURCE = "names.cname", ;
        HEIGHT = 24, ;
        LEFT = 56, ;
        TABINDEX = 2, ;
        TOP = 12, ;
        WIDTH = 125, ;
        NAME = "txtName"

    ADD OBJECT lblNameLabel AS LABEL WITH ;
        CAPTION = "Name:", ;
        HEIGHT = 17, ;
        LEFT = 16, ;
        TOP = 16, ;
        WIDTH = 40, ;
        TABINDEX = 1, ;
        NAME = "lblNameLabel"

    PROCEDURE LOAD
        CREATE CURSOR names (cname C(40), nvalue N(19,2))
        INSERT INTO names VALUES('Thomas',12.5)
        INSERT INTO names VALUES('Jerry',18.2)
        INSERT INTO names VALUES('Andrew',9.2)
        GO TOP
    ENDPROC

    PROCEDURE INIT
        THIS.grdNames.Column1.Header1.CAPTION = "Name"

        WITH THIS.grdNames.Column1.Text1
            .BORDERSTYLE = 0
            .MARGIN = 0
        ENDWITH

        THIS.grdNames.Column2.Header1.CAPTION = "Value"
        WITH THIS.grdNames.Column2.Text1
            .BORDERSTYLE = 0
            .MARGIN = 0
        ENDWITH

    ENDPROC

    PROCEDURE cmdClose.CLICK
        THISFORM.RELEASE
    ENDPROC

    PROCEDURE grdNames.AFTERROWCOLCHANGE
        LPARAMETERS nColIndex
        THISFORM.REFRESH
    ENDPROC

    PROCEDURE txtName.VALID
        THISFORM.grdnames.REFRESH
    ENDPROC

ENDDEFINE

PROCEDURE ShowControl
IF TYPE("_Screen.ActiveForm.ActiveControl")=="O"
    LOCAL loActiveControl
    m.loActiveControl = _SCREEN.ACTIVEFORM.ACTIVECONTROL
    IF m.loActiveControl.BASECLASS = "Grid"
        m.loActiveControl = ;
            EVALUATE("m.loActiveControl.Columns(m.loActiveControl.ActiveColumn)." + ;
            m.loActiveControl.COLUMNS(m.loActiveControl.ACTIVECOLUMN).CURRENTCONTROL)
    ENDIF
    m.cObjHierarchy=UPPER(SYS(1272,m.loActiveControl))
    WAIT WINDOW AT 4,30 "_SCREEN.ActiveForm.ActiveControl = "+m.cObjHierarchy NOWAIT
ELSE
    WAIT WINDOW AT 4,30 "There is no ActiveControl; there is no ActiveForm" NOWAIT
ENDIF
ENDPROC

See Also

Other Resources

ActiveForm Property
Properties
Language Reference


ActiveForm Property

Visual FoxPro 9.0 Language Reference
ActiveForm Property
See Also Example

References the active Form object in a form set or the _SCREEN object. Not available at design time; read-only at run time.

Object.ActiveForm.Property [ = Setting]
-or-
Object.ActiveForm.Method

Return Value

Property

Specifies any property of the active form contained in the form set; for example, the Caption property.
Setting

The existing or new setting of the Property.
Method

Specifies any method of the active form contained in the form set; for example, the Move method.

Remarks

Applies To: Form Object | FormSet Object | _SCREEN

If the containing FormSet object is active, ActiveForm references the Form object that has the focus. If the containing FormSet object is not active, an error occurs.

Use the ActiveForm property to access the active Form object's properties and methods.

Example

This example shows how the ActiveForm property may be used within a menu to enable opening and closing a form. When running this sample, note that the Close menu item in the Window menu pad is only enabled if there is an open form. This behavior is controlled by the SKIP FOR clause in bar 1 of the Wwindow popup, which checks to see if a form is active by testing whether the Name of the form is of the character type. The Name property will be character type if there is an active form; otherwise, the property will be undefined.
Copy Code
SET SYSMENU TO
SET SYSMENU AUTOMATIC

DEFINE PAD _0k50sa3dr OF _MSYSMENU PROMPT "\<Window" COLOR SCHEME 3 ;
    KEY ALT+W, ""
DEFINE PAD _0k50sa3ds OF _MSYSMENU PROMPT "E\<xit" COLOR SCHEME 3 ;
    KEY ALT+X, ""
ON PAD _0k50sa3dr OF _MSYSMENU ACTIVATE POPUP Wwindow
ON SELECTION PAD _0k50sa3ds OF _MSYSMENU DO CloseDemo

DEFINE POPUP Wwindow MARGIN RELATIVE SHADOW COLOR SCHEME 4
DEFINE BAR 1 OF Wwindow PROMPT "\<Close" ;
    SKIP FOR TYPE("_Screen.ActiveForm.Name")<>"C"
DEFINE BAR 2 OF Wwindow PROMPT "\<Open"
ON SELECTION BAR 1 OF Wwindow =_SCREEN.ACTIVEFORM.RELEASE()
ON SELECTION BAR 2 OF Wwindow DO OpenForm

PUBLIC ARRAY aoForms(1)
aoForms[1] = NEWOBJECT("frmdemo")
aoForms[1].SHOW

READ EVENTS

SET SYSMENU TO DEFAULT
CLEAR ALL

    PROCEDURE OpenForm
    DIMENSION aoForms(ALEN(aoForms)+1)
    aoForms[ALEN(aoForms)] = NEWOBJECT("frmdemo")
    aoForms[ALEN(aoForms)].SHOW
    RETURN

    PROCEDURE CloseDemo
    CLEAR EVENTS
    RETURN

DEFINE CLASS frmdemo AS FORM
    CAPTION = "Demo Form"
    NAME = "frmDemo"

    ADD OBJECT cmdClose AS COMMANDBUTTON WITH ;
        TOP = 200, ;
        LEFT = 264, ;
        HEIGHT = 27, ;
        WIDTH = 84, ;
        CANCEL = .T., ;
        CAPTION = "Close", ;
        DEFAULT = .T., ;
        NAME = "cmdClose"

    PROCEDURE cmdClose.CLICK
    m.nOKButton=0
    m.nInfo=64
    =MESSAGEBOX("After this Form closes, select Exit from the menu to return to the Command Window",m.nInfo+m.nOKButton)
    THISFORM.RELEASE
ENDPROC

    PROCEDURE RELEASE
    LOCAL m.nIndex
    FOR m.nIndex = 1 TO ALEN(aoForms)
        IF VARTYPE(aoForms[m.nIndex])=="O"
            IF aoForms[m.nIndex]=THIS
                aoForms[m.nIndex] = ""
                EXIT
            ENDIF
        ENDIF
    ENDFOR
ENDPROC
ENDDEFINE

See Also

Other Resources

Activate Event
Deactivate Event
Properties
Language Reference


ActivePage Property

Visual FoxPro 9.0 Language Reference
ActivePage Property
See Also Example

Returns the number of the active Page in a PageFrame object. Available at design time; read/write at run time.

PageFrame.ActivePage

Remarks

Applies To: PageFrame Control

Example

The following example creates a custom class called WizardExample. It uses this class to demonstrate manipulating the ActivePage property of a tabless pageframe, commonly used in some Visual FoxPro wizards.
Copy Code
local loform
loform = createobject('WizardExample')
loform.Show(1)
return

DEFINE CLASS WizardExample AS form
 Caption = "Wizard Example"
 Name = "Form1"

 ADD OBJECT pageframe1 AS pageframe WITH ;
  PageCount = 3, ;
  BorderWidth = 0, ;
  Top = 12, ;
  Left = 12, ;
  Width = 336, ;
  Height = 169, ;
  Tabs = .F., ;
  Name = "Pageframe1", ;
  Page1.Caption = "Page1", ;
  Page1.Name = "Page1", ;
  Page2.Caption = "Page2", ;
  Page2.Name = "Page2", ;
  Page3.Caption = "Page3", ;
  Page3.Name = "Page3"

 ADD OBJECT CmdPrev AS commandbutton WITH ;
  Top = 216, ;
  Left = 60, ;
  Height = 27, ;
  Width = 84, ;
  Caption = "Previous", ;
  Name = "CmdPrev"

 ADD OBJECT CmdNext AS commandbutton WITH ;
  Top = 216, ;
  Left = 204, ;
  Height = 27, ;
  Width = 84, ;
  Caption = "Next", ;
  Name = "CmdNext"

 PROCEDURE CmdPrev.Click
  With THISFORM.Pageframe1
   if .ActivePage > 1 then
    .ActivePage = .ActivePage - 1
   endif
  Endwith
 ENDPROC

 PROCEDURE CmdNext.Click
  With THISFORM.Pageframe1
   if .ActivePage < .PageCount then
    .ActivePage = .ActivePage + 1
   endif
  Endwith
 endproc

 PROCEDURE Init
  With THISFORM.pageframe1
   .Page1.AddObject('Label1','label')
   With .Page1.Label1
    .Caption = "Wizard Page 1"
    .Height = 17
    .Left = 11
    .Top = 20
    .Width = 97
    .Visible = .T.
   Endwith

   .Page2.AddObject('Label1','label')
   With .Page2.Label1
    .Caption = "Wizard Page 2"
    .Height = 17
    .Left = 11
    .Top = 20
    .Width = 97
    .Visible = .T.
   Endwith

   .Page3.AddObject('Label1','label')
   With .Page3.Label1
    .Caption = "Wizard Page 3"
    .Height = 17
    .Left = 11
    .Top = 20
    .Width = 97
    .Visible = .T.
   Endwith
  Endwith
 ENDPROC
ENDDEFINE

See Also

Other Resources

Activate Event
GotFocus Event
Properties
Language Reference


ActiveProject Property

Visual FoxPro 9.0 Language Reference
ActiveProject Property
See Also Example

Contains an object reference to the Project object for the currently active Project Manager window. Read-only at design time and run time.

Object.ActiveProject

Remarks

Applies To: Application Object | _VFP System Variable

The ActiveProject property contains an object reference to the Project object for the foremost Project Manager window when more than one Project Manager window is open. An error is generated if you attempt to access the ActiveProject property when a Project Manager window isn't open.

For more information about projects, see Project Manager Hooks and Development Productivity Tools.

Example

The following example uses the ActiveProject property to get a count of Reports and Labels in an active project. If the MyApp project does not exist, it will be created when MODIFY PROJECT is executed.
Copy Code
MODIFY PROJECT myApp NOSHOW NOWAIT
nRptsLbls=0
FOR EACH oFile IN _VFP.ACTIVEPROJECT.FILES
   IF INLIST(oFile.Type, "R", "B")  && Report and Label
      nRptsLbls=nRptsLbls+1
   ENDIF
ENDFOR

See Also

Other Resources

File Object
Files Collection
Project Object
ProjectHook Object
Projects Collection
Server Object
Servers Collection
Properties
Language Reference


ActiveRow Property

Visual FoxPro 9.0 Language Reference
ActiveRow Property
See Also Example

Specifies the row that contains the active cell in a Grid control. Not available at design time; read-only at run time.

Grid.ActiveRow

Remarks

Applies To: Grid Control

The ActiveRow property does not return the same value as RECNO( ) in an indexed table. ActiveRow returns zero if the grid doesn't have the focus or when you access a row outside the grid display.

Example

The following example creates a table and a form with a grid. The grid's ActiveRow property is used to show a row number within the grid.
Copy Code
CREATE TABLE ardemo (fruit C(15))
INSERT INTO ardemo (fruit) VALUES ("Apples")
INSERT INTO ardemo (fruit) VALUES ("Oranges")
INSERT INTO ardemo (fruit) VALUES ("Grapes")
INSERT INTO ardemo (fruit) VALUES ("Bananas")
INSERT INTO ardemo (fruit) VALUES ("Pears")
INSERT INTO ardemo (fruit) VALUES ("Cherries")
LOCATE  && Moves to top of table, synonymous with GO TOP

oForm1=NEWOBJECT("form1")
oForm1.Show
READ EVENTS
RETURN

DEFINE CLASS form1 AS Form
    Caption = "Form1"
    Name = "Form1"
    ADD OBJECT Grid1 AS Grid WITH ;
        ColumnCount = 2, ;
        Height = 200, ;
        Left = 24, ;
        RecordSource = "ardemo", ;
        Top = 24, ;
        Width = 320, ;
        Name = "Grid1", ;
        Column1.ControlSource = "ardemo.fruit", ;
        Column1.Width = 75, ;
        Column1.Name = "Column1", ;
        Column2.Bound = .F., ;
        Column2.ControlSource = "This.ActiveRow", ;
        Column2.Name = "Column2"

    PROCEDURE Init
    THIS.Grid1.Column2.Header1.Caption = 'ActiveRow'
ENDPROC
    PROCEDURE Unload
    CLEAR EVENTS
ENDPROC

ENDDEFINE

See Also

Other Resources

ActivateCell Method
ActiveColumn Property
GridHitTest Method
RECNO( ) Function
Properties
Language Reference


AddLineFeeds Property

Visual FoxPro 9.0 Language Reference
AddLineFeeds Property
See Also

Specifies that the EditBox should insert linefeed characters (CHR(10)) after carriage return characters (CHR(13)) within the text of an EditBox whenever the Value property is read or whenever the value is stored to the ControlSource. Available at design time and run time.

Object.AddLineFeeds[ = lExpr]

Parameters

lExpr

True (.T.) (Default) Linefeed characters are inserted into the EditBox text after carriage return characters when the Value property is read or stored to the ControlSource. False (.F.) The EditBox text is not modified when the Value property is read or stored to the ControlSource.

Remarks

Applies To: EditBox Control

The EditBox, by default, ensures that line endings have both carriage return and linefeed characters by inserting linefeed characters if they are not present when the Value property is read. In addition to when user code reads the Value property, this may also occur whenever the EditBox loses focus, since Visual FoxPro automatically reads the Value contents and stores to the ControlSource at that time.

Inserting linefeed characters shifts text, but the SelStart value does not change; therefore, the SelStart property can point to the wrong location in the text buffer. Set the AddLineFeeds property to False (.F.) to ensure that no characters are inserted into the text buffer. The AddLineFeeds property is forced to True (.T.) when the Editbox control is bound.

Reading the Text property never causes linefeed characters to be inserted, regardless of the setting of AddLineFeeds.

See Also

Other Resources

ControlSource Property
SelStart Property
Text Property
Value Property
Properties
Language Reference


ADOCodePage Property

Visual FoxPro 9.0
ADOCodePage Property
See Also

Specifies a code page for the CursorAdapter object to use during character data translation when working with ADO data. Read/write at design time and run time.

CursorAdapter.AllowInsert [ = nCodePage ]

Return Value

nCodePage

The code page (integer) to use for character data translation when using ADO data sources. An error will occur if you try to set an invalid code page. The default setting is 0.

Remarks

Applies To: CursorAdapter Class

The code page specified by the ADOCodePage property is used to translate for the following commands:

  • Select

  • Insert

  • Update

  • Delete

  • ConflictCheck

  • InsertRefresh

  • UpdateRefresh

  • Refresh

  • FetchMemo

It is also used with all character parameters passed to and from the ADO data source.

After a CursorFill or CursorRefresh method call, the opened cursor becomes bound to the code page specified by the ADOCodePage property at the time the cursor is filled or refreshed. This means that regardless of the current ADOCodePage setting, all character data fetched from the data source are translated using the bound code page. This includes normal fetch process, fetch during auto-refresh, on demand refresh, and delayed memo fetch.

You can only bind a code page (as specified by ADOCodePage) to an ADO-based cursor. However, ADOCodePage can still be used with non ADO-based cursors. When a non ADO-based cursor is attached to a CursorAdapter object, the ADOCodePage setting is used to translate character data fetched during auto-refresh, on demand refresh and delayed memo fetch.

A cursor can be rebound to a different code page by changing the ADOCodePage property and executing the CursorRefresh Method.

You can retrieve the code page associated with a ADO-based cursor by passing "ADOCodePage" as parameter to the CURSORGETPROP( ) Function.

If a code page other than 0 is used to translate a parameter and the CursorAdapter creates the parameter (the Parameters.Refresh method fails to create it), the parameter is created as adVarWChar/adLongVarWChar rather than adVarChar/adLongVarChar.

See Also

Reference

SYS(3101) - COM Code Page Translation
CURSORGETPROP( ) Function

Other Resources

Properties
Code Pages in Visual FoxPro
CursorAdapter Object Properties, Methods, and Events


Alias Property

Visual FoxPro 9.0 Language Reference
Alias Property
See Also

Specifies an alias name for the appropriate object. Read/write at design time and run time.

The Alias property mimics the behavior of the ALIAS clause in the USE command. There are several versions of this syntax.

DataEnvironment.Cursor.Alias [= cText]
CursorAdapter.Alias [= cText]
XMLTable.Alias [= cText]
XMLTable.XMLField.Alias [= cText]

Return Value

cText

Character data type. The following table describes the values for cText, depending on the object.

Object cText

Cursor

Alias name for each table or view associated with the cursor.

CursorAdapter

Alias name for the cursor generated by the SelectCmd property.

XMLTable

Alias name for the Visual FoxPro cursor.

If cText is an empty string (""), the XMLAdapter ToXML method adds the table schema but does not add any data.

XMLField

Alias name for the field name in the Visual FoxPro cursor.

If cText is an empty string (""), the XMLTable ToCursor and ApplyDiffGram methods disregard the field.

Remarks

Applies To: Cursor Object | CursorAdapter Class | XMLTable Class | XMLField Class

For Cursor objects, when Visual FoxPro loads the data environment, it assigns an alias name that is the same as the table or view name to each table or view associated with the cursor by default. You can change the Alias property to override the default alias name.

For CursorAdapter objects, Visual FoxPro uses Alias property to resolve the correct alias name for tables and fields that you drag and drop to the form from the data environment at design time. If you do not specify values for Alias, Visual FoxPro generates an error and, at run time, uses the default aliases for the tables and fields.

For XMLTable and XMLField objects, Visual FoxPro loads the value of the XMLName property into the corresponding Alias property for those objects by default. If the XMLField Alias property is empty, the XMLTable ToCursor method disregards XMLField objects and creates a cursor that does not include any fields specified by those XMLField objects.

If you change the Alias property, Visual FoxPro also renames the cursor created by the ToCursor method and the Alias properties for XMLTable and XMLField objects.

When executing the ToXML method, Visual FoxPro uses the XMLName property instead of the Alias property.

See Also

Other Resources

USE Command
ALIAS( ) Function
InitialSelectedAlias Property
ParentAlias Property
Properties
Language Reference


Align Property

Visual FoxPro 9.0 Language Reference
Align Property
See Also

Specifies the alignment of an ActiveX™ control (.ocx) on a form. Available at design time and run time.

OLEContainerControl.Align[ = nAlign]

Return Value

nAlign

The settings for the Align property are:

Setting Description

0

Standard alignment. The ActiveX control is placed in the same position as the OLE Container control on the form.

1

Top. The ActiveX control is placed at the top of the form.

2

Bottom. The ActiveX control is placed at the bottom of the form.

3

Left. The ActiveX control is placed at the left edge of the form.

4

Right. The ActiveX control is placed at the right edge of the form.

Remarks

Applies To: OLE Container Control

An ActiveX control (.ocx file) is placed in OLE Container control.

The Align property is only available for ActiveX controls that support changes to their alignment. Insertable OLE objects such as Microsoft Excel worksheets do not support the Align property.

The Align property is available only for ActiveX controls that are placed on a form.

If two or more ActiveX controls have the same Align property setting, the controls are stacked on top of each other.

See Also

Other Resources

OLE Container Control
ActiveX Controls Overview
Alignment Property
How to: Add OLE Objects to Applications
Properties
Language Reference


Alignment Property

Visual FoxPro 9.0 Language Reference
Alignment Property
See Also

Specifies the alignment for text in a control. Available at design time and run time.

Control.Alignment[ = nAlign]

Return Value

CheckBox, OptionButton, and CommandButton Controls

nAlign

Specifies a numerical value representing the alignment of text in a control.

nAlign Description

0

Vertically Centered Left. (Default for check boxes and option buttons) Aligns text flush left and vertically centered on the control.

1

Vertically Centered Right. (Default for Middle Eastern versions of Windows) Aligns text flush right and vertically centered on the control.

2

Centered. (Default for command buttons) Centers text vertically and horizontally.

Note:
For command buttons, the image and text appear in the center of the control. However, when an image is specified for the Picture property, this setting displays the default behavior only when the PictureMargin and PictureSpacing properties are set to 0.

Note:
For check boxes and option buttons, this setting applies only when the control's Style property is set to 1. Setting the Style property affects the appearance of the control. For more information, see Style Property.

4

Top Left. Aligns text in top left corner of the control.

Note:
For check boxes and option buttons, this setting applies only when the control's Style property is set to 1. Setting the Style property affects the appearance of the control. For more information, see Style Property.

5

Top Right. Aligns text in top right corner of the control.

Note:
For check boxes and option buttons, this setting applies only when the control's Style property is set to 1. Setting the Style property affects the appearance of the control. For more information, see Style Property.

6

Top Center. Aligns text at the top and horizontally centered on the control.

Note:
This setting applies only when the control's Style property is set to 1. Setting the Style property affects the appearance of the control. For more information, see Style Property.

7

Bottom Left. Aligns text in the bottom left corner of the control.

Note:
For check boxes and option buttons, this setting applies only when the control's Style property is set to 1. Setting the Style property affects the appearance of the control. For more information, see Style Property.

8

Bottom Right. Aligns text in bottom right corner of the control.

Note:
For check boxes and option buttons, this setting applies only when the control's Style property is set to 1. Setting the Style property affects the appearance of the control. For more information, see Style Property.

9

Bottom Center. Aligns text at the bottom and vertically centered on the control.

Note:
For check boxes and option buttons, this setting applies only when the control's Style property is set to 1. Setting the Style property affects the appearance of the control. For more information, see Style Property.
Note:
For CommandButton controls, you can set the Alignment property without specifying an image for the Picture property. However, certain Alignment settings are visible only when you specify an image for the Picture property and set the PicturePosition property to a value other than the default. In addition, some Alignment settings are not visible unless the WordWrap property is set to True (.T.) and Caption text displays on multiple lines. When you do not specify an image for the Picture property, the PicturePosition setting does not affect the Alignment property.

Note:
For CheckBox and OptionButton controls, when Style is set to 0, the PicturePosition property affects the position of the check boxes or option buttons in the control. When you specify an image for the Picture property, the PicturePosition property can affect the Alignment property. For example, the default setting for PicturePosition results in a centered alignment regardless of the setting for Alignment. For more information, see Picture Property and PicturePosition Property.

ComboBox, EditBox, Label, and Spinner Controls

nAlign

Specifies a numerical value representing the alignment of text in a control.

nAlign Description

0

Left. Aligns text flush left. (Default for combo boxes, edit boxes, and labels)

1

Right. Aligns text flush right. (Default for spinners and for Middle Eastern versions of Windows)

2

Center. Centers text vertically and horizontally on the control.

3

Automatic. Aligns text based on the data type of the control source.

Note:
The Automatic setting does not apply to EditBox, Header, or Label controls.
Note:
For ComboBox controls, the Alignment property applies only when the Style property is set to 0.

Header and Column Objects

nAlign

Specifies a numerical value representing the alignment of text in a control.

nAlign Description

0

Vertically Centered Left. Aligns text flush left and centers it vertically in the column.

1

Vertically Centered Right. Aligns the text flush right and centers it vertically in the column.

2

Centered. Centers the text vertically and horizontally.

3

Automatic. Aligns text in the column based on the data type of the control source. (Default)

Note:
The Automatic setting aligns text based on the data type of the control source, specified by the ControlSource property. For control sources with numeric types, such as Numeric, Double, Float, Currency, and Integer, text is aligned to the right. For control sources with other data types, text is aligned to the left.

4

Top Left. Aligns the text flush left at the top of the column.

5

Top Right. Aligns the text flush right at the top of the column.

6

Top Center. Aligns the text at the top and horizontally centered in the column.

7

Bottom Left. Aligns the text flush left at the bottom of the column.

8

Bottom Right. Aligns the text flush right at the bottom of the column.

9

Bottom Center. Aligns the text at the bottom and horizontally centered in the column.
For a Header object, if the WordWrap property is set to False (.F.), values 0-2, 4-9 are available. If the WordWrap property is set to True (.T.), values 0-2 are effective.

TextBox Control

nAlign

Specifies a numerical value representing the alignment of text in Textbox control.

nAlign Description

0

Left. Aligns text flush left.

1

Right. Aligns text flush right.

2

Center. Aligns text in the horizontally and vertically centered on the control.

3

Automatic. (Default)

Note:
For a TextBox control not contained in a column, the Automatic setting aligns text based on the data type of the control source, specified by the ControlSource property. For control sources with numeric types, such as Numeric, Double, Float, Currency, and Integer, text is aligned to the right. For control sources with other data types, text is aligned to the left. For more information, see ControlSource Property.

Note:
For a TextBox control in a column, the column's Alignment setting determines alignment of text in the text box.

Remarks

Applies To: CommandButton Control | CheckBox Control | Column Object | ComboBox Control | EditBox Control | Header Object | Label Control | OptionButton Control | Spinner Control | TextBox Control

See Also

Other Resources

AutoSize Property
Caption Property
Properties
Language Reference


AllowAddNew Property

Visual FoxPro 9.0 Language Reference
AllowAddNew Property
See Also

Specifies whether new records can be added to a table from within a grid. Available at design time and run time.

Grid.AllowAddNew[ = lExpr]

Return Value

lExpr

One of the following:

Setting Description

True (.T.)

New records can be added to a table from within a grid.

False (.F.)

(Default) New records cannot be added to a table from within a grid.

Remarks

Applies To: Grid Control

If AllowAddNew is set to True (.T.), you can add a new record to a table in a grid by pressing the down arrow while positioned on the last record in the grid, as long as the grid is read/write. New records cannot be added from within the grid if the grid is read-only (if the RecordSourceType is a query, a table is read-only, and so on).

See Also

Other Resources

APPEND Command
How to: Add Records to Tables
RecordSourceType Property
Properties
Language Reference


AllowAutoColumnFit Property

Visual FoxPro 9.0 Language Reference
AllowAutoColumnFit Property
See Also

Specifies how columns resize to the width of data automatically inside the grid or browse window. You can use AllowAutoColumnFit when you create an object reference for the browse window using the NAME clause in the BROWSE command. Read/write at design time and run time.

Grid.AllowAutoColumnFit [ = nValue ]

Return Value

nValue

Numeric data type. The following table lists the values for nValue.

nValue Setting description

0

Enables all or individual columns to fit data automatically. (Default)

1

Enables only individual columns to fit all data automatically. "All data" refers only to all rows in the grid or browse window, not all records in the table.

2

Disables capability for columns to fit data automatically.

Remarks

Applies To: Grid Control | BROWSE Command

Setting this property makes it possible for you to resize columns automatically to the width of data when you double-click the area between column headers, or the square immediately preceding the first column header in the upper and leftmost corner of a grid. AllowAutoColumnFit affects interaction only through the user interface.

Fitting columns automatically to data occurs in both the left and right grid or browse panels, but only when either one or both are visible.

You can override AllowAutoColumnFit by using the AutoFit method, which resizes all or individual columns programmatically.

When a column resizes, the Resize event for that column fires.

You can prevent the automatic resizing of a particular column by setting the Resizable property of that column to False (.F.).

Header click events are not called because you click between the column headers.

Hidden grid columns, which have their Visible property set to False (.F.) and have a Width property value of 0, are not resized.

See Also

Other Resources

Properties
AutoFit Method
Resizable Property


AllowCellSelection Property

Visual FoxPro 9.0 Language Reference
AllowCellSelection Property
See Also

Specifies whether one can select individual cells in a grid, for example, you can use the AllowCellSelection property to mimic a list box. Available at design time and run time.

Grid.AllowCellSelection [= lExpr]

Return Value

lExpr

Specifies whether you can select the contents of a grid cell or only the entire row. The following table lists the values for lExpr.

lExpr Description

True (.T.)

Specifies that one can select contents in a grid cell (field). (Default)

False (.F.)

Specifies that one must select the entire the row.

Remarks

Applies To: Grid Control

Selecting individual cells or the entire row does not change color of the selected row or cell.

When AllowCellSelection is set to False (.F.), the following additional behavior occurs:

  • The grid disregards the SelectedItemForeColor and SelectedItemBackColor properties. The row takes on a uniform color based on the HighlightBackColor and HighlightForeColor properties and other color-related properties at the column level.

    Note:
    If you do not specify colors for the highlighting properties, a rectangular outline appears around a selected row.

  • If the HighlightStyle property is set to a value greater than 0, the default HighlightBackColor is a 50 percent lighter gradient.

  • The grid always shows the cursor specified with the MousePointer property and does not display a text insertion pointer when inside a cell. Clicking a cell selects the entire row, instead of setting focus to the individual cell.

  • Tabbing between cells is disabled, and grid behavior acts similar to a grid with a single column.

  • You cannot select a row in the grid for deletion by clicking the deletion column as this functionality is disabled.

  • Hidden columns are disregarded. You can view columns that are scrolled to the left or right outside the visible grid by using the LEFT ARROW and RIGHT ARROW keys or the mouse and the horizontal scrollbar.

  • The ActiveColumn property evaluates to 0; use the RelativeColumn property to obtain the correct column in the grid.

  • The ActivateCell method merely selects the entire row.

  • All events are handled at the grid level instead of at the control level. For example, double-clicking a cell is handled by the Grid.DblClick event. However, header events and attributes are still supported. For example, you can click on a header to resort the column's contents based on the field.

  • Support for Find is disabled as well as Edit menu commands because setting AllowCellSelection makes the grid read-only. However, the AllowCellSelection property does not affect the delete mark column in a grid.

  • The AfterRowColChange and BeforeRowColChange events only work for row change. The RowColChange property always returns a value of 1 (Row Change).

The AllowCellSelection property supports all standard Visual FoxPro controls; however, ActiveX controls embedded within a column are not supported.

If the AllowCellSelection property for a grid is set to True (.T.), Visual FoxPro disregards the Grid.KeyPress event and uses the event at the individual cell level.

See Also

Other Resources

Properties
ActiveColumn Property
AfterRowColChange Event
BeforeRowColChange Event
HighlightBackColor Property
HighlightStyle Property
RelativeColumn Property
SelectedItemForeColor Property
KeyPress Event


AllowDelete Property

Visual FoxPro 9.0 Language Reference
AllowDelete Property
See Also

Specifies whether to permit delete operations against a data source. Read/write at design time and run time.

Note:
AllowDelete does not affect the ability to delete a row in the cursor itself.

CursorAdapter.AllowDelete [ = lValue ]

Return Value

lValue

Logical data type. The following table lists the settings for lValue.

lValue Description

True (.T.)

Permit delete operations. (Default)

When the CursorAdapter DeleteCmd property is empty (""), Visual FoxPro generates a SQL DELETE command automatically. For more information, see Data Access Management Using CursorAdapters.

False (.F.)

Does not permit delete operations.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


AllowHeaderSizing Property

Visual FoxPro 9.0 Language Reference
AllowHeaderSizing Property
See Also

Specifies whether the height of a grid's header can be changed at run time. Available at design time and run time.

Grid.AllowHeaderSizing[ = lExpr]

Return Value

lExpr

One of the following:

Setting Description

True (.T.)

(Default) The height of the grid's header can be changed by dragging the header at run time.

False (.F.)

The height of the grid's header cannot be changed by dragging the header at run time.

Remarks

Applies To: Grid Control

See Also

Other Resources

AllowRowSizing Property
HEADER( ) Function
HeaderHeight Property
Properties
Language Reference


AllowInsert Property

Visual FoxPro 9.0 Language Reference
AllowInsert Property
See Also

Specifies whether to permit insert operations against a data source. Read/write at design time and run time.

CursorAdapter.AllowInsert [ = lValue ]

Return Value

lValue

Logical data type. The following table lists the settings for lValue.

lValue Description

True (.T.)

Permit insert operations. (Default)

When the CursorAdapter InsertCmd property is empty (""), Visual FoxPro generates a SQL INSERT command automatically. For more information, see Data Access Management Using CursorAdapters.

False (.F.)

Does not permit insert operations.

Remarks

Applies To: CursorAdapter Class

AllowInsert does not affect the ability to insert a row into the cursor itself.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


AllowModalMessages Property

Visual FoxPro 9.0
AllowModalMessages Property
See Also

Specifies whether a ReportListener can provide modal messages as part of its user interface.

ReportListener.AllowModalMessages [= lExpr]

Return Value

Logical data type.

True

Modal messages are permitted.
False

(Default) Modal messages are not permitted.

Remarks

Applies To: ReportListener Object.

The ReportListener class has two methods, DoMessage and DoStatus, you can use to display user feedback of different types. The distinction allows different code for modal message display (such as a MESSAGEBOX upon completion of a report run) and for modeless status display (such as a WAIT NOWAIT message to indicate of progress during the report run).

When you write code that ordinarily provides a modal message in a class derived from ReportListener, use the value of AllowModalMessages to determine whether such a message is appropriate in the current environment. If the value of AllowModalMessages is .F., your DoMessage code can decide to defer to DoStatus to display a modeless message instead. Alternatively, your DoMessage code can opt to suppress the feedback message.

The value of the QuietMode property takes precedence over AllowModalMessages. If the value of QuietMode is .T., the user of the class opts to suppress all user feedback.

See Also

Reference

DoMessage Method
DoStatus Method
QuietMode Property

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


AllowOutput Property

Visual FoxPro 9.0 Language Reference
AllowOutput Property
See Also

Specifies whether to allow default output to appear on a form. Read/write at design time and run time.

Form.AllowOutput = lExpr

Parameters

lExpr

Logical data type. The following table lists the settings for lExpr.

lExpr Description

True (.T.)

(Default) Sends user output to the form if it is active.

False (.F.)

Redirects user output to the desktop if the form is active.

Remarks

Applies To: Form Object

If the AllowOutput property is programmatically changed from True (.T.) to False (.F.), at run time, Visual FoxPro automatically redirects output to the desktop.

Note:
Using the AllowOutput property can affect code that relies on the position and size of a window. This includes the use of WOUTPUT( ) or other commands, such as DEFINE POPUP...FROM, that implicitly base their coordinates on the output window.

Setting the AllowOutput property to False (.F.) on a form, changes the following Visual FoxPro behavior.

  • Painting of the form is redirected to the next output window or desktop. This affects commands, such as ?, ??, DIR, LIST, DISPLAY, CLEAR, and other commands that display output on a form.

  • The WOUTPUT( ) function does not return the name of the active form. It returns the name of the current output form or desktop.

  • The BROWSE command does not inherit the window size and window settings of the form.

  • The MCOL( ) and MROW( ) functions, without the use of their optional parameter, may not be relative to the form they are called on.

When a form closes with the AllowOutput property set to False (.F.), Visual FoxPro defaults to the next output form or desktop.

See Also

Other Resources

? | ?? Command
BROWSE Command
CLEAR Command
DEFINE POPUP Command
DIR or DIRECTORY Command
DISPLAY Command
LIST Command
Properties
WOUTPUT( ) Function


AllowRowSizing Property

Visual FoxPro 9.0 Language Reference
AllowRowSizing Property
See Also

Specifies whether the height of records in a grid can be changed at run time. Available at design time and run time.

Grid.AllowRowSizing[ = lExpr]

Return Value

lExpr

One of the following:

Setting Description

True (.T.)

(Default) The height of records in the grid can be changed by dragging at run time.

False (.F.)

The height of records in the grid cannot be changed by dragging at run time.

Remarks

Applies To: Grid Control

See Also

Other Resources

AllowHeaderSizing Property
RowHeight Property
ROW( ) Function
Properties
Language Reference


AllowSimultaneousFetch Property

Visual FoxPro 9.0 Language Reference
AllowSimultaneousFetch Property
See Also

Specifies whether to permit simultaneous fetching for Open Database Connectivity (ODBC) cursors when using a shared connection. Read/write at design time and run time.

Note:
AllowSimultaneousFetch applies only when the CursorAdapter DataSourceType property is set to "ODBC". If the associated connection is not shared, setting AllowSimultaneousFetch has no effect.

CursorAdapter.AllowSimultaneousFetch [= lValue]

Return Value

lValue

Logical data type. The following table specifies the values for lValue.

lValue Description

False (.F.)

When using a shared connection, similarly configured cursors that share the connection are not permitted to fetch rows simultaneously. (Default)

True (.T.)

When using a shared connection, similarly configured cursors that share the connection are permitted to fetch rows simultaneously.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
DataSourceType Property


AllowTabs Property

Visual FoxPro 9.0 Language Reference
AllowTabs Property
See Also

Specifies whether to allow tabs in an EditBox control.

EditBox.AllowTabs[ = lExpr]

Return Value

lExpr

Specifies a logical value that determines whether tabs are allowed in an EditBox control. The following table lists the settings for lExpr:

lExpr Description

True (.T.)

Allow tabs in the edit box.

To exit the control, press CTRL+TAB.

False (.F.)

Do not allow tabs in the edit box. (Default)

To exit and move focus to the next control in the tab order, press the TAB key.

Remarks

Applies To: EditBox

See Also

Other Resources

TabIndex Property
TabStop Property
TabStyle Property
Properties
Language Reference


AllowUpdate Property

Visual FoxPro 9.0 Language Reference
AllowUpdate Property
See Also

Specifies whether to permit update operations against a data source. Read/write at design time and run time.

Note:
AllowUpdate does not affect the ability to update a row in the cursor itself.

CursorAdapter.AllowUpdate [ = lValue ]

Return Value

lValue

Logical data type. The following table lists the settings for lValue.

lValue Description

True (.T.)

Permit update operations. (Default)

When the CursorAdapter UpdateCmd property is empty (""), Visual FoxPro generates a UPDATE - SQL command automatically. For more information, see Data Access Management Using CursorAdapters.

False (.F.)

Does not permit update operations.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


AlwaysOnBottom Property

Visual FoxPro 9.0 Language Reference
AlwaysOnBottom Property
See Also

Prevents other windows from being covered by a form's window. Available at design time; read/write at run time.

Object.AlwaysOnBottom[ = lExpr]

Return Value

lExpr

The settings for the AlwaysOnBottom property are:

Setting Description

True (.T.)

The form is always on the bottom (only another window with the AlwaysOnBottom property set to True (.T.) can be under the form).

False (.F.)

(Default) The form can cover another window.

Remarks

Applies To: Form Object | _SCREEN

The AlwaysOnBottom property is ignored if any of the following properties are set to the specified values:

  • AlwaysOnTop = .T.

  • Desktop = .T.

  • ShowWindow = 2

The AlwaysOnBottom property setting is ignored for _SCREEN.

See Also

Other Resources

AlwaysOnTop Property
Desktop Property
ShowWindow Property
ZOrder Method
Properties
Language Reference


AlwaysOnTop Property

Visual FoxPro 9.0 Language Reference
AlwaysOnTop Property
See Also

Prevents other windows from covering the form's window. Available at design time; read/write at run time.

Object.AlwaysOnTop[ = lExpr]

Return Value

lExpr

The settings for the AlwaysOnTop property are:

Setting Description

True (.T.)

The form is always on the top (only another window with the AlwaysOnTop property set to True (.T.) can be on top of the form).

False (.F.)

(Default) The form can be covered by another window.

Remarks

Applies To: Form Object | _SCREEN

See Also

Other Resources

AlwaysOnBottom Property
ShowWindow Property
ZOrder Method
Properties
Language Reference


Anchor Property

Visual FoxPro 9.0 Language Reference
Anchor Property
See Also

Defines which borders of the parent container that a visual control is anchored to when resizing the container. Read/write at design time and run time.

Control.Anchor [= nValue]

Return Value

nValue

Specifies a bit value that determines the anchor behavior of the control. The following table describes bit values you can set or add to produce values for nValue.

Position Bit value Bit number Conflicting values Description

Top Left

0

Anchors control to the top and left borders of the container and does not change the distance between the top and left borders. (Default)

Top Absolute

1

0

16, 512

Anchors control to top border of container and does not change the distance between the top border.

Left Absolute

2

1

32, 256

Anchors control to left border of container and does not change the distance between the left border.

Bottom Absolute

4

2

64, 512

Anchors control to bottom border of container and does not change the distance between the bottom border.

Right Absolute

8

3

128, 256

Anchors control to right border of container and does not change the distance between the right border.

Top Relative

16

4

1, 512

Anchors control to top border of container and maintains relative distance between the top border.

Left Relative

32

5

2, 256

Anchors control to left border of container and maintains relative distance between the left border.

Bottom Relative

64

6

4, 512

Anchors control to bottom border of container and maintains relative distance between the bottom border.

Right Relative

128

7

8, 256

Anchors control to right border of container and maintains relative distance between the right border.

Horizontal Fixed Size

256

8

2, 8, 32, 128

Anchors center of control relative to left and right borders but remains fixed in size.

Vertical Fixed Size

512

9

1, 4, 16, 64

Anchors center of control relative to top and bottom borders but remains fixed in size.
The following table describes examples of common settings for the Anchor property.

Control nValue Description

TextBox or EditBox

10

Resizes control horizontally as you resize it.

CommandButton

12

Displays a set of two controls, for example, OK and Cancel, in the lower right corner.

CommandButton

128 and 32

Centers two left and right command buttons.

CommandButton

260

Centers control on the bottom of a form.

Remarks

Applies To: CheckBox Control | ComboBox Control | CommandButton Control | CommandGroup Control | Container Object | Control Object | EditBox Control | Grid Control | Image Control | Label Control | Line Control | ListBox Control | OLE Bound Control | OLE Container Control | OptionButton Control | OptionGroup Control | PageFrame Control | Shape Control | Spinner Control | TextBox Control

Anchoring is based on the coordinates of the control at the time when the control's Anchor property is originally set, typically, when the control is instantiated. It is not based on the control's current position. Therefore, even after you move a control, anchoring applies to the control's original position. This behavior explains the difference between an Anchor value of 0 and 3.

For example, suppose you have a CommandButton control on a form and the Anchor property for the control is initially set to 3. By inserting the following code in the control's Click event and clicking the button, you can move the command button:

Copy Code
This.Left = This.Left + 10

However, when you resize the form, the control returns to its original position.

Tip:
If you want to base anchoring on the control's current position after it is has been moved, reset the control's Anchor property to 0 and then back to 3. For example, using the following code in the command button's Click event moves the command button when you click it but retains the control's current position when the form is resized:

Copy Code
This.Left = This.Left + 10
This.Anchor = 0
This.Anchor = 3

Settings for the Anchor property are obeyed for applicable controls in the following containers:

  • CommandGroup Control

  • Container Object

  • Control Object

  • Form Object

  • OptionGroup Control

  • Page Object

Settings for the Anchor property are disregarded for controls in the ToolBar and Column objects.

You can resize the control if anchor values are set for both opposing edges, for example, left and right edges or top and bottom edges. You can only move the control if you set a single edge.

If you do not set bits for a particular axis, the control's position does not change for that axis when the container resizes. For example, the bit numbers 1, 3, 5, 7, and 10 affect the top and bottom dimension.

You cannot set bit values that conflict with each other. These bit values include the following:

  • Absolute and Relative bits for the same border, for example, an nValue of 17.

  • Fixed Size and Border bits for the same axis borders, for example, an nValue of 258 or 513.

For a description of the conflicting values, see the table listing the values for nValue.

See Also

Other Resources

Properties
Adding Objects to Forms
Controls for Extending Forms


Application Property

Visual FoxPro 9.0 Language Reference
Application Property
See Also

Provides a reference to the Application object containing an object. Not available at design time; read-only at run time.

Object.Application.Property [ = Setting]
-or-
Object.Application.Method

Return Value

Property

Specifies any property of the Application object or the _VFP system variable; for example, the Caption property.
Setting

The existing or new setting of the Property.
Method

Specifies any method of the Application object or the _VFP system variable; for example, the DoCmd method.

Remarks

Applies To: CheckBox Control | Column Object | ComboBox Control | CommandButton Control | CommandGroup Control | Container Object | Control Object | Cursor Object | CursorAdapter Class | Custom Object | DataEnvironment Object | EditBox Control | Form Object | FormSet Object | Grid Control | Header Object | Hyperlink Object | Image Control | Label Control | Line Control | ListBox Control | OLE Bound Control | OLE Container Control | OptionButton Control | OptionGroup Control | Page Object | PageFrame Control | ProjectHook Object | Relation Object | _SCREEN | Separator Object | Session Object | Shape Control | Spinner Control | TextBox Control | Timer Control | ToolBar Object

Use the Application property to access an Application object's properties and methods from an object contained by the application. The Application property can also be used with the _VFP system variable to access properties and methods for the current instance of Visual FoxPro.

See Also

Other Resources

CREATEOBJECT( ) Function
Properties
Language Reference


AutoActivate Property

Visual FoxPro 9.0 Language Reference
AutoActivate Property
See Also

Determines how an OLE Container control can be activated. Available at design time and run time.

Control.AutoActivate[ = nValue]

Return Value

nValue

The settings for the AutoActivate property are:

Setting Description

0

Manual. The control isn't automatically activated. You can activate a control programmatically using the DoVerb method.

1

GotFocus. If the control contains an object, the application that provides the object is activated when the control receives the focus.

2

(Default) DoubleClick. If the control contains an object, the application that provides the object is activated when the user double-clicks the control or presses ENTER when the control has the focus.

3

Automatic. If the control contains an object, the application that provides the object is activated based on the object's normal method of activation (when the control receives the focus or when the user double-clicks the control).

Remarks

Applies To: OLE Bound Control | OLE Container Control

If an embedded object supports in-place activation, you can set AutoActivate to 1 (GotFocus) to activate an object when the control receives the focus.

Note:
When AutoActivate is set to 2 (Double-Click), the DblClick event does not occur.

See Also

Other Resources

DoVerb Method
DblClick Event
Properties
Language Reference


AutoCenter Property

Visual FoxPro 9.0 Language Reference
AutoCenter Property
See Also

Specifies whether the form object is automatically centered in the main Visual FoxPro window or on the desktop the first time it is displayed. Available at design time and run time.

Object.AutoCenter [ = lExpr]

Return Value

lExpr

Specifies whether the Form object is centered or placed according to the settings of the Top and Left properties. The settings for the AutoCenter property are:

Setting Description

True (.T.)

The Form object is centered and the values of the Top and Left properties are set to the new position.

False (.F.)

(Default) The Form object is not centered and is placed at the coordinates specified by the Top and Left properties.

Remarks

Applies To: Form Object | _SCREEN

Forms are displayed in the main window, so setting AutoCenter to true (.T.) centers the form within the main window.

Note:
Resetting AutoCenter to false (.F.) after it has been set to true (.T.) will not return the form to the original Top and Left position.

See Also

Other Resources

Desktop Property
Left Property
Top Property
Properties
Language Reference


AutoCloseTables Property

Visual FoxPro 9.0 Language Reference
AutoCloseTables Property
See Also

Specifies whether the tables or views specified by the data environment are closed when the form set, form, or report is released. Available at design time; read-only at run time.

DataEnvironment.AutoCloseTables[ = lExpr]

Return Value

lExpr

The settings for the AutoCloseTables property are:

Setting Description

True (.T.)

(Default) Closes the tables and views when the form set, form, or report is released.

False (.F.)

Tables and views remain open when the form set, form, or report is released.

Remarks

Applies To: DataEnvironment Object

If AutoCloseTables is set to false (.F.) and the form set, form, or report is not running in a private data session, the tables and views associated with Cursors in the data environment remain open after the form set, form, or report is released. In all other cases, the tables and views associated with Cursors in the data environment are closed.

See Also

Other Resources

AutoOpenTables Property
DataSession Property
DataSessionID Property
Properties
Language Reference


AutoComplete Property

Visual FoxPro 9.0
AutoComplete Property
See Also

Specifies that the text box tracks values previously entered and makes them available in a dynamic list of suggested entries. Read/write at design time and run time.

Textbox.AutoComplete [ = nValue]

Return Value

nValue

Integer data type. The following table lists the values for nValue.

nValue Setting

0

Does not display a list of entries.

1

Alphabetical Sorts entries alphabetically and is not case sensitive.

2

Most Frequently Used (MFU) Sorts entries based on the highest count and then most recently updated.

3

Most Recently Used Sorts entries based on the Updated field in the source table with the most recent first.

4

Custom Uses the Weight field populated using your own algorithm to specify how you want the entries sorted. The results are sorted in descending order (highest to lowest value). If there are ties, then the Updated field is used (most recent appears first).

Remarks

Applies to: TextBox Control (Visual FoxPro)

Set the AutoComplete property to provide a text box that automatically stores and suggests values. As characters are typed, a drop-down list displays recently entered words that match the pattern of the typed characters. When the user selects an entry from the list, the text box value becomes equal to that entry and updates the usage information for that entry in the Autocomp.dbf or other table you have specified.

For more information about how the data is stored, see AutoCompTable Property.

If you use the custom sort option (4), you need to define the weighted order by updating the Weight field in the AutoComplete table, which is reserved for your use. For example, you might specify code in the Valid Event for the text box which updates the Weight field based on frequency timing in which more recent entries are given a higher weight value.

If you want to control the number of items that appear in the dynamic list, you can set the List Display Count option in the Options dialog box. You can also specify this setting with SYS(2910) - List Display Count.

See Also

Reference

TextBox Control (Visual FoxPro)
AutoCompTable Property
AutoCompSource Property

Other Resources

Properties (Visual FoxPro)


AutoCompSource Property

Visual FoxPro 9.0
AutoCompSource Property
See Also Example

Specifies the Source field in the table that tracks text for auto-completion functionality in a Text box control. Read/write at design time and run time.

cTextbox.AutoCompSource [= cValue]

Return Value

cValue

Name of the field in the auto-completion table associated with the text box.

Remarks

Applies to: TextBox Control (Visual FoxPro)

Specifies the Source name used for looking up data in the AutoComp table. This field is case-insensitive and is stored as uppercase in the AutoComp table.

When entries are written to or read from the AutoComp table, they use a key, which is the Source field. By default, if this property is not specified, then the name of the text box becomes the key value in that field of the AutoComp table.

You can write applications that use a single AutoComp table that supplies values to several text box controls within a single application.

The Source field in the AutoComp table is limited to 20 characters. You should ensure that your AutoCompSource property is limited to this amount. The control's Name property is used if you do not specify an AutoCompSource value. If the source used is longer than 20 characters, it is truncated to its first 20 characters for lookup against the Source field in the Autocomp table.

Example

For example, you might have many forms that have an Address field. By setting the AutoCompSource property to “myAddress” for each text box that displays an address field, you can reuse the entries of the AutoComp table throughout your entire application.
Copy Code
AddressForm.AddressText1.AutoCompSource = 'myAddress'

See Also

Reference

TextBox Control (Visual FoxPro)
AutoCompTable Property
AutoComplete Property

Other Resources

Properties (Visual FoxPro)


AutoCompTable Property

Visual FoxPro 9.0
AutoCompTable Property
See Also

Specifies the name and location of the table that stores the data used by a Textbox control to suggest values based on previously entered values.

Textbox.AutoCompTable [ = cValue]

Return Value

cValue

Specifies the name and path to the table the supports displaying a list of previously used entries into a text box.

Remarks

Applies to: TextBox Control (Visual FoxPro)

The default location and name for this property is HOME(7) + “Autocomp.DBF”. If you enter a name for a table that does not exist, the table is created for you.

The following table describes the structure of the Auto Complete table.

Field name | Type (size) | Description
Source | C (20) | Source name of the Textbox control.
Data | C (254) | Data item to display.
Count | I | Number of times data item was selected.
Weight | I | Specifies value to use when AutoComplete is set to 4 (Custom).
Created | T | Timestamp when data item first created.
Updated | T | Timestamp when data item last updated.
User | M | Specifies user information.

See Also

Reference

TextBox Control (Visual FoxPro)
AutoCompTable Property
AutoCompSource Property
AutoComplete Property

Other Resources

Properties (Visual FoxPro)


AutoHideScrollBar Property

Visual FoxPro 9.0 Language Reference
AutoHideScrollBar Property
See Also Example

Shows or hides the scroll bar in a ListBox control. Read/write at design time and run time.

Note:
If the list box is empty or if all items in the list box are visible, the scroll bar does not display.

ListBox.AutoHideScrollBar [= nValue]

Return Value

nValue

Specifies a value that determines when a scroll bar is visible in a list box. The following table lists the values for nValue.

nValue Description

0

Always show scroll bar. (Default)

1

Show scroll bar only if items in the list box cannot be fully displayed.

Remarks

Applies To: ListBox

When drawing scroll bars, Visual FoxPro respects the setting for the IntegralHeight property.

Example

The following example creates a list box on a form and specifies an array as the source of the items in the list box. In the user-defined class list box class, lstMyListbox, the AutoHideScrollBar property is set to 1 so that the scroll bar only appears if the number of items in the list box can't be fully displayed. Resize the form to adjust size of the list box.

The steps performed in this example appear as follows:

  • Clear the main Visual FoxPro window using the CLEAR command.

  • Create an array called gaMyListArray using the DIMENSION command.

  • Fill the array with letters using the FOR...ENDFOR and STORE commands.

  • Create a form using the CREATEOBJECT( ) function.

  • Add a CommandButton control based on the user-defined cmdMyCmdButton class by calling the AddObject method.

  • Add a ListBox control based on the custom lstMyListBox class by calling the AddObject method.

  • Specify an array as the row source type for the list box by setting the RowSourceType property to 5 (Array).

  • Specify the array gaMyListArray as the row source for the list box by setting the RowSource property.

  • Show the command button by setting the Visible property.

  • Show the list box by setting the Visible property.

  • Display the form by calling the form's Show method.

  • Begin event processing by calling the READ EVENTS command.

  • Define the user-defined cmdMyCmdButton class based on the CommandButton control using the DEFINE CLASS command. The code in the DEFINE CLASS command sets properties for the user-defined class and defines procedures.

  • Define the user-defined lstMyListBox class based on the ListBox control using the DEFINE CLASS command. The code in the DEFINE CLASS command sets properties for the user-defined class and defines procedures.

Copy Code
CLEAR
DIMENSION gaMyListArray(10)
FOR gnCount = 1 to 10
   STORE REPLICATE(CHR(gnCount+64),6) TO gaMyListArray(gnCount)
NEXT

frmMyForm = CREATEOBJECT('Form')
frmMyForm.AddObject('cmbCommand1','cmdMyCmdBtn')
frmMyForm.AddObject('lstListBox1','lstMyListBox')
frmMyForm.lstListBox1.RowSourceType = 5
frmMyForm.lstListBox1.RowSource = 'gaMyListArray'
frmMyForm.cmbCommand1.Visible =.T.
frmMyForm.lstListBox1.Visible =.T.
frmMyForm.Show
READ EVENTS

DEFINE CLASS cmdMyCmdBtn AS CommandButton
   Caption = '\<Quit'
   Cancel = .T.
   Left = 125
   Top = 210
   Height = 25
   PROCEDURE Click
      CLEAR EVENTS
      CLEAR
ENDDEFINE

DEFINE CLASS lstMyListBox AS ListBox
   Left = 10
   Top = 30
   Anchor = 5
   AutoHideScrollBar = 1
ENDDEFINE

See Also

Other Resources

RowSource Property
RowSourceType Property
Properties


AutoIncrement Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
AutoIncrement Property (Visual FoxPro)
See Also

Specifies if the build version number of a project is automatically incremented each time a distributable .exe or in-process .dll is built.

Object.AutoIncrement[ = lExpression]

Return Value

lExpression

The settings for the AutoIncrement property are:

Setting Description

True (.T.)

The build version number of a project is automatically incremented each time a distributable .exe or in-process .dll is built.

False (.F.)

(Default) The build version number isn't automatically incremented.

Remarks

Applies To: Project Object

The build version number isn't incremented if AutoIncrement is set to false (.F.) or when the project is rebuilt or a distributable .app is built.

The value of the AutoIncrement property corresponds to the Auto Increment check box in the EXE Version dialog box. The build version number can be determined or set with the VersionNumber Property.

See Also

Other Resources

BUILD APP Command
BUILD DLL Command
BUILD EXE Command
BUILD PROJECT Command
EXE Version Dialog Box
VersionNumber Property
Properties
Language Reference


AutoOpenTables Property

Visual FoxPro 9.0 Language Reference
AutoOpenTables Property
See Also

Determines whether the tables or views associated with a form set, form, or report's data environment are loaded automatically. Available at design time; read-only at run time.

DataEnvironment.AutoOpenTables [= lExpr]

Parameters

lExpr

Logical data type. The following table lists the values for lExpr.

lExpr Description

True (.T.)

The form set, form, or report's tables and views are opened automatically. (Default)

False (.F.)

The tables and views are not opened automatically.

Remarks

Applies To: DataEnvironment Object

When AutoOpenTables is set to True (.T.), the data environment automatically calls the AutoOpen method of any CursorAdapter object contained in the data environment. The data environment opens any cursors or cursor adapters in the order that they were added to the data environment.

When AutoOpenTables is set to False (.F.), you can call the OpenTables method of the data environment to programmatically load the data environment.

See Also

Other Resources

BeforeOpenTables Event
OpenTables Method
OpenViews Property
AutoOpen Method
CursorAdapter Class
Properties
Language Reference


AutoRelease Property

Visual FoxPro 9.0 Language Reference
AutoRelease Property
See Also

Determines whether a form set is released when the last form in the form set is released. Available at design time; read/write at run time.

FormSet.AutoRelease[ = lExpr]

Return Value

lExpr

The settings for the AutoRelease property are:

Setting Description

True (.T.)

The default in the Form Designer. The form set is released when the last form in the form set is released.

False (.F.)

The default in program code. The form set is not released when the last form in the form set is released.

Remarks

Applies To: FormSet Object

See Also

Other Resources

Release Method
ReleaseType Property
Form Designer
Properties
Language Reference


AutoSize Property

Visual FoxPro 9.0 Language Reference
AutoSize Property
See Also

Specifies whether a control is automatically resized to fit its contents. Available at design time and run time.

Control.AutoSize[ = lExpr]

Return Value

lExpr

Specifies whether a control is resized to fit its contents. The settings for the AutoSize property are:

Setting Description

True (.T.)

The control is automatically resized to fit its contents.

False (.F.)

(Default) The contents are clipped when they exceed the area of the control.

Remarks

Applies To: CheckBox Control | CommandButton Control | CommandGroup Control | Label Control | OLE Bound Control | OLE Container Control | OptionButton Control | OptionGroup Control

For OLE Container controls, Autosize applies only to OLE objects that support in-place editing. The Sizable property must be set to true (.T.) to change the size of an OLE object during in-place editing.

See Also

Other Resources

Alignment Property
Height Property
Width Property
Properties
Language Reference


AutoVerbMenu Property

Visual FoxPro 9.0 Language Reference
AutoVerbMenu Property
See Also

Specifies whether a shortcut menu containing an OLE object's verbs is displayed when the OLE object is clicked with the right mouse button. Available at run time only.

Control.AutoVerbMenu[ = lExpr]

Return Value

lExpr

One of the following:

Setting Description

True (.T.)

(Default) The shortcut menu containing the OLE object's verbs is displayed when the OLE object is right-clicked.

False (.F.)

The shortcut menu containing the OLE object's verbs is not displayed when the OLE object is right-clicked.

Remarks

Applies To: Enabled Property | OLE Bound Control | OLE Container Control

At run time, if the AutoVerbMenu and Enabled properties are set to true (.T.), right-clicking the OLE object displays the shortcut menu containing the verbs supported by the OLE object. If the AutoVerbMenu and Enabled properties are set to false (.F.) or the OLE object does not support verbs, the shortcut menu isn't displayed when you right-click the OLE object.

See Also

Other Resources

DoVerb Method
How to: Add OLE Objects to Applications
Properties
Language Reference


AutoYield Property

Visual FoxPro 9.0 Language Reference
AutoYield Property
See Also

Specifies whether an instance of Visual FoxPro processes pending Windows events between execution of each line of user program code.

ApplicationObject.AutoYield[ = lExpr]

Return Value

lExpr

Specifies whether an instance of Visual FoxPro processes Windows events between each line of user program code. lExpr can be one of the following logical values:

lExpr Description

True (.T.)

(Default) The instance of Visual FoxPro processes pending Windows events between execution of each line of user program code.

If lExpr is set to true (.T.), the instance of Visual FoxPro processes pending Windows events in the same manner as earlier versions of Visual FoxPro.

False (.F.)

The instance of Visual FoxPro does not process pending Windows events between each line of user program code.

All pending Windows events are placed in a queue, and the events in the queue are processed when DOEVENTS is issued or a wait state occurs. A wait state occurs when Visual FoxPro is waiting for input from the user. The WAIT command does not create a wait state.

Remarks

Applies To: Application Object | _VFP System Variable

The AutoYield property should be set to false (.F.) when a form contains an ActiveX control. Setting AutoYield to false (.F.) prevents events for an ActiveX control from executing between lines of user program code. For example, if AutoYield is set to true (.T.), clicking an ActiveX control while user program code is executing may cause an event for the ActiveX control to execute, ignoring the user program code for the event, producing undesirable or unpredictable results.

The following occurs when the AutoYield property is set to false (.F.):

  • ActiveX controls cannot process events until a wait state occurs, so clicking an ActiveX control has no effect while user program code is executing. This is the same behavior for Visual FoxPro controls such as the Grid.

  • ON KEY LABEL commands and mouse events are ignored while user program code is executing. The ON KEY LABEL commands and mouse events are placed in a queue and processed at the next wait state.

  • Pressing Esc does not interrupt program execution. This is identical to setting ESCAPE to OFF. In this case you cannot exit infinite loops without shutting down the instance of Visual FoxPro.

  • Queries cannot be interrupted.

  • Switching to other applications is supported, but you cannot switch back to Visual FoxPro while Visual FoxPro user program code is executing.

See Also

Other Resources

DOEVENTS Command
WAIT Command
ON KEY LABEL Command
Properties
Language Reference


BackColor, ForeColor Properties

Visual FoxPro 9.0 Language Reference
BackColor, ForeColor Properties
See Also Example

Specifies the background or foreground color used to display text and graphics in an object. Read/write at design and run time.

Object.BackColor[ = nColor]
Object.ForeColor[ = nColor]

Return Value

nColor

Specifies a single color value. If nColor is a negative value, Visual FoxPro uses the integer and ignores any rollover issues. For example, -1 is the equivalent of 0xFFFFFFFF. The following table lists typical color values.

Color RGB values nColor

White

255, 255, 255

16777215

Black

0, 0, 0

0

Gray

192, 192, 192

12632256

Dark gray

128, 128, 128

8421504

Red

255, 0, 0

255

Dark red

128, 0, 0

128

Yellow

255, 255, 0

65535

Dark yellow

128, 128, 0

32896

Green

0, 255, 0

65280

Dark green

0, 128, 0

32768

Cyan

0, 255, 255

16776960

Dark cyan

0, 128, 128

8421376

Blue

0, 0, 255

16711680

Dark blue

0, 0, 128

8388608

Magenta

255, 0 ,255

16711935

Dark magenta

128, 0, 128

8388736

Remarks

Applies To: CheckBox Control | Column Object | ComboBox Control | CommandButton Control | CommandGroup Control | Container Object | Control Object | EditBox Control | Form Object | Grid Control | Header Object | Label Control | OptionButton Control | OptionGroup Control | Page Object | _SCREEN | Shape Control | Spinner Control | TextBox Control | ToolBar Object

Visual FoxPro uses a red-green-blue (RGB) color scheme for colors. The red, green, and blue components are each represented by a number between 0 and 255. Use the RGB( ) function to convert the three component colors into one composite nColor.

Note:
The ForeColor property does not apply to the CommandGroup, OptionGroup, or Shape controls.

The color settings, or Themes, of the operating system set the default color settings for the BackColor and ForeColor properties.

If the Themes property is True (.T.), setting the BackColor property value produces a 35% transparency overlay on top of the themed button. This produces a colorizing effect.

The Page BackColor property is disregarded if Page Themes is True (.T.). However, because a page is only a visual representation in the Class Designer, the back color appears.

Example

The following example demonstrates how the Shape control can be used to display a circle, ellipse, or square on a form, and how the BackColor property can be used to specify the color of each shape.

A form is created, and a set of option buttons and a command button are placed on the form. When you choose one of the option buttons, the corresponding shape is displayed on the form. The BackColor property is used to specify the color of each shape. The Height, Width, and Curvature properties of each shape determine the type of shape created.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('cmdCommand1','cmdMyCmndBtn')  && Add Command button
frmMyForm.AddObject('opgOptionGroup1','opgMyOptGrp') && Add Option Group
frmMyForm.AddObject('shpCircle1','shpMyCircle')  && Add Circle Shape
frmMyForm.AddObject('shpEllipse1','shpMyEllipse')  && Add Ellipse Shape
frmMyForm.AddObject('shpSquare','shpMySquare')  && Add Box Shape

frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible

frmMyForm.opgOptionGroup1.Buttons(1).Caption = "\<Circle"
frmMyForm.opgOptionGroup1.Buttons(2).Caption = "\<Ellipse"
frmMyForm.opgOptionGroup1.Buttons(3).Caption = "\<Square"
frmMyForm.opgOptionGroup1.SetAll("Width", 100) && Set Option group width
frmMyForm.opgOptionGroup1.Visible = .T.  && Option Group visible
frmMyForm.opgOptionGroup1.Click  && Show the circle

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS opgMyOptGrp AS OptionGroup  && Create an Option Group
   ButtonCount = 3  && Three Option buttons
   Top = 10
   Left = 10
   Height = 75
   Width = 100

   PROCEDURE Click
      ThisForm.shpCircle1.Visible = .F.  && Hide the circle
      ThisForm.shpEllipse1.Visible = .F.  && Hide the ellipse
      ThisForm.shpSquare.Visible = .F.  && Hide the square

      DO CASE
         CASE ThisForm.opgOptionGroup1.Value = 1
            ThisForm.shpCircle1.Visible = .T. && Show the circle
         CASE ThisForm.opgOptionGroup1.Value = 2
            ThisForm.shpEllipse1.Visible = .T.  && Show the ellipse
         CASE ThisForm.opgOptionGroup1.Value = 3
            ThisForm.shpSquare.Visible = .T.  && Show the square
      ENDCASE
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

DEFINE CLASS shpMyCircle AS SHAPE  && Create a circle
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 99
   BackColor = RGB(255,0,0)  && Red
ENDDEFINE

DEFINE CLASS shpMyEllipse AS SHAPE  && Create an ellipse
   Top = 35
   Left = 200
   Width = 100
   Height = 50
   Curvature = 99
   BackColor = RGB(0,128,0)  && Green
ENDDEFINE

DEFINE CLASS shpMySquare AS SHAPE  && Create a square
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 0
   BackColor = RGB(0,0,255)  && Blue
ENDDEFINE

See Also

Other Resources

BackStyle Property
ColorScheme Property
DisabledBackColor, DisabledForeColor Properties
FillColor Property
FillStyle Property
GETCOLOR( ) Function
RGB( ) Function
Properties
Language Reference


BackStyle Property

Visual FoxPro 9.0 Language Reference
BackStyle Property
See Also

Specifies whether the background of an object is transparent or opaque. Available at design time and run time.

Object.BackStyle[ = nStyle]

Return Value

nStyle

The settings for the BackStyle property are:

Setting Description

0

Transparent. Anything behind the object is visible.

1

(Default) Opaque. The object's BackColor fills the control and obscures any color or graphics behind it.

Remarks

Applies To: CheckBox Control | CommandGroup Control | Container Object | Control Object | EditBox Control | Image Control | Label Control | OptionButton Control | OptionGroup Control | Page Object | Shape Control | TextBox Control

You can use the BackStyle property to create transparent controls when you are using a background color on a Form object or when you want to place a control over a graphic. Use an opaque control when you want it to stand out on a busy background.

An object's BackColor property is ignored if the BackStyle property is set to 0 (Transparent).

For a Page object, the BackStyle property is read-only when the Tabs property is set to True (.T.) for the PageFrame containing the Page.

An object's BackStyle property is ignored if the object's Theme property is set to True (.T.).

See Also

Other Resources

BackColor, ForeColor Properties
DisabledBackColor, DisabledForeColor Properties
Properties
Language Reference


BaseClass Property

Visual FoxPro 9.0 Language Reference
BaseClass Property
See Also

Contains the name of the Visual FoxPro base class on which the referenced object is based. Read-only at design time and run time.

Object.BaseClass

Return Value

cBaseClass

Contains the Visual FoxPro base class on which the object is based. For more information about Visual FoxPro base classes, see Base Classes in Visual FoxPro.

Remarks

Applies To: CheckBox Control | Collection Class | Column Object | ComboBox Control | CommandButton Control | CommandGroup Control | Container Object | Control Object | CursorAdapter Class | Custom Object | EditBox Control | Exception Class | Form Object | FormSet Object | Grid Control | Header Object | Hyperlink Object | Image Control | Label Control | Line Control | ListBox Control | OLE Bound Control | OLE Container Control | OptionButton Control | OptionGroup Control | Page Object | PageFrame Control | ProjectHook Object | ReportListener Object | _SCREEN | Session Object | Shape Control | Spinner Control | TextBox Control | Timer Control | ToolBar Object

See Also

Other Resources

Class Property
Properties
Language Reference


BatchUpdateCount Property

Visual FoxPro 9.0 Language Reference
BatchUpdateCount Property
See Also

Specifies the number of update statements sent to the remote data source for buffered tables. When working with this property for regular cursors, use the CURSORSETPROP() and CURSORGETPROP() functions. Read/write.

Adjusting BatchUpdateCount can increase automatic updating performance dramatically.

Note:
Setting BatchUpdateCount for CursorAdapter objects overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

CursorAdapter.BatchUpdateCount [ = nValue]

Return Value

nValue

Numeric data type. The nValue parameter has a default value of 1.
Note:
When you are updating data, using Table Buffering, and updating the table or tables in the data source from multiple clients, avoid setting BatchUpdateCount to a value greater than 1. In these scenarios, TABLEUPDATE( ) always returns True (.T.). You can safely set BatchUpdateCount to a value greater than 1 for INSERT, UPDATE, and DELETE operations when lForce in TABLEUPDATE( ) is set to True (.T.).

Remarks

Applies To: CursorAdapter Class

BatchUpdateCount applies to CursorAdapter objects only when the data source type for the SQL INSERT, UPDATE, and DELETE commands is one of the following:

  • "ODBC"

    Additionally, the same connection handle must be used as the data source for the SQL INSERT, UPDATE, and DELETE commands.

    Note:
    The data source and data source type might be inherited from the DataSource and DataSourceType properties of either the CursorAdapter or DataEnvironment object.

  • "ADO"

    The same ADODB Command object must be used as the data source for the SQL INSERT, UPDATE, and DELETE commands. It is recommended that you set the InsertCmdDataSource, InsertCmdDataSourceType, UpdateCmdDataSource, UpdateCmdDataSourceType, DeleteCmdDataSource, and DeleteCmdDataSourceType properties explicitly because inheritance does not work in this scenario.

  • "XML"

    It is recommended that you set the InsertCmdDataSource, InsertCmdDataSourceType, UpdateCmdDataSource, UpdateCmdDataSourceType, DeleteCmdDataSource, and DeleteCmdDataSourceType properties explicitly because inheritance does not work in this scenario.

If BatchUpdateCount is greater than 1, Visual FoxPro updates the batch by executing the UpdateCmd property once per batch.

Note:
If batch updating is used, the BeforeInsert, AfterInsert, BeforeUpdate, AfterUpdate, BeforeDelete, and AfterDelete events do not fire. If an update fails for a batch, Visual FoxPro attempts to send a separate update for each row in the batch; however, the events still do not fire.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function
INSERT - SQL Command
UPDATE - SQL Command
DELETE - SQL Command
DataSource Property
DataSourceType Property
InsertCmdDataSource Property
InsertCmdDataSourceType Property
UpdateCmdDataSource Property
UpdateCmdDataSourceType Property
DeleteCmdDataSource Property
DeleteCmdDataSourceType Property
UpdateCmd Property
BeforeInsert Event
AfterInsert Event
BeforeUpdate Event
AfterUpdate Event
BeforeDelete Event
AfterDelete Event


BindControls Property

Visual FoxPro 9.0 Language Reference
BindControls Property
See Also Example

Specifies when data binding occurs for data-bound controls.

Visual FoxPro usually binds the controls to the data source when the form loads. However, you can use BindControls to specify when data binding occurs for various reasons, such as to improve performance or to delay binding controls to the data source until the user performs an action, after the form loads, or until the data is needed.

Note:
BindControls is intended for use when initially displaying a form and for binding controls after displaying the form. Although you can set BindControls to False (.F.) and back to True (.T.), BindControls is not intended for unbinding and rebinding controls at run time.

Form.BindControls [= lValue]

Return Value

Logical data type. The following table lists the values for lValue.

lValue | Description
True (.T.) | The Control.ControlSource or Grid.RecordSource binds to data when the form loads. (Default) If Form.BindControls = .T. and Control.ControlSource or Grid.RecordSource is changed, the control is rebound. If Form.BindControls is changed from .T. to .F., current bindings are not changed.
False (.F.) | The Control.ControlSource or Grid.RecordSource does not bind to data when the form loads. If Form.BindControls = .F. and Control.ControlSource or Grid.RecordSource is changed, the control is not rebound, but the ControlSource property or Recordsource property is changed. If Form.BindControls is changed from .F. to .T., all controls in the form are rebound according to the current value of Control.ControlSource or Grid.RecordSource.

Remarks

Applies To: Form Object

Example

Suppose a form needs to load a large number of tables or has a grid or other controls that bind to a cursor produced by a SQL statement that takes a long time to run. When the user launches the form, the form does not appear until it completely loads all the data.

By setting BindControls to False (.F.), the form appears immediately. You can then change BindControls to True (.T.) when the form is activated such as when the Form Activate event occurs and display a message such as "Please wait while loading data." The user then sees the form immediately along with a message that explains the delay in loading data instead of waiting for the form to appear.

See Also

Other Resources

Form Object Properties, Methods and Events
Properties
Language Reference


BorderColor Property

Visual FoxPro 9.0 Language Reference
BorderColor Property
See Also

Specifies the border color of an object. Available at design time and run time.

Object.BorderColor[ = nColor]

Return Value

nColor

Specifies the border color value. The following table lists typical color values:

Color RGB values nColor value

White

255, 255, 255

16777215

Black

0, 0, 0

0

Gray

192, 192, 192

12632256

Dark gray

128, 128, 128

8421504

Red

255, 0, 0

255

Dark red

128, 0, 0

128

Yellow

255, 255, 0

65535

Dark yellow

128, 128, 0

32896

Green

0, 255, 0

65280

Dark green

0, 128, 0

32768

Cyan

0, 255, 255

16776960

Dark cyan

0, 128, 128

8421376

Blue

0, 0, 255

16711680

Dark blue

0, 0, 128

8388608

Magenta

255, 0 ,255

16711935

Dark magenta

128, 0, 128

8388736

Remarks

Applies To: ComboBox Control | CommandGroup Control | Container Object | Control Object | EditBox Control | Image Control | Line Control | ListBox Control | OptionGroup Control | PageFrame Control | Shape Control | TextBox Control

BorderColor applies only to a text box or edit box when the SpecialEffect property is set to 1 - Plain.

Use the RGB( ) function to convert the three component colors into one composite nColor.

See Also

Other Resources

BackColor, ForeColor Properties
GetColor( ) Function
RGB( ) Function
SpecialEffect Property
Properties
Language Reference


BorderStyle Property

Visual FoxPro 9.0 Language Reference
BorderStyle Property
See Also

Specifies the border style of an object. Available at design time and run time.

Object.BorderStyle[ = nStyle]

Return Value

nStyle

For a CommandGroup, EditBox, Image, Label, OptionGroup, or TextBox control, the settings for the BorderStyle property are:

Setting Description

0

None. Default for Image and Label controls.

1

Fixed Single. Default for CommandGroup, EditBox, OptionGroup, and TextBox controls.
For a line or shape, the settings for the BorderStyle property are:

Setting Description

0

Transparent

1

(Default) Solid. The outer edge of the border is the outer edge of the Shape control.

2

Dash

3

Dot

4

Dash-Dot

5

Dash-Dot-Dot

6

Inside Solid
For a Form object, the settings for the BorderStyle property are:

Setting Description

0

No border

1

Fixed Single

2

Fixed Dialog

3

(Default) Sizable

Remarks

Applies To: ComboBox Control | CommandGroup Control | EditBox | Form Object | Image Control | Label Control | Line Control | OptionGroup Control | _SCREEN | Shape Control | TextBox Control | Spinner Control

If the BorderWidth property setting is greater than 1, regardless of the BorderStyle setting, a solid border is drawn. If BorderWidth is set to 1, BorderStyle produces the effects described in the tables above.

See Also

Other Resources

BorderColor Property
BorderWidth Property
DrawStyle Property
DrawWidth Property
Properties
Language Reference


BorderWidth Property

Visual FoxPro 9.0 Language Reference
BorderWidth Property
See Also

Specifies the width of a control's border. Available at design time and run time.

Control.BorderWidth[ = nWidth]

Return Value

nWidth

Specifies the width, which can range from 0 to 8192.
Note:
If the BorderWidth setting is greater than 1, the BorderStyle property setting is ignored.

Remarks

Applies To: Container Object | Control Object | Line Control | PageFrame Control | Shape Control

When BorderWidth is set to 0, the control appears to have no border. The BorderWidth setting is ignored for PageFrame controls when the Tabs setting is .T. (True).

See Also

Other Resources

BorderStyle Property
Properties
Language Reference


Bound Property

Visual FoxPro 9.0 Language Reference
Bound Property
See Also

Determines whether a control in a Column object is bound to the control source for the Column. Available at design time and run time.

Column.Bound[ = lExpr]

Return Value

lExpr

The settings for the Bound property are:

Setting Description

True (.T.)

(Default) The control is bound to the column's control source.

False (.F.)

The control is not bound to the column's control source.

Remarks

Applies To: Column Object

If a column's Bound property is set to true (.T.), the column's ControlSource property setting applies to the column and any controls contained in it. If you attempt to set the contained control's ControlSource property, an error occurs. If a column's Bound property is set to false (.F.), you can set the ControlSource property of a contained control directly. If you subsequently set the ControlSource setting of the column, it overrides the ControlSource setting of the contained control.

Typically, the following controls are bound to the corresponding data types:

Column control base class | Typical column data types
CheckBox | Logical, Numeric
ComboBox | Character, Numeric
CommandButton | Character, Numeric
EditBox | Character
ListBox | Character, Numeric
OptionButton | Character, Numeric
Spinner | Currency, Numeric
TextBox | Any data type except General or Memo
Note:
You cannot bind a control to a column whose data type is General or Memo.

See Also

Other Resources

AddObject Method
ControlSource Property
CurrentControl Property
Sparse Property
Properties
Language Reference


BoundColumn Property

Visual FoxPro 9.0 Language Reference
BoundColumn Property
See Also

Determines which column of a multicolumn list box or combo box is bound to the Value property of the control. Available at design time and run time.

Control.BoundColumn[ = nCol]

Return Value

nCol

Specifies the number of the column that is bound to the Value property. The default for nCol is 1.

Remarks

Applies To: ComboBox Control | ListBox Control

Use BoundColumn when the list box or combo box has multiple columns and when you want the data in a column other than the first column to be stored in the control's Value property.

See Also

Other Resources

Value Property
ActiveColumn Property
Columns Property
Properties
Language Reference


BoundTo Property

Visual FoxPro 9.0 Language Reference
BoundTo Property
See Also

Specifies whether the Value property of a combo box or list box is determined by the List or the ListIndex properties. Available at design time and run time.

 [Form.]Control.BoundTo[ = lExpression]

Return Value

lExpression

The settings for the BoundTo property are:

Setting Description

.T.

The Value property is determined by the List property.

.F.

(Default) The Value property is determined by data type of the variable or field specified in the ControlSource property.

If the variable or field specified in the ControlSource property setting is of character type, the Value property is determined by the List property.

If the variable or field specified in the ControlSource property setting is of numeric type, the Value property uses the index number from the ListIndex property.

This setting provides compatibility with Microsoft Visual FoxPro 3.0 and 2.x versions of FoxPro.

Remarks

Applies To: ComboBox Control | ListBox Control

In Visual FoxPro 3.0, if the ControlSource property for a combo box or list box is numeric, the ListIndex property value of the selected item is stored in the variable or field to which the control is bound. Set the BoundTo property to true (.T.) to store the value of the List property in the variable or field to which the control is bound.

See Also

Other Resources

ControlSource Property
ListIndex Property
Value Property
Properties
Language Reference


BreakOnError Property

Visual FoxPro 9.0 Language Reference
BreakOnError Property
See Also

Specifies whether Visual FoxPro permits errors to break program execution at the location where they occurred or sends them to the cursor adapter. Read/write at design time and run time.

BreakOnError applies only when the cursor adapter executes an event or an SQL INSERT, UPDATE, or DELETE command.

CursorAdapter.BreakOnError [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

Visual FoxPro does not display an error message and sends the error to the cursor adapter. (Default)

This behavior is the same as if Visual FoxPro raised an error, and the user cancelled execution. The error routine makes the last unhandled error available to the calling routine.

True (.T.)

Visual FoxPro permits the execution of the event or method to break at the location where the error occurs and displays an error message.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


BufferMode Property

Visual FoxPro 9.0 Language Reference
BufferMode Property
See Also

Specifies whether records are updated pessimistically or optimistically. Available at design time and run time.

Object.BufferMode[ = nValue]

Return Value

nValue

The settings for the BufferMode property are:

Setting Description

0

(Default) None. Records are locked when editing begins and fields are written when the record pointer moves. Mimics FoxPro 2.x behavior.

1

Pessimistic. Records are locked when editing begins and fields are written when the record pointer moves. You can use TABLEREVERT( ) to undo your changes to the current record.

2

Optimistic. Records are not locked when edited and Visual FoxPro attempts to lock the records when they are written to disk with TABLEUPDATE( ).

Remarks

Applies To: Form Object | FormSet Object | _SCREEN

If BufferMode is set to 1 or 2, any cursor used by a Grid control is enabled for table buffering. Any other control bound to data uses row buffering.

The BufferMode property setting will override any buffering settings made to form cursors prior to the form Init method, including those made in the form Load method.

See Also

Other Resources

BufferModeOverride Property
TABLEREVERT( ) Function
TABLEUPDATE ( ) Function
Properties
Language Reference


BufferModeOverride Property

Visual FoxPro 9.0 Language Reference
BufferModeOverride Property
See Also

Specifies whether to override the BufferMode property set at the form or form set level. Available at design time and run time.

DataEnvironment.Cursor.BufferModeOverride[ = nValue]

Return Value

nValue

The settings for the BufferModeOverride property are listed in the following table:

Setting Description

3

Optimistic row buffering. Allows edits to a single record and locks the record only when it is written to disk. You can use TABLEREVERT( ) to undo your changes.

5

Optimistic table buffering. Allows edits to all records and does not lock them until the records are written to disk with TABLEUPDATE( ). You can use TABLEREVERT( ) to undo your changes.

Applies To: Cursor Object | CursorAdapter Class

See Also

Other Resources

BufferMode Property
TABLEREVERT( ) Function
TABLEUPDATE ( ) Function
Properties
Language Reference


BuildDateTime Property

Visual FoxPro 9.0 Language Reference
BuildDateTime Property
See Also

Contains the last build date and time for a project. Read-only.

Object.BuildDateTime

Remarks

Applies To: Project Object

If a project has not been built, BuildDateTime contains an empty DateTime value.

See Also

Other Resources

Build Options Dialog Box
BUILD PROJECT Command
DATETIME( ) Function
Properties
Language Reference


ButtonCount Property

Visual FoxPro 9.0 Language Reference
ButtonCount Property
See Also Example

Specifies the number of buttons in a CommandGroup or OptionGroup. Available at design time and run time.

Control.ButtonCount[ = nNumber]

Return Value

nNumber

Specifies the number of buttons for the control.

Remarks

Applies To: CommandGroup Control OptionGroup Control

Use the ButtonCount property to dynamically set the number of buttons contained in a CommandGroup or OptionGroup.

If you change the number of buttons at run time, names are automatically assigned to the new buttons. The buttons are assigned the name CommandN for a CommandGroup or OptionN for an OptionGroup where N is the number of the button added. For example, if there are four buttons in the CommandGroup and the Buttons property setting is changed to 5, the new button is named Command5.

Example

The following example creates an OptionGroup control and places the control on a form. The OptionGroup control has three buttons; depending on the option button you click, a circle, ellipse, or square appears. The ButtonCount property is used to specify the number of buttons in the OptionGroup. The Buttons and Caption properties specify the text displayed next to each option button.

The Shape control is used to create the circle, ellipse, and square. The OptionGroup control's Click event uses a DO CASE ... ENDCASE structure and the Value property to display the appropriate shape when you click an option button.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('cmdCommand1','cmdMyCmndBtn')  && Add Command button
frmMyForm.AddObject('opgOptionGroup1','opgMyOptGrp') && Add Option Group
frmMyForm.AddObject('shpCircle1','shpMyCircle')  && Add Circle Shape
frmMyForm.AddObject('shpEllipse1','shpMyEllipse')  && Add Ellipse Shape
frmMyForm.AddObject('shpSquare','shpMySquare')  && Add Box Shape

frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible

frmMyForm.opgOptionGroup1.Buttons(1).Caption = "\<Circle"
frmMyForm.opgOptionGroup1.Buttons(2).Caption = "\<Ellipse"
frmMyForm.opgOptionGroup1.Buttons(3).Caption = "\<Square"
frmMyForm.opgOptionGroup1.SetAll("Width", 100) && Set Option group width
frmMyForm.opgOptionGroup1.Visible = .T.  && Option Group visible
frmMyForm.opgOptionGroup1.Click  && Show the circle

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS opgMyOptGrp AS OptionGroup  && Create an Option Group
   ButtonCount = 3  && Three Option buttons
   Top = 10
   Left = 10
   Height = 75
   Width = 100

   PROCEDURE Click
      ThisForm.shpCircle1.Visible = .F.  && Hide the circle
      ThisForm.shpEllipse1.Visible = .F.  && Hide the ellipse
      ThisForm.shpSquare.Visible = .F.  && Hide the square

      DO CASE
         CASE ThisForm.opgOptionGroup1.Value = 1
            ThisForm.shpCircle1.Visible = .T. && Show the circle
         CASE ThisForm.opgOptionGroup1.Value = 2
            ThisForm.shpEllipse1.Visible = .T.  && Show the ellipse
         CASE ThisForm.opgOptionGroup1.Value = 3
            ThisForm.shpSquare.Visible = .T.  && Show the square
      ENDCASE
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

DEFINE CLASS shpMyCircle AS SHAPE  && Create a circle
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 99
   BackColor = RGB(255,0,0)  && Red
ENDDEFINE

DEFINE CLASS shpMyEllipse AS SHAPE  && Create an ellipse
   Top = 35
   Left = 200
   Width = 100
   Height = 50
   Curvature = 99
   BackColor = RGB(0,128,0)  && Green
ENDDEFINE

DEFINE CLASS shpMySquare AS SHAPE  && Create a square
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 0
   BackColor = RGB(0,0,255)  && Blue
ENDDEFINE

See Also

Other Resources

Buttons Property
DO CASE ... ENDCASE Command
CommandButton Control
Properties
Language Reference


Buttons Property

Visual FoxPro 9.0 Language Reference
Buttons Property
See Also Example

An array for accessing every button in a group. Not available at design time.

Control.Buttons(nIndex).Property = Value
-Or-
Control.Buttons(nIndex).Method

Return Value

nIndex

An integer between 1 and the number of buttons specified in the ButtonCount property for Control.
Property

A property of a CommandButton or OptionButton.
Value

The value of Property.
Method

A method of a CommandButton or OptionButton.

Remarks

Applies To: CommandGroup Control | OptionGroup

You can use the Buttons property to set properties and call methods for all the buttons in the group. The Buttons property is an array that is created when the button group is created.

Example

The following example creates an OptionGroup control and places the control on a form. The OptionGroup control has three buttons; depending on the option button you click, a circle, ellipse, or square appears. The ButtonCount property specifies the number of buttons in the OptionGroup. The Buttons and Caption properties specify the text displayed next to each option button.

The Shape control is used to create the circle, ellipse, and square. The OptionGroup control's Click event uses a DO CASE ... ENDCASE structure and the Value property to display the appropriate shape when you click an option button.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('cmdCommand1','cmdMyCmndBtn')  && Add Command button
frmMyForm.AddObject('opgOptionGroup1','opgMyOptGrp') && Add Option Group
frmMyForm.AddObject('shpCircle1','shpMyCircle')  && Add Circle Shape
frmMyForm.AddObject('shpEllipse1','shpMyEllipse')  && Add Ellipse Shape
frmMyForm.AddObject('shpSquare','shpMySquare')  && Add Box Shape

frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible

frmMyForm.opgOptionGroup1.Buttons(1).Caption = "\<Circle"
frmMyForm.opgOptionGroup1.Buttons(2).Caption = "\<Ellipse"
frmMyForm.opgOptionGroup1.Buttons(3).Caption = "\<Square"
frmMyForm.opgOptionGroup1.SetAll("Width", 100) && Set Option group width
frmMyForm.opgOptionGroup1.Visible = .T.  && Option Group visible
frmMyForm.opgOptionGroup1.Click  && Show the circle

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS opgMyOptGrp AS OptionGroup  && Create an Option Group
   ButtonCount = 3  && Three Option buttons
   Top = 10
   Left = 10
   Height = 75
   Width = 100

   PROCEDURE Click
      ThisForm.shpCircle1.Visible = .F.  && Hide the circle
      ThisForm.shpEllipse1.Visible = .F.  && Hide the ellipse
      ThisForm.shpSquare.Visible = .F.  && Hide the square

      DO CASE
         CASE ThisForm.opgOptionGroup1.Value = 1
            ThisForm.shpCircle1.Visible = .T. && Show the circle
         CASE ThisForm.opgOptionGroup1.Value = 2
            ThisForm.shpEllipse1.Visible = .T.  && Show the ellipse
         CASE ThisForm.opgOptionGroup1.Value = 3
            ThisForm.shpSquare.Visible = .T.  && Show the square
      ENDCASE
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

DEFINE CLASS shpMyCircle AS SHAPE  && Create a circle
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 99
   BackColor = RGB(255,0,0)  && Red
ENDDEFINE

DEFINE CLASS shpMyEllipse AS SHAPE  && Create an ellipse
   Top = 35
   Left = 200
   Width = 100
   Height = 50
   Curvature = 99
   BackColor = RGB(0,128,0)  && Green
ENDDEFINE

DEFINE CLASS shpMySquare AS SHAPE  && Create a square
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 0
   BackColor = RGB(0,0,255)  && Blue
ENDDEFINE

See Also

Other Resources

ButtonCount Property
SetAll Method
CommandButton Control
Properties
Language Reference


Cancel Property

Visual FoxPro 9.0 Language Reference
Cancel Property
See Also Example

Specifies whether a CommandButton or OLE Container control is the Cancel button; that is, if the user presses the ESC key, the Cancel button's Click event will occur. Available at design time and run time.

Object.Cancel[ = lExpr]

Return Value

lExpr

The settings for the Cancel property are:

Setting Description

True (.T.)

The CommandButton or OLE Container control is the Cancel button.

False (.F.)

(Default) The CommandButton or OLE Container control is not the Cancel button.

Remarks

Applies To: CommandButton | OLE Container Control

The Cancel property applies only to an OLE Container control that contains an "Acts like a Button" ActiveX control (.ocx).

Example

The following example creates a command button and an OptionGroup control and places them on a form. The Cancel property is used to assign the command button as the Cancel button. If the ESC key is pressed, the Command button's Click event occurs and the Click event procedure executes CLEAR EVENTS to close the form and stop event processing.

The OptionGroup control has three buttons; depending on the option button you click, a circle, ellipse, or square is displayed. The Shape Control is used to create the circle, ellipse, and square. The OptionGroup control's Click event uses a DO CASE ... ENDCASE structure and the Value property to display the appropriate shape when you click an option button.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('cmdCommand1','cmdMyCmndBtn')  && Add Command button
frmMyForm.AddObject('opgOptionGroup1','opgMyOptGrp') && Add Option Group
frmMyForm.AddObject('shpCircle1','shpMyCircle')  && Add Circle Shape
frmMyForm.AddObject('shpEllipse1','shpMyEllipse')  && Add Ellipse Shape
frmMyForm.AddObject('shpSquare','shpMySquare')  && Add Box Shape

frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible

frmMyForm.opgOptionGroup1.Buttons(1).Caption = "\<Circle"
frmMyForm.opgOptionGroup1.Buttons(2).Caption = "\<Ellipse"
frmMyForm.opgOptionGroup1.Buttons(3).Caption = "\<Square"
frmMyForm.opgOptionGroup1.SetAll("Width", 100) && Set Option group width
frmMyForm.opgOptionGroup1.Visible = .T.  && Option Group visible
frmMyForm.opgOptionGroup1.Click  && Show the circle

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS opgMyOptGrp AS OptionGroup  && Create an Option Group
   ButtonCount = 3  && Three Option buttons
   Top = 10
   Left = 10
   Height = 75
   Width = 100

   PROCEDURE Click
      ThisForm.shpCircle1.Visible = .F.  && Hide the circle
      ThisForm.shpEllipse1.Visible = .F.  && Hide the ellipse
      ThisForm.shpSquare.Visible = .F.  && Hide the square

      DO CASE
         CASE ThisForm.opgOptionGroup1.Value = 1
            ThisForm.shpCircle1.Visible = .T. && Show the circle
         CASE ThisForm.opgOptionGroup1.Value = 2
            ThisForm.shpEllipse1.Visible = .T.  && Show the ellipse
         CASE ThisForm.opgOptionGroup1.Value = 3
            ThisForm.shpSquare.Visible = .T.  && Show the square
      ENDCASE
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

DEFINE CLASS shpMyCircle AS SHAPE  && Create a circle
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 99
   BackColor = RGB(255,0,0)  && Red
ENDDEFINE

DEFINE CLASS shpMyEllipse AS SHAPE  && Create an ellipse
   Top = 35
   Left = 200
   Width = 100
   Height = 50
   Curvature = 99
   BackColor = RGB(0,128,0)  && Green
ENDDEFINE

DEFINE CLASS shpMySquare AS SHAPE  && Create a square
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 0
   BackColor = RGB(0,0,255)  && Blue
ENDDEFINE

See Also

Other Resources

Click Event
Default Property
CANCEL Command
Cancel Button
Commands
Language Reference


Caption Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Caption Property (Visual FoxPro)
See Also Example

Specifies the text displayed in the caption of an object. Available at design time and run time.

Object.Caption[ = cText]

Return Value

cText

Specifies text displayed with an object. The maximum number of characters for the Caption property is 255. The following table describes how captions display depending on the object.

Object Caption display

Form

Caption displays in the title bar of the form. When the form minimizes, the caption displays to the right of the form icon.

PageFrame

Caption displays on the tab of each page in the page frame.

Controls

Caption displays on or next to the control. If the control displays an icon, setting the PicturePosition property determines the placement of the icon and therefore, the placement of the caption.

Remarks

Applies To: CheckBox Control | CommandButton Control | Form Object | Header Object | Label Control | OptionButton Control | Page Object | _SCREEN | ToolBar Object

When you create a new form or control, the default value of the Name property sets the default value of the Caption property. This default caption includes the name of the object class and an integer, for example, Command1, Combo1, or Form1.

Use the Name property to properly refer to an object in code. The Caption property describes only the text that appears on the screen for identifying the control. These two properties begin with the same value, but are set independently thereafter.

If you do not specify a Width property setting for a control, the control is automatically sized to contain the caption.

To automatically resize a Label control to fit its caption, set the AutoSize property to True (.T.).

To assign an access key to a control, include a backslash and a less-than sign (\<) in the caption immediately preceding the character you want to designate as the access key. A user can then press ALT and the specified character to move focus to that control. If the control is a command button, check box, or option button, pressing ALT and the specified character also has the effect of clicking the control.

To add an underline to a character in a column header caption, precede the character with an ampersand (&). If you want to include the character "&" in a column header caption, use two consecutive & characters. Note that this does not cause the letter to behave as an access key, but only underlines the header caption character.

Example

This example demonstrates the use of the Caption property to change the main Visual FoxPro window caption from Microsoft Visual FoxPro to the current version number of Visual FoxPro.
Copy Code
_SCREEN.Caption=VERSION()

See Also

Other Resources

AutoSize Property
BorderStyle Property
Name Property
Style Property
Width Property


Centered Property

Visual FoxPro 9.0 Language Reference
Centered Property
See Also Example

Specifies whether a CheckBox control is centered within the control boundaries.

CheckBox.Centered [= lExpr]

Return Value

lExpr

Logical data type. The following table lists the values of lExpr.

lExpr Description

False (.F.)

The CheckBox control is not centered within the control boundaries. (Default)

True (.T.)

Centers the CheckBox control within the control boundaries.

Remarks

Applies To: CheckBox Control

If a CheckBox control is not contained in a grid, the control is centered within its own control boundaries.

Centered works in conjunction with the Alignment property. If you supply a caption, the left and right alignment values of the Alignment property determine on which side of the check box the caption appears. If the Centered property is also set to True (.T.), both the caption and check box are centered horizontally and vertically in the grid column.

If the Sparse property of the column is set to True (.T.) (default), the Alignment property of the column determines the placement of text in all the cells in the column. However, when a particular cell gets focus, and the control appears, Visual FoxPro uses the Alignment property of the control. If you set the Sparse property of the column to False (.F.), Visual FoxPro uses the Alignment property of the control and disregards the column's Alignment property.

When the column's Alignment property is set at design time, the designer attempts to set the Alignment property on the controls in the column as well. When that control is a CheckBox, setting the column's Alignment to any of the "center" property values automatically sets the Centered property to True (.T.).

If Centered is True (.T.), the check box remains centered horizontally and vertically in the grid cell as the grid columns and rows are resized.

Example

The following example shows how you can set the Centered property to align a check box with the center of the control and its caption to the right of the check box:
Copy Code
Checkbox1.Centered = .T.
Checkbox1.Alignment = 1

Example 2

The following example shows how you can set the Centered property to align a check box within the center of a grid column. Setting the Sparse property of the column to False (.F.) specifies that the Alignment property of the control takes precedence over the Alignment property of the grid column:

Copy Code
Column1.Sparse = .F.
Column1.Checkbox1.Centered = .T.
Column1.Checkbox1.Caption = ""

See Also

Other Resources

Properties
Sparse Property
Alignment Property


Century Property

Visual FoxPro 9.0 Language Reference
Century Property
See Also

Specifies whether the century portion of a date is displayed in a text box. Available at design time and run time.

Object.Century[ = nValue]

Return Value

nValue

One of the following settings:

Setting Description

0

Off. The century portion of the date is not displayed.

1

(Default) On. The century portion of the date is displayed.

2

The SET CENTURY setting determines if the century portion of the date is displayed. If SET CENTURY is ON, the century portion of the date is displayed. If SET CENTURY is OFF, the century portion of the date is not displayed.

Remarks

Applies To: TextBox Control

The Century property setting is ignored if the DateFormat property is set to Short or Long.

Note that in earlier versions of Visual FoxPro the default for the Century property is 2.

See Also

Other Resources

DateFormat Property
DateMark Property
Hours Property
Seconds Property
SET CENTURY Command
StrictDateEntry Property
Properties
Language Reference


ChildAlias Property

Visual FoxPro 9.0 Language Reference
ChildAlias Property
See Also

Specifies the alias of the child table. Read-only at design time and run time.

DataEnvironment.Relation.ChildAlias[ = cText]

Return Value

cText

Specifies the alias of the child table in the relation.

Remarks

Applies To: Relation

The ChildAlias property setting must be the same name as the Alias property setting for the Cursor object that represents the child table.

See Also

Other Resources

Alias Property
ParentAlias Property
Cursor Object
Cursor Object Properties, Methods and Events
Properties
Language Reference


ChildOrder Property

Visual FoxPro 9.0 Language Reference
ChildOrder Property
See Also

Specifies the index tag for the record source of the Grid control or Relation object. Available at design time and read-only at run time.

Object.ChildOrder[ = cTagName]

Return Value

cTagName

Specifies an existing index tag name.

Remarks

Applies To: Grid Control | Relation Object

If the ChildOrder property is set, the Order property of the Cursor for the child table is ignored.

Use this property to link two tables that have a one-to-many relationship. For example, a customer table containing one record per customer links to an order table containing multiple orders per customer. For this one-to-many relationship, set the ChildOrder property to the customer ID index tag field.

The ChildOrder property mimics the behavior of SET ORDER.

See Also

Other Resources

ControlSource Property
LinkMaster Property
SET ORDER Command
Properties
Language Reference


ChildTable Property

Visual FoxPro 9.0 Language Reference
ChildTable Property
See Also Example

Contains an object reference to a child XMLTable object. Read/write.

XMLTable.ChildTable

Return Value

Object reference. ChildTable contains an object reference to a child XMLTable object and null (.NULL.) when not populated.

Remarks

Applies To: XMLTable Class

For nested tables in SQL XML, Visual FoxPro populates the ChildTable property with information about the nested tables involved in the join operation. However, XMLAdapter does not assign the ChildTable property when working with ADO.NET DataSets. For more information about how XMLAdapter treats nested tables for ADO.NET DataSet and SQL XML data sources, see XMLAdapter Class.

Example

The following example illustrates how an XMLAdapter object treats the Orders table as child table for the Customers table and the Order_details table as a child table for the Orders table.
Copy Code
<?xml version="1.0" encoding="utf-8"?>
<SqlXmlAdoData>
   <Schema name="Schema1" xmlns="urn:schemas-microsoft-com:xml-data" xmlns:dt="urn:schemas-microsoft-com:datatypes">
      <ElementType name="Customers" content="eltOnly" model="closed" order="many">
         <element type="Orders" maxOccurs="*"/>
         <element type="CustomerID"/>
         <element type="CompanyName"/>
      </ElementType>
      <ElementType name="CustomerID" content="textOnly" model="closed" dt:type="string"/>
      <ElementType name="CompanyName" content="textOnly" model="closed" dt:type="string"/>
      <ElementType name="Orders" content="eltOnly" model="closed" order="many">
         <element type="Order_details" maxOccurs="*"/>
         <element type="OrderID"/>
         <element type="OrderDate"/>
         <element type="ShipName"/>
      </ElementType>
      <ElementType name="OrderID" content="textOnly" model="closed" dt:type="i4"/>
      <ElementType name="OrderDate" content="textOnly" model="closed" dt:type="dateTime"/>
      <ElementType name="ShipName" content="textOnly" model="closed" dt:type="string"/>
      <ElementType name="Order_details" content="eltOnly" model="closed" order="many">
         <element type="ProductID"/>
         <element type="UnitPrice"/>
         <element type="Quantity"/>
      </ElementType>
      <ElementType name="ProductID" content="textOnly" model="closed" dt:type="i4"/>
      <ElementType name="UnitPrice" content="textOnly" model="closed" dt:type="fixed.14.4"/>
      <ElementType name="Quantity" content="textOnly" model="closed" dt:type="i2"/>
   </Schema>
   <Customers xmlns="x-schema:#Schema1">
      <CustomerID>CACTU</CustomerID>
      <CompanyName>Cactus Comidas para llevar</CompanyName>
      <Orders>
         <OrderID>10521</OrderID>
         <OrderDate>1997-04-29T00:00:00</OrderDate>
         <ShipName>Cactus Comidas para llevar</ShipName>
         <Order_details>
            <ProductID>35</ProductID>
            <UnitPrice>18</UnitPrice>
            <Quantity>3</Quantity>
         </Order_details>
         <Order_details>
            <ProductID>41</ProductID>
            <UnitPrice>9.65</UnitPrice>
            <Quantity>10</Quantity>
         </Order_details>
         <Order_details>
            <ProductID>68</ProductID>
            <UnitPrice>12.5</UnitPrice>
            <Quantity>6</Quantity>
         </Order_details>
      </Orders>
   </Customers>
</SqlXmlAdoData>

See Also

Other Resources

Properties
XMLTable Object Properties, Methods, and Events


Class Browser Properties

Visual FoxPro 9.0 Language Reference
Class Browser Properties
See Also

The following properties are associated with the Class Browser. For more information, see How to: Customize the Class Browser and Class Browser Window.

Note:
Properties marked as "Reference only" or "Internal use only" are maintained internally and used by the Class Browser. Avoid changing the value of reference-only properties; you might cause errors in the Class Browser.

lActive

Reference only. Returns the active status of the Class Browser. If the Class Browser has the focus, the value is True (.T.).
cAlias

Returns the alias of the work area within the Class Browser data session associated with the selected class in the class list. By default, the Class Browser private data session opens at least two table aliases: BROWSER and METADATA. The BROWSER alias is for Browser.dbf and is shared for all instances. The METADATA alias is for the class library (.vcx) or form (.scx) open in the Class Browser. If more than one file is open, the METADATA alias is incremented once for each open file.
cAddInMethod

Reference only. Returns the method name that called the external add-in being executed and clears when execution is complete. When an add-in is executed, this property contains the name of the method that called the add-in.
lAddInMode

Returns the status of a Class Browser add-in. If True (.T.), the add-in is called; if False (.F.), the add-in is complete.
lAddInTrace

Returns the status of the display trace mode that monitors the events of an add-in. If True (.T.), messages describing the events of an add-in are sent to the Visual FoxPro main window.
nAtPos

Internal use only. The default value is 0.
lAutoExpand

Determines whether the class list expands or collapses automatically when it is refreshed. If the value is True (.T.), the class list automatically expands or collapses the class trees in the outline. If False (.F), the class list outline does not expand or collapse. The default value is True (.T.).
cBaseClass

Reference only. Returns the name of the base class of the selected class in the class list.
cBrowserTable

Reference only. Returns the full path of the Browser.dbf registration table.
lBusyState

Reference only. Returns the status of the refresh operation for the Class Browser. If True (.T.), the refresh operation is in progress.
cClass

Reference only. Returns the name of the selected class in the class list.
nClassCount

Reference only. Returns the total number of items in the class list. The default value is 0.
cClassLibrary

Reference only. Returns the name of the class library for the selected class in the class list.
aClassList

Reference only. A two-dimensional array of values associated with a class library (.vcx) or form (.scx) file in the current class list. Each file in the list has its own alias. For example, if the class list displays two files, the aliases are METADATA1 and METADATA2. The array contains the following formation.

aClassList position Setting

[nIndex,1]

Name of a class

[nIndex,2]

Associated metadata record number

[nIndex,3]

Outline indentation level

[nIndex,4]

Name of the file containing the parent class

[nIndex,5]

Name of the parent class

[nIndex,6]

Name of the file containing the class

[nIndex,7]

Name of the class icon file

[nIndex,8]

The BaseClass of the class

[nIndex,9]

Specifies whether class is defined as OLE public
nClassListIndex

Reference only. Returns the position of the selected class in the Class list. The value for the first item is 0. The default value is – 1.
nClassTimeStamp

The TimeStamp value (from the .vcx/.scx TimeStamp field) for the selected class.
cClassType

Reference only. Returns the current filter on the Class list as specified in the ClassType box.
tcClassType

The initial Type filter for the Class list.
tcDefaultClass

Reference only. Returns the value or reference of the second parameter passed to BROWSER.APP. For example, if you open the Class Browser by typing the following code, this property returns "baseform."
Copy Code
DO (_BROWSER) WITH "wizstyle.vcx","baseform"
lDescriptions

If True (.T.), descriptions are displayed for classes and members.
lDisplayHierarchyError

Whether or not to display an error message if classes without valid ParentClasses are loaded in the Class Browser. The default is True (.T.).
nDisplayMode

Reference only. Returns the display mode specified by the display mode option group: 1 – hierarchical or 2 – alphabetical. The default value is 1.
lDragDrop

For internal use only. Whether or not a drag operation is in progress.
cDragIcon

Returns the current cursor file for the drag icon during a drag operation.
lEmptyFilter

If True (.T.), empty methods are displayed in the Members list. The default is False (.F.).
lError

Returns the status of error checking. If True (.T.), an error occurred and the Class Browser error dialog box is displayed. When the Class Browser opens, this property is set to False (.F.). If you want to check for errors, make sure this property is set to False.
lExpanded

For internal use only.
nFileCount

Reference only. Returns the number of class library (.vcx) or form (.scx) files currently open in the Class Browser. The default value is 0.
lFileMode

Reference only. Returns the type of the selected item in the class list. If True (.T.), a file is selected; if False (.F.), a class is selected.
cFileName

Reference only. Returns the full path of the file associated with the selected class in the class list.
tcFileName

Reference only. Returns the value or reference of the second parameter passed to BROWSER.APP. For example, if you open the Class Browser by typing the following code, this property returns "Wizstyle.vcx."
Copy Code
DO (_BROWSER) WITH "wizstyle.vcx","baseform"
aFiles

Reference only. An array of class library (.vcx), form (.scx), application (.exe), object library (.olb), and type library (.tlb) files currently opened in the Class Browser.
cFilter

Reference only. Returns the current SET FILTER setting from the open metadata table for the selected class in the class list.
lFormAddObject

For internal use only.
cGetFileExt

Determines the Class Browser's GETFILE( ) default method extensions. The default value is "VCX;SCX;PJX;EXE;OLB;TLB."
lHiddenFilter

If True (.T.), hidden members are displayed in the Members list. The default is False (.F.).
lIgnoreErrors

For internal use only.
lInitialized

Reference only. Returns the initialization state of the Class Browser. If True (.T.), the Class Browser is initialized; if False (.F.), the Class Browser is not initialized.
aInstances

Reference only. An array of instances associated with the selected class in the class list. Functionality is identical to AINSTANCE( ).
nInstances

Reference only. Returns the total number of instances associated with the selected class in the class list using AINSTANCE( ). The default value is 0.
cLastFindText

For internal use only.
nLastHeight

The initial height of a form before a Resize event occurs. The default value is (THIS.Height).
nLastRecNo

For internal use only. The initial value is 1.
cLastSetComp

The setting of SET COMPATIBLE when the Class Browser was loaded.
cLastSetESC

The setting of SET ESCAPE when the Class Browser was loaded.
cLastSetUDFParms

The setting of SET UDFPARMS when the Class Browser was loaded.
cLastValue

For internal use only.
nLastWidth

Returns the initial width of a form before a Resize event occurs. The default value is (THIS.Width).
tlListBox

If a True (.T.) value is passed to the Class Browser in this argument, classes and members are displayed in list boxes rather than in tree view controls.
lModalDialog

Determines if the class list is refreshed when the Class Browser regains focus after activating a modal dialog box. If True (.T.), the list is not refreshed; if False (.F.), the list is refreshed. The default value is True (.T.).
nMouseButton

For internal use only. Returns which mouse button was pressed.
lNoDefault

Returns the status indicating how default behavior is handled when returning from an add-in. If True (.T.), the default behavior is ignored.
lOutlineOCX

Reference only. If True (.T.), classes and members are displayed in tree view controls. You might need this information in an add-in program.
cParentClass

Reference only. Returns the name of the parent class of the selected class in the class list.
lParentClassBrowser

If True (.T.), the Edit ParentClass Method toolbar is displayed. The default is True. You can click this button to immediately view or edit the parent class method from the editor
cParentClassBrowserCaption

The caption of the ParentClass Browser toolbar. The default value is SPACE(10) + "ParentClass Browser"
cParentClassSymbol

Determines the symbol displayed beside a class to indicate that it is a subclass of a class that is not displayed in the Classes list.
nPixelOffset

Internal use only. Determines the number of pixels to cascade multiple instances of the Class Browser. The default value is 22.
cPlatform

Reference only. Returns the name of the current platform.
cProgramName

Reference only. Returns the full path of the BROWSER.APP file being executed.
lProtectedFilter

If True (.T.), protected members are displayed in the Members list. The default is False (.F.).
lReadOnly

Reference only. Returns the read-only status of the file associated with the selected class in the class list.
nRecCount

Reference only. Returns the total number of records in the open class library (.vcx) and form (.scx) files. The default value is 0.
lRefreshMode

Internal use only.
lRelease

Internal use only. Specifies that the Class Browser is automatically released.
lResizeMode

Internal use only. Returns the resize mode status of the Class Browser.
lSCXMode

Reference only. Returns the status of the file type of the selected class in the class list. If True (.T.), the file is a form (.scx); if False (.F.), the file is a class library (.vcx).
nShift

For internal use only. State of the SHIFT key when a mouse button is pressed.
oSource

Reference only. Returns the reference for an object dropped on a form from the Class Browser. After the DragDrop method is complete, oSource is set to null (.NULL.).
cStartName

Reference only. Returns the Name property of the Class Browser from when the Class Browser was loaded, but before the name is incremented. For example, the default value is ClassBrowser and, for each instance opened, the name is incremented: ClassBrowser1, ClassBrowser2.
nStrLen

For internal use only. The default value is 0.
cTimeStamp

Reference only. Returns the timestamp field value of the selected class in the class list.
lVCXSCXMode

If True (.T.), the class or file selected is a .vcx or .scx, or is in a .vcx or .scx.
tnWindowState

For internal use only. Whether the Class Browser window is minimized (1), maximized (2), or normal (0).

Initial Values of Class Browser Properties

When an instance of the Class Browser is opened, the properties are set to the default values shown in the following table.

Class Browser property | Initial setting
cAddIn | ""
cAddInMethod | ""
cAlias | ""
Caption | "Class Browser"
cBaseClass | ""
cBrowserTable | ""
cClass | ""
cClassLibrary | ""
cClassTimeStamp | ""
cClasstype | ""
cDragIcon | ""
cFileName | ""
cFilter | ""
cGetFileExt | vcx;scx;pjx;exe;olb;tlb
cLastGetFileExt | ""
cLastSetComp | ""
cLastSetEsc | ""
cLastSetudfParms | ""
cLastValue | ""
cParentClass | ""
cParentClassSymbol | (IIF(VERSION(3)=="00",CHR(171),"<"))
cPlatform | ""
cProgramName | ""
cStartName | ""
DataSession | 2
FontBold | .F.
FontName | "MS Sans Serif"
FontSize | 8
Height | 360
HelpContextID | 95825501
Icon | Browser.ico
lAutoExpand | .T.
lDescriptions | .T.
lDisplayHierarchyError | .T.
Left | 0
lParentClassBrowser | .T.
MinHeight | (175)
MinWidth | (250)
Name | "classbrowser"
nAtPos | 0
nClassCount | 0
nClassListIndex | -1
nDisplayMode | 1
nFileCount | 0
nInstances | 0
nLastHeight | (this.Height)
nLastRecNo | 1
nLastWidth | (this.Width)
nMouseButton | 0
nPixelOffset | 22
nRecCount | 0
nShift | 0
nStrLen | 0
nTimeStamp | 0
oParentClassBrowser | .NULL.
oSource | .NULL.
ShowTips | .T.
Top | -1
Width | 462

See Also

Other Resources

Class Browser Methods
Class Browser Object Members
Properties


Class Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Class Property (Visual FoxPro)
See Also

Returns the name of the class on which an object is based. Read-only at design time and run time.

Object.Class

Remarks

Applies To: CheckBox Control | Collection Class | Column | ComboBox Control | CommandButton Control | CommandGroup Control | Container Object | Control Object | CursorAdapter Class | Custom Object | EditBox Control | Exception Class | Form Object | FormSet Object | Grid Control | Header Object | Image Control | Label Control | Line Control | ListBox Control | OLE Bound Control | OLE Container Control | OptionButton Control | OptionGroup Control | Page Object | PageFrame Control | ProjectHook Object | ReportListener Object | Session Object | Shape Control | _SCREEN | Spinner Control | TextBox Control | Timer Control | ToolBar Object

In the Class Designer, the Class property returns the actual name of the class.

See Also

Other Resources

AddObject Method
BaseClass Property
Properties
Language Reference


ClassLibrary Property

Visual FoxPro 9.0 Language Reference
ClassLibrary Property
See Also

Specifies the file name of the user-defined class library that contains the object's class. Read-only at design time and run time.

Object.ClassLibrary

Remarks

Applies To: CheckBox Control | Collection Class | Column Object | ComboBox Control | CommandButton Control | CommandGroup Control | Container Object | Control Object | Custom Object | CursorAdapter Class | EditBox Control | Exception Class | Form Object | FormSet Object | Grid Control | Header Object | Image Control | Label Control | Line Control | ListBox Control | OLE Bound Control | OLE Container Control | OptionButton Control | OptionGroup Control | Page Object | PageFrame Control | ProjectHook Object | ReportListener Object | _SCREEN | Session Object | Shape Control | Spinner Control | TextBox Control | Timer Control | ToolBar Object

Visual FoxPro base class objects are built into the product and have no ClassLibrary setting.

See Also

Other Resources

BaseClass Property
Class Property
Properties
Language Reference


ClipControls Property

Visual FoxPro 9.0 Language Reference
ClipControls Property
See Also

Determines whether graphics methods in Paint events repaint the entire object or only newly exposed areas. Also determines whether the graphical operating environment creates a clipping region that excludes nongraphical controls contained by the object. Available at design time and run time.

Object.ClipControls[ = lExpr]

Return Value

lExpr

The settings for the ClipControls property are:

Setting Description

True (.T.)

(Default) Graphics methods in Paint events repaint the entire object. A clipping region is created around nongraphical controls on a form before a Paint event.

False (.F.)

Graphics methods in Paint events repaint only newly exposed areas. A clipping region is not created around nongraphical controls.

Remarks

Applies To: Form Object | _SCREEN

See Also

Other Resources

Paint Event
DataToClip Method
_CLIPTEXT System Variable
Properties
Language Reference


Closable Property

Visual FoxPro 9.0 Language Reference
Closable Property
See Also Example

Specifies whether the form can be closed by double-clicking the window pop-up menu icon, choosing Close from the window pop-up menu, or by clicking the Close button. Available at design time and run time.

Object.Closable[ = lExpr]

Return Value

lExpr

The settings for the Closable property are:

Setting Description

True (.T.)

(Default) The Close item is added to the window pop-up menu.

False (.F.)

The form cannot be closed by double-clicking the window pop-up menu icon, and the Close item is removed from the window pop-up menu.

Example

Applies To: Form Object | _SCREEN

The following example demonstrates how the Closable property is set to False (.F.) to prevent a form from being closed using the window pop-up menu or the Close button. If the form's Closable property is set to True (.T.) and the form is closed using the window pop-up menu, CLEAR EVENTS must be issued to stop event processing and exit the program.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the window pop-up menu
                          && and Close button

frmMyForm.AddObject('shpLine','Line')  && Add a Line control to the form
frmMyForm.AddObject('cmdCmndBtn1','cmdMyCmndBtn1')  && Up Cmnd button
frmMyForm.AddObject('cmdCmndBtn2','cmdMyCmndBtn2')  && Down Cmnd button
frmMyForm.AddObject('cmdCmndBtn3','cmdMyCmndBtn3')  && Quit Cmnd button

frmMyForm.shpLine.Visible = .T.  && Make Line control visible
frmMyForm.shpLine.Top = 20  && Specify Line control row
frmMyForm.shpLine.Left = 125  && Specify Line control column

frmMyForm.cmdCmndBtn1.Visible =.T.  && Up Command button visible
frmMyForm.cmdCmndBtn2.Visible =.T.  && Down" Command button visible
frmMyForm.cmdCmndBtn3.Visible =.T.  && Quit Command button visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmndBtn1 AS COMMANDBUTTON  && Create Command button
   Caption = 'Slant \<Up'  && Caption on the Command button
   Left = 50  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='/'  && Slant up
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn2 AS CommandButton  && Create Command button
   Caption = 'Slant \<Down'  && Caption on the Command button
   Left = 200  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='\'  && Slant down
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn3 AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 150  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

See Also

Other Resources

ControlBox Property
TitleBar Property
DEFINE CLASS Command
QueryUnload Event
Unload Event
Release Method
Destroy Event
Properties
Language Reference


CLSID Property

Visual FoxPro 9.0 Language Reference
CLSID Property
See Also Example

Contains the registered CLSID (Class Identifier) for a server in a project. Read-only at design time and run time.

Object.CLSID

Remarks

Applies To: Server Object

A CLSID is created in the Windows registry for a server when you build an executable file (.exe) or dynamic link library (.dll) from a project.

Example

The following example demonstrates a use of the CLSID property after creation of a COM server (.dll).

Copy Code
* In a program("Testclass.prg"), create a class
DEFINE CLASS myclass AS SESSION OLEPUBLIC
ENDDEFINE
...

In a project, include the .prg file in a .dll or MTDLL Build. The server object properties are then available by code access. For example, in the Command window, type the following:

Copy Code
MyServer = _VFP.ActiveProject.Servers("myclass")
? "Class ID is ", MyServer.CLSID      && Class ID is {620E56FE-F7F8-4E99-B767-CB08009261F0}
                                    && a GUID
? "Description is ", MyServer.Description    && testclass.myclass

See Also

Other Resources

CREATEOBJECTEX( ) Function
ProgID Property
TypeLibCLSID Property
TypeLibDesc Property
TypeLibName Property
Properties
Language Reference


CodePage Property

Visual FoxPro 9.0 Language Reference
CodePage Property
See Also Example

Specifies the character set used for encoding or decoding an object. For the File object, the property is read-only. For XML objects, the property is read-write at design time and run time.

oXMLAdapter.CodePage = nValue
oXMLTable.CodePage = nValue
oXMLField.CodePage = nNvalue
oFileObject.CodePage

Return Value

oXMLAdapter, oXMLTable, oXMLField

XML objects that support code pages.
oFileObject

Object representing a file in a Visual FoxPro project.
nValue

Numeric value associated with a code page. For XML objects, the default value is zero (0).

Remarks

Applies To: XMLAdapter Class, XMLTable Class, XMLField Class, File Object

A numeric value indicates the character set used for the object. Code pages usually correspond to different platforms and languages and are used in international applications.

When you use the LoadXML or Attach methods to load an XML document, the XMLAdapter object processes the XML to determine the CodePage property. If the XMLAdapter object is unable to determine the code page or the code page is not on the list of supported code pages, the CodePage property is set to zero (0).

For more information on code pages and international support in Visual FoxPro, see Code Pages Supported by Visual FoxPro and Developing International Applications.

Example

This example counts how many project files are using code page 1252 (ANSI Windows).
Copy Code
nCode1252=0
MODIFY PROJECT myproject NOWAIT
FOR i = 1 TO _VFP.ActiveProject.Files.Count
   IF  _VFP.ActiveProject.Files(i).CodePage = 1252
      nCode1252=nCode1252+1
   ENDIF
ENDFOR
?nCode1252    && Show the count in the Visual FoxPro screen.

See Also

Reference

XMLAdapter Class
XMLTable Class
XMLField Class
LoadXML Method

Other Resources

CPCONVERT( ) Function
CPCURRENT( ) Function
CPDBF( ) Function
Properties
Language Reference


ColorSource Property

Visual FoxPro 9.0 Language Reference
ColorSource Property
See Also

Determines how a control's colors are set. Available at design time and run time.

Object.ColorSource[ = nSource]

Return Value

nSource

The settings for nSource are:

Setting Description

0

Object's Color Properties. The control uses its color property settings (ForeColor, BackColor, and so on). This setting is available for the following controls and objects:

CheckBox, ComboBox, CommandButton, CommandGroup, Container, Control, EditBox, Form, Image, Label, Line, ListBox, OptionButton, OptionGroup, Page, PageFrame, Shape, Spinner, TextBox, and Toolbar.

1

Form's Color Scheme. The control uses the color scheme of the form in which it is placed. This setting is available for the following controls and objects:

CheckBox, ComboBox, CommandButton, EditBox, Label, ListBox, OptionButton, Shape, Spinner, and TextBox.

2

ColorScheme Property Scheme. The control uses the color scheme specified in its ColorScheme property. This setting is available for the following controls and objects:

CheckBox, ComboBox, CommandButton, EditBox, Label, ListBox, OptionButton, Shape, Spinner, and TextBox.

3

Default Scheme. The control uses its default color scheme. For most controls, the default color scheme is the form's color scheme; for EditBoxes and ListBoxes, the default color scheme is Scheme 2, User Menus. This setting is available for the following controls and objects:

CheckBox, ComboBox, CommandButton, EditBox, Label, ListBox, OptionButton, Shape, Spinner, and TextBox.

4

Windows Control Panel (3D Colors) (Default). The control uses the 3D color settings specified in the Windows Control Panel. This setting is available for the following controls and objects:

CheckBox, ComboBox, CommandButton, CommandGroup, Container, Control, EditBox, Form, Image, Label, Line, ListBox, OptionButton, OptionGroup, Page, PageFrame, Shape, Spinner, TextBox, and Toolbar.

5

Windows Control Panel (Windows Colors). The control uses the color settings specified in the Windows Control Panel.This setting is available only for the Form object.

Remarks

Applies To: CheckBox Control | ComboBox Control | CommandButton Control | CommandGroup Control | Container Object | Control Object | EditBox Control | Form Object | Image Control | Label Control | Line Control | ListBox Control | OptionButton Control | OptionGroup Control | Page Object | PageFrame Control | Shape Control | Spinner Control | TextBox Control | Toolbar Object

Setting a color property (ForeColor, BackColor, SelectedForeColor, and so on) for an object overrides the ColorSource property setting. If a color property is not set for an object, the object's colors are determined by the ColorSource property setting.

See Also

Other Resources

ColorScheme Property
Properties
Language Reference


ColumnCount Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
ColumnCount Property (Visual FoxPro)
See Also

Specifies the number of Column objects in a Grid, ComboBox, or ListBox control. For a grid, available at design time and read/write at run time. For a combo box or list box, available at design time and run time.

Object.ColumnCount[ = nCol]

Return Value

nCol

For a Grid control, specifies the number of columns to display. The default is –1, which specifies that the Grid control should contain enough columns to accommodate all the fields in the grid's record source. The maximum number of columns is 255. If you create a specific number of columns by setting nCol to a positive value, specify the data to display in a particular column by setting that column's ControlSource property. (If ControlSource is not specified for a column, the Grid control displays the next available undisplayed field of the grid's record source.) For a ComboBox or ListBox control, nCol specifies the number of columns the control contains. If you set ColumnCount to 0, the first column is displayed based on the RowSource property or on the items added with the AddItem method.

Remarks

Applies To: ComboBox Control | Grid Control | ListBox Control

For a grid, use the AddColumn method to increase the number of columns.

See Also

Other Resources

AddColumn Method
ColumnOrder Property
Order Property
Properties
Language Reference


ColumnLines Property

Visual FoxPro 9.0 Language Reference
ColumnLines Property
See Also

Shows or hides the lines between columns. Available at design time and run time.

Control.ColumnLines[ = lExpr]

Return Value

lExpr

Specifies whether lines separating columns are displayed. The settings for the ColumnLines property are:

Setting Description

True (.T.)

(Default) The lines between columns are visible.

False (.F.)

The lines between columns are hidden.

Remarks

Applies To: ComboBox Control | ListBox Control

See Also

Other Resources

ColumnWidths Property
ColumnOrder Property
Columns Property
Properties
Language Reference


ColumnOrder Property

Visual FoxPro 9.0 Language Reference
ColumnOrder Property
See Also

Specifies the relative order of column objects in a Grid control. Available at design time and run time.

Column.ColumnOrder[ = nExpr]

Return Value

nExpr

Specifies the order of a column relative to other columns in the grid.

Remarks

Applies To: Column Object

If a Grid contains five columns and you want the third column displayed last, set the ColumnOrder property of the third column to 5. The ColumnOrder setting for the fourth column becomes 3, the ColumnOrder setting for the fifth column becomes 4, and so on.

Note:
ColumnOrder settings do not have to be sequential.

See Also

Other Resources

Activate Event
Deactivate Event
ZOrder Method
ColumnCount Property
ColumnLines Property
ColumnWidths Property
Properties
Language Reference


Columns Property

Visual FoxPro 9.0 Language Reference
Columns Property
See Also

An array for accessing individual Column objects in the Grid control by column number. Available at design time and read-only at run time.

Grid.Columns(nCol).Property [ = Setting]

Return Value

nCol

Specifies the column in agGrid whose property is referenced. The far left Column is number 1.
Property

Specifies the column's property to access.
Setting

Specifies the new property setting for all cells specified with nCol.

Remarks

Applies To: Grid Control

Use the Columns property to access the properties of a particular Column in a Grid. For example, SpecialGrid.Columns(1).BackColor = RGB(255,0,0) changes the BackColor property of all the cells in Column 1 to bright red.

See Also

Other Resources

Column Object
ColumnCount Property
SetAll Method
Properties
Language Reference


ColumnWidths Property

Visual FoxPro 9.0 Language Reference
ColumnWidths Property
See Also

Specifies the width of columns for a ComboBox or ListBox control. Available at design time and run time.

Control.ColumnWidths[ = "cCol1Width, cCol2Width, ... cColnWidth"]

Return Value

" cCol1Width, cCol2Width, ...cColnWidth"

Specifies the width of a column or series of columns in the ComboBox or ListBox. For example, cColumnWidths = "5, 7, 9" specifies that the first column is 5 units wide, the second column is 7 units wide, and the third column is 9 units wide, in the unit of measurement specified by the ScaleMode property of the form. Use commas to separate each width number. You can specify the number of columns with the ColumnCount property.

Remarks

Applies To: ComboBox Control | ListBox Control

See Also

Other Resources

ColumnCount Property
ScaleMode Property
Width Property
ColumnLines Property
Properties
Language Reference


CommandClauses Property

Visual FoxPro 9.0
CommandClauses Property
See Also Example

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.
Copy Code
IF EMPTY(THIS.PrintJobName)
   cName = PROPER(JUSTFNAME(THIS.CommandClauses.FILE))
ELSE
   cName = THIS.PrintJobName
ENDIF
THIS.ThermForm.Caption = ;
   cName + ": " + OUTPUTCLASS_CANCEL_INSTRUCTIONS_LOC

See Also

Reference

ReportListener Object Properties, Methods, and Events
REPORT FORM Command
Empty Class

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)
Extending Report Output Functionality


Comment Property

Visual FoxPro 9.0 Language Reference
Comment Property
See Also

Stores information about an object. Available at design time and run time.

Object.Comment[ = cTextString]

Return Value

cTextString

Specifies a text string.

Remarks

Applies To: CheckBox Control | Collection Class | ComboBox Control | CommandButton Control | CommandGroup Control | Container Object | Control Object | CursorAdapter Class | Custom Object | EditBox Control | Exception Class | Form Object | FormSet Object | Grid Control | Image Control | Label Control | Line Control | ListBox Control | OLE Bound Control | OLE Container Control | OptionButton Control | OptionGroup Control | Page Object | PageFrame Control | ProjectHook Object | ReportListener Object | _SCREEN | Session Object | Shape Control | Spinner Control | TextBox Control | Timer Control | ToolBar Object

Unlike other properties, the value of the Comment property is not used by Visual FoxPro; you can use this property to identify or describe objects.

You can use this property to assign an identification string to an object without affecting any of its other property settings. The Comment property is useful for checking the identity of a control or form that is passed as a variable to a procedure.

By default, the Comment property is set to a zero-length string ("").

Tip:
When you create a new instance of a form, assign a unique value to the Comment property.

See Also

Other Resources

Caption Property
Name Property
Properties
Language Reference


CompareMemo Property

Visual FoxPro 9.0 Language Reference
CompareMemo Property
See Also

Specifies whether memo fields of type Memo, General, or Picture are included in the WHERE clause when using automatic updating. When working with this property for regular cursors, use the CURSORSETPROP() and CURSORGETPROP() functions. Read/write.

Note:
Setting CompareMemo for CursorAdapter objects overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

CursorAdapter.CompareMemo [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

True (.T.)

Includes memo fields in the WHERE clause.

True (.F.)

Does not include memo fields in the WHERE clause.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


ConflictCheckCmd Property

Visual FoxPro 9.0 Language Reference
ConflictCheckCmd Property
See Also

Specifies a custom command to use for checking update or delete conflicts when CursorAdapter ConflictCheckType is set to 4. Read/write at design time and run time.

You can use ConflictCheckCmd with native, Open Database Connectivity (ODBC), and ActiveX Object (ADO) data sources. When using ADO, the CursorAdapter object should use an ADO Command object for the SQL UPDATE or DELETE operation. Otherwise, Visual FoxPro disregards ConflictCheckCmd.

CursorAdapter.ConflictCheckCmd [= cValue]

Parameters

cValue

Specifies a custom command string reference to append to the commands specified by the UpdateCmd and DeleteCmd properties for checking update or delete conflicts. The default value for cValue contains an empty string.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
ConflictCheckType Property
CursorAdapter Object Properties, Methods, and Events
UPDATE - SQL Command
DELETE - SQL Command


ConflictCheckType Property

Visual FoxPro 9.0 Language Reference
ConflictCheckType Property
See Also

Specifies how to handle conflict checking during an update or delete operation using commands specified by the CursorAdapter UpdateCmd and DeleteCmd properties. Read-write at design time and run time.

You can use ConflictCheckType with native, Open Database Connectivity (ODBC), and ActiveX Object (ADO) data sources. When using ADO, the CursorAdapter object should use an ADO Command object for the SQL UPDATE or DELETE operation. Otherwise, Visual FoxPro disregards ConflictCheckType.

CursorAdapter.ConflictCheckType [= nValue]

Return Value

nValue

Specifies a number that determines how to handle conflict checking. The following table lists the values for nValue.

nValue Description

0

Do not perform checks. (Default)

1

In single row update mode, check for update conflicts during a SQL UPDATE or DELETE operation. If conflict occurs, specifically, no record is affected by any command specified by the UpdateCmd or DeleteCmd property, return message "Update conflict (Error 1585)".

2

In single row update mode, check for key uniqueness during a SQL UPDATE or DELETE operation. If more than one record is affected by any command specified by the UpdateCmd or DeleteCmd property, return message "Warning: The key defined by the KeyField property for table "alias" is not unique. (Error 1495)"

3

Perform checks as specified by settings 1 and 2.

4

Append custom command specified in ConflictCheckCmd property to the end of the command in the UpdateCmd and DeleteCmd properties.
Note:
Due to ODBC and ADO limitations, settings 1, 2, and 3 might not work correctly if the UpdateCmd and DeleteCmd properties contain more than one command. It is possible that the number of affected rows is not returned for every command in a batch. Therefore, it is recommended that you set ConflictCheckType to 4 and specify a custom command in the ConflictCheckCmd property or make sure that only one SQL UPDATE or DELETE command will be executed. Also, Visual FoxPro disregards settings 1, 2, and 3 when performing a batched TABLEUPDATE( ) operation.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
ConflictCheckCmd Property
UpdateCmd Property
DeleteCmd Property
CursorAdapter Object Properties, Methods, and Events
UPDATE - SQL Command
DELETE - SQL Command
TABLEUPDATE( ) Function


ContinuousScroll Property

Visual FoxPro 9.0 Language Reference
ContinuousScroll Property
See Also

Specifies if scrolling within a form is continuous, or if scrolling occurs only when a scroll box is released. Available at design time and run time.

Object.ContinuousScroll[ = lExpression]

Return Value

lExpression

The settings for lExpression are:

Setting Description

True (.T.)

(Default) Scrolling is continuous within the form. The form scrolls continuously as the scroll boxes are moved. The Scrolled event occurs continuously as the form is scrolled.

False (.F.)

Scrolling only occurs when a scroll box is released. The form is stationary until a scroll box is released, and then the form is redrawn in its new position. The Scrolled event occurs after the form is redrawn.

Remarks

Applies To: Form Object

The Scrollbars property determines if a form has scroll bars.

See Also

Other Resources

ScrollBars Property
Scrolled Event
HScrollSmallChange Property
Properties
Language Reference


ControlBox Property

Visual FoxPro 9.0 Language Reference
ControlBox Property
See Also

Specifies whether a program icon appears in the upper-left corner and whether Minimize, Maximize, Restore, and Close buttons appear in the upper-right corner of a form. In the case of Toolbars the ControlBox Property controls the appearance of only the Close button. Available at design time and run time.

Object.ControlBox[ = lExpr]

Return Value

lExpr

The settings for the ControlBox property are:

Setting Description

True (.T.)

(Default) Displays a program icon.

False (.F.)

Does not display a program icon.

Remarks

Applies To: Form Object | _SCREEN | ToolBar Object

Both modal and modeless forms and toolbars can include a program icon. The menu commands available at run time depend on the settings for related properties. For example, setting MaxButton and MinButton to False (.F.) disables the Maximize and Minimize menu commands on the program icon, but the Move and Close menu commands remain available.

See Also

Other Resources

BorderStyle Property
Closable Property
MaxButton Property
MinButton Property
Properties
Language Reference


ControlCount Property

Visual FoxPro 9.0 Language Reference
ControlCount Property
See Also

Specifies the number of controls in a container object. Not available at design time; read-only at run time.

Object.ControlCount

Remarks

Applies To: Column Object | Container Object | Control Object | Form Object | Page Object | _SCREEN | ToolBar Object

You can use this property to cycle through all the controls on a container and perform an operation on each.

See Also

Other Resources

Controls Property
Properties
Language Reference


Controls Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Controls Property (Visual FoxPro)
See Also

An array for accessing the controls in a container object. Available at run time.

ContainerObject.Controls(Index).Property[ = Expr]

Return Value

Expr

Specifies a property value for a control contained in ContainerObject.

Remarks

Applies To: Column Object | Container Object | Control Object | Form Object | Page Object | _SCREEN | ToolBar Object

Use the Controls property to access the properties of contained objects.

See Also

Other Resources

ControlCount Property
Properties
Language Reference


ControlSource Property

Visual FoxPro 9.0 Language Reference
ControlSource Property
See Also

Specifies the source of data to which an object is bound. Available at design time and run time.

Object.ControlSource[ = cName]

Return Value

cName

For controls, cName is a variable or field.

Remarks

Applies To: CheckBox Control | Column Object | ComboBox Control | CommandGroup Control | EditBox Control | ListBox Control | OLE Bound Control | OptionButton Control | OptionGroup Control | Spinner Control | TextBox Control

Once the ControlSource property is set to a field or variable, the Value property always has the same data value and the same data type as the variable or field to which the ControlSource property is set.

For TextBox controls, cName is typically a field.

In a Grid control, if you do not specify a ControlSource setting for a column, the column displays the next available undisplayed field of the grid's record source.

If a Column's Bound property is set to True (.T.), the Column's ControlSource property setting applies to the column and any controls contained in it. If you attempt to set the contained control's ControlSource property, an error occurs. If a Column's Bound property is set to False (.F.), you can set the ControlSource property of a contained control directly. If you subsequently set the ControlSource setting of the Column, it overrides the ControlSource setting of the contained control.

See Also

Other Resources

Bound Property
Order Property
RecordSourceType Property
Value Property
Properties
Language Reference


ConversionFunc Property

Visual FoxPro 9.0 Language Reference
ConversionFunc Property
See Also

Specifies a comma-delimited list of field and function name pairs separated by single spaces. Read/write at design time and run time.

Note:
ConversionFunc applies only when using automatic updating. ConversionFunc is not evaluated at design time.

Use ConversionFunc to specify native Visual FoxPro or custom conversion functions that are applied to one or more cursor fields before sending them to the data source through an update, insert, or delete operation. The actual values sent to the data source are the values returned by the function associated with each field.

CursorAdapter.ConversionFunc [ = 'cFieldName1 cFuncName1 [, cFieldName2 cFuncName2 ]...' ]

Return Value

cFieldName

Specifies a field name.
cFuncName

Specifies a function name that accepts a field value as the first parameter. The specified function or method must accept the associated field name as the sole parameter.
Note:
Do not include parentheses at the end of the function or method name.

Remarks

Applies To: CursorAdapter Class

If the local cursor contains character fields that are used as part of the WHERE clause for an automatically generated update command, the data source might require that the trailing spaces be removed to obtain a proper match at the data source. The following example illustrates how to remove such spaces:

Copy Code
CursorAdapter.ConversionFunc = "companyname TRIM, contactname TRIM"

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


Count Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Count Property (Visual FoxPro)
See Also

Contains the number of items in a collection, for example, project , file, or server objects in a project, file, or server collection. Read-only at design time and run time.

Object.Count

Return Value

Numeric

Remarks

Applies To: Files Collection | Projects Collection | Servers Collection | Collection Class

For a projects collection, the Count property contains zero if no instances of the Project Manager exist. For a file or server collection, the Count property contains zero if no files or servers exist in the file or server collection.

You can use the Count property to access the number of items in a collection. However, you cannot manually change Count except by using the Add and Remove methods of the collection. Collection objects provide their own Add and Remove methods.

You should use Count to determine the number of items in a collection when iterating through items in the collection using FOR...ENDFOR or referencing individual items with the Item method.

Count supports the Access method. Since Count is read-only, it does not support the Assign method.

See Also

Other Resources

Item Method (File Object)
Add Method (File Object)
Remove Method (File Object)
Item Method (Collection Class)
Add Method (Collection Class)
Remove Method (Collection Class)
FOR ... ENDFOR Command
Access and Assign Methods
Properties
Language Reference


CurrentControl Property

Visual FoxPro 9.0 Language Reference
CurrentControl Property
See Also

Specifies which control contained in a Column object is used to display the values of the active cell. Available at design time; read/write at run time.

Column.CurrentControl[ = cName]

Return Value

cName

Specifies the name of the control that displays and accepts data for the active cell in a Column object.

Remarks

Applies To: Column Object

The default control is a TextBox having Text1 as the Name property. Use the AddObject method to add other controls.

If the Column's Sparse property is set to true (.T.), only the active cell in the Column uses the object specified in the CurrentControl property; the other cells display data using a TextBox. If the Sparse property is set to false (.F.), all cells in the Column use the CurrentControl property to display data.

Note:
You can add an unlimited number of controls to a Column object using the AddObject method. However, you can set the CurrentControl property for only one control at any given time.

See Also

Other Resources

AddObject Method
Bound Property
RemoveObject Method
Sparse Property
Properties
Language Reference


CurrentDataSession Property

Visual FoxPro 9.0
CurrentDataSession Property
See Also

Provides the ReportListener with the datasession ID of a report’s data during the execution of a LABEL or REPORT FORM command. This datasession may be a private datasession, opened by the Report Engine for the report run, or a datasession shared with the form or application that issued the command.

ReportListener.CurrentDataSession

Return Value

Integer data type.

The default value is 1 (the ID of the default datasession).

Remarks

Applies To: ReportListener Object.

If the report opens its data in a private datasession, the Report Engine creates this session after the LoadReport event and before the BeforeReport event. The private datasession closes before the UnloadReport event.

For information about when the native Report System components assigns this value and other reporting attributes at the beginning and end of a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

See Also

Tasks

How to: Specify a Report's Data Session

Reference

ReportListener Object Properties, Methods, and Events
SET DATASESSION Command

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


CurrentPass Property

Visual FoxPro 9.0
CurrentPass Property
See Also

Specifies the current pass through a report's data and rendering functions, during a report run that requires multiple passes through the data scope to produce output, such as a report with _PAGETOTAL.

ReportListener.CurrentPass

Property Value/Return Value

Integer data type.

Remarks

Applies To: ReportListener Object.

The ReportListener evaluates the TwoPassProcess property value after the BeforeReport event. Based on this result, it sets the CurrentPass property according to the values in the table below. As a result, the value of both these properties provide useful information starting at the next ReportListener event (BeforeBand).

CurrentPass also provides information when a LABEL or REPORT FORM command concludes. The value of this property is not cleared after a report run, so you can check it after the run, to find out whether the report ran in one or two passes. In contrast, TwoPassProcess is re-set to .F. after a report run, so the ReportListener can recognize a .T. value in the next run as your explicit instructions.

For information about when the native Report System components assign this value and other reporting attributes at the beginning and end of a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

The following table lists the possible values of the CurrentPass property.

Setting | Description
0 | Default value when ReportListener object instance is created. Value during calculation pass, or prepass, when the ReportListener is running a report requiring multiple passes through the data scope (TwoPassProcess = .T.). Value during entire report run, and at the conclusion of the report run, when TwoPassProcess is .F..
1 | Value during second, output pass, and value at conclusion of report run, when TwoPassProcess is .T..

See Also

Reference

TwoPassProcess Property

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


CurrentX, CurrentY Properties

Visual FoxPro 9.0 Language Reference
CurrentX, CurrentY Properties
See Also

Specifies the horizontal (X) and vertical (Y) coordinates for the next drawing method. Not available at design time; read/write at run time.

Object.CurrentX[ = nXCoord]
Object.CurrentY[ = nYCoord]

Return Value

nXCoord

Specifies the horizontal coordinate of the form, in the unit of measurement specified by the ScaleMode property of the form.
nYCoord

Specifies the vertical coordinate of the form, in the unit of measurement specified by the ScaleMode property of the form.

Coordinates are measured from the upper-left corner of an object. CurrentX is 0 at an object's left edge and CurrentY is 0 at its top edge. Coordinates are expressed in foxels or the current unit of measurement defined by the ScaleMode property.

When you use the following graphics methods, the CurrentX and CurrentY settings are changed as indicated.

Method | CurrentX, CurrentY set to
Box | The endpoint of the box as specified by the last two arguments.
Circle | The center of the object.
Cls | 0, 0.
Line | The endpoint of the line.
Print | The next print position.
Pset | The point drawn.

Remarks

Applies To: Form Object | _SCREEN

See Also

Other Resources

Box Method
Circle Method
Cls Method
DrawMode Property
DrawStyle Property
Left Property
Line Method
PSet Method
ScaleMode Property
SYS(1270) - Object Location
Top Property
Properties
Language Reference


CursorSchema Property

Visual FoxPro 9.0 Language Reference
CursorSchema Property
See Also

Specifies the structure of the cursor associated with a CursorAdapter object. Read/write at design time and run time.

CursorSchema is essentially the portion "between the parentheses" of the SQL CREATE TABLE and CREATE CURSOR commands. In Visual FoxPro 8.0, you can use CursorSchema to define an XML data source. In Visual FoxPro 9.0, you can use CursorSchema to define XML, Native, ADO and ODBC data sources.

Note:
In Visual FoxPro 9.0, DEFAULT values and table and field level CHECK constraints are supported for XML, Native, ADO and ODBC data sources. In Visual FoxPro 8.0, DEFAULT values and table and field level CHECK constraints are only supported for an XML data source. For the DEFAULT values and CHECK constraints to be applied to a cursor, call the CursorFill method with the lUseSchema parameter set to True (.T.).

Visual FoxPro uses the CursorSchema property at design time to determine the structure of the cursor to place on the surface of the Data Environment Designer. Visual FoxPro uses CursorSchema at run time if specified by the CursorFill method.

Note:
You must make sure that CursorSchema matches and maps to the data source columns in an acceptable manner.

CursorAdapter.CursorSchema [ = cList ]

Return Value

cList

Character data type. The cList parameter specifies a character string or expression that evaluates to a valid comma-delimited list of field names and types. For example:
Copy Code
CursorAdapter.CursorSchema = ;
"col1 I, col2 Character(25), col3 M, col4 Currency, col5 n(12,3)"
See the CREATE CURSOR - SQL Command for a list of field names and types. If CursorSchema is empty or set to null (.NULL.), Visual FoxPro uses the data source of the CursorAdapter object to determine the cursor structure.

Remarks

Applies To: CursorAdapter Class

When the lUseCursorSchema parameter in the CursorFill method evaluates to True (.T.), or when you add a CursorAdapter-based cursor to the surface of the Data Environment Designer, a CursorAdapter object uses CursorSchema as a template for the cursor created by CursorFill.

For ADO data sources, CursorSchema supports mapping from ADO types to Visual FoxPro data types. For more information, see Data Type Conversion Control.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CursorFill Method


CursorSource Property

Visual FoxPro 9.0 Language Reference
CursorSource Property
See Also

Specifies the name of the table or view associated with a Cursor object. Read-only at design time; read/write at run time.

DataEnvironment.Cursor.CursorSource[ = cText]

Return Value

cText

For views, specifies the name of the view in a database. For tables in a database, specifies the long table name. For free tables, specifies the full path to the free table.

Remarks

Applies To: Cursor Object

See Also

Other Resources

Database Property
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function
Properties
Language Reference


CursorStatus Property

Visual FoxPro 9.0 Language Reference
CursorStatus Property
See Also

Specifies whether the CursorAdapter object represented by the CursorAdapter Alias property is attached and how it is attached. Visual FoxPro requires CursorStatus to determine state of the current CursorAdapter object and from where the associated cursor originated. Read-only.

CursorAdapter.CursorStatus [ = nValue ]

Return Value

nValue

Numeric data type. The following table lists the possible values for nValue.

nValue Description

0

CursorAdapter <Alias> is not attached. (Default)

1

CursorAdapter <Alias> is attached via the CursorFill method.

2

CursorAdapter <Alias> is attached via the CursorAttach method.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
Alias Property
CursorFill Method
CursorAttach Method


Curvature Property

Visual FoxPro 9.0 Language Reference
Curvature Property
See Also Example

Specifies the curvature of a Shape control's corners. Available at design time and run time.

Shape.Curvature[ = nCurve]

Return Value

nCurve

The settings for the Curvature property are:

Setting Description

0

Specifies no curvature, creating square corners.

1 through 98

Specifies progressively rounded corners. A higher number increases the curvature.

99

Specifies maximum curvature and creates a circle or ellipse.

Remarks

Applies To: Shape Control

Example

The following example demonstrates how the Curvature property can be used with the Shape control to display a circle, ellipse, or square on a form.

A form is created, and a set of option buttons and a command button are placed on the form. When you click one of the option buttons, the corresponding shape is displayed on the form. The Height, Width, and Curvature properties of each shape determine the type of shape (circle, ellipse, or square) created. The Curvature property is set to 99 to create the circle and ellipse.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('cmdCommand1','cmdMyCmndBtn')  && Add Command button
frmMyForm.AddObject('opgOptionGroup1','opgMyOptGrp') && Add Option Group
frmMyForm.AddObject('shpCircle1','shpMyCircle')  && Add Circle Shape
frmMyForm.AddObject('shpEllipse1','shpMyEllipse')  && Add Ellipse Shape
frmMyForm.AddObject('shpSquare','shpMySquare')  && Add Box Shape

frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible

frmMyForm.opgOptionGroup1.Buttons(1).Caption = "\<Circle"
frmMyForm.opgOptionGroup1.Buttons(2).Caption = "\<Ellipse"
frmMyForm.opgOptionGroup1.Buttons(3).Caption = "\<Square"
frmMyForm.opgOptionGroup1.SetAll("Width", 100) && Set Option group width
frmMyForm.opgOptionGroup1.Visible = .T.  && Option Group visible
frmMyForm.opgOptionGroup1.Click  && Show the circle

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS opgMyOptGrp AS OptionGroup  && Create an Option Group
   ButtonCount = 3  && Three Option buttons
   Top = 10
   Left = 10
   Height = 75
   Width = 100

   PROCEDURE Click
      ThisForm.shpCircle1.Visible = .F.  && Hide the circle
      ThisForm.shpEllipse1.Visible = .F.  && Hide the ellipse
      ThisForm.shpSquare.Visible = .F.  && Hide the square

      DO CASE
         CASE ThisForm.opgOptionGroup1.Value = 1
            ThisForm.shpCircle1.Visible = .T. && Show the circle
         CASE ThisForm.opgOptionGroup1.Value = 2
            ThisForm.shpEllipse1.Visible = .T.  && Show the ellipse
         CASE ThisForm.opgOptionGroup1.Value = 3
            ThisForm.shpSquare.Visible = .T.  && Show the square
      ENDCASE
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

DEFINE CLASS shpMyCircle AS SHAPE  && Create a circle
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 99
   BackColor = RGB(255,0,0)  && Red
ENDDEFINE

DEFINE CLASS shpMyEllipse AS SHAPE  && Create an ellipse
   Top = 35
   Left = 200
   Width = 100
   Height = 50
   Curvature = 99
   BackColor = RGB(0,128,0)  && Green
ENDDEFINE

DEFINE CLASS shpMySquare AS SHAPE  && Create a square
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 0
   BackColor = RGB(0,0,255)  && Blue
ENDDEFINE

See Also

Other Resources

DEFINE CLASS Command
DO CASE ... ENDCASE Command
Shape Control Properties, Methods and Events
Properties
Language Reference


Database Property

Visual FoxPro 9.0 Language Reference
Database Property
See Also

Specifies the path to the database that contains the table or view associated with a cursor or CursorAdapter. Read-only at design time; read/write at run time.

Note:
When you access a regular cursor using the CURSORSETPROP() function, the Database property is read-only at run time.

DataEnvironment.Cursor.Database [ = cPath ]

Return Value

cPath

Specifies the full path to the database (.dbc) file.

Remarks

Applies To: Cursor Object

If the cursor is based on a free table, Database contains an empty string ("").

See Also

Other Resources

CursorSource Property
CURSORSETPROP( ) Function
Database Manipulation
Properties
Language Reference


DataEnvironment Property

Visual FoxPro 9.0 Language Reference
DataEnvironment Property
See Also

Provides a reference to the object's data environment. Read-only at design time and run time.

Object.DataEnvironment

Remarks

Applies To: Form Object | FormSet

See Also

Other Resources

DataEnvironment Object
DataEnvironment Object Properties, Methods and Events
Properties
Language Reference


DataSession Property

Visual FoxPro 9.0 Language Reference
DataSession Property
See Also

Specifies whether an object can run in its own data session with a unique data environment. Available at design time; read-only at run time.

Object.DataSession[ = nSession]

Return Value

nSession

Specifies a numeric value for the DataSession property. The following table lists the values for nSession.

Setting Description

1

Default data session. (Default except for Session objects)

2

Private data session. Creates a new data session for each instance that is created. (Default for Session objects.)

Remarks

Applies To: Form Object | FormSet Object | _SCREEN | Session Object | ToolBar Object

See Also

Other Resources

DataSessionID Property
SET DATASESSION Command
Properties
Language Reference


DataSessionID Property

Visual FoxPro 9.0 Language Reference
DataSessionID Property
See Also

Returns the data session ID that identifies the private data session for the object. Read-only at design time; read/write at run time.

If the DataSession property of the object is set to 1 (Default Data Session), returns the default data session ID.

Object.DataSessionID

Remarks

Applies To: Form Object | FormSet Object | _SCREEN | Session Object | ToolBar Object

Available only if the DataSession property of the object is set to 2 (Private data session).

You can use SET DATASESSION with the DataSessionID property to change data sessions.

When you set DataSessionID, the setting affects the working data session for the object. The DataSessionID property setting does not affect objects you create by using CREATEOBJECT( ).

Changing the DataSessionID property setting increments the reference count of the data session changed to and decrements the reference count of the data session changed from. However, if you create a data session by setting the DataSession property to 2 (Private data session), changing the DataSessionID property setting does not release the initial data session. In such case, the object must be released to free the initial session.

For more information on multiple data sessions, see Programming for Shared Access.

Caution:
Changing the DataSessionID property setting of an object that contains data-bound controls causes the controls to lose their original data sources. In general, use DataSessionID on objects that do not contain data-bound controls.

See Also

Other Resources

CREATEOBJECT( ) Function
DataSession Property
SET DATASESSION Command
Properties
Language Reference


DataSource Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
DataSource Property (Visual FoxPro)
See Also

Specifies the data source for DataEnvironment and CursorAdapter objects to use. The DataEnvironment or CursorAdapterDataSourceType property determines the value of the corresponding DataSource property. Read/write at design time and run time. There are two versions of the syntax.

DataEnvironment.DataSource [= DataSource]
CursorAdapter.DataSource [= DataSource]

Return Value

DataSource

Specifies a reference to an existing data source of permissible data source types. DataSource acts only as a pointer to the actual data source, which must exist at run time. The following table lists the values for DataSource, which depend on the value of the DataSourceType property.

DataSource DataSourceType

Reference to a valid ActiveX Data Object (ADO) RecordSet object

"ADO"

Positive integer that represents or memory variable that contains a valid Open Database Connectivity (ODBC) connection handle

"ODBC"

Disregarded.

"Native", "XML", null (.NULL.), or empty string ("")

Remarks

Applies To: CursorAdapter Class | DataEnvironment Object

When the CursorAdapterDataSourceType is "Native", specifying CursorAdapterDataSource is not required because the cursor returned by the CursorAdapter SelectCmd property is the default data source. The name of the cursor returned is determined by the CursorAdapterAlias property, which is set by the CursorAdapterCursorFill method.

If the CursorAdapter InsertCmdDataSourceType, UpdateCmdDataSourceType, and DeleteCmdDataSourceType properties are empty, the CursorAdapterDataSource property overrides the CursorAdapter InsertCmdDataSource, UpdateCmdDataSource, and DeleteCmdDataSource properties.

If the CursorAdapterUseDeDataSource property is True (.T.), the DataEnvironmentDataSource and DataSourceType properties override the same CursorAdapter properties.

See Also

Other Resources

Properties
DataEnvironment Object Properties, Methods and Events
CursorAdapter Object Properties, Methods, and Events
DEClass Property
DataSourceType Property


DataSourceType Property

Visual FoxPro 9.0 Language Reference
DataSourceType Property
See Also

Specifies the data source type of the data source in the DataEnvironment or CursorAdapter DataSource property. The DataEnvironment or CursorAdapter DataSourceType property determines the value of the corresponding DataSource property. Read-only at design time and read/write at run time. There are two versions of the syntax.

DataEnvironment.DataSourceType [= cDataSourceType]
CursorAdapter.DataSourceType [= cDataSourceType]

Return Value

cDataSourceType

Character data type. The cDataSourceType parameter specifies a character string describing the data source type of the data source used by the data environment or cursor adapter. The following table lists the values for cDataSourceType.

DataSourceType DataSource

"ADO"

Reference to a valid ActiveX Data Object (ADO) RecordSet or Command object

"ODBC"

A valid Open Database Connectivity (ODBC) connection handle

"Native", "XML", null (.NULL.), or empty string ("")

Disregarded

Remarks

Applies To: CursorAdapter Class | DataEnvironment Object

You cannot use local and remote views as a "Native" source for CursorAdapter objects, but you can attach them using the CursorAttach method.

The DataEnvironment DataSourceType is not specified at design time when the data environment does not specify a data source.

See Also

Other Resources

Properties
DataEnvironment Object Properties, Methods and Events
CursorAdapter Object Properties, Methods, and Events
DEClass Property
DataSource Property
CursorAttach Method


DataType Property

Visual FoxPro 9.0 Language Reference
DataType Property
See Also

Specifies the Visual FoxPro data type for the field in the XML document.

XMLField.DataType

Return Value

Character data type (C(1)). The DataType property contains the name of a Visual FoxPro data type for the XMLField object.

Remarks

Applies To: XMLField Class

When DataType is set to the Blob or Varbinary type, the XMLField IsBinary and NoCpTrans properties are set to True (.T.) automatically and the XMLField DisableEncode property is set to False (.F.). Changes to these properties cannot be made when XMLField DataType is set to Blob or Varbinary.

For more information about Visual FoxPro and XML data type mapping, see Visual FoxPro and XML Schema Data Type Mapping.

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events


DateFormat Property

Visual FoxPro 9.0 Language Reference
DateFormat Property
See Also

Specifies the format for Date and DateTime values displayed in a text box. Available at design time and run time.

Object.DateFormat[ = nValue]

Return Value

nValue

One of the following settings:

Setting Description Format

0

(Default) The displayed date format is determined by the setting of SET DATE.

Determined bySET DATE

1

American

mm/dd/yy

2

ANSI

yy.mm.dd

3

British

dd/mm/yy

4

Italian

dd-mm-yy

5

French

dd/mm/yy

6

German

dd.mm.yy

7

Japan

yy/mm/dd

8

Taiwan

yy/mm/dd

9

USA

mm-dd-yy

10

MDY

mm/dd/yy

11

DMY

dd/mm/yy

12

YMD

yy/mm/dd

13

Short

Determined by the Windows Control Panel short date setting

14

Long

Determined by the Windows Control Panel long date setting

Remarks

Applies To: TextBox Control

A Date or DateTime value displayed in a text box may be displayed in a different format when the text box does not have the focus. Certain short and long date formats that you can specify in the Windows Control Panel do not correspond to valid Visual FoxPro formats, and are displayed in a default format.

The Format property overrides the DateFormat property when the YS, YL, E, or D settings are specified for the Format property.

See Also

Other Resources

Century Property
DateMark Property
Hours Property
Seconds Property
SET DATE Command
StrictDateEntry Property
Properties
Language Reference


DateMark Property

Visual FoxPro 9.0 Language Reference
DateMark Property
See Also

Specifies the delimiter for Date and DateTime values displayed in a text box. Available at design time and run time.

Object.DateMark[ = cDateMarkCharacter]

Return Value

cDateMarkCharacter

Specifies the Date and DateTime value delimiter. If cDateMarkCharacter is the empty string, the delimiter is determined by the setting of SET MARK. If cDateMarkCharacter is a space, the delimiter for the current setting of the text box's DateFormat property is used. In the Properties window, use the = command to specify the empty string (= "") or a space (= " ") for the DateMark property.

Remarks

Applies To: TextBox Control

The DateMark property setting is ignored if the DateFormat property is set to Short or Long.

See Also

Other Resources

Century Property
DateFormat Property
Hours Property
Seconds Property
SET MARK TO Command
StrictDateEntry Property
Properties
Language Reference


Debug Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Debug Property (Visual FoxPro)
See Also

Specifies if debugging information is included with compiled source code in a project.

Object.Debug[ = lExpression]

Return Value

lExpression

The settings for the Debug property are:

Setting Description

True (.T.)

(Default) Debugging information is included with the compiled source code.

False (.F.)

Debugging information is not included and you cannot view a program's execution in the Trace window or use MESSAGE(1) to return the source code for a line that causes an error. Setting lExpression to false (.F.) is identical to including the NODEBUG argument in the COMPILE Command.

Remarks

Applies To: Project Object

Source code in a project includes program and format files, source code in form, label, report, and visual class libraries, and stored procedures in databases. The Debug property corresponds to the Debuginfo check box on the Project tab of the Project Information dialog box.

See Also

Other Resources

COMPILE Command
Project Information Dialog Box
Properties
Language Reference


DeclareXMLPrefix Property

Visual FoxPro 9.0
DeclareXMLPrefix Property
See Also

Specifies whether the XMLAdapter object declares an XMLPrefix for the object involved in parsing. Read-write at design time and run time.

XMLAdapter.DeclareXMLPrefix = lValue

Return Value

lValue

Logical data type. The following table lists values for lValue.

lValue Description

False (.F.)

(Default) An XML namespace prefix property is not declared.

True (.T.)

An XMLPrefix is declared for the object.

Remarks

Applies to: XMLTable Class | XMLTable Class

If you want the XMLAdapter object to declare prefixes for objects involved in parsing, set the DeclareXMLPrefix property in addition to XMLNamespace property and XMLPrefix property. If RespectNesting is True (.T.), the following objects are involved in parsing: the XMLAdapter object, the target XMLTable object and its ancestors.

If either the XMLNamespace property or the XMLPrefix property is empty, the DeclareXMLPrefix property is ignored.

If you want to declare a namespace for all of the parsing operations, specify an XMLNamespace with an XMLPrefix in the SelectionNamespaces property.

See Also

Reference

XMLNamespace Property
XMLPrefix Property
SelectionNamespaces Property

Other Resources

Properties


DEClass Property

Visual FoxPro 9.0 Language Reference
DEClass Property
See Also Example

Specifies the name of the DataEnvironment class to use when adding a data environment to a form. Read/write at design time and read-only at run time.

At design time, DEClass makes it possible for you to specify a DataEnvironment class from the class library in the DEClassLibrary property.

Form.DEClass [= cClassName]

Return Value

cClassName

Character data type. The cClassName parameter specifies one of the following:
  • Name of a programmatic class in a program (.prg) file

  • Name of a non-visual class in a visual class library (.vcx) file

Remarks

Applies To: Form Object

Visual FoxPro supports DEClass and DEClassLibrary for form (.scx), visual class library (.vcx), and program (.prg) files but not for FormSet objects or in the Report Designer.

Visual FoxPro instantiates a DataEnvironment object from DEClass and its associated DEClassLibrary property under the following conditions:

  • DEClass specifies a DataEnvironment class at design time in the Properties window for the form.

  • DEClass specifies a DataEnvironment class when programmatically creating the form.

When the form is created, Visual FoxPro uses the specified DataEnvironment class to create the DataEnvironment object. If you specify a value for the DEClassLibrary property but not for DEClass, or if the DataEnvironment class is the wrong type or does not exist in the class library specified, Visual FoxPro generates the appropriate message.

You can set DEClass and DEClassLibrary using the Properties window in the Form Designer, in a Form class, or from a class definition in a .prg file. Visual FoxPro displays DEClass and DEClassLibrary in the Properties window as read-only. However, clicking the ellipsis (...) button in the Properties window displays the Open dialog box so you can select a desired .prg file or, if supported, .vcx file.

You can also use the ASELOBJ( ) function to store object references to an array to set object properties individually. However, if you set only the DEClass or the DEClassLibrary property, Visual FoxPro disregards the settings for these properties and uses the default DataEnvironment class. You must set both properties.

Note:
When setting the DEClass and DEClassLibrary properties using code or the ASELOBJ( ) function, you must set the DEClassLibrary property before setting the DEClass property.

When you open the Data Environment Designer by right-clicking the form, the following occurs:

  • DataEnvironment class containing Cursor objects

    If the contained cursor or cursors refer to an existing table or remote view, tables and views placed on the Data Environment Designer surface are read-only. You can drag and drop fields or tables on the Form Designer surface if the following properties are set with the specified requirements:

    • CursorSource (Required) Table name and path if a free table; table name only if a database container (DBC) table.

    • Database (Optional) Name and path of the DBC is filled in automatically if a DBC table or view.

    • Alias (Optional) Alias assigned to the table if different from the table name. Otherwise, the alias defaults to the CursorSource name.

    If the DataEnvironment class contains a Cursor object, but the cursor does not contain a valid reference to a table or view, the Data Environment Designer does not open. Visual FoxPro loads the data environment after generating the appropriate message.

    If the DataEnvironment class contains multiple Cursor objects, only those cursors containing valid table and/or view references are placed on the Data Environment Designer surface. Cursors that do not contain valid table or view references are disregarded.

    If the cursor references a DBC, but the cursor does not reference a valid table or view in the DBC, Visual FoxPro loads the data environment after displaying the appropriate message.

    If the DataEnvironment class does not contain a Cursor object, the Data Environment Designer does not open, and Visual FoxPro generates an appropriate message.

    When you drag a table (.dbf) file from a folder to a form while a non-DataEnvironment class data environment is open, Visual FoxPro automatically adds the table to the data environment. However, if the opened data environment is based on a DataEnvironment class, the data environment is read-only, and Visual FoxPro does not add the .dbf file to the data environment.

  • DataEnvironment class containing CursorAdapter objects

    If the DataEnvironment class contains a CursorAdapter object, the CursorAdapter must meet the following requirements to appear on the Data Environment Designer surface:

    • The CursorAdapter CursorSchema property is specified and set to a valid value.

    • The CursorAdapter Alias property is specified.

    Note:
    If the prior conditions are met, cursor adapters appear on the Data Environment Designer surface as read-only. You can drag and drop tables and fields on the form. The properties, events, or methods of the data environment and any contained CursorAdapter objects are read-only.

    The Data Environment Designer does not open if any of the following conditions are true:

    • The DataEnvironment class contains a CursorAdapter object, but the cursor adapter does not contain valid data in the CursorSchema property.

    • The CursorAdapter object does not instantiate for any reason.

To modify the DataEnvironment class, you must close the Form Designer, release any classes in use, modify and recompile the DataEnvironment class in the file specified by the DEClassLibrary property, and return to the Form Designer.

When the DEClass and DEClassLibrary properties are set, running the form creates and loads the data environment from the DataEnvironment class specified. To set DEClass and DEClassLibrary at run time, you must use code.

If you attempt to convert a form to a form set at design time when the Form Designer is open, and the DEClass and DEClassLibrary properties are specified for the form, Visual FoxPro generates the appropriate message. If a form set is open in the Form Designer, and you attempt add a form that specifies the DEClass and DEClassLibrary properties to the form set at design time, Visual FoxPro generates the appropriate message and makes the DEClass and DEClassLibrary properties unavailable. If you attempt to add a form that specifies the DEClass and DEClassLibrary properties to the form set at run time, Visual FoxPro disregards DEClass and DEClassLibrary and does not load the data environment class specified.

DEClass and DEClassLibrary supports Public, Hidden, and Protected scope.

DEClass and DEClassLibrary does not support Access and Assign methods.

In a subclassed form, DEClass and DEClassLibrary are inherited as normal.

Example

The following example creates a Form class and then sets the DEClassLibrary and DEClass properties to specify an external DataEnvironment class and class library.
Copy Code
DEFINE CLASS form1 as Form
   DEClassLibrary="MyProgram.prg"
   DEClass="MyDE"
ENDDEFINE

See Also

Other Resources

Form Object Properties, Methods and Events
DEClassLibrary Property
Access and Assign Methods
PUBLIC Command
Protecting and Hiding Class Members
DataEnvironment Object
Properties
Language Reference


DEClassLibrary Property

Visual FoxPro 9.0 Language Reference
DEClassLibrary Property
See Also Example

Specifies the name of a program (.prg) or visual class library (.vcx) file that contains the DataEnvironment class specified by the DEClass property. Read/write at design time and read-only at run time.

Form.DEClassLibrary [= cClassLibraryName]

Return Value

cClassLibraryName

Character data type. The cClassLibraryName parameter specifies one of the following:
  • Name of a program (.prg) file

  • Name of a visual class library (.vcx) file

Remarks

Applies To: Form Object

For details, see DEClass Property.

Example

The following example creates a Form class and then sets the DEClassLibrary and DEClass properties to specify an external DataEnvironment class and class library.
Copy Code
DEFINE CLASS form1 as Form
   DEClassLibrary="MyProgram.prg"
   DEClass="MyDE"
ENDDEFINE

See Also

Other Resources

Form Object Properties, Methods and Events
Access and Assign Methods
PUBLIC Command
Protecting and Hiding Class Members
DataEnvironment Object
Properties
Language Reference


Default Property

Visual FoxPro 9.0 Language Reference
Default Property
See Also

Specifies which command button or OLE Container control responds to the ENTER key being pressed when there are two or more command buttons on an active form. Available at design time and run time.

Object.Default[ = lExpr]

Return Value

lExpr

The settings for the Default property are:

Setting Description

True (.T.)

When the button's Default property is set to true (.T.) and its parent form is active, the user can execute the button's command by pressing ENTER. (If the focus is in an edit box, the user can press CTRL+ENTER.) If KEYCOMP is set to WINDOWS, the default button's command is not executed if the focus has been moved to another command button. In that case, pressing ENTER affects the button with the focus instead of the default button.

False (.F.)

(Default) The button is not the default button.

Remarks

Applies To: CommandButton | OLE Container Control

The Default property only applies to an OLE Container control that contains an "Acts like a Button" ActiveX control (.ocx).

Only one command button or OLE Container control on a form can be the default command button. When the Default property is set to true (.T.) for one command button or OLE Container control, it is automatically set to false (.F.) for all other command buttons or OLE Container controls on the form. You cannot create a default command button or OLE Container control in a toolbar.

See Also

Other Resources

Enabled Property
KeyPress Event
Properties
Language Reference


DefaultFilePath Property

Visual FoxPro 9.0 Language Reference
DefaultFilePath Property
See Also

Specifies the default drive and directory used by an Application object. Available at run time.

ApplicationObject.DefaultFilePath[ = cPath]

Return Value

cPath

Specifies one of the following:
  • A drive designator.

  • A drive designator with a directory name.

  • A child directory name.

  • Any of the above using MS-DOS® shorthand notation ( \ or ..).

Remarks

Applies To: Application Object | _VFP System Variable

The DefaultFilePath property is similar to SET DEFAULT.

Visual FoxPro searches for a file in the default Visual FoxPro directory. The default directory is the one from which you start Visual FoxPro. However, you can use the DefaultFilePath property to specify a different default directory. If Visual FoxPro cannot find a file in the default directory, it then searches the Visual FoxPro path if one has been specified. Use SET PATH to specify the Visual FoxPro path.

See Also

Other Resources

SET DEFAULT Command
SET PATH Command
Properties
Language Reference


DefOLELCID Property

Visual FoxPro 9.0 Language Reference
DefOLELCID Property
See Also

Specifies the default OLE Locale ID for a form or the main Visual FoxPro window. Available at design time and run time.

Form.DefOLELCID[ = nValue]

Return Value

nValue

Specifies a default OLE Locale ID value for a form or the main Visual FoxPro window. This default value determines the Locale ID for OLE Bound controls and OLE Container controls when they are placed on the form or the main Visual FoxPro window.

Remarks

Applies To: Form | _SCREEN

If the default OLE Locale ID value for a form or the main Visual FoxPro window is changed to a new value, OLE Bound controls and OLE Container controls placed on the form or the main Visual FoxPro window after the new default Locale ID value is in effect use the new value.

If DefOLELCID is set to zero for a form or the main Visual FoxPro window, SYS(3004) determines the default Locale ID for OLE Bound controls and OLE Container controls placed on the form or the main Visual FoxPro window.

See SYS(3005) for a listing of Locale IDs.

Note:
The DefOLELCID property only affects the language of the user interface, which OLE controls display, and not the language of the Automation commands. The Automation command language is affected only by the Global LocaleID, set with SYS(3005).

See Also

Other Resources

OLELCID Property
SYS(3005) - Set Locale ID
Events
Language Reference


DeleteCmd Property

Visual FoxPro 9.0 Language Reference
DeleteCmd Property
See Also

Specifies the command to use when deleting rows. Read/write at design time and run time.

CursorAdapter.DeleteCmd [ = cCommand ]

Return Value

cCommand

Character data type. The following table lists the possible values for DeleteCmd.

cCommand Description

Character string or expression

Specifies a valid command string for the data source in the DeleteCmdDataSource property.

Empty string ("")

The CursorAdapter object generates a SQL DELETE command automatically if the AllowDelete property is set to True (.T.).

For more information about generating SQL commands automatically, see Data Access Management Using CursorAdapters.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


DeleteCmdDataSource Property

Visual FoxPro 9.0 Language Reference
DeleteCmdDataSource Property
See Also

Specifies the data source used by the DeleteCmd property. Read/write at design time and run time.

Note:
The CursorAdapter DeleteCmdDataSourceType property determines how the DeleteCmdDataSource property is used.

CursorAdapter.DeleteCmdDataSource [ = cDataSource]

Return Value

cDataSource

Character data type. The cDataSource parameter specifies the data source used by the DeleteCmd property.

Remarks

Applies To: CursorAdapter Class

The following table describes additional behaviors that apply to DeleteCmdDataSource depending on the value of DeleteCmdDataSourceType.

DeleteCmdDataSourceType DeleteCmdDataSource behavior

Empty ("")

DeleteCmdDataSource is disregarded. Visual FoxPro uses the data source in the CursorAdapter DataSource property.

If the cursor associated with the CursorAdapter object is based on an ActiveX Data Object (ADO) RecordSet, Visual FoxPro uses the functionality of the ADO RecordSet to delete the record. To use this functionality, make sure the CursorAdapter DataSourceType property is set to "ADO".

"ADO"

DeleteCmdDataSource must be set to a valid ADO Command object. The ActiveConnection property of the ADO Command object must be set to a valid and open ADO Connection object.

Visual FoxPro sets the CommandText property of the ADO Command object to the value of the CursorAdapter DeleteCmd property. Visual FoxPro parses the command for parameters, creates parameter values if found, and sets them in the Command object.

The delete operation occurs as:

Copy Code
CursorAdapter.DeleteCmdDataSource.Execute()

For more information about using an ADO RecordSet, automatic updating, and generating SQL commands automatically, see Data Access Management Using CursorAdapters.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


DeleteCmdDataSourceType Property

Visual FoxPro 9.0 Language Reference
DeleteCmdDataSourceType Property
See Also

Specifies the data source type for the data source used by the DeleteCmdDataSource property. Read/write at design time and run time.

CursorAdapter.DeleteCmdDataSourceType [= cDataSourceType]

Return Value

cDataSourceType

Character data type. The cDataSourceType parameter specifies the data source type of the data source in the DeleteCmdDataSource property.

Remarks

Applies To: CursorAdapter Class

If DeleteCmdDataSourceType is empty ("") or null (.NULL.), Visual FoxPro disregards the CursorAdapter DeleteCmdDataSource property and uses the CursorAdapter DataSource and DataSourceType properties.

To generate an XML UpdateGram, you must set the value of DeleteCmdDataSourceType to "XML".

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
UpdateGram Property


DeleteMark Property

Visual FoxPro 9.0 Language Reference
DeleteMark Property
See Also

Specifies whether the delete mark column appears in a Grid control. Available at design time and run time.

Grid.DeleteMark[ = lExpr]

Return Value

lExpr

The settings for the DeleteMark property are:

Setting Description

True (.T.)

(Default) The delete mark column appears on the Grid at the far left column.

False (.F.)

The delete mark column does not appear.

Remarks

Applies To: Grid

The delete mark column enables the user to mark records for deletion. The user clicks in the delete column at the record to delete.

See Also

Other Resources

DELETE Command
Deleted Event
Properties
Language Reference


Description Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Description Property (Visual FoxPro)
See Also

For a File object, the description for the file. For a Server object, the description of the server class. Available at design time and run time.

Object.Description[ = cExpression]

Return Value

cExpression

Specifies the description for the File or Server object. For a File object, the default value is the empty string. You can also specify a description for a file in a project by choosing Edit Description from the Project menu. For a Server, the default value is the name of the server class. You can also specify a description for a server in the Servers tab of the Project Information dialog box. The Server object description also appears for the server in the Registry.

Remarks

Applies To: File Object | Server Object

See Also

Other Resources

Name Property
Properties
Language Reference


Desktop Property

Visual FoxPro 9.0 Language Reference
Desktop Property
See Also

Specifies whether a form can appear anywhere on the Windows desktop or is contained in the main Visual FoxPro window. Available at design time; read-only at run time.

Object.Desktop[ = lExpr]

Return Value

lExpr

The settings for the Desktop property are:

Setting Description

True (.T.)

The form can be anywhere on the Windows desktop.

False (.F.)

(Default) The form is contained in the main Visual FoxPro window.

Remarks

Applies To: Form | _SCREEN

The Desktop property is ignored if the ShowWindow property is set to 2 – As Top-Level form.

You should not use the Desktop property when you create Single Document Interface (SDI) applications in which you might want to hide the Visual FoxPro desktop window (_SCREEN). Instead, set the ShowWindow property setting to 2 to create a top-level form.

See Also

Other Resources

AlwaysOnBottom Property
AlwaysOnTop Property
AutoCenter Property
MaxHeight Property
MaxLeft Property
MaxTop Property
MaxWidth Property
MinHeight Property
MinWidth Property
ShowWindow Property
Properties
Language Reference


Details Property

Visual FoxPro 9.0 Language Reference
Details Property
See Also

Specifies additional details about an exception object that are related to information specified by the Message property. Read/write at run time.

Exception.Details

Return Value

Character data type. Details can be NULL unless the error has an additional parameter; in that case, this property contains the text of the error parameter.

Remarks

Applies To: Exception Class

Identical to the value returned by SYS(2018) and the third element in the array produced by the AERROR() function.

See Also

Other Resources

Properties
Exception Object Properties, Methods, and Events
Message Property
AERROR( ) Function
SYS(2018) - Error Message Parameter
TRY...CATCH...FINALLY Command
Structured Error Handling


DisabledBackColor, DisabledForeColor Properties

Visual FoxPro 9.0 Language Reference
DisabledBackColor, DisabledForeColor Properties
See Also

Specifies the background and foreground colors for a disabled control. Read/write at design time and run time. There are two versions of the syntax for each property.

Control.DisabledBackColor[ = nColor]
Control.DisabledBackColor = RGB(nRedValue, nGreenValue, nBlueValue)
Control.DisabledForeColor[ = nColor]
Control.DisabledForeColor = RGB(nRedValue, nGreenValue, nBlueValue)

Return Value

nColor

Specifies a single number to represent the color.
nRedValue, nGreenValue, nBlueValue

Specifies three separate color intensities that compose the control's foreground color or background color. You must use the RGB( ) function with these values to consolidate the three color components into one number.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | EditBox | Label | ListBox | OptionButton | Spinner | TextBox

The color you specify is dithered with gray.

Note:
In the Properties window, you can double-click any of the color properties to display the Color dialog box. You can choose or define colors from this dialog box. The red, green, and blue intensities that correspond to the color you choose become the settings for these properties after you close the Color dialog box.

The color settings, or Themes, of the operating system set the default color settings for the DisabledBackColor and DisabledForeColor properties.

If the Themes property is set to True (.T.), setting the DisabledBackColor property value produces a 35% transparency overlay on top of the themed button. This produces a colorizing effect.

See Also

Other Resources

BackColor, ForeColor Properties
Properties
Language Reference


DisabledItemBackColor, DisabledItemForeColor Properties

Visual FoxPro 9.0 Language Reference
DisabledItemBackColor, DisabledItemForeColor Properties
See Also

Specifies the background or foreground color for the disabled items in a ComboBox or ListBox control. Available at design time and run time. There are two versions of the syntax for each property.

Control.DisabledItemBackColor[ = nColor]
Control.DisabledItemBackColor RGB(nRedValue, nGreenValue,  nBlueValue)
Control.DisabledItemForeColor[ = nColor]
Control.DisabledItemForeColor RGB(nRedValue, nGreenValue, nBlueValue)

Return Value

nColor

Specifies a single number to represent the color.
Note:
In the Properties window, you can double-click any of the color properties to display the Color dialog box. You can choose or define colors from this dialog box. The red, green, and blue intensities that correspond to the color you choose become the settings for these properties after you close the Color dialog box.

For more information, see the color table in the BackColor, ForeColor Properties topic.

Remarks

Applies To: ComboBox | ListBox

See Also

Other Resources

BackColor, ForeColor Properties
DisabledBackColor, DisabledForeColor Properties
RGB( ) Function
SelectedBackColor, SelectedForeColor Properties
Properties
Language Reference


DisabledPicture Property

Visual FoxPro 9.0 Language Reference
DisabledPicture Property
See Also

Specifies the graphic to display when the control is disabled. Available at design time and run time.

Control.DisabledPicture[ = cPicture]

Return Value

cPicture

Specifies either a complete path and file name of a bitmap or the name of a general field in a database table.

Remarks

Applies To: CheckBox | CommandButton | OptionButton

If you set the DisabledPicture property at design time and the file you specify does not exist, Visual FoxPro displays an error message, but the property remains set to the file you specified. Visual FoxPro ignores the DisabledPicture property at run time if it is set to a file that does not exist.

If you do not set the DisabledPicture property, Visual FoxPro uses the Picture property setting to determine the graphic displayed when the control is disabled.

For CommandButton controls, the Style property must be set to 0 (Standard) for the bitmap to be displayed on the control; For CheckBox and OptionButton controls, the Style property must be set to 1 (Graphical).

See Also

Other Resources

DownPicture Property
Enabled Property
Picture Property
Style Property
Properties
Language Reference


DisableEncode Property

Visual FoxPro 9.0 Language Reference
DisableEncode Property
See Also

Enables or disables base64 or hexBinary encoding for Memoor Characterfields.

Setting DisableEncode at the XMLAdapter level sets the default DisableEncode values for XMLField objects when they are created and added to the Fields collection by the following XMLAdapter methods:

  • LoadXML

  • Attach

  • AddTableSchema

Additionally, changing DisableEncode at the XMLAdapter level affects only the next set of XMLField objects created, not the existing XMLField objects in the Fields collection. Therefore, to modify the setting of DisableEncode for an existing XMLField object, change the value at the XMLField level.

Note:
DisableEncode applies to XMLField objects only if IsBinary is set to True (.T.). For more information, see IsBinary Property.

Object.DisableEncode [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

Disable base64 or hexBinary encoding for Memoor Characterfields. (Default)

True (.T.)

Enable base64 or hexBinary encoding for Memoor Characterfields.

Remarks

Applies To: XMLAdapter Class | XMLField Class

Visual FoxPro disregards invalid characters or incorrect length in base64 and hexBinary encoded strings.

If XMLAdapter DisableEncode is True (.T.) when the LoadXML method is executed, the XMLField MaxLength property is set to the maximum length for the encoded data. Otherwise, Visual FoxPro uses the original MaxLength value.

If XMLAdapter DisableEncode is True (.T.) when the ToXML method is executed, the xsd:maxLength value in the XML Schema Definition (XSD) schema is set to the maximum length for the decoded data. Otherwise, Visual FoxPro uses the value of the XMLField MaxLength property.

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
XMLField Object Properties, Methods, and Events
Fields Collection (XMLTable)
MaxLength Property
ToXML Method


DisplayCount Property

Visual FoxPro 9.0 Language Reference
DisplayCount Property
See Also

Specifies the maximum number of items displayed in the list portion of a ComboBox control.

Object.DisplayCount[ = nExpression]

Return Value

nExpression

Specifies the maximum number of items displayed in the list portion of the ComboBox control. The default value is zero; if nExpression is zero, a maximum of 7 items are displayed in the list. Scroll arrows are not displayed in the list portion of a ComboBox control if nExpression is one.

Remarks

Applies To: ComboBox

See Also

Other Resources

ColumnCount Property
DisplayValue Property
Properties
Language Reference


DisplayOrientation Property

Visual FoxPro 9.0 Language Reference
DisplayOrientation Property
See Also

Specifies the display orientation for an application running on a Tablet PC.

_SCREEN.DisplayOrientation [= nValue]

Return Value

nValue

The settings for the DisplayOrientation property are:

Setting Description

0

Display is in Upright Landscape mode.

1

Display is in Upright Portrait mode.

2

Display is in Inverted Landscape mode.

3

Display is in Inverted Portrait mode.
If you omit the nValue parameter, DisplayOrientation returns a value indicating the current display orientation.

Remarks

The DisplayOrientation property is read-write. If you change the DisplayOrientation property value, the Tablet PC's display orientation is rotated as it would from the Tablet PC’s control panel.

You can detect a Tablet PC screen rotation event by using the BINDEVENT( ) Function with the DisplayOrientation property.

See Also

Reference

BINDEVENT( ) Function
_SCREEN System Variable Properties, Methods and Events


DisplayValue Property

Visual FoxPro 9.0 Language Reference
DisplayValue Property
See Also

Specifies the contents of the first column of the selected item in a ListBox or ComboBox control. Available at design time and run time.

Use the DisplayValue property when a combo box or list box has more than one column, and the control's BoundColumn property is set to a value greater than 1.

 [Form.]Control.DisplayValue[ = Expr]

Return Value

Expr

Specifies a character string or numeric value. The following table describes the values of Expr.

Expr Description

Character string

Specifies the value of the first column of the selected item.

For combo boxes, DisplayValue specifies the text displayed in the text box portion of the combo box when DisplayValue is a character string. However, the ComboBox InputMask and MaxLength properties can affect its display.

Numeric value

Specifies the index of the selected item.

Remarks

Applies To: ComboBox | ListBox

When a combo box or list box has only one column, the DisplayValue property and Value property of the control usually have the same setting if both contain character strings. An exception exists when both properties contain character strings, and a value is typed in the combo box, but the value does not exist in the list. In this case, the value is an empty string (""), and DisplayValue will be the value that is typed in.

See Also

Other Resources

BoundColumn Property
Value Property
Properties
Language Reference


Dockable Property

Visual FoxPro 9.0 Language Reference
Dockable Property
See Also Example

Determines whether a form can be docked. Read/write at design time and run time.

Form.Dockable [= nValue]

Return Value

nValue

Specifies a value that determines whether a form can be docked. The following table lists the values for nValue.

nValue Description

0

Form does not support docking. (Default)

1

Form supports docking and is dockable. The HalfHeightCaption property is set to True (.T).

2

Form supports docking but is not dockable. The HalfHeightCaption property is set to True (.T).
Note:
Before setting Dockable to 1 or 2, the ScrollBars property must be 0 (None), the ShowWindow property must be 0 (In Screen), and Desktop must be False (.F.). The ScrollBars, ShowWindow, and Desktop properties are read-only during run time. For more information, see ScrollBars Property and ShowWindow Property.

Remarks

Applies To: Form Object

Forms that are part of a form set do not support docking.

If the Dockable property changes when a form is docked, the form is undocked automatically.

When the form supports docking, that is, Dockable is set to 1 or 2, you can interactively set the form as dockable using one of two methods:

  • On the Window menu, click Dockable.

-OR-

  • Right-click the form's title bar and click Dockable on the shortcut menu.

Performing either of these actions switches the setting of Dockable between 1 and 2.

When Dockable is set to a value greater than 0, Visual FoxPro sets the properties in the following table automatically and disregards changes made to these properties. Setting Dockable to 0 does not revert these properties to their previous values.

Property | Setting | Notes
AlwaysOnBottom | .F. |
AlwaysOnTop | .F. |
BorderStyle | 3 |
Closable | .T. |
Desktop | .F. | Read-only at run time.
Enabled | .T. |
HalfHeightCaption | .T. |
MaxButton | .F. | Used only when Dockable is set to 2.
MDIForm | .F. |
MinButton | .F. | Used only when Dockable is set to 2.
Movable | .T. |
ScrollBars | 0. | Read-only at run time.
ShowWindow | 0. | Read-only at run time.
TitleBar | 1 |
Visible | .T. |
WindowState | 0 |
WindowType | 0 |

When Dockable is set to a value greater than 0, Visual FoxPro disregards the following properties entirely:

  • MaxLeft

  • MaxTop

  • MaxWidth

  • MinHeight

  • MinWidth

When a form is docked, the following properties are read-only:

  • Left Property

  • Top Property

  • Width Property

  • Height Property

Example

The following example uses the CREATEOBJECT( ) function to create a form, sets the Dockable and Visible properties so that the form is dockable and visible, and uses the Dock method to dock the form to the left side of the main Visual FoxPro window.
Copy Code
omyForm = CREATEOBJECT("Form")
omyForm.Dockable = 1
omyForm.Visible = .T.
omyForm.Dock(1)

See Also

Other Resources

Properties
How to: Dock Forms
Docked Property
DockPosition Property
AfterDock Event
BeforeDock Event
UnDock Event
Dock Method
GetDockState Method
ADOCKSTATE( ) Function


Docked Property

Visual FoxPro 9.0 Language Reference
Docked Property
See Also

Indicates whether a user-defined toolbar or form is docked. Read-only at design time and run time.

Object.Docked [= lValue]

Return Value

lValue

Specifies a Logical value that indicates whether a toolbar or form is docked. The following table lists the values for lValue.

lValue Description

False (.F.)

The toolbar or form is not docked. (Default)

True (.T.)

The toolbar or form is docked.

Remarks

Applies To: Form Object | ToolBar Object

To dock a form or toolbar, use the Dock method. For more information, see Dock Method.

See Also

Reference

DOCK Command

Other Resources

DockPosition Property
GetDockState Method
BeforeDock Event
AfterDock Event
UnDock Event
ADOCKSTATE( ) Function
How to: Coordinate Toolbars and Forms Using Code
Properties
Language Reference


DockPosition Property

Visual FoxPro 9.0 Language Reference
DockPosition Property
See Also

Indicates the docking position for a user-defined ToolBar object or Form object. Read-only at design time and run time.

Object.DockPosition [= nPosition]

Return Value

nPosition

Indicates the docking position for a toolbar or form. The following table lists the values for nPosition.

nPosition Description

–1

Not docked

0

Top

1

Left

2

Right

3

Bottom

4

Tabbed (forms only)

5

Link-docked (forms only)

Note:
A value of 5 indicates that a form is part of link-docked container. You can dock a tab-docked window with a link-docked container; therefore, it is recommended that you obtain additional docking information using the ADOCKSTATE( ) function and GetDockState method.

Remarks

Applies To: Form Object | ToolBar Object

To retrieve detailed docking information, see ADOCKSTATE( ) Function and GetDockState Method.

See Also

Other Resources

How to: Dock Windows
How to: Dock Forms
Docked Property
Properties


DocumentFile Property

Visual FoxPro 9.0 Language Reference
DocumentFile Property
See Also Example

Returns the name of the file from which a linked OLE object was created. At design time, specifies the name of the linked file. Read-only at design time and run time for an existing object, but can be set for an object when creating it.

Object.DocumentFile[ = cFileName]

Return Value

cFileName

The name of the file to which the object is linked. The name includes the full path of the file.

Remarks

Applies To: OLE Bound Control | OLE Container Control

DocumentFile contains the empty string for embedded (not linked) objects.

You set the DocumentFile property of a linked OLE object using the Insert Object dialog box when you initially add an OLE container to a form. You can also set this property when creating an OLE object using the APPEND GENERAL command or when defining the object in code as part of a class definition.

Before specifying the contents of an OLE object using the DocumentFile property, specify the Automation server application by setting the object's OLEClass.

Example

The following example adds an OLE Container control to a form, and uses the DocumentFile and OleClass properties to specify a Microsoft Excel worksheet as the file to edit and Microsoft Excel as the Automation server.

The DocumentFile property specifies a worksheet named Book1.xls in the EXCEL directory on drive C. This example will not work properly if the file and directory specified in the DocumentFile property do not exist; it may be necessary to modify the DocumentFile property to specify an existing directory and worksheet file.

The DoVerb method is used to activate the worksheet for editing.
Copy Code
frmMyForm = CREATEOBJECT('form')  && Create a form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('cmdCommand1','cmdMyCmdBtn')  && Add Command button
frmMyForm.AddObject("oleObject","oleExcelObject")  && Add OLE object

frmMyForm.cmdCommand1.Visible=.T.  && Display the "Quit" Command button

frmMyForm.oleObject.Visible=.T.  && Display the OLE control
frmMyForm.oleObject.Height = 50  && OLE control height

frmMyForm.Show  && Display the form

frmMyForm.oleObject.DoVerb(-1)  && -1 for Edit

READ EVENTS  && Start event processing

DEFINE CLASS oleExcelObject as OLEControl
   OleClass ="Excel.Sheet"  && Server name
   DocumentFile = "C:\EXCEL\BOOK1.XLS"  && This file must exist
ENDDEFINE

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close form
ENDDEFINE

See Also

Other Resources

APPEND GENERAL Command
CREATEOBJECT( )
OLEClass
Properties
Language Reference


DownPicture Property

Visual FoxPro 9.0 Language Reference
DownPicture Property
See Also

Specifies the graphic displayed when the control is selected. Available at design time and run time.

Control.DownPicture[ = cPicture]

Return Value

cPicture

Specifies a complete path and file name of a bitmap.

Remarks

Applies To: CheckBox | CommandButton | OptionButton

If you set the DownPicture property at design time and the file you specify does not exist, Microsoft Visual FoxPro displays an error message, but the property remains set to the file you specified. Visual FoxPro ignores the DownPicture property at run time if it is set to a file that does not exist.

If you do not specify a setting for the DownPicture property, Visual FoxPro uses the graphic specified by the Picture property when the control is selected.

For CommandButton controls, the Style property must be set to 0 (Standard) for the bitmap to be displayed on the control; For CheckBox and OptionButton controls, the Style property must be set to 1 (Graphical).

See Also

Other Resources

DisabledPicture Property
Enabled Property
Picture Property
Style Property
Properties
Language Reference


DragIcon Property

Visual FoxPro 9.0 Language Reference
DragIcon Property
See Also

Specifies the icon displayed as the pointer during a drag-and-drop operation. Available at design time and run time.

Control.DragIcon[ = cIcon]

Return Value

cIcon

Specifies the file that contains the icon to use as the mouse pointer. Typically, you specify the icon file using the Properties window at design time. The file you specify must have the .cur extension and be saved in VGA-Mono 2-Color 32 x 32 format. If you try to use a color .cur file, an error message is generated. You can use ImageEdit, to create a two-color .cur file. If you omit cIcon, an arrow pointer inside a rectangle is used.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | Shape | Spinner | TextBox

DragIcon is useful for providing visual feedback during a drag operation — for instance, to indicate that the source control is over an appropriate target. DragIcon takes effect when the user initiates dragging. Typically, you set DragIcon during a MouseDown or DragOver event.

If you set the DragIcon property at design time and the file you specify does not exist, Visual FoxPro displays an error message, but the property remains set to the file you specified. Visual FoxPro ignores the DragIcon property at run time if it is set to a file that does not exist.

See Also

Other Resources

Drag Method
DragDrop Event
DragMode Property
MouseDown Event
MouseMove Event
MousePointer Property
MouseUp Event
Properties
Language Reference


DragMode Property

Visual FoxPro 9.0 Language Reference
DragMode Property
See Also

Specifies manual or automatic drag mode for a drag-and-drop operation. Available at design time and run time.

Control.DragMode[ = nMode]

Return Value

nMode

The settings for the DragMode property are:

Setting Description

0

(Default) Manual. Requires using the Drag method to initiate dragging of the source control.

1

Automatic. Clicking the source control automatically initiates dragging.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox

When DragMode is set to 0 (Manual), the control responds to mouse events and the Drag method must be used to begin drag operations.

When DragMode is set to 1 (Automatic), the control does not respond to mouse events, and drag operations begin automatically when the user presses and holds the primary (left) mouse button over the control.

Releasing the mouse button while the mouse pointer is over a target control or form during a drag operation generates a DragDrop event for the target object and ends the drag operation. Dragging can also trigger a DragOver event.

Note:
While a control is being dragged, it does not receive other user-initiated mouse or keyboard events (KeyPress, MouseDown, MouseMove, or MouseUp).

See Also

Other Resources

DragDrop Event
DragIcon Property
DragOver Event
KeyPress Event
MouseDown Event
MouseMove Event
MouseUp Event
OLEDragMode Property
Properties
Language Reference


DrawMode Property

Visual FoxPro 9.0 Language Reference
DrawMode Property
See Also

Determines, in conjunction with the color properties, how a shape or line is displayed on screen. Available at design time and run time.

Object.DrawMode[ = nMode]

Return Value

nMode

The settings for the DrawMode property are:

Setting Description

1

Blackness Pen. Shape is drawn black.

2

NotMerge Pen. Inverse of setting 15.

3

Mask Not Pen. Combination of the colors common to the BackColor and the inverse of the ForeColor.

4

Not Copy Pen. Inverse of setting 13.

5

Mask Pen Not. Combination of the colors common to both the ForeColor and the inverse of the BackColor.

6

Invert. Inverse of the BackColor.

7

XOR Pen. Combination of the colors in the ForeColor and in the BackColor, but not in both.

8

Not Mask Pen. Inverse of setting 9.

9

Mask Pen. Combination of the colors common to both the ForeColor and the BackColor.

10

Not XOR Pen. Inverse of setting 7.

11

NOP. No operation. Output remains unchanged. In effect, this setting turns drawing off.

12

Merge Not Pen. Combination of the BackColor and the inverse of the ForeColor.

13

(Default). Copy Pen. Color specified by the ForeColor property.

14

Merge Pen Not. Combination of the ForeColor and the inverse of the BackColor.

15

Merge Pen. Combination of the ForeColor and the BackColor.

16

Whiteness Pen. Shape is drawn white.

Remarks

Applies To: Form | Line | _SCREEN | Shape

Use the DrawMode property to produce visual effects with Shape or Line controls or when drawing with graphics methods. As a new shape is drawn, Visual FoxPro compares each pixel in the pattern with the corresponding pixel in the existing background and then applies bitwise operations. For example, setting 7 uses the exclusive OR operator (XOR) to combine a drawing pattern pixel with the background pixel.

The exact effect of the DrawMode property setting depends on how the color of a line drawn at run time combines with colors already on the screen. Settings 1, 6, 7, 11, 13, and 16 yield the most predictable results.

See Also

Other Resources

Box Method
Circle Method
DrawWidth Property
DrawStyle Property
FillColor Property
FillStyle Property
Line Method
Pset Method
Properties
Language Reference


DrawStyle Property

Visual FoxPro 9.0 Language Reference
DrawStyle Property
See Also

Specifies the line style to use when drawing with graphics methods. Available at design time and run time.

Object.DrawStyle[ = nStyle]

Return Value

nStyle

The settings for the DrawStyle property are:

Setting Description

0

(Default) Solid

1

Dash

2

Dot

3

Dash-Dot

4

Dash-Dot-Dot

5

Transparent

6

Inside Solid
Note:
If DrawWidth is set to 1, DrawStyle produces the effect described in the preceding table for each setting. But if DrawWidth is set to a value greater than 1, settings 1 through 4 produce a solid line.

Remarks

Applies To: Form | _SCREEN

See Also

Other Resources

Circle Method
DrawMode Property
DrawWidth Property
FillColor Property
FillStyle Property
ForeColor Property
Line Method
PSet Method
Properties
Language Reference


DrawWidth Property

Visual FoxPro 9.0 Language Reference
DrawWidth Property
See Also

Specifies the line width for output from graphics methods. Available at design time and run time.

Object.DrawWidth[ = nSize]

Return Value

nSize

Specifies the width of the line in pixels. You can set DrawWidth to a value of 1 through 32,767. The default value is 1 pixel wide. Increase the value of this property to increase the width of the line.

Remarks

Applies To: Form | _SCREEN

See Also

Other Resources

Circle Method
DrawMode Property
DrawStyle Property
FillColor Property
FillStyle Property
ForeColor Property
Properties
Language Reference


DynamicAlignment Property

Visual FoxPro 9.0 Language Reference
DynamicAlignment Property
See Also

Specifies the alignment of text and controls in a Column object. Available at design time; read/write at run time.

Column.DynamicAlignment [= "cAlign"]

Return Value

cAlign

Specifies a character expression that evaluates to a value as described in the following table. The alignment value is reevaluated at run time each time the Grid control is refreshed.

cAlign evaluates to Description

0

Middle Left.

Aligns the text flush left and centered vertically.

1

Middle Right.

Aligns the text flush right and centered vertically.

2

Middle Center.

Aligns the text in the middle with equal spaces to the right and left and is centered vertically.

3

Automatic. (Default)

Aligns text based on the data type of the control source. Numeric types, such as Numeric, Double, Float, Currency, and Integer, are aligned to the right; controls with other data types are aligned to the left.

4

Top Left.

Aligns the text flush left and at the top of the column.

5

Top Right.

Aligns the text flush right and at the top of the column.

6

Top Center.

Aligns the text in the middle with equal spaces to the right and left and at the top of the column.

7

Bottom Left.

Aligns the text flush left and at the bottom of the column.

8

Bottom Right.

Aligns the text flush right and at the bottom of the column.

9

Bottom Center. Aligns the text in the middle with equal spaces to the right and left and at the bottom of the column.

Remarks

Applies To: Column

Note:
The Grid AutoFit method might not resize adequately to display the entire contents of a column if you use this property.

See Also

Other Resources

Alignment Property
Properties
Language Reference


DynamicBackColor, DynamicForeColor Properties

Visual FoxPro 9.0 Language Reference
DynamicBackColor, DynamicForeColor Properties
See Also Example

Specifies the background and foreground colors of a Column object. Available at design time; read/write at run time.

Column.DynamicBackColor [= "cExpression"]
Column.DynamicForeColor [= "cExpression"]

Return Value

cExpression

Specifies a character expression evaluates at run time to a single color value. The color value is reevaluated at run time whenever the Grid control is refreshed.

Remarks

Applies To: Column

Note:
The Grid AutoFit method might not resize adequately to display the entire contents of a column if you use these properties.

You can use the DynamicBackColor and DynamicForeColor properties to create special effects, such as displaying the odd-numbered rows in green and the even-numbered rows in gray.

Example

The following example uses the DynamicBackColor property and the SetAll method to specify the background colors for the records in a Grid control. If the number of a record displayed in the grid is even, the record's DynamicBackColor is white; otherwise, DynamicBackColor is green.

A Grid control is placed on a form, and the customer table is opened and its contents displayed in the Grid. The Caption property is used to specify a different header caption (Customer ID) for the CUST_ID field. A command button is placed on the form to close the form.
Copy Code
CLOSE ALL  && Close tables and databases
OPEN DATABASE (HOME(2) + 'Data\testdata')

USE customer  IN 0  && Opens Customer table

frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .f.  && Disable the Control menu box

frmMyForm.AddObject('cmdCommand1','cmdMyCmdBtn')  && Add Command button
frmMyForm.AddObject('grdGrid1','Grid')  && Add Grid control

frmMyForm.grdGrid1.Left = 25  && Adjust Grid position

frmMyForm.grdGrid1.SetAll("DynamicBackColor", ;
   "IIF(MOD(RECNO( ), 2)=0, RGB(255,255,255) ;
   , RGB(0,255,0))", "Column")  && Alternate white and green records

frmMyForm.grdGrid1.Visible = .T.  && Grid control visible
frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible
frmMyForm.grdGrid1.Column1.Header1.Caption = 'Customer ID'

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
      CLOSE ALL  && Close table and database
ENDDEFINE

See Also

Other Resources

BackColor_ForeColor Properties
Properties
Language Reference


DynamicCurrentControl Property

Visual FoxPro 9.0 Language Reference
DynamicCurrentControl Property
See Also

Specifies which control in a Column object is used to display the values of the active cell. Available at design time; read/write at run time.

Column.DynamicCurrentControl [= cExpression]

Return Value

cExpression

Specifies a character expression that evaluates to the name of the control that displays and accepts data for the active cell in the specified column at run time. The name of the control is reevaluated each time the Grid control is refreshed.
Note:
The default control is a TextBox control with Text1 as the Name property. To add other controls, use the AddObject method.

Remarks

Applies To: Column

Note:
The Grid AutoFit method might not resize adequately to display the entire contents of a column if you use this property.

If the column's Sparse property is set to True (.T.), only the active cell in the column uses the object specified in the DynamicCurrentControl property setting to display data; the other cells display data using a text box. If the Sparse property is set to False (.F.), all cells in the column use the object specified in the DynamicCurrentControl property setting to display data.

See Also

Other Resources

AddObject Method
CurrentControl Property
Properties
Language Reference


DynamicFontBold, DynamicFontItalic, DynamicFontStrikethru, DynamicFontUnderline Properties

Visual FoxPro 9.0 Language Reference
DynamicFontBold, DynamicFontItalic, DynamicFontStrikethru, DynamicFontUnderline Properties
See Also

Specifies that text displayed in a Column object has one or more of the following styles: Bold, Italic, Strikethru, or Underline. The logical expression is reevaluated each time the Grid control is refreshed. Available at design time; read/write at run time.

Column.DynamicFontBold [= "lExpr"]
Column.DynamicFontItalic [= "lExpr"]
Column.DynamicFontStrikeThru [= "lExpr"]
Column.DynamicFontUnderline [= "lExpr"]

Return Value

" lExpr "

Specifies a logical expression that evaluates to True (.T.) or False (.F.). The following table describes the settings for these values.

lExpr evaluates to Description

True (.T.)

Font style is bold, italic, strikethru, or underline.

False (.F.)

Font style is not bold, italic, strikethru, or underline. (Default except for DynamicFontBold)

Remarks

Applies To: Column

You can use these properties to control the appearance of text based on data values at run time. For example, you can set DynamicFontUnderline to indicate names of new members in an organization.

Note:
The Grid AutoFit method might not resize adequately to display the entire contents of a column if you use these properties.

See Also

Other Resources

DynamicFontSize Property
DynamicFontName Property
Properties
Language Reference


DynamicFontName Property

Visual FoxPro 9.0 Language Reference
DynamicFontName Property
See Also

Specifies the name of the font used to display text in a Column object. Available at design time; read/write at run time.

Column.DynamicFontName [= cName]

Return Value

cName

Specifies a character expression that evaluates to the name of a font. The expression is reevaluated at run time each time the Grid control is refreshed.
Note:
At design time, you can view a list of available fonts by selecting the FontName property in the Properties window and clicking the arrow to the right of the property settings box.

Remarks

Applies To: Column

Note:
The Grid AutoFit method might not resize adequately to display the entire contents of a column if you use this property.

See Also

Other Resources

FontName Property
DynamicFontOutline Property
DynamicFontBold, DynamicFontItalic, DynamicFontStrikethru, DynamicFontUnderline Properties
Properties
Language Reference


DynamicFontOutline Property

Visual FoxPro 9.0 Language Reference
DynamicFontOutline Property
See Also

Specifies whether the text associated with a Column object is outlined. Available at design time and run time.

Column.DynamicFontOutline[ = "lExpr"]

Return Value

"lExpr"

Specifies a logical expression that evaluates to True (.T.) or False (.F.). The expression is reevaluated at run time each time the Grid control is refreshed. The following table describes the settings for these values.

lExpr evaluates to Description

True (.T.)

The text is outlined.

False (.F.)

The text is not outlined. (Default)

Remarks

Applies To: Column

Note:
The Grid AutoFit method might not resize adequately to display the entire contents of a column if you use this property.

See Also

Other Resources

FontOutline Property
DynamicFontShadow Property
DynamicFontBold, DynamicFontItalic, DynamicFontStrikethru, DynamicFontUnderline Properties
Properties
Language Reference


DynamicFontShadow Property

Visual FoxPro 9.0 Language Reference
DynamicFontShadow Property
See Also

Specifies whether the text associated with a Column object appears with a shadow. Available at design time and run time.

Column.DynamicFontShadow [= "lExpr"]

Return Value

"lExpr"

Specifies a logical expression that evaluates to True (.T.) or False (.F.). The expression is reevaluated at run time each time the Grid control is refreshed. The following table describes the settings for these values.

lExpr evaluates to Description

True (.T.)

The text is shadowed.

False (.F.)

The text is not shadowed. (Default)

Remarks

Applies To: Column

Note:
The Grid AutoFit method might not resize adequately to display the entire contents of a column if you use this property.

See Also

Other Resources

FontShadow Property
DynamicFontOutline Property
DynamicFontBold, DynamicFontItalic, DynamicFontStrikethru, DynamicFontUnderline Properties
Properties
Language Reference


DynamicFontSize Property

Visual FoxPro 9.0 Language Reference
DynamicFontSize Property
See Also

Specifies the font size for text displayed in a Column object. Available at design time; read/write at run time.

Column.FontSize [= "nSize"]

Return Value

"nSize"

Specifies a numerical expression that evaluates to a font size. The default font size is 10 points. The maximum value for nSize is 2,048 points. The font size is reevaluated at run time each time the Grid control is refreshed.
Note:
There are 72 points in 1 inch.

Remarks

Applies To: Column

You can use this property to change the font size of a row.

Note:
The Grid AutoFit method might not resize adequately to display the entire contents of a column if you use this property.

See Also

Other Resources

DynamicAlignment Property
DynamicFontName Property
DynamicFontBold, DynamicFontItalic, DynamicFontStrikethru, DynamicFontUnderline Properties
Properties
Language Reference


DynamicInputMask Property

Visual FoxPro 9.0 Language Reference
DynamicInputMask Property
See Also Example

Specifies the dynamic format of text and controls in a column by controlling how data is entered and displayed in a Column object. Available at design time; read/write at run time.

Column.DynamicInputMask[ = cInputMask]

Return Value

cInputMask

Specifies a character expression that must evaluate to a character string with the following format:
Copy Code
[@cFunction] [cMask]
The character expression is reevaluated at run time each time the Grid control is refreshed. For additional information about the format of cFunction and cMask, see the Format and InputMask properties.

Remarks

Applies To: Column

The DynamicInputMask property takes precedence over the Format and InputMask properties.

If the control specified by the column's CurrentControl property is a text box, spinner, or combo box, the cFunction and cMask portions of the DynamicInputMask expression are passed to the Format and InputMask properties for the text box, spinner, or combo box.

Note:
The Grid AutoFit method might not resize adequately to display the entire contents of a column if you use this property.

Example

The following example demonstrates a typical format for cInputMask:
Copy Code
Column1.DynamicInputMask = "@R$ ###,###,###.##"

See Also

Other Resources

Properties
Language Reference


DynamicLineHeight Property

Visual FoxPro 9.0
DynamicLineHeight Property
See Also

Indicates whether the ReportListener should use GDI+ standard linespacing according to font characteristics, or backward-compatible fixed line spacing.

ReportListener.DynamicLineHeight [= lExpr]

Return Value

Logical data type.

True

(Default) Multi-line objects are rendering using default GDI+ behavior. Line spacing is determined dynamically, according to font. If the object has an opaque fill or backcolor, this color shows for the entire block.
False

Backward compatible mode. Multi-line objects are rendered individually, with fixed spacing. If the object has an opaque fill or backcolor, this color shows only under the rendered text.

Remarks

Applies To: ReportListener Object.

Previous to Visual FoxPro 9, the Report Engine used a fixed line height for rendering multi-line text objects. Visual FoxPro's ReportListener class has the ability to render multi-lined objects using GDI+ default line spacing, which is dynamically adjusted for font characteristics.

You can set this property to .F. if you want the Report Engine to render multi-lined objects line-by-line, using the same spacing as it used in previous versions. This line spacing calculation is as follows:

The Engine takes the height of the object from the FRX (in FRUs, 10000ths of an inch) and divides by the number of lines in the current content for the layout object, according to the current font characteristics. It converts the result to 960dpi to get the height of a single line.

There is a performance penalty for setting DynamicLineHeight to .F., because the Report Engine must calculate the words that fit on each line of the multi-line object before adding the fixed vertical spacing, and then continuing to render the next line.

The two methods of handling multi-line objects also differ in how they show opaque fills or background colors. When DynamicLineHeight is .T., the entire multi-line block is handled by GDI+ as a single object. When DynamicLineHeight is .F., each separately-rendered line contains its own background, and each line may have a different width.

See Also

Tasks

How to: Change Opacity of Report Controls

Concepts

Using GDI+ in Reports

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


EditorOptions Property

Visual FoxPro 9.0 Language Reference
EditorOptions Property
See Also Example

Specifies the Visual FoxPro Editor options to set. There are two versions of the syntax.

ApplicationObject.EditorOptions [= cOptionString]
_VFP.EditorOptions [= cOptionString]

Return Value

cOptionString

Specifies a character string consisting of one or more letters that represent options to enable or disable. The following table describes valid values for cOptionString.

Editor option cOptionString Default Run time

List Members (Manual)

l

Off

Yes1

Quick Info (Manual)

q

Off

Yes1

List Members (Automatic)

L

On

Yes1

Quick Info (Automatic)

Q

On

Yes1

Enable Hyperlinks (CTRL + Click to follow the link)

K

On

Yes

Enable Hyperlinks (Click to follow the link)

k

Off

Yes

DragDrop Between Words

W

Off

No

Designer Value Tips

T

On

No

Suppress RTF Clipboard Format

X

Off

Yes
1 Only available at run time through the oFoxCode object in a FoxCode script.
Note:
You cannot use the uppercase and lowercase settings of the same letter together in the same cOptionString.

Tip:
You can disable all IntelliSense functionality by setting EditorOptions to the empty string (""). The default settings are "LQKT".

Remarks

Applies To: Application Object | _VFP System Variable

Designer Value Tips ("T") are information tips associated with items in lists and drop-down controls. These include the following:

  • Fields in data source lists (tables and views) in Database, View, and Form (Data Environment) designers.

  • Methods and events in Form and Class Designer method editor procedure drop-down controls.

In Visual FoxPro 9.0, _VFP editor options you specify with the EditorOptions property are persisted between Visual FoxPro sessions.

The Suppress RTF Clipboard option ("X") suppresses copying of color syntax code as rich text (RTF format) when copying from a Visual FoxPro editor and pasting into another editor such as Microsoft Word. With this option set, text is only copied to the clipboard as plain text without any rich formatting.

Example

By default, IntelliSense in Visual FoxPro is set to Automatic. To set IntelliSense to Manual, making it available through keyboard shortcuts or menus, use the lowercase settings instead of uppercase. For example:
Copy Code
_VFP.EditorOptions = "lq"    && Sets IntelliSense to Manual.
_VFP.EditorOptions = "LQ"    && Sets IntelliSense to Automatic.

For more information, see How to: Set IntelliSense Options and Visual FoxPro IntelliSense Manager Window.

See Also

Other Resources

Properties
EDITSOURCE( ) Function
IntelliSense Overview
How to: Set Editor Options


Enabled Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Enabled Property (Visual FoxPro)
See Also

Specifies whether an object can respond to user-generated events. Available at design time and run time.

Object.Enabled[ = lExpr]

Return Value

lExpr

The settings for the Enabled property are:

Setting Description

True (.T.)

(Default) An object responds to events.

False (.F.)

An object does not respond to events.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | _SCREEN | Shape | Spinner | TextBox | Timer | ToolBar

The Enabled property allows objects to be enabled or disabled at run time. For example, you can disable objects that do not apply to the current state of the application. You can also disable a control to restrict its use — for example, an edit box can be disabled to display read-only information. If a control is disabled, it cannot be selected.

When a container object has its enabled property set to false (.F.), all of its contained controls are disabled, too. If the user clicks on any of the controls contained in a disabled Form, for example, no events are triggered.

Disabling a Timer control by setting Enabled to false (.F.) cancels the countdown specified by the Timer control's Interval property.

See Also

Other Resources

Properties
Click Event
DblClick Event
DragDrop Event
DragOver Event
DropDown Event
KeyPress Event
MouseDown Event
MouseMove Event
MouseUp Event
RightClick Event
Scrolled Event
Undock Event


EnableHyperlinks Property

Visual FoxPro 9.0 Language Reference
EnableHyperlinks Property
See Also

Specifies whether hyperlinks are displayed and enabled within an EditBox or TextBox control. Read/write at design and run time.

Object.EnableHyperlinks [ = lExpr ]

Parameters

lExpr

Logical data type. The following table lists the values for lExpr.

lExpr Setting

True (.T.)

Enables display and activation of URL hyperlinks within the control.

False (.F.)

Displays hyperlinks support within the control. (Default)

Remarks

Applies To: EditBox Control | TextBox Control

Setting the global Enable Hyperlinks option in the Options dialog box affects EnableHyperlinks, which you can set at run time using _VFP.EditorOptions. If you turn off hyperlinks globally, Visual FoxPro disregards EnableHyperlinks and does not activate hyperlinks.

As within the editor, the activation of a hyperlink depends on the _VFP.EditorOptions setting (whether click or CTRL+Click goes to the link).

If a form's ShowTips property is set to True (.T.), Visual FoxPro displays a value tip such as "CTRL+Click to follow link" when you move the mouse over the hyperlink. If a value is specified for the ToolTipText property, Visual FoxPro displays the ToolTip text when your mouse moves over any non-hyperlink portion of the control.

See Also

Other Resources

Properties
Editor Tab, Options Dialog Box
_VFP System Variable
EditorOptions Property
ShowTips Property
ToolTipText Property


Encrypted Property

Visual FoxPro 9.0 Language Reference
Encrypted Property
See Also

Specifies if compiled source code in a project is encrypted.

Object.Encrypted[ = lExpression]

Return Value

lExpression

The settings for the Encrypted property are:

Setting Description

True (.T.)

The compiled source code is encrypted. Setting lExpression to true (.T.) provides additional protection for your source code, and is identical to including the ENCRYPT argument in the COMPILE command.

False (.F.)

(Default) The compiled source code isn't encrypted.

Remarks

Applies To: Project Object

Source code in a project includes program and format files, source code in form, label, report, and visual class libraries, and stored procedures in databases. The Encrypted property corresponds to the Encrypted check box on the Project tab of the Project Information dialog box.

See Also

Other Resources

Properties
COMPILE Command
Project Information Dialog Box


ErrorNo Property

Visual FoxPro 9.0 Language Reference
ErrorNo Property
See Also

Specifies the error number for an Exception object. Read/write at run time.

Exception.ErrorNo

Return Value

Numeric data type

Remarks

Applies To: Exception Class

If the exception results from a THROW command that specifies a value for the eUserExpression parameter, the value of ErrorNo is 2071.

Identical to the value returned by the ERROR( ) function and the first element in the array produced by the AERROR( ) function.

See Also

Other Resources

Properties
Exception Object Properties, Methods, and Events
ERROR( ) Function
AERROR( ) Function
SYS(2018) - Error Message Parameter
TRY...CATCH...FINALLY Command
Structured Error Handling


Exclude Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Exclude Property (Visual FoxPro)
See Also

Specifies if a file is excluded from an application (.app), dynamic link library (.dll), or executable file (.exe) when it is built from a project. Available at design time and run time.

Object.Exclude[ = lExpression]

Return Value

lExpression

Specifies if the file is excluded from an .app, .dll, or .exe when it is built. If lExpression is true (.T.), the file is excluded; otherwise the file is included. The file type determines the default value for lExpression. For example, tables are automatically excluded when added to a project.

Remarks

Applies To: File Object

Excluded files appear with a slashed circle before their names in the Project Manager. Excluded files are listed in the Project Manager window for your reference, but you must manually distribute them if the application needs them. You can also exclude a file by choosing Exclude in the Project menu.

See Also

Other Resources

Build Method
Properties
Language Reference


Exclusive Property

Visual FoxPro 9.0 Language Reference
Exclusive Property
See Also

Specifies whether a table associated with a Cursor object is opened exclusively. Available at design time; read/write at run time.

DataEnvironment.Cursor.Exclusive[ = lExpr]

Return Value

lExpr

The settings for the Exclusive property are:

Setting Description

True (.T.)

(Default) The table associated with the Cursor is opened exclusively when the data environment is loaded.

False (.F.)

The table associated with the cursor is not opened exclusively when the data environment is loaded.

Remarks

Applies To: Cursor

Note:
When the Cursor object is accessed using CURSORSETPROP(), the Exclusive property is read-only at run time.

When the data environment is loaded, each table associated with a Cursor can be opened exclusively (no other user in a multiuser environment can access the table) or in shared mode. Use the Exclusive property to specify how the table is accessed.

Note:
If you set the DataSession property to 2 (Private Data Session), the default setting of the Exclusive property for all Cursor objects in the data environment is changed to false (.F.).

For views, the View object itself is always opened in shared mode. However, the tables that define the view are affected by the Exclusive property. For local views, the Visual FoxPro tables that define the view are opened in exclusive or shared mode, depending on the setting of the Exclusive property. The Exclusive property has no effect on remote views.

The Exclusive property mimics the behavior of the USE command's EXCLUSIVE and SHARE clauses.

See Also

Other Resources

DataSession Property
SET EXCLUSIVE Command
USE Command
Properties
Language Reference


FetchAsNeeded Property

Visual FoxPro 9.0 Language Reference
FetchAsNeeded Property
See Also

Specifies how records are fetched. When working with this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions. Read/write.

Note:
Setting FetchAsNeeded applies only to CursorAdapter objects with ODBC or ADO data sources, affects only the next opened cursor, and overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

CursorAdapter.FetchAsNeeded [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

True (.T.)

Fetch records as needed.

False (.F.)

For CursorAdapter objects with ODBC and ADO data sources, the MaxRecords property determines the number of records fetched. For native and XML data sources, all records are fetched.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function
MaxRecords Property


FetchMemo Property

Visual FoxPro 9.0 Language Reference
FetchMemo Property
See Also

Specifies whether memo fields are fetched with view results. When handling this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions. Read/write.

Note:
Setting FetchMemo applies only to CursorAdapter objects with ODBC or ADO data sources and overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

CursorAdapter.FetchMemo [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

True (.T.)

Fetch memo fields with view results.

False (.F.)

Do not fetch memo fields with view results.

Remarks

Applies To: CursorAdapter Class

FetchMemo applies primarily for remote views and setting it does not affect local views. However, you can preset this property for local views that will be upsized.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


FetchMemoCmdList Property

Visual FoxPro 9.0 Language Reference
FetchMemoCmdList Property
See Also

Specifies the commands to use for the Memo fields fetch performed by the DelayedMemoFetch method. Read/write at design time and run time.

CursorAdapter.FetchMemoCmdList[ = cCommands]

Parameters

cCommands

Character data type. cCommands is a comma delimited list of pairs of Memo field names and corresponding Memo field fetch commands. The fetch command must be enclosed in angle brackets (< >). Ensure that there is no white space between the right angle bracket (>) and the comma in multiple Memo field name and fetch command pairs. The following example demonstrates the proper format for two pairs of Memo field names and corresponding Memo field fetch commands:
Copy Code
oCA.FetchMemoCmdList=;
"memofield1 <SELECT memofield1 FROM MyCAMemoFetch WHERE field3=?EVALUATE(this.RefreshAlias +'.field3')>, ;
Memofield2 <SELECT memofield2 FROM MyCAMemoFetch WHERE field3=?EVALUATE(this.RefreshAlias +'.field3')>"
You can specify any command that is supported by the data source and returns exactly one record. If a command for the target Memo field is not specified in the FetchMemoCmdList property, the CursorAdapter attempts to generate the command. The generated command is based on the data source and the CursorAdapter Tables, KeyFieldList, UpdateNameList properties. An error is generated if Visual FoxPro is unable to generate an appropriate command.

Remarks

Applies To: CursorAdapter Class

Only the first result-set is used by the DelayedMemoFetch method.

An error is generated if data conversion from a source field to the target field is not supported. Validation rules for target fields are not executed. If a target record cannot be located, the native Visual FoxPro DelayedMemoFetch implementation marks the target record as DELETED and generates an error.

For ADODB Recordsets, the FetchMemoCmdList property is ignored. The CursorAdapter Tables, KeyFieldList, and UpdateNameList properties are also ignored, and no error is generated if key fields aren't specified. Fields are refreshed using the current field values in the Recordset.

If the lock type for the ADODB Recordset is not adLockBatchOptimistic or adLockUnspecified, the CursorAdapter calls the Resync Method with the ResyncValues parameter set to adResyncAllValues to refresh the record before the field value is retrieved.

See Also

Reference

KeyFieldList Property
Tables Property
UpdateNameList Property


FetchMemoDataSource Property

Visual FoxPro 9.0 Language Reference
FetchMemoDataSource Property
See Also

Specifies the data source used for the DelayedMemoFetch method. Read/write at design time and run time.

CursorAdapter.FetchMemoDataSource[ = DataSource]

Parameters

DataSource

Specifies a reference to an existing data source of permissible data source types. DataSource acts only as a pointer to the actual data source, which must exist at run time. The following table lists the values for DataSource, which depend on the value of the FetchMemoDataSourceType Property.

DataSource DataSource Type

"ADO"

Reference to a valid ActiveX Data Object (ADO) Command object.

"ODBC"

Positive integer that represents or memory variable that contains a valid Open Database Connectivity (ODBC) connection handle.

"Native", null (.NULL.), or empty string ("")

Disregarded.

The default value is the null value (.NULL.).

Remarks

Applies To: CursorAdapter Class

See Also

Reference

DelayedMemoFetch Method
FetchMemoCmdList Property
FetchMemoDataSourceType Property


FetchMemoDataSourceType Property

Visual FoxPro 9.0 Language Reference
FetchMemoDataSourceType Property
See Also

Specifies the data source type used for the DelayedMemoFetch method. Read/write at design time and run time.

CursorAdapter.FetchMemoDataSourceType[ = cExpression]

Return Value

cExpression

Specifies the data source type used for the DelayedMemoFetch method. cExpression is a character expression that evaluates to one of the following:

cExpression Description

Empty string ""

Visual FoxPro disregards the CursorAdapter FetchMemoDataSource property and uses the CursorAdapter DataSource and DataSourceType properties.

ODBC

The data source is ODBC (Open Database Connectivity).

ADO

The data source is ADO (ActiveX Data Objects).

Remarks

Applies To: CursorAdapter Class

See Also

Reference

DataSource Property
DataSourceType Property
DelayedMemoFetch Method
FetchMemoCmdList Property
FetchMemoDataSource Property


FetchSize Property

Visual FoxPro 9.0 Language Reference
FetchSize Property
See Also

Specifies the number of rows progressively fetched from the remote table result set. When handling this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions. Read/write.

Note:
Setting FetchSize applies only to CursorAdapter objects with ODBC or ADO data sources and overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

CursorAdapter.FetchSize [= nValue]

Parameters

nValue

Numeric data type. The nValue parameter has a default value of 100 rows. If nValue is -1, Visual FoxPro retrieves the complete result set, which is limited by the value of the MaxRecords property.

Remarks

Applies To: CursorAdapter Class

FetchSize applies primarily for remote views and setting it does not affect local views. However, you can preset this property for local views that will be upsized.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


FileClass Property

Visual FoxPro 9.0 Language Reference
FileClass Property
See Also

Contains the name of the form class on which a form in a project is based. Read-only at design time and run time.

Object.FileClass

Remarks

Applies To: File Object

The FileClass property applies only to forms in a project, and contains the empty string for other file types.

See Also

Other Resources

FileClassLibrary Property
Type Property
Properties
Language Reference


FileClassLibrary Property

Visual FoxPro 9.0 Language Reference
FileClassLibrary Property
See Also

Contains the name of the class library containing the class on which a form in a project is based. Read-only at design time and run time.

Object.FileClassLibrary

Remarks

Applies To: File Object

The FileClassLibrary property applies only to forms in a project, and contains the empty string for other file types.

See Also

Other Resources

FileClass Property
Type Property
Properties
Language Reference


FillColor Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
FillColor Property (Visual FoxPro)
See Also

Specifies the color used to fill shapes drawn on an object by graphics routines. Available at design time and run time.

Object.FillColor[ = nColor ]
Object.FillColor[ = RGB(nRedValue, nGreenValue, nBlueValue) ]

Return Value

nColor

Specifies a single number to represent the color. By default, FillColor is set to 0 (Black). For more information on color settings, see the BackColor_ForeColor Properties topic.
nRedValue, nGreenValue, nBlueValue

Specifies three separate color intensities that compose the fill color; must be used with the RGB( ) function to consolidate the three color components into one number, which is what the FillColor property is.
Note:
In the Properties window, you can double-click any of the color properties to display the Color dialog box. You can choose or define colors from this dialog box. The red, green, and blue intensities that correspond to the color you choose become the settings for these properties after you close the Color dialog box.

Remarks

Applies To: Form | _SCREEN | Shape

When the FillStyle property is set to its default, 1 (Transparent), the FillColor setting is ignored.

Only an enclosed shape, such as a circle, box, or ellipse can be filled.

Shape objects use the BackColor property to specify the fill color.

See Also

Other Resources

BackColor_ForeColor Properties
BorderColor Property
Box Method
Circle Method
FillStyle Property
ForeColor Property
GETCOLOR( ) Function
RGB( ) Function
Properties
Language Reference


FillStyle Property

Visual FoxPro 9.0 Language Reference
FillStyle Property
See Also

Specifies the pattern used to fill shapes and figures created with the Circle and Box graphics methods. Available at design time and run time.

Object.FillStyle[ = nStyle]

Return Value

nStyle

Specifies the pattern used to fill a shape or figure. The settings for the FillStyle property are:

Setting Description

0

Solid.

1

(Default) Transparent. The FillColor property is ignored.

2

Horizontal Line.

3

Vertical Line.

4

Upward Diagonal. Upward diagonal lines from upper left to lower right.

5

Downward Diagonal. Downward diagonal from lower left to upper right.

6

Cross. Crossed vertical and horizontal lines forming squares.

7

Diagonal Cross.

Remarks

Applies To: Form | _SCREEN | Shape

See Also

Other Resources

BorderStyle Property
Box Method
Circle Method
DrawMode Property
DrawStyle Property
DrawWidth Property
FillColor Property
Properties
Language Reference


Filter Property

Visual FoxPro 9.0 Language Reference
Filter Property
See Also

Excludes records that do not meet the criteria in the specified expression. Available at design time; read/write at run time.

DataEnvironment.Cursor.Filter[ = cExpr]

Return Value

cExpr

Any Visual FoxPro expression, typically an expression that operates on a set of records.

Remarks

Applies To: Cursor | CURSORSETPROP( ) Function

Mimics the behavior of SET FILTER.

Note:
When the Cursor object is accessed using CURSORSETPROP( ), the Filter property is read-only at run time.

See Also

Other Resources

SET FILTER Command
Properties
Language Reference


FirstElement Property

Visual FoxPro 9.0 Language Reference
FirstElement Property
See Also

Specifies the first element of an array to display in a ComboBox or ListBox control. Available at design time and run time.

Control.FirstElement[ = nElement]

Return Value

nElement

Specifies which element in the array is displayed as the first element in the list.

Remarks

Applies To: ComboBox | ListBox

This property is available only when the RowSource is an array (RowSourceType = 5). Note that the FirstElement property only applies to ComboBoxes and ListBoxes with one column.

See Also

Other Resources

NumberOfElements Property
RowSource Property
Properties
Language Reference


FirstNestedTable Property

Visual FoxPro 9.0
FirstNestedTable Property
See Also

Indicates the first nested XMLTable object in the hierarchy of an XML document. Read-only at design time and run time.

XMLTable.FirstNestedTable = oXMLTable

Return Value

oXMLTable

Object reference to the first XMLTable object.
null (.NULL.)

Property not populated. Indicates that there are no nested XMLTables.

Remarks

Applies to: XMLTable Class

See Also

Reference

LoadXML Method
Nest Method
XMLTable Class

Other Resources

Properties


Flags Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Flags Property (Visual FoxPro)
See Also

Specifies flag settings for the CursorAdapter as described by the nFlags parameter in XMLUPDATEGRAM( ) function. Read/write at design time and run time.

Note:
Flags applies only when the CursorAdapter DataSourceType property is set to "XML". The CursorAdapter object passes flags specified by the Flags property when constructing an XML UpdateGram. The CursorAdapter object evaluates Flags only once per update operation.

CursorAdapter.Flags [= nFlags]

Return Value

nFlags

Integer data type. The nFlags parameter specifies nFlag settings from the XMLUPDATEGRAM( ) function and has a default value of 0.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
UpdateGram Property


FontBold, FontItalic, FontStrikethru, FontUnderline Properties

Visual FoxPro 9.0 Language Reference
FontBold, FontItalic, FontStrikethru, FontUnderline Properties
See Also

Specifies whether text has one or more of the following styles: Bold, Italic, Strikethru, or Underline. Available at design time and run time.

Object.FontBold[ = lExpr]Object.FontItalic
[ = lExpr]Object.FontStrikeThru[ = lExpr]Object.FontUnderline[ = lExpr]

Return Value

lExpr

The settings for the font properties are:

Setting Description

True (.T.)

Font style is bold, italic, strikethru, or underline.

False (.F.)

(Default except for FontBold) Font style is not bold, italic, strikethru, or underline.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | EditBox | Form | Grid | Header | Label | ListBox | OptionButton | Page | _SCREEN | Spinner | TextBox

In general, change the FontName property before you set size and style attributes with the FontSize, FontBold, FontItalic, FontStrikethru, and FontUnderline properties. However, when you set TrueType fonts to smaller than 8 points, you should set the point size with the FontSize property, next set the FontName property, and then set the size again with the FontSize property. Windows uses a different font for TrueType fonts that are smaller than 8 points.

Note:
Fonts that are available vary according to your system configuration, display devices, and printing devices. Font-related properties can be set only to values for which actual fonts exist.

Note:
The FontBold property does not apply to the Page object.

See Also

Other Resources

FontName Property
FontSize Property
SetAll Method
Properties
Language Reference


FontCharSet Property

Visual FoxPro 9.0 Language Reference
FontCharSet Property
See Also

Specifies the character set, or language script, of the font used to display text for every object that supports fonts. Read/write at design and run time.

Object.FontCharSet [ = nFontCharSet ]

Parameters

Term | Definition
nFontCharSet | Specifies a numerical value for the language script you want.

Remarks

Applies To: CheckBox Control | Column Object | ComboBox Control | CommandButton Control | EditBox Control | Form Object | Grid Control | Header Object | Label Object | ListBox Control | OptionButton Control | Page Object | _SCREEN System Variable | Spinner Control | TextBox Control

The operating system and font determine the default setting for FontCharSet. Setting FontCharSet to 1 indicates the Visual FoxPro to use the default setting. If you set FontCharSet in the Properties window explicitly by choosing a language script from the Font dialog box, the Properties window displays the specific font. For example, suppose you set the FontCharSet property for a text box to 1 (Western) in the Properties window. If you open the Font Picker Dialog Box and select 0 (Western), the Properties window displays 0 (Western) because it was set explicitly.

Tip:
To reset the property to the default setting, right-click the property in the Properties window and click Reset to Default.

Visual FoxPro attempts to retrieve the character set identifier for the font you specify. If Visual FoxPro cannot find the character set identifier, or if you pass an invalid FontCharSet value for a particular font set, the Windows font manager makes the appropriate substitution using the Default character set, usually ANSI or Symbol.

Fonts support only certain language scripts. To choose a language script that a font can support, select the FontCharSet property in the Properties window and click the ellipsis (...) button that appears to open the Font dialog box. You can select a language script from the Script drop-down list. You can also change the font, size, and style. Visual FoxPro updates the font properties with the changed values.

If you change the font to one for which the current FontCharSet value is not supported, Visual FoxPro resets the FontCharSet property.

If the Style property for a Label is set to 3 (Themed), the FontCharSet property is ignored. If the Themes property is set to True (.T.) for a grid, the FontCharSet property for the grid Header is ignored. To display the grid Header using the FontCharSet property, set Themes of the grid to False (.F.).

The GETFONT( ) function supports the passing or retrieving of a font script.

See Also

Other Resources

Properties
GETFONT( ) Function
Style Property
AFONT( ) Function


FontCondense, FontExtend Properties

Visual FoxPro 9.0 Language Reference
FontCondense, FontExtend Properties
See Also

Available in Visual FoxPro for Macintosh only.

See Also

Other Resources

Properties


FontName Property

Visual FoxPro 9.0 Language Reference
FontName Property
See Also

Specifies the name of the font used to display text. Available at design time and run time.

Object.FontName[ = cName]

Return Value

cName

Specifies the name of the font. The default is Arial.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | EditBox | Form | Grid | Header | Label | ListBox | OptionButton | Page | _SCREEN | Spinner | TextBox

The default FontSize property setting is 9 points. Available fonts vary according to your system configuration. Font-related properties can be set only to values for which fonts exist. At design time, a list of available fonts is displayed when you select the FontName property in the Properties window and click the down arrow to the right of the Property Settings box.

In general, change FontName before setting size and style attributes with the FontSize, FontBold, FontItalic, FontStrikethru, and FontUnderline properties.

See Also

Other Resources

Font Style Properties
FontSize Property
Properties
Language Reference


FontOutline Property

Visual FoxPro 9.0 Language Reference
FontOutline Property
See Also

Included for compatibility with the Macintosh.

See Also

Other Resources

Properties


FontShadow Property

Visual FoxPro 9.0 Language Reference
FontShadow Property
See Also

Included for compatibility with the Macintosh.

See Also

Other Resources

Properties


FontSize Property

Visual FoxPro 9.0 Language Reference
FontSize Property
See Also

Specifies the font size for text displayed with an object. Available at design time and run time.

Object.FontSize[ = nSize]

Return Value

nSize

Specifies the size of the font in points. The default font size is 9 points.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | EditBox | Form | Grid | Header | Label | ListBox | OptionButton | Page | _SCREEN | Spinner | TextBox

The maximum value for nSize is 127 points. There are 72 points in 1 inch.

In general, you should change the FontName property before you set size and style attributes with the FontSize, FontBold, FontItalic, FontStrikethru, and FontUnderline properties. However, when you set TrueType fonts to smaller than 8 points, you should set the point size with the FontSize property, next set the FontName property, and then set the size again with the FontSize property. The Windows environment uses a different font for TrueType fonts that are smaller than 8 points.

Note:
Available fonts vary according to your system configuration and printing devices. Font-related properties can be set only to values for which fonts exist.

See Also

Other Resources

Font Style Properties
Properties
Language Reference


ForceCloseTag Property

Visual FoxPro 9.0 Language Reference
ForceCloseTag Property
See Also Example

Specifies whether to replace single empty element tags with a set of empty element open and close tags. You can use the ForceCloseTag if you search for open and close tags when parsing XML or if you want to increase readability.

ForceCloseTag applies when executing the XMLAdapter ToXML method, which creates XML consistent with its setting.

XMLAdapter.ForceCloseTag [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

Does not replace single empty element tags with a set of empty element open and close tags. (Default)

True (.T.)

Replaces single empty element tags with a set of empty element open and close tags.

Remarks

Applies To: XMLAdapter Class

Example

The following example contains an empty element tag, <col1/>:

Copy Code
<?xml version = "1.0" encoding="Windows-1252" standalone="yes"?>
<VFPData>
   <etest>
      <col1>One</col1>
   </etest>
   <etest>
      <col1/>
   </etest>
</VFPData>

Setting ForceCloseTag to True (.T.) replaces the single empty element tag with a set of valid empty element open and close tags, <col1></col1>.

Copy Code
<?xml version = "1.0" encoding="Windows-1252" standalone="yes"?>
<VFPData>
   <etest>
      <col1>One</col1>
   </etest>
   <etest>
      <col1></col1>
   </etest>
</VFPData>

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events


Format Property

Visual FoxPro 9.0 Language Reference
Format Property
See Also

Specifies the input and output formatting of a control's Value property. Available at design time and run time.

Control.Format[ = cFunction]

Return Value

cFunction

Specifies the character constraints for data entry and formatting for display. The following table lists the valid cFunction values for the appropriate controls.

cFunction Description

EditBox control

K

Selects all the text when the control gets focus.

Spinner control

$

Displays the currency symbol.

^

Displays numeric data using scientific notation.

K

Selects all the text when the control gets the focus.

L

Displays leading zeros instead of spaces in the text box.

R

Displays the format mask for the text box that is specified in the InputMask property.

The mask formats data for easier entry and clearer display (for example, if the mask is 99-999, the number 12345 is displayed as 12-345), but is not stored as part of the data. Use only with character or numeric data.

TextBox control and Column object

!

Converts alphabetic characters to uppercase. Use with data of Character type only.

$

Displays the currency symbol. The ControlSource property must specify a numeric source for the text box.

^

Displays numeric data using scientific notation. The ControlSource property must specify a numeric source for the text box.

A

Allows alphabetic characters only with no spaces or punctuation marks.

D

Uses the current SET DATE format.

E

Edits Date values as British dates.

F

Prevents Varchar values from being padded with trailing spaces in text boxes or Varbinary values from being padded with trailing zeroes (0s).

Note:
For text boxes bound to data with Varchar type, the MaxLength property must be set to a nonzero value to permit input for the desired number of characters.

Note:
When you drag a field with Varchar type to a form, the created text box's Format property is set to "F", and the MaxLength property is set to the maximum length for the Varchar field. When you drag a Grid control to a form and create TextBox controls for columns with Varchar type, the Format property is set to "F", and the MaxLength property is set to the maximum length for the Varchar field.

Note:
When you drag a field with Varbinary type to a form or when you drag a Grid control to a form and create TextBox controls for columns with Varbinary type, the following occur:

  • Format property is set to "F".

  • MaxLength property is set to the maximum length multiplied by 2 for the Varchar field.

  • InputMask property is filled with "H" up to the value of the MaxLength property.

K

Selects all the text when the control gets the focus.

L

Displays leading zeros instead of spaces in the text box. The ControlSource property must specify a numeric source for the text box.

M

Included for backward compatibility.

R

Displays the format mask for the text box that is specified in the InputMask property.

The mask formats data for easier entry and clearer display. For example, if the mask is 99-999, the number 12345 is displayed as 12-345 but is not stored as part of the data. Use only with Character or Numeric data.

T

Trims leading and trailing blanks from the input field.

YS

Displays Date values in a short date format determined by the Windows Control Panel short date setting.

YL

Displays Date values in a long date format determined by the Windows Control Panel long date setting.

EditBox control, TextBox control, Column object, and Spinner control

Z

Displays the value as blank if it is 0, except when the control has focus.

Dates are also supported in these controls. The / / date delimiters are not displayed unless the control has focus.

Remarks

Applies To: Column | ComboBox | EditBox | Spinner | TextBox

The Format property specifies a behavior for the entire input field. You can mix several Format codes, but they always affect everything in the input field. This property contrasts to the InputMask property in which each entry in the input mask corresponds to an entry in the input field.

The Format property mimics the behavior of the FUNCTION clause in the @ ... GET and @ ... EDIT commands.

See Also

Reference

Value Property

Other Resources

DynamicInputMask Property
InputMask Property
Properties
Language Reference


FormattedOutput Property

Visual FoxPro 9.0 Language Reference
FormattedOutput Property
See Also

Generates XML as formatted output or as a single continuous string.

FormattedOutput applies when executing the XMLAdapter ToXML method, which creates XML consistent with its setting.

XMLAdapter.FormattedOutput [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

True (.T.)

Display XML as formatted output. (Default)

False (.F.)

Display XML output as a single continuous string.

Remarks

Applies To: XMLAdapter Class

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
ToXML Method


FormCount Property

Visual FoxPro 9.0 Language Reference
FormCount Property
See Also

Contains the number of forms in a form set. Not available at design time; read-only at run time.

Object.FormCount

Remarks

Applies To: FormSet | _SCREEN

You can use this property to cycle through all the forms in a form set and do some action.

See Also

Other Resources

Forms Property
Properties
Language Reference


Forms Property

Visual FoxPro 9.0 Language Reference
Forms Property
See Also

An array to access individual forms in a form set. Not available at design time; read-only at run time.

Object.Forms(nIndex)

Return Value

nIndex

Uniquely identifies a form in a form set.

Remarks

Applies To: FormSet | _SCREEN

Use the Forms property to change the property settings of forms in a form set without using the Name property of the forms. You can use the Forms property in conjunction with the FormCount property to step through all the forms in a form set and perform an action. For example, the following code changes the captions of all the forms in a form set:

Copy Code
FOR x = 1 TO THISFORMSET.FormCount
   THISFORMSET.Forms(x).Caption = THISFORMSET.Forms(x).Caption;
      + "[Read Only]"
ENDFOR

See Also

Other Resources

FormCount Property
Objects Collection
Properties
Language Reference


FractionDigits Property

Visual FoxPro 9.0 Language Reference
FractionDigits Property
See Also

For Numeric data types, FractionDigits specifies the number of digits to the right of the decimal point.

XMLField.FractionDigits

Return Value

Numeric data type. FractionDigits specifies the number of digits to the right of the decimal point. If none exists or if FractionDigits is not applicable, the value of FractionDigits is -1.

Remarks

Applies To: XMLField Class

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events
Visual FoxPro and XML Schema Data Type Mapping


FRXDataSession Property

Visual FoxPro 9.0
FRXDataSession Property
See Also

Provides the datasession ID in which the Report Engine places a private copy of the report or label file (frx or lbx) for ReportListener use during a report run.

ReportListener.FRXDataSession

Return Value

Integer data type.

The default value is -1 when you create the instance of ReportListener, indicating that the special datasession does not exist at this point.

Remarks

Applies To: ReportListener Object.

This property contains a valid value (an existing datasession's ID) from LoadReport through UnloadReport. However, the Report Engine does not open the read-only copy of the report or label file until after the LoadReport event and before the BeforeReport event. This gives you a chance to manipulate the report or label file before the Report Engine reads the report or label file layout information and begins the report run. For more information on the order of events during run time processing, see Understanding Visual FoxPro Object-Assisted Reporting.

Important
The copy of the report or label file provided by the Report Engine in this data session during the run is read-only. The ReportEngine and native ReportListener do not refer to the report or label file during the report run, once they have read in its layout information during report start-up procedures. If the cursor were read/write, and if you made changes to its data, the changes would not be significant to the native Visual FoxPro reporting components. The copy of the report or label file is purely for your reference while the report executes. You can change certain aspects of how the report renders various layout objects, using ReportListener events. For more information, see AdjustObjectSize Event and EvaluateContents Event.

See Also

Tasks

How to: Use Data Sessions

Reference

ReportListener Object Properties, Methods, and Events
SET DATASESSION Command

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)
Extending Reports at Run Time


FullName Property

Visual FoxPro 9.0 Language Reference
FullName Property
See Also

Contains the file name of an instance of Visual FoxPro and the name of the directory from which the instance of Visual FoxPro was started. Read-only at run time.

ApplicationObject.FullName

Remarks

Applies To: Application Object | _VFP System Variable

Use the FullName property to determine the directory from which an instance of Visual FoxPro was started.

See Also

Other Resources

HOME( ) Function
Properties
Language Reference


GDIPlusGraphics Property

Visual FoxPro 9.0
GDIPlusGraphics Property
See Also Example

Provides access to the GDIPlus Graphics object the ReportListener uses to handle output.

ReportListener.GDIPlusGraphics

Return Value

Integer data type.

The default is 0. This property is readonly.

Remarks

Applies To: ReportListener Object.

This property gives derived ReportListener-based classes a way to inject their own output into the output stream, by accessing the baseclass ReportListener's handle to this stream.

Important
When code written in Visual FoxPro accesses this handle, it must DECLARE and use functions based in the same file copy of GDIPLUS.DLL that the product uses in native code. To ensure this, use the syntax IN GDIPLUS.DLL with no explicit path in your DECLARE DLL statements.

Visual FoxPro ships with a number of Foundation Classes designed to make working with the GDI+ API easier to use. For more information, see GDI Plus API Wrapper Foundation Classes.

Example

This example adjusts all text in the Page Header band of a report by rotating it to an angle, similar to an angled set of headers in a spreadsheet. Such an approach is useful when you have a report with many columns and the labels for each column header would ordinarily take up much more room than the contents of each column requires in the Detail band.
Copy Code
LOCAL oListener
oListener = CREATEOBJECT("rotateText")
oListener.ListenerType = 1
REPORT FORM ? OBJECT oListener

#define FRX_OBJCOD_PAGEHEADER 1

DEFINE CLASS rotateText AS ReportListener

   IsInPageHeader = .F.

   PROCEDURE Init()
      DECLARE integer GdipRotateWorldTransform In GDIPlus.Dll ;
            integer graphics,single angle,integer enumMatrixOrder_order
      DECLARE integer GdipTranslateWorldTransform In GDIPlus.Dll ;
            integer graphics,single dx,single dy,;
            integer enumMatrixOrder_order
      DECLARE integer GdipSaveGraphics IN GDIPlus.DLL ;
          integer graphics, integer @xx
      DECLARE integer GdipRestoreGraphics IN GDIPlus.DLL ;
          integer graphics, integer xx
   ENDPROC

   PROCEDURE BeforeBand(nBandObjCode, nFRXRecNo)
      DODEFAULT(nBandObjCode, nFRXRecNo)
      IF (nBandObjCode = FRX_OBJCOD_PAGEHEADER)
         THIS.IsInPageHeader = .T.
      ENDIF
   ENDPROC

   PROCEDURE AfterBand(nBandObjCode, nFRXRecNo)
      IF (nBandObjCode = FRX_OBJCOD_PAGEHEADER)
         THIS.IsInPageHeader = .F.
      ENDIF
      DODEFAULT(nBandObjCode, nFRXRecNo)
   ENDPROC

   PROCEDURE Render(nFRXRecNo, nLeft, nTop, nWidth, nHeight,;
       nObjectContinuationType, cContentsToBeRendered, GDIPlusImage)
      LOCAL xx,x,y, z
      xx = 0
      IF THIS.IsInPageHeader
         * get appropriate versions of coords
         x = nLeft
         y = nTop

         * save the current state of the graphics handle
         z = GdipSaveGraphics(this.GDIPlusGraphics, @xx)

         * now move the 0,0 point to where we'd like it to be
         * so that when we rotate we're rotating around the
         * appropriate point
         z = GdipTranslateWorldTransform(this.GDIPlusGraphics,x,y,0)
         * should check z here -- will be 0 if no error occurred

         * now change the angle at which the draw will occur
         z = GdipRotateWorldTransform ( this.GDIPlusGraphics,-20,0)
         * should check z as above

         * restore the 0,0 point
         z = GdipTranslateWorldTransform(this.GDIPlusGraphics,-x,-y, 0)
         * should check z as above

      ENDIF

      * explicitly call the baseclass behavior
      * when we are ready for it
      DODEFAULT(nFRXRecNo, nLeft, nTop, nWidth, nHeight, ;
               nObjectContinuationType, cContentsToBeRendered, ;
               GDIPlusImage)

      * put back the state of the graphics handle
      IF THIS.IsInPageHeader
         GdipRestoreGraphics(this.GDIPlusGraphics, xx)
      ENDIF

      * don't let the baseclass render
      * when and how it would otherwise do it
      NODEFAULT

   ENDPROC

ENDDEFINE

See Also

Reference

DECLARE - DLL Command

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)
Extending Report Output Functionality


GridLineColor Property

Visual FoxPro 9.0 Language Reference
GridLineColor Property
See Also

Specifies the color of the lines separating cells in a Grid control. Available at design time; read/write at run time. There are two versions of the syntax.

Grid.GridLineColor[ = nColor]
Grid.GridLineColor = RGB(nRedValue, nGreenValue, nBlueValue)

Return Value

nColor

Specifies a single number to represent the color. By default, GridLineColor is set to 0 (Black).
nRedValue, nGreenValue, nBlueValue

Specifies three separate color intensities that compose the Grid's line color; must be used with the RGB( ) function to consolidate the three color components into one number, which is what the GridLineColor property is.
Note:
the Properties window, you can double-click any of the color properties to display the Color dialog box. You can choose or define colors from this dialog box. The red, green, and blue intensities that correspond to the color you choose become the settings for these properties after you close the Color dialog box.

Remarks

Applies To: Grid

See Also

Other Resources

GridLines Property
GridLineWidth Property
Properties
Language Reference


GridLines Property

Visual FoxPro 9.0 Language Reference
GridLines Property
See Also

Determines whether horizontal and vertical lines are displayed in the Grid control. Available at design time; read/write at run time.

Grid.GridLines[ = nSetting]

Return Value

nSetting

The settings for the GridLines property are:

Setting Description

0

None. No grid lines.

1

Horizontal. Horizontal grid lines only.

2

Vertical. Vertical grid lines only.

3

(Default) Both. Both horizontal and vertical grid lines.

Remarks

Applies To: Grid

See Also

Other Resources

GridLineColor Property
GridLineWidth Property
Properties
Language Reference


GridLineWidth Property

Visual FoxPro 9.0 Language Reference
GridLineWidth Property
See Also

Specifies the thickness, in pixels, of the lines separating cells in a Grid control. Available at design time; read/write at run time.

Grid.GridLineWidth[ = nWidth]

Return Value

nWidth

Specifies the thickness of the line separating cells in a Grid control. The default value for nWidth is 1, and the minimum and maximum values are 1 and 40 respectively.

Remarks

Applies To: Grid

See Also

Other Resources

GridLineColor Property
GridLines Property
Properties
Language Reference


HalfHeightCaption Property

Visual FoxPro 9.0 Language Reference
HalfHeightCaption Property
See Also

Specifies whether the caption of a form is half the normal height. Available at design time and run time.

Object.HalfHeightCaption[ = lExpr]

Return Value

lExpr

The settings for the HalfHeightCaption property are:

Setting Description

True (.T.)

The form's caption is half the normal height.

False (.F.)

(Default) The form's caption is normal height.

Remarks

Applies To: Form | _SCREEN | Height Property

Menus on SDI forms (ShowWindow = 2) are not supported when the HalfHeightCaption property of the form is set to true (.T.).

See Also

Reference

ShowWindow Property

Other Resources

Caption Property
Properties
Language Reference


HeaderClass Property

Visual FoxPro 9.0 Language Reference
HeaderClass Property
See Also

Specifies the name of the member class to use when adding new header member objects to a Column container. Read/write at design time and run time.

The HeaderClass property is used instead of MemberClass for a Column parent container. For more information about the MemberClass property, see MemberClass Property.

Note:
If the member class is based on a class that is stored in a program (.prg) file, make sure that the compiled program (.fxp) file is synchronized with the .prg file.

Column.HeaderClass [ = cClassName ]

Return Value

cClassName

Specifies the name of a member class in a program (.prg) file.

Remarks

Applies To: Column Object

You cannot edit or create a subclass of the Header class in a visual class library (.vcx). You need to use a program (.prg) file to define a Header class.

The Column class can contain only one header; therefore, no header count property is associated with the column.

At run time, changing the HeaderClassLibrary and HeaderClass properties at run time does not affect the header. You can change the header only by using the AddObject or ' methods, which replaces the current header with the new header.

See Also

Other Resources

Properties
Member Classes
MemberClass Property
HeaderClassLibrary Property
AddObject Method
NewObject Method


HeaderClassLibrary Property

Visual FoxPro 9.0 Language Reference
HeaderClassLibrary Property
See Also

Specifies the class library containing the member class associated with the HeaderClass property. Read/write at design time and run time.

HeaderClassLibrary is used instead of MemberClassLibrary for a Column parent container. For more information, see MemberClassLibrary Property.

Column.HeaderClassLibrary [= cClassFile]

Return Value

Character string. The cClassFile parameter specifies the program (.prg) file name containing the member class definition specified by HeaderClass.

Remarks

Applies To: Column Object

Visual FoxPro includes the HeaderClassLibrary program (.prg) in the project during a project build.

If you set HeaderClassLibrary at run time, you must use the full file name including its extension.

See Also

Other Resources

Properties
Member Classes
HeaderClass Property
MemberClassLibrary Property
MemberClassLibrary Property


HeaderHeight Property

Visual FoxPro 9.0 Language Reference
HeaderHeight Property
See Also

Specifies the height of column headers in the Grid control. Available at design time; read/write at run time.

Header.HeaderHeight[ = nHeight]

Return Value

nHeight

The height of the header, specified in pixels.

Remarks

Applies To: Grid

See Also

Other Resources

ScaleMode Property
Height Property
HEADER( ) Function
Properties
Language Reference


Height Property

Visual FoxPro 9.0 Language Reference
Height Property
See Also Example

Specifies the height of an object on the screen. Available at design time and run time.

Object.Height[ = nHeight]

Return Value

nHeight

Specifies the object's height measured in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | Custom | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | PageFrame | _SCREEN | Shape | Spinner | TextBox | Timer | ToolBar

For forms, the Height measurement does not include the borders and title bar. Also, if the ScrollBars property is set to enable scroll bars, Height does not include space taken up by the scroll bar when it appears. In Visual FoxPro, the maximum height of a form has been increased to approximately 32,000 pixels.

For controls, the height is measured from the outside of the control's border.

The value for this property changes as the object is sized by the user or by code.

Use the Height and Width properties for calculations based on an object's total area.

Note:
The Height property is read-only when it applies to a control contained in a Column object.

Example

The following example demonstrates how the Height property is used specify the height of three command buttons on a form.

The AddObject method is used to add a Line control and three command buttons to a form. The Height property specifies the vertical height of each command button.
Copy Code
frmMyForm = CREATEOBJECT('form')  && Create a form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('shpLine','Line')  && Add a Line control to the form
frmMyForm.AddObject('cmdCmndBtn1','cmdMyCmndBtn1')  && Up Cmnd button
frmMyForm.AddObject('cmdCmndBtn2','cmdMyCmndBtn2')  && Down Cmnd button
frmMyForm.AddObject('cmdCmndBtn3','cmdMyCmndBtn3')  && Quit Cmnd button

frmMyForm.shpLine.Visible = .T.  && Make Line control visible
frmMyForm.shpLine.Top = 20  && Specify Line control row
frmMyForm.shpLine.Left = 125  && Specify Line control column

frmMyForm.cmdCmndBtn1.Visible =.T.  && Up Command button visible
frmMyForm.cmdCmndBtn2.Visible =.T.  && Down" Command button visible
frmMyForm.cmdCmndBtn3.Visible =.T.  && Quit Command button visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmndBtn1 AS COMMANDBUTTON  && Create Command button
   Caption = 'Slant \<Up'  && Caption on the Command button
   Left = 50  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='/'  && Slant up
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn2 AS CommandButton  && Create Command button
   Caption = 'Slant \<Down'  && Caption on the Command button
   Left = 200  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='\'  && Slant down
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn3 AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 150  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close form
ENDDEFINE

See Also

Other Resources

Left Property
Move Method
ScaleMode Property
Top Property
Width Property
Properties
Language Reference


HelpContextID Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
HelpContextID Property (Visual FoxPro)
See Also

Specifies a context ID for a topic in a Help file to provide context-sensitive Help for the object. Available at design time and run time.

Object.HelpContextID[ = nContextID]

Return Value

nContextID

Specifies the context ID number of a topic in a Help file. The valid range for context ID numbers is range 0 to 268,435,455.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | _SCREEN | Server Object | Shape | Spinner | TextBox | ToolBar

To create context-sensitive Help for an object in your application, you must assign the same context number to both the object and the associated Help topic when you create the Help file.

If you have created Help for your application, Visual FoxPro calls the Help file and requests the topic identified by the current context ID number. You can specify a Help file with SET HELP TO, and you can specify a key to activate the Help file with ON KEY LABEL. The Help compiler required to create graphical-style help is included with Visual FoxPro.

The current context ID number is the setting of the HelpContextID property for the object that has the focus. If a nonzero current context number is not found, the main contents screen of the Help file is displayed.

For a server object, the HelpContextID property specifies the context ID for the type library created for the server. The ServerHelpFile property specifies the Help file containing the help topic corresponding to the context ID.

See Also

Other Resources

ServerHelpFile Property
SET HELP Command
SET TOPIC Command
Properties
Language Reference


HideSelection Property

Visual FoxPro 9.0 Language Reference
HideSelection Property
See Also

Specifies whether selected text appears selected when a control loses focus. Available at design time and run time.

Control.HideSelection[ = lExpr]

Return Value

lExpr

The settings for the HideSelection property are:

Setting Description

True (.T.)

(Default) Selected text does not appear selected when the control loses the focus.

False (.F.)

Selected text appears selected when the control loses the focus.

Remarks

Applies To: ComboBox | EditBox | Spinner | TextBox

You can use this property to indicate the text that is selected while another form or a dialog box has the focus — for example, in a spelling-check routine.

See Also

Other Resources

DisabledBackColor, DisabledForeColor Properties
GotFocus Event
LostFocus Event
Properties
Language Reference


Highlight Property

Visual FoxPro 9.0 Language Reference
Highlight Property
See Also

Specifies whether the cell with the focus in a Grid control appears selected. Available at design time and read/write at run time.

Grid.Highlight [= lExpr ]

Return Value

lExpr

The settings for the Highlight property are:

Setting Description

True (.T.)

The cell is marked (highlighted) as selected. (Default)

False (.F.)

The cell is not selected.

Remarks

Applies To: Grid Control

If the HighLight property is set to true (.T.), you can use it in conjunction with a Column's SelectOnEntry property to determine if the entire cell appears selected. If you set the HighLight property to false (.F.), the SelectOnEntry property is ignored.

See Also

Other Resources

HighlightRow Property
SelectOnEntry Property
HighlightForeColor Property
HighlightBackColor Property
HighlightStyle Property
Properties
Language Reference


HighlightBackColor Property

Visual FoxPro 9.0 Language Reference
HighlightBackColor Property
See Also

Specifies the background color of a Grid row when it is selected. A grid's HighlightBackColorproperty applies only when the grid's HighlightStyle property is set to a value greater than 0. Read/write at design and run time.

Grid.HighlightBackColor [= nColor ]

Parameters

nColor

Numeric data type. HighlightBackColor specifies an integer representing a single color value. Visual FoxPro derives the default color setting from the Windows operating system color setting for Selected Items. For more information about valid color values, see BackColor, ForeColor Properties.

Remarks

Applies To: Grid Control | BROWSE Command

If HighlightStyle contains a value greater than 0, Visual FoxPro defaults to displaying HighlightBackColor as a 50% lighter gradient fill. If you override the HighlightBackColor setting, Visual FoxPro does not apply any gradient effect.

For more information, see HighlightForeColor Property.

See Also

Reference

HighlightBackColor Property

Other Resources

Properties
HighlightStyle Property
AllowCellSelection Property
ResetToDefault Method
DynamicBackColor, DynamicForeColor Properties
Highlight Property
HighlightRow Property
HighlightStyle Property


HighlightForeColor Property

Visual FoxPro 9.0 Language Reference
HighlightForeColor Property
See Also

Specifies the foreground or highlight color of the text in a Grid row when it is selected. A grid's HighlightForeColorproperty applies only when the grid's HighlightStyle property is set to a value greater than 0. Read/write at design and run time.

Grid.HighlightForeColor [= nColor ]

Parameters

nColor

Numeric data type. HighlightForeColor specifies an integer representing a single color value. Visual FoxPro derives the default color setting from the Windows operating system font color setting for Selected Items. For information about valid color values, see BackColor, ForeColor Properties.

Remarks

Applies To: Grid Control | BROWSE Command

In Windows XP, you can find the Selected Items font color setting in the Advanced Appearance dialog box. To open the Advanced Appearance dialog box, right-click the Windows desktop, click Properties. In the Display Properties dialog box, click the Appearance tab, then Advanced, and select Selected Items from the Item list. The operating system font color is specified in the Color box to the right of the Font box.

In Windows 2000, you can set the font color for Selected Items information on the Appearance tab.

Note:
Changing the font color for Selected Items changes the setting for all applications.

You can select a color by typing the RGB value in the Properties window property settings box or display the Color dialog box by double-clicking the property in the Properties window properties list. The RGB value for the color you select in the Color dialog box becomes the setting after you close the Color dialog box.

After setting HighlightStyle to a value greater than 0, highlighting remains in effect until HighlightStyle is set to 0. If HighlightStyle is set to a value of 2, only the highlight colors persist. Selected items display only when a grid has focus.

Highlighting affects all cells in a row except the currently selected one, unless the grid's AllowCellSelection property is set to False (.F.), and overrides color property settings such as BackColor and DynamicBackColor settings for any column in the grid.

The following example shows how you can interchange the Windows Selected Items and Selected Items font colors for HighlightForeColor and HighlightBackColor:

Copy Code
tmpColor1 = THIS.GrdCustomer.HighlightBackColor
tmpColor2 = THIS.GrdCustomer.HighlightForeColor
THIS.GrdCustomer.HighlightBackColor = tmpColor2
THIS.GrdCustomer.HighlightForeColor = tmpColor1

See Also

Other Resources

Properties
HighlightStyle Property
AllowCellSelection Property
HighlightBackColor Property
ResetToDefault Method
DynamicBackColor, DynamicForeColor Properties
Highlight Property
HighlightRow Property


HighlightRow Property

Visual FoxPro 9.0 Language Reference
HighlightRow Property
See Also

Specifies whether the current row and cell in a Grid control is highlighted. Available at design time and read/write at run time.

Grid.HighlightRow [= lExpr]

Return Value

lExpr

The settings for the HighlightRow property are:

Setting Description

True (.T.)

Current row and cell are highlighted. (Default)

False (.F.)

Current row and cell are not highlighted.

Remarks

Applies To: Grid Control

See Also

Other Resources

Highlight Property
HighlightForeColor Property
HighlightBackColor Property
HighlightStyle Property
Properties
Language Reference


HighlightRowLineWidth Property

Visual FoxPro 9.0 Language Reference
HighlightRowLineWidth Property
See Also

Specifies the thickness of the border around the selected Grid row.

Grid.HighlightRowLineWidth [= nValue]

Parameters

nValue

Specifies the horizontal line thickness of the border in pixels. The minimum value is 0, the maximum value is 7, and the default value is 1. The vertical line thickness is not displayed at design time, but is a run time visual effect.

Remarks

Applies To: Grid

This property is effective only when the HighlightRow property is set to True (.T.).

See Also

Other Resources

HighlightRow Property
Properties
Language Reference


HighlightStyle Property

Visual FoxPro 9.0 Language Reference
HighlightStyle Property
See Also

Specifies whether the selected row in a Grid remains highlighted when changing the focus to another control in the form. Read/write at design and run time.

HighlightStyle works with the HighlightForeColor and HighlightBackColor properties in determining whether the selected row is highlighted, and whether it remains highlighted when you press the TAB key to move around in the grid, or when you click outside the grid to move focus to another control.

Grid.HighlightStyle [ = nValue ]

Parameters

nValue

Numerical data type. The following table describes the settings for nValue.

nValue

0

No color highlighting for grid row (Default)

1

Enable highlighting for current row.

2

Enable highlighting for current row and persist when grid is not the current active control.

Remarks

Applies To: Grid Control

If HighlightStyle contains a value greater than 0, the default color of HighlightBackColor appears as a 50% lighter gradient fill.

If HighlightStyle is set to a value of 2, only the highlight colors persist. Selected items display only when a grid has focus.

When the AllowCellSelection property is set to False (.F.), the current row is always highlighted when HighlightStyle is set to a value of 0.

If a column's Sparse property is set to False (.F.), the column will not be highlighted, when the grid's HighlightStyle property is set to 1 or 2.

See Also

Reference

AllowCellSelection Property

Other Resources

Properties
HighlightForeColor Property
Highlight Property
HighlightBackColor Property
HighlightRow Property


HomeDir Property

Visual FoxPro 9.0 Language Reference
HomeDir Property
See Also

Specifies the home directory for a project.

Object.HomeDir[ = cDirectory]

Return Value

cDirectory

Specifies the home directory for the project. The default value is the directory in which the project file (.pjx) is located.

Remarks

Applies To: Project Object

The home directory for a project is the relative path for all the files in the project. The HomeDir property corresponds to the directory in the Home text box on the Project tab of the Project Information dialog box.

See Also

Other Resources

CURDIR( ) Function
Project Information Dialog Box
Properties
Language Reference


HostName Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
HostName Property (Visual FoxPro)
See Also

Returns or sets the user-readable host name of your Visual FoxPro application. Available at design time; read/write at run time.

Control.HostName [ = cName]

Return Value

cName

Returns or sets a string expression specifying the host name.

Remarks

Applies To: OLE Bound Control | OLE Container Control

When editing an object, the HostName property setting can be displayed in the object's window title. However, some applications that provide objects do not display the HostName.

See Also

Other Resources

DocumentFile Property
Properties
Language Reference


Hours Property

Visual FoxPro 9.0 Language Reference
Hours Property
See Also

Specifies whether the hours portion of a DateTime value is displayed in 12- or 24-hour time format. Available at design time and run time.

Object.Hours[ = nValue]

Return Value

nValue

One of the following settings:

Setting Description

0

(Default) The SET HOURS setting determines whether the hours portion of a DateTime value is displayed in 12- or 24-hour time format. If SET HOURS is 12, the hours portion of a DateTime value is displayed in 12-hour time format. If SET HOURS is 24, the hours portion of a DateTime value is displayed in 24-hour time format.

12

The hour portion of the DateTime value is displayed in a 12-hour time format.

24

The hour portion of the DateTime value is displayed in a 24-hour time format.

Remarks

Applies To: TextBox

The Hours property setting is ignored if the DateFormat property is set to Short or Long.

See Also

Other Resources

Century Property
DateFormat Property
DateMark Property
Seconds Property
SET HOURS Command
StrictDateEntry Property
Properties
Language Reference


HScrollSmallChange Property

Visual FoxPro 9.0 Language Reference
HScrollSmallChange Property
See Also

Specifies the increment a form scrolls in the horizontal direction when you click on a horizontal scroll arrow. Available at design time and run time.

Object.HScrollSmallChange[ = nExpression]

Return Value

nExpression

Specifies the increment for horizontal scrolling. The unit of measure is determined by the Scalemode property setting. The default increment is 10 pixels when the Scalemode property is set to 3 - Pixels.

Remarks

Applies To: Form

See Also

Other Resources

ScaleMode Property
ScrollBars Property
VScrollSmallChange Property
Properties
Language Reference


hWnd Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
hWnd Property (Visual FoxPro)
See Also

Returns a handle to Forms and user-defined Toolbar objects.

Object.hWnd

Remarks

The Microsoft Windows operating environment identifies each form in an application by assigning it a handle, or hWnd. The hWnd property is used with Windows API calls. Many Windows operating environment functions require the hWnd of the active window as an argument.

The handle returned by the hWnd property is assigned to the form at run time. Therefore, the handle might be a different value every time the form runs, but the value remains constant during the life of the form. If the same form runs multiple times, each instance of the form can have a different hWnd value.

hWnd is available in user-defined Forms and Toolbar objects and is read-only at both run and design-time.

See Also

Other Resources

Form Object
Toolbar Object
_WhToHwnd( ) API Library Routine
Properties
Language Reference


Icon Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Icon Property (Visual FoxPro)
See Also

For forms, specifies the icon displayed for a form at run time when the form is minimized. Available at design time and run time.

For a project object, specifies the icon displayed for a distributed .exe application.

Object.Icon[ = cFileName]

Return Value

cFileName

For a form, specifies the file name and path of the icon to display when the form is minimized. For a distributed .exe application, specifies the file name and path of the icon displayed for the application.

Remarks

Applies To: Form | Project Object | _SCREEN

For forms, use the Icon property to specify a custom icon for any form that the user can minimize at run time. For example, you can assign a unique icon to a form to indicate the form's function. Enter the file name of the icon in the Properties window at design time. The file name you enter must have the .ico extension and icon format. If you do not specify a custom icon, the Visual FoxPro default icon for forms is used.

You can use the Microsoft Visual FoxPro Icon Library in HOME( )+"graphics\icons" as a source for icons.

Note:
If you set the Icon property at design time and the file you specify does not exist, Visual FoxPro displays an error message, but the property remains set to the file you specified. Visual FoxPro ignores the Icon property at run time if it is set to a file that does not exist.

For a project object, use the Icon property to specify the icon displayed for a distributed .exe application. You cannot specify an icon for a distributed Visual FoxPro .app application.

See Also

Other Resources

Caption Property
Picture Property
Properties
Language Reference


IMEMode Property

Visual FoxPro 9.0 Language Reference
IMEMode Property
See Also

Specifies the Input Method Editor (IME) window setting for an individual control. Available at design time and run time.

Object.IMEMode[ = nExpression]

Return Value

nExpression

One of the following settings:

nExpression IME window action

0

(Default) No Control. The operating system determines if the IME window is opened when the control has the focus. If the IME window is closed when the control has the focus, the IME window can be opened by pressing the key combination that activates the IME window.

1

Open IME. The IME window is opened when the control has the focus.

2

Close IME. The IME window is closed when the control has the focus. The IME window can be opened by pressing the key combination that activates the IME window.

Remarks

Applies To: ComboBox | EditBox | TextBox

This property is ignored unless you are running an East Asia version of a supported version of Microsoft Windows.

See Also

Other Resources

How to: Enter International Data
IMESTATUS( ) Function
SET BROWSEIME Command
Properties
Language Reference


Increment Property

Visual FoxPro 9.0 Language Reference
Increment Property
See Also

Specifies how much the value in the Spinner control increases or decreases when you click the up or down button. Available at design time and run time.

Spinner.Increment[ = nIncrement]

Return Value

nIncrement

Specifies a numeric value to add to the value displayed in the Spinner control when clicking the up button and the number to subtract when clicking the down button. The default is set to 1.00.
Note:
When entering a value for Increment in the Properties window, the value is limited to two decimal places of precision.

Remarks

Applies To: Spinner

See Also

Other Resources

RangeLow Event
IncrementalSearch Property
Properties
Language Reference


IncrementalSearch Property

Visual FoxPro 9.0 Language Reference
IncrementalSearch Property
See Also

Specifies whether a control supports an incremental search for keyboard steering. Available at design time and run time.

Control.IncrementalSearch[ = lExpr]

Return Value

lExpr

The settings for the IncrementalSearch property are:

Setting Description

True (.T.)

(Default) Supports incremental search.

False (.F.)

Does not support incremental search.

Remarks

Applies To: ComboBox | ListBox

An example of an incremental search is if you are searching for the word "ELASTIC," you can type E-L-A, and so on. As you type, Visual FoxPro incrementally searches for the combination of letters you have typed to match the word you are looking for. Otherwise, it finds the first word that starts with an E, then the first word that starts with an L, and so on.

Note that the setting of the _INCSEEK System Variable system variable determines how long to wait for the next letter to be typed. You may need to adjust the value of _INCSEEK to make incremental searching work properly.

A combo box with the Style property set to 0 (Dropdown Combo) will only show incremental searching in the text box if the drop-down list is shown. With the Style property set to 2 (Dropdown List), incremental searching will show in the text box, regardless of whether the drop-down list is shown.

See Also

Other Resources

Properties


InitialSelectedAlias Property

Visual FoxPro 9.0 Language Reference
InitialSelectedAlias Property
See Also

Specifies an alias associated with a Cursor object as the current alias when the data environment is loaded. Available at design time; read-only at run time.

DataEnvironment.InitialSelectedAlias[ = cText]

Return Value

cText

Specifies an alias name associated with a Cursor object.

Remarks

Applies To: DataEnvironment

Mimics the behavior of SELECT.

See Also

Other Resources

Properties
Alias Property
SELECT Command


InputMask Property

Visual FoxPro 9.0 Language Reference
InputMask Property
See Also

Specifies how users enter data and how to display data in a control. Available at design time and run time.

Control.InputMask[ = cMask]

Return Value

cMask

Specifies settings to determine how to enter and display data. The following table displays the possible values for cMask.

cMask Description

!

Converts lowercase letters to uppercase letters.

#

Permit entry of digits, spaces, and signs, such as the minus sign ( – ).

$

Displays the current currency symbol, as specified by the SET CURRENCY command, in a fixed position.

$$

Displays floating currency symbol that always appears adjacent to the digits in a spinner or text box.

,

Displays the current digit-grouping, or separator, symbol as set by the Regional and Language Options setting in the Windows Control Panel.

.

Displays the current decimal point character as specified by the SET POINT command setting. (Default is a period (.))

9

Permits entry of digits and signs.

A

Permits alphabetic characters only.

H

Prevents entry of non-hexadecimal symbols in the specified position.

L

Permits logical data only.

N

Permits letters and digits only.

U

Permits alphabetic characters only and converts them to uppercase (A - Z).

W

Permits alphabetic characters only and converts them to lowercase (a - z).

X

Permits any character.

Y

Permits the letters, Y, y, N, and n for the logical values True (.T.) and False (.F.), respectively.

Remarks

Applies To: Column | ComboBox | Spinner | TextBox

InputMask differs from the Format property in that it specifies behavior for the entire input field. You can mix several Format codes; however, they affect all data in the input field.

See Also

Reference

SET POINT Command
SET CURRENCY Command

Other Resources

Properties
DynamicInputMask Property
Format Property


InsertCmd Property

Visual FoxPro 9.0 Language Reference
InsertCmd Property
See Also

Specifies the command to use for inserting new rows. Read/write at design time and run time.

CursorAdapter.InsertCmd [ = cCommand ]

Return Value

cCommand

Character data type. The following table lists the possible values for cCommand.

cCommand Description

Character string or expression

Specifies a valid command string for the data source in the InsertCmdDataSource Property.

Empty string ("")

The CursorAdapter object generates a SQL INSERT command automatically if the AllowInsert property is set to True (.T.).

For more information about generating SQL commands automatically, see Data Access Management Using CursorAdapters.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


InsertCmdDataSource Property

Visual FoxPro 9.0 Language Reference
InsertCmdDataSource Property
See Also

Specifies the data source to use for the InsertCmd property. Read/write at design time and run time.

Note:
The CursorAdapter InsertCmdDataSourceType property determines how the InsertCmdDataSource property is used.

CursorAdapter.InsertCmdDataSource [= cDataSource]

Return Value

cDataSource

Character data type. The cDataSource parameter specifies the data source used by the InsertCmd property.

Remarks

Applies To: CursorAdapter Class

The following table describes behaviors that apply to InsertCmdDataSource depending on the value of InsertCmdDataSourceType.

InsertCmdDataSourceType InsertCmdDataSource behavior

Empty ("")

InsertCmdDataSource is disregarded. Visual FoxPro uses the data source in the CursorAdapter DataSource property.

However, if the cursor associated with the CursorAdapter object is based on an ActiveX Data Object (ADO) RecordSet, Visual FoxPro uses the functionality of the ADO RecordSet to insert the record. To use this functionality, make sure the CursorAdapter DataSourceType property is set to "ADO".

"ADO"

InsertCmdDataSource must be set to a valid ADO Command object. The ActiveConnection property of the ADO Command object must be set to a valid and open ADO Connection object.

Visual FoxPro sets the CommandText property of the ADO Command object to the value of the CursorAdapter InsertCmd property. Visual FoxPro parses the command for parameters, creates parameter values if found, and sets them in the Command object.

The insert operation occurs as:

Copy Code
CursorAdapter.InsertCmdDataSource.Execute()

For more information about using an ADO RecordSet, automatic updating, and generating SQL commands automatically, see Data Access Management Using CursorAdapters.

"XML"

Visual FoxPro disregards the CursorAdapter DataSource property.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


InsertCmdDataSourceType Property

Visual FoxPro 9.0 Language Reference
InsertCmdDataSourceType Property
See Also

Specifies the data source type of the data source in the InsertCmdDataSource property. Read/write at design time and run time.

CursorAdapter.InsertCmdDataSourceType [= cDataSourceType]

Return Value

cDataSourceType

Character data type. The cDataSourceType parameter specifies the data source type of the data source in the InsertCmdDataSource property.

Remarks

Applies To: CursorAdapter Class

If InsertCmdDataSourceType is empty ("") or null (.NULL.), Visual FoxPro disregards the CursorAdapter InsertCmdDataSource property and uses the CursorAdapter DataSource and DataSourceType properties.

To generate an XML UpdateGram, you must set the value of InsertCmdDataSourceType to "XML".

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
UpdateGram Property


InsertCmdRefreshCmd Property

Visual FoxPro 9.0 Language Reference
InsertCmdRefreshCmd Property
See Also

Specifies the command to automatically refresh the record after an Insert command is executed. Read/write at design time and run time.

CursorAdapter.InsertCmdRefreshCmd[ = cCommand]

Return Value

Term Definition

cCommand

Character data type. The following table lists the possible values for cCommand.

cCommand | Description
Character string or expression | Specifies a valid refresh command for the data source.
Empty string ("") | The CursorAdapter object generates the refresh command automatically.

Remarks

Applies To: CursorAdapter Class

See Also

Reference

InsertCmdRefreshCmd Property
InsertCmdRefreshFieldList Property
InsertCmdRefreshKeyFieldList Property
UpdateCmdRefreshCmd Property
UpdateCmdRefreshFieldList Property
UpdateCmdRefreshKeyFieldList Property


InsertCmdRefreshFieldList Property

Visual FoxPro 9.0 Language Reference
InsertCmdRefreshFieldList Property
See Also

Specifies the fields in the cursor to refresh after an Insert command is executed. Read/write at design time and run time.

CursorAdapter.InsertCmdRefreshFieldList[ = cExpr]

Return Value

Term | Definition
cExpr | The character expression cExpr is a comma delimited list of the fields in the cursor that are refreshed.

Remarks

Applies To: CursorAdapter Class

The InsertCmdRefreshFieldList property determines which fields in the cursor are automatically refreshed after an Insert command is issued.

Note:
The AllowInsert Property must be set to True (.T.) to permit insert operations to a data source.

For more information about how Visual FoxPro updates remote data using a CursorAdapter, see Data Access Management Using CursorAdapters.

See Also

Reference

InsertCmdRefreshCmd Property
InsertCmdRefreshKeyFieldList Property
UpdateCmdRefreshCmd Property
UpdateCmdRefreshFieldList Property
UpdateCmdRefreshKeyFieldList Property


InsertCmdRefreshKeyFieldList Property

Visual FoxPro 9.0 Language Reference
InsertCmdRefreshKeyFieldList Property
See Also

Specifies the key fields in the cursor used to retrieve a record after an Insert command is executed. Read/write at design time and run time.

CursorAdapter.InsertCmdRefreshKeyFieldList[ = cExpr]

Return Value

Term | Definition
cExpr | The character expression cExpr is a comma delimited list of the key fields in the cursor that is used to retrieve a record from the data source.

Remarks

Applies To: CursorAdapter Class

For more information about how Visual FoxPro updates CursorAdapters, see Data Access Management Using CursorAdapters.

See Also

Reference

InsertCmdRefreshCmd Property
InsertCmdRefreshFieldList Property
UpdateCmdRefreshCmd Property
UpdateCmdRefreshFieldList Property
UpdateCmdRefreshKeyFieldList Property


Instancing Property

Visual FoxPro 9.0 Language Reference
Instancing Property
See Also

Specifies how a server in a project can be instantiated. Available at design time and run time.

Object.Instancing[ = nExpression]

Return Value

nExpression

Specifies how the server can be instantiated. The following table lists the values for nExpression with a description of each.

Settings FoxPro.h constant Description

0

SERVERINSTANCE_NOTCREATABLE

Makes it possible for you to create instances of the class only inside Visual FoxPro.

1

SERVERINSTANCE_SINGLEUSE

(Default) Makes it possible for you to create an instance of the class both inside Visual FoxPro and outside of Visual FoxPro using Automation.

Each request for an instance of the class by an automation client outside of the project causes a separate copy of the automation server to start.

2

SERVERINSTANCE_MULTIUSE

Makes it possible for you to create an instance of the class both inside Visual FoxPro and outside of Visual FoxPro using Automation.

Each request for an instance of the class by an automation client outside of the project causes an already running copy of the automation server to be provided as the source for the new instance.

Remarks

Applies To: Server Object

See Also

Other Resources

Properties
GETOBJECT( ) Function
ServerClass Property
ServerClassLibrary Property


IntegralHeight Property

Visual FoxPro 9.0 Language Reference
IntegralHeight Property
See Also

Specifies that the height of an EditBox or ListBox control is automatically adjusted so the last item in the control is properly displayed. Specifies that the height of a TextBox control is adjusted to accommodate one line of text. Available at design time; read-only at run time.

Object.IntegralHeight[ = lExpr]

Return Value

lExpr

One of the following:

lExpr Description

True (.T.)

The height an EditBox or ListBox control is adjusted as necessary so the last item in the control is properly displayed. The height of a TextBox is adjusted to accommodate one line of text.

False (.F.)

(Default) The height of an EditBox or ListBox isn't adjusted, allowing the last item in the control to be improperly displayed. The height of a TextBox isn't adjusted to accommodate one line of text.

Remarks

Applies To: EditBox | ListBox | TextBox

The last line of text in an EditBox or ListBox control might be partially displayed if the control isn't the proper height. For example, the height of the control may be such that only the top half of the last item is displayed in the control. Set IntergralHeight to true (.T.) to automatically adjust the height of the control so the last item in the control is always properly displayed.

For a TextBox, set IntergralHeight to true (.T.) to ensure that the control automatically adjusts its height when its FontSize property is changed.

When the IntegralHeight property is set to true (.T.), the value of the Height property might not match the actual height of the control.

See Also

Reference

FontSize Property

Other Resources

Height Property
Properties
Language Reference


Interval Property

Visual FoxPro 9.0 Language Reference
Interval Property
See Also

Specifies the number of milliseconds between calls to a Timer control's Timer event. Available at design time and run time.

Timer.Interval[ = nTime]

Return Value

nTime

Specifies the number of milliseconds between Timer events. The default value is 0, which prevents the Timer event from firing.

Remarks

Applies To: Timer

For more information about the Interval property, see "Initializing a Timer Control" in How to: Perform Specific Actions at Given Intervals .

See Also

Other Resources

Reset Method
Timer Event
Properties
Language Reference


IsAttribute Property

Visual FoxPro 9.0 Language Reference
IsAttribute Property
See Also

Specifies whether the field is represented as an Attribute in the associated XML document.

XMLField.IsAttribute [= lValue]

Return Value

lValue

Logical data type. The following table lists values for lValue.

lValue Description

False (.F.)

The field is in Element form, not Attribute form, in the associated XML document. (Default)

True (.T.)

The field is represented as an Attribute in the associated XML document.

Remarks

Applies To: XMLField Class

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events


IsBase64 Property

Visual FoxPro 9.0 Language Reference
IsBase64 Property
See Also

Specifies whether the field in the XML document is encoded as base64 or hexBinary.

XMLField.IsBase64 [= lValue]

Return Value

lValue

Logical data type. The following table lists values for lValue.

lValue Description

False (.F.)

(Default) The field is encoded as hexBinary.

True (.T.)

The field is encoded as base64.

Remarks

Applies To: XMLField Class

IsBase64 applies only when the IsBinary property is True (.T.).

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events
IsBinary Property


IsBinary Property

Visual FoxPro 9.0 Language Reference
IsBinary Property
See Also

Specifies whether the field is Binary in the XML Schema.

XMLField.IsBinary [= lValue]

Return Value

lValue

Logical data type. The following table lists values for lValue.

lValue Description

False (.F.)

(Default) The field is not Binary but String in the XML Schema.

True (.T.)

The field is specified as Binary in the XML Schema.

Remarks

Applies To: XMLField Class

For the IsBase64 property to apply, IsBinary must be True (.T.).

See Also

Reference

IsBase64 Property

Other Resources

Properties
XMLField Object Properties, Methods, and Events


IsDiffGram Property

Visual FoxPro 9.0 Language Reference
IsDiffGram Property
See Also

Indicates whether the XMLAdapter object is associated with a .NET DiffGram. Read/write.

Note:
Setting the IsDiffGram property does not actually alter the associated XML document.

XMLAdapter.IsDiffGram [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

The XMLAdapter object is not a .NET DiffGram. (Default)

True (.T.)

The XMLAdapter object is a .NET DiffGram.

Remarks

Applies To: XMLAdapter Class

XMLAdapter detects whether imported XML is a DiffGram and sets IsDiffGram. When creating and generating XML from tables and executing the XMLAdapter ToXML method, Visual FoxPro checks IsDiffGram and creates XML consistent with its setting.

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
ToCursor Method
ToXML Method


IsLoaded Property

Visual FoxPro 9.0 Language Reference
IsLoaded Property
See Also

Indicates whether the XMLAdapter object is associated with an XML document. Read-only.

XMLAdapter.IsLoaded [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

XMLAdapter is not associated with an XML document. (Default)

True (.T.)

XMLAdapter is associated with an XML document.

Remarks

Applies To: XMLAdapter Class

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events


IsNull Property

Visual FoxPro 9.0 Language Reference
IsNull Property
See Also

Specifies whether the field in the XML document supports null values.

XMLField.IsNull [= lValue]

Return Value

IValue

Logical data type. The following table lists values for lValue.

lValue Description

False (.F.)

The field does not support null values. (Default)

True (.T.)

The field supports null values.

Remarks

Applies To: XMLField Class

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events


ItemBackColor, ItemForeColor Properties

Visual FoxPro 9.0 Language Reference
ItemBackColor, ItemForeColor Properties
See Also

Specifies the background or foreground color used to display the text of items in a ComboBox or ListBox control. Available at design time and run time.

Control.ItemBackColor [= nColor ]
-or-
Control.ItemBackColor = RGB( nRedValue, nGreenValue, nBlueValue )
Control.ItemForeColor [ = nColor ]
-or-
Control.ItemForColor = RGB( nRedValue, nGreenValue, nBlueValue )

Return Value

nColor

Specifies an integer that represents the color of the text. For more information, see the color table in the BackColor_ForeColor Properties topic.

Remarks

Applies To: ComboBox Control | ListBox Control

To choose or define colors, double-click any of the color properties in the Properties window to display the Color dialog box. The red, green, and blue color values corresponding to the color you choose become the settings for these properties after you close the Color dialog box.

See Also

Other Resources

BackColor, ForeColor Properties
Properties
Language Reference


ItemData Property

Visual FoxPro 9.0 Language Reference
ItemData Property
See Also

Uses an index to reference a one-dimensional array that contains the same number of items as a ComboBox or ListBox control's List property setting. Not available at design time; read/write at run time.

Control.ItemData(nIndex)[ = nData]

Return Value

nIndex

Specifies the index of the item to store or retrieve. The nIndex corresponds to the display order of the items in the list.
nData

The number to store or retrieve from the ItemData list.

Remarks

Applies To: ComboBox | ListBox

Use the ItemData property to associate a specific number with each item in a combo box or list box. You can then use these numbers in code to identify the items in the list. For example, you can use an identification number to identify each employee name in a list box. When you fill the list box, also fill the corresponding elements in the ItemData array with the employee numbers.

Note:
When you insert an item into a list with the AddItem method, an item is automatically allocated in the ItemData array as well. However, the value is not initialized; it retains the value that was in that position before you added the item to the list. When you use the ItemData property, be sure to set each element's value when adding new items to a list.

See Also

Other Resources

AddItem Method
ItemIDToIndex Method
List Property
ListItemID Property
NewItemID Property
RemoveItem Method
Selected Property
TopItemID Property
Properties
Language Reference


ItemIDData Property

Visual FoxPro 9.0 Language Reference
ItemIDData Property
See Also

Uses a unique identification number to reference a one-dimensional array that contains the same number of items as a ComboBox or ListBox control's List property setting. Not available at design time; read/write at run time.

Control.ItemIDData(nItemID)[ = nData]

Return Value

nItemID

Specifies the item ID, a unique identification number.
nData

The number to store or retrieve from the ItemIDData list.

Remarks

Applies To: ComboBox | ListBox

Use the ItemIDData property to associate a specific number with each item in a combo box or list box. You can then use these numbers in code to identify the items. For example, you can use an identification number to identify each employee name in a list box. When you fill the list box, also fill the corresponding elements in the ItemIDData array with the employee numbers.

Note:
When you insert an item into a list with the AddItem Method, an item is automatically allocated in the ItemIDData array as well. However, the value is not initialized; it retains the value that was in that position before you added the item to the list. When you use the ItemIDData property, be sure to set each element's value when adding new items to a list. This is the same array that is accessed by the ItemData Property.

See Also

Other Resources

IndexToItemID Method
List Property
ListItemID Property
NewItemID Property
RemoveItem Method
Selected Property
TopItemID Property
Properties


ItemTips Property

Visual FoxPro 9.0 Language Reference
ItemTips Property
See Also

Specifies whether item tips are displayed for items in a combo box or list box. Available at design time; read/write at run time.

Control.ItemTips[= lExpression]

Return Value

lExpression

The settings for the ItemTip property are:

Setting Description

True (.T.)

Item tips are displayed for items in a combo box or list box.

False (.F.)

(Default) Item tips are not displayed for items in a combo box or list box.

Remarks

Applies To: ComboBox | ListBox

An item tip is a small window that displays an entire combo box or list box item when the mouse pointer is positioned over the item. Set this property to true (.T.) whenever items in a ComboBox or ListBox control are longer than the width of the control.

See Also

Other Resources

ItemData Property
Properties
Language Reference


IXMLDOMElement Property

Visual FoxPro 9.0 Language Reference
IXMLDOMElement Property
See Also

Contains an object reference to an IXMLDOMElement object after the successful execution of the XMLAdapter LoadXML or Attach method. XMLAdapter methods work within the scope of this IXMLDOMElement object.

For more information about IXMLDOMElement objects, see the Microsoft XML Core Services (MSXML) 4.0 SDK on the MSDN Library Web site at http://msdn.microsoft.com/library/.

XMLAdapter.IXMLDOMElement

Return Value

Object reference. IXMLDOMElement contains an object reference to an IXMLDOMElement object. When not populated, IXMLDOMElement contains null (.NULL.).

Remarks

Applies To: XMLAdapter Class

The XMLAdapter LoadXML method points IXMLDOMElement to the root element of the document.

If you pass an XMLDOMElement object as the first parameter of the XMLAdapter Attach method, Attach assigns the element to the IXMLDOMElement property.

If you pass an IXMLDOMDocument object as the first parameter of the XMLAdapter Attach method, Attach assigns its root element to the IXMLDOMElement property.

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
LoadXML Method
Attach Method


KeyboardHighValue, KeyboardLowValue Properties

Visual FoxPro 9.0 Language Reference
KeyboardHighValue, KeyboardLowValue Properties
See Also

Specifies the highest or lowest value that can be entered into a Spinner control text box using the keyboard. Available at design time and run time.

Spinner.KeyboardHighValue[ = nHigh]Spinner.KeyboardLowValue[ = nLow]

Return Value

nHigh

Specifies the highest value that can be entered. The default value for nHigh is 2,147,483,647.
nLow

Specifies the lowest value that can be entered. The default value for nLow is – 2,147,483,647.

Remarks

Applies To: Spinner

See Also

Other Resources

SpinnerHighValue, SpinnerLowValue Properties
KEYBOARD Command
Properties
Language Reference


Keyfield Property

Visual FoxPro 9.0 Language Reference
Keyfield Property
See Also

Specifies whether the field is a key field.

Keyfield applies only when executing the XMLTable ApplyDiffgram method. You can set this property when desired; Visual FoxPro does not set this property.

XMLField.Keyfield [= lValue]

Return Value

Logical data type. The following table lists the values for lValue.

lValue | Description
False (.F.) | The field is not a key field. (Default)
True (.T.) | The field is a key field.

Remarks

Applies To: XMLField Class

See Also

Reference

ApplyDiffgram Method

Other Resources

Properties
XMLField Object Properties, Methods, and Events
ApplyDiffgram Method


KeyFieldList Property

Visual FoxPro 9.0 Language Reference
KeyFieldList Property
See Also

Specifies a comma-delimited list of primary fields for the cursor or CursorAdapter object. When working with this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions. Read/write.

Note:
Setting KeyFieldList for CursorAdapter objects overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP( ) has no effect.

CursorAdapter.KeyFieldList [= cList]

Return Value

cList

Character data type. The cList parameter specifies a comma-delimited list of primary fields for the cursor or CursorAdapter object and does not have a default value.
Note:
You must include a list of field names when using automatic updating for updates to work.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


KeyPreview Property

Visual FoxPro 9.0 Language Reference
KeyPreview Property
See Also

Specifies whether a form's KeyPress event intercepts the KeyPress events of a control. Available at design time and run time.

Object.KeyPreview[ = lExpr]

Return Value

lExpr

The settings for the KeyPreview property are:

Setting Description

True (.T.)

The form receives KeyPress events first and then the active control receives KeyPress events.

False (.F.)

(Default) The active control receives Keypress events; the form doesn't.

Remarks

Applies To: Form | Page | _SCREEN | ToolBar

The KeyPreview property is used to allow the form to handle KeyPress events before the active control processes them.

You can use this property to create a keyboard-handling procedure for a form. For example, when an application uses function keys, you can process the keystrokes at the form level rather than writing code for each control that can receive keystroke events.

If a form has no visible and enabled controls, it automatically receives all keyboard events.

See Also

Other Resources

Enabled Property
KeyPress Event
Visible Property
Properties
Language Reference


KeySort Property

Visual FoxPro 9.0 Language Reference
KeySort Property
See Also Example

Specifies how Visual FoxPro enumerates through items in a collection when you use the FOR EACH command. Available at design time and run time.

Collection.KeySort [ = nValue ]

Return Value

nValue

The following table lists values for nValue.

nValue Description

0

Index ascending (default)

1

Index descending

2

Key ascending

3

Key descending

Remarks

Applies To: Collection Class

The KeySort property applies only to FOR EACH enumerations.

The KeySort property does not affect how the Add method for collection objects adds items to a collection. Add always adds items by index at the end unless you specify an eBeforeItem or eAfterItem parameter.

You can have a collection in which none of the items have keys. In this case, the last two values you can specify for nValue, 2 and 3, do not apply. If you specify a value of 3, Visual FoxPro uses the value of 1.

Within a collection's FOR EACH loop, changing the KeySort property does not affect the sequencing of items. However, you can nest collection enumerations to change the sequencing. In the following example, the outer FOR EACH loop is sorted using KeySort with a value of 1, and the inner loop is sorted using KeySort with a value of 2:

Copy Code
oCollection.KeySort = 1
FOR EACH oItem IN oCollection
     oCollection.KeySort = 2
     FOR EACH oItem2 IN oCollection
     ENDFOR
ENDFOR

Example

You can set a value for KeySort as shown in the following example:
Copy Code
* Sorts a collection in ascending index order
oCollection.KeySort = 0

See Also

Other Resources

Properties
Collection Object Properties, Methods, and Events
Add Method (Collection Class)
FOR EACH ... ENDFOR Command


LanguageOptions Property

Visual FoxPro 9.0 Language Reference
LanguageOptions Property
See Also Example

This application object property provides ability to control general Visual FoxPro language settings. This includes the ability to check for improperly declared memory variables.

_VFP.LanguageOptions [= eValue]

Return Value

eValue

Bit Value Description

1

Strict type declaration is required for memory variables.

Remarks

Applies To: Application Object | _VFP System Variable

When LanguageOptions is set to 1, you must declare all memory variables and arrays as LOCAL or PUBLIC prior to using them. An attempt to use an undeclared variable or array will generate output to the DEBUG OUTPUT window. No error is generated. You can log this output to a file as in the following code:

Copy Code
   SET DEBUGOUT TO MyErrorFile

The output from undeclared variables in LanguageOptions is comma-delimited in the following format:

LangOptionsErr, DateTime, cLineNo, cProcedure|cMethod, cFileName, cVarName

Item | Description
LangOptionsErr | Specifies the name of the output type for searches and filters
DateTime | Specifies the time stamp when run (= DATETIME( ))
cLineNo | Specifies the line number where error occurred (=LINENO( ))
cProcedure|cMethod | Specifies the name of the procedure or method in which the error occurred ( = PROGRAM( ))
cFileName | Specifies the name of the file in which the error occurred. (=SYS(16( ))
cVarName | Specifies the name of the undeclared variable

Declaring variables PRIVATE does not create a variable (unlike declaring variables PUBLIC or LOCAL), so the following code generates a log entry:

Copy Code
   PRIVATE myvar
   myvar = 1

Commands that create variables on the fly, such as SCATTER ... NAME, REPORT ... NAME and others, will generate log entries, because these variables are created as PRIVATE.

Example

The following code shows the debug output resulting from entering an undeclared variable, myvar.
Copy Code
_VFP.LanguageOptions=1
myvar=4

Strict typing in Visual FoxPro is enforced only at run time, so you must run code to detect errors. Strict typing affects both development and run-time versions of Visual FoxPro.

Note:
Use of private variables such as those declared with the PRIVATE command or those created using the NAME clause of certain commands will generate errors. If you are distributing code that might be affected by developers potentially setting this property to 1, you should protect your code by resetting this property to 0 when needed.

See Also

Other Resources

PUBLIC Command
PRIVATE Command
LOCAL Command
How to: Set Properties at Run Time
Variable Declaration
Properties
Language Reference


LastModified Property

Visual FoxPro 9.0 Language Reference
LastModified Property
See Also

Contains the date and time of the last modification made to a file in a project. Read-only at design time and run time.

Object.LastModified

Remarks

Applies To: File Object

The LastModified property contains a DateTime value indicating when the file was last modified.

See Also

Other Resources

FDATE( ) Function
FTIME( ) Function
Properties
Language Reference


Left Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Left Property (Visual FoxPro)
See Also Example

Specifies the distance between the left edge of a control or form and its container object. Available at design time and run time.

Object.Left[ = nDist]

Return Value

nDist

Specifies the distance between the left edge of an object or form and the left edge of its container object. The default container for a form is the main Visual FoxPro window.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | Custom | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | PageFrame | _SCREEN | Shape | Spinner | TextBox | Timer | ToolBar

The Left property specifies how far from the object's zero position the object is located. For example, if a form is contained within the Visual FoxPro main window, the zero position is immediately to the right of the main window's left border. If a toolbar is docked to the left of the main window, the zero position is immediately to the right of the toolbar.

Use Left, Top, Height, and Width properties for operations based on an object's external dimensions, such as moving or resizing. Use the ScaleMode property to change the unit of measurement.

Note:
The Left property is read-only when it applies to a control contained in a Column object.

Example

The following example demonstrates how the Left property is used to position controls on a form. The AddObject method is used to add a Line control and three command buttons to a form, and the Left property specifies the horizontal placement of each control on the form.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a form
frmMyForm.Closable = .F.  && Disable the window pop-up menu

frmMyForm.AddObject('shpLine','Line')  && Add a Line control to the form
frmMyForm.AddObject('cmdCmndBtn1','cmdMyCmndBtn1')  && Up Cmnd button
frmMyForm.AddObject('cmdCmndBtn2','cmdMyCmndBtn2')  && Down Cmnd button
frmMyForm.AddObject('cmdCmndBtn3','cmdMyCmndBtn3')  && Quit Cmnd button

frmMyForm.shpLine.Visible = .T.  && Make Line control visible
frmMyForm.shpLine.Top = 20  && Specify Line control row
frmMyForm.shpLine.Left = 125  && Specify Line control column

frmMyForm.cmdCmndBtn1.Visible =.T.  && Up Command button visible
frmMyForm.cmdCmndBtn2.Visible =.T.  && Down" Command button visible
frmMyForm.cmdCmndBtn3.Visible =.T.  && Quit Command button visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmndBtn1 AS COMMANDBUTTON  && Create Command button
   Caption = 'Slant \<Up'  && Caption on the Command button
   Left = 50  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='/'  && Slant up
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn2 AS CommandButton  && Create Command button
   Caption = 'Slant \<Down'  && Caption on the Command button
   Left = 200  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='\'  && Slant down
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn3 AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 150  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close form
ENDDEFINE

See Also

Other Resources

Height Property
Move Method
ScaleMode Property
Top Property
Width Property
Properties
Language Reference


LeftColumn Property

Visual FoxPro 9.0 Language Reference
LeftColumn Property
See Also

Contains the number of the left-most column being displayed by a Grid control. Read-only at design time and run time.

Grid.LeftColumn

Remarks

Applies To: Grid

Use the LeftColumn property to determine which columns are not visible to the user. For example, if LeftColumn = 3, columns 1 and 2 are not visible.

See Also

Other Resources

ActiveColumn Property
ActiveRow Property
ColumnOrder Property
RelativeColumn Property
RelativeRow Property
Properties
Language Reference


LineContents Property

Visual FoxPro 9.0 Language Reference
LineContents Property
See Also

Specifies the contents of the line that produced an exception object. Read/write at run time.

Exception.LineContents

Return Value

Character data type

Remarks

Applies To: Exception Class

Identical to the value returned by the statement:

Copy Code
MESSAGE(1)

See Also

Other Resources

Properties
Exception Object Properties, Methods, and Events
MESSAGE( ) Function
TRY...CATCH...FINALLY Command
Structured Error Handling


LineNo Property

Visual FoxPro 9.0 Language Reference
LineNo Property
See Also

Specifies the line number of the statement that produced an exception object. Read/write at run time.

Exception.LineNoProperty

Return Value

Numeric data type

Remarks

Applies To: Exception Class

Identical to the value returned by the LINENO( ) function.

See Also

Reference

LINENO( ) Function

Other Resources

Properties
Exception Object Properties, Methods, and Events
TRY...CATCH...FINALLY Command
Structured Error Handling


LineSlant Property

Visual FoxPro 9.0 Language Reference
LineSlant Property
See Also

Specifies the slope direction of a Line control or rounded corners (Bezier curve) for a polygon line drawn with a Line control. Read/write at design time and run time.

Line.LineSlant [= cSlant]

Return Value

cSlant

Specifies the slope direction of a line control or rounded corners for polygon lines drawn with a line control. The following table lists the values for cSlant.

cSlant Description

\

Line slopes from upper left to lower right. (Default)

/

Line slopes from lower left to upper right.

S or s

Line is drawn as a Bezier curve when a valid array of coordinates is set for the PolyPoints property. To remove this setting, set LineSlant to "\" or "/".

Note:
The PolyPoints array must specify a total of (3n + 1) coordinates with n representing the number of curves you want to draw a Bezier curve. If PolyPoints does not contain coordinates that form a valid polygon, and the "S" or "s" setting is specified, no line is drawn.

For more information, see PolyPoints Property.

Remarks

Applies To: Line

Code Example

The following example creates a form with a Line control and three command buttons that demonstrate the three values for the LineSlant property.

Copy Code
Public oForm
oForm = Createobject('Form')
With oForm
   .AddObject('linSample','Line')
   .AddObject('cmdSlantUp','cmdSlantUp')
   .AddObject('cmdSlantDown','cmdSlantDown')
   .AddObject('cmdBezier','cmdBezier')

   .linSample.Top = 10
   .linSample.Left = 25
   .linSample.Width = 300
   .linSample.Height = 200

   .SetAll('Visible', .T.)

* Creates an array of points that define the curve.
   Dimension aBezierPoints[4,2]
      aBezierPoints[1,1]= 0
      aBezierPoints[1,2]= 0
      aBezierPoints[2,1]= 100
      aBezierPoints[2,2]= 25
      aBezierPoints[3,1]= 0
      aBezierPoints[3,2]= 75
      aBezierPoints[4,1]= 100
      aBezierPoints[4,2]= 100
Endwith

oForm.Show(1)

* Defines a button that changes the slant of the line.
Define Class cmdSlantUp As CommandButton
   Caption = 'Slant \<Up (/)'
   Left = 25
   Top = 220
   Height = 25

   Procedure Click
      Thisform.linSample.Polypoints = ""
      Thisform.linSample.LineSlant = '/'  && Slant up
   Endproc
Enddefine

* Defines a button that changes the slant of the line.
Define Class cmdSlantDown As CommandButton
   Caption = 'Slant \<Down (\)'
   Left = 125
   Top = 220
   Height = 25

   Procedure Click
      Thisform.linSample.Polypoints = ""
      Thisform.linSample.LineSlant = '\'  && Slant down
   Endproc
Enddefine

* Defines a button that changes the line to a Bezier curve.
Define Class cmdBezier As CommandButton
   Caption = 'Be\<zier Curve (S) '
   Left = 225
   Top = 220
   Height = 25

   Procedure Click
      Thisform.linSample.Polypoints = "aBezierPoints" && Specifies points on the curve.
      Thisform.linSample.LineSlant = 'S' && Specifies to display a curve.
      Thisform.linSample.Visible = .T.
      Thisform.Visible = .T.
   Endproc
Enddefine

See Also

Other Resources

DrawMode Property
DrawStyle Property
Properties
Language Reference


LinkMaster Property

Visual FoxPro 9.0 Language Reference
LinkMaster Property
See Also

Specifies the parent table linked to the child table displayed in a Grid control. Available at design time; read/write at run time.

Grid.LinkMaster[ = cName]

Return Value

cName

Specifies the alias of the parent table that drives the display of the child table in a Grid control.

Remarks

Applies To: Grid

Use the LinkMaster property to set up a one-to-many relationship between the parent, or primary, table of the Form, and the table referenced by the Grid's RecordSource property.

See Also

Reference

SET RELATION Command

Other Resources

ChildOrder Property
RelationalExpr Property
Properties
Language Reference


ListenerType Property

Visual FoxPro 9.0
ListenerType Property
See Also Example

Specifies the type of report output the ReportListener produces.

ReportListener.ListenerType [= iExpr]

Return Value

Integer data type.

The following table lists the values recognized by Visual FoxPro natively.

Native ListenerType | Output Result
-1 | (Default) This is the base state of the abstract ReportListener native class. It produces no output.
0 | The ReportListener renders output page by page, sending rendering events to a printer driver.
1 | The ReportListener renders all pages, and then makes the output pages available to a new Xbase component stored in _REPORTPREVIEW. This ListenerType takes no action if there is no _REPORTPREVIEW object available.
2 | The ReportListener renders output page by page, but does not send it to a printer. You can use the output by writing code in the OutputPage method, which is invoked as each page is produced.
3 | The ReportListener renders all pages at once, and does not explicitly call _REPORTPREVIEW. You can use the output by writing code after the report run, calling OutputPage to instruct the ReportListener to send a page to your chosen target device.

The Report Output Application adds some user-defined rendering results to the native set above. However, using these values do not prevent you from receiving native Visual FoxPro output results simultaneously from the same ReportListener object, according to the native ListenerType values above. For more information, see OutputType Property (Visual FoxPro).

Call Report Output Application with | Output Result
4 | The ReportListener provides an XML file as output. By default, its ListenerType is -1 (no native output). You can also set its ListenerType property to one of the natively supported values, for two types of output at once.
5 | The ReportListener provides an HTML file, and optional subsidiary image files, as output. By default, its ListenerType is -1 (no native output). You can also set its ListenerType property to one of the natively supported values, for two types of output at once.

Remarks

Applies To: ReportListener Object.

The Report Engine provides a ListenerType value to the Report Output Application when you use the OBJECT TYPE <N> clause on a REPORT FORM command, or when you SET REPORTBEHAVIOR 90, indicating that you want to use object-assisted reporting for all REPORT FORM commands. Report Output Application maintains a registry for default ReportListener classes to handle the native ListenerType values, as well as the two additional OutputType values added by its own Visual Foxpro class library and any others that you nominate. For more information, see Report Output Application.

Your derived ReportListener classes can handle multiple types of output results by supporting multiple ListenerType values. You can use the SupportsListenerType method to evaluate the ListenerType property during a report run, and determine whether your derived class should take action.

You can register a single class as the default handler for multiple types of output results with Report Output Application. Report Output Application assigns the value it receives from the Report Engine to a companion property of your ReportListener-derived object, OutputType. Your class can dynamically determine the correct ListenerType value to use, based on the OutputType it receives and its own capabilities to handle different output results.

For example, Report Output Application provides UpdateListener, the ReportListener User Feedback Foundation Class, as the default handler for multiple native ListenerType values. When initialized, UpdateListener has a ListenerType of -1 (no output). It checks OutputType to determine which ListenerType it should have for each REPORT FORM command you execute.

Example

The following code comes from the OutputType_assign method of the ReportListener Base Foundation Class, the class from which UpdateListener descends. The code checks to see if the value received as OutputType is one of the ListenerType values the class supports, and assigns the value to ListenerType if it is.

Copy Code
IF THIS.SupportsListenerType(THIS.OutputType)
   THIS.ListenerType = THIS.OutputType
ENDIF

See Also

Reference

ReportListener Object Properties, Methods, and Events
REPORT FORM Command

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)
ReportListener Foundation Classes


List Property

Visual FoxPro 9.0 Language Reference
List Property
See Also Example

A character string array used to access the items in a ComboBox or ListBox control. Not available at design time; read/write at run time.

Control.List(nRow [, nCol]])[ = cChar]

Return Value

nRow

Specifies the row of the item to be retrieved using the display order. For example, nRow = 3 specifies the third row shown in the list.
nCol

Specifies the column of the item to be retrieved using the display order. For example, nCol = 2 specifies the second column shown in the list. If nCol is not specified, the List property retrieves the first column by default. Specify nCol only for ComboBox and ListBox controls that have more than one column.
cChar

Specifies a value to add to a combo box or list box.

Remarks

The List property works in conjunction with the ListCount property; enumerating a list from 1 to ListCount returns all items in the list.

You cannot use array functions with the List property. However, if you set the RowSourceType property to 5 (Array) and set the RowSource property to the array of values to be contained in the list, you can use array functions on the array specified in the RowSource property.

Note:
When RowSourceType is set to 0 or 1, add items to a combo box or list box using the AddItem method. To remove items, use the RemoveItem method. To keep items in alphabetic order, set the control's Sorted property to true (.T.) before adding items to the list.

Example

Applies To: ComboBox | ListBox

In the following example, ListCount is used to cycle through all the of the items specified by the List property of the combo box or list box.

The following example creates a list box. The source of the items that appear in the list box items is an array; the array is specified with the RowSourceType and RowSource properties.

The MultiSelect property for the list box is set to true (.T.), making it possible for you to make multiple selections from the list box. The ListCount property is used within a FOR ... ENDFOR loop to display the item or items you choose in the list box. The Selected property is used to determine the items you chose, and the List property is used to return the items.
Copy Code
CLEAR

DIMENSION gaMyListArray(10)
FOR gnCount = 1 to 10  && Fill the array with letters
   STORE REPLICATE(CHR(gnCount+64),6) TO gaMyListArray(gnCount)
ENDFOR

frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.Move(150,10)  && Move the form

* Add "Quit" command button and list box control
frmMyForm.AddObject('cmbCommand1','cmdMyCmdBtn')
frmMyForm.AddObject('lstListBox1','lstMyListBox')

* && Specifies an array containing listbox items
frmMyForm.lstListBox1.RowSourceType = 5
frmMyForm.lstListBox1.RowSource = 'gaMyListArray'

frmMyForm.cmbCommand1.Visible =.T.  && "Quit" Command button visible
frmMyForm.lstListBox1.Visible =.T.  && "List Box visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
      CLEAR  && Clear main Visual FoxPro window
ENDDEFINE

DEFINE CLASS lstMyListBox AS ListBox  && Create ListBox control
   Left = 10  && List Box column
   Top = 10  && List Box row
   MultiSelect = .T.  && Allow selecting more than 1 item

PROCEDURE Click
   ACTIVATE SCREEN
   CLEAR
   ? "Selected items:"
   ? "---------------"
   FOR nCnt = 1 TO ThisForm.lstListBox1.ListCount
      IF ThisForm.lstListBox1.Selected(nCnt)  && Is item selected?
         ? SPACE(5) + ThisForm.lstListBox1.List(nCnt) && Show item
      ENDIF
   ENDFOR

ENDDEFINE

See Also

Other Resources

AddItem Method
IndexToItemID Method
ItemIDToIndex Method
ListCount Property
ListItem Property
ListItemID Property
RowSource Property
RowSourceType Property
Sorted Property
Properties
Language Reference


ListCount Property

Visual FoxPro 9.0 Language Reference
ListCount Property
See Also Example

Contains the number of items in the list portion of a ComboBox or ListBox control. Not available at design time; read-only at run time.

Control.ListCount

Remarks

Applies To: ComboBox | ListBox

Example

The following example creates a list box. The source of the items that appear in the list box items is an array; the array is specified with the RowSourceType and RowSource properties.

ListCount is used to cycle through all of the items specified by the List property of the ComboBox or ListBox.

The MultiSelect property for the list box is set to true (.T.), allowing you to make multiple selections from the list box. The ListCount property is used within a FOR ... ENDFOR loop to display the item or items you choose in the list box. The Selected and List properties are used to determine the items you chose.
Copy Code
CLEAR

DIMENSION gaMyListArray(10)
FOR gnCount = 1 to 10  && Fill the array with letters
   STORE REPLICATE(CHR(gnCount+64),6) TO gaMyListArray(gnCount)
ENDFOR

frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .f.  && Disable the Control menu box

frmMyForm.Move(150,10)  && Move the form

frmMyForm.AddObject('cmbCommand1','cmdMyCmdBtn')  && Add "Quit" Command button
frmMyForm.AddObject('lstListBox1','lstMyListBox')  && Add list box control

frmMyForm.lstListBox1.RowSourceType = 5  && Specifies an array
frmMyForm.lstListBox1.RowSource = 'gaMyListArray' && Array containing listbox items

frmMyForm.cmbCommand1.Visible =.T.  && "Quit" Command button visible
frmMyForm.lstListBox1.Visible =.T.  && "List Box visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
      CLEAR  && Clear main Visual FoxPro window
ENDDEFINE

DEFINE CLASS lstMyListBox AS ListBox  && Create ListBox control
   Left = 10  && List Box column
   Top = 10  && List Box row
   MultiSelect = .T.  && Allow selecting more than 1 item

PROCEDURE Click
   ACTIVATE SCREEN
   CLEAR
   ? "Selected items:"
   ? "---------------"
   FOR nCnt = 1 TO ThisForm.lstListBox1.ListCount
      IF ThisForm.lstListBox1.Selected(nCnt)  && Is item selected?
         ? SPACE(5) + ThisForm.lstListBox1.List(nCnt) && Show item
      ENDIF
   ENDFOR

ENDDEFINE

See Also

Other Resources

Properties
AddItem Method
List Property
ListItemID Property
RemoveItem Method


ListIndex Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
ListIndex Property (Visual FoxPro)
See Also

Specifies the index number of the selected item in a ComboBox or ListBox control. Not available at design time; read/write at run time.

Control.ListIndex[ = nIndex]

Return Value

nIndex

The settings for the ListIndex property are:

Setting Description

0

(Default) Indicates no items selected. For a combo box, this means that the user has entered a value not in the list.

1 ... ListCount

The index of the selected item.

Remarks

Applies To: ComboBox | ListBox

The following displays the string of the selected item.

Copy Code
? List(MyList.ListIndex)

You can return the same value by using the control's Value property.

Setting the MultiSelect property of a ListBox to .T. allows more than one item to be selected. In this case, the ListIndex will contain the index of the item that currently has the selection border.

See Also

Other Resources

Properties
AddItem Method
AddListItem Method
IndexToItemID Method
ItemIDToIndex Method
List Property
ListCount Property
ListItem Property
RemoveItem Method
Value Property


ListItem Property

Visual FoxPro 9.0 Language Reference
ListItem Property
See Also

A character string array used to access the items in a ComboBox or ListBox control by item ID. Not available at design time; read/write at run time.

Control.ListItem(nRow [, nCol])[ = cChar]

Return Value

nRow

Specifies the row from which to retrieve the item. You can use the Control.listitemID property.
nCol

Specifies, optionally, the column from which to derive the value. If you specify only listitemID,column 1 provides the value.
nChar

Represents a value, optionally, to be assigned to the specified Control.listitem.

Remarks

Applies To: ComboBox | ListBox

Use the List property to retrieve items in the order they are displayed; use the ListItem property to retrieve items according to their item ID.

Note:
To add items to a combo box or list box, use the AddItem or AddListItem method. To remove items, use the RemovetItem method or the RemoveListItem method. To keep items in alphabetic order, set the control's Sorted property to True (.T.) before adding items to the list.

The ListItem property is also set when the Selected property on a Listbox control is set.

See Also

Other Resources

Properties
AddItem Method
AddListItem Method
IndexToItemID Method
ItemIDToIndex Method
ListCount Property
List Property
ListItemID Property
Selected Property


ListItemID Property

Visual FoxPro 9.0 Language Reference
ListItemID Property
See Also

Specifies the unique ID number for the selected item in a ComboBox or ListBox control. Not available at design time; read/write at run time.

Control.ListItemID[ = nItemID]

Return Value

nItemID

The settings and interpretations for the ListItemID property are:

nItemID Description

0

Indicates that no items are selected.

Note:
For ComboBox controls, the value 0 means that the user has entered a value not in the list.

1 or any number greater than 1

The item ID of the selected item.
The ListItemID property is also set when the SelectedID property on a ListBox control is set.

Remarks

Applies To: ComboBox | ListBox

If the RemoveListItem method is used to remove an item from a list, all remaining items retain their unique identification numbers. When the AddItem method is used to add an item to a list, and the Sorted property is set to False (.F.), nItemID is assigned the lowest number available. When the AddListItem method is used to add an item to a list, and the Sorted property is set to False (.F.), you can assign any number to nItemID.

See Also

Other Resources

Properties
AddItem Method
AddListItem Method
IndexToItemID Method
ItemIDToIndex Method
ListCount Property
List Property
ListItem Property
RemoveItem Method
RemoveListItem Method
SelectedID Property


LockColumns Property

Visual FoxPro 9.0 Language Reference
LockColumns Property
See Also Example

Specifies the number of columns to lock in the right panel of a grid, beginning at the left edge. Read/write at design time and run time.

After LockColumns is set, the ability to move columns is disabled. Locked columns remain in the grid or Browse window when tabbing to the right.

Grid.LockColumns [ = nValue ]

Parameters

nValue

Numeric data type. Specifies a number of columns to lock in the right panel of a grid. The default value is 0. If nValue is greater than 0, setting nValue to 0 removes the current number of columns locked.

Remarks

Applies To: Grid Control | BROWSE Command

A grid always contains two panels; however, only the right panel is visible when in default mode. You can activate the left panel by setting the SplitBar property to True (.T.) and dragging the split bar in the user interface to expose the left panel, or by setting a value for the Partition property.

A column separator line, which appears 1 pixel wider than the line separating the other columns, indicates the area where the locked columns end and the normal columns begin.

LockColumns applies only to the right grid panel, which is displayed by default. To lock columns in the left grid panel, when exposed via the Partition or SplitBar properties, use the LockColumnsLeft property.

The Column SetFocus method does not work if a column is locked and not visible in the grid window, for example, scrolled off to the left side.

When any of the locked columns scroll out of the Grid window to the left, they remain out of view and do not become visible again until locking is removed. For example, suppose a grid contains five columns, and the data source has ten columns. When you scroll two columns to the right, the first and second columns scroll out of the grid to the left.

Suppose you set LockColumns with the following code:

Copy Code
Grid.LockColumns = 3

The first, second, and third columns are now locked. The third column appears as the first visible column in the locked grid, even though the first and second columns still exist and remain out of view. You cannot scroll to the left to view all of the locked columns. This functionality is useful if you want to lock the columns in the middle of the grid and do not want to display the preceding or following columns.

Example

The following example demonstrates how to use LockColumns with BROWSE ... NAME:
Copy Code
CLOSE DATABASES
OPEN DATABASE testdata && Open testdata database in \Samples\Data.
USE Customer
BROWSE NAME Customer
Customer.LockColumns = 2 && Locks first two columns in right pane.

See Also

Tasks

How to: Configure Browse Windows or Grids

Other Resources

Properties
SplitBar Property
Partition Property
LockColumnsLeft Property
SetFocus Method


LockColumnsLeft Property

Visual FoxPro 9.0 Language Reference
LockColumnsLeft Property
See Also Example

Specifies the number of columns to lock in the left panel of a grid, beginning at the left edge. Read/write at design time and run time.

Locked columns remain in the grid or Browse window when tabbing to the right. LockColumnsLeft applies only to the left grid panel, which is not displayed by default. After LockColumns is set, the ability to move columns is disabled.

Grid.LockColumnsLeft [ = nValue ]

Return Value

nValue

Numeric data type. Specifies a number of columns to lock in the left panel of a grid. The default value is 0. If nValue is greater than 0, setting nValue to 0 removes the current number of columns locked.

Remarks

Applies To: Grid Control | BROWSE Command

A column separator line, which appears 1 pixel wider than the line separating the other columns, indicates the area where the locked columns end and the normal columns begin.

To lock columns in the right panel of the grid, use the LockColumns property.

Example

The following example demonstrates how to use LockColumnsLeft with BROWSE ... NAME:
Copy Code
CLOSE DATABASES
&& Open testdata database in \Samples\Data.
OPEN DATABASE testdata
USE Customer
BROWSE NAME Customer
&& Locks first two columns in left pane.
Customer.LockColumnsLeft = 2

See Also

Tasks

How to: Configure Browse Windows or Grids

Other Resources

Properties
LockColumns Property


LockScreen Property

Visual FoxPro 9.0 Language Reference
LockScreen Property
See Also

Determines whether a form batches all changes to property settings for its contained objects. Available at design time and run time.

Object.LockScreen[ = lExpr]

Return Value

lExpr

The settings for the LockScreen property are:

Setting Description

True (.T.)

The form's contained objects reflect changes in property settings only when LockScreen is reset to false (.F.) rather than as soon as the changes are made.

False (.F.)

(Default) The form's contained objects reflect changes in property settings as soon as the changes are made.

Remarks

Applies To: Form | _SCREEN | ToolBar

Set LockScreen to True (.T.) to reduce annoying screen refreshes when presentation properties such as BackColor, FontName, and so on are changed during run time.

The LockScreen property does not prevent changes to the form from being reflected immediately. For example, even if LockScreen is set to true, the form is moved if you call its Move method.

Note:
If you set LockScreen to False (.F.), the form's contained controls are repainted immediately.

See Also

Other Resources

Properties
Paint Event


MacDesktop Property

Visual FoxPro 9.0 Language Reference
MacDesktop Property
See Also

Specifies whether a form is placed in the main Visual FoxPro window. Included for backward compatibility.

Copy Code
Object.MacDesktop[ = nValue]

Property Values

nValue

The settings for the MacDesktop property are:

Setting Description

0

(Default) Automatic. The form is contained in the Visual FoxPro main window according to the setting established with the SET MACDESKTOP command. If SET MACDESKTOP is set to ON, the form exists at the level of the Macintosh desktop; if set to OFF, the form is contained within the Visual FoxPro main window.

1

Macintosh Desktop. The form exists at the level of the Macintosh desktop, and can be moved and resized independently of the main Visual FoxPro window.

2

Visual FoxPro Desktop. The form is contained in the Visual FoxPro main window and cannot be moved outside it.

Remarks

Applies To: Form

Setting the MacDesktop property enables you to override for individual forms the setting established with the SET MACDESKTOP command. SET MACDESKTOP affects user-defined windows (forms) and system windows such as the Browse, View, and Form Designer windows. By default, user-defined windows behave according to the SET MACDESKTOP setting.

The MacDesktop property enables you to control whether your applications resemble Macintosh applications or Windows applications.

See Also

Other Resources

SET KEYCOMP


MainFile Property

Visual FoxPro 9.0 Language Reference
MainFile Property
See Also

Contains the name and path of the file set as the main program in a project. Read-only.

Object.MainFile

Remarks

Applies To: Project Object

MainFile contains the empty string if a main program has not been set for a project. A program or form can be set as the main program in a project by right-clicking the program or form and choosing Set Main from the shortcut menu. You can also use the SetMain method to programmatically specify a main program for a project.

See Also

Other Resources

Properties
SetMain Method


MapBinary Property

Visual FoxPro 9.0 Language Reference
MapBinary Property
See Also

The CursorAdapter MapBinary property enables default data type mapping from ODBC and ADO data types to Visual FoxPro Varbinary Blob types.

The XMLAdapter MapBinary property enables default data type mapping from XML data types to Visual FoxPro Varbinary Blob types.

Read/write at design time and run time.

Object.MapBinary [= lValue]

Return Value

lValue

Enables default data type mapping from for ODBC, ADO, and XML data source types. The following table describes the values for lValue.

lValue Description

True (.T.)

For CursorAdapter objects, the following data type mapping occurs by default:

  • ODBC SQL_LONGVARBINARY type maps to Blob type.

  • ODBC SQL_BINARY and SQL_VARBINARY ODBC types map to Varbinary type when the precision of the corresponding column in the data source is equal to or less than 254 bytes. Otherwise, if precision is greater than 254 bytes, these types are mapped to the Blob type.

  • For ADO types, adVarBinary and adBinary map to Varbinary type when the precision of the corresponding column in the data source is equal to or less than 254 bytes. Otherwise, if precision is greater than 254 bytes, these types are mapped to the Blob type.

For XMLAdapter objects, the LoadXML method maps all binary types to Varbinary type if their size is less than or equal to 254 bytes. Otherwise, if their size is greater than 254 bytes, binary types map to Blob type. When XMLField DataType property is set to Varbinary or Blob, XMLField IsBinary is set to True (.T.), and XMLField DisableEncode is set to False (.F.) automatically.

Note:
You cannot change the IsBinary and DisableEncode properties while XMLField DataType is set to Varbinary.

False (.F.) (Default)

For CursorAdapter objects, prevents default mapping from remote types to Visual FoxPro Varbinary and Blob types. For more information, see Data Type Conversion Control.

For XMLAdapter objects, prevents default mapping from XML types to Visual FoxPro Varbinary and Blob data types. For more information, see Visual FoxPro and XML Schema Data Type Mapping.

Remarks

Applies To: CursorAdapter | XMLAdapter

See Also

Other Resources

Visual FoxPro Data and Field Types
AddTableSchema Method
LoadXML Method
IsBinary Property
DisableEncode Property
Properties


MapN19_4ToCurrency Property

Visual FoxPro 9.0 Language Reference
MapN19_4ToCurrency Property
See Also Example

Specifies whether to map the XML type xsd:decimal to the Visual FoxPro Currency data type when the XML facets totalDigits and fractionDigits are 19 and 4 respectively. You can set the MapN19_4ToCurrency property to preserve precision. Read/write.

MapN_4ToCurrency applies only when executing the LoadXML and Attach methods, which retrieve XML consistent with its setting.

XMLAdapter.MapN19_4ToCurrency [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

Does not map xsd:decimal to Currency. (Default)

True (.T.)

Map xsd:decimal to Currency. The XML facets totalDigits and fractionDigits must be 19 and 4 respectively.

Remarks

Applies To: XMLAdapter Class

By default, Visual FoxPro maps xsd:decimal to Numeric. However, you can retain currency type precision by mapping xsd:decimal to Currency instead of Numeric. For example, SQL Server currency fields are represented in XML as decimal 19,4 with 19 total digits and 4 digits following the decimal point.

For more information about Visual FoxPro and XSD data type mapping, see Visual FoxPro and XML Schema Data Type Mapping.

Example

The following example shows how the XML schema type simpleType, as defined, is mapped to Currency in Visual FoxPro:
Copy Code
<xsd:simpleType>
   <xsd:restriction base="xsd:decimal">
   <xsd:totalDigits value="19"/>
   <xsd:fractionDigits value="4"/>
   </xsd:restriction>
   </xsd:simpleType>

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
Currency Data Type
Numeric Data Type
LoadXML Method
Attach Method


MapVarchar Property

Visual FoxPro 9.0 Language Reference
MapVarchar Property
See Also

The MapVarchar property for the CursorAdapter enables default data type mapping from ODBC and ADO data types to the Visual FoxPro Varchar data type.

The MapVarchar property for the XMLAdapter enables default data type mapping from XML data types to the Visual FoxPro Varchar data type.

Read/write at design time and run time.

Object.MapVarchar [= lValue]

Return Value

lValue

Enables default data type mapping from ODBC, ADO, and XML data types to the Visual FoxPro Varchar data type The following table describes the values for lValue.

lValue Description

True (.T.)

For CursorAdapter objects, the following data type mapping occurs by default:

  • SQL_WVARCHAR and SQL_VARCHAR ODBC data types map to Varchar type when the precision of the corresponding column in the data source is equal to or less than 254 bytes. Otherwise, if precision is greater than 254 bytes, these types are mapped to the Memo type.

  • adVarChar and adVarWChar ADO data types map to Varchar type when possible.

For XMLAdapter objects, Visual FoxPro maps data that was previously mapped to Character type to Varchar type instead.

False (.F.) (Default)

For CursorAdapter objects, prevents default mapping from remote types to the Visual FoxPro Varchar data type. For more information, see Data Type Conversion Control.

For XMLAdapter objects, prevents default mapping from XML types to the Visual FoxPro Varchar data type. For more information, see Visual FoxPro and XML Schema Data Type Mapping.

Remarks

Applies To: CursorAdapter | XMLAdapter

See Also

Other Resources

Visual FoxPro Data and Field Types
Properties


Margin Property

Visual FoxPro 9.0 Language Reference
Margin Property
See Also

Specifies the margin width created in the text portion of the control. Available at design time and run time.

Control.Margin[ = nValue]

Return Value

nValue

Specifies the margin created in the text portion of the control.

Remarks

Applies To: ComboBox | EditBox | Spinner | TextBox

Use the Margin property to specify the position of text on the control. The Margin property creates a margin in the interior portion of the control; it doesn't affect the size of the control.

See Also

Other Resources

Properties
Alignment Property


MaxButton Property

Visual FoxPro 9.0 Language Reference
MaxButton Property
See Also

Specifies whether a form has a Maximize button. Available at design time and run time.

Object.MaxButton[ = lExpr]

Return Value

lExpr

The settings for the MaxButton property are:

Setting Description

True (.T.)

(Default) The form has a Maximize button.

False (.F.)

The form doesn't have a Maximize button.

Remarks

Applies To: Form | _SCREEN

A Maximize button enables a user to enlarge a form to full-screen size.

A Maximize button automatically becomes a Restore button when a window is maximized. Minimizing, or restoring, a window automatically changes the Restore button back to a Maximize button.

The settings you specify for MaxButton, MinButton, BorderStyle, and ControlBox are not reflected in the form's appearance until run time.

Maximizing a form at run time triggers the Resize event.

Note:
The WindowState property reflects the current state of the window. If you set the WindowState property to 2 (Maximized), the form is maximized independently of whatever settings are in effect for the MaxButton and BorderStyle properties.

See Also

Other Resources

Properties
BorderStyle Property
ControlBox Property
MinButton Property
Resize Event
TitleBar Property
WindowState Property


MaxHeight Property

Visual FoxPro 9.0 Language Reference
MaxHeight Property
See Also

Determines the maximum height to which a form can be sized. Available at design time and run time.

Object.MaxHeight[ = nHeight]

Return Value

nHeight

The maximum height, in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: Form | _SCREEN

When the user sizes a form by choosing either the Size command from the Control menu or by dragging the borders of the form, the form doesn't exceed the height specified in the MaxHeight property setting.

The default setting for the MaxHeight property is – 1; no maximum height is specified.

See Also

Other Resources

Properties
ScaleMode Property


MaxLeft Property

Visual FoxPro 9.0 Language Reference
MaxLeft Property
See Also

Specifies the distance a maximized form is from the left edge of the main Visual FoxPro window. Available at design time and run time.

Object.MaxLeft[ = nMaxLeft]

Return Value

nMaxLeft

Specifies the distance from the left edge of the main Visual FoxPro window to the left edge of the maximized form, in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: Form | _SCREEN

Use the MaxLeft property to ensure that a maximized form does not get moved too far to the left in the main Visual FoxPro window at run time.

See Also

Other Resources

Properties
MaxTop Property
MaxWidth Property
MinHeight Property
Scalemode Property


MaxLength Property

Visual FoxPro 9.0 Language Reference
MaxLength Property
See Also

Specifies the maximum length in characters that can be entered in an EditBox, TextBox, or ComboBox control. For XMLField objects, MaxLength specifies the total length of the Character or Numeric field in a cursor when using the XMLTable ToCursor method or in an XML schema when using the XMLAdapter ToXML method. Available at design time and run time. There are two versions of the syntax.

Control.MaxLength [= nMaxLength]
XMLField.MaxLength [= nMaxLength]

Return Value

nMaxLength

Specifies the maximum number of characters that can be entered in an edit box, text box, or combo box. When nMaxLength is set to 0, there is no limit to the number of characters that can be entered into an edit box. For text and combo boxes, the size of the text or combo box and its data type determines the number of characters that can be entered. For XMLField objects, MaxLength for Memo fields is 2147483647. For Numeric, Float, and Double fields, MaxLength is the same as XML facet totalDigits+1.

Remarks

Applies To: ComboBox | EditBox | TextBox | XMLField Class

For text or combo boxes, MaxLength applies only when set to a value greater than 0, and the control does not use the InputMask property. For combo boxes, MaxLength is significant only when Style is set to 0 and applies only to the text box portion of the combo box. The Value property of the text box must be of Character type; however, the Value property of a combo box can be other types, such as Numeric.

If the ControlSource property of a control is bound to a field, Visual FoxPro truncates any characters entered that exceed the length of the field.

See Also

Other Resources

Properties
ToCursor Method
ToXML Method
InputMask Property
Value Property
Style Property
ControlSource Property
SelLength Property


MaxRecords Property

Visual FoxPro 9.0 Language Reference
MaxRecords Property
See Also

Specifies the maximum number of rows to fetch when result sets are returned. When working with this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions. Read/write.

Note:
Setting MaxRecords applies only to CursorAdapter objects with ODBC or ADO data sources and overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

CursorAdapter.MaxRecords [= nValue]

Return Value

nValue

Numeric data type. The nValue parameter has a default value of -1, which specifies that all rows be returned. Setting nValue to 0 specifies that the view is executed, but no results are fetched.

Remarks

Applies To: CursorAdapter Class

MaxRecords applies primarily for remote views and setting it does not affect local views. However, you can preset this property for local views that will be upsized.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


MaxTop Property

Visual FoxPro 9.0 Language Reference
MaxTop Property
See Also

Specifies the distance a maximized form is from the top edge of the main Visual FoxPro window. Available at design time and run time.

Object.MaxTop[ = nMaxTop]

Return Value

nMaxTop

Specifies the distance from the top edge of the main Visual FoxPro window to the top edge of the maximized form, in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: Form | _SCREEN

This property is ignored in Visual FoxPro for the Macintosh.

Use the MaxTop property to ensure that a maximized form doesn't get moved too close to the top of the main Visual FoxPro window at run time.

See Also

Other Resources

Properties
MaxLeft Property
MaxWidth Property
MinHeight Property
MinWidth Property
Scalemode Property


MaxWidth Property

Visual FoxPro 9.0 Language Reference
MaxWidth Property
See Also

Specifies the maximum width a form can be resized to. Available at design time and run time.

Object.MaxWidth[ = nMaxWidth]

Return Value

nMaxWidth

Specifies the maximum width a form can be resized to, in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: Form | _SCREEN

When the user sizes a form by choosing either the Size command from the Control menu or dragging the borders of the form, the form doesn't exceed the width specified in the MaxWidth property setting.

The default for the MaxWidth property setting is –1; no maximum width is specified.

See Also

Other Resources

Properties
MaxHeight Property
MinHeight Property
MinWidth Property
ScaleMode Property


MDIForm Property

Visual FoxPro 9.0 Language Reference
MDIForm Property
See Also

Specifies if the form is multiple-document interface (MDI) compliant.

Syntax

Copy Code
Object.MDIForm [= lValue]

Property Value

IExpr

The settings for the MDIForm property are:

Setting Description

True (.T)

The form will be combined with a parent form when maximized.

False (.F)

(Default) The form is always in a separate window.

Remarks

Set a form's MDIForm property to True (.T.) if you want the child form to be combined with the parent when maximized, or to False (.F.) if the child window should be retained as a separate window when maximized.

See Also

Other Resources

Language Reference


MemberClass Property

Visual FoxPro 9.0 Language Reference
MemberClass Property
See Also Example

Specifies the name of the member class to use when adding new members to a container. Read/write at design time and run time.

For a Column parent container and its header members, use the HeaderClass property instead of MemberClass.

Note:
If the member class is based on a class that is stored in a program (.prg) file, make sure that the compiled program (.fxp) file is synchronized with the .prg file.

Object.MemberClass [ = cClassName ]

Return Value

cClassName

Specifies the name of a member class in a program (.prg) or visual class library (.vcx) file.

Remarks

Applies To: PageFrame Control | CommandGroup Control | OptionGroup Control | Grid Control

Visual FoxPro creates a member object using MemberClass under the following conditions:

  • MemberClass is specified for a container class definition at design time. When Visual FoxPro creates the container, it instantiates members using MemberClass.

  • The member object's Count property, such as the PageCount, ButtonCount, or ColumnCount properties, is increased at run time. If the member object's Count property is programmatically or interactively increased, Visual FoxPro adds new instances using MemberClass.

    Note:
    The ColumnCount property is unique in that you can specify its value as -1 or 0. All other Count properties must be greater than or equal to zero.

Both MemberClass and MemberClassLibrary support the Access and Assign methods and Public, Hidden and Protected scope.

A container can hold objects of different member classes with the same base class. For example, suppose you have a PageFrame object and two member classes, myPage1 and myPage2, defined as Page classes. You can specify myPage1 for the PageFrame MemberClass property at design time and change PageFrame MemberClass to myPage2 at run time, followed by an increase in the PageFrame PageCount property.

The MemberClass and MemberClassLibrary properties have the following additional behaviors at design time and run time:

  • Behavior at design time

    When setting the MemberClass and MemberClassLibrary properties at design time, you are prompted to destroy existing member classes, including property settings; new, added, or modified method code; and added objects.

    When you create a subclass from a container that specifies the MemberClass property, the subclass inherits the proper MemberClass and MemberClassLibrary properties, which you can modify.

    Visual FoxPro displays the MemberClass and MemberClassLibrary properties in the Properties window as read-only. However, you can set these properties in the Properties window by clicking the ellipsis (...) button to display the Open dialog box, browsing for, and selecting the member class and class library you want to use.

    Note:
    If you want to specify a member class for the container, you must set, not only one, but both MemberClass and MemberClassLibrary properties.

    If you are setting the member object's Count property in a program (.prg) file at design time, you must specify the member object's Count property after setting the MemberClass and MemberClassLibrary properties because of certain dependencies. For example:

    Copy Code
    DEFINE CLASS myPageFrame AS PageFrame
   MemberClassLibrary = 'MyPages.prg'
   MemberClass = 'myPage'
   PageCount = 3
ENDDEFINE
    When using the ASELOBJ( ) function to set the MemberClass and MemberClassLibrary properties individually, the following behavior occurs:

    • If you specify only the MemberClass or MemberClassLibrary property using the ASELOBJ() function, Visual FoxPro does not generate an error but disregards the property specified and uses the base class when adding a new member object.

    • If the member object's Count property is 0 (or -1 for Grid objects), Visual FoxPro does not perform error checking when setting MemberClass and MemberClassLibrary, which you can set in any order.

    • If the member object's Count property is greater than 0, Visual FoxPro performs error checking when MemberClass is set. Therefore, in this situation, you need to set MemberClassLibrary before setting MemberClass.

      Note:
      If either property is invalid, Visual FoxPro generates the appropriate message if the class or class library is invalid and sets the member object's Count property back to 0.

      If both MemberClass and MemberClassLibrary are valid, Visual FoxPro recreates all existing member classes based on the new member class, and all previous member object data is lost.

      Caution:
      Visual FoxPro does not prompt you to destroy existing member classes, including property settings; new, added, or modified method code; and added objects when setting MemberClass and MemberClassLibrary in code.

      As when setting the member object's Count property in a program (.prg) file at design time, you must specify the member object's Count property after setting the MemberClass and MemberClassLibrary properties.

      You can change MemberClassLibrary to another class library that has the same MemberClass. If you increase the member object's Count property, Visual FoxPro adds a new member class using the new MemberClassLibrary. Though the designer displays member classes from different class libraries, only the most recent MemberClassLibrary persists when saving the class. Therefore, when you instantiate or open the class again, all member objects are created from the most recent MemberClassLibrary.

  • Behavior at run time

    Changing MemberClass and MemberClassLibrary affects only newly created member objects, not existing member objects in the container. You can also use the AddObject and NewObject methods, which function as usual, to specify a different class.

    Note:
    You should specify both MemberClass and MemberClassLibrary properties at run time. If you specify only MemberClass or MemberClassLibrary at run time, Visual FoxPro does not generate an error; however, it uses the base class when adding a new member and disregards the property specified.

    To reliably determine the member class used to instantiate a particular member object, use the Class and ClassLibrary properties of the member object instead of MemberClass and MemberClassLibrary because the latter properties can change at run time.

    Note:
    A container can have member objects derived from different member classes.

    Visual FoxPro does not support the capability to specify a class in a class library bound inside a compiled Visual FoxPro application (.app).

Example

The following example creates a form, adds a PageFrame container to the form, defines the PageFrame container as "myPageFrame", sets the MemberClassLibrary and MemberClass properties for "myPageFrame", defines a Page member object as "myPage", and adds code for a command button and events.
Copy Code
PUBLIC x
x = CREATEOBJECT("form")
x.ADDOBJECT("pf1","myPageFrame")
x.pf1.Visible = .T.
x.Show()

DEFINE CLASS myPageFrame AS PageFrame
   MemberClassLibrary = 'myPages.PRG'
   MemberClass = 'myPage'
   PageCount = 2
   TabOrientation = 1
ENDDEFINE

DEFINE CLASS myPage AS Page
   ADD OBJECT cmd1 AS commandbutton WITH ;
      Caption = "Hello", FontBold = .T.
   PROCEDURE Init
      THIS.Caption = "Funpage"+TRANSFORM(THIS.Parent.PageCount)
   ENDPROC
   PROCEDURE cmd1.Click
      MESSAGEBOX(this.Caption)
      THIS.Parent.Parent.PageCount = THIS.Parent.Parent.PageCount+1
   ENDPROC
ENDDEFINE

See Also

Other Resources

Properties
Member Classes
MemberClassLibrary Property
HeaderClass Property
HeaderClassLibrary Property
ASELOBJ( ) Function


MemberClassLibrary Property

Visual FoxPro 9.0 Language Reference
MemberClassLibrary Property
See Also

Specifies the name of the class library containing the member class in the MemberClass property. Read/write at design time and run time.

For a Column parent container and its header members, use the HeaderClassLibrary property instead of MemberClassLibrary.

Object.MemberClassLibrary [ = cClassFile ]

Return Value

cClassFile

Specifies the file name containing the member class in MemberClass.

Remarks

Applies To: PageFrame Control | CommandGroup Control | OptionGroup Control | Grid Control

Visual FoxPro includes the MemberClassLibrary visual class library (.vcx) or program (.prg) in the project during a project build.

If you set MemberClassLibrary at run time, you must use the full file name including the file extension.

If you specify MemberClassLibrary without specifying MemberClass, Visual FoxPro does not generate an error; however, it uses the base class when adding a new member and disregards the property specified.

For additional information about the MemberClassLibary and MemberClass properties, see MemberClass Property.

See Also

Other Resources

Properties
Member Classes
MemberClass Property
HeaderClassLibrary Property


Message Property

Visual FoxPro 9.0 Language Reference
Message Property
See Also

Specifies the actual error message for an exception object. Read/write at run time.

Exception.MessageProperty

Return Value

Character data type

Remarks

Applies To: Exception Class

Identical to the value returned by the MESSAGE() function and the second element in the array produced by the AERROR() function.

See Also

Other Resources

Properties
Exception Object Properties, Methods, and Events
MESSAGE( ) Function
AERROR( ) Function
TRY...CATCH...FINALLY Command
Structured Error Handling


MinButton Property

Visual FoxPro 9.0 Language Reference
MinButton Property
See Also

Specifies whether a form has a Minimize button. Available at design time and run time.

Object.MinButton[ = lExpr]

Return Value

lExpr

The settings for the MinButton property are:

Setting Description

True (.T.)

(Default) The form has a Minimize button.

False (.F.)

The form does not have a Minimize button.

Remarks

Applies To: Form | _SCREEN

A Minimize button enables users to minimize a Form window to an icon.

The settings you specify for MaxButton, MinButton, BorderStyle, and ControlBox are not reflected in the Form's appearance until run time.

In Microsoft Windows version 3.0 or later, an MDI child form is displayed with a Minimize button regardless of the setting of MinButton. However, if MinButton is set to false (.F.), it is disabled, and the corresponding Minimize command is not on the form's Controlbox menu.

Minimizing a form to an icon at run time generates a Resize event. The WindowState property reflects the current state of the window. If you set the WindowState property to 1 (Minimized), the Form is minimized independently of whatever settings are in effect for the MinButton and BorderStyle properties.

See Also

Other Resources

Events
BorderStyle Property
ControlBox Property
MaxButton Property
TitleBar Property
WindowState Property


MinHeight Property

Visual FoxPro 9.0 Language Reference
MinHeight Property
See Also

Specifies the minimum height that a form can be resized to. Available at design time and run time.

Object.MinHeight[ = nHeight]

Return Value

nHeight

The minimum height that the form can be resized to, in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: Form | _SCREEN

When the user sizes a form by choosing either the Size command from the Control menu or by dragging the borders of the form, the form does not become any shorter than the height specified in the MinHeight property setting.

The default setting for the MinHeight property setting is –1; no minimum height is specified.

See Also

Other Resources

Events
MaxHeight Property
MaxWidth Property
MinWidth Property
ScaleMode Property


MinWidth Property

Visual FoxPro 9.0 Language Reference
MinWidth Property
See Also

Specifies the minimum width that a form can be resized to. Available at design time and run time.

Object.MinWidth[ = nWidth]

Return Value

nWidth

The minimum width that the form can be resized to, in the unit of measurement specified by the ScaleMode property of the Form.

Remarks

Applies To: Form | _SCREEN

When the user sizes a Form by choosing either the Size command from the Control menu or by dragging the borders of the form, the Form cannot be made any narrower than the width specified in the MinWidth property setting.

The default setting for the MinWidth property is – 1; no minimum width is specified.

See Also

Other Resources

Events
MaxHeight Property
MaxWidth Property
MinHeight Property
ScaleMode Property


MouseIcon Property

Visual FoxPro 9.0 Language Reference
MouseIcon Property
See Also

Specifies the mouse pointer icon displayed when the mouse pointer is positioned over an object. Available at design time and run time.

Object.MouseIcon[ = cFileName]

Return Value

cFileName

Specifies the file that is displayed when the mouse pointer is positioned over the object. You can specify a mouse icon (.ico) file, a mouse cursor (.cur) file, or an animated mouse cursor (.ani) file.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | _SCREEN | Shape | Spinner | TextBox | ToolBar

To display the mouse icon, set the MousePointer property to 99 (Custom).

See Also

Other Resources

Properties
MousePointer Property


MousePointer Property

Visual FoxPro 9.0 Language Reference
MousePointer Property
See Also

Specifies the shape of the mouse pointer when you move the mouse over a particular part of an object at run time. Read/write at design time and run time.

You can use the MousePointer property to indicate changes in functionality as the mouse pointer passes over controls on a form or dialog box.

Object.MousePointer [= nType]

Return Value

nType

Specifies a value representing the shape of the mouse pointer.
Note:
When you set the MousePointer property using the Properties window, the drop-down list displays the setting names used in Visual FoxPro for Windows.

The following table lists the values for nType.

nType Description

0

Shape determined by the object. (Default)

1

Arrow.

2

Cross (cross-hair pointer).

3

I-beam.

4

Icon (small white square within a black square).

5

Size (four-pointed arrow pointing up, down, left, and right).

6

Size NE SW (double arrow pointing diagonally from bottom left to top right).

7

Size NS (double arrow pointing vertically up and down).

8

Size NW SE (double arrow pointing diagonally from bottom right to top left).

9

Size WE (double arrow pointing horizontally left and right).

10

Up arrow.

11

Hourglass or wristwatch.

Tip:
To indicate that the user should wait for a process to finish, set the MousePointer property to 11.

12

No drop.

13

Hide pointer.

14

Arrow.

Note:
Not a valid property value for grids. If set for grids, returns the error, "Expression evaluated to an illegal value."

15

Hand.

Note:
When running Visual FoxPro applications on Windows 2000 operating systems, an arrow appears instead of a hand.

16

Down arrow.

Tip:
This setting is particularly useful if the parent column of a header overrides the default setting for the header's MousePointer property.

99

Custom. Uses pointer specified in object's MouseIcon property.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | _SCREEN | Shape | Spinner | TextBox | ToolBar

See Also

Other Resources

Properties
MouseMove Event
MouseIcon Property


Movable Property

Visual FoxPro 9.0 Language Reference
Movable Property
See Also

Specifies whether an object can be moved at run time by the user. Available at design time; read-only at run time.

Object.Movable[ = lExpr]

Return Value

lExpr

The settings for the Movable property are:

Setting Description

True (.T.)

(Default) The object can be moved. For forms in Visual FoxPro for Windows, the Move command is added to the Control menu.

False (.F.)

The object cannot be moved. For grid columns, you cannot move the column by direct manipulation. However, the column can be moved if you change the column's ColumnOrder property or move another column on top of it.

Remarks

Applies To: Column | Form | _SCREEN | ToolBar

See Also

Other Resources

Properties
Sizable Property


MoverBars Property

Visual FoxPro 9.0 Language Reference
MoverBars Property
See Also

Specifies whether mover bars are displayed on a ListBox control. Available at design time; read/write at run time.

ListBox.MoverBars[ = lExpr]

Return Value

lExpr

The settings for the MoverBars property are:

Setting Description

True (.T.)

Display mover bars.

Users can interactively reorganize the contents of the control.

False (.F.)

Does not display mover bars. (Default)

Remarks

Applies To: ListBox

You can select and move an item by pressing CTRL+UP ARROW, CTRL+DOWN ARROW, using the mouse, or programmatically by calling the MoveItem method. The OnMoveItem event occurs when an item moves up or down in a list box.

The MoverBars property is available only if the RowSourceType property is set to 0 (None) or 1 (Value).

See Also

Other Resources

Properties
RowSourceType Property
ScrollBars Property
OnMoveItem Event
MoveItem Method


MultiSelect Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
MultiSelect Property (Visual FoxPro)
See Also Example

Specifies whether a user can make multiple selections in a ListBox control and how the multiple selections can be made. Available at design time; read/write at run time.

ListBox.MultiSelect[ = nChoice]

Return Value

nChoice

The settings for the MultiSelect property are:

Setting Description

0

(Default) Multiple selection isn't allowed.

1

Multiple selection is allowed. To select multiple items in a ListBox control, hold the CTRL key down while clicking the items.

Remarks

Applies To: ListBox

Set MultiSelect to true (.T.) to enable a user to select multiple items in a list. You can use the Selected property to determine which items are selected.

Example

The following example creates a ListBox. The MultiSelect property for the list box is set to true (.T.), allowing you to make multiple selections from the list box. The source of the items that appear in the list box items is an array; the array is specified with the RowSourceType and RowSource properties.

The ListCount property is used within a FOR ... ENDFOR loop to display the item or items you choose in the list box. The Selected property is used to determine the items you chose, and the List property is used to return the items.
Copy Code
CLEAR

DIMENSION gaMyListArray(10)
FOR gnCount = 1 to 10  && Fill the array with letters
   STORE REPLICATE(CHR(gnCount+64),6) TO gaMyListArray(gnCount)
ENDFOR

frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .f.  && Disable the Control menu box

frmMyForm.Move(150,10)  && Move the form

frmMyForm.AddObject('cmbCommand1','cmdMyCmdBtn')  && Add "Quit" Command button
frmMyForm.AddObject('lstListBox1','lstMyListBox')  && Add ListBox control

frmMyForm.lstListBox1.RowSourceType = 5  && Specifies an array
frmMyForm.lstListBox1.RowSource = 'gaMyListArray' && Array containing listbox items

frmMyForm.cmbCommand1.Visible =.T.  && "Quit" Command button visible
frmMyForm.lstListBox1.Visible =.T.  && "List Box visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
      CLEAR  && Clear main Visual FoxPro window
ENDDEFINE

DEFINE CLASS lstMyListBox AS ListBox  && Create ListBox control
   Left = 10  && List Box column
   Top = 10  && List Box row
   MultiSelect = .T.  && Allow selecting more than 1 item

PROCEDURE Click
   ACTIVATE SCREEN
   CLEAR
   ? "Selected items:"
   ? "---------------"
   FOR nCnt = 1 TO ThisForm.lstListBox1.ListCount
      IF ThisForm.lstListBox1.Selected(nCnt)  && Is item selected?
         ? SPACE(5) + ThisForm.lstListBox1.List(nCnt) && Show item
      ENDIF
   ENDFOR

ENDDEFINE

See Also

Other Resources

Properties
AddItem Method
Clear Method
List Property
ListCount Property
NewItemID Property
RemoveItem Method
Selected Property
TopItemID Property


Name Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Name Property (Visual FoxPro)
See Also

Specifies the name used to reference an object in code. Available at design time; read/write at run time.

Object.Name[ = cName]

Return Value

cName

Specifies the name used to reference the object in code.

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | Cursor | CursorAdapter Class | Custom | DataEnvironment | EditBox | Exception Class | File Object | Form | FormSet | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | Project Object | ProjectHook Object | Relation | ReportListener Object | _SCREEN | Session Object | Shape | Spinner | TextBox | Timer | ToolBar

The default name for new objects is the type of object plus a unique integer. For example, the first new Form object is Form1, and the third text box you create on a Form is Text3.

Note:
If the object is the first object in the object hierarchy (that is, the outermost container object), use the object variable to reference the object instead of the Name property.

For a Project object, the Name property contains the name and path to the project, and is read-only at design time and run time.

For a File object, the Name property contains the name and path to the file, and is read-only at design time and run time.

See Also

Other Resources

Properties
Caption Property
NewIndex Property
NewItemID Property
ServerName Property
TypeLibName Property


NestedInto Property

Visual FoxPro 9.0
NestedInto Property
See Also

Specifies the parent XMLTable object for an XMLTable within a hierarchy. Read-only at design time and run time.

XMLTable.NestedInto = oXMLTable

Return Value

oXMLTable

Object reference to the parent XMLTable object.
null (.NULL.)

Property not populated. Indicates that there is no parent XMLTable.

Remarks

Applies to: XMLTable Class

See Also

Reference

Nest Method

Other Resources

Properties


NewIndex Property

Visual FoxPro 9.0 Language Reference
NewIndex Property
See Also

Specifies the index of the item most recently added to a ComboBox or ListBox control. Not available at design time; read-only at run time.

Control.NewIndex

Remarks

Applies To: ComboBox | ListBox

The NewIndex property is especially useful when adding items to a sorted list.

See Also

Other Resources

Properties
Caption Property
NewItemID Property
Name Property


NewItemID Property

Visual FoxPro 9.0 Language Reference
NewItemID Property
See Also

Specifies the item ID of the item most recently added to a ComboBox or ListBox control. Not available at design time; read-only at run time.

 [Form.]Control.NewItemID

Remarks

Applies To: ComboBox | ListBox

For more information about the differences between using an item ID or an index, see AddItem Method or AddListItem Method.

See Also

Other Resources

Properties
AddItem Method
AddListItem Method
Clear Method
ItemData Property
List Property
ListCount Property
MultiSelect Property
NewIndex Property
RemoveItem Method
Selected Property
TopItemID Property


NextSiblingTable Property

Visual FoxPro 9.0
NextSiblingTable Property
See Also

Specifies the next sibling XMLTable object for an XMLTable object nested within a hierarchy. Read-only at design time and run time.

XMLTable.NextSiblingTable = oXMLTable

Return Value

oXMLTable

An object reference to a sibling XMLTable object.
null (.NULL.)

Property not populated. Indicates that there is no sibling XMLTable object.

Remarks

Applies to: XMLTable Class

See Also

Reference

LoadXML Method
Nest Method

Other Resources

Properties


NoCpTrans Property

Visual FoxPro 9.0 Language Reference
NoCpTrans Property
See Also

Specifies whether character and memo field types are created as Character (Binary) or Memo (Binary) data types. Read/write. There are two versions of the syntax.

XMLAdapter.NoCpTrans [= lValue]
XMLField.NoCpTrans [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

Create field as normal Character or Memo field. (Default)

True (.T.)

Create field as Character (NoCpTrans) or Memo (NoCpTrans) field.

Remarks

Applies To: XMLAdapter Class | XMLField Class

For more information about Visual FoxPro and XSD data type mapping, see Visual FoxPro and XML Schema Data Type Mapping.

Setting NoCpTrans at the XMLAdapter level sets the default NoCpTrans values for XMLField objects they are created and added to the Fields collection by the following XMLAdapter methods:

  • LoadXML

  • Attach

  • AddTableSchema

Additionally, changing NoCpTrans at the XMLAdapter level affects only the next set of XMLField objects created, not the existing XMLField objects in the Fields collection. Therefore, to modify the setting of NoCpTrans for an existing XMLField object, change the value at the XMLField level.

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
XMLField Object Properties, Methods, and Events
Visual FoxPro Data and Field Types
XMLAdapter Class
Fields Collection (XMLTable)


NoData Property

Visual FoxPro 9.0 Language Reference
NoData Property
See Also

Specifies the default value for the CursorFill Method lNoData parameter. Read/write at design time and run time.

CursorAdapter.NoData [ = lExpr]

Return Value

lExpr

The settings for the NoData property are:

Setting Description

True (.T.)

Sets the default value for the CursorFill method lNoData parameter to a logical True (.T.).

If the CursorFill method is called without the lNoData parameter, the cursor is created but is not filled with data.

False (.F.)

(Default) Sets the default value for the CursorFill method lNoData parameter to a logical False (.F.).

If the CursorFill method is called without the lNoData parameter, the cursor is created and is filled with data.

Remarks

Applies To: CursorAdapter Class.

The value specified by this property is used by the CursorFill method when the lNoData parameter is omitted in the method. This property is ignored if the lNoData parameter is included in the CursorFill method.

See Also

Reference

CursorFill Method
UseCursorSchema Property


NoDataOnLoad Property

Visual FoxPro 9.0 Language Reference
NoDataOnLoad Property
See Also

Causes the view associated with a Cursor to activate without downloading data. Available at design time; read/write at run time.

DataEnvironment.Cursor.NoDataOnLoad[ = lExpr]

Return Value

lExpr

The settings for the NoDataOnLoad property are:

Setting Description

True (.T.)

The view associated with the Cursor is opened without downloading data.

False (.F.)

(Default) The view associated with the Cursor is opened with data.

Remarks

Applies To: Cursor

Note:
When the Cursor object is accessed using CURSORSETPROP(), the NoDataOnLoad property is read-only at run time.

Use the NoDataOnLoad property to ensure that the FormSet or Form associated with the view loads quickly (it can be time-consuming to download data from a backend server). You can use REQUERY( ) in conjunction with NoDataOnLoad to download data into the active view once the Form is loaded.

The NoDataOnLoad property mimics the behavior of the NODATA clause of USE.

See Also

Other Resources

Properties
REQUERY( ) Function
USE Command


NullDisplay Property

Visual FoxPro 9.0 Language Reference
NullDisplay Property
See Also

Specifies the text that is displayed to indicate null values. Available at design time and run time.

Object.NullDisplay[ = cNullText]

Return Value

cNullText

Specifies the text that is displayed for null values. .NULL. is the default value.

Remarks

Applies To: ComboBox | EditBox | ListBox | Spinner | TextBox

This property changes the null display for individual objects only. To change null display for all objects, use SET NULLDISPLAY.

See Also

Other Resources

Properties
CREATE TABLE - SQL Command
SET NULLDISPLAY Command


NumberOfElements Property

Visual FoxPro 9.0 Language Reference
NumberOfElements Property
See Also

Specifies how many items in an array are used to fill the list portion of a ComboBox or ListBox control. Available at design time and run time.

 [Form.]Control.NumberOfElements[ = nTotal]

Return Value

nTotal

Specifies the number of elements that a list can contain.

Remarks

Applies To: ComboBox | ListBox

Available only when the ListSourceType property is set to 5 (Array) and the ColumnCount property is set to 1.

NumberOfElements is useful to limit the number of elements in an array that are displayed in a list. The number of elements used for the list begins with the FirstElement property setting and includes the number of elements specified in the NumberOfElements property setting.

See Also

Other Resources

Properties
DisplayCount Property
FirstElement Property


Object Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Object Property (Visual FoxPro)
See Also

Provides access to the Automation server properties and methods for an OLE object. Not available at design time. Depending on the Automation server, the properties for the OLE object may be read-only or read/write at run time.

OLEObject.Object[.Property] [= eValue]
-or-
OLEObject.Object[.Method]

Return Value

Property

Specifies a property the Automation server supports for the OLE object.
eValue

Specifies a value for a property the Automation server supports for the OLE object.
Method

Specifies a method the Automation server supports for the OLE object

Remarks

Applies To: OLE Bound Control | OLE Container Control

For information about the properties and methods supported by the Automation server, see the documentation for the OLE–enabled application that created the object. For example, if the OLE object is a Microsoft Excel worksheet, see the Excel documentation for the properties and methods supported by Excel (an OLE–enabled application).

See Also

Other Resources

Properties
CREATEOBJECT( ) Function
GETOBJECT( ) Function


OLEClass Property

Visual FoxPro 9.0 Language Reference
OLEClass Property
See Also Example

Returns the named class ID of an OLE object. Read-only at design time and run time for an existing object, but can be set for an object when creating it.

Control.OLEClass[ = cName]

Return Value

cName

The named class ID of the object. This is the registered name of the application that was used to create the object or will be invoked if the object is activated.

Remarks

Applies To: OLE Bound Control | OLE Container Control

You set OLEClass property of an OLE container object using the Insert Object dialog box when you initially add an OLE container to a form, or in code when creating an OLE object as part of a class definition. This property is also set when you create OLE objects using the APPEND GENERAL command.

The OLEClass property of an object specifies the application that is used to create or edit the OLE object. To specify the actual contents of the object, set its DocumentFile property.

Example

The following example adds an OLE Container control to a form, and uses the OLEClass and DocumentFile properties to specify Microsoft Excel as the Automation server and an Excel worksheet as the file to edit.
Copy Code
Define class myForm as form
 add object oleXLSheet1 as oleXLSheet
EndDefine

Define class oleXLSheet as OLECONTROL
 oleclass = "Excel.Sheet"
 documentfile="C:\msoffice\Excel\mysheet.xls"
 oletypeallowed = 1  && Embedded
EndDefine

See Also

Other Resources

Properties
APPEND GENERAL Command
CREATEOBJECT( ) Function
DocumentFile Property


OLEDragMode Property

Visual FoxPro 9.0 Language Reference
OLEDragMode Property
See Also

Specifies how a drag operation is initiated. Available at design time and run time.

Object.OLEDragMode[= nValue]

Return Value

nValue

Specifies how the control or object handles OLE drag operations. The following table lists the settings for nValue.

Setting Description

0

Manual (Default).

Visual FoxPro does not initiate the OLE drag operation when you attempt to drag data. You must call the OLEDrag method to begin the drag operation.

Setting OLEDragMode to 0 provides backward compatibility (no OLE drag support) for existing applications if you do not include additional drag operation coding.

1

Automatic

Visual FoxPro allows automatically initiates a drag operation when you attempt to drag data.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

OLEDragMode is a drag source property. If the DragMode property for a control or object is set to 1 – Automatic, the control or object cannot act as an OLE drag source. This provides backward compatibility for previous drag-and-drop support in earlier versions of Visual FoxPro.

Note that OLEDragMode property is read-only for the Grid control.

See Also

Other Resources

Properties
DragMode Property
OLE Drag-and-Drop Overview
OLEDrag Method
OLEStartDrag Event


OLEDragPicture Property

Visual FoxPro 9.0 Language Reference
OLEDragPicture Property
See Also

Specifies the picture displayed under the mouse pointer during an OLE drag-and-drop operation. Available at design time and run time.

Object.OLEDragPicture[= cFileName]

Parameters

cFileName

Specifies the file name and path of the graphic to display when an OLE drag-and-drop operation occurs. The graphics file you specify can be of type .bmp, .dib, .jpg, .gif, .ani, .cur, or .ico. The graphics file is typically a translucent or outline representation of the object being dragged. To create a translucent representation of the object, use a black-and-white checkerboard mask file (.msk).

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

OLEDragPicture is a drag source property. The picture is displayed when the mouse pointer is positioned over the form containing the drag source.

See Also

Other Resources

Properties
OLE Drag-and-Drop Overview


OLEDropEffects Property

Visual FoxPro 9.0 Language Reference
OLEDropEffects Property
See Also

Specifies the type of drop operations an OLE drop target supports. Available at design time and run time.

Object.OLEDropEffects[= nDropEffect]

Return Value

nDropEffect

Specifies the type of drop operations an OLE drop target supports. The following table lists the values for nDropEffect with a description of each.

nDropEffect Foxpro.h constant Description

0

DROPEFFECT_NONE

Drop target does not accept the data as a drop target.

1

DROPEFFECT_COPY

Data can be copied to the drop target.

2

DROPEFFECT_MOVE

Data can be moved to the drop target.

4

DROPEFFECT_LINK

Data can be linked to the drop target.
A drop can support multiple drop operations by adding multiple values together for nDropEffect. For example, if nDropEffect is 3, the drop target supports both copy and move drop operations (3 = 1 (copy) + 2 (move)).

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Shape | Spinner | TextBox | ToolBar

OLEDropEffects is a drop target property, and should be set in the OLEDragOver event.

See Also

Other Resources

Properties
OLE Drag-and-Drop Overview
OLEDragOver Event
OLEDropHasData Property


OLEDropHasData Property

Visual FoxPro 9.0 Language Reference
OLEDropHasData Property
See Also

Specifies how a drop operation is managed. Available at run time and read-only at design time.

Object.OLEDropHasData[= nDropEffect]

Return Value

nDropEffect

Specifies how the drop operation is managed. The following table lists the values for nDropEffect with a description of each.

nDropEffect Foxpro.h constant Description

–1

DROPHASDATA_VFPDETERMINE

Default. Visual FoxPro automatically determines if the DataObject contains data in a format that can be dropped on the drop target.

If the DataObject contains data in a proper format for the drop target, the data is dropped on the drop target. Visual FoxPro handles the mouse pointer and notification of the drag source.

If the data isn't in the proper format for the drop target, Visual FoxPro displays the No Drop mouse pointer, the drop operation is canceled, and the drag source is notified that the drop operation was canceled.

0

DROPHASDATA_NOTUSEFUL

The DataObject does not contain data in a format that can be dropped on the drop target, and the No Drop mouse pointer is displayed.

1

DROPHASDATA_USEFUL

The DataObject contains data in a format that can be dropped on the drop target.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Shape | Spinner | TextBox | ToolBar

OLEDropHasData is a drop target property and should be set in the OLEDragOver event. Use GetFormat in the OLEDragOver event to determine if the DataObject contains data in the proper format for the drop target. If the data is in the proper format for the drop target, set OLEDropHasData to 1.

See Also

Other Resources

Properties
OLE Drag-and-Drop Overview
OLEDragOver Event
OLEDropEffects Property


OLEDropMode Property

Visual FoxPro 9.0 Language Reference
OLEDropMode Property
See Also

Specifies how a drop target manages OLE drop operations. Available at design time and run time.

Object.OLEDropMode[= nValue]

Return Value

nValue

Specifies how the control or object handles OLE drop operations. The following table lists the settings for nValue.

nValue Foxpro.h constant Description

0

DROP_DISABLED

Disabled (Default).

Data cannot be dropped onto the control or object, and no drop target events occur. The No Drop mouse pointer is displayed when the mouse pointer is positioned over the control or object.

Setting OLEDropMode to 0 provides backward compatibility (no OLE drop support) for existing applications.

1

DROP_ENABLED

Enabled.

Visual FoxPro allows the dropping of data onto the control or object, and drop target events occur.

2

DROP_PASSTOCONTAINER

Pass to Container.

The control or object behaves as if it is disabled for OLE drop operations, and the data is dropped on the container for the control or object.

The container's OLEDropMode property must be set to 1 or 2 to accept the data. The No Drop mouse pointer is displayed if the container's OLEDropMode property is set to 0.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Shape | Spinner | TextBox | ToolBar

OLEDropMode is a drop target property. If the DropMode property for a control or object is set to 0 – Disabled, the control or object cannot act as an OLE drop source. This provides backward compatibility for previous drag-and-drop support in earlier versions of Visual FoxPro.

If the Enabled property of a control or object is set to false (.F.), you cannot drop data on the control or object. For drop operations, the No Drop mouse pointer is displayed when the Enabled property of a control or object is set to false (.F.).

See Also

Other Resources

Properties
Enabled Property
OLE Drag-and-Drop Overview


OLEDropTextInsertion Property

Visual FoxPro 9.0 Language Reference
OLEDropTextInsertion Property
See Also

Specifies if you can drop text in the middle of a word in the text box portion of a control.

Object.OLEDropTextInsertion[= lExpression]

Parameters

lExpression

The settings for the OLEDropTextInsertion property are:

Setting Description

0

(Default) Text can be dropped into a word.

1

Text can only be dropped before or after a word.

Remarks

Applies To: ComboBox | EditBox | Spinner | TextBox

The OLEDropMode property of a control must be set to 1 – Enabled to drop text in the text box portion of the control.

See Also

Other Resources

Properties
OLE Drag-and-Drop Overview
OLEDropMode Property


OLELCID Property

Visual FoxPro 9.0 Language Reference
OLELCID Property
See Also

Contains a numeric value indicating the Locale ID for an OLE Bound control or an OLE Container control. Read-only at design time and run time.

Control.OLELCID

Remarks

Applies To: OLE Bound Control | OLE Container Control

The Locale ID value is determined by the value of the DefOLELCID property for the form or the main Visual FoxPro window when an OLE Bound control or an OLE Container control is placed on the form or the main Visual FoxPro window.

If the form or the main Visual FoxPro window's DefOLELCID property is zero when the OLE Bound control or OLE Container control is placed on the form or the main Visual FoxPro window, the control uses the current Visual FoxPro Locale ID (LCID). Use SYS(3004) to determine the current Visual FoxPro Locale ID. Use the DefOLELCID property to specify a Locale ID for a form.

See SYS(3005) for a listing of Locale IDs.

Note:
The OLELCID property only affects the language of the user interface, which OLE controls display, and not the language of the Automation commands. The Automation command language is affected only by the Global LocaleID, set with SYS(3005).

See Also

Other Resources

Properties
DefOLELCID Property
SYS(3005) - Set Locale ID


OLERequestPendingTimeout Property

Visual FoxPro 9.0 Language Reference
OLERequestPendingTimeout Property
See Also

Specifies how long after an Automation request is made before a busy message is displayed. Read/write at run time.

ApplicationObject.OLERequestPendingTimeout[ = nMilliseconds]

Return Value

nMilliseconds

Specifies the number of milliseconds that must elapse before a busy message is displayed when an Automation request is pending. The busy message is displayed when a mouse or keyboard event occurs. The default value for nMilliseconds is 5,000 milliseconds. If nMilliseconds is 0, a busy message isn't displayed when an Automation request is pending and a mouse or keyboard event occurs.

Remarks

Applies To: Application Object | _VFP System Variable

See Also

Other Resources

Properties
OLEServerBusyRaiseError Property
OLEServerBusyTimeout Property


OLEServerBusyRaiseError Property

Visual FoxPro 9.0 Language Reference
OLEServerBusyRaiseError Property
See Also

Specifies whether an error message is displayed when an Automation request is rejected. Read/write at run time.

ApplicationObject.OLEServerBusyRaiseError[ = lExpression]

Return Value

lExpression

One of the following settings:

Setting Description

.T. (True)

An error doesn't occur and a busy message is not displayed when the number of milliseconds specified by the OLEServerBusyTimeout property have elapsed.

.F. (False)

(Default) An error occurs and a busy message is displayed when the number of milliseconds specified by the OLEServerBusyTimeout property have elapsed.

Remarks

Applies To: Application Object | _VFP System Variable

See Also

Other Resources

Properties
OLERequestPendingTimeout Property
OLEServerBusyTimeout Property


OLEServerBusyTimeout Property

Visual FoxPro 9.0 Language Reference
OLEServerBusyTimeout Property
See Also

Specifies how long an Automation request is retried while a server is busy. Read/write at run time.

ApplicationObject.OLEServerBusyTimeout[ = nMilliseconds]

Return Value

nMilliseconds

Specifies the number of milliseconds for which an Automation request is retried before a server busy message is displayed.

Remarks

Applies To: Application Object | _VFP System Variable

See Also

Other Resources

Properties
OLERequestPendingTimeout Property
OLEServerBusyRaiseError Property


OLETypeAllowed Property

Visual FoxPro 9.0 Language Reference
OLETypeAllowed Property
See Also

Returns the type of OLE object (embedded or linked) contained in a control. Read-only at design time and run time.

Control.OLETypeAllowed[ = nValue]

Return Value

nValue

Returns a value that indicates the type of OLE object (embedded or linked) contained in a control. Possible values are 0 (Linked), 1 (Embedded), –1 (an OLE Bound control that does not contain an OLE object), and –2 (ActiveX control (.ocx)).

Remarks

Applies To: OLE Bound Control | OLE Container Control

OLETypeAllowed is only useful when you specify a setting for the DocumentFile property.

Note:
You can set the OLETypeAllowed property in code to create a linked OLE object using the DEFINE CLASS command.

See Also

Other Resources

Properties
DEFINE CLASS Command
DocumentFile Property


OneToMany Property

Visual FoxPro 9.0 Language Reference
OneToMany Property
See Also

When moving through records in the parent table, specifies whether the record pointer remains on the same parent record until the record pointer of the child table moves through all related records. Available at design time; read-only at run time.

Object.DataEnvironment.Relation.OneToMany[ = lExpr]

Return Value

lExpr

The settings for the OneToMany property are:

Setting Description

True (.T.)

The record pointer remains on the same parent record until the record pointer of the child table moves through all related records.

False (.F.)

(Default) The parent table's record pointer moves to the specified record and the child table's record pointer moves to the first related record.

Remarks

Applies To: Relation

The OneToMany property can be used to specify the record pointer movement in a simple parent-child table relationship. To specify the record pointer movement in a more complex relationship (for example, a grandparent-parent-child relationship), use SET SKIP in the Init method for the Form or report.

When OneToMany is set to true (.T.), it mimics the behavior of SET SKIP.

See Also

Other Resources

Properties
SET SKIP Command


OpenViews Property

Visual FoxPro 9.0 Language Reference
OpenViews Property
See Also

Determines the type of views associated with a form set, form, or report's data environment that are opened automatically. Available at design time; read-only at run time.

DataEnvironment.OpenViews[ = nExpression]

Return Value

nExpression

The settings for the OpenViews property are:

Setting Description

0

(Default) Local and Remote. Both local and remote views for the data environment for the form set, form, or report are opened automatically.

1

Local only. Only local views for the data environment for the form set, form, or report are opened automatically.

2

Remote only. Only remote views for the data environment of the form set, form, or report are opened automatically.

3

None. No views are opened for the data environment of the form set, form, or report.

Remarks

Applies To: DataEnvironment

The OpenViews property applies when the AutoOpenTables property is set to true (.T.) or the OpenTables method is executed.

See Also

Other Resources

Properties
AutoOpenTables Property
OpenTables Method


Optimize Property (Visual FoxPro)

Visual FoxPro 9.0
Optimize Property (Visual FoxPro)
See Also

Specifies whether the Grid control uses Rushmore optimization. Read/write at design time and run time.

Grid.Optimize [ = lExpr]

Return Value

lExpr

Logical expression specifying if the Grid control uses Rushmore optimization.

Setting Description

True (.T.)

The Grid control uses Rushmore optimization.

False (.F.)

(Default) The Grid control does not use Rushmore optimization.

Remarks

Applies To: Grid Control

When Rushmore Optimization is enabled by setting the Optimize property to True (.T.), the set of matched records is refreshed during the following operations:

  • When the Grid is initially populated

  • When the Grid is activated

  • When the Grid Refresh Method is called

Note:
As with any data manipulation command that can impact Rushmore optimization, you should be aware that actions taken against the Grid's data source could result in behavior that differs from when the Optimize property is set to False (.F.). For example, Rushmore optimization might trigger an implicit TABLEUPDATE to occur for a row buffered cursor. And an error may or may not occur depending on whether the record is blank or whether the cursor is a view.

See Also

Reference

SYS(3054) - Rushmore Query Optimization Level
SET OPTIMIZE Command

Concepts

Using Rushmore Query Optimization to Speed Data Access


Order Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Order Property (Visual FoxPro)
See Also

Specifies the controlling index tag for a Cursor object. Available at design time and run time.

DataEnvironment.Cursor.Order[ = cTagName]

Return Value

cTagName

Specifies an existing index tag for a table.

Remarks

Applies To: Cursor

If the ChildOrder property of a relation object is set, the Order property is ignored.

Use the Order property to specify the order in which records are displayed or accessed. Setting the Order property changes the index order and moves the record pointer to the first record in the cursor.

See Also

Other Resources

Properties
ChildOrder Property
INDEX Command
SET ORDER Command


OrderDirection Property

Visual FoxPro 9.0 Language Reference
OrderDirection Property
See Also

Specifies an ascending or descending order for the controlling index tag specified by the Order property of a Cursor object. Read/write at design time and run time.

Note:
OrderDirection is disregarded when the cursor's Order property is empty.

Cursor.OrderDirection  [= nValue]

Return Value

nValue

Specifies a value that determines the order for a cursor index. The following table lists the values for nValue.

nValue Description

0

Base index order on how the index file or tag is defined, for example, using the INDEX command. (Default)

1

Set index order to ascending.

2

Set index order to descending.

Remarks

Applies To: Cursor

Setting OrderDirection to ascending or descending order is equivalent to calling the SET ORDER command with the ASCENDING or DESCENDING keyword. However, you can change the controlling index and its order for a cursor without changing the OrderDirection and Order properties. Changes to the OrderDirection property do not affect the index order until the Order property is also changed.

See Also

Other Resources

Properties
INDEX Command
SET ORDER Command
SYS(22) - Controlling Tag or Index Name
TAG( ) Function
DESCENDING( ) Function


OutputPageCount Property

Visual FoxPro 9.0
OutputPageCount Property
See Also

Provides the number of pages that has been rendered and could be accessed using the OutputPage method.

ReportListener.OutputPageCount

Return Value

Integer data type.

The default value is 0. This property is readonly.

Remarks

Applies To: ReportListener Object.

OutputPageCount provides the number of pages that have been rendered during a report run. If you use the RANGE clause on the LABEL or REPORT FORM command, this number may be less than the full number of pages in the report scope.

The pages in OutputPageCount are the only pages you can request from the ReportListener using the OutputPage method.

Note:
Exactly how or when you can ask for these pages using OutputPage is dependent on whether the engine is in page-at-a-time mode (print-oriented ListenerType values 0 and 2) or all-pages-at-once mode (preview-oriented ListenerType values 1 and 3). For more information, see OutputPage Method.

OutputPageCount is not reset between reports, so you can check its value between report runs. When you run a report, OutputPageCount is set to 0 before LoadReport, unless the previous report run used the NOPAGEEJECT keyword. It remains at a constant value, either 0 or the retained value of the last report's run if NOPAGEEJECT was used, throughout the calculation pass, if the report is going through multiple passes.

OutputPageCount does not change during LoadReport or BeforeReport. It is incremented at the end of every page included in output. Starting at the AfterReport event, OutputPageCount therefore contains all pages including output so far, for the current report plus any previous reports chained to this one using NOPAGEEJECT.

Note:
The base class ReportListener determines whether a page is included in output by invoking the IncludePageInOutput Method internally. In a multiple-pass report, the ReportListener only makes this determination on the second pass.

For more information about how the native Report System components assign the OutputPageCount value and other values at the beginning and end of a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

See Also

Reference

ReportListener Object Properties, Methods, and Events
REPORT FORM Command
TwoPassProcess Property

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


OutputType Property (Visual FoxPro)

Visual FoxPro 9.0
OutputType Property (Visual FoxPro)
See Also

Provides the value the Report Engine passes to _REPORTOUTPUT to represent the OBJECT TYPE clause of the LABEL or REPORT FORM command.

ReportListener.OutputType [= iExpr]

Return Value

Integer data type.

Default value: -1.

Remarks

Applies To: ReportListener Object.

This property is a companion property to ListenerType. It is not used by the baseclass ReportListener.

The values of the two properties do not necessarily match, although they are related. If they match, the ReportListener provides a single form of output, specified by ListenerType; the object may either replace or augment the native behavior for this ListenerType. If they do not match, the object may use OutputType to provide a second output result, while leveraging inherited behavior for the output result specified by ListenerType.

For more information and an example of usage, see ListenerType Property.

Tip:
Because Visual FoxPro does not use OutputType internally and does not need to evaluate its value, there is no companion method to SupportsListenerType. However, if you want to evaluate and respond only to specified OutputType values, you can create a matching SupportsOutputType method in your derived class. For more information, see SupportsListenerType Method.

See Also

Reference

ReportListener Object Properties, Methods, and Events
_REPORTOUTPUT System Variable

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)
Report Output Application


PageCount Property

Visual FoxPro 9.0 Language Reference
PageCount Property
See Also

Specifies the number of pages contained in a page frame. Available at design time and run time.

PageFrame.PageCount[ = nPages]

Return Value

nPages

Specifies the number of pages contained in a page frame.

Remarks

Applies To: PageFrame Control

The minimum value for the PageCount property setting is 0, and the maximum value is 99.

Caution:
If you decrease the PageCount property setting (for example, if you change the setting from 3 to 2), all pages that exceed the new setting and the objects they contain are lost.

See Also

Other Resources

Properties
ButtonCount Property
ControlCount Property
FormCount Property
Page Object


PageHeight Property

Visual FoxPro 9.0 Language Reference
PageHeight Property
See Also

Specifies the height of a page. Read-only at design time and run time.

PageFrame.PageHeight[ = nHeight]

Parameters

nHeight

Specifies the height of the page in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: PageFrame

See Also

Other Resources

Properties
PageWidth Property
Page Object
ScaleMode Property


PageNo Property

Visual FoxPro 9.0
PageNo Property
See Also

Provides the current page number for report output.

ReportListener.PageNo

Return Value

Integer data type.

Default value is 0. This property is read-only.

Remarks

Applies To: ReportListener Object.

The ReportListener class has two member properties, PageTotal and PageNo, plus a third property, named OutputPageCount. These items function differently from the standard reporting globals (_PAGENO and _PAGETOTAL), which can be assigned values by the user at any time and do not reliably indicate pages that have actually been created.

Note:
Factors with impact on the reliability of _PAGENO and _PAGETOTAL include the use of NORESET, NOPAGEEJECT, and RANGE clauses on the REPORT FORM command (and RANGE clause on the LABEL command) along with possible user re-assignment of the values.

ReportListener.PageNo and ReportListener.PageTotal, like _PAGENO and _PAGETOTAL, are not sensitive to the RANGE clause on the LABEL or REPORT FORM command. They can be used for pagination expressions within report output.

Tip:
To use these member properties reliably in reporting expressions, you must assign your ReportListener to a variable with appropriate scope for them to be visible during the LABEL or REPORT FORM command. If you use the Report Output application to instantiate your ReportListener object, you can use the application's _oReportOutput global collection to reference your ReportListener. For more information, see Report Output Application.

ReportListener.PageNo indicates the real value for a given report run as the engine understands that report run. In effect, the engine assumes NORESET for ReportListener.PageNo and ReportListener.PageTotal if NOPAGEEJECT was used on the previouscommand.

See Also

Reference

ReportListener Object Properties, Methods, and Events
REPORT FORM Command
LABEL Command
_PAGENO System Variable
_PAGETOTAL System Variable
OutputPageCount Property
PageTotal Property

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


PageOrder Property

Visual FoxPro 9.0 Language Reference
PageOrder Property
See Also

Specifies the relative order of pages in a page frame. Available at design time and run time.

Page.PageOrder[ = nOrder]

Parameters

nOrder

Specifies the relative order of a page in a page frame.

Remarks

Applies To: Page

If a page frame contains five pages and you want the third page displayed last, set the PageOrder property of the third page to 5. The PageOrder setting for the fourth page becomes 3, the PageOrder setting for the fifth page becomes 4, and so on.

Note:
PageOrder settings don't have to be sequential. Also, the PageOrder must be less than or equal to the number of pages in a page frame.

See Also

Other Resources

Properties
Activate Event
Deactivate Event
PageFrame Control
ZOrder Method


Pages Property

Visual FoxPro 9.0 Language Reference
Pages Property
See Also

An array used to access individual pages in a page frame. Available at run time only.

PageFrame.Pages(Index).Property[ = Expr]

Parameters

Index

Represents the index of the page you want to access.
Expr

Specifies a property value for the page contained in a page frame.

Remarks

Applies To: PageFrame

See Also

Other Resources

Properties
Buttons Property
Page Object
PageCount Property


PageTotal Property

Visual FoxPro 9.0
PageTotal Property
See Also

Provides a PageTotal for report output.

ReportListener.PageTotal

Return Value

Integer data type.

Default value: 0. This property is read-only.

Remarks

Applies To: ReportListener Object.

ReportListener.PageTotal is not available until after the prepass in each multi-pass LABEL or REPORT FORM command, but otherwise functions similarly to ReportListener.PageNo. See PageNo Property and CurrentPass Property for more information.

See Also

Reference

ReportListener Object Properties, Methods, and Events
REPORT FORM Command
_PAGENO System Variable
_PAGETOTAL System Variable

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


PageWidth Property

Visual FoxPro 9.0 Language Reference
PageWidth Property
See Also

Specifies the width of the page. Available at design time; read-only at run time.

PageFrame.PageWidth[ = nWidth]

Return Value

nWidth

Specifies the width of the page in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: PageFrame

The PageWidth property setting is the same as the Width property setting unless the page frame contains more than one page and the pages are stacked.

See Also

Other Resources

Properties
PageHeight Property
Page Object
ScaleMode Property


Panel Property

Visual FoxPro 9.0 Language Reference
Panel Property
See Also

Specifies the active panel in a Grid control. Available at design time; read/write at run time. Available only if the Partition property is set to a value greater than 0.

Grid.Panel[ = nSide]

Return Value

nSide

The settings for the Panel property are:

Setting Description

0

Left panel is active.

1

(Default) Right panel is active.

Remarks

Applies To: Grid

See Also

Other Resources

Properties
PanelLink Property
Partition Property


PanelLink Property

Visual FoxPro 9.0 Language Reference
PanelLink Property
See Also

Specifies whether the left and right panels of a Grid control are linked when the grid is split. Available at design time; read/write at run time. Available only if the Partition property is set to a value greater than 0.

Grid.PanelLink[ = lExpr]

Return Value

lExpr

The settings for the PanelLink property are:

Setting Description

True (.T.)

(Default) The left and right panels of the grid are linked when the grid is split.

False (.F.)

The left and right panels of the grid are not linked when the grid is split.

If PanelLink is set to true (.T.), both panels of the grid are affected when the following properties are set: HeaderHeight, DeleteMark, GridLineColor, GridLines, GridLineWidth, Highlight, RecordMark, RowHeight, and ScrollBars.

If PanelLink is set to false (.F.), the Panel property setting determines which panel the following properties are set on: HeaderHeight, DeleteMark, GridLineColor, GridLines, GridLineWidth, HighLight, RecordMark, RowHeight, and ScrollBars.

Remarks

Applies To: Grid

See Also

Other Resources

Properties
DeleteMark Property
GridLineColor Property
GridLines Property
GridLineWidth Property
HeaderHeight Property
Highlight Property
Panel Property
Partition Property
RecordMark Property
RowHeight Property
ScrollBars Property


ParentAlias Property

Visual FoxPro 9.0 Language Reference
ParentAlias Property
See Also

Specifies the alias name of the parent table. Read-only at design time and at run time.

DataEnvironment.Relation.ParentAlias[ = cAliasName]

Return Value

cAliasName

Specifies the alias name of the parent table in the relation.

Remarks

Applies To: Relation

The ParentAlias property setting must be the same name as the Alias property setting for the Cursor object that represents the parent table.

See Also

Other Resources

Properties
Alias Property
ChildAlias Property


ParentClass Property

Visual FoxPro 9.0 Language Reference
ParentClass Property
See Also

Returns the name of the class on which the object's class is based. Read-only at design time and run time.

Object.ParentClass

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | CursorAdapter Class | Custom | EditBox | Exception Class | Form | FormSet | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | ReportListener Object | _SCREEN | Session Object | Shape | Spinner | TextBox | Timer | ToolBar

In the Class Designer, the ParentClass property contains the name of the class on which the subclass's class is based.

See Also

Other Resources

Properties
Parent Property


ParentTable Property

Visual FoxPro 9.0 Language Reference
ParentTable Property
See Also

Contains an object reference to a parent XMLTable object that exists and contains the XMLTable object. Read-only.

XMLTable.ParentTable

Return Value

Object reference. ParentTable contains one of the following:

  • An object reference to the parent XMLTable object when it contains the XMLTable object

  • Null (.NULL.) under the following conditions:

    • You create the XMLTable object by itself, neither contained by an XMLAdapter object nor as the child of another XMLTable object.

    • When the XMLTable object is contained by an XMLAdapter object. The XMLAdapter property contains an object reference to the XMLAdapter object containing the XMLTable object.

Remarks

Applies To: XMLTable Class

See Also

Other Resources

Properties
XMLTable Object Properties, Methods, and Events
XMLAdapter Class


Partition Property

Visual FoxPro 9.0 Language Reference
Partition Property
See Also

Specifies whether a Grid control is split into two panels and specifies where the split is relative to the left edge of the grid. Available at design time; read/write at run time.

Grid.Partition[ = nSplit]

Return Value

nSplit

Specifies the position where the grid splits into two panels. If nSplit is 0, the grid isn't split.

Remarks

Applies To: Grid

Note that the SplitBar property takes precedence over the Partition property.

See Also

Other Resources

Properties
Panel Property
PanelLink Property
SplitBar Property


PasswordChar Property

Visual FoxPro 9.0 Language Reference
PasswordChar Property
See Also

Determines whether the characters entered by a user or placeholder characters are displayed in a TextBox control; determines the character used as a placeholder. Available at design time and run time.

TextBox.PasswordChar[ = cCharString]

Return Value

cCharString

Specifies the characters displayed in a text box.

Remarks

Applies To: EditBox Control, TextBox Control

Use this property to create a password field in a dialog box. Although you can use any character, most applications use the asterisk (*), ANSI character 42.

This property does not affect the Value property setting; it contains exactly what the user types or what was set from code. Set PasswordChar to an empty string ("") to display the actual text. The default setting is an empty string.

You can assign any string to this property, but only the first character is significant; all others are ignored.

See Also

Other Resources

Properties
Format Property
InputMask Property
Value Property


Picture Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Picture Property (Visual FoxPro)
See Also

Specifies an image to display on a control or object. Available at design time and run time.

Note:
At design time, if you set the Picture property to a file that does not exist, Visual FoxPro displays the appropriate message, but the property remains set to the file specified. At run time, if the Picture property is set to a file that does not exist, Visual FoxPro disregards the Picture property.

Control.Picture [ = cFileName ]
-Or
Control.Picture(nIndex) [ = cFileName ]

Parameters

cFileName

Specifies the name of a graphics file.
Note:
Visual FoxPro supports all graphics file formats handled by Graphics Device Interface+ (GDI+). Visual FoxPro supports animated .gif files for the Picture property only on an Image control. For more information about valid graphics file formats, see Graphics Support in Visual FoxPro.

nIndex

Specifies an integer corresponding to the order in which items are displayed in the control. For the first item in a control, nIndex = 1.

Remarks

Applies To: CheckBox Control | CommandButton Control | ComboBox Control | Container Object | Control Object | Custom Object | Form Object | Header Object | Image Control | ListBox Control | OptionButton Control | Page Object | _SCREEN System Variable |

On controls, images appear centered. On forms, the image displays as a background for a form. If the RowSourceType property is set to 7 (Files), pictures are not supported.

For CommandButton and OptionButton controls, the specified image is used whether a button is available, selected, or unavailable. You can specify a different image for each button state by setting the DownPicture and DisabledPicture properties.

For CommandButton, CheckBox, and OptionButton controls, you must set the Style property for the corresponding control. The following table lists the values you must set for the Style property for the corresponding control.

Control | Style property
CommandButton | 0 (Standard)
CheckBox, OptionButton | 1 (Graphical)

For Header objects, if the header does not contain a caption, the image appears in the center of the header. If the header contains a caption, the Header Alignment property determines how the image aligns with caption text. If Header Alignment is set to left or center, the image appears to the right of the caption. If Alignment is set to right, the image appears to the left of the caption.

For ToolBar objects, the recommended image dimensions are 16 x 15 pixels (width x height).

For ComboBox and ListBox controls, you can use the Picture property as single-value property or as an array. If you use Picture as a single-value property, all items in the control show the same image. If you use Picture as an array, which stores an image for each item in the list, each item can have a different image. For example:

Copy Code
oCombobox.AddItem("Home")
oCombobox.AddItem("Community")
oCombobox.AddItem("Web Services")
oCombobox.Picture[1] = 'home.bmp'
oCombobox.Picture[2] = 'community.bmp'
oCombobox.Picture[3] = 'websvc.bmp'

For Image, CheckBox, and CommandButton controls, the Picture property respects the transparency of the image.

Note:
For high resolution Transparent GIF images, the transparency aspect of the image is only supported for the Image control. Because Visual FoxPro stores only one instance of that image as a resource for use internally, it is possible to use this image on another control such as a CommandButton and have it retain transparency. To do this, you first need to load the image into an Image control and persist that control (maybe hidden). Once the image has been loaded as a resource by the Image control, it can then be used by the CommandButton.

See Also

Reference

PictureVal Property

Other Resources

Properties
DisabledPicture Property
DownPicture Property
Style Property
How to: Add Pictures to Items in a List


PictureMargin Property

Visual FoxPro 9.0 Language Reference
PictureMargin Property
See Also

Specifies the margin in pixels between an image as specified by the Picture property on a control and the edge of the control as determined by the PicturePosition property. Read/write at design time and run time.

Control.PictureMargin [= nValue]

Return Value

nValue

Specifies the number of pixels between an image and the edge of the control. You can specify a value of 0 (default) to 65,535 for nValue. When PictureMargin is set to 0, positioning of the image is determined by the PicturePosition and Alignment properties. When PictureMargin is greater than 0, the image appears nValue number of pixels from the edge of the control and only PicturePosition affects the positioning of the image. For more information, see PicturePosition Property and Alignment Property.

Remarks

Applies To: CheckBox | CommandButton | OptionButton

PictureMargin applies to CheckBox and OptionButton controls when their Style property is set to 1 (Graphical). For more information, see Style Property.

PictureMargin is disregarded when PicturePosition is set to a value greater than 11.

See Also

Other Resources

PictureSpacing Property
Properties
Controls for Displaying Information


PicturePosition Property

Visual FoxPro 9.0 Language Reference
PicturePosition Property
See Also

Specifies the location of a picture relative to its caption. Read/write at run time.

The picture and caption, as a unit, appear centered on the control. If no caption exists, the picture is located relative to the center of the control. The PicturePosition property is affected by the Picture, DownPicture, and DisabledPicture properties. For more information, see Picture Property, DownPicture Property, and DisabledPicture Property.

Note:
To apply PicturePosition, you must specify an image for the Picture property. The size of the image is fixed. If you want to stretch, resize, or crop the image, you must use an Image control. Animated .gif files are not supported. For more information, see Image Control.

Object.PicturePosition [ = nValue ]

Parameters

nValue

Specifies alignment for a picture. The following table lists the settings for nValue.

nValue Setting

0

The picture appears to the left of the caption. The picture aligns with the top of the caption.

1

The picture appears to the left of the caption. The picture is centered relative to the caption.

2

The picture appears to the left of the caption. The picture aligns with the bottom of the caption.

3

The picture appears to the right of the caption. The picture aligns with top of the caption.

4

The picture appears to the right of the caption. The picture is centered relative to the caption.

5

The picture appears to the right of the caption. The picture aligns with the bottom of the caption.

6

The picture appears above the caption. The picture aligns with the left edge of the caption.

7

The picture appears above the caption. The picture is centered above the caption.

8

The picture appears above the caption. The picture aligns with the right edge of the caption.

9

The picture appears below the caption. The picture aligns with the left edge of the caption.

10

The picture appears below the caption. The picture is centered below the caption.

11

The picture appears below the caption. The picture aligns with the right edge of the caption.

12

The picture appears in the center of the control. The caption is centered horizontally and vertically with top of the picture.

13

(Default) The picture appears in the center of the control. The caption is centered below the picture but stays relative to the bottom of the button when resized.

14

No text. The picture appears centered and hides the text specified by the Caption property. For more information, see Caption Property.

Tip:
To apply this setting, the Style property of the control must be set to 1 (Graphical). Use this setting when you want to provide a hotkey without displaying text on the control. For more information, see Style Property.

Remarks

Applies To: CommandButton Control | OptionButton Control | CheckBox Control

For CommandButton controls, Visual FoxPro disregards PicturePosition if Style is set to 1 (Invisible).

The WordWrap property and the AutoSize property are supported with PicturePosition. For more information, see WordWrap Property and AutoSize Property.

The SpecialEffect and VisualEffect properties affect the outer border but do not affect PicturePosition. For more information, see SpecialEffect Property and VisualEffect Property.

Versions earlier than Visual FoxPro 8.0 use a positioning algorithm that differs slightly from the standard 0 – 12 settings. The image always remains centered; however, the text remains relative to the bottom of the image. When PicturePosition is set to a value of 7, similar behavior occurs. However, as the button size is reduced, the text is cropped instead of shifted towards the top of the button. Setting PicturePosition to a value of 13 corresponds with behavior in versions prior to Visual FoxPro 8.0.

See Also

Other Resources

PictureSpacing Property
PictureMargin Property
Properties


PictureSelectionDisplay Property

Visual FoxPro 9.0 Language Reference
PictureSelectionDisplay Property
See Also

Specifies how an image appears in the text box portion of a ComboBox control.

Note:
You can specify an image by setting the Picture property of the control to an image file name.

Combobox.PictureSelectionDisplay = nExpr

Parameters

nExpr

Numeric data type. The following table lists the values of nExpr.

nExpr Description

0 (None)

Does not display the image in the text box of the combo box. (Default)

1 (Clip)

The image is clipped to the same height of the text box of a combo box. The width of the image remains the same.

2 (Isometric)

The image resizes to fit the height of the text box of a combo box while maintaining its original proportions.

3 (Stretch)

The image resizes to fit the height of the text box of a combo box but does not maintain its original proportions. The width of the image remains the same.

Remarks

Applies To: ComboBox Control

If the combo box Style property is set to 0 (Drop-down ComboBox), images display in the text box of the combo box with the following behavior:

  • When the list portion of the combo box is not visible, and you are typing text directly into the combo box, the default image, if specified, appears until the text matches an item in the list. If no match exists, the default image appears even when the control loses focus.

  • The Margin property of the combo box specifies text spacing, plus padding, from the left and top borders of the text box. When an image appears in the text box, the Margin property specifies the spacing between the image borders and the left and top borders of the text box. The horizontal spacing between the right border of the image and the text is always four pixels, regardless of the setting of the Margin property of the combo box. The text cursor appears two pixels from the right border of the image. You can insert additional space by providing an image containing white space.

    Note:
    Even if Margin is set to 0, a three-pixel space from the left border and top borders exists to provide space for the text cursor. Specifying a value for Margin adds pixels to this padding. However, if an image appears, Margin affects only the margin between the top border of the text box and the text. The left margin of the text always appears four pixels from the image to maintain alignment of items inside the list.

If the combo box Style property is set to 2 (Drop-down List), images display in the text box of the combo box with two pixels of horizontal spacing between the right border of the image and the text.

See Also

Other Resources

Properties
Margin Property
Picture Property


PictureSpacing Property

Visual FoxPro 9.0 Language Reference
PictureSpacing Property
See Also

Specifies the margin in pixels between the image specified by the Picture property and text specified by the Caption property on a control. Read/write at design time and run time.

Control.PictureSpacing [= nValue]

Return Value

nValue

Specifies the number of pixels between an image and text on a control. You can specify a value of 0 (default) to 65,535 for nValue. When PictureSpacing is set to 0, the PicturePosition and Alignment properties determine the margin between the image and the control. When PictureSpacing is greater than 0, the text appears nValue number of pixels from the image, and the PicturePosition and Alignment properties affect the positioning of text in the control. PictureSpacing is disregarded when PicturePosition is set to a value greater than 11. For more information, see PicturePosition Property and Alignment Property.

Remarks

Applies To: CheckBox | CommandButton | OptionButton

PictureMargin applies to CheckBox and OptionButton controls when their Style property is set to 1 (Graphical). For more information, see Style Property.

See Also

Other Resources

PictureMargin Property
Properties
Controls for Displaying Information


PictureVal Property

Visual FoxPro 9.0 Language Reference
PictureVal Property
See Also

Specifies a character string expression or object that represents an image for the Image control.

PROCEDURE Image.PictureVal [= eExpression]

Return Value

eExpression

Specifies a character string expression or object that represents an image. If eExpression is a string expression, it must be a valid expression that GDI+ can use to render an image. For example, it could be an expression derived from code as in the following example.
Copy Code
cPict = FILETOSTR('myimage.bmp')
oForm.Img1.PictureVal = cPict
eExpression can also be a string expression that represents a memo or blob type field containing strict binary data. For example, you can use the APPEND MEMO Command to import an image into a memo field. You cannot use a general type field for eExpression because general fields store additional unrelated binary data. If eExpression is an object, the object must be in an IPicture interface format. The IPicture interface format is the same format returned by the LOADPICTURE( ) Function.
Copy Code
oPict = LOADPICTURE(“myimage.bmp”)
oForm.img1.PictureVal = oPict

Remarks

Applies to: Image Control (Visual FoxPro)

The PictureVal property takes precedence over the Picture Property (Visual FoxPro) if both are specified.

Note that Visual FoxPro only uses the memory required to render an image when the image is stored in a memo or blob field. This is a memory efficient way to display images in Visual FoxPro. However, using a file reference in the PictureVal property requires Visual FoxPro to use up to twice the amount of memory as the size of the file. For example, if you reference a 5 MB image file, Visual FoxPro requires up to 10MB of memory to display the file.

You cannot specify a mask (MSK) file with the PictureVal property. If you are using BMP images and want a mask, you should use the Picture property instead. You can also use a different image format such as GIF which has transparency defined within the image.

See Also

Reference

LOADPICTURE( ) Function
Graphics Support in Visual FoxPro


PolyPoints Property

Visual FoxPro 9.0 Language Reference
PolyPoints Property
See Also Example

Specifies an array of coordinates for creating polygon shapes using the Shape control and polygon lines using the Line control. Read/write at design time and run time.

For Shape controls, PolyPoints creates a polygon shape. For Line controls, PolyPoints creates a polygon line or shape.

Control.PolyPoints [= cArrayName]

Return Value

cArrayName

Specifies the name of an array containing pairs of coordinates for drawing a polygon shape or line. Coordinates use the format (X, Y). The array must be in scope in order for the object to properly display the polygon or polyline
Tip:
The array can have any dimension; however, having two columns makes it easier for you to program. Store the X-coordinate point in first column and store the Y-coordinate point in the second column. The array must be filled entirely with numeric values; otherwise, trailing elements containing False (.F.) will prevent the line or shape from being drawn.

Note:
PolyPoints requires at least two pairs of coordinates to draw a line, three pairs of coordinates to draw a polygon line, three pairs of coordinates to draw a polygon shape with the Shape control, and four pairs of coordinates to draw an enclosed polygon line, or shape, with the Line control.

To create a polygon shape with the Line control, the fifth pair of coordinates in the array must have the same coordinates as the first pair to draw the last line segment and complete the polygon shape. When setting the LineSlant property to draw Bezier curves, you must specify a total of (3n + 1) coordinates with n representing the number of curves you want to draw. For more information, see LineSlant Property.

Remarks

Applies To: Line | Shape

Visual FoxPro draws polygons in the order that the coordinates appear in the array, which affects the fill regions associated with polygons. You can draw shapes within the polygon without touching the polygon border by specifying points within the border. For more information about fill regions and styles, see FillStyle Property and FillColor Property.

The coordinates specified in the array are relative percentages to the dimensions of the Shape (or Line) control so that the polygon will resize as the shape is resized.

Updating the array updates the Shape or Line control automatically the next time it is drawn.

If the array contains an odd number of elements, the last element is disregarded.

If PolyPoints is set, Visual FoxPro disregards the Style property when it is set to 3 (Themed), the Curvature property, and the three-dimensional SpecialEffect property settings.

Visual FoxPro redraws the shape automatically when the Rotation setting, which rotates the shape, is changed. For more information, see Rotation Property.

The array must be in scope for the object to display the polygon or polyline. If you want to display the polygon in design-time, then the PolyPoints property must point to a public array in scope. For more information about scope, see Access to Variables.

Example

The following example displays a form with a polygon line drawn using the Line control based on an array of coordinates specified by the PolyPoints property.

Copy Code
DIMENSION poly[5,2]
poly[1,1]= 0
poly[1,2]= 50
poly[2,1]= 50
poly[2,2]= 100
poly[3,1]= 100
poly[3,2]= 50
poly[4,1]= 50
poly[4,2]= 0
poly[5,1]=0
poly[5,2]=50
frmMyForm = CREATEOBJECT('Form')
frmMyForm.AddObject('shpLine','Line')
frmMyForm.AddObject('cmdCmndBtn1','cmdMyCmndBtn1')
frmMyForm.shpLine.Top = 20
frmMyForm.shpLine.Left = 125
frmMyForm.shpLine.PolyPoints = "poly"
frmMyForm.shpLine.Visible = .T.
frmMyForm.cmdCmndBtn1.Visible =.T.
frmMyForm.Show
READ EVENTS
DEFINE CLASS cmdMyCmndBtn1 AS CommandButton
   Caption = '\<Quit'
   Cancel = .T.
   Left = 125
   Top = 150
   Height = 25
   PROCEDURE Click
      CLEAR EVENTS
ENDDEFINE

See Also

Reference

LineSlant Property

Other Resources

Customizing Forms
Properties


Prepared Property

Visual FoxPro 9.0 Language Reference
Prepared Property
See Also

Specifies whether to prepare SQL statements for subsequent REQUERY( ) function calls. You can use REQUERY( ) to retrieve data again for an SQL view. When handling this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions. Read/write.

Note:
Setting Prepared for CursorAdapter objects overrides the property setting of a cursor when it is attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP( ) has no effect.

For more information, see REQUERY( ) Function and SQLPREPARE( ) Function.

CursorAdapter.Prepared [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

True (.T.)

Prepare SQL statements for subsequent REQUERY( ) function calls. (Default)

False (.F.)

Do not prepare SQL statements for subsequent REQUERY( ) function calls.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


PreserveWhiteSpace Property

Visual FoxPro 9.0 Language Reference
PreserveWhiteSpace Property
See Also

Preserves or removes white space from XML output. Read/write.

PreserveWhiteSpace applies only when executing the XMLAdapter LoadXML and ToXML methods, which respectively retrieve and create XML consistent with these settings. PreserveWhiteSpace does not apply to data in a CDATA section.

XMLAdapter.PreserveWhiteSpace [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

Removes white space. (Default)

True (.T.)

Preserves white space.

Remarks

Applies To: XMLAdapter Class

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
LoadXML Method
ToXML Method


PreviewContainer Property

Visual FoxPro 9.0
PreviewContainer Property
See Also

Provides a reference to the display surface on which the report will be rendered when the ReportListener provides output of Preview type.

ReportListener.PreviewContainer [=oReference]

Return Value

An object implementing the PreviewContainer API. .

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

Remarks

Applies To: ReportListener Object.

The ReportListener stores a reference to a Preview Container when rendering a report in preview mode (ReportListener.ListenerType = 1). You can provide the reference explicitly, or rely on the ReportListener's base behavior, which gets the reference to a PreviewContainer from the Report Preview Application. For more information, see _REPORTPREVIEW System Variable.

See Also

Reference

ReportListener Object Properties, Methods, and Events
The Preview Container API

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


PrintJobName Property

Visual FoxPro 9.0
PrintJobName Property
See Also Example

Shows a user-specified value as the name of the document currently printing in the Windows Print Queue.

Note:
The Windows Print Queue is not a dialog box that appears within Visual FoxPro. It is the window that shows documents waiting to be printed, and the status of each document, for a specific printer. You access the Print Queue window by double-clicking the printer for which you want to view document status in Printers and Faxes.

ReportListener.PrintJobName [= cText]

Return Value

Character data type, limited to 255 characters.

Default value is an empty string.

Remarks

Applies To: ReportListener Object.

You can use this property for additional user feedback purposes in derived ReportListener classes. As examples, the ReportListener User Feedback Foundation Class uses PrintJobName in the title of its progress window, and the ReportListener HTML Foundation Class uses PrintJobName in its HTML document title. If you do not assign a value to PrintJobName, both classes default to the report or label filename, similar to the default value Visual FoxPro assigns in the Windows Print Queue for these labels. For more information, see ReportListener Foundation Classes.

Note:
When NOPAGEEJECT causes a single print run to occur for multiple reports, the printable page size and other printer-determined characteristics are determined by the first report in the run, because this is the moment at which the print spool is opened. The PrintJobName property is also applied at this time, so only the first value in a chained run of reports is significant to a ReportListener of ListenerType 1 (print mode).

Example

The following example illustrates the availability of multiple PrintJobName properties during a single run of multiple reports chained using NOPAGEEJECT. If you set the ListenerType property for the ReportListener derived class to 1 in this example, the name of the currently-printing document in the Windows Print Queue is My First Report for the entire run. However, when you derive classes from ReportListener and implement other ListenerType values, you can make use of each PrintJobName value during the chained report run.
Copy Code
LOCAL loListener
loListener = CREATEOBJECT("PJN")
loListener.PrintJobName = "My First Report"
REPORT FORM ? NOPAGEEJECT OBJECT loListener
loListener.PrintJobName = "My Second Report"
REPORT FORM ? OBJECT loListener

DEFINE CLASS PJN AS ReportListener

   PROCEDURE BeforeReport()
     MESSAGEBOX(THIS.PrintJobName + ;
       " (runs " + THIS.CommandClauses.File) + ")"
   ENDPROC

ENDDEFINE

See Also

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


Procedure Property

Visual FoxPro 9.0 Language Reference
Procedure Property
See Also

Specifies the name of the procedure or method where an exception occurs. Read/write at run time.

Exception.Procedure

Return Value

Character data type.

Remarks

Applies To: Exception Class

Identical to the value returned by the PROGRAM( ) function.

See Also

Other Resources

Properties
Exception Object Properties, Methods, and Events
PROGRAM( ) Function
TRY...CATCH...FINALLY Command
Structured Error Handling


PROCESSID Property

Visual FoxPro 9.0 Language Reference
PROCESSID Property
See Also

Returns the unique identifier of the current process.

_VFP.ProcessID

Remarks

Applies To: Application Object | _VFP

You can use this property to evaluate resource usage during debugging.

See Also

Other Resources

Properties
Application Object


ProgID Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
ProgID Property (Visual FoxPro)
See Also

Contains the registered PROGID (Programmatic Identifier) for a server in a project. Read-only at design time and run time.

Object.ProgID

Remarks

Applies To: Server Object

A PROGID is created in the Windows registry for a server when you build an executable file (.exe) or dynamic link library (.dll) from a project.

See Also

Other Resources

Properties
CLSID Property
CREATEOBJECTEX( ) Function
TypeLibCLSID Property
TypeLibDesc Property
TypeLibName Property


ProjectHook Property

Visual FoxPro 9.0 Language Reference
ProjectHook Property
See Also

An object reference to the ProjectHook object instantiated for a project.

Object.ProjectHook[ = oProjectHookClass]

Return Value

oProjectHookClass

Specifies a class based on the Visual FoxPro ProjectHook base class. By default, contains an object reference to the default ProjectHook class specified in the Project tab of the Project Information dialog box.

Remarks

Applies To: Project Object

The ProjectHook property contains the null value if it has not been assigned a class based on the ProjectHook base class or the project doesn't have a default ProjectHook class (specified in the Project tab of the Project Information dialog box). Assigning the null value to ProjectHook property releases the ProjectHook object, but doesn't affect the default ProjectHook class for the project.

For more information about projects, see Project Manager Hooks.

See Also

Other Resources

Properties
ProjectHook Object
ProjectHookClass Property
ProjectHookLibrary Property


ProjectHookClass Property

Visual FoxPro 9.0 Language Reference
ProjectHookClass Property
See Also

The default ProjectHook class for a project.

Object.ProjectHookClass[ = cClassName]

Return Value

cClassName

Specifies the default ProjectHook class for a project. Before you can specify a ProjectHook class for a project, specify the .vcx visual class library containing the ProjectHook class with the ProjectHookLibrary property. To delete the default ProjectHook class for a project, set the ProjectHookClass or ProjectHookLibrary property to the empty string.

Remarks

Applies To: Project Object

You can also specify the default ProjectHook class for a project in the Project tab of the Project Information dialog box.

Changing the ProjectHookClass property doesn't instantiate the new ProjectHook object. The change takes effect the next time the project is opened. To change the current ProjectHook object, use the ProjectHook property.

For more information about projects, see Project Manager Hooks.

See Also

Other Resources

Properties
ProjectHook Object
ProjectHook Property
ProjectHookLibrary Property


ProjectHookLibrary Property

Visual FoxPro 9.0 Language Reference
ProjectHookLibrary Property
See Also

The .vcx visual class library containing the default ProjectHook class for a project.

Object.ProjectHookLibrary[ = cLibraryName]

Return Value

cLibraryName

Specifies a .vcx visual class library that contains a class based on the ProjectHook base class. After you specify the .vcx visual class library with this property, use the ProjectHookClass property to specify the default class for the project. To delete the default ProjectHook class for a project, set the ProjectHookLibrary or ProjectHookClass property to the empty string.

Remarks

Applies To: Project Object

You can also specify the default ProjectHook class for a project in the Project tab of the Project Information dialog box.

Changing the ProjectHookLibrary property doesn't instantiate the new ProjectHook object. The change takes effect the next time the project is opened. To change the current ProjectHook object, use the ProjectHook property.

For more information about projects, see Project Manager Hooks.

See Also

Other Resources

Properties
ProjectHook Object
ProjectHook Property
ProjectHookClass Property


QuietMode Property

Visual FoxPro 9.0
QuietMode Property
See Also

Specifies whether the ReportListener may provide any user feedback or interface.

ReportListener.QuietMode [= lExpr]

Return Value

Logical data type.

The default value of QuietMode differs depending on how the Visual FoxPro session was started, as determined by the value of the _VFP.StartMode property. See StartMode Property for more information.

True

User feedback is permitted. This value is default for a ReportListener object instantiated within an interactive Visual FoxPro session or in a distributable application (.app or .exe file).
False

User feedback is not permitted. This value is default for a ReportListener object instantiated in an automation server.

Remarks

Applies To: ReportListener Object.

If you use NODIALOG on a LABEL or REPORT FORM command and the value of QuietMode is .F., the NODIALOG keyword takes precedence for this report run. The ReportListener sets QuietMode to .T. temporarily during the report run.

For information about when the native Report System components assigns this value in relation to other reporting events at the beginning and end of a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

QuietMode takes precedence over the setting of AllowModalMessages, and affects the behavior of both DoStatus Method and DoMessage Methods. For more information about the ReportListener user feedback mechanisms, see AllowModalMessages Property.

See Also

Reference

DoMessage Method
DoStatus Method

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


ReadOnly Property

Visual FoxPro 9.0 Language Reference
ReadOnly Property
See Also

Specifies whether the user can edit a control, specifies whether a table or view associated with a Cursor object allows updates, or contains a value that indicates if a file in a project can be edited. Available at design time; read/write at run time.

 [Form.]Control.ReadOnly[ = lExpr]
DataEnvironment.Cursor.ReadOnly[ = lExpr]
Project.Files.Item(nItem).ReadOnly

Return Value

lExpr

The settings for the ReadOnly property are:

Setting Description

True (.T.)

The user cannot edit the control.The table or view associated with the Cursor object cannot be modified.

False (.F.)

(Default) The user can edit the control.The table or view associated with the Cursor object can be modified.

Remarks

Applies To: CheckBox | Column | ComboBox | Cursor | EditBox | File Object | Grid | Spinner | TextBox

Note:
When the Cursor is accessed using CURSORSETPROP(), the ReadOnly property is read-only at run time.

The ReadOnly property differs from the Enabled property because when ReadOnly is set to true (.T.), the user can still move to the control.

For Cursors, ReadOnly mimics the NOUPDATE clause of USE.

For combo box controls, the ReadOnly property cannot be set to true (.T.) when the Style property is set to 2 – Drop-down List.

For a file in a project, the ReadOnly property contains a logical value that indicates if the file can be edited. If ReadOnly is true (.T.), the file can be edited; otherwise the file cannot be edited. Read-only at design time and run time.

See Also

Other Resources

Properties
Enabled Property
USE Command


RecordMark Property

Visual FoxPro 9.0 Language Reference
RecordMark Property
See Also

Specifies whether the record selector column is displayed in a Grid control. Available at design time; read/write at run time.

Grid.RecordMark[ = lExpr]

Return Value

lExpr

The settings for the RecordMark property are:

Setting Description

True (.T.)

(Default) The record selector column is displayed in a Grid.

False (.F.)

The record selector column is not displayed in a Grid.

Remarks

Applies To: Grid

See Also

Other Resources

Properties
ScrollBars Property
How to: Control Record Selection with Joins


RecordSource Property

Visual FoxPro 9.0 Language Reference
RecordSource Property
See Also

Specifies the source of data to which the Grid control is bound. Available at design time; read/write at run time.

Grid.RecordSource[ = cName]

Return Value

cName

cName is typically the alias name of a cursor or the name of a table. The RecordSource property specifies the main cursor that the grid is bound to.

Remarks

Applies To: Grid

If you specify a record source for a grid, you can specify the contents of individual columns in the grid by setting the columns' ControlSource property. If you do not set the ControlSource property for a grid column, the column displays the next available and field in the grid's record source that is not yet displayed. For more information, see ControlSource Property.

When you are working with grids, you might sometimes need to change or query the RecordSource property again at run time. Because the new source might have a different structure than the previous source, Visual FoxPro resets column settings, such as the width and font, to their default values. When you want to preserve the previous settings, for example, in scenarios when the new record source has the same structure as the previous one, you can use the SPACE( ) function set the RecordSource property temporarily to SPACE(0).

Note:
Using SPACE(0) might not preserve all the grid settings that you want. You might need to reset some settings in code after setting the RecordSource property.

The following code example uses the Customers table in the Northwind sample database in the Visual FoxPro directory ..\Samples\Northwind\ and illustrates how to preserve the previous settings:

Copy Code
PUBLIC oForm
oForm=NEWOBJECT("MyForm")
oForm.Show()

DEFINE CLASS MyForm AS Form
    ADD OBJECT oGrid1 AS Grid WITH RecordSource="MyCust",ColumnCount=3
    ADD OBJECT oButton1 AS CommandButton WITH TOP = 200

    PROCEDURE Load
      SELECT * FROM HOME()+"Samples\Northwind\Customers" ;
        WHERE Country="France" INTO CURSOR MyCust

    PROCEDURE Init
        THISFORM.oGrid1.Column1.Width = 50
        THISFORM.oGrid1.Column1.FontSize=14
        THISFORM.oGrid1.Column2.Width = 50
        THISFORM.oGrid1.Column3.Width = 50

    PROCEDURE oButton1.Click
        THISFORM.oGrid1.RecordSource = SPACE(0)
        SELECT * FROM HOME()+"Samples\Northwind\Customers" ;
           WHERE Country="France" INTO CURSOR MyCust
           THISFORM.oGrid1.RecordSource = "MyCust"

ENDDEFINE

See Also

Other Resources

Properties
ControlSource Property
Order Property
RecordMark Property
RecordSourceType Property


RecordSourceType Property

Visual FoxPro 9.0 Language Reference
RecordSourceType Property
See Also

Specifies how the data source that populates the Grid control is opened. Available at design time and read/write at run time.

Grid.RecordSourceType[ = nType]

Return Value

nType

The settings for the RecordSourceType property are:

Setting Description

0

Table. Automatically opens the table specified in the RecordSource property setting.

1

(Default) Alias. Treats the record source as specified.

2

Prompt. The user is prompted for the record source at run time. If a database is open, the user can choose one of the tables it contains as a record source.

3

Query (.qpr). The RecordSource property setting specifies a .qpr file.

4

SQL Statement. The SQL statement is specified in the RecordSource property.

Remarks

Applies To: Grid

See Also

Other Resources

RecordSource Property
Properties
How to: Set the Data Environment


RefreshAlias Property

Visual FoxPro 9.0 Language Reference
RefreshAlias Property
See Also

Contains the alias of the read-only cursor used as the record refresh target for the RecordRefresh and DelayedMemoFetch methods. Read-only at design time and run time.

CursorAdapter.RefreshAlias

Remarks

Applies To: CursorAdapter Class

When the RecordRefresh or DelayedMemoFetch methods are executing, the RefreshAlias property will contain the alias of the read-only cursor they open.

See Also

Reference

DelayedMemoFetch Method
RecordRefresh Method


RefreshCmd Property

Visual FoxPro 9.0 Language Reference
RefreshCmd Property
See Also

Specifies the command to use for the record Refresh performed by the RecordRefresh method. Read/write at design time and run time.

CursorAdapter.RefreshCmd[ = cCommand]

Parameters

cCommand

Character data type. The following table lists the possible values for cCommand.

cCommand Description

Character string or expression

Specifies a valid command string for the data source specified by the RefreshCmdDataSourceType Property and RefreshCmdDataSource Property properties.

For ADO and ODBC data sources, you can specify any command that is supported by the data source and returns exactly one record.

For a native Visual FoxPro data source, the command should be a SQL SELECT command that returns exactly one record. Fields are matched by their position in the cursor excluding fields specified in the RefreshIgnoreFieldList property.

Empty string ("")

The CursorAdapter object automatically generates a record Refresh command.

The generated command is based on the data source and the CursorAdapter Tables, KeyFieldList, UpdateNameList and RefreshIgnoreFieldList properties. If you include a command, the Tables, KeyFieldList, and UpdateNameList properties are ignored.

Note:
A command that is automatically generated does not include AUTOINC or key fields, even if they are not included in the RefreshIgnoreFieldList property.

Remarks

Applies To: CursorAdapter Class

The command you specify is executed for every target record. Validation rules for target fields are not executed.

No fields are refreshed if an error occurs during the record refresh. An error is generated if data conversion from a source field to the target field is not supported. Attempting to refresh an AUTOINC field will generate an error. The refresh operation is cancelled if an attempt to update indexes fails due to non-unique key or for any other reason.

For ADODB Recordsets, the CursorAdapter RefreshCmd, Tables, KeyFieldList, and UpdateNameList properties are ignored, and no error is generated if key fields are not specified.

If the lock type for the ADODB Recordset is not adLockBatchOptimistic or adLockUnspecified, the CursorAdapter calls the Resync Method with the ResyncValues parameter set to adResyncAllValues to refresh the record in the Recordset before the record in the cursor is refreshed.

You can set this property in the BeforeRecordRefresh Event.

See Also

Reference

BeforeRecordRefresh Event
KeyFieldList Property
RefreshIgnoreFieldList Property
RefreshCmdDataSource Property
RecordRefresh Method
Tables Property
UpdateNameList Property


RefreshCmdDataSource Property

Visual FoxPro 9.0 Language Reference
RefreshCmdDataSource Property
See Also

Specifies the data source used for the RecordRefresh method. Read/write at design time and run time.

CursorAdapter.RefreshCmdDataSource[ = DataSource]

Parameters

DataSource

Specifies a reference to an existing data source of permissible data source types. DataSource acts only as a pointer to the actual data source, which must exist at run time. The following table lists the values for DataSource, which depend on the value of the RefreshCmdDataSourceType Property.

DataSource DataSource Type

"ADO"

Reference to a valid ActiveX Data Object (ADO) Command object

"ODBC"

Positive integer that represents or memory variable that contains a valid Open Database Connectivity (ODBC) connection handle

"Native", null (.NULL.), or empty string ("")

Disregarded.

The default value is the null value (.NULL.).

Remarks

Applies To: CursorAdapter Class

You can set this property in the BeforeRecordRefresh Event.

See Also

Reference

BeforeRecordRefresh Event
RecordRefresh Method
RefreshCmdDataSourceType Property


RefreshCmdDataSourceType Property

Visual FoxPro 9.0 Language Reference
RefreshCmdDataSourceType Property
See Also

Specifies the data source type used for the RecordRefresh method. Read/write at design time and run time.

CursorAdapter.RefreshCmdDataSourceType[ = cExpression]

Return Value

cExpression

Specifies the data source type used for the RecordRefresh method. cExpression is a character expression that evaluates to one of the following:

cExpression Description

Empty string ""

Visual FoxPro disregards the CursorAdapter RefreshCmdDataSource property and uses the CursorAdapter DataSource and DataSourceType properties.

ODBC

The data source is ODBC (Open Database Connectivity).

ADO

The data source is ADO (ActiveX Data Objects).

Native

The data source is native Visual FoxPro tables or cursors.

Remarks

Applies To: CursorAdapter Class

You can set this property in the BeforeRecordRefresh Event.

See Also

Reference

BeforeRecordRefresh Event
DataSource Property
DataSourceType Property
RecordRefresh Method
RefreshCmdDataSource Property


RefreshIgnoreFieldList Property

Visual FoxPro 9.0 Language Reference
RefreshIgnoreFieldList Property
See Also

Specifies a list of fields that are ignored by the refresh process when the RecordRefresh method is executed. Read/write at design time and run time.

CursorAdapter.RefreshIgnoreFieldList [ = cExpr]

Parameters

Term | Definition
cExpr | The character expression cExpr is a comma delimited list of the fields in the cursor that are ignored by the refresh process.

Remarks

Applies To: CursorAdapter Class

You can set this property in the BeforeRecordRefresh Event.

See Also

Reference

BeforeRecordRefresh Event
RecordRefresh Method


RefreshTimeStamp Property

Visual FoxPro 9.0 Language Reference
RefreshTimeStamp Property
See Also

Specifies if the fields included in the TimestampFieldList Property are automatically refreshed when an Insert or Update command is executed. Read/write at design time and run time.

CursorAdapter.RefreshTimestamp[ = lExpr]

Return Value

lExpr

One of the following logical values:

Setting Description

True (.T.)

Enables automatic refresh of the fields included in the TimestampFieldList property.

False (.F.)

(Default) Disables automatic refresh of the fields included in the TimestampFieldList property.

Remarks

Applies To: CursorAdapter Class

Setting the RefreshTimestamp property to True (.T.) is identical to including the timestamp fields at the end of the InsertCmdRefreshFieldList Property and the UpdateCmdRefreshFieldList Property.

See Also

Reference

TimestampFieldList Property


RelationalExpr Property

Visual FoxPro 9.0 Language Reference
RelationalExpr Property
See Also

Specifies the expression based on fields in the parent table that relates to an index in the child table joining the two tables. For the Grid control, available at design time; read/write at run time. For the Relation object, available at design time; read-only at run time.

Object.RelationalExpr[ = cExpr]

Return Value

cExpr

Specifies any Visual FoxPro expression, typically one that matches the child table's current index as specified by the ChildOrder property.

Remarks

Applies To: Grid | Relation

See Also

Other Resources

ChildOrder Property
LinkMaster Property
Properties
SET RELATION Command


RelativeColumn Property

Visual FoxPro 9.0 Language Reference
RelativeColumn Property
See Also

Specifies the active column in the visible portion of a Grid control. Not available at design time and read-only at run time.

Grid.RelativeColumn[ = nColumn]

Return Value

nColumn

Specifies the active column in a Grid control.

Remarks

Applies To: Grid

Use the RelativeColumn property to determine the relative position of the active column in a grid. For example, if you scroll through a grid so that the first column is no longer visible, but the active column is the first visible column in the grid, RelativeColumn is set to 1. To determine the absolute position of the active column in a grid, use the ActiveColumn property.

See Also

Other Resources

Properties
ActiveColumn Property
ActiveRow Property
RelativeRow Property


RelativeRow Property

Visual FoxPro 9.0 Language Reference
RelativeRow Property
See Also

Contains the active row in the visible portion of a Grid control. Not available at design time and read-only at run time.

Grid.RelativeRow

Return Value

nRow

Numeric data type. RelativeRow contains the number of the active row in a Grid control.

Remarks

Applies To: Grid

You can use RelativeRow to determine the relative position of the active row in a grid. For example, if you scroll through a grid so that the first row is no longer visible, but the active row is the first visible row in the grid, RelativeRow is set to 1.

To determine the absolute position of the active row in a grid, use the ActiveRow property.

See Also

Other Resources

Properties
ActiveColumn Property
ActiveRow Property
RelativeColumn Property


ReleaseType Property

Visual FoxPro 9.0 Language Reference
ReleaseType Property
See Also

Returns an integer that determines how a Form object is released. Not available at design time; read-only at run time.

Object.ReleaseType

Return Value

The settings for the ReleaseType property are:

Setting | Description
0 | Variable released.
1 | Close menu command or close box.
2 | Exit Visual FoxPro.

Remarks

Applies To: Form Object | _SCREEN System Variable

The ReleaseType property is set prior to the QueryUnload event being called.

See Also

Other Resources

Properties
QueryUnload Event
Unload Event


Resizable Property

Visual FoxPro 9.0 Language Reference
Resizable Property
See Also

Specifies whether a Column object can be sized at run time by the user. Available at design time; read/write at run time.

Column.Resizable[ = lExpr]

Return Value

lExpr

The settings for the Resizable property are:

Setting Description

True (.T.)

The Column object is sizable.

False (.F.)

(Default) The Column object cannot be sized by the user.

Remarks

Applies To: Column

See Also

Other Resources

Properties
Width Property
Resize Object
Resize Event


RespectCursorCP Property

Visual FoxPro 9.0 Language Reference
RespectCursorCP Property
See Also

Specifies whether to take the code page of the cursor into consideration.

Note:
The UTF8Encoded property works in conjunction with the setting of RespectCursorCP when UTF8Encoded is True (.T.).

RespectCursorCP applies only when executing the XMLAdapter ToXML method, which creates XML consistent with its setting.

For more information about how code pages map to XML encoding attributes, see CURSORTOXML( ) Function.

XMLAdapter.RespectCursorCP [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

Create XML with default Windows-1252 encoding. (Default)

True (.T.)

Set encoding to the code page of the cursor.

Remarks

Applies To: XMLAdapter Class

For example, the following table describes how RespectCursorCP and UTF8Encoded interact with each other.

RespectCursorCP | UTF8Encoded | Conversion performed
False | False | Windows-1252 (Default)
True | False | Set output encoding attribute to the code page of the cursor.
False | True | Set output encoding attribute to UTF-8. No character translation occurs.
True | True | Set output encoding attribute to UTF-8. Translate character data to UTF-8.
True | False | Set output encoding attribute to the code page of the cursor.

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
UTF8Encoded Property
ToXML Method


RespectNesting Property

Visual FoxPro 9.0
RespectNesting Property
See Also

Specifies whether the ToXML Method should nest tables based on the NestedInto Property setting, and whether nesting should be respected during XML parsing.

XMLAdapter.RespectNesting = [lValue]

Return Value

lValue

Logical data type. The following table lists values for lValue.

lValue Description

False (.F.)

Specifies that the ToXML method ignores the NestedInto property setting.

True (.T.)

Specifies that the ToXML method nests tables based on the NestedInto property.

Remarks

Applies to: XMLAdapter Class

When this property is set to False (.F.), the XMLAdapter behavior is the same as in Visual FoxPro 8.0. However, when RespectNesting is set to True (.T.), the Visual FoxPro 9.0 behavior differs as follows:

  • When loading a .NET Dataset schema, the LoadXML method sets the NestedInto, NextSiblingTable, and FirstNestedTable properties for all XMLTables objects based on the nesting information from the schema.

  • The ToCursor and ChangesToCursor methods (when only unchanged records are loaded) use the following parsing logic:

    • If a table is nested, its node must be an immediate child for the outer table’s node.

    • If a table isn't nested, its node must be an immediate child for the XMLAdapter's node.

  • If schema is generated, the ToXML method respects the nesting information and generates schema with appropriate nesting.

  • If XML is generated in diffgram + changes-only mode, an error is generated because the nested format is not supported for that mode.

  • The ToXML method appropriately nests data. The nesting is done based on the nesting information and the relation set from the outer cursor to the nested cursor. Note that a direct relation is required.

See Also

Reference

XMLAdapter Class
XMLTable Class
ToXML Method
ToCursor Method
ChangesToCursor Method
NestedInto Property
FirstNestedTable Property
NextSiblingTable Property

Other Resources

Properties (Visual FoxPro)


RightToLeft Property

Visual FoxPro 9.0 Language Reference
RightToLeft Property
See Also

Specifies the reading order of text in controls and the display of streaming output on forms. RightToLeft is disregarded unless you are running a Middle Eastern version of Microsoft Windows. Available at design time; read/write at run time.

Object.RightToLeft[ = lExpression]

Return Value

lExpression

The settings for the RightToLeft property are:

Setting Description

True (.T.)

(Default) Text is entered and displayed in controls in a right to left reading order. Streaming output (for example, text displayed with ? or ??) is displayed on forms in a right-to-left reading order.

False (.F.)

Text is entered and displayed in controls in a left-to-right reading order. Streaming output is displayed on forms in a left-to-right reading order.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | EditBox | Form | Grid | Label | ListBox | OptionButton | PageFrame | _SCREEN | Spinner | TextBox

Use the Alignment property to specify the orientation of text in check boxes and option buttons.

See Also

Other Resources

Properties
Alignment Property


RotateFlip Property

Visual FoxPro 9.0 Language Reference
RotateFlip Property
See Also

Specifies a rotation or inversion (flip) for an image. Read/write at design and run time.

Image.RotateFlip [ = nValue ]

Parameters

nValue

Numeric data type. The following table lists the values for nValue.

nValue Setting Description

0

RotateNoneFlipNone

Specifies no rotation or flipping.

1

Rotate90FlipNone

Specifies a 90-degree rotation without flipping.

2

Rotate180FlipNone

Specifies a 180-degree rotation without flipping.

3

Rotate270FlipNone

Specifies a 270-degree rotation without flipping.

4

RotateNoneFlipX

Specifies no rotation and a horizontal flip.

5

Rotate90FlipX

Specifies a 90-degree rotation followed by a horizontal flip.

6

Rotate180FlipX

Specifies a 180-degree rotation followed by a horizontal flip.

7

Rotate270FlipX

Specifies a 270-degree rotation followed by a horizontal flip.

Remarks

Applies To: Image Control

Animated .gif images are not supported.

Because an image can have an .msk file, the .msk file must be formatted properly.

Note:
Visual FoxPro stores a single image in memory internally. If you use that image multiple times, Visual FoxPro renders it the same way regardless of RotateFlip. If you want to display the same image multiple times in various rotations, rename each copy of the image that you use. If you issue the CLEAR...RESOURCES command, Visual FoxPro reloads the image into memory and loses any prior GDI+ settings.

See Also

Other Resources

Properties
Graphics Support in Visual FoxPro
CLEAR Commands
PicturePosition Property
Picture Property


Rotation Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Rotation Property (Visual FoxPro)
See Also Example

Specifies a number of degrees to rotate a control in a counterclockwise direction. Read/write at design time and run time.

Control.Rotation [= nValue]

Return Value

nValue

Specifies 0 to 360 degrees of rotation for a control. The default setting is 0.

Remarks

Applies To: Label | Line | Shape

Clarity of the text can vary depending on the font and font size specified. For example, small font sizes appear best set at 0-, 90-, or 180-degrees.

For Label controls, the following functionality applies when setting Rotation:

  • Rotation works only with TrueType fonts. Certain font settings such as FontStrikethru might not display properly at certain angles.

  • Rotation is not supported when the Style property is set to 3 (Themed) because the label text is drawn by the theme. For more information, see Style Property.

  • When aligning text in the label, the Alignment property is respected only when Rotation is set to 0. Otherwise, the label is centered then rotated. For more information, see Alignment Property.

  • The WordWrap property is supported only when Rotation is set to 0. In other words, if Rotation is set to a value other than 0, no wordwrapping occurs even if WordWrap is to True (.T.). For more information, see WordWrap Property.

  • The AutoSize property does not resize the control based on the Rotation setting. Text is always centered in the label. Therefore, it is recommended that you make sure the label is large enough to accommodate for any rotation position. For more information, see AutoSize Property.

  • Hotkeys (\<) specified in the Caption property do not display, though they remain functional, when labels are rotated. For more information, see Caption Property.

For Shape and Line controls, the following functionality applies when setting Rotation:

  • Rotation applies when drawing polygon shapes and lines created by the PolyPoints property. For more information, see PolyPoints Property.

  • The control rotates around its center axis.

Example

The following example creates a form and adds a label and two command buttons based on custom classes. The Rotation property is set each time you click the Rotate command button, which rotates the label.

The following lines of code use the CREATEOBJECT( ) function to create a form and the AddObject method to add a Label control and two custom command buttons to the form. The Visible property is then set to True (.T.) for the label and the command buttons so they display on the form. The Show method displays the form and the READ EVENTS command begins event processing. The DEFINE CLASS command defines a custom Label class and CommandButton classes and contains settings for the appropriate properties.

Copy Code
frmMyForm = CREATEOBJECT('Form')
frmMyForm.AddObject('lblLabel1','lblMyLabel')
frmMyForm.AddObject('cmdCmndBtn1','cmdMyCmndBtn1')
frmMyForm.AddObject('cmdCmndBtn2','cmdMyCmndBtn2')
frmMyForm.lblLabel1.Visible = .T.
frmMyForm.cmdCmndBtn1.Visible =.T.
frmMyForm.cmdCmndBtn2.Visible =.T.
frmMyForm.Show
READ EVENTS
DEFINE CLASS lblMyLabel AS Label
   Caption = "MyLabel"
   Left = 150
   Top = 50
   Height = 50
   Width = 50
ENDDEFINE

The class definition for the following command button increments the Rotation property in the Click event every time the button is clicked. When the Rotation property is increased, the label rotates by the specified number of degrees. When the number of degrees totals 360, the Rotation property is reset to 0 so that the label appears in its starting position.

Copy Code
DEFINE CLASS cmdMyCmndBtn1 AS CommandButton
   Caption = '\<Rotate'
   Left = 125
   Top = 150
   Height = 25
   PROCEDURE Click
      ThisForm.lblLabel1.Visible = .F.
      ThisForm.lblLabel1.Rotation = ThisForm.lblLabel1.Rotation + 45
      IF ThisForm.lblLabel1.Rotation = 360
         ThisForm.lblLabel1.Rotation = 0
      ENDIF
      ThisForm.lblLabel1.Visible = .T.
ENDDEFINE

The class definition for the following command button includes the CLEAR EVENTS command in the Click event of the command button to stops event processing and closes the form.

Copy Code
DEFINE CLASS cmdMyCmndBtn2 AS CommandButton
   Caption = '\<Quit'
   Cancel = .T.
   Left = 125
   Top = 200
   Height = 25
   PROCEDURE Click
      CLEAR EVENTS
ENDDEFINE

See Also

Other Resources

RotateFlip Property
Properties


RowColChange Property

Visual FoxPro 9.0 Language Reference
RowColChange Property
See Also

Contains a value that identifies the type of cell movement made in a grid. Readonly at design and run-time.

Grid.RowColChange

Remarks

Applies To: Grid

The value of RowColChange is 0 at opening and after refresh of a grid. You can query this property in AfterRowColChange and BeforeRowColChange events to determine the type of change that triggered the event, according to the following table.

Value | Description
0 (default) | No change.
1 | Row change
2 | Column change
3 | Row and column change

See Also

Other Resources

Properties
Grid Control
AfterRowColChange Event
BeforeRowColChange Event


RowHeight Property

Visual FoxPro 9.0 Language Reference
RowHeight Property
See Also

Specifies the height of the rows in a Grid control. Available at design time; read/write at run time.

Grid.RowHeight[ = nHeight]

Return Value

nHeight

Specifies the height of all the rows in a Grid control.

Remarks

Applies To: Grid

If RowHeight is set to –1 (Auto), it automatically resizes the rows to fit the current FontSize property setting.

See Also

Other Resources

Properties
FontSize Property
RowColChange Property
RowSource Property


RowSource Property

Visual FoxPro 9.0 Language Reference
RowSource Property
See Also Example

Specifies the source of the values in a ComboBox or ListBox control. Read/write at design time and run time.

Note:
The RowSourceType property determines the source you can set for the RowSource property. It is recommended that you set RowSourceType before setting RowSource. For more information, see RowSourceType Property.

Control.RowSource [= cValue]

Return Value

cValue

Specifies the source for the values displayed in the control.
Note:
When you set the RowSource property using code, you must enclose the value with quotation marks ("").

The following table lists possible values for cValue.

cValue Description

Nothing

The control is filled at run time using the AddItem or AddListItem method or List or ListItem properties. (Default)

For more information, see AddItem Method, AddListItem Method, List Property, and ListItem Property.

Val1,Val2,Val3,...

A comma-delimited list of values.

The control is populated with values from the comma-delimited list.

TableAlias

The alias of an open table.

The control is populated with values from the fields in the table.

SQLSELECTStatement

A SQL SELECT statement that creates a cursor or table, for example, "SELECT * FROM Table".

The control is populated with values from columns in the cursor or table created by the SQL statement.

Note:
A browse window appears when the SQL SELECT statement is executed.

MyQueryFile.qpr

The name of a query (.qpr) file.

Note:
Be sure to include the .qpr file name extension. A Browse window appears when the query is executed.

The control is populated with values from the columns in the query results.

myArray

The name of an array.

The control is populated with values from the array.

TableAlias.Field1, Field2, Field3, ...

A comma-delimited list of fields from a single open table, which can be prefaced by the table alias and a period.

The control is populated with values from the fields. The ColumnCount property should match the number of fields specified.

*.fileExt

A file skeleton (for example, "*.dbf" or "*.txt") or a mask.

The control is populated with file names from the current directory as well as options to choose a different drive or directory containing the file names.

TableName or TableAlias

The name or alias of a table.

The control is populated with field names from the table.

Note:
When RowSourceType is set to 8, and if RowSource property is empty, the control is populated with field names from the currently selected table. Otherwise, if RowSource specifies the name of a table, a table alias, or the name of the database, the control is populated with field names from the specified source.

MenuName

The name of a menu. Included for backward compatibility.

CollectionName [, CollectionMemberProp [, CollectionMemberProp2 [, ...]]]

CollectionName specifies a string that is an expression, which evaluates to a Visual FoxPro or COM Collection object.

You can also specify properties of objects in the collection. The control is populated with values of the properties specified as well as with other members of the collection that are not objects.

Note:
When you specify a collection and properties of the objects in the collection for RowSource, the value for each property is displayed as a separate column. Members of the collection that are not objects display in the first column.

Note:
If you do not specify any properties for RowSource, the control displays other members of the collection that are not objects and the string "(Object)" for each object in the collection in a single column. The string "(Object)" is returned for the Value property. For more information, see Value Property.

Remarks

Applies To: ComboBox | ListBox

You can display multiple columns in the control by setting the ColumnCount property. The values you specify for RowSource fill the control, by row, up to the number of columns specified by the ColumnCount property. For example, you can display values in multiple columns by setting RowSourceType to 1 (Value) and specifying the values, separated by commas, for each column and row for the RowSource property as shown in the following example:

Copy Code
myListBox.ColumnCount = 2
myListBox.RowSource = "Col1Row1,Col2Row1,Col1Row2,Col2Row2,Col2Row3"

In the example, no value is entered between the value in column 2, row 2 and the value in column 2, row 3 so no value displays in column 1, row 3.

To specify an alias for the table containing the columns, use the following syntax:

Copy Code
myListBox.RowSource = Alias.Col1Row1,Col2Row1,Col1Row2,Col2Row2,Col2Row3
Note:
When the ColumnCount property is set to 0 or 1, the control displays the first item or value only in a single column. Otherwise, the control displays each item or value in a column up to the number of columns specified by ColumnCount. You might need to set the ColumnWidths property to expand the width of the control so the items or values within display properly.

For more information, see ColumnCount Property, How to: Create Multicolumn List Boxes, and Display Multiple Columns in a List Box Sample.

Because the default value for the Value property is numeric, if you want the Value property to reflect the character string of the selected item in a list box or combo box, set the Value property to an empty string (""). To enter an empty string in the Properties window, press the SPACEBAR key and then the BACKSPACE key. For more information, see Value Property and Properties Window.

Example

Example 1

The following example creates a list box on a form and specifies an array as the source of the items in the list box. The RowSourceType property is set to 5 (Array) to specify that an array is the source for the items in the list box, and the name of the array is specified by the RowSource property. The MultiSelect property for the list box is set to True (.T.) so that you can make multiple selections from the list box.

The steps performed in this example appear as follows:

  • Clear the main Visual FoxPro window using the CLEAR command.

  • Create an array called gaMyListArray using the DIMENSION command.

  • Fill the array with letters using the FOR...ENDFOR and STORE commands.

  • Create a form using the CREATEOBJECT( ) function.

  • Disable the Close button on the form's title bar by setting the Closable property.

  • Move the form by setting the Move property.

  • Add a CommandButton control based on the user-defined cmdMyCmdButton class by calling the AddObject method.

  • Add a ListBox control based on the custom lstMyListBox class by calling the AddObject method.

  • Specify an array as the row source type for the list box by setting the RowSourceType property.

  • Specify the array gaMyListArray as the row source for the list box by setting the RowSource property.

  • Show the command button by setting the Visible property.

  • Show the list box by setting the Visible property.

  • Display the form by calling the form's Show method.

  • Begin event processing by calling the READ EVENTS command.

  • Define the user-defined cmdMyCmdButton class based on the CommandButton control using the DEFINE CLASS command. The code in the DEFINE CLASS command sets properties for the user-defined class and defines procedures.

  • Define the user-defined lstMyListBox class based on the ListBox control using the DEFINE CLASS command. The code in the DEFINE CLASS command sets properties for the user-defined class and defines procedures.

Copy Code
CLEAR
DIMENSION gaMyListArray(10)
FOR gnCount = 1 to 10
   STORE REPLICATE(CHR(gnCount+64),6) TO gaMyListArray(gnCount)
NEXT

frmMyForm = CREATEOBJECT('Form')
frmMyForm.Closable = .F.
frmMyForm.Move(150,10)
frmMyForm.AddObject('cmbCommand1','cmdMyCmdBtn')
frmMyForm.AddObject('lstListBox1','lstMyListBox')
frmMyForm.lstListBox1.RowSourceType = 5
frmMyForm.lstListBox1.RowSource = 'gaMyListArray'
frmMyForm.cmbCommand1.Visible =.T.
frmMyForm.lstListBox1.Visible =.T.
frmMyForm.Show
READ EVENTS

DEFINE CLASS cmdMyCmdBtn AS CommandButton
   Caption = '\<Quit'
   Cancel = .T.
   Left = 125
   Top = 210
   Height = 25
   PROCEDURE Click
      CLEAR EVENTS
      CLEAR
ENDDEFINE

DEFINE CLASS lstMyListBox AS ListBox
   Left = 10
   Top = 10
   MultiSelect = .T.
   PROCEDURE Click
      ACTIVATE SCREEN
      CLEAR
      ? "Selected items:"
      ? "---------------"
      FOR nCnt = 1 TO ThisForm.lstListBox1.ListCount
         IF ThisForm.lstListBox1.Selected(nCnt)
            ? SPACE(5) + ThisForm.lstListBox1.List(nCnt)
         ENDIF
      ENDFOR
ENDDEFINE

Example 2

The following example explains how to specify a collection for the RowSource property of a list box. Suppose you create a collection referenced by the memory variable oCustomerCol using the following steps:

  • Call the SCAN...ENDSCAN command with the Customers table in the Northwind sample database located in ...\Samples\Northwind directory.

  • Call SCATTER...NAME for each record.

  • Add the object created by the SCATTER command to the collection.

You can specify the collection referenced by oCustomerCol and the record fields for the RowSource property as follows:

Copy Code
lstmyListBox.RowSource = "colCustomerCol, CustID, Company, LastName"

For more examples, see How to: Choose the Type of Data for a List or Combo Box.

See Also

Other Resources

Properties
RecordSource Property
How to: Allow Users to Add Items to a List Box
Controls for Displaying Lists
How to: Display Child Records in a List
How to: Populate Query Results in a Form Control
How to: Refresh a One-to-Many Display Based on a List Value


RowSourceType Property

Visual FoxPro 9.0 Language Reference
RowSourceType Property
See Also

Specifies the type belonging to the row source set for the RowSource property. Read/write at design time and run time.

For more information about using the RowSourceType property, see How to: Choose the Type of Data for a List or Combo Box.

Control.RowSourceType [= nValue]

Return Value

nValue

Specifies a value indicating the type for the row source value in the control. The following table lists the values for nValue.

nValue Description

0

None. (Default)

1

Value.

2

Table alias.

3

SQL statement.

4

Query (.qpr) file.

5

Array.

6

Fields.

7

Files.

8

Field structure of a table.

9

Pop-up. Included for backward compatibility.

10

Collection object.

Remarks

Applies To: ComboBox | ListBox

See Also

Other Resources

Properties
RowSource Property
RecordSourceType Property
How to: Allow Users to Add Items to a List Box
Controls for Displaying Lists
How to: Display Child Records in a List
How to: Populate Query Results in a Form Control
How to: Refresh a One-to-Many Display Based on a List Value


ScaleMode Property

Visual FoxPro 9.0 Language Reference
ScaleMode Property
See Also

Specifies the unit of measurement for the coordinates of an object when using graphics methods or when positioning controls. Available at design time and run time.

Object.ScaleMode = nMode

Return Value

nMode

The settings for the ScaleMode property are:

Setting Description

0

Foxels (A Visual FoxPro term. Equivalent to the maximum height and average width of a character in the current font.)

3

Pixels (default; smallest unit of monitor or printer resolution)

Remarks

Applies To: Form | _SCREEN | ToolBar

See Also

Other Resources

Properties
DrawMode Property
DrawStyle Property


SCCProvider Property

Visual FoxPro 9.0 Language Reference
SCCProvider Property
See Also

The name of the source code control provider for a project. Read-only.

Object.SCCProvider

Remarks

Applies To: Project Object

You can specify a source code control provider for new projects in the Projects tab of the Options dialog box. The SCCProvider property contains the empty string if a project isn't under source control.

See Also

Other Resources

Properties
Source Control Software in Visual FoxPro
SCCStatus Property
Projects Tab, Options Dialog Box


SCCStatus Property

Visual FoxPro 9.0 Language Reference
SCCStatus Property
See Also

Contains a numeric value indicating the source control status of a file in a project. Read-only at design time and run time.

Object.SCCStatus

Remarks

Applies To: File Object

The following table lists the values the SCCStatus property can contain:

Value | FoxPro.h constant | Description
0 | SCCFILE_NOTCONTROLLED | File is not source controlled.
1 | SCCFILE_NOTCHECKEDOUT | File is in source control but is not checked out.
2 | SCCFILE_CHECKEDOUTCU | File is checked out to the current user.
3 | SCCFILE_CHECKEDOUTOU | File is checked out to someone other than the current user.
4 | SCCFILE_MERGECONFLICT | File has a merge conflict.
5 | SCCFILE_MERGE | File has been merged without conflict.
6 | SCCFILE_CHECKEDOUTMU | File is checked out to multiple users.

See Also

Other Resources

Properties
SCCProvider Property
Source Control Software in Visual FoxPro
How to: Put Projects Under Source Control


ScrollBars Property

Visual FoxPro 9.0 Language Reference
ScrollBars Property
See Also

Specifies the type of scroll bars that an EditBox control, Form object, or Grid control has. Read/write at design time; read-only at run time.

[Form.]Control.ScrollBars[= nType]

Return Value

nType

Specifies the type of scroll bars for the control or object. For EditBox controls, the following table lists the settings for nType.

nType Description

0

None

2

Vertical (Default)
For Form objects, the following table lists the settings for nType.

nType Description

0

None (Default)

1

Horizontal

2

Vertical

3

Both vertical and horizontal
For Grid controls, the following table lists the settings for nType.

nType Description

0

None

1

Horizontal

2

Vertical

3

Both vertical and horizontal (Default)

Remarks

Applies To: EditBox | Form | Grid

ScrollBars is ignored for the _SCREEN system variable. For more information, see _SCREEN System Variable.

Scroll bars, if enabled, display automatically when the form, grid, or edit box contains more information than can be displayed in the space provided. The Scrollbars property setting is evaluated for a form when the form is instantiated.

Tip:
If you want to control the size of the scroll bar at run time, specify a non-zero value for nType.

Note:
Values of nType greater than 0 require more memory to accommodate the possible use of the SaveAs method. For more information, see SaveAs Method. To save memory, specify nType = 0.

See Also

Other Resources

Properties
ContinuousScroll Property
DoScroll Method
Scrolled Event


Seconds Property

Visual FoxPro 9.0 Language Reference
Seconds Property
See Also

Specifies whether the seconds portion of a DateTime value is displayed in a text box. Available at design time and run time.

Object.Seconds[ = nValue]

Return Value

nValue

One of the following settings:

Setting Description

0

Off. The seconds portion of the DateTime value is not displayed.

1

On. The seconds portion of the DateTime value is displayed.

2

(Default) The SET SECONDS setting determines if the seconds portion of the DateTime value is displayed. If SET SECONDS is ON, the seconds portion of the DateTime value is displayed. If SET SECONDS is OFF, the seconds portion of the DateTime value is not displayed.

Remarks

Applies To: TextBox

The Seconds property setting is ignored if the DateFormat property is set to Short or Long.

See Also

Other Resources

Properties
Century Property
DateFormat Property
DateMark Property
Hours Property
SET SECONDS Command
StrictDateEntry Property


SelectCmd Property

Visual FoxPro 9.0 Language Reference
SelectCmd Property
See Also

Specifies the command for retrieving data from the data source in the CursorAdapter DataSourceType property. Read/write at design time and run time.

CursorAdapter.SelectCmd [ = cCommand ]

Return Value

cCommand

Specifies a character string or expression that evaluates to a valid command string. For XML data sources, cCommand should be one of the following:
  • An expression that evaluates to a valid XML source for the XMLTOCURSOR( ) function. XMLTOCURSOR( ) retrieves the data.

  • An expression that evaluates to an XMLTable object. The XMLTable ToCursor method retrieves the data.

Remarks

Applies To: CursorAdapter Class

If the CursorAdapter UseDeDataSource property is True (.T.), and the cursor adapter is a member of the data environment, the DataEnvironment DataSource and DataSourceType properties override the relevant CursorAdapter properties.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
XMLTOCURSOR( ) Function
XMLTable Class
ToCursor Method


Selected Property

Visual FoxPro 9.0 Language Reference
Selected Property
See Also Example

Specifies whether an item is selected in a ComboBox or ListBox control. Not available at design time and read/write at run time.

[Form.]Control.Selected(nIndex) [= lExpr ]

Return Value

nIndex

Numeric data type. Selected specifies the index of an item in a ComboBox or ListBox.
lExpr

Logical data type. The following table lists the settings for the Selected property.

Setting Description

True (.T.)

Item is selected.

False (.F.)

Item is not selected. (Default)

Remarks

Applies To: ComboBox Control | ListBox Control

Setting the Selected property on a ListBox control also sets the ListItem property and fires the ProgrammaticChange event.

The Selected property is particularly useful where users can make multiple selections. You can quickly check which items in a list are selected. You can also use this property to select or clear items in a list from within a program. To check whether the third item in a list box is selected, use the following code:

Copy Code
IF MyList.Selected(3)
  WAIT WINDOW "It's selected!"
ELSE
  WAIT WINDOW "It's not!"
ENDIF

Example

The following example creates a list box. An array serves as the source of the items that appear in the list box items, and the name of the array is specified using the RowSource property. The RowSourceType property is set to 5 (array) to specify that an array is the source for the items in the list box.

The MultiSelect property for the list box is set to True (.T.), making it possible for you to make multiple selections from the list box. The item or items you choose in the list box are displayed by using the ListCount, Selected, and List properties to determine the number of items in the list box and the items you chose.
Copy Code
CLEAR

DIMENSION gaMyListArray(10)
FOR gnCount = 1 to 10  && Fill the array with letters
   STORE REPLICATE(CHR(gnCount+64),6) TO gaMyListArray(gnCount)
NEXT

frmMyForm = CREATEOBJECT('Form')  && Create a form.
frmMyForm.Closable = .f.  && Disable window context menu.

frmMyForm.Move(150,10)  && Move the form.

frmMyForm.AddObject('cmbCommand1','cmdMyCmdBtn')  && Add "Quit" command button.
frmMyForm.AddObject('lstListBox1','lstMyListBox')  && Add ListBox control.

frmMyForm.lstListBox1.RowSourceType = 5  && Specifies an array.
frmMyForm.lstListBox1.RowSource = 'gaMyListArray' && Specifies array source containing list box items.

frmMyForm.cmbCommand1.Visible =.T.  && "Quit" command button visible.
frmMyForm.lstListBox1.Visible =.T.  && List box visible.

frmMyForm.SHOW  && Display form.
READ EVENTS  && Start event processing.

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create command button.
   Caption = '\<Quit'  && Assign caption on the command button.
   Cancel = .T.  && Assign default Cancel command button (Esc).
   Left = 125  && Command button column.
   Top = 210  && Command button row.
   Height = 25  && Command button height.

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing and close form.
      CLEAR  && Clear main Visual FoxPro window.
ENDDEFINE

DEFINE CLASS lstMyListBox AS ListBox  && Create ListBox control.
   Left = 10  && List Box column
   Top = 10  && List Box row
   MultiSelect = .T.  && Allow selecting more than 1 item.

PROCEDURE Click
   ACTIVATE SCREEN
   CLEAR
   ? "Selected items:"
   ? "---------------"
   FOR nCnt = 1 TO ThisForm.lstListBox1.ListCount
      IF ThisForm.lstListBox1.Selected(nCnt)  && Is item selected?
         ? SPACE(5) + ThisForm.lstListBox1.List(nCnt) && Show item.
      ENDIF
   ENDFOR

ENDDEFINE

See Also

Other Resources

Properties
AddItem Method
Clear Method
ItemBackColor, ItemForeColor Properties
List Property
ListCount Property
ListItemID Property
MultiSelect Property
NewItemID Property
RemoveItem Method
RemoveListItem Method
SelectedID Property
SelectedItemBackColor Property
SelectedItemForeColor Property
TopItemID Property


SelectedBackColor, SelectedForeColor Properties

Visual FoxPro 9.0 Language Reference
SelectedBackColor, SelectedForeColor Properties
See Also

Specifies the background or foreground color for the selected text. Available at design time and run time. There are two versions of the syntax for each of these two properties.

Control.SelectedBackColor[ = nColor]
Control.SelectedBackColor = RGB(nRedValue, nGreenValue, nBlueValue)
Control.SelectedForeColor[ = nColor]
Control.SelectedForeColor = RGB(nRedValue, nGreenValue, nBlueValue)

Return Value

nColor

Specifies a single number to represent the color.
Note:
In the Properties window, you can double-click any of the color properties to display the Color dialog box. You can choose or define colors from this dialog box. The red, green, and blue intensities that correspond to the color you choose become the settings for these properties after you close the Color dialog box.

Remarks

Applies To: ComboBox Control | EditBox Control | Spinner Control | TextBox Control

See Also

Other Resources

Properties
BackColor, ForeColor Properties
RGB( ) Function
SelectedItemBackColor Property
SelectedItemForeColor Property


SelectedID Property

Visual FoxPro 9.0 Language Reference
SelectedID Property
See Also

Specifies whether an item is selected in a combo box or list box. Not available at design time; read/write at run time.

Control.SelectedID(nItemID)[= lExpr]

Return Value

nItemID

Specifies the item ID of an item in a combo box or ListBox.
lExpr

The settings for the SelectedID property are:

Setting Description

True (.T.)

The item is selected.

False (.F.)

(Default) The item isn't selected.

Remarks

Applies To: ComboBox | ListBox

Setting the SelectedID property on a Listbox control also sets the ListItemID property, and fires the ProgrammaticChange event.

The SelectedID property is particularly useful where users can make multiple selections. You can quickly check which items in a list are selected. You can also use this property to select or deselect items in a list using code. To check whether the third item in a ListBox is selected, issue the following:

Copy Code
IF MyList.SelectedID(3)
    WAIT WINDOW "It's selected!"
ELSE
    WAIT WINDOW "It's not!"
ENDIF

See Also

Other Resources

Properties
AddItem Method
Clear Method
List Property
ListCount Property
ListItemID Property
MultiSelect Property
NewItemID Property
RemoveItem Method
RemoveListItem Method
Selected Property
TopItemID Property


SelectedItemBackColor Property

Visual FoxPro 9.0 Language Reference
SelectedItemBackColor Property
See Also

Specifies the background color for a selected item in a ComboBox or ListBox or cell (TextBox only) in a Grid control. SelectedItemBackColor is related to the HighlightForeColor and HighlightBackColor properties in that you need to control the color of the selected cell in a Grid row. Read/write at design and run time. There are two versions of the syntax.

Control.SelectedItemBackColor [= nColor ]
Control.SelectedItemBackColor = RGB( nRedValue, nGreenValue, nBlueValue )

Parameters

nColor

Numeric data type. SelectedItemBackColor specifies an integer representing a single color value. Visual FoxPro derives the default color setting from the Windows operating system color setting for Selected Items. For information about valid color values, see BackColor, ForeColor Properties.

Remarks

Applies To: ComboBox Control | ListBox Control | Grid Control

You can find the Selected Items color setting in the Advanced Appearance dialog box, which you can open by going to the Start Menu, opening the Control Panel, selecting Display, clicking the Appearance tab, clicking Advanced, and selecting Selected Items from the Item drop-down list.

You can also define colors by entering the RGB value for the property in the Properties window or choose colors by double-clicking the property in the Properties window to display the Color dialog box. The red, green, and blue color values corresponding to the color you choose become the settings for these properties after you close the Color dialog box.

At the Grid control level, SelectedItemBackColor and SelectedItemForeColor apply only to TextBox controls. Though a Grid column can contain many different types of objects, only the default TextBox control is supported. You must set SelectedItemBackColor and SelectedItemForeColor individually at the control level for other controls. The priority of the Grid SelectedItemBack and SelectedItemForeColor settings over the behavior of a specific TextBox control in the column is determined as follows:

  • When Grid HighlightStyle is set to 0, Grid SelectedItemBackColor and SelectedItemForeColor are disregarded, and the properties of the text box take precedence. If Grid HighlightStyle is set to a value of 2, only the highlight colors persist, and selected items display only when a grid has focus.

  • When Grid HighlightStyle is set to a value greater than 0, the following behavior applies:

    • The TextBox control properties control the actual colors of the selected text box.

    • When Grid SelectedItemBackColor and SelectedItemForeColor are explicitly set, the corresponding properties for all TextBox controls the grid are set. This occurs at design time and run time.

    • The grid's property settings take precedence over conflicting text box property settings. If you want the TextBox SelectedItemBackColor and SelectedItemForeColor to override the corresponding grid properties, set the individual text box properties after setting the grid properties.

      Tip:
      You can create routine that performs this process, which provides flexibility should the grid properties change at run time.

    • When setting the TextBox BackColor and ForeColor properties to control how the text box displays when clicked for editing, the Grid SelectedItemBackColor and SelectedItemForeColor properties behave as if the entire cell was selected.

You can reset the colors of a grid and its text boxes to their class default settings by calling the ResetToDefault method for the Grid and TextBox SelectedItemForeColor and SelectedItemBackColor properties.

Note:
This differs from how Visual FoxPro handles other grid color settings. For example, when you call ResetToDefault on a grid's BackColor property, the underlying columns and text boxes are set to the grid's default BackColor property and not the default BackColor properties of the columns and text boxes.

See Also

Other Resources

Properties
HighlightStyle Property
SelectedItemForeColor Property
TextBox Control
ResetToDefault Method
Selected Property
ItemBackColor, ItemForeColor Properties
RGB( ) Function


SelectedItemForeColor Property

Visual FoxPro 9.0 Language Reference
SelectedItemForeColor Property
See Also

Specifies the foreground color of the text of a selected item in a ComboBox or ListBoxor cell (TextBox only) in a Grid control. SelectedItemForeColor is related to the HighlightForeColor and HighlightBackColor properties in that you need to control the color of the selected cell in a grid row. Read/write at design and run time. There are two verions of the syntax.

Control.SelectedItemForeColor [= nColor ]
Control.SelectedItemForeColor = RGB( nRedValue, nGreenValue, nBlueValue )

Parameters

nColor

Numeric data type. SelectedItemForeColor specifies an integer representing a color value. Visual FoxPro derives the default color setting from the Windows operating system font color setting for Selected Items. For information about valid color values, see BackColor, ForeColor Properties.

Remarks

Applies To: ComboBox Control | ListBox Control | Grid Control

For more information about the Grid SelectedItemForeColor and GridSelectedItemBackColor properties, see SelectedItemBackColor Property.

See Also

Other Resources

Properties
HighlightStyle Property
TextBox Control
ResetToDefault Method
Selected Property
ItemBackColor, ItemForeColor Properties
RGB( ) Function


SelectOnEntry Property

Visual FoxPro 9.0 Language Reference
SelectOnEntry Property
See Also

Specifies whether text in a column cell, edit box, or text box selected when the user moves to it. Available at design time and run time.

Object.SelectOnEntry[ = lExpr]

Return Value

The settings for the SelectOnEntry property are:

Setting | Description
True (.T.) | (Default for columns) The text is selected.
False (.F.) | (Default for edit and text boxes) The text isn't selected.

Remarks

Applies To: Column Object | EditBox Control | TextBox Control

If the Highlight property is set to true (.T.), you can use it in conjunction with the SelectOnEntry property to determine if the entire text appears selected. If you set the Highlight property to false (.F.), the SelectOnEntry property is ignored.

See Also

Other Resources

Properties
Highlight Property
HighlightRow Property


SelectionNamespaces Property

Visual FoxPro 9.0
SelectionNamespaces Property
See Also

Specifies a custom XMLNamespace declaration for XPath expressions. Read-write and design time and run time.

XMLAdapter.SelectionNamespaces = sValue

Return Value

sValue

Unicode string that specifies a custom XML namespace declaration. The default value is an empty string ("").

Remarks

Applies to: XMLAdapter class

For more information, see the SelectionNamespaces property description in the Microsoft Core XML Services (MSXML) 4.0 SDK.

The namespace prefixes in the following list are reserved for the XMLAdapter class and should not be used in this property:

  • "dataset"

  • all prefixes starting with "rowdata"

  • "diffgr"

See Also

Reference

XMLAdapter Class
DeclareXMLPrefix Property
XMLNameIsXPath Property

Other Resources

Properties


SelLength Property

Visual FoxPro 9.0 Language Reference
SelLength Property
See Also

Returns the number of characters the user selects in a text-entry area of a control, or specifies the number of characters to select. Not available at design time; read/write at run time.

 [Form.]Control.SelLength[= nLength]

Return Value

nLength

Specifies the number of characters selected. Selected text appears highlighted. The valid range of settings is 0 to the total number of characters in the control. Setting SelLength to less than 0 causes a run-time error.

Remarks

Applies To: ComboBox | EditBox | Spinner | TextBox

Use this property with the SelStart and SelText properties for tasks such as:

  • Setting the insertion point within a string of characters.

  • Establishing an insertion range that limits where the insertion point can go.

  • Selecting a specific group of characters (substrings) in a control.

  • Clearing text.

When working with these properties, be aware of the following behaviors:

  • Setting SelLength to less than 0 causes a run-time error.

  • Setting SelStart to greater than the text length sets the property to the existing text length. Changing SelStart changes the selection to an insertion point and sets SelLength to 0.

  • Setting SelText to a new value sets SelLength to 0 and replaces the selected text with the new string.

See Also

Other Resources

Properties
SelStart Property
SelText Property


SelStart Property

Visual FoxPro 9.0 Language Reference
SelStart Property
See Also

Returns the starting point of a text selection made by the user in a text-entry area of a control, or indicates the position of the insertion point if no text is selected. Also, specifies the starting point of a text selection in a text-entry area of a control. Not available at design time; read/write at run time.

 [Form.]Control.SelStart[= nStart]

Return Value

nStart

Specifies the starting point of text selected or indicates the position of the insertion point if no text is selected. Selected text appears shaded. The valid range of settings is 0 to the total number of characters in the edit area of the control.

Remarks

Applies To: ComboBox | EditBox | Spinner | TextBox

Use this property with the SelLength and SelText properties for tasks such as:

  • Setting the insertion point within a string of characters.

  • Establishing an insertion range that limits where the insertion point can go.

  • Selecting a specific group of characters (substrings) in a control.

  • Clearing text.

When working with these properties, be aware of the following behaviors:

  • Setting SelLength to less than 0 causes a run-time error.

  • Setting SelStart to greater than the text length sets the property to the existing text length. Changing SelStart changes the selection to an insertion point and sets SelLength to 0.

  • Setting SelText to a new value sets SelLength to 0 and replaces the selected text with the new string.

See Also

Other Resources

Properties
SelLength Property
SelText Property


SelText Property

Visual FoxPro 9.0 Language Reference
SelText Property
See Also

Returns the text that the user selected in a text-entry area of a control, or returns an empty string ("") if no characters are selected. Specifies the string containing the selected text. Not available at design time; read/write at run time.

 [Form.]Control.SelText[= cString]

Return Value

cString

Specifies the string containing the selected text or consists of an empty string if no characters are selected. Selected text appears shaded.

Remarks

Applies To: ComboBox | EditBox | Spinner | TextBox

Use this property with the SelLength and SelStart properties for tasks such as:

  • Setting the insertion point within a string of characters.

  • Establishing an insertion range that limits where the insertion point can go.

  • Selecting a specific group of characters (substrings) in a control.

  • Clearing text.

When working with these properties, be aware of the following behaviors:

  • Setting SelLength to less than 0 causes a run-time error.

  • Setting SelStart to greater than the text length sets the property to the existing text length. Changing SelStart changes the selection to an insertion point and sets SelLength to 0.

  • Setting SelText to a new value sets SelLength to 0 and replaces the selected text with the new string.

See Also

Other Resources

Properties
SelLength Property
SelStart Property


SendGDIPlusImage Property

Visual FoxPro 9.0
SendGDIPlusImage Property
See Also Example

Specifies whether the ReportListener will be passed a handle to the image source when the image is loaded by an object reference or from a General field. Does not apply to images loaded by filename.

ReportListener.SendGDIPlusImage Property [= iExpr]

Return Value

Integer data type.

Note that the property is set to integer type, not logical, to allow for the possibility that a derived class might use other integer values to represent providing the image in other ways besides a graphics handle. For example, a derived class might recognize a value of 2 to indicate "load all file-based images from their original files, and copy them to a different location or different format."

The following lists the values for iExpr recognized by the baseclass ReportListener.

0 or any negative integer value

(0 is Default) The ReportListener baseclass does not provide a handle to GDI+ images to derived classes in the Render method.
1 and higher integer values

The ReportListener baseclass provides a handle to GDI+ images to derived classes in the Render method.

Remarks

Applies To: ReportListener Object.

This property value has no meaning for baseclass ReportListener objects; it has no effect on native print and preview rendering capabilities. However, ReportListeners providing other types of output can set the property to 1 and receive a handle to the graphics object representing rendered images that come from General fields or the PictureVal property of an Image control, rather than file-based sources.

By default, for performance reasons, this information is not provided to derived classes.

Tip:
When you have a reference to a GDI+ graphics handle, you use the GDI+ API to manipulate it. Visual FoxPro ships with a number of Foundation Classes designed to make working with the GDI+ API easier to use. For more information, see GDI Plus API Wrapper Foundation Classes.

This property value does not affect the ReportListener's handling of file-based images. Derived classes receive the appropriate filename as an argument to the Render method, so no other handle is required.

Example

The following code fragment, showing three ReportListener methods, is similar to the internal methods of the XMLDisplayListener derived class. See ReportListener XML Display-Style Foundation Class for more information about this class and how it handles images.

In the BeforeReport event, the code in this example saves the current value of the SendGDIPlusImage. Then it checks to see if the report contains any General fields. If it finds any references to images in the layout information, it sets SendGDIPlusImage to 1 for the duration of the report.
Copy Code
#DEFINE LISTENER_SEND_GDI_IMAGE_HANDLE 1
PROCEDURE BeforeReport()
   THIS.oldSendGDIPlusImage = THIS.SendGDIPlusImage
   IF (THIS.SendGDIPlusImage < LISTENER_SEND_GDI_IMAGE_HANDLE) ;
        AND THIS.checkReportForGeneralFields()
     THIS.SendGDIPlusImage =   LISTENER_SEND_GDI_IMAGE_HANDLE
   ENDIF
   DODEFAULT()
ENDPROC

PROCEDURE checkReportForGeneralFields()
   LOCAL liGeneralFields, llOpened
   THIS.SetFRXDataSession()
   IF USED("FRX")
      * check,because
      * the method might be called
      * in the LoadReport() as well as BeforeReport()
      SELECT FRX
   ELSE
      USE (THIS.CommandClauses.File) SHARED NOUPDATE ALIAS FRX IN 0
      SELECT FRX
      llOpened = .T.
   ENDIF
   COUNT FOR ObjType = FRX_OBJTYP_PICTURE  AND  ;
            Offset =  FRX_PICTURE_SOURCE_GENERAL TO ;
            liGeneralFields
   IF llOpened
      USE IN FRX
   ENDIF
   THIS.SetCurrentDataSession()
   RETURN ( liGeneralFields > 0 )
ENDPROC

PROCEDURE AfterReport()
   DODEFAULT()
   THIS.SendGDIPlusImage = THIS.oldSendGDIPlusImage
ENDPROC

See Also

Tasks

How to: Add Pictures to Reports

Reference

Render Method
GDIPlusGraphics Property
PictureVal Property

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


SendUpdates Property

Visual FoxPro 9.0 Language Reference
SendUpdates Property
See Also

Specifies whether to send an SQL update query to update tables. When handling this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions. Read/write.

Note:
Setting SendUpdates applies only to CursorAdapter objects with ODBC or ADO data sources and overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP( ) has no effect.

CursorAdapter.SendUpdates [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

True (.T.)

Send an SQL update query to update tables when a view is used to make the update. (Default)

False (.F.)

Do not send an SQL update query to update tables.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


ServerClass Property

Visual FoxPro 9.0 Language Reference
ServerClass Property
See Also

Contains the name of a server class in a project. Read-only at design time and run time.

Object.ServerClass

Remarks

Applies To: Server Object

The names of server classes in a project are also displayed in the Servers tab of the ProjectInformation dialog box.

Automation servers are created in Visual FoxPro by adding classes defined as OLEPUBLIC to a project, and then building an executable file (.exe) or dynamic link library (.dll) from the project. You can have as many OLEPUBLIC classes as you want in the project and they can be defined in program files (.prg) or class libraries (.vcx).

For information about creating custom Automation servers, see How to: Create Automation Servers.

See Also

Other Resources

Properties
CREATE CLASS Command
DEFINE CLASS Command
ServerClassLibrary Property


ServerClassLibrary Property

Visual FoxPro 9.0 Language Reference
ServerClassLibrary Property
See Also

Contains the name of the class library or program containing a server class. Read-only at design time and run time.

Object.ServerClassLibrary

Remarks

Applies To: Server Object

The name of the class library or program containing the server class is also displayed in the Servers tab of the Project Information dialog box.

Automation servers are created in Visual FoxPro by adding classes defined as OLEPUBLIC to a project, and then building an executable file (.exe) or dynamic link library (.dll) from the project. You can have as many OLEPUBLIC classes as you want in the project and they can be defined in program files (.prg) or class libraries (.vcx).

For information about creating custom Automation servers, see How to: Create Automation Servers.

See Also

Other Resources

Properties
CREATE CLASS Command
DEFINE CLASS Command
ServerClass Property


ServerHelpFile Property

Visual FoxPro 9.0 Language Reference
ServerHelpFile Property
See Also

Specifies the Help file for the type library created for server classes in a project.

You can use the ServerHelpFile property to specify a Help file for the type library created when building a .dll or .exe file that contains server classes. Creating and specifying a Help file provides information about the properties or methods in server classes from a class or object browser. For example, Visual FoxPro includes the Object Browser so you can view type library information.

Object.ServerHelpFile [= cHelpFileName]

Return Value

cHelpFileName

Specifies the name of the help file for the type library. By default, cHelpFileName contains the empty string ("").

Remarks

Applies To: Project Object

See Also

Other Resources

Properties
HelpContextID Property
Server Object
Servers Collection
ServerProject Property


ServerName Property

Visual FoxPro 9.0 Language Reference
ServerName Property
See Also

Contains the full path and file name for an Automation server. Read-only at run time.

ApplicationObject.ServerName

Remarks

Applies To: Application Object | _VFP System Variable

The ServerName property makes it possible for you to determine the directory from which an in-process .dll or an out-of-process .exe Automation server was started, facilitating referencing of other files in distributed applications. You can also use ServerName to determine the directory from which a Visual FoxPro .EXE application was started.

The ServerName property for a development version of Visual FoxPro started in an interactive session contains the same value as the FullName property.

See Also

Other Resources

Properties
FullName Property
StartMode Property


ServerProject Property

Visual FoxPro 9.0 Language Reference
ServerProject Property
See Also

The name of the project containing server classes.

Object.ServerProject[ = cName]

Return Value

cName

Specifies the name of the project containing server classes. The default value is the name of the project containing the server classes, or, identically, the value of the Name property for the project.

Remarks

Applies To: Project Object

The ServerProject name you specify is the first section of the ProgID (Programmatic Identifier) that uniquely identifies the server. For example, if you set the ServerProject property to "MyApplication" and the server has an OLEPublic class named "Server1," you access the Server1 class with the syntax "MyApplication.Server1."

This property corresponds to the Project name item on the Servers tab of the Project Information dialog box.

See Also

Other Resources

Properties
Name Property
Server Object
Servers Collection
ServerHelpFile Property


ShowInTaskbar Property

Visual FoxPro 9.0 Language Reference
ShowInTaskbar Property
See Also

Specifies whether the top-level form object appears in the Windows taskbar at runtime. This setting is read-only at runtime.

Form.ShowInTaskbar = lExpr

Parameters

lExpr

Defaults to true (.T.), enabled. False (.F.) disables this property

Remarks

The ShowInTaskbar setting is ignored unless the ShowWindow Property value = 2

See Also

Other Resources

ShowWindow Property
Form Object
Properties
Language Reference


ShowTips Property

Visual FoxPro 9.0 Language Reference
ShowTips Property
See Also

Determines whether ToolTips are shown for the controls on the specified Form object or the specified toolbar object. Available at design time and run time.

Object.ShowTips = lExpr

Return Value

lExpr

Determines whether ToolTips are shown for the specified control. The settings for the ShowTips property are:

Setting Description

True (.T.)

(Default for the toolbar object) ToolTips are displayed when a user places the mouse on a control.

False (.F.)

(Default for the Form object) ToolTips are not displayed when a user places the mouse on a control.

Remarks

Applies To: Form | _SCREEN | ToolBar

You can specify the text that appears in each ToolTip using the ToolTipText property.

The _SCREEN ShowTips property must be set to True (.T.) for Memo Tips to be enabled in Browse windows and Grid controls.

See Also

Other Resources

ToolTipText Property
Properties
Language Reference


ShowWindow Property

Visual FoxPro 9.0 Language Reference
ShowWindow Property
See Also

Specifies whether a form or toolbar is a top-level form or a child form. Available at design time; read-only at run time.

Form.ShowWindow[ = nExpr]

Return Value

nExpr

The settings for the ShowWindow property are:

Setting Description

0

In Screen (Default). The form is a child form that is placed in the main Visual FoxPro window.

1

In Top-Level Form. The form is a child form of the active top-level form, which can be the main Visual FoxPro window or another top-level form. Use this setting if you want the child form to be placed inside the active top-level form.

If nExpr is set to 1 when the top-level form is the main Visual FoxPro window, Visual FoxPro automatically resets nExpr to 0.

2

As Top-Level Form. The form is a top-level form in which child forms can be placed. Note that a top-level form is always modeless, regardless of the WindowType property setting.

Remarks

Applies To: Form | ToolBar

A child form is a form contained within another form. Child forms cannot be moved outside the bounds of their parent form; when minimized, they appear at the bottom of their parent form. If a parent form is minimized, the child forms are also minimized.

A top-level form is an independent, modeless form without a parent form, and is used to create an SDI (single document interface) application or to serve as the parent for other child forms. Top-level forms work at the same level as other Windows applications, and can appear in front of or behind them. Top-level forms appear on the Windows taskbar.

The Desktop property determines the behavior of a child form. If the Desktop property is set to true (.T.) the child form is not constrained to the borders of its parent form and can be moved anywhere on the Windows desktop. The child form does not appear in the Windows taskbar.

See Also

Other Resources

ACTIVATE WINDOW Command
AlwaysOnBottom Property
AlwaysOnTop Property
Desktop Property
Properties
Language Reference


Sizable Property

Visual FoxPro 9.0 Language Reference
Sizable Property
See Also

Specifies whether an object can be sized. Available at design time; read/write at run time.

Object.Sizable = lExpr

Return Value

lExpr

The settings for the Sizable property are as follows:

Setting Description

True (.T.)

(Default) You can size the object.

False (.F.)

You cannot size the object.

Remarks

Applies To: OLE Bound Control | OLE Container Control | ToolBar

For bound and unbound OLE controls, Sizable affects the OLE object that the control contains. If Sizable is set to true (.T.) and you activate the OLE object, you can size it larger or smaller than the OLE control. If the AutoSize property is set to true (.T.), the OLE control automatically resizes to fit the new size of the OLE object when you deactivate it.

Note:
To make a Form sizable, set the BorderStyle property to 3.

See Also

Other Resources

AutoSize Property
BorderStyle Property
Properties
Language Reference


SizeBox Property

Visual FoxPro 9.0 Language Reference
SizeBox Property
See Also

Included for backwards compatibility with the Macintosh. Specifies whether a form has a size box. Available at design time; read/write at run time.

Copy Code
Object.SizeBox = lExpr

Property Values

lExpr

The settings for the SizeBox property are as follows:

Setting Description

True (.T.)

A size box appears in the lower-right corner of the form if the form's BorderStyle property is set to 3 (the default).

False (.F.)

(Default) No size box appears in the form.

Remarks

Applies To: Form

The SizeBox provides a way for users to resize a form using the mouse. The size box can appear in a form only if the form's BorderStyle property is set to 3 (Sizable Border), which is the default for new forms.

See Also

Other Resources

BorderStyle Property
ZoomBox Property


SOM Property

Visual FoxPro 9.0 Language Reference
SOM Property
See Also

Contains an object reference to the XML Schema Object Model (SOM) document (ISchema) after the successful execution of the XMLAdapter LoadXML or Attach method.

XMLAdapter.SOM

Return Value

Object reference. SOM contains an object reference to a SOM document or a null value (.NULL.) when not populated.

Remarks

Applies To: XMLAdapter Class

The SOM provides a navigable set of classes that directly reflect the W3C XML Schema Definition (XSD) language specification. These classes make it possible for you to traverse the elements of an XML Schema document and obtain information about properties and declarations and the relationships between them.

For more information about XML SOM ISchema, see the SOM Reference in Microsoft XML Core Services 4.0 reference on the MSDN Library Web site at http://msdn.microsoft.com/library/.

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
LoadXML Method
Attach Method


Sorted Property

Visual FoxPro 9.0 Language Reference
Sorted Property
See Also

Specifies whether the items in the list portion of a ComboBox or ListBox control are automatically sorted alphabetically. Available at design time and run time.

 [Form.]Control.Sorted[= lExpr]

Return Value

lExpr

The settings for the Sorted property are as follows:

Setting Description

True (.T.)

List items are sorted alphabetically (case-sensitive). Visual FoxPro handles almost all necessary string processing to maintain alphabetic order, including changing the index numbers for items as required when items are added or removed from the list.

False (.F.)

(Default) List items are not sorted alphabetically.

Remarks

Applies To: ComboBox | ListBox

The Sorted property is only available if the RowSourceType property is set to 0 (None) or 1 (Value).

Note that once the items are sort alphabetically, setting the Sorted property to false (.F.) doesn't restore the items to their original order. To restore the original order, set the control's RowSource property to itself, as in the following example:

Copy Code
MyForm.MyCombo1.Rowsource = MyForm.MyCombo1.Rowsource

See Also

Other Resources

AddItem Method
List Property
ListCount Property
ListItemID Property
RemoveItem Method
RowSource Property
RowSourceType Property
Properties
Language Reference


Sparse Property

Visual FoxPro 9.0 Language Reference
Sparse Property
See Also

Specifies whether the CurrentControl property affects all cells or only the active cell in a Column object. Available at design time; read/write at run time.

Column.Sparse [= lExpr]

Return Value

lExpr

The settings for the Sparse property are as follows:

Setting Description

True (.T.)

(Default) Only the Column's active cell uses the CurrentControl property setting to accept and display data. The other cells use the TextBox control if the current control for the cells is not the container object or a command button. The other cells remain empty if the current control for the cells is the container object or a command button.

False (.F.)

All cells in the Column object use the CurrentControl property setting to display data; the active cell accepts data.

Remarks

Applies To: Column

See Also

Other Resources

Bound Property
CurrentControl Property
DynamicCurrentControl Property
Properties
Language Reference


SpecialEffect Property

Visual FoxPro 9.0 Language Reference
SpecialEffect Property
See Also

Specifies different format options for a control. Available at design time and run time.

 [Form.]Control.SpecialEffect = nExpr

Return Value

nExpr

For a PageFrame control, Container object, or Control object, the settings for the SpecialEffect property are as follows:

Setting Description

0

Raised. The control appears to be raised from the form.

1

Sunken. The control appears to be set into the form.

2

Flat.
Note:
For a PageFrame control, SpecialEffect is available only if the Tabs Property is set to false (.F.). Also, the BorderColor property for a PageFrame applies only when nExpr is set to 2 (Flat).

For all other controls, the settings for the SpecialEffect property are as follows:

Setting Description

0

(Default for all controls and objects except the Container object.) 3D. Border of control is raised to simulate a 3-dimensional look.

1

Plain. Control appears without a 3-dimensional border.

2

Hot tracking. Provides mouseover effect for specific controls.
Note:
If the Height property is set to a value too small, the 3D setting has no effect. Hot tracking is supported on the following controls: ListBox, ComboBox, Spinner, TextBox, EditBox, CommandButton, CheckBox, OptionButton. Hot tracking for CheckBox or OptionButton controls is only supported if Style = 2 (graphical). Hot tracking is supported for CommandButtons only when Style <> 1 (invisible). The following table describes hot tracking support.

Control Default Mouseover effect

Listbox

Plain

3D

ComboBox

Plain

3D

Spinner

Plain

3D

TextBox

Plain

3D

EditBox

Plain

3D

CommandButton

Plain in normal position

3D

CheckBox

Plain

None

OptionButton

Plain in normal position

3D

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | ListBox | OptionButton | OptionGroup | PageFrame | Shape | Spinner | TextBox

See Also

Other Resources

BackColor, ForeColor Properties
SelectedBackColor, SelectedForeColor Properties
Properties
Language Reference


SpinnerHighValue, SpinnerLowValue Properties

Visual FoxPro 9.0 Language Reference
SpinnerHighValue, SpinnerLowValue Properties
See Also

Specifies the highest or lowest value that can be entered into a Spinner control by clicking the up and down arrows. Available at design time and run time.

Spinner.SpinnerHighValue[ = nHigh]
Spinner.SpinnerLowValue[ = nLow]

Return Value

nHigh

Specifies the highest value that can be entered into a spinner with the up arrow.
nLow

Specifies the lowest value that can be entered into a spinner with the down arrow.

Remarks

Applies To: Spinner

See Also

Other Resources

KeyboardHighValue, KeyboardLowValue Properties
Properties
Language Reference


SplitBar Property

Visual FoxPro 9.0 Language Reference
SplitBar Property
See Also

Specifies whether the split bar is displayed in a Grid control. Available at design time; read-only at run time.

Grid.SplitBar[ = lExpr]

Return Value

lExpr

One of the following:

lExpr Description

True (.T.)

(Default) The split bar is displayed in a Grid control, allowing you to split the Grid into two separate panes. To synchronize the two halves of the grid, add "This.Refresh" to the Grid AfterRowColChange event.

False (.F.)

The split bar isn't displayed in a Grid control, preventing you from splitting the Grid into separate panes.

Remarks

Applies To: Grid Control

Note that the SplitBar property takes precedence over the Partition property.

See Also

Other Resources

GridLines Property
Partition Property
Properties
Language Reference


StackLevel Property

Visual FoxPro 9.0 Language Reference
StackLevel Property
See Also

Specifies the stack level for the program in which the exception occurs. Read/write at run time.

Exception.StackLevel

Return Value

Numeric data type

Remarks

Applies To: Exception Class

See Also

Other Resources

Properties
Exception Object Properties, Methods, and Events
TRY...CATCH...FINALLY Command
Structured Error Handling


StartMode Property

Visual FoxPro 9.0 Language Reference
StartMode Property
See Also

Contains a numeric value that indicates how an instance of Visual FoxPro was started. Read-only at run time.

ApplicationObject.StartMode

Remarks

Applies To: Application Object | _VFP System Variable

The following table lists the numeric values the StartMode property can contain and how the instance of Visual FoxPro was started.

Value Description

0

A development version of Visual FoxPro was started in an interactive session.

1

Visual FoxPro was started as an application object. For example, the following command creates an instance of Visual FoxPro as an application object:

Copy Code
oMyObject = CREATEOBJECT('VisualFoxPro.Application')

2

Visual FoxPro was started as an out-of-process .exe automation server.

3

Visual FoxPro was started as an in-process .dll automation server.

4

Visual FoxPro was started as a distributable .app or .exe file.

5

Visual FoxPro was started as an in-process .dll automation server for multithreaded use.

For additional information about using Visual FoxPro to create custom automation servers, see Sharing Information and Adding OLE.

See Also

Other Resources

CREATEOBJECT( ) Function
ServerName Property
SYS(2335) – Unattended Server Mode
Properties
Language Reference


StatusBar Property

Visual FoxPro 9.0 Language Reference
StatusBar Property
See Also

Specifies the text displayed in the status bar of an instance of Visual FoxPro. Read/write at run time.

ApplicationObject.StatusBar[ = cMessageText]

Return Value

cMessageText

Specifies the text displayed in the status bar.

Remarks

Applies To: Application Object | _VFP System Variable

See Also

Other Resources

SET MESSAGE Command
Properties
Language Reference


StatusBarText Property

Visual FoxPro 9.0 Language Reference
StatusBarText Property
See Also

Specifies the text that is displayed in the status bar when a control gains focus or when the mouse pointer moves over the control. Read/write at design time and run time.

 [Form.]Control.StatusBarText [= cExpr]

Return Value

cExpr

Character data type. StatusBarText specifies the text that describes the control.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | CommandGroup | Container | Control | EditBox | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OptionButton | OptionGroup | PageFrame | Shape | Spinner | TextBox

Text appears in the status bar only when either the graphical status bar or status section is visible.

Text appears in the status bar for controls that gain focus only when the control gains focus, regardless of how the ShowTips property of the form is set. Text appears in the status bar for controls that never gain focus only when the mouse moves over the control, and the ShowTips property for the form is set to True (.T.). The following controls never gain focus:

  • CommandGroup

  • OptionGroup

  • Container

  • Line

  • Label

  • Image

  • Shape

If the graphical status bar is not visible because SET STATUS BAR is set to OFF, but the status section is visible because SET STATUS is set to ON, the text in the status bar displays in the center of the status section at the bottom of the screen.

See Also

Other Resources

Caption Property
Properties
Language Reference


Stretch Property

Visual FoxPro 9.0 Language Reference
Stretch Property
See Also Example

Specifies how an image is sized to fit inside a control. Available at design time and run time.

Note:
You must set the object's Picture property before setting Stretch; otherwise, the Stretch setting is disregarded. For more information, see Picture Property.

 [Form.]Control.Stretch[= nType]

Return Value

nType

Specifies a numeric value indicating how to size an image to fit a control. The following table contains the values for nType.

nType Description

0

Clip. The image is clipped to fit the control. (Default)

1

Isometric. The image resizes to fit the control while maintaining its original proportions.

2

Stretch. The image resizes to fit the control, but does not maintain its original proportions.

Remarks

Applies To: Image | OLE Bound Control | OLE Container Control

Example

Copy Code
CREATE FORM myForm NOWAIT
oform=_vfp.ActiveForm
oform.ADDOBJECT("image1","image")
this1=oform.image1
this1.picture= HOME()+"\graphics\bitmaps\assorted\beanie.bmp"
this1.stretch=0
this1.height = 50
this1.width = 50

See Also

Other Resources

Autosize Property
Sizable Property
Properties
Language Reference


StrictDateEntry Property

Visual FoxPro 9.0 Language Reference
StrictDateEntry Property
See Also

Specifies whether date and DateTime values must be entered in a specific, strict format in a text box. Available at design time and run time.

Object.StrictDateEntry[ = nValue]

Return Value

nValue

One of the following settings:

Setting Description

0

Loose. Dates and DateTime values can be entered in a loosely formatted manner. The order in which the days, months, and years are entered is determined by the DateFormat property or SET DATE.

Spaces, backslashes, periods, hyphens, and the current date delimiter (specified with the DateMark property or SET MARK ) can be used to delimit date values. If the year is omitted from a date, the current year is used for the date.

A caret (^) can be included as the first character in a date to specify year-month-day date ordering, overriding the order specified by the DateFormat property or SET DATE.

A comma or a space can be used to delimit the date from the time in a DateTime value. When entering just an hour in a DateTime value, the colon can be omitted if the year is included in the date or a comma is used to separate the date from the time.

If an invalid date or DateTime value is entered, an error message is not displayed and the text box value is set to an empty date or DateTime value. You can test for an invalid date in the Valid event.

1

(Default) Strict. Provides compatibility with previous versions of Visual FoxPro.

Dates in date and DateTime values must be entered in a strict 99/99/99 format when CENTURY is set to OFF, or a 99/99/9999 format when CENTURY is set to ON. 99 represents days, months, and years, and 9999 represents years including the century. The order in which the days, months, and years are entered is determined by the DateFormat property or SET DATE.

Remarks

Applies To: TextBox

The following table lists valid date and DateTime values you can enter in a text box when StrictDateEntry is set to 0 (Loose).

Date or DateTime value | Description
12 31 | December 31st of the current year.
12 31 98 14 | December 31st of 1998, 2 P.M.
12 31, 14 | December 31st of the current year, 2 P.M.
12 - 31 - 98, 2p | December 31st of 1998, 2 P.M. Note the extra spaces between the hyphen delimiters.
^98-12-31, 2p | December 31st of 1998, 2 P.M. Caret (^) specifies year-month-day date ordering, overriding the order specified by the DateFormat property or SET DATE.
^/12/31 | December 31st of the current year. Caret (^) specifies year-month-day date ordering, overriding the order specified by the DateFormat property or SET DATE.

See Also

Other Resources

Century Property
DateFormat Property
DateMark Property
Hours Property
Seconds Property
SET CENTURY Command
SET DATE Command
SET MARK TO Command
SET STRICTDATE Command
Properties
Language Reference


Style Property

Visual FoxPro 9.0 Language Reference
Style Property
See Also

Specifies the style for a control. Read/write at design and run time.

[Form.]Control.Style [= nType]

Return Value

nType

Specifies a numerical value that determines the style of a control. For CheckBox and OptionButton controls, the following table lists the values for nType.

nType Description

0

Standard (Default)

1

Graphical.

The button appears like a command button and can contain both graphics and text. When the button contains both, the position of the text and graphic is determined by the PicturePosition property. For more information, see PicturePosition Property.
For ComboBox controls, the following table lists the values for nType.

nType Description

0

Drop-down combo box, which includes a list box and an edit box. (Default)

The user can select from the list box or type characters in the edit box.

2

Drop-down list box.

The user must select items from the list box.
To decide which setting to choose for combo boxes, follow these guidelines:
  • To provide a list of choices and allow the user to type a selection in the edit box, set Style to 0 (drop-down combo box). This setting saves space on a form because the list box closes when the user makes a selection.

  • To display a fixed list of choices that the user can select an item from, set Style to 2 (drop-down list box). The list box closes when the user selects an item.

For CommandButton controls, the following table lists the values for nType.

nType Description

0

Standard (Default)

1

Invisible
For TextBox controls, the following table lists the values for nType.

nType Description

0

Normal (Default)

1

Included for backward compatibility with the FoxPro version 2.x @ ... SAY command. The text box is read-only and cannot receive focus.
For toolbar Separator objects, the following table lists the values for nType.

nType Description

0

Normal (Default).

No vertical or horizontal line appears as the separator object in toolbars.

1

Specifies that a vertical or horizontal line appears as the separator object in toolbars and is visible at run time only.

When the toolbar displays horizontally, the line appears vertically. When the toolbar displays vertically, the line appears horizontally.
Note:
In versions prior to Visual FoxPro 9.0, undocked vertical system and user-defined toolbars did not display horizontal separators. However, horizontal separators now display for vertical undocked toolbars.

For Label and Shape controls, and Container and Control objects, the following table lists the values for nType.

nType Description

0

Normal (Default)

3

Themed

On a Label control, Style controls the color of the text. You can use this setting for captions on group boxes that surround other controls. If the themed label is hosted in a Container, you may also need to set the Container's Style to 3. If Themes is enabled for a label, Visual FoxPro disregards the Enabled and FontCharSet properties. For more information, see Enabled Property and FontCharSet Property.

On a Shape control, Container or Control object, Style controls the color and style of the border. You can use this setting for borders on group boxes that surround other controls. If Themes is turned on for a Shape control, Visual FoxPro disregards the Curvature property. For more information, see Curvature Property.

If an operating system does not support Windows XP Themes, or if Themes is turned off, Visual FoxPro uses the settings for other properties such as SpecialEffect. For more information, see SpecialEffect Property.

4

Themed background only

On Label controls, Style controls the color of the background only. The label's background color is the same color as the label's parent container. You can use this setting primarily for labels on themed pages.

This setting is not supported for Shape controls, Container, and Control objects.

Remarks

Applies To: CheckBox Control | ComboBox Control | CommandButton Control | OptionButton Control | Separator Object | TextBox Control | Label Control | Shape Control | Container Object | Control Object

See Also

Other Resources

Themes Property
SYS(2700) - Enables Windows XP Themes
Properties


TabIndex Property

Visual FoxPro 9.0 Language Reference
TabIndex Property
See Also

Specifies the tab order of controls on a page and the tab order of forms in a form set. Available at design time and run time.

 [Object.]Control.TabIndex[ = nOrder]

Return Value

nOrder

Specifies the tab order for the control.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Label | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | PageFrame | _SCREEN | Spinner | TextBox

For controls on a form, a tab order is assigned based on the order in which the controls are added. Each new control is placed last in the tab order.

For a form in a form set, a tab order is assigned based on the order in which the form was added. The form with nOrder set to 1 is the first form that is active in the form set. When a user tabs from the last control on a form, the first control on the next form in the tab order gets the focus. If a form is not included in a form set, the TabIndex property is ignored.

You can make changes at design time using the Properties window or at run time using code. However, if you change the TabIndex setting of one control or form, be sure to change the TabIndex setting for all controls on the pages or forms in the form set. If you do not designate a tab order for all controls or forms, Microsoft Visual FoxPro assigns the tab order for the remaining controls and forms based on the order in which they are added and changed at run time, which can produce unintended results.

To ignore the tab order of a control or a form, set the TabStop property to false (.F.).

See Also

Other Resources

TabStop Property
Properties
Language Reference


Tables Property

Visual FoxPro 9.0 Language Reference
Tables Property
See Also

Specifies a comma-delimited list of table names, which must have the table names in the exact order you want them to appear in the SQL UPDATE, INSERT, and DELETE commands. When working with this property for regular cursors, use the CURSORSETPROP() and CURSORGETPROP() functions. Read/write.

Note:
You must include this list of table names when using automatic updating for updates to work.

Note:
Setting Tables for CursorAdapter objects overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

CursorAdapter.Tables [= cList]

Return Value

cList

Character data type. The cList parameter specifies a comma-delimited list of table names that displays the table names in the exact order you want them to appear in the SQL UPDATE, INSERT, and DELETE commands. No default setting exists.

Remarks

Applies To: CursorAdapter Class

Tables should not refer to a cursor that was attached to a CursorAdapter object by CursorAttach.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


TabOrientation Property

Visual FoxPro 9.0 Language Reference
TabOrientation Property
See Also

Specifies where the tabs display on a PageFrame control. Read/write at design and run time.

PageFrame.TabOrientation [ = nValue ]

Parameters

nValue

Numeric data type. The following table lists the possible values for nValue.

nValue Setting

0

Top (default)

1

Bottom

2

Left

3

Right

Remarks

Applies To: PageFrame Control

You can usually specify hotkeys in Page captions by including the "\<" characters. Though Visual FoxPro functionally supports hotkeys when TabOrientation is set to left or right positions, the hotkeys do not visually display.

For Page objects, setting the TabOrientation property has no effect unless the font for the page caption is a TrueType or OpenType font. For more information, see Caption Property and FontName Property.

See Also

Other Resources

Properties
Themes Property


Tabs Property

Visual FoxPro 9.0 Language Reference
Tabs Property
See Also

Specifies whether a page frame has tabs. Available at design time and run time.

PageFrame.Tabs[ = lExpr]

Return Value

lExpr

The settings for the Tabs property are as follows:

Setting Description

True (.T.)

(Default) The page frame has tabs.

False (.F.)

The page frame does not have tabs.

Remarks

Applies To: PageFrame

Specify the text on the tabs by setting the Caption property of the page. The width of the tab is increased if the Caption width is greater than the default width of the tab. Shorter captions have no effect on tab width.

See Also

Other Resources

Caption Property
AllowTabs Property
TabStop Property
Properties
Language Reference


TabStop Property

Visual FoxPro 9.0 Language Reference
TabStop Property
See Also

Specifies whether a user can use the TAB key to move the focus to an object. Available at design time and run time.

 [Object.]Control.TabStop[ = lExpr]

Return Value

lExpr

Specifies whether an object is included in the tab order. The settings for the TabStop property are as follows:

Setting Description

True (.T.)

(Default) The control or form is included in the tab order, as determined by the TabIndex property.

False (.F.)

The object is ignored in the tab order. For a control, when a user presses the TAB key, the focus skips a control that has its TabStop property set to false (.F.). For a form, when a user presses the TABkey on the last control on a form and the next form in the tab order has its TabStop property set to false (.F.), the focus moves to the first control on the same form. The focus does not move to the next form in the tab order.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | Container Object | Control Object | EditBox | Form | Grid | ListBox | OLE Bound Control | OLE Container Control | OptionButton | Page | PageFrame | _SCREEN | Spinner | TextBox

If TabStop property is set to false (.F.) for a control or form, the control or form is skipped when the TAB key is used to move through the tab order, but it can still receive the focus when the mouse is used.

Note:
If you want to remove a control within a Column control from the Tab order, set the Enabled property for the Column to False (.F.).

See Also

Other Resources

TabIndex Property
Properties
Language Reference


TabStretch Property

Visual FoxPro 9.0 Language Reference
TabStretch Property
See Also

Specifies the behavior if the tabs do not fit on the page frame. Available at design time and run time. TabStretch is available only if Tabs is set to true (.T.).

PageFrame.TabStretch[ = nSetting]

Return Value

nSetting

The settings for the TabStretch property are as follows

Setting Description

0

Stack. A second row of tabs is created.

1

(Default) Clip. The tabs are clipped as necessary.

Remarks

Applies To: PageFrame

See Also

Other Resources

Tabs Property
TabStyle Property
Properties
Language Reference


TabStyle Property

Visual FoxPro 9.0 Language Reference
TabStyle Property
See Also

Specifies whether the Page tabs in a page frame are justified or non-justified. Available at design time and run time.

PageFrame.TabStyle[ = nStyle]

Return Value

nStyle

One of the following:

nStyle Description

0

(Default) Justified. The width of each page tab is adjusted to accommodate its caption. If necessary, the width of each page tab is increased so the page tabs span the entire width of the PageFrame.

This setting is ignored if the TabStretch property is set to 1, Single Row.

1

Non-justified. The width of each page tab is not adjusted to accommodate its caption. The width of each page tab is not adjusted so that the page tabs span the entire width of the PageFrame.

This setting is ignored if the TabStretch property is set to 1, Single Row.

Remarks

Applies To: PageFrame

See Also

Other Resources

TabStretch Property
AllowTabs Property
Properties
Language Reference


Tag Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Tag Property (Visual FoxPro)
See Also

Stores any extra data needed for your program. Available at design time and run time.

Object.Tag[ = Expr]

Return Value

Expr

Specifies any string.

Remarks

Applies To: CheckBox | Collection Class | ComboBox | CommandButton | CommandGroup | CursorAdapter Class | EditBox | Exception Class | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | ProjectHook Object | ReportListener Object | _SCREEN | Session Object | Shape | Spinner | TextBox | Timer

By default, the Tag property is set to an empty string (""). You can use this property to assign any string to an object without affecting it in any way. Unlike other properties, the value of the Tag property is not used by Visual FoxPro.

See Also

Other Resources

Comment Property
Properties
Language Reference


Text Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Text Property (Visual FoxPro)
See Also

Contains the unformatted text entered in the textbox portion of a control. Not available at design time; read-only at run time.

Object.Text

Remarks

Applies To: ComboBox | EditBox | Spinner | TextBox

Unlike the Value property, the value contained in the Text property is unformatted and is identical to the text entered in the control by the user.

The unformatted text contained in a control's Text property can differ from the control's Value property for the following reasons:

  • The Value property may not be of Character type; it may contain a Date or Numeric value.

  • For an edit box, the Value property may add line feeds to the text entered in the edit box, providing compatibility with previous versions. For this reason, using the Text property is the preferred method for selecting text with the SelStart and SelLength properties.

  • If the Format property for the control uses the R setting, input mask characters are removed from the Value property.

If the Style property for a combo box control is set to 2 (Drop-down List), the Text property contains the empty string because the ComboBox does not have a text box.

See Also

Other Resources

Format Property
SelStart Property
SelLength Property
Style Property
Value Property
Properties
Language Reference


Themes Property

Visual FoxPro 9.0 Language Reference
Themes Property
See Also

Specifies whether Windows XP Themes are enabled or disabled for a control. For forms and toolbars, Themes controls whether child objects are themed. Read/write at design and run time.

Note:
The Themes property for visual classes can affect your existing user interface when using Microsoft Windows XP. You can turn this support off by setting the Themes property at the control, form, or _SCREEN system variable level.

Object.Themes [ = lExpr ]

Parameters

lExpr

Logical data type. The following table lists the settings for lExpr.

lExpr

True (.T.)

Enabled (Default)

False (.F.)

Disabled

Remarks

Applies To: _SCREEN System Variable | CheckBox Control | ComboBox Control | CommandButton Control | CommandGroup Control | Form Object | Grid Control | Image Control | ListBox Control | OptionButton Control | OptionGroup Control | PageFrame Control | Spinner Control | TextBox Control | ToolBar Object

Controls defined using @...GET or @...SAY and similar @... commands are not compatible with Windows XP Themes. Therefore, when running programs written with FoxPro 2.x on Windows XP or later, you should set the _SCREEN.Themes property to False (.F.); otherwise, the controls on the forms disappear. The following example illustrates code that you can use to prevent the controls on the forms from disappearing:

Copy Code
_SCREEN.Themes = .T.

DEFINE WINDOW ThemesDemo AT 0.000, 0.000;
   SIZE 29.000,121.200;
   TITLE "ThemesDemo";
   FONT "MS Sans Serif", 8;
   float;
   CLOSE;
   NOMINIMIZE;
   SYSTEM;
   COLOR RGB(,,,192,192,192)

ACTIVATE WINDOW ThemesDemo

@ 2.500,55.833 GET DemoDB;
   PICTURE "@*C Demo CheckBox";
   SIZE 1.308,21.400;
   DEFAULT 0;
   FONT "Microsoft Sans Serif", 8;
   STYLE "T"
   _SCREEN.activeform.lockscreen = .T.
   _SCREEN.activeform.lockscreen = .F.
READ CYCLE

You can set _SCREEN.Themes property to False (.F.) to disable Themes entirely in Visual FoxPro.

Note:
When you set _SCREEN.Themes property, you do not actually alter the current state of Themes set at the operating system level. You should use SYS(2700) - Enables Windows XP Themes to check the current state of Themes.

When Themes is enabled, Visual FoxPro overrides the SpecialEffect property and uses the default theme except when SpecialEffect is set to a value of 2 (hot tracking). In this scenario, Visual FoxPro preserves hot tracking, which displays special effects when you move the mouse over the CommandButton, graphical OptionButton and CheckBox controls.

For CheckBox controls, Themes supports three-state check boxes.

For Form and ToolBar objects, Themes enables themes for the entire form. To enable themes for a control, you need to set Themes to True (.T.) for both the form and control. For other container controls such as PageFrame, Themes does not control how child objects display themes; it controls only visual aspects such as borders or tabs.

Note:
When Themes are enabled, you should avoid using the CLEAR command for forms because it might cause paint issues with themed controls, such as command buttons, that have mouse hovering effects.

For OptionGroup, CommandGroup, and Image controls, Themes determines whether borders are themed.

Controls such as PageFrame tabs and Grid headers are dynamically drawn by the operating system Themes manager when you move your mouse over them. Therefore, do not position other controls on top of these controls.

For a Grid control, Themes affects the visual appearance of column headers. If themes are enabled for a grid, the BackColor and ForeColor properties of the header are disregarded because they inherit the attributes of the theme. However, the BackColor and ForeColor properties of a Column object display independently from the setting of a grid's Themes property.

For PageFrame controls, Themes determines whether tabs are themed. You might need to make minor modifications to forms that contain PageFrame objects. The Themes property provides a gradient effect on Page objects, so a label, option button, or similar control with text does not appear correctly if the BackStyle property of the control is set to Opaque. You can remedy this situation by setting BackStyle to Transparent.

If your operating system does not support themes, or if Themes is turned off, Visual FoxPro uses the settings controlled by SpecialEffect and other properties.

For more specific details about Windows XP Themes, see the following resources:

  • "Using Windows XP Visual Styles" at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwxp/html/xptheming.asp.

  • "Visual Styles" at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/CommCtls/Userex/themes.asp.

  • "Microsoft Windows XP: What's in It for Developers?" at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwxp/html/winxpintro.asp.

See Also

Other Resources

Properties
SpecialEffect Property
Style Property
SYS(2700) - Enables Windows XP Themes


ThreadID Property

Visual FoxPro 9.0 Language Reference
ThreadID Property
See Also

Returns the Win32 ID of the thread on which the object was called.

_VFP.ThreadID

Remarks

Applies To: Application Object | _VFP

You can use this property especially during debugging. For instance, you can use it to compare the threadID of a received call with the threadID of the object receiving the call.

See Also

Other Resources

Application Object
Properties
Language Reference


TimestampFieldList Property

Visual FoxPro 9.0 Language Reference
TimestampFieldList Property
See Also

Specifies the timestamp fields in the cursor. Read/write at design time and run time.

CursorAdapter.TimestampFieldList [= cExpr]

Return Value

Term | Definition
cExpr | The character expression cExpr is a comma delimited list of timestamp fields in the cursor.

Remarks

Applies To: CursorAdapter Class

Use this property to specify the timestamp fields in a cursor in a CursorAdapter object. If you specify the timestamp fields with this property and the CursorAdapter WhereType property is set to 4, Visual FoxPro includes the timestamp fields in the where condition for UPDATE/DELETE commands for Native, ODBC and ADODB.Command based updates. For XML based updates, the timestamp fields are included in the <before> section of the UpdateGram.

See Also

Reference

CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


TitleBar Property

Visual FoxPro 9.0 Language Reference
TitleBar Property
See Also

Specifies if a title bar appears at the top of a form.

Object.TitleBar[ = nExpression]

Return Value

nExpression

The settings for the TitleBar property are as follows:

Setting Description

0

The title bar is not displayed.

1

(Default) The title bar is displayed.

Remarks

Applies To: Form

If the TitleBar property is set to 0, a title bar is not displayed and the window pop-up menu and the Minimize, Maximize, and Close buttons are not available.

See Also

Other Resources

Closable Property
MaxButton Property
MinButton Property
WhatsThisButton Property
Properties
Language Reference


ToolTipText Property

Visual FoxPro 9.0 Language Reference
ToolTipText Property
See Also

Specifies the text that appears as a ToolTip for a control. You can set the ToolTipText property only if the ShowTips property of the form or toolbar that contains the control is set to True (.T.). Read/write at design and run time.

Control.ToolTipText [= cExpr]

Return Value

cExpr

Specifies the text to use for the ToolTip. The maximum number of characters you can specify for cExpr is 4,095.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | CommandGroup | Container | Control | EditBox | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OptionButton | OptionGroup | PageFrame | Shape | Spinner | TextBox

Visual FoxPro supports wordwrapping for ToolTips.

When you specify the ToolTipText property for contained controls like a Column, Header, or OptionButton, the ToolTipText property of the innermost object takes precedence if the mouse cursor moves over both objects that specify a ToolTip.

For all contained controls except the Grid control, if the contained object does not specify the ToolTipText property, but the container does, Visual FoxPro does not display a ToolTip when the mouse moves over the contained control.

If the objects contained in a Grid control do not specify the ToolTipText property, but the container does, Visual FoxPro displays the ToolTip for the container. For example, if the mouse moves over a column Header object, and the Header does not specify the ToolTipText property, Visual FoxPro displays the ToolTip of the column.

Visual FoxPro displays controls inside a column, for example, a TextBox control, that specify the ToolTipText property only when the control has focus. If the control does not specify a ToolTip when it has focus, the ToolTip of the column is displayed.

Examples

Example 1

The following code sections illustrate how to display ToolTips for contained controls other than a grid. The following example shows how the ToolTips for the CommandButton control and the CommandGroup control display when each control has focus, for example, when you move the mouse pointer over the command button or command group.

Copy Code
CommandGroup1.ToolTipText = "Hi, I'm a CommandGroup."
CommandGroup1.Command1.ToolTipText = "Hi, I'm Command 1."
CommandGroup1.Command2.ToolTipText = "Hi, I'm Command 2."

In the following code section, the ToolTip for Command2 does not display when the control has focus because the ToolTip for the control is not specified.

Copy Code
CommandGroup1.ToolTipText = "Hi, I'm a CommandGroup."
CommandGroup1.Command1.ToolTipText = "Hi, I'm Command 1."

Example 2

The following code sections illustrate how to display ToolTips for controls contained in a grid. The following example shows how the ToolTip for the TextBox control displays when the control has focus, for example, when you move the mouse pointer over the text box.

Copy Code
Grid1.ToolTipText = "Hi, I'm a Grid."
Grid1.Column1.ToolTipText = "Hi, I'm a Column."
Grid1.Column1.Header1.ToolTipText = "Hi, I'm a Header."
Grid1.Column1.Text1.ToolTipText = "Hi! I'm the Textbox!"

In the following code section, the ToolTip for the TextBox control does not display when the control has focus because the ToolTip for the text box is not specified.

Copy Code
Grid1.ToolTipText = "Hi, I'm a Grid."
Grid1.Column1.ToolTipText = "Hi, I'm a Column."
Grid1.Column1.Header1.ToolTipText = "Hi, I'm a Header."

In the following code section, the ToolTip for the column appears when the Header control has focus because the ToolTip for the header is not specified.

Copy Code
Grid1.ToolTipText = "Hi, I'm a Grid."
Grid1.Column1.ToolTipText = "Hi, I'm a Column."

In the following code section, the ToolTip for the grid appears when the Column or Header control has focus because the ToolTip for the column or header is not specified.

Copy Code
Grid1.ToolTipText = "Hi, I'm a Grid."

See Also

Reference

_TOOLTIPTIMEOUT System Variable

Other Resources

ShowTips Property
Properties
Language Reference


Top Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Top Property (Visual FoxPro)
See Also Example

Specifies the distance between the top edge of a control or form and its container object. Available at design time and run time.

Object.Top[ = nValue]

Return Value

nValue

Specifies the distance between the top edge of an object or form and the top edge of its container object. The default container for a form is the main Visual FoxPro window.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | Custom | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | PageFrame | _SCREEN | Shape | Spinner | TextBox | Timer | ToolBar

The Top property specifies how far from the object's zero position the object is located. For example, if a form is contained within the Visual FoxPro main window, the zero position is immediately below the system menu, or if a toolbar is docked to the top of the main window, immediately below the toolbar.

Use the Left and Top and the Height and Width properties for operations based on an object's external dimensions, such as moving or resizing.

Note:
The Top property is read-only when it applies to a control contained in a Column object.

The unit of measurement used by the Top property is determined by the control's ScaleMode property setting.

Example

The following example demonstrates how the Top property is used to position controls on a form. The AddObject method is used to add a Line control and three command buttons to a form. The Top property specifies the vertical placement of each control on the form.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the window pop-up menu

frmMyForm.AddObject('shpLine','Line')  && Add a Line control to the form
frmMyForm.AddObject('cmdCmndBtn1','cmdMyCmndBtn1')  && Up Cmnd button
frmMyForm.AddObject('cmdCmndBtn2','cmdMyCmndBtn2')  && Down Cmnd button
frmMyForm.AddObject('cmdCmndBtn3','cmdMyCmndBtn3')  && Quit Cmnd button

frmMyForm.shpLine.Visible = .T.  && Make Line control visible
frmMyForm.shpLine.Top = 20  && Specify Line control row
frmMyForm.shpLine.Left = 125  && Specify Line control column

frmMyForm.cmdCmndBtn1.Visible =.T.  && Up Command button visible
frmMyForm.cmdCmndBtn2.Visible =.T.  && Down Command button visible
frmMyForm.cmdCmndBtn3.Visible =.T.  && Quit Command button visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmndBtn1 AS COMMANDBUTTON  && Create Command button
   Caption = 'Slant \<Up'  && Caption on the Command button
   Left = 50  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='/'  && Slant up
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn2 AS CommandButton  && Create Command button
   Caption = 'Slant \<Down'  && Caption on the Command button
   Left = 200  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='\'  && Slant down
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn3 AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 150  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

See Also

Other Resources

Left Property
Height Property
Move Method
ScaleMode Property
Width Property
Properties
Language Reference


TopIndex Property

Visual FoxPro 9.0 Language Reference
TopIndex Property
See Also

Specifies the item that appears in the top-most position in a list.

Control.TopIndex[ = nIndex]

Return Value

nIndex

Specifies the index of the item that appears in the top-most position in a list.

Remarks

Applies To: ComboBox | ListBox

The index of an item reflects its position in the list, which is relative to other items in the list and can change.

Combo box controls are read-only all the time and list box controls are read-only at design time and read/write at run time.

See Also

Other Resources

AddItem Method
Clear Method
List Property
ListCount Property
MultiSelect Property
NewItemID Property
RemoveItem Method
Selected Property
TopItemID Property
Properties
Language Reference


TopItemID Property

Visual FoxPro 9.0 Language Reference
TopItemID Property
See Also

Specifies the item ID of the item that appears in the top-most position in a list.

Control.TopIItemID[ = nItemID]

Return Value

nItemID

Specifies the item ID of the item that appears in the top-most position in a list.

Remarks

Applies To: ComboBox | ListBox

The default setting for the TopItemID property is 1, or the first item in the list.

Combo box controls are read-only all the time and list box controls are read-only at design time and read/write at run time.

See Also

Other Resources

AddItem Method
Clear Method
List Property
ListCount Property
MultiSelect Property
NewItemID Property
RemoveItem Method
Selected Property
TopIndex Property
Properties
Language Reference


TwoPassProcess Property

Visual FoxPro 9.0
TwoPassProcess Property
See Also

Specifies whether this report run requires multiple passes through the data scope to produce output.

ReportListener.TwoPassProcess

Return Value

Logical data type.

The default value is False (.F.).

Remarks

Applies To: ReportListener Object.

When the TwoPassProcess property is .T., a report executes as a two-pass report. The extra prepass provides the means for the Engine and ReportListener to determine the value of _PAGETOTAL for display in report expressions during the subsequent output pass.

The Visual FoxPro Report System components opt to perform a two-pass report when they find an expression using the _PAGETOTAL system value in the report, or when you explicitly set this property's value to .T.. If TwoPassProcess is .F. but the engine finds a _PAGETOTAL expression in the report, the engine sets the property value to .T. for the duration of the report.

Tip:
By setting TwoPassProcess to .T. before a report run, you can force the report to perform a two-pass process, even if you have not used _PAGETOTAL in any expressions in the report. You do not need to add a hidden expression containing _PAGETOTAL to your report layout, as you did in previous versions of Visual FoxPro.

TwoPassProcess works together with the CurrentPass property to give you information about the status of a report run while it executes. The value of CurrentPass changes depending on the value of TwoPassProcess. See CurrentPass Property for more information. For additional information about how the native Report System components handle these and other reporting options at the beginning and end of a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

See Also

Reference

CurrentPass Property
_PAGETOTAL System Variable

Other Resources

Properties (Visual FoxPro)
Language Reference (Visual FoxPro)


Type Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Type Property (Visual FoxPro)
See Also

Contain a character indicating the file type of a file in a project. Available at design time and run time.

Object.Type

Remarks

Applies To: File Object

The following table list the values the Type property can contain and the corresponding file types.

Value | FoxPro.H Constant | File Type and Extension
d | FILETYPE_DATABASE | Database, .dbc
D | FILETYPE_FREETABLE | Free table, .dbf
Q | FILETYPE_QUERY | Query, .qpr
K | FILETYPE_FORM | Form, .scx
R | FILETYPE_REPORT | Report, .frx
B | FILETYPE_LABEL | Label, .lbx
V | FILETYPE_CLASSLIB | Visual class Library, .vcx
P | FILETYPE_PROGRAM | Program, .prg
L | FILETYPE_APILIB | Visual FoxPro dynamic link library, .fll
Z | FILETYPE_APPLICATION | Application, .app
M | FILETYPE_MENU | Menu, .mnx
T | FILETYPE_TEXT | Text file, varies
x | FILETYPE_OTHER | Other, varies

These values are stored in the Type field of the project's .pjx file.

See Also

Other Resources

FileClass Property
FileClassLibrary Property
Properties
Language Reference


TypeLibCLSID Property

Visual FoxPro 9.0 Language Reference
TypeLibCLSID Property
See Also

The registry CLSID (Class Identifier) for a type library created for server classes in a project. Read-only.

Object.TypeLibCLSID

Remarks

Applies To: Project Object

A type library is created and registered when you build a .dll or .exe from a project that contains server classes. Type libraries have a .tlb extension, and are placed in the same directory as the .dll or .exe that is built.

See Also

Other Resources

CLSID Property
ProgID Property
TypeLibDesc Property
TypeLibName Property
Properties
Language Reference


TypeLibDesc Property

Visual FoxPro 9.0 Language Reference
TypeLibDesc Property
See Also

The description for a type library created for server classes in a project.

Object.TypeLibDesc[ = cTypeLibraryDescription]

Return Value

cTypeLibraryDescription

Specifies the description for a type library created for server classes in a project. By default, contains the name of the project containing the server classes appended with "Type Library."

Remarks

Applies To: Project Object

A type library is created and registered when you build a .dll or .exe from a project that contains server classes. Type libraries have a .tlb extension, and are placed in the same directory as the .dll or .exe that is built.

This property corresponds to the Typelib description item on the Servers tab of the Project Information dialog box.

See Also

Other Resources

CLSID Property
ProgID Property
TypeLibCLSID Property
TypeLibName Property
Properties
Language Reference


TypeLibName Property

Visual FoxPro 9.0 Language Reference
TypeLibName Property
See Also

The name of the type library created for server classes in a project. Read-only.

Object.TypeLibName

Remarks

Applies To: Project Object

A type library is created and registered when you build a .dll or .exe from a project that contains server classes. Type libraries have a .tlb extension, and are placed in the same directory as the .dll or .exe that is built.

See Also

Other Resources

CLSID Property
Name Property
ProgID Property
TypeLibCLSID Property
TypeLibDesc Property
Properties
Language Reference


Unicode Property

Visual FoxPro 9.0 Language Reference
Unicode Property
See Also

Specifies how the XMLAdapter LoadXML, Attach, AddTableSchema, and ToXML methods and the XMLTable ToCursor, ChangesToCursor, and ApplyDiffGram methods handle character strings.

XMLField Unicode specifies whether to place a Unicode string into the field.

Note:
If XMLField IsBinary property is True (.T.), and XMLField Unicode is True (.T.), Visual FoxPro generates the appropriate message.

Read/write at design time and run time.

Object.Unicode [= lValue]

Parameters

lValue

Specifies a logical value that determines the how strings are handled depending on the method being executed or are stored. The following table describes the values and behaviors of Unicode depending on the method being called or object.

Method or Object lValue

XMLAdapter LoadXML and Attach methods

True (.T.): Doubles length of a given string and assigns result to the XMLField MaxLength property.

False (.F.): Assigns length of a given string to the XMLField MaxLength property.

When LoadXML and Attach is called, XMLField Unicode is set to the value of XMLAdapter Unicode for Character and Memo fields.

XMLAdapter AddTableSchema method

True (.T.): Assigns value of XMLAdapter Unicode (True, or .T.) to XMLField Unicode.

False (.F.): Assigns value of XMLAdapter Unicode (False, or .F.) to XMLField Unicode.

XMLAdapter ToXML method

True (.T.): Divides length of a given character field by 2 and assigns the result to xsd:maxLength.

False (.F.): Assigns length of a given character field to xsd:maxLength.

When using XMLAdapter ToXML, the content of the field is converted from Unicode to the code page of the XML, and the embedded null symbol (CHR(0)+CHR(0)) is considered a string terminator. For Unicode strings stored in Character fields, if the string length is shorter than the field size, the null terminator is required. To terminate the string, use CHR(0)+CHR(0).

XMLTable ToCursor, ChangesToCursor, and ApplyDiffgram methods

True (.T.): Creates field with NOCPTRANS flag regardless of XMLField NoCpTrans property and stores a Unicode string in the field. For more information, see SET NOCPTRANS Command.

Note:
If the XMLField MaxLength property is an odd number, Visual FoxPro generates the appropriate message.

False (.F.): Creates the field as a regular Character or Memo field.

XMLField object

True (.T.): Stores a Unicode string in the field.

False (.F.): Stores a non-Unicode string in the field.

Remarks

Applies To: XMLAdapter Class | XMLField Class

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
XMLField Object Properties, Methods, and Events
LoadXML Method
Attach Method
ToCursor Method
ChangesToCursor Method
ApplyDiffGram Method
AddTableSchema Method


UpdatableFieldList Property

Visual FoxPro 9.0 Language Reference
UpdatableFieldList Property
See Also

Specifies a comma-delimited list of fields in the view and includes fields from the cursor. When working with this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions. Read/write.

Note:
You must include a list of field names for updates to work when using automatic updating.

Note:
Setting UpdatableFieldList for CursorAdapter objects overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

CursorAdapter.UpdatableFieldList [= cList]

Return Value

cList

Character data type. The cList parameter specifies a comma-delimited list of fields in the view and includes fields from the cursor.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


UpdateCmd Property

Visual FoxPro 9.0 Language Reference
UpdateCmd Property
See Also

Specifies the command to use when updating tables. Read/write at design time and run time.

CursorAdapter.UpdateCmd [ = cCommand ]

Return Value

cCommand

Character data type. The following table lists the possible values for cCommand.

cCommand Description

Character string or expression

Specifies a valid command string for the data source in the UpdateCmdDataSource property.

Empty string ("")

The CursorAdapter object generates a SQL UPDATE command automatically if the CursorAdapter AllowUpdate property is set to True (.T.).

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


UpdateCmdDataSource Property

Visual FoxPro 9.0 Language Reference
UpdateCmdDataSource Property
See Also

Specifies the data source used by the UpdateCmd property. Read/write at design time and run time.

CursorAdapter.UpdateCmdDataSource [= cDataSource]

Return Value

cDataSource

Character data type. The cDataSource parameter specifies the data source used by the UpdateCmd property.

Remarks

Applies To: CursorAdapter Class

The following table describes behaviors that apply to UpdateCmdDataSource depending on the value of UpdateCmdDataSourceType.

UpdateCmdDataSourceType UpdateCmdDataSource behavior

Empty ("")

UpdateCmdDataSource is disregarded. Visual FoxPro uses the data source in the CursorAdapter DataSource property.

However, if the cursor associated with the CursorAdapter object is based on an ActiveX Data Object (ADO) RecordSet, Visual FoxPro uses the functionality of the ADO RecordSet to update a record. To use this functionality, make sure the CursorAdapter DataSourceType property is set to "ADO".

"ADO"

UpdateCmdDataSource must be set to a valid ADO Command object. The ActiveConnection property of the ADO Command object must be set to a valid and open ADO Connection object.

Visual FoxPro sets the CommandText property of the ADO Command object to the value of the CursorAdapter UpdateCmd property. Visual FoxPro parses the command for parameters, creates parameter values if found, and sets them in the Command object.

The update operation occurs as:

Copy Code
CursorAdapter.UpdateCmdDataSource.Execute()

For more information about using an ADO RecordSet, automatic updating, and generating SQL commands automatically, see Data Access Management Using CursorAdapters.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


UpdateCmdDataSourceType Property

Visual FoxPro 9.0 Language Reference
UpdateCmdDataSourceType Property
See Also

Specifies the data source type for the data source used by the UpdateCmdDataSource property. Read/write at design time and run time.

CursorAdapter.UpdateCmdDataSourceType [= cDataSourceType]

Return Value

cDataSourceType

Character data type. The cDataSourceType parameter specifies the data source type of the data source in the UpdateCmdDataSource property.

Remarks

Applies To: CursorAdapter Class

If UpdateCmdDataSourceType is empty ("") or null (.NULL.), Visual FoxPro uses the data source in the CursorAdapter DataSource property.

To generate an XML UpdateGram, you must explicitly set the value of UpdateCmdDataSourceType to "XML".

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
UpdateGram Property


UpdateCmdRefreshCmd Property

Visual FoxPro 9.0 Language Reference
UpdateCmdRefreshCmd Property
See Also

Specifies the command to automatically refresh the record after an Update command is executed. Read/write at design time and run time.

CursorAdapter.UpdateCmdRefreshCmd[ = cCommand]

Return Value

Term Definition

cCommand

Character data type. The following table lists the possible values for cCommand.

cCommand | Description
Character string or expression | Specifies a valid refresh command for the data source.
Empty string ("") | The CursorAdapter object generates an refresh command automatically.

Remarks

Applies To: CursorAdapter Class

Note:
The AllowUpdate Property must be set to True (.T.) to permit update operations to a data source.

For more information about how Visual FoxPro updates CursorAdapters, see Data Access Management Using CursorAdapters.

See Also

Reference

InsertCmdRefreshCmd Property
InsertCmdRefreshFieldList Property
InsertCmdRefreshKeyFieldList Property
UpdateCmdRefreshFieldList Property
UpdateCmdRefreshKeyFieldList Property


UpdateCmdRefreshFieldList Property

Visual FoxPro 9.0 Language Reference
UpdateCmdRefreshFieldList Property
See Also

Specifies the fields in the cursor to refresh after an Update command is executed. Read/write at design time and run time.

CursorAdapter.UpdateCmdRefreshFieldList[ = cExpr]

Return Value

Term | Definition
cExpr | The character expression cExpr is a comma delimited list of the fields in the data source that are refreshed.

Remarks

Applies To: CursorAdapter Class

The UpdateCmdRefreshFieldList property determines which fields in the cursor are automatically refreshed after an Update command is issued.

Note:
The AllowUpdate Property must be set to True (.T.) to permit update operations to a data source.

For more information about how Visual FoxPro updates CursorAdapters, see Data Access Management Using CursorAdapters.

See Also

Reference

InsertCmdRefreshCmd Property
InsertCmdRefreshFieldList Property
InsertCmdRefreshKeyFieldList Property
UpdateCmdRefreshCmd Property
UpdateCmdRefreshKeyFieldList Property


UpdateCmdRefreshKeyFieldList Property

Visual FoxPro 9.0 Language Reference
UpdateCmdRefreshKeyFieldList Property
See Also

Specifies the key fields in the cursor used to retrieve a record after an Update command is executed. Read/write at design time and run time.

CursorAdapter.UpdateCmdRefreshKeyFieldList[ = cExpr]

Return Value

Term | Definition
cExpr | The character expression cExpr is a comma delimited list of the key fields in the cursor that are used to retrieve a record from the data source.

Remarks

Applies To: CursorAdapter Class

Note:
The AllowUpdate Property must be set to True (.T.) to permit insert operations to a data source.

For more information about how Visual FoxPro updates CursorAdapters, see Data Access Management Using CursorAdapters.

See Also

Reference

InsertCmdRefreshCmd Property
InsertCmdRefreshKeyFieldList Property
InsertCmdRefreshFieldList Property
UpdateCmdRefreshCmd Property
UpdateCmdRefreshFieldList Property


UpdateGram Property

Visual FoxPro 9.0 Language Reference
UpdateGram Property
See Also

Contains the XML UpdateGram generated only under the following conditions:

  • Visual FoxPro executes insert, update, or delete commands.

  • UpdateCmdDataSourceType, InsertCmdDataSourceType, and DeleteCmdDataSourceType properties are set to "XML".

Read–only at design time and run time.

CursorAdapter.UpdateGram

Return Value

Character data type. UpdateGram contains an XML UpdateGram.

Remarks

Applies To: CursorAdapter Class

Even though a CursorAdapter object can generate the XML UpdateGram, you must implement the actual update operation using the appropriate protocols, such as SQL XML through HTTP, SQL XML OLEDB, or XML Web service to .NET.

For more information about automatic updating and XML, see Data Access Management Using CursorAdapters.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


UpdateGramSchemaLocation Property

Visual FoxPro 9.0 Language Reference
UpdateGramSchemaLocation Property
See Also

Specifies the mapping schema name and location passed to the XMLUPDATEGRAM( ) function. Read/write at design time and run time.

Note:
UpdateGramSchemaLocation applies only when CursorAdapter DataSourceType is "XML". When specified, UpdateGramSchemaLocation is passed to the SchemaLocation parameter in XMLUPDATEGRAM( ). Visual FoxPro does not support creating mapping schemas; therefore, you must supply one.

CursorAdapter.UpdateGramSchemaLocation [= cName]

Return Value

cName

Character data type. The cName parameter specifies a mapping schema name and location, and the default value is an empty string ("").

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events


UpdateNameList Property

Visual FoxPro 9.0 Language Reference
UpdateNameList Property
See Also

Specifies a comma-delimited list consisting of pairs of local and full remote field names. Each pair of names consists of a local field name followed by the full remote field name. The full remote field name appears as <remote table name>.<remote field name> where <remote table name> matches the name from the Tables property. Read/write.

Note:
Setting UpdateNameList for CursorAdapter objects overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

Note:
You must set UpdateNameList, which you can also use to specify valid Visual FoxPro names for fields in the cursor that have invalid Visual FoxPro field names.

When working with this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions.

CursorAdapter.UpdateNameList [= cList]

Return Value

cList

Character data type. The cList parameter specifies a comma-delimited list consisting of pairs of local and full remote field names.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function
Tables Property


UpdateType Property

Visual FoxPro 9.0 Language Reference
UpdateType Property
See Also

Specifies what to do with old data when performing updates. When working with this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions. Read/write.

Note:
Setting UpdateType for CursorAdapter objects overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

CursorAdapter.UpdateType [= nValue]

Return Value

nValue

Numeric data type. The following table lists the values for nValue.

nValue Description

1

Update old data with new data. (Default)

2

Delete old data and insert new data.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


UseCodePage Property

Visual FoxPro 9.0
UseCodePage Property
See Also

Specifies whether the XMLAdapter object should use special logic to determine what code page should be used for encoding or decoding data. Read/write at design time and run time.

XMLAdapter.UseCodePage = lValue

Return Value

lValue

Logical data type. The following table lists values for lValue.

lValue Description

False (.F.)

(Default) See the table below for the effect of setting the UseCodePage property to False (.F.).

True (.T.)

See the table below for the effect of setting the UseCodePage property to True (.T.).

Remarks

Applies to: XMLAdapter Class

When the XMLAdapter UseCodePage property is True (.T.), the behavior of the ToCursor, ChangesToCursor, and ApplyDiffgram methods change as follows:

  • The XMLTable CodePage (or the XMLAdapter CodePage if the codepage is zero) is used as the code page for the new cursor unless the nCodePage parameter is passed.

  • When a field is populated, the XMLField CodePage (if zero, then the cursor’s code page) is used to decode data from Unicode. The XMLField CodePage does not have to be supported by Visual FoxPro. For example, code page 65001 can be used to decode data using UTF-8 code page.

The following table shows how the UseCodePage, RespectCursorCP, and UTF8Encoded property settings affect the ToXML method.

RespectCursorCP | UTF8Encoded | UseCodePage=.F. | UseCodePage=.T.
False (.F.) | False (.F.) | The Windows 1252 code page is used as the encoding attribute for the XML document. Character data is translated to the current default code page except for fields marked as NOCPTRANS. Unicode data is translated using code page 1252. | Identical to UseCodePage = .F.
True (.T.) | False (.F.) | The cursor’s code page is used as the encoding attribute for the XML document. Character data is not translated and raw data from the table is used. Unicode data is translated using cursor’s code page. | Identical to UseCodePage = .F. However, an error is generated if the XMLField CodePage is greater than zero and does not match cursor’s code page.
False (.F.) | True (.T.) | The UTF-8 code page is used as the encoding attribute for the XML document. Character data is translated to the current default code page except for fields marked as NOCPTRANS, and no additional character translation to the UTF-8 code page occurs. Unicode data is translated using the UTF-8 code page. | Identical to UseCodePage = .F.
True (.T.) | True (.T.) | The UTF-8 code page is used as the encoding attribute for the XML document. Character data is translated to the current default code page except for fields marked as NOCPTRANS. These fields are translated to UTF-8 using code page specified with the SYS(3005) - Set Locale ID. Unicode data is translated using UTF-8 code page. | The UTF-8 code page is used as the encoding attribute for the XML document. Raw character data from the table is translated to the UTF-8 code page using either the cursor’s code page or the XMLField CodePage if it is greater than zero. Unicode data is translated using the UTF-8 code page.

See Also

Reference

XMLAdapter Class
CodePage Property
RespectCursorCP Property
UTF8Encoded Property

Other Resources

Properties (Visual FoxPro)


UseCursorSchema Property

Visual FoxPro 9.0 Language Reference
UseCursorSchema Property
See Also

Specifies a default setting to use for the lUseCursorSchema parameter in the CursorFill Method. Available at design time and run time.

CursorAdapter.UseCursorSchema [ = lValue]

Return Value

lValue

Logical data type. The following table specifies the values for lValue.

lValue Description

False (.F.)

(Default) A logical False (.F.) is used by default for the lUseCursorschema parameter in the CursorFill method.

CursorFill creates the cursor using the data types as normally determined by Visual FoxPro according to the CursorAdapter DataSourceType Property.

True (.T.)

A logical True (.T.) is used by default for the lUseCursorschema parameter in the CursorFill method.

Remarks

Applies To: CursorAdapter Class.

The value specified by this property is used by the CursorFill method when the lUseCursorSchema parameter is omitted in the method. This property is ignored if the lUseCursorSchema parameter is included in the CursorFill method.

See Also

Reference

CursorFill Method
NoData Property


UseDeDataSource Property

Visual FoxPro 9.0 Language Reference
UseDeDataSource Property
See Also

Determines whether to use the data source of the data environment container as the data source for the CursorAdapter object. The data source of the associated data environment is specified by the DataEnvironment DataSource property. Read/write at design time and run time.

Note:
UseDeDataSource applies only when the cursor adapter exists in the data environment.

CursorAdapter.UseDeDataSource [ = lValue ]

Return Value

lValue

Logical data type. The following table lists the settings for lValue.

lValue Description

True (.T.)

Use the data source of the associated data environment as the cursor adapter data source.

Setting UseDeDataSource to True (.T.) is not appropriate if the data environment contains multiple CursorAdapter objects using ActiveX Data Object (ADO) data sources. Multiple cursor adapters cannot share a single ADO RecordSet. You should set each cursor adapter's DataSource and DataSourceType properties individually.

If the cursor adapter is a member of the data environment, the DataEnvironment DataSource and DataSourceType properties override the relevant CursorAdapter properties.

False (.F.)

Do not use the data source of the associated data environment as the cursor adapter data source.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
DataEnvironment Object Properties, Methods, and Events


UseMemoSize Property

Visual FoxPro 9.0 Language Reference
UseMemoSize Property
See Also

Specifies the minimum size in bytes for returning result columns in memo fields. For example, if the width of a column result exceeds the value of UseMemoSize, the column result is stored in a memo field. Read/write.

Note:
Setting UseMemoSize applies only to CursorAdapter objects with ODBC or ADO data sources and overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

When working with this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions.

CursorAdapter.UseMemoSize [= nValue]

Return Value

nValue

Numeric data type. The nValue parameter has a default value of 255 bytes and can vary from 1 byte to 255 bytes.

Remarks

Applies To: CursorAdapter Class

This property applies primarily for remote views and setting it does not affect local views. However, you can preset this property for local views that will be upsized.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


UseTransactions Property

Visual FoxPro 9.0 Language Reference
UseTransactions Property
See Also

Specifies if the CursorAdapter uses transactions when sending Insert, Update or Delete commands through ADO or ODBC. Read/write at design time and run time.

CursorAdapter.UseTransactions[ = lExpr]

Return Value

lExpr

The settings for the UseTransactions property are:

Setting Description

True (.T.)

(Default) The CursorAdapter uses transactions when sending Insert, Update or Delete commands through ADO or ODBC.

False (.F.)

The CursorAdapter doesn't use transactions when sending Insert, Update or Delete commands through ADO or ODBC.

Remarks

Applies To: CursorAdapter Class.

The CursorAdapter object relies on ADO and ODBC APIs to manage transactions. If you ignore API recommendations and send specific transaction commands directly to an ADO or ODBC backend, you may want to set the UseTransactions property to False (.F.) to prevent undesirable transaction interaction.

See Also

Reference

BEGIN TRANSACTION Command
END TRANSACTION Command
ROLLBACK Command


UserValue Property

Visual FoxPro 9.0 Language Reference
UserValue Property
See Also

Specifies the value passed by the THROW statement used to generate an exception. You can use this value as an object reference. Read/write at run time.

Exception.UserValue

Return Value

Variant data type

Remarks

Applies To: Exception Class

See Also

Other Resources

Properties
Exception Object Properties, Methods, and Events
TRY...CATCH...FINALLY Command
Structured Error Handling


UTF8Encoded Property

Visual FoxPro 9.0 Language Reference
UTF8Encoded Property
See Also

Specifies whether to set encoding to Unicode Transformation Format-8 (UTF-8). UTF8Encoded works in conjunction with the RespectCursorCP property.

UTF8Encoded applies only when executing the XMLAdapter ToXML method, which creates XML consistent with its setting.

XMLAdapter.UTF8Encoded [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

Does not set encoding to UTF-8. (Default)

True (.T.)

Sets encoding to UTF-8.

Remarks

Applies To: XMLAdapter Class

The default encoding for XML is UTF-8, whereas for Visual FoxPro, the default encoding is Windows-1252. When you want to output data to XML, you can preserve UTF-8 encoding by setting encoding to UTF-8 and instructing Visual FoxPro to translate double-byte characters to the proper UTF-8 encoding sequence.

If you have a group of characters representing Korean or Chinese text, you can convert those characters to double-byte character sets (DBCS) to view them in Visual FoxPro. You can then reconvert them to UTF-8 when transmitting them across the Web as XML so that other systems can correctly display the data.

For example, the following table describes how RespectCursorCP and UTF8Encoded interact with each other.

RespectCursorCP | UTF8Encoded | Conversion performed
False | False | Windows-1252 (Default)
True | False | Set output encoding attribute to the code page of the cursor.
False | True | Set output encoding attribute to UTF-8. No character translation occurs.
True | True | Set output encoding attribute to UTF-8. Translate character data to UTF-8.
True | False | Set output encoding attribute to the code page of the cursor.

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
RespectCursorCP Property
ToXML Method


Value Property

Visual FoxPro 9.0 Language Reference
Value Property
See Also

Specifies the current state of a control. Available at design time and run time.

[Form.]Control.Value [= nSetting]

Return Value

nSetting

Specifies a setting that indicates the current state of the control. For CommandGroup, ComboBox, EditBox, ListBox, OptionGroup, and Spinner controls, the Value property contains the character string or numeric value that is currently selected in the control. For a TextBox control, the Value property contains the character string or numeric, date, datetime, currency, or logical value that is currently selected in the control. The default value is a character string. For a CheckBox control, the following table lists the settings for nSetting:

nSetting Description

0

Cleared. (Default)

1

Selected.

2

Mixed-value. This setting is only available in code.
For an OptionButton control, the following table lists the settings for nSetting:

nSetting Description

0

Not selected. (Default)

1

Selected.

Remarks

Applies To: CheckBox | ComboBox | CommandGroup | EditBox | Grid | ListBox | OptionButton | OptionGroup | Spinner | TextBox

For the Grid control, the Value property is available only when the Grid control has focus.

The Value method does not support the Assign method.

You can use the Value property of a CommandGroup or OptionGroup control to determine which button in the group triggers an event. The Value property is set to an integer that indicates which button in the group caused the event.

The Value property changes behavior when a control source is set for a control. When a control source is set, the Value property setting of a control is the data type of the variable or field referenced by the ControlSource property. If the data type is not valid for the given control, Visual FoxPro generates an error.

The following table lists valid data types.

Control | Data Types allowed
CheckBox | Integer, Logical, Numeric
ComboBox | Character, Integer, Numeric
CommandGroup | Character, Integer, Numeric
EditBox | Character, Memo
Grid | Character, Numeric
ListBox | Character, Integer, Numeric
OptionButton | Integer, Logical, Numeric
OptionGroup | Character, Integer, Numeric
Spinner | Currency, Integer, Numeric
TextBox | Any data type

See Also

Other Resources

Bound Property
ListIndex Property
Properties
Language Reference


Version Property

Visual FoxPro 9.0 Language Reference
Version Property
See Also

Returns the version number of an instance of Visual FoxPro as a character string. Read-only at run time.

ApplicationObject.Version

Remarks

Applies To: Application Object | _VFP System Variable

See Also

Other Resources

VERSION( ) Function


VersionComments Property

Visual FoxPro 9.0 Language Reference
VersionComments Property
See Also

The comments for a project.

Object.VersionComments[ = cComments]

Return Value

cComments

Specifies the comments for a project. The default value is the empty string.

Remarks

Applies To: Project Object

The VersionComments property corresponds to the value of the Comments item in the EXE Version dialog box.

See Also

Other Resources

AGETFILEVERSION( ) Function
VersionCompany Property
VersionCopyright Property
VersionDescription Property
VersionLanguage Property
VersionNumber Property
VersionProduct Property
VersionTrademarks Property
Properties
Language Reference


VersionCompany Property

Visual FoxPro 9.0 Language Reference
VersionCompany Property
See Also

The company name information for a project.

Object.VersionCompany[ = cCompanyName]

Return Value

cCompanyName

Specifies the company name information for a project. The default value is the empty string.

Remarks

Applies To: Project Object

The VersionCompany property corresponds to the value of the Company Name item in the EXE Version dialog box.

See Also

Other Resources

AGETFILEVERSION( ) Function
VersionComments Property
VersionCopyright Property
VersionDescription Property
VersionLanguage Property
VersionNumber Property
VersionProduct Property
VersionTrademarks Property
Properties
Language Reference


VersionCopyright Property

Visual FoxPro 9.0 Language Reference
VersionCopyright Property
See Also

The copyright information for a project.

Object.VersionCopyright[ = cCopyRight]

Return Value

cCopyRight

Specifies the copyright information for a project. The default value is the empty string.

Remarks

Applies To: Project Object

The VersionCopyRight property corresponds to the value of the LegalCopyright item in the EXE Version dialog box.

See Also

Other Resources

AGETFILEVERSION( ) Function
VersionComments Property
VersionCompany Property
VersionDescription Property
VersionLanguage Property
VersionNumber Property
VersionProduct Property
VersionTrademarks Property
Properties
Language Reference


VersionDescription Property

Visual FoxPro 9.0 Language Reference
VersionDescription Property
See Also

The description for a project.

Object.VersionDescription[ = cDescription]

Return Value

cDescription

Specifies the description for a project. The default value is the empty string.

Remarks

Applies To: Project Object

The VersionDescription property corresponds to the value of the File Description item in the EXE Version dialog box.

See Also

Other Resources

AGETFILEVERSION( ) Function
VersionComments Property
VersionCompany Property
VersionCopyright Property
VersionLanguage Property
VersionNumber Property
VersionProduct Property
VersionTrademarks Property
Properties
Language Reference


VersionLanguage Property

Visual FoxPro 9.0 Language Reference
VersionLanguage Property
See Also

The language information for a project.

Object.VersionLanguage[ = nLanguage]

Return Value

nLanguage

Specifies the language ID for a project. FOXPRO.H contains a listing of the values for the primary and sub-language IDs that can be combined to create a valid language ID. For example, the following code sets the VersionLanguage to United States English (0x09 specifies English, 0x0400 specifies United States English) for the current project:
Copy Code
Application.ActiveProject.VersionLanguage = 0x09 + 0x0400

Remarks

Applies To: Project Object

The VersionLanguage property corresponds to the value of the Language ID item in the EXE Version dialog box.

See Also

Other Resources

AGETFILEVERSION( ) Function
VersionComments Property
VersionCompany Property
VersionCopyright Property
VersionDescription Property
VersionNumber Property
VersionProduct Property
VersionTrademarks Property
Properties
Language Reference


VersionNumber Property

Visual FoxPro 9.0 Language Reference
VersionNumber Property
See Also

The build number for a project.

Object.VersionNumber[ = cBuildNumber]

Return Value

cBuildNumber

Specifies a build number for a project. The standard format for a project build number is "MMMM.mmmm.bbbb" where MMMM is the major build number, mmmm is the minor build number, and bbbb is the build number. Separate each component of a project build number with a period (.). Each build number can be zero to four digits (numbers). Do not use letters in the build number. You can specify ".." for cBuildNumber to reset both the minor build number and the build number to zero. If the AutoIncrement property is set to true (.T.) and you build an executable (.exe) or dynamic link library (.dll) from the project, the build number has leading zeros removed from last portion (".bbbb") of the build number. The default value is the empty string.

Remarks

Applies To: Project Object

The VersionNumber property corresponds to the values of Version Number items in the EXE Version dialog box.

See Also

Other Resources

AGETFILEVERSION( ) Function
VersionComments Property
VersionCompany Property
VersionCopyright Property
VersionDescription Property
VersionLanguage Property
VersionProduct Property
VersionTrademarks Property
Properties
Language Reference


VersionProduct Property

Visual FoxPro 9.0 Language Reference
VersionProduct Property
See Also

The product name information for a project.

Object.VersionProduct[ = cProductName]

Return Value

cProductName

Specifies the product name information for a project. The default value is the empty string.

Remarks

Applies To: Project Object

The VersionProduct property corresponds to the value of the Product Name item in the EXE Version dialog box.

See Also

Other Resources

AGETFILEVERSION( ) Function
VersionComments Property
VersionCompany Property
VersionCopyright Property
VersionDescription Property
VersionLanguage Property
VersionNumber Property
VersionTrademarks Property
Properties
Language Reference


VersionTrademarks Property

Visual FoxPro 9.0 Language Reference
VersionTrademarks Property
See Also

The trademarks information for a project.

Object.VersionTrademarks[ = cTradeMarks]

Return Value

cTradeMarks

Specifies the trademarks information for a project. The default value is the empty string.

Remarks

Applies To: Project Object

The VersionTrademarks property corresponds to the value of the Legal Trademarks item in the EXE Version dialog box.

See Also

Other Resources

AGETFILEVERSION( ) Function
VersionComments Property
VersionCompany Property
VersionCopyright Property
VersionDescription Property
VersionLanguage Property
VersionNumber Property
VersionProduct Property
Properties
Language Reference


VFPXMLProgID Property

Visual FoxPro 9.0 Language Reference
VFPXMLProgID Property
See Also Example

References a COM component you can use to override the internal functionality of the CURSORTOXML( ), XMLTOCURSOR( ), and XMLUPDATEGRAM( ) functions.

You can create the COM component in Visual FoxPro, Visual C/C++, Visual Basic or any developer tool that creates COM components with the ability to implement interfaces.

_VFP.VFPXMLProgID [=cValue]

Return Value

cValue

Specifies the ProgID of the COM component class whose functions override the functionality of the listed Visual FoxPro XML functions. Setting cValue to the default empty string ("") value resets use to the internal implementations of these functions.

Remarks

The class you use must implement the IVFPXML interface from the Visual FoxPro type library. To provide methods to overwrite, open the Object Browser from the Tools menu. From the Microsoft Visual FoxPro Type Library, drag the IVFPXML interface to a program (.prg) file.

Example

The following example creates a classes that replace the CURSORTOXML( ), XMLTOCURSOR( ), and XMLUPDATEGRAM( ) functions. Create a project for these classes and add custom XML function handler code to the three methods. VesrNum represents the version number of Visual FoxPro.

Copy Code
DEFINE CLASS MyXMLClass AS session OLEPUBLIC
   IMPLEMENTS IVFPXMLVerNum IN "VisualFoxPro.Application.VerNum"

   * Replaces CURSORTOXML( ).
   PROCEDURE IVFPXMLVerNum_CursorToXML(bstrAlias AS STRING, ;
      nOutputFormat AS Number, nFlags AS Number, ;
      nRecords AS Number, bstrOutputFile AS STRING, ;
      bstrSchema AS STRING, bstrSchemaLocation AS STRING, ;
      bstrNameSpace AS STRING, pVFP AS VARIANT) AS VARIANT ;
      HELPSTRING "Converts from a Cursor to XML"
      * Add user code here.
   ENDPROC

   * Replaces XMLTOCURSOR( ).
   PROCEDURE IVFPXMLVerNum_XMLToCursor(pvarXMLSource AS VARIANT, ;
      bstrCursorName AS STRING, nFlags AS Number, pVFP AS VARIANT) ;
      AS Number HELPSTRING "Converts from XML to a Cursor"
      * Add user code here.
   ENDPROC

   * Replaces XMLUPDATEGRAM( ).
   PROCEDURE IVFPXMLVerNum_XMLUpdateGramVerNum( nFlags AS Number, ;
      bstrCursorList AS STRING, pVFP AS VARIANT , ;
      bstrSchemaLocation AS STRING ) AS VARIANT;
      HELPSTRING "Generates an XML UpdateGram"
      * Add user code here.
   ENDPROC

   * Included for backward compatibility with previous
   * versions of this interface.
   PROCEDURE IVFPXMLVerNum_XMLUpdateGram(nFlags AS Number, ;
      bstrCursorList AS STRING, pVFP AS VARIANT) AS VARIANT;
      HELPSTRING "Generates an XML UpdateGram"
      * Add user code here.
   ENDPROC

ENDDEFINE

When you are finished, build the project into a dynamic-link library (.dll) or executable (.exe) file. Set the VFPXMLProgID property to the correct ProgID for your class. For example, if your project name is MyXMLProj, you would set VFPXMLProgID using the following line of code:

Copy Code
_VFP.VFPXMLProgID = "MyXMLProj.MyXMLClass"

With _VFP VFPXMLProgID set to a specific ProgID, calls to CURSORTOXML( ), XMLTOCURSOR( ), or XMLUPDATEGRAM( ) are redirected to the corresponding method in the class specified by that ProgID. A reference to _VFP is also passed to the method, providing a way to access and manipulate data cursors and memory variables. For more information, see _VFP System Variable Properties, Methods, and Events.

Prior to Visual FoxPro 8.0, XMLUPDATEGRAM( ) did not have the cSchemaLocation parameter; therefore, the interface was different. Visual Foxpro supports both interfaces and looks for the current interface first. If unsuccessful, Visual FoxPro then looks for the earlier interface.

The following is a sample class definition for the earlier interface without the cSchemaLocation parameter:

Copy Code
DEFINE CLASS MyXMLClass AS session OLEPUBLIC
   IMPLEMENTS IVFPXML IN "VisualFoxPro.Application.8"

   * Replaces CURSORTOXML( ).
   PROCEDURE IVFPXML_CursorToXML(bstrAlias AS STRING, ;
      nOutputFormat AS Number, nFlags AS Number, ;
      nRecords AS Number, bstrOutputFile AS STRING, ;
      bstrSchema AS STRING, bstrSchemaLocation AS STRING, ;
      bstrNameSpace AS STRING, pVFP AS VARIANT) AS VARIANT ;
      HELPSTRING "Converts from a Cursor to XML"
      * Add user code here.
   ENDPROC

   * Replaces XMLTOCURSOR( ).
   PROCEDURE IVFPXML_XMLToCursor(pvarXMLSource AS VARIANT, ;
      bstrCursorName AS STRING, nFlags AS Number, pVFP AS VARIANT) ;
      AS Number HELPSTRING "Converts from XML to a Cursor"
      * Add user code here.
   ENDPROC

   * Replaces XMLUPDATEGRAM( ).
   PROCEDURE IVFPXML_XMLUpdateGram(nFlags AS Number, ;
      bstrCursorList AS STRING, pVFP AS VARIANT) AS VARIANT;
      HELPSTRING "Generates an XML UpdateGram"
      * Add user code here.
   ENDPROC

ENDDEFINE

See Also

Other Resources

Properties
_VFP System Variable
How to: View Type Library Information
XML Functions
CURSORTOXML( ) Function
XMLTOCURSOR( ) Function
XMLUPDATEGRAM( ) Function


View Property

Visual FoxPro 9.0 Language Reference
View Property
See Also

Specifies the type of view for a Grid control. Available at design time; read/write at run time.

Grid.View[ = nType]

Return Value

nType

If the panes are not split (the Partition property is set to 0), the settings for the View property are:

Setting Description

0

Browse

1

Change
If the panes are split, the settings for the View property are:

Setting Description

0

Browse (left pane), Browse (right pane)

1

Browse (left pane), Change (right pane)

2

Change (left pane), Browse (right pane)

3

Change (left pane), Change (right pane)

Remarks

Applies To: Grid

See Also

Other Resources

Panel Property
PanelLink Property
Partition Property
Properties
Language Reference


ViewPortHeight Property

Visual FoxPro 9.0 Language Reference
ViewPortHeight Property
See Also

Contains the viewport height for a form. Read-only at design time and run time.

Object.ViewPortHeight

Remarks

Applies To: Form Object

The viewport is the rectangular area of a form displayed in the form's container. The form container controls the size of the viewport. If you change the size of a form's container, the viewport also changes size.

The unit of measurement for the viewport height is determined by the form's ScaleMode property setting – pixels (the default) or foxels.

See Also

Other Resources

ScaleMode Property
SetViewPort Method
ViewPortLeft Property
ViewPortTop Property
ViewPortWidth Property
Properties
Language Reference


ViewPortLeft Property

Visual FoxPro 9.0 Language Reference
ViewPortLeft Property
See Also

Contains the left coordinate of the form that is visible in the viewport. Read-only at design time and run time.

Object.ViewPortLeft

Remarks

Applies To: Form Object

The viewport is the rectangular area of a form displayed in the form's container. The form container controls the size of the viewport. If you change the size of a form's container, the viewport also changes size.

The unit of measurement for the left coordinate of the form is determined by the form's ScaleMode property setting – pixels (the default) or foxels.

See Also

Other Resources

ScaleMode Property
SetViewPort Method
ViewPortHeight Property
ViewPortTop Property
ViewPortWidth Property
Properties
Language Reference


ViewPortTop Property

Visual FoxPro 9.0 Language Reference
ViewPortTop Property
See Also

Contains the top coordinate of the form that is visible in the viewport. Read-only at design time and run time.

Object.ViewPortTop

Remarks

Applies To: Form Object

The viewport is the rectangular area of a form displayed in the form's container. The form container controls the size of the viewport. If you change the size of a form's container, the viewport also changes size.

The unit of measurement for the top coordinate of the form is determined by the form's ScaleMode property setting – pixels (the default) or foxels.

See Also

Other Resources

ScaleMode Property
SetViewPort Method
ViewPortHeight Property
ViewPortLeft Property
ViewPortWidth Property
Properties
Language Reference


ViewPortWidth Property

Visual FoxPro 9.0 Language Reference
ViewPortWidth Property
See Also

Contains the viewport width for a form. Read-only at design time and run time.

Object.ViewPortWidth

Remarks

Applies To: Form Object

The viewport is the rectangular area of a form displayed in the form's container. The form container controls the size of the viewport. If you change the size of a form's container, the viewport also changes size.

The unit of measurement for the viewport width is determined by the form's ScaleMode property setting – pixels (the default) or foxels.

See Also

Other Resources

ScaleMode Property
SetViewPort Method
ViewPortHeight Property
ViewPortLeft Property
ViewPortTop Property
Properties
Language Reference


Visible Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Visible Property (Visual FoxPro)
See Also Example

Specifies whether an object is visible or hidden. Read/write at design time and run time.

Object.Visible [= lExpr]

Return Value

lExpr

Specifies a value that determines whether an object is visible or hidden. The following table lists the values for lExpr.

lExpr Description

True (.T.)

The object is visible. (Default in the Form Designer)

False (.F.)

The object is hidden. (Default in program code)

Note:
Even when the object is hidden, you can still access it in code.

Tip:
To hide an object at startup, set the Visible property to False (.F.) at design time. If you set the Visible property in code, you can hide an object and display it at run time in response to a particular event.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | FormSet | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | PageFrame | Project Object | _SCREEN | Separator | Shape | Spinner | TextBox | ToolBar

For Form objects, when Visible is set to False (.F.), the form is hidden and the most recently active form set, form, or other object becomes active. When Visible is set to True (.T.), the form becomes visible; however, the form does not become active. To make a form visible and active in the same step, use the Show method. For more information, see Show Method.

Note:
A form in a FormSet object does not display when its Visible property is set to False (.F.) even if the form set's Visible property is set to True (.T.). However, all forms in the form set are hidden if the form set's Visible property is set to False (.F.).

Setting a form's Visible property to True (.T.) does not affect the form's Order property setting.

For Separator objects, the Visible property determines whether a space appears as the separator when its Style property is set to 0 (Normal - do not display a line). For example, when the separator's Visible property is set to True (.T.), and its Style property is set to 0, a space appears instead of the separator. When the separator's Visible property is set to False (.F.), no space appears, regardless of the setting of its Style property.

In versions prior to Visual FoxPro 5.0, setting the Visible property for the _SCREEN system variable has no effect.

Example

The following example displays a form with a line control and three command buttons based on three separate custom CommandButton classes. Pressing the "Slope Up" or "Slope Down" buttons change the slope of the line and pressing the Quit button ends the program. The Visible property is used to hide and display controls at appropriate times.

The following lines of code create a form and disable the form's Close button so the custom Quit button can be used to exit the program.

Copy Code
frmMyForm = CREATEOBJECT('Form')
frmMyForm.Closable = .F.

The following lines of code use the AddObject method to add a Line control and three custom command buttons to the form.

Copy Code
frmMyForm.AddObject('shpLine','Line')
frmMyForm.AddObject('cmdCmndBtn1','cmdMyCmndBtn1')
frmMyForm.AddObject('cmdCmndBtn2','cmdMyCmndBtn2')
frmMyForm.AddObject('cmdCmndBtn3','cmdMyCmndBtn3')

The Visible property is set to True (.T.) for the line control and the command buttons to display them on the form. The Top and Left properties specify the distance between the line control and the form.

Copy Code
frmMyForm.shpLine.Visible = .T.
frmMyForm.cmdCmndBtn1.Visible =.T.
frmMyForm.cmdCmndBtn2.Visible =.T.
frmMyForm.cmdCmndBtn3.Visible =.T.
frmMyForm.shpLine.Top = 20
frmMyForm.shpLine.Left = 125

The Show method displays the form and the READ EVENTS command begins event processing.

Copy Code
frmMyForm.SHOW
READ EVENTS

The DEFINE CLASS command defines three custom CommandButton classes and contains settings for the appropriate properties. In the Click event, the Visible property hides the line control so that its slope direction can be changed and displays the line control after its slant direction is changed. The CLEAR EVENTS command in the Click event of the third command button stops event processing and closes the form.

Copy Code
DEFINE CLASS cmdMyCmndBtn1 AS COMMANDBUTTON
   Caption = 'Slope \<Up'
   Left = 50
   Top = 100
   Height = 25
   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.
      ThisForm.shpLine.LineSlant ='/'
      ThisForm.shpLine.Visible = .T.
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn2 AS CommandButton
   Caption = 'Slope \<Down'
   Left = 200
   Top = 100
   Height = 25
   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.
      ThisForm.shpLine.LineSlant ='\'
      ThisForm.shpLine.Visible = .T.
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn3 AS CommandButton
   Caption = '\<Quit'
   Cancel = .T.
   Left = 125
   Top = 150
   Height = 25
   PROCEDURE Click
      CLEAR EVENTS
ENDDEFINE

See Also

Other Resources

AddObject Method
Click Event
Properties


VisualEffect Property

Visual FoxPro 9.0 Language Reference
VisualEffect Property
See Also

Makes it possible for you to apply SpecialEffect behaviors programmatically to Visual FoxPro command buttons. Available only at run time.

CommandButton.VisualEffect[ = nValue]

Return Value

nValue

Specifies the format setting of a control according to the following table:

Setting Description

0

None. Existing visual effect is unchanged.

1

Raised. Gives raised visual effect similar to mouse hover with SpecialEffect=2 (Hot Tracking).

2

Depressed. Gives sunken visual effect similar to having the mouse held down on the command button.

Remarks

Applies To: CommandButton

Because the Raised setting of VisualEffect (1) conflicts with the 3D SpecialEffect setting, the VisualEffect value of 1 is ignored if SpecialEffect = 0.

See Also

Other Resources

SpecialEffect Property
OLEDropEffects Property
Create Coolbar Control Effects
Properties
Language Reference


VScrollSmallChange Property

Visual FoxPro 9.0 Language Reference
VScrollSmallChange Property
See Also

Specifies the increment a form scrolls vertically when you click on a scroll arrow. Available at design time and run time.

Object.VScrollSmallChange[ = nExpression]

Return Value

nExpression

Specifies the increment for vertical scrolling. The unit of measure is determined by the Scalemode property setting. The default increment is 10 pixels when the Scalemode property is set to 3 - Pixels.

Remarks

Applies To: Form

See Also

Other Resources

HScrollSmallChange Property
ScaleMode Property
ScrollBars Property
Properties
Language Reference


WhatsThisButton Property

Visual FoxPro 9.0 Language Reference
WhatsThisButton Property
See Also

Specifies whether the What's This button appears in a form's title bar. Read-only at run time.

Form.WhatsThisButton[ = lExpr]

Return Value

lExpr

One of the following:

Setting Description

True (.T.)

Turns display of the What's This button on.

False (.F.)

(Default) Turns display of the What's This button off.

Remarks

Applies To: Form

The What's This button is not displayed in the form's title bar if the WhatsThisButton property is set to true (.T.) and any of the following are true:

  • The form's WhatsThisHelp property is set to false (.F).

  • The form's BorderStyle property is set to 0 (None).

  • The form's MinButton property is set to true (.T.).

  • The form's MaxButton property is set to true (.T.).

See Also

Other Resources

BorderStyle Property
MaxButton Property
MinButton Property
ShowWhatsThis Method
TitleBar Property
WhatsThisMode Method
WhatsThisHelp Property
WhatsThisHelpID Property
Properties
Language Reference


WhatsThisHelp Property

Visual FoxPro 9.0 Language Reference
WhatsThisHelp Property
See Also

Specifies whether context-sensitive Help uses What's This help or the Windows help file specified with SET HELP.

Form.WhatsThisHelp[ = lExpr]

Return Value

lExpr

One of the following:

Setting Description

True (.T.)

The form uses one of the three What's This Help techniques to open the Windows help file specified with SET HELP and display the topic specified with the WhatsThisHelpID property.

False (.F.)

(Default) The form uses the F1 key to open the Windows help file specified with SET HELP. The Help topic specified with the HelpContextID property is displayed.

Remarks

Applies To: Form

The three What's This Help techniques are as follows:

  1. A What's This button is displayed in the form title bar. When this button is clicked, the mouse pointer changes to an arrow with a question mark. The Help topic displayed when a control is clicked is specified with the WhatsThisHelpID property for the control.

  2. The WhatsThisMode method is invoked, changing the mouse pointer changes to an arrow with a question mark. The Help topic displayed when a control is clicked is specified with the WhatsThisHelpID property for the control.

  3. The ShowWhatsThis method is invoked for a control. The Help topic displayed is specified with the control's WhatsThisHelpID property.

If Help is set to an HTML Help file, for example, HelpFileName.chm, the Help topic is displayed in the HTML Help viewer. If Help is set to a Windows Help file, for example, HelpFileName.hlp, the Help topic is displayed in a small popup window next to the control.

See Also

Other Resources

HelpContextID Property
SET HELP Command
ShowWhatsThis Method
WhatsThisButton Property
WhatsThisMode Method
WhatsThisHelpID Property
Properties
Language Reference


WhatsThisHelpID Property

Visual FoxPro 9.0 Language Reference
WhatsThisHelpID Property
See Also

Specifies the context ID corresponding to a What's This Help topic or an HTML Help topic for an object. Available at design time and run time.

Object.WhatsThisHelpID[ = nContextID]

Return Value

nContextID

Specifies the context ID number of the corresponding topic in a Help file. The following table lists the values for nContextID and action performed when clicking the What's This Help button in the title bar.

nContextID Description

Negative

Displays the What's This Help popup window with the text, "No Help topic is associated with this item" or the main Help page of an HTML Help file, if available. (Default, –1)

Zero

Searches the object hierarchy for the first object with a positive WhatsThisHelpID value. If found, Visual FoxPro displays the corresponding What's This Help topic or HTML Help topic, if available.

If not found, Visual FoxPro does not display a What's This Help topic or an HTML Help topic.

Positive

Displays the What's This Help topic or HTML Help topic matching the specified nContextID.

If no Help topic matches the specified nContextID, Visual FoxPro displays the What's This Help popup window with the text, "No Help topic is associated with this item" or main Help page of an HTML Help file, if available.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Shape | Spinner | TextBox | Timer | ToolBar

See Also

Other Resources

HelpContextID Property
SET HELP Command
ShowWhatsThis Method
WhatsThisButton Property
WhatsThisHelp Property
WhatsThisMode Method
Properties
Language Reference


WhereType Property

Visual FoxPro 9.0 Language Reference
WhereType Property
See Also

Specifies the fields that the WHERE clause consists of when used for updating tables. When working with this property for regular cursors, use the CURSORSETPROP( ) and CURSORGETPROP( ) functions. Read/write.

Note:
Setting WhereType for CursorAdapter objects overrides the property setting of a cursor when attached to a CursorAdapter object. That is, changing the settings on the cursor using CURSORSETPROP() has no effect.

CursorAdapter.WhereType [= nValue]

Return Value

nValue

Numeric data type. The following table lists the values for nValue.

nValue Description

1 or DB_KEY (from FOXPRO.H)

Includes only the primary fields specified by the KeyFieldList property.

2 or DB_KEYANDUPDATABLE (from FOXPRO.H)

Includes the primary fields specified by the KeyFieldList property and any updatable fields.

3 or DB_KEYANDMODIFIED (from FOXPRO.H)

Includes the primary fields specified by the KeyFieldList property and other modified fields.

4 or DB_KEYANDTIMESTAMP (from FOXPRO.H)

Includes the primary fields specified by the KeyFieldList property and a comparison of time stamps.

Remarks

Applies To: CursorAdapter Class

For forced update and delete operations, CursorAdapter uses the value of 1 for the CursorAdapter WhereType property regardless of the actual setting. Otherwise, CursorAdapter respects user settings for WhereType.

See Also

Other Resources

Properties
CursorAdapter Object Properties, Methods, and Events
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function
KeyFieldList Property


Width Property

Visual FoxPro 9.0 Language Reference
Width Property
See Also

Specifies the width of an object. Available at design time and run time.

 [Object.]Width[ = nWidth]

Return Value

nWidth

Specifies the width of an object.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | Custom | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | PageFrame | _SCREEN | Shape | Spinner | TextBox | Timer | ToolBar

Use the Height, Width, Left, and Top properties for operations or calculations based on an object's total area, such as sizing or moving the object.

For forms and controls, the values for this property changes as the object is sized by the user or in code. Maximum settings of this property for all objects are system-dependent.

For forms, the Width property specifies the external width of the form, excluding the borders. If the ScrollBars property is set to enable scroll bars, Width does not include space taken up by the scroll bar when it appears. . In Visual FoxPro, the maximum width of a form has been increased to approximately 32,000 pixels.

For controls, the Width property is measured from the center of the control's border so that controls with different border widths align correctly.

Note:
The Width property is read-only when it applies to a control contained in a Column object.

The Width property is determined in the unit of measurement specified by the ScaleMode property setting.

See Also

Other Resources

Height Property
Left Property
Move Method
ScaleMode Property
Top Property
Properties
Language Reference


WindowState Property (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
WindowState Property (Visual FoxPro)
See Also

Specifies whether a form window is displayed as a maximized, minimized, or normal window at run time. Available at design time and run time.

 [Object.]WindowState[ = nState]

Return Value

nState

The settings for the WindowState property are as follows:

Setting Description

0

Normal

1

Minimized (minimized to an icon). If the main Visual FoxPro window is minimized when you exit Visual FoxPro, the main Visual FoxPro window will not display before exiting. If your application displays a dialog before exiting, be sure to set _SCREEN.WindowState to 0 before displaying the dialog.

2

Maximized (enlarged to fill the screen)

Remarks

Applies To: Form | _SCREEN

See Also

Other Resources

Height Property
Left Property
Top Property
Width Property
Properties
Language Reference


WindowType Property

Visual FoxPro 9.0 Language Reference
WindowType Property
See Also

Specifies how a form set or form behaves when it is shown or run with DO FORM. Available at design time and run time.

Object.WindowType[ = nType]

Return Value

nType

For a form set, the settings for the WindowType property are as follows:

Setting Description

0

Modeless.

1

Modal. No other forms can become active and the menu can be active. All forms in the form set are active.

2

Read. The form set behaves as if it were activated by the READ command. Execution stops on the Show method or DO FORM command. When the Form is deactivated, execution continues. (Included for backward compatibility, and available only for Forms converted from previous versions of FoxPro.)

3

Read Modal. The form set behaves as if it were activated by a READ command's MODAL clause. Program execution stops at the Show method or the DO FORM command. Any forms specified in the WindowList property are available, but other forms and the menu are not available. (Included for backward compatibility, and available only for forms converted from previous versions of FoxPro.)
For a form, the settings for the WindowType property are as follows:

Setting Description

0

Modeless.

1

Modal. No other forms can become active and the menu is inactive. All forms in the form set are active.

Remarks

Applies To: Form | FormSet | _SCREEN

You cannot change the WindowType setting once the window has been displayed.

The Show method takes a parameter that can override the WindowType setting.

Note:
The WindowType setting of a form set overrides the individual WindowType settings of the forms it contains. For example, if the WindowType property for a form set is set to 0, all the forms contained in it are modeless, regardless of their individual WindowType property settings.

See Also

Other Resources

DO FORM Command
READ Command
READ EVENTS Command
Show Method
WindowList Property
Properties
Language Reference


WordWrap Property

Visual FoxPro 9.0 Language Reference
WordWrap Property
See Also

Specifies whether text displays on a single line or multiple lines within a control or object. Available at design time and run time. There are two versions of the syntax.

[Form.]Control.WordWrap [= lExpr]
Grid.Column.Header.WordWrap [= lExpr]

Return Value

lExpr

Specifies a Logical value that indicates whether text displays on multiple lines in the control or object. The following table lists values of lExpr for CheckBox, CommandButton, Label, and OptionButton controls.

lExpr Description

False (.F.)

Text displays on a single line and appears truncated if the text does not fit the control. (Default)

True (.T.)

Text displays on multiple lines to fit within the control.

Note:
When the WordWrap property is True (.T.) for check boxes and option buttons, the PicturePosition property determines the position of images on the controls. For more information, see PicturePosition Property.
The following table lists values of lExpr for Header objects in grid columns.

lExpr Description

False (.F.)

Text displays on a single line and appears truncated if text does not fit the header. (Default)

True (.T.)

Text displays on multiple lines and wraps to fit the column boundary. However, the text appears truncated if you do not adjust the header height to fit the text.

Tip:
To change the height of the header, change the Grid HeaderHeight property. For more information, see HeaderHeight Property.

Remarks

Applies To: CheckBox | CommandButton | Header | Label | OptionButton

For CheckBox, CommandButton, Label, and OptionButton controls, WordWrap specifies whether text specified by the control's Caption property displays on a single line or on multiple lines so they fit the control. For check boxes, command buttons, and option buttons, the text always appears centered vertically in the control. For labels, text appears at the top.

Tip:
The control's AutoSize property determines whether the control resizes automatically to fit its contents. To resize the control automatically, set the control's AutoSize property to True (.T.). Otherwise, you might need to adjust the height of the control to accommodate multiple lines of text.

For check boxes, option buttons, and headers, the Alignment property determines the text alignment. For more information, see Alignment Property.

For column Header objects in grids, WordWrap specifies whether the text specified by the header's Caption property wraps to fit the column boundary.

Note:
The WordWrap property only respects the CHR(10) (carriage return) and CHR(13)+CHR(10) (linefeed and carriage return) characters to manually wrap text.

See Also

Other Resources

Properties
How to: Select, Move, and Resize Form Controls
Caption Property
Language Reference


WrapCharInCDATA Property

Visual FoxPro 9.0 Language Reference
WrapCharInCDATA Property
See Also

Specifies whether to wrap character fields in CDATA sections.

WrapCharInCDATA applies only when executing the following methods:

  • LoadXML

  • Attach

  • AddTableSchema

XMLAdapter.WrapCharInCDATA [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

Does not wrap character fields in CDATA sections. (Default)

True (.T.)

Wraps character fields in CDATA sections.

Remarks

Applies To: XMLAdapter Class

The XMLAdapter LoadXML, Attach, and AddTableSchema methods use WrapCharInCDATA to set the XMLField WrapInCDATA property for Character fields.

See Also

Reference

WrapCharInCDATA Property

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
XMLField Class
WrapInCDATA Property


WrapInCDATA Property

Visual FoxPro 9.0 Language Reference
WrapInCDATA Property
See Also

Specifies whether the field is wrapped in CDATA sections.

WrapInCDATA applies only to Character, Character (Binary), Memo, or Memo (Binary) fields and when executing the XMLAdapter ToXML method, which creates XML consistent with its setting.

XMLField.WrapInCDATA [= lValue]

Return Value

Logical data type. The value of WrapInCDATA defaults to the value of XMLAdapter WrapMemoInCDATA or WrapCharInCDATA properties as appropriate. The following table lists values for lValue.

lValue | Description
True (.T.) | The field is wrapped in CDATA sections.
False (.F.) | The field is not wrapped in CDATA sections.

Remarks

Applies To: XMLField Class

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events
Visual FoxPro Data and Field Types
ToXML Method
WrapMemoInCDATA Property
WrapCharInCDATA Property


WrapMemoInCDATA Property

Visual FoxPro 9.0 Language Reference
WrapMemoInCDATA Property
See Also

Specifies whether to wrap Memo fields in CDATA sections.

WrapMemoInCDATA applies only when executing the following XMLAdapter methods:

  • LoadXML

  • Attach

  • AddTableSchema

XMLAdapter.WrapMemoInCDATA [= lValue]

Return Value

lValue

Logical data type. The following table lists the values for lValue.

lValue Description

False (.F.)

Does not wrap Memo fields in CDATA sections. (Default)

True (.T.)

Wraps Memo fields in CDATA sections.

Remarks

Applies To: XMLAdapter Class

The XMLAdapter LoadXML, Attach, and AddTableSchema methods use WrapMemoInCDATA to set the XMLField WrapInCDATA property for Memo fields.

See Also

Reference

WrapMemoInCDATA Property

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
XMLField Class
WrapInCDATA Property


XMLAdapter Property

Visual FoxPro 9.0 Language Reference
XMLAdapter Property
See Also

Contains an object reference to an XMLAdapter object only when that XMLAdapter Tables collection contains the XMLTable object.

XMLTable.XMLAdapter

Return Value

Object reference. XMLAdapter contains one of the following:

  • An object reference to an XMLAdapter object whose Tables collection contains the XMLTable object

  • Null (.NULL.) under the following conditions:

    • The XMLTable object is created by itself, contained neither by an XMLAdapter object nor as the child of another XMLTable object.

    • When the XMLTable object is contained by another XMLTable object. The ParentTable property contains an object reference to the parent XMLTable object.

Remarks

Applies To: XMLTable Class

See Also

Other Resources

Properties
XMLTable Object Properties, Methods, and Events
XMLAdapter Class
Tables Collection (XMLAdapter)
ParentTable Property


XMLConstraints Property

Visual FoxPro 9.0 Language Reference
XMLConstraints Property
See Also

Contains an object reference to the ISchemaItemCollection object after the successful execution of the XMLAdapter LoadXML or Attach method.

If the LoadXML and Attach methods analyze the XML schema, they set XMLConstraints to the appropriate value, although Visual FoxPro neither analyzes nor enforces any constraints declared in the XMLConstraints collection.

Object.XMLConstraints

Return Value

Object reference. XMLConstraints contains an object reference to the ISchemaItemCollection object or a null value (.NULL.) when not populated.

Remarks

Applies To: XMLAdapter Class | XMLTable Class

XML schema can contain constraints, which are associated with the schema. XMLConstraints provides you with access to constraints defined within the DataSet element.

Visual FoxPro does not include any functionality in XMLAdapter that uses these constraints, but it provides access so that you can obtain constraints information and use them in your application if needed.

In the following XML example, note the location of the Primary Key constraint:

Copy Code
<?xml version="1.0" encoding="Windows-1252"?>
<DataSet xmlns="http://tempuri.org/">
<xs:schema id="NewDataSet" xmlns="" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
<xs:element name="NewDataSet" msdata:IsDataSet="true">
   <xs:complexType>
      <xs:choice maxOccurs="unbounded">
         <xs:element name="Tbl2">
            <xs:complexType>
               <xs:sequence>
                  <xs:element name="source"/>
                  <xs:element name="num" type="xs:int"/>
                  <xs:element name="xdtime" type="xs:dateTime"/>
                  <xs:element name="xlog" type="xs:boolean"/>
               </xs:sequence>
            </xs:complexType>
         </xs:element>
      </xs:choice>
   </xs:complexType>
   <xs:unique name="Constraint1" msdata:PrimaryKey="true">
      <xs:selector xpath=".//Tbl2"/>
      <xs:field xpath="source"/>
   </xs:unique>
</xs:element>
</xs:schema>
<diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
<NewDataSet xmlns="">
   <Tbl2 diffgr:id="Tbl21" msdata:rowOrder="0">
      <source>Buckner             </source>
      <num>9</num>
      <xdtime>2002-04-03T00:00:00.0000000-08:00</xdtime>
      <xlog>true</xlog>
   </Tbl2>
</NewDataSet>
   </diffgr:diffgram>
</DataSet>

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
XMLTable Object Properties, Methods, and Events
LoadXML Method
Attach Method


XMLName Property

Visual FoxPro 9.0 Language Reference
XMLName Property
See Also

Contains the following for the specified objects:

XMLAdapter: XMLName contains the name of the element that specifies where to look for table elements. Read/write.

For more information about how the XMLAdapter LoadXML and Attach methods set this property, see the Remarks section.

XMLTable: XMLName contains the element name for that table in the XML document. Read-only when associated with an XMLAdapter object.

XMLField: XMLName contains the element or attribute name for that field in the XML document. Read-only when attached to an XMLTable object.

Object.XMLName

Return Value

Character data type. XMLName contains a Unicode character string or is empty ("") when not populated.

Note:
Before assigning a string value to XMLName, you must convert the value to Unicode. You can use the STRCONV( ) function to perform this requirement.

Remarks

Applies To: XMLAdapter Class | XMLTable Class | XMLField Class

The XMLAdapter LoadXML and Attach methods set the XMLAdapter XMLName property as follows:

  • ADO.NET DataSet element name for ADO.NET DataSet

  • "data" for ADO Recordset XML

  • Empty string ("") for Microsoft XML Data Reduced Schema (XDR) as used by Microsoft SQL-XML

If XMLAdapter XMLName is empty, XMLTable ToCursor looks for table elements within element referenced by the XMLAdapter IXMLDOMElement property.

The XMLAdapter ToXML method uses the XMLAdapter XMLName as the DataSet element name. If XMLName is empty, ToXML uses the string, "VFPDataSet".

The XMLTable ChangesToCursor and ApplyDiffgram methods require that XMLAdapter XMLName be set to a nonempty value and that the XML document is in DiffGram format.

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
XMLTable Object Properties, Methods, and Events
XMLField Object Properties, Methods, and Events
LoadXML Method
Attach Method
STRCONV( ) Function
ToCursor Method
IXMLDOMElement Property
ToXML Method
ChangesToCursor Method
ApplyDiffgram Method


XMLNameIsXPath Property

Visual FoxPro 9.0
XMLNameIsXPath Property
See Also

Specifies whether the XMLName property contains an XPath expression. Read/write at design time and run time.

XMLTable.XMLNameIsXPath = [lValue]

Property Value/Return Value

lValue

Logical data type. The following table lists values for lValue.

lValue Description

False (.F.)

(Default) The XMLName property does not contain an XPath expressions.

True (.T.)

The XMLName property contains an XPath expression.

Remarks

Applies to: XMLAdapter Class | XMLTable Class | XMLField Class

If you change the property from True (.T.) to False (.F.), you may get an error if the value of the XMLName Property contains white-space characters.

For more information about XPath expressions, see the XPath Reference in the Microsoft Core XML Services 4.0 (MSXML4) SDK in the MSDN library at http://msdn.microsoft.com/library.

See Also

Other Resources

Properties


XMLNamespace Property

Visual FoxPro 9.0 Language Reference
XMLNamespace Property
See Also

Contains the following for the specified objects:

XMLAdapter: XMLNamespace contains the XML Namespace to which XMLAdapter XMLName belongs, if any. Read/write.

XMLTable: XMLNamespace contains the XML Namespace to which XMLTable XMLName belongs. If empty, the XMLAdapter Namespace property is used instead. Read/write.

Note:
Only the XMLTable ToCursor, ChangesToCursor, and ApplyDiffgram methods use the XMLTable XMLNameSpace. The XMLField XMLName should belong to the same namespace as XMLTable XMLName.

Object.XMLNamespace

Return Value

Character data type. XMLNamespace contains a Unicode character string or is empty ("") when not populated.

Note:
Before assigning a string value to XMLNamespace, you must convert the value to Unicode. You can use the STRCONV( ) function to perform this requirement.

Remarks

Applies To: XMLAdapter Class | XMLTable Class

Note:
Visual FoxPro disregards the XMLTable XMLNamespace property when executing XMLAdapter ToXML method. Instead, it inserts the XMLTable XMLName and XMLField XMLName into the XMLAdapter XMLNamespace.

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
XMLTable Object Properties, Methods, and Events
XMLName Property
ToXML Method
ToCursor Method
ChangesToCursor Method
ApplyDiffgram Method
STRCONV( ) Function


XMLPrefix Property

Visual FoxPro 9.0 Language Reference
XMLPrefix Property
See Also

Contains the prefix used to reference the XMLNamespace property for the corresponding object.

Visual FoxPro disregards XMLPrefix unless XMLNamespace for the corresponding object is set to a nonempty value. The XMLAdapter ToXML method disregards XMLTable XMLPrefix.

Object.Prefix

Return Value

Character data type. XMLPrefix contains a Unicode character string or is empty ("") when not populated.

Note:
Before assigning a string value to XMLPrefix, you must convert the value to Unicode. You can use the STRCONV( ) function to perform this requirement.

Remarks

Applies To: XMLAdapter Class | XMLTable Class

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
XMLTable Object Properties, Methods, and Events
XMLNamespace Property
ToXML Method
STRCONV( ) Function


XMLSchemaLocation Property

Visual FoxPro 9.0 Language Reference
XMLSchemaLocation Property
See Also

Specifies schema information.

XMLSchemaLocation applies only when executing the following XMLAdapter methods:

  • LoadXML

  • Attach

  • ToXML

XMLAdapter.XMLSchemaLocation [= cValue]

Return Value

Character data type. The following table lists the values for cValue.

cValue Description

"1"

LoadXML processes inline or external schema, if referenced in the XML document. ToXML generates inline schema. (Default)

"schema location"

LoadXML processes inline or external schema, if referenced and accessible in the XML document. Otherwise, Visual FoxPro attempts to load schema from the specified "schema location". ToXML generates external schema in the specified location.

"" (Empty)

LoadXML does not:

  • Process any schema during loading.

  • Change the Tables collection.

  • Set the IsDiffGram property.

ToXML does not generate any schema.

Remarks

Applies To: XMLAdapter Class

See Also

Other Resources

Properties
XMLAdapter Object Properties, Methods, and Events
Tables Collection (XMLAdapter)
IsDiffGram Property


XMLTable Property

Visual FoxPro 9.0 Language Reference
XMLTable Property
See Also

Contains an object reference to an associated XMLTable object.

XMLField.XMLTable

Return Value

Object reference. XMLTable contains an object reference to an associated XMLTable object.

Remarks

Applies To: XMLField Class

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events
XMLTable Class


XMLType Property

Visual FoxPro 9.0 Language Reference
XMLType Property
See Also

Contains an object reference to the Microsoft XML Core Services (MSXML) 4.0 lSchemaType object, which contains restrictions, patterns, and so on for the field.

For more information about lSchemaType objects, see the MSXML 4.0 SDK on the MSDN Library Web site at http://msdn.microsoft.com/library/.

XMLField.XMLType

Return Value

Object reference. XMLType contains an object reference to the MSXML 4.0 lSchemaType object.

Remarks

Applies To: XMLField Class

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events


XSDfractionDigits Property

Visual FoxPro 9.0 Language Reference
XSDfractionDigits Property
See Also

Contains the XML Schema Definition (XSD) fractionDigits value, which appears to the right of the decimal point.

Note:
XSDfractionDigits is disregarded unless XMLField XSDtype has a nonempty value.

The following XMLAdapter methods populate the XSDfractionDigits property as appropriate:

  • LoadXML

  • Attach

  • AddTableSchema

XMLField.XSDfractionDigits

Return Value

Character data type. XSDfractionDigits specifies the XSD fraction digits.

Remarks

Applies To: XMLField Class

When generating XML using the XMLAdapter ToXML method, you can set this property to specify the fractionDigits restriction in the XSD schema. You might need this behavior when the fractionDigits value required for the schema differs from what Visual FoxPro would otherwise calculate. Visual FoxPro does not perform validation in this situation; therefore, you need to make sure the data conforms to the restrictions imposed by fractionDigits.

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events
XSDtype Property
XMLAdapter Class
ToXML Method


XSDmaxLength Property

Visual FoxPro 9.0 Language Reference
XSDmaxLength Property
See Also

Contains the XML Schema Definition (XSD) maxLength value.

Note:
XSDmaxLength is disregarded unless XMLField XSDtype is a nonempty value.

The following XMLAdapter methods populate the XSDmaxLength property as appropriate:

  • LoadXML

  • Attach

  • AddTableSchema

XMLField.XSDmaxLength

Return Value

Character data type. XSDmaxLength specifies the XSD maximum number of units of length.

Remarks

Applies To: XMLField Class

When generating XML using the XMLAdapter ToXML method, you can set this property to specify the maxLength restriction in the XSD schema. You might need this behavior when the maxLength value required for the schema differs from what Visual FoxPro would otherwise calculate. Visual FoxPro does not perform validation in this situation; therefore, you need to make sure the data conforms to the restrictions imposed by maxLength.

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events
XSDtype Property
XMLAdapter Class
ToXML Method


XSDtotalDigits Property

Visual FoxPro 9.0 Language Reference
XSDtotalDigits Property
See Also

Contains the XML Schema Definition (XSD) totalDigits value, which determines numeric precision.

Note:
XSDtotalDigits is disregarded unless XMLField XSDtype is a nonempty value.

The following XMLAdapter methods populate the XSDtotalDigits property as appropriate:

  • LoadXML

  • Attach

  • AddTableSchema

XMLField.XSDtotalDigits

Return Value

Character data type. XSDtotalDigits specifies the XSD total number of digits.

Remarks

Applies To: XMLField Class

When generating XML using the XMLAdapter ToXML method, you can set this property to specify the totalDigits restriction in the XSD schema. You might need this behavior when the totalDigits value required for the schema differs from what Visual FoxPro would otherwise calculate. Visual FoxPro does not perform validation in this situation; therefore, you need to make sure the data conforms to the restrictions imposed by totalDigits.

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events
XSDtype Property
XMLAdapter Class
ToXML Method


XSDtype Property

Visual FoxPro 9.0 Language Reference
XSDtype Property
See Also

Contains the XML Schema Definition (XSD) data type of the attribute or the restriction base.

The following XMLAdapter methods populate the XSDtype property as appropriate:

  • LoadXML

  • Attach

  • AddTableSchema

For example, the xsd:int or xs:int XSD Schema data types from the XML Schema are stored as "int", without its prefix, in XSDtype.

XMLField.XSDtype

Return Value

Character data type. XSDtype specifies the XSD data type of the attribute or the restriction base. If XSDtype is empty, the following XMLField properties are disregarded:

  • XSDmaxLength

  • XSDfractionDigits

  • XSDtotalDigits

Remarks

Applies To: XMLField Class

When generating XML using the XMLAdapter ToXML method, you can set this property to specify the XSD data type in the XSD schema. You might need this behavior when Visual FoxPro does not support the data type value required for the schema. Visual FoxPro does not validate data in this situation; therefore, you need to make sure the data conforms to the limits imposed of the specified XSD data type.

See Also

Other Resources

Properties
XMLField Object Properties, Methods, and Events
XMLAdapter Class
ToXML Method


ZoomBox Property

Visual FoxPro 9.0 Language Reference
ZoomBox Property
See Also

Included for backward compatibility with the Macintosh. Specifies whether a form has a zoom box. Available at design time; read/write at run time.

Copy Code
Object.ZoomBox = lExpr

Property Values

lExpr

The settings for the ZoomBox property are as follows:

Setting Description

True (.T.)

A zoom box appears in the upper-right corner of the form.

False (.F.)

(Default) No zoom box appears in the form.

Remarks

Applies To: Form

See Also

Other Resources

BorderStyle Property
SizeBox Property


_MemberData Property

Visual FoxPro 9.0 Language Reference
_MemberData Property
See Also

Specifies an XML string that contains extensibility settings for Visual FoxPro at the class level. For example, you can specify a custom property editor, display a property on the Favorites tab, or change the capitalization. Read/write at design time only.

Class._MemberData = [cXMLstring]

Return Value

cXMLString

Character string of XML representing a customization.

Remarks

You can annotate the MemberData XML with customization details. The customization you add to _MemberData is at the class and global levels. The class level always overrides the global level. At the class level, support is handled by the _MemberData property. The property contains an XML string with the actual member metadata. As a property, it is inherited and overridden by subclasses.

See Also

Reference

IntelliSense Table Structure

Concepts

MemberData Extensibility


Methods (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Methods (Visual FoxPro)
See Also

For information about backward compatible-only language reference, see Backward-Compatible Language Elements.

ActivateCell Method

Add Method (Collection Class)

Add Method (File Object)

AddColumn Method

AddItem Method

AddListItem Method

AddObject Method

AddProperty Method

AddTableSchema Method

AddToSCC Method

ApplyDiffGram Method

Attach Method

AutoFit Method

AutoOpen Method

Box Method

Build Method

CancelReport Method

ChangesToCursor Method

CheckIn Method

CheckOut Method

Circle Method

CleanUp Method

Clear Method

ClearData Method

ClearStatus Method

CloneObject Method

Close Method

CloseTables Method

Cls Method

CursorAttach Method

CursorDetach Method

CursorFill Method

CursorRefresh Method

DataToClip Method

DelayedMemoFetch Method

DeleteColumn Method

Dock Method

DoMessage Method

DoScroll Method

DoStatus Method

DoVerb Method

Drag Method

Draw Method

Eval Method

GetData Method

GetDockState Method

GetFormat Method

GetKey Method

GetLatestVersion Method

GetPageHeight Method

GetPageWidth Method

Help Method

Hide Method

IncludePageInOutput Method

IndexToItemID Method

Item Method (File Object)

ItemIDToIndex Method

LoadXML Method

Line Method

Modify Method

Move Method

MoveItem Method

Nest Method

OLEDrag Method

OnPreviewClose Method

OutputPage Method

Point Method

Print Method

PSet Method

Quit Method

ReadExpression Method

ReadMethod Method

RecordRefresh Method

Refresh Method

Release Method

ReleaseXML Method

Remove Method

RemoveFromSCC Method

RemoveItem Method

RemoveListItem Method

RemoveObject Method

Render Method

Requery Method

RequestData Method

Reset Method

ResetToDefault Method

Run Method

SaveAs Method

SaveAsClass Method

SetAll Method

SetData Method

SetFocus Method

SetFormat Method

SetMain Method

SetVar Method

SetViewPort Method

Show Method

ShowWhatsThis Method

SupportsListenerType Method

TextHeight Method

TextWidth Method

ToCursor Method

ToXML Method

UndoCheckOut Method

Unnest Method

UpdateStatus Method

WhatsThisMode Method

WriteExpression Method

WriteMethod Method

ZOrder Method

See Also

Other Resources

Language Reference


ActivateCell Method

Visual FoxPro 9.0 Language Reference
ActivateCell Method
See Also

Activates a cell in a Grid control.

Grid.ActivateCell(nRow, nCol)

Parameters

nRow, nCol

Specifies the row and the column that contain the active cell.

Remarks

Applies To: Grid Control

See Also

Other Resources

ActiveColumn Property
ActiveRow Property
GridHitTest Method
Methods
Language Reference


Add Method (Collection Class)

Visual FoxPro 9.0 Language Reference
Add Method (Collection Class)
See Also Example

Use to add a member to a collection.

The member object can have any valid type that can be assigned to a memory variable. This includes simple data types, such as strings, numbers, dates, logical, or more complex types such as Visual FoxPro and Component Object Model (COM) objects.

Collection.Add( eItem [, cKey [, [eBefore |, eAfter ]]] )

Parameters

eItem

Specifies an expression of any type that represents a member to add to the collection. Usually, this is an object, but it could be a number, string, or member that has a valid type.
cKey

Specifies an optional, unique, alphanumeric (character type) expression that represents a key string, instead of a positional index, that can be used to access a member of the collection. For collections using keys, cKey is a case-sensitive parameter and cannot be empty or have a null value (.NULL.). Either all items added to the collection must have the cKey parameter specified for them or not specified because of performance reasons. The first item added determines the behavior for the collection. You can test for the presence of keys in a collection by using the following code: GetKey(1) If the key already exists for a member in the collection, an error occurs. However, because cKey is case-sensitive, no duplication error occurs if the same keys with different case are added. A key includes any trailing spaces present in cKey.
[, [ eBefore|, eAfter]]

Specifies an optional expression that represents a position where a new member is to be inserted before or after another item in the collection. You can specify an eBefore or an eAfter expression but not both, which generates the appropriate message. This expression can be one of two types:
  • Numeric. The eBefore and eAfter expression must have a value from 1 to the value of the Count property for the collection.

  • String. The eBefore and eAfter expression must correspond to the cKey that was specified for the referenced item when it was added to the collection.

Inserting a new item into a collection before or after an existing one requires that the collection must be a keyed collection. When you specify a cKey value with an eBefore or eAfter parameter, the new item is added before or after the index value of the specified key. In this case, the value of Collection KeySort has no effect. For example, suppose cKey for a new item is "ZZZ", and for an existing item, cKey is "YYY", and its index value is 15. The new item would receive an index value of 15, and the existing item would receive a new index value of 16. To insert a new item before an existing item, include the key of the item you want to insert the new item before as shown in the following example:
Copy Code
loItems.Add("Roses", "flower1", "flower2")
To insert a new item after an existing item, include the key of the item you want to insert the new item after. In addition, you must pass an empty third parameter for eBefore as shown in the following example:
Copy Code
loItems.Add("Orchids", "flower3",, "flower2")
If eBefore and eAfter do not refer to an existing member of the collection, an error occurs. Visual FoxPro adds an item to the end of a collection when eBefore or eAfter are not specified.

Remarks

When adding objects to collections, Visual FoxPro increases the reference count for that object. According to usual Visual FoxPro object behavior, you can release an object only when its reference count is 0. Therefore, you should make sure that the reference to the object in the collection is released when releasing the object; otherwise, the Visual FoxPro does not remove the object entirely from memory.

You are not limited to the number of items you can add to a collection. However, the size of a collection can affect the performance of operations such as accessing, searching, and enumerating items in the collection. For example, creating a large collection based on records from a very large table (.dbf) is not recommended because you cannot use query optimization and other features associated with the Visual FoxPro native data engine.

You can have a collection of collections because collections are objects. However, avoid creating circular references, such as attempting to add an outer collection to an inner collection.

Adding arrays as items to a collection instantiated from the base class has limited use because there is no easy way to reference all the elements in the array. Consider the following example:

Copy Code
DIMENSION x[3]
x[1] = 1
x[2] = 22
x[3] = 333
y = CREATEOBJECT("collection")
y.Add(@x)
z = y.item(1)   && Returns just the first element
? z[2]         && Error

Therefore, you should create a subclass with special handling for this scenario.

You can pass a value of NULL as an item type and use TYPE( ) and VARTYPE( ) functions to query the type of the item in the collection.

You can add items of mixed type. However, Visual FoxPro does not enforce type safety, so you should provide it for the class if needed. If an incorrect type is passed for a specific parameter, an error occurs.

Include the NODEFAULT command in the Add method for collection objects to prevent adding a particular item to the collection.

Example

The following example illustrates the following tasks:

  • Adds four items to a collection using the cKey parameter.

  • Adds a second item with a key that precedes the first item using the eBefore parameter.

  • Adds a fourth item with a key that follows the first added item using the eAfter parameter.

  • Iterates through all the items displaying to the screen.

Copy Code
CLEAR
LOCAL loItems, lcFlower
loItems = NEWOBJECT("Collection")
loItems.Add("Daffodils", "flower2")

* Add "Roses" with "flower1" key before "flower2".
loItems.Add("Roses", "flower1", "flower2")
loItems.Add("Daisies", "flower4")

* Add "Orchids" with "flower4" key after "flower2".
loItems.Add("Orchids","flower3",,"flower2")
FOR EACH lcFlower IN loItems
   ? lcFlower
ENDFOR

The following example generates an error. You cannot specify both an eBefore and an eAfter.

Copy Code
* Generates an error. Cannot specify both eBefore and eAfter.
loItems.Add("Violets","flower5","flower2","flower1")

See Also

Other Resources

Collection Object Properties, Methods, and Events
Collection Class
KeySort Property
Methods
TYPE( ) Function
VARTYPE( ) Function
NODEFAULT Command


Add Method (File Object)

Visual FoxPro 9.0 Language Reference
Add Method (File Object)
See Also Example

Adds a file to a project.

Object.Add(cFileName)

Parameters

cFileName

Specifies the name of the file to add to the project. An error is generated if the file you specify does not exist. The Project Manager window, if open, is refreshed after the file has been added.

Return Value

Object

Remarks

Applies To: Files Collection

The Add method is a method for the files collection. When a file is added to a project with the Add method, a File object is created for the file, and the File object is added to the Files collection.

An object reference to the newly added file is returned if the file is successfully added to the project. The null value is returned if the file can't be added to the project.

The QueryAddFile event occurs just before a file is added to a project. If NODEFAULT is specified in the QueryAddFile event, the file isn't added to the project.

Include NODEFAULT in the QueryAddFile event to prevent a file from being added to the project.

Example

The following example programmatically creates a Project and then builds an executable (EXE) from that Project. It uses the Add method to add program code to the project.
Copy Code
SET SAFETY OFF
LOCAL lcCode
TEXT TO lcCode NOSHOW
CLEAR
PUBLIC loForm

SET TALK OFF
SET DELETED ON
SET EXCLUSIVE OFF
SET CENTURY ON

ON SHUTDOWN clear events
loForm = CREATEOBJECT('Test1')
loForm.Show(0)
READ EVENTS
ON SHUTDOWN
RETURN

DEFINE CLASS Test1 as Form
 Top = 0
 Left = 0
 Width = 240
 Height = 150
 Caption = 'Add Method sample'
 ShowWindow = 2

 ADD OBJECT cmdClose as CommandButton WITH ;
  Caption = '\<Close', ;
  Top = 80, ;
  Left = 80, ;
  Height = 24, ;
  Width = 80

 ADD OBJECT lblTitle as Label WITH ;
  Top = 30, ;
  Left = 40, ;
  Height = 34, ;
  Width = 160, ;
  Caption = 'This sample was made programmatically.';
  WordWrap = .t.

 PROCEDURE Init
  SET TALK off
  ThisForm.AutoCenter = .t.
 ENDPROC
 PROCEDURE Unload
  CLEAR EVENTS
 ENDPROC
 PROCEDURE cmdClose.Click
  ThisForm.Release()
 ENDPROC
ENDDEFINE
ENDTEXT

STRTOFILE(lcCode, 'addsample.prg')
CREATE PROJECT 'AddSample' NOSHOW NOWAIT SAVE
LOCAL loPJX
loPJX = _VFP.ActiveProject
WITH loPJX
 .Files.Add('addsample.prg')
 .SetMain('addsample.prg')
 .Build('addsample.exe',3,.t.,.t.,.f.)
 .Close()
ENDWITH
RUN /n addsample.exe

See Also

Other Resources

File Object
QueryAddFile Event
NODEFAULT Command
Methods
Language Reference


AddColumn Method

Visual FoxPro 9.0 Language Reference
AddColumn Method
See Also

Adds a Column object to a Grid control.

Grid.AddColumn(nIndex)

Parameters

nIndex

Specifies a number representing the position in the grid where the new Column is added.

Remarks

Applies To: Grid Control

When AddColumn( ) is called, existing columns are moved to the right, and their ColumnOrder properties are incremented accordingly. The grid's ColumnCount property is also increased.

The grid's Controls property array is enlarged by one element, and a reference to the new column is placed in the new element. The new column is assigned a unique name.

For example, to add a new column and then assign a new name to that column, you could do the following.

Copy Code
THISFORM.Grid1.AddColumn(1)   && Insert column at left.
THISFORM.Grid1.Columns(THISFORM.Grid1.ColumnCount).Name = "NewColumn"
THISFORM.Grid1.NewColumn.ControlSource = "Customer.CustID"

See Also

Other Resources

AddObject Method
ColumnCount Property
DeleteColumn Method
Methods
Language Reference


AddItem Method (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
AddItem Method (Visual FoxPro)
See Also Example

Adds a new item to a ComboBox or ListBox control, optionally making it possible for you to specify the item's index.

Control.AddItem(cItem [, nIndex] [, nColumn])

Parameters

cItem

Specifies the string expression to add to the control.
nIndex

Specifies the position where the item is placed in the control. If you supply a valid value for the optional nIndex, cItem is placed at that position within the control. If you specify an nIndex that already exists, the item is inserted at that position and all items below that item are moved down one position in the list portion of the ComboBox or ListBox control. If you omit nIndex and the Sorted property is set to True (.T.), cItem is added in alphabetic sort order. If you omit nIndex and the Sorted property is set to False (.F.), cItem is added to the end of the list portion of the ComboBox or ListBox control.
nColumn

Specifies the column of the control to which the new item is added. The default is 1.

Remarks

Use the AddItem method or AddListItem method when the RowSourceType property is set to 0 (None).

Each item added to a ComboBox or ListBox has two identification numbers assigned to it:

  • nItemID, an integer corresponding to the unique ID of the item in the control: the first item corresponds to nItemID = 1 unless another nItemID is specified.

  • nIndex, an integer corresponding to the order in which items are displayed by the control: the first item in the control corresponds to nIndex = 1.

The AddItem method always inserts a new row into a multicolumn ComboBox or ListBox. After a row has been inserted, columns in that row should be populated using the .List(.NewIndex, nColumn) syntax.

The backslash ("\") is treated as a special character when used in the expression for an item. The following rules apply for this character:

  • You can disable an item in a list box or combo box by adding a single backslash to the beginning of the expression. When you disable an item using a backslash, it is disabled for mouse access only, however, a user can still access that item using the keyboard. To disable the item from mouse and keyboard access, preface the entry with both backslash and close bracket characters ("\]").

  • Any multiple of two backslashes used in the expression is displayed as a single backslash. For example, one or two backslashes used together will display as one, and three or four backslashes together will display as two. The following example code contains a list box item containing a Universal Naming Convention (UNC) path. The code displays in the list box as \\MyServer\MyMachine\MyFolder.

    Copy Code
    MyForm.List1.AddItem("\\\\MyServer\\MyMachine\\MyFolder")
  • If the expression begins with multiple backslashes, the item is not disabled. If you want to disable an item that begins with multiple backslashes, add a backslash and a close bracket (]) to the beginning of the item. For example, the following disables the UNC path item in the list box.

    Copy Code
    MyForm.List1.AddItem("\]\\\MyServer\\MyMachine\\MyFolder")
  • To include a separator line, use a backslash followed by a hyphen as the item to add to the list box. For example, the following code adds a separator line to a list box.

    Copy Code
    MyForm.List1.AddItem("\-")

Example

This example demonstrates using the AddItem and AddListItem methods to add values to the ListItem array. Both proper and improper ways of populating a combo box are shown for clarity.
Copy Code
PUBLIC ofrmListExamples
ofrmListExamples=NEWOBJECT("frmListExamples")
ofrmListExamples.Show
RETURN

DEFINE CLASS frmListExamples AS form

 DataSession = 2
 Top = 0
 Left = 0
 Height = 262
 Width = 325
 Caption = "List and ListItem Array Example"
 Name = "frmListExamples"

 ADD OBJECT shape1 AS shape WITH ;
  Top = 43, ;
  Left = 32, ;
  Height = 76, ;
  Width = 261, ;
  SpecialEffect = 0, ;
  Name = "Shape1"

 ADD OBJECT cbolistbad AS combobox WITH ;
  ColumnCount = 3, ;
  ColumnWidths = "100,100,50", ;
  Height = 22, ;
  Left = 111, ;
  Sorted = .T., ;
  Style = 2, ;
  TabIndex = 1, ;
  Top = 53, ;
  Width = 147, ;
  Name = "cboListBad"

 ADD OBJECT cbolistitem AS combobox WITH ;
  ColumnCount = 3, ;
  ColumnWidths = "100,100,50", ;
  Left = 34, ;
  Sorted = .T., ;
  Style = 2, ;
  TabIndex = 3, ;
  Top = 154, ;
  Name = "cboListItem"

 ADD OBJECT label1 AS label WITH ;
  FontBold = .T., ;
  Caption = "Using the List Array:", ;
  Height = 17, ;
  Left = 34, ;
  Top = 24, ;
  Width = 176, ;
  TabIndex = 7, ;
  Name = "Label1"

 ADD OBJECT label2 AS label WITH ;
  FontBold = .T., ;
  Caption = "Using the ListItem Array:", ;
  Height = 17, ;
  Left = 34, ;
  Top = 135, ;
  Width = 173, ;
  TabIndex = 8, ;
  Name = "Label2"

 ADD OBJECT cbolistgood AS combobox WITH ;
  ColumnCount = 3, ;
  ColumnWidths = "100,100,50", ;
  Height = 22, ;
  Left = 111, ;
  Sorted = .T., ;
  style = 2, ;
  TabIndex = 2, ;
  Top = 86, ;
  Width = 147, ;
  Name = "cboListGood"

 ADD OBJECT label3 AS label WITH ;
  Alignment = 1, ;
  Caption = "Wrong!", ;
  Height = 17, ;
  Left = 51, ;
  Top = 56, ;
  Width = 47, ;
  TabIndex = 9, ;
  Name = "Label3"

 ADD OBJECT label4 AS label WITH ;
  Alignment = 1, ;
  Caption = "Right!", ;
  Height = 17, ;
  Left = 58, ;
  Top = 89, ;
  Width = 40, ;
  TabIndex = 10, ;
  Name = "Label4"

 PROCEDURE cbolistbad.Init
  WITH This
   .AddItem( 'Cleveland' )
   .AddItem( 'Ohio', .NewIndex, 2 )
   .AddItem( '44122', .NewIndex, 3 )
   .AddItem( 'Caversham' )
   .AddItem( 'England', .NewIndex, 2 )
   .AddItem( 'RG4 8BX', .NewIndex, 3 )
   .AddItem( 'Buffalo' )
   .AddItem( 'New York', .NewIndex, 2 )
   .AddItem( '14228', .NewIndex, 3 )
   .AddItem( 'Milwaukee' )
   .AddItem( 'Wisconsin', .NewIndex, 2 )
   .AddItem( '43225', .NewIndex, 3 )
   .AddItem( 'International Falls')
   .AddItem( 'Minnesota', .NewIndex, 2 )
   .AddItem( '42666', .NewIndex, 3 )
  ENDWITH
 ENDPROC

PROCEDURE cbolistgood.Init
  WITH This
   .AddItem( 'Cleveland' )
   .List[.NewIndex, 2] = 'Ohio'
   .List[.NewIndex, 3] = '44122'
   .AddItem( 'Caversham' )
   .List[.NewIndex, 2] = 'England'
   .List[.NewIndex, 3] = 'RG4 8BX'
   .AddItem( 'Buffalo' )
   .List[.NewIndex, 2] = 'New York'
   .List[.NewIndex, 3] = '14228'
   .AddItem( 'Milwaukee' )
   .List[.NewIndex, 2] = 'Wisconsin'
   .List[.NewIndex, 3] = '43225'
   .AddItem( 'International Falls' )
   .List[.NewIndex, 2] = 'Minnesota'
   .List[.NewIndex, 3] = '42666'
  ENDWITH
 ENDPROC

 PROCEDURE cbolistitem.Init
  WITH This
   .AddListitem( 'Cleveland' )
   .AddListItem( 'Ohio', .NewItemID, 2 )
   .AddListItem( '44122', .NewItemID, 3 )
   .AddListItem( 'Caversham' )
   .AddListItem( 'England', .NewItemID, 2 )
   .AddListItem( 'RG4 8BX', .NewItemID, 3 )
   .AddListItem( 'Buffalo' )
   .AddListItem( 'New York', .NewItemID, 2 )
   .AddListItem( '14228', .NewItemID, 3 )
   .AddListItem( 'Milwaukee' )
   .AddListItem( 'Wisconsin', .NewItemID, 2 )
   .AddListItem( '43225', .NewItemID, 3 )
   .AddListItem( 'International Falls')
   .AddListItem( 'Minnesota', .NewItemID, 2 )
   .AddListItem( '42666', .NewItemID, 3 )
  ENDWITH
 ENDPROC
ENDDEFINE

See Also

Other Resources

AddListItem Method
Clear Method
List Property
ListIndex Property
ListItemID Property
RowSourceType Property
RemoveItem Method
Sorted Property
Methods
Language Reference


AddListItem Method

Visual FoxPro 9.0 Language Reference
AddListItem Method
See Also Example

Adds a new item to a ComboBox or ListBox control, optionally making it possible for you to specify the item's item ID.

Control.AddListItem(cItem [, nItemID] [, nColumn])

Parameters

cItem

Specifies the item to add to the control.
nItemID

Specifies an integer representing the unique ID of the item in the control. The maximum value you can specify for nItemID is 32,767. If you omit nItemID and the Sorted property is set to True (.T.), cItem is added in alphabetic sort order. If you omit nItemID and the Sorted property is set to False (.F.), cItem is added to the end of the list of the ComboBox or ListBox.
nColumn

Specifies the column of the control to add the new item to. The default is 1.

Remarks

Applies To: ComboBox Control | ListBox Control

Use the AddItem method or AddListItem method when the RowSourceType property is set to 0 (None).

Each item added to a ComboBox or ListBox has two identification numbers assigned to it:

  • nItemID, an integer corresponding to the unique ID of the item in the control: the first item corresponds to nItemID = 1 unless another nItemID is specified.

  • nIndex, an integer corresponding to the order in which items are displayed by the control: the first item in the control corresponds to nIndex = 1.

The backslash ("\") is treated as a special character when used in the expression for an item. The following rules apply for this character:

  • You can disable an item in a list box or combo box by adding a single backslash to the beginning of the expression.

  • Any multiple of two backslashes used in the expression is displayed as a single backslash. For example, one or two backslashes used together will display as one, three or four backslashes together will display as two. The following example code contains a list box item containing a Universal Naming Convention (UNC) path. The code displays in the list box as \\MyServer\MyMachine\MyFolder.

    Copy Code
    MyForm.List1.AddItem("\\\\MyServer\\MyMachine\\MyFolder")
  • If the expression begins with multiple backslashes, the item is not disabled. If you want to disable an item that begins with multiple backslashes, add a backslash and a close bracket (]) to the beginning of the item. For example, the following disables the UNC path item in the list box:

    Copy Code
    MyForm.List1.AddItem("\]\\\MyServer\\MyMachine\\MyFolder")
  • To include a separator line, use a backslash followed by a hyphen as the item to add to the list box. For example, the following code adds a separator line to a list box.

    Copy Code
    MyForm.List1.AddItem("\-")

Example

This example demonstrates using the AddItem and AddListItem methods to add values to the ListItem array. Both proper and improper ways of populating a combo box are shown for clarity.
Copy Code
PUBLIC ofrmListExamples
ofrmListExamples=NEWOBJECT("frmListExamples")
ofrmListExamples.Show
RETURN

DEFINE CLASS frmListExamples AS form

 DataSession = 2
 Top = 0
 Left = 0
 Height = 262
 Width = 325
 Caption = "List and ListItem Array Example"
 Name = "frmListExamples"

 ADD OBJECT shape1 AS shape WITH ;
  Top = 43, ;
  Left = 32, ;
  Height = 76, ;
  Width = 261, ;
  SpecialEffect = 0, ;
  Name = "Shape1"

 ADD OBJECT cbolistbad AS combobox WITH ;
  ColumnCount = 3, ;
  ColumnWidths = "100,100,50", ;
  Height = 22, ;
  Left = 111, ;
  Sorted = .T., ;
  Style = 2, ;
  TabIndex = 1, ;
  Top = 53, ;
  Width = 147, ;
  Name = "cboListBad"

 ADD OBJECT cbolistitem AS combobox WITH ;
  ColumnCount = 3, ;
  ColumnWidths = "100,100,50", ;
  Left = 34, ;
  Sorted = .T., ;
  Style = 2, ;
  TabIndex = 3, ;
  Top = 154, ;
  Name = "cboListItem"

 ADD OBJECT label1 AS label WITH ;
  FontBold = .T., ;
  Caption = "Using the List Array:", ;
  Height = 17, ;
  Left = 34, ;
  Top = 24, ;
  Width = 176, ;
  TabIndex = 7, ;
  Name = "Label1"

 ADD OBJECT label2 AS label WITH ;
  FontBold = .T., ;
  Caption = "Using the ListItem Array:", ;
  Height = 17, ;
  Left = 34, ;
  Top = 135, ;
  Width = 173, ;
  TabIndex = 8, ;
  Name = "Label2"

 ADD OBJECT cbolistgood AS combobox WITH ;
  ColumnCount = 3, ;
  ColumnWidths = "100,100,50", ;
  Height = 22, ;
  Left = 111, ;
  Sorted = .T., ;
  style = 2, ;
  TabIndex = 2, ;
  Top = 86, ;
  Width = 147, ;
  Name = "cboListGood"

 ADD OBJECT label3 AS label WITH ;
  Alignment = 1, ;
  Caption = "Wrong!", ;
  Height = 17, ;
  Left = 51, ;
  Top = 56, ;
  Width = 47, ;
  TabIndex = 9, ;
  Name = "Label3"

 ADD OBJECT label4 AS label WITH ;
  Alignment = 1, ;
  Caption = "Right!", ;
  Height = 17, ;
  Left = 58, ;
  Top = 89, ;
  Width = 40, ;
  TabIndex = 10, ;
  Name = "Label4"

 PROCEDURE cbolistbad.Init
  WITH This
   .AddItem( 'Cleveland' )
   .AddItem( 'Ohio', .NewIndex, 2 )
   .AddItem( '44122', .NewIndex, 3 )
   .AddItem( 'Caversham' )
   .AddItem( 'England', .NewIndex, 2 )
   .AddItem( 'RG4 8BX', .NewIndex, 3 )
   .AddItem( 'Buffalo' )
   .AddItem( 'New York', .NewIndex, 2 )
   .AddItem( '14228', .NewIndex, 3 )
   .AddItem( 'Milwaukee' )
   .AddItem( 'Wisconsin', .NewIndex, 2 )
   .AddItem( '43225', .NewIndex, 3 )
   .AddItem( 'International Falls')
   .AddItem( 'Minnesota', .NewIndex, 2 )
   .AddItem( '42666', .NewIndex, 3 )
  ENDWITH
 ENDPROC

 PROCEDURE cbolistitem.Init
  WITH This
   .AddListitem( 'Cleveland' )
   .AddListItem( 'Ohio', .NewItemID, 2 )
   .AddListItem( '44122', .NewItemID, 3 )
   .AddListItem( 'Caversham' )
   .AddListItem( 'England', .NewItemID, 2 )
   .AddListItem( 'RG4 8BX', .NewItemID, 3 )
   .AddListItem( 'Buffalo' )
   .AddListItem( 'New York', .NewItemID, 2 )
   .AddListItem( '14228', .NewItemID, 3 )
   .AddListItem( 'Milwaukee' )
   .AddListItem( 'Wisconsin', .NewItemID, 2 )
   .AddListItem( '43225', .NewItemID, 3 )
   .AddListItem( 'International Falls')
   .AddListItem( 'Minnesota', .NewItemID, 2 )
   .AddListItem( '42666', .NewItemID, 3 )
  ENDWITH
 ENDPROC

 PROCEDURE cbolistgood.Init
  WITH This
   .AddItem( 'Cleveland' )
   .List[.NewIndex, 2] = 'Ohio'
   .List[.NewIndex, 3] = '44122'
   .AddItem( 'Caversham' )
   .List[.NewIndex, 2] = 'England'
   .List[.NewIndex, 3] = 'RG4 8BX'
   .AddItem( 'Buffalo' )
   .List[.NewIndex, 2] = 'New York'
   .List[.NewIndex, 3] = '14228'
   .AddItem( 'Milwaukee' )
   .List[.NewIndex, 2] = 'Wisconsin'
   .List[.NewIndex, 3] = '43225'
   .AddItem( 'International Falls' )
   .List[.NewIndex, 2] = 'Minnesota'
   .List[.NewIndex, 3] = '42666'
  ENDWITH
 ENDPROC
ENDDEFINE

See Also

Other Resources

AddItem Method
Clear Method
ListIndex Property
ListItemID Property
RowSourceType Property
RemoveItem Method
Sorted Property
Methods
Language Reference


AddObject Method

Visual FoxPro 9.0 Language Reference
AddObject Method
See Also Example

Adds an object to a Container object at run time.

Object.AddObject(cName, cClass [, cOLEClass] [, aInit1, aInit2 ...])

Parameters

cName

Specifies the name used to reference the new object.
cClass

Specifies the class of the object to add.
cOLEClass

Specifies the OLE class of the object to add.
Note:
If you plan to distribute run-time applications which add ActiveX Controls requiring License key information (for example, Microsoft Treeview and Listview controls), you should not use the AddObject(.....cOLEClass) method. Instead, create and save a subclass of your ActiveX Control to a VCX class library. Then, at run time you can use the AddObject (or NewObject) method to add this OleControl class containing your control.

aInit1, aInit2

Specify parameters passed to the Init event of the new object.

Remarks

Applies To: Column Object | CommandGroup Control | Container Object | Custom Object | DataEnvironment Object | Form Object | FormSet Object | Grid Control | OptionGroup Control | Page Object | PageFrame Control | _SCREEN | ToolBar Object

Calling the AddObject method triggers the Init event of the object being added. When a form is added to a form set, the Load event occurs before the Init event.

Note:
When you use AddObject to add an object to a container, the object's Visible property is set to False (.F.) so you can set the properties of the object without any awkward visual effects as the object's appearance changes.

If you use the AddObject( ) method to add an ActiveX Control to a form dynamically, your distributed application can fail if that control requires certain licensing registry keys that are not available on the target machine. Many vendors of ActiveX controls require such registry keys for manipulation of these controls at design time as with the AddObject( ) method. Avoid this licensing requirement by first subclassing the ActiveX Control in a class library file (.vcx) and then using AddObject( ) to add an instance of the subclass dynamically at run time. You should always check with the vendor of any ActiveX control you plan to distribute with your custom application since there may be other dependent files that you need to include.

Example

The following example demonstrates how the AddObject method can be used to add objects or controls to a form. AddObject is used to add a Line control and three command buttons to the form.

The Visible property is set to True (.T.) for the Line control and the command buttons. By default, objects and controls are not visible when they are added to a form.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('shpLine','Line')  && Add a Line control to the form
frmMyForm.AddObject('cmdCmndBtn1','cmdMyCmndBtn1')  && Up Cmnd button
frmMyForm.AddObject('cmdCmndBtn2','cmdMyCmndBtn2')  && Down Cmnd button
frmMyForm.AddObject('cmdCmndBtn3','cmdMyCmndBtn3')  && Quit Cmnd button

frmMyForm.shpLine.Visible = .T.  && Make Line control visible
frmMyForm.shpLine.Top = 20  && Specify Line control row
frmMyForm.shpLine.Left = 125  && Specify Line control column

frmMyForm.cmdCmndBtn1.Visible =.T.  && Up Command button visible
frmMyForm.cmdCmndBtn2.Visible =.T.  && Down" Command button visible
frmMyForm.cmdCmndBtn3.Visible =.T.  && Quit Command button visible

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmndBtn1 AS COMMANDBUTTON  && Create Command button
   Caption = 'Slant \<Up'  && Caption on the Command button
   Left = 50  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='/'  && Slant up
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn2 AS CommandButton  && Create Command button
   Caption = 'Slant \<Down'  && Caption on the Command button
   Left = 200  && Command button column
   Top = 100  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      ThisForm.shpLine.Visible = .F.  && Hide the Line control
      ThisForm.shpLine.LineSlant ='\'  && Slant down
      ThisForm.shpLine.Visible = .T.  && Show the Line control
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn3 AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 150  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

See Also

Other Resources

Init Event
Load Event
NewObject Method
RemoveObject Method
Visible Property
Methods
Language Reference


AddProperty Method

Visual FoxPro 9.0 Language Reference
AddProperty Method
See Also

Adds a new property to an object.

Object.AddProperty(cPropertyName [, eNewValue [, nVisibility [, cDescription]]])

Parameters

cPropertyName

Specifies the name of the new property to add to the object.
eNewValue

Specifies the value to which the new property is set. If eNewValue is omitted, the value of the new property is unchanged if the property already exists or is set to False (.F.) for a new property.
nVisibility

Specifies the visibility of the new property. Available for use at design-time, however, a value of 1 can be specified at runtime.

nVisibility Visibility

1

Public

2

Protected

3

Hidden
cDescription

Specifies a description for the new property. Available only at design-time. The property description is limited to 255 characters.

Return Value

Logical

Remarks

Applies To: CheckBox Control | Collection Class | Column Object | ComboBox Control | CommandButton Control | CommandGroup Control | Container Object | Control Object | Cursor Object | CursorAdapter Class | Custom | DataEnvironment Object | EditBox Control | Exception Class | Form Object | FormSet Object | Grid Control | Header Object | Image Control | Label Control | Line Control | ListBox Control | OLE Bound Control | OLE Container Control | OptionButton Control | OptionGroup Control | Page Object | PageFrame Control | ProjectHook Object | Relation Object | ReportListener Object | _SCREEN | Separator Object | Session Object | Shape Control | Spinner Control | TextBox Control | Timer Control | ToolBar Object

The AddProperty( ) method makes it possible for you to add a property to an object at run time. The new property is added as a PUBLIC property.

You can also create property arrays for an object. Every element in the property array is initialized to eNewValue if it is included; otherwise every property array element contains False (.F.). The following code demonstrates how you can create a property array for an object:

Copy Code
oMyForm = CREATEOBJECT('Form')
oMyForm.AddProperty('MyArray(2)', 1)  && Add an array as a property
oMyForm.MyArray(2) = 'Two'
CLEAR
? oMyForm.MyArray(1)  && Displays 1
? oMyForm.MyArray(2)  && Displays Two

If a property with the name you specify does not exist, the property is created and a logical True (.T.) is returned.

If a property already exists with the name you specify, then AddProperty( ) returns the following:

  • True (.T.) if the new property is an array property and the existing property is also an array property. The size of the array is redimensioned to that of the new array. If a value is specified with eNewValue, all the elements in the array are set to its value. If eNewValue is omitted, all the array elements are set to False (.F.).

  • True (.T.) if the new property is not an array property and the existing property is an array property. The property remains an array property. If a value is specified with eNewValue, all the elements in the array are set to its value. If eNewValue is omitted, the array elements remain unchanged.

  • True (.T.) if the new property is not an array property and the existing property is not an array property or is not a read-only Visual FoxPro native property. If a value is specified with eNewValue, the existing property is set to its value. If eNewValue is omitted, the existing property value remains unchanged.

  • False (.F.) if the new property is an array property and the existing property is not an array property. The existing property remains unchanged.

  • A "Property <PropertyName> is read-only" error is generated if the existing property is a read-only Visual FoxPro native property such as the BaseClass property.

  • An "Incorrect property name" error is generated if the property name is not valid (the property name contains a space or other illegal characters).

The AddProperty( ) method only works with some native Visual FoxPro objects. You can use the ADDPROPERTY( ) function to add a property to any object that Visual FoxPro works with, such as COM objects or those created with the SCATTER...NAME property. For more information, see ADDPROPERTY( ) function.

See Also

Other Resources

DEFINE CLASS Command
NewObject Method
SaveAs Method
SaveAsClass Method
Methods
Language Reference


AddTableSchema Method

Visual FoxPro 9.0 Language Reference
AddTableSchema Method
See Also

Adds a new XMLTable object to the XMLAdapter Tables collection and the necessary XMLField objects to the XMLTable Fields collection based on the specified table alias.

The following parameters must be converted to Unicode before passing as parameters to AddTableSchema:

  • cXMLName

  • cXMLNamespace

  • cXMLPrefix

You can use theSTRCONV( ) function to perform this requirement.

XMLAdapter.AddTableSchema(cAlias [, lElementBased [, cXMLName
   [, cXMLNamespace [, cXMLPrefix [, lWrapMemoInCDATA
   [, lWrapCharacterInCDATA[, lAutoNest]]]]]]])

Parameters

cAlias

Specifies the alias of the Visual FoxPro table or cursor to use as a schema template.
lElementBased

Specifies the style of XML. The default value of lElementBased is True (.T.).
cXMLName

Specifies the name to use for the table in the XML and must be converted to Unicode before passing as a parameter. The default value for the cXMLName parameter is the value of the cAlias parameter. Conversion to Unicode is performed automatically.
cXMLNamespace

Specifies the XML Namespace to use, which must be converted to Unicode before passing as a parameter. The default value is an empty ("") string.
cXMLPrefix

Specifies the XML Prefix to use, which must be converted to Unicode before passing as a parameter. The default value is an empty ("") string.
lWrapMemoInCDATA

Specifies whether to wrap Memo fields in CDATA sections. The default value is specified by the WrapMemoInCDATA property for the XMLAdapter object.
lWrapCharacterInCDATA

Specifies whether to wrap Character fields in CDATA sections. The default value is specified by the WrapCharInCDATA property for the XMLAdapter object.
lAutoNest

Specifies whether tables added to the XMLAdapter Tables collection are automatically nested. The default value is specified by the RespectNesting property for the XMLAdapter object.

Remarks

Applies To: XMLAdapter Class

The following property settings affect how the AddTableSchema method is executed:

  • DisableEncode

  • NoCpTrans

  • WrapCharInCDATA

  • WrapMemoInCDATA

If lAutoNest is set to True (.T.), nesting of the XMLTable objects in the XMLAdapter Tables collection occurs after the new XMLTable object is added. The relationship specified with the SET RELATION Command and the XMLTable Alias property determine the nesting schema.

  • Parent Tables: The first XMLTable object with an Alias property value matching the Alias of a parent cursor in any relationship to the new table becomes the parent XMLTable object for the new XMLTable object, and the new XMLTable object becomes the last nested object.

  • Nested Tables: Any XMLTable objects with an alias matching the alias of a child cursor in any relationship from the new table becomes a nested XMLTable object in the new XMLTable object, unless it is already nested.

See Also

Reference

RespectNesting Property

Other Resources

Methods
XMLAdapter Object Properties, Methods, and Events
Tables Collection (XMLAdapter)
XMLField Class
Fields Collection (XMLTable)
STRCONV( ) Function
Memo Field Type
Character Data Type


AddToSCC Method

Visual FoxPro 9.0 Language Reference
AddToSCC Method
See Also

Adds a file in a project to source code control.

Object.AddToSCC( )

Remarks

Applies To: File Object

True (.T.) is returned if the file is successfully added to source code control. False (.F.) is returned if the file could not be added to source code control or the project is not under source code control.

See Also

Other Resources

CheckIn Method
CheckOut Method
GetLatestVersion Method
RemoveFromSCC Method
UndoCheckOut Method
Methods
Language Reference


ApplyDiffgram Method

Visual FoxPro 9.0 Language Reference
ApplyDiffgram Method
See Also

Applies a DiffGram to local Visual FoxPro tables.

XMLTable.ApplyDiffgram( [ cAlias [, oCursorAdapter [, lPreserveChanges [, nCodePage ]]]] )

Parameters

cAlias

Specifies the alias of the target cursor. The value of cAlias defaults to the XMLTableAlias property, including when cAlias is an empty string ("").
oCursorAdapter

Specifies a pre-existing CursorAdapter object. ApplyDiffgram attaches the temporary table-buffered cursor containing changes to the specified CursorAdapter object. ApplyDiffgram also applies any updates, such as modified, inserted, or deleted records, to the base table set for the CursorAdapter object or to the cursor matching the Alias property of the XMLTable object. If you do not provide a value for oCursorAdapter, ApplyDiffgram automatically handles updates to the base table.
Note:
You can update the remote data source using the ApplyDiffgram method provided that the CursorAdapter is configured for such a purpose.

lPreserveChanges

Specifies whether to keep the cursor, with changes, attached to the CursorAdapter object and any changes to the properties of the CursorAdapter object intact when you provide a custom CursorAdapter object, and ApplyDiffgram fails, . The following table describes the values for lPreserveChanges.

lPreserveChanges Description

True (.T.)

(Default) Keep the cursor, with changes, attached to the cursor adapter and the changes to the properties of the cursor adapter intact.

False (.F.)

Detach the cursor, with changes, and revert any changes that were made to the properties of the cursor adapter.
nCodePage

Specifies a code page. The default value is zero (0).

Remarks

Applies To: XMLTable Class

ApplyDiffgram is supported only for XMLTable objects in the XMLAdapter Tables collection. ApplyDiffgram disregards XMLField objects when the XMLField Alias property is empty.

Visual FoxPro checks the XMLField Keyfield property when executing ApplyDiffgram.

Tip:
When you use automatic updating, you should set the appropriate XMLField Keyfield properties in the Fields collection to True (.T.) to improve update performance.

Visual FoxPro changes the properties for a custom CursorAdapter as follows:

  • If the Tables Property is empty, Visual FoxPro sets it to the table specified by the cAlias parameter.

  • Visual FoxPro sets the SendUpdates Property to True (.T.).

  • If the DataSource Property is empty, Visual FoxPro sets it to "Native".

  • If the KeyFieldList Property is empty, Visual FoxPro adds key fields only if specified. Otherwise, Visual FoxPro adds all fields.

  • If KeyFieldList is modified, Visual FoxPro sets the WhereType property to Key Fields (DB_KEY or 1).

  • If the UpdatableFieldList Property is empty, Visual FoxPro adds all fields.

  • If the UpdateNameList Property is empty, Visual FoxPro adds all fields and uses the table specified by the cAlias parameter as the base table.

After applying the DiffGram, Visual FoxPro restores all the listed property values to their previous states.

The nCodePage parameter must exist in the list of supported code pages. If nCodePage is zero (0) and the UseCodePage property is False (.F.), the current default code page is used. For more information, see Code Pages Supported by Visual FoxPro and the UseCodePage Property.

The ApplyDiffgram method fails if XPath expressions are used for XMLAdapter or XMLTable objects.

See Also

Other Resources

Methods
XMLTable Object Properties, Methods, and Events
Tables Collection (XMLAdapter)
XMLField Class
Alias Property
CursorAdapter Class
Fields Collection (XMLTable)
CursorAdapter Object Properties, Methods, and Events


Attach Method (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Attach Method (Visual FoxPro)
See Also

Attaches an existing XML Document Object Model (DOM) document or DOM element, and, optionally, XML schema to the XMLAdapter object.

Attach also sets the XMLAdapter IXMLDOMElement property. In addition, if the XML schema is analyzed, Visual FoxPro repopulates the Tables collection with a new set of XMLTable objects and sets the following XMLAdapter properties to appropriate values:

  • XMLName

  • XMLNamespace

  • XMLPrefix

  • IsDiffgram

  • SOM

XMLAdapter.Attach( oDOM [, oSchema ] )

Parameters

oDOM

Specifies an existing Microsoft XML Core Services (MSXML) 4.0 DOM document object or IXMLDOMElement object.
oSchema

Specifies an existing MSXML 4.0 Schema Object Model (SOM) document object, a DOM document object with a schema node as the root element, or IXMLDOMElement object, which represents the schema. If you specify a value for oSchema, Visual FoxPro disregards the value of XMLAdapter XMLSchemaLocation and analyzes the schema. Otherwise, XMLSchemaLocation determines whether XML schema is analyzed.

Remarks

Applies To: XMLAdapter Class

The Attach method facilitates loading returned results from Web services where the data set is usually returned as two IXMLDOMNodes with Item(0) as the schema (oSchema) and Item(1) as the data (oDom). You can attach these two nodes instead of calling LoadXML against a string.

The following property settings affect how the Attach method is executed:

  • DisableEncode

  • MapN19_4ToCurrency

  • NoCpTrans

  • WrapCharInCDATA

  • WrapMemoInCDATA

  • XMLSchemaLocation

See Also

Other Resources

Methods
XMLAdapter Object Properties, Methods, and Events
IXMLDOMElement Property
Tables Collection (XMLAdapter)
XMLField Class
LoadXML Method


AutoFit Method

Visual FoxPro 9.0 Language Reference
AutoFit Method
See Also

Controls the automatic resizing of columns. AutoFit resizes all visible columns at the grid or browse window levels and resizes the individual column at the column level.

Object.AutoFit( )

Return Value

Boolean data type. AutoFit returns True (.T.) if columns are successfully resized and False (.F.) if not successfully resized.

Remarks

Applies To: Grid Control | BROWSE Command | Column Object

You can use AllowAutoColumnFit when you create an object reference for the browse window using the NAME clause in the BROWSE command.

Setting the AllowAutoColumnFit property does not affect resizing performed by AutoFit at either the grid or column level. You can override AllowAutoColumnFit using AutoFit.

For Column objects, AutoFit works only with TextBox controls. When a column resizes, the Resize event for that column fires.

You can prevent the automatic resizing of a particular column by setting the Resizable property of that column to False (.F.).

Hidden grid columns, which have their Visible property set to False (.F.) and have a Width property value of 0, are not resized.

See Also

Other Resources

Methods
AllowAutoColumnFit Property
Resizable Property


AutoOpen Method

Visual FoxPro 9.0 Language Reference
AutoOpen Method
See Also

Executes the CursorFill method with a default of no parameters. When the CursorAdapter object exists in a data environment, the data environment calls AutoOpen automatically from within the DataEnvironment OpenTables method.

CursorAdapter.AutoOpen()

Return Value

Logical data type. AutoOpen returns True (.T.) if successful. Otherwise, AutoOpen returns False (.F.).

Note:
If AutoOpen fails, the DataEnvironment OpenTables method does not report an error. To retrieve error information when AutoOpen returns False (.F.), you must call the AERROR( ) function because Visual Foxpro error handling, such as the ON ERROR command, Error event, and TRY...CATCH...FINALLY command, does not capture this error information.

Remarks

Applies To: CursorAdapter Class

You can override AutoOpen by using the NODEFAULT command and explicitly calling CursorFill.

See Also

Other Resources

Methods
CursorAdapter Object Properties, Methods, and Events
CursorFill Method
AutoOpenTables Property
NODEFAULT Command


Box Method

Visual FoxPro 9.0 Language Reference
Box Method
See Also

Draws a rectangle on a Form object. There are two versions of the syntax.

Object.Box(nXCoord1, nYCoord1, nXCoord2, nYCoord2)
Object.Box(nXCoord2, nYCoord2)

Parameters

nXCoord1, nYCoord1

Specifies the coordinates of the starting point for the rectangle. The ScaleMode method of the form determines the unit of measurement used. If you omit these arguments, the value of CurrentX and CurrentY are used.
nXCoord2, nYCoord2

Specifies the endpoint of the rectangle.

Remarks

Applies To: Form Object | _SCREEN

The width of the lines drawn depends on the DrawWidth property setting. How a rectangle is drawn on the background depends on the settings of the DrawMode and DrawStyle properties. When the Box method is called, the CurrentX and CurrentY properties are set to the endpoint specified by the last two arguments.

See Also

Other Resources

CurrentX, CurrentY Properties
DrawMode Property
DrawStyle Property
DrawWidth Property
ScaleMode Property
Methods
Language Reference


Build Method

Visual FoxPro 9.0 Language Reference
Build Method
See Also

Rebuilds a project or creates an application (.app) file, executable (.exe) file, or dynamic-link library (.dll) from a Visual FoxPro project.

Object.Build([cOutputName] [, nBuildAction] [, lRebuildAll]
[, lShowErrors] [, lBuildNewGUIDs])

Parameters

cOutputName

Specifies the name of the .app, .exe, or .dll file to create. If cOutputName includes a file extension and nBuildAction is omitted, the file extension in cOutputName determines the type of file built. For example, if the extension in cOutputName is ".exe", an executable file is created.
nBuildAction

Specifies that to rebuild a project or generate an .app, .exe, or .dll file. If nBuildAction is specified and cOutPutName does not include an extension, the appropriate extension is added. The following table lists the values for nBuildAction.

nBuildAction FoxPro.h constant Description

1

BUILDACTION_REBUILD

Rebuilds the project. (Default)

2

BUILDACTION_BUILDAPP

Creates an .app file.

3

BUILDACTION_BUILDEXE

Creates an .exe file.

4

BUILDACTION_BUILDDLL

Creates a .dll file.

5

BUILDACTION_BUILDMTDLL

Creates a multithreaded .dll file.
lRebuildAll

Specifies whether to recompile files in the project before creating an .app, .exe, or .dll file. If lRebuildAll is True (.T.), the following files are recompiled:
  • Program files.

  • Format files.

  • Source code in forms, labels, reports, and visual class libraries.

  • Stored procedures in databases.

If lRebuildAll is False (.F.) or is omitted, files in the project are not recompiled before creating the .app, .exe, or .dll file.
lShowErrors

Specifies whether to display compilation errors in an editing window after the build completes. The following table describes the values for lShowErrors.

lShowErrors Description

True (.T.)

Display errors in an editing window for an error (.err) file.

False (.F.) or omitted

Do not display errors.
lBuildNewGUIDs

Specifies whether to generate new registry globally unique identifiers (GUIDs) when creating an .exe or .dll file.
Note:
If nBuildAction is less than 3, Visual FoxPro disregards lBuildNewGUIDs.

The following table describes values for lBuildNewGUIDs.

lShowErrors Description

True (.T.)

Generate new GUIDs.

False (.F.) or omitted

Do not generate new GUIDs.

Return Value

Logical. Build returns True (.T.) if the project is successfully rebuilt or an .app, .exe, or .dll file successfully created without errors; otherwise Build returns False (.F.).

Remarks

Applies To: Project Object

See Also

Other Resources

How to: Build Applications
BUILD APP Command
BUILD DLL Command
BUILD EXE Command
BUILD PROJECT Command
CREATE PROJECT Command
MODIFY PROJECT Command
Refresh Method
Methods
Language Reference


CancelReport Method

Visual FoxPro 9.0
CancelReport Method
See Also

Allows the user or a program to abnormally terminate a report run, similar to pressing Esc.

oReportListener.CancelReport()

Parameters

None.

Return Value

None.

Remarks

Applies To: ReportListener Object.

Using CancelReport, you can terminate a report early. When you invoke this method, the baseclass ReportListener provides necessary cleanup code, for example closing the print queue, after checking to see whether a report is running before attempting its cleanup chores.

Important
If you are debugging report code or handling errors during a report run, you should invoke this method before you issue a CANCEL or QUIT command. You should also check for an active report run in procedures invoked by an ON SHUTDOWN handler. You can use the SYS(2040) function to check for an active report. See SYS(2040) - Detect Report Status for more information.

You can add to Visual FoxPro's internal cleanup code in this method. However, you should provide for the possibility that this method is called by external sources such as error handling routines attempting to exit an application gracefully. For this reason, your code in this method should not fail even if a report is not actively running, similar to ReportListener's native behavior.

For example, if your code sets a global property indicating that a report has failed to run, it should make sure the ReportListener was actually in the process of running a report before setting the flag.

When you invoke CancelReport, normal reporting events continue until the end of the current page. After this, the native cleanup code runs, followed by the AfterReport and UnloadReport events. For more information about the reporting event sequence, and the time period during which you can successfully cancel a report, see Understanding Visual FoxPro Object-Assisted Reporting.

You can check whether a CancelReport call occurred, abnormally terminating the report, by using the SYS(2024) function. For more information, see SYS(2024) - Detect Report Cancellation.

Tip:
You can provide an opportunity for users to cancel a report in this method, but also offer them the choice to continue running the report. Use NODEFAULT in the CancelReport method to continue the report run. The ReportListener User Feedback Foundation Class takes this approach. Refer to the DoMessage Method for the complete text of this class's CancelReport method code. See ReportListener User Feedback Foundation Class for more information.

See Also

Reference

ReportListener Object

Concepts

Handling Errors During Report Runs

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


ChangesToCursor Method

Visual FoxPro 9.0 Language Reference
ChangesToCursor Method
See Also

Creates a table-buffered cursor and populates it with changes, which come from the associated DiffGram.

Note:
ChangesToCursor is supported only for XMLTable objects in the XMLAdapter Tables collection. ChangesToCursor disregards XMLField objects when the XMLField Alias property is empty.

XMLTable.ChangesToCursor( [ cAlias [, lIncludeUnchangedData [, nCodePage ]]] )

Parameters

cAlias

Specifies the alias name for the cursor to be created. The value of cAlias defaults to the XMLTableAlias property, including when cAlias is an empty string ("").
lIncludeUnchangedData

Specifies whether to include unchanged data in the created cursor. The following table lists the values for lIncludeUnchangedData.

lIncludeUnchangedData Description

False (.F.)

(Default) Do not include unchanged data in the created cursor.

True (.T.)

Include unchanged data in the created cursor.
nCodePage

Integer greater than zero (0) specifying a code page. The default value is zero (0).

Remarks

Applies To: XMLTable Class

When mapping binary fields to Character data types, Visual FoxPro fills any remaining white space with 0x00 characters (CHR(0) or zeros) after decoding.

The nCodePage parameter must exist in the list of supported code pages. If nCodePage is zero (0) and the UseCodePage property is False (.F.), the current default code page is used. For more information, see Code Pages Supported by Visual FoxPro and the UseCodePage Property.

If the RespectNesting property of the XMLAdapter is True (.T.), the node for an unchanged record must be an immediate child for the outer table's node. If the table is not nested, the node must be an immediate child for the XMLAdapter node.

The ChangesToCursor method fails if the XMLNameIsXPath property is True (.T.) because it does not support XPath expressions.

See Also

Reference

XMLAdapter Class
XMLNameIsXPath Property
RespectNesting Property

Other Resources

Methods
XMLTable Object Properties, Methods, and Events
Tables Collection (XMLAdapter)
Alias Property


CheckIn Method

Visual FoxPro 9.0 Language Reference
CheckIn Method
See Also

Checks in changes made to a file in a project under source code control.

Object.CheckIn( )

Remarks

Applies To: File Object

True (.T.) is returned if the file is successfully checked in. False (.F.) is returned if the file could not be checked into source code control or the project is not under source code control.

See Also

Other Resources

AddToSCC Method
CheckOut Method
GetLatestVersion Method
RemoveFromSCC Method
UndoCheckOut Method
Methods
Language Reference


CheckOut Method

Visual FoxPro 9.0 Language Reference
CheckOut Method
See Also

Checks out a file in a project under source code control, allowing you to make changes to the file.

Object.CheckOut( )

Remarks

Applies To: File Object

True (.T.) is returned if the file is successfully checked out of source code control. False (.F.) is returned if the file could not be checked out or the project is not under source code control.

See Also

Other Resources

AddToSCC Method
CheckIn Method
GetLatestVersion Method
RemoveFromSCC Method
UndoCheckOut Method
Methods
Language Reference


Circle Method

Visual FoxPro 9.0 Language Reference
Circle Method
See Also

Draws a circle or ellipse on a form.

Object.Circle (nRadius [, nXCoord, nYCoord [, nAspect]])

Parameters

nRadius

Specifies the radius of the circle or ellipse. The ScaleMode property of the form determines the unit of measurement used.
nXCoord, nYCoord

Specifies the coordinates for the center point of the circle or ellipse. The ScaleMode property of the form determines the units of measurement used.
nAspect

Specifies the aspect ratio of the circle. The default value is 1.0, which produces a perfect (nonelliptical) circle. Values greater than 1.0 produce a vertical ellipse; values less than 1.0 produce a horizontal ellipse.

Remarks

Applies To: Form Object | _SCREEN

To control the width of the line used to draw the circle or ellipse, set the DrawWidth property.

To control the way the circle is drawn in the background, set the DrawMode and DrawStyle properties.

To fill a circle, set the FillColor and FillStyle properties of the form.

When the Circle method is invoked, CurrentX and CurrentY are set to the center point arguments, nXCoord, nYCoord.

See Also

Other Resources

BackColor Property
CurrentX, CurrentY Properties
DrawMode Property
DrawStyle Property
DrawWidth Property
FillColor Property
FillStyle Property
ForeColor Property
ScaleMode Property
Methods
Language Reference


Class Browser Methods

Visual FoxPro 9.0 Language Reference
Class Browser Methods
See Also

The following methods are associated with the Class Browser. For more information, see How to: Customize the Class Browser and Class Browser Window.

AddClass( )

Copies a class from one class library (.vcx) file to another. Used after a drag-and-drop operation between instances of the Class Browser and dependent on the oSource property. If the specified class does not exist, a class is created.
AddFile([ cFileName][, lIgnoreRefresh] )

Adds a class library (.vcx) or form (.scx) file to the Class Browser class list. If no parameters are passed, an AddFile dialog box appears by using the Class Browser GetFile( ) method. If lIgnoreRefresh is True (.T.), the Class Browser class list is not refreshed. If you are adding multiple files, you can wait until all classes are added before refreshing the list.
AddIn( cName[, cProgram] [, cMethod] [, cFileFilter] [, cPlatform] [, cComment] )

Installs or removes the specified add-in to the Browser.dbf registration table. The following list describes the parameters available for this method:
  • cName Specifies the name of the add-in. Not case-sensitive; however, when displayed on a menu, the value appears as entered.

  • cProgram Specifies the name of a program (.PRG), form (.scx), application (.APP), executable file (.EXE), or compiled program (.FXP) to run. If no extension is provided, the extension .PRG is assumed.

    Note:
    If this argument is .NULL., the add-in is marked for deletion in Browser.dbf and disabled in the add-in shortcut menu.

  • cMethod Specifies a method name to use as an event hook. If empty, the add-in appears on the menu.

  • cFileFilter Specifies a list of class libraries and forms that enable the add-in. If empty, the add-in is available for all class libraries (.vcx) and forms (.scx).

  • cPlatform Specifies the platform the add-in is available on. If empty, the add-in is available on all platforms supported by Visual FoxPro.

  • cComment Specifies text stored in a memo field in the Browser.dbf.

AddInMenu( )

Expands the menu that displays the registered add-ins.
AddInMethod( cObjMethod )

Executes any registered add-in for the specified object method. Example: To change the default behavior of the Help button in the Class Browser, use the following code:
Copy Code
_OBROWSER.AddInMethod("cmdHelp.click")
AutoRefresh( )

Determines whether to refresh the display by checking for updated class library (.vcx) information in the selected class in the class list, and by checking the total number of records in the class library (.vcx) file being edited. This method runs when the Class Browser form is activated.
BinToInt([ cBinaryValue] )

Returns the integer equivalent of a string representing a binary value. For example, passing this method a cBinaryValue of "11001" would return 25.
CleanUpFile( )

Removes records from the class library (.vcx) file associated with the selected class in the class list.
ClearBrowser( )

Internal use only.
ClearClass([ lClearAll] )

Clears the class cache from memory with the CLEAR CLASS command for a specific class, or all classes displayed if lClearAll is set to True (.T.).
NewClass( )

Creates a subclass of the selected class in the class list.
DeactivateMenu( )

Deactivates the add-in popup menu.
DisplayMenu( tnMenuMode )

Displays the shortcut menu at the current mouse pointer location. If tnMenuMode is 0, the Class Browser form shortcut menu is displayed; if 1, the Class list shortcut menu; if 2, the Member list shortcut menu.
DoAddIn([ cAddInName] )

Executes the specified add-in of the current or specific record of the table with the BROWSER alias.
FileMatch( cFileName, cFileList)

Compares the specified file against the specified file list to determine if the file is one associated with the add-in.
ExportClass([ lShow] [, tcExportToFileName] )

Generates and displays the definition source code of the selected class or the selected file in the class list. The following list describes the parameters available for this method:
  • lShow Specifies whether to display the code. If the parameter lShow is True (.T.), the Class Browser window displays the code.

  • tcExportToFileName Specifies the name of the file to receive the code.

FindClass([ cFind] )

Finds class text within a class.
FormAddObject( oObject[, nXCoord] [, nYCoord] [, lActivateForm] [, lDesignMode][, lNoShow] [, lNoErrors] [, lBuilder] [, oForm] )

Adds an instance of the selected class in the class list to an external form. The following list describes the parameters available for this method:
  • oObject Specifies a reference to the destination container. The values can be either "command" for the Command window, "screen" for the Visual FoxPro desktop, or "new". You can implement these options with the following commands:

    Copy Code
    _oBrowser.FormAddObject("command")
_oBrowser.FormAddObject("-screen")
_oBrowser.FormAddObject("new")
  • nXCoord Specifies the horizontal position of the object inside the container. If no value is passed, the current mouse position is used.

  • nYCoord Specifies the vertical position of the object inside the container. If no value is passed, the current mouse position is used.

  • lActivateForm If True (.T.), the destination form is activated when the object is added to it; if False (.F.), the Class Browser remains active.

  • lDesignMode If True (.T.), the object reference is an object currently in the Form Designer or class designer.

  • lNoShow If True (.T.), the object reference is an object currently in the Form Designer or class designer.

  • lNoErrors Specifies whether errors generated at instantiation are ignored. If False (.F.), errors are displayed in the Class Browser.

  • lBuilder Specifies whether a custom builder is launched after the object is added to a container.

  • oForm Specifies the container to which an object is added. oForm, an optional parameter, is primarily used to contain the host object in design mode.

FormatMethods( cMethods )

Formats the text of generated methods in the display of the class definition code.
FormatProperties( cProperties[, lAddObjectMode] )

Formats the text of generated properties in the display of the class definition source code.
GetFile([ cFileExt] )

Opens the Class Browser GetFile( ) dialog box. The GetFile( ) method is used internally by the Open or Add buttons in the Class Browser. Whenever the Class Browser prompts for a class library (.vcx) or form (.scx), the GetFile( ) method is called internally.
GetTimeStamp([ ntimestamp] )

Returns the character equivalent of a timestamp value. If no parameter is passed, returns the timestamp string of the currently selected file.
IndentText( cCode )

Indents a block of text one tab.
IntToBin([ nInteger] )

Returns a string representing a binary value that is the equivalent of an integer value. For example, passing this method a nInteger of 25 would return "11001".
ModifyClass( )

Opens the selected class in the Class Designer.
MsgBox( cMessage[, nType] [, cTitle] )

Displays the Class Browser message box. Similar to the Visual FoxPro MESSAGEBOX( ) function.
NewFile([ cFileName] [, lOpenFile] )

Creates a new class library (.vcx) file. If no parameters are passed, the Open dialog box is displayed. If parameters are provided, a new class library (.vcx) is created and added to the class list in Class Browser.
OpenFile([ cFileName] )

Opens an existing class library (.vcx) or form (.scx) file. If a file name is not provided, the Open dialog box appears.
ProperBaseClass( cBaseClass )

Returns the base class name in the proper case. For example, "combobox" would return as "ComboBox".
RedefineClass([ cAsClass] [, cClassLoc] )

Changes the parent class of the selected class in the class list.
RefreshButtons( )

Refreshes the Class Browser command buttons based on the file type.
RefreshClassIcon( )

Reloads the class icon from the icon file.
RefreshClassList([ cDefaultClass] [, lIgnoreTable] )

Refreshes the class list.
RefreshClassListSubclass( )

For internal use only.
RefreshFileAttrib( )

Refreshes the file attribute status of the file name associated with the selected class in the class list.
RefreshCaption( )

Refreshes the Class Browser caption of a form.
RefreshDescriptions( )

Internal use only. Refreshes the descriptions of classes and members.
RefreshMembers([ tcDefaultMember] )

Refreshes the Member tabs to display information associated with the selected class in the class list and, if provided, the specified member.
RefreshParentClassBrowser( )

Refreshes the state of the ParentClass Browser toolbar.
RefreshPrefRecNo( )

Refreshes the Browser.dbf preference record pointer for the class library (.vcx) or form (.scx) file being edited.
RefreshRecNo( )

Refreshes the current record pointer of the class library (.vcx) or form (.scx) table for the file of the selected class.
RemoveClass([ lConfirm] )

Removes the selected class in the class list from its associated class library (.vcx) file.
RenameClass([ cToClass] )

Changes the class name of the selected class in the class list.
ResetDefaults( )

Restores original display settings. This method is called when you choose Restore Defaults from the shortcut menu.
SavePreferences( )

Saves current preference settings to the Browser.dbf registration table.
ScaleResize( )

Scales the controls on the Class Browser form to fit after the form is resized using the Resize( ) event.
SeekClass([ cClass][, cClassLibrary] )

Moves the class list pointer to a specific class or index in the class list. Can use the numeric value of the visual position in the class list.
SeekMember( tcMember )

Moves the member list pointer to a specific member.
SeekParentClass( )

Displays the parent class of the selected class in the class list.
SetBusyState( lBusyState )

Sets the lBusyStatus property to True (.T.) or False (.F.) based on the parameter received; also sets the mouse pointer shape to an arrow or hourglass.
SetFont([ cFontName][, nFontSize][, lFontBold][, lFontItalic] )

Sets the font and font size used by the Class Browser for its form, controls, and dialog boxes. If you don't specify a font name or size, SetFont( ) opens the Get Font dialog box.
ShowMenu( aMenu[, cOnSelection] )

Displays a menu based on an array. If a menu is a single-dimension array, this method displays a list of all items in your menu. If the array is two-dimensional with an item and an action, it displays the menu items and when the item is selected, it executes the associated action.
TrimExt( cFileName[, lPlatformType] )

Truncates the file name extension.
TrimFile( cFileName[, lPlatformType] )

Truncates the file name and returns only the file name and path.
TrimPath( cFileName[, lTrimExt] [, lPlatformType] )

Truncates the path name.
UpdateReferences( tcOldClassLoc, tcOldClass, tcNewClassLoc, tcNewClass [, tlAllInstances] )

Used to update references of classes (subclasses and object members) when renaming a class and when moving a class from one class browser to another. The following list describes the parameters available for this method:
  • tcOldClassLoc Specifies the original contents of the ClassLoc field in the .vcx or .scx file.

  • tcOldClass Specifies the original contents of the Class field in the .vcx or .scx file.

  • tcNewClassLoc Specifies the new contents of the ClassLoc field in the .vcx or .scx file..

  • tcNewClass Specifies the new contents of the Class field in the .vcx or .scx file.

  • tlAllInstances If True (.T.) all files in all Class Browser windows are updated. If False (.F.) only the files in the current Class Browser window are updated.

VersionCheck([ lShowErrorMsg] )

Validates the open class library (.vcx) or form (.scx) file.
ViewProperty( cProperty )

Displays the value of a specific property of the selected class.
WildcardMatch( cMatchExpList, cExpressionSearched)

Compares strings for a wildcard match with the filters specified in the Type box.

See Also

Other Resources

Class Browser Object Members
Class Browser Properties
Methods


CleanUp Method

Visual FoxPro 9.0 Language Reference
CleanUp Method
See Also

Cleans up a project table by removing records marked for deletion and packing memo fields.

Object.CleanUp(lRemoveObjectCode)

Parameters

lRemoveObjectCode

Specifies if object code stored in the OBJECT field of the project table is removed. If lRemoveObjectCode is True (.T.), the object code is removed from the table. If lRemoveObjectCode is False (.F.) or is omitted, the object code isn't removed. The OBJECT field contains object code for program (.prg), menu (.mnx), and query (.qpr) files in the project. If the object code stored in the OBJECT field of the project table is removed, the next time the project is rebuilt the source code is compiled and the object code is stored in the OBJECT field again.

Remarks

Applies To: Project Object

Every project has a corresponding table that contains project information. Use the CleanUp method to reduce the size of the table by removing records marked for deletion and packing memo fields. Cleaning up a project table reduces the time it takes to rebuild a large project or create an application file (.app), dynamic link library (.dll), or executable file (.exe) from a large project.

See Also

Other Resources

BUILD APP Command
BUILD DLL Command
BUILD EXE Command
Build Method
BUILD PROJECT Command
CREATE PROJECT Command
MODIFY PROJECT Command
Methods
Language Reference


Clear Method

Visual FoxPro 9.0 Language Reference
Clear Method
See Also

Clears the contents of a ComboBox or ListBox control.

Object.Clear

Remarks

Applies To: ComboBox | ListBox

The Clear method removes all items from a ComboBox or ListBox control, but only if the RowSourceType property is set to 0 (None). Additionally, it sets the ListCount property to 0.

See Also

Other Resources

AddItem Method
RemoveItem Method
RowSourceType Property
Methods
Language Reference


ClearData Method

Visual FoxPro 9.0 Language Reference
ClearData Method
See Also

Clears all data and data formats from the OLE drag-and-drop DataObject object. Available at run time only.

oDataObject.ClearData

Remarks

Applies To: DataObject Object

The ClearData method can only be executed in the OLEStartDrag event; calling the ClearData method from the OLEDragDrop or OLE DragOver events generates an error.

See Also

Other Resources

GetData Method
GetFormat Method
OLE Drag-and-Drop Overview
SetData Method
SetFormat Method
Methods
Language Reference


ClearStatus Method

Visual FoxPro 9.0
ClearStatus Method
See Also Example

Removes the interface elements provided by the DoStatus method.

oReportListener.ClearStatus()

Parameters

None.

Return Value

None.

Remarks

Applies To: ReportListener Object.

The DoStatus method provides modeless feedback for ReportListener objects. Since your program continues running after the DoStatus user interface elements appear, you need a way of removing these elements explicitly. The ClearStatus method provides this service.

Write appropriate code in this method to remove the interface elements your class provides in its DoStatus method. For example, the baseclass ReportListener uses a WAIT NOWAIT window to provide feedback during a report run, so the base class ReportListener ClearStatus method performs the equivalent of a WAIT CLEAR. The ReportListener User Feedback Foundation Class, in contrast, provides a progress bar in a form as report run feedback, so its ClearStatus method removes the form.

Important
Your user interface code should take the setting of the QuietMode property into account, emulating the behavior of the baseclass ReportListener. For more information, see DoStatus Method.

Example

You can invoke DoStatus and ClearStatus at any time, even when a report run is not in progress. In the following example, a ReportListener object adds some custom behavior if a DoStatus call occurs between report runs. When a report run begins, it clears any previous feedback that might be on-screen from any earlier call to DoStatus.
Copy Code
LOCAL oListener
oListener = CREATEOBJECT("messagingReportListener")
oListener.DoStatus()
REPORT FORM ? OBJECT oListener
oListener.DoStatus()
REPORT FORM ? OBJECT oListener
oListener.DoStatus()

DEFINE CLASS messagingReportListener AS ReportListener
   iReportRuns = 0
   ListenerType = 1
   PROCEDURE BeforeReport()
     THIS.iReportRuns = This.iReportRuns + 1
     THIS.ClearStatus()
     DODEFAULT()
   ENDPROC
   PROCEDURE DoStatus(cMessage)
      IF EMPTY(cMessage)
         NODEFAULT
         DODEFAULT("You have run " + ;
                   TRANSFORM(THIS.iReportRuns) + " report(s) so far!")
      ENDIF
   ENDPROC
ENDDEFINE

See Also

Reference

ReportListener Object
DoStatus Method
ReportListener User Feedback Foundation Class

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


CloneObject Method

Visual FoxPro 9.0 Language Reference
CloneObject Method
See Also

Duplicates an object, including all the object's properties, events, and methods. Available only at design time.

Object.CloneObject(NewName)

Parameters

NewName

Specifies the name of the new, or duplicate, object.

Remarks

Applies To: CheckBox Control | ComboBox Control | CommandButton Control | CommandGroup Control | Custom Object | EditBox Control | Grid Control | Image Control | Label Control | Line Control | ListBox Control | OLE Bound Control | OLE Container Control | OptionButton Control | OptionGroup Control | Page Object | PageFrame Control | Shape Control | Spinner Control | TextBox Control | Timer Control | ToolBar Object

See Also

Other Resources

SaveAs Method
SaveAsClass Method
Methods
Language Reference


Close Method (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Close Method (Visual FoxPro)
See Also

Closes a project and releases the project's ProjectHook and Project objects.

Object.Close( )

Remarks

Applies To: Project Object

Executing the Close method causes the project's ProjectHook.Destroy event to occur. After the ProjectHook.Destroy event occurs, the ProjectHook object is released, and then the Project object is released.

See Also

Other Resources

CLOSE Commands
Destroy Event
ProjectHook Object
Methods
Language Reference


CloseTables Method

Visual FoxPro 9.0 Language Reference
CloseTables Method
See Also

Causes the tables and views associated with the data environment to close.

DataEnvironment.CloseTables

Remarks

Applies To: DataEnvironment

Closes the tables and views associated with Cursor objects in the data environment. You can reopen the tables and views by calling the OpenTables method.

See Also

Other Resources

AfterCloseTables Event
AutoCloseTables Property
BeforeOpenTables Event
OpenTables Method
Methods
Language Reference


Cls Method

Visual FoxPro 9.0 Language Reference
Cls Method
See Also

Clears graphics and text from a form.

Object.Cls

Remarks

Applies To: Form Object | _SCREEN

Cls clears text and graphics generated at run time with graphics and printing statements. Background bitmaps created using the Picture property and controls placed on the form at design time are not affected by the Cls method.

The Cls method resets the CurrentX and CurrentY properties to 0.

See Also

Other Resources

Circle Method
CurrentX, CurrentY Properties
Line Method
Picture Property
Methods
Language Reference


CursorAttach Method

Visual FoxPro 9.0 Language Reference
CursorAttach Method
See Also

Attaches an existing cursor to the current instance of a CursorAdapter object.

CursorAdapter.CursorAttach( [ cAlias [, lInheritCursorProperties ] ] )

Parameters

cAlias

Specifies the alias of the cursor or table to be attached. When cAlias is specified, CursorAttach populates the CursorAdapter Alias property with the alias of the attached cursor or table. When cAlias is not specified, CursorAttach attempts to attach the cursor or table, which must exist, specified by the current value of the CursorAdapter Alias property.
lInheritCursorProperties

Specifies whether you wish to keep or discard the properties of the cursor or table being attached. The following table lists the possible values for lInheritCursorProperties.

lInheritCursorProperties Description

True (.T.)

Existing properties set for the cursor are inherited by the corresponding properties of the CursorAdapter object.

False (.F.) or empty

Existing properties set for the cursor are not copied into the corresponding properties of the CursorAdapter object.
This option adds flexibility when you are attaching a SQL Pass-Through, Remote View, or other cursor.

Return Value

Logical data type. CursorAttach returns True (.T.) if the cursor is attached successfully and False (.F.) if attachment fails.

Note:
To retrieve error information when CursorAttach returns False (.F.), you must call the AERROR( ) function because Visual Foxpro error handling, such as the ON ERROR command, Error event, and TRY...CATCH...FINALLY command, does not capture this error information.

Remarks

Applies To: CursorAdapter Class

A cursor or table can have only one instance of a CursorAdapter object attached to it at any given time.

When Visual FoxPro attaches a cursor, you cannot change the cursor or table using the MODIFY STRUCTURE or SQL ALTER TABLE commands.

Calling CursorAttach closes the currently attached cursor. To preserve the currently attached cursor, call CursorDetach first.

Calling CursorAttach populates the Alias property of the CursorAdapter instance with the alias of the attached cursor or table.

Calling CursorAttach turns on BufferModeOverride (3) or BufferModeOverride (5), depending on the BufferModeOverride property for the CursorAdapter object, if not already set. If buffering is already turned on but is less granular than Optimistic Row Buffering, Visual FoxPro promotes buffering to Optimistic Row Buffering.

Visual FoxPro generates error messages under the following conditions:

  • If cAlias cannot be found.

  • If CursorAttach attempts to attach a cursor that is already attached to another instance of CursorAdapter.

The Tables property should not refer to a cursor that was attached to a CursorAdapter object by CursorAttach.

See Also

Reference

GETCURSORADAPTER( ) Function

Other Resources

Methods
CursorAdapter Object Properties, Methods, and Events
Alias Property
ALTER TABLE - SQL Command
BeforeCursorAttach Event
AfterCursorAttach Event
MODIFY STRUCTURE Command
CursorDetach Method
BufferModeOverride Property
How to: Update Remote Data with SQL Pass-Through


CursorDetach Method

Visual FoxPro 9.0 Language Reference
CursorDetach Method
See Also

Frees the currently attached cursor from the current instance of CursorAdapter.

CursorAdapter.CursorDetach()

Return Value

Logical data type. CursorDetach returns True (.T.) if cursor is detached successfully and False (.F.) if not detached successfully.

Note:
To retrieve error information when CursorDetach returns False (.F.), you must call the AERROR( ) function because Visual Foxpro error handling, such as the ON ERROR command, Error event, and TRY...CATCH...FINALLY command, does not capture this error information.

Remarks

Applies To: CursorAdapter Class

Visual FoxPro preserves all settings, such as buffering and so on, available to a normal cursor in the freed cursor.

Visual FoxPro preserves all unsaved changes. For example, you do not need to call the TABLEUPDATE( ) function before detaching the cursor.

See Also

Other Resources

Methods
CursorAdapter Object Properties, Methods, and Events
TABLEUPDATE( ) Function
BeforeCursorDetach Event
AfterCursorDetach Event
CursorAttach Method


CursorFill Method

Visual FoxPro 9.0 Language Reference
CursorFill Method
See Also

Executes the command in the SelectCmd property against the data source in the CursorAdapter DataSource property, creates a cursor, retrieves data, and performs any necessary data conversion according to the CursorAdapter DataSourceType and CursorSchema properties.

CursorAdapter.CursorFill( [ lUseCursorSchema [, lNoData [, nOptions [, Source ] ] ] ] )

Parameters

lUseCursorSchema

The following table lists the values for lUseCursorSchema.

lUseCursorSchema Description

True (.T.)

Uses the schema in the CursorSchema property to create the cursor.

Note:
Visual FoxPro generates error messages when CursorSchema is required but is missing or invalid.

False (.F.) or empty

Does not use the schema in the CursorSchema property to create the cursor.

Instead, CursorFill creates the cursor using the data types as normally determined by Visual FoxPro according to the CursorAdapter DataSourceType property.
lNoData

The following table lists the values for lNoData.

lNoData Description

True (.T.)

Create the cursor but do not fill it with data.

When the CursorAdapter DataSourceType property is "ADO", and SelectCmd contains parameters, CursorFill attempts to evaluate the parameters in SelectCmd. If CursorFill cannot evaluate the parameters, it uses null (.NULL.) values for the parameter values.

When the CursorAdapter DataSourceType property is "XML", CursorFill creates the cursor using the schema in the CursorSchema property, regardless of the value passed to lUseCursorSchema. If CursorSchema is empty or invalid, Visual FoxPro generates an error.

False (.F.) or empty

Create the cursor and fill it with data.
If you specify lNoData for CursorFill, and SelectCmd is a SQL SELECT command against a parameterized view, Visual FoxPro continues to prompt you for parameter input. This action is equivalent to the following statement:
Copy Code
SELECT * FROM "customers in specific country" WHERE 1=0
nOptions

Specifies numeric values or flags for creating the cursor. The values for nOptions are also used for the CursorRefresh method. The following table lists values for nOptions depending on the setting of the CursorAdapter DataSourceType property.

DataSourceType nOptions

"ADO"

An integer representing the Command type or Execution Enum values you want to set for the ActiveX Data Object (ADO) RecordSet Open method. The default value is -1.

"XML"

Any combination of valid XMLTOCURSOR( ) function flags except 8192, which is automatically set when the lUseCursorSchema parameter contains a value of True (.T.).
Source

Specifies a reference to an ADO Command or an open RecordSet object. The ADO Command object must have its ActiveConnection property set to the appropriate and already open ADO Connection object. When an ADO Command object is passed to Source, Visual FoxPro sets the ADO Command CommandText property to value of the CursorAdapter SelectCmd property. Visual FoxPro parses any parameters in SelectCmd, and creates and sets parameter values in the ADO Command object. CursorFill method then executes in the following manner:
Copy Code
CursorAdapter.DataSource.Open( Source,,,,Options )
In this call, DataSource is the ADO RecordSet object in the CursorAdapter DataSource property, and Source is the ADO Command object referenced in this parameter. The ADO RecordSet object must be open when passed to Source, CursorFill executes against the ADO RecordSet object and populates the cursor accordingly. In this case, only the CursorAdapter DataSourceType property must be set to "ADO". The CursorAdapter SelectCmd and DataSource properties are not used. If you do not specify a value for Source, CursorFill executes in the following manner:
Copy Code
CursorAdapter.DataSource.Open( CursorAdapter.SelectCmd,,,,Options )
In this call, DataSource is the ADO RecordSet object in the CursorAdapter DataSource property. However, the ADO RecordSet object directly executes the current CursorAdapter SelectCmd property instead of using an ADO Command object. The ADO RecordSet must have its ActiveConnection property set to a valid ADO Connection object.

Return Value

Logical data type. CursorFill returns True (.T.) if the cursor is created successfully and False (.F.) if not created successfully.

Note:
If CursorFill returns False (.F.), the cursor is discarded. In this case, the BeforeCursorClose and AfterCursorClose events do not occur. To retrieve error information when CursorFill returns False (.F.), you must call the AERROR( ) function because Visual Foxpro error handling, such as the ON ERROR command, Error event, and TRY...CATCH...FINALLY command, does not capture this error information.

Remarks

Applies To: CursorAdapter Class

The following table lists how CursorFill behaves depending on how the CursorAdapter DataSourceType property is set.

DataSourceType SelectCmd property behavior

"Native"

CursorFill executes SelectCmd, which must contain a SelectCmd a valid Visual FoxPro SQL SELECT command.

"ADO"

CursorFill executes SelectCmd by calling the ADO RecordSet Open method. You must therefore set the CursorAdapter DataSource property to a valid ADO RecordSet object. If SelectCmd contains parameters, you must specify a valid ADO Command object in the Source parameter for the CursorFill method

Manually closing the cursor closes the associated ADO RecordSet. However, this does not apply if the cursor was obtained using the CursorAttach method.

CursorFill does not set the ADO RecordSet MaxRecords property to the CursorAdapter MaxRecords property.

"ODBC"

CursorFill executes SelectCmd using the connection handle of the DataSource property of the CursorAdapter object. Visual FoxPro returns the cursor using SQL Pass-Through. The name of the cursor corresponds to the alias obtained by calling This.Alias.

Note:
When several CursorAdapter objects share the same ODBC statement handle, CursorFill might fail for some CursorAdapter objects because another CursorAdapter object has not finished retrieving data. To avoid this situation, set the FetchSize property to 1 for all CursorAdapter objects or use a dedicated ODBC statement handle for each object.

"XML"

One of the following:

  • SelectCmd is an expression that evaluates to a valid XMLTable object. CursorFill calls the XMLTable ToCursor method, and the resulting cursor is attached.

  • SelectCmd is an expression, command, or function that returns XML. CursorFill uses the XMLTOCURSOR( ) function to transform the XML to a cursor. For more information, see the following list of additional remarks.

In addition, when DataSourceType is set to "XML", and SelectCmd is an expression, command, or function that returns XML:

  • The XML requirements are the same as those for the first parameter of the XMLTOCURSOR( ) function. You can specify these requirements by passing the appropriate XMLTOCURSOR( ) nFlags value to the CursorFill nOptions parameter. You can specify additional XMLTOCURSOR( ) flags or combine them as in XMLTOCURSOR( ).

  • CursorFill chooses between eExpression and cXMLFile from XMLTOCURSOR( ) based on nOptions:

    • If nOptions is 0, CursorFill processes XMLSource as eExpression and expects a memory variable containing a valid XML string or an expression that results in an XML string.

    • If nOptions is 512, CursorFill processes XMLSource as cXMLFile and expects a string literal with quotation marks ("") or a memory variable containing a valid file name.

  • The cCursorName parameter in XMLTOCURSOR( ) is always the current value in the Alias property for the CursorAdapter object.

  • If lUseCursorSchema is True (.T.), CursorFill automatically adds the 8192 flag to enforce use of the existing cursor for the XML.

When Visual FoxPro calls CursorFill, it closes the currently attached cursor, if it exists, and the work area that contains the newly created cursor becomes the active work area.

Note:
If you wish to preserve the currently attached cursor, call the CursorDetach method before calling CursorFill.

When Visual FoxPro attaches a cursor, you cannot change the cursor or table using the MODIFY STRUCTURE or SQL ALTER TABLE commands.

See Also

Reference

NoData Property
UseCursorSchema Property
GETCURSORADAPTER( ) Function

Other Resources

Methods
CursorAdapter Object Properties, Methods, and Events


CursorRefresh Method

Visual FoxPro 9.0 Language Reference
CursorRefresh Method
See Also Example

Refreshes a cursor with current data from the data source. CursorRefresh re-executes the value of the SelectCmd parameter in the BeforeCursorRefresh event with respect to CursorAdapter DataSourceType.

Note:
If the SelectCmd parameter in the BeforeCursorRefresh event contains parameters, you can modify the scope of the rows that are returned through the original query by changing the parameters.

CursorAdapter.CursorRefresh()

Return Value

Logical data type. CursorRefresh returns True (.T.) if the cursor is repopulated successfully and False (.F.) if not repopulated successfully.

Note:
To retrieve error information when CursorRefresh returns False (.F.), you must call the AERROR( ) function because Visual Foxpro error handling, such as the ON ERROR command, Error event, and TRY...CATCH...FINALLY command, does not capture this error information.

Remarks

Applies To: CursorAdapter Class

CursorRefresh updates the following properties for the ADO or ODBC-based cursor from the following CursorAdapter properties:

  • AllowSimultaneousFetch

  • CompareMemo

  • FetchAsNeeded

  • FetchMemo

  • FetchSize

  • MaxRecords

  • Prepared

  • UseMemoSize

Visual FoxPro generates an error message when the cursor contains unsaved changes.

If the CursorAdapter DataSourceType property is "ADO" when executing the CursorAdapter CursorFill method, CursorRefresh behaves in the following manner:

  • CursorAdapter object has an attached cursor resulting from executing SelectCmd using CursorFill:

    • Sets the ADO Command CommandText property for the ADO RecordSet ActiveCommand object to the SelectCmd used to open the ADO RecordSet unless CommandText already contains this value.

    • Refreshes the Command object parameters collection and re-evaluates the parameter values.

    • Calls the ADO RecordSet Requery method and passes the same values in the nOptions parameter used by CursorFill to open the ADO RecordSet.

  • CursorAdapter object has an attached cursor resulting from passing an already open ADO RecordSet to the CursorFill Source parameter.

    • Calls the ADO RecordSet Requery method and pass the same value for the nOptions parameter used by CursorFill.

Note:
The CursorRefresh method ignores the MapBinary and MapVarchar properties for mapping data types.

Example

Example 1

The following example illustrates retrieving results using ADO with a parameter and using CursorRefresh to refresh data. The connection string settings for SQL Server (localhost) and Visual FoxPro OLE DB Provider are the following:

Copy Code
* .ConnectionString = 'provider=SQLOLEDB.1;data source=localhost;'+
* 'initial catalog=Northwind;trusted_connection=yes'
CLEAR
LOCAL loConn AS ADODB.CONNECTION, ;
   loCommand AS ADODB.COMMAND, ;
   loException AS EXCEPTION, ;
   loCursor AS CURSORADAPTER, ;
   country, ;
   laErrors[1]
loConn = CREATEOBJECT('ADODB.Connection')
WITH loConn
   .ConnectionString = 'provider=vfpoledb;data source=' + ;
   HOME(2)+'northwind\Northwind.dbc'
   TRY
      .OPEN()
   CATCH TO loException
      MESSAGEBOX(loException.MESSAGE)
      CANCEL
   ENDTRY
ENDWITH
loCommand = CREATEOBJECT('ADODB.Command')
loCommand.ActiveConnection = loConn
loCursor = CREATEOBJECT('CursorAdapter')
WITH loCursor
   .ALIAS          = 'Customers'
   .DATASOURCETYPE = 'ADO'
   .SELECTCMD      = ;
   'select * from customers where country=?lcCountry'
   lcCountry       = 'Brazil'
   .DATASOURCE = CREATEOBJECT('ADODB.Recordset')
   .DATASOURCE.ActiveConnection = loConn
   llReturn = .CURSORFILL(.F., .F., 0, loCommand)
   IF llReturn
      BROWSE
      lcCountry = 'Canada'
      llReturn  = .CURSORREFRESH()
      IF llReturn
         BROWSE
      ENDIF llReturn
   ELSE
      AERROR(laErrors)
      MESSAGEBOX(laErrors[2])
   ENDIF llReturn
ENDWITH

The following example that illustrates using CursorRefresh with an already opened ADO Recordset. The connection string settings for SQL Server (localhost) and the Visual FoxPro OLE DB Provider are:

Copy Code
* .ConnectionString = 'provider=SQLOLEDB.1;data source=localhost;' + ;
* 'initial catalog=Northwind;trusted_connection=yes'
CLEAR
LOCAL loConn AS ADODB.CONNECTION, ;
   loCommand AS ADODB.COMMAND, ;
   loParam AS ADODB.PARAMETER, ;
   loRs AS ADODB.Recordset,;
   loException AS EXCEPTION, ;
   loCursor AS CURSORADAPTER, ;
   lcCountry, ;
   laErrors[1]
loConn = CREATEOBJECT('ADODB.Connection')
WITH loConn
   .ConnectionString = 'provider=vfpoledb;data source=' + ;
      HOME(2)+'northwind\Northwind.dbc'
   TRY
      .OPEN()
   CATCH TO loException
      MESSAGEBOX(loException.MESSAGE)
      CANCEL
   ENDTRY
ENDWITH
loCommand = CREATEOBJECT('ADODB.Command')
loCommand.CommandText = ;
   "SELECT * FROM customers WHERE Country = ?"
loParam = loCommand.CreateParameter("Country", 129, 1, 15, "")
loCommand.PARAMETERS.APPEND(loParam)
loCommand.PARAMETERS("Country") = "Brazil"
loCommand.ActiveConnection = loConn
loRs = loCommand.Execute()
loCursor = CREATEOBJECT('CursorAdapter')
WITH loCursor
   .ALIAS          = 'Customers'
   .DATASOURCETYPE = 'ADO'
   llReturn = .CURSORFILL(.F., .F., 0, loRs)
   IF llReturn
      BROWSE
      loRs.ActiveCommand.PARAMETERS("Country") = "Canada"
      llReturn  = .CURSORREFRESH()
      IF llReturn
         BROWSE
      ENDIF llReturn
   ELSE
      AERROR(laErrors)
      MESSAGEBOX(laErrors[2])
   ENDIF llReturn
ENDWITH

See Also

Other Resources

Methods
CursorAdapter Object Properties, Methods, and Events
BeforeCursorRefresh Event


DataToClip Method

Visual FoxPro 9.0 Language Reference
DataToClip Method
See Also

Copies a set of records as text to the Clipboard.

ApplicationObject.DataToClip([nWorkArea | cTableAlias]
   [, nRecords] [, nClipFormat])

Return Value

nWorkArea

Specifies the work area number of the table for which records are copied to the Clipboard. If you omit cTableAlias and nWorkArea, records are copied to the Clipboard for the table open in the current work area.
cTableAlias

Specifies the alias of the table for which the records are copied to the Clipboard.
nRecords

Specifies the number of records copied to the Clipboard. If nRecords is greater than the number of remaining records in the table, all the remaining records are copied to the Clipboard. If nRecords and nClipFormat are omitted, the current record and all remaining records are copied to the Clipboard.
nClipFormat

Specifies how fields are delimited. The settings for nClipFormat are:

nClipFormat Description

1

(Default) Fields delimited with spaces

3

Fields delimited with tabs
If nClipFormat is omitted, fields are delimited with spaces.

Remarks

Applies To: Application Object | _VFP System Variable

The field names appear as the first line of the text copied to the Clipboard, followed by a separate line for each record.

See Also

Other Resources

Eval Method
SetVar Method
_CLIPTEXT System Variable
Methods
Language Reference


DelayedMemoFetch Method

Visual FoxPro 9.0 Language Reference
DelayedMemoFetch Method
See Also

Performs a delayed Memo field fetch for a target record in a cursor in a CursorAdapter object.

CursorAdapter.DelayedMemoFetch(cMemoName)

Parameters

cMemoName

Specifies the name of the Memo field to be fetched in the current record of the cursor associated with the CursorAdapter object.

Remarks

Applies To: CursorAdapter Class

When the FetchMemo Property is set to False (.F.), the ability to perform a delayed Memo fetch is enabled. A delayed Memo fetch prevents the contents of Memo fields from being updated during CursorFill and CursorRefresh method calls. An attempt to fetch content for a Memo field is done when the application attempts to access that field's value. The following four CursorAdapter members enable you to use delayed Memo fetching.

  • DelayedMemoFetch Method

  • FetchMemoDataSourceType Property

  • FetchMemoDataSource Property

  • FetchMemoCmdList Property

The DelayedMemoFetch method performs a delayed memo fetch for the Memo field cMemoName in the current record. This method will return the contents of the specified Memo field. An error is raised if the data cannot be retrieved.

Note:
For delayed Memo fetch to work with a CursorAdapter, the associated cursor should be opened in exclusive mode.

Note:
The DelayedMemoFetch method should never be called other than to perform a delayed Memo fetch. Under no circumstances should this method change the current record.

To allow access to data in the target record, Visual FoxPro opens a read-only cursor with the target record as the current record. This read-only cursor is opened exclusively, and its alias is contained in the RefreshAlias property. If the RefreshAlias property is empty, then the DelayedMemoFetch method was not invoked by the Visual FoxPro data engine.

You can return the contents of a General field using DelayedMemoFetch. To do so, you need to convert the field contents to a Blob using the CAST( ) Function.

The following sample shows using DelayedMemoFetch to retrieve Memo and General field data from the Northwind Categories table via the Visual FoxPro OLE DB Provider.

Copy Code
CLOSE DATABASES all
CLEAR

LOCAL oCA as CursorAdapter
LOCAL oConn AS ADODB.Connection
LOCAL oRS AS ADODB.Recordset
LOCAL cConnStr,lcNorthwindFile

lcNorthwindFile = HOME()+"Samples\Northwind\northwind.dbc"
cConnStr = [Provider=VFPOLEDB.1;Data Source=&lcNorthwindFile.;Password="";Collating Sequence=MACHINE]

oConn  = createobject('ADODB.Connection')
oConn.Open(cConnStr)
oRS = CREATEOBJECT("ADODB.Recordset")
oRS.ActiveConnection = oConn
oRS.CursorLocation = 3  && adUseClient
oRS.CursorType = 3&& adOpenStatic
oRS.LockType = 3&& adLockOptimistic

oCA=CREATEOBJECT("CADelayedFetch")
oCA.DataSource=oRS

IF !oCA.CursorFill()
AERROR(aerrs)
DISPLAY MEMORY LIKE aerrs
RETURN
ENDIF

GO TOP
BROWSE

DEFINE CLASS CADelayedFetch AS CursorAdapter
FetchMemo=.F.
DataSourceType="ADO"
SelectCmd="SELECT * from categories"
CursorSchema="categoryid i, categoryname c(15), description m, picture g"
UseCursorSchema=.T.

FUNCTION DelayedMemoFetch(cFieldName)
NODEFAULT
IF UPPER(cFieldName)==UPPER("picture")
RETURN CAST(DODEFAULT(cFieldName) as W)
ENDIF
RETURN [Modified value:] + DODEFAULT(cFieldName)
ENDFUNC
ENDDEFINE

See Also

Reference

RefreshAlias Property
FetchMemo Property
FetchMemoDataSource Property
FetchMemoDataSourceType Property
FetchMemoCmdList Property


DeleteColumn Method

Visual FoxPro 9.0 Language Reference
DeleteColumn Method
See Also

Removes a Column object from a Grid control.

Grid.DeleteColumn[(nIndex)]

Parameters

nIndex

Specifies a number referencing the order of Columns in a Grid. If nIndex is not specified, the last Column in the Grid is removed.

Remarks

Applies To: Grid

See Also

Other Resources

AddColumn Method
AddObject Method
RemoveObject Method
Methods
Language Reference


Dock Method

Visual FoxPro 9.0 Language Reference
Dock Method
See Also Example

Positions a ToolBar or Form object along a border of the main Visual FoxPro window or positions a Form object within Visual FoxPro IDE windows or with other forms. To use the Dock method for forms, the form's Dockable property must be set to 1. There are two versions of the syntax.

Toolbar.Dock(nLocation [, X, Y])
Form.Dock(nLocation, [, oForm])

Parameters

nLocation

Specifies the location to dock the toolbar or form. The following table lists the values for nLocation.

nLocation Description FoxPro.h constant

–1

Undocks the toolbar or form.

TOOL_NOTDOCKED

0

Positions the toolbar or form at the top of the main Visual FoxPro window.

TOOL_TOP

1

Positions the toolbar or form at the left side of the main Visual FoxPro window.

TOOL_LEFT

2

Positions the toolbar or form at the right side of the main Visual FoxPro window.

TOOL_RIGHT

3

Positions the toolbar or form at the bottom of the main Visual FoxPro window.

TOOL_BOTTOM

4

Tab docks a form with another window. (Forms only)

TOOL_TAB
X, Y

Specifies the horizontal and vertical coordinates respectively for the toolbar docking position.
oForm

Specifies an object reference to another form for tab or link docking.

Return Value

Logical data type. Dock returns True (.T.) if the item successfully docks. Otherwise, Dock returns False (.F.).

Remarks

Applies To: Form Object | ToolBar

Visual FoxPro does not support docking for top-level forms. Therefore, Visual FoxPro disregards a docked form's ShowWindow property, which determines whether a form is a top-level form and always defaults the property's value to 0.

When calling the Dock method, the Activate and Resize events occur.

You cannot dock items recursively. For example, you cannot dock one form while docking another.

For more information about docking toolbars and forms, see How to: Dock Toolbars and How to: Dock Forms.

Example

The following example uses the CREATEOBJECT( ) function to create a form, sets the Dockable and Visible properties so that the form is dockable and visible, and uses the Dock method to dock the form to the left side of the main Visual FoxPro window.
Copy Code
omyForm = CREATEOBJECT("Form")
omyForm.Dockable = 1
omyForm.Visible = .T.
omyForm.Dock(1)

See Also

Other Resources

Dockable Property
GetDockState Method
AfterDock Event
BeforeDock Event
Docked Property
Undock Event
ADOCKSTATE( ) Function
Methods
Language Reference


DoCmd Method

Visual FoxPro 9.0 Language Reference
DoCmd Method
See Also

Executes a Visual FoxPro command for an instance of the Visual FoxPro application automation server.

ApplicationObject.DoCmd(cCommand)

Return Value

cCommand

Specifies the Visual FoxPro command to execute.

Remarks

Applies To: Application Object | _VFP System Variable

cCommand must evaluate to a legal Visual FoxPro command.

See Also

Other Resources

DO Command
Eval Method
SetVar Method
Methods
Language Reference


DoMessage Method

Visual FoxPro 9.0
DoMessage Method
See Also Example

Provides a modal dialog box when AllowModalMessages is True (.T.), otherwise triggers DoStatus.

oReportListener.DoMessage(cMessage[,nParams[,cTitle])

Parameters

cMessage

Specifies the message shown by the ReportListener object's user feedback mechanism.
nParams

Numeric value specifying dialog box attributes, identical to the values allows in the MESSAGEBOX function.
cTitle

Specifies caption for the dialog box. Like the MESSAGEBOX function, this value defaults to Microsoft Visual FoxPro if you do not include it.

Return Value

None.

Remarks

Applies To: ReportListener Object.

The baseclass ReportListener object uses a MESSAGEBOX dialog box to provide modal feedback. Its second and third parameters are identical to those you use in the MESSAGEBOX function. For more information, see MESSAGEBOX( ) Function.

If you override or augment this method, you should observe the same parameter conventions, as well as additional interface requirements set by the baseclass: respect the values of AllowModalMessages and QuietMode properties when evaluating what type of feedback the method should display. For more information, see MESSAGEBOX( ) Function and QuietMode Property.

Unlike the MESSAGEBOX function, the baseclass ReportListener does not have a fourth argument specifying a numeric Timeout value, and it has no mechanism for responding to a return value. In a class deriving from ReportListener, however, you can opt to implement this functionality, and you can choose how you want to handle the user's response.

For example, the ReportListener User Feedback Foundation Class uses an augmented version of this method to allow users to cancel a report midway through a report run.

Example

The following code shows the way ReportListener User Feedback Class invokes DoMessage to allow users to cancel a report. This class leverages the version of DoMessage implemented by ReportListener Base Foundation Class, its parent. The enhanced method provides a suitable return value, so the User Feedback Class can respond to the user's choice. ReportListener Base Foundation Class's implementation of the DoMessage method is also shown below.

Tip:
Notice that ReportListener Base Foundation Class provides a consistent numeric value for the second parameter when it invokes MESSAGEBOX. If you use the baseclass ReportListener's DoMessage method, and if you do not need to specify dialog box attributes but wish to provide a custom dialog box caption, you should provide a value of 0 for the second parameter, similar to what you see in this example. If you specify a non-numeric value for this parameter (such as .F.), an error occurs.
Copy Code
* UpdateListener class
* (ReportListener User Feedback Foundation Class)
PROCEDURE CancelReport
   IF THIS.IsRunning AND ;
      (THIS.QuietMode OR ;
       (NOT THIS.AllowModalMessages) OR ;
        THIS.DoMessage(;
             OUTPUTCLASS_REPORT_CANCELQUERY_LOC, ;
             MB_ICONQUESTION+MB_YESNO) =  IDYES )
      DODEFAULT()
      IF SYS(2024) = "Y"
         THIS.ThermForm = NULL
         THIS.DoMessage(OUTPUTCLASS_REPORT_INCOMPLETE_LOC, ;
                        MB_ICONEXCLAMATION)
      ENDIF
   ELSE
      NODEFAULT
   ENDIF
ENDPROC

* _ReportListener class
* (ReportListener Base Foundation Class)
PROCEDURE DoMessage(cMessage,iParams,cTitle)
   NODEFAULT
   IF THIS.QuietMode OR ;
   (THIS.IsRunning AND THIS.CommandClauses.NoDialog)
   * to emulate the base class behavior, do both checks,
   * in case the call to DoMessage() occurs
   * before the baseclass sets QuietMode .T. in response
   * to NoDialog at the beginning of the report run,
   * or after the baseclass re-sets QuietMode to .F.
   * at the end of the report run.
      RETURN 0
   ELSE
      IF THIS.AllowModalMessages
         IF VARTYPE(cTitle) = "C"
            RETURN ;
            MESSAGEBOX(TRANS(cMessage), ;
                       VAL(TRANS(iParams)),cTitle)
         ELSE
            RETURN  ;
            MESSAGEBOX(TRANS(cMessage), ;
                       VAL(TRANS(iParams)),THIS.AppName)
         ENDIF
      ELSE
         THIS.DoStatus(cMessage)
         RETURN 0
      ENDIF
   ENDIF
ENDPROC

See Also

Reference

ReportListener Object
DoStatus Method
ReportListener User Feedback Foundation Class
ReportListener Base Foundation Class

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


DoScroll Method

Visual FoxPro 9.0 Language Reference
DoScroll Method
See Also

Scrolls the Grid control to simulate a user clicking the scroll bars.

Grid.DoScroll(nDirection)

Parameters

nDirection

The settings for nDirection are:

Scroll command Scroll action

0

Scroll up

1

Scroll down

2

Scroll page up

3

Scroll page down

4

Scroll left

5

Scroll right

6

Scroll page left

7

Scroll page right

Remarks

Applies To: Grid

The Scrolled event is triggered after the DoScroll method.

See Also

Other Resources

Scrolled Event
Methods
Language Reference


DoStatus Method

Visual FoxPro 9.0
DoStatus Method
See Also

Provides the interface for modeless user feedback such as status messages during a report run.

oReportListener.DoStatus(cMessage)

Parameters

cMessage

Specifies the message shown by the ReportListener object's user feedback mechanism.

Return Value

None.

Remarks

Applies To: ReportListener Object.

Like the DoMessage method provided for modal user feedback in the ReportListener class, DoStatus respects the setting of the QuietMode Property when evaluating if user feedback is appropriate in the current environment. For more information, see QuietMode Property.

The baseclass ReportListener uses a WAIT NOWAIT mechanism to implement DoStatus, but you can override with a different form of modeless user feedback, as shown by the ReportListener User Feedback Foundation Class. Be sure to match your implementation of DoStatus with an appropriate implementation of ClearStatus, to remove your modeless feedback when it no longer applies (for example, at the end of a report run). For more information, see ClearStatus Method.

See Also

Reference

DoMessage Method
ReportListener Object

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


DoVerb Method

Visual FoxPro 9.0 Language Reference
DoVerb Method
See Also Example

Executes a verb on the specified object.

Object.DoVerb[(Verb)]

Parameters

Verb

The verb to execute on the object within the OLE container control. If not specified, the default verb is executed. The value of this argument can be one of the standard verbs supported by all objects or an index of the ObjectVerbs property array. Each object can support its own set of verbs. The following values represent standard verbs supported by every object:

Value Action

0

The default action for the object.

–1

Activates the object for editing. If the application that created the object supports in-place activation, the object is activated within the OLE container control.

–2

Opens the object in a separate application window. If the application that created the object supports in-place activation, the object is activated in its own window.

–3

For embedded objects, hides the application that created the object.

–4

If the object supports in-place activation, activates the object for in-place activation and shows any user interface tools. If the object doesn't support in-place activation, the object doesn't activate, and an error occurs.

–5

If the user moves the focus to the OLE container control, creates a window for the object and prepares the object to be edited. An error occurs if the object doesn't support activation on a single mouse click.

–6

Used when the object is activated for editing to discard all record of changes that the object's application can undo.

Remarks

Applies To: OLE Bound Control | OLE Container Control

If you set the AutoActivate property to 2 (DoubleClick), the OLE container control automatically activates the current object when the user double-clicks the control.

Tip:
Although you can use the name of the verb (edit, open, play, and so on) to specify the verb to use with DoVerb, it is much faster to use the index (0, 1, 2, and so on).

Example

The following example adds an OLE Container control to a form, and uses the OleClass and DocumentFile properties to specify Microsoft Excel as the Automation server and a Microsoft Excel worksheet as the file to edit.

The DocumentFile property specifies a worksheet named Book1.xls in the EXCEL directory on drive C. This example will not work properly if the file and directory specified in the DocumentFile property do not exist; it may be necessary to modify the DocumentFile property to specify an existing directory and worksheet file.

* The DoVerb method is used to activate the worksheet for editing.
Copy Code
*frmMyForm = CREATEOBJECT('form')  && Create a form
*frmMyForm.Closable = .F.  && Disable the Control menu box

frmMyForm.AddObject('cmdCommand1','cmdMyCmdBtn')  && Add Command button
frmMyForm.AddObject("oleObject","oleExcelObject")  && Add OLE object

frmMyForm.cmdCommand1.Visible=.T.  && Display the "Quit" Command button

frmMyForm.oleObject.Visible=.T.  && Display the OLE control
frmMyForm.oleObject.Height = 50  && OLE control height

frmMyForm.Show  && Display the form

frmMyForm.oleObject.DoVerb(-1)  && -1 for Edit

READ EVENTS  && Start event processing

DEFINE CLASS oleExcelObject as OLEControl
   OleClass ="Excel.Sheet"  && Server name
   DocumentFile = "C:\EXCEL\BOOK1.XLS"  && This file must exist
ENDDEFINE

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close form
ENDDEFINE

See Also

Other Resources

OLE Bound Control
OLE Container Control
Methods
Language Reference


Drag Method

Visual FoxPro 9.0 Language Reference
Drag Method
See Also

Begins, ends, or cancels a drag operation.

Control.Drag [(nAction)]

Parameters

nAction

Indicates the action to perform. If you omit nAction, nAction is set to 1. The settings for the Drag method are:

Setting Description

0

Cancel drag operation; restore original position of control.

1

(Default) Begin dragging the control.

2

End dragging — that is, drop the control.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox

Usually, the MouseDown event procedure calls the Drag method to begin the dragging operation.

It's necessary to use the Drag method to control dragging only when the DragMode property of the control is set to 0 (Manual). You can use Drag on a control whose DragMode property is set to 1 (Automatic), but the MouseDown and MouseUp events are not triggered.

If you want the mouse pointer to change while the control is being dragged, use either the DragIcon property or the MousePointer property to define the pointer. The MousePointer property only has an effect if the DragIcon property is not set.

See Also

Other Resources

DragDrop Event
DragIcon Property
DragMode Property
MousePointer Property
Move Method
Methods
Language Reference


Draw Method

Visual FoxPro 9.0 Language Reference
Draw Method
See Also

Repaints a Form object.

Object.Draw

Remarks

Applies To: Form | _SCREEN

See Also

Other Resources

Paint Event
Methods
Language Reference


Eval Method

Visual FoxPro 9.0 Language Reference
Eval Method
See Also

Evaluates an expression and returns the result for an instance of the Visual FoxPro application automation server.

ApplicationObject.Eval(cExpression)

Return Value

Character, Numeric, Currency, Date, or Logical

Return Value

cExpression

Specifies the expression to evaluate. cExpression can be a literal character string, or a valid Visual FoxPro expression, variable, array element, or field of any data type, enclosed in quotation marks.

Remarks

Applies To: Application Object | _VFP System Variable

cExpression must be a legal Visual FoxPro character expression.

See Also

Other Resources

DoCmd Method
SetVar Method
Methods
Language Reference


GetData Method

Visual FoxPro 9.0 Language Reference
GetData Method
See Also

Retrieves data from the OLE drag-and-drop DataObject object. Available at run time only.

oDataObject.GetData(nFormat | cFormat [, @ArrayName])

Parameters

nFormat| cFormat

Specifies the format of the data to retrieve. The following table lists the values for each data format and a description of each format. The DataObject automatically supports the following formats (more formats are available, but these may require additional programming to use). For more information about the data formats available, see the documentation for Visual C++® on the Microsoft Developer Network.

Data format* nFormat| cFormat Description

CF_TEXT

1

Text format.

CF_OEMTEXT

7

Text format containing characters in the OEM character set.

CF_UNICODETEXT

13

Unicode text format

Note:
Available only for versions of Visual FoxPro running on Windows NT 4.0 or later.

CF_FILES or CF_HDROP

15

A handle that identifies a list of files, such as a set of files dragged from the Windows Explorer.

CF_LOCALE

16

A handle to the locale identifier associated with text on the clipboard.

CFSTR_OLEVARIANTARRAY

"OLE Variant Array"

A Visual FoxPro array. Multiple values can be transferred in a single drag and drop operation with this format.

For example, this format can be used to drag a set of items in a list box to another list box.

CFSTR_OLEVARIANT

"OLE Variant"

A Visual FoxPro variant. All data types in Visual FoxPro are represented as variants. This format can be used to drag and drop Visual FoxPro data without losing the data type.

CFSTR_VFPSOURCEOBJECT

"VFP Source Object"

A reference to a Visual FoxPro object.
* Defined in FOXPRO.H.
@ArrayName

Specifies the name of the array in which the data is stored when the data can contain multiple values. The only data formats in which the data can contain multiple values are CF_FILES, CF_HDROP, and CFSTR_OLEVARIANTARRAY. For example, you can drag a set of files from the Windows Explorer onto a Visual FoxPro list box. Use the GetData method in the OLEDragDrop event of the list box to place the names of the files into an array, then use the AddItem method in a FOR ... ENDFOR loop to add the contents of the array to the list box. The array must exist before you can specify its name in the GetData method. If the array exists and isn't large enough to contain the data, Visual FoxPro automatically increases the size of the array. If the array is larger than necessary, Visual FoxPro truncates the array.

Remarks

Applies To: DataObject Object

The value returned by the GetData method is determined by the format of the data specified with nFormat or cFormat. False (.F.) is returned if the DataObject doesn't contain data in the format you specify with nFormat or cFormat. True (.T.) is returned when the data is in a multiple value format such as CF_FILES, CF_HDROP, or CFSTR_OLEVARIANTARRAY. The data on the DataObject is returned when the data is in a single value format such as CF_TEXT, CFSTR_OLEVARIANT, or CFSTR_VFPSOURCEOBJECT.

The OLESetData event for a drag source is triggered if the data format you specify with nFormat or cFormat exists, but there is no data in the DataObject for that format. (The SetFormat method can be used to specify a data format before the corresponding data is placed on the DataObject with the SetData method.)

See Also

Other Resources

ClearData Method
GetFormat Method
OLE Drag-and-Drop
OLESetData Event
SetData Method
SetFormat Method
Methods
Language Reference


GetDockState Method

Visual FoxPro 9.0 Language Reference
GetDockState Method
See Also

Returns information in an array about the dock state of a form.

Note:
To use GetDockState, the form's Dockable property must be set to 1.

Form.GetDockState(ArrayName)

Parameters

ArrayName

Returns a single row, six-column array containing dock information for a form.
Note:
You must first create the array before passing an array name.

The following table describes the array returned by GetDockState.

Column Description

1

Name of the docking form.

2

Dock state:

1 - Docked

2 - Not docked

3

Dock position.

For values, see DockPosition Property.

4

Target form, or caption of the form to which the specified form is docked.

5

Object reference for the docking form.

6

Object reference for the target window or form.

Return Value

Applies To: Form Object

Logical data type. GetDockState returns True (.T.) if the array is successfully updated with the dock state. Otherwise, GetDockState returns False. (.F.).

Remarks

If a form is docked to an IDE window, the value of column 6 will be an empty string. If a form is docked to the Visual FoxPro desktop, then column 6 will contain an object reference to _SCREEN.

GetDockState is a limited variation of the ADOCKSTATE( ) function in that it limits its details to the current form. Since GetDockState is a limited subset of the ADOCKSTATE( ) function, it may not provide all the necessary information about the current docking state of the form. You may need to call ADOCKSTATE( ) as well to obtain more complete picture. For more information, see ADOCKSTATE( ) Function.

See Also

Reference

GetDockState Method

Other Resources

How to: Dock Forms
Dock Method
Dockable Property
Docked Property
DockPosition Property
AfterDock Event
BeforeDock Event
UnDock Event
Methods


GetFormat Method

Visual FoxPro 9.0 Language Reference
GetFormat Method
See Also

Determines if data in a specified format is available on the OLE drag-and-drop DataObject. Available at run time only.

oDataObject.GetFormat(nFormat | cFormat)

Parameters

nFormat| cFormat

Specifies the format of the data to retrieve. The following table lists some of the formats with a description of each format. For more information about the data formats available, see the documentation for Visual C++ on the Microsoft Developer Network. You can also create your own format by specifying a unique character string for cFormat.

Data Format* nFormat| cFormat Description

CF_TEXT

1

Text format.

CF_OEMTEXT

7

Text format containing characters in the OEM character set.

CF_UNICODETEXT

13

Unicode text format.

Note:
Available only for versions of Visual FoxPro running on Windows NT 4.0 or later.

CF_FILES or CF_HDROP

15

A handle that identifies a list of files, such as a set of files dragged from the Windows Explorer.

CFSTR_OLEVARIANTARRAY

"OLE Variant Array"

An array. Multiple values can be transferred in a single drag and drop operation with this format.

For example, this format can be used to drag a set of items in a list box to another list box.

CFSTR_OLEVARIANT

"OLE Variant"

A variant. All data types in Visual FoxPro are represented as variants. This format can be used to drag and drop Visual FoxPro data without losing the data type.

CFSTR_VFPSOURCEOBJECT

"VFP Source Object"

A reference to the Visual FoxPro drag source object.
* Defined in FOXPRO.H.

Remarks

Applies To: DataObject Object

The GetFormat method returns true (.T.) if the DataObject contains data in the format you specify with nFormat or cFormat; otherwise returns false (.F.).

See Also

Other Resources

ClearData Method
GetData Method
OLE Drag-and-Drop
SetData Method
SetFormat Method
Methods
Language Reference


GetKey Method

Visual FoxPro 9.0 Language Reference
GetKey Method
See Also Example

Returns the key or index of an item in a collection depending on the value that is passed.

Collection.GetKey(eIndex)

Parameters

eIndex

Specifies a required expression that represents a position of an item in the collection. This expression can be one of two types:
  • Numeric. The eIndex expression must have a value from 1 to the value of the Count property of the collection.

  • String. The eIndex expression must correspond to the cKey that was specified for the item when it was added to the collection.

Return Value

The following table lists the return values for GetKey.

Return value | Condition
String (key) | When passing an index or integer value
Integer (index) | When passing a key or string
Empty string ("") | When passing an index that does not exist or if items were added to the collection without keys
0 | When passing a key that does not exist

Remarks

  • Because the GetKey method returns a value, you need to add a RETURN statement to the end of GetKey in the source code for any subclass you have modified. For example:

    Copy Code
    RETURN DODEFAULT( eIndex )
    If you do not want to return the value, use the RETURN command without the DODEFAULT() function.

  • To determine if keys were specified when items were added to the collection, you can use the statement GetKey(1) and the EMPTY() function to check for an empty return value as follows:

    Copy Code
    ? !EMPTY(Collection.GetKey(1))
  • To derive the index or key from an item in a collection from within a FOR EACH loop, use a normal FOR loop instead of a FOR EACH loop.

  • Visual FoxPro generates an error if the wrong type or no parameter is passed to GetKey.

Example

The following example illustrates the following tasks after creating a collection and adding items:

  • Check if items have keys.

  • Retrieve and display key for the second item.
Copy Code
CLEAR
LOCAL oItems AS Collection

oItems = NEWOBJECT("Collection")
oItems.Add("Daffodils", "flower2")
oItems.Add("Roses", "flower1", "flower2")
oItems.Add("Daisies", "flower3")
? !EMPTY(oItems.GetKey(1))
? oItems.GetKey(2)

See Also

Other Resources

Collection Object Properties, Methods, and Events
Collection Class
Count Property
Methods
RETURN Command
DODEFAULT( ) Function
FOR EACH ... ENDFOR Command
FOR Loops


GetLatestVersion Method

Visual FoxPro 9.0 Language Reference
GetLatestVersion Method
See Also

Gets the latest version of a file in a project from source code control and copies a read-only version to your local drive.

Object.GetLatestVersion( )

Remarks

Applies To: File Object

The GetLatestVersion method does not check the file out.

True (.T.) is returned if source code control can successfully get the file. False (.F.) is returned if source code control cannot get the file or the project is not under source code control.

See Also

Other Resources

AddToSCC Method
CheckIn Method
CheckOut Method
RemoveFromSCC Method
UndoCheckOut Method
Methods
Language Reference


GetPageHeight Method

Visual FoxPro 9.0
GetPageHeight Method
See Also Example

Returns page height in 960 dots per inch (dpi) during a report run.

iPageHeight = oReportListener.GetPageHeight()

Parameters

None.

Return Value

Integer data type, the height of the page in 1/960ths of an inch. Between report runs, this method returns 0.

Remarks

Applies To: ReportListener Object.

This method and GetPageWidth allow a preview object or any other “participant” in the output process to interrogate the ReportListener object for the dimensions of page output, as determined by the printer settings in force for the report run. The ReportListener's PreviewContainer uses these methods when the ReportListener object calls its Show method, to determine how to display the current report's contents.

These methods provide usable values at all points in the reporting process after BeforeReport and before UnloadReport, unless you invoke continuation by using NOPAGEEJECT on your REPORT FORM command. If you use NOPAGEJECT, these methods continue to provide usable results until a REPORT FORM without NOPAGEEJECT arrives at its UnloadReport event. At other times, both methods return 0.

Note:
The time period during which GetPageHeight and GetPageWidth provide usable values is determined by when the ReportListener sets up the page layout and print job. The ReportListener does not re-evaluate page layout and page dimensions between REPORT FORM commands when you use NOPAGEJECT since these report runs are part of a single print job. However, you can create classes derived from ReportListener that can handle multiple page sizes during a continued report run.

For more information about the sequence of events at the beginning and end of a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

Example

You can override this method to provide custom page size information.

Important
Providing different information to the ReportListener's rendering mechanism will not send page size instructions to your printer. When a printer receives the information for each page, and when the information it receives does not match its anticipated page format, it has latitude to determine how it will handle the output data. For example, it can stretch the output data for a short page until it fits the expected paper size. However, overriding this method with different instructions can provide significant functionality to other forms of output not dependent on fixed physical page sizes, such as HTML.

In the following example, an object derived from the ReportListener class overrides GetPageHeight according to the value of a custom property. The example shows a preview of two report runs with different page heights, and uses the ReportListener DoMessage method and OutputPageCount property, to show you that the two report runs for the same report have different numbers of pages.

Copy Code
LOCAL loReportListener, lcFRX

lcFRX = GETFILE("frx")
IF EMPTY(lcFRX)
   RETURN
ENDIF

loReportListener = CREATEOBJECT("halfSizePage")

REPORT FORM (lcFRX) OBJECT loReportListener
loReportListener.DoMessage("This report run was: " + ;
    TRANSF(loReportListener.OutputPageCount) + " pages long.")

loReportListener.wantHalfSizePage = .T.

REPORT FORM (lcFRX) OBJECT loReportListener
loReportListener.DoMessage("This report run was: " + ;
    TRANSF(loReportListener.OutputPageCount) + " pages long.")

DEFINE CLASS halfSizePage As ReportListener
   ListenerType = 1
   AllowModalMessages = .T.
   wantHalfSizePage = .F.

   PROCEDURE GetPageHeight()
     LOCAL liSize
     liSize = DODEFAULT()
   RETURN IIF(THIS.wantHalfSizePage, liSize/2, liSize)
ENDDEFINE

See Also

Reference

ReportListener Object
GetPageWidth Method
PreviewContainer Property
The Preview Container API

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


GetPageWidth Method

Visual FoxPro 9.0
GetPageWidth Method
See Also

Returns page width in 960 dots per inch (dpi) during a report run.

iPageWidth = oReportListener.GetPageWidth()

Parameters

None.

Return Value

Integer data type, the width of the page in dots per inch. Between report runs, this method returns 0.

Remarks

Applies To: ReportListener Object.

This method and GetPageHeight allow a preview object or any other “participant” in the output process to interrogate the ReportListener object for the dimensions of page output, as determined by the printer settings in force for the report run. The ReportListener's PreviewContainer uses these methods when the ReportListener object calls its Show method, to determine how to display the current report's contents.

These methods provide usable values at all points in the reporting process after BeforeReport and before UnloadReport, unless you invoke continuation by using NOPAGEEJECT on your REPORT FORM command. If you use NOPAGEJECT, these methods continue to provide usable results until a REPORT FORM without NOPAGEEJECT arrives at its UnloadReport event. At other times, both methods return 0.

Note:
The time period during which GetPageHeight and GetPageWidth provide usable values is determined by when the ReportListener sets up the page layout and print job. The ReportListener does not re-evaluate page layout and page dimensions between REPORT FORM commands when you use NOPAGEJECT since these report runs are part of a single print job. However, you can create classes derived from ReportListener that can handle multiple page sizes during a continued report run.

For more information about the sequence of events at the beginning and end of a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

For illustrative sample code and comments about appropriate usage, see GetPageHeight Method.

See Also

Reference

ReportListener Object
PreviewContainer Property
The Preview Container API

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


GridHitTest Method

Visual FoxPro 9.0 Language Reference
GridHitTest Method
See Also

Returns, as output parameters, the components of a grid control corresponding to specified horizontal (X) and vertical (Y) coordinates.

Grid.GridHitTest(nXCoord_In, nYCoord_In
   [, nWhere_Out [, nRelRow_Out [, nRelCol_Out [, nView_Out]]]])

Parameters

nXCoord_In

Specifies the horizontal (X) position in pixels within the form containing the grid.
nYCoord_In

Specifies the vertical (Y) position in pixels within the form containing the grid.
nWhere_Out

An output parameter that contains a value corresponding to the grid component at the position specified with nXCoord_In and nYCoord_In. The following table lists the values for @nWhere_Out and the corresponding grid component.

@nWhere_Out Grid component

0

A grid component that cannot be determined.

1

Column header.

2

Between column headers.

3

Cell.

4

Reserved.

5

SplitBar.

6

Record deletion marker.

7

Reserved

8

Reserved.

9

Reserved.

10

Reserved.

11

Box in upper left corner.

12

Record marker.

13

Column header sizing area.

14

Row sizing area.

15

Reserved.

16

Horizontal scrollbar.

17

Vertical scrollbar.
nRelRow_Out

An output parameter containing the relative grid row at the specified point.
nRelCol_Out

An output parameter containing the relative grid column at the specified point.
nView_Out

An output parameter containing a value corresponding to the grid pane containing the specified point. If the grid is split into two panes, this parameter contains 0 if the specified point is in the left pane, and contains 1 if the specified point is in the right pane. If the grid isn't split into separate panes, this parameter contains 1.

Remarks

Applies To: Grid Control

The GridHitTest( ) method returns true (.T.) if the specified point is within the grid; otherwise false (.F.) is returned.

The GridHitTest( ) method can be used during mouse events or OLE drop target events to determine where the mouse pointer is positioned over the grid. The nRelRow_Out and nRelCol_Out parameters can be passed to the ActivateCell( ) method to activate a specific cell in the grid.

See Also

Other Resources

ActivateCell Method
ActiveColumn Property
ActiveRow Property
MCOL( ) Function
MROW( ) Function
Methods
Language Reference


Help Method

Visual FoxPro 9.0 Language Reference
Help Method
See Also

Opens the Help window.

ApplicationObject.Help([cFileName] [, nContextID] [, cHelpTopic])

Parameters

cFileName

Specifies the name of the Help file to open. Include a path with the Help file name if the Help file isn't in the default directory.
nContextID

Specifies the Help topic to display, based on the topic's context ID. nContextID is a context number in the MAP section of the help project file.
cHelpTopic

Specifies the Help topic to display. If you include just a partial spelling of a topic title, Visual FoxPro opens the Help window and displays the topic with the closest matching title.

Remarks

Applies To: Application Object | _VFP System Variable

If none of the optional arguments are included, the main Help topic is displayed.

See Also

Other Resources

HELP Command
SET HELP Command
Methods
Language Reference


Hide Method

Visual FoxPro 9.0 Language Reference
Hide Method
See Also

Hides a form, form set, or toolbar by setting the Visible property to false (.F.).

Object.Hide

Remarks

Applies To: Form | FormSet | _SCREEN | ToolBar

Controls on a hidden form are not accessible to the user, but are still available and can be accessed in code. Although they are not visible, controls contained in an invisible form retain their own Visible property setting.

When the Visible property of the form set is set to false (.F.), the user cannot see the Forms it contains. Forms in a hidden form set are not accessible to the user, but are still available and can be accessed in code. The Hide method for a form set does not set the Visible property of its child Forms, so when a form is contained in a form set, you must check the Visible property settings of both the form and form set to determine if the form is visible.

After a form set is hidden, Visual FoxPro activates the last active object. If no objects were active before the form set, the main Visual FoxPro window becomes active.

Calling the Hide Method for the _SCREEN system variable has no effect.

See Also

Other Resources

Activate Event
Deactivate Event
Enabled Property
GotFocus Event
Show Method
Visible Property
Methods
Language Reference


IncludePageInOutput Method

Visual FoxPro 9.0
IncludePageInOutput Method
See Also Example

Allows ReportListener to specify output page ranges.

? oReportListener.IncludePageInOutput(iPage)

Parameters

iPage

Specifies the page number for which the ReportListener indicates rendering will, or will not, occur.

Return Value

Logical data type.

Returns True (.T.) if the parameter you pass identifies a page in the current set of pages to be rendered.

Remarks

Applies To: ReportListener Object.

The native ReportListener class uses the two RANGE arguments of the REPORT FORM command to return a value for this method. These two arguments are represented in its CommandClauses member object as CommandClauses.RangeFrom and CommandClauses.RangeTo.

However, derived classes can support more finely-tuned ranges such as 1-10,16,20 and return different values from IncludePageInOutput.

Important
The native ReportListener uses this method to evaluate which pages are rendered for output results, but not which records or pages are actually processed. During a report run, all records and pages appropriate to your scope clauses are always processed, even when not all pages are included in output. This rule ensures that, even if you specify a limited page range for output, your calculated expressions, such as page numbers and summary totals, are correct.

Because the Report System needs to evaluate the full scope to provide the correct results, the ReportListener does not invoke this method on its preliminary pass if performing a multi-pass report run. However, your derived class can invoke this method at any time, to evaluate the need for its own actions during the preliminary pass. For more information, see TwoPassProcess Property.

If the user invokes printing from a report preview, using ReportListener's OnPreviewClose method, the pages that print do not necessarily match the results from IncludePageInOutput. The printed pages can be determined either by a user's changes to print range using the REPORT FORM command's PROMPT dialog box or by a dynamic change to the ReportListener's CommandClauses members provided for this purpose: PrintPageCurrent, PrintRangeFrom, and PrintRangeTo. The printed pages may be any subset of the full output page range. For more information, see CommandClauses Property.

Example

The following example shows an object derived from ReportListener evaluating whether to include a page in output using criteria specific to its class.
Copy Code
PROC IncludePageInOutput(nPageNo)
   LOCAL lInclude
      FOR EACH oRangeObject in THIS.MyRangeCollection
            IF oRangeObject.Includes(nPageNo)
                lInclude = .T.
                EXIT
           ENDIF
      END FOR
   RETURN lInclude
ENDPROC

See Also

Reference

ReportListener Object
OutputPageCount Property
OnPreviewClose Method

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


IndexToItemID Method

Visual FoxPro 9.0 Language Reference
IndexToItemID Method
See Also

Returns an ItemID for a given Index number.

Control.IndexToItemID(nIndex)

Parameters

nIndex

Specifies a number that represents the position that an item is displayed in a control.

Return Value

The following table lists the return values for IndexToItemID Method.

Return value | Condition
nItemID | Returns an ItemID for a given Index number.

Remarks

Applies To: ComboBox | ListBox

Each item added to a ComboBox or ListBox has two identification numbers assigned to it:

  • The nItemID, a unique identification number.

  • The nIndex, an integer corresponding to the order in which items are displayed by the control: The first item in the list corresponds to nIndex = 1.

Initially, as items are added to the control, these two numbers are identical. But as items are sorted, removed, and added, these numbers are no longer identical.

Use the IndexToItemID method to return the nItemID number for a particular item in the control when you know its nIndex number.

See Also

Other Resources

Methods
AddItem Method
AddListItem Method
ItemIDToIndex Method


Item Method (Collection Class)

Visual FoxPro 9.0 Language Reference
Item Method (Collection Class)
See Also Example

Returns a specific member object in the collection by numeric position or string key.

The member object can have any valid type that can be assigned to a memory variable. This includes simple data types, such as strings, numbers, dates, logical, or more complex ones such as Visual FoxPro and Component Object Model (COM) objects. The Item method for collection objects is typically used with FOR EACH...ENDFOR enumerations to reference members of the collection.

Collection.Item( eIndex )

Parameters

eIndex

Specifies a required expression that represents a position of an item in the collection. This expression can be one of two types:
  • Numeric. The eIndex expression must have a value from 1 to the value of the Count property for the collection.

  • String. The eIndex expression must correspond to the cKey that was specified for the item when it was added to the collection.

If eIndex does not match an existing member of the collection, an error occurs.

Return Value

Returns the specific item.

Remarks

If an incorrect type is passed for a specific parameter, an error occurs.

The Item method for collection objects returns a value, which is the item itself. Therefore, you need to add a RETURN statement to the end of the Item method in the source code for any subclass you have modified:

Copy Code
RETURN DODEFAULT(eIndex)

If you do not want to return the item, use the RETURN statement without the DODEFAULT() function.

The Item method for collection objects is the default method for a collection. For example, suppose you have the following code:

Copy Code
Public MyCollection AS Collection
MyCollection = CREATEOBJECT("Collection")
MyCollection.Add(CREATEOBJECT("Form"),"myKey")

The following lines of code are equivalent:

Copy Code
? MyCollection(1)
? MyCollection.Item(1)
? MyCollection("myKey")

Example

The following example illustrates these tasks at run time:

  • Creates forms and a collection.

  • Adds forms to the collection.

  • Displays the name of each form in the collection.

  • Displays the number of forms in the collection.

  • Displays the name of the first item in the collection.

  • Displays the name of the first item in the collection using the Item method for collections.
Copy Code
loForm1 = CREATEOBJECT("myForm1")
loForm2 = CREATEOBJECT("myForm2")
loCol = CREATEOBJECT("myCollection")
loCol.Add(loForm1)
loCol.Add(loForm2)
? loCol(1).Name
? loCol.Item(1).Name

See Also

Other Resources

Collection Object Properties, Methods, and Events
Methods
Collection Class
FOR EACH ... ENDFOR Command
RETURN Command
DODEFAULT( ) Function


Item Method (File Object)

Visual FoxPro 9.0 Language Reference
Item Method (File Object)
See Also

Returns an object reference to a specified file, project, or server in a files, projects, or servers collection.

Object.Item(nIndex)

Remarks

nIndex

A number that specifies a file, project, or server in a files, projects, or servers collection. An "Invalid subscript reference" error is generated if nIndex is greater than the number of files, projects, or servers in a collection.

Remarks

Applies To: Files Collection | Projects Collection | Servers Collection

Use the Name property with the Item property to determine the name of a file, project, or server and the directory in which it is contained.

See Also

Other Resources

Name Property
Methods
Language Reference


ItemIDToIndex Method

Visual FoxPro 9.0 Language Reference
ItemIDToIndex Method
See Also

Returns the value of nIndex, the position of an item in a control's list.

 [nIndex =]Control.ItemIDToIndex(nItemID)

Parameters

nItemID

The unique identification number associated with that item.

Remarks

Applies To: ComboBox | ListBox

Each item added to a combo box or list box has two numbers assigned to it:

  • The nItemID, a unique identification number.

  • The nIndex, an integer corresponding to the order in which items are displayed by the control. The first item in the list corresponds to nIndex = 1.

Initially, as items are added to the control, these two numbers are identical. But as items are sorted, removed, and added, these numbers are no longer identical.

Use the ItemIDToIndex method to retrieve the nIndex number for a particular item in the control's list when you know its nItemID number.

See Also

Other Resources

AddItem Method
AddListItem Method
IndexToItemID Method
ListItemID Property
List Property
ListCount Property
Methods
Language Reference


Line Method

Visual FoxPro 9.0 Language Reference
Line Method
See Also

Draws a line on a Form object. There are two versions of the syntax.

Object.Line(nXCoord2, nYCoord2)
Object.Line(nXCoord1, nYCoord1, nXCoord2, nYCoord2)

Parameters

nXCoord1, nYCoord1

Specifies the coordinates of the starting point of the line. The unit of measurement is specified by the ScaleMode property of the form.
nXCoord2, nYCoord2

Specifies the coordinates of the endpoint of the line.

Remarks

Applies To: Form | _SCREEN

The width of the line drawn depends on the setting of DrawWidth property. The way a line is drawn on the background depends on the setting of the DrawMode and DrawStyle properties. After the Line method runs, the CurrentX and CurrentY properties are set to nXCoord2, nYCoord2.

See Also

Other Resources

CurrentX, CurrentY Properties
DrawMode Property
DrawStyle Property
DrawWidth Property
ScaleMode Property
Methods
Language Reference


LoadXML Method

Visual FoxPro 9.0 Language Reference
LoadXML Method
See Also

Loads XML from a file or string into a Document Object Model (DOM) document and attaches it to the XMLAdapter object.

XMLAdapter.LoadXML( cXMLDocument [, lFile [, lValidateOnParse ]] )

Parameters

cXMLDocument

Specifies an XML file name, XML string, or expression that evaluates to a valid XML file name or string.
lFile

Specifies whether cXMLDocument is a file name. The default value of lFile is False (.F.).
lValidateOnParse

Specifies whether the XML should be validated upon parsing. The default value of lValidateOnParse is True (.T.). For more information about how DOM performs validation, see the Microsoft XML Core Services (MSXML) 4.0 SDK on the MSDN Library Web site at http://msdn.microsoft.com/library/.

Remarks

Applies To: XMLAdapter Class

LoadXML sets the XMLAdapter IXMLDOMElement property. In addition, if the XML schema is analyzed, Visual FoxPro populates the Tables collection with a new set of XMLTable objects and sets the XMLAdapter XMLName, XMLNamespace, XMLPrefix, IsDiffgram, and SOM properties to appropriate values.

If the RespectNesting property of the XMLAdapter object is True (.T.), the LoadXML method preserves the XML hierarchy within the document. However, the method ignores the top level element declaration if that element is referenced from some other complex element. In that case, the method nests the XMLTable object for the referenced element into the XMLTable object for the element that has a reference to it.

If the XML document is not formatted as a Visual Studio dataset, then the XMLAdapter object leaves the XMLName and XMLPrefix properties empty. The XMLNamspace property is set to the targetNamespace attribute value for the xsd:schema node. Each XML element declared as an xsd:complexType is mapped to an XMLTable object, and the XMLNamespace property is set to namespaceURI for the element. The IsDiffgram and SOM properties are set to appropriate values.

The following property settings affect how LoadXML method is executed:

  • DisableEncode

  • MapN19_4ToCurrency

  • NoCpTrans

  • PreserveWhiteSpace

  • WrapCharInCDATA

  • WrapMemoInCDATA

  • XMLSchemaLocation

  • RespectNesting Property

See Also

Reference

RespectNesting Property

Other Resources

Methods
XMLAdapter Object Properties, Methods, and Events
IXMLDOMElement Property
Tables Collection (XMLAdapter)
XMLName Property
XMLNamespace Property
XMLPrefix Property
IsDiffgram Property
SOM Property


Modify Method

Visual FoxPro 9.0 Language Reference
Modify Method
See Also

Opens a file in a project for modification in the appropriate designer or editor.

Object.Modify([cClassName])

Parameters

cClassName

Specifies the name of the visual class to open for modification when Object is a .vcx visual class library.

Remarks

Applies To: File Object

The Modify method returns true (.T.) if the file is successfully opened for modification; otherwise false (.F.) is returned.

The QueryModifyFile event occurs before the file is opened. If the QueryModifyFile event returns false (.F.), the file isn't opened and the Modify method returns false (.F.). If the QueryModifyFile method returns true (.T.), the file is opened and the Modify method returns true (.T.).

See Also

Other Resources

Methods
Add Method
Remove Method (File Object)
QueryModifyFile Event


Move Method (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Move Method (Visual FoxPro)
See Also

Moves an object.

Object.Move (nLeft [, nTop [, nWidth [, nHeight]]])

Parameters

nLeft

Specifies the horizontal coordinate for the left edge of the object. nLeft is a single-precision value.
nTop

Specifies the vertical coordinate for the top edge of the object. nTop is a single-precision value.
nWidth

Specifies the new width of the object. nWidth is a single-precision value.
nHeight

Specifies the new height of the object. nHeight is a single-precision value.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | PageFrame | _SCREEN | Shape | Spinner | TextBox | ToolBar

Only the nLeft argument is required. However, to include any other arguments, you must also include all arguments in the syntax before the argument you want to include. For example, you cannot specify nWidth without specifying nLeft and nTop. Any trailing arguments that are unspecified remain unchanged.

Moving a Form on the screen or moving a control on a form is always relative to the origin (0,0), which is the upper-left corner. When moving controls in a container, the coordinate system of the container is used.

See Also

Other Resources

Methods
Top Property
Width Property


MoveItem Method

Visual FoxPro 9.0 Language Reference
MoveItem Method
See Also

Moves an item to a new position in a list box.

ListBox.MoveItem(nItemIndex, nMoveBy)

Parameters

nItemIndex

Specifies the current index for the item you wish to move.
nMoveBy

Indicates how many positions the item should be moved. A positive value indicates downward movement. A negative number indicates upward movement.

Remarks

Applies To: ListBox Control

Calling the MoveItem method fires the OnMoveItem event.

The OnMoveItem event always fires once when the MoveItem method is called, however, movement of an item in the list box occurs only if the list box's RowSourceType property is set to 0 (None) or 1 (Value).

See Also

Other Resources

Methods
OnMoveItem Event
RowSourceType Property
MoverBars Property


Nest Method

Visual FoxPro 9.0
Nest Method
See Also

Nests an XMLTable object into a specified XMLTable.

XMLTable.Nest(oXMLTable [, oAfterXMLTable | nAfterIndex])

Parameters

oXMLTable

Object reference to the XMLTable object to nest.
oAfterXMLTable

Object reference to the XMLTable object to insert oXMLTable after.
nAfterIndex

Integer indicating which existing XMLTable object to insert oXMLTable after.

nAfterIndex Setting

A number that is less than or equal to the number of nested XLMTables.

oXMLTable is inserted after the XLMTable object within the specified index.

A number that is greater than the number of nested tables.

oXMLTable is inserted as the last nested table.

-1

oXMLTable is inserted as the last nested table.

0

oXMLTable is inserted as the first nested table.

unspecified

oXMLTable is inserted as the last nested table.

Remarks

Applies to: XMLTable Class

The oXMLTable parameter and the oAfterXMLTable parameters must reference XMLTable objects that are members of the same XMLAdapter Tables collection.

The nAfterTable parameter must be greater than or equal to -1.

If you remove a nested XMLTable object from an XMLAdapterTables collection, the XMLTable object's NestedInto, NextSiblingTable and FirstNestedTable properties are automatically set to null (.NULL.). All of its child XMLTable objects are disconnected from it, and their NestedInto and NextSiblingTable properties are set to null (.NULL.). The child objects remain in the collection but are no longer nested.

If an XMLTable object is nested at the time the Nest method is called, it is unnested before its new position is calculated.

For more information about how XML parsing and generation is affected by XLMTable nesting, see RespectNesting Property and XMLAdapter Class.

See Also

Reference

RespectNesting Property
NestedInto Property
NextSiblingTable Property
FirstNestedTable Property
XMLTable Class

Other Resources

Methods (Visual FoxPro)


NewObject Method

Visual FoxPro 9.0 Language Reference
NewObject Method
See Also

Adds a new class or object to an object directly from a .vcx visual class library or program.

Object.NEWOBJECT(cObjectName, cClassName [, cModule [, cInApplication
   [, eParameter1, eParameter2, ...]]])

Remarks

cObjectName

Specifies the name used to reference the newly added class or object.
cClassName

Specifies the class or object from which the new class or object is added.
cModule

Specifies a .vcx visual class library or Visual FoxPro program (.prg, .mpr, .app, .exe, and so on) containing the class or object specified with cClassName. The default is a .vcx visual class library; you must include an extension if you specify a program.
Note:
A class library can have an alias. To specify a class or object from a class library with an alias, include the class library alias followed by a period and the object name.

If cModule is omitted, or is the empty string or the null value, Visual FoxPro searches for the class or object in the following order:
  • Visual FoxPro base classes.

  • User-defined class definitions in memory in the order they were loaded.

  • Classes in the current program.

  • Class libraries opened with SET CLASSLIB.

  • Classes in procedure files opened with SET PROCEDURE.

  • Classes in the Visual FoxPro program execution chain.

  • The OLE registry if SET OLEOBJECT is ON.

cInApplication

Specifies the Visual FoxPro application (.exe or .app) containing the .vcx visual class library you specify with cClassLibName. You must include an extension for the application. CInApplication is ignored if cModule is omitted, or if cInApplication is the empty string or the null value.
eParameter1, eParameter2, ...

Specifies optional parameters that are passed to the Init event procedure for the class or object.

Remarks

Applies To: Column | CommandGroup | Container Object | Custom | DataEnvironment | Form | FormSet | Grid | OptionGroup | Page | PageFrame | _SCREEN | ToolBar | Session Object

The NEWOBJECT method makes it possible for you to add a new class or object to an object without opening a .vcx visual class library or procedure file.

See Also

Other Resources

Methods
AddObject Method
AddProperty Method
Class Designer
CREATE CLASS Command
CREATE CLASSLIB Command
CREATEOBJECT( ) Function
DEFINE CLASS Command
NEWOBJECT( ) Function


OLEDrag Method

Visual FoxPro 9.0 Language Reference
OLEDrag Method
See Also

Starts an OLE drag-and-drop operation.

PROCEDURE Object.OLEDrag(lDetectDrag)

Parameters

lDetectDrag

Specifies when the OLEStartDrag event is executed. If lDetectDrag is false (.F.), the OLEStartDrag event is immediately executed. If lDetectDrag is true (.T.), the OLEStartDrag event is executed after the user has pressed the mouse button for a sufficient period of time to indicate that a drag operation is occurring, or the mouse is moved a sufficient distance while the mouse button is pressed, again indicating that a drag operation is occurring. If you don't specify a value for lDetectDrag, true (.T.) is automatically returned.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

OLEDrag is a drag source method.

See Also

Other Resources

Methods
OLE Drag-and-Drop Overview
OLEDragMode Property
OLEStartDrag Event


OnPreviewClose Method

Visual FoxPro 9.0
OnPreviewClose Method
See Also Example

Occurs when the user closes a report preview or opts to print from a report preview.

oReportListener.OnPreviewClose([lPrint])

Parameters

lPrint

Specifies whether the user indicated a desire to print the pages in the current output page set after closing the report preview.

Return Value

None.

Remarks

Applies To: ReportListener Object.

The PreviewContainer API specifies that, when the user closes a report preview form, the PreviewContainer must call the ReportListener’s OnPreviewClose method. When the user chooses to print from Preview, Preview calls OnPreviewClose with an argument of True (.T.).

Note:
The ReportListener invokes the PreviewContainer's SetReport method in OnPreviewClose with an argument of NULL (.NULL.). At this time, the ReportListener can choose to set its PreviewContainer reference to NULL (.NULL.) or retain it. However, cccording to the conventions of the PreviewContainer API, it is the responsibility of PreviewContainer to remove its back reference to the ReportListener at this time. For more information, see The Preview Container API and PreviewContainer Property.

If the user opted to print from preview, the print run starts after this method finishes. The print run uses cached pages prepared for preview at this point, so the available output exactly matches what the user saw in preview, including any RANGE or scope specifications included in the REPORT FORM command that invoked the preview.

If the ReportListener's CommandClauses.Prompt value is True (.T.) at this point, the printer setup dialog appears before the print run. The user may alter the specifications with which the report prints. This value may be True for one of the following reasons:

  • You used the PROMPT clause on the original REPORT FORM command.

  • The PreviewContainer or ReportListener adjust the CommandClauses.Prompt value dynamically.

The pages that print are not always the full range of available output pages; they may be some subset of this range. Fewer than the full number of output pages may print for one of the following reasons:

  • The user adjusts the page range in the PROMPT dialog.

  • The PreviewContainer or ReportListener adjusts the ReportListener CommandClauses members provided for the purpose of limiting printed output from the OnPreviewClose method. These members are PrintPageCurrent, PrintRangeFrom, and PrintRangeTo. For more information, see CommandClauses Property.

If you use NOPAGEEJECT to combine multiple reports within a single report run, the value of CommandClauses.Prompt is only significant at the moment the PreviewContainer invokes the print run. If you have not dynamically adjusted its value, the value of CommandClauses.Prompt has therefore been determined by whether the final REPORT FORM command in the report run included the PROMPT clause.

Important
Because the printer setup dialog appears after the report has been rendered, in response to CommandClauses.Prompt, and because the report was rendered with information gathered from the printer set earlier, there is some potential for a mismatch between the previously-rendered report and the instructions set by the user in the dialog. For example, the printer chosen in the dialog might have a different printable page size than the original printer. The printed results in this scenario are determined by the way the chosen printer's driver chooses to handle this page size instruction.

Example

You can alter the various dynamic members of CommandClauses during the OnPreviewClose method, to print complex page ranges. In the following code sketch, a derived ReportListener provides a custom dialog to gather a complex page range from a user, and then invokes the native behavior multiple times to print the various page ranges requested by the user.
Copy Code
PROCEDURE OnPreviewClose(lPrint)
   LOCAL liRange
   IF lPrint
      NODEFAULT
      IF NOT EMPTY(THIS.CommandClauses.PrintPageCurrent
         *user chose "print current page" option from PreviewContainer.
         *Print only that page:
         THIS.CommandClauses.PrintRangeFrom = ;
           THIS.CommandClauses.PrintPageCurrent
         THIS.CommandClauses.PrintRangeTo = ;
           THIS.CommandClauses.PrintPageCurrent
         DODEFAULT(.T.)
      ELSE
         THIS.ShowCustomPageSetupDialog()
         THIS.CommandClauses.Prompt = .F.
         IF EMPTY(THIS.PageRangeArray[1])
            * no printing is requested
            DODEFAULT(.F.)
         ELSE
            * user chose at least one range;
            * go through the array set up by
            * the dialog and print the range(s)
            FOR liRange = 1 TO (ALEN(THIS.PageRangeArray,1))
               THIS.CommandClauses.PrintRangeFrom = ;
                 THIS.PageRangeArray[liRange,1]
               THIS.CommandClauses.PrintRangeTo = ;
                 THIS.PageRangeArray[liRange,2]
               DODEFAULT(.T.)
            ENDFOR
         ENDIF
      ENDIF
   ENDIF
ENDPROC

See Also

Reference

ReportListener Object
OutputPageCount Property
IncludePageInOutput Method

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


OpenTables Method

Visual FoxPro 9.0 Language Reference
OpenTables Method
See Also

Programmatically opens the tables and views associated with the data environment.

DataEnvironment.OpenTables

Parameters

DataEnvironment

Specifies the data environment associated with the form, form set, or report.

Remarks

Applies To: DataEnvironment

The OpenTables method loads the data environment tables when the data environment's AutoOpenTables property is set to False (.F.) or if the data environment has been unloaded using the CloseTables method. The OpenTables method acts like an event in that is called automatically if the AutoOpenTables property is set to True (.T.).

If a cursor adapter's AutoOpen method fails, the data environment's OpenTables method does not report an error.

See Also

Other Resources

Methods
AfterCloseTables Event
AutoOpenTables Property
BeforeOpenTables Event
CloseTables Method


OutputPage Method

Visual FoxPro 9.0
OutputPage Method
See Also

Provides access to the current page or the full range of pages for a report run, according to the value of the ListenerType property.

oReportListener.OutputPage(;
                  nPageNo, ;
                  eDevice, ;
                  nDeviceType ;
                 [,nleft, nTop, nWidth, nHeight ;
                 [,nClipLeft,nClipTop, nClipWidth, nClipHeight]])

Parameters

nPageNo

In page-at-a-time mode (ListenerType values 0 and 2), ReportListener uses this parameter to send you the current page number as it prepares each page for output. You can request that this single page be rendered to an alternate device at this point. In all pages-at-once mode (ListenerType values 1 and 3), you use this parameter to send the ReportListener the page number you wish to render. For more information about supported ListenerType values, see ListenerType Property.
eDevice

Provides a handle, reference, or filename for the device to which output is rendered. When its ListenerType property value is 0, ReportListener uses this parameter to send you a GDI+ graphics handle to the current printer. When its ListenerType property value is 2, output is not actually going to a printer, so ReportListener sends you the value 0. In all pages-at-once mode (ListenerType values 1 and 3), you use this parameter to send the ReportListener one of the following:
  • A GDI handle to a printer.

  • A GDI+ graphics handle to another output device.

  • A reference to an object derived from either the Visual FoxPro Shape or Container baseclass.

  • A filename.

You tell the ReportListener what type of eDevice value you send in this parameter by sending an appropriate value in nDeviceType.
nDeviceType

Represents the type of Device to which output is rendered.

Value Device Type

-1

No device.

The ReportListener sends this value when it triggers OutputPage in ListenerType 2.

0

hDC (GDI handle).

You can send a GDI handle to the ReportListener, to send output to an alternate printer.

1

hGraphics (GDI+ graphics handle).

The ReportListener sends this value when it triggers OutputPage in ListenerType 0. You can send it to the ReportListener, to send output to a different GDI+ context, such as a window.

2

oFoxControl.

Use this value to tell the Report Listener to create a preview display, using a Visual FoxPro Shape or Container control.

100

This value specifies a filename, to be saved as image of EMF type.

101

This value specifies a filename, to be saved as image of TIFF type.

102

This value specifies a filename, to be saved as image of JPEG type.

103

This value specifies a filename, to be saved as image of GIF type.

104

This value specifies a filename, to be saved as image of PNG type.

105

This value specifies a filename, to be saved as image of BMP type.

201

This value specifies a page to be saved additively into a previously-created TIFF, generating a multi-page TIFF file.

Tip:
The ReportListener is able to perform some extra optimization of this file format when you use this value before a report run finishes. For a ReportListener with ListenerType 0 or 2, the OutputPage event happens during this time. An example of this usage is shown below. For a ReportListener with ListenerType 1 or 3, you can call OutputPage during the AfterReport Event to take advantage of the optimization.
[nleft, nTop, nWidth, nHeight,[nClipLeft,nClipTop, nClipWidth, nClipHeight]]

These optional parameters are not relevant when nDeviceType is 2 (a Visual FoxPro control surface). The first set of four coordinates (nleft, nTop, nWidth, nHeight) specifies the coordinates, in units of 1/960 inch (960 dpi), of the rectangle on the current device in which this occurrence of the layout element will be rendered. The second set of four coordinates (nClipLeft,nClipTop, nClipWidth, nClipHeight) allows a preview-type output device to indicate that only a portion of the page needs to be refreshed.

Return Value

None.

Remarks

Applies To: ReportListener Object.

The OutputPage method is unusual because, depending on the current ListenerType value, a ReportListener either triggers this method to signal you that a page is ready or expects you to trigger the calls yourself, to request the pages you want.

Understanding OutputPage's Two Processing Modes

In the first processing mode, the ReportListener acts in a style appropriate to printers and other output devices that handle output one page at a time. If necessary, these devices place incoming pages in a spool or queue until they are ready to handle more pages. This type of page-processing is forward-only; you cannot ask for any specific page a single time, after the ReportListener has begun rendering subsequent pages.

In the second processing mode, the ReportListener prepares all pages at once, effectively providing a queue of all pages until the device is ready to request them. You cannot request any pages until all pages are prepared. However, this type of page-processing results in a cached, or scrollable, collection of pages, as required by previewing devices; once the pages are prepared, you can request them in any order, and, you can request them multiple times.

Error-handling for OutputPage Parameters

The parameter list to OutputPage is complex and some parameters have multiple uses. For this reason, it may be difficult to interpret the errors you receive when you use the parameters incorrectly.

The following are the error messages you can expect if you send the ReportListener unexpected or inappropriate values when using this method.

Error message and number Conditions triggering this error

Must specify additional parameters (Error 94)

Triggered if you do not include all three required parameters (nPageNo, eDevice, nDeviceType).

Function argument value, type, or count is invalid (Error 11)

Triggered if nDeviceType receives an unrecognized value.

DataType property for field 'eDevice' is invalid (Error 1544)

Triggered if the eDevice argument’s data type does not match the requirements for a valid value in nDeviceType.

For example, you might receive this value if nDeviceType is 0 or 1 and eDevice is not a valid handle, or if nDeviceType is one of the filename types but eDevice is not a string representing a valid filename.

Error writing to file 'filename' (Error 1105)

Triggered if nDeviceType is one of the filename types and eDevice appears valid but the file cannot be created. For example, the user might not have permissions to create a file in the specified directory.

Output page 'pageno' is not available (Error 2194)

Triggered if nPageNo is not appropriate to the current rendered pages, or if the ListenerType value is not properly set to one of the values (0, 1, 2, or 3) in which the ReportListener renders pages.

For more information about Visual FoxPro error messages, see Error Messages Listed Numerically. For more information about what to do when errors occur when you process reports, see Handling Errors During Report Runs.

Caution:
In addition to the error messages above, which you may see if you invoke OutputPage with incorrect parameters, be aware that OutputPage needs resources available to the report even when you call it after the report run concludes. For example, if image file used in a report is built into your calling application, a call to OutputPage from a PreviewContainer needs access to that image file. Although no error message is generated, your report output will not be complete if you unload the application from which the REPORT FORM or LABEL command was issued.

Examples

Example 1: OutputPage in page-at-a-time mode for image files from output pages

This sample code creates a multipage Tag Image File Format (TIFF) document from a report. It uses the native ReportListener ability to specify the OutputPage nDeviceType parameter as 101, to create a TIFF file, followed by additional calls with an eDeviceType value of 201, to add into this TIFF document for subsequent pages. This ReportListener derived class uses a ListenerType value of 2, so the native code invokes OutputPage as it prepares each page.

Tip:
The ReportListener class's native ability to provide images of pages as various file types is limited to some default settings for each image type it supports. In the case of TIFFs, ReportListener provides compressed TIFFs for performance. However, you are not limited to the settings provided in the native implementation. You can give the ReportListener a GDI+ graphics handle and, in the OutputPage method, request that it render a page to this device. You can then save the result to an image file with non-default specifications. Visual FoxPro supplies a class library to help you perform this and other GDI+-related tasks. For more information, see GDI Plus API Wrapper Foundation Classes.

Code

Copy Code
#define OutputNothing -1
#define OutputTIFF 101
#define OutputTIFFAdditive (OutputTIFF+100)

LOCAL oReportListener
oReportListener = NEWOBJECT("MPTiffListener")
oReportListener.Filename = "Multi"

WAIT WINDOW "Processing report to TIFF file...." NOWAIT
REPORT FORM ? OBJECT oReportListener
WAIT CLEAR

DEFINE CLASS MPTiffListener AS ReportListener

   PROCEDURE Init
      this.AddProperty("Filename", "temp")
      this.ListenerType = 2
   ENDPROC

   PROCEDURE BeforeReport
      ERASE this.Filename
   ENDPROC

   PROCEDURE OutputPage(nPageNo, eDevice, nDeviceType)
      IF (nDeviceType == OutputNothing)
         IF (nPageNo == 1)
             nDeviceType = OutputTIFF
         ELSE
            nDeviceType = OutputTIFFAdditive
         ENDIF
         THIS.OutputPage(nPageNo, this.Filename, nDeviceType)
         NODEFAULT
     ENDIF
   ENDPROC

ENDDEFINE

Example 2: OutputPage in page-at-a-time echoing output to the display

This example provides a replacement for backward-compatible reporting's echoed output to the display, when the keyword NOCONSOLE is not used on the REPORT FORM Command. It uses the OutputPage method's ability to write to a GDI+ Graphics handle. If the REPORT FORM specifies NOCONSOLE, the ReportListener object does not provide display output.

By default, this ReportListener uses a ListenerType value of 2, so it invokes OutputPage as it prepares each output page but has no native output result. It evaluates CommandClauses Property values to check for the NOCONSOLE keyword, and also to evaluate the user's specified output target. If the user chose to generate output to a printer, a file, or preview, this class adjusts its behavior to match previous versions of Visual FoxPro.

Code

Copy Code
#DEFINE OUTPUTDEVICETYPE_GDIPLUS 1
#DEFINE OUTPUTTO_PRINT           1
#DEFINE OUTPUTTO_FILE            2
#DEFINE LISTENER_TYPE_PRN        0
#DEFINE LISTENER_TYPE_PRV        1
#DEFINE LISTENER_TYPE_PAGED      2
LOCAL loRL, loForm
loRL = CREATEOBJECT("EchoListener")
REPORT FORM ? OBJECT loRL && output to the console
REPORT FORM ? OBJECT loRL NEXT 1 TO PRINT && output to console and print
_SCREEN.Cls && clear screen
REPORT FORM ? OBJECT loRL PREVIEW && to preview only, no console output
loForm = CREATEOBJECT("form")
loForm.Caption = "My Output Window"
loForm.Show()
REPORT FORM ? OBJECT loRL TO FILE c:\temp\x.txt && to file and output window
REPORT FORM ? OBJECT loRL TO FILE c:\temp\x.txt NOCONSOLE && to file only

DEFINE CLASS EchoListener as ReportListener
  ListenerType = LISTENER_TYPE_PAGED

  GP = 0
  RHeight = 0
  RWidth = 0

  PROCEDURE LoadReport()
    IF THIS.CommandClauses.Preview
       THIS.ListenerType = LISTENER_TYPE_PRV
    ELSE
       IF INLIST(THIS.CommandClauses.OutputTo,OUTPUTTO_PRINT,OUTPUTTO_FILE)
          THIS.ListenerType = LISTENER_TYPE_PRN
       ENDIF
    ENDIF
  ENDPROC

  PROCEDURE BeforeReport()
     IF NOT (THIS.CommandClauses.NoConsole OR THIS.CommandClauses.Preview)
        DECLARE integer GdipCreateFromHWND IN GDIPLUS.DLL ;
          integer hwnd, integer @ nGraphics
        LOCAL lH, nG
        nG = 0
        IF TYPE("_SCREEN.ActiveForm") = "O"
           m.lH = _SCREEN.ActiveForm.HWnd
        ELSE
           m.lH = _SCREEN.HWnd
        ENDIF
       IF GdipCreateFromHWND( m.lH, @nG ) = 0
          THIS.GP = m.nG
          THIS.RHeight = THIS.GetPageHeight()/10 && convert 960 DPI to 96 DPI
          THIS.RWidth = THIS.GetPageWidth()/10
       ENDIF
    ENDIF
  ENDPROC

  PROCEDURE OutputPage(nPageNo, ;
                  eDevice, ;
                  nDeviceType, ;
                  nleft, nTop, nWidth, nHeight, ;
                  nClipLeft,nClipTop, nClipWidth, nClipHeight)
      IF THIS.GP # 0
         DODEFAULT(nPageNo, THIS.GP,OUTPUTDEVICETYPE_GDIPLUS , ;
                   0,0,THIS.RWidth, THIS.RHeight, ;
                   0,0,THIS.RWidth, THIS.RHeight)
      ENDIF

  ENDPROC

  PROCEDURE UnloadReport()
     * reset:
     IF NOT THIS.GP = 0
        DECLARE integer GdipDeleteGraphics IN GDIPLUS.DLL integer
        GdipDeleteGraphics( THIS.GP )
        THIS.GP = 0
     ENDIF
     THIS.ListenerType = LISTENER_TYPE_PAGED
  ENDPROC

ENDDEFINE

Example 3: OutputPage in all-pages-at-once mode

This example uses a ListenerType value of 3, so the native ReportListener class does not invoke OutputPage as it prepares pages. Instead, this derived class invokes OutputPage after the report run concludes, and displays the output to a simple preview object contained by a form. As this example shows, by varying the dimensions of the preview object, you can vary and control zoom level using any algorithm or restrictions you prefer. By passing a reference to this object in the OutputPage method, you instruct the native code what size you want for the previewed page. The native OutputPage behavior takes care of scaling the preview output appropriately.

Tip:
Notice that this class's DoOutputPage wrapper code for the OutputPage method checks to see that the external call to the method has included a valid page number before invoking native OutputPage code, to avoid errors.

Code

Copy Code
#DEFINE BASEPAGEHEIGHT  550
#DEFINE BASEPAGEWIDTH 425

CLEAR ALL
oListener = NEWOBJECT("zoomListener")
oForm = CREATEOBJECT("form")

WITH oForm
   .ScaleMode = 3
   .allowOutput = .F.
   .top = 0
   .left = 0
   .height = BASEPAGEHEIGHT
   .width = BASEPAGEWIDTH
   .backcolor = RGB(255,255,255)
   .Show()
ENDWITH

oListener.PreviewContainer = oForm
REPORT FORM ? OBJECT oListener
oListener.DoOutputPage(1,1)
WAIT window  ;
   "Previewing at 100%... " + ;
   "press any key for the next preview zoom level"
oListener.DoOutputPage(2, .21123 )
WAIT window ;
   "Previewing at 21.123%... " + ;
   "press any key for the next preview zoom level"
oListener.DoOutputPage(3,2.367)
WAIT window ;
   "Previewing at 236.7%... "

DEFINE CLASS zoomListener AS ReportListener
   ListenerType = 3

   PROCEDURE DoOutputPage(tPage, tMultiplier)
      LOCAL liPage
      IF VARTYPE(tPage) = "N" AND ;
         BETWEEN(tPage,;
                 THIS.CommandClauses.RangeFrom, ;
                 IIF(THIS.CommandClauses.RangeTo=-1, ;
                     THIS.PageTotal, ;
                     THIS.CommandClauses.RangeTo))
         liPage = INT(tPage)
      ELSE
         liPage = THIS.CommandClauses.RangeFrom
      ENDIF
      THIS.SetPreview(tMultiplier)
      THIS.OutputPage(liPage,ThIS.PreviewContainer.MyPreview,2)
   ENDPROC

   PROCEDURE SetPreview(tMultiplier)
      LOCAL liHeight, liWidth
      IF TYPE("THIS.PreviewContainer.MyPreview") # "O"
         THIS.PreviewContainer.AddObject("MyPreview","shape")
      ENDIF
      IF VARTYPE(tMultiplier) = "N" AND ;
         BETWEEN(tMultiplier,.01, 10)
         liHeight = BASEPAGEHEIGHT * tMultiplier
         liWidth  = BASEPAGEWIDTH * tMultiplier
         WAIT WINDOW ;
            "H:" + TRANSFORM(liHeight)+ ;
          ", W:" + TRANSFORM(liWidth) TIMEOUT 1
         * note that VFP will round the pixels
         WITH THIS.PreviewContainer
            .LockScreen = .T.
            .MyPreview.Height = liHeight
            .MyPreview.Width = liWidth
            .Height = liHeight
            .Width = liWidth
            .LockScreen = .F.
            .Cls()
         ENDWITH
      ENDIF
   ENDPROC

   PROCEDURE Destroy
      THIS.PreviewContainer = NULL
   ENDPROC

ENDDEFINE

See Also

Reference

ReportListener Object
CommandClauses Property
ListenerType Property
LoadReport Event
OutputPageCount Property
PageNo Property
Shape Control
Container Object
The Preview Container API

Concepts

Using GDI+ in Reports

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


Point Method

Visual FoxPro 9.0 Language Reference
Point Method
See Also

Returns the red-green-blue (RGB) color of the specified point on a form.

Object.Point ([nXCoord, nYCoord])

Parameters

nXCoord

Specifies the horizontal coordinate of the point, in the units specified in the ScaleMode property setting of the form.
nYCoord

Specifies the vertical coordinate of the point, in the units specified in the ScaleMode property setting of the form.

Remarks

Applies To: Form Object | _SCREEN System Variable

If nXCoord or nYCoord is outside of the form, the Point method returns – 1.

See Also

Other Resources

Commands
Circle Method
Line Method
Print Method
PSet Method


Print Method

Visual FoxPro 9.0 Language Reference
Print Method
See Also

Prints a character string on a form.

 [FormSet.] Object.Print [(cText)]

Parameters

cText

Specifies the character string to print. If you omit cText, a blank line is printed. cText is printed on the form starting at the position specified by the CurrentX and CurrentY properties. When a carriage return is included, CurrentX is increased by the width of cText (same as the value returned by TextWidth) and CurrentY remains unchanged. When the Print method is finished, the CurrentX and CurrentY properties are set to the point immediately after the last character printed.
Note:
This method is not supported if BITMAP=OFF.

Remarks

Applies To: Form | _SCREEN

See Also

Other Resources

Methods
CurrentX, CurrentY Properties
TextHeight Method
TextWidth Method


PSet Method

Visual FoxPro 9.0 Language Reference
PSet Method
See Also

Sets a point on a form or the main Visual FoxPro window to the foreground color.

 [FormSet.]Object.PSet([nXCoord, nYCoord])

Parameters

nXCoord

Specifies the horizontal coordinate of the point to set, in the unit of measurement specified by the ScaleMode property of the form.
nYCoord

Specifies the vertical coordinate of the point to set, in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: Form | _SCREEN

The size of the point drawn depends on the DrawWidth property. When DrawWidth is set to 1, the PSet method sets a single pixel to the specified color. When DrawWidth is set to a value greater than 1, the point is centered on the specified coordinates. The way the point is drawn depends on the setting of the DrawMode and DrawStyle properties.

When the PSet method is called, the CurrentX and CurrentY properties are set to the point specified by the arguments.

See Also

Other Resources

Methods
CurrentX, CurrentY Properties
DrawMode Property
DrawStyle Property
DrawWidth Property
ForeColor Property


Quit Method

Visual FoxPro 9.0 Language Reference
Quit Method
See Also

Ends an instance of Visual FoxPro.

ApplicationObject.Quit( )

Remarks

Applies To: Application Object | _VFP System Variable

Call the Quit( ) method to return control to the application that created the instance of Visual FoxPro.

See Also

Other Resources

Methods
QUIT Command


ReadExpression Method

Visual FoxPro 9.0 Language Reference
ReadExpression Method
See Also

Returns the expression entered for a property value in the Properties window. Available at design time and run time.

Object.ReadExpression(cPropertyName)

Parameters

cPropertyName

Specifies the name of the property to return the expression from.

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | CommandGroup | Cursor | CursorAdapter Class | Custom | DataEnvironment | EditBox | Exception Class | Form | FormSet | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Relation | ReportListener Object | Session Object | Shape | Spinner | TextBox | Timer | ToolBar

See Also

Other Resources

Methods
WriteExpression Method


ReadMethod Method

Visual FoxPro 9.0 Language Reference
ReadMethod Method
See Also

Returns the text of the specified method. Available at design time.

Control.ReadMethod(cMethod)

Parameters

cMethod

Specifies the name of a method.

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | CommandGroup | Cursor | CursorAdapter Class | Custom | DataEnvironment | EditBox | Exception Class | Form | FormSet | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Relation | ReportListener Object | Session Object | Shape | Spinner | TextBox | Timer | ToolBar

See Also

Other Resources

Methods
ReadExpression Method
WriteExpression Method
WriteMethod Method


RecordRefresh Method

Visual FoxPro 9.0 Language Reference
RecordRefresh Method
See Also

Refreshes the current field values for the specified records.

CursorAdapter.RecordRefresh([nRecords],[ nRecordOffset])

Parameters

nRecords

Specifies the number of consecutive records (in physical order) to refresh. nRecords is an integer greater than or equal to zero. If nRecords is 1 or you omit nRecords, only the field values in the current record are refreshed. If nRecords is 0, no field values are refreshed.
nRecordOffset

Specifies the number of records before the current record where the refresh begins. nRecordOffset is an integer greater than, less than, or equal to zero. For example, if the current record is record 10 and nRecordOffset is 4, record refresh begins with record 6. If nRecordOffset is 0 or you omit nRecordOffset, the refresh begins with the current record.

Return Value

Numeric. The RecordRefresh method returns the number of refreshed records or zero if no records were refreshed and there were no errors. For example, zero is returned if all target records are buffered inserts or nRecords is zero. In case of failure, a negative integer is returned which represents the negative value of the number of successfully refreshed records minus 1.

Remarks

Applies To: CursorAdapter Class

The RecordRefresh method refreshes the current field values for the target records. Use the CURVAL( ) Function to determine current field values.

The tables or cursors must be opened exclusively.

The refresh operation is not supported buffered inserts, which are simply ignored, and no error is generated. If a target record has buffered table or record changes, those changes are preserved, and the current field values are refreshed.

If a target record cannot be located in at least one base table, the target record’s current field values are not refreshed and the record is marked as DELETED. Records are refreshed record by record until the number of records specified by nRecords is refreshed or until a failure occurs. When the refresh key is not unique an error is generated.

The CursorAdapter FetchMemo Property setting is respected during the refresh operation unless there is an index on a Memo field. In this case, the Memo field is fetched regardless of the FetchMemo property setting. Long running RecordRefresh execution can be interrupted by pressing ESC; no error is generated.

Use the AERROR( ) function to determine the cause of failure of the RecordRefresh method. The ON ERROR Command and TRY...CATCH...FINALLY Command cannot be used to determine the cause of RecordRefresh method errors.

The RecordRefresh method is integrated with the REFRESH( ) Function. If the REFRESH( ) function is called for a cursor associated with a CursorAdapter object, the RecordRefresh method is called for the CursorAdapter object. For backward compatibility, the REFRESH( ) function returns zero if the RecordRefresh method fails.

Note:
The RecordRefresh method uses CursorAdapter properties. In Visual FoxPro 8, the REFRESH( ) function always uses cursor properties set with the CURSORSETPROP( ) Function and the CURSORGETPROP( ) Function regardless of whether or not the cursor is associated with a CursorAdapter object.

See Also

Reference

CURVAL( ) Function


Refresh Method (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Refresh Method (Visual FoxPro)
See Also

Repaints a form or control and refreshes any values, or refreshes a project's visual display. There are two versions of the syntax.

[Form.]Object.Refresh
Project.Refresh([lUpdateSCCStatus])

Parameters

lUpdateSCCStatus

Logical data type. The lUpdateSCCStatus parameter specifies, for a project, if the source control status for each file under source control is updated. Visual FoxPro disregards lUpdateSCCStatus if no files in the project are under source control. The following table lists the values for lUpdateSCCStatus.

lUpdateSCCStatus Description

True (.T.)

Updates the source control status for each file in the project under source control.

False (.F.) or none

Does not update the source control status.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | FormSet | Grid | Header | Label | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | Project Object | _SCREEN | Shape | Spinner | TextBox | ToolBar

Generally, Visual FoxPro automatically handles painting a form or control while no events are occurring. You can use the Refresh method when you want to update the form or control immediately, force a complete repaint of a form or control, or to update the value of a control.

You can also use the Refresh method when you want to display a form while another form is loading, or when you want to update the contents of a control. To update the contents of a combo box or a list box, use the Requery method.

Note:
When a form is refreshed, all controls on the form are also refreshed. When a page frame is refreshed, only the active page is refreshed.

When you call the Refresh method for a Label control, Visual FoxPro updates the Caption property and redraws the label.

When you call the Refresh method for a Shape control, Visual FoxPro redraws the shape.

When you call the Refresh method for projects, Visual FoxPro refreshes a project's visual display with any changes made to the project. For example, after programmatically adding files to the project with the Add method, you can call the Refresh method to display the newly added files in the project.

The Grid Refresh method visually updates the grid's record indicator even if the grid does not have focus.

See Also

Other Resources

Methods
Paint Event
Requery Method


Release Method

Visual FoxPro 9.0 Language Reference
Release Method
See Also

Releases a form, form set, or toolbar from memory.

The Release method is particularly useful when a Form or FormSet object is created with the DO FORM command, and no variable exists to reference the form or form set. For more information, see DO FORM Command.

Object.Release

Remarks

Applies To: Form | FormSet | _SCREEN | ToolBar

You can use the forms collection of the _SCREEN object to find the form or form set and call its Release method.

When adding objects to collections, Visual FoxPro increases the reference count for that object. According to usual Visual FoxPro object behavior, you can release an object only when its reference count is 0. Therefore, you should make sure that the reference to the object in the collection is released when releasing the object; otherwise, the Visual FoxPro does not remove the object entirely from memory.

Note:
When you have an object reference to a form in a collection, and you call the form's Release method, the object is removed from the collection without having to release or remove the form from the collection first.

See Also

Other Resources

Methods


ReleaseXML Method

Visual FoxPro 9.0 Language Reference
ReleaseXML Method
See Also

Releases the attached IXMLDOMElement object.

XMLAdapter.ReleaseXML( [lDisposeSchema] )

Parameters

lDisposeSchema

Determines whether schema information is cleaned by ReleaseXML. The following table lists the values for lDisposeSchema.

lDisposeSchema Description

True (.T.)

Clean Tables collection and sets the following XMLAdapter properties:

  • XMLName, XMLNamespace, and XMLPrefix to an empty string ("")

  • IsDiffGram to False (.F.)

  • SOM to null (.NULL.)

  • XMLConstraints to null (.NULL.)

(Default)

False (.F.)

Schema information remains and XMLAdapter XMLName, XMLNamespace, XMLPrefix, IsDiffGram, XMLConstraints, and SOM remain unchanged.

Remarks

Applies To: XMLAdapter Class

See Also

Other Resources

Methods
XMLAdapter Object Properties, Methods, and Events
Tables Collection (XMLAdapter)
XMLName Property
XMLNamespace Property
XMLPrefix Property
IsDiffGram Property
SOM Property
XMLConstraints Property


Remove Method (Collection Class)

Visual FoxPro 9.0 Language Reference
Remove Method (Collection Class)
See Also Example

Use to remove a member object from a collection.

The member object can have any valid type that can be assigned to a memory variable. This includes simple data types, such as strings, numbers, dates, logical, or more complex ones such as Visual FoxPro and Component Object Model (COM) objects.

Collection.Remove( eIndex )

Parameters

eIndex

Specifies an expression that represents a position of an item in the collection. This expression can be one of two types:
  • Numeric. The eIndex expression must have a value from 1 to the value of the Count property for the collection. If you pass a value of -1, Visual FoxPro removes all items in the collection.

  • String. The eIndex expression must correspond to the cKey that was specified for the item when it was added to the collection.

If eIndex does not match an existing member of the collection, an error occurs.

Remarks

  • If an incorrect type is passed for a specific parameter, an error occurs.

  • Include the NODEFAULT command in the Remove method for collection objects to prevent removing a particular item from the collection.

Example

The following example illustrates these tasks at run time:

  • Creates forms and a collection.

  • Adds forms to the collection.

  • Displays the number of forms in the collection.

  • Removes the first form from the collection.

  • Displays the current number of forms in the collection.
Copy Code
loForm1 = CREATEOBJECT("myForm1")
loForm2 = CREATEOBJECT("myForm2")
loCol = CREATEOBJECT("myCollection")
loCol.Add(loForm1)
loCol.Add(loForm2)
? loCol.Count
loCol.Remove(1)
? loCol.Count

See Also

Other Resources

Collection Object Properties, Methods, and Events
Collection Class
Methods
NODEFAULT Command


Remove Method (File Object)

Visual FoxPro 9.0 Language Reference
Remove Method (File Object)
See Also

Removes a file from its files collection and project.

Object.Remove( )

Remarks

Applies To: File Object

The Remove method for file objects returns true (.T.) if the file is successfully removed from the project; otherwise false (.F.) is returned. Note that a warning isn't displayed when you use the Remove method to remove files from a project, including files that are under source code control.

The QueryRemoveFile event occurs before the file is removed from its Files collection and project. If the QueryRemoveFile event returns false (.F.), the file isn't removed from its Files collection and project and the Remove method returns false (.F.). If the QueryRemoveFile method returns true (.T.), the file is removed from its Files collection and project and the Remove method returns true (.T.).

See Also

Other Resources

Methods
Add Method (File Object)
Modify Method
QueryRemoveFile Event


RemoveFromSCC Method

Visual FoxPro 9.0 Language Reference
RemoveFromSCC Method
See Also

Removes a file in a project from source code control.

Object.RemoveFromSCC( )

Remarks

Applies To: File Object

The RemoveFromSCC method returns true (.T.) if the file is successfully removed from source code control; otherwise false (.F.) is returned.

See Also

Other Resources

Methods
AddToSCC Method
CheckIn Method
CheckOut Method
GetLatestVersion Method
UndoCheckOut Method


RemoveItem Method

Visual FoxPro 9.0 Language Reference
RemoveItem Method
See Also

Removes an item from a combo box or list box.

Control.RemoveItem(nIndex)

Parameters

nIndex

Specifies an integer corresponding to the order in which items are displayed in the control. For the first item in a list box or combo box, nIndex = 1.

Remarks

Applies To: ComboBox Control | ListBox Control

See Also

Other Resources

Methods
AddItem Method
Clear Method
RemoveListItem Method


RemoveListItem Method

Visual FoxPro 9.0 Language Reference
RemoveListItem Method
See Also

Removes an item from a combo box or list box.

Control.RemoveListItem(nItemId)

Parameters

nItemId

Specifies an integer representing the unique ID of the item in the control.

Remarks

Applies To: ComboBox Control | ListBox Control

See Also

Other Resources

Methods
AddItem Method
Clear Method


RemoveObject Method

Visual FoxPro 9.0 Language Reference
RemoveObject Method
See Also

Removes a specified object from a container object at run time.

Object.RemoveObject(cObjectName)

Parameters

cObjectName

Specifies the name of an object to remove. If the object does not exist, an error occurs.

Remarks

Applies To: Column Object | CommandGroup Control | Container Object | Custom Object | DataEnvironment Object | Form Object | FormSet Object | Grid Control | OptionGroup Control | Page Object | PageFrame Control | _SCREEN System Variable | ToolBar Object

When an object is removed, it disappears from the screen and can no longer be referenced.

See Also

Other Resources

Methods
AddObject Method
RemoveItem Method
RemoveListItem Method


Render Method

Visual FoxPro 9.0
Render Method
See Also Example

Occurs when ReportListener is ready to provide output for a layout element in a report or label.

oReportListener.Render(nFRXRecNo,;
                       nLeft,nTop,nWidth,nHeight,;
                       nObjectContinuationType, ;
                       cContentsToBeRendered, GDIPlusImage)

Parameters

nFRXRecno

Specifies the record number in the report or label definition file (frx or lbx) describing the layout element being rendered.
nLeft

Specifies the column coordinate, in units of 1/960 inch (960 dpi), of the rectangle on the current page in which this occurrence of the layout element will be rendered.
nTop

Specifies the row coordinate, in units of 1/960 inch (960 dpi), of the rectangle on the current page in which this occurrence of the layout element will be rendered.
nWidth

Specifies the width, in units of 1/960 inch (960 dpi), of the rectangle on the current page in which this occurrence of the layout element will be rendered.
nHeight

Specifies the height, in units of 1/960 inch (960 dpi), of the rectangle on the current page in which this occurrence of the layout element will be rendered.
nObjectContinuationType

Indicates the current continuation state for the rendered element. When layout elements span pages, they are rendered in multiple sections (once for each page).
Note:
Continuation can occur for layout elements of Expression (Field), Shape, or Line type. Although Labels and Pictures can span bands in a report, they cannot span pages and ReportListener renders them only once. Not all band types support spanning pages. Refer to Report Bands for more information.

The following table lists the possible values for nObjectContinuationType.

Value Continuation Type

0

Complete (no continuation).

1

Start of layout element occurrence, will not finish on the current page.

2

Mid-element, neither started nor finished on the current page.

3

End of element, completed on the current page.
cContentsToBeRendered

Indicates the text to be rendered for Expression (Field) and Label layout elements. For Picture layout elements sourced from a file, cContentsToBeRendered contains the filename. When specifying a filename for an image, ReportListener provides cContentsToBeRendered as a DBCS string, which is the standard format for strings in Visual FoxPro. However, when indicating text to be rendered, ReportListener provides cContentsToBeRendered as a Unicode string, appropriately translated to the correct locale using any regional script information associated with this layout control in its report definition file (frx) record. If your derived class sends the text value through some additional processing, such as storage in a table, you can use the STRCONV() function, and its optional regional script parameter, to convert the string to DBCS first. For more information, see STRCONV( ) Function.
Note:
You set the default regional script for a report in the Report Properties dialog box. For more information, see Page Layout Tab, Report Properties Dialog Box (Report Builder). You can also set regional script settings for individual layout controls, when you select other font attributes. For more information, see How to: Change Font Settings in Report Controls.

GDIPlusImage

Provides a handle to the GDI+ graphics handle when a Picture layout is sourced from a non-file-based image (a General field or an Image control). When the ReportListener renders a different type of layout element, or when you do not set the value of its SendGDIPlusImage property to True (.T.), this parameter has the value 0. For more information, see SendGDIPlusImage Property.

Return Value

None.

Remarks

Applies To: ReportListener Object.

ReportListener calls Render once for each occurrence of each layout element to be rendered, potentially multiple times for some layout element types that span pages.

Note:
During report processing, if you use a Print When expression on a layout element, the Report System evaluates this expression to decide whether each occurrence of a layout element should appear. If Print When evaluates to False (.F.) for a specific occurrence of a layout object, the element does not appear and the ReportListener does not call Render.

Note:
If Print When evaluates to True (.T.), you can change the rendered contents of some layout elements using the AdjustObjectSize and EvaluateContents (for example, changing the text of an Expression layout control to a null-length string, or making it transparent). As a result of this activity, you may not see any rendered result in the report output. However, the ReportListener still calls Render in this situation.

Special Features of Visual FoxPro GDI+ Rendering

ReportListener objects use Microsoft Windows GDI+ to render to output devices. GDI+ allows the output to be device-independent, which means the same rendering mechanism is used whether you are previewing report content, printing it, or saving it to an image file.

ReportListener exposes some special features of GDI+ that provide opportunities for you to customize text rendering. For example, the ReportListener's DynamicLineHeight property allows you to leverage GDI+ dynamic line-spacing for rendering text. ReportListener also exposes GDI+ StringTrimming options, which allow you to determine how text is rendered when it does not fit into the space you allotted for an expression control in the report layout. For more information, see DynamicLineHeight Property and Using GDI+ in Reports.

Example

Some parameters are only appropriate for some layout element types. You can use the first parameter, nFRXRecno, to check the report definition file (frx) and determine the layout element type. You can then augment the Render process appropriately for the current element type.

The following example is similar to the code used by the ReportListener XML Display-Style Foundation Class to copy file-based images to disk when the ReportListener renders them. It uses the nFRXRecNo parameter to ascertain the layout element type. If the element is a Picture, it checks the cContentsToBeRendered parameter to see if the file is available for copying. It then defers to the native ReportListener class's code to continue rendering the image to the standard output device.

Copy Code
PROCEDURE Render(nFRXRecNo,;
                 nLeft,nTop,nWidth,nHeight,;
                 nObjectContinuationType, ;
                 cContentsToBeRendered, GDIPlusImage)

   LOCAL llCopyImage, lcFile

   IF THIS.CopyImageFilesToExternalFileLocation
      THIS.SetFRXDataSession()
      GO nFRXRecNo IN FRX
      IF FRX.ObjType = FRX_OBJTYP_PICTURE AND ;
         FRX.Offset # FRX_PICTURE_SOURCE_GENERAL AND ;
         FILE(cContentsToBeRendered)
         llCopyImage = .T.
      ENDIF
      THIS.SetCurrentDataSession()
   ENDIF

   IF llCopyImage
      lcFile = FORCEPATH(cContentsToBeRendered, ;
          FULLPATH(THIS.ExternalFileLocation, ;
          ADDBS(JUSTPATH(THIS.TargetFileName))))
      IF NOT FILE(lcFile)
         COPY FILE (cContentsToBeRendered) TO (lcFile)
      ENDIF
   ENDIF

   DODEFAULT(nFRXRecNo,;
             nLeft,nTop,nWidth,nHeight,;
             nObjectContinuationType, ;
             cContentsToBeRendered, GDIPlusImage)
ENDPROC

See Also

Reference

ReportListener Object
EvaluateContents Event
AdjustObjectSize Event
Print When Tab, Report Control Properties Dialog Box (Report Builder)

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


Requery Method

Visual FoxPro 9.0 Language Reference
Requery Method
See Also

Requeries the row source to which the ListBox or ComboBox control is bound.

Control.Requery

Remarks

Applies To: ComboBox | ListBox

Use the Requery method to ensure a control contains the most recent data. The Requery method requeries the RowSource property and updates the list with the new values.

See Also

Other Resources

Methods
RowSource Property


RequestData Method

Visual FoxPro 9.0 Language Reference
RequestData Method
See Also Example

Creates an array containing data from a table open in an instance of Visual FoxPro.

ApplicationObject.RequestData([nWorkArea | cTableAlias] [, nRecords])

Return Value

Array

Return Value

nWorkArea

Specifies the work area number of the table from which data is stored in the array. If you omit cTableAlias and nWorkArea, data from the table open in the current work area is stored in the array.
cTableAlias

Specifies the alias of the table from which data is stored in the array.
nRecords

Specifies the number of records stored in the array, starting from the current record. If nRecords is omitted and sufficient memory is available, all records, starting from the current record, are stored in the array.

Remarks

Applies To: Application Object | _VFP System Variable

Use the RequestData method to retrieve data from an instance of Visual FoxPro.

Example

The following example, run from within Visual FoxPro, creates a second instance of Visual FoxPro. The Customer table is opened in the second instance of Visual FoxPro.

An array containing data from the Customer table is created in the first instance of Visual FoxPro, and the contents of the array are displayed. The array contains data from the first 5 records in the Customer table. The second instance of Visual FoxPro is then closed.
Copy Code
oNewInstance = CREATEOBJECT('VisualFoxPro.Application')
oNewInstance.DoCmd "USE (HOME(2) + 'Data\Customer')"
aCustomerArray = oNewInstance.RequestData('Customer',5)
DISPLAY MEMORY LIKE aCustomerArray
oNewInstance.DoCmd('QUIT')

See Also

Other Resources

Methods
DataToClip Method


Reset Method

Visual FoxPro 9.0 Language Reference
Reset Method
See Also

Resets the Timer control so that it starts counting from 0.

Timer.Reset

Remarks

Applies To: Timer

See Also

Other Resources

Methods
Interval Property
Timer Event


ResetToDefault Method

Visual FoxPro 9.0 Language Reference
ResetToDefault Method
See Also

Restores a property, event, or method to its Visual FoxPro default setting. Available at run time and design time.

 [Form.]Object.ResetToDefault(cPropertyName | cEventName | cMethodName)

Return Value

cPropertyName

Specifies the name of the property to reset to the Visual FoxPro default setting.
cEventName

Specifies the name of the event to reset. All user-defined code in the event is deleted.
cMethodName

Specifies the name of the method to reset. All user-defined code in the method is deleted.

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | Cursor | CursorAdapter Class | Custom | DataEnvironment | EditBox | Exception Class | Form | FormSet | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Relation | ReportListener Object | _SCREEN | Shape | Session Object | Spinner | TextBox | Timer | ToolBar

ResetToDefault returns a property to the setting it had when first created. For example, if you have changed the font of a command button, calling this method for the caption resets the font to its default (Arial).

ResetToDefault removes all user-defined code from an event or method at design time.

ResetToDefault has no effect on member arrays, since there is no default value in a class.

ResetToDefault does not apply to Access/Assign methods since these are tied more closely to their associated property and therefore are treated differently than normal methods.

See Also

Other Resources

Methods
GETPEM( ) Function


Run Method (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Run Method (Visual FoxPro)
See Also

Runs or previews a file in a project.

Object.Run( )

Remarks

Applies To: File Object

The Run method returns true (.T.) if the file is successfully run or previewed; otherwise false (.F.) is returned. Labels and reports are previewed by the Run method.

The QueryRunFile event occurs before the file is run or previewed. If NODEFAULT is specified in the QueryRunFileEvent, the file isn't run or previewed and the Run method returns false (.F.). Otherwise, the file is run or previewed and the Run method returns true (.T.).

Include NODEFAULT in the QueryRunFile event to prevent a file from being run or previewed.

See Also

Other Resources

Methods
QueryAddFile Event
QueryModifyFile Event
QueryRunFile Event
QueryRemoveFile Event
NODEFAULT Command


SaveAs Method (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
SaveAs Method (Visual FoxPro)
See Also

Saves an object as an .scx file.

Object.SaveAs(cFileName [, oDataEnvironment])

Parameters

cFileName

Specifies the .scx file to which you want to save the object.
oDataEnvironment

Specifies a reference to a DataEnvironment object. The DataEnvironment object must have its Name property set to "DataEnvironment".

Remarks

Applies To: DEFINE CLASS | Form | FormSet | _SCREEN

Use the SaveAs method to create a form or form set and save it as an .scx file. The SaveAs method is only available during an interactive Visual FoxPro session.

When you use the SaveAs method, all the properties, events, and methods associated with the object are stored as well. Note that only objects created from Visual FoxPro base classes can be saved. User-defined classes cannot be saved. For a complete list of the Visual FoxPro base classes, see Base Classes in Visual FoxPro.

See Also

Reference

Name Property

Other Resources

Methods
SaveAsClass Method
SET CLASSLIB Command


SaveAsClass Method

Visual FoxPro 9.0 Language Reference
SaveAsClass Method
See Also

Saves an instance of an object as a class definition in a class library.

Object.SaveAsClass(ClassLibName, ClassName [, Description])

Parameters

ClassLibName

Specifies the name of the .vcx file in which to store the class definition.
ClassName

Specifies the name assigned to the class.
Description

Specifies the optional description for the class.

Remarks

Applies To: CheckBox | Collection Class | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | Custom | EditBox | Exception Class | Form | FormSet | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | PageFrame | ProjectHook Object | ReportListener Object | _SCREEN | Shape | Spinner | TextBox | Timer | ToolBar

When you use the SaveAsClass method, all the properties, events, and methods associated with the object are stored as part of the class definition.

See Also

Other Resources

Methods
SaveAs Method
SET CLASSLIB Command


SetAll Method

Visual FoxPro 9.0 Language Reference
SetAll Method
See Also Example

Assigns a property setting on all, or a certain class of, controls in a Container object.

Container.SetAll(cProperty, Value [, cClass])

Parameters

cProperty

Specifies the property to be set.
Value

Specifies the new setting for the property. The data type of Value depends on the property being set.
cClass

Specifies the class name (the class on which the object is based, not the Visual FoxPro base class for the object).

Remarks

Applies To: Column | CommandGroup | Container Object | Form | FormSet | Grid | OptionGroup | Page | PageFrame | _SCREEN | ToolBar

Use the SetAll method to set a property for all, or a certain class of, controls in a Container. For example, to set the BackColor property on all the Column objects in a Grid control to red, issue the following:

Copy Code
Form1.Grid1.SetAll("BackColor", RGB(255, 0, 0), "Column")

You can also set the properties for objects that are contained by other objects within the container. To set the ForeColor property of the Headers that are contained by each Column object contained in a Grid control to green, issue the following:

Copy Code
Form1.Grid1.SetAll("ForeColor", RGB(0, 255, 0), "Header")

Example

The following example uses the SetAll method with the DynamicBackColor property to specify the background colors for the records in a Grid control. If the number of a record displayed in the Grid is even, the record's DynamicBackColor is white, otherwise its DynamicBackColor is green.

A Grid control is placed on a form, and the customer table is opened and its contents displayed in the grid. The Caption property is used to specify a different header caption (Customer ID) for the CUST_ID field. A command button is placed on the form to close the form.
Copy Code
CLOSE ALL  && Close tables and databases
OPEN DATABASE (HOME(2) + 'Data\testdata')

USE customer  IN 0  && Opens Customer table

frmMyForm = CREATEOBJECT('Form')  && Create a form
frmMyForm.Closable = .f.  && Disable the window pop-up menu

frmMyForm.AddObject('cmdCommand1','cmdMyCmdBtn')  && Add Command button
frmMyForm.AddObject('grdGrid1','Grid')  && Add Grid control

frmMyForm.grdGrid1.Left = 25  && Adjust Grid position

frmMyForm.grdGrid1.SetAll("DynamicBackColor", "IIF(MOD(RECNO( ), 2)=0, RGB(255,255,255), RGB(0,255,0))", "Column")  && Alternate white and green records

frmMyForm.grdGrid1.Visible = .T.  && Grid control visible
frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible
frmMyForm.grdGrid1.Column1.Header1.Caption = 'Customer ID'

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close form
      CLOSE ALL  && Close table and database
ENDDEFINE

See Also

Other Resources

SaveAs Method
SaveAsClass Method
Methods
Language Reference


SetData Method

Visual FoxPro 9.0 Language Reference
SetData Method
See Also

Places data in the OLE drag-and-drop DataObject. Available at run time only.

oDataObject.SetData(eData [, nFormat | cFormat])

Parameters

eData

Specifies the data placed on the DataObject. If you omit the optional nFormat and cFormat arguments, Visual FoxPro places the data on the DataObject in the CF_TEXT and CFSTR_OLEVARIANT formats. If eData is an array, precede eData with an ampersand (@). An array is placed on the DataObject in the CFSTR_OLEVARIANTARRAY format. An error is generated if eData is an object reference or a general field, or the array contains an object reference.
nFormat| cFormat

Specifies the format of the data placed on the DataObject. The following table lists the values for some common data formats with a description of each format. You can specify a user-defined format with cFormat. In this case, eData must be of character type or a binary type created with CREATEBINARY( ).

Data format* nFormat| cFormat Description

CF_TEXT

1

Text format.

CF_OEMTEXT

7

Text format containing characters in the OEM character set.

CF_UNICODETEXT

13

Unicode text format.

Note:
Available only for versions of Visual FoxPro running on Windows NT 4.0 or later.

CF_FILES or CF_HDROP

15

A handle that identifies a list of files, such as a set of files dragged from the Windows Explorer.

CFSTR_OLEVARIANTARRAY

"OLE Variant Array"

An array. Multiple values can be transferred in a single drag-and-drop operation with this format.

For example, this format can be used to drag a set of items in a list box to another list box.

CFSTR_OLEVARIANT

"OLE Variant"

A variant. All data types in Visual FoxPro are represented as variants. This format can be used to drag and drop Visual FoxPro data without losing the data type.

CFSTR_VFPSOURCEOBJECT

"VFP Source Object"

A reference to the Visual FoxPro drag source object.
* Defined in FOXPRO.H.

Remarks

Applies To: DataObject Object

The SetData method can only be executed in the OLEStartDrag and OLESetData events.

See Also

Other Resources

ClearData Method
CREATEBINARY( ) Function
GetData Method
GetFormat Method
OLE Drag-and-Drop Overview
OLEStartDrag Event
SetFormat Method
Methods
Language Reference


SetFocus Method

Visual FoxPro 9.0 Language Reference
SetFocus Method
See Also

Assigns the focus to a control.

Control.SetFocus

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | Container Object | Control Object | EditBox | Grid | ListBox | OLE Bound Control | OLE Container Control | OptionButton | Page Object | Spinner | TextBox

You cannot assign the focus to a control if the control's Enabled or Visible property is set to false (.F.), or the control's When event returns false (.F.). If the Enabled or Visible property has been set to false (.F.), you must first set it to true (.T.) before the control can receive the focus from the SetFocus method.

Once a control has the focus, any user input is directed to that control.

In Visual FoxPro 9.0, the SetFocus method is not supported in the When Event, Valid Event, RangeHigh Event and RangeLow Event events. However, you can include a RETURN Command with an object name (RETURN <ObjectName>) in these events to set the focus to another control. If a RETURN command with an object name is included, the focus is set to the control specified with <ObjectName>.

The object specified in the RETURN command must be a valid Visual FoxPro object that can receive the focus. If the object you specify is disabled or cannot receive the focus, the next object in the tab order receives the focus. Focus remains with the current object if you specify an invalid object.

RETURN <ObjectName> allows you to set the focus to an object on another visible form. You can also set the focus to an object on a non-visible page of a pageframe, but you must include code to activate that page (for example, PageFrame1.ActivePage = 2).

See Also

Other Resources

Enabled Property
GotFocus Event
LostFocus Event
Visible Property
Methods
Language Reference


SetFormat Method

Visual FoxPro 9.0 Language Reference
SetFormat Method
See Also

Places a data format in the OLE DataObject object. Available at run time only.

You can call the SetFormat method in the OLEStartDrag and OLESetData events.

oDataObject.SetFormat(nFormat | cFormat)

Parameters

nFormat| cFormat

Specifies the format of the data placed on the DataObject object. You can also create your own format by specifying a unique character string for cFormat. The following table lists values for some common data formats with a description of each format.

Data format* nFormat| cFormat Description

CF_TEXT

1

Text format.

CF_OEMTEXT

7

Text format containing characters in the OEM character set.

CF_UNICODETEXT

13

Unicode text format.

Note:
Available only for versions of Visual FoxPro running on Windows NT 4.0 or later.

CF_FILES or CF_HDROP

15

A handle that identifies a list of files, such as a set of files dragged from the Windows Explorer.

CFSTR_OLEVARIANTARRAY

"OLE Variant Array"

An array. Multiple values can be transferred in a single drag-and-drop operation with this format.

For example, this format can be used to drag a set of items in a list box to another list box.

CFSTR_OLEVARIANT

"OLE Variant"

A variant.

All data types in Visual FoxPro are represented as variants. This format can be used to drag and drop Visual FoxPro data without losing the data type.

CFSTR_VFPSOURCEOBJECT

"VFP Source Object"

A reference to the Visual FoxPro drag source object.
* Defined in FOXPRO.H.

Remarks

Applies To: DataObject Object

You can place a data format in the DataObject object before placing the corresponding data on the DataObject object. If you place a data format in the DataObject object without corresponding data and invoke the GetData method in the OLEDragDrop event, the OLESetData event is executed for the drag source. The drag source can then place the data on the DataObject with the SetData method in the OLESetData event.

Tip:
When using data formats that are not natively supported by Visual FoxPro or when using a large number of formats, you can improve OLE drag-and-drop performance by placing only the data formats on the DataObject object when a large amount of data is placed on the DataObject object.

See Also

Other Resources

Methods
ClearData Method
GetData Method
GetFormat Method
OLE Drag-and-Drop Overview
OLEDragDrop Event
OLESetData Event
OLEStartDrag Event
SetData Method


SetMain Method

Visual FoxPro 9.0 Language Reference
SetMain Method
See Also

Sets the main file in a project.

Object.SetMain([cFileName])

Parameters

cFileName

Specifies a file in the project to set as the main file. The main file can be a program or a form. Be sure to include the file extension in cFileName. If cFileName is omitted or is an empty string, no file in the project is set as the main file.

Remarks

Applies To: Project Object

The SetMain method returns true (.T.) if the file you specify is set as the main file. False (.F.) is returned if the file you specify is not in the project or the file you specify is not the proper file type.

The main file is a program (.prg file) or form (.scx file) that serves as the execution starting point for a compiled application, and from which other components of your application are called. Typically, the main file sets the application's operational environment, runs menu programs or forms to display the application's interface, and establishes the event loop of the application with the READ EVENTS command. You must designate a main file in the Project Manager before you can create an application (.app) or executable file (.exe) from the project.

Note:
Specifying a file as the main file in a project also sets the project's MainFile property.

See Also

Other Resources

MainFile Property
Methods
Language Reference


SetVar Method

Visual FoxPro 9.0 Language Reference
SetVar Method
See Also

Creates a variable and stores a value to the variable for an instance of the Visual FoxPro application automation server.

ApplicationObject.SetVar(cVariableName, eValue)

Return Value

cVariableName

Specifies the name of the variable to create.
eValue

Specifies the value stored to the variable. If the variable specified with cVariableName already exists, the new value is store to the variable.

Remarks

Applies To: Application Object | _VFP System Variable

While the DoCmd method can be used to set a variable to a character value, the SetVar method should be used to set a variable to other data types.

See Also

Other Resources

DoCmd Method
Eval Method
STORE Command
Methods
Language Reference


SetViewPort Method

Visual FoxPro 9.0 Language Reference
SetViewPort Method
See Also

Sets the values of the ViewPortLeft and ViewPortTop properties for a form.

Object.SetViewPort(nLeft, nTop)

Parameters

nLeft

Specifies the value of the ViewPortLeft property for the form.
nTop

Specifies the value of the ViewPortTop property for the form.

Remarks

Applies To: Form

The SetViewPort method returns true (.T.) if the ViewPortLeft and ViewPortTop properties are successfully set; otherwise false (.F.) is returned. The SetViewPort method is ignored for forms that do not contain scroll bars.

The unit of measurement for the ViewPortLeft and ViewPortTop properties is determined by the form's ScaleMode property setting – pixels (the default) or foxels.

See Also

Other Resources

ScaleMode Property
ScrollBars Property
ViewPortLeft Property
ViewPortHeight Property
ViewPortTop Property
ViewPortWidth Property
Methods
Language Reference


Show Method (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Show Method (Visual FoxPro)
See Also

Displays a form and determines whether the form is modal or modeless.

 [FormSet.]Object.Show([nStyle])

Parameters

nStyle

Determines how a form is shown. The following values are valid:

Value Description

1

Modal. No user input (keyboard or mouse) can occur in any other form or in the menu until the modal form is hidden or released. The program must hide or release a modal form (usually in response to some user action) before further user input can occur. Although other forms in your application are disabled when a modal form is displayed, other applications are not.

2

(Default) Modeless. Code that occurs after the Show method is run as it is encountered.
If you omit nStyle, the form is shown in the style specified by the WindowType property.

Remarks

Applies To: Form | FormSet | _SCREEN | ToolBar

The Show method sets a form or form set's Visible property to true (.T.) and makes the form the active object. If a form's Visible property is already set to true (.T.), the Show method makes it the active object.

If a form set is activated, the last active form in the form set also becomes active. If no form is active, the form that was added to the FormSet class definition first is made active.

Forms contained within a form set retain their Visible property setting. If a form's Visible property is set to false (.F.), the Show method for the form set does not show the form.

See Also

Other Resources

Activate Event
Hide Method
Visible Property
WindowType Property
Methods
Language Reference


ShowWhatsThis Method

Visual FoxPro 9.0 Language Reference
ShowWhatsThis Method
See Also

Displays the Whats This Help topic specified for an object with the WhatsThisHelpID property.

Object.ShowWhatsThis

Return Value

Object

Specifies the object for which the Whats This Help topic is displayed.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Shape | Spinner | TextBox | Timer | ToolBar

The ShowWhatsThis method is automatically called when the F1 key is pressed. If the WhatsThisHelp property is set to true (.T.), the Whats This Help topic for the object, specified with the WhatsThisHelpID property, is displayed. If the WhatsThisHelp property is set to false (.F.), the Help topic for the object, specified with the HelpContextID property, is displayed.

See Also

Other Resources

WhatsThisButton Property
WhatsThisMode Method
WhatsThisHelp Property
WhatsThisHelpID Property
Methods
Language Reference


SupportsListenerType Method

Visual FoxPro 9.0
SupportsListenerType Method
See Also Example

Specifies whether the ReportListener supports a particular type of report rendering.

? oReportListener.SupportsListenerType(iListenerType)

Parameters

iListenerType

Specifies the type of rendering mechanism for which the ReportListener indicates support.

Return Value

Logical data type.

Returns True (.T.) if the parameter you pass identifies a supported type.

Remarks

Applies To: ReportListener Object.

The ReportListener class will not error if ListenerType is set to a value it does not recognize; it simply provides no output. Your derived classes should follow the same strategy. Implementing SupportsListenerType provides a way to let the user of your class know what your class can handle, without triggering an error.

Classes derived from ReportListener can use this method to eliminate certain forms of natively-supported output from their supported types. For example, you could create a class that requires all page images to be available at the end of the report run, just as Preview does. This class supports only ListenerType values 1 and 3, the two values that allow you to use OutputPage to request page images at the end of the report run. The class returns False (.F.) for the native ListenerType values -1, 0 and 2. These ListenerType values do not cache page images and therefore do not provide the functionality your class needs.

Note:
See ListenerType Property for more information about supported and recognized ListenerType values. This topic also has another code example using the SupportsListenerType method.

Classes derived from ReportListener are not required to return True (.T.) for additional values, even if they are registered with additional integer values in the Report Output Application. A class can opt to respect all native ListenerType values (0 through 3), to provide all internally-supported output results, while using its OutputType value, as received from the Report Output Application, to determine an alternative output result.

For example, the ReportListener HTML Foundation Class supports all native ListenerType values and does not add to them. It provides an alternative output result, but does not adjust either its ListenerType value or the SupportsListenerType method. For this reason, you can choose to instruct the HtmlListener to preview or print, using the appropriate ListenerType values, at the same time as it generates HTML. For more information, see OutputType Property (Visual FoxPro).

Example

In the following example, you pass the integer value 99 to an instance of the ReportListener baseclass. You receive a return value of False (.F.) because ReportListener does not support this type. You next pass the integer value 2, and receive a return value of True (.T.), because this is a supported Listenertype.
Copy Code
LOCAL loReportListener
loReportListener = CREATEOBJECT("ReportListener")
? loReportListener.SupportsListenerType(99)
* displays: .F.
? loReportListener.SupportsListenerType(2)
* displays: .T.

See Also

Reference

ReportListener Object

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)
Report Output Application
ReportListener Foundation Classes


TextHeight Method

Visual FoxPro 9.0 Language Reference
TextHeight Method
See Also

Returns the height of a text string as it would be displayed in the current font.

 [nHeight =] [Form.]TextHeight(cText)

Parameters

nHeight

Returns a value in pixels specifying the height of the text string.
cText

Specifies the character string for which the text height is determined.

Remarks

Applies To: Form | _SCREEN

The TextHeight method determines the amount of vertical space required to display cText. The height returned includes the leading space above and below the character string, so you can use the height returned to calculate and position multiple lines of text within the form. If cText contains embedded carriage returns, the TextHeight method returns the cumulative height of the lines, including the leading space above and below each line.

See Also

Other Resources

FontSize Property
ScaleMode Property
TextWidth Method
Methods
Language Reference


TextWidth Method

Visual FoxPro 9.0 Language Reference
TextWidth Method
See Also

Returns the width of a text string as it would be displayed in the current font.

 [nWidth =] [Form.]TextWidth(cText)

Parameters

nWidth

Returns a value in pixels specifying the width of the text string.
cText

Specifies the character string for which the text width is determined.

Remarks

Applies To: Form | _SCREEN

The TextWidth method determines the amount of horizontal space required to display cText.

If you want to get the length of a character expression with respect to the average character width for a font, use the TXTWIDTH( ) Function.

See Also

Other Resources

FontSize Property
ScaleMode Property
TextHeight Method
Methods


ToCursor Method

Visual FoxPro 9.0 Language Reference
ToCursor Method
See Also

Creates a cursor specified by XMLTable with the fields described by the XMLTable Fields collection and loads it with data from the referenced XML document.

ToCursor is supported only for XMLTable objects in the XMLAdapter Tables collection.

XMLTable.ToCursor( [ lAppend [, cAlias [, nCodePage ]]] )

Parameters

lAppend

Specifies whether to append data or records to an existing cursor specified by the cAlias parameter. The following table lists the values for lAppend.

lAppend Description

False (.F.)

(Default) Does not add fields to an existing cursor.

True. (.T.)

Adds fields to an existing cursor.
cAlias

Specifies the alias for the target cursor. The value of cAlias defaults to the XMLTableAlias property, including when cAlias is an empty string ("").
nCodePage

Specifies a code page. The default value is zero (0).

Remarks

Applies To: XMLTable Class

If the XMLField Alias property is empty, the XMLTable ToCursor method disregards XMLField objects and creates a cursor that does not include any fields specified by those XMLField objects.

The nCodePage parameter must exist in the list of supported code pages. If nCodePage is zero (0) and the UseCodePage property is False (.F), the current default code page is used. For more information, see Code Pages Supported by Visual FoxPro and the UseCodePage Property.

When you use ToCursor to append data, Visual FoxPro adds an empty row if no XMLField object name matches any cursor column.

When mapping binary fields to Character data types, Visual FoxPro fills any remaining white space with 0x00 characters (CHR(0) or zeros) after decoding.

If the RespectNesting property of the XMLAdapter is True (.T.), the node must be an immediate child for the outer table's node. If the table is not nested, the node must be an immediate child for the XMLAdapter's node.

The ToCursor method fails if XMLAdapter.XMLNameIsXPath property is True (.T.) and XMLAdapter.IsDiffgram is True (.T.).

See Also

Reference

RespectNesting Property
XMLNameIsXPath Property
IsDiffGram Property
ToCursor Method

Other Resources

Methods
XMLTable Object Properties, Methods, and Events
Fields Collection (XMLTable)
XMLName Property
Alias Property
XMLField Class


ToXML Method

Visual FoxPro 9.0 Language Reference
ToXML Method
See Also

Generates XML to a file or memory variable.

XMLAdapter.ToXML( cXMLDocument [, cSchemaLocation [, lFile [, lIncludeBefore [, lChangesOnly ]]]] )

Parameters

cXMLDocument

Specifies the file or memory variable name for the XML document.
cSchemaLocation

Specifies the location for a reference to external schema. The default value of cSchemaLocation is empty (""). If cSchemaLocation is empty and external schema has been generated, the value of XMLAdapterXMLSchemaLocation is used as the external schema reference.
lFile

Specifies whether cXMLDocument is a file. The default value of lFile is False (.F.).
lIncludeBefore

Specifies whether to include the diffgr:before section in the DiffGram. The diffgr:before section contains the original version of a row. The default value of lIncludeBefore is False (.F.). If lIncludeBefore is True (.T.), Visual FoxPro filters deleted records, regardless of the current filter setting, such as SET FILTER TO NOT DELETED( ) and SET DELETED ON or OFF. All deleted records in the table buffer are inserted in the diffgr:before section but have no matching row in the DiffGram DataInstance block. Although you might want to hide deleted rows by using a filter, the DiffGram indicates which rows were deleted so that the data source can be correctly updated. Visual FoxPro disregards lIncludeBeforeif the XMLAdapter IsDiffGram property is False (.F.).
lChangesOnly

Specifies whether the XML should contain changes only. Visual FoxPro disregards lChangesOnlyif the XMLAdapter IsDiffGram property is False (.F.) or if lIncludeBefore is False (.F.).

Remarks

Applies To: XMLAdapter Class

If the XMLTable Alias property is empty, no XML elements are generated for that XMLTable object, however, the table is included in the schema if one is generated.

For character fields, Visual FoxPro fills any remaining space in the field with white space (0x20). When ToXML maps character fields to binary fields and performs encoding, ToXML encodes the trailing white space regardless of the value for the XMLAdapter PreserveWhiteSpace property.

The following XMLAdapter property settings affect how ToXML is executed:

  • ForceCloseTag

  • FormattedOutput

  • PreserveWhiteSpace

  • RespectCursorCP

  • RespectNesting Property

  • UseCodePage Property

  • UTF8Encoded

  • XMLNameIsXPath Property

  • XMLSchemaLocation

Nested XML When the XMLAdapter RespectNesting property is True (.T.) and a relationship between the tables is specified, ToXML generates nested XML. Nesting is not supported if the IChangesOnly parameter is set to True (.T.).

XML Encoding When the XMLAdapter RespectCursorCP property is True (.T.), XMLAdapter UTF8Encoded is False (.F.), and two or more table aliases are referenced in the Tables collection, those tables should use the same code page. If you also set the UseCodePage property, the results generated by ToXML varies. See UseCodePage property for a table that shows the results.

Numeric Overflow Conditions An XMLAdapter object does not load XML containing Visual FoxPro-type numeric overflow conditions, for example, *****.**, in the place of a Numeric or Integer value. The Microsoft XML Core Services (MSXML) parser causes an error similar to the following:

Copy Code
Error 2110 (XML Error): XML Error: XML Parse error: The value of '***' is invalid according to its data type.
The element: 'myfield' has an invalid value according to its data type.
Line 7, Position 17.
   <myfield>***</myfield>

If the XMLNameIsXpath property is True (.T.) for XMLAdapter or XMLTable object and the XMLName property is not empty, ToXML fails. ToXML ignores XMLField objects that use XPath expressions.

See Also

Other Resources

Methods
XMLAdapter Object Properties, Methods, and Events
IsDiffGram Property
Alias Property
XMLTable Class
Tables Collection (XMLAdapter)


UndoCheckOut Method

Visual FoxPro 9.0 Language Reference
UndoCheckOut Method
See Also

Discards any changes made to a file and checks the file back into source code control.

Object.UndoCheckOut( )

Remarks

Applies To: File Object

True (.T.) is returned if the changes to the file are successfully discarded and the file is checked back into source code control; otherwise a false (.F.) is returned.

See Also

Other Resources

AddToSCC Method
CheckIn Method
CheckOut Method
GetLatestVersion Method
RemoveFromSCC Method
Methods
Language Reference


Unnest Method

Visual FoxPro 9.0
Unnest Method
See Also

Removes the hierarchical relation of a nested XMLTable object while leaving the XMLTables nested.

XMLTable.Unnest( )

Remarks

Applies To: XMLTable Class

If an XMLtable object is nested using the Nest Method, the Unnest method removes the hierarchical relation to the XMLtable. If the XMLTable is not currently nested, the Unnest method does nothing.

See Also

Reference

Nest Method

Other Resources

Methods (Visual FoxPro)


UpdateStatus Method

Visual FoxPro 9.0
UpdateStatus Method
See Also

Triggers a change of information in the user interface elements provided by DoStatus.

oReportListener.UpdateStatus()

Parameters

None.

Return Value

None.

Remarks

Applies To: ReportListener Object.

This method provides an opportunity for the ReportListener object to evaluate whether the conditions in the report have changed in some way that justifies calling the DoStatus method to display new information to the user.

The frequency with which you call this method, and at what points during the report run you choose to call it, depend on what type of feedback your ReportListener provides.

Tip:
You choose the frequency or schedule with which you show feedback during a report run, as well as the feedback message you show, by overriding this method. You determine the way you display the feedback message by overriding the DoStatus method.

The native ReportListener shows the progress of the report by invoking UpdateStatus each time it renders a new page. The ReportListener User Feedback Class, however, evaluates the current record in the report's driving alias, and updates its progress bar each time this record changes.

See Also

Reference

ReportListener Object
ReportListener User Feedback Foundation Class
DoStatus Method

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)


WhatsThisMode Method

Visual FoxPro 9.0 Language Reference
WhatsThisMode Method
See Also

Displays the What's This Help question mark mouse pointer and enables What's This Help mode.

 [Form.]Object.WhatsThisMode

Remarks

Applies To: Form

Calling the WhatsThisMode method changes the mouse pointer to an arrow with a question mark and enables What's This Help mode. Clicking an object displays the What's This Help topic specified by the WhatsThisHelpID property for the object. Pressing ESC disables the What's This Help mode and returns the mouse pointer to its original state.

See Also

Other Resources

HelpContextID Property
SET HELP Command
ShowWhatsThis Method
WhatsThisButton Property
WhatsThisHelp Property
WhatsThisHelpID Property
Methods
Language Reference


WriteExpression Method

Visual FoxPro 9.0 Language Reference
WriteExpression Method
See Also

Writes an expression to a property. Available at design time and run time.

Object.WriteExpression[cPropertyName, cExpression]

Parameters

cPropertyName

Specifies the name of the property to write the expression to.
cExpression

Specifies a character string that is written to the property sheet as an expression.

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | CommandGroup | Cursor | CursorAdapter Class | Custom | DataEnvironment | EditBox | Exception Class | Form | FormSet | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Relation | ReportListener Object | Session Object | Shape | Spinner | TextBox | Timer | ToolBar

See Also

Other Resources

ReadExpression Method
Methods
Language Reference


WriteMethod Method

Visual FoxPro 9.0 Language Reference
WriteMethod Method
See Also

Writes the specified text to the specified method. Available at design time only.

Control.WriteMethod(cMethodName, cMethodText [,lCreateMethod [, nVisibility [, cDescription]]])

Parameters

cMethodName

Specifies the name of the method to write the specified text to.
cMethodText

Specifies the text to write to the specified methods.
lCreateMethod

Specifies whether the method is created when it doesn't already exist. Because this method is useful only at design time, you must save the form or class before changes can be effective.
nVisibility

Specifies the visibility of the new method.

nVisibility Visibility

1

Public

2

Protected

3

Hidden
cDescription

Specifies a description for the new method. The method description is limited to 255 characters.

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | CommandGroup | Custom | EditBox | Exception Class | Form | FormSet | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | ReportListener Object | Shape | Spinner | TextBox | Timer | ToolBar

See Also

Other Resources

ReadExpression Method
ReadMethod Method
WriteExpression Method
Methods
Language Reference


ZOrder Method

Visual FoxPro 9.0 Language Reference
ZOrder Method
See Also

Places a specified form or control at the front or back of the z-order within its graphical level. Places a control contained by the ToolBar object at the front or back of the controls array that determines the order in which controls appear in the toolbar.

 [Object.]ZOrder([nOrder])

Return Value

nOrder

Specifies an integer indicating the position of the object relative to other objects. If you omit nOrder, the setting is 0.

Setting Description

0

(Default) The object is positioned at the front of the z-order.

1

The object is positioned at the back of the z-order.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | _SCREEN | Shape | Spinner | TextBox | ToolBar

There are two graphical layers associated with objects. The back layer is the drawing space, where the results of the graphics methods appear, and the front layer is the object layer. The contents of one layer covers the contents of the layer behind. The ZOrder method arranges objects only within the layer where the object appears.

Note:
For a Page object, the ZOrder method does not affect the PageOrder property setting. ZOrder only determines the Page that is on top and active.

For more information about using controls, see Using Controls.

See Also

Other Resources

AlwaysOnBottom Property
AlwaysOnTop Property
PageOrder Property
Methods
Language Reference


Events (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Events (Visual FoxPro)
See Also

For information about backward compatible-only language reference, see Backward-Compatible Language Elements.

Activate Event

AdjustObjectSize Event

AfterBand Event

AfterBuild Event

AfterCloseTables Event

AfterCursorAttach Event

AfterCursorClose Event

AfterCursorDetach Event

AfterCursorFill Event

AfterCursorRefresh Event

AfterCursorUpdate Event

AfterDelete Event

AfterInsert Event

AfterRecordRefresh Event

AfterUpdate Event

AfterDock Event

AfterReport Event

AfterRowColChange Event

BeforeBand Event

BeforeCursorAttach Event

BeforeCursorClose Event

BeforeCursorDetach Event

BeforeCursorFill Event

BeforeCursorRefresh Event

BeforeCursorUpdate Event

BeforeDelete Event

BeforeInsert Event

BeforeDock Event

BeforeOpenTables Event

BeforeRecordRefresh Event

BeforeReport Event

BeforeRowColChange Event

BeforeUpdate Event

Click Event

DBC_Activate Event

DBC_AfterAddTable Event

DBC_AfterAppendProc Event

DBC_AfterCloseTable Event

DBC_AfterCopyProc Event

DBC_AfterCreateConnection Event

DBC_AfterCreateOffline Event

DBC_AfterCreateTable Event

DBC_AfterCreateView Event

DBC_AfterDBGetProp Event

DBC_AfterDBSetProp Event

DBC_AfterDeleteConnection

DBC_AfterDropOffline Event

DBC_AfterDropTable Event

DBC_AfterModifyConnection

DBC_AfterModifyProc Event

DBC_AfterModifyTable

DBC_AfterModifyView

DBC_AfterOpenTable Event

DBC_AfterRemoveTable Event

DBC_AfterRenameConnection

DBC_AfterRenameTable

DBC_AfterRenameView

DBC_AfterValidateData Event

DBC_BeforeAddTable Event

DBC_BeforeAppendProc Event

DBC_BeforeCloseTable Event

DBC_BeforeCopyProc Event

DBC_BeforeCreateConnection Event

DBC_BeforeCreateOffline Event

DBC_BeforeCreateTable Event

DBC_BeforeCreateView Event

DBC_BeforeDBGetProp Event

DBC_BeforeDBSetProp Event

DBC_BeforeDeleteConnection Event

DBC_BeforeDropOffline Event

DBC_BeforeDropTable Event

DBC_BeforeModifyConnection Event

DBC_BeforeModifyProc Event

DBC_BeforeModifyTable Event

DBC_BeforeModifyView Event

DBC_BeforeOpenTable Event

DBC_BeforeRemoveTable Event

DBC_BeforeRenameConnection Event

DBC_BeforeRenameTable Event

DBC_BeforeRenameView Event

DBC_BeforeValidateData Event

DBC_CloseData Event

DBC_Deactivate Event

DBC_ModifyData Event

DBC_OpenData Event

DBC_PackData Event

DblClick Event

Deactivate Event

Deleted Event

Destroy Event

DoCmd Method

DownClick Event

DragDrop Event

DragOver Event

DropDown Event

Error Event

ErrorMessage Event

EvaluateContents Event

GotFocus Event

Init Event

InteractiveChange Event

KeyPress Event

Load Event

LoadReport Event

LostFocus Event

Message Event

MiddleClick Event

MouseDown Event

MouseEnter Event

MouseLeave Event

MouseMove Event

MouseUp Event

MouseWheel Event

Moved Event

OLECompleteDrag Event

OLEDragOver Event

OLEGiveFeedBack Event

OLESetData Event

OLEStartDrag Event

OnMoveItem Event

Paint Event

ProgrammaticChange Event

QueryAddFile Event

QueryModifyFile Event

QueryNewFile Event

QueryRemoveFile Event

QueryRunFile Event

QueryUnload Event

RangeHigh Event

RangeLow Event

ReadActivate Event

ReadDeactivate Event

ReadShow Event

ReadValid Event

ReadWhen Event

Resize Event

RightClick Event

SCCInit Event

SCCDestroy Event

Scrolled Event

Timer Event

UIEnable Event

Undock Event

Unload Event

UnloadReport Event

UpClick Event

Valid Event

When Event

See Also

Other Resources

Language Reference


Activate Event (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Activate Event (Visual FoxPro)
See Also

Occurs when a Form, FormSet, Project, or Page object becomes active or when a Toolbar object is shown.

PROCEDURE Object.Activate

Remarks

Applies To: _SCREEN System Variable | Form Object | FormSet Object | ProjectHook Object | Page Object | ToolBar Object

Triggers for this event depend on the type of object:

  • A Form object is activated by a user action, such as clicking a form or a control or when the Show method for the Form object is called.

  • A FormSet object is activated when a form in the form set receives focus or when the Show method for the form set is called.

  • A ProjectHook is activated by a user action, such as clicking on the Project window, or by a command such as ACTIVATE WINDOW project.

  • A Page object is activated by user action, such as clicking the tab of the page or clicking a control contained in the page, or if the ActivePage property of the page frame containing it is set to the page's number.

  • A ToolBar object is activated when the Show method for the ToolBar is called.

If you use the Show method for a form set, all forms with their Visible property set to True (.T.) are shown. The Activate event is triggered first for the form set, then for the form, and then for the page.

See Also

Other Resources

ActivePage Property
Deactivate Event
GotFocus Event
LostFocus Event
SetFocus Method
Show Method
Visible Property
Events
Language Reference


AdjustObjectSize Event

Visual FoxPro 9.0
AdjustObjectSize Event
See Also Example

Occurs just before ReportListener begins rendering layout elements of type Shape or Picture.

PROCEDURE Object.AdjustObjectSize
LPARAMETERS nFRXRecno, oObjProperties

Parameters

Visual FoxPro passes the AdjustObjectSize event parameters in the following order:

nFRXRecno

Integer data type, specifying the record number in the report or label definition file (frx or lbx) describing the layout element being rendered.
oObjProperties

An object of Empty class, with members providing values relevant to adjusting the size of a Shape or Picture.

oObjProperties member Type Usage

reload

Logical, defaults to .F.

Flag to alert the ReportListener if you make changes.

Set this value to True (.T.) to notify the ReportListener of changes to height or width.

height

Integer, valid values from 0 to 64000

Height of layout element, in 960ths of an inch.

If you change this value and set reload to .T., the ReportListener renders with the revised value.

width

Integer, valid values from 0 to 64000

Width of layout element, in 960ths of an inch.

If you change this value and set reload to .T. , the ReportListener does not use the revised value but provides the revised value in the Render method for this layout element.

top,left

Integer, readonly

Coordinates of top- and left-most point of the Shape or Picture element. Provides information about the position of the layout element on the output page, for reference in calculations.

reattempt

Logical, readonly

Indicates whether this element has been pushed to a second page because it did not fit on the previous page.

maxheightavailable

Integer, readonly

Indicates the available room on this page for this element, allowing for the height of subsequent bands (such as the page footer) for which space must be reserved.
Note:
Microsoft reserves the right to invoke AdjustObjectSize for additional report and label layout elements, as needed, and to add to the oObjProperties members appropriately for these additional layout element types. You can use nFRXRecno to test for layout element type, as shown in the sample code in Render Method.

Remarks

Applies To: ReportListener Object.

VisualFoxPro invokes AdjustObjectSize once for each layout element of type Shape or Picture, unless it finds no code in the derived ReportListener class at run time. It also does not call AdjustObjectSize if the element is in a band not marked Stretchable (fixed band height). For more information, see Report Band Properties Dialog Box.

Tip:
To enhance performance, Visual FoxPro does not call either AdjustObjectSize or EvaluateContents if it determines that there is no code in the ReportListener for the event. If you usually include placeholder code or generalized code in every event, consider omitting such code for these two events, especially if the class level is abstract (never directly instantiated). Only include code at the class levels that actually use this functionality. The performance cost for AdjustObjectSize increases by approximately the same amount for each Shape or Picture element in a report; the performance cost for EvaluateContents varies. For more information, see EvaluateContents Event.

This feature is primarily for the use of ReportListeners interpreting certain Shapes as placeholders for custom objects, which they draw in the space reserved for the Shape in the layout.

AdjustObjectSize is not supported for Shapes or Pictures that stretch between any header and footer pair of bands, and does not support changes to shape curvature.

Although the oObjProperties parameter has several members, the only value that will affect the ReportListener’s rendering behavior is a change to oObjProperties.height. Change to oObjProperties.height is respected only if the new height is greater than the original height. This change will cause a change to the element’s height as rendered by the ReportListener and also cause other floating layout elements to be pushed down, and the band to stretch to accommodate the new height.

Because it is not supported for Shapes or Pictures that span bands, you cannot adjust the height of a Shape to continue through multiple pages. If the element does not fit on the page after the ReportListener has changed its height, the entire element will be pushed down to the next page. In some cases, because not all bands can span pages, this determination may result in the entire band being pushed to the next page. Refer to Report Bands for more information on which bands can span pages.

Use the oObjProperties.maxheightavailable member to determine the maximum size you can give the Shape or Picture without its being pushed entirely to the next page.

When you set a higher value than oObjProperties.maxheightavailable for oObjProperties.height and set oObjProperties.reload to True (.T.), the ReportListener's Render event is not called for this element on the current page. Instead, AdjustObjectPage is called again for the same element on the next page.

On the next page, oObjProperties.height is set back to its original value, oObjProperties.reattempt is set to True (.T.), and oObjProperties.maxheightavailable has a new value, based on the new value of oObjProperties.top on this page. At this point, you can re-evaluate the height you want for the element on the new page.

Caution:
If you have set a height value too large for any page, the element will not display. No immediate error occurs, but continued assignments of such a value will cause the element to be re-pushed to subsequent pages repeatedly. Use oObjProperties.reattempt to avoid trying to reload the same value repeatedly, after your initial attempt.

Changes to the oObjProperties.width value do not affect the ReportListener’s base rendering behavior; however, they will be passed to your derived class for use in Render if oObjProperties.reload is True (.T.).

Both oObjProperties.height and oObjProperties.width have a valid range of 0 to 64000. If either value is set out of range, it snaps to 0 or 64000 and no error occurs.

oObjProperties.top and oObjProperties.left are read-only. They are passed for your derived class' reference, since there is no other way for the ReportListener to determine where in the page layout this instance of the element will be rendered.

Example

This example adjusts the height of a layout element in a report to display a differently-sized image for each record in a table. The filename for the image is stored in one column of the table and the desired image height (in inches) is stored in a second column of the table. The images referenced in each record may be a different height, and some records have no image file included. In the report layout, the image element is set to be only a few pixels high, an expression representing the table column holding the image filename is associated with this layout element. Elements in the same band below this region are set to float and stretch.

In the BeforeReport code, the ReportListener determines which record in the FRX layout definition describes the image, and saves this information for later use. When the AdjustObjectSize event occurs, the ReportListener checks its nFRXRecno argument to see if FRX element being evaluated matches its stored record number for the image element. If it does, the ReportListener adjusts the height of the image element to match whatever image is associated with this record.

Tip:
Notice that the AdjustObjectSize code multiples the height value stored in the table by 960. The table stores its measurements in inches, and the ReportListener's rendering code handles measurements in 960 dots per inch (DPI).
Copy Code
DEFINE CLASS rl AS ReportListener
   FrxPic = 0

  PROCEDURE BeforeReport()
     SET DATASESSION TO (THIS.FRXDataSession)
     SELECT FRX
     LOCATE FOR ObjType = 17 && image
     IF EOF()
        THIS.FrxPic = 0
     ELSE
        THIS.FrxPic = RECNO()
     ENDIF
   ENDPROC

   PROCEDURE AdjustObjectSize(nFrxRecno,oProps)
       IF nFrxRecno = THIS.FrxPic
          SET DATASESSION TO (THIS.CurrentDataSession)
          IF (NOT EMPTY(MyTable.picFile))
             * express in DPI units:
             oProps.Height = MyTable.picInches * 960
             oProps.Reload = .T.
          ENDIF
       ENDIF
   ENDPROC

ENDDEFINE

See Also

Tasks

How to: Add Shapes to Reports
How to: Add Pictures to Reports
How to: Set Stretching Report Controls

Reference

ReportListener Object
Round Rectangle Dialog Box
Rectangle/Line Dialog Box

Other Resources

Events (Visual FoxPro)
Language Reference (Visual FoxPro)


AfterBand Event

Visual FoxPro 9.0
AfterBand Event
See Also

Occurs directly after the Report System finishes processing a report band.

PROCEDURE Object.AfterBand
LPARAMETERS nBandObjCode, nFRXRecNo

Parameters

Visual FoxPro passes the AfterBand event parameters in the following order:

nBandObjCode

Integer data type, specifying the type of band, as stored in the ObjCode field of the report or label definition file (frx or lbx). Recognized numeric values for nBandObjCode are documented in the 60FRX.DBF table in the FILESPEC directory, as follows:

0

Title

1

Page Header

2

Column Header

3

Group Header

4

Detail

5

Group Footer

6

Column Footer

7

Page Footer

8

Summary

9

Detail Header

10

Detail Footer
For more information about 60FRX, see Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx).
nFRXRecno

Integer data type, specifying the record number in the report or label definition file (frx or lbx) describing the layout element being rendered.

Remarks

Applies To: ReportListener Object.

For each band in the report, the ReportListener triggers the BeforeBand event before the Report Engine runs any code in the OnEntry expression. It triggers the AfterBand event after any OnExit code runs.

Note:
Previous to running OnExit code and triggering the AfterBand event for a Detail or Detail Footer band, the Report Engine has moved the record pointer forward to the next record in the report scope. For information about the order of events in a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

See Also

Tasks

How to: Specify Expressions to Evaluate When Processing Bands

Reference

ReportListener Object
BeforeBand Event

Other Resources

Events (Visual FoxPro)
Language Reference (Visual FoxPro)


AfterBuild Event

Visual FoxPro 9.0 Language Reference
AfterBuild Event
See Also

Occurs after a project is rebuilt or an application file (.app), dynamic link library (.dll), or executable file (.exe) is created from a project.

PROCEDURE Object.AfterBuild
LPARAMETERS nError

Parameters

nError

The Visual FoxPro error number returned after the project is rebuilt or an .app, .dll, or.exe is created. If nError is 0, no errors occurred when the project was rebuilt or the .app, .dll, or.exe was created.

Remarks

Applies To: ProjectHook Object

See Also

Other Resources

BeforeBuild Event
Build Method
BUILD PROJECT Command
Events
Language Reference


AfterCloseTables Event

Visual FoxPro 9.0 Language Reference
AfterCloseTables Event
See Also

Occurs after the tables or views specified in the data environment for a form, form set, or report are released.

PROCEDURE DataEnvironment.AfterCloseTables

Remarks

Applies To: DataEnvironment Object

For a form or form set, the AfterCloseTables event occurs after the form set's or form's Unload event occurs and after any tables or views that were opened by the data environment are closed.

For a report, the AfterCloseTables event occurs after any tables or views that were opened by the data environment are closed.

The AfterCloseTables event occurs whenever the CloseTables method is called. The Destroy event of the data environment and its associated objects occurs after the AfterCloseTables event.

See Also

Other Resources

CloseTables Method
Destroy Event
Unload Event
Events
Language Reference


AfterCursorAttach Event

Visual FoxPro 9.0 Language Reference
AfterCursorAttach Event
See Also

Occurs immediately after the CursorAdapter object attempts to attach the cursor. You can use this event to perform tasks such as customize cursors and cursor adapters as appropriate and perform validations.

PROCEDURE Object.AfterCursorAttach
LPARAMETERS cAlias, lResult

Parameters

cAlias

Specifies the alias of the attached cursor or table.
lResult

Specifies True (.T.) if the cursor or table attached successfully and False (.F.) if not attached successfully.

Remarks

Applies To: CursorAdapter Class

In Visual FoxPro 9.0, the target record is kept current in an ADODB.Recordset during the AfterCursorAttach event.

See Also

Other Resources

Methods
CursorAdapter Object Properties, Methods, and Events
BeforeCursorAttach Event
CursorAttach Method


AfterCursorClose Event

Visual FoxPro 9.0 Language Reference
AfterCursorClose Event
See Also

Occurs immediately after a cursor closes. You can use this event to reset CursorAdapter properties and so on.

PROCEDURE Object.AfterCursorClose
LPARAMETERS cAlias, lResult

Parameters

cAlias

Specifies the alias of the closed cursor or table.
lResult

Specifies True (.T.) if cursor or table closes successfully and False (.F.) if not closed successfully, for example, cursor contained unsaved changes.

Remarks

Applies To: CursorAdapter Class

You must clear or reset the Alias property if you wish to remove its previous value. When an extended cursor closes, Visual FoxPro marks the CursorAdapter object as no longer attached to a cursor but does not clear the Alias property.

See Also

Other Resources

Methods
CursorAdapter Object Properties, Methods, and Events
Alias Property


AfterCursorDetach Event

Visual FoxPro 9.0 Language Reference
AfterCursorDetach Event
See Also

Occurs immediately after a CursorAdapter object detaches a cursor. You can use AfterCursorDetach to perform tasks such as reset cursor adapter properties and perform operations on the freed table.

PROCEDURE Object.AfterCursorAttach
LPARAMETERS cAlias, lResult

Parameters

cAlias

Specifies the alias of the detached cursor or table.
lResult

Specifies True (.T.) if the CursorAdapterCursorDetach method detaches the cursor or table successfully and False (.F.) if not detached successfully.

Remarks

Applies To: CursorAdapter Class

In Visual FoxPro 9.0, the target record is kept current in an ADODB.Recordset during the AfterCursorDetach event.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
BeforeCursorDetach Event
CursorDetach Method


AfterCursorFill Event

Visual FoxPro 9.0 Language Reference
AfterCursorFill Event
See Also Example

Occurs immediately after a CursorAdapter object attempts to create a new cursor.

PROCEDURE Object.AfterCursorFill
LPARAMETERS lUseCursorSchema, lnoDataOnLoad, cSelectCmd, lResult

Parameters

lUseCursorSchema

Specifies the value in the lUseCursorSchema parameter from the CursorFill method.
lnoDataOnLoad

Specifies the value in the lNoData parameter from CursorFill.
cSelectCmd

Specifies the same SelectCmd parameter used by the BeforeCursorFill event.
lResult

Specifies the True (.T.) or False (.F.) value returned by CursorFill.

Remarks

Applies To: CursorAdapter Class

If any of the first three parameters are changed in BeforeCursorFill, AfterCursorFill uses the changed values instead of actual values in the properties, which do not change.

In Visual FoxPro 9.0, the target record is kept current in an ADODB.Recordset during the AfterCursorFill event.

Example

The following example illustrates using the AfterCursorFill event to set the index order from a preset property:
Copy Code
PROCEDURE AfterCursorFill
LPARAMETERS lUseCursorSchema, noDataOnLoad, cSelectCmd, lResult
SELECT (this.Alias)
SET ORDER TO (this.Order)
ENDPROC

See Also

Reference

AfterCursorFill Event

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
CursorFill Method
SelectCmd Property
BeforeCursorFill Event


AfterCursorRefresh Event

Visual FoxPro 9.0 Language Reference
AfterCursorRefresh Event
See Also

Occurs after a CursorAdapter object attempts to refresh.

PROCEDURE Object.AfterCursorRefresh
LPARAMETERS cSelectCmd, lResult

Parameters

cSelectCmd

Specifies the current value of SelectCmd as established in the BeforeCursorFill event. For example, if the cSelectCmd parameter is changed in BeforeCursorFill, then the changed value of SelectCmd is used. However, the value in the SelectCmd property does not change.
lResult

Specifies the True (.T.) or False (.F.) value returned by the CursorRefresh method.

Remarks

Applies To: CursorAdapter Class

In Visual FoxPro 9.0, the target record is kept current in an ADODB.Recordset during the AfterCursorRefresh event.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
SelectCmd Property
BeforeCursorFill Event
BeforeCursorRefresh Event
CursorRefresh Method


AfterCursorUpdate Event

Visual FoxPro 9.0 Language Reference
AfterCursorUpdate Event
See Also

Occurs immediately after all intermediate AfterUpdate, AfterDelete, or AfterInsert events have occurred and before the TABLEUPDATE( ) function returns.

PROCEDURE Object.AfterCursorUpdate
LPARAMETERS nRows, lTableUpdateResult, cErrorArray

Parameters

nRows

Specifies the setting from the nRows parameter from a TABLEUPDATE( ) function operation.
lTableUpdateResult

Specifies the value returned by a TABLEUPDATE( ) operation.
cErrorArray

Contains the contents of the cErrorArray parameter from a TABLEUPDATE( ) operation. Visual FoxPro populates this array from TABLEUPDATE( ) only under the circumstances described by the cErrorArray description in the TABLEUPDATE( ) function.

Remarks

Applies To: CursorAdapter Class

AfterCursorUpdate occurs once upon the completion of the update process. If multiple rows are being updated, the AfterUpdate, AfterInsert, and AfterDelete events occur for each updated row as appropriate.

You can call the AERROR( ) function to retrieve errors from upstream data sources.

In Visual FoxPro 9.0, the target record is kept current in an ADODB.Recordset during the AfterCursorUpdate event.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
BeforeCursorUpdate Event
AfterDelete Event
AfterInsert Event
TABLEUPDATE( ) Function
AERROR( ) Function


AfterDelete Event

Visual FoxPro 9.0 Language Reference
AfterDelete Event
See Also

Occurs immediately after a delete operation for a record is performed.

Note:
If batch updating is used, that is, CursorAdapter BatchUpdateCount property is greater than 1, AfterDelete does not occur.

PROCEDURE Object.AfterDelete
LPARAMETERS cFldState, lForce, cDeleteCmd, lResult

Parameters

cFldState

Specifies the field states of the row being processed. This is the same value obtained from calling the following function:
Copy Code
GETFLDSTATE(-1)
For example, this value can be a character string consisting of deletion and edit status values for all fields in the table or cursor. If a table has five fields and only the first field has been edited, GETFLDSTATE( ) returns a value of 121111. The number 1 in the first position indicates that the deletion status has not changed.
lForce

Specifies the value of the lForce parameter from the TABLEUPDATE( ) function.
cDeleteCmd

Specifies the value of the cDeleteCmd parameter from the BeforeDelete event.
lResult

Specifies the value returned by running TABLEUPDATE( ) for this record. If lResult is True (.T.), the field states are cleared for this record. If lResult is False (.F.), the field states are not cleared for this record. You can change the value of lResult to override the result as returned.

Remarks

Applies To: CursorAdapter Class

You can call the AERROR( ) function to retrieve errors from upstream data sources.

In Visual FoxPro 9.0, the target record is kept current in an ADODB.Recordset during the AfterDelete event.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
GETFLDSTATE( ) Function
TABLEUPDATE( ) Function
BeforeDelete Event
AERROR( ) Function


AfterDock Event

Visual FoxPro 9.0 Language Reference
AfterDock Event
See Also

Occurs after docking a ToolBar object or a Form object, for example, after dragging the toolbar or form to a docking area or calling the Dock method.

PROCEDURE Object.AfterDock

Remarks

Applies To: Form Object | ToolBar Object

See Also

Other Resources

How to: Dock Forms
How to: Dock Toolbars
ADOCKSTATE( ) Function
BeforeDock Event
Dock Method
Dockable Property
Docked Property
DockPosition Property
GetDockState Method
Undock Event
Events
Language Reference


AfterInsert Event

Visual FoxPro 9.0 Language Reference
AfterInsert Event
See Also

Occurs immediately after an insert operation for a record is performed.

Note:
If batch updating is used, that is, the CursorAdapter BatchUpdateCount property is greater than 1, AfterInsert does not occur.

PROCEDURE Object.AfterInsert
LPARAMETERS cFldState, lForce, cInsertCmd, lResult

Parameters

cFldState

Specifies the field states of the row being processed. This is the same value obtained from calling the following function:
Copy Code
GETFLDSTATE(-1)
For example, this value can be a character string consisting of deletion and edit status values for all fields in the table or cursor. If a table has five fields and only the first field has been edited, GETFLDSTATE() returns a value of 121111. The number 1 in the first position indicates that the deletion status has not changed.
lForce

Specifies the value of the lForce parameter from the TABLEUPDATE() function.
cInsertCmd

Specifies the value of the cInsertCmd parameter from the BeforeInsert event.
lResult

Specifies the value returned by running TABLEUPDATE( ) for this record. If lResult is True (.T.), the field states are cleared for this record. If lResult is False (.F.), the field states are not cleared for this record. You can change the value of lResult to override the result as returned.

Remarks

Applies To: CursorAdapter Class

You can call the AERROR( ) function to retrieve errors from upstream data sources.

In Visual FoxPro 9.0, the target record is kept current in an ADODB.Recordset during the AfterInsert event.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
GETFLDSTATE( ) Function
TABLEUPDATE( ) Function
BeforeInsert Event
AERROR( ) Function


AfterRecordRefresh Event

Visual FoxPro 9.0 Language Reference
AfterRecordRefresh Event
See Also

Occurs immediately after the RecordRefresh method is executed.

PROCEDURE Object.AfterRecordRefresh
LPARAMETERS nRecords, nRecordOffset, nRefreshed

Parameters

nRecords

The number of records to refresh passed to the RecordRefresh method.
nRecordOffset

The record offset passed to the RecordRefresh method.
nRefreshed

The return value from the RecordRefresh method.

Remarks

Applies To: CursorAdapter Class

See the RecordRefresh Method for additional information about the nRecords and nRecordOffset parameters, and the RecordRefresh method return value passed to the nRefreshed parameter.

Note:
This event occurs just once after the RecordRefresh method is executed, not each time a record refresh is attempted.

You can include the AERROR( ) function in this event to determine the cause of errors (if any) generated by the RecordRefresh method.

See Also

Reference

BeforeRecordRefresh Event

Other Resources

CursorAdapter Object Properties, Methods, and Events


AfterReport Event

Visual FoxPro 9.0
AfterReport Event
See Also

Occurs directly after the Report Engine finishes processing a report form.

PROCEDURE Object.AfterReport

Parameters

None.

Remarks

Applies To: ReportListener Object.

At the conclusion of the report run, after the final AfterBand event, the Report Engine fires the AfterReport event. At this time, the private datasession specified by the FRXDataSession property still contains its read-only copy of the report definition file (frx). The print job (if the report is printing) is still open.

When AfterReport returns, output is finalized (for example, the print job is closed) if there was no NOPAGEEJECT keyword on this REPORT FORM command.

Note:
For more information about the order of events in a report run, refer to Understanding Visual FoxPro Object-Assisted Reporting.

See Also

Reference

ReportListener Object
BeforeReport Event
REPORT FORM Command
LABEL Command

Other Resources

Events (Visual FoxPro)
Language Reference (Visual FoxPro)


AfterRowColChange Event

Visual FoxPro 9.0 Language Reference
AfterRowColChange Event
See Also

Occurs when the user moves to another row or column in the Grid, after the new cell gets the focus, and after the When event of the object in the new row or column. The AfterRowColChange event doesn't fire unless the When event of the object in the new row or column returns true (.T.).

PROCEDURE Grid.AfterRowColChange
LPARAMETERS nColIndex

Parameters

nColIndex

Returns the index of the newly selected row or column.

Remarks

Applies To: Grid Control

AfterRowColChange is triggered interactively by the mouse or keyboard, or programmatically, such as by calling the ActivateCell method.

Use this event to synchronize the two halves of a grid when the SplitBar property = .T., by adding This.Refresh.

You can query the RowColChange property in this event to determine the type of change that triggered the event.

See Also

Other Resources

ActivateCell Method
BeforeRowColChange Event
RowColChange Property
When Event
NODEFAULT Command
Events
Language Reference


AfterUpdate Event

Visual FoxPro 9.0 Language Reference
AfterUpdate Event
See Also

Occurs immediately after an update operation for a record is performed.

Note:
If batch updating is used, that is, the CursorAdapter BatchUpdateCount property is greater than 1, AfterUpdate does not occur.

PROCEDURE Object.AfterUpdate
LPARAMETERS cFldState, lForce, nUpdateType, UpdateInsertCmd, DeleteCmd, lResult

Parameters

cFldState

Specifies the field states of the row being processed. This is the same value as obtained from calling the following function:
Copy Code
GETFLDSTATE(-1)
For example, this value can be a character string consisting of deletion and edit status values for all fields in the table or cursor. If a table has five fields and only the first field has been edited, GETFLDSTATE( ) returns a value of 121111. The number 1 in the first position indicates the deletion status has not been changed.
lForce

Specifies the value of the lForce parameter from the TABLEUPDATE( ) function.
nUpdateType

Specifies the value of the nUpdateType parameter from the BeforeUpdate event.
UpdateInsertCmd

Specifies the value of the UpdateInsertCmd parameter from the BeforeUpdate event.
DeleteCmd

Specifies the value of the DeleteCmd parameter from the BeforeUpdate event.
lResult

Specifies the value returned by running TABLEUPDATE( ) for this record. The following table describes values for lResult.

lResult Description

True (.T.)

Clears field states for the record.

False (.F.)

Does not clear field states for the record.
You can change the value of lResult to override the result as returned.

Remarks

Applies To: CursorAdapter Class

You can call the AERROR( ) function to retrieve errors from upstream data sources.

In Visual FoxPro 9.0, the target record is kept current in an ADODB.Recordset during the AfterUpdate event.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
GETFLDSTATE( ) Function
TABLEUPDATE( ) Function
BeforeUpdate Event
AERROR( ) Function


BeforeBand Event

Visual FoxPro 9.0
BeforeBand Event
See Also

Occurs just before the Report System begins processing a report band.

PROCEDURE Object.BeforeBand
LPARAMETERS nBandObjCode, nFRXRecNo

Parameters

Visual FoxPro passes the BeforeBand event parameters in the following order:

nBandObjCode

Integer data type, specifying the type of band, as stored in the ObjCode field of the report or label definition file (frx or lbx). Recognized numeric values for nBandObjCode are documented in the 60FRX.DBF table in the FILESPEC directory, as follows:

0

Title

1

Page Header

2

Column Header

3

Group Header

4

Detail

5

Group Footer

6

Column Footer

7

Page Footer

8

Summary

9

Detail Header

10

Detail Footer
For more information about 60FRX, see Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx).
nFRXRecno

Integer data type, specifying the record number in the report or label definition file (frx or lbx) describing the layout element being rendered.

Remarks

Applies To: ReportListener Object.

For each band in the report, the ReportListener triggers the BeforeBand event before the Report Engine runs any code in the OnEntry expression. It triggers the AfterBand event after any OnExit code runs.

Note:
For information about the order of events in a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

See Also

Tasks

How to: Specify Expressions to Evaluate When Processing Bands

Reference

ReportListener Object
AfterBand Event

Other Resources

Events (Visual FoxPro)
Language Reference (Visual FoxPro)


BeforeBuild Event

Visual FoxPro 9.0 Language Reference
BeforeBuild Event
See Also

Occurs before a project is rebuilt or an application file (.app), dynamic link library (.dll), or executable file (.exe) is created from a project.

PROCEDURE Object.BeforeBuild
LPARAMETERS cOutputName, nBuildAction, lRebuildAll, lShowErrors, lBuildNewGuids

Parameters

cOutputName

Specifies the name of the application, dynamic link library, or executable file that is created. If cOutputName includes a file extension and nBuildAction is omitted, the file extension in cOutputName determines the type of file built. For example, if the extension in cOutputName is ".exe" an executable file is created.
nBuildAction

Specifies that the project is rebuilt or generates an application, a dynamic link library, or an executable file. The following table lists the values for nBuildAction with a description of each.

nBuildAction FoxPro.h constant Description

1

BUILDACTION_REBUILD

Rebuilds the project

2

BUILDACTION_BUILDAPP

Creates an .app

3

BUILDACTION_BUILDEXE

Creates an .exe

4

BUILDACTION_BUILDDLL

Creates a .dll

5

BUILDACTION_BUILDMTDLL

Creates a multi-threaded .dll
nBuildAction takes precedence over the file extension specified in cOutPutName. For example, an executable file is created if nBuildAction is 3 and cOutputName doesn't specify an ".exe" extension.
lRebuildAll

Specifies whether files in the project are recompiled before an .app, .dll, or .exe is created. If lRebuildAll is True (.T.), the following are recompiled:
  • Program files

  • Format files

  • Source code in forms, labels, reports, and visual class libraries

  • Stored procedures in databases

If lRebuildAll is False (.F.) or is omitted, files in the project are not recompiled before the .app, .dll, or .exe is created.
lShowErrors

Specifies whether compilation errors are displayed in an editing window after the build is complete. If lShowErrors is True (.T.), the errors are displayed. If lShowErrors is False (.F.) or is omitted, compilation errors aren't displayed.
lBuildNewGUIDs

Specifies whether new registry GUIDs (globally unique identifiers) are generated when an executable file or dynamic link library is created. If lBuildNewGUIDs is True (.T.), new GUIDs are generated. If lBuildNewGUIDs is False (.F.) or is omitted, new GUIDs aren't generated. lBuildNewGUIDs is ignored if nBuildAction is less than 3.

Remarks

Applies To: ProjectHook Object

The parameters listed above are passed to the BeforeBuild event when you execute the Build method, when you issue the BUILD APP, BUILD DLL, BUILD EXE, or BUILD PROJECT commands, or when you choose OK in the Build Options dialog box. The parameters are passed by reference with the exception of the nBuildAction parameter, which is passed by value. You can change the values of these parameters within the BeforeBuild event to change how a project, .app, .dll, or .exe is created from the project.

Include NODEFAULT in the BeforeBuild event to prevent a project from being rebuilt or an application file (.app), dynamic link library (.dll), or executable file (.exe) from being created.

See Also

Other Resources

AfterBuild Event
Build Method
BUILD PROJECT Command
NODEFAULT Command
Events
Language Reference


BeforeCursorAttach Event

Visual FoxPro 9.0 Language Reference
BeforeCursorAttach Event
See Also Example

Occurs immediately before the CursorAdapter object attempts to attach a cursor. You can use this event to perform any necessary operations before attaching the cursor or table, determine an alias to attach, and so on.

PROCEDURE Object.BeforeCursorAttach
LPARAMETERS cAlias

Parameters

cAlias

Specifies the alias of the cursor or table being attached.

Remarks

Applies To: CursorAdapter Class

If the code in BeforeCursorAttach returns a value of False (.F.), the cursor attachment does not occur.

Note:
The CursorAdapter object respects any changes that might be made to the cAlias parameter by BeforeCursorAttach.

Example

The following example illustrates how to open a local view in BeforeCursorAttach so that you can attach the view to a CursorAdapter object:

Copy Code
PROCEDURE BeforeCursorAttach
OPEN DATABASE HOME(2)+"tastrade\data\tastrade.dbc"
USE 'product listing'
ENDPROC

Then make the following call to attach the view:

Copy Code
CursorAttach('product listing', .T.)

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
AfterCursorAttach Event
CursorAttach Method


BeforeCursorClose Event

Visual FoxPro 9.0 Language Reference
BeforeCursorClose Event
See Also

Occurs immediately before a cursor closes. You can use this event to perform any operations needed before closing a cursor or table, and so on.

PROCEDURE Object.BeforeCursorClose
LPARAMETERS cAlias

Parameters

cAlias

Specifies the alias of the cursor or table being closed.

Remarks

Applies To: CursorAdapter Class

If the code in BeforeCursorClose returns a value of False (.F.), the cursor does not close, and Visual FoxPro generates an error message.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
AfterCursorClose Event


BeforeCursorDetach Event

Visual FoxPro 9.0 Language Reference
BeforeCursorDetach Event
See Also

Occurs immediately before a CursorAdapter object detaches a cursor. You can use this event to perform any necessary operations before detaching the cursor or table.

PROCEDURE Object.BeforeCursorAttach
LPARAMETERS cAlias

Parameters

cAlias

Specifies the alias of the cursor or table being detached.

Remarks

Applies To: CursorAdapter Class

If the code in BeforeCursorDetach returns a value of False (.F.), the cursor does not detach, and any return values are ignored.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
AfterCursorDetach Event
CursorDetach Method


BeforeCursorFill Event

Visual FoxPro 9.0 Language Reference
BeforeCursorFill Event
See Also

Occurs immediately before a CursorAdapter object attempts to attach a new cursor.

PROCEDURE Object.BeforeCursorFill
LPARAMETERS lUseCursorSchema, lNoDataOnLoad, cSelectCmd

Parameters

lUseCursorSchema

Specifies the value of the lUseCursorSchema parameter from the CursorFill method.
lNoDataOnLoad

Specifies the value of the lNoData property in CursorFill.
cSelectCmd

Specifies the current value of the SelectCmd property. You can change the value of the cSelectCmd parameter in this event. However, the value in the SelectCmd property does not change. If you change the value of the cSelectCmd parameter in this event, Visual FoxPro uses the changed value of cSelectCmd.

Remarks

Applies To: CursorAdapter Class

Visual FoxPro stores the value changes, which are used by CursorFill. The CursorRefresh method uses the value of the SelectCmd parameter, not the SelectCmd property. This facilitates construction of custom queries "on the fly". For example, you can store a basic SELECT – SQL command in the SelectCmd property and add a WHERE clause to the SelectCmd parameter in this event without changing the underlying value of the property. The value of the SelectCmd parameter is then passed to the AfterCursorFill event.

If the code in BeforeCursorFill returns a value of False (.F.), CursorFill does not execute, and the currently attached cursor remains unclosed. However, if the code in BeforeCursorFill does not return false, the currently attached cursor closes, and CursorFill executes.

Changes made to these parameters take precedence over the original values stored in the respective properties or that are passed to CursorFill.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
CursorFill Method
SelectCmd Property
CursorRefresh Method
SelectCmd Property
SELECT - SQL Command
AfterCursorFill Event


BeforeCursorRefresh Event

Visual FoxPro 9.0 Language Reference
BeforeCursorRefresh Event
See Also

Occurs immediately before a CursorAdapter object attempts to refresh.

PROCEDURE Object.BeforeCursorRefresh
LPARAMETERS cSelectCmd

Parameters

cSelectCmd

Specifies the current value of SelectCmd as established in the BeforeCursorFill event. For example, if the cSelectCmd parameter is changed in BeforeCursorFill, then the changed value of SelectCmd is used. However, the value of the SelectCmd property does not change.

Remarks

Applies To: CursorAdapter Class

If the code in BeforeCursorRefresh returns a value of False (.F.), the CursorAdapter object does not refresh.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
SelectCmd Property
BeforeCursorFill Event
AfterCursorRefresh Event


BeforeCursorUpdate Event

Visual FoxPro 9.0 Language Reference
BeforeCursorUpdate Event
See Also

Occurs immediately before the TABLEUPDATE( ) function executes.

PROCEDURE Object.BeforeCursorUpdate
LPARAMETERS nRows, lForce

Parameters

nRows

Specifies the setting of the nRows parameter from the TABLEUPDATE( ) function.
lForce

Specifies the value of the lForce parameter from the TABLEUPDATE( ) function.

Remarks

Applies To: CursorAdapter Class

BeforeCursorUpdate occurs once at the beginning of the update process. If multiple rows are being updated, the BeforeUpdate, BeforeInsert, and BeforeDelete events occur for each updated row as appropriate.

If code in BeforeCursorUpdate returns False (.F.), no update, insert, or delete operations occurs.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
TABLEUPDATE( ) Function
BeforeUpdate Event
BeforeInsert Event
BeforeDelete Event
AfterCursorUpdate Event


BeforeDelete Event

Visual FoxPro 9.0 Language Reference
BeforeDelete Event
See Also

Occurs immediately before a delete command for a record executes.

Note:
If batch updating is used, that is, the CursorAdapter BatchUpdateCount property is greater than 1, BeforeDelete does not occur.

PROCEDURE Object.BeforeDelete
LPARAMETERS cFldState, lForce, cDeleteCmd

Parameters

cFldState

Specifies the field states of the row being processed. This is the same value as obtained from calling the following function:
Copy Code
GETFLDSTATE(-1)
For example, this value can be a character string consisting of deletion and edit status values for all fields in the table or cursor. If a table has five fields and only the first field has been edited, GETFLDSTATE( ) returns a value of 121111. The number 1 in the first position indicates the deletion status has not been changed.
lForce

Specifies the value of the lForce parameter from the TABLEUPDATE( ) function.
cDeleteCmd

Specifies the value of the DeleteCmd property. Visual FoxPro uses the value of cDeleteCmd as the delete command, which you can change in this event. However, if you change the value of the cDeleteCmd parameter, the value of the DeleteCmd property does not change.

Remarks

Applies To: CursorAdapter Class

If code in BeforeDelete returns False (.F.), the delete operation does not occur.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
GETFLDSTATE( ) Function
TABLEUPDATE( ) Function
DeleteCmd Property
AfterDelete Event


BeforeDock Event

Visual FoxPro 9.0 Language Reference
BeforeDock Event
See Also

Occurs before docking a ToolBar object or a Form object, for example, when dragging a toolbar or form to a docking area or calling the Dock method.

PROCEDURE Object.BeforeDock
LPARAMETERS nLocation

Parameters

nLocation

Returns the docking position for the toolbar or form. The following table lists the values for nLocation.

nLocation Description FoxPro.h constant

-1

Form or toolbar will undock.

TOOL_NOTDOCKED

0

Form or toolbar will dock at the top of main Visual FoxPro window.

TOOL_TOP

1

Form or toolbar will dock to the left edge of the main Visual FoxPro window.

TOOL_LEFT

2

Form or toolbar will dock to the right edge of the main Visual FoxPro window.

TOOL_RIGHT

3

Form or toolbar will dock at the bottom edge of the Visual FoxPro window.

TOOL_BOTTOM

4

Form will tab dock to another form.

TOOL_TAB

5

Form will link dock to another form.

Note:
To determine additional information for the target and position, you need to call the GetDockState method after the docking operation completes. For more information, see GetDockState Method.

TOOL_LINK

Remarks

Applies To: Form Object | ToolBar Object

BeforeDock occurs before Visual FoxPro redraws the form or toolbar so you can change the appearance of the form or toolbar. For example, suppose you want to replace a ComboBox control on the form with a CommandButton control, which has different proportions. You can insert code into the BeforeDock event that replaces the control when docking the form.

Returning .F. (False) from code in the event or adding the NODEFAULT command does not prevent docking. For more information, see NODEFAULT Command.

See Also

Other Resources

How to: Dock Forms
How to: Dock Toolbars
ADOCKSTATE( ) Function
AfterDock Event
Dock Method
Dockable Property
Docked Property
DockPosition Property
GetDockState Method
UnDock Event
Events
Language Reference


BeforeInsert Event

Visual FoxPro 9.0 Language Reference
BeforeInsert Event
See Also

Occurs immediately before an insert command for a record executes.

Note:
If batch updating is used, that is, the CursorAdapter BatchUpdateCount property is greater than 1, BeforeInsert does not occur.

PROCEDURE Object.BeforeInsert
LPARAMETERS cFldState, lForce, cInsertCmd

Parameters

cFldState

Specifies the field states of the row being processed. This is the same value as obtained from calling the following function:
Copy Code
GETFLDSTATE(-1)
For example, this value can be a character string consisting of deletion and edit status values for all fields in the table or cursor. If a table has five fields and only the first field has been edited, GETFLDSTATE( ) returns a value of 121111. The number 1 in the first position indicates the deletion status has not been changed.
lForce

Specifies the value of the lForce parameter from the TABLEUPDATE( ) function.
cInsertCmd

Specifies the value of the InsertCmd property. Visual FoxPro uses the value of cInsertCmd as the insert command, which you can change in this event. However, if you change the value of the cInsertCmd parameter, the value of the InsertCmd property does not change.

Remarks

Applies To: CursorAdapter Class

If code in BeforeInsert returns False (.F.), the insert operation does not occur.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
GETFLDSTATE( ) Function
TABLEUPDATE( ) Function
InsertCmd Property
AfterInsert Event


BeforeOpenTables Event

Visual FoxPro 9.0 Language Reference
BeforeOpenTables Event
See Also

Occurs just before the tables and views associated with the data environment for a form set, form, or report are opened.

PROCEDURE DataEnvironment.BeforeOpenTables

Remarks

Applies To: DataEnvironment Object

The BeforeOpenTables event occurs before the Load event for a form set or form.

See Also

Other Resources

AfterCloseTables Event
CloseTables Method
Load Event
OpenTables Method
Unload Event
Events
Language Reference


BeforeRecordRefresh Event

Visual FoxPro 9.0 Language Reference
BeforeRecordRefresh Event
See Also

Occurs immediately before the RecordRefresh method is executed.

PROCEDURE Object.BeforeRecordRefresh
LPARAMETERS nRecords, nRecordOffset

Parameters

nRecords

Specifies the number of consecutive records (in physical order) to refresh. This parameter is passed to the RecordRefresh method.
nRecordOffset

Specifies the number of records before the current record where the refresh begins. This parameter is passed to the RecordRefresh method.

Remarks

Applies To: CursorAdapter Class

The nRecords and nRecordOffset parameters are passed to the RecordRefresh method. See the RecordRefresh Method for additional information about the nRecords and nRecordOffset parameters.

If BeforeRecordRefresh event fails or doesn’t return a logical true (.T.) value, the RecordRefresh method isn't executed and AfterRecordRefresh event does not occur.

See Also

Reference

AfterRecordRefresh Event

Other Resources

CursorAdapter Object Properties, Methods, and Events


BeforeReport Event

Visual FoxPro 9.0
BeforeReport Event
See Also

Occurs just before the Report Engine begins processing a report form.

PROCEDURE Object.BeforeReport

Parameters

None.

Remarks

Applies To: ReportListener Object.

When Visual FoxPro triggers the BeforeReport event for a report run, it has done all necessary internal setup work for rendering the report. It has read the contents of the report definition file (frx) and has opened a read-only copy of this file in a private datasession for use by your derived class. For more information, see FRXDataSession Property.

Before triggering the BeforeReport event, the Report Engine has also created a private data session for the report's data, if the report specifies one. It has opened the tables and performed other initialization tasks as specified by the report's DataEnvironment. For more information, see CurrentDataSession Property. You can investigate the report's layout definition and the report's data, as needed, by switching between these two data sessions.

At this point, the Engine has also checked the report scope, providing you with the number of records to be processed in this report run. This information is available to your code in the CommandClauses.RecordTotal member. In BeforeReport, all other CommandClauses' member values are fully available as well. For more information, see CommandClauses Property.

After the BeforeReport() event returns, the Report Engine can begin the report run. It begins by evaluating the expressions in the report, to assess whether this report requires a preprocessing or calculation pass. It assigns additional properties of the Listener at this time, indicating the result of this assessment. For more information, see TwoPassProcess Property and CurrentPass Property. The next event triggered is the first BeforeBand event for the report.

Note:
For more information about the order of events in a report run, refer to Understanding Visual FoxPro Object-Assisted Reporting.

See Also

Reference

ReportListener Object
AfterReport Event
BeforeBand Event
REPORT FORM Command
LABEL Command
DataEnvironment Object
SET DATASESSION Command

Other Resources

Events (Visual FoxPro)
Language Reference (Visual FoxPro)


BeforeRowColChange Event

Visual FoxPro 9.0 Language Reference
BeforeRowColChange Event
See Also

Occurs when the user changes the active row or column before the new cell gets the focus. It also occurs before the Valid event of the current object in the grid column and any rules in the database. Use NODEFAULT to prevent the active row and column in the grid from changing.

PROCEDURE Grid.BeforeRowColChange
LPARAMETERS nColIndex

Parameters

nColIndex

Returns the index of the column that is active before the row or column change.

Remarks

Applies To: Grid Control

BeforeRowColChange is triggered interactively using the mouse or keyboard or programmatically, such as calling the ActivateCell method.

You can query the RowColChange property in this event to determine the type of change that triggered the event.

See Also

Other Resources

ActivateCell Method
AfterRowColChange Event
DEFINE CLASS [NODEFAULT]
RowColChange Property
Valid Event
NODEFAULT Command
Events
Language Reference


BeforeUpdate Event

Visual FoxPro 9.0 Language Reference
BeforeUpdate Event
See Also

Occurs immediately before an update command for a record executes.

Note:
If batch updating is used, that is, CursorAdapter BatchUpdateCount property is greater than 1, BeforeUpdate does not occur.

PROCEDURE Object.BeforeUpdate
LPARAMETERS cFldState, lForce, nUpdateType, cUpdateInsertCmd, cDeleteCmd

Parameters

cFldState

Specifies the field states of the row being processed. This is the same value as obtained from calling the following function:
Copy Code
GETFLDSTATE(-1)
For example, this value can be a character string consisting of deletion and edit status values for all fields in the table or cursor. If a table has five fields and only the first field has been edited, GETFLDSTATE( ) returns a value of 121111. The number 1 in the first position indicates the deletion status has not been changed.
lForce

Specifies the value of the lForce parameter from the TABLEUPDATE( ) function.
nUpdateType

Specifies a numeric value in the UpdateType property of the generated CursorAdapter object. The following table lists the possible values for nUpdateType.

nUpdateType Description

1

Update old data with new data. (Default)

2

Update data by deleting old data and inserting new data.
Changing this value changes the behavior for the current record but does not change the value of the property. You need this value only if you are using automatic updating.
cUpdateInsertCmd

Specifies the value of the UpdateCmd or InsertCmd property as appropriate. Visual FoxPro uses the value of this parameter as the update or insert command, which you can change in this event. However, if you change the cUpdateInsertCmd parameter, the UpdateCmd and InsertCmd properties do not change.
cDeleteCmd

Specifies that cDeleteCmd is empty if the nUpdateType parameter is set to 1. Otherwise, set cDeleteCmd to the value of the DeleteCmd property. Visual FoxPro uses the value of cDeleteCmd as the delete command, which you can in this event. However, if you change the cDeleteCmd parameter, the value of the DeleteCmd property does not change.

Remarks

Applies To: CursorAdapter Class

If code in BeforeUpdate returns False (.F.), the update operation does not occur.

See Also

Other Resources

Events
CursorAdapter Object Properties, Methods, and Events
GETFLDSTATE( ) Function
TABLEUPDATE( ) Function
UpdateType Property
UpdateCmd Property
InsertCmd Property
DeleteCmd Property
AfterUpdate Event


Click Event

Visual FoxPro 9.0 Language Reference
Click Event
See Also Example

Occurs when you include code in a program that triggers the event, when the user clicks a control, changes the value of certain controls, or clicks in a blank area of a form.

PROCEDURE Object.Click

Remarks

Applies To: CheckBox Control | ComboBox Control | CommandButton Control | CommandGroup Control | Container Object | Control Object | EditBox Control | Form Object | Grid Control | Header Object | Image Control | Label Control | Line Control | ListBox Control | OptionButton Control | OptionGroup Control | Page Object | PageFrame Control | Shape Control | Spinner Control | TextBox Control | ToolBar Object

The Click event occurs when the user:

  • Clicks a check box, command button, combo box, list box, or option button with the left mouse button.

  • Presses the SPACEBAR when a command button, option button, or check box has the focus.

  • Presses ENTER when a form has a command button with its Default property set to True (.T.).

  • Presses the access key for a control. For example, if the caption of a command button is "\<Go", pressing ALT+G triggers the Click event.

  • Clicks a blank area of a form. Click events on a form do not occur when the pointer is over the title bar, the Window menu icon, or the window borders.

  • Clicks the text entry area of a spinner.

  • Clicks a disabled control. The Click event occurs for the container on which the disabled control is placed.

The Click event also occurs as a result of code you include that issues the MOUSE command.

Note:
Resizing grid column headers does not trigger the Click event for the column header. This affects column separators.

Example

The following example creates an OptionGroup control and places the control on a form. The OptionGroup control has three buttons, and depending on the option button you click, a circle, ellipse, or square appears. The ButtonCount property is used to specify the number of buttons in the OptionGroup. The Buttons and Caption properties are used to specify the text displayed next to each option button.

The Shape control is used to create the circle, ellipse, and square. The OptionGroup control's Click event uses a DO CASE ... ENDCASE structure and the Value property to display the appropriate shape when you click an option button.
Copy Code
frmMyForm = CREATEOBJECT('Form')  && Create a Form
frmMyForm.Closable = .F.  && Disable the window pop-up menu

frmMyForm.AddObject('cmdCommand1','cmdMyCmndBtn')  && Add Command button
frmMyForm.AddObject('opgOptionGroup1','opgMyOptGrp') && Add Option Group
frmMyForm.AddObject('shpCircle1','shpMyCircle')  && Add Circle Shape
frmMyForm.AddObject('shpEllipse1','shpMyEllipse')  && Add Ellipse Shape
frmMyForm.AddObject('shpSquare','shpMySquare')  && Add Box Shape

frmMyForm.cmdCommand1.Visible =.T.  && "Quit" Command button visible

frmMyForm.opgOptionGroup1.Buttons(1).Caption = "\<Circle"
frmMyForm.opgOptionGroup1.Buttons(2).Caption = "\<Ellipse"
frmMyForm.opgOptionGroup1.Buttons(3).Caption = "\<Square"
frmMyForm.opgOptionGroup1.SetAll("Width", 100) && Set Option group width
frmMyForm.opgOptionGroup1.Visible = .T.  && Option Group visible
frmMyForm.opgOptionGroup1.Click  && Show the circle

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS opgMyOptGrp AS OptionGroup  && Create an Option Group
   ButtonCount = 3  && Three Option buttons
   Top = 10
   Left = 10
   Height = 75
   Width = 100

   PROCEDURE Click
      ThisForm.shpCircle1.Visible = .F.  && Hide the circle
      ThisForm.shpEllipse1.Visible = .F.  && Hide the ellipse
      ThisForm.shpSquare.Visible = .F.  && Hide the square

      DO CASE
         CASE ThisForm.opgOptionGroup1.Value = 1
            ThisForm.shpCircle1.Visible = .T. && Show the circle
         CASE ThisForm.opgOptionGroup1.Value = 2
            ThisForm.shpEllipse1.Visible = .T.  && Show the ellipse
         CASE ThisForm.opgOptionGroup1.Value = 3
            ThisForm.shpSquare.Visible = .T.  && Show the square
      ENDCASE
ENDDEFINE

DEFINE CLASS cmdMyCmndBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
ENDDEFINE

DEFINE CLASS shpMyCircle AS SHAPE  && Create a circle
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 99
   BackColor = RGB(255,0,0)  && Red
ENDDEFINE

DEFINE CLASS shpMyEllipse AS SHAPE  && Create an ellipse
   Top = 35
   Left = 200
   Width = 100
   Height = 50
   Curvature = 99
   BackColor = RGB(0,128,0)  && Green
ENDDEFINE

DEFINE CLASS shpMySquare AS SHAPE  && Create a square
   Top = 10
   Left = 200
   Width = 100
   Height = 100
   Curvature = 0
   BackColor = RGB(0,0,255)  && Blue
ENDDEFINE

See Also

Other Resources

Events
DblClick Event
MiddleClick Event
MOUSE Command
MouseDown Event
MouseUp Event
MouseWheel Event
Value Property


dbc_Activate Event

Visual FoxPro 9.0 Language Reference
dbc_Activate Event
See Also Example

Occurs when a database becomes active. There are two versions of the syntax.

PROCEDURE dbc_Activate(cDatabaseName)
PROCEDURE dbc_Activate
LPARAMETERS cDatabaseName

Parameters

cDatabaseName

Specifies the name of the database being activated.

Remarks

You can have many Databases open at the same time but only one can be active at a time. A database can become active under several circumstances. To explicitly activate a database, use the SET DATABASE TO command. If several databases (with DBC Events turned on) are open, the dbc_Activate method runs only in the active database.

If you place DBC Events code in a program file, the code applies to any database that specifies that program file as its events file. In this case, DBC events method code can affect several databases at the same time. When you use DBC events in this way, use the cDatabaseName parameter in the event code to specify which database is being activated. This way you can use one block of method code to determine the activated database and then apply code appropriate to that database.

Return False (.F.) from this procedure to prevent the database from being activated.

Visual FoxPro will ignore a return of False (.F.) from this event during design time.

Example

Copy Code
PROCEDURE dbc_Activate ;
         (cDatabaseName)
? '     cDatabaseName  = ' + TRANSFORM(cDatabaseName) + ' - ' ;
                       + TYPE('cDatabaseName ')+' /end/ '
ENDPROC

See Also

Other Resources

dbc_Deactivate Event
SET DATABASE Command
dbc_CloseData Event
dbc_ModifyData Event
dbc_OpenData Event
Events
Language Reference


dbc_AfterAddRelation Event

Visual FoxPro 9.0 Language Reference
dbc_AfterAddRelation Event
See Also

Occurs after a relation is successfully added to the database. There are two versions of the syntax.

PROCEDURE dbc_AfterAddRelation(cRelationID, cTableName, cRelatedChild, cRelatedTable, cRelatedTag)
PROCEDURE dbc_AfterAddRelation
LPARAMETERS cRelationID, cTableName, cRelatedChild, cRelatedTable, cRelatedTag

Parameters

cRelationID

Specifies the Relation ID number stored in the database.
cTableName

Specifies the name of the parent table.
cRelatedChild

Specifies the name of the linked column in the child table.
cRelatedTable

Specifies the table containing the linked column.
cRelatedTag

Specifies the index tag of the parent table.

Remarks

You can use the dbc_AfterAddRelation event to verify appropriate values for cRelationID and the other parameters in a procedure that tracks, or manages access to the database after a relation is added to the database.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeAddRelation Event


dbc_AfterAddTable Event

Visual FoxPro 9.0 Language Reference
dbc_AfterAddTable Event
See Also Example

Occurs after a table is added to an active database. There are two versions of the syntax.

PROCEDURE dbc_AfterAddTable(cTableName, cLongTableName)
PROCEDURE dbc_AfterAddTable
LPARAMETERS cTableName, cLongTableName

Parameters

cTableName

Specifies the name of the table being added to the database.
cLongTableName

Specifies the long name of the table being added to the database.

Remarks

You can add method code to the dbc_AfterAddTable event that performs functions like updating your data dictionary or sending an email to the database administrator.

This event does not occur when you create a table in the database.

Example

Copy Code
PROCEDURE dbc_AfterAddTable ;
         (cTableName, ;
          cLongTableName)
? '     cTableName     = ' + TRANSFORM(cTableName)     + ' - ' ;
                       + TYPE('cTableName ')
? '     cLongTableName = ' + TRANSFORM(cLongTableName) + ' - ' ;
                       + TYPE('cLongTableName ')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_BeforeCreateTable Event
dbc_BeforeAddTable Event
Events
Language Reference


dbc_AfterAppendProc Event

Visual FoxPro 9.0 Language Reference
dbc_AfterAppendProc Event
See Also Example

Occurs after the APPEND PROCEDURE command completes. There are two versions of the syntax.

PROCEDURE dbc_AfterAppendProc(cFileName, nCodePage, lOverwrite)
PROCEDURE dbc_AfterAppendProc
LPARAMETERS cFileName, nCodePage, lOverwrite

Parameters

cFileName

Specifies the name of a text file from which the stored procedures have been appended.
nCodePage,

Specifies the code page of the text file from which the stored procedures were appended. Visual FoxPro copies the contents of the text file and, as it does so, automatically converts those contents to the code page you specify.
lOverWrite

Specifies whether the current stored procedures in the database were overwritten by those in the text file. If the OVERWRITE keyword was omitted from the APPEND PROCEDURE command, the current stored procedures in the database are appended to any existing stored procedures in the text file.

Remarks

You can use the dbc_AfterAppendProc event to track access to the database after stored procedure are appended.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterAppendProc ;
         (cFileName,;
          nCodePage,;
          lOverwrite)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     Current DBC:      ' + SUBSTR(DBC(),RAT('\',DBC())+1)
 ? '     cFileName       = ' + TRANSFORM(cFileName)  + ' - ' ;
                         + TYPE('cFileName')
 ? '     nCodePage       = ' + TRANSFORM(nCodePage)  + ' - ' ;
                         + TYPE('nCodePage')
 ? '     lOverwrite      = ' + TRANSFORM(lOverwrite) + ' - ' ;
                         + TYPE('lOverwrite')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeAppendProc Event


dbc_AfterCloseTable Event

Visual FoxPro 9.0 Language Reference
dbc_AfterCloseTable Event
See Also Example

Occurs after a table or view is closed. There are two versions of the syntax.

PROCEDURE dbc_AfterCloseTable(cTableName)
PROCEDURE dbc_AfterCloseTable
LPARAMETERS cTableName

Parameters

cTableName

Specifies the name of the table or view being closed.

Remarks

You can use the dbc_AfterCloseTable event to track access to the database after a table is closed in the current database.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterCloseTable ;
         (cTableName)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cTableName = ' + TRANSFORM(cTableName) + ' - ' ;
                   + TYPE('cTableName')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_BeforeCloseTable Event
Events
Language Reference


dbc_AfterCopyProc Event

Visual FoxPro 9.0 Language Reference
dbc_AfterCopyProc Event
See Also Example

Occurs after the COPY PROCEDURE command has completed. There are two versions of the syntax.

PROCEDURE dbc_AfterCopyProc(cFileName, nCodePage, lAdditive)
PROCEDURE dbc_AfterCopyProc
LPARAMETERS cFileName, nCodePage, lAdditive

Parameters

cFileName

Specifies the name of the text file to which the stored procedures were copied.
nCodePage,

Specifies the code page of the program file to which the stored procedures are copied. Visual FoxPro copies the contents of the stored procedures in the database and, as it does so, automatically converts those contents to the code page you specify.
lAdditive

Specifies whether the ADDITIVE keyword was included in the COPY PROCEDURE command that triggered this event. If ADDITIVE was omitted, the stored procedures replaced the contents of the program file.

Remarks

You can use the dbc_AfterCopyProc event to track access to the database after a copy procedure completes.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterCopyProc ;
         (cFileName,;
          nCodePage,;
          lAdditive)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     Current DBC:      ' + SUBSTR(DBC(),RAT('\',DBC())+1)
 ? '     cFileName       = ' + TRANSFORM(cFileName)  + ' - ' ;
                         + TYPE('cFileName')
 ? '     nCodePage       = ' + TRANSFORM(nCodePage)  + ' - ' ;
                         + TYPE('nCodePage')
 ? '     lAdditive      = ' + TRANSFORM(lAdditive) + ' - ' ;
                         + TYPE('lAdditive')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeCopyProc Event


dbc_AfterCreateConnection Event

Visual FoxPro 9.0 Language Reference
dbc_AfterCreateConnection Event
See Also Example

Occurs after a connection has been created. There are two versions of the syntax.

PROCEDURE dbc_AfterCreateConnection
(cConnectionName, cDataSourceName, cUserID, cPassWord, cConnectionString)
PROCEDURE dbc_AfterCreateConnection
LPARAMETERS cConnectionName, cDataSourceName, cUserID, cPassWord,
 cConnectionString

Parameters

cConnectionName

Specifies the name of the connection that was created.
cDataSourceName

Specifies the name of the ODBC data source.
cUserID

Specifies your user identification for the ODBC data source.
cPassWord

Specifies your password for the ODBC data source.
cConnectionString

Specifies a connection string for the ODBC data source. You can use the connection string instead of explicitly including the ODBC data source, the user identification, and the password.

Remarks

You can use the dbc_AfterCreateConnection event to track attempted access to the database after a connection is created.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameters passed.
PROCEDURE dbc_AfterCreateConnection ;
         (cConnectionName, ;
          cDataSourceName, ;
          cUserID, ;
          cPassword, ;
          cConnectionString)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cConnectionName    = ' + TRANSFORM(cConnectionName)   + ' - ' ;
                           + TYPE('cConnectionName ')
? '     cDataSourceName    = ' + TRANSFORM(cDataSourceName)   + ' - ' ;
                           + TYPE('cDataSourceName ')
? '     cUserID            = ' + TRANSFORM(cUserID)           + ' - ' ;
                           + TYPE('cUserID ')
? '     cPassword          = ' + TRANSFORM(cPassword)         + ' - ' ;
                           + TYPE('cPassword ')
? '     cConnectionString  = ' + TRANSFORM(cConnectionString) + ' - ' ;
                           + TYPE('cConnectionString ')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_BeforeCreateConnection Event
Events
Language Reference


dbc_AfterCreateOffline Event

Visual FoxPro 9.0 Language Reference
dbc_AfterCreateOffline Event
See Also Example

Occurs after CREATEOFFLINE( ) has completed. There are two versions of the syntax.

PROCEDURE dbc_AfterCreateOffline(cViewName, cPath)
PROCEDURE dbc_AfterCreateOffline
LPARAMETERS cViewName, cPath

Parameters

cViewName

Specifies the name of the existing view being taken offline.
cPath

Specifies the directory in which the offline view has been placed.

Remarks

You can use the dbc_AfterCreateOffline event to track access to the database after an offline view is created.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterCreateOffline ;
         (cViewName,;
          cPath)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cViewName =  ' + TRANSFORM(cViewName) + ' - ' ;
                  + TYPE('cViewName')
? '     cPath     =  ' + TRANSFORM(cPath)     + ' - ' ;
                  + TYPE('cPath') + ' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeCreateOffline Event


dbc_AfterCreateTable Event

Visual FoxPro 9.0 Language Reference
dbc_AfterCreateTable Event
See Also Example

Occurs after a table is created in the active database. There are two versions of the syntax.

PROCEDURE dbc_AfterCreateTable(cTableName, cLongTableName)
PROCEDURE dbc_AfterCreateTable
LPARAMETERS cTableName, cLongTableName

Parameters

cTableName

Specifies the name of the table that was created.
cLongTableName

Specifies the long name for the table that was created.

Remarks

This event does not occur when you create a free table.

You can use the dbc_AfterCreateTable event to verify appropriate values for cTableName or cLongTableName, use those parameters in a procedure to track, or manage access to the database after a table is created in the database.

Example

Copy Code
PROCEDURE dbc_AfterCreateTable ;
         (cTableName, ;
          cLongTableName)
? '     cTableName      = ' + TRANSFORM(cTableName)     + ' - ' ;
                        + TYPE('cTableName ')
? '     cLongTableName  = ' + TRANSFORM(cLongTableName) + ' - ' ;
                        + TYPE('cLongTableName ')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_BeforeCreateTable Event
Events
Language Reference


dbc_AfterCreateView Event

Visual FoxPro 9.0 Language Reference
dbc_AfterCreateView Event
See Also Example

Occurs after SQL view is created. There are two versions of the syntax.

PROCEDURE dbc_AfterCreateView(cViewName, lRemote)
PROCEDURE dbc_AfterCreateView
LPARAMETERS cViewName, lRemote

Parameters

cViewName

Specifies the name of the view that was created.
lRemote

Specifies whether the view is remote.

Remarks

You can use the dbc_AfterCreateView event to track access to the database after a view is created.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterCreateView ;
         (cViewName, ;
          lRemote)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     cViewName  = ' + TRANSFORM(cViewName) + ' - ' ;
                    + TYPE('cViewName ')
 ? '     lRemote    = ' + TRANSFORM(lRemote)   + ' - ' ;
                    + TYPE('lRemote')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeCreateView Event


dbc_AfterDBGetProp Event

Visual FoxPro 9.0 Language Reference
dbc_AfterDBGetProp Event
See Also Example

Occurs after the DBGetProp( ) function completes. There are two versions of the syntax.

PROCEDURE dbc_AfterDBGetProp(cName, cType, cProperty)
PROCEDURE dbc_AfterDBGetProp
LPARAMETERS cName, cType, cProperty

Parameters

cName

Specifies the value of the first parameter in the DBGetProp() function, the name of the database, field, named connection, table, or view for which DBGETPROP( ) returns information.
cType

Specifies the value of the second parameter in the DBGetProp() function, the object type of the item named in cName.
cProperty

Specifies the value of the third parameter in the DBGetProp() function, the property for which DBGETPROP( ) returns information.

For details on valid cType and cProperty values, see in Help.

Remarks

You can use the dbc_AfterDBGetProp event to track access to the database after DBGetProp runs.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterDBGetProp ;
         (cName,;
          cType,;
          cProperty)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     Current DBC: ' + SUBSTR(DBC(),RAT('\',DBC())+1)
 ? '     cName     =  ' + TRANSFORM(cName)     + ' - ' + TYPE('cName')
 ? '     cType     =  ' + TRANSFORM(cType)     + ' - ' + TYPE('cType')
 ? '     cProperty =  ' + TRANSFORM(cProperty) + ' - ' + TYPE('cProperty')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeDBGetProp Event
DBGETPROP( ) Function


dbc_AfterDBSetProp Event

Visual FoxPro 9.0 Language Reference
dbc_AfterDBSetProp Event
See Also Example

Occurs after the DBSetProp( ) function completes. There are two versions of the syntax.

PROCEDURE dbc_AfterDBSetProp(cName, cType, cProperty, ePropertyValue)
PROCEDURE dbc_AfterDBSetProp
LPARAMETERS cName, cType, cProperty, ePropertyValue

Parameters

cName

Specifies the value of the first parameter in the DBGetProp( ) function, the name of the database, field, named connection, table, or view for which DBSETPROP( ) changes the value.
cType

Specifies the value of the second parameter in the DBSetProp( ) function, the object type of the item named in cName.
cProperty

Specifies the value of the third parameter in the DBSetProp( ) function, the property for which DBSETPROP( ) changes the value.
ePropertyValue

Specifies the value of the fourth parameter in the DBSetProp( ) function, the value to be assigned to the property in cProperty.

For details on valid cType and cProperty values, see DBSETPROP( ) and DBGETPROP( ) in Help.

Remarks

You can use the dbc_AfterDBCSetProp event to track access to the database after DBGETPROP( ) runs.

Some property values can be changed using DBSetProp( ) or using a designer. For example, you can change the Comment property for a table using DBSetProp( ) as well as from the table designer. Because DBSetProp( ) makes changes directly to the database itself, dbc_BeforeModifyTable or dbc_AfterModifyTable will not catch changes made by DBSETPROP( ). To trap for changes that could be made either way, you would need to use dbc_BeforeDBSetProp, dbc_AfterDBSetProp, dbc_BeforeModifyTable, and dbc_AfterModifyTable to check for the appropriate changes.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterDBSetProp ;
         (cName,;
          cType,;
          cProperty,;
          ePropertyValue)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     Current DBC:     ' + SUBSTR(DBC(),RAT('\',DBC())+1)
 ? '     cName          = ' + TRANSFORM(cName)          + ' - ' + TYPE('cName')
 ? '     cType          = ' + TRANSFORM(cType)          + ' - ' + TYPE('cType')
 ? '     cProperty      = ' + TRANSFORM(cProperty)      + ' - ' + TYPE('cProperty')
 ? '     ePropertyValue = ' + TRANSFORM(ePropertyValue) + ' - ' + TYPE('ePropertyValue')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeDBSetProp Event


dbc_AfterDeleteConnection Event

Visual FoxPro 9.0 Language Reference
dbc_AfterDeleteConnection Event
See Also Example

Occurs after a connection is deleted. There are two versions of the syntax.

PROCEDURE dbc_AfterDeleteConnection(cConnectionName)
PROCEDURE dbc_AfterConnection
LPARAMETERS cConnectionName

Parameters

cConnectionName

Specifies the name of the connection being deleted.

Remarks

You can use the dbc_AfterDeleteConnection event to track access to the database after a connection is deleted from the database.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterDeleteConnection ;
          cItemName)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     cConnectionName    = ' + TRANSFORM(cConnectionName)        + ' - ' ;
                      + TYPE('cConnectionName ')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeDeleteConnection Event


dbc_AfterDropOffline Event

Visual FoxPro 9.0 Language Reference
dbc_AfterDropOffline Event
See Also Example

Occurs after DROPOFFLINE( ) has completed. There are two versions of the syntax.

PROCEDURE dbc_AfterDropOffline(cViewName, cPath)
PROCEDURE dbc_AfterDropOffline
LPARAMETERS cViewName, cPath

Parameters

cViewName

Specifies the name of the offline view taken back online.
cPath

Specifies the directory in which the offline view is located.

Remarks

You can use the dbc_AfterDropOffline event to track access to the database after an offline view is taken back online.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterDropOffline ;
         (cViewName,;
          cPath)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cViewName = ' + TRANSFORM(cViewName) + ' - ' ;
                  + TYPE('cViewName')
? '     cPath     = ' + TRANSFORM(cPath)     + ' - ' ;
                  + TYPE('cPath')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeDropOffline Event


dbc_AfterDropRelation Event

Visual FoxPro 9.0 Language Reference
dbc_AfterDropRelation Event
See Also

Occurs after a relation is successfully dropped from a database. There are two versions of the syntax.

PROCEDURE dbc_AfterDropRelation(cRelationID, cTableName, cRelatedChild, cRelatedTable, cRelatedTag)
PROCEDURE dbc_AfterDropRelation
LPARAMETERS cRelationID, cTableName, cRelatedChild, cRelatedTable, cRelatedTag

Parameters

cRelationID

Specifies the Relation ID stored in the database.
cTableName

Specifies the name of the parent table.
cRelatedChild

Specifies the name of the linked column in the child table.
cRelatedTable

Specifies the table containing the linked column.
cRelatedTag

Specifies the index tag of the parent table.

Remarks

You can use the dbc_AfterDropRelation event to verify appropriate values for cRelationID and the other parameters in a procedure that tracks, or manages access to the database after a relation is dropped from the database.

Return .F. from this procedure to prevent the relation from being dropped.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeDropRelation Event


dbc_AfterDropTable Event

Visual FoxPro 9.0 Language Reference
dbc_AfterDropTable Event
See Also Example

Occurs after a table is removed from database and deleted from disk by the DROP TABLE command. There are two versions of the syntax.

PROCEDURE dbc_AfterDropTable(cTableName, lRecycle)
PROCEDURE dbc_AfterDropTable
LPARAMETERS cTableName, lRecycle

Parameters

cTableName

Specifies the table removed from the current database and deleted from disk.
lRecycle

Specifies whether the table was placed in the Windows Recycle Bin rather than immediately deleted from the disk.

Remarks

You can use the dbc_AfterDropTable event to verify an appropriate value for cTableName, use those parameters in a procedure to track, or manage access to the database after a table is removed from the database and from the disk.

If you delete a table by using DELETE FILE or the operating system, no event occurs.

Example

Copy Code
* Reports to the screen the event name, where it is called from, and
* the parameter values passed to it.
PROCEDURE dbc_AfterDropTable ;
         (cTableName, ;
          lRecycle)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cTableName = ' + TRANSFORM(cTableName) + ' - ' ;
                   + TYPE('cTableName ')
? '     lRecycle   = ' + TRANSFORM(lRecycle)   + ' - ' ;
                   + TYPE('lRecycle')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_BeforeDropTable Event
Events
Language Reference


dbc_AfterDropView Event

Visual FoxPro 9.0 Language Reference
dbc_AfterDropView Event
See Also Example

Occurs after SQL view definition is removed from the current database. There are two versions of the syntax.

PROCEDURE dbc_AfterDropView(cViewName)
PROCEDURE dbc_AfterDropView
LPARAMETERS cViewName

Parameters

cViewName

Specifies the name of the view deleted from the current database.

Remarks

DROP VIEW is almost identical to DELETE VIEW; DROP VIEW is the ANSI SQL standard syntax for deleting a SQL view. Both commands remove a view definition from the active database, but the syntax is slightly different.

You can use the dbc_AfterDropView event to track access to the database after a view definition is removed from the database.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterDropView ;
         (cViewName)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     cViewName  = ' + TRANSFORM(cViewName) + ' - ' ;
                    + TYPE('cViewName ')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeDropView Event


dbc_AfterModifyConnection Event

Visual FoxPro 9.0 Language Reference
dbc_AfterModifyConnection Event
See Also

Occurs after a connection is modified. There are two versions of the syntax.

PROCEDURE dbc_AfterModifyConnection(cConnectionName, lChanged)
PROCEDURE dbc_AfterModifyConnection
LPARAMETERS cConnectionName, lChanged

Parameters

cConnectionName

Specifies the name of the connection modified.
lChanged

Specifies whether a modification to the view was saved in the Connection Designer.

Remarks

You can use the dbc_AfterModifyView event to track or manage access to the database after connections are modified.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeModifyConnection Event


dbc_AfterModifyProc Event

Visual FoxPro 9.0 Language Reference
dbc_AfterModifyProc Event
See Also Example

Occurs after modifications have been made and the stored procedure editor for the database has been closed.

PROCEDURE dbc_AfterModifyProc( )

Remarks

You can use the dbc_AfterModifyProc event to track access to the database after the stored procedure is modified.

Example

Copy Code
* Reports to the screen Event name, where it is called.
PROCEDURE dbc_AfterModifyProc
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     Current DBC:    ' + SUBSTR(DBC(),RAT('\',DBC())+1)+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeModifyProc Event


dbc_AfterModifyTable Event

Visual FoxPro 9.0 Language Reference
dbc_AfterModifyTable Event
See Also

Occurs after a table is modified. There are two versions of the syntax.

PROCEDURE dbc_AftermodifyTable(cTableName, lChanged)
PROCEDURE dbc_AfterModifyTable
LPARAMETERS cTableName, lChanged

Parameters

cTableName

Specifies the name of the table modified.
lChanged

Specifies whether a modification was saved in the Table Designer.

Remarks

You can use the dbc_AfterModifyTable event to track access to the database after tables are modified.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeModifyTable Event


dbc_AfterModifyView Event

Visual FoxPro 9.0 Language Reference
dbc_AfterModifyView Event
See Also

Occurs after a view has been modified. There are two versions of the syntax.

PROCEDURE dbc_AfterModifyView(cViewName, lChanged)
PROCEDURE dbc_AfterModifyView
LPARAMETERS cViewName, lChanged

Parameters

cViewName

Specifies the name of the view modified.
lChanged

Specifies whether a modification was saved in the View Designer.

Remarks

You can use the dbc_AfterModifyView event to track changes to a database as views are modified.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeModifyView Event


dbc_AfterOpenTable Event

Visual FoxPro 9.0 Language Reference
dbc_AfterOpenTable Event
See Also Example

Occurs after a table or view is opened. There are two versions of the syntax.

PROCEDURE dbc_AfterOpenTable(cTableName)
PROCEDURE dbc_AfterOpenTable
LPARAMETERS cTableName

Parameters

cTableName

Specifies the name of the table or view that was opened.

Remarks

You can use the dbc_AfterOpenTable event to track access to the database after a table is opened in the database.

If the underlying tables are not open when a view is opened, this event occurs for both the tables and the view.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_AfterOpenTable ;
         (cTableName)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cTableName = ' + TRANSFORM(cTableName) + ' - ' + TYPE('cTableName')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_BeforeOpenTable Event
Events
Language Reference


dbc_AfterRemoveTable Event

Visual FoxPro 9.0 Language Reference
dbc_AfterRemoveTable Event
See Also Example

Occurs after table removal is complete. There are two versions of the syntax.

PROCEDURE dbc_AfterRemoveTable(cTableName, lDelete, lRecycle)
PROCEDURE dbc_AfterRemoveTable
LPARAMETERS cTableName, lDelete, lRecycle

Parameters

cTableName

Specifies the name of the table that was removed from the database.
lDelete

Specifies whether the table was deleted instead of being converted to a free table.
lRecycle

Specifies whether the table was placed in the Windows Recycle Bin rather than immediately deleted from the disk. Some data, such as the table properties available only in tables contained in a database, is lost even if the table is only recycled rather than removed and deleted.

Remarks

You can use the dbc_AfterRemoveTable event to track access to the database after a table is removed from the database and from the disk.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameters passed.
PROCEDURE dbc_AfterRemoveTable ;
         (cTableName, ;
          lDelete, ;
          lRecycle)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cTableName = ' + TRANSFORM(cTableName) + ' - ' ;
                   + TYPE('cTableName ')
? '     lDelete    = ' + TRANSFORM(lDelete)    + ' - ' ;
                   + TYPE('lDelete')
? '     lRecycle   = ' + TRANSFORM(lRecycle)   + ' - ' ;
                   + TYPE('lRecycle')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_BeforeRemoveTable Event
Events
Language Reference


dbc_AfterRenameConnection Event

Visual FoxPro 9.0 Language Reference
dbc_AfterRenameConnection Event
See Also

Occurs before a connection is renamed. There are two versions of the syntax.

PROCEDURE dbc_AfterRenameConnection(cConnectionName, cNewName)
PROCEDURE dbc_AfterRenameConnection
LPARAMETERS cPreviousName, cNewName

Parameters

cPreviousName

Specifies the previous name of the connection.
cNewName

Specifies the new name of the connection.

Remarks

You can use the dbc_AfterRenameConnection event to track changes to the database as connections are renamed.

Return .F. from this procedure to prevent the connection from being renamed.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeRenameConnection Event


dbc_AfterRenameTable Event

Visual FoxPro 9.0 Language Reference
dbc_AfterRenameTable Event
See Also Example

Occurs before a table is renamed. There are two versions of the syntax.

PROCEDURE dbc_AfterRenameTable(cPreviousName, cNewName)
PROCEDURE dbc_AfterRenameTable
LPARAMETERS cPreviouName, cNewName

Parameters

cPreviousName

Specifies the current name of the table.
cNewName

Specifies the new name of the table.

Remarks

You can use the dbc_AfterRenameTable event to track changes to the database as tables are renamed.

Example

Copy Code
PROCEDURE dbc_AfterRenameTable;
   (cPreviousName, ;
    cNewName)
 ? '>>   ' + PROGRAM()
 ?? 'in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1
 ? '     Current DBC:    ' + SUBSTR(DBC(),RAT('\',DBC())+1
 ? '     cPreviousName = ' + TRANSFORM(cPreviousName)    + ' – ' + TYPE('cPreviousName ')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeRenameTable Event


dbc_AfterRenameView Event

Visual FoxPro 9.0 Language Reference
dbc_AfterRenameView Event
See Also

Occurs before a view is renamed. There are two versions of the syntax.

PROCEDURE dbc_AfterRenameView(cPreviousName, cNewName)
PROCEDURE dbc_AfterRenameView
LPARAMETERS cPreviousName, cNewName

Parameters

cPreviousName

Specifies the current name of the view.
cNewName

Specifies the new name of the view.

Remarks

You can use the dbc_AfterRenameView event to track changes to the database when views are renamed.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeRenameView Event


dbc_AfterValidateData Event

Visual FoxPro 9.0 Language Reference
dbc_AfterValidateData Event
See Also Example

Occurs after VALIDATE DATABASE completes. There are two versions of the syntax.

PROCEDURE dbc_AfterValidateData
(lRecover, lNoConsole, lPrint, lFile [, cFilename])
PROCEDURE dbc_AfterValidateData
LPARAMETERS lRecover, lNoConsole, lPrint, lFile [, cFilename]

Parameters

lRecover

Specifies whether the RECOVER keyword was included in the VALIDATE DATABASE command that triggered this event.
lNoConsole

Specifies whether the NOCONSOLE keyword was included in the VALIDATE DATABASE command that triggered this event.
lPrint

Specifies whether the PRINT keyword was included in the VALIDATE DATABASE command that triggered this event.
lFile

Specifies whether the TO FILE clause was included in the VALIDATE DATABASE command that triggered this event.
cFilename

Specifies the name of the output file named in the TO FILE clause of the VALIDATE DATABASE command. cFilename is optional, but if you omit it and use the TO FILE clause of VALIDATE DATABASE, you will receive the error "Must specify additional parameters." If you do not use TO FILE and include the cFilename parameter, it will be passed a value of .F.

Remarks

You can use the dbc_AfterValidateData event to track access to the database after data are validated.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameters passed.
PROCEDURE dbc_AfterValidateData ;
         (lRecover, ;
          lNoConsole, ;
          lPrint, ;
          lFile, ;
          cFileName)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     lRecover   = ' + TRANSFORM(lRecover)   + ' - ' ;
                    + TYPE('lRecover')
 ? '     lNoConsole = ' + TRANSFORM(lNoConsole) + ' - ' ;
                    + TYPE('lNoConsole')
 ? '     lPrint     = ' + TRANSFORM(lPrint)     + ' - ' ;
                    + TYPE('lPrint')
 ? '     lFile      = ' + TRANSFORM(lFile)      + ' - ' ;
                    + TYPE('lFile')
 ? '     cFileName  = ' + TRANSFORM(cFileName)  + ' - ' ;
                    + TYPE('cFileName ')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_BeforeValidateData Event


dbc_BeforeAddRelation Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeAddRelation Event
See Also

Occurs before a relation is added to the database. There are two versions of the syntax.

PROCEDURE dbc_BeforeAddRelation(cRelationID, cTableName, cRelatedChild,
   cRelatedTable, cRelatedTag)
PROCEDURE dbc_BeforeAddRelation
LPARAMETERS cRelationID, cTableName, cRelatedChild, cRelatedTable,
   cRelatedTag

Parameters

cRelationID

Specifies the Relation ID number stored in the database.
cTableName

Specifies the name of the parent table.
cRelatedChild

Specifies the name of the linked column.
cRelatedTable

Specifies the table containing the linked column.
cRelatedTag

Specifies the index tag of the parent table.

Remarks

You can use the dbc_BeforeAddRelation event to verify appropriate values for the parameters in a procedure that tracks, or manages access to the database before a relation is added to the database.

Return .F. from this procedure to prevent the relation from being added.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterAddRelation Event


dbc_BeforeAddTable Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeAddTable Event
See Also Example

Occurs before an existing free table is added to the active database.

You can use the dbc_BeforeAddTable event to execute code before the table is added to a database. This is useful for programming needs such as controlling whether or under what conditions a table is added to the database or to log the addition of the table. There are two versions of the syntax.

Note:
This event does not occur when you create a table in the database.

PROCEDURE dbc_BeforeAddTable(cTableName, cLongTableName)
PROCEDURE dbc_BeforeAddTable
LPARAMETERS [cTableName, cLongTableName]

Parameters

cTabl eName,

Specifies the name of the table being added.
cLongTableName

Specifies the long name to be given to the table.

Remarks

To prevent the table from being added to the database, return a value of False (.F.) from this procedure.

Example

Copy Code
PROCEDURE dbc_BeforeAddTable ;
         (cTableName, ;
          cLongTableName)
? '     cTableName     = ' + TRANSFORM(cTableName)     + ' - ' ;
                       + TYPE('cTableName ')
? '     cLongTableName = ' + TRANSFORM(cLongTableName) + ' - ' ;
                       + TYPE('cLongTableName ')
userID      = SUBSTR(SYS(0),AT('#',SYS(0))+2)
IF UPPER(userID) = 'MYALIAS'   && only one user can add tables.
   RETURN .T.
ENDIF
   RETURN .F.
ENDIF
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_AfterAddTable
dbc_BeforeRemoveTable
dbc_AfterRemoveTable
Events
Language Reference


dbc_BeforeAppendProc Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeAppendProc Event
See Also Example

Occurs before an APPEND PROCEDURES command completes. There are two versions of the syntax.

PROCEDURE dbc_BeforeAppendProc(cFileName, nCodePage, lOverwrite)
PROCEDURE dbc_BeforeAppendProc
LPARAMETERS cFileName, nCodePage, lOverwrite

Parameters

cFileName

Specifies the name of a text file from which the stored procedures are to be appended.
nCodePage,

Specifies the code page of the text file from which the stored procedures are to be appended. Visual FoxPro copies the contents of the text file and, as it does so, automatically converts those contents to the code page you specify.
lOverwrite

Specifies whether the OVERWRITE keyword was included in the APPEND PROCEDURE command. If OVERWRITE was omitted, the current stored procedures in the database are appended to the existing stored procedures, otherwise they replace any existing procedures.

Remarks

You can use the dbc_BeforeAppendProc to track attempted access to the database before stored procedures are appended.

Return .F. from this procedure to prevent the contents of the text file from being appended to the database stored procedures.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_BeforeAppendProc ;
         (cFileName,;
          nCodePage,;
          lOverwrite)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     Current DBC:      ' + SUBSTR(DBC(),RAT('\',DBC())+1)
 ? '     cFileName       = ' + TRANSFORM(cFileName)  + ' - ' ;
                         + TYPE('cFileName')
 ? '     nCodePage       = ' + TRANSFORM(nCodePage)  + ' - ' ;
                         + TYPE('nCodePage')
 ? '     lOverwrite      = ' + TRANSFORM(lOverwrite) + ' - ' ;
                         + TYPE('lOverwrite')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterAppendProc Event


dbc_BeforeCloseTable Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeCloseTable Event
See Also Example

Occurs before the table or view is closed. There are two versions of the syntax.

PROCEDURE dbc_BeforeCloseTable(cTableName)
PROCEDURE dbc_BeforeCloseTable
LPARAMETERS cTableName

Parameters

cTableName

Specifies the name of the table or view being closed.

Remarks

You can use the dbc_BeforeCloseTable event to track access to the database before a table is closed in the current database.

Return .F. from this procedure to prevent the table from being closed.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_BeforeCloseTable ;
         (cTableName)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cTableName = ' + TRANSFORM(cTableName) + ' - ' ;
                   + TYPE('cTableName')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_AfterCloseTable Event
Events
Language Reference


dbc_BeforeCopyProc Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeCopyProc Event
See Also Example

Occurs before the COPY PROCEDURE command begins. There are two versions of the syntax.

PROCEDURE dbc_BeforeCopyProc(cFileName, nCodePage, lAdditive)
PROCEDURE dbc_BeforeCopyProc
LPARAMETERS cFileName, nCodePage, lAdditive

Parameters

cFileName

Specifies the name of a text file to which the stored procedures are to be copied.
nCodePage,

Specifies the code page of the text file to which the stored procedures are to be copied. Visual FoxPro copies the contents of the text file and, as it does so, automatically converts those contents to the code page you specify.
lAdditive

Specifies whether the ADDITIVE keyword was included in COPY PROCEDURE command that triggered this event.

Remarks

You can use the dbc_BeforeCopyProc event to track attempted access to the database before stored procedure are copied.

Return .F. from this procedure to prevent the stored procedures from being copied.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_BeforeCopyProc ;
         (cFileName,;
          nCodePage,;
          lAdditive)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     Current DBC:      ' + SUBSTR(DBC(),RAT('\',DBC())+1)
 ? '     cFileName       = ' + TRANSFORM(cFileName)  + ' - ' + TYPE('cFileName')
 ? '     nCodePage       = ' + TRANSFORM(nCodePage)  + ' - ' + TYPE('nCodePage')
 ? '     lAdditive = ' + TRANSFORM(lAdditive) + ' - ' + TYPE('lAdditive')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterCopyProc Event


dbc_BeforeCreateConnection Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeCreateConnection Event
See Also Example

Occurs before a new connection is created.

PROCEDURE dbc_BeforeCreateConnection( )

Remarks

You can add code in the dbc_BeforeCreateConnection event to track attempted access to the database before a connection is created, or to prevent the creation of a connection.

Return .F. from this procedure to prevent the connection from being created.

Example

Copy Code
* Reports to the screen Event name and where it is called from.
PROCEDURE dbc_BeforeCreateConnection
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
RETURN .F.    && Prevents user from creating a connection.
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_AfterCreateConnection Event
Events
Language Reference


dbc_BeforeCreateOffline Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeCreateOffline Event
See Also Example

Occurs before a view is taken offline. There are two versions of the syntax.

PROCEDURE dbc_BeforeCreateOffline(cViewName, cPath)
PROCEDURE dbc_BeforeCreateOffline
LPARAMETERS cViewName, cPath

Parameters

cViewName

Specifies the name of the view being taken offline.
cPath

Specifies the directory in which the offline view is placed and the name of the offline view.

Remarks

You can use the dbc_BeforeCreateOffline event to verify appropriate values for cViewName and cPath or use those parameters in a procedure to track attempted access to the database before an offline view is created.

Return .F. from this procedure to prevent the view from taken offline.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_BeforeCreateOffline ;
         (cViewName,;
          cPath)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cViewName =  ' + TRANSFORM(cViewName) + ' - ' ;
                  + TYPE('cViewName')
? '     cPath     =  ' + TRANSFORM(cPath)     + ' - ' ;
                  + TYPE('cPath')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_AfterCreateOffline Event
Events
Language Reference


dbc_BeforeCreateTable Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeCreateTable Event
See Also Example

Occurs before a table is created in the active database. There are two versions of the syntax.

PROCEDURE dbc_BeforeCreateTable(cTableName, cLongTableNameT)
PROCEDURE dbc_BeforeCreateTable
LPARAMETERS cTableName, cLongTableName

Parameters

cTableName

Specifies the name of the table being created.
cLongTableName

Specifies the long name to be given to the table.

Remarks

This event does not occur when you create a free table.

You can use the dbc_BeforeCreateTable event to verify appropriate values for cTableName or cLongTableName. Use those parameters in a procedure to track, or manage access before a table is created in the database.

Return .F. from this procedure to prevent the table from being created.

Example

Copy Code
PROCEDURE dbc_BeforeCreateTable ;
         (cTableName, ;
          cLongTableName)
? '     cTableName     = ' + TRANSFORM(cTableName)     + ' - ' ;
                       + TYPE('cTableName ')
? '     cLongTableName = ' + TRANSFORM(cLongTableName) + ' - ' ;
                       + TYPE('cLongTableName ')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_AfterCreateTable Event
Events
Language Reference


dbc_BeforeCreateView Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeCreateView Event
See Also Example

Occurs before a SQL view (updatable cursor) is created. There are two versions of the syntax.

PROCEDURE dbc_BeforeCreateView(cViewName)
PROCEDURE dbc_BeforeCreateView
LPARAMETERS cViewName)

Parameters

cViewName

Specifies the name of the view being created.

Remarks

You can use the dbc_BeforeCreateView event to track attempted access to the database before a view is created.

Return .F. from this procedure to prevent the view from being created.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameters passed.
PROCEDURE dbc_BeforeCreateView ;
         (cViewName, ;
          lRemote)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     cViewName =  ' + TRANSFORM(cViewName) + ' - ' ;
                   + TYPE('cViewName ')+' /end/ '
*RETURN .f.
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterCreateView Event


dbc_BeforeDBGetProp Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeDBGetProp Event
See Also Example

Occurs before the DBGetProp( ) function runs. There are two versions of the syntax.

PROCEDURE dbc_BeforeDBGetProp(cName, cType, cProperty)
PROCEDURE dbc_BeforeDBGetProp
LPARAMETERS cName, cType, cProperty

Parameters

cName

Specifies the value of the first parameter in the DBGetProp( ) function, the name of the database, field, named connection, table, or view for which DBGETPROP( ) returns information.
cType

Specifies the value of the second parameter in the DBGetProp( ) function, the object type of the item named in cName.
cProperty

Specifies the value of the third parameter in the DBGetProp( ) function, the property for which DBGETPROP( ) returns information.

Remarks

You can use the dbc_BeforeDBGetProp event to track attempted access to the database before DBGetProp( ) runs.

Return .F. from this procedure to prevent the property value from being returned to DBGetProp(). This will cause the DBGetProp() function to return NULL.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_BeforeDBGetProp ;
         (cName,;
          cType,;
          cProperty)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     Current DBC: ' + SUBSTR(DBC(),RAT('\',DBC())+1)
 ? '     cName     =  ' + TRANSFORM(cName)     + ' - ' + TYPE('cName')
 ? '     cType     =  ' + TRANSFORM(cType)     + ' - ' + TYPE('cType')
 ? '     cProperty =  ' + TRANSFORM(cProperty) + ' - ' + TYPE('cProperty')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterDBGetProp Event
DBGETPROP( ) Function


dbc_BeforeDBSetProp Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeDBSetProp Event
See Also Example

Occurs before DBSetProp( ) runs. There are two versions of the syntax.

PROCEDURE dbc_BeforeDBSetProp(cName, cType, cProperty, ePropertyValue)
PROCEDURE dbc_BeforeDBSetProp
LPARAMETERS cName, cType, cProperty, ePropertyValue

Parameters

cName

Specifies the value of the first parameter in the DBGetProp( ) function, the name of the database, field, named connection, table, or view for which DBSETPROP( ) changes the value.
cType

Specifies the value of the second parameter in the DBSetProp( ) function, the object type of the item named in cName.
cProperty

Specifies the value of the third parameter in the DBSetProp( ) function, the property for which DBSETPROP( ) changes the value.
ePropertyValue

Specifies the value of the fourth parameter in the DBSetProp( ) function, the value to be assigned to the property in cProperty.

For details on valid cType and cProperty values, see DBSETPROP( ) and DBGETPROP( ) in Help.

Remarks

You can use the dbc_BeforeDBSetProp event to track attempted access to the database before DBSETPROP( ) runs.

Return .F. from this procedure to prevent the property value from being set. This will cause the DBSetProp() function to return .F..

Some property values can be changed using DBSetProp( ) or using a designer. For example, you can change the Comment property for a table using DBSetProp( ) as well as from the table designer. Because DBSetProp( ) makes changes directly to the database itself, dbc_BeforeModifyTable or dbc_AfterModifyTable will not catch changes made by DBSETPROP( ). To trap for changes that could be made either way, you would need to use dbc_BeforeDBSetProp, dbc_AfterDBSetProp, dbc_BeforeModifyTable, and dbc_AfterModifyTable to check for the appropriate changes.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_BeforeDBSetProp ;
         (cName,;
          cType,;
          cProperty,;
          ePropertyValue)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     Current DBC:     ' + SUBSTR(DBC(),RAT('\',DBC())+1)
 ? '     cName          = ' + TRANSFORM(cName)          + ' - ' + TYPE('cName')
 ? '     cType          = ' + TRANSFORM(cType)          + ' - ' + TYPE('cType')
 ? '     cProperty      = ' + TRANSFORM(cProperty)      + ' - ' + TYPE('cProperty')
 ? '     ePropertyValue = ' + TRANSFORM(ePropertyValue) + ' - ' + TYPE('ePropertyValue')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterDBSetProp Event


dbc_BeforeDeleteConnection Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeDeleteConnection Event
See Also

Occurs before a connection is deleted. There are two versions of the syntax.

PROCEDURE dbc_BeforeDeleteConnection(cConnectionName)
PROCEDURE dbc_BeforeDeleteConnection
LPARAMETERS cConnectionName

Parameters

cConnectionName

Specifies the name of the connection.

Remarks

You can use the dbc_BeforeDeleteConnection event to track attempted access to the database before connections are deleted.

Return .F. from this procedure to prevent the connection from being deleted.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterDeleteConnection Event


dbc_BeforeDropOffline Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeDropOffline Event
See Also Example

Occurs immediately before a DROPOFFLINE( ) function, which returns an offline view on line. There are two versions of the syntax.

PROCEDURE dbc_BeforeDropOffline(cViewName, cPath)
PROCEDURE dbc_BeforeDropOffline
LPARAMETERS cViewName, cPath

Parameters

cViewName

Specifies the name of the offline view being taken back online.
cPath

Specifies the directory in which the offline view is located.

Return .F. from this procedure to prevent returning the view online.

Remarks

You can use the dbc_BeforeDropOffline event to track attempted access to the database before an offline view is taken back online.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_BeforeDropOffline ;
         (cViewName,;
          cPath)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cViewName =  ' + TRANSFORM(cViewName) + ' - ' ;
                  + TYPE('cViewName')
? '     cPath     =  ' + TRANSFORM(cPath)     + ' - ' ;
                  + TYPE('cPath')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterDropOffline Event


dbc_BeforeDropRelation Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeDropRelation Event
See Also

Occurs before a relation is dropped from a database. There are two versions of the syntax.

PROCEDURE dbc_BeforeDropRelation(cRelationID, cTableName, cRelatedChild,
   cRelatedTable, cRelatedTag)
PROCEDURE dbc_BeforeDropRelation
LPARAMETERS [cRelationID, cTableName, cRelationChild, cRelatedTable,
   cRelatedTag]

Parameters

cRelationID

Specifies the Relation ID stored in the database.
cTableName

Specifies the name of the parent table.
cRelatedChild

Specifies the name of the linked column in the child table.
cRelatedTable

Specifies the child table containing the linked column.
cRelatedTag

Specifies the index tag of the parent table.

Remarks

You can use the dbc_BeforeDropRelation event to verify appropriate values for cRelationID and the other parameters in a procedure that tracks, or manages access to the database before a relation is dropped from the database.

Return .F. from this procedure to prevent the relation from being dropped.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterDropRelation Event


dbc_BeforeDropTable Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeDropTable Event
See Also Example

Occurs before the specified table is removed from the active database and deleted from disk with the DROP TABLE command. There are two versions of the syntax.

PROCEDURE dbc_BeforeDropTable(cTableName, lRecycle)
PROCEDURE dbc_BeforeDropTable
LPARAMETERS cTableName, lRecycle

Parameters

cTableName

Specifies the table being removed from the current database and deleted from disk.
lRecycle

Specifies whether the table is to be placed in the Microsoft Windows Recycle Bin rather than immediately deleted from the disk. Some data, such as the table properties available only in tables contained in a database, are lost even if the table is only recycled rather than removed and deleted.

Remarks

You can use the dbc_BeforeDropTable event to verify an appropriate value for cTableName, and use those parameters in a procedure to track, or manage access to the database before the table is removed from the database and the disk.

If you delete a table by using DELETE FILE or the operating system, no event occurs.

Return .F. from this procedure to prevent the table from being dropped.

Example

Copy Code
* Reports the name of the method, where it came from and what the
* parameter values were.
PROCEDURE dbc_BeforeDropTable ;
         (cTableName, ;
          lRecycle)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cTableName = ' + TRANSFORM(cTableName) + ' - ' ;
                   + TYPE('cTableName ')
? '     lRecycle   = ' + TRANSFORM(lRecycle)   + ' - ' ;
                   + TYPE('lRecycle')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_AfterDropTable Event
Events
Language Reference


dbc_BeforeDropView Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeDropView Event
See Also Example

Occurs before a View is removed from the current database. There are two versions of the syntax.

PROCEDURE dbc_BeforeDropView(cViewName)
PROCEDURE dbc_BeforeDropView
LPARAMETERS cViewName

Parameters

cViewName

Specifies the name of the view to be deleted from the current database.

Remarks

DROP VIEW is almost identical to DELETE VIEW; DROP VIEW is the ANSI SQL standard syntax for deleting a SQL view. Both commands remove a view definition from the active database, but the syntax is slightly different.

You can use the dbc_BeforeDropView event to track attempted access to the database before a view is removed from the database.

Return .F. from this procedure to prevent the view from being dropped.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_BeforeDropView ;
         (cViewName)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     cViewName =  ' + TRANSFORM(cViewName) + ' - ' ;
                   + TYPE('cViewName ')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterDropView Event


dbc_BeforeModifyConnection Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeModifyConnection Event
See Also

Occurs before a connection is modified. There are two versions of the syntax.

PROCEDURE dbc_BeforeModifyConnection(cConnectionName)
PROCEDURE dbc_BeforeModifyConnection
LPARAMETERS cConnectionName

Parameters

cViewName

Specifies the name of the connection modified.

Remarks

You can use the dbc_BeforeModifyView event to track attempted access to the database before connections are modified.

Return .F. from this procedure to prevent the connection from being modified.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterModifyConnection Event


dbc_BeforeModifyProc Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeModifyProc Event
See Also Example

Occurs before the stored procedures in the open database are modified.

PROCEDURE dbc_BeforeModifyProc( )

Remarks

You can use the dbc_BeforeModiProc event to track attempted access to the database before the stored procedures are modified.

Return .F. from this procedure to prevent the stored procedures from being modified.

Example

Copy Code
* Reports to the screen Event name, and where it is called from.
PROCEDURE dbc_BeforeModifyProc
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? DBC()
RETURN .F. && prevents modification of stored procedures.
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterModifyProc Event


dbc_BeforeModifyTable Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeModifyTable Event
See Also

Occurs before a table is modified. There are two versions of the syntax.

PROCEDURE dbc_BeforeModifyTable(cTableName)
PROCEDURE dbc_BeforeModifyTable
LPARAMETERS cTableName

Parameters

cTableName

Specifies the name of the table modified.

Remarks

You can use the dbc_BeforeModifyTable event to track attempted access to the database before tables are modified.

Return .F. from this procedure to prevent the table from being modified.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterModifyTable Event


dbc_BeforeModifyView Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeModifyView Event
See Also

Occurs before a view has been modified. There are two versions of the syntax.

PROCEDURE dbc_BeforeModifyView(cViewName)
PROCEDURE dbc_BeforeModifyView
LPARAMETERS cViewName

Parameters

cViewName

Specifies the name of the view modified.

Remarks

You can use the dbc_BeforeModifyView event to track attempted access to the database before Views are modified.

Return .F. from this procedure to prevent the view from being modified.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterModifyView Event


dbc_BeforeOpenTable Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeOpenTable Event
See Also Example

Occurs before a table or view contained in the database is opened. There are two versions of the syntax.

PROCEDURE dbc_BeforeOpenTable(cTableName)
PROCEDURE dbc_BeforeOpenTable
LPARAMETERS cTableName

Parameters

cTableName

Specifies the name of the table or view being opened.

Remarks

You can use method code in the dbc_BeforeOpenTable event to track attempted access before a table is opened in the database. This event occurs anytime a table or view in the database is opened either explicitly by the USE command or implicitly by other commands such as SELECT.

If the underlying tables are not open when a view is opened, this event occurs for both the tables and the view. The dbc_BeforeOpenTable event receives the name of the table as the parameter and not the cursor name.

Return .F. from this procedure to prevent the table from being opened.

Example

Copy Code
* Reports the method name, where it is called from and the
* value of the paramater cTableName.
PROCEDURE dbc_BeforeOpenTable ;
         (cTableName)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cTableName = ' + TRANSFORM(cTableName) + ' - ' ;
                    + TYPE('cTableName')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_AfterOpenTable Event
Events
Language Reference


dbc_BeforeRemoveTable Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeRemoveTable Event
See Also Example

Occurs before a table is removed from the database. There are two versions of the syntax.

PROCEDURE dbc_BeforeRemoveTable(cTableName, lDelete, lRecycle)
PROCEDURE dbc_BeforeRemoveTable
LPARAMETERS cTableName, lDelete, lRecycle

Parameters

cTableName

Specifies the name of the table being removed from the database.
lDelete

Specifies whether the table is deleted rather than converted to a free table.
lRecycle

Specifies whether the table is placed in the Windows Recycle Bin rather than immediately deleted from the disk. Some data, such as the table properties available only in tables contained in a database, is lost even if the table is only recycled rather than removed and deleted.

Remarks

You can use the dbc_BeforeRemoveTable event to track, or manage access to the database before a table is removed from the database and from the disk.

Return .F. from this procedure to prevent the table from being removed.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_BeforeRemoveTable ;
         (cTableName, ;
          lDelete, ;
          lRecycle)
? '>>   ' + PROGRAM()
?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
? '     cTableName = ' + TRANSFORM(cTableName) + ' - ' ;
                   + TYPE('cTableName ')
? '     lDelete    = ' + TRANSFORM(lDelete)    + ' - ' ;
                   + TYPE('lDelete')
? '     lRecycle   = ' + TRANSFORM(lRecycle)   + ' - ' ;
                   + TYPE('lRecycle')+' /end/ '
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_AfterRemoveTable Event
Events
Language Reference


dbc_BeforeRenameConnection Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeRenameConnection Event
See Also Example

Occurs before a connection is renamed. There are two versions of the syntax.

PROCEDURE dbc_BeforeRenameConnection(cPreviousName,cNewName)
PROCEDURE dbc_BeforeRenameConnection
LPARAMETERS cPreviousName, cNewName

Parameters

cPreviousName

Specifies the current name of the connection.
cNewName

Specifies the new name of the connection.

Remarks

You can use the dbc_BeforeRenameConnection event to track attempted access to the database before connections are renamed.

Return .F. from this procedure to prevent the connection from being renamed.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_BeforeRenameConnection ;
         (cPreviousName, cNewName)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     cPreviousName = ' + TRANSFORM(cPreviousName)    + ' - ' ;
                       + TYPE('cPreviousName ')
 ? '     cNewName      = ' + TRANSFORM(cNewName)         + ' - ' ;
                       + TYPE('cNewName ')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterRenameConnection Event


dbc_BeforeRenameTable Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeRenameTable Event
See Also Example

Occurs before a table is renamed. There are two versions of the syntax.

PROCEDURE dbc_BeforeRenameTable(cPreviousName, cNewName)
PROCEDURE dbc_BeforeRenameTable
LPARAMETERS cPreviousName, cNewName

Parameters

cPreviousName

Specifies the current name of the table.
cNewName

Specifies the new name of the table.

Remarks

You can use the dbc_BeforeRenameTable event to track attempted access to the database before a connection, is renamed, or to prevent renaming of a table.

Return .F. from this procedure to prevent the table from being renamed.

Example

Copy Code
PROCEDURE dbc_BeforeRenameTable;
   (cPreviousName, ;
    cNewName)
 ? '>>   ' + PROGRAM()
 ?? 'in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1
 ? '     Current DBC:    ' + SUBSTR(DBC(),RAT('\',DBC())+1
 ? '     cPreviousName = ' + TRANSFORM(cPreviousName)     + ' – ' +
TYPE('cPreviosName ')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterRenameTable Event


dbc_BeforeRenameView Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeRenameView Event
See Also

Occurs before a view is renamed. There are two versions of the syntax.

PROCEDURE dbc_BeforeRenameView(cPreviousName, cNewName)
PROCEDURE dbc_BeforeRenameView
LPARAMETERS cPreviousName, cNewName

Parameters

cPreviousName

Specifies the current name of the view.
cNewName

Specifies the new name of the view.

Remarks

You can use the dbc_BeforeRenameView event to track attempted access to the database before views are renamed.

Return .F. from this procedure to prevent the view from being renamed.

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterRenameView Event


dbc_BeforeValidateData Event

Visual FoxPro 9.0 Language Reference
dbc_BeforeValidateData Event
See Also Example

Occurs immediately before the VALIDATE DATABASE command runs. There are two versions of the syntax.

PROCEDURE dbc_BeforeValidateData
(lRecover, lNoConsole, lPrint, lFile [, cFilename])
PROCEDURE dbc_BeforeValidateData
LPARAMETERS lRecover, lNoConsole, lPrint, lFile [, cFilename]

Parameters

lRecover

Specifies whether the RECOVER keyword was included in the VALIDATE DATABASE command that triggered this event.
lNoConsole

Specifies whether the NOCONSOLE keyword was included in the VALIDATE DATABASE command that triggered this event.
lPrint

Specifies whether the PRINT keyword was included in the VALIDATE DATABASE command that triggered this event.
lFile

Specifies whether the FILE keyword was included in the VALIDATE DATABASE command that triggered this event.
cFilename

Specifies the name of the output file named in the TO FILE clause of the VALIDATE DATABASE command. cFilename is optional, but if you omit it and use the TO FILE clause of VALIDATE DATABASE, you will receive the error "Must specify additional parameters." If you do not use TO FILE and include the cFilename parameter, it will be passed a value of .F..

Remarks

You can use the dbc_BeforeValidateData event to track attempted access to the database before data are validated.

Return .F. from this procedure to prevent the database from being validated.

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameters passed.
PROCEDURE dbc_BeforeValidateData;
         (lRecover, ;
          lNoConsole, ;
          lPrint, ;
          lFile, ;
          cFileName)
 ? '>>   ' + PROGRAM()
 ?? ' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     lRecover   = ' + TRANSFORM(lRecover)   + ' - ' ;
                    + TYPE('lRecover')
 ? '     lNoConsole = ' + TRANSFORM(lNoConsole) + ' - ' ;
                    + TYPE('lNoConsole')
 ? '     lPrint     = ' + TRANSFORM(lPrint)     + ' - ' ;
                    + TYPE('lPrint')
 ? '     lFile      = ' + TRANSFORM(lFile)      + ' - ' ;
                    + TYPE('lFile')
 ? '     cFileName  = ' + TRANSFORM(cFileName)  + ' - ' ;
                    + TYPE('cFileName ')+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
dbc_AfterValidateData Event


dbc_CloseData Event

Visual FoxPro 9.0 Language Reference
dbc_CloseData Event
See Also Example

Occurs when a database closes. There are two versions of the syntax.

PROCEDURE dbc_CloseData(cDatabaseName, lAll)
PROCEDURE dbc_CloseData
LPARAMETERS cDatabaseName, lAll

Parameters

cDatabaseName

Specifies the name of the target database.
lAll

Specifies whether the ALL keyword was included in the CLOSE DATABASES command. If DBC Events is turned on, this event occurs whenever a database is closed whether or not it is closed explicitly with the CLOSE DATABASES command.

Remarks

You can use the dbc_CloseData event to verify appropriate values for cDatabaseName and lAll or use those parameters in a procedure to track access to the database when the database is about to be closed

When several databases are closed at one time, the dbc_CloseData method for each database is fired in turn. Therefore, if you issue the CLOSE DATABASES ALL command, several different CloseData events occur and several different dbc_CloseData methods can be executed.

Return .F. from this procedure to prevent the database from being closed.

Example

Copy Code
PROCEDURE dbc_CloseData ;
         (cDatabaseName,;
          lAll)
? '     cDatabaseName = ' + TRANSFORM(cDatabaseName) + ' - ' ;
                      + TYPE('cDatabaseName')
? '     lAll          = ' + TRANSFORM(lAll)          + ' - ' ;
                      + TYPE('lAll')+' /end/ '
RETURN .F.     && This will prevent database closure.
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
dbc_BeforeAddTable Event
dbc_Activate Event
Events
Language Reference


dbc_Deactivate Event

Visual FoxPro 9.0 Language Reference
dbc_Deactivate Event
See Also Example

Occurs when a database ceases to be active. There are two versions of the syntax.

PROCEDURE dbc_Deactivate(cDatabaseName)
PROCEDURE dbc_Deactivate
LPARAMETERS cDatabaseName

Parameters

cDatabaseName

Specifies the name of the database being deactivated.

Remarks

You can have many Databases open at the same time but only one can be active at a time. Several situations can deactivate a database. To explicitly deactivate a database without activating another database, use the SET DATABASE TO command without arguments.

If several databases (with DBC Events turned on) are open, when one is deactivated the dbc_Deactivate method in that database is executed.

If you place DBC Events code in a program file, the code applies to any database that specifies that program file as its events file. In such program code, use the cDatabaseName parameter to determine which database called the event. This way, you can use one block of method code to determine the deactivated database and then apply code appropriate to that database.

Return .F. from this procedure to prevent the database from being deactivated. Because closing a database implicitly deactivates it, this will also prevent the database from being closed.

Example

Copy Code
PROCEDURE dbc_Deactivate ;
         (cDatabaseName)
? '     cDatabaseName = ' + TRANSFORM(cDatabaseName) + ' - ' ;
                      + TYPE('cDatabaseName')+' /end/ '
ENDPROC

See Also

Other Resources

dbc_Activate Event
SET DATABASE Command
dbc_CloseData Event
dbc_ModifyData Event
dbc_OpenData Event
Events
Language Reference


dbc_ModifyData Event

Visual FoxPro 9.0 Language Reference
dbc_ModifyData Event
See Also Example

Occurs immediately after MODIFY DATABASE is issued. Use to prevent opening of the database designer window. There are two versions of the syntax.

PROCEDURE dbc_ModifyData(cDatabaseName, lNoWait, lNoEdit )
PROCEDURE dbc_ModifyData
LPARAMETERS [cDatabaseName, lNoWait, lNoEdit ]

Parameters

CDatabaseName

Specifies the name of the Database being modified.
lNoWait

Specifies whether the NOWAIT keyword was included in the MODIFY DATABASE command, which would cause the program execution to continue after the Database Designer is opened.
lNoEdit

Specifies whether the NOEDIT keyword was included in the MODIFY DATABASE command, which would prevent editing of the database.

Remarks

You can use the dbc_ModifyData event to track access to the database when the database is modified. Return .F. from this procedure to prevent the database from being modified.

Example

Copy Code
PROCEDURE dbc_ModifyData ;
         (CDatabaseName, ;
            lNoWait, ;
            lNoEdit)
? '     cDatabaseName = ' + cDatabaseName + ' - ' ;
                      + TYPE('cDatabaseName ')
 ? '     lNoWait       = ' + TRANSFORM(lNoWait) + ' - ' ;
                       + TYPE('lNoWait')
 ? '     lNoEdit       = ' + TRANSFORM(lNoEdit) + ' - ' ;
                       + TYPE('lNoEdit')+' /end/ '
* Stop user from changing the database in the Designer.
IF lNoEdit
   RETURN .T.
ELSE
   RETURN .F.
ENDIF
ENDPROC

See Also

Other Resources

MODIFY DATABASE Command
How to: Enable or Disable DBC Events
Database Designer
Events
Language Reference


dbc_OpenData Event

Visual FoxPro 9.0 Language Reference
dbc_OpenData Event
See Also Example

Occurs when a database is opened explicitly by the OPEN DATABASE command or implicitly by another command such as MODIFY DATABASE or USE <Table> with a table contained in a closed database. There are two versions of the syntax.

PROCEDURE dbc_OpenData (cDatabaseName, lExclusive, lNoUpdate, lValidate )
PROCEDURE dbc_OpenData
LPARAMETERS [cDatabaseName, lExclusive, lNoUpdate, lValidate ]

Parameters

cDatabaseName

Specifies the name of the database being opened.
lExclusive

Specifies whether the database is being opened in exclusive mode.
lNoUpdate

Specifies whether the NOUPDATE keyword was included in the OPEN DATABASE command, which means the database is being opened in read only mode.
lValidate

Specifies whether the VALIDATE keyword was included in the OPEN DATABASE command, which causes the database to be validated as it is opened.

Remarks

You can use the dbc_OpenData event to track attempted access to the database as the database opens.

By returning false, this method prevents the database from being opened.

Example

Copy Code
PROCEDURE dbc_OpenData ;
         (cDatabaseName, ;
          lExclusive, ;
          lNoUpdate, ;
          lValidate)
 ? '     cDatabaseName = ' + TRANSFORM(cDatabaseName) + ' - ' ;
                       + TYPE('cDatabaseName')
 ? '     lExclusive    = ' + TRANSFORM(lExclusive) + ' - ' ;
                       + TYPE('lExclusive')
 ? '     lNoUpdate     = ' + TRANSFORM(lNoUpdate)  + ' - ' ;
                       + TYPE('lNoUpdate')
 ? '     lValidate     = ' + TRANSFORM(lValidate)  + ' - ' ;
                       + TYPE('lValidate'
ENDPROC

See Also

Other Resources

How to: Enable or Disable DBC Events
OPEN DATABASE Command
MODIFY DATABASE Command
Events
Language Reference


dbc_PackData Event

Visual FoxPro 9.0 Language Reference
dbc_PackData Event
See Also Example

Occurs before the PACK DATABASE command runs.

PROCEDURE dbc_PackData( )

Remarks

You can use the dbc_PackData event to track access to the database before a PACK DATABASE runs.

Return .F. from this procedure to prevent the database from being packed. You will get a "File access denied" error when attempting to pack the database when returning .F..

Example

Copy Code
* Reports to the screen Event name, where it is called from and ;
* the parameter passed.
PROCEDURE dbc_PackData
 ? '  -  ' + PROGRAM()
 ??' in ' + SUBSTR(SYS(16),RAT('\',SYS(16))+1)
 ? '     Current DBC: ' + SUBSTR(DBC(),RAT('\',DBC())+1)+' /end/ '
ENDPROC

See Also

Other Resources

Events
How to: Enable or Disable DBC Events
PACK DATABASE Command


DblClick Event

Visual FoxPro 9.0 Language Reference
DblClick Event
See Also

Occurs when the user presses and releases the mouse button twice in quick succession.

PROCEDURE Object.DblClick

Remarks

Applies To: CheckBox Control | ComboBox Control | CommandGroup Control | Container Object | Control Object | EditBox Control | Form Object | Grid Control | Header Object | Image Control | Label Control | Line Control | ListBox Control | OptionButton Control | OptionGroup Control | Page Object | PageFrame Control | Shape Control | Spinner Control | TextBox Control | ToolBar Object

The DblClick event also occurs when you select an item in a list box or a combo box and press ENTER.

If DblClick does not occur within the system's double-click time limit, the object recognizes another Click event. Therefore, when you attach procedures for these related events, make sure that their actions do not conflict. Controls that do not receive DblClick events may receive two single clicks instead of a double-click.

Note:
If the mouse has more than one button, you can distinguish between the left, right, and middle mouse buttons using the MouseDown and MouseUp events.

See Also

Other Resources

Click Event
MouseDown Event
MouseUp Event
Events
Language Reference


Deactivate Event

Visual FoxPro 9.0 Language Reference
Deactivate Event
See Also

Occurs when a container object, such as a form, is no longer active because none of its contained objects has the focus.

PROCEDURE Object.Deactivate

Remarks

Applies To: Form | FormSet | Page | ProjectHook Object | ToolBar

The Activate and Deactivate events occur only when you are moving the focus within an application. Moving focus to or from a form in another application does not trigger either event. The Deactivate event does not occur when unloading a form.

When a new object is activated, programmatically or interactively, the Deactivate event for the previously active object occurs, and the Activate event for the new object occurs.

For Form objects, clicking the Visual FoxPro desktop causes a form's Deactivate event to occur and deactivates an active user form. This improvement provides better integration with the BINDEVENT( ) function for activating and deactivating forms.

For ToolBar objects, Deactivate occurs when the toolbar is hidden using the Hide method.

For ProjectHook objects, Deactivate occurs when you click away from the Project window or call the ACTIVATE WINDOW command for a different window.

See Also

Other Resources

Activate Event
Hide Method
LostFocus Event
Show Method
Visible Property
BINDEVENT( ) Function
Events
Language Reference


Deleted Event

Visual FoxPro 9.0 Language Reference
Deleted Event
See Also

Occurs when the user marks a record for deletion or unmarks a record marked for deletion.

PROCEDURE Grid.Deleted
LPARAMETERS nRecNo

Parameters

nRecNo

Returns the record number of the row being deleted.

Remarks

Applies To: Grid

See Also

Other Resources

DELETE Command
DeleteMark Property
Events
Language Reference


Destroy Event

Visual FoxPro 9.0 Language Reference
Destroy Event
See Also

Occurs when an object is released.

PROCEDURE Object.Destroy

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | Container Object | Control Object | Cursor | CursorAdapter Class | Custom | DataEnvironment | EditBox | Exception Class | Form | FormSet | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | Page | PageFrame | ProjectHook Object | Relation | ReportListener Object | Session Object | Shape | Spinner | TextBox | Timer | ToolBar

The Destroy event for a container object triggers before the Destroy event for any of its contained objects; the container's Destroy event can refer to its contained objects before they are released.

See Also

Other Resources

AddObject Method
CREATEOBJECT( ) Function
Init Event
RELEASE Command
QueryUnload Event
Unload Event
Release Method
Events
Language Reference


DownClick Event

Visual FoxPro 9.0 Language Reference
DownClick Event
See Also

Occurs when the user clicks the down arrow of a Spinner control, the drop-down arrow of a ComboBox control, or the down arrow in the drop-down list of a ComboBox control.

PROCEDURE Control.DownClick

Remarks

Applies To: ComboBox | Spinner

See Also

Other Resources

UpClick Event
Events
Language Reference


DragDrop Event

Visual FoxPro 9.0 Language Reference
DragDrop Event
See Also

Occurs when a drag-and-drop operation is completed.

PROCEDURE Object.DragDrop
LPARAMETERS oSource, nXCoord, nYCoord

Parameters

You must include an LPARAMETERS or PARAMETERS statement in the event procedure and specify a name for each parameter. Visual FoxPro passes the DragDrop event parameters in the following order:

oSource

References the control being dragged. You can refer to properties and methods of the control with this parameter.
nXCoord, nYCoord

Contains the horizontal (nXCoord) and vertical (nYCoord) position of the mouse pointer within the Form when data is dropped on a drop target. These coordinates are expressed in terms of the Form's coordinate system in the unit of measurement specified by the ScaleMode property of the Form.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

A drag-and-drop operation is completed when a control is dragged over another control or form and the mouse button is released, or when the Drag method with its nAction argument set to 2 (Drop) is called for the control.

Use a DragDrop event to control what happens after a drag operation is complete. For example, you can move the source control to a new location or copy a file from one location to another.

Note:
The DragDrop event involves two objects, a control being dragged and a target object. The DragDrop event is triggered for the target object, not the control being dragged. Use the DragMode property and Drag method to specify how dragging is to be initiated. Once dragging is initiated, you can handle events that precede a DragDrop event with a DragOver event.

See Also

Other Resources

Drag Method
DragIcon Property
DragMode Property
DragOver Event
MouseDown Event
MouseUp Event
MouseMove Event
Events
Language Reference


DragOver Event

Visual FoxPro 9.0 Language Reference
DragOver Event
See Also

Occurs when a control is being dragged over a target object.

PROCEDURE Object.DragOver
LPARAMETERS oSource, nXCoord, nYCoord, nState

Parameters

You must include an LPARAMETERS or PARAMETERS statement in the event procedure and specify a name for each parameter; otherwise an error occurs. Visual FoxPro passes the DragOver event parameters in the following order:

oSource

Contains a reference to the control being dragged. You can refer to properties and methods of the control with this parameter.
nXCoord, nYCoord

Contains the horizontal (nXCoord) and vertical (nYCoord) position of the mouse pointer within the Form when data is dragged over a drop target. These coordinates are expressed in terms of the Form's coordinate system in the unit of measurement specified by the ScaleMode property of the Form. '
nState

Contains a number that represents the transition state of the control being dragged in relation to the target object:

Setting Description

0

Enter. The control is being dragged within the range of a target.

1

Leave. The control is being dragged out of the range of a target.

2

Over. The control has moved from one position in the target to another.
Use nStateto determine actions at key transition points. For example, you can highlight a possible target on nState= 0 (Enter) and restore the object's appearance on nState= 1 (Leave).

When an object receives a DragOver event with nState = 0 (Enter):

  • A DragDrop event is triggered if the source control is dropped on a target object.

  • Another DragOver event is triggered with nState = 1 (Leave) if the source control is not dropped on a valid target.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

The object under the drag icon is the target object and responds to the DragOver event. You can use this event to monitor when the mouse pointer enters, leaves, or is directly over a target object.

Use a DragOver event to determine what happens after dragging is initiated and before a control is dropped onto a target. For example, you can verify a valid target range by highlighting the target, by setting the BackColor, or ForeColor property or by displaying a special pointer.

See Also

Other Resources

Drag Method
DragDrop Event
DragIcon Property
DragMode Property
MouseDown Event
MouseUp Event
MouseMove Event
Events
Language Reference


DropDown Event

Visual FoxPro 9.0 Language Reference
DropDown Event
See Also

Occurs when the list portion of a ComboBox control is about to drop down after the drop-down arrow is clicked.

PROCEDURE ComboBox.DropDown

Remarks

Applies To: ComboBox

Use a DropDown event procedure to make final updates to the list portion of a ComboBox before the user makes a selection. This enables you to add or remove items from the list using the AddItem or RemoveItem method. This flexibility is useful if you want controls to interact at run time. For example, what you want to appear in the list portion of a ComboBox could be determined by what the user chooses in an OptionGroup.

In Visual FoxPro 9.0 you can include the NODEFAULT Command within the DropDown event procedure to prevent the list portion of a ComboBox control from dropping down. Including NODEFAULT prevents a user from accessing the list portion, either with the mouse or the keyboard.

See Also

Other Resources

AddItem Method
DownClick Event
RemoveItem Method
Events
Language Reference


Error Event (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Error Event (Visual FoxPro)
See Also

Occurs when an error occurs in a method at run time. You can add Error event code so that the object can handle errors.

Note:
The Error event occurs only when the error occurs in code. If the Error event does not contain code, the Error event does not occur. If an ON ERROR routine is already on the call stack, the Error event does not occur.

Tip:
Make sure that you include code that handles errors that you cannot anticipate. Otherwise, the Error event code executes but does not take action to handle the unanticipated error, and the default Visual FoxPro error message will not display.

PROCEDURE Object.Error
LPARAMETERS nError, cMethod, nLine

Parameters

nError

Contains the Visual FoxPro error number.
cMethod

Contains the name of the method that caused the error. However, if a method calls a user-defined function, and an error occurs within that function, cMethod contains the name of the user-defined function, rather than the name of the method that called the function.
nLine

Contains the line number within the method or user-defined function that caused the error.

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | Cursor | CursorAdapter Class | Custom | DataEnvironment | EditBox | Exception Class | Form | FormSet | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Relation | ReportListener Object | Session Object | Shape | Spinner | TextBox | Timer | ToolBar

The Error event overrides the ON ERROR routine and makes it possible for each object to detect and handle errors internally.

If any errors occur in the code for an Error event, the object must handle those errors and cannot escalate them to an ON ERROR routine or TRY...CATCH...FINALLY structure.

See Also

Other Resources

ON ERROR Command
TRY...CATCH...FINALLY Command
Events
Language Reference


EvaluateContents Event

Visual FoxPro 9.0
EvaluateContents Event
See Also Example

Occurs just before ReportListener begins rendering objects for a band, for each layout element of Expression type, providing an opportunity to change its attributes.

PROCEDURE Object.EvaluateContents
LPARAMETERS nFRXRecno, oObjProperties

Parameters

Visual FoxPro passes the EvaluateContents event parameters in the following order:

nFRXRecno

Integer data type, specifying the record number in the report or label definition file (frx or lbx) describing the layout element being rendered.
oObjProperties

An object of Empty class, with members providing values relevant to adjusting the attributes of an Expression layout element.

oObjProperties member Type Usage

reload

Logical, defaults to .F.

Flag to alert the ReportListener if you make changes.

Set this value to True (.T.) to notify the ReportListener of changes to any of the read/write members of oObjProperties.

text

Character, defaults to evaluated contents of the Expression layout element.

You can change this value to change the rendered contents of the Expression at run time.

value

Variant, readonly

This value provides the evaluated results of report expressions, including calculated fields, of the following data types:

Double (B)

Date (D)

Float (F)

Integer (I)

Logical (L)

Numeric (N)

DateTime (T)

Currency (Y)

Null (X)

For other data types, its contents is a null string ("").

Expressions concatenated with the special operators ";" and "," may have elements of mixed type, and are considered character strings (type "C") in this context. For more information, see Trimming and Concatenating Expressions.

fontname

Character, defaults to the font stored in the report or label definition table for this layout element.

You can change this value to change the font of the Expression at run time.

fontstyle, fontsize

Integer, default to the numeric style and size values stored in the report or label definition table for this layout element.

You can change these values to change the size and style of the font used to render this Expression at run time.

Recognized numeric values for oObjProperties.fontstyle are documented in the 60FRX.DBF table in the FILESPEC directory.

For more information about 60FRX, see Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx).

fillred, fillblue, fillgreen, penred, penblue, pengreen

Integer, valid values 0 to 255, defaults to 255, defaults to the values stored in the report or label definition table, unless the table value was -1 to indicate "use default". If the table value was -1, the ReportListener substitutes the real value it intends to use.

You can change these values to change the Red, Blue, and Green components of the Fill and Pen colors for an Expression element.

For more information, see How to: Change Colors in Report Controls.

If a non-valid value or non-numeric value is passed for any of the color properties, they revert to default values stored in the report definition table. No error occurs.

fillalpha

Integer, valid values 0 to 255, defaults to 0 when backstyle is transparent and 255 when backstyle is opaque.

See Remarks below for information on using the alpha values of report layout elements. If a non-valid value or non-numeric value is passed for this value, it reverts to the default value as shown in this chart.

For information on report backstyle settings (transparent and opaque), see How to: Change Opacity of Report Controls.

penalpha

Integer, valid values 0 to 255, defaults to 255 (opaque).

See Remarks below for information on using the alpha values of report layout elements.

If a non-valid value or non-numeric value is passed for this value, it reverts to the default value as shown in this chart.
Note:
Microsoft reserves the right to invoke EvaluateContents for additional report and label layout elements, as needed, and to add to the oObjProperties members appropriately for these additional layout element types. You can use nFRXRecno to test for layout element type, as shown in the sample code in Render Method.

Remarks

Applies To: ReportListener Object.

Visual FoxPro calls EvaluateContents at the beginning of band processing, once for each Expression element. It is not guaranteed to be called exactly once; it may be called multiple times for evaluated expressions that span bands or pages if the Report System deems necessary (for example, if the expression includes _PAGENO).

Note:
If you write code to try to forecast when EvaluateContents might be called multiple times, consider that not all band types support spanning pages. Refer to Report Bands for more information.

Tip:
To enhance performance, Visual FoxPro does not call either AdjustObjectSize or EvaluateContents if it determines that there is no code in the ReportListener for the event. If you usually include placeholder code or generalized code in every event, consider omitting such code for these two events, especially if the class level is abstract (never directly instantiated). Only include code at the class levels that actually use this functionality. The performance cost for EvaluateContents increases with amount of text the native ReportListener provides in the oObjProperties.text member property, so it may vary with each call.

You can use this method to change various characteristics of Expression layout elements. However, you cannot change the width of the layout element, so you should adjust the font characteristics and contents of the Expression with this limitation in mind. If the layout element has been marked to stretch, it follows the same rules as Shape and Picture elements to which you make height adjustments in the AdjustObjectSize event. For more information, see AdjustObjectSize Event.

EvaluateContents gives you the means to change the Alpha value (transparency) of both the Pen and Fill values for an Expression. Report and label definition files store only RGB (Red, Green, Blue) components of color values, with a single setting for "opaque" or "transparent." Using EvaluateContents, you can provide more subtle color effects by direct manipulation of the Alpha value.

Tip:
The ability to use Alpha color values when rendering is a feature provided by Microsoft Windows GDI+. For more information, see Using GDI+ in Reports.

Example

The following example cycles through different color combinations based for the odd and even instances of any report's Detail band Expressions, providing a "greenbar" output effect. It also applies some style attributes to elements not in Detail bands. Notice that these effects are applied only to Expressions (for example, labels in a Page Header band are not affected).
Copy Code
oReportListener = CREATEOBJECT("greenBar")
oReportListener.ListenerType = 1
REPORT FORM (GETFILE("frx")) PREVIEW OBJECT oReportListener

#DEFINE DETAIL_BAND 4
#DEFINE BOLD_UNDERLINE_ITALIC 1+4+2
DEFINE CLASS greenBar AS ReportListener
   detailInstance = 0
   isDetail = .F.

   PROC BeforeBand(nBandObjCode, nFRXRecno)
     IF nBandObjCode = DETAIL_BAND
        THIS.detailInstance = THIS.detailInstance + 1
        THIS.isDetail = .T.
     ELSE
        THIS.isDetail = .F.
     ENDIF
   ENDPROC

   PROC EvaluateContents(nFRXRecno, oProps)
       oProps.Reload = .T.
       * re-load every time, in this example,
       * since we want to change every Expression
       IF THIS.isDetail
          IF THIS.detailInstance % 2 = 0
             oProps.penRed = 0
             oProps.penBlue = 125
             oProps.penGreen = 0
          ELSE
             oProps.penRed = 0
             oProps.penBlue = 0
             oProps.penGreen = 0
             oProps.fillRed = 0
             oProps.FillBlue = 0
             oProps.FillGreen = 255
             oProps.FillAlpha = 125
              *half-transparent background color
          ENDIF
       ELSE
          oProps.FontStyle = BOLD_UNDERLINE_ITALIC
       ENDIF
   ENDPROC
ENDDEFINE

See Also

Tasks

How to: Add Field Controls to Reports

Reference

ReportListener Object

Other Resources

Events (Visual FoxPro)
Language Reference (Visual FoxPro)


GotFocus Event

Visual FoxPro 9.0 Language Reference
GotFocus Event
See Also

Occurs when an object receives the focus, either by user action or through code.

PROCEDURE Object.GotFocus

Remarks

Applies To: CheckBox | ComboBox | CommandButton | Container Object | Control Object | EditBox | Form | ListBox | OLE Bound Control | OLE Container Control | OptionButton | Spinner | TextBox

Use the GotFocus event to specify actions to occur when an object receives the focus. For example, by attaching a GotFocus event to each control on a Form, you can guide a user by displaying brief instructions or status bar messages. You can also provide visual cues by enabling, disabling, or showing other controls that depend on the control that has the focus.

A control receives the focus by user action, such as a mouse click, or when the SetFocus method is called in code.

Note:
An object can receive the focus only if its Enabled and Visible properties are set to true (.T.). To customize the keyboard interface for moving the focus, set the tab order or specify access keys for controls on a form. The GotFocus event occurs after the Activate event for the control's container.

See Also

Other Resources

Activate Event
ActiveControl Property
Click Event
Deactivate Event
Enabled Property
LostFocus Event
SetFocus Method
TabIndex Property
TabStop Property
Visible Property
Events
Language Reference


Init Event

Visual FoxPro 9.0 Language Reference
Init Event
See Also

Occurs when an object is created.

PROCEDURE Object.Init
[LPARAMETERS Param1, Param2,...]

Parameters

Param1, Param2...

Parameters are optional, but if parameters are passed, you must include an LPARAMETERS or PARAMETERS statement that lists each parameter. Otherwise, Visual FoxPro generates an error.

Remarks

Applies To: CheckBox | Collection Class | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | Cursor | CursorAdapter Class | Custom | DataEnvironment | EditBox | Exception Class | Form | FormSet | Grid | Header | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Relation | ReportListener Object | Session Object | Shape | Spinner | TextBox | Timer | ToolBar

For form sets and other container objects, the Init events for all the contained objects are triggered before the container's Init event, so you can access the contained objects within the container's Init event. The Init event for each contained object occurs in the order it was added to the container object.

To prevent a control from being created, return false (.F.) from the Init event. The Destroy event will not be triggered. For example, the following code returns false (.F.) if the Invoice table is not available:

Copy Code
PROCEDURE INIT
  IF NOT FILE("INVOICE.DBF")
  ERROR 'Initialization Failed: File not found'
  RETURN .F.
  ELSE
  USE INVOICE IN 0 AGAIN
  THIS.WorkArea = SELECT()
  ENDIF
ENDPROC

See Also

Other Resources

Events
AddObject Method
CREATEOBJECT( ) Function
Load Event


InteractiveChange Event

Visual FoxPro 9.0 Language Reference
InteractiveChange Event
See Also

Occurs when the user changes the value of a control using the keyboard or the mouse.

PROCEDURE Control.InteractiveChange

Remarks

Applies To: CheckBox | ComboBox | CommandGroup | EditBox | ListBox | OptionGroup | Spinner | TextBox

This event occurs each time the object's value changes interactively. For example, as a user types in a text box, the InteractiveChange event is triggered after each keystroke.

See Also

Other Resources

Click Event
Events
Language Reference


KeyPress Event

Visual FoxPro 9.0 Language Reference
KeyPress Event
See Also

Occurs when the user presses and releases a key. You can use the KeyPress event for intercepting keystrokes entered in a control. You can also test keystrokes immediately for validity or format characters as they are typed. Use the KeyPreview property to create global keyboard-handling routines.

PROCEDURE Object.KeyPress
LPARAMETERS nKeyCode, nShiftAltCtrl

Parameters

nKeyCode

Contains a number that identifies the key pressed. For a list of codes for special keys and key combinations, see INKEY( ).
nShiftAltCtrl

Sets a particular bit if a modifier key is held down while pressing the key specified by nKeyCode. Valid modifier keys are the SHIFT, CTRL, and ALT keys. The following table lists the modifier key values for nShiftAltCtrl.

nShiftAltCtrl Modifier key

1

SHIFT

2

CTRL

4

ALT
This parameter is the sum of the bits with the least-significant bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. This parameter indicates the state of these keys. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys is pressed. For example, if both CTRL and ALT are pressed, the value of nShiftAltCtrl is 6.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | EditBox | Form | Grid | ListBox | OptionButton | Spinner | TextBox

The KeyPress event does not occur for any combination of keys with the ALT key.

The object with the focus receives the KeyPress event.

A form can receive the KeyPress event in three special cases:

  • The form contains no controls, or none of its controls is visible and enabled.

  • The form's KeyPreview property is set to True (.T.). The form first receives the KeyPress event, and then the control with focus receives the event.

  • The control on the form cannot process a keystroke, for example, when TAB is pressed to move the focus to the next control.

If the AllowCellSelection property for a grid is set to True (.T.), Visual FoxPro disregards the Grid KeyPress event and uses the event at the individual cell level.

See Also

Other Resources

INKEY( ) Function
KeyPreview Property
Events
Language Reference


Load Event

Visual FoxPro 9.0 Language Reference
Load Event
See Also

Occurs just before an object is created.

PROCEDURE Object.Load

Remarks

Applies To: Form | FormSet

The Load event occurs first for the form set and then for the contained forms. The Load event occurs before the Activate and GotFocus events.

To prevent a form from being created, return false (.F.) from the Load event; the Destroy event will not be executed.

See Also

Other Resources

Events
Activate Event
GotFocus Event
Unload Event


LoadReport Event

Visual FoxPro 9.0
LoadReport Event
See Also Example

Occurs previous to a report run, before output is initialized in the BeforeReport event. Provides access to report command clauses.

PROCEDURE Object.LoadReport

Parameters

None.

Remarks

Applies To: ReportListener Object.

LoadReport and UnloadReport are the two framing events of the report or label run; from the Report System's point of view, the report run has not yet started when it invokes LoadReport, and the report run has already ended when it invokes UnloadReport.

Consequently, these events allow you to perform certain setup and cleanup activities. For example, in LoadReport, you can change the contents of the report or label definition table (frx or lbx) because the Report Engine and ReportListener have not read the contents of the table at this point. The print job has not yet started, unless this REPORT FORM command continues the print job started in an earlier REPORT FORM command that used the NOPAGEEJECT keyword, so you can change the current printer setup.

Note:
For information about the order of events in a report run, see Understanding Visual FoxPro Object-Assisted Reporting.

If you write code in the LoadReport event that returns a value of False (.F.), the report run will not proceed. The print spool will not be opened, preview will not be instantiated, further Listener events will not be called, and so on. This behavior is similar to the Load event for forms and formsets; for forms, if Load returns .F., the form does not instantiate.

The clauses with which you invoked REPORT FORM or LABEL FORM are available for your use in LoadReport; however, certain values are not yet calculated at this point. For more information, see CommandClauses Property.

Example

In the following example class definition, the report definition file (frx) specified in the REPORT FORM command is "swapped" for a temporary file during the LoadReport event. It is replaced in its original position during the UnloadReport event.
Copy Code
DEFINE CLASS rlswap AS ReportListener

   ListenerType = 1  && to see the results, use a preview
   realFRX = ""
   useFRX = ""
   tempFRX = FORCEPATH(SYS(2015),SYS(2023))

   PROCEDURE LoadReport
      THIS.realFRX = THIS.CommandClauses.FILE
      THIS.useFRX = GETFILE("frx")
      IF EMPTY(THIS.useFRX)
         RETURN .F.
      ENDIF
      SET DATASESSION TO THIS.FRXDataSession
      SET SAFETY OFF  && it's scoped to session anyway
      THIS.ClearFRX(THIS.tempFRX)
      RENAME  (FORCEEXT(THIS.realFRX,"frx")) TO ;
               FORCEEXT(THIS.tempFRX,"frx")
      RENAME  (FORCEEXT(THIS.realFRX,"frt")) TO ;
               FORCEEXT(THIS.tempFRX,"frt")
      COPY FILE  (FORCEEXT(THIS.useFRX,"frx")) TO ;
               FORCEEXT(THIS.realFRX,"frx")
      COPY FILE  (FORCEEXT(THIS.useFRX,"frt")) TO ;
               FORCEEXT(THIS.realFRX,"frt")
   ENDPROC

   PROTECTED PROCEDURE clearFRX(tFRX)
      IF FILE(FORCEEXT(tFRX,"frx"))
         ERASE FORCEEXT(tFRX,"frx")) NORECYCLE
      ENDIF
      IF FILE(FORCEEXT(tFRX,"frt"))
         ERASE FORCEEXT(tFRX,"frt")) NORECYCLE
      ENDIF
   ENDPROC

   PROCEDURE UnloadReport
      SET DATASESSION TO THIS.FRXDataSession
      USE IN FRX
      THIS.clearFRX(THIS.realFRX)
      RENAME  (FORCEEXT(THIS.tempFRX,"frx")) TO ;
               FORCEEXT(THIS.realFRX,"frx")
      RENAME  (FORCEEXT(THIS.tempFRX,"frt")) TO ;
               FORCEEXT(THIS.realFRX,"frt")
   ENDPROC

ENDDEFINE

See Also

Reference

ReportListener Object
UnloadReport Event
REPORT FORM Command
LABEL Command

Other Resources

Events (Visual FoxPro)
Language Reference (Visual FoxPro)


LostFocus Event

Visual FoxPro 9.0 Language Reference
LostFocus Event
See Also

Occurs when an object loses the focus.

PROCEDURE Object.LostFocus

Remarks

Applies To: CheckBox | ComboBox | CommandButton | Container Object | Control Object | EditBox | Form | ListBox | OLE Bound Control | OLE Container Control | OptionButton | Spinner | TextBox

The timing of this event occurs depends on the type of object:

  • A control loses the focus by user action, such as tabbing to or clicking another control, or by changing the focus in code using the SetFocus method. A Grid loses the focus when a user presses CTRL+TAB in Microsoft Windows or CONTROL+TAB on the Macintosh to exit the Grid.

  • A form loses the focus when the form has no controls, all its controls have their Enabled and Visible properties set to false (.F.), or another form gets the focus.

For forms, the LostFocus event occurs before the Deactivate event.

See Also

Other Resources

Events
Deactivate Event
Enabled Property
GotFocus Event
Visible Property


MiddleClick Event

Visual FoxPro 9.0 Language Reference
MiddleClick Event
See Also

Occurs when the user clicks the middle mouse button on a three-button mouse over a control.

PROCEDURE Control.MiddleClick

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container | Control | EditBox | Form | Grid | Header | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

See Also

Other Resources

Events
Click Event
DblClick Event
DragDrop Event
DragOver Event
DropDown Event
Enabled Property
KeyPress Event
MouseDown Event
MouseMove Event
MouseUp Event
Scrolled Event
Undock Event


MouseDown Event

Visual FoxPro 9.0 Language Reference
MouseDown Event
See Also

Occurs when the user presses a mouse button.

PROCEDURE Object.MouseDown
LPARAMETERS nButton, nShift, nXCoord, nYCoord

Parameters

You must include an LPARAMETERS or PARAMETERS statement in the event procedure and specify a name for each parameter. Visual FoxPro passes the MouseDown event parameters in the following order:

nButton

Contains a number that specifies which button was pressed to trigger the event: 1 (left), 2 (right), or 4 (middle).
nShift

Contains a number specifying the state of modifier keys when the mouse is pressed. The valid modifier keys are the SHIFT, CTRL, and ALT keys. The values returned in nShift for individual modifier keys are listed in the following table. Modifier key values for nShift

Windows key Value

SHIFT

1

CTRL

2

ALT

4
If more than one modifier key is held down when the mouse is pressed, the nShift argument contains the sum of the values for the modifier keys. For example, if the user holds CTRL while pressing the mouse button, the nShift argument contains 2. But If the user holds CTRL+ALT while pressing the mouse button, the nShift argument contains 6.
nXCoord, nYCoord

Contains the current horizontal (nXCoord) and vertical (nYCoord) position of the mouse pointer within the form. These coordinates are expressed in terms of the form's coordinate system in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Header | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

Use a MouseDown procedure to specify actions to occur when a given mouse button is pressed. Unlike the Click and DblClick events, you can use the MouseDown event to distinguish between the left, right, and middle mouse buttons. You can also write code for mouse-keyboard combinations that use the modifier keys.

Tip:
You can use a MouseMove event to respond to an event caused by moving the mouse. The nButton argument for MouseDown and MouseUp differs from the nButton argument used for MouseMove. For MouseDown or MouseUp, the nButton argument indicates exactly one button per event; for MouseMove, it indicates the current state of all buttons.

See Also

Other Resources

Events
Click Event
DblClick Event
MiddleClick Event
MouseMove Event
MousePointer Property
MouseUp Event
MouseWheel Event


MouseEnter Event

Visual FoxPro 9.0 Language Reference
MouseEnter Event
See Also

Occurs when a mouse cursor moves into a control

PROCEDURE Object.MouseEnter
LPARAMETERS nButton, nShift, nXCoord, nYCoord

Parameters

nButton

Contains a number that specifies which button was pressed to trigger the event: 1 (left), 2 (right), or 4 (middle).
nShift

Contains a number specifying the state of modifier keys when the mouse is pressed. The valid modifier keys are the SHIFT, CTRL, and ALT keys. The values returned in nShift for individual modifier keys are listed in the following table. Modifier key values for nShift

Windows key Value

SHIFT

1

CTRL

2

ALT

4
If more than one modifier key is held down when the mouse is pressed, the nShift argument contains the sum of the values for the modifier keys. For example, if the user holds CTRL while pressing the mouse button, the nShift argument contains 2. But If the user holds CTRL+ALT while pressing the mouse button, the nShift argument contains 6.
nXCoord, nYCoord

Contains the current horizontal (nXCoord) and vertical (nYCoord) position of the mouse pointer within the form. These coordinates are expressed in terms of the form's coordinate system in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: CheckBox | OptionButton | OptionGroup | CommandButton | CommandGroup | ComboBox | ListBox | Grid | Header | Spinner | TextBox | EditBox | Label | Line | Container Object | Shape | Image | Page | PageFrame Control

You can use this and the MouseLeave event to create rollover and mouseover behaviors as in DHTML.

A control receives a MouseEnter event when the user moves the mouse into a control from a mouse position that was previously outside the control. In the case of overlapping or intersecting controls, the topmost control in the z-order receives the event.

A MouseEnter event is passed to objects on forms or toolbars. Forms and toolbars themselves do not receive this event.

See Also

Other Resources

Events
MouseLeave Event
Click Event
DblClick Event
MiddleClick Event
MouseMove Event
MousePointer Property
MouseUp Event
MouseWheel Event


MouseLeave Event

Visual FoxPro 9.0 Language Reference
MouseLeave Event
See Also

Occurs when a mouse cursor exits a control

PROCEDURE Object.MouseLeave
LPARAMETERS nButton, nShift, nXCoord, nYCoord

Parameters

nButton

Contains a number that specifies which button was pressed to trigger the event: 1 (left), 2 (right), or 4 (middle).
nShift

Contains a number specifying the state of modifier keys when the mouse is pressed. The valid modifier keys are the SHIFT, CTRL, and ALT keys. The values returned in nShift for individual modifier keys are listed in the following table. Modifier key values for nShift

Windows key Value

SHIFT

1

CTRL

2

ALT

4
If more than one modifier key is held down when the mouse is pressed, the nShift argument contains the sum of the values for the modifier keys. For example, if the user holds CTRL while pressing the mouse button, the nShift argument contains 2. But If the user holds CTRL+ALT while pressing the mouse button, the nShift argument contains 6.
nXCoord, nYCoord

Contains the current horizontal (nXCoord) and vertical (nYCoord) position of the mouse pointer within the form. These coordinates are expressed in terms of the form's coordinate system in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: CheckBox | OptionButton | OptionGroup | CommandButton | CommandGroup | ComboBox | ListBox | Grid | Header | Spinner | TextBox | EditBox | Label | Line | Container Object | Shape | Image | Page | PageFrame Control

You can use this and the MouseEnter event to create rollover and mouseover behaviors as in DHTML.

A control receives a MouseLeave event when the user moves the mouse out of the control from a mouse position that was previously inside the control. In the case of overlapping or intersecting controls, the topmost control in the z-order receives the event.

A MouseLeave event is passed to objects on forms or toolbars. Forms and toolbars themselves do not receive this event.

See Also

Other Resources

Events
MouseEnter Event
Click Event
DblClick Event
MiddleClick Event
MouseMove Event
MousePointer Property
MouseUp Event
MouseWheel Event


MouseMove Event

Visual FoxPro 9.0 Language Reference
MouseMove Event
See Also

Occurs when the user moves the mouse over an object.

PROCEDURE Object.MouseMove
LPARAMETERS nButton, nShift, nXCoord, nYCoord

Parameters

You must include an LPARAMETERS or PARAMETERS statement in the event procedure and specify a name for each parameter. Visual FoxPro passes the MouseMove event parameters in the following order:

nButton

Contains a number that specifies which mouse button was being held down as the mouse was moved, as listed in the following table: Mouse button values for nButton

Windows nButton Value

Left mouse button

1

Right mouse button

2

Middle mouse button

4
If more than one mouse button is held down as the mouse is moved, nButton contains the sum of the values for the mouse buttons. For example, if both the left and right mouse buttons are pressed, the value of nButton is 3.
nShift

Contains a number specifying the state of modifier keys when the mouse is moved. In Visual FoxPro for Windows, the valid modifier keys are the SHIFT, CTRL, and ALT keys. The values returned in nShift for individual modifier keys are listed in the following table. Modifier key values for nShift

Windows key Value

SHIFT

1

CTRL

2

ALT

4
If more than one modifier key is held down when the mouse is pressed, the nShift argument contains the sum of the values for the modifier keys. For example, in Visual FoxPro for Windows, if the user holds CTRL while pressing the mouse button, the nShift argument contains 2. But if the user holds CTRL+ALT while pressing the mouse button, the nShift argument contains 6.
nXCoord, nYCoord

Contains the current horizontal (nXCoord) and vertical (nYCoord) position of the mouse pointer within the form. These coordinates are always expressed in terms of the form's coordinate system, in the unit of measurement specified in the ScaleMode property setting.

The MouseMove event is triggered continually as the mouse pointer moves across objects.

Note:
You can use MouseDown and MouseUp events to respond to events caused by pressing and releasing mouse buttons. The nButton parameter for MouseMove differs from the nButton parameter for MouseDown and MouseUp. For MouseMove, the nButton parameter indicates the current state of all buttons; a single MouseMove event can indicate that some, all, or no buttons are pressed. For MouseDown or MouseUp, the nButton parameter indicates exactly one button per event. Avoid moving a window inside a MouseMove event procedure; it can cause cascading events and generate run-time errors, such as a stack overflow. MouseMove events are triggered when the window moves underneath the pointer. A MouseMove event can be triggered even if the mouse is stationary.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Header | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

See Also

Other Resources

Events
Click Event
DblClick Event
MiddleClick Event
MousePointer Property
MouseDown Event
MouseUp Event
MouseWheel Event


MouseUp Event

Visual FoxPro 9.0 Language Reference
MouseUp Event
See Also

Occurs when the user releases a mouse button.

PROCEDURE Object.MouseUp
LPARAMETERS nButton, nShift, nXCoord, nYCoord

Parameters

You must include an LPARAMETERS or PARAMETERS statement in the event procedure and specify a name for each parameter. Visual FoxPro passes the MouseUp event parameters in the following order.

nButton

In Visual FoxPro for Windows, contains a number that specifies which button was released to trigger the event: 1 (left), 2 (right), or 4 (middle).
nShift

Contains a number specifying the state of modifier keys when the mouse is released. In Visual FoxPro for Windows, the valid modifier keys are the SHIFT, CTRL, and ALT keys. The values returned in nShift for individual modifier keys are listed in the following table. Modifier key values for nShift

Windows key Value

SHIFT

1

CTRL

2

ALT

4
If more than one modifier key is held down when the mouse is released, the nShift argument contains the sum of the values for the modifier keys. For example, in Visual FoxPro for Windows, if the user holds CTRL while releasing the mouse button, the nShift argument contains 2. But if the user holds CTRL+ALT while releasing the mouse button, the nShift argument contains 6.
nXCoord, nYCoord

Contains the current horizontal (nXCoord) and vertical (nYCoord) position of the mouse pointer within the form. These coordinates are always expressed in terms of the form's coordinate system in the unit of measurement specified by the ScaleMode property of the form.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Header | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

Use a MouseUp procedure to specify actions to occur when a given mouse button is released. Unlike the Click and DblClick events, the MouseUp event makes it possible for you to distinguish between the left, right, and middle mouse buttons. You can also write code for mouse-keyboard combinations that use the modifier keys.

You can use a MouseMove procedure to respond to an event caused by moving the mouse.

Note:
The nButton argument for MouseDown and MouseUp differs from the nButton argument used for MouseMove. For MouseDown or MouseUp, the nButton argument indicates exactly one button per event; for MouseMove, it indicates the current state of all buttons.

See Also

Other Resources

Events
Click Event
DblClick Event
MiddleClick Event
MouseDown Event
MouseMove Event
MousePointer Property
MouseWheel Event
ScaleMode Property


MouseWheel Event

Visual FoxPro 9.0 Language Reference
MouseWheel Event
See Also

Occurs when the user rotates the mouse wheel on a mouse device that has a wheel.

PROCEDURE Object.MouseWheel
LPARAMETERS nDirection, nShift, nXCoord, nYCoord

Parameters

You must include an LPARAMETERS or PARAMETERS statement in the event procedure and specify a name for each parameter. Visual FoxPro passes the MouseWheel event parameters in the following order.

nDirection

Contains a mouse device dependent number that indicates the direction the mouse wheel is rotated. A negative value indicates the mouse wheel is rotated backwards; a positive value indicates the mouse wheel is rotated forwards.
nShift

Contains a number specifying the state of modifier keys when the mouse wheel is rotated. The valid modifier keys are the SHIFT, CTRL, and ALT keys. The values returned in nShift for individual modifier keys are listed in the following table.

Value Key

1

SHIFT

2

CTRL

4

ALT
If more than one modifier key is held down when the mouse wheel is rotated, the nShift argument contains the sum of the values for the modifier keys. For example, if the user holds CTRL while rotating the mouse wheel, the nShift argument contains 2. But if the user holds CTRL+ALT while rotating the mouse wheel, the nShift argument contains 6.
nXCoord, nYCoord

Contains the current horizontal (nXCoord) and vertical (nYCoord) position of the mouse pointer within the form. These coordinates are always expressed in terms of the form's coordinate system, in the unit of measurement specified in the ScaleMode property setting.

Remarks

Applies To: CheckBox | Column | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Header | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

See Also

Other Resources

Events
Click Event
MiddleClick Event
MousePointer Property
MouseDown Event
MouseUp Event


Moved Event

Visual FoxPro 9.0 Language Reference
Moved Event
See Also

Occurs when an object is moved to a new position or a container object's Top or Left property settings have been changed programmatically.

PROCEDURE Object.Moved

Remarks

Applies To: Column | Container Object | Control Object | Form | Grid | OLE Bound Control | OLE Container Control | PageFrame | ToolBar

Occurs when an object is moved to a new position or when the settings for the Top or Left properties have been changed in code.

See Also

Other Resources

Events
ColumnOrder Property
Left Property
Top Property


OLECompleteDrag Event

Visual FoxPro 9.0 Language Reference
OLECompleteDrag Event
See Also

Occurs when data is dropped on the drop target or the OLE drag-and-drop operation is canceled.

PROCEDURE Object.OLECompleteDrag
LPARAMETERS nEffect

Return Value

nEffect

A value passed from the OLEDragDrop event, corresponding to the action performed when data is dropped on the drop target. The following table lists the values for nEffect with a description of each action.

nEffect Foxpro.h constant Description

0

DROPEFFECT_NONE

Drop target did not accept the data or the drop operation was canceled.

1

DROPEFFECT_COPY

Data was copied from the drag source to the drop target.

2

DROPEFFECT_MOVE

Data was moved from the drag source to the drop target.

4

DROPEFFECT_LINK

Data was linked from the drag source to the drop target.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

OLECompleteDrag is a drag source event, and is the last event to occur during an OLE drag-and-drop operation. Including NODEFAULT prevents a text move from deleting the text.

This event allows the drag source to determine the action performed on the data on the drop target. The drop target can set nEffect in its OLEDragDrop event and the drag source can perform the appropriate action based on the value of nEffect. For example, if the data was moved to the drop target, the drag source should remove the data from itself.

See Also

Other Resources

Events
OLE Drag-and-Drop Overview
OLEDragDrop Event
OLEDropMode Property
NODEFAULT Command


OLEDragDrop Event

Visual FoxPro 9.0 Language Reference
OLEDragDrop Event
See Also

Occurs when data is dropped on a drop target and the drop target's OLEDropMode property is set to 1 – Enabled.

PROCEDURE Object.OLEDragDrop
LPARAMETERS oDataObject, nEffect, nButton,
  nShift,   nXCoord, nYCoord

Return Value

oDataObject

An object reference to OLE drag-and-drop DataObject, used with the GetData and GetFormat methods to return data and data formats in the DataObject.
nEffect

A value passed to the OLECompleteDrag event, indicating the action performed when data is dropped on the drop target. nEffect is initially a value that indicates the OLE drag-and-drop operations supported by the drag source. Within the OLEDragDrop event you can change the value of nEffect , which is passed to the OLECompleteDrag event. If you change the value of nEffect, be sure to include NODEFAULT in the event code to prevent the default behavior. The following table lists the values for nEffect that you can pass to the OLECompleteDrag event with a description of each action.

nEffect Foxpro.h constant Description

0

DROPEFFECT_NONE

Drop target did not accept the data or the drop operation was canceled.

1

DROPEFFECT_COPY

Data was copied from the drag source to the drop target.

2

DROPEFFECT_MOVE

Data was moved from the drag source to the drop target.

4

DROPEFFECT_LINK

Data was linked from the drag source to the drop target.
nButton

Contains a number that specifies which mouse button was released to drop the data on the target: 1 (left), 2 (right), or 4 (middle).
nShift

Contains a number specifying the state of modifier keys when the mouse was released to drop the data on the drop target. The valid modifier keys are the SHIFT, CTRL, and ALT keys. The values returned in nShift for individual modifier keys are listed in the following table.

nShift Modifier key

1

SHIFT

2

CTRL

4

ALT
If more than one modifier key is held down when the mouse is pressed, the nShift argument contains the sum of the values for the modifier keys. For example, if the user holds CTRL while releasing the mouse button, the nShift argument contains 2. But If the user holds CTRL+ALT while releasing the mouse button, the nShift argument contains 6.
nXCoord, nYCoord

Contains the horizontal (nXCoord) and vertical (nYCoord) position of the mouse pointer within the Form when the mouse button was released to drop the data on the drop target. These coordinates are expressed in terms of the Form's coordinate system in the unit of measurement specified by the ScaleMode property of the Form.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Shape | Spinner | TextBox | ToolBar

OLEDragDrop is a drop target event that only occurs when the OLEDropMode property for the control or object is set to 1 – Enabled. This event does not occur if the OLEDropMode property is set to 0 – Disabled or 2 – Pass to Container.

If you perform your own drop processing in the OleDragDrop event, include NODEFAULT to prevent the default drop from occuring. In this case, you must then set the resulting nEffect value.

See Also

Other Resources

Events
OLE Drag-and-drop Overview
OLECompleteDrag Event
OLEDropMode Property
NODEFAULT Command


OLEDragOver Event

Visual FoxPro 9.0 Language Reference
OLEDragOver Event
See Also

Occurs when data is dragged over a drop target and the drop target's OLEDropMode property is set to 1 – Enabled.

PROCEDURE Object.OLEDragOver
LPARAMETERS oDataObject, nEffect, nButton,
  nShift,   nXCoord, nYCoord, nState

Return Value

oDataObject

An object reference to OLE drag-and-drop DataObject, used with the GetData and GetFormat methods to return data and data formats in the DataObject.
nEffect

A value passed to the OLEGiveFeedback event, indicating the action performed if data is dropped on the drop target. nEffect is initially a value that indicates the OLE drag-and-drop operations supported by the drag source. The following table lists the values for nEffect with a description of each action.

nEffect Foxpro.h constant Description

0

DROPEFFECT_NONE

Drop target doesn't accept the data or the drop operation is canceled.

1

DROPEFFECT_COPY

Data is copied from the drag source to the drop target.

2

DROPEFFECT_MOVE

Data is moved from the drag source to the drop target.

4

DROPEFFECT_LINK

Data is linked from the drag source to the drop target.
nButton

Contains a number that specifies which mouse button is pressed when data is dragged over a drop target: 1 (left), 2 (right), or 4 (middle).
nShift

Contains a number specifying the state of modifier keys when data is dragged over a drop target. The valid modifier keys are the SHIFT, CTRL, and ALT keys. The values returned in nShift for individual modifier keys are listed in the following table.

nShift Modifier key

1

SHIFT

2

CTRL

4

ALT
If more than one modifier key is held down when the mouse is pressed, the nShift argument contains the sum of the values for the modifier keys. For example, if the user holds CTRL while releasing the mouse button, the nShift argument contains 2. But, if the user holds CTRL+ALT while releasing the mouse button, the nShift argument contains 6.
nXCoord, nYCoord

Contains the horizontal (nXCoord) and vertical (nYCoord) position of the mouse pointer within the Form when data is dragged over a drop target. These coordinates are expressed in terms of the Form's coordinate system in the unit of measurement specified by the ScaleMode property of the Form.
nState

Contains a number specifying the direction in which the data is dragged – into the control or object, within the control or object, or out of the control or object. The values for nState are listed in the following table.

nState Description

0

Data is dragged into the control or object. The OLEDropEffects and OLEDropHasData properties can be set when nState is zero.

1

Data is dragged out of the control or object.

2

Data is dragged within the control or object.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Shape | Spinner | TextBox | ToolBar

OLEDragOver is a drop target event that only occurs when the OLEDropMode property for the control or object is set to 1 – Enabled. This event does not occur if the OLEDropMode property is set to 0 – Disabled or 2 – Pass to Container.

Note that you should avoid creating wait states in the OLEDragOver event with commands and functions such as WAIT WINDOW and MESSAGEBOX( ).

See Also

Other Resources

Events
OLE Drag-and-Drop Overview
OLEGiveFeedBack Event
OLEDropEffects Property
OLEDropHasData Property
OLEDropMode Property


OLEGiveFeedback Event

Visual FoxPro 9.0 Language Reference
OLEGiveFeedback Event
See Also

Occurs after every OLEDragOver event. Allows the drag source to specify the type of OLE drag-and-drop operation and the visual feedback.

PROCEDURE Object.OLEGiveFeedback
LPARAMETERS nEffect, eMouseCursor

Return Value

nEffect

The action performed when data is dropped on the drop target. The value of nEffect is set by the drop target in its OLEDragOver event. The following table lists the values for nEffect with a description of each action.

nEffect Foxpro.h constant Description

0

DROPEFFECT_NONE

Drop target cannot accept the data.

1

DROPEFFECT_COPY

Drop results in a copy.

2

DROPEFFECT_MOVE

Drop results in a move.

4

DROPEFFECT_LINK

Drop results in a link.
eMouseCursor

Specifies the mouse pointer displayed during the OLE drag-and-drop operation. eMouseCursor can be a character or numeric value. eMouseCursor is an output parameter and is set to zero on entry into event. If eMouseCursor is a character value, it's assumed that the character value is the name of a graphics file of type .ani, .cur, or .ico. If eMouseCursor is a numeric value, the value specifies the mouse pointer displayed. The following table lists the numeric values for eMouseCursor with a description of each mouse pointer.

eMouseCursor Foxpro.h constant Description

0

MOUSE_DEFAULT

Shape determined by the object. (Default)

1

MOUSE_ARROW

Arrow.

2

MOUSE_CROSSHAIR

Cross. A cross-hair pointer.

3

MOUSE_IBEAM

I-Beam.

4

MOUSE_ICON_POINTER

Icon. A small white square within a black square.

5

MOUSE_SIZE_POINTER

Size. A four-pointed arrow pointing north, south, east, west.

6

MOUSE_SIZE_NE_SW

Size NE SW. A double arrow pointing northeast and southwest.

7

MOUSE_SIZE_N_S

Size NS. A double arrow pointing north and south.

8

MOUSE_SIZE_NW_SE

Size NW SE. A double arrow pointing northwest and southeast.

9

MOUSE_W_E

Size WE. A double arrow pointing west and east.

10

MOUSE_UP_ARROW

Up Arrow.

11

MOUSE_HOURGLASS

Hourglass.

12

MOUSE_NO_DROP

No Drop.

13

MOUSE_HIDE_POINTER

Hide Pointer.

14

MOUSE_ARROW2

Arrow.

15

MOUSE_ARROW_HOURGLASS

Arrow and hourglass.

16

MOUSE_ARROW_QUESTION

Arrow and question mark.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | ProjectHook Object | Shape | Spinner | TextBox | ToolBar

OLEGiveFeedback is a drag source event that lets you provide visual feedback to the user. You can change the mouse cursor to indicate the operation that occurs when the mouse is positioned over the drag source or the drop target. Including NODEFAULT has no effect on the behavior of this method.

Note that you should avoid creating wait states in the OLEGiveFeedback event with commands and functions such as WAIT WINDOW and MESSAGEBOX( ).

See Also

Other Resources

Events
OLE Drag-and-Drop Overview
OLEDragOver Event
NODEFAULT Command


OLESetData Event

Visual FoxPro 9.0 Language Reference
OLESetData Event
See Also

Occurs on a drag source when a drop target calls the GetData method.

PROCEDURE Object.OLESetData
LPARAMETERS oDataObject, eFormat

Return Value

oDataObject

An object reference to OLE drag-and-drop DataObject, used with the SetData method to place data in the DataObject.
eFormat

A numeric or character value that indicates the format of the data the GetData method requests. The drag source uses this value to determine the format of the data to place in the DataObject. See the GetData method for a table that lists the numeric or character values for each data format and a description of each format.

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

OLESetData is a drag source event. Including NODEFAULT has no effect on the behavior of this method.

The OLESetData event occurs when the GetData method is executed. Within the OLESetData event you can place data in the DataObject in the specified format with the SetData method. This technique is called "delay rendering" and allows you to put data on the DataObject only when it is requested.

See Also

Reference

OLESetData Event

Other Resources

Events
GetData Method
OLE Drag-and-Drop Overview
SetData Method
NODEFAULT Command


OLEStartDrag Event

Visual FoxPro 9.0 Language Reference
OLEStartDrag Event
See Also

Occurs when the OLEDrag method is called.

PROCEDURE Object.OLEStartDrag
LPARAMETERS oDataObject, nEffect

Return Value

oDataObject

An object reference to OLE drag-and-drop DataObject. You can call any of the DataObject methods from within the OLEStartDrag event.
nEffect

The OLE drag operations supported by the drag source. The following table lists the values for nEffect with a description of each action. nEffect is an output parameter and is set to three on entry into event, so you should provide the value for nEffect in this event. For example, to allow only copy operations, set nEffect to 1 (DROPEFFECT_COPY).

nEffect Foxpro.h constant Description

0

DROPEFFECT_NONE

Drag source did not support any drag operations.

1

DROPEFFECT_COPY

Drag source supports Copy operations.

2

DROPEFFECT_MOVE

Drag source supports Move operations (the default).

4

DROPEFFECT_LINK

Drag source supports link operations.
A drag source can support multiple drag operations by adding multiple values together for nEffect. For example, if nEffect is 3, the drag source supports both copy and move drag operations (3 = 1 (copy) + 2 (move)).

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Form | Grid | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

OLEStartDrag is a drag source event. Including NODEFAULT has no effect on the behavior of this method.

See Also

Other Resources

Events
OLE Drag-and-Drop Overview
OLEDrag Method
OLEDragMode Property
NODEFAULT Command


OnMoveItem Event

Visual FoxPro 9.0 Language Reference
OnMoveItem Event
See Also

Occurs when you select and move an item up or down in a list box using the mouse, keyboard, or programmatically with the MoveItem method.

PROCEDURE OnMoveItem
LPARAMETERS nSource, nShift, nCurrentIndex, nMoveBy

Parameters

nSource

Contains a number that specifies how the event is triggered.

nSource Description

0

Keyboard

1

Left mouse button

2

Right mouse button

4

Middle mouse button

8

Programmatically triggered by the MoveItem method
nShift

Contains a number that specifies which modifier keys, SHIFT, CTRL, and ALT, are also pressed when the mouse button is pressed. The following table lists the values returned by nShift for individual modifier keys.

nShift Description

1

SHIFT

2

CTRL

4

ALT
If more than one modifier key is held down when the mouse button is pressed, the nShift argument contains the sum of the values for the modifier keys. For example, if the user holds CTRL while pressing the mouse button, the nShift argument contains a value of 2. However, if the user holds down CTRL+ALT while pressing the mouse button, the nShift argument contains a value of 6.
nCurrentIndex

Contains the current index of the item being moved.
nMoveBy

Indicates how many positions the item is being moved. A positive value indicates downward movement. A negative number indicates upward movement. The nMoveBy parameter always has a value of 1 or -1 if the user is moving a list item using the keyboard. It usually has a value of 1 or -1 if the user is moving a list item using the mouse. However, nMoveBy indicates the position to which the item is moved if the user drags the mouse outside the bounds of the list box and then back to a remote position.

Remarks

Applies To: ListBox Control

OnMoveItem occurs after selecting and moving an item by pressing CTRL+UP ARROW, CTRL+DOWN ARROW or by using the mouse, or when calling the MoveItem method programmatically. OnMoveItem occurs after every subsequent move but before the list box displays the item movement. However, OnMoveItem occurs only once when calling the MoveItem method programmatically.

Note:
You can move ListBox control items only if the list box's RecordSourceType property is set to 0 (None) or 1 (Value).

To prevent movement from occurring, return False (.F.) from the code in the OnMoveItem event.

See Also

Other Resources

Events
MoveItem Method
RecordSourceType Property
MoverBars Property


Paint Event

Visual FoxPro 9.0 Language Reference
Paint Event
See Also

Occurs when a form or toolbar is repainted.

PROCEDURE Object.Paint

Remarks

Applies To: Form | ToolBar

A form or toolbar is repainted when part or all of the form or toolbar is exposed after it has been moved or sized, or after a window that was covering the form or toolbar has been moved.

Using a Refresh method in a Resize event forces repainting of the entire object every time a user resizes the form or toolbar.

The Paint event can be called frequently; therefore avoid performing data manipulation or calling commands or functions that set up a modal state.

Using a Paint event for certain tasks can cause a cascading event. In general, avoid using a Paint event for the following:

  • Moving or sizing a form or control.

  • Changing any variables that affect size or appearance, such as setting an object's BackColor property.

  • Calling the Refresh method.

    Note:
    A Resize event may be more appropriate for some of these tasks.

See Also

Other Resources

Properties
Circle Method
ClipControls Property
Line Method
Print Method
PSet Method
Refresh Method
Resize Event


ProgrammaticChange Event

Visual FoxPro 9.0 Language Reference
ProgrammaticChange Event
See Also

Occurs when the value of a control is changed in code.

PROCEDURE Control.ProgrammaticChange

Remarks

Applies To: CheckBox | ComboBox | CommandGroup | EditBox | ListBox | OptionGroup | Spinner | TextBox

Setting Selected or SelectedID properties on a Listbox control fires the Programmatic Change event after setting ListItem or ListItemID properties.

See Also

Other Resources

Events
InteractiveChange Event
Value Property


QueryAddFile Event

Visual FoxPro 9.0 Language Reference
QueryAddFile Event
See Also

Occurs just before a file is added to a project.

PROCEDURE Object.QueryAddFile
LPARAMETERS cFileName

Parameters

cFileName

Contains the name of the file to add to the project. cFileName is passed to the QueryAddFile event after the Add method is executed, you choose Add in the Project Manager, or you choose Add File from the Project menu.

Remarks

Applies To: ProjectHook Object

Include NODEFAULT in the QueryAddFile event to prevent a file from being added to the project.

See Also

Other Resources

Events
Add Method
QueryModifyFile Event
QueryRemoveFile Event
QueryRunFile Event
QueryNewFile Event
NODEFAULT Command


QueryModifyFile Event

Visual FoxPro 9.0 Language Reference
QueryModifyFile Event
See Also

Occurs just before a file is modified in a project.

PROCEDURE Object.QueryModifyFile
LPARAMETERS oFile, cClassName

Parameters

oFile

Contains an object reference to the file to modify. oFile is passed to the QueryModifyFile event after the Modify method is executed, you choose Modify in the Project Manager, or you choose Modify File from the Project menu.
cClassName

Contains the name of the class to modify if the file is a .vcx visual class library.

Remarks

Applies To: ProjectHook Object

Include NODEFAULT in the QueryModifyFile event to prevent a file from being modified in the project.

See Also

Other Resources

Events
Modify Method
QueryAddFile Event
QueryRemoveFile Event
QueryRunFile Event
QueryNewFile Event
NODEFAULT Command


QueryNewFile Event

Visual FoxPro 9.0 Language Reference
QueryNewFile Event
See Also Example

Occurs when the New button is pressed in the Project Manager, just before a file is added to a project.

PROCEDURE Object.QueryNewFile
LPARAMETERS cFileType

Parameters

cFileType

Specifies the file type selected in Project Manager when the New button was pressed. These values are the same as the File object Type property. QueryNewFile event is also supported on database container items, a special case, by the following cFileType values.

Value FoxPro.H Constant File type Extension

d

FILETYPE_DATABASE

Database

.dbc

D

FILETYPE_FREETABLE

Free table

.dbf

Q

FILETYPE_QUERY

Query

.qpr

K

FILETYPE_FORM

Form

.scx

R

FILETYPE_REPORT

Report

.frx

B

FILETYPE_LABEL

Label

.lbx

V

FILETYPE_CLASSLIB

Visual class Library

.vcx

P

FILETYPE_PROGRAM

Program

.prg

M

FILETYPE_MENU

Menu

.mnx

T

FILETYPE_TEXT

Text file

varies
The following table describes cFileType values for items specific to the DBC container. Except for the DBC table, which adds a table to the project, these items affect only the DBC.

Value DBC Type Extension

p

Stored Procedure

t

DBC table

.dbf

c

Connection

r

Remote View

l

Local View

Remarks

Addition of Visual FoxPro libraries (.FLL files) and applications (.APP files) do not call the QueryNewFile event.

Since this event does not directly add files to the project, if you wish to add other files when QueryNewFile is called, you should do this explicitly with your own code, using the Project Objects File Collection Add. For example, you could do this if you wanted the QueryNewFile event to call a Wizard, which you created, when adding a new file of a specific type.

Example

Copy Code
     _VFP.ActiveProject.Files.Add(mynewfile)

See Also

Other Resources

Events
File Object
Type Property
Project Object
QueryAddFile Event
QueryModifyFile Event
QueryRemoveFile Event
QueryRunFile Event


QueryRemoveFile Event

Visual FoxPro 9.0 Language Reference
QueryRemoveFile Event
See Also

Occurs just before a file is removed from a project.

PROCEDURE Object.QueryRemoveFile
LPARAMETERS oFile, cClassName, lDeleteFile

Parameters

oFile

Contains an object reference to the file to remove from the project. oFile is passed to the QueryRemoveFile event after the Remove method is executed, you choose Remove in the Project Manager, or you choose Remove File from the Project menu.
cClassName

Contains the name of the class to remove if the file is a .vcx visual class library.
lDeleteFile

Contains a logical value that indicates if the file is to be deleted from disk as well as the project. lDeleteFile contains false (.F.) if Remove (remove from project) is chosen in the dialog that is displayed when you attempt to remove a file from a project. lDeleteFile contains true (.T.) if Delete (remove from project and delete from disk) is chosen in the dialog.

Remarks

Applies To: ProjectHook Object

Include NODEFAULT in the QueryRemoveFile event to prevent a file from being removed from the project.

See Also

Other Resources

Events
QueryAddFile Event
QueryModifyFile Event
QueryRunFile Event
QueryNewFile Event
Remove Method (File Object)
NODEFAULT Command


QueryRunFile Event

Visual FoxPro 9.0 Language Reference
QueryRunFile Event
See Also

Occurs just before a file is executed or a report or label is previewed in a project.

PROCEDURE Object.QueryRunFile
LPARAMETERS oFile

Parameters

oFile

Contains an object reference to the file to execute or preview. oFile is passed to the QueryRunFile event after the Run method is executed, you choose Run or Preview in the Project Manager, or you choose Run File or Preview File from the Project menu.

Remarks

Applies To: ProjectHook Object

Include NODEFAULT in the QueryRunFile event to prevent a file from being executed or previewed.

See Also

Other Resources

Events
QueryAddFile Event
QueryModifyFile Event
QueryRemoveFile Event
QueryNewFile Event
Run Method
NODEFAULT Command


QueryUnload Event

Visual FoxPro 9.0 Language Reference
QueryUnload Event
See Also

Occurs before a form is unloaded.

PROCEDURE Form.QueryUnload

Remarks

Applies To: Form

The QueryUnload event occurs before the Destroy event. The ReleaseType property is set prior to the QueryUnload event being called.

The QueryUnload event occurs when CLEAR WINDOWS, RELEASE WINDOWS, or QUIT is executed in code, or when the user double-clicks the window pop-up menu icon or chooses Close from the window pop-up menu on a form.

Note:
The QueryUnload event does not occur if you issue the RELEASE command on the form in code or invoke the form's Release method.

Issuing NODEFAULT in the QueryUnload event procedure prevents the form from unloading.

See Also

Other Resources

Events
CLEAR Command
ControlBox Property
DEFINE CLASS Command
Destroy Event
QUIT Command
RELEASE Command
Release Method
RELEASE WINDOWS Command
ReleaseType Property
Unload Event
Closable Property
NODEFAULT Command


RangeHigh Event

Visual FoxPro 9.0 Language Reference
RangeHigh Event
See Also

For a spinner or text box, occurs when the control loses the focus. For a combo box or list box, occurs when the control receives the focus.

PROCEDURE Object.RangeHigh

Remarks

Applies To: ComboBox | ListBox | Spinner | TextBox

A RangeHigh event can return a numeric value to Microsoft Visual FoxPro through a RETURN statement. For a spinner or a text box with a numeric value, if the value returned to Visual FoxPro is less than the value entered in the control, the control retains the focus. For a combo box or list box, the value returned to Visual FoxPro specifies which item in the control is initially selected, For example, if 2 is returned to Visual FoxPro, the second item in the control is initially selected.

See Also

Other Resources

Events
KeyboardHighValue, KeyboardLowValue Properties
RangeLow Event
RETURN Command
SpinnerHighValue, SpinnerLowValue Properties


RangeLow Event

Visual FoxPro 9.0 Language Reference
RangeLow Event
See Also

For a spinner or text box, occurs when the control loses the focus. For a combo box or list box, occurs when the control receives the focus.

PROCEDURE Object.RangeLow

Remarks

Applies To: ComboBox | ListBox | Spinner | TextBox

A RangeLow event can return a numeric value to Visual FoxPro through a RETURN statement. For a spinner or a text box with a numeric value, if the value returned to Visual FoxPro is greater than the value entered in the control, the control retains the focus. For a combo box or list box, the value returned to Visual FoxPro specifies which item in the control is initially selected, For example, if 2 is returned to Visual FoxPro, the second item in the control is initially selected.

See Also

Other Resources

Events
KeyboardHighValue, KeyboardLowValue Properties
RangeHigh Event
RETURN Command
SpinnerHighValue, SpinnerLowValue Properties


Resize Event

Visual FoxPro 9.0 Language Reference
Resize Event
See Also

Occurs when an object is resized.

PROCEDURE Object.Resize

Remarks

Applies To: _SCREEN System Variable | Column | Container Object | Control Object | Form | Grid | OLE Bound Control | OLE Container Control | PageFrame | ToolBar

You can trigger the Resize interactively or in code by setting the Height and Width properties.

For a Column object, you can trigger Resize in code by setting the Width property for the column.

You can also trigger the Resize event by using event binding. For more information, see Event Binding for Visual FoxPro Objects and BINDEVENT( ) Function.

See Also

Other Resources

Events
Height Property
Paint Event
Width Property
BINDEVENT( ) Function


RightClick Event

Visual FoxPro 9.0 Language Reference
RightClick Event
See Also

Occurs when the user clicks the right (secondary) mouse button over a control in Microsoft Windows.

PROCEDURE Control.RightClick

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container | Control | EditBox | Form | Grid | Header | Image | Label | Line | ListBox | OptionButton | OptionGroup | Page | PageFrame | Shape | Spinner | TextBox | ToolBar

See Also

Other Resources

Events
Click Event
DblClick Event
DragDrop Event
DragOver Event
DropDown Event
Enabled Property
KeyPress Event
MouseDown Event
MouseMove Event
MouseUp Event
Scrolled Event
Undock Event


SCCDestroy Event

Visual FoxPro 9.0 Language Reference
SCCDestroy Event
See Also

Occurs immediately before a ProjectHook object's Destroy event.

PROCEDURE ProjectHook.SCCDestroy

Remarks

Applies To: ProjectHook Object

The SCCDestroy event occurs immediately before a ProjectHook object's Destroy event, allowing you to perform source code control functions (checking in files, for example) before a Project is closed.

See Also

Reference

Destroy Event
SCCInit Event
SCCProvider Property
SCCStatus Property

Other Resources

Events


SCCInit Event

Visual FoxPro 9.0 Language Reference
SCCInit Event
See Also

Occurs immediately after a ProjectHook object's Init event.

PROCEDURE ProjectHook.SCCInit

Remarks

Applies To: ProjectHook Object

The SCCInit event occurs immediately after a ProjectHook object's Init event, allowing you to perform source code control functions (checking out files, for example) after a Project is opened.

See Also

Reference

Init Event
SCCDestroy Event
SCCProvider Property
SCCStatus Property

Other Resources

Events


Scrolled Event

Visual FoxPro 9.0 Language Reference
Scrolled Event
See Also

Occurs in a Grid control or Form object when moving horizontal or vertical scroll bars or moving a scroll box. The Scrolled event also occurs for a grid if you call the DoScroll method from within a program. The Scrolled event does not occur when pressing keyboard arrow keys.

PROCEDURE Object.Scrolled
LPARAMETERS nDirection

Parameters

nDirection

Specifies how the user scrolled through the contents of a Grid control or a form. The following table describes the possible values for nDirection.

Value User scrolled using...

0

Up arrow on vertical scroll bar.

1

Down arrow on vertical scroll bar.

2

Vertical scroll bar in area above the scroll box.

3

Vertical scroll bar in area below the scroll box

4

Left arrow on horizontal scroll bar.

5

Right arrow on horizontal scroll bar.

6

Horizontal scroll bar in area to the left of the scroll box.

7

Horizontal scroll bar in area to the right of the scroll box.

Remarks

Applies To: Form | Grid

The Scrollbars property determines whether a form has scroll bars.

Screen painting problems can occur when the grid or form is scrolled. Therefore, avoid creating wait states, for example, using the WAIT WINDOW command, within the Scrolled event.

See Also

Other Resources

Events
ActiveColumn Property
ActiveRow Property
DoScroll Method
RelativeColumn Property
RelativeRow Property
ScrollBars Property


Timer Event

Visual FoxPro 9.0 Language Reference
Timer Event
See Also

Occurs when the number of milliseconds specified in the Interval property has elapsed.

PROCEDURE Timer.Timer

Remarks

Applies To: Timer

See Also

Other Resources

Interval Property
Reset Method
Events
Language Reference


UIEnable Event

Visual FoxPro 9.0 Language Reference
UIEnable Event
See Also

Occurs for all objects contained within a page whenever the page is activated or deactivated.

PROCEDURE Object.UIEnable
LPARAMETERS lEnable

Parameters

lEnable

Contains a logical value that specifies whether the page that the object is contained within is being activated or deactivated. If lEnable is true (.T.), the page that the object is contained within is being activated (becoming the active page). If lEnable is false (.F.), the page is being deactivated (becoming the inactive page).

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | Container Object | Control Object | EditBox | Grid | Image | Label | Line | ListBox | OLE Bound Control | OLE Container Control | OptionGroup | PageFrame | Shape | Spinner | TextBox

Use the UIEnable event to specify any action you want to occur for an object or control when the page that it is contained within is activated or deactivated.

The UIEnable event does not occur for pages when the form is initially activated. The UIEnable event occurs only when a page is programmatically or interactively activated or deactivated.

See Also

Other Resources

Activate Event
Deactivate Event
Events
Language Reference


UnDock Event

Visual FoxPro 9.0 Language Reference
UnDock Event
See Also

Occurs when a ToolBar or Form object is dragged from its docked position.

PROCEDURE Object.Undock

Remarks

Applies To: Form Object | ToolBar Object

See Also

Other Resources

AfterDock Event
BeforeDock Event
Dock Method
Events
Language Reference


Unload Event

Visual FoxPro 9.0 Language Reference
Unload Event
See Also

Occurs when an object is released.

Unload is the last event to occur before a form set or form is released.

PROCEDURE Object.Unload

Remarks

Applies To: Form | FormSet

Unload occurs after the Destroy event and after all the contained objects have been released. In addition, Unload occurs depending on the type of object:

  • Form objects are released in code when the object variable that refers to the form is released or when its form set is released.

  • Form set objects are released in code when the object variable that refers to the form set is released.

If a container object, such as a form set, contains objects, the Unload event for the container object occurs after the Unload events for the objects it contains. For example, a form set containing one form that contains one control (a CommandButton) is released in this order:

  1. FormSet Destroy event

  2. Form Destroy event

  3. CommandButton Destroy event

  4. Form Unload event

  5. FormSet Unload event

To return a value to the TO VarName clause in the DO FORM command, use the RETURN command in the Unload event. For more information, see DO FORM Command.

See Also

Other Resources

Destroy Event
QueryUnload Event
Destroy Event
DO FORM Command
RETURN Command
Events
Language Reference


UnloadReport Event

Visual FoxPro 9.0
UnloadReport Event
See Also

Occurs at the conclusion of a report run after output has been finalized in the AfterReport event.

PROCEDURE Object.UnloadReport

Parameters

None.

Remarks

Applies To: ReportListener Object.

LoadReport and UnloadReport are the two framing events of the report or label run; from the Report System's point of view, the report run has not yet started when it invokes LoadReport, and the report run has already ended when it invokes UnloadReport. For more information and an example of use, see LoadReport Event.

See Also

Reference

ReportListener Object
REPORT FORM Command
LABEL Command

Other Resources

Events (Visual FoxPro)
Language Reference (Visual FoxPro)


UpClick Event

Visual FoxPro 9.0 Language Reference
UpClick Event
See Also

Occurs when the user clicks the up arrow of a Spinner control or in the drop-down list of a ComboBox control.

PROCEDURE Control.UpClick

Remarks

Applies To: ComboBox | Spinner

See Also

Other Resources

DownClick Event
Events
Language Reference


Valid Event

Visual FoxPro 9.0 Language Reference
Valid Event
See Also

Occurs before a control loses the focus.

PROCEDURE Control.Valid

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | EditBox | Grid | ListBox | OptionButton | OptionGroup | Spinner | TextBox

If the Valid event returns true (.T.), the control can lose focus - focus might not pass to another control. If the Valid event returns false (.F.), the control does not lose focus.

The Valid event can also return a numeric value. Returning a numeric value has one of three effects:

  • If 0 is returned, the control does not lose focus.

  • If a positive value is returned, the value specifies the number of controls the focus advances.

  • If a negative value is returned, the value specifies the number of controls the focus moves back. For example, if the Valid event returns –1, the previous control gets the focus.

You can also use the optional ObjectName parameter in the RETURN command of the Valid event to direct where focus is assigned. The object specified must be a valid Visual FoxPro object. If the specified object is disabled or cannot receive focus, then focus is assigned to the next object in the tab order. If an invalid object is specified, Visual FoxPro keeps the focus at the current object.

You can set focus to objects in the following scenarios:

  • Set focus to an object on another visible form.

  • Set focus to an object on a non-visible Page or Pageframe control.

For more information, see the RETURN command.

See Also

Other Resources

LostFocus Event
When Event
Events
Language Reference


When Event

Visual FoxPro 9.0 Language Reference
When Event
See Also

Occurs before a control receives the focus.

PROCEDURE Control.When

Remarks

Applies To: CheckBox | ComboBox | CommandButton | CommandGroup | EditBox | Grid | ListBox | OptionButton | OptionGroup | Spinner | TextBox

If the When event returns true (.T.), the default control receives the focus. If the When event returns false (.F.), the control does not receive the focus. The order of events when a control gains the focus is:

  1. When event

  2. GotFocus event

For ListBox controls, the When event occurs each time a user moves the focus between items in the list by clicking on items or by moving the selection with the arrow keys.

Note:
The Grid control does not have a GotFocus event, so only When fires.

For all other controls, the When event occurs when an attempt is made to move the focus to the control.

See Also

Other Resources

GotFocus Event
Valid Event
Events
Language Reference


Functions

Visual FoxPro 9.0 Language Reference
Functions
See Also

Visual FoxPro contains functions in the following categories as well as additional functions.

Character Functions

Lists functions that operate on character data.
Data Conversion Functions

Lists functions that convert data from one data type to another.
Date and Time Functions

Lists functions that generate and manipulate date and time data.
COM Functions

Lists the commands and functions that make it possible for you to access COM objects and servers.
Numeric Functions

Lists functions that operate on or return numeric data.
XML Functions

Describes functions that make it possible for data manipulations between Visual FoxPro and Extensible Markup Language (XML) data.
Supported Visual FoxPro Commands and Functions in OLE DB Provider

Lists commands and functions you can use in the OLE DB Provider.
Unsupported Visual FoxPro Commands and Functions in OLE DB Provider

Lists commands and functions not supported in the OLE DB Provider.

For information about backward compatible-only language reference, see Backward-Compatible Language Elements.

ABS( ) Function

ACLASS( ) Function

ACOPY( ) Function

ACOS( ) Function

ADATABASES( ) Function

ADBOBJECTS( ) Function

ADDBS( ) Function

ADDPROPERTY( ) Function

ADEL( ) Function

ADIR( ) Function

ADLLS( ) Function

ADOCKSTATE( ) Function

AELEMENT( ) Function

AERROR( ) Function

AEVENTS() Function

AFIELDS( ) Function

AFONT( ) Function

AGETCLASS( ) Function

AGETFILEVERSION( ) Function

AINS( ) Function

AINSTANCE( ) Function

ALANGUAGE( ) Function

ALEN( ) Function

ALIAS( ) Function

ALINES( ) Function

ALLTRIM( ) Function

AMEMBERS( ) Function

AMOUSEOBJ( ) Function

ANETRESOURCES( ) Function

APRINTERS( ) Function

APROCINFO( ) Function

ASC( ) Function

ASCAN( ) Function

ASELOBJ( ) Function

ASESSIONS( ) Function

ASIN( ) Function

ASORT( ) Function

ASQLHANDLES( ) Function

ASTACKINFO( ) Function

ASUBSCRIPT( ) Function

AT( ) Function

AT_C( ) Function

ATAGINFO( ) Function

ATAN( ) Function

ATC( ) Function

ATCC( ) Function

ATCLINE( ) Function

ATLINE( ) Function

ATN2( ) Function

AUSED( ) Function

AVCXCLASSES( ) Function

BAR( ) Function

BARCOUNT( ) Function

BARPROMPT( ) Function

BETWEEN( ) Function

BINDEVENT() Function

BINTOC( ) Function

BITAND( ) Function

BITCLEAR( ) Function

BITLSHIFT( ) Function

BITNOT( ) Function

BITOR( ) Function

BITRSHIFT( ) Function

BITSET( ) Function

BITTEST( ) Function

BITXOR( ) Function

BOF( ) Function

CANDIDATE( ) Function

CAPSLOCK( ) Function

CAST( ) Function

CDOW( ) Function

CDX( ) Function

CEILING( ) Function

CHR( ) Function

CHRSAW( ) Function

CHRTRAN( ) Function

CHRTRANC( ) Function

CLEARRESULTSET( ) Function

CMONTH( ) Function

CNTBAR( ) Function

CNTPAD( ) Function

COL( ) Function

COM Functions

COMARRAY( ) Function

COMCLASSINFO( ) Function

COMPOBJ( ) Function

COMPROP( ) Function

COMRETURNERROR( ) Function

COS( ) Function

CPCONVERT( ) Function

CPCURRENT( ) Function

CPDBF( ) Function

CREATEBINARY( ) Function

CREATEOBJECT( ) Function

CREATEOBJECTEX( ) Function

CREATEOFFLINE( ) Function

CTOBIN( ) Function

CTOD( ) Function

CTOT( ) Function

CURDIR( ) Function

CURSORGETPROP( ) Function

CURSORSETPROP( ) Function

CURSORTOXML( ) Function

CURVAL( ) Function

DATE( ) Function

DATETIME( ) Function

DAY( ) Function

DBC( ) Function

DBF( ) Function

DBGETPROP( ) Function

DBSETPROP( ) Function

DBUSED( ) Function

DDE Functions

DDEAbortTrans( ) Function

DDEAdvise( ) Function

DDEEnabled( ) Function

DDEExecute( ) Function

DDEInitiate( ) Function

DDELastError( ) Function

DDEPoke( ) Function

DDERequest( ) Function

DDESetOption( ) Function

DDESetService( ) Function

DDESetTopic( ) Function

DDETerminate( ) Function

DEFAULTEXT( ) Function

DELETED( ) Function

DESCENDING( ) Function

DIFFERENCE( ) Function

DIRECTORY( ) Function

DISKSPACE( ) Function

DisplayPath( ) Function

DMY( ) Function

DODEFAULT( ) Function

DOW( ) Function

DRIVETYPE( ) Function

DROPOFFLINE( ) Function

DTOC( ) Function

DTOR( ) Function

DTOS( ) Function

DTOT( ) Function

EDITSOURCE( ) Function

EMPTY( ) Function

EOF( ) Function

ERROR( ) Function

EVALUATE( ) Function

EVENTHANDLER( ) Function

EVL( ) Function

EXECSCRIPT( ) Function

EXP( ) Function

FCHSIZE( ) Function

FCLOSE( ) Function

FCOUNT( ) Function

FCREATE( ) Function

FDATE( ) Function

FEOF( ) Function

FERROR( ) Function

FFLUSH( ) Function

FGETS( ) Function

FIELD( ) Function

FILE( ) Function

FILETOSTR( ) Function

FILTER( ) Function

FKLABEL( ) Function

FKMAX( ) Function

FLDLIST( ) Function

FLOCK( ) Function

FLOOR( ) Function

FONTMETRIC( ) Function

FOPEN( ) Function

FOR( ) Function

FORCEEXT( ) Function

FORCEPATH( ) Function

FOUND( ) Function

FPUTS( ) Function

FREAD( ) Function

FSEEK( ) Function

FSIZE( ) Function

FTIME( ) Function

FULLPATH( ) Function

FUNCTION Command

FV( ) Function

FWRITE( ) Function

GETAUTOINCVALUE( ) Function

GETBAR( ) Function

GETCOLOR( ) Function

GETCP( ) Function

GETDIR( ) Function

GETENV( ) Function

GETFILE( ) Function

GETFLDSTATE( ) Function

GETFONT( ) Function

GETINTERFACE( ) Function

GETNEXTMODIFIED( ) Function

GETOBJECT( ) Function

GETPAD( ) Function

GETPEM( ) Function

GETPICT( ) Function

GETPRINTER( ) Function

GETRESULTSET( ) Function

GETWORDCOUNT( ) Function

GETWORDNUM( ) Function

GETCURSORADAPTER( ) Function

GOMONTH( ) Function

HEADER( ) Function

HOME( ) Function

HOUR( ) Function

ICASE( ) Function

IDXCOLLATE( ) Function

IIF( ) Function

IMESTATUS( ) Function

INDBC( ) Function

INDEXSEEK( ) Function

INKEY( ) Function

INLIST( ) Function

InputBox( ) Function

INSMODE( ) Function

INT( ) Function

ISALPHA( ) Function

ISBLANK( ) Function

ISCOLOR( ) Function

ISDIGIT( ) Function

ISEXCLUSIVE( ) Function

ISFLOCKED( ) Function

ISLEADBYTE( ) Function

ISLOWER( ) Function

ISMEMOFETCHED( ) Function

ISMOUSE( ) Function

ISNULL( ) Function

ISPEN( ) Function

ISREADONLY( ) Function

ISRLOCKED( ) Function

ISTRANSACTABLE( ) Function

ISUPPER( ) Function

JUSTDRIVE( ) Function

JUSTEXT( ) Function

JUSTFNAME( ) Function

JUSTPATH( ) Function

JUSTSTEM( ) Function

KEY( ) Function

KEYMATCH( ) Function

LASTKEY( ) Function

LEFT( ) Function

LEFTC( ) Function

LEN( ) Function

LENC( ) Function

LIKE( ) Function

LIKEC( ) Function

LINENO( ) Function

LOADPICTURE( ) Function

LOCFILE( ) Function

LOCK( ) Function

LOG( ) Function

LOG10( ) Function

LOOKUP( ) Function

LOWER( ) Function

LTRIM( ) Function

LUPDATE( ) Function

MAKETRANSACTABLE( ) Function

MAX( ) Function

MCOL( ) Function

MDOWN( ) Function

MDX( ) Function

MDY( ) Function

MEMLINES( ) Function

MEMORY( ) Function

MENU( ) Function

MESSAGE( ) Function

MESSAGEBOX( ) Function

MIN( ) Function

MINUTE( ) Function

MLINE( ) Function

MOD( ) Function

MONTH( ) Function

MRKBAR( ) Function

MRKPAD( ) Function

MROW( ) Function

MTON( ) Function

MWINDOW( ) Function

NDX( ) Function

NEWOBJECT( ) Function

NORMALIZE( ) Function

NTOM( ) Function

NUMLOCK( ) Function

NVL( ) Function

OBJNUM( ) Function

OBJTOCLIENT( ) Function

OBJVAR( ) Function

OCCURS( ) Function

OEMTOANSI( ) Function

OLDVAL( ) Function

ON( ) Function

ORDER( ) Function

OS( ) Function

PAD( ) Function

PADL( ) | PADR( ) | PADC( ) Functions

PARAMETERS( ) Function

PAYMENT( ) Function

PCOL( ) Function

PCOUNT( ) Function

PEMSTATUS( ) Function

PI( ) Function

POPUP( ) Function

PRIMARY( ) Function

PRINTSTATUS( ) Function

PRMBAR( ) Function

PRMPAD( ) Function

PROGRAM( ) Function

PROMPT( ) Function

PROPER( ) Function

PROW( ) Function

PRTINFO( ) Function

PUTFILE( ) Function

PV( ) Function

Quarter( ) Function

RAISEEVENT() Function

RAND( ) Function

RAT( ) Function

RATC( ) Function

RATLINE( ) Function

RDLEVEL( ) Function

READKEY( ) Function

RECCOUNT( ) Function

RECNO( ) Function

RECSIZE( ) Function

REFRESH( ) Function

RELATION( ) Function

REPLICATE( ) Function

REQUERY( ) Function

RGB( ) Function

RGBSCHEME( ) Function

RIGHT( ) Function

RIGHTC( ) Function

RLOCK( ) Function

ROUND( ) Function

ROW( ) Function

RTOD( ) Function

RTRIM( ) Function

SAVEPICTURE( ) Function

SCHEME( ) Function

SCOLS( ) Function

SEC( ) Function

SECONDS( ) Function

SEEK( ) Function

SELECT( ) Function

SET( ) Function

SETFLDSTATE( ) Function

SETRESULTSET( ) Function

SIGN( ) Function

SIN( ) Function

SKPBAR( ) Function

SKPPAD( ) Function

SOUNDEX( ) Function

SPACE( ) Function

SQLCANCEL( ) Function

SQLCOLUMNS( ) Function

SQLCOMMIT( ) Function

SQLCONNECT( ) Function

SQLDISCONNECT( ) Function

SQLEXEC( ) Function

SQLGETPROP( ) Function

SQLIDLEDISCONNECT( ) Function

SQLMORERESULTS( ) Function

SQLPREPARE( ) Function

SQLROLLBACK( ) Function

SQLSETPROP( ) Function

SQLSTRINGCONNECT( ) Function

SQLTABLES( ) Function

SQRT( ) Function

SROWS( ) Function

STR( ) Function

STRCONV( ) Function

STREXTRACT( ) Function

STRTOFILE( ) Function

STRTRAN( ) Function

STUFF( ) Function

STUFFC( ) Function

SUBSTR( ) Function

SUBSTRC( ) Function

SYS( ) Functions Overview

SYSMETRIC( ) Function

TABLEREVERT( ) Function

TABLEUPDATE( ) Function

TAG( ) Function

TAGCOUNT( ) Function

TAGNO( ) Function

TAN( ) Function

TARGET( ) Function

TEXTMERGE( ) Function

TIME( ) Function

TRANSFORM( ) Function

TRIM( ) Function

TTOC( ) Function

TTOD( ) Function

TXNLEVEL( ) Function

TXTWIDTH( ) Function

TYPE( ) Function

UNBINDEVENTS() Function

UNIQUE( ) Function

UPDATED( ) Function

UPPER( ) Function

USED( ) Function

VAL( ) Function

VARREAD( ) Function

VARTYPE( ) Function

VERSION( ) Function

WBORDER( ) Function

WCHILD( ) Function

WCOLS( ) Function

WDOCKABLE( ) Function

WEEK( ) Function

WEXIST( ) Function

WFONT( ) Function

WLAST( ) Function

WLCOL( ) Function

WLROW( ) Function

WMAXIMUM( ) Function

WMINIMUM( ) Function

WONTOP( ) Function

WOUTPUT( ) Function

WPARENT( ) Function

WREAD( ) Function

WROWS( ) Function

WTITLE( ) Function

WVISIBLE( ) Function

XMLTOCURSOR( ) Function

XMLUPDATEGRAM( ) Function

YEAR( ) Function

See Also

Other Resources

Language Reference


Character Functions

Visual FoxPro 9.0 Language Reference
Character Functions
See Also

These functions operate on character data.

Functions

$ Operator

ALLTRIM( ) Function

ASC( ) Function

AT( ) Function

AT_C( ) Function

ATC( ) Function

ATCC( ) Function

ATCLINE( ) Function

ATLINE( ) Function

BETWEEN( ) Function

CHR( ) Function

CHRTRAN( ) Function

CHRTRANC( ) Function

CPCONVERT( ) Function

CTOD( ) Function

DIFFERENCE( ) Function

DTOC( ) Function

EMPTY( ) Function

EVALUATE( ) Function

GETWORDCOUNT( ) Function

GETWORDNUM( ) Function

INLIST( ) Function

ISALPHA( ) Function

ISDIGIT( ) Function

ISLEADBYTE( ) Function

ISLOWER( ) Function

ISUPPER( ) Function

LEFT( ) Function

LEFTC( ) Function

LEN( ) Function

LENC( ) Function

LIKE( ) Function

LIKEC( ) Function

LOWER( ) Function

LTRIM( ) Function

MAX( ) Function

MIN( ) Function

NORMALIZE( ) Function

OCCURS( ) Function

PADL( ) | PADR( ) | PADC( ) Functions

PROPER( ) Function

RAT( ) Function

RATC( ) Function

RATLINE( ) Function

REPLICATE( ) Function

RIGHT( ) Function

RIGHTC( ) Function

RTRIM( ) Function

SOUNDEX( ) Function

SPACE( ) Function

STR( ) Function

STRCONV( ) Function

STRTOFILE( ) Function

STRTRAN( ) Function

STUFF( ) Function

STUFFC( ) Function

SUBSTR( ) Function

SUBSTRC( ) Function

SYS(10) - String from Julian Day Number

SYS(15) - Character Translation

SYS(2007) - Checksum Value

TEXTMERGE( ) Function

TRANSFORM( ) Function

TRIM( ) Function

TXTWIDTH( ) Function

TYPE( ) Function

UPPER( ) Function

VARTYPE( ) Function

See Also

Other Resources

Functions
Language Reference
Language Categories


Data Conversion Functions

Visual FoxPro 9.0 Language Reference
Data Conversion Functions
See Also

These functions convert data from one data type to another.

Functions

CAST( ) Function

CHR( ) Function

CTOD( ) Function

CURVAL( ) Function

CURSORToXML( ) Function

DTOC( )

MTON( ) Function

NTOM( ) Function

NVL( ) Function

STR( )

SYS(10) - String from Julian Day Number

SYS(15) - Character Translation

TEXTMERGE( ) Function

TRANSFORM( ) Function

TTOC( ) Function

TTOD( ) Function

VAL( ) Function

VARTYPE( ) Function

See Also

Other Resources

Functions
Language Reference
Language Categories


Date and Time Functions

Visual FoxPro 9.0 Language Reference
Date and Time Functions
See Also

These functions generate and manipulate date and time data.

Functions

BETWEEN( ) Function

CDOW( ) Function

CMONTH( ) Function

CTOD( ) Function

CTOT( ) Function

DATE( ) Function

DATETIME( ) Function

DAY( ) Function

DMY( ) Function

DOW( ) Function

DTOC( ) Function

DTOS( ) Function

DTOT( ) Function

EMPTY( ) Function

FDATE( ) Function

FTIME( ) Function

GOMONTH( ) Function

HOUR( ) Function

INLIST( ) Function

MAX( ) Function

MDY( ) Function

MIN( ) Function

MINUTE( ) Function

MONTH( ) Function

QUARTER( ) Function

SEC( ) Function

SECONDS( ) Function

SET HOURS Command

SET MARK TO Command

SET SECONDS Command

SYS(1) - Julian System Date

SYS(2) - Seconds Since Midnight

SYS(10) - String from Julian Day Number

SYS(11) - Julian Day Number

TIME( ) Function

TTOC( ) Function

TTOD( ) Function

WEEK( ) Function

YEAR( ) Function

See Also

Other Resources

Functions
Language Reference
Language Categories


COM Functions

Visual FoxPro 9.0 Language Reference
COM Functions
See Also

These functions make it possible for you to access COM objects and servers.

Functions

COMCLASSINFO( ) Function

COMARRAY( ) Function

COMRETURNERROR( ) Function

COMPROP( ) Function

CREATEOBJECT( ) Function

CREATEOBJECTEX( ) Function

GETOBJECT( ) Function

DEFINE CLASS Command

GETINTERFACE( ) Function

EVENTHANDLER( ) Function

See Also

Other Resources

Functions
Language Reference
Language Categories


Numeric Functions

Visual FoxPro 9.0 Language Reference
Numeric Functions
See Also

These functions operate on or return numeric data.

Functions

% Operator

ABS( ) Function

ACOS( ) Function

ASIN( ) Function

ATAN( ) Function

ATN2( ) Function

BETWEEN( ) Function

BITAND( ) Function

BITCLEAR( ) Function

BITLSHIFT( ) Function

BITNOT( ) Function

BITOR( ) Function

BITRSHIFT( ) Function

BITSET( ) Function

BITTEST( ) Function

BITXOR( ) Function

CALCULATE Command

CEILING( ) Function

COS( ) Function

DTOR( ) Function

EMPTY( ) Function

EXP( ) Function

FLOOR( ) Function

FV( ) Function

INLIST( ) Function

INT( ) Function

LOG( ) Function

LOG10( ) Function

MAX( ) Function

MIN( ) Function

MOD( ) Function

PAYMENT( ) Function

PI( ) Function

PV( ) Function

RAND( ) Function

ROUND( ) Function

RTOD( ) Function

SET DECIMALS Command

SIGN( ) Function

SIN( ) Function

SQRT( ) Function

TAN( ) Function

VAL( ) Function

See Also

Other Resources

Functions
Language Reference
Language Categories


XML Functions

Visual FoxPro 9.0 Language Reference
XML Functions
See Also

The following functions perform data exchange through XML formatting.

Functions

XMLUPDATEGRAM( ) Function

CURSORTOXML( ) Function

XMLTOCURSOR( ) Function

See Also

Other Resources

Functions
Converting Between XML and Visual FoxPro Data
Language Reference
Language Categories


$ Operator

Visual FoxPro 9.0 Language Reference
$ Operator
See Also Example

Returns True (.T.) if a character expression is contained in another character expression; otherwise, returns False (.F.).

cSearchFor $ cSearchIn

Parameters

cSearchFor

Specifies the expression looked for within cSearchIn.
cSearchIn

Specifies the expression that is searched to see if it contains cSearchFor. If cSearchFor is found in cSearchIn, $ returns True (.T.); otherwise, it returns False (.F.). cSearchFor and cSearchIn can be character-type variables or array elements, character-type fields, character string literals, or memo fields of any length. Memo fields can be manipulated like character expressions, fields in tables, variables, or array elements. For example, if MEMO_FLD is a memo field, the following is acceptable:
Copy Code
LIST FOR 'FOX' $ UPPER(memo_fld)

Return Value

Logical

Remarks

If the character expression is not found, False (.F.) is returned. The $ operator is case-sensitive and is not Rushmore optimizable.

Example

The following example creates a table called memotest containing one memo field. Three records are appended to the table. LIST is used to display the three records. The dollar sign ($) is used to list the records that contain the string "FOX". The files created for the example are then deleted.
Copy Code
CLOSE DATABASES
CLEAR
CREATE TABLE memotest (Text C(3), Memo M)
INSERT INTO  memotest (Text, Memo) VALUES ('Fox', 'Fox')
INSERT INTO  memotest (Text, Memo) VALUES ('Cat', 'Cat')
INSERT INTO  memotest (Text, Memo) VALUES ('FOX', 'FOX')
LIST FIELDS  Memo, Text FOR 'FOX' $ UPPER(Memo)
USE
DELETE FILE memotest.dbf
DELETE FILE memotest.fpt

See Also

Other Resources

% Operator
DELETE FILE Command
CREATE TABLE – SQL Command
Using Rushmore Query Optimization to Speed Data Access
AT( ) Function
ATLINE( ) Function
RAT( ) Function
RATLINE( ) Function
OCCURS( ) Function
INLIST( ) Function
Operators


% Operator (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
% Operator (Visual FoxPro)
See Also Example

Returns the remainder (modulus) obtained by dividing one numeric expression into another.

nDividend % nDivisor

Parameters

nDividend

Specifies the dividend (numeric expression being divided). The number of decimal places in nDividend determines the number of decimal places in the result.
nDivisor

Specifies the divisor (the numeric expression dividing the dividend nDividend). A positive number is returned if nDivisor is positive; a negative number if nDivisor is negative. nDivisor cannot be zero.

Remarks

The modulus operator (%) and MOD( ) return identical results.

The modulus operator (%) is an arithmetic operator. Other arithmetic operators are: + (addition), - (subtraction), * (multiplication), / (division), and ^ (exponentiation). When these operators are combined in a numeric expression, % has the same precedence as * and /.

For a further discussion of operators and their order of precedence, see the Operators topic.

Example

Copy Code
? 36 % 10         && Displays 6
? (4*9) % (90/9)      && Displays 6
? 25.250 % 5.0      && Displays 0.250
? IIF(YEAR(DATE( )) % 4 = 0, 'Summer Olympics this year';
   , 'No Summer Olympics this year')

See Also

Other Resources

MOD( ) Function
$ Operator
Numeric Operators
Creating Numeric Expressions
Operators
Language Reference


:: Scope Resolution Operator

Visual FoxPro 9.0 Language Reference
:: Scope Resolution Operator
See Also Example

Runs a parent class method from within a subclass method.

cClassName::cMethod

Remarks

The :: operator is used to execute a parent class method from within a subclass method. When you create a subclass, the subclass methods are automatically inherited from the parent class. The :: operator makes it possible for you to execute the parent class method in the subclass method and then perform additional processing for the subclass method. The subclass definitions in the example demonstrate how the :: operator is used to execute the parent class method within a subclass method.

For additional information about the :: scope resolution operator, see Object-Oriented Programming.

Example

The following example creates a form and adds two command buttons to the form. By clicking either button, you can exit the form – the second button, cmdAnotherButton, calls the Click procedure from cmdQuit. This action is possible because of subclassing. The scope resolution operator calls the parent class code for the subclassed object.

Copy Code
frmMyForm = CREATEOBJECT("Form")
frmMyForm.Width  = 450
frmMyForm.Height   = 100
frmMyForm.Caption  = "Scope Resolution Example"
frmMyForm.AutoCenter =.T.
frmMyForm.AddObject("cmdQuit","cmdQuitButton")
frmMyForm.AddObject("cmdAnother","cmdAnotherButton")
frmMyForm.SHOW       && Display the form
READ EVENTS        && Start event processing

The following example defines two command buttons. The first button will be used to subclass the second button. The subclassing can be seen by the FontBold and ForeColor properties which are defined for cmdQuit, but never explicitly set for the cmdAnotherButton. We are defining cmdAnotherButton to be a subclass of the cmdQuitButton. As a result, this button will pick up all the attributes defined above for cmdQuitButton.

Copy Code
DEFINE CLASS cmdQuitButton AS CommandButton
  Caption  = "\<Quit"   && Caption on command button
  Left   = 175    && Left edge of button
  Top    = 60     && Position for top of button
  Height   = 25     && Button height
  Visible  = .T.    && Show button on form
  FontItalic = .T.    && Turn on italic text
  ForeColor  = RGB(0,0,255) && Change button text color

  PROCEDURE Click
  WAIT WINDOW "Executing the CLICK procedure for cmdQuit." TIMEOUT 1
  CLEAR EVENTS     && Stop event processing
ENDDEFINE
DEFINE CLASS cmdAnotherButton AS cmdQuitButton

  Caption = "Click to quit"
  Left  = 175
  Top   = 30
  Height  = 25

  PROCEDURE Click
  WAIT WINDOW "Click event for button: cmdAnotherButton" TIMEOUT 1
  cmdQuitButton::Click
ENDDEFINE

See Also

Other Resources

ADD CLASS Command
CREATE CLASS Command
CREATE CLASSLIB Command
CREATEOBJECT( ) Function
DEFINE CLASS Command
DODEFAULT( ) Function
GETOBJECT( ) Function
MODIFY CLASS Command
RELEASE CLASSLIB Command
SET CLASSLIB Command
WITH ... ENDWITH Command
Operators
Language Reference


ABS( ) Function

Visual FoxPro 9.0 Language Reference
ABS( ) Function
See Also Example

Returns the absolute value of the specified numeric expression.

ABS(nExpression)

Parameters

nExpression

Specifies the numeric expression whose absolute value ABS( ) returns.

Return Value

Numeric

Example

Copy Code
? ABS(-45)       && Displays 45
? ABS(10-30)     && Displays 20
? ABS(30-10)     && Displays 20
STORE 40 TO gnNumber1
STORE 2 TO gnNumber2
? ABS(gnNumber2-gnNumber1)     && Displays 38

See Also

Other Resources

INT( ) Function
ROUND( ) Function
SIGN( ) Function
Functions
Language Reference


ACLASS( ) Function

Visual FoxPro 9.0 Language Reference
ACLASS( ) Function
See Also Example

Places an object's class name and its ancestor class names into a variable array.

ACLASS(ArrayName, oExpression)

Parameters

ArrayName

Specifies the name of the array into which the class names are placed. If you specify the name of an array that doesn't exist, Microsoft Visual FoxPro automatically creates the array. If you specify the name of an existing array that isn't large enough to hold all the parent names, Visual FoxPro automatically increases the size of the array. If the array is larger than necessary, the array size is truncated. If you specify the name of an existing two-dimensional array, the array is redimensioned to a one-dimensional array.
oExpression

Specifies an object whose class name and ancestor class names are placed into the array. oExpression can be any object expression, such as an object reference, an object variable, or an object array element.

Return Value

Numeric

Remarks

ACLASS( ) creates a one-dimensional array containing the class name of the specified object and its ancestor class names. The first array element contains the class name of the object, the second element contains the name of the object's parent class, the third element contains the name of the object's grandparent class, and so on.

ACLASS( ) returns the number of class names in the array. ACLASS( ) returns 0 if the array cannot be created.

Example

The following example creates two custom classes named FormChild and FormGrandChild from the Visual FoxPro Form base class. ACLASS( ) is used to create an array named gaNewarray containing the class names, which are then displayed.
Copy Code
CLEAR
frmMyForm = CREATEOBJECT("FormGrandChild")
FOR nCount = 1 TO ACLASS(gaNewarray, frmMyForm)    && Creates an array
   ? gaNewarray(nCount)  && Displays the names of the classes
ENDFOR
RELEASE frmMyForm

DEFINE CLASS FormChild AS FORM
ENDDEFINE

DEFINE CLASS FormGrandChild AS FormChild
ENDDEFINE

See Also

Other Resources

ADD CLASS Command
AMEMBERS( ) Function
CREATE CLASS Command
CREATE CLASSLIB Command
CREATEOBJECT( ) Function
DEFINE CLASS Command
Functions
Language Reference


ACOPY( ) Function

Visual FoxPro 9.0 Language Reference
ACOPY( ) Function
See Also Example

Copies elements from one array to another array.

ACOPY(SourceArrayName, DestinationArrayName
[, nFirstSourceElement [, nNumberElements [, nFirstDestElement ]]])

Parameters

SourceArrayName, DestinationArrayName

Specifies the source array SourceArrayName from which elements are copied one-to-one to the destination array DestinationArrayName. The elements in the source array replace the elements in the destination array. The arrays can be one- or two-dimensional. If the destination array doesn't exist, Visual FoxPro automatically creates it. In such a case, the size of the destination array will be the same as that of the source array.
Note:
You can refer to an element in a two-dimensional variable array in two ways: The first uses two subscripts to specify the row and column position of the element in the array; the other uses a single-element number. This function and others that manipulate two-dimensional arrays require single-element numbers (here, nFirstSourceElement and nFirstDestElement). Use AELEMENT( ) to return the proper element number for a two-dimensional array from its row and column subscripts.

nFirstSourceElement

Specifies the first element number in the source array to be copied; inclusive (element number nFirstSourceElement is included in the copying). If nFirstSourceElement isn't included, copying begins with the first element in the source array.
nNumberElements

Specifies the number of elements copied from the source array. If nNumberElements is –1, all elements of the source array beginning with element nFirstSourceElement are copied.
nFirstDestElement

Specifies the first element in the destination array to be replaced.

Return Value

Numeric. ACOPY( ) returns the number of elements copied to the destination array.

Remarks

Copying a member array to an existing non-member array with certain dimensions using the ACOPY( ) function might generate the error, "Subscript is outside defined range." You can avoid this error changing the dimension of the destination array to a single element before calling ACOPY( ). For more information, see DIMENSION Command.

Example

The following example creates an array from selected records in the customer table and then uses ACOPY( ) to create a new array.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer     && Open customer table

SELECT DISTINCT company ;
   FROM customer ;
   ORDER BY company ;
   WHERE country = 'Germany';
   INTO ARRAY gaCompanies
= ACOPY(gaCompanies, gaCompaniesTemp)  && Make a copy of the array
CLEAR
DISPLAY MEMORY LIKE gaCompaniesTemp

See Also

Other Resources

ADEL( ) Function
AELEMENT( ) Function
AINS( ) Function
ASCAN( ) Function
ASORT( ) Function
Functions
Language Reference


ACOS( ) Function

Visual FoxPro 9.0 Language Reference
ACOS( ) Function
See Also Example

Returns the arc cosine of a specified numeric expression.

ACOS(nExpression)

Parameters

nExpression

Specifies a numeric expression whose arc cosine ACOS( ) returns. The value of nExpression can range from –1 through +1. The value returned by ACOS( ) ranges from 0 through pi (3.141592). The number of decimal places ACOS( ) returns is determined by SET DECIMALS. Use RTOD( ) to convert radians to degrees.

Return Value

Numeric

Remarks

The arc cosine is returned in radians.

Example

Copy Code
CLEAR
? RTOD(ACOS(0))  && Displays 90.00
STORE -1 to gnArcAngle
? RTOD(ACOS(gnArcAngle))  && Displays 180.00
? RTOD(ACOS(SQRT(2)/2))  && Displays 45.00

See Also

Reference

ACOS( ) Function

Other Resources

ASIN( ) Function
ATAN( ) Function
ATN2( ) Function
DTOR( ) Function
RTOD( ) Function
SET DECIMALS Command
SIN( ) Function
TAN( ) Function
Functions
Language Reference


ADATABASES( ) Function

Visual FoxPro 9.0 Language Reference
ADATABASES( ) Function
See Also Example

Places the names of all open databases and their paths into a variable array.

ADATABASES(ArrayName)

Parameters

ArrayName

Specifies the name of the array. If the array you specify doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain all the database information, Visual FoxPro automatically increases the size of the array to accommodate the information. If the array is larger than necessary, Visual FoxPro truncates the array. If the array exists and ADATABASES( ) returns 0 because no databases are open, an existing array remains unchanged. If the array doesn't exist, and ADATABASES( ) returns 0, the array is not created.

Return Value

Numeric

Remarks

The names of all open databases are placed into a variable array.

ADATABASES( ) creates a two-dimensional array. The first column of the array contains the names of the open databases, and the second column contains the paths to the databases.

ADATABASES( ) returns the number of database names (rows) in the array. If no databases are open, ADATABASES( ) returns 0 and the array isn't created.

Example

The following example opens the testdata database, and then uses ADATABASES( ) to create an array named gaDatabase containing the names of all open databases.
Copy Code
SET PATH TO (HOME(2) + 'data\')     && Sets path to database
OPEN DATABASE testdata && Opens the database
CLEAR
? ADATABASES(gaDatabase)     && Creates an array of open databases
DISPLAY MEMORY LIKE gadatabase  && Displays the contents of the array
CLOSE DATABASES

See Also

Other Resources

CREATE DATABASE Command
DISPLAY DATABASE Command
LIST DATABASE Command
MODIFY DATABASE Command
OPEN DATABASE Command
Functions
Language Reference


ADBOBJECTS( ) Function

Visual FoxPro 9.0 Language Reference
ADBOBJECTS( ) Function
See Also Example

Places the names of named connections, relations, tables, or SQL views in the current database into a variable array.

ADBOBJECTS(ArrayName, cSetting)

Parameters

ArrayName

Specifies the name of the array in which the names are placed. If the array you specify doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain all the names, Visual FoxPro automatically increases the size of the array to accommodate the names. If the array is larger than necessary, Visual FoxPro truncates the array. If the array exists and ADBOBJECTS( ) returns 0 because no names are found, the array remains unchanged. If the array doesn't exist, and ADBOBJECTS( ) returns 0, the array is not created. A one-dimensional array is created when you specify CONNECTION, TABLE, or VIEW for cSetting. Each row in the one-dimensional array contains the name of a connection, table, or view in the database. A two-dimensional array is created when you specify RELATION for cSetting. Each row in the two-dimensional array corresponds to a relationship in the database. The first column in an array row contains the name of the child table and the second column in an array row contains the name of the parent table. The third column contains the name of the index tag for the child table and the fourth column contains the name of the index tag for the parent table. The fifth column in an array row contains referential integrity information. This column is empty if the relation has no referential integrity rules. If the relationship does have referential integrity rules, the column contains characters corresponding to the type of referential integrity rules for updates, deletions, and insertions. The first character indicates the type of update rule, the second character indicates the type of deletion rule, and the third character indicates the type of insertion rule. Possible values for updates and deletions are "C" for cascade, "R" for restrict, and "I" for ignore. Possible values for insertions are "R" for restrict, and "I" for ignore. For example, if a relation has cascaded updates, restricted deletions, and ignores insertion referential integrity rules, the column contains "CRI".
cSetting

Specifies the names to place in the variable array. The following table lists the values for cSetting and the corresponding names placed in the array:

cSetting Names

CONNECTION

Connection names

RELATION

Table relationships

TABLE

Table names

VIEW

View names
The CONNECTION, RELATION, TABLE, and VIEW settings cannot be abbreviated.

Return Value

Numeric

Remarks

A database must be open and current when ADBOBJECTS( ) is issued; otherwise Visual FoxPro generates an error message.

Example

The following example opens the testdata database and uses ADBOBJECTS( ) to create an array named gaTables containing names of tables in the database. The tables names are then displayed.
Copy Code
* Close any open databases
CLOSE DATABASES

* Clear desktop to prepare for displaying the array
CLEAR

* Open sample testdata database
OPEN DATABASE (HOME(2) + 'Data\testdata')

* Function call with cSetting for table names
=ADBOBJECTS(gaTables, "TABLE")

* Displays array gaTables created by ADBOBJECTS( ) function
DISPLAY MEMORY LIKE gaTables

See Also

Other Resources

ADATABASES( ) Function
CREATE Command
CREATE CONNECTION Command
CREATE DATABASE Command
CREATE SQL VIEW Command
CREATE TABLE - SQL Command
DISPLAY DATABASE Command
INDBC( ) Function
LIST DATABASE Command
MODIFY DATABASE Command
SET DATABASE Command
Functions
Language Reference


ADDBS( ) Function

Visual FoxPro 9.0 Language Reference
ADDBS( ) Function
See Also Example

Adds a backslash (if needed) to a path expression.

ADDBS(cPath)

Parameters

cPath

Specifies the path name to which to add the backslash.

Return Value

Character

Example

The following code displays a directory path and demonstrates that the ADDBS( ) function adds a backslash if one does not exist, but does not duplicate if one does exist.
Copy Code
*-- Both print C:\Windows\
? ADDBS( "C:\Windows" )
? ADDBS( "C:\Windows\" )

See Also

Other Resources

DEFAULTEXT( ) Function
FILE( ) Function
FORCEEXT( ) Function
FORCEPATH( ) Function
JUSTDRIVE( ) Function
JUSTEXT( ) Function
JUSTFNAME( ) Function
JUSTPATH( ) Function
JUSTSTEM( ) Function
Functions
Language Reference


ADDPROPERTY( ) Function

Visual FoxPro 9.0 Language Reference
ADDPROPERTY( ) Function
See Also

Adds a new property to an object at run time.

You can use ADDPROPERTY( ) to add properties and their values to valid Visual FoxPro objects, including those created from Visual FoxPro classes, COM classes, and the SCATTER...NAME command.

ADDPROPERTY(oObjectName, cPropertyName, [, eNewValue ])

Parameters

oObjectName

Specifies the name of the object to which the property is added. If oObjectName is not a valid object, Visual FoxPro generates the appropriate message.
cPropertyName

Specifies the name of the new property to add to the object. If the property with the name you specify does not exist, the property is created and added.
eNewValue

Specifies the value to set for the new property. If you omit eNewValue, and the property exists, Visual FoxPro leaves the value of the property unchanged. If you omit eNewValue, and the property is new, Visual FoxPro sets the value of the new property to False (.F.).

Return Value

Logical data type. The following table describes the return values for ADDPROPERTY( ) and the behavior when you attempt to add a property that already exists for an object.

Return value Description

True (.T.)

When ADDPROPERTY( ) adds the property successfully.

When the new property is an array property, and the array already exists, ADDPROPERTY( ) redimensions the array with the dimensions specified by cPropertyName. If you specify a value with eNewValue, all elements in the array are set to that value. If you omit eNewValue, all array elements are set to False (.F.).

If the new property is not an array property, but the existing property is an array property. The property remains an array property with the same dimensions. If you specify a value with eNewValue, all elements in the array are set to that value. If you omit eNewValue, all array elements are set to False (.F.).

If the new property is not an array property, and the existing property is not an array property or is not a read-only Visual FoxPro native property. If you specify a value with eNewValue, the existing property is set to that value. If you omit eNewValue, the existing property value remains unchanged.

If the specified property is already a member of the object but is marked as Hidden or Protected. Visual FoxPro generates an error, "Property name is not found (Error 1734)", and the property is not set to the value passed to ADDPROPERTY( ).

False (.F.)

When ADDPROPERTY( ) did not add the property successfully.

If the property is an array property, and the existing property is not an array property. The existing property remains unchanged.

Remarks

You can create property arrays using ADDPROPERTY( ) for an object. When you do so, every element in the array is initialized with eNewValue, if provided. Otherwise, the value of each property in the array is set to False (.F.). For more information about creating a property array for an object, see the Examples section.

Visual FoxPro adds the new property as a Public property. You cannot specify the property as Protected or Hidden.

If the existing property is a read-only Visual FoxPro native property, such as the BaseClass property, Visual FoxPro generates an error, "Property name is read-only (Error 1743)".

If the property name is not valid, for example, the property name contains a space or other illegal characters, Visual FoxPro generates an error, "Incorrect property name (Error 1470)".

For object instances derived from native Visual FoxPro classes, ADDPROPERTY( ) respects the visibility setting of the intrinsic AddProperty method. If AddProperty is marked as Hidden or Protected, ADDPROPERTY( ) does not create the new property and returns False (.F.). If the AddProperty method is marked as Public (default), ADDPROPERTY( ) creates the property and returns True (.T.). This protects the original class design.

Note:
This does not apply to COM objects created with Visual FoxPro OLEPUBLIC classes.

ADDPROPERTY( ) does not work when using the FOR EACH command with object references. However, you can use the AddProperty method instead.

Examples

Example 1

The following example adds a new property to an object created with the SCATTER command.

Copy Code
USE customers
SCATTER NAME oCust
ADDPROPERTY(oCust,"MyProperty")

Example 2

The following example creates a property array for the object, oMyForm, and displays its contents, 1 and "Two".

Copy Code
oMyForm = CREATEOBJECT('Form')
ADDPROPERTY(oMyForm, 'MyArray(2)', 1)
oMyForm.MyArray(2) = "Two"
CLEAR
? oMyForm.MyArray(1)
? oMyForm.MyArray(2)

See Also

Other Resources

Functions
AddProperty Method
SCATTER Command
REMOVEPROPERTY( ) Function


ADEL( ) Function

Visual FoxPro 9.0 Language Reference
ADEL( ) Function
See Also Example

Deletes an element from a one-dimensional array, or a row or column from a two-dimensional array.

ADEL(ArrayName, nElementNumber [, 2])

Parameters

ArrayName

Specifies the array from which the element, row, or column is deleted.
nElementNumber

Specifies the number of the element, row, or column to delete from the array. If the array is multidimensional, nElementNumber will specify the row. You must include the optional 2 argument to delete a column from the array.
Tip:
For more information on how to reference elements in an array, see DIMENSION.

2

Deletes a column from the array.

Return Value

Numeric

Remarks

Deleting an element or row from an array doesn't change the size of the array; instead, the trailing elements, rows, or columns are moved towards the start of the array, and the last element, row, or column in the array is set to False (.F.). If you delete a column, values of the elements in the deleted column are set to False (.F.), but trailing elements are not moved.

If the element, row, or column is successfully deleted, 1 is returned.

Example

The following example creates and fills an array, then searches for a particular company name, which, if found, is removed from the array.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer     && Open customer table
SELECT company FROM customer ;
   WHERE country = 'UK' ;
   INTO ARRAY gaCompanies
gnCount = _TALLY
gcName = 'Seven Seas Imports'
CLEAR
DISPLAY MEMORY LIKE gaCompanies
gnPos = ASCAN(gaCompanies, gcName)   && Search for company
IF gnPos != 0
   * Company found, remove it from the array
   = ADEL(gaCompanies, gnPos)
   gnCount = gnCount - 1
ENDIF
DISPLAY MEMORY LIKE gaCompanies

See Also

Other Resources

ACOPY( ) Function
ADIR( ) Function
AELEMENT( ) Function
AFIELDS( ) Function
AINS( ) Function
ALEN( ) Function
ASCAN( ) Function
ASORT( ) Function
ASUBSCRIPT( ) Function
DIMENSION Command
Functions
Language Reference


ADIR( ) Function

Visual FoxPro 9.0 Language Reference
ADIR( ) Function
See Also Example

Places information about files into an array and then returns the number of files.

ADIR(ArrayName [, cFileSkeleton [, cAttribute [, nFlag]]])

Parameters

ArrayName

Specifies the name of the array. If the array you include doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain all the information, Visual FoxPro automatically increases the size of the array to accommodate the information. If the array is larger than necessary, Visual FoxPro truncates the array. If the array exists and ADIR( ) returns 0 because no matching files are found, the array remains unchanged. If the array doesn't exist and ADIR( ) returns 0, the array isn't created. The following table describes the contents and data type of each column in the array:

Column Array contents Data type

1

File names

Character

2

File sizes

Numeric

3

Dates last modified

Date

4

Times last modified

Character

5

File attributes

Character
The last array column contains the file attributes of the matching files. Each file attribute is expressed by a letter; a file can have more than one attribute. The following table indicates the file attribute represented by each letter:

Letter Attribute

A

Archive – Read/Write

H

Hidden

R

Read-only

S

System

D

Directory
cFileSkeleton

Specifies a file skeleton so you can store information about files with names or extensions that match a search criterion. For example, the criterion can be all tables, all text files, all files with names that have A as their first letter, and so on. Such general searches are done by including the wildcards * and ? in cFileSkeleton. A question mark represents a single character; an asterisk represents any number of characters. You can use any number of wildcards in any position within the file skeleton. You can specify a drive and/or directory to search for matching file names. If you don't specify a drive and a directory, Visual FoxPro places information about files in the current directory into the array.
cAttribute

Specifies the inclusion of subdirectories and hidden or system files. cAttribute can contain any combination of D, H, and S. Including D returns subdirectory names of the current directory in addition to file names that match the file skeleton specified in cFileSkeleton. Including H returns information about hidden files that match the file skeleton specified in cFileSkeleton. Including S returns information about system files that match the file skeleton specified in cFileSkeleton. Include an empty string in cFileSkeleton to return just subdirectory names, hidden files or system files. You can include V in cAttribute to return the volume name of the current drive. Only the volume name is returned to the array if V is included with D, H, or S. The volume name is stored in the first array element and the remainder of the array is truncated.
nFlag

Specifies whether the display provides DOS naming or actual case sensitivity.

nFlag Description

0

(Default) Display represents the full file name in uppercase

1

Display represents original Case in names

2

Display follows DOS 8+3 naming convention

Return Value

Numeric

Remarks

For each file, ADIR( ) places into the array the file name, size, date last modified, time last modified, and attributes.

Example

The following example uses ADIR( ) to create an array containing database information. The names of the databases are then displayed.
Copy Code
CLOSE DATABASES
SET DEFAULT TO (HOME(2) + 'Data')

gnDbcnumber = ADIR(gaDatabase, '*.DBC')  && Create array

CLEAR
FOR nCount = 1 TO gnDbcnumber  && Loop for number of databases
   ? gaDatabase(nCount,1)  && Display database names
ENDFOR
SET PATH TO HOME( )  && Set path to Visual FoxPro directory

See Also

Other Resources

ADEL( ) Function
AELEMENT( ) Function
AFIELDS( ) Function
AINS( ) Function
ALEN( ) Function
ANETRESOURCES( ) Function
ASCAN( ) Function
ASORT( ) Function
ASUBSCRIPT( ) Function
DIMENSION Command
DIR or DIRECTORY Command
Functions
Language Reference


ADLLS( ) Function

Visual FoxPro 9.0 Language Reference
ADLLS( ) Function
See Also

Returns an array containing the names of functions loaded by DECLARE DLLs.

ADLLS(ArrayName)

Parameters

Arrayname

Specifies the name of the array. If the array you specify doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain all the database information, Visual FoxPro automatically increases the size of the array to accommodate the information. If the array is larger than necessary, Visual FoxPro truncates the array. If no DLL functions have been declared, the array is not created, and an existing array is not modified.

Return Value

Numeric

Remarks

The numeric value returned by the ADLLS function specifies the number of DLL loaded functions. If no alias is provided, the 2nd element returns the same value as the 1st element (function name).

The array created by the ADLLS function has the following format:

Column | Field Info | Data Type
1 | Function Name | Character
2 | Function Alias | Character
3 | Library Name | Character

For details about how to declare functions, see DECLARE - DLL Command.

See Also

Other Resources

Arrays
CLEAR Commands
DISPLAY DLLS Command
LIST DLLS Command
DISPLAY STATUS Command
Functions
Language Reference


ADOCKSTATE( ) Function

Visual FoxPro 9.0 Language Reference
ADOCKSTATE( ) Function
See Also Example

Retrieves the dock state of any dockable form, Integrated Development Environment (IDE) window, or toolbar. For forms only, you can use the GetDockState Method. ADOCKSTATE( ) is available in the run time.

ADOCKSTATE( ArrayName [, nType | nExtended])

Parameters

ArrayName

Specifies an array with one or more rows containing the dock state of dockable items.
Note:
Both system and user-defined toolbars can appear in the array. A form appears in the array only if the form's Dockable property is set to a value greater than 0.

The following table illustrates the information that the array contains.

Element Description

1

Name of the form, IDE window, or toolbar.

For user-defined toolbars, the first element contains the Caption property value for that toolbar.

2

Dock state:

1 - Docked

0 - Undocked

3

Dock position.

For form and toolbar values, see DockPosition Property. For windows, see DOCK Command.

4

Target object that specified object is docked with.

This element does not apply to toolbars unless they are docked to the main Visual FoxPro window. For toolbars or windows docked to the main Visual FoxPro window, the fourth element contains the main Visual FoxPro window name, which you can retrieve using the _VFP Caption property. If a window or toolbar is not docked, the fourth element contains an empty string.

Note:
If a toolbar appears between the Visual FoxPro desktop and a window docked to the Visual FoxPro desktop, the fourth element contains the name of the toolbar.

5

Object reference to docking form or toolbar.

Applies only when docking user-defined forms or toolbars; otherwise, this element contains an empty string (IDE window).

6

Object reference to the target object if it is a user-defined form. If the target object is the main Visual FoxPro window, this element contains an object reference to the _SCREEN system variable. Otherwise, this element contains an empty string (IDE window).

nType

Specifies one or more items for which you want ADOCKSTATE( ) to return dock state information. The following table lists the values for nType.

nType Description

0

Return all or no windows. (Default)

1

Return only IDE windows.

2

Return only toolbars.

3

Return only user-defined forms.
nExtended

Specifies the number of elements to return in the array. The following table lists the values for nExtended.

nExtended Description

0

Return a four-element array for windows and toolbars.

1

Return a six-element array for forms.

Return Value

Numeric data type. ADOCKSTATE( ) returns the number of rows populated or 0 if none found.

Remarks

For tab-docked windows, the leftmost window is the anchor window and contains details about how the entire container is docked. Visual FoxPro traverses the windows from left to right. For link-docked windows, the upper left window in a link-docked container contains details about how the entire container is docked.

The following rules determine docking order:

  • Visual FoxPro traverses the link-docked container beginning with upper leftmost window.

  • Visual FoxPro traverses windows from top to bottom, from left to right. A link-docked container might consist of multiple inner containers. Thus, the ordering of windows in the ADOCKSTATE( ) array might appear different.

  • The position contained in the third element of the array is relative to the window referenced in first element of the array.

  • Visual FoxPro traverses all link-docked windows first and tab-docked windows second. Essentially, Visual FoxPro makes two passes through a linked container. Visual FoxPro includes only the leftmost tab-docked window in the first pass for link-docked windows.

  • Visual FoxPro traverses a tab-docked container from left to right.

If the third element in the array is set to -1 (not docked), the container is not docked. If the container is docked to the desktop, the third element in the array contains the position in which the container is docked to the Visual FoxPro desktop as referenced in the fourth element of the array.

For example, the following code creates an array, opens and docks several windows, and produces an array as shown:

Copy Code
CLEAR ALL
PUBLIC aa
DIMENSION aa[1]
ACTIVATE WINDOW Command
ACTIVATE WINDOW Trace
ACTIVATE WINDOW Document
ACTIVATE WINDOW Properties
ACTIVATE WINDOW Watch
ACTIVATE WINDOW Locals
SET
DOCK WINDOW View POSITION -1
DOCK WINDOW Command POSITION -1
DOCK WINDOW Trace POSITION -1
DOCK WINDOW Document POSITION -1
DOCK WINDOW Properties POSITION -1
DOCK WINDOW Watch POSITION -1
DOCK WINDOW Command POSITION 1 WINDOW View
DOCK WINDOW Trace POSITION 1 WINDOW Command
DOCK WINDOW Document POSITION 3 WINDOW View
DOCK WINDOW Properties POSITION 3 WINDOW Trace
DOCK WINDOW Watch POSITION 4 WINDOW Command
DOCK WINDOW Locals POSITION 3 WINDOW Command
ADOCKSTATE(aa,1)

The resulting array appears as follows:

Row | First element | Second element | Third element | Fourth element
1 | Trace | 1 | -1 |
2 | Properties | 1 | 3 | Trace
3 | Watch | 1 | 2 | Trace
4 | Locals | 1 | 3 | Watch
5 | View | 1 | 2 | Watch
6 | Document View | 1 | 3 | View
7 | Command | 1 | 4 | Watch

Visual FoxPro displays docking information for debugger windows in the debugger. If a window is undocked, Visual FoxPro shows the name, dock state (0) and position (-1). If a window is docked, Visual FoxPro shows only the name, dock state (1), position, and window ("Visual FoxPro Debugger").

Historically, in prior versions of Visual FoxPro, the Data Session window has always been referred to as the View window. Additionally, language used to control this window, such as HIDE WINDOW, ACTIVATE WINDOW, WONTOP( ), also refers to this window as the View window. Visual FoxPro continues to refer to the View window for the ADOCKSTATE( ) function.

Example

The following example shows the return results of ADOCKSTATE( ) when no toolbars or windows have been previously docked, for example, after deleting the FoxUser resource files or when Visual FoxPro is newly installed. Make sure the Command window is open.

Copy Code
CLEAR
dockNum = ADOCKSTATE(dockState)
? dockNum   && Returns 2 because Standard toolbar also exists.
? dockState(1,1)  && Outputs "COMMAND".
? dockState(1,4)  && Outputs an empty string because the Command
                && window is not docked.
? dockState(2,1)  && Outputs "Standard".
? dockState(2,4)  && Outputs "Microsoft Visual FoxPro" because the
                && Standard toolbar is docked to the Microsoft
                && Visual FoxPro desktop.

The following example shows how to use the DOCK command to dock the Command window to the Visual FoxPro desktop window and use ADOCKSTATE( ) to obtain the dock state of the Command window. First, make sure the Command window is open. After docking the Command window, you can see that the Standard toolbar and Command windows are docked to the Microsoft Visual FoxPro desktop window. The position of the toolbars or windows in the array returned by ADOCKSTATE( ) can vary depending on the order in which the toolbars or windows are docked.

Copy Code
CLEAR
DOCK WINDOW Command POSITION 0
dockNum = ADOCKSTATE(dockState)
? dockNum   && Returns 2 because Standard toolbar also exists.
? dockState(1,1)  && Outputs "Standard".
? dockState(1,4)  && Outputs "Microsoft Visual FoxPro".
? dockState(2,1)  && Outputs "COMMAND".
? dockState(2,4)  && Outputs "Microsoft Visual FoxPro".

See Also

Reference

DOCK Command

Other Resources

Functions
Caption Property
DockPosition Property
Docked Property
How to: Dock Forms
How to: Dock Toolbars
How to: Dock Windows


AELEMENT( ) Function

Visual FoxPro 9.0 Language Reference
AELEMENT( ) Function
See Also

Returns the number of an array element from the element's subscripts.

AELEMENT(ArrayName, nRowSubscript [, nColumnSubscript])

Parameters

ArrayName

Specifies the name of the array whose element number you want to return.
nRowSubscript

Specifies the row subscript. If the array is one-dimensional, AELEMENT( ) identically returns nRowSubscript. If you include just nRowSubscript and it is greater than the number of rows in the array, Visual FoxPro generates an error message.
nColumnSubscript

Specifies the column subscript. If the array is two-dimensional, include both nRowSubscript and nColumnSubscript.

Return Value

Numeric

Remarks

You can refer to an element in a two-dimensional array in one of two ways. The first method uses two subscripts to specify the row and column position of the element in the array, and the second method uses a single-element number. AELEMENT( ) returns the element number when supplied with an element's row and column subscripts.

The Visual FoxPro functions ADEL( ), ADIR( ), AFIELDS( ), AINS( ), ALEN( ), ASCAN( ), ASORT( ), and ASUBSCRIPT( ) can manipulate two-dimensional arrays and require that elements be referred to by their element number. AELEMENT( ) facilitates conversion from subscripts to an element number for use by these functions. The corresponding row and column subscripts can be returned from an element number with ASUBSCRIPT( ).

The following example illustrates the creation of an array with two rows and three columns. DISPLAY MEMORY shows the contents of the elements of the array listed in element number order.

Copy Code
DIMENSION gaMyArray(2,3)
DISPLAY MEMORY LIKE gaMyArray
gaMyArray   Pub  A
  ( 1, 1)   L  .F. (element number 1)
  ( 1, 2)   L  .F. (element number 2)
  ( 1, 3)   L  .F. (element number 3)
  ( 2, 1)   L  .F. (element number 4)
  ( 2, 2)   L  .F. (element number 5)
  ( 2, 3)   L  .F. (element number 6)

An element can be referred to by its subscripts or its element number. The commands STORE 'INVOICE' TO gaMyArray(2, 1) and STORE 'INVOICE' TO gaMyArray(4) both store the character string INVOICE to the same array element.

In one-dimensional arrays, an element number is identical to its single-row subscript. It isn't necessary to use AELEMENT( ) with one-dimensional arrays.

See Also

Other Resources

ADEL( ) Function
ADIR( ) Function
AFIELDS( ) Function
AINS( ) Function
ALEN( ) Function
ASCAN( ) Function
ASORT( ) Function
ASUBSCRIPT( ) Function
DIMENSION Command
DISPLAY MEMORY Command
Functions
Language Reference


AERROR( ) Function

Visual FoxPro 9.0 Language Reference
AERROR( ) Function
See Also Example

Creates a variable array containing information about the most recent Visual FoxPro, OLE, or ODBC error.

AERROR(ArrayName)

Parameters

ArrayName

Specifies the name of the array for AERROR( ) to create.

Return Value

Numeric. AERROR( ) returns the number of rows in the array.

Remarks

AERROR( ) creates an array with seven columns containing information about the error. The type of error that occurred determines the number of rows in the array.

Note:
If no error occurred, AERROR( ) does not create the array.

When a Visual FoxPro error occurs, the array contains one row. The following table describes the contents of each element.

Element number | Description
1 | Numeric. The number of the error. Identical to the value returned by ERROR( ).
2 | Character. The text of the error message. Identical to the value returned by MESSAGE( ).
3 | The null value. However, if the error has an additional error parameter, contains the text of the error parameter. Almost identical to the value returned by SYS(2018), the difference being that AERROR( ) returns mixed case but SYS(2018) returns all uppercase.
4 | The null value. However, as appropriate, contains the number of the work area in which the error occurred.
5 | The null value. However, if a trigger failed (error 1539), contains one of the following numeric values:1 – Insert trigger failed.2 – Update trigger failed.3 – Delete trigger failed.
6 | The null value.
7 | The null value.

When OLE errors numbered 1427 or 1429 occur, the array contains one row. The following table describes the contents of each element.

Element number | Description
1 | Numeric. Contains 1427 or 1429.
2 | Character. The text of the Visual FoxPro error message.
3 | Character. The text of the OLE error message.
4 | Character. The application name (for example, Microsoft Excel).
5 | The null value or Character. Contains the name of the application's Help file where more information about the error can be found if the information is available from the application; otherwise contains the null value.
6 | The null value or Character. Contains the Help context ID for the appropriate Help topic if the information is available from the application; otherwise contains the null value.
7 | Numeric. An OLE 2.0 exception number.

When an ODBC error numbered 1526 occurs, the array contains one or more rows, one row for each ODBC error. The following table describes the contents of each element.

Element number | Description
1 | Numeric. Contains 1526.
2 | Character. The text of the error message.
3 | Character. The text of the ODBC error message.
4 | Character. The current ODBC SQL state.
5 | Numeric. The error number from the ODBC data source.
6 | Numeric. The ODBC connection handle.
7 | The null value.

Example

The following example uses ON ERROR to specify an error handling routine named errhand. An error is generated by issuing a misspelled command (BRWS). The errhand error handling routine uses AERROR( ) to create an array containing error information, and this information is then displayed.
Copy Code
ON ERROR DO errhand     && errhand is the error handler procedure

BRWS  && Causes a syntax error
ON ERROR  && Restore system error handler

PROCEDURE errhand
   = AERROR(aErrorArray)  && Data from most recent error
   CLEAR
   ? 'The error provided the following information'  && Display message
   FOR n = 1 TO 7  && Display all elements of the array
      ? aErrorArray(n)
   ENDFOR

See Also

Other Resources

COMRETURNERROR( ) Function
CREATE TRIGGER Command
ERROR Command
ERROR( ) Function
MESSAGE( ) Function
ON ERROR Command
SYS(2018) – Error Message Parameter
Error Messages A-Z
Error Messages by Number
Functions
Language Reference


AEVENTS( ) Function

Visual FoxPro 9.0 Language Reference
AEVENTS( ) Function
See Also Example

You can use the AEVENTS( ) function to retrieve the number of existing event bindings.

AEVENTS( ArrayName [, 0 | 1 | oEventObject ] )

Parameters

ArrayName

Specifies the name of the array that contains the results of AEVENTS( ).
0

Specifies that AEVENTS( ) returns a three-element array containing an object reference to the current event source, the name of the triggered event, and how the event was triggered.

Column Description Type

1

Event source

Object reference

2

Event

String

3

Event type, or how event was raised.

0 - System

1 - RAISEEVENT( ) function

2 - Method call
The third array element indicates how an event was triggered. If the event is a property, this value can be 1 or 2. The value is 2 if the property is set or assigned.
1

Specifies that AEVENTS( ) returns a four-column array containing information about Windows Message (Win Msg) events. The array contains one row for each binding. Bindings are created with the BINDEVENT( ) Function. The following table describes the contents of each column in the array.

Column Description Type

1

hWnd

Integer

2

Window Message

Integer

3

Reference of handler

Object reference

4

Handler delegate

String
oEventObject

Specifies an object reference. If you specify an object reference, AEVENTS( ) returns a five-column array that contains the events raised and the delegate methods for oEventObject. Each row in ArrayName represents a binding. The following table describes the information in each of the five columns.

Column Description Type

1

.T. if second element is the event source

.F. if second element is the event handler

Logical

2

Event source if you pass the event handler to oEventObject; otherwise, event handler if you pass the event source to oEventObject.

Object reference

3

Event

String

4

Delegate method

String

5

BINDEVENT( ) flags

Integer
When you pass oEventObject, the number of bindings returned by AEVENTS( ) should equal the number of unbound events returned by the UNBINDEVENTS( ) function when passing only the oEventObject parameter.

Return Value

Numeric. AEVENTS( ) returns the number of rows in the specified array. Typically, the number represents the number of event bindings. However, if you pass zero (0), then AEVENTS( ) returns 3.

Remarks

If AEVENTS( ) returns 0, and the array does not exist, Visual FoxPro does not create the array. Visual FoxPro changes or alters an existing array only if valid results are returned. The array remains unchanged under the following conditions:

  • No events exist.

  • You specify a value of 0 as the second parameter, and AEVENTS( ) does not appear within an event or oEventObject has no bindings.

Example

The following example shows how to use AEVENTS( ) to retrieve the number of existing event bindings. BINDEVENTS( ) keeps the Class Browser positioned to the right side of the Visual FoxPro desktop, regardless of how the desktop is resized. For more information, see BINDEVENT( ) Function.

UNBINDEVENTS( ) detaches the Resize event of the _SCREEN system variable from the object, oHandler. AEVENTS( ) returns the number of event bindings before BINDEVENT( ) and after UNBINDEVENTS( ) in an array called myArray:
Copy Code
PUBLIC oHandler
oHandler=NEWOBJECT("myhandler")
DO (_browser)

BINDEVENT(_SCREEN,"Resize",oHandler,"myresize")
AEVENTS(myArray,oHandler)
numRows=ALEN(myArray,1)
numCols=ALEN(myArray,2)
WAIT "Rows in array after binding: " + TRANSFORM(numRows) WINDOW AT 20,20
WAIT "Cols in array after binding: " + TRANSFORM(numCols) WINDOW AT 20,20
FOR count1 = 1 TO numRows
   FOR count2 = 1 TO numCols
      WAIT myArray[count1,count2] WINDOW AT 20,20
   ENDFOR
ENDFOR

* Comment the following line to see event binding persist.
UNBINDEVENTS(_SCREEN,"Resize",oHandler,"myresize")
AEVENTS(myArray,oHandler)

* Check if AEVENTS( ) created and populated new array.
IF VARTYPE(myArray) <> U
   * The following code does not execute if event is unbound because
   * AEVENT( ) does not create a new array if it returns 0. To execute
   * the following code and see the contents of the new array, uncomment
   * the UNBINDEVENTS( ) statement.
   numRows=ALEN(myArray,1)
   numCols=ALEN(myArray,2)
   WAIT "Rows in array after unbinding: " + TRANSFORM(numRows) ;
      WINDOW AT 20,20
   WAIT "Cols in array after unbinding: " + TRANSFORM(numCols) ;
      WINDOW AT 20,20
   FOR count1 = 1 TO numRows
      FOR count2 = 1 TO numCols
         WAIT myArray[count1,count2] WINDOW AT 20,20
      ENDFOR
   ENDFOR
ENDIF

DEFINE CLASS myhandler AS Session
   PROCEDURE myresize
   _obrowser.left = _SCREEN.Width - _obrowser.width
   RETURN
ENDDEFINE

See Also

Reference

SYS(2325) - WCLIENTWINDOW from Visual FoxPro WHANDLE
SYS(2326) - WHANDLE from a Window's hWnd
SYS(2327) - Window's hWnd from Visual FoxPro WHANDLE

Other Resources

Functions
Event Binding for Visual FoxPro Objects
BINDEVENT( ) Function
UNBINDEVENTS( ) Function
RAISEEVENT( ) Function


AFIELDS( ) Function

Visual FoxPro 9.0 Language Reference
AFIELDS( ) Function
See Also Example

Retrieves and stores information about the structure of the table in a specified work area, specified by a table alias, or in the currently selected work area in an array and returns the number of fields in the table.

AFIELDS( ArrayName [, nWorkArea | cTableAlias ] )

Parameters

ArrayName

Specifies an array to store information about the table structure. If the array you specify does not exist, Visual FoxPro automatically creates it. If the array exists and is not large enough to contain all the information returned by AFIELDS( ), the size of the array is automatically increased to accommodate the information.
nWorkArea

Specifies the work area of the table.
cTableAlias

Specifies a table alias. If you omit nWorkArea and cTableAlias, AFIELDS( ) retrieves information for the table in the currently selected work area.

Return Value

Numeric data type. AFIELDS( ) returns the number of fields in the table. The array contains 18 columns and has the same number of rows as fields in the table.

The following table describes the content of each column in the first row of the array and the data type of the information stored in each column. Values for table-specific properties in columns 10 through 16 only appear in the first row of the array. One row is created for each field in the table.

Column number | Field info | Data type
1 | Field name | Character
2 | Field type: C = Character Y = Currency D = Date T = DateTime B = Double F = Float G = General I = Integer L = Logical M = Memo N = Numeric Q = Varbinary V = Varchar and Varchar (Binary) W = Blob | Character
3 | Field width | Numeric
4 | Decimal places | Numeric
5 | Null values allowed | Logical
6 | Code page translation not allowed | Logical
7 | Field validation expression | Character
8 | Field validation text | Character
9 | Field default value | Character
10 | Table validation expression | Character
11 | Table validation text | Character
12 | Long table name | Character
13 | Insert trigger expression | Character
14 | Update trigger expression | Character
15 | Delete trigger expression | Character
16 | Table comment | Character
17 | NextValue for autoincrementing | Numeric
18 | Step for autoincrementing | Numeric

Remarks

If the fields in the table use autoincrementing, the Step value is greater than 0.

You can use COPY STRUCTURE EXTENDED to place similar information into a table instead of an array.

Example

The following example creates an array named gaMyArray, which contains information about the fields in the Customer table. The names of the fields are displayed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer     && Open Customer table.

gnFieldcount = AFIELDS(gaMyArray)  && Create array.
CLEAR
FOR nCount = 1 TO gnFieldcount
   ? gaMyArray(nCount,1)  && Display field names.
ENDFOR

See Also

Other Resources

ADEL( ) Function
ADIR( ) Function
AELEMENT( ) Function
AINS( ) Function
ALEN( ) Function
ALTER TABLE – SQL Command
ASCAN( ) Function
ASORT( ) Function
ASUBSCRIPT( ) Function
Autoincrementing Field Values in Tables
COPY STRUCTURE EXTENDED Command
CREATE Command
CREATE TABLE Command
DIMENSION Command
Visual FoxPro Data and Field Types
Functions
Language Reference


AFONT( ) Function

Visual FoxPro 9.0 Language Reference
AFONT( ) Function
See Also Example

Places information about available fonts, such as their names, into an array.

Tip:
You can also use AFONT( ) to determine available font sizes or if a font is scalable. To display a dialog box containing available fonts, font sizes, and styles, use the GETFONT( ) function. For more information, see GETFONT( ) Function.

AFONT(ArrayName [, cFontName [, nFontSize | nFontCharSet [, nFlags]]])

Parameters

ArrayName

Specifies the variable array into which the names of available fonts are placed. If the array is not large enough to contain all the fonts, Visual FoxPro automatically increases the size of the array. If you specify an existing two-dimensional array, Visual FoxPro changes the array to a one-dimensional array.
cFontName

Specifies a font for which information is placed into the array. If the font you specify supports only discrete font sizes (8-point, 10-point, ...), the font sizes are stored to the array, and AFONT( ) returns True (.T.). If the font you specify in cFontName is scalable (supports fractional font size values), the array has a single element containing –1, and AFONT( ) returns True (.T.). If the font you specify is not available, the array is not created, and AFONT( ) returns False (.F.).
nFontSize

Specifies a size for the font specified in cFontName. If the font size nFontSize is available for the font specified in cFontName, the array has a single element containing a True (.T.) value, and AFONT( ) returns True (.T.). If the font size is not available for the specified font, the array is not created, and AFONT( ) returns False (.F.).
nFontCharSet

Specifies a character set for the font specified in cFontName. If the font character set specified is available for the font specified in cFontName, the array has a single element containing a True (.T.) value, and AFONT( ) returns True (.T.). If the font character set is not available for the specified font, the array is not created, and AFONT( ) returns False (.F.).
nFlags

Controls whether the third parameter passed is treated as the font size or font character set. The following table describes behavior for various nFlags values specified.

nFlags Description

Omitted or 0 for the first bit

Third parameter is treated as a font size value.

If third parameter is -1, array is updated with all available font sizes for the font specified in cFontName for nonproportional fonts, such as MS Sans Serif, and AFONT( ) returns True (.T.). This behavior in Visual FoxPro 8.0 and later is equivalent to passing only the first two parameters.

Note:
In versions prior to Visual FoxPro 8.0, if you specified any negative or positive font size for a non-proportional font, AFONT( ) returned False (.F.).

If the third parameter passed is 0, for nonproportional fonts, AFONT( ) returns False (.F.) for Visual FoxPro 8.0 and later. However, the behavior for proportional fonts such as TrueType or OpenType (Arial) has not changed.

1

Third parameter is treated as a font character set. Array is populated with character sets available for the specified font.

If the third parameter passed is -1, array is updated with all available font character sets for the font specified in cFontName.

Return Value

Logical data type. AFONT( ) returns True (.T.) if array is successfully created. Otherwise, AFONT( ) returns False (.F.).

Remarks

If only ArrayName was passed in versions earlier than Visual FoxPro 8.0, the array populated in AFONT( ) included extra fonts that were really part of a single font family. For example, the array might have included the following Arial fonts under Visual FoxPro 7.0:

  • Arial

  • Arial Baltic

  • Arial Black

  • Arial CE

  • Arial CYR

  • Arial Greek

  • Arial Narrow

  • Arial Tur

Many of these fonts are not included in a standard Font Picker dialog box such as the GETFONT( ) function. In this version of Visual FoxPro, the array in AFONT( ) excludes these extra fonts. For example, the array only includes the following fonts:

  • Arial

  • Arial Baltic

  • Arial Black

Example

The following example uses AFONT( ) to create an array containing the names of all available fonts. The name of each font is displayed, along with an example of the font. If there are more than 10 fonts installed, only the first 10 are displayed.
Copy Code
CLEAR
=AFONT(gaFontArray)  && Array containS font names.
gnNumFonts = ALEN(gaFontArray)  && Number of fonts
IF gnNumFonts > 10
   gnNumFonts = 10  && Display first 10 fonts.
ENDIF

FOR nCount = 1 TO gnNumFonts
   ? ALLTRIM(gaFontArray(nCount))  && Display font name.
   ?? '  This is an example of ' ;
      + ALLTRIM(gaFontArray(nCount)) FONT gaFontArray(nCount), 8
ENDFOR

See Also

Other Resources

FONTMETRIC( ) Function
SYSMETRIC( ) Function
WFONT( ) Function
TXTWIDTH( ) Function
Functions
Language Reference


AGETCLASS( ) Function

Visual FoxPro 9.0 Language Reference
AGETCLASS( ) Function
See Also Example

Displays class libraries in the Open dialog box and creates an array containing the name of the class library and class chosen.

AGETCLASS(ArrayName [, cLibraryName [, cClassName [, cTitleText
[, cFileNameCaption [, cButtonCaption]]]]])

Parameters

ArrayName

Specifies the name of the array in which the names of the class library and class are placed. The following table lists the contents of each element of the array created when you chose a class.

Element Contents

1

File name of the class library chosen.

2

Name of the class chosen.
cLibraryName

Specifies the name of the class library initially selected when the Open dialog is displayed. cLibraryName can be a visual (.vcx) or program (.prg) -based class library. The class library name you specify is displayed in the File name text box. An error is generated if the class library you specify doesn't exist or cLibraryName is the empty string or the null value.
cClassName

Specifies the name of the class initially selected in the Class name list when the Open dialog is displayed. If the class you specify doesn't exist, the first class in the Class name list is selected. An error is generated if you omit cLibraryName or cClassName is the null value.
cTitleText

Specifies the text displayed in the title bar of the Open dialog. By default, "Open" is the text displayed.
cFileNameCaption

Specifies the text displayed next to the File name text box. By default, "File name:" is the text displayed.
cButtonCaption

Specifies the caption for the OK button.

Return Value

Logical data type. AGETCLASS( ) returns True (.T.), if you chose a class, and creates a one-dimensional array containing two elements. The first element contains the file name of the class library chosen; the second element contains the name of the class chosen. AGETCLASS returns False (.F.) if you exit the Class Library dialog box by pressing ESC, choosing Cancel, or clicking the Close button.

Remarks

If the array you specify does not exist, Visual FoxPro automatically creates the array.

If the array exists and is not large enough to contain the names of the class library and class, Visual FoxPro automatically increases the size of the array.

If the array is larger than necessary, Visual FoxPro truncates the array. If the array exists, and AGETCLASS( ) returns False (.F.) because the Class Library dialog box was closed by pressing ESC, choosing Cancel, or clicking the Close button, the array remains unchanged.

If the array does not exist, and AGETCLASS( ) returns false (.F.), the array is not created.

Visual FoxPro 8.0 does not support AGETCLASS( ) in its run-time libraries. AGETCLASS( ) is supported in Visual FoxPro 9.0 run-time libraries, but the Program (*.prg) option is not available in the Files of type drop-down list box.

Example

The following example creates an array named aClassLib. The directory is changed to the \Samples subdirectory that contains the sample class libraries. AGETCLASS( ) is used to display a dialog with the Buttons class library and the VCR class selected. If you choose the Modify button, the name of the class library and class you select is stored in the array. The class is then opened in the Class designer.
Copy Code
LOCAL aClassLib(2)  && Create an array, initialized to .F.
cCurrentDir = CURDIR( )  && Save the current directory.
CD HOME(2) + 'CLASSES'  && Switch directories.

AGETCLASS(aClassLib, 'BUTTONS.VCX', 'VCR', 'Modify Class', ;
   'Class File:', 'Modify')  && Display the dialog.
CD (cCurrentDir)  && Switch to the previous directory.

IF TYPE('aClassLib(2)') = 'C'  && Class chosen?
   MODIFY CLASS (aClassLib(2)) OF (aClassLib(1))  && Open to modify.
ENDIF

See Also

Other Resources

ACLASS( ) Function
AMEMBERS( ) Function
AVCXCLASSES( ) Function
CREATE CLASS Command
Functions
Language Reference


AGETFILEVERSION( ) Function

Visual FoxPro 9.0 Language Reference
AGETFILEVERSION( ) Function
See Also

Creates an array containing information about files with Windows version resources such as .exe, .dll, and .fll files, or automation servers created in Visual FoxPro.

Note:
For a Visual FoxPro automation server to have Windows version resources, you must specify a value for at least one item in the EXE Version dialog box. For more information, see EXE Version Dialog Box.

AGETFILEVERSION(ArrayName, cFileName)

Parameters

ArrayName

Specifies the name of the array in which the file information is placed. If the array you specify doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain the file information, Visual FoxPro automatically increases the size of the array. If the array is larger than necessary, Visual FoxPro truncates the array. The following table lists the contents of each element of the array.

Element Contents

1

Comments

2

Company Name

3

File Description

4

File Version

5

Internal Name

6

Legal Copyright

7

Legal Trademarks

8

Original File Name

9

Private Build

10

Product Name

11

Product Version

The format of this value is dependent on the version of Visual FoxPro. For details, see VERSION( ) Function.

12

Special Build

13

OLE Self Registration (contains "OLESelfRegister" if the file supports self-registration; otherwise contains the empty string)

14

Language (derived from the Translation Code)

15

Translation Code

For example, you can use the following code to determine the Locale ID for the Visual FoxPro executable file:

Copy Code
DIMENSION aFiles[1]
AGETFILEVERSION(aFiles,"VFP9.EXE")
? EVAL("0x"+LEFT(aFiles[15],4))
** Returns 1033 for US version
cFileName

Specifies the name, and optionally the path, of the target file.

Return Value

Numeric. AGETFILEVERSION( ) returns the number of elements in the array. If the file you specify does not exist or does not contain Windows version resources, AGETFILEVERSION( ) returns zero, and the array, if already created, remains unchanged.

Remarks

AGETFILEVERSION( ) can be abbreviated to a minimum number of 5 characters.

See Also

Other Resources

ADIR( ) Function
DIR or DIRECTORY Command
GETFILE( ) Function
Functions
Language Reference


AINS( ) Function

Visual FoxPro 9.0 Language Reference
AINS( ) Function
See Also Example

Inserts an element into a one-dimensional array, or a row or column into a two-dimensional array.

AINS(ArrayName, nElementNumber [, 2])

Parameters

ArrayName

Specifies the name of the array into which the element is inserted.
nElementNumber

Specifies where the new element, row, or column is inserted into the array. To insert an element into a one-dimensional array, include ArrayName and the element nElementNumber where the insertion occurs. The new element is inserted just before element nElementNumber. To insert a row into a two-dimensional array, include ArrayName and the number of the row nElementNumber where the insertion occurs. The new row is inserted just before row nElementNumber. For more information on referencing an array element by its subscripts, see DIMENSION Command.
2

Inserts a column into a two-dimensional array. The new column is inserted just before the column specified with nElementNumber.

Return Value

Numeric

Remarks

Inserting an element, row, or column into an array does not change the size of the array. The trailing elements, rows, or columns are shifted toward the end of the array and the last element, row, or column in the array is dropped from it. The newly inserted element, row, or column is initialized to false (.F.).

AINS( ) returns 1 if the element, row, or column is successfully inserted.

Example

The following example creates and fills an array with company names and scans the array for a specific company name. If the company name isn't found, it inserts the missing company name into the array.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer     && Open customer table
SELECT company FROM customer ;
   WHERE country = 'Germany' ;
   INTO ARRAY gaCompanies

gnCount = _TALLY
gcName = 'Seven Seas Imports'
CLEAR
DISPLAY MEMORY LIKE gaCompanies

IF ASCAN(gaCompanies, gcName) = 0  && Search for company
*** Company not found-add it ***
   DIMENSION gaCompanies[gnCount+1,1]
   = AINS(gaCompanies, gnCount-1)
   gaCompanies[gnCount-1] = gcName
ENDIF
DISPLAY MEMORY LIKE gaCompanies

See Also

Other Resources

ACOPY( ) Function
ADEL( ) Function
ADIR( ) Function
AELEMENT( ) Function
AFIELDS( ) Function
ALEN( ) Function
ASCAN( ) Function
ASORT( ) Function
ASUBSCRIPT( ) Function
DIMENSION Command
Functions
Language Reference


AINSTANCE( ) Function

Visual FoxPro 9.0 Language Reference
AINSTANCE( ) Function
See Also Example

Places instances of a class into a variable array and returns the number of instances placed in the array.

AINSTANCE(ArrayName, cClassName)

Parameters

ArrayName

Specifies the name of the array into which the instances are placed. If the array you specify doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain all the instances, Visual FoxPro automatically increases the size of the array to accommodate the instances. If the array is larger than necessary, Visual FoxPro truncates the array. If the array exists and AINSTANCE( ) returns 0 because no instances are found, the array remains unchanged. If the array doesn't exist and AINSTANCE( ) returns 0, the array is not created. Only class instances assigned to variables and array elements with CREATEOBJECT( ) or NEWOBJECT( ) are placed into the array.
cClassName

Specifies a Visual FoxPro base class name or a user-defined class name. For a complete list of the Visual FoxPro base classes, see Base Classes in Visual FoxPro.

Return Value

Numeric

Example

In the following example, CREATEOBJECT( ) is used to create two instances of the Visual FoxPro Form base class. AINSTANCE( ) is used to create an array named gaMyArray that contains the variable references (goINSTANCE1 and goINSTANCE2) for each form instance. The contents of the array are then displayed.
Copy Code
CLEAR ALL
goINSTANCE1 = CREATEOBJECT('Form')
goINSTANCE2 = CREATEOBJECT('Form')

CLEAR
? AINSTANCE(gaMyArray, 'Form')  && Returns 2, two form instances
DISPLAY MEMORY LIKE gaMyArray  && Displays the references

See Also

Other Resources

ADD CLASS Command
AMEMBERS( ) Function
CREATE CLASS Command
CREATE CLASSLIB Command
CREATEOBJECT( ) Function
DEFINE CLASS Command
Functions
Language Reference


ALANGUAGE( ) Function

Visual FoxPro 9.0 Language Reference
ALANGUAGE( ) Function
See Also

Returns an array containing the names of all valid Visual FoxPro commands, functions, or base classes.

ALANGUAGE(ArrayName, nType)

Parameters

ArrayName

Specifies the name of the array to contain the language items. If the array doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain all the data, Visual FoxPro automatically increases the size of the array to accommodate the information. If the array is larger than necessary, Visual FoxPro truncates the array.
nType

Specifies the type of language item returned, according to the following list:

Value Description Array Type

1

Commands

One-dimensional: Command name

2

Functions
Two-dimensional:

Function name [M] nParamR [- nParamT] The matchFlag, M, specifies that you must use the full function name in code.nParamR specifies the number of required parameters. nParamT specifies total number of possible parameters.

3

Base classes
One-dimensional:

Base Class name

4

DBC Events
One-dimensional:

DBC event name (The displayed name omits the "DBC_" prefix of the event name.)

Remarks

The ALANGUAGE( ) function returns an array of all valid Visual FoxPro commands and functions. To return object information, use the AMEMBERS( ) function.

Examples

Use the ALANGUAGE( ) function to access Visual FoxPro functions as in the following code:

Copy Code
   ALANGUAGE(FuncArr,2)

The resulting array, FuncArr, will contain the following values:

Copy Code
   JUSTSTEM, M1

JUSTSTEM( ) cannot be abbreviated and it requires one parameter.

Copy Code
   KEYMATCH, 1-4

KEYMATCH( ) can be abbreviated to four characters, and has one required, and three optional parameters (total = 4).

Copy Code
   LASTKEY, 0

LASTKEY( ) can be abbreviated and requires no parameters.

See Also

Other Resources

Using Commands and Functions
LASTKEY( ) Function
KEYMATCH( ) Function
JUSTSTEM( ) Function
Functions
Language Reference


ALEN( ) Function

Visual FoxPro 9.0 Language Reference
ALEN( ) Function
See Also Example

Returns the number of elements, rows, or columns in an array.

ALEN(ArrayName [, nArrayAttribute])

Parameters

ArrayName

Specifies the name of the array. If you include only the array name, ALEN( ) returns the number of elements in the array.
nArrayAttribute

Determines whether ALEN( ) returns the number of elements, rows or columns in the array according to the following values for nArrayAttribute:

0

Returns the number of elements in the array. Omitting nArrayAttribute is identical to specifying 0.

1

Returns the number of rows in the array.

2

Returns the number of columns in the array. If the array is a one-dimensional array, ALEN( ) returns 0 (no columns).

Return Value

Numeric

Example

The following example uses AFONT( ) to create an array containing the names of all available fonts. ALEN( ) is used to determine the number of rows in the array. The name of each font is displayed, along with an example of the font. If more than 10 fonts are installed, only the first 10 are displayed.
Copy Code
CLEAR
=AFONT(gaFontArray)  && Array containing font names
gnNumFonts= ALEN(gaFontArray)  && Number of fonts
IF gnNumFonts > 10
   gnNumFonts = 10  && Display first 10 fonts
ENDIF

FOR nCount = 1 TO gnNumFonts
   ? ALLTRIM(gaFontArray(nCount))  && Display font name
   ?? '  This is an example of ' ;
      + ALLTRIM(gaFontArray(nCount)) FONT gaFontArray(nCount), 8
ENDFOR

See Also

Other Resources

ADEL( ) Function
ADIR( ) Function
AELEMENT( ) Function
AFIELDS( ) Function
AINS( ) Function
ASCAN( ) Function
ASORT( ) Function
ASUBSCRIPT( ) Function
DIMENSION Command
STORE Command
AFONT( ) Function
Functions
Language Reference


ALIAS( ) Function

Visual FoxPro 9.0 Language Reference
ALIAS( ) Function
See Also Example

Returns the table alias of the current or specified work area.

ALIAS([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area number for which ALIAS( ) returns the table alias.
cTableAlias

Specifies the table alias for which ALIAS( ) returns the table alias. If you omit nWorkArea or cTableAlias, ALIAS( ) returns the alias of the table open in the current work area. An empty string is returned if a table isn't open in the current or specified work area.

Return Value

Character

Example

The following example opens the customer table and displays its alias. The customer table is opened again in another work area, is assigned an alias of MyCustomer, and the alias is displayed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer     && Open customer table
CLEAR
? ALIAS( )  && Display the alias
SELECT 0
USE customer AGAIN ALIAS MyCustomer  && Different alias
? ALIAS( )  && Display the alias

See Also

Other Resources

DBF( ) Function
SELECT( ) Function
How to: Create and Use Table Aliases
Alias Property
Functions
Language Reference


ALINES( ) Function

Visual FoxPro 9.0 Language Reference
ALINES( ) Function
See Also Example

Copies each line in a character expression or memo field to a corresponding row in an array.

ALINES(ArrayName, cExpression [, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

Parameters

ArrayName

Specifies the name of the array to store the copied lines in the character expression or memo field.
Note:
If the array you specify does not exist, Visual FoxPro automatically creates the array. If the array exists but is not large enough to contain all the lines in the memo field, Visual FoxPro automatically increases the size of the array. If the array is larger than necessary, Visual FoxPro truncates the array.

Note:
When used with binary values, such as Varbinary and Blob, ALINES( ) creates an array with elements that have Varbinary type.

cExpression

Specifies the character expression or memo field containing the lines to copy to the array. All character expressions are case-sensitive.
Note:
If cExpression is the empty string or the null value, an array with a single row is created and the row contains the empty string. You can use double-byte expressions.

[, nFlags]

Note:
In previous versions of Visual FoxPro, nFlags was the lTrim option. The lTrim option corresponds to a value of 1 for nFlag. Previous code will run identically in Visual FoxPro 9.0.

The following table describes the values for nFlags.

Bit Value (additive) Description

0

1

(Default) Removes leading and trailing spaces from lines, or for Varbinary and Blob values, removes trailing zeroes (0) instead of spaces.

1

2

Include the last element in the array even if the element is empty.

2

4

Do not include empty elements in the array.

3

8

Specifies case-insensitive parsing.

4

16

Include the parsing characters in the array.
[, cParseChar[, c ParseChar2[, ...]]]

Specifies one or more character strings that terminate the elements in cExpression. When cParseChar is specified, the line breaks when cParseChar is found, and the next line continues with the character following cParseChar.
Note:
The maximum number of strings permitted in cParseChar is 23.

You can use a line feed (CHR(10)) or carriage return (CHR(13)) character to denote the end of a line. You can also denote the end of the line with either combination of these two characters, for example, (CHR(10) + CHR(13) or CHR(13) + CHR(10)). The default behavior for ALINES( ) is to ignore CHR(13) and CHR(10) when you specify one or more values for cParseChar, unless you also specify the end of line characters.
Note:
When cParseChar is omitted for Varbinary or Blob input, ALINES( ) treats the hexadecimal value 0hA (10) as a carriage return and discontinues the line at that location. The value, 0hA, is not saved in the resulting array element and might result in an incorrect binary value. For example, given the binary value, 0hFE0AF2, ALINES( ) creates a two-element array with the values, 0hFE and 0hF2.

Return Value

Numeric. ALINES( ) returns the number of rows in the array, or, identically, the number of lines in the character expression or memo field.

Remarks

ALINES( ) provides an easy way to parse lines in a character expression or memo field. While you can also use MLINES( ) to parse a character expression or memo field, ALINES( ) is faster and requires less programming. Also, ALINES( ) is not affected by the value of SET MEMOWIDTH.

The first line of the character expression or memo field is copied to the first row of the array, the second line of the character expression or memo field is copied to the second row of the array, and so on.

You must have sufficient memory to copy the lines in a large memo field to an array. Visual FoxPro generates an error message if you lack sufficient memory.

If you want to perform a case-insensitive parse, you can follow one of the following examples:

Copy Code
? ALINES(aMyArray, UPPER(employee.notes), "R.")

- OR -

Copy Code
? ALINES(aMyArray, employee.notes, "R.", "r.")

Example

The following example opens the Employee table in the Testdata.dbc sample database. ALINES( ) is used to copy the lines in the Notes memo field to an array named aMyArray, and then the contents of the array is displayed. Various parsing character are specified in each of the ALINES( ) statements.

Copy Code
CLOSE DATABASES
CLEAR
SET TALK OFF
OPEN DATABASE (HOME(2) + "data\testdata")
USE employee  && Open Employee table

? ALINES(aMyArray, employee.notes)            && Displays 1
? ALINES(aMyArray, employee.notes, CHR(13))   && Displays 1

? ALINES(aMyArray, employee.notes, " ")       && Displays 75
? ALINES(aMyArray, employee.notes, ".")       && Displays 7
? ALINES(aMyArray, employee.notes, ",")       && Displays 4
? ALINES(aMyArray, employee.notes, ".", ",")  && Displays 10

? ALINES(aMyArray, employee.notes, 8, "m")    && Displays 14
? ALINES(aMyArray, employee.notes, "m")       && Displays 11
? ALINES(aMyArray, employee.notes, "M")       && Displays 4

See Also

Other Resources

MEMLINES( ) Function
_MLINE System Variable
SCATTER Command
MLINE( ) Function
SET MEMOWIDTH Command
ATCLINE( ) Function
ATLINE( ) Function
COPY MEMO Command
MODIFY MEMO Command
Functions
Language Reference


ALLTRIM( ) Function

Visual FoxPro 9.0 Language Reference
ALLTRIM( ) Function
See Also Example

Removes all leading and trailing spaces or parsing characters from the specified character expression, or all leading and trailing zero (0) bytes from the specified binary expression.

ALLTRIM(Expression [, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

Parameters

Expression

Specifies an expression of Character or Varbinary type to remove leading and trailing spaces or 0 bytes from, respectively.
nFlags

Specifies if trimming is case-sensitive when one or more parse characters (cParseChar, cParseChar2, … are included. Trimming is case-sensitive if nFlags is zero or is omitted. Trimming is case-insensitive if nFlags 1.
cParseChar [, cParseChar2 [, ...]]

Specifies one or more character strings that are trimmed from the beginning and end of cExpression. If cParseChar is not included, then leading and trailing spaces or 0 bytes are removed from Expression. Note The maximum number of strings permitted in cParseChar is 23.

Return Value

Character or Varbinary. ALLTRIM( ) returns the specified expression without leading or trailing spaces, parsing characters, or 0 bytes respectively.

Remarks

You can use ALLTRIM( ) to ensure that spaces or 0 bytes are removed from data entered by a user.

Example

The following example uses the AFONT( ) function to create an array containing the names of all available fonts. ALLTRIM( ) removes the leading and trailing spaces from the font names. The trimmed name of each font is displayed along with an example of the font. If more than 10 fonts are installed, only the first 10 are displayed.
Copy Code
CLEAR
=AFONT(gaFontArray)  && Array containing font names
gnNumFonts= ALEN(gaFontArray)  && Number of fonts
IF gnNumFonts > 10
   gnNumFonts = 10  && Display first 10 fonts
ENDIF

FOR nCount = 1 TO gnNumFonts
   ? ALLTRIM(gaFontArray(nCount))  && Display font name
   ?? '  This is an example of ' ;
      + ALLTRIM(gaFontArray(nCount)) FONT gaFontArray(nCount), 8
ENDFOR

See Also

Other Resources

LTRIM( ) Function
RTRIM( ) Function
TRIM( ) Function
AFONT( ) Function
Functions
Language Reference


AMEMBERS( ) Function

Visual FoxPro 9.0 Language Reference
AMEMBERS( ) Function
See Also Example

Places the names of properties, procedures, and member objects for an object into a variable array.

AMEMBERS(ArrayName, oObjectName | cClassName [, nArrayContentsID] [, cFlags])

Parameters

ArrayName

Specifies the array into which the names of the member properties for oObjectName are placed. If you specify the name of an array that doesn't exist, the array is automatically created. If the array isn't large enough to contain all the names, Visual FoxPro automatically increases the size of the array.
oObjectName

Specifies the object whose member properties are placed in the variable array specified with ArrayName. oObjectName can be any expression that evaluates to an object, such as an object reference, an object variable, or an object array element.
cClassName

Specifies the Visual FoxPro class whose member properties are placed in the variable array specified with ArrayName.
nArrayContentsID

Description

0

Specifies that the array contains a single column of property names. Omitting the nArrayContentsID parameter is the same as passing a 0.

1

Specifies that the array contains the names of the properties of the object or class, as well as the methods and member objects. The resulting array is two-dimensional with the second column specifying what type of member is listed in the first column. The possible values for the second column are Property, Event, Method, or Object.

2

Specifies that the array contains the names of objects that are members of a native Visual FoxPro object specified with oObjectName. The resulting array is one-dimensional.

This option provides a method to determine the names of child objects in a container such as all Form objects in a form set or controls in a form.

3

Specifies that the array contains information about one or more objects. You can pass an object reference to either a native Visual FoxPro object or to a COM object.

Note:
A value of 3 for this parameter is not supported in .app or .exe applications.
The array returned when you specify this parameter consists of four columns as described in the following table:

Column Description

1

Name of the event or method

2

Property type (for example, PROPERTYPUT, PROPERTYGET, PROPERTYPUTREF, METHOD)

3

Function signature (parameters and their types, and the function return type). This information is similar to the Quick Info text provided in IntelliSense expansion of a method.

4

Help string
If you omit nArrayContentsID, AMEMBERS( ) returns a one column array of properties.
cFlags

Specify the filtering applied to the array returned by the AMEMBERS( ) function. cFlags will not function when AMEMBERS( ) is passed a COM object (the value of ArrayContentsID is 3). Some flags are mutually exclusive so that if you use more than one cFlag, use them in the following groupings: [P | H | G] [N | U] [C] [I | B] [R] The following tables describe the valid values for cFlags.

Value Filter Flags

P

Protected properties, methods, or events

H

Hidden properties, methods, or events

G

Public properties, methods, or events

N

Native (Intrinsic) properties, methods, or events

U

User-Defined (Extrinsic) properties, methods, or events

C

Changed properties (but not changed array properties)

I

Inherited properties, methods, or events

B

Base properties, methods, or events (using the AddProperty method)

R

Read-Only Properties

The default configuration for the filtering specified by cFlags is logical OR between flags. You can change this by using the special "+" cFlags.

Value | Special Flags
# | Adds a new column to the output array with the corresponding cFlags value.
+ | Performs logical AND between filter flags.

Return Value

Numeric

Remarks

AMEMBERS( ) returns the number of objects, properties, and procedures for the object, or 0 if the array cannot be created. If you omit the optional 1, 2, or 3 flag parameters, a one-dimensional array is created containing the properties of oObjectName.

You can pass COM object references to the AMEMBERS( ) function, but when you do so, you must also pass a value of 3 in the third (flag) parameter, as in the following example.

Copy Code
oExcel = CREATEOBJECT("excel.application")
= AMEMBERS(gaPropArray, oExcel, 3)

Example

The following example uses CREATEOBJECT( ) to create a Form object named goForm1. AMEMBERS( ) is used to create an array named gaPropArray containing the properties available for the form; the properties are then displayed.
Copy Code
CLEAR
goForm1 = CREATEOBJECT("Form")  && Creates a Form
= AMEMBERS(gaPropArray, goForm1, 1)  && Array containing Form properties
DISPLAY MEMORY LIKE gaPropArray  && Display the Form properties

See Also

Other Resources

ADD CLASS Command
AINSTANCE( ) Function
CREATE CLASS Command
CREATE CLASSLIB Command
CREATEOBJECT( ) Function
DEFINE CLASS Command
Functions
Language Reference


AMOUSEOBJ( ) Function

Visual FoxPro 9.0 Language Reference
AMOUSEOBJ( ) Function
See Also

Creates an array containing information about the mouse pointer position and the object over which the mouse pointer is positioned.

AMOUSEOBJ(ArrayName [, 1])

Parameters

ArrayName

Specifies the name of the array containing the mouse pointer information. If the array you specify doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain all the lines in the memo field, Visual FoxPro automatically increases the size of the array. If the array is larger than necessary, Visual FoxPro truncates the array. The array that is created contains four rows. The following table describes the contents of each row in the array:

Array row Description

1

Contains an object reference to the object over which the mouse pointer is positioned when AMOUSEOBJ( ) is executed.

2

Contains an object reference to the container of the object over which the mouse pointer is positioned when AMOUSEOBJ( ) is executed.

3

Contains the horizontal (X) coordinate in pixels of the mouse pointer, relative to the container of the object over which the mouse pointer is positioned when AMOUSEOBJ( ) is executed.

4

Contains the vertical (Y) coordinate in pixels of the mouse pointer, relative to the container of the object over which the mouse pointer is positioned when AMOUSEOBJ( ) is executed.

Note that the first and second rows in the array can contain the same values if the mouse is positioned over a generic container such as a pageframe.

[, 1]

This optional parameter specifies that the mouse pointer information contained in the array is relative to the current form (THISFORM). If this option is included, the second array row always contains an object reference to the current form, and the third and fourth rows contain the mouse pointer coordinates relative to the current form.

Return Value

Numeric

Remarks

AMOUSEOBJ( ) can also be used to determine where the mouse pointer is positioned during design time. The following table lists the design time element and the values contained in each row of the array:

Design-time element | Array contents
Form and Class Designers | Row 1 – Object reference to the control.Row 2 – Object reference to the form.Row 3 – Mouse pointer horizontal (X) coordinate relative to the form.Row 4 – Mouse pointer vertical (Y) coordinate relative to the form.
Project Manager | Row 1 – Object reference to the project.Row 2 – Object reference to the project.Row 3 – Zero.Row 4 – Zero.
Visual FoxPro Desktop | Row 1 – Object reference to the desktop.Row 2 – Object reference to the desktop.Row 3 – Mouse pointer horizontal (X) coordinate relative to the desktop.Row 4 – Mouse pointer vertical (Y) coordinate relative to the desktop.

AMOUSEOBJ( ) returns 4 (the number of rows in the array) if the mouse pointer is positioned over an area listed above. If the mouse pointer is positioned over an area other than those listed above, AMOUSEOBJ( ) returns zero and if the array you specify already exists, it remains unchanged. If the array you specify doesn't exist, it isn't created.

See Also

Other Resources

MCOL( ) Function
MROW( ) Function
SYS(1270) - Object Location
ASELOBJ( ) Function
Functions
Language Reference


ANETRESOURCES( ) Function

Visual FoxPro 9.0 Language Reference
ANETRESOURCES( ) Function
See Also

Places the names of network shares or printers into an array and then returns the number of resources.

ANETRESOURCES(ArrayName, cNetworkName, nResourceType)

Parameters

ArrayName

Specifies the name of the array containing the network share or printer information. If the array you specify doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain all the information, Visual FoxPro automatically increases the size of the array to accommodate the information. If the array is larger than necessary, Visual FoxPro truncates the array. If the array exists and ANETRESOURCES( ) returns 0 because no network shares or printers are found, the array remains unchanged. If the array doesn't exist and ANETRESOURCES( ) returns 0, the array isn't created.
cNetworkName

Specifies the name of the network or domain for which share or printer information is returned. The network name should be in the format "\\NetworkName." You do not have to be connected to the network you specify, and specifying a network doesn't connect you to the network. If you specify a domain name, ANETRESOURCES( ) returns an array of members or resources from that domain.
nResourceType

Specifies the type of network resource for which information is returned. The names of shares on the network are returned if nResourceType evaluates to 1. The names of printers on the network are returned if nResourceType evaluates to 2. A value of 0 returns the name of any resource.

Return Value

Numeric

Remarks

ANETRESOURCES( ) returns the number of network shares or printers found (identical to the number of rows in the array). ANETRESOURCES( ) returns zero if there are no shares or printers for the network of the type you specify, or the network you specify doesn't exist.

Note:
Before Windows 2000, share names were limited to twelve characters in length. If you run ANETRESOURCES() on a computer that uses an operating system earlier than Windows 2000, ANETRESOURCES() will not return any shares that are on computers running Windows 2000 or later that have share names longer than twelve characters.

Refer to the WNetOpenEnum and WNetEnumResource Win32 API functions for more details.

See Also

Other Resources

ADIR( ) Function
APRINTERS( ) Function
GETPRINTER( ) Function
Functions
Language Reference


APRINTERS( ) Function

Visual FoxPro 9.0 Language Reference
APRINTERS( ) Function
See Also Example

Stores information about currently-available printers into an array.

Note:
The behavior of this function is OS (operating system) - specific. Visual FoxPro may or may not check to see if the printers are actually connected to your computer when it prepares this list, and the list may include all printers installed as printer setups, or only those available on the current network.

APRINTERS(ArrayName [, nValue])

Parameters

ArrayName

Specifies the name of the array containing information about printers.
Note:
If the array you include does not exist, Visual FoxPro automatically creates the array. If the array exists but is not large enough to contain all the information, Visual FoxPro increases the size of the array to accommodate the information. If the array is larger than necessary, Visual FoxPro truncates the array. If the array exists but APRINTERS( ) returns 0 because no printers are available, the array remains unchanged. If the array does not exist, and APRINTERS( ) returns 0, the array is not created.

[, nValue]

Specifies a value that creates a two-column array or five-column array. Each row in the array contains information about a printer. The following table describes the possible values of nValue.

nValue Description

0 or omitted

Return a two-column array containing the following items beginning with the first column:

  • Printer name.

  • Name of the port to which the printer is connected.

1

Return a five-column array containing the following items beginning with the first column:

  • Printer name.

  • Name of the port to which the printer is connected.

  • Name of the printer driver.

  • Printer comment.

  • Printer location.

Return Value

Numeric. APRINTERS( ) returns the number of rows in the array or 0 when no printers are available.

Example

The following example creates an array named gaPrinters if any printers are available and displays information about those printers. Otherwise, it displays a message indicating that APRINTERS( ) is unable to retrieve information about any printers.
Copy Code
IF APRINTERS(gaPrinters) > 0
   CLEAR  && clear the current output window
   DISPLAY MEMORY LIKE gaPrinters && show the contents of the array
ELSE
   WAIT WINDOW 'No printers found.'
ENDIF

See Also

Other Resources

GETPRINTER( ) Function
PRINTSTATUS( ) Function
PRTINFO( ) Function
SET PRINTER Command
Functions
Language Reference


APROCINFO( ) Function

Visual FoxPro 9.0 Language Reference
APROCINFO( ) Function
See Also

Creates an array containing Visual FoxPro language elements contained in a program file.

APROCINFO(ArrayName, cFileName [, nType])

Parameters

ArrayName

Specifies the name of the array to be created.
cFileName

Specifies the filename of the program that this function traverses.
nType

Specifies the type of information returned in cArrayName. The following table specifies valid nType values and describes the information returned by each nType value.

nType Description Array Details

0 (default

Populates the array with all document information.

Column1 – Doc View content

Column2 – line

Column3 – type

Column4 – indentation

Indentation is used with preprocessor directives to show nested levels of #IF type statements.

1

Populates the array with only the class definitions in the document.

Column1 – class name

Column2 – line

Column3 – parentclass

Column4 - is OLEpublic

2

Populates the array with only class procedure information (class definition excluded)

Column1 – Doc View content

Column2 – line

3

Populates the array with #define and other preprocessor directives in the document.

Column1 – Doc View content

Column2 – line

Column3 – type
The following table describes the "type" values returned in Column3 for nType values of 0 and 3.

nType Description

Define

#DEFINE preprocessor directive

Directive

Other preprocessor directives, such as #IF

Class

Class definition line

Procedure

Procedure, Method or Event

Return Value

Numeric. APROCINFO( ) returns the number of rows added to the array.

Remarks

Visual FoxPro automatically creates the array you specify if it doesn't already exist. Visual FoxPro automatically increases or truncates the size of the array to accommodate the returned information. This function supports program (PRG) files only.

See Also

Other Resources

Data Transfer and Arrays
Arrays
Array Manipulation
EDITSOURCE( ) Function
#DEFINE ... #UNDEF Preprocessor Directive
#IF ... #ENDIF Preprocessor Directive
Document View Window
Functions
Language Reference


ASC( ) Function

Visual FoxPro 9.0 Language Reference
ASC( ) Function
See Also Example

Returns the ANSI value for the leftmost character in a character expression.

ASC(cExpression)

Parameters

cExpression

Specifies the character expression containing the character whose ANSI value ASC( ) returns. Any characters after the first character in cExpression are ignored by ASC( ).

Return Value

Numeric

Remarks

ASC( ) returns the position of the character in the character table of the current code page. Every character has a unique ANSI value in the range from 0 to 255.

Example

The following example displays the characters A through J and uses ASC( ) to display their corresponding ANSI values.
Copy Code
STORE 'ABCDEFGHIJ' TO gcANSI  && 10 characters
CLEAR
FOR nCOUNT = 1 TO 10
   ? SUBSTR(gcANSI, nCount,1)  && Display a character
   ?? ASC(SUBSTR(gcANSI, nCount)) && Display ANSI value
ENDFOR

See Also

Other Resources

CHR( ) Function
SET ANSI Command
ANSITOOEM( ) Function
OEMTOANSI( ) Function
Functions
Language Reference


ASCAN( ) Function

Visual FoxPro 9.0 Language Reference
ASCAN( ) Function
See Also Example

Searches an array for an element containing the same data and data type as an expression.

ASCAN(ArrayName, eExpression [, nStartElement [, nElementsSearched [, nSearchColumn [, nFlags ]]]])

Parameters

ArrayName

Specifies the name of the array to search.
eExpression

Specifies the general expression to search for.
nStartElement

Specifies the element number at which the search begins. The element number you specify is included in the search. If you omit nStartElement, the entire array is searched by default.
nElementsSearched

Specifies the number of elements that are searched. If you omit nStartElement and nElementsSearched, the search begins with the first array element and continues to the last array element if you do not specify nSearchColumn.
Note:
You can refer to an element in a two-dimensional variable array in one of two ways. The first method uses two subscripts to specify the row and column position of the element in the array; the other method uses an element number. This function and others that manipulate two-dimensional arrays require element numbers (nStartElement and nElementsSearched). Use AELEMENT( ) to return the element number from row and column subscripts in a two-dimensional array.

nSearchColumn

Specifies the array column to search. This is often useful in arrays created by functions such as AFIELDS( ). You can use 0 or a negative number for nSearchColumn to impose a search of the entire array. If you use a value greater than 0 for nSearchColumn, ASCAN( ) treats the specified column as a one-dimensional array, using each data row as an element in the search. For instance, the following example searches only the third and fourth elements of column 2 instead of the entire array.
Copy Code
? ASCAN(abc,"M",3,2,2)
Visual FoxPro generates an error if nSearchColumn is a number larger than the number of available columns.
nFlags

Specifies additional search criteria to apply to the scan function. Default scans are case-sensitive. The number you specify in nFlags provides a bit-value that determines the case sensitivity or exactness setting of a scan according to the following table:

NFlag Bit Description

0

0000

Behavior existing in Visual FoxPro 6 or earlier

1

0001

Case Insensitive

2

0010

Current behavior existing in the previous version of Visual FoxPro

3

0011

Case Insensitive

4

0100

Exact OFF

5

0101

Case Insensitive; Exact OFF

6

0110

Exact ON

7

0111

Case Insensitive; Exact ON

8

1000

Return row number

9

1001

Case Insensitive; return row number

10

1010

Return row number

11

1011

Case Insensitive; return row number

12

1100

Return row number; Exact OFF

13

1101

Case Insensitive; Return row number; Exact OFF

14

1110

Return row number; Exact ON

15

1111

Case Insensitive; Return row number; Exact ON

The bit values are as follows:

Bit | Description
0 | Case Insensitive bit
1 | Exactness ON bit (Only effective if bit 2 is set)
2 | Override system Exact setting bit
3 | Return row number if 2D array

nFlags applies only to the ASCAN( ) function and does not affect settings for SET EXACT.

Return Value

Numeric

Remarks

If a match is found, ASCAN( ) returns the number of the element containing the expression. If a match cannot be found, ASCAN( ) returns 0.

The criteria for a successful match of character data are determined by the setting of the system SET EXACT if nFlag with bit 2 is not set. If SET EXACT is ON, an element must match the search expression character for character and have the same length. If SET EXACT is OFF, and an element and search expression match until the end of the expression is reached, the match is successful. For more information on match criteria for character strings, see the string comparison table in the SET EXACT topic.

In Visual FoxPro 6.0, the nStartElement and nElementsSearched parameters are optional. The nStartElement must be > 0 while nElementsSearched can be any value. In order to accommodate the nSearchColumn parameter, you will need to bypass these parameters by passing a value of -1.

The nStartElement and nElementsSearched parameters take on special meaning if the value of nSearchColumn is greater than 0. In Visual FoxPro 6.0, they are always referenced to the entire array. Beginning with Visual FoxPro 7.0, if a positive nSearchColumn is passed, the values of nStartElement and nElementsSearched are referenced to the single one-dimensional array represented by the nSearchColumn. For example, the following would only search the third and fourth elements of column 2, and not the entire array:

Copy Code
? ASCAN(abc,"M",3,2,2)

Example

The following example creates and fills an array with company names, and then uses ASCAN( ) to search for a particular company name. If the company name is found, it is removed from the array.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer     && Open customer table
SELECT company FROM customer ;
   WHERE country = 'UK' ;
   INTO ARRAY gaCompanies
gnCount = _TALLY
gcName = 'Seven Seas Imports'
CLEAR
DISPLAY MEMORY LIKE gaCompanies*
gnPos = ASCAN(gaCompanies, gcName) && Search for company
IF gnPos != 0
   *** Company found, remove it from the array ***
   = ADEL(gaCompanies, gnPos)
   gnCount = gnCount - 1
ENDIF
DISPLAY MEMORY LIKE gaCompanies

See Also

Other Resources

ACOPY( ) Function
ADEL( ) Function
ADIR( ) Function
AELEMENT( ) Function
AFIELDS( ) Function
AINS( ) Function
ASORT( ) Function
ASUBSCRIPT( ) Function
DIMENSION Command
SET EXACT Command
Functions
Language Reference


ASELOBJ( ) Function

Visual FoxPro 9.0 Language Reference
ASELOBJ( ) Function
See Also Example

Places an object reference for the currently selected control or container that exists in the Form Designer, Class Designer, or code editing window into a specified variable array. When calling ASELOBJ( ) in a code editing window, the array also includes elements for forms (.scx), visual class libraries (.vcx), and #INCLUDE file names. You can also use ASELOBJ( ) to create control builders.

ASELOBJ( ArrayName, [ 1 | 2 | 3 ] )

Parameters

ArrayName

Specifies the name of the array you want to use.
1

Creates a one-element array containing an object reference to the container for the currently active and selected control. For example, if the currently active and selected control is a spinner on a form, the array contains an element with the value "FORM." When calling ASELOBJ( ) in the Command window, include this argument.
Note:
When a page frame is selected, ASELOBJ() returns the name of the current page.

2

Creates a one-element array containing an object reference to the DataEnvironment object for the form. The DataEnvironment object makes it possible for you to determine the data environment properties of the form.
3

Creates three-element array containing information in context with the currently active code editing window: object reference to a container object, the full path and name of the .scx or .vcx file, and the full path and name of the #INCLUDE file, if available. The following table shows the order in which these elements appear.

Array element Description

1

Object reference to container object

2

Full path and name of .scx or .vcx file

3

Full path and name of #INCLUDE file, if available

Note:
If no #INCLUDE file is available, the third element contains an empty string.

Return Value

Numeric data type. ASELOBJ( ) returns the number of objects selected. The array contains three columns and a row for each selected object. .

Remarks

If no controls are selected, and the argument, 1, is omitted, ASELOBJ( ) returns 0 and does not create the array. If no controls exist on the form, ASELOBJ( ) does not recognize the form as the selected control. If no controls are currently selected and the argument, 1, is included, ASELOBJ( ) returns 1.

If the array does not exist, Visual FoxPro automatically creates the array.

If the array exists but is too small to contain all the information, Visual FoxPro automatically increases the size of the array to accommodate the information. If the array is larger than needed, Visual FoxPro truncates the array.

If the array exists, and ASELOBJ( ) returns 0 because no controls are selected, the array remains unchanged. If the array does not exist, and ASELOBJ( ) returns 0, the array is not created.

Example

Before running the following example, open a new form in the Form Designer and add one or more controls with Caption properties, such as a Label or CommandButton, to the form. Select a number of these controls and then run the example. ASELOBJ( ) displays the names of the selected controls, and then changes the captions of the selected controls.
Copy Code
gnobjects = ASELOBJ(gaSelected)     && Create array of control names
IF gnobjects > 0  && 0 indicates no controls selected
   CLEAR
   DISPLAY MEMORY LIKE gaSelected     && Displays selected controls
   FOR nCnt = 1 TO gnobjects
      ? gaSelected(nCnt).Caption + ' => New Caption ' ;
         + LTRIM(STR(nCnt))  && Display old and new caption
      gaSelected(nCnt).Caption = 'New Caption ' ;
         + ALLTRIM(STR(nCnt))  && Assign new caption
   NEXT
ENDIF

See Also

Other Resources

CREATE FORM Command
DataEnvironment Object
Form Designer
_ObjectReference( ) API Library Routine
AMOUSEOBJ( ) Function
Functions
Language Reference


ASESSIONS( ) Function

Visual FoxPro 9.0 Language Reference
ASESSIONS( ) Function
See Also

Creates an array of existing data session IDs.

ASESSIONS(ArrayName)

Parameters

ArrayName

Specifies the array that contains the data session IDs.

Return Value

Numeric. Returns the number of data sessions.

Remarks

If the array does not exist, Visual FoxPro automatically creates and populates it. Visual FoxPro automatically resizes the array to accommodate current data sessions.

See Also

Other Resources

Array Manipulation
Commands that Scope to a Data Session
How to: Use Data Sessions
Functions
Language Reference


ASIN( ) Function

Visual FoxPro 9.0 Language Reference
ASIN( ) Function
See Also Example

Returns in radians the arc sine of a numeric expression.

ASIN(nExpression)

Parameters

nExpression

Specifies the numeric expression whose arc sine ASIN( ) returns. The value of nExpression can range from +1 through –1, and the value ASIN( ) returns can range from –pi/2 through +pi/2 ( –1.57079 to 1.57079). The number of decimal places in the display of the result can be specified with SET DECIMALS.

Return Value

Numeric

Remarks

Use RTOD( ) to convert radians to degrees.

Example

Copy Code
CLEAR
? RTOD(ASIN(0))  && Returns 0.00
STORE 1 to gnArcAngle
? RTOD(ASIN(gnArcAngle))  && Returns 90.00
? RTOD(ASIN(SQRT(2)/2))  && Returns 45.00

See Also

Other Resources

RTOD( ) Function
SET DECIMALS Command
SIN( ) Function
Creating Numeric Expressions
Functions
Language Reference


ASORT( ) Function

Visual FoxPro 9.0 Language Reference
ASORT( ) Function
See Also Example

Sorts elements in an array in ascending or descending order.

ASORT(ArrayName [, nStartElement [, nNumberSorted [, nSortOrder [, nFlags]]])

Parameters

ArrayName

Specifies the name of the array to sort.
nStartElement

Specifies the starting element of the sort. If you omit nStartElement, the array is sorted starting with the first array element by default. If the array is one-dimensional, the sort includes nStartElement. If the array is two-dimensional, the starting element nStartElement determines both the row where the sort begins and the column that determines the sort order of the rows.
Note:
You can refer to an element in a two-dimensional array in one of two ways. The first method uses two subscripts to specify the row and column position of the element in the array; the other method uses an element number. This function and others that manipulate two-dimensional arrays require element numbers (in ASORT() the numeric expressions nStartElement and nNumberSorted). You can use AELEMENT( ) to return the element number from row and column subscripts in a two-dimensional array.

The following example illustrates that the starting element nStartElement determines how the rows in a two-dimensional array are sorted. A small array named gaArray is created and sorted twice. The first sort begins with the first element of gaArray; the rows are sorted based on the values contained in the first column of the array. The second sort begins with the fourth element of gaArray; the rows are sorted based on the values contained in the second column. The first sort begins with the first row. The second sort begins with the second row. You can use DISPLAY MEMORY to display the contents of the array; in these examples tables are used to graphically display the results of the sorts. These commands create the array named gaArray:
Copy Code
DIMENSION gaArray(3,2)
gaArray(1) = 'G'
gaArray(2) = 'A'
gaArray(3) = 'C'
gaArray(4) = 'Z'
gaArray(5) = 'B'
gaArray(6) = 'N'
gaArray looks like this:

Column 1 Column 2

Row 1

G

A

Row 2

C

Z

Row 3

B

N
The array is then sorted by ASORT( ) starting with the first element (1,1) in the array. The elements in the first column are placed in ascending order by rearranging the rows of the array.
Copy Code
=ASORT(gaArray,1)
Note the new order of the rows:

Column 1 Column 2

Row 1

B

N

Row 2

C

Z

Row 3

G

A
The array is then sorted starting with the fourth element (2,2) in the array. The elements in the second column are placed in order by rearranging the array rows.
Copy Code
=ASORT(gaArray,4)
Note the difference in the order of the rows:

Column 1 Column 2

Row 1

B

N

Row 2

G

A

Row 3

C

Z
nNumberSorted

Specifies the number of elements that are sorted in a one-dimensional array, or the number of rows that are sorted in a two-dimensional array. For example, if the array is one-dimensional and nStartElement is 2, indicating that the sort starts with the second array element, and nNumberSorted is 3, indicating that the sort should include three elements, the second, third and fourth array elements are sorted. If nNumberSorted is –1 or is omitted, all array elements from the starting element nStartElement through the last element in the array are sorted. If the array is two-dimensional, nNumberSorted designates the number of rows to sort, beginning with the row containing the starting element nStartElement. For example, if nStartElement is 2 and nNumberSorted is 3, the row containing the second array element and the following two rows are sorted. If nNumberSorted is –1 or is omitted, all array rows beginning with the row containing the starting element nStartElement through the last array row are sorted.
nSort Order

Specifies the sort order (ascending or descending) for the elements in the array. By default, array elements are sorted in ascending order. If nSortOrder is 0 or is omitted, the array elements are sorted in ascending order. If nSortOrder is any positive value, the array elements are sorted in descending order.
nFlags

Specifies case-sensitive search criteria to apply to the sort function. Valid values are 0 (the default) and 1. ASORT( ) uses the current collate sequence (see SET COLLATE) to determine the sort order. Certain collate sequences (such as "GENERAL") are not case-sensitive, and specifying nFlags = 0 will not cause a case-sensitive sorting. The nFlags parameter is only useful when the current collate sequence is case-sensitive (such as "MACHINE"), and you wish to do a non-case-sensitive sort. The number you specify in nFlags provides a bit-value that determines the case sensitivity of a sort according to the following table:

nFlag Bit Description

0

000

Case-sensitive sort

1

001

Case insensitive sort
Note:
If you specify nFlags, you can omit the other parameters by passing them in as -1.

Return Value

Numeric

Remarks

All elements included in the sort must be of the same data type. One-dimensional arrays are sorted by their elements; two-dimensional arrays are sorted by their rows. When a two-dimensional array is sorted, the order of the rows in the array is changed so that the elements in a column of the array are in ascending or descending order.

If the sort is successful, 1 is returned; otherwise –1 is returned.

Example

The following example copies the contact field from the customer table to an array named gaContact. The first 20 contacts in the array are displayed, the array is sorted, and the contacts are displayed again in sorted order.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer  && Open customer table

COUNT TO gnCount  && Number of contacts
DIMENSION gaContact(gnCount,1)  && Create a contact array
COPY TO ARRAY gaContact FIELD contact     && Fill the array

CLEAR
? 'Contact names:'
?
FOR nCount = 1 TO 20
   ? gaContact(nCount)  && Display first 20 contacts
ENDFOR
= ASORT(gaContact)     && Sort the array

?
? 'Sorted Contact names:'
?
FOR nCount = 1 TO 20
   ? gaContact(nCount)  && Display first 20 contacts, sorted
ENDFOR

See Also

Other Resources

ACOPY( ) Function
ADEL( ) Function
ADIR( ) Function
AELEMENT( ) Function
AFIELDS( ) Function
AINS( ) Function
ALEN( ) Function
ASCAN( ) Function
Functions
Language Reference


ASQLHANDLES( ) Function

Visual FoxPro 9.0 Language Reference
ASQLHANDLES( ) Function
See Also

Stores numeric references to all active SQL connection statement handles in an array.

ASQLHANDLES(ArrayName [, nStatementHandle])

Parameters

ArrayName

Specifies the name of an array to store statement handle information. If the array you specify does not exist, Visual FoxPro creates the array automatically. If the array exists and is not large enough to store the information, Visual FoxPro increases the array size automatically. If the array is larger than necessary, Visual FoxPro truncates the array.
nStatementHandle

Populates the array with statement handles that use the same shared connection, including nStatementHandle.

Return Value

Numeric. ASQLHANDLES( ) returns the number of statement handles in use. If no statement handles are available, ASQLHANDLES( ) returns 0 and does not modify the array.

Remarks

You can use references to statement handles in other Visual FoxPro SQL functions, such as SQLEXEC( ) and SQLDISCONNECT( ). For more information, see SQLEXEC( ) Function and SQLDISCONNECT( ) Function.

You can create and return new statement handles using the SQLCONNECT( ) and SQLSTRINGCONNECT( ) functions. For more information, see SQLCONNECT( ) Function and SQLSTRINGCONNECT( ) Function.

See Also

Other Resources

SQLGETPROP( ) Function
SQLSETPROP( ) Function
SQL Commands and Functions
Functions


ASTACKINFO( ) Function

Visual FoxPro 9.0 Language Reference
ASTACKINFO( ) Function
See Also Example

Creates an array and populates it with information about the current state of the call stack.

ASTACKINFO(ArrayName)

Parameters

ArrayName

Specifies the name of the array to store information about the call stack. The following table describes the information returned by the ASTACKINFO( ) function:

Array Element Description

1

Call Stack Level

2

Current program filename

3

Module or Object name

4

Module or Object Source filename

5

Line number in the object source file

6

Source line contents

Return Value

Numeric

Remarks

ASTACKINFO( ) populates an array with information about the entire calling stack. It combines functionality of SYS(16) and PROGRAM( ) functions while adding new support for line numbers at each call stack level. The value returned is the number of program levels or rows of the returned array.

ASTACKINFO( ) only populates the 6th array element if source line contents are available, otherwise it will be left empty.

ASTACKINFO( ) provides, in the 2nd and 4th elements respectively, the name of the current file and, if the file is bound in an APP or other separate file, a full path name to the binding program.

The 4th element contains the original source file information. For objects, this is same information returned by SYS(16), even when bound inside of applications.

Note:
ASTACKINFO() might not be able to retrieve information about program (.prg) files. In this case, Visual FoxPro displays the 2nd element similar to the SYS(16) function. For more information, see SYS(16) - Executing Program File Name.

Example

A modeless form bound in an APP file (myAppl.app) with a button from buttons.vcx class (also in the APP). The developer runs myAppl.app in Visual FoxPro to display the form (the form remains open because this is not run time Visual FoxPro). When the user clicks the button to run the report, the report (which exists outside of myAppl.app) calls a query form in its BeforeOpenTables event.

This query form (getcusts.scx), which resides inside of myAppl.app, issues a call to ASTACKINFO( ) [then displays the resulting array as in the following example].
Copy Code
ASTACKINFO(myarray)
DISPLAY MEMO LIKE myarray
myArray
(1,1)   1                                    && Stack level = 1
(1,2)   c:\vfp\myAppl.app                        && Current program
(1,3) frmRerport.PrintReport.Click         && Object
(1,4) c:\vfp\myclasses\buttons.vct         && Object source file name
(1,5) 42                              && Line number in the source
(1,6) THISFORM.DoReport()                  && in the source
(2,1)   2                                    && Stack level = 2
(2,2) c:\vfp\myAppl.app
(2,3) frmRerport.DoReport
(2,4) c:\vfp\forms\frmRerport.sct         && Module source file name
(2,5) 31
(2,6) DO RunListReport                     && in the source
(3,1)   3                                    && Stack level = 3
(3,2) c:\vfp\myAppl.app
(3,3)
(3,4) c:\vfp\programs\runlisterport.prg   && Module source file name
(3,5) 12
(3,6) REPORT FORM myreport1.frx            && in the source
(4,1)   4                                    && Stack level = 4
(4,2) c:\vfp\reports\myreport1.frt
(4,3) myreport1.DataEnvironment.BeforeOpenTables
(4,4) c:\vfp\reports\myreport1.frt          && Module source file name
(4,5) 31
(4,6) DO FORM getcusts                     && in the source
(5,1)   5                                    && Stack level = 5
(5,2) c:\vfp\myAppl.app
(5,3) getcusts.init
(5,4) c:\vfp\forms\getcusts.sct            && Module source file name
(5,5) 2
(5,6) ASTACKINFO(myarray)                  && in the source

See Also

Other Resources

Arrays
Objects
Call Stack Window
LINENO( ) Function
PROGRAM( ) Function
Functions
Language Reference


ASUBSCRIPT( ) Function

Visual FoxPro 9.0 Language Reference
ASUBSCRIPT( ) Function
See Also

Returns the row or column subscript of an element from the element's number.

ASUBSCRIPT(ArrayName, nElementNumber, nSubscript)

Parameters

ArrayName

Specifies the name of the array.
nElementNumber

Specifies the element number.
nSubscript

Determines if the row or column subscript is returned. If the array is one-dimensional, include the element number in nElementNumber and 1 in nSubscript. ASUBSCRIPT( ) identically returns nElementNumber. If the array is two-dimensional, include both the element number nElementNumber and a value of 1 or 2 in nSubscript. Specifying 1 in nSubscript returns the row subscript of the element, and specifying 2 returns the column subscript. For more information on how to reference elements in an array, see DIMENSION.

Return Value

Numeric

Remarks

You can refer to elements in two-dimensional variable arrays in one of two ways. The first method uses two subscripts to specify the row and column position of the element in the array. The second method uses an element number. Use ASUBSCRIPT( ) to obtain an element's row or column subscript from the element's number.

In the following example, an array with two rows and three columns is created. DISPLAY MEMORY shows the contents of the elements of the array listed in element number order.

Copy Code
DIMENSION gaMyArray(2,3)
DISPLAY MEMORY LIKE gaMyArray
GAMYARRAY  Pub  A
  ( 1, 1)   L  .F. (element number 1)
  ( 1, 2)   L  .F. (element number 2)
  ( 1, 3)   L  .F. (element number 3)
  ( 2, 1)   L  .F. (element number 4)
  ( 2, 2)   L  .F. (element number 5)
  ( 2, 3)   L  .F. (element number 6)

Each of these commands stores the character string INVOICE to the same array element:

Copy Code
STORE 'INVOICE' TO gaMyArray(2, 1)
STORE 'INVOICE' TO gaMyArray(4)

In one-dimensional arrays, an element's number is identical to its single row subscript. It isn't necessary to use ASUBSCRIPT( ) with one-dimensional arrays.

See Also

Other Resources

ADEL( ) Function
ADIR( ) Function
AELEMENT( ) Function
AFIELDS( ) Function
AINS( ) Function
ALEN( ) Function
ASCAN( ) Function
ASORT( ) Function
DIMENSION Command
DISPLAY MEMORY Command
Functions
Language Reference


AT( ) Function

Visual FoxPro 9.0 Language Reference
AT( ) Function
See Also Example

Searches a character expression for the occurrence of another character expression.

Note:
The search performed by AT( ) is case-sensitive. To perform a search that is not case-sensitive, use ATC( ). For more information, see ATC( ) Function.

AT(cSearchExpression, cExpressionSearched [, nOccurrence])

Parameters

cSearchExpression

Specifies the character expression to search for in cExpressionSearched.
cExpressionSearched

Specifies the character expression to search for cSearchExpression. Both cSearchExpression and cExpressionSearched can be memo fields of any size.
nOccurrence

Specifies which occurrence, first, second, third, and so on, of cSearchExpression to search for in cExpressionSearched. By default, AT( ) searches for the first occurrence of cSearchExpression (nOccurrence = 1).

Return Value

Numeric. AT( ) returns an integer indicating the position of the first character for a character expression or memo field within another character expression or memo field, beginning from the leftmost character. If the expression or field is not found, or if nOccurrence is greater than the number of times cSearchExpression occurs in cExpressionSearched, AT( ) returns 0.

Example

Copy Code
STORE 'Now is the time for all good men' TO gcString
STORE 'is the' TO gcFindString
CLEAR
? AT(gcFindString,gcString)  && Displays 5
STORE 'IS' TO gcFindString
? AT(gcFindString,gcString)  && Displays 0, case-sensitive

See Also

Other Resources

AT_C( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
RAT( ) Function
RATLINE( ) Function
RIGHT( ) Function
SUBSTR( ) Function
ATCC( ) Function
LEFTC( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
STREXTRACT( ) Function
$ Operator
OCCURS( ) Function
INLIST( ) Function
Functions
Language Reference


AT_C( ) Function

Visual FoxPro 9.0 Language Reference
AT_C( ) Function
See Also

Returns the beginning numeric position of the first occurrence of a character expression or memo field within another character expression or memo field, counting from the leftmost character.

AT_C(cSearchExpression, cExpressionSearched [, nOccurrence])

Parameters

cSearchExpression

Specifies the character expression that AT_C( ) searches for in cExpressionSearched.
cExpressionSearched

Specifies the character expression cSearchExpression searches for. Both cSearchExpression and cExpressionSearched can be memo fields of any size.
nOccurrence

Specifies which occurrence (first, second, third, and so on) of cSearchExpression is searched for in cExpressionSearched. By default, AT_C( ) searches for the first occurrence of cSearchExpression (nOccurrence = 1). Including nOccurrence lets you search for additional occurrences of cSearchExpression in cExpressionSearched. AT_C( ) returns 0 if nOccurrence is greater than the number of times cSearchExpression occurs in cExpressionSearched.

Return Value

Numeric

Remarks

AT_C( ) searches the second character expression for the first occurrence of the first character expression. It then returns an integer indicating the position of the first character in the character expression found. If the character expression isn't found, AT_C( ) returns 0.

AT_C( ) is designed for expressions containing double-byte characters. If the expression contains only single-byte characters, AT_C( ) is equivalent to AT( ).

The search performed by AT_C( ) is case-sensitive. To perform a search that isn't case-sensitive, use ATCC( ).

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

ATCC( ) Function
AT( ) Function
ATC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
RAT( ) Function
RATLINE( ) Function
RIGHT( ) Function
SUBSTR( ) Function
ATCC( ) Function
LEFTC( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
$ Operator
OCCURS( ) Function
INLIST( ) Function
Functions
Language Reference


ATAGINFO( ) Function

Visual FoxPro 9.0 Language Reference
ATAGINFO( ) Function
See Also

Creates an array that contains information about index files for the selected table.

ATAGINFO(ArrayName [,cCDXName [, nWorkArea | cTableAlias]])

Parameters

ArrayName

Specifies the name of the array to create. Visual FoxPro creates the array if it does not already exist.
cCDXName

Specifies the name of the compound index (.cdx) file to return information for.
Note:
Specifying an empty string ("") returns the number of tags in all open .cdx files and all open standalone index (.idx) files for the selected table.

nWorkArea

Specifies the work area that contains the table to returns information for.
cTableAlias

Specifies the alias of the table to return information for.
Note:
Omitting cTableAlias and nWorkArea uses the table in the current work area.

Return Value

Numeric. ATAGINFO( ) returns the number of index tags in compound index (.cdx) files or open single-key standalone index (.idx) files for the current table.

Remarks

The following table describes the information stored in the array that ATAGINFO( ) creates.

Column | Description | Data type
1 | Index tag name in a .cdx file or index file name for .idx files | Character
2 | Index tag type | Character
3 | Index key expression | Character
4 | Filter expression | Character
5 | Index order as created (Ascending or Descending) | Character
6 | Collate sequence | Character

See Also

Other Resources

TAG( ) Function
TAGCOUNT( ) Function
TAGNO( ) Function
Tag Property
Working with Table Indexes
Functions


ATAN( ) Function

Visual FoxPro 9.0 Language Reference
ATAN( ) Function
See Also Example

Returns in radians the arc tangent of a numeric expression.

ATAN(nExpression)

Parameters

nExpression

Specifies a numeric expression whose arc tangent ATAN( ) returns. nExpression can be any value. The value returned by ATAN( ) can range from –pi/2 through +pi/2 (–1.57079 to 1.57079). The number of decimal places displayed in the value returned by ATAN( ) is determined by SET DECIMALS.

Return Value

Numeric

Remarks

Use RTOD( ) to convert radians to degrees.

Example

Copy Code
CLEAR
? ATAN(0)  && Displays 0.00
STORE PI( )/2 to gnAngle
? ATAN(gnAngle)  && Displays 1.00
? ATAN(PI( )/2)  && Displays 1.00
? ATAN(DTOR(90))  && Displays 1.00

See Also

Other Resources

ATN2( ) Function
RTOD( ) Function
SET DECIMALS Command
TAN( ) Function
Creating Numeric Expressions
Functions
Language Reference


ATC( ) Function

Visual FoxPro 9.0 Language Reference
ATC( ) Function
See Also Example

Returns the beginning numeric position of the first occurrence of a character expression or memo field within another character expression or memo field, without regard for the case of these two expressions.

ATC(cSearchExpression, cExpressionSearched [, nOccurrence])

Parameters

cSearchExpression

Specifies the character expression that ATC( ) searches for in cExpressionSearched.
cExpressionSearched

Specifies the character expression cSearchExpression searches for. Both cSearchExpression and cExpressionSearched can be memo fields of any size.
nOccurrence

Specifies which occurrence (first, second, third, and so on) of cSearchExpression is searched for in cExpressionSearched. By default, ATC( ) searches for the first occurrence of cSearchExpression (nOccurrence = 1). Including nOccurrence lets you search for additional occurrences of cSearchExpression in cExpressionSearched.

Return Value

Numeric

Remarks

ATC( ) searches the second character expression for the occurrence of the first character expression, without concern for the case (upper or lower) of the characters in either expression. Use AT( ) to perform a case-sensitive search.

ATC( ) returns an integer corresponding to the position where the first character of the character expression is found. If the character expression isn't found, ATC( ) returns 0.

Example

Copy Code
STORE 'Now is the time for all good men ... ' TO gcString
STORE 'IS THE' TO gcFindString
CLEAR
? ATC(gcFindString, gcString)  && Displays 5
STORE 'is' TO gcFindString
? ATC(gcFindString, gcString)  && Displays 5
? ATC('now',gcString)  && Displays 1

See Also

Other Resources

AT( ) Function
AT_C( ) Function
ATCC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
RAT( ) Function
RATLINE( ) Function
RIGHT( ) Function
SUBSTR( ) Function
LEFTC( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
Functions
Language Reference


ATCC( ) Function

Visual FoxPro 9.0 Language Reference
ATCC( ) Function
See Also

Returns the beginning numeric position of the first occurrence of a character expression or memo field within another character expression or memo field, without regard for the case of these two expressions.

ATCC(cSearchExpression, cExpressionSearched [, nOccurrence])

Parameters

cSearchExpression

Specifies the character expression that ATCC( ) searches for in cExpressionSearched.
cExpressionSearched

Specifies the character expression cSearchExpression searches for. Both cSearchExpression and cExpressionSearched can be memo fields of any size.
nOccurrence

Specifies which occurrence (first, second, third, and so on) of cSearchExpression is searched for in cExpressionSearched. By default, ATCC( ) searches for the first occurrence of cSearchExpression (nOccurrence = 1). Including nOccurrence lets you search for additional occurrences of cSearchExpression in cExpressionSearched.

Return Value

Numeric

Remarks

ATCC( ) is designed for expressions containing double-byte characters. If the expression contains only single-byte characters, ATCC( ) is equivalent to ATC( ).

ATCC( ) searches the second character expression for the occurrence of the first character expression, without concern for the case (upper or lower) of the characters in either expression. Use AT_C( ) to perform a case-sensitive search.

ATCC( ) returns an integer corresponding to the position where the first character of the character expression is found. If the character expression isn't found, ATCC( ) returns 0.

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
RAT( ) Function
RATLINE( ) Function
RIGHT( ) Function
SUBSTR( ) Function
LEFTC( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
Functions
Language Reference


ATCLINE( ) Function

Visual FoxPro 9.0 Language Reference
ATCLINE( ) Function
See Also Example

Returns the line number of the first occurrence of a character expression or memo field within another character expression or memo field, without regard for the case (upper or lower) of the characters in either expression.

ATCLINE(cSearchExpression, cExpressionSearched)

Parameters

cSearchExpression

Specifies the character expression that ATCLINE( ) searches for in cExpressionSearched.
cExpressionSearched

Specifies the character expression cSearchExpression searches for. Both cSearchExpression and cExpressionSearched can be memo fields of any size. Use MLINE( ) to return the line containing the matching character expression.
Tip:
ATCLINE() offers a convenient way to search memo fields.

Return Value

Numeric

Remarks

If the search is successful, ATCLINE( ) returns the number of the line containing the first character expression. If the search is unsuccessful, ATCLINE( ) returns 0.

The line number that ATCLINE( ) returns is determined by the value of SET MEMOWIDTH, even if cExpressionSearched isn't a memo field. For more information, see SET MEMOWIDTH.

Use ATLINE( ) to perform a case-sensitive search.

Example

Example 1 locates the first time a character string occurs in a memo field, displays the first and last names of the employee, and the line of the memo containing the character string.

Example 2 demonstrates how the memo width affects ATCLINE( ).
Copy Code
* Example 1
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE employee  && Open employee table

CLEAR
STORE 'JAPANESE' TO gcFindString  && Case insensitive
LOCATE FOR ATCLINE(gcFindString, notes) != 0
? First_Name
?? Last_Name
? MLINE(notes, ATCLINE(gcFindString, notes))

* Example 2
STORE '1234567890ABCDEFGHIJ' TO gcString
SET MEMOWIDTH TO 20
? ATCLINE('AB', gcString)  && Displays 1
SET MEMOWIDTH TO 10
? ATCLINE('AB', gcString)  && Displays 2

See Also

Other Resources

AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCC( ) Function
ATLINE( ) Function
LEFT( ) Function
RAT( ) Function
RATLINE( ) Function
RIGHT( ) Function
SUBSTR( ) Function
LEFTC( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
MLINE( ) Function
SET MEMOWIDTH Command
Functions
Language Reference


ATLINE( ) Function

Visual FoxPro 9.0 Language Reference
ATLINE( ) Function
See Also Example

Returns the line number of the first occurrence of a character expression or memo field within another character expression or memo field, counting from the first line.

ATLINE(cSearchExpression, cExpressionSearched)

Parameters

cSearchExpression

Specifies the character expression that Microsoft Visual FoxPro looks for in cExpressionSearched.
cExpressionSearched

Specifies the character expression that cSearchExpression searches for. Both cSearchExpression and cExpressionSearched can be memo fields of any size. Use MLINE( ) to return the line containing the matching character expression as a character string.
Tip:
ATLINE() offers a convenient way to search memo fields.

Return Value

Numeric

Remarks

ATLINE( ) searches the second character expression for the occurrence of the first character expression. ATLINE( ) performs a case-sensitive search. Use ATCLINE( ) to perform a search that isn't case-sensitive.

If the search is successful, ATLINE( ) returns the number of the line where the match occurs. If the search is unsuccessful, ATLINE( ) returns 0.

The line number that ATLINE( ) returns is determined by the value of SET MEMOWIDTH, even if cExpressionSearched isn't a memo field. For more information, see SET MEMOWIDTH.

Example

Example 1 locates the first time a character string occurs in a memo field, displays the first and last names of the employee, and the line of the memo containing the character string.

Example 2 demonstrates how the memo width affects ATLINE( ).
Copy Code
* Example 1
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE employee  && Open employee table

CLEAR
STORE 'Japanese' TO gcFindString  && Case sensitive
LOCATE FOR ATLINE(gcFindString, notes) != 0
? First_Name
?? Last_Name
? MLINE(notes, ATLINE(gcFindString, notes))

* Example 2
STORE '1234567890ABCDEFGHIJ' TO gcString
SET MEMOWIDTH TO 20
? ATLINE('AB', gcString)  && Displays 1
SET MEMOWIDTH TO 10
? ATLINE('AB', gcString)  && Displays 2

See Also

Other Resources

AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCC( ) Function
ATCLINE( ) Function
LEFT( ) Function
RAT( ) Function
RATLINE( ) Function
RIGHT( ) Function
SUBSTR( ) Function
LEFTC( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
MLINE( ) Function
SET MEMOWIDTH Command
$ Operator
OCCURS( ) Function
INLIST( ) Function
Functions
Language Reference


ATN2( ) Function

Visual FoxPro 9.0 Language Reference
ATN2( ) Function
See Also Example

Returns the arc tangent in all four quadrants from specified values.

ATN2(nYCoordinate, nXCoordinate)

Parameters

nYCoordinate

Specifies the y coordinate.
nXCoordinate

Specifies the x coordinate.

Return Value

Numeric

Remarks

ATN2( ) returns the angle (in radians) between the line y = 0 and the line connecting the specified coordinates and the origin (0, 0) of the coordinate system.

ATN2( ) returns a value between – pi/2 and +pi/2.

You can convert the value returned by ATN2( ) to degrees with RTOD( ). You can specify the number of decimal places that are displayed in the result with SET DECIMALS.

Example

Copy Code
CLEAR
? PI( )  && Displays 3.14
? ATN2(0,-1)  && Displays 3.14
STORE COS(PI( )) TO gnXCoord
STORE SIN(PI( )) TO gnYCoord
? ATN2(gnYCoord,gnXCoord)  && Displays 3.14
? ATN2(gnYCoord,gnXCoord)/PI( )  && Displays 1.00

See Also

Other Resources

ATAN( ) Function
DTOR( ) Function
RTOD( ) Function
SET DECIMALS Command
TAN( ) Function
Functions
Language Reference


AUSED( ) Function

Visual FoxPro 9.0 Language Reference
AUSED( ) Function
See Also Example

Places table aliases and work areas for a data session into a variable array.

AUSED(ArrayName [, nDataSessionNumber [, cTableName]])

Parameters

ArrayName

Specifies the name of the array containing the table aliases and work areas for a data session. If the array you specify does not exist, Visual FoxPro automatically creates the array. If the array exists and is not large enough to contain all the table aliases and work areas, Visual FoxPro automatically increases the size of the array. If the array is larger than necessary, Visual FoxPro truncates the array. If the array exists, and AUSED( ) returns 0 because no tables are open in the data session, the array remains unchanged. If the array does not exist, and AUSED( ) returns 0, the array is not created.
nDataSessionNumber

Specifies the data session number for which AUSED( ) returns the table aliases and work areas. If you omit nDataSessionNumber, AUSED( ) returns information about the current data session. Use SET DATASESSION to specify the current data session.
cTableName

The array will only contain aliases of the table specified with cTableName. The current data session is used if you set nDataSessionNumber to the null value (.NULL.). cTableName can be in the following formats, listed in the order in which Visual FoxPro searches for tables. DatabaseName!TableName or DatabaseName!ViewName. Path\DatabaseName!TableName or Path\DatabaseName!ViewName. Database container (DBC) defined table name or view in the current DBC in the data session. Simple or full table name.

Return Value

Numeric

Remarks

AUSED( ) returns the number of rows in the array, which is identical to the number of tables open in the data session.

AUSED( ) creates a two-dimensional array and places the aliases of tables open for the data session in the first column of the array. The second column of the array contains the tables' corresponding work area numbers.

The table aliases are placed into the array in reverse order that they were opened in. For example, the first array element contains the alias of the last table opened, and the last array element contains the alias of the first table opened. This ordering is useful when using TABLEUPDATE( ) on views that contain views. For example:

Copy Code
FOR x = 1 TO AUSED(aTableAliases,1)
   IF CURSORGETPROP( "Buffering", aTableAliases(x) ) > 1 && Buffered
      ? TABLEUPDATE( 0, .T., aTableAliases(x) )
   ENDIF
NEXT

Example

The following example uses AUSED( ) to create an array named gaInuse that contains the table aliases and work areas for tables open in the current data session. The number of open tables for the current data session is displayed, and the table aliases and work areas are then displayed.
Copy Code
OPEN DATABASE (HOME(2) + 'Data\testdata') EXCLUSIVE
USE Customer IN 0
CLEAR
? AUSED(gaInuse)
DISPLAY MEMORY LIKE gaInuse
CLOSE DATABASES

See Also

Other Resources

ALIAS( ) Function
SET DATASESSION Command
USE Command
How to: Create and Use Table Aliases
Functions
Language Reference


AVCXCLASSES( ) Function

Visual FoxPro 9.0 Language Reference
AVCXCLASSES( ) Function
See Also Example

Places the information about classes in a class library into an array.

AVCXCLASSES(ArrayName, cLibraryName)

Parameters

ArrayName

Specifies the name of the array in which the class information is placed. If the array you specify doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain the class names and base classes, Visual FoxPro automatically increases the size of the array. If the array is larger than necessary, Visual FoxPro truncates the array. The array contains a row for each class in the class library, and each row contains 11 columns containing information about the class. The following table lists the class information in each column.

Column Class information .VCX field name

1

Class name.

OBJNAME

2

Base class of the class.

BASECLASS

3

Parent class name of the class.

CLASS

4

Relative path and file name of the parent class library.

CLASSLOC

5

Relative path and file name of the bitmap for a custom class icon.

RESERVED4

6

Relative path and file name for a custom Project Manager or Class Browser class icon.

RESERVED5

7

ScaleMode of the class, Pixels or Foxels.

RESERVED6

8

Description of the class.

RESERVED7

9

Relative path and file name for the #INCLUDE file for the class.

RESERVED8

10

User-defined information for the class.

USER

11

Logical true (.T.) if the class is OLEPUBLIC, otherwise logical false (.F.).

RESERVED2
cLibraryName

Specifies the name of the class library for which AVCXCLASSES( ) places class information into the array specified with ArrayName. cLibraryName can contain a path to the class library. An error is generated if the class library you specify doesn't exist.

Return Value

Numeric

Remarks

AVCXCLASSES( ) returns the number of rows in the array (the number of classes in the class library).

Example

The following example uses AVCXCLASSES( ) to create and populate an array named aClasses with the names and base classes of the classes in the Buttons class library. DISPLAY MEMORY lists the contents of the array in the main Visual FoxPro window.
Copy Code
ACTIVATE SCREEN
CLEAR

? AVCXCLASSES(aClasses, '\VFP\SAMPLES\CLASSES\BUTTONS.VCX')
*** Displays 5

FOR nColCount = 1 TO ALEN(aClasses,2) && Loop through columns
   ? aClasses(1, nColCount) && Each column of the 1st class
NEXT

*** Displays the following:
*
* cmdCancel
* commandbutton
* cmdok
* buttons.vcx
* cancel.bmp
* cancel.bmp
* Pixels
* Release Form or Form Set
*
*
* .F.

See Also

Other Resources

ACLASS( ) Function
AGETCLASS( ) Function
AMEMBERS( ) Function
CREATE CLASS Command
Functions
Language Reference


BAR( ) Function

Visual FoxPro 9.0 Language Reference
BAR( ) Function
See Also Example

Returns the number of the most recently chosen item from a menu defined with DEFINE POPUP or a menu item chosen from a Visual FoxPro menu.

BAR( )

Return Value

Numeric

Remarks

Each item on a menu is assigned a number with DEFINE BAR. When a menu item is chosen from the menu, BAR( ) returns the number assigned to that item. A program can branch to other routines based on the value that BAR( ) returns.

BAR( ) returns 0 if there is no active menu or if the user presses ESC to exit the menu.

Example

The following example uses BAR( ) to pass the number of a menu item to a procedure. The current system menu bar is saved to memory with SET SYSMENU SAVE, and then all system menu titles are removed with SET SYSMENU TO.

Two menu titles are created with DEFINE PAD; DEFINE POPUP is used to create a menu for each menu title. DEFINE BAR is used to create items on each menu. When you choose a menu title, ON PAD uses ACTIVATE POPUP to activate the corresponding menu.

When you choose an item from a menu, ON SELECTION POPUP uses BAR( ) and POPUP( ) to pass the item number and menu title to the choice procedure. The choice procedure displays the number of the chosen item and the name of the menu containing the item, and the original Visual FoxPro system menu is restored with SET SYSMENU TO DEFAULT.
Copy Code
*** Name this program BAR_EXAM.PRG ***
CLEAR
SET SYSMENU SAVE
SET SYSMENU TO
DEFINE PAD padConv OF _MSYSMENU ;
   PROMPT '\<Conversions' COLOR SCHEME 3 ;
   KEY ALT+C, ''
DEFINE PAD padCard OF _MSYSMENU ;
   PROMPT 'Card \<Info' COLOR SCHEME 3 ;
   KEY ALT+I, ''
ON PAD padConv OF _MSYSMENU ACTIVATE POPUP popConv
ON PAD padCard OF _MSYSMENU ACTIVATE POPUP popCard
DEFINE POPUP popConv MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF popConv PROMPT 'Ar\<ea' KEY CTRL+E, '^E'
DEFINE BAR 2 OF popConv PROMPT '\<Length' ;
   KEY CTRL+L, '^L'
DEFINE BAR 3 OF popConv PROMPT 'Ma\<ss' ;
   KEY CTRL+S, '^S'
DEFINE BAR 4 OF popConv PROMPT 'Spee\<d' ;
   KEY CTRL+D, '^D'
DEFINE BAR 5 OF popConv PROMPT '\<Temperature' ;
   KEY CTRL+T, '^T'
DEFINE BAR 6 OF popConv PROMPT 'T\<ime' ;
   KEY CTRL+I, '^I'
DEFINE BAR 7 OF popConv PROMPT 'Volu\<me' ;
   KEY CTRL+M, '^M'
*** Here is where the POPCONV menu uses the BAR( ) function
*** to pass a bar number to the procedure called choice below.
ON SELECTION POPUP popConv;
   DO choice IN bar_exam WITH BAR( ), POPUP( )
DEFINE POPUP popCard MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF popCard PROMPT '\<View Charges' ;
   KEY ALT+V, ''
DEFINE BAR 2 OF popCard PROMPT 'View \<Payments' ;
   KEY ALT+P, ''
DEFINE BAR 3 OF popCard PROMPT 'Vie\<w Users' ;
   KEY ALT+W, ''
DEFINE BAR 4 OF popCard PROMPT '\-'
DEFINE BAR 5 OF popCard PROMPT '\<Charges ';
   KEY ALT+C
DEFINE BAR 6 OF popCard PROMPT '\-'
DEFINE BAR 7 OF popCard PROMPT 'E\<xit ';
   KEY ALT+X
*** Here is where the POPCARD menu uses the BAR( ) function
*** to pass a bar number to the procedure called choice below.
ON SELECTION POPUP popCard;
   DO choice IN bar_exam WITH BAR( ), POPUP( )
*** The procedure choice uses the gnBar parameter
*** to contain the value passed by the BAR( ) function.
PROCEDURE choice
PARAMETERS gnBar, gcPopup
WAIT WINDOW 'You chose bar #' + LTRIM(STR(gnBar)) + ;
   ' from popup ' + gcPopup NOWAIT
SET SYSMENU TO DEFAULT

See Also

Other Resources

ACTIVATE POPUP Command
CNTBAR( ) Function
DEFINE BAR Command
DEFINE POPUP Command
GETBAR( ) Function
MRKBAR( ) Function
ON BAR Command
ON SELECTION BAR Command
PRMBAR( ) Function
Functions
Language Reference


BARCOUNT( ) Function

Visual FoxPro 9.0 Language Reference
BARCOUNT( ) Function
See Also

Included for compatibility with dBASE.

See Also

Other Resources

Language Reference


BARPROMPT( ) Function

Visual FoxPro 9.0 Language Reference
BARPROMPT( ) Function
See Also

Included for compatibility with dBASE.

See Also

Other Resources

Language Reference


BETWEEN( ) Function

Visual FoxPro 9.0 Language Reference
BETWEEN( ) Function
See Also Example

Determines whether the value of an expression is inclusively between the values of two expressions of the same type.

BETWEEN(eTestValue, eLowValue, eHighValue)

Parameters

eTestValue

Specifies an expression to evaluate.
eLowValue

Specifies the lower value in the range.
eHighValue

Specifies the upper value in the range.

Return Value

Logical or null. BETWEEN( ) returns True (.T.) if the value of the specified expression is equal to one of the values or greater than the lower value and less than the higher value of the two expressions. Otherwise, BETWEEN( ) returns False (.F.). BETWEEN( ) returns a null value if eLowValue or eHighValue is a null value.

Example

The following example scans the orders table for all records in the order_amt field with values between 950 and 1000 inclusive and displays the cust_id field and the order_amt field.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE orders  && Open order table

CLEAR
SCAN FOR BETWEEN(order_amt,950,1000)
   ? cust_id, order_amt
ENDSCAN

See Also

Other Resources

MAX( ) Function
MIN( ) Function
Functions
Language Reference


BINDEVENT( ) Function

Visual FoxPro 9.0 Language Reference
BINDEVENT( ) Function
See Also Example

Provides ability to execute user code (an object method) when an event occurs.

With the first form of the syntax below, you can use BINDEVENT( ) to bind events, properties, or methods from native Visual FoxPro objects to other Visual FoxPro objects.

With the second syntax variation below, you can bind to Windows Message (Win Msg) events.

Note:
If you want to bind to events from Component Object Model (COM) objects, use the EVENTHANDLER( ) function.

BINDEVENT(oEventSource, cEvent, oEventHandler, cDelegate [, nFlags])
BINDEVENT(hWnd | 0, nMessage, oEventHandler, cDelegate [, nFlags])

Parameters

oEventSource

Specifies the event source, which must be a valid Visual FoxPro object.
hWnd

Specifies the integer handle of the window that receives Windows Messages. If a value of 0 is passed, the specified event (nMessage) is trapped for all windows. You can use the hWnd Property (Visual FoxPro) to bind Windows Messages (events) received by _VFP, _SCREEN and instantiated form. ActiveX controls also have an hWnd property
cEvent

Specifies the name of the event, method, or property you want to bind.
nMessage

Specifies a valid Windows message that is trapped. See MSDN (the Microsoft Developer Network) for information about Windows messages.
oEventHandler

Specifies the object, which must be a valid Visual FoxPro object, handling the event.
cDelegate

Specifies the method, or "delegate", that handles the event for oEventHandler. The delegate method must have the same parameters as the event specified in cEvent. You can call the AEVENTS( ) function to retrieve an object reference to the event source. If the delegate method does not have enough parameters to handle those passed by the event, Visual FoxPro generates an error. When trapping for Windows Message (Win Msg) events, the cDelegate method must include a PARAMETERS statement to accept four parameters that get passed to the method. The format of the parameters is identical to the format of the Windows WindowProc function. See MSDN (the Microsoft Developer Network) for information about the Windows WindowProc function. The method must return an integer value.
nFlags

Specifies an additive bit flag you can set for the event binding operation. The nFlags parameter is ignored when a Windows message event binding is created.

nFlags Bits Event Type Description

0

000

FoxPro object

Call delegate code before event code. (Default)

1

001

FoxPro object

Call event code before delegate code.

2

010

FoxPro object

Do not trigger event (call delegate code) by simple method call.

31

011

FoxPro object

Call event code before delegate code. Do not trigger event (call delegate code) when simple method calls occur.

4

100

Windows Message

Prevents recursion of similar events while user event code is executing.

1If you use an nFlags value of 1, the value returned by a method call to the event is not that of the event, but rather that of the last delegate invoked. The event gets called before any of the delegates, so the return value of the delegate is the remaining value on the stack. Therefore, it is recommended that the delegate method contain the same return value as that of the event itself. In Visual FoxPro, a procedure that has no explicit RETURN statement returns an implicit value of True (.T.). This is an issue only if the event was triggered by method call and not via normal interactive mode or RAISEEVENT( ) call. The following table shows whether an event is raised when Bit 1 is off or on.

Event trigger OFF (Default) ON

Interactive

YES

YES

Programmatic

YES

NO

RAISEEVENT( )

YES

YES

Return Value

Numeric data type. BINDEVENT( ) returns the number of bindings for the object's event.

BINDEVENT( ) always returns 1 when a Windows message event binding is created. No error detection is performed, so if invalid hWnd and nMessage values are specified, 1 is still returned and the binding remains in effect until it is released.

Remarks

You can bind to any valid Visual FoxPro object event, property, or method, including the Access and Assign methods. However, the event and delegate methods must be public, not protected or hidden, members of the class.

You cannot bind to an event with parameters that are passed by reference. Though calling BINDEVENT( ) succeeds, raising the event, for example, using RAISEEVENT( ), fails.

When you bind to a property, you should bind to it directly and not to the Assign method. If you bind directly to the Assign method, be aware that Access and Assign methods are marked as Protected and are not visible except within the class.

Note:
If you bind to a property that has an Assign method, the delegate method might trigger twice. The first time is when the property assignment call is made. The second time is when the property is actually set, within the Assign method, to the parameter that is passed. The delegate method should be aware of this possibility.

Normal rules of inheritance apply. If the delegate method does not contain any code, Visual FoxPro traverses up the parent hierarchy.

An event handler is called when an event occurs or if it is called as a method. Calling the event as a method triggers the event unless you specify an nFlags value of 2 or 3.

By default, Visual FoxPro calls the delegate method before the event. However, you can change the default behavior by using an nFlags setting.

If you specify a property as the event you want to bind, Visual FoxPro binds that property to an implicit Assign method. When the value of that property changes, Visual FoxPro triggers an event.

If an invalid parameter is passed, Visual FoxPro generates the error, "Function argument value, type, or count is invalid." However, if a problem occurs during the binding operation, Visual FoxPro does not generate an error. You can retrieve the return value of BINDEVENT( ) to check the number of bindings.

Certain control events such as GotFocus, LostFocus, InteractiveChange, and ProgrammaticChange do not work if the second bit of the nFlags parameter is set, for example, nFlags set to 2. These events are treated as method calls internally by Visual FoxPro, even though they are considered events. The same behavior applies to the Refresh method of an object on a form that is called when the form's Refresh method is called. Certain events such as When and Valid require code in the event for it to occur.

BINDEVENT( ) does not directly support the Value property because it is handled by Visual FoxPro in a special way. You should use the InteractiveChange and ProgrammaticChange events instead. Additionally, the ActivePage property is not supported.

If the original event contains a NODEFAULT command, Visual FoxPro still processes the event because it is possible that the delegate method is called before the event. NODEFAULT applies only to native Visual FoxPro events.

If you make an exact duplicate BINDEVENT( ) call, Visual FoxPro disregards the call but still returns the number of bindings for the object's event. If you change the nFlags setting, you can call BINDEVENT( ) to rebind the event.

When binding to Windows message (Win Msg) events, only one hWnd to Windows message pairing can exist. You can pass an hWnd value of 0 if you want to bind all windows to the same Windows message event. A Windows message event binding can be released with the UNBINDEVENTS( ) Function and the CLEAR Commands. Also, if the event handler object specified with the oEventHandler parameter no longer exists, the binding is released when its Windows message occurs.

With a Windows message event binding, your user code will execute whenever an event occurs including scenarios in which a modal dialog is displayed. This is because the Window Procedure must always process the message and return. Since it is possible for recursion to occur with an event while your user code is executing, you may want to specify an nFlags value of 4 to prevent this from happening.

Note:
A Windows message event binding should be used with care since your user code is bound to events being triggered by the Windows operating system and these events can occur at times when you do not expect them to.

Example

The following example shows how you can keep the Class Browser positioned to the right side of the Visual FoxPro desktop, regardless of how the desktop is resized. BINDEVENT( ) associates the Resize event of the _SCREEN system variable, or Visual FoxPro desktop, with oHandler, which uses myresize as its delegate. The code for myresize runs when the Resize event is triggered.
Copy Code
PUBLIC oHandler
oHandler=NEWOBJECT("myhandler")
DO (_browser)
BINDEVENT(_SCREEN,"Resize",oHandler,"myresize")

DEFINE CLASS myhandler AS Session
   PROCEDURE myresize
      IF ISNULL(_obrowser) THEN
         UNBINDEVENTS(THIS)
      ELSE
         _obrowser.left = _SCREEN.Width - _obrowser.width
      ENDIF
   RETURN
ENDDEFINE

See Also

Reference

SYS(2325) - WCLIENTWINDOW from Visual FoxPro WHANDLE
SYS(2326) - WHANDLE from a Window's hWnd
SYS(2327) - Window's hWnd from Visual FoxPro WHANDLE

Other Resources

Functions
Event Binding for Visual FoxPro Objects
AEVENTS( ) Function
RAISEEVENT( ) Function
UNBINDEVENTS( ) Function


BINTOC( ) Function

Visual FoxPro 9.0 Language Reference
BINTOC( ) Function
See Also

Converts a numeric value to a binary character representation.

BINTOC(nExpression [, eFlags])

Parameters

nExpression

Specifies the value to convert. For eFlags settings 1, 2 or 4, this value is an integer. Otherwise, the expression data type is based on the eFlags setting.
eFlags

Specifies the length in characters of the returned character string. eFlags determines the value you can specify for nExpression. eFlags can either be numeric or character. The following table lists the permissible values for eFlags and the corresponding range of values for nExpression:

eFlags nExpression Range

1

–128 to 127

2

–32,768 to 32,767

4

–2,147,483,648 to 2,147,483,647

This is default setting.

8

The range of nExpression depends on its type. Only numeric, float, double, and currency data types are supported with this option. See Visual FoxPro Data and Field Types for the ranges of the numeric, float, double, and currency data types.

BINTOC( ) returns 8 bytes for this setting.

F

nExpression is interpreted as a Float Field Type and BINTOC( ) returns 4 bytes.

B

nExpression is interpreted as a Double Field Type and BINTOC( ) returns 8 bytes.

R

Reverses the resulting binary expression.

S

Prevents the sign bit of number from being toggled (BITXOR).
If this parameter is omitted, BINTOC( ) returns a character string composed of four characters.

Return Value

Character. BINTOC( ) returns a binary character expression.

Remarks

The eFlags parameter can either be numeric or character. The 'R' and 'S' settings are additive while the others are mutually exclusive. Character settings can be passed in either upper or lower case (e.g., 'R' or 'r'). The following examples show various uses of the eFlags parameter.

Copy Code
? BINTOC(1,1)
? BINTOC(1000,"2")&& same as BINTOC(1000,2)
? BINTOC($12.34,8)
? BINTOC(1, "4RS")&& same as BINTOC(1,"RS")
? BINTOC(-100, "Fr")

You can use BINTOC( ) to reduce the size of indexes for numeric fields containing integer data by passing a numeric eFlags parameter. For example, a numeric field named nPartCode might contain an integer value from 1 to 32,767, which corresponds to a parts classification code. BINTOC( ) lets you convert the value in the numeric field to a smaller character representation. For example, the following command creates an index with a two-character index key:

Copy Code
INDEX ON BINTOC(nPartCode,2) TAG PartCode

When using BINTOC( ) for an 8 byte index creation, you should use 8 and not "B". For 4 byte results, you should use 4 if nExpression is an integer type. Otherwise, you should use 'F' for floating point type.

BINTOC( ) can also be used when working with Win32 API routines where you might need to convert to or from a Win32 struct member. When used for indexing, BINTOC( ) needs to properly handle negative numbers for the resulting binary expression. This is done by using a BITXOR operation on the high bit. This also means that the most significant byte is first. For Win32 API routines on an Intel platform, the architecture follows the little-endian rule where the least significant byte is stored first (memory location with lowest address). The 'R' and 'S' settings allow you to use BINTOC( ) to work more efficiently with routines that use structs.

See Also

Other Resources

CTOBIN( ) Function
CREATEBINARY( ) Function
Integer Field Type
Functions
Language Reference


BITAND( ) Function

Visual FoxPro 9.0 Language Reference
BITAND( ) Function
See Also Example

Performs a bitwise AND operation on two or more values of Numeric, Varbinary, or Blob type and returns the result. There is a numeric and a binary version of the syntax.

BITAND(nNumericExpression1, nNumericExpression2, ... , nNumericExpression26)
BITAND(BinaryExpression1, BinaryExpression2, ... , BinaryExpression26)

Parameters

nNumericExpression1, nNumericExpression2, ... , nNumericExpression26

Specifies Numeric values to perform the bitwise AND operation.
BinaryExpression1, BinaryExpression2, ... , BinaryExpression26

Specifies Varbinary or Blob values to perform the bitwise AND operation.
Note:
You can specify a maximum of 26 values. The specified values must have the same type. If the specified expressions are not integers, they are converted to integers before performing the operation.

Return Value

Numeric or Varbinary. BITAND( ) returns the result of the bitwise AND operation performed on the specified expressions.

Note:
For Varbinary or Blob values, the return value is calculated as if all values are padded with 0h00 on the right of the value up to the length of the longest value. The appropriate operation is then performed between those values.

Remarks

BITAND( ) compares each bit in eExpressionN to the corresponding bit in eExpressionN+1. If the bits in eExpressionN and eExpressionN+1 are both 1, the corresponding result bit is set to 1; otherwise, the corresponding result bit is set to 0.

The following table shows the result of a bitwise AND operation on corresponding eExpressionN and eExpressionN+1 bits:

eExpressionN bit | eExpressionN+1 bit | Resulting bit
0 | 0 | 0
0 | 1 | 0
1 | 1 | 1
1 | 0 | 0

Example

Copy Code
x = 3  && 0011 binary
y = 6  && 0110 binary

? BITAND(x,y) && Returns 2, 0010 binary

See Also

Other Resources

BITCLEAR( ) Function
BITLSHIFT( ) Function
BITNOT( ) Function
BITOR( ) Function
BITRSHIFT( ) Function
BITSET( ) Function
BITTEST( ) Function
BITXOR( ) Function
Functions
Language Reference


BITCLEAR( ) Function

Visual FoxPro 9.0 Language Reference
BITCLEAR( ) Function
See Also Example

Clears the specified bit in a Numeric, Varbinary, or Blob value by setting it to 0 and returns the resulting value. There is a numeric and a binary version of the syntax.

Note:
If the specified expression is not an integer, it is converted to an integer before performing the operation.

BITCLEAR(nNumericExpression1, nNumericExpression2)
BITCLEAR(BinaryExpression [, nStartBit [, nBitCount]])

Parameters

nNumericExpression1

Specifies the Numeric value to clear the bit in. If the expression is not an integer, it is converted to an integer before setting the bit.
nNumericExpression2

Specifies the bit position in nExpression1 to clear. nExpression2 can range from 0 to 31 with 0 located as the bit to the farthest right.
BinaryExpression

Specifies a Varbinary or Blob expression.
[ nStartBit[, nBitCount]]

Specifies a starting zero-based number of the first bit to perform the operation as nStartBit and the number of bits to perform the operation as nBitCount. If you do not specify nStartBit and nBitCount, the operation applies to all bits in the expression. If you specify nStartBit only, the operation applies to nStartBit only.

Return Value

Numeric, Varbinary, or Blob. BITCLEAR( ) returns the specified expression without specified bit.

Example

Copy Code
x = 7  && 0111 binary
y = 1  && 2nd bit position (0 = 1st bit position)
? BITCLEAR(x,y) && Returns 5, 0101 binary

See Also

Other Resources

BITAND( ) Function
BITLSHIFT( ) Function
BITNOT( ) Function
BITOR( ) Function
BITRSHIFT( ) Function
BITSET( ) Function
BITTEST( ) Function
BITXOR( ) Function
Functions
Language Reference


BITLSHIFT( ) Function

Visual FoxPro 9.0 Language Reference
BITLSHIFT( ) Function
See Also Example

Moves bits in a numeric value to the left by the specified number of positions and returns the resulting value.

Note:
If the specified expressions are not integers, they are converted to integers before performing the operation.

BITLSHIFT(nExpression1, nExpression2)

Parameters

nExpression1

Specifies the numeric value in which to move bits to the left.
nExpression2

Specifies the number of bit positions to move to the left.

Return Value

Numeric. BITLSHIFT( ) returns the specified expression with bits moved by the specified number of positions.

Remarks

BITLSHIFT( ) does not support Varbinary values.

Example

Copy Code
x = 5  && 0101 binary
y = 1  && Shift bits 1 position left

? BITLSHIFT(x,y) && Returns 10, 1010 binary

See Also

Other Resources

BITAND( ) Function
BITCLEAR( ) Function
BITNOT( ) Function
BITOR( ) Function
BITRSHIFT( ) Function
BITSET( ) Function
BITTEST( ) Function
BITXOR( ) Function
Functions
Language Reference


BITNOT( ) Function

Visual FoxPro 9.0 Language Reference
BITNOT( ) Function
See Also Example

Performs a bitwise NOT operation on a value of Numeric, Varbinary, or Blob type and returns the bitwise complement on the specified value. There is a numeric and a binary version of the syntax.

Note:
If the specified expression is not an integer, it is converted to an integer before performing the operation.

BITNOT(nNumericExpression)
BITNOT(BinaryExpression [, nStartBit [, nBitCount]])

Parameters

nNumericExpression

Specifies a Numeric value to perform the bitwise NOT operation.
BinaryExpression

Specifies a Varbinary or Blob value to perform the bitwise NOT operation.
[ nStartBit[, nBitCount]]

Specifies nStartBit as the starting zero-based number of the first bit to perform the operation and nBitCount as the number of bits to perform the operation. If you do not specify nStartBit and nBitCount, the operation applies to all bits in the expression. If you specify nStartBit only, the operation applies to nStartBit only.

Return Value

Numeric, Varbinary, or Blob. BITNOT( ) returns the bitwise complement of the specified expression. In other words, the return value represents the specified expression with each 0 bit changed to 1 and each 1 bit changed to 0.

Example

Copy Code
x = 5  && 0101 binary
? BITNOT(x) && Returns -6

See Also

Other Resources

BITAND( ) Function
BITCLEAR( ) Function
BITLSHIFT( ) Function
BITOR( ) Function
BITRSHIFT( ) Function
BITSET( ) Function
BITTEST( ) Function
BITXOR( ) Function
Functions
Language Reference


BITOR( ) Function

Visual FoxPro 9.0 Language Reference
BITOR( ) Function
See Also Example

Perform a bitwise inclusive OR operation on two or more values of Numeric, Varbinary, or Blob type and returns the result. There is a numeric and a binary version of the syntax.

BITOR(nNumericExpression1, nNumericExpression2, ... , nNumericExpression26)
BITOR(BinaryExpression1, BinaryExpression2, ... , BinaryExpression26)

Parameters

nNumericExpression1, nNumericExpression2, ... , nNumericExpression26

Specifies Numeric values to perform the bitwise inclusive OR operation.
BinaryExpression1, BinaryExpression2, ... , BinaryExpression26

Specifies Varbinary or Blob values to perform the bitwise inclusive OR operation.
Note:
You can specify a maximum of 26 values. The specified values must have the same type. If the specified expressions are not integers, they are converted to integers before performing the operation.

Return Value

Numeric or Varbinary. BITOR( ) returns the result of a bitwise inclusive OR operation on the specified expressions.

Note:
For Varbinary or Blob values, the return value is calculated as if all values are padded with 0h00 on the right of the value up to the length of the longest value. The appropriate operation is then performed between those values.

Remarks

BITOR( ) compares each bit in eExpressionN to the corresponding bit in eExpressionN+1. If either of the bits in eExpressionN and eExpressionN+1 is 1, the corresponding result bit is set to 1; otherwise, the corresponding result bit is set to 0.

The following table shows the result of an inclusive OR operation on corresponding eExpressionN and nExpressionN+1 bits:

eExpressionN bit | eExpressionN+1 bit | Resulting bit
0 | 0 | 0
0 | 1 | 1
1 | 0 | 1
1 | 1 | 1

Example

Copy Code
x = 5  && 0101 binary
y = 6  && 0110 binary

? BITOR(x,y) && Returns 7, 0111 binary

See Also

Other Resources

BITAND( ) Function
BITCLEAR( ) Function
BITLSHIFT( ) Function
BITNOT( ) Function
BITRSHIFT( ) Function
BITSET( ) Function
BITTEST( ) Function
BITXOR( ) Function
Functions
Language Reference


BITRSHIFT( ) Function

Visual FoxPro 9.0 Language Reference
BITRSHIFT( ) Function
See Also Example

Moves bits in a numeric value to the right by the specified number of positions and returns the resulting value.

Note:
If the specified expressions are not integers, they are converted to integers before performing the operation.

BITRSHIFT(nExpression1, nExpression2)

Parameters

nExpression1

Specifies the numeric value in which to move bits to the right.
nExpression2

Specifies the number of bit positions to move to the right.

Return Value

Numeric. BITRSHIFT( ) returns the specified expression with bits moved by the specified number of positions.

Remarks

BITRSHIFT( ) does not support Varbinary values.

Example

Copy Code
x = 5  && 0101 binary
y = 1  && Shift bits 1 position right

? BITRSHIFT(x,y) && Returns 2, 0010 binary

See Also

Other Resources

BITAND( ) Function
BITCLEAR( ) Function
BITLSHIFT( ) Function
BITNOT( ) Function
BITOR( ) Function
BITSET( ) Function
BITTEST( ) Function
BITXOR( ) Function
Functions
Language Reference


BITSET( ) Function

Visual FoxPro 9.0 Language Reference
BITSET( ) Function
See Also Example

Sets a bit to 1 in a value of Numeric, Varbinary, or Blob type and returns the resulting value. There is a numeric and a binary version of the syntax.

Note:
If the specified expression is not an integer, it is converted to an integer before setting the bit.

BITSET(nNumericExpression1, nNumericExpression2)
BITSET(BinaryExpression [, nStartBit [, nBitCount]])

Parameters

nNumericExpression1

Specifies a Numeric value to set the bit.
nNumericExpression2

Specifies the position of the bit in nExpression1 to set to 1. nExpression2 can range from 0 to 31 with 0 as the bit farthest to the right.
BinaryExpression

Specifies a Varbinary or Blob expression.
[ nStartBit[, nBitCount]]

Specifies a starting zero-based number of the first bit to perform the operation as nStartBit and the number of bits to perform the operation as nBitCount. If you do not specify nStartBit and nBitCount, the operation applies to all bits in the expression. If you specify nStartBit only, the operation applies to nStartBit only.

Return Value

Numeric, Varbinary, or Blob. BITSET( ) returns the specified expression with the specified bit set to 1.

Example

Copy Code
x = 5  && 0101 binary
y = 1  && 2nd bit position (0 = 1st bit position)
? BITSET(x,y) && Returns 7, 0111 binary

See Also

Other Resources

BITAND( ) Function
BITCLEAR( ) Function
BITLSHIFT( ) Function
BITNOT( ) Function
BITOR( ) Function
BITRSHIFT( ) Function
BITTEST( ) Function
BITXOR( ) Function
Functions
Language Reference


BITTEST( ) Function

Visual FoxPro 9.0 Language Reference
BITTEST( ) Function
See Also Example

Determines whether a specific bit in a Numeric, Varbinary, or Blob value is set to 1. There is a numeric and a binary version of the syntax.

Note:
If the specified expression is not an integer, it is converted to an integer before performing the operation.

BITTEST(nNumericExpression1, nNumericExpression2)
BITTEST(BinaryExpression, nBitNumber)

Parameters

nNumericExpression1

Specifies the Numeric value to check for the specified bit.
nNumericExpression2

Specifies the bit position in nExpression1 to check. nExpression2 can range from 0 to 31 with 0 as the bit farthest to the right.
BinaryExpression

Specifies a Varbinary or Blob expression to check for the specified bit.
nBitNumber

Specifies a zero-based bit in qExpression. If nBitNumber is out of range of qExpression, Visual FoxPro generates an error.

Return Value

Logical. BITTEST( ) returns True (.T.) if the specified bit is set to 1; otherwise, it returns False (.F.).

Example

The following example uses BITTEST( ) to determine whether a series of integers are even. If an integer is even, the function IsEven returns True (.T.); otherwise, it returns False (.F.).
Copy Code
CLEAR
? '2 even? '
?? IsEven(2)  && Even, .T. returned
? '3 even? '
?? IsEven(3)  && Not even, .F. returned
? '0 even? '
?? IsEven(0)  && Even, .T. returned
? '-13 even? '
?? IsEven(-13)  && Not even, .F. returned

Function IsEven
   PARAMETER nInteger
   RETURN NOT BITTEST(nInteger, 0)

See Also

Other Resources

BITAND( ) Function
BITCLEAR( ) Function
BITLSHIFT( ) Function
BITNOT( ) Function
BITOR( ) Function
BITRSHIFT( ) Function
BITSET( ) Function
BITXOR( ) Function
Functions
Language Reference


BITXOR( ) Function

Visual FoxPro 9.0 Language Reference
BITXOR( ) Function
See Also Example

Perform a bitwise exclusive OR operation on two or more values of Numeric, Varbinary, or Blob type and returns the result. There is a numeric and a binary version of the syntax.

BITXOR(nNumericExpression1, nNumericExpression2 ..., nNumericExpression26)
BITXOR(BinaryExpression1, BinaryExpression2 ..., BinaryExpression26)

Parameters

nNumericExpression1, nNumericExpression2, ... , nNumericExpression26

Specifies Numeric values to perform the bitwise exclusive OR operation.
BinaryExpression1, BinaryExpression2, ... , BinaryExpression26

Specifies Varbinary or Blob values to perform the bitwise exclusive OR operation.
Note:
You can specify a maximum of 26 values. The specified values must have the same type. If the specified expressions are not integers, they are converted to integers before performing the operation. Not applicable for Varbinary input parameters.

Return Value

Numeric or Varbinary. BITXOR( ) returns the result of the bitwise exclusive OR operation performed on the specified expressions.

Note:
For Varbinary or Blob values, the return value is calculated as if all values are padded with 0h00 on the right of the value up to the length of the longest value. The appropriate operation is then performed between those values.

Remarks

BITXOR( ) compares each bit in eExpressionN to the corresponding bit in eExpressionN+1. If the bits in eExpressionN and eExpressionN+1 are the same, the corresponding result bit is set to 0; otherwise, the corresponding result bit is set to 1.

The following table shows the result of an exclusive OR operation on corresponding eExpressionN and eExpressionN+1 bits:

eExpressionN bit | eExpressionN+1 bit | Result bit
0 | 0 | 0
0 | 1 | 1
1 | 0 | 1
1 | 1 | 0

Example

The following example stores a value of 5, which has a binary value of 0101, to variable Var1 and a value of 6, which has a binary value of 0110, to variable Var2. BITXOR( ) returns a value of 3, which has a binary value of 0011.
Copy Code
Var1 = 5  && 0101 binary value
Var2 = 6  && 0110 binary value
? BITXOR(Var1,Var2) && returns 3 (0011 binary value)

See Also

Other Resources

BITAND( ) Function
BITCLEAR( ) Function
BITLSHIFT( ) Function
BITNOT( ) Function
BITOR( ) Function
BITRSHIFT( ) Function
BITSET( ) Function
BITTEST( ) Function
Functions
Language Reference


BOF( ) Function

Visual FoxPro 9.0 Language Reference
BOF( ) Function
See Also Example

Determines whether the record pointer is positioned at the beginning of a table.

BOF([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area number for a table open in another work area.
cTableAlias

Specifies the table alias for a table open in another work area. If the table you want to test for a beginning-of-file condition is open in a work area other than the currently selected work area, use these optional arguments to specify the work area number or table alias for the table. If a table isn't open in the work area you specify, BOF( ) returns false (.F.).

Return Value

Logical

Remarks

Use BOF( ) to test for a beginning-of-file condition for a table. BOF( ) returns true (.T.) if you have tried to move the record pointer to a position before the first record in the table.

Example

The following example opens the customer table and lists the company name one page at a time, starting with the last record in the table. The listing continues until the beginning of the file is reached or until you choose Cancel.
Copy Code
CLOSE DATABASES
CLEAR
OPEN DATABASE (HOME() + "samples\data\testdata")
USE customer
GO BOTTOM
local recCtr, btnValue
recCtr = 0
btnValue = 1
DO WHILE btnValue = 1 AND NOT BOF()
 ? "Company : " + company
 recCtr = recCtr + 1
 if (recCtr % 20) = 0 then
  btnValue =MESSAGEBOX ("Click OK to continue, Cancel to quit.",33)
  clear
 endif
 Skip -1    && Move up one record
ENDDO
=MESSAGEBOX("Listing complete.",48)

See Also

Other Resources

EOF( ) Function
FEOF( ) Function
_FEOF( ) API Library Routine
Functions
Language Reference


CANDIDATE( ) Function

Visual FoxPro 9.0 Language Reference
CANDIDATE( ) Function
See Also Example

Returns true (.T.) if an index tag is a candidate index tag; otherwise, returns false (.F.).

CANDIDATE([nIndexNumber] [, nWorkArea | cTableAlias])

Parameters

nIndexNumber

Specifies the number of the index tag for which CANDIDATE( ) returns the candidate status. CANDIDATE( ) returns the candidate status in the following order as nIndexNumber increases from 1 to the total number of structural compound and independent compound index tags:
  1. Candidate status for each tag in the structural compound index (if one is present) is returned first. The candidate status is returned for the tags in the order in which the tags are created in the structural index.

  2. Candidate status for each tag in any open independent compound indexes is returned last. The candidate status is returned for the tags in the order in which the tags are created in the independent compound indexes.

If you omit nIndexNumber, CANDIDATE( ) checks the master controlling index tag to see if it is a candidate index tag. If there is no master controlling index tag, CANDIDATE( ) returns false (.F.).
nWorkArea

Specifies the work area of the index tag specified with nIndexNumber.
cTableAlias

Specifies the work area of the index tag specified with nIndexNumber. If you omit nWorkArea and cTableAlias, CANDIDATE( ) checks the index tag in the currently selected work area to see if it is a candidate index tag.

Return Value

Logical

Remarks

A candidate index tag is an index tag that can become the primary index tag because it does not contain null or duplicate values.

Example

The following example opens the customer table in the testdata database. FOR ... ENDFOR is used to create a loop in which the candidate status of each index tag in the customer structural index is checked. The name of each structural index tag is displayed with its candidate status.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer     && Open customer table

FOR nCount = 1 TO TAGCOUNT( )
   IF !EMPTY(TAG(nCount))  && Checks for tags in the index
   ? TAG(nCount)  && Display tag name
   ? CANDIDATE(nCount)  && Display candidate status
   ELSE
      EXIT  && Exit the loop when no more tags are found
   ENDIF
ENDFOR

See Also

Other Resources

ALTER TABLE - SQL Command
CREATE TABLE - SQL Command
INDEX Command
PRIMARY( ) Function
Functions
Language Reference


CAPSLOCK( ) Function

Visual FoxPro 9.0 Language Reference
CAPSLOCK( ) Function
See Also Example

Returns the current mode of the CAPS LOCK key or sets the CAPS LOCK key mode on or off.

CAPSLOCK([lExpression])

Parameters

lExpression

Include to turn the CAPS LOCK key on or off. CAPSLOCK(.T.) turns CAPS LOCK on and CAPSLOCK(.F.) turns CAPS LOCK off. A logical value is returned corresponding to the CAPS LOCK setting before CAPSLOCK(.T.) or CAPSLOCK(.F.) is issued.

Return Value

Logical

Remarks

Issuing CAPSLOCK( ) with no argument returns true (.T.) if CAPS LOCK is on, or false (.F.) if CAPS LOCK is off.

Example

The following code stores the state of CAPSLOCK( ) to a system variable. The = command executes the CAPSLOCK( ) function to set CAPS LOCK on. Then the = command executes the CAPSLOCK( ) function to set CAPS LOCK to its previous state.
Copy Code
glOldLock = CAPSLOCK( )     && Save original setting
CAPSLOCK(.T.)     && Turn CAPS LOCK on

*** Perform any number of statements ***

CAPSLOCK(glOldLock)  && Return to original setting

*** or, toggle CapsLock to the opposite value and back ***

CAPSLOCK(!CAPSLOCK( ))
WAIT WINDOW
CAPSLOCK(!CAPSLOCK( ))
WAIT WINDOW
CAPSLOCK(glOldLock)  && Return to original setting

See Also

Other Resources

INSMODE( ) Function
NUMLOCK( ) Function
Functions
Language Reference


CAST( ) Function

Visual FoxPro 9.0 Language Reference
CAST( ) Function
See Also Example

Converts an expression from one data type to another.

CAST(eExpression AS cDataType [(nFieldWidth [, nPrecision])]
   [NULL | NOT NULL])

Parameters

eExpression

Specifies a data expression, usually in a SQL statement, that you want to convert to another data type. eExpression can be a field, calculated field, or other type of expression.
cDataType

Specifies the valid name of or letter representing the target data type name. cDataType can also be an expression that evaluates to a valid data type name or letter representing a valid data type.
Note:
If you specify an expression for cDataType, you must enclose the expression you specify for cDataType with parentheses.

Some field data types require that you specify a value for nFieldWidth, nPrecision, or both. The following table lists values for cDataType and whether nFieldWidth and nPrecision apply.

cDataType Data type nFieldWidth nPrecision

W, Blob

Blob

No

No

C, Char, Character

Character

Yes

No

Y, Currency

Currency

No

No

D, Date

Date

No

No

T, DateTime

DateTime

No

No

B, Double

Double

No

Yes

F, Float

Floating

Yes

Yes

G, General

General

No

No

I, Int, Integer

Integer

No

No

L, Logical

Logical

No

No

M, Memo

Memo

No

No

N, Num, Numeric

Numeric

Yes

Yes

Q, Varbinary

Varbinary

Yes

No

V, Varchar

Varchar

Yes

No
nFieldWidth

Specifies the field width for certain data types. Visual FoxPro disregards nFieldWidth for the following data types: D, T, I, Y, L, M, G, and W. If nFieldWidth is not specified, default values are used, for example, as defined by the CREATE TABLE command.
nPrecision

Specifies the number of decimal place precision for certain data types. Visual FoxPro disregards nPrecision for the following data types: C, D, T, I, Y, L, M, G, V, Q, and W. If nPrecision is not included for the Numeric or Float data type, the default is zero (0), which is no decimal places. If nPrecision is not included for the Double data type, nPrecision defaults to the number of decimal place precision set by the SET DECIMALS command. If nPrecision is not specified for any other data type, default values are used, for example, as defined by the CREATE TABLE command.
NULL | NOT NULL

Specifies whether to permit null values in the field.
Note:
If one or more fields can contain null values, the maximum number of fields the table can contain is reduced from 255 to 254.

If NULL or NOT NULL is not specified, it is inherited from the expression.

Remarks

The following table shows conversions supported by the CAST( ) function. The vertical axis lists the source data type, and the horizontal axis lists the target data type. The following letters describe the level of conversion supported:

  • F - Full conversion without loss of data

  • P - Partial conversion with possible loss of data

  • N - Not supported

Type | C | D | T | N | F | I | B | Y | L | M | G | V | Q | W
C | F | P | P | P | P | P | P | P | P | F | N | F | F | F
D | F | F | F | N | N | N | N | N | N | F | N | F | N | N
T | F | P | F | N | N | N | N | N | N | F | N | F | N | N
N | F | N | N | F | F | P | F | P | P | F | N | F | N | N
F | F | N | N | F | F | P | F | P | P | F | N | F | N | N
I | F | N | N | F | F | F | F | F | P | F | N | F | N | N
B | P | N | N | P | P | P | F | P | P | F | N | P | N | N
Y | F | N | N | P | P | P | F | F | P | F | N | F | N | N
L | F | N | N | F | F | F | F | F | F | F | N | F | N | N
M | P | P | P | P | P | P | P | P | P | F | N | P | P | F
G | N | N | N | N | N | N | N | N | N | N | F | N | N | F
V | P | P | P | P | P | P | P | P | P | F | N | F | P | P
Q | P | N | N | N | N | N | N | N | N | F | N | P | F | F
W | P | N | N | N | N | N | N | N | N | F | F | P | P | F

If you specify decimal precision, conversions between numeric data types, for example, Numeric, Float, Currency, and Double, to Integer data type might result in loss of precision.

For conversions to Character, Varchar, and Varbinary data types, if the specified field width is less than that of the original data, Visual FoxPro truncates values to fit the field width. For conversions to Character data type, if the specified width is greater than that of the original data, Visual FoxPro pads the field with spaces to the right of the value.

Example

The following example uses the SQL SELECT command to retrieve data from the Product_ID field in the Products table from the Visual FoxPro sample database, TestData.dbc. The example uses the CAST( ) function to convert the results returned from the expression unit_Cost * in_Stock, which have Currency type, as a value with Numeric type with a field width of 8 and a decimal precision of 2.
Copy Code
CLEAR ALL
OPEN DATABASE HOME(2) + 'Data\Testdata.dbc'
SELECT Product_ID, CAST(unit_Cost * in_Stock AS Numeric(8,2)) FROM Products

See Also

Other Resources

Functions
Data and Field Types
How to: Choose Data Types
Data Conversion Functions
Data Type Conversion Control


CDOW( ) Function

Visual FoxPro 9.0 Language Reference
CDOW( ) Function
See Also Example

Returns the day of the week from a given Date or DateTime expression.

CDOW(dExpression | tExpression)

Parameters

dExpression

Specifies the date from which CDOW( ) returns the day.
tExpression

Specifies the datetime from which CDOW( ) returns the day.

Return Value

Character

Remarks

CDOW( ) returns the name of the day of the week as a string in proper noun format.

Example

Copy Code
STORE {^1998-02-16} TO gdDate
CLEAR
? CDOW(gdDate)  && Displays Monday

See Also

Other Resources

DAY( ) Function
DOW( ) Function
SET FDOW Command
SET FWEEK Command
SYS( ) Functions Overview
DATETIME( ) Function
Functions
Language Reference


CDX( ) Function

Visual FoxPro 9.0 Language Reference
CDX( ) Function
See Also Example

Returns the names of the open compound index (.cdx) file that has the specified index position number.

CDX(nIndexNumber [, nWorkArea | cTableAlias])

Parameters

nIndexNumber

The following apply to a table with a structural compound index and one or more compound indexes:

nIndexNumber Description

1

Returns the name of the structural index file (which is always the same as the name of the table).

2

Returns the first compound index file name specified in the INDEX clause of USE or in SET INDEX.

3

Returns the second compound index file name, if any, and so on.

Greater than the number of open .cdx files

Returns the empty string.
The following apply to a table with no structural compound index and one or more compound indexes:

nIndexNumber Description

1

Returns the first compound index file name specified in the INDEX clause of USE or in SET INDEX.

2

Returns the second compound index file name, if any, and so on.

Greater than the number of open .cdx files

Returns the empty string.
nWorkArea

Specifies the work area number of a table whose open compound index file names you want CDX( ) to return.
cTableAlias

Specifies the alias of a table whose open compound index file names you want CDX( ) to return. If you omit nWorkArea and cTableAlias, names of compound index files are returned for the table in the currently selected work area.

Return Value

Character

Remarks

The CDX( ) function is identical to the MDX( ) function.

A .cdx (compound) index consists of one physical file containing many index tags. Each index tag is an index order reference for the associated table.

There are two types of .cdx files: standard compound index (.cdx) and structural .cdx. A standard compound index (.cdx) may have a different name from its associated table and can reside in a different directory from its associated table. A table can have multiple compound index files. You open a compound index with the INDEX clause of USE or with SET INDEX.

A structural .cdx must have the same name as its associated table and reside in the same directory. A table can have only one structural index file. Structural .cdx files are automatically opened and updated when the associated table is opened with USE.

CDX( ) ignores any .idx (Microsoft FoxBASE+ and FoxPro 1.0 compatible index) files specified in USE or SET INDEX.

Use TAG( ) to return individual tag names contained in a .cdx, and NDX( ) to return the name of open .idx files.

When SET FULLPATH is ON, CDX( ) returns the path and name of the .cdx. When SET FULLPATH is OFF, CDX( ) returns the drive and name of the .cdx.

Example

The following example opens the customer table in the testdata database. FOR ... ENDFOR is used to create a loop in which the name of each structural index is displayed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer     && Open customer table

CLEAR
FOR nCount = 1 TO TAGCOUNT( )
   IF !EMPTY(TAG(nCount))  && Checks for tags in the index
   ? CDX(nCount)     && Display structural index names
   ELSE
      EXIT  && Exit the loop when no more tags are found
   ENDIF
ENDFOR

See Also

Other Resources

INDEX Command
MDX( ) Function
NDX( ) Function
SET FULLPATH Command
SET INDEX Command
SYS(14) - Index Expression
SYS(21) - Controlling Index Number
SYS(22) - Controlling Tag or Index Name
SYS(2021) - Filtered Index Expression
TAG( ) Function
USE Command
Functions
Language Reference


CEILING( ) Function

Visual FoxPro 9.0 Language Reference
CEILING( ) Function
See Also Example

Returns the next highest integer that is greater than or equal to the specified numeric expression.

CEILING(nExpression)

Parameters

nExpression

Specifies the number whose next highest integer CEILING( ) returns.

Return Value

Numeric

Remarks

CEILING rounds a number with a fractional portion to the next highest integer.

Example

Copy Code
STORE 10.1 TO num1
STORE -10.9 TO num2
? CEILING(num1)  && Displays 11
? CEILING(num2)  && Displays -10
? CEILING(10.0)  && Displays 10
? CEILING(-10.0) && Displays -10

See Also

Other Resources

FLOOR( ) Function
ROUND( ) Function
Creating Numeric Expressions
Integer Field Type
Functions
Language Reference


CHR( ) Function

Visual FoxPro 9.0 Language Reference
CHR( ) Function
See Also Example

Returns the character associated with the specified numeric ANSI code.

CHR(nANSICode)

Parameters

nANSICode

Specifies a number between 0 and 255 whose equivalent ANSI character CHR( ) returns. Use ASC( ) to return the ANSI value for a specified character.

Return Value

Character

Remarks

CHR( ) returns a single character corresponding to the numeric position of the character in the character table of the current code page. CHR( ) can be used to send printer control codes to a printer.

Example

The following example displays the numbers 65 through 75 and uses CHR( ) to display their corresponding character values A through K.
Copy Code
CLEAR
FOR nCOUNT = 65 TO 75
   ? nCount && Display numeric value
   ?? ' ' + CHR(nCount) && Display character
ENDFOR

See Also

Other Resources

ASC( ) Function
INKEY( ) Function
SET ANSI Command
Functions
Language Reference


CHRSAW( ) Function

Visual FoxPro 9.0 Language Reference
CHRSAW( ) Function
See Also Example

Determines whether or not a character is present in the keyboard buffer.

CHRSAW([nSeconds])

Parameters

nSeconds

Specifies the time in seconds that CHRSAW( ) waits before checking the keyboard buffer. The keyboard buffer is checked immediately if you omit nSeconds. Including nSeconds lets you use CHRSAW( ) for a variety of timed activities. For example, your program can close an application if a key hasn't been pressed for a specific number of seconds.

Return Value

Logical

Remarks

CHRSAW( ) returns True (.T.) if a character is present in the keyboard buffer, and False (.F.) if not. CHRSAW( ) doesn't affect the keyboard buffer contents.

Example

In the following example, the system displays a window containing input fields created with @ ... GET commands, and waits 5 seconds for keyboard input. If a key isn't pressed in this time period, CHRSAW( ) returns False (.F.) and the program terminates.
Copy Code
SET TALK OFF
DEFINE WINDOW wEnter FROM 7,10 to 13,70 PANEL
ACTIVATE WINDOW wEnter
@ 1,3 SAY 'Customer: '   GET gcCustomer  DEFAULT SPACE(40)
@ 3,3 SAY 'Address:  '   GET gcAddress  DEFAULT SPACE(40)
WAIT WINDOW 'Waiting for input' NOWAIT
IF NOT CHRSAW(5)
   DEACTIVATE WINDOW wEnter
   CLEAR GETS
ELSE
   READ
   DEACTIVATE WINDOW wEnter
ENDIF
RELEASE WINDOW wEnter
WAIT
CLEAR

See Also

Other Resources

INKEY( ) Function
KEYBOARD Command
READKEY( ) Function
Functions
Language Reference


CHRTRAN( ) Function

Visual FoxPro 9.0 Language Reference
CHRTRAN( ) Function
See Also Example

Replaces each character in a character expression that matches a character in a second character expression with the corresponding character in a third character expression.

CHRTRAN(cSearchedExpression, cSearchExpression, cReplacementExpression)

Parameters

cSearchedExpression

Specifies the expression in which CHRTRAN( ) replaces characters.
cSearchExpression

Specifies the expression containing the characters CHRTRAN( ) looks for in cSearchedExpression.
cReplacementExpression

Specifies the expression containing the replacement characters. If a character in cSearchExpression is found in cSearchedExpression, the character in cSearchedExpression is replaced by a character from cReplacementExpression that's in the same position in cReplacementExpression as the respective character in cSearchExpression. If cReplacementExpression has fewer characters than cSearchExpression, the additional characters in cSearchExpression are deleted from cSearchedExpression. If cReplacementExpression has more characters than cSearchExpression, the additional characters in cReplacementExpression are ignored.

Return Value

Character

Remarks

CHRTRAN( ) translates the character expression cSearchedExpression using the translation expressions cSearchExpression and cReplacementExpression and returns the resulting character string.

Example

Copy Code
? CHRTRAN('ABCDEF', 'ACE', 'XYZ')  && Displays XBYDZF
? CHRTRAN('ABCD', 'ABC', 'YZ')  && Displays YZD
? CHRTRAN('ABCDEF', 'ACE', 'XYZQRST')  && Displays XBYDZF

See Also

Other Resources

CHRTRANC( ) Function
SYS(15) - Character Translation
Creating Character Expressions
STRTRAN( ) Function
Functions
Language Reference


CHRTRANC( ) Function

Visual FoxPro 9.0 Language Reference
CHRTRANC( ) Function
See Also

Replaces each character in a character expression that matches a character in a second character expression with the corresponding character in a third character expression.

CHRTRANC(cSearched, cSearchFor, cReplacement)

Parameters

cSearched

Specifies the expression in which CHRTRANC( ) replaces characters.
cSearchFor

Specifies the expression containing the characters CHRTRANC( ) looks for in cSearched.
cReplacement

Specifies the expression containing the replacement characters. If a character in cSearchFor is found in cSearched, the character in cSearched is replaced by a character from cReplacement that's in the same position in cReplacement as the respective character in cSearchFor. If cReplacement has fewer characters than cSearchFor, the additional characters in cSearchFor are deleted from cSearched. If cReplacement has more characters than cSearchFor, the additional characters in cReplacement are ignored.

Return Value

Character

Remarks

CHRTRANC( ) is designed to facilitate working with expressions that contain double-byte characters. Use CHRTRANC( ) to replace single-byte characters with double-byte characters or double-byte characters with single-byte characters. If the expressions contains only single-byte characters, CHRTRANC( ) is equivalent to CHRTRAN( ) .

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

CHRTRAN( ) Function
STRCONV( ) Function
Creating Character Expressions
Functions
Language Reference


CLEARRESULTSET( ) Function

Visual FoxPro 9.0 Language Reference
CLEARRESULTSET( ) Function
See Also

Clears the marker from a cursor marked by SETRESULTSET( ) in the current data session.

CLEARRESULTSET( )

Return Value

Numeric. CLEARRESULTSET( ) returns the number of the work area for the previously marked cursor or zero (0) if no cursor is marked in the current data session.

Remarks

CLEARRESULTSET( ) is supported in Visual FoxPro and the Visual FoxPro OLE DB Provider. You can use GETRESULTSET( ) in a database container (DBC) stored procedure or send it to the Visual FoxPro OLE DB Provider, assuming that the cursor has been previously opened by the OLE DB Provider.

See Also

Other Resources

SETRESULTSET( ) Function
GETRESULTSET( ) Function
How to: Use Data Sessions
Supported Visual FoxPro Commands and Functions in OLE DB Provider
Functions


CMONTH( ) Function

Visual FoxPro 9.0 Language Reference
CMONTH( ) Function
See Also Example

Returns the name of the month from a given date or DateTime expression.

CMONTH(dExpression | tExpression)

Parameters

dExpression

Specifies the date expression from which CMONTH( ) returns the name of the month.
tExpression

Specifies the DateTime expression from which CMONTH( ) returns the name of the month.

Return Value

Character

Remarks

CMONTH( ) returns the name of the month as a string in proper noun format based on the current resource file you are using and not on the Windows locale. For more information, see Managing Files in an International Application.

Example

Copy Code
? CMONTH(DATE( ))
STORE {^1998-02-16} TO gdDueDate
? 'Your payment was due in ', CMONTH(gdDueDate)
STORE gdDueDate+60 TO gdFinalDate
? 'You must pay by ', CMONTH(gdFinalDate)

See Also

Other Resources

DMY( ) Function
MDY( ) Function
MONTH( ) Function
DATETIME( ) Function
Functions
Language Reference


CNTBAR( ) Function

Visual FoxPro 9.0 Language Reference
CNTBAR( ) Function
See Also Example

Returns the number of menu items on a user-defined menu or the Visual FoxPro system menu.

CNTBAR(cMenuName)

Parameters

cMenuName

Specifies the name of the menu for which CNTBAR( ) returns the number of menu items. For a list of the Visual FoxPro system menu names, see the System Menu Names topic.

Return Value

Numeric

Remarks

If a user-defined menu is created with the PROMPT option in DEFINE POPUP, Visual FoxPro evaluates the number of menu items when you issue ACTIVATE POPUP. For such a menu, CNTBAR( ) returns a meaningful value only after you activate the menu. However, if the menu items in the menu are created with DEFINE BAR, CNTBAR( ) can determine the number of menu items before you issue ACTIVATE POPUP.

Example

In the following program example, named CNTBAR.prg, a menu title is added to the system menu. The menu popEnv is created with four menu items. The program places a mark character by each item when the item is selected. CNTBAR( ) is used within a loop to initially display marks next to the appropriate menu items.
Copy Code
*** You must name this program CNTBAR.PRG ***
CLEAR
SET TALK OFF
DEFINE PAD padEnv OF _MSYSMENU PROMPT 'E\<nvironment';
   KEY ALT+R, 'ALT+R'
ON PAD padEnv OF _MSYSMENU ACTIVATE POPUP popEnv
DEFINE POPUP popEnv MARGIN RELATIVE COLOR SCHEME 4
DEFINE BAR 1 OF popEnv PROMPT '\<Status Bar'
DEFINE BAR 2 OF popEnv PROMPT '\<Clock'
DEFINE BAR 3 OF popEnv PROMPT '\<Extended Video'
DEFINE BAR 4 OF popEnv PROMPT 'St\<icky'
ON SELECTION POPUP popEnv DO enviropop IN cntbar.prg
FOR i = 1 TO CNTBAR('popEnv')
   DO CASE
      CASE PRMBAR('popEnv', i) = 'Status Bar'
         IF _WINDOWS or _MAC
            SET MARK OF BAR i OF popEnv TO SET('STATUS BAR') = 'ON'
         ELSE
            SET MARK OF BAR i OF popEnv TO SET('STATUS') = 'ON'
         ENDIF
      CASE PRMBAR('popEnv', i) = 'Clock'
         SET MARK OF BAR i OF popEnv TO  SET('CLOCK') = 'ON'
      CASE PRMBAR('popEnv', i) = 'Extended Video'
         SET MARK OF BAR i OF popEnv TO  SROW( ) > 25
      CASE PRMBAR('popEnv', i) = 'Sticky'
         SET MARK OF BAR i OF popEnv TO  SET('STICKY') = 'ON'
   ENDCASE
ENDFOR
PROCEDURE enviropop
DO CASE
   CASE PROMPT() = 'Status'
      IF mrkbar('popEnv', BAR( ))
         DO CASE
            CASE _WINDOWS OR _MAC
               SET STATUS BAR OFF
            CASE _DOS
               SET STATUS OFF
            OTHERWISE
         ENDCASE
         SET MARK OF BAR BAR( ) OF popEnv TO .F.
      ELSE
         DO CASE
            CASE _WINDOWS OR _MAC
               SET STATUS BAR ON
            CASE _DOS
               SET STATUS ON
            OTHERWISE
         ENDCASE
         SET MARK OF BAR BAR( ) OF popEnv TO .T.
      ENDIF
CASE PROMPT( ) = 'Clock'
   IF mrkbar('popEnv', BAR( ))
      SET CLOCK OFF
      SET MARK OF BAR BAR( ) OF popEnv TO .F.
   ELSE
      DO CASE
         CASE _WINDOWS OR _MAC
            SET STATUS BAR ON
            SET CLOCK STATUS
         CASE _DOS
            SET CLOCK ON
         OTHERWISE
      ENDCASE
      SET MARK OF BAR BAR( ) OF popEnv TO .T.
   ENDIF
CASE PROMPT( ) = 'Extended Video'
   IF MRKBAR('popEnv', BAR( ))
      SET DISPLAY TO VGA25
      SET MARK OF BAR BAR( ) OF popEnv TO .F.
   ELSE
      SET DISPLAY TO VGA50
      SET MARK OF BAR BAR( ) OF popEnv TO .T.
   ENDIF
CASE PROMPT( ) = 'Sticky'
   IF MRKBAR('popEnv', BAR( ))
      DO CASE
         CASE _WINDOWS OR _MAC
            WAIT WINDOW 'STICKY is always on in this Visual FoxPro version'
         CASE _DOS
            SET STICKY OFF
         OTHERWISE
      ENDCASE
      SET MARK OF BAR BAR( ) OF popEnv TO .F.
   ELSE
      DO CASE
         CASE _WINDOWS OR _MAC
            WAIT WINDOW 'STICKY is always ON in Visual FoxPro'
         CASE _DOS
            SET STICKY ON
         OTHERWISE
      ENDCASE
       SET MARK OF BAR BAR( ) OF popEnv TO .T.
   ENDIF
ENDCASE

See Also

Other Resources

ACTIVATE POPUP Command
CNTPAD( ) Function
CREATE MENU Command
DEFINE BAR Command
DEFINE POPUP Command
GETBAR( ) Function
MRKBAR( ) Function
ON BAR Command
ON SELECTION BAR Command
PRMBAR( ) Function
Functions
Language Reference


CNTPAD( ) Function

Visual FoxPro 9.0 Language Reference
CNTPAD( ) Function
See Also Example

Returns the number of menu titles on a user-defined menu bar or the Visual FoxPro system menu bar.

CNTPAD(cMenuBarName)

Parameters

cMenuBarName

Specifies the name of the menu bar for which CNTPAD( ) returns the number of menu titles.

Return Value

Numeric

Example

The following command uses CNTPAD( ) to display the number of menu titles in the Visual FoxPro system menu bar.
Copy Code
? CNTPAD('_MSYSMENU')

See Also

Other Resources

ACTIVATE MENU Command
CNTBAR( ) Function
CREATE MENU Command
DEFINE PAD Command
DEFINE MENU Command
GETPAD( ) Function
MRKPAD( ) Function
ON PAD Command
ON SELECTION PAD Command
PRMPAD( ) Function
Functions
Language Reference


COMARRAY( ) Function

Visual FoxPro 9.0 Language Reference
COMARRAY( ) Function
See Also

Specifies how to pass arrays to COM objects.

COMARRAY(oObject [, nNewValue])

Parameters

oObject

Specifies an object reference to a COM object.
nNewValue

Specifies how to pass an array to a COM object specified with oObject. The following table lists the settings for nNewValue and how the to pass the array to the COM object.

nNewValue Description

0

The array is a zero-based array and is passed by value.

1

The array is a one-based array and is passed by value. Compatible with earlier versions of Visual FoxPro. (Default)

10

The array is a zero-based array and is passed by reference.

11

The array is a one-based array and is passed by reference.

100

The array is a fixed size array and cannot be redimensioned.

1000

Byte arrays are not converted to strings.
To return the current setting, call COMARRAY( ) without an argument for the nNewValue parameter.

Return Value

Numeric. COMARRAY( ) returns the current setting.

Remarks

Use COMARRAY( ) only when you pass arrays to COM objects using the following syntax:

oComObject.Method(@MyArray)

Note:
If you omit the at sign (@), only the first element of the array passes to the COM object, and COMARRAY( ) has no effect. This behavior is the same as that in earlier versions of Visual FoxPro.

When you use a byte array (VT_UI1) to communicate with a COM server, Visual FoxPro converts the byte array into a string. The additive nValue of 1000 retains the original proper type of the array and does not convert the result to a string.

If a client passes a byte array by reference to a Visual FoxPro COM Server, the Visual FoxPro COM Server must also set the nValue additive to 1000. You can do this by putting the following call in the Init event of the Visual FoxPro COM Server:

Copy Code
COMARRAY(THIS,1000)

The additive nValue of 100 makes it possible for you to prevent redimensioning of an array. You should check for possible errors after calling the server in case the server attempts to redimension the array. The following example shows how to prevent redimensioning of the array. To run this example, first build the class definition into a DLL named "t1.dll".

Copy Code
LOCAL loSvr, laTest
loSvr = NEWOBJECT("t1.arrayhandler")
DIMENSION laTest[10]
laTest=3
? COMARRAY(loSvr,11 + 100)
* The COM server will return an error on the next line of code
* because arrays passed to loSvr will not allow re-dimensioning.
loSvr.RedimensionArray(@laTest,4)
? ALEN(laTest)

DEFINE CLASS ARRAYHANDLER AS CUSTOM OLEPUBLIC
    PROCEDURE RedimensionArray(aArray, nRows)
        DIME aArray[nRows]
    ENDPROC
ENDDEFINE

See Also

Other Resources

Passing Arrays to Automation Servers
COMCLASSINFO( ) Function
CREATEOBJECT( ) Function
GETOBJECT( ) Function
Functions
Language Reference


COMCLASSINFO( ) Function

Visual FoxPro 9.0 Language Reference
COMCLASSINFO( ) Function
See Also

Returns registry information about a COM object such as a Visual FoxPro automation server.

COMCLASSINFO(oObject [, nInfoType])

Parameters

oObject

An object reference to a COM or OLE object.
nInfoType

Specifies the type of information to return. The following table lists the values for nInfoType and the information returned.

nInfoType Information returned

1 (Default)

The object's programmatic identifier (ProgID).A ProgID is a registry entry that can be associated with a CLSID.

2

The object's VersionIndependentProgID.The VersionIndependentProgID associates a ProgID with a CLSID. It is used to determine the latest version of an object application, refers to the application's class, and does not change from version to version.

3

The object's friendly name.

4

The object's class identifier (CLSID). A CLSID is a globally unique identifier that identifies a COM class object.

5

Type of object passed: Return value Description 1 Visual FoxPro object 2 ActiveX Control 3 COM Component 4 OLEBound object (General field)

Return Value

Character

Remarks

COMCLASSINFO( ) returns the empty string if registry information isn't available for the object you specify. Visual FoxPro automation servers are COM objects, both .exe executable files and .dll dynamic link libraries you can create in the Project Manager.

If you create an instance of an ActiveX control by using CREATEOBJECT( ) as in the following code, nInfoType returns 3 (COM Component) rather than 2.

Copy Code
X=CREATEOBJECT("MSComctlLib.treectrl.2")

To return 2 (ActiveX control) you must use the object as such, as in the following code:

Copy Code
ox.addobject("oc","olecontrol","MSComctlLib.treectrl.2")

See Also

Other Resources

COMARRAY( ) Function
CREATE PROJECT Command
CREATEOBJECT( ) Function
GETOBJECT( ) Function
Functions
Language Reference


COMPOBJ( ) Function

Visual FoxPro 9.0 Language Reference
COMPOBJ( ) Function
See Also Example

Compares the properties of two objects and returns True (.T.) if their properties and property values are identical.

COMPOBJ(oExpression1, oExpression2)

Parameters

oExpression1, oExpression2

Specifies the objects to compare. oExpression1 and oExpression2 can be any expressions that evaluate to objects, such as object references, object variables, or object array elements.

Return Value

Logical

Remarks

COMPOBJ( ) returns False (.F.) if an object has a property that the other object doesn't have, or if the objects have identical properties but the values of one or more properties differ.

Example

In the following example, two ListBoxes named lstMyList1 and lstMyList2 and a ComboBox named cmbMyCombo are created. The Name property of each ListBox is displayed.

COMPOBJ( ) is used to compare the properties of the first ListBox with the properties of the ComboBox. Because many of the properties are different, .F. is displayed. COMPOBJ( ) is then used to compare the properties of the first ListBox with the properties of the second ListBox. Because the Names properties are different, .F. is displayed. The second ListBox lstMyList2 is replaced with the first ListBox lstMyList1, and COMPOBJ( ) is used to compare the properties. Because their properties are identical, .T. is displayed.
Copy Code
lstMyList1 = CREATEOBJ('ListBox')  && Creates a ListBox
lstMyList2 = CREATEOBJ('ListBox')  && Creates a second ListBox
cmbMyCombo = CREATEOBJ('ComboBox')  && Creates a ComboBox
lstMyList1.Name = 'list1'
lstMyList2.Name = 'list2'

CLEAR
? lstMyList1.Name  && Displays List1 Name property
? lstMyList2.Name  && Displays List2 Name property

? COMPOBJ(lstMyList1, cmbMyCombo)     && Displays .F.
? COMPOBJ(lstMyList1, lstMyList2)     && Displays .F., different Names
lstMyList2.Name = lstMyList1.Name
? COMPOBJ(lstMyList1, lstMyList2)     && Displays .T., same properties

See Also

Other Resources

CREATEOBJECT( ) Function
DEFINE CLASS Command
GETOBJECT( ) Function
SET CLASSLIB Command
Functions
Language Reference


COMPROP( ) Function

Visual FoxPro 9.0 Language Reference
COMPROP( ) Function
See Also

Sets or returns the behavior setting of a COM object property.

COMPROP(oCOMObject, cProperty [, eValue])

Parameters

oComObject

Specifies a reference to a COM object. cProperty is not case sensitive. You must use the complete name of the COM object. If you do not provide eValue, COMPROP( ) returns the value of cProperty.
cProperty

Specifies the name of the COM property to set. The following table lists possible values of cProperty.

cProperty Description

UTF8

Determines whether UNICODE strings returned from a COM object are converted to ANSI. Conversion is performed by default.

PUTREF

Determines if initial object assignment is PROPERTY_PUT (default) or PUTREF.
eValue

Specifies a value representing behavior to apply to the cProperty. The following table lists values for eValue.

eValue Description

0

Apply default behavior.

1

Apply nondefault behavior as described in the table for cProperty.

For example, setting an eValue of 1 for UTF8 prevents the display of multi-byte characters as question marks. Setting an eValue of 1 for PUTREF causes Visual FoxPro to attempt object assignment as a PUTREF first and, only if that fails, attempt assignment as a PROPERTY_PUT. Object assignments to properties of some ActiveX controls or COM objects requires PUTREF, and Visual FoxPro defaults to PROPERTY_PUT.

Return Value

COMPROP( ) returns the value of cProperty.

Examples

The following example returns data from methods of an ADO recordset as UNICODE instead of allowing conversion to ANSI:

Copy Code
LOCAL oConn AS adodb.Connection, oRS AS adodb.Recordset
LOCAL lcStr AS STRING
oConn=CREATEOBJECT("ADODB.Connection")
oConn.Open("DSN=Nwind;")  && DSN to SQL Server
oRS=oConn.Execute("select * from customers")
COMPROP(oRS,'UTF8',1)
DO WHILE NOT oRS.Eof
   lcStr = oRS.Fields(4).Value
   oRS.MoveNext
ENDDO
oRS.Close()
oRS.ActiveConnection=NULL
oRS=NULL
oConn.Close()
oConn=NULL

In the following example, an ActiveX control is made to use PUTREF rather than PROPERTY_PUT:

Copy Code
=COMPROP(oForm.OLECONTROL1, 'PUTREF',1)

See Also

Other Resources

Functions
DBGETPROP( ) Function
COMARRAY( ) Function


COMRETURNERROR( ) Function

Visual FoxPro 9.0 Language Reference
COMRETURNERROR( ) Function
See Also

Populates the COM exception structure with information that Automation clients can use to determine the source of Automation errors.

COMRETURNERROR(cExceptionSource, cExceptionText)

Parameters

cExceptionSource

Specifies the text for the source of the exception.
cExceptionText

Specifies the text for the description of the exception.

Remarks

COMRETURNERROR( ) allows Visual FoxPro Automation servers to populate the COM exception structure so that Automation clients can determine the cause of an error on the Automation server.

Executing COMRETURNERROR( ) places the specified text in the COM exception structure, aborts executing the current method, and returns control to the client. The Automation server remains in memory and the client can call more Automation server methods.

Visual FoxPro clients can use AERROR( ) to view the text placed on the COM exception structure.

Note:
(For advanced users) COMReturnErrorInfo fills in a COM exception information structure. This is used only for IDispatch (late binding calls). If you call the server via early binding and the client passes a COM exception structure to the server, there is no error mechanism to return the error info unless the client does a QueryInterface on the ISupportsErrorInfo interface.

See Also

Other Resources

AERROR( ) Function
ON ERROR Command
COMCLASSINFO( ) Function
How to: Create Automation Servers
GETINTERFACE( ) Function
Error Messages A-Z
Error Messages by Number
Functions
Language Reference


COS( ) Function

Visual FoxPro 9.0 Language Reference
COS( ) Function
See Also Example

Returns the cosine of a numeric expression.

COS(nExpression)

Parameters

nExpression

Specifies a numeric expression whose cosine COS( ) returns. nExpression can be any value.

Return Value

Numeric

Remarks

COS( ) returns the cosine of nExpression in radians. Use DTOR( ) to convert an angle from degrees to radians. The number of decimal places that COS( ) returns can be specified with SET DECIMALS. The value COS( ) returns ranges between –1 and 1.

Example

Copy Code
CLEAR
? COS(0)  && Displays 1.00
? COS(PI( ))  && Displays -1.00
? COS(DTOR(180))  && Displays -1.00
STORE PI( ) * 3 TO gnAngle
? COS(gnAngle)  && Displays -1.00

See Also

Other Resources

ACOS( ) Function
DTOR( ) Function
RTOD( ) Function
SET DECIMALS Command
SIN( ) Function
Functions
Language Reference


CPCONVERT( ) Function

Visual FoxPro 9.0 Language Reference
CPCONVERT( ) Function
See Also

Converts character or memo fields or character expressions to another code page.

CPCONVERT(nCurrentCodePage, nNewCodePage, cExpression)

Parameters

nCurrentCodePage

Specifies the code page that cExpression is being converted from.
nNewCodePage

Specifies the code page to which cExpression is converted.
cExpression

Specifies the character expression that's converted.

Remarks

Note that CPCONVERT( ) isn't required for normal cross-platform functioning of the product. It is used strictly to access the underlying translation facilities of Visual FoxPro.

For example, if the variable gcCharExpr contains a character that looks like on the Macintosh (in code page 10000) then CPCONVERT( ) will return a character that looks like in Microsoft Windows (code page 1252):

Copy Code
CPCONVERT(10000, 1252, gcCharExpr)

For additional information on code pages and Visual FoxPro's international support, see Code Pages Supported by Visual FoxPro and Developing International Applications.

See Also

Other Resources

CPCURRENT( ) Function
CPDBF( ) Function
MODIFY COMMAND Command
MODIFY FILE Command
SET NOCPTRANS Command
Functions
Language Reference


CPCURRENT( ) Function

Visual FoxPro 9.0 Language Reference
CPCURRENT( ) Function
See Also

Returns the code page setting (if any) in your Visual FoxPro configuration file, or returns the current operating system code page.

CPCURRENT([1 | 2])

Remarks

CPCURRENT( ) returns one of the following:

  • In Visual FoxPro, the current operating system code page if the CODEPAGE configuration item isn't included in your configuration file. In previous versions of FoxPro, 0 is returned if the CODEPAGE configuration item isn't included in your configuration file.

  • The code page number specified in the CODEPAGE configuration item. For example, CPCURRENT( ) returns 852 if the following line is included in your configuration file:

    Copy Code
    CODEPAGE = 852
  • The current operating system code page if you have included the following line in your configuration file:

    Copy Code
    CODEPAGE = AUTO

In Visual FoxPro, CPCURRENT(1) returns the current operating system code page, regardless of your configuration CODEPAGE setting.

CPCURRENT(2) always returns the underlying operating system code page, regardless of your configuration CODEPAGE setting. For example, if you're running Windows, CPCURRENT(2) returns the MS-DOS code page.

For additional information on code pages and Visual FoxPro's international support, see Code Pages Supported by Visual FoxPro and Developing International Applications.

See Also

Other Resources

CPCONVERT( ) Function
CPDBF( ) Function
MODIFY COMMAND Command
MODIFY FILE Command
SET NOCPTRANS Command
Functions
Language Reference


CPDBF( ) Function

Visual FoxPro 9.0 Language Reference
CPDBF( ) Function
See Also

Returns the code page with which an open table has been marked.

CPDBF([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area number.
cTableAlias

Specifies the table alias. Include nWorkArea or cTableAlias to specify a table open in a work area other than the current work area. CPDBF( ) returns 0 if a table isn't open in the work area you specify. If a table doesn't have the alias you specify with cTableAlias, Visual FoxPro generates an error message.

Remarks

DISPLAY STRUCTURE also displays the code page with which an open table has been marked.

For additional information on code pages and Visual FoxPro's international support, see Code Pages Supported by Visual FoxPro and Developing International Applications.

See Also

Other Resources

CPCONVERT( ) Function
CPCURRENT( ) Function
MODIFY COMMAND Command
MODIFY FILE Command
SET NOCPTRANS Command
Functions
Language Reference


CREATEBINARY( ) Function

Visual FoxPro 9.0 Language Reference
CREATEBINARY( ) Function
See Also

Converts character type data created in Visual FoxPro to a binary type character string you can pass to an ActiveX control or automation object.

CREATEBINARY(cExpression)

Parameters

cExpression

Specifies the character expression for which a binary type character string is returned.

Return Value

Character

Remarks

Visual FoxPro character strings can contain binary data. However, an ActiveX control or automation object character string (OLE VT_BSTR type data) cannot contain binary data. An ActiveX control or automation object passes binary data to applications such as Visual FoxPro as an array of VT_UI1 type data.

Visual FoxPro automatically converts binary data passed from an ActiveX control or automation object as an array of VT_UI1 type data to a Visual FoxPro character string. Visual FoxPro internally marks this character string as binary data passed from an ActiveX control or automation object. When the character string is passed back to an ActiveX control or automation object, Visual FoxPro automatically converts the character string to an array of VT_UI1 type data the ActiveX control or automation object expects.

Use CREATEBINARY( ) to convert character type data created in Visual FoxPro to a binary type character string you can pass to an ActiveX control or automation object. The minimum number of characters to which CREATEBINARY( ) can be abbreviated is 7.

For more information about ActiveX controls and automation objects, see Sharing Information and Adding OLE.

See Also

Reference

ActiveX Controls Overview

Other Resources

OLE Bound Control
OLE Container Control
Functions
Language Reference


CREATEOBJECT( ) Function

Visual FoxPro 9.0 Language Reference
CREATEOBJECT( ) Function
See Also Example

Creates an object from a class definition or an Automation-enabled application.

CREATEOBJECT(cClassName [, eParameter1, eParameter2, ...])

Parameters

ClassName

Specifies the class or OLE object from which the new object is created. Visual FoxPro searches for the class or OLE object in the following order:
  1. Visual FoxPro base classes

  2. Classes in the current program

  3. Classes in .vcx class libraries opened with SET CLASSLIB

  4. Classes in procedure files opened with SET PROCEDURE

  5. Classes in the Visual FoxPro program execution chain

  6. The OLE registry if SET OLEOBJECT is ON

OLE objects are created using the following syntax for ClassName:
Copy Code
ApplicationName.Class
For example, to create a Microsoft Excel worksheet (which supports Automation), you can use the following syntax:
Copy Code
x = CREATEOBJECT('Excel.Sheet')
When this code is run, Microsoft Excel is started (if not already running), and a new worksheet is created. A class library can have an alias. To specify an object in a class library with an alias, include the class library alias followed by a period and the object name. Note that ClassName cannot be the Visual FoxPro OLE Container control base class.
eParameter1, eParameter2, ...

These optional parameters are used to pass values to the Init event procedure for the class. The Init event is executed when you issue CREATEOBJECT( ) and allows you to initialize the object.

Return Value

Object

Remarks

Use CREATEOBJECT( ) to create an object from a class definition or an application that supports Automation, and assign a reference to the object to a system variable or array element.

Before you can create an object from a user-defined class, the user-defined class must first be created with DEFINE CLASS, or it must be available in a .vcx visual class library opened with SET CLASSLIB.

Use = or STORE to assign a reference to the object to a system variable or array element. If an object assigned to a system variable or array element is released, the system variable or array element contains the null value. Use RELEASE to remove the system variable or array element from memory.

Example

The following example uses DEFINE CLASS and CREATEOBJECT( ) to create two custom classes named FormChild and FormGrandChild from the Visual FoxPro Form base class. ACLASS( ) is used to create an array named gaNewarray containing the class names, which are then displayed.
Copy Code
CLEAR

* Verify current class library setting
cCurClassLib=SET("CLASSLIB")
IF LEN(ALLTRIM(cCurClassLib))=0
   cCurClassLib="None"
ENDIF

WAIT WINDOW "Current class library is: " + cCurClassLib + CHR(13);
   + "Press any key to continue..."

frmMyForm = CREATEOBJECT("FormGrandChild")

* Create an array
FOR nCount = 1 TO ACLASS(gaNewarray, frmMyForm)
   ? gaNewarray(nCount)  && Display the names of the classes
ENDFOR

RELEASE frmMyForm

* Create FormChild from FORM baseclass
DEFINE CLASS FormChild AS FORM
ENDDEFINE

* Create FormGrandChild from user-defined FormChild class
DEFINE CLASS FormGrandChild AS FormChild
ENDDEFINE

See Also

Other Resources

_BROWSER System Variable
COMCLASSINFO( ) Function
CREATEOBJECTEX( ) Function
DEFINE CLASS Command
GETOBJECT( ) Function
NEWOBJECT( ) Function
RELEASE Command
SET CLASSLIB Command
SET OLEOBJECT Command
Functions
Language Reference


CREATEOBJECTEX( ) Function

Visual FoxPro 9.0 Language Reference
CREATEOBJECTEX( ) Function
See Also Example

Creates an instance of a registered COM object (such as a Visual FoxPro Automation server) on a remote computer.

CREATEOBJECTEX(cCLSID | cPROGID, cComputerName [, cIID])

Parameters

cCLSID| cPROGID

Specifies the CLSID (Class Identifier) or PROGID (Programmatic Identifier) for the COM object to instantiate. If you include a CLSID, the COM object must be registered on the remote server you specify with cComputerName. If you include a PROGID, the COM object must be registered on both the your local computer and the remote computer you specify with cComputerName. Attempting to use a PROGID without first registering the server on your local computer will generate the OLE error Code 0x800401f3, "Invalid Class String." For Visual FoxPro automation servers created on your local machine, you can use the server object CLSID and PROGID properties to determine the local CLSID and PROGID values.
cComputerName

Specifies the remote computer on which the COM object is instantiated. If cComputerName is the empty string, the COM object is instantiated on the local computer or a redirected machine as specified in the registry. cComputerName supports Universal Naming Convention (UNC) names such as "\\myserver" and "myserver," and Domain System Names (DNS) names.
cIID

Specifies the Interface ID GUID of cCLSID | cPROGID when you create an early bound instance of the class. If you pass an empty string as cIID Visual FoxPro attempts to access the default interface (IID) of cCLSID | cPROGID.

Return Value

Object

Example

Copy Code
      x = CREATEOBJECTEX("excel.application","",;
      "{000208D5-0000-0000-C000-000000000046}")
Note:
The following is a valid function call for an excel application object. It will return the excel.application default interface.

Copy Code
      x = CREATEOBJECTEX("excel.application","","")

Remarks

CREATEOBJECTEX( ) returns an object reference to the COM object if it is successfully instantiated. CREATEOBJECTEX( ) cannot be used to instantiate Visual FoxPro classes such as forms – use CREATEOBJECT( ) to instantiate Visual FoxPro classes. Note that you can only abbreviate CREATEOBJECTEX( ) to a minimum of 13 characters, distinguishing it from the CREATEOBJECT( ) function.

When you call certain COM classes with CREATEOBJECT( ) they return "No such interface supported" because they do not support an IDispatch interface. Using the cIID parameter you can now access these classes in your applications.

If you pass an empty string ("") as cIID Visual FoxPro attempts to to get the default interface (IID) of the specified CLSID or PROGID.

Because it supports early binding through cIID, CREATEOBJECTEX( ) can help improve performance by avoiding much of the overhead of IDispatch calls.

CREATEOBJECTEX( ) supports creation of new early-bound objects. However, it is also possible that your Visual FoxPro component is passed an object that you want to call via early-binding. You can use the GETINTERFACE( ) support on existing COM objects.

For additional information about using Visual FoxPro to create Automation servers, see Sharing Information and Adding OLE.

See Also

Other Resources

CLSID Property
CREATEOBJECT( ) Function
ProgID Property
Server Object
GETINTERFACE( ) Function
Functions
Language Reference


CREATEOFFLINE( ) Function

Visual FoxPro 9.0 Language Reference
CREATEOFFLINE( ) Function
See Also

Takes an existing view offline.

CREATEOFFLINE(ViewName [, cPath])

Parameters

ViewName

Specifies the name of the existing view to take offline. The database containing the existing view must be open before you can take the existing view offline.
cPath

Specifies the directory in which the offline view is placed and the name of the offline view.

Return Value

Logical

Remarks

CREATEOFFLINE( ) returns a logical true (.T.) if the existing view is successfully taken offline; otherwise false (.F.) is returned.

An offline view is opened with USE. When an offline view is open, you can append records or make changes to records in the offline view. However, you cannot use the CREATE TRIGGER, INSERT, PACK or ZAP commands in an offline view. After making changes to the offline view, you can update the data on the server with your changes by opening the offline view with USE and including the ONLINE clause.

You cannot refresh the contents of an offline view with data from the server until the offline view has been opened with USE and the ONLINE clause.

Use DROPOFFLINE( ) to take the offline view back online.

See Also

Other Resources

DROPOFFLINE( ) Function
USE Command
CREATE TRIGGER Command
INSERT Command
PACK Command
ZAP Command
Functions
Language Reference


CTOBIN( ) Function

Visual FoxPro 9.0 Language Reference
CTOBIN( ) Function
See Also

Converts a binary character representation to a numeric value.

CTOBIN(cExpression [, cFlags])

Parameters

cExpression

Specifies the binary character representation to convert.
cFlags

If the binary character representation specified with cExpression was generated using an 8 byte data type (currency or double, for example), include cFlags to control the type of value returned by CTOBIN( ).

cFlags Description

1

cExpression is an expression that is 1 byte long.

2

cExpression is an expression that is 2 bytes long.

4

cExpression is an expression that is 4 bytes long.

8

cExpression is an expression that is 8 bytes long.

B

cExpression is a double data type, and must be 8 bytes long.

CTOBIN( ) returns a double data type value. This is the default for an expression that is 8 bytes long.

N

cExpression is a numeric data type, and must be 4 or 8 bytes long.

CTOBIN( ) returns a numeric type value.

Y

cExpression is a currency data type, and must be 8 bytes long.

CTOBIN( ) returns a currency type value.

R

Reverses the binary expression.

S

Prevents the sign bit of number from being toggled (BITXOR).

Return Value

Numeric. CTOBIN( ) returns a numeric value from a binary character expression.

Remarks

The cFlags parameter is a character expression. The 'R' and 'S' settings are additive while the others are mutually exclusive. Character settings can be passed in either upper or lower case (e.g., 'R' or 'r'). Specifying a value of '1', '2' or '4' is not required, but is available as a convenience to provide feedback for the length of cExpression.

The following examples show various uses of the cFlags parameter.

Copy Code
? CTOBIN("A")&& same as CTOBIN("A","1")
? CTOBIN(BINTOC($12.34,"8"),"Y")
? CTOBIN(BINTOC(12.34,"8"),"B")
? CTOBIN(BINTOC(PI(),"BR"),"NRS")

You can use CTOBIN( ) to convert a binary character representation created with BINTOC( ) to its integer value. CTOBIN( ) can also be used when working with Win32 API routines where you might need to convert to or from a Win32 struct member. The 'R' and 'S' settings allow you to use CTOBIN ( ) to work more efficiently with these scenarios.

See Also

Reference

Visual FoxPro Data and Field Types

Other Resources

BINTOC( ) Function
CREATEBINARY( ) Function
Create Small Indexes Using BINTOC( )
Functions


CTOD( ) Function

Visual FoxPro 9.0 Language Reference
CTOD( ) Function
See Also Example

Converts a character expression to a date expression.

CTOD(cExpression)

Parameters

cExpression

Specifies a character expression.

Return Value

Date data type. CTOD( ) returns a Date value.

Remarks

Note:
CTOD() can create ambiguous Date values and generates a compilation error when SET STRICTDATE is set to 2. To create unambiguous Date values, use the DATE( ) function.

Example

The following example uses CTOD( ) to convert Character data to a Date and then performs simple date related actions.
Copy Code
SET CENTURY ON               && Shows the century value.
cDate="01/01/2003"
?CTOD(cDate)               && Returns 01/01/2003 as Date.
?GOMONTH(CTOD(cDate),12)   && Returns 01/01/2004.
?CTOD(cDate)+100            && Returns 04/11/2003.

See Also

Other Resources

DATE( ) Function
SET STRICTDATE Command
TTOD( ) Function
Functions
Language Reference


CTOT( ) Function

Visual FoxPro 9.0 Language Reference
CTOT( ) Function
See Also

Returns a DateTime value from a character expression.

CTOT(cCharacterExpression)

Parameters

cCharacterExpression

Specifies the character expression from which a DateTime value is returned.

Return Value

DateTime data type. CTOT( ) returns a DateTime value from a character expression.

Remarks

Note:
CTOT() can create ambiguous DateTime values and generates a compilation error when SET STRICTDATE is set to 2. To create nonambiguous Date values, use the DATETIME( ) function instead.

Visual FoxPro supports the native SQL Datatypes Datetime and Smalldatetime, which are returned in 24 hour format in SQL XML.

Note:
The CTOT() function does not address the 19 different ways that T-SQL Convert() function returns datetime and smalldatetime values.

To convert date formats from Access, SQL Server, Visual Studio, and XML, you must call the appropriate SET DATE setting to interpret DateTime strings properly. However, if an uppercase T is in the XML date string, Visual FoxPro overrides the current date setting by internally calling SET DATE YMD and restores the current date setting when exiting CTOT( ).

Note:
CTOT( ) resolves these dates to the limits of precision of the Visual FoxPro DateTime data type. Therefore, precision can be lost when using CTOT( ) with certain formats. The Visual FoxPro DateTime data type does not support milliseconds or time zones.

CTOT( ) respects the setting of the SET CENTURY command. For more information, see SET CENTURY Command.

Examples

The following examples show how CTOT( ) handles DateTime values from different sources. In all examples, CTOT( ) converts the DateTime values correctly without needing to call SET DATE YMD.

  • Access 2000 XML date format

    Copy Code
    * 2000-10-24T13:30:00 (24-hour format is exported from Access,
* whether original was in 12- or 24-hour format)
? CTOT("2000-10-24T13:30:00")
  • SQL Server 2000 XML date format

    Copy Code
    ? CTOT("2000-10-24T20:47:58.170")   && datetime (24-hour format)
? CTOT("2000-10-24T21:11:00")         && Small DT (24-hour format)
? CTOT("2000-10-03T02:02:02")
  • Visual Studio XML

    Copy Code
    ? CTOT("2002-10-05T04:04:04.0000000-07:00")
  • Simple Object Access Protocol (SOAP)

    Copy Code
    ? CTOT("2001-09-14T07:00:00Z")

See Also

Other Resources

DATETIME( ) Function
SET STRICTDATE Command
Functions
Language Reference


CURDIR( ) Function

Visual FoxPro 9.0 Language Reference
CURDIR( ) Function
See Also Example

Returns the current directory.

CURDIR([cExpression])

Parameters

cExpression

Specifies the drive or volume for which CURDIR( ) returns the current directory or folder. If you omit cExpression, the current default drive or volume is assumed. The empty string is returned if the drive or volume you specify in cExpression doesn't exist. Note that this argument is only included for earlier versions of Visual FoxPro and FoxPro running under Window 3.1 or MS-DOS.

Return Value

Character

Remarks

CURDIR( ) returns, as a character string, the current MS-DOS directory on a specified drive.

Example

The following example stores the current directory to a variable, sets the default to the directory Visual FoxPro was started in, displays the new directory, returns the default to the original directory, and displays the original directory.
Copy Code
CLEAR
? 'Current directory: ', CURDIR( )
gcOldDir = SET('DEFAULT') + SYS(2003)
SET DEFAULT TO (HOME( ))
? 'Visual FoxPro directory: ', CURDIR( )
SET DEFAULT TO (gcOldDir)
? 'Current directory: ', CURDIR( )

See Also

Other Resources

FULLPATH( ) Function
HOME( ) Function
SYS(2003) - Current Directory
Functions
Language Reference


CURSORGETPROP( ) Function

Visual FoxPro 9.0 Language Reference
CURSORGETPROP( ) Function
See Also Example

Retrieves the current property settings for a Visual FoxPro table or a cursor.

Tip:
To set a specific property for a Visual FoxPro table or a cursor, use CURSORSETPROP( ). For additional information about each of the properties and their settings, see CURSORSETPROP( ).

CURSORGETPROP(cProperty [, nWorkArea | cTableAlias])

Parameters

cProperty

Specifies the property setting to retrieve. The following table includes a list of properties whose settings can be returned, the data type of the return value, and a description of the return value.

cProperty Type Description

ADOBookmark

Variant

Contains a value that corresponds to an ADO Bookmark for the current record in an ADO-based cursor.

ADOCodePage

N

Returns the code page bound to an ADO-based cursor as specified by the ADOCodePage Property. Read-only.

ADORecordset

O

Contains an object reference to the ActiveX Data Object (ADO) Recordset associated with the cursor. Not valid for cursors that are not based on ADO Recordsets. Read-only.

AllowSimultaneousFetch

L

Applies when using remote views, a shared connection, and to cursors created using ODBC.

AllowSimultaneousFetch contains True (.T.) when similarly configured cursors sharing the connection are permitted to fetch rows simultaneously.

Otherwise, AllowSimultaneousFetch contains False (.F.) when fetching rows simultaneously is not permitted.

AutoIncError

L

Contains True (.T.) when attempts to insert or update a value in a field that uses automatically incrementing field values generate an error message.

Contains False (.F.) when attempts to insert or update a value in a field that uses automatically incrementing field values does not generate an error message and the specified value to be inserted or updated is disregarded.

Applies to cursors and sessions.

Read/write.

BatchUpdateCount*

N

Contains the number of update statements sent to the remote data source for buffered tables. The default value is 1. Adjusting this value can greatly increase update performance.

Read/write.

Buffering

N

1 – Row and table buffering is off. (Default)

2 – Pessimistic row buffering is on.

3 – Optimistic row buffering is on.

4 – Pessimistic table buffering is on.

5 – Optimistic table buffering is on.

Read/write.

CompareMemo

L

Contains True (.T.) if WHERE clause for updates includes memo fields of type Memo, General, or Picture. (Default).

Otherwise, contains False (.F.).

For views only.

Read/write.

ConnectHandle

N

The connection handle. This property is valid only when the data source contains a remote table. The connection handle obtained for a view might close when the view closes.

Read-only.

ConnectName

C

The connection name used when the cursor is created. This property is valid only when the data source contains a remote table.

Read-only.

Database

C

The name of the database that contains the table or view. If a table is a free table, Database contains an empty string.

Read-only.

FetchAsNeeded

L

If True (.T.), data is fetched only when needed, such as when record pointer moves to a row that has not been fetched.

If False (.F.), additional data is fetched during idle time. (Default)

Note:
FetchAsNeeded does not apply when progressive fetching is disabled (FetchSize is -1).

Read/write.

FetchIsComplete

L

If True (.T.), the fetch process is complete for an ODBC or ADO-based cursor.

If False (.F.), the fetch process has not been completed.

This option is not supported for tables and local views or on the environment level (work area 0).

FetchMemo*

L

Contains True (.T.) if memo fields are fetched with the view results. Otherwise, contains False (.F.). (Default).

Use the ISMEMOFETCHED( ) Function to determine if the memo field has been fetched.

Read/write.

FetchSize*

N

Contains the number of rows fetched at a time from the remote tables. The default is 100 rows. Setting FetchSize to –1 retrieves the complete result set, limited by the MaxRecords setting.

Note:
Progressive fetching holds the connection until all rows are retrieved. Use caution coding with FetchSize if ShareConnection is True (.T.).

Read/write.

KeyFieldList

C

A comma delimited list of primary fields for the cursor.

Read/write.

MapBinary

L

Contains True (.T.) if Varbinary mapping is turned on. Otherwise, contains (.F.).

Read/write for nWorkArea set to 0 only. Read-only for SQL Pass-Through cursors. Invalid for table cursors (nWorkArea equal to or greater than 1).

MapVarchar

L

Contains True (.T.) if Varchar mapping is turned on. Otherwise, contains False (.F.).

Read/write for nWorkArea set to 0 only. Read-only for SQL Pass-Through cursors. Invalid for table cursors (nWorkArea equal to or greater than 1).

MaxRecords*

N

The maximum number of rows fetched when result sets are returned. The default value is – 1 (all rows are returned). A value of 0 specifies that the view is executed but no results are fetched.

Read/write.

ParameterList

C

A semi-colon delimited list of view parameters and parameter types. For views only.

Read/write.

Prepared

L

Contains True (.T.) if SQL statements are prepared for subsequent REQUERY( ) function calls. Otherwise, contains False (.F.). (Default).

REQUERY( ) is used to retrieve data again for a SQL view. See SQLPREPARE( ) for additional information about preparing SQL statements. For views only.

Read/write.

RecordsFetched

N

Contains a numeric value that indicates the number of records fetched from the data source for an ODBC or ADO-based cursor.

This numeric value may not reflect the current record count for the cursor if records were locally deleted or appended.

This option is not supported for tables and local views or on the environment level (work area 0).

Note:
Any filter conditions are ignored in the record count.

Read-only.

Refresh

N

Contains a numeric value that indicates the refresh setting for an individual cursor in the current data session or an initial refresh value for newly opened cursors in the current data session.

SendUpdates

L

Contains True (.T.) if a SQL update query is sent to update tables when an update is made using the view; otherwise, contains false (.F.) (default).

Read/write.

SourceName

C

Contains the long name for a SQL view or a table in a database, or the file path and table name for a free table.

Read-only.

SourceType

N

1 – The data source is a local SQL view.

101 (1 + 100) - Cursor is created by the CursorFill method.

201 (1 + 200) - Cursor is attached to a CursorAdapter object using the CursorAttach method.

2 – The data source is a remote SQL view.

102 (2 + 100) - Cursor is created by CursorFill.

202 (2 + 200) - Cursor is attached to a CursorAdapter object using CursorAttach.

3 – The data source is a table.

103 (3 + 100) - Cursor is created by CursorFill.

203 (3 + 200) - Cursor is attached to a CursorAdapter object using CursorAttach.

4 - The cursor is based on ADO Recordset and attached to a CursorAdapter object.

104 (4 + 100) - Cursor is created by CursorFill.

204 (4 + 200) - Cursor is attached to a CursorAdapter object using CursorAttach.

Read-only.

SQL

C

The SQL statement executed when the cursor is created.

Read-only.

Tables

C

A comma delimited list of the names of tables.

Read/write.

UpdatableFieldList

C

A comma delimited list of fields in the view. This list can include fields from local and remote tables.

Read/write.

UpdateNameList

C

A comma delimited list of remote field names and the local field names assigned to the cursor. Use this option to specify valid Visual FoxPro names for fields in the cursor that have invalid Visual FoxPro field names.

Read/write.

UpdateType

N

1 – Specifies that old data is updated with the new data. (Default).

2 – Specifies that updates occur by deleting the old data and inserting the new data.

Read/write.

UseMemoSize*

N

The minimum size, in bytes, for result columns to return in memo fields. For example, if the width of a column result is greater than the value of UseMemoSize, the column result is stored in a memo field. UseMemoSize may vary from 1 to 255; the default value is 255.

Read/write.

WhereType

N

The WHERE clause for updates to tables. WhereType can specify the following values:

1 or DB_KEY (from FOXPRO.H). The WHERE clause used to update tables consists of only the primary fields specified with the KeyFieldList property.

2 or DB_KEYANDUPDATABLE (from FOXPRO.H). The WHERE clause used to update tables consists of the primary fields specified with the KeyFieldList property and any updatable fields.

3 or DB_KEYANDMODIFIED (from FOXPRO.H) (default). The WHERE clause used to update tables consists of the primary fields specified with the KeyFieldList property and any other fields that are modified.

4 or DB_KEYANDTIMESTAMP (from FOXPRO.H). The WHERE clause used to update tables consists of the primary fields specified with the KeyFieldList property and a comparison of the time stamps.

Read/write.
* The value returned by this property is significant only for remote views; if you get this property for local views, the CURSORGETPROP( ) function returns the default value. The following table includes a list of properties whose settings can be returned, the data type of the return value, and a description of the return value.
nWorkArea

Specifies the work area of the table or cursor from which the property setting is returned. If you specify 0 for nWorkArea, CURSORGETPROP( ) returns the environment setting.
cTableAlias

Specifies the alias of the table or cursor from which the property setting is returned.

Return Value

Character, Numeric, or Logical data type

Remarks

The current property settings are returned for the table or cursor open in the currently selected work area if CURSORGETPROP( ) is issued without the optional cTableAlias or nWorkArea arguments. If you use CURSORGETPROP( ) without a table selected, a cursor open, or an alias specified, you get Error 52 (No table is open in current work area.) unless a work area is specified as in this example, CURSORSETPROP("Refresh",-2,0).

Example

When a cursor is opened, the default value for the AutoIncError property is read from the session default value, which is the current default data session setting. The following example shows how you can retrieve the default AutoIncError value for each session by specifying 0 (default session) as the last parameter:

Copy Code
CURSORGETPROP("AutoIncError", 0)

The default session is used when opening a new private data session or cursor. The following example shows how you can retrieve the cursor or table AutoIncError setting for each table by using the nWorkArea or cTableAlias parameter as the last parameter:

Copy Code
CURSORGETPROP("AutoIncError", nWorkArea | cTableAlias)

The following example opens a "Customer" table in the "Testdata" database and uses CURSORGETPROP( ) to display the buffering mode for the table and the name of the database in which the table is contained:

Copy Code
CLOSE DATABASES
CLEAR

OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer     && Open customer table

? CURSORGETPROP("Buffering") && Displays buffering mode
? CURSORGETPROP("Database")  && Displays database name

See Also

Reference

ISMEMOFETCHED( ) Function

Other Resources

CURSORSETPROP( ) Function
SQLGETPROP( ) Function
SQLSETPROP( ) Function
Functions
Language Reference


CURSORSETPROP( ) Function

Visual FoxPro 9.0 Language Reference
CURSORSETPROP( ) Function
See Also Example

Specifies property settings for a Visual FoxPro table or a cursor.

CURSORSETPROP( cProperty [, eExpression] [,cTableAlias | nWorkArea])

Parameters

cProperty

Specifies the table or cursor property to set. Buffering is the only property you can specify for a Visual FoxPro table.
eExpression

Specifies the value for the property you specify with cProperty. If you omit eExpression, the property is set to its default value. The following table lists the properties you can specify for cProperty and a description of the values eExpression can assume.

Property eExpression values

AllowSimultaneousFetch

Applies when using remote views, a shared connection, and to cursors created using ODBC.

.T. - Permit similarly configured cursors sharing the connection to fetch rows simultaneously.

.F. - Do not permit similarly configured cursors sharing the connection to fetch rows simultaneously.

AutoIncError

.T. - Generate an error message when attempting to insert or update values in a field that uses automatically incrementing field values.

.F. - Does not generate an error message but does not use the value specified when attempting to insert or update the value in a field that uses automatically incrementing field values, which uses the appropriate incremented value.

Applies to cursors and sessions.

BatchUpdateCount*

Specifies the number of update statements to send to the remote data source for buffered tables. The default value is 1. Adjusting this value can greatly increase update performance when using automatic updating.

Buffering

1 – Sets row and table buffering off. Record locking and data writing are identical to earlier FoxPro versions. (Default)

2 – Sets pessimistic row buffering on.

3 – Sets optimistic row buffering on.

4 – Sets pessimistic table buffering on.

5 – Sets optimistic table buffering on. SET MULTILOCKS must be ON for all Buffering modes except 1 (off).

CompareMemo

.T. - Include memo fields of type Memo, General, or Picture in the WHERE clause for updates.

.F. – Do not include memo fields in the WHERE clause for updates.

Applies when automatic updating is used.

FetchAsNeeded

.T. – Fetch records only when needed, such as when record pointer moves to a row that has not been fetched.

.F. – Fetch additional data during idle time.

Note:
FetchAsNeeded does not apply when progressive fetching is disabled (FetchSize is -1).

FetchMemo*

.T. – Fetch memo fields with the view results.

.F. – Do not fetch memo fields with the view results.

FetchSize*

Specifies the number of rows progressively fetched from the remote table result set. The default value is 100 rows. Setting FetchSize to –1 retrieves the complete result set, limited by the MaxRecords setting.

Note:
Progressive fetching holds the connection until all rows are retrieved. Use caution coding with FetchSize if ShareConnection is True (.T.).

KeyFieldList

Specifies a comma-delimited list of primary fields for the cursor. No default. You must include a list of field names for updates to work when using automatic updating.

MapBinary

.T. - At the session level, SQL Pass-Through maps SQL_BINARY, SQL_VARBINARY, and SQL_LONGVARBINARY ODBC types to Varbinary or Blob data type.

For remote views, the CREATE SQL VIEW command maps the SQL_LONGVARBINARY ODBC data source type to Blob type, and it maps SQL_BINARY and SQL_VARBINARY ODBC data source types to Varbinary type when the precision of the corresponding column in the data source is less than or equal to 254 bytes. When precision is greater than 254 bytes, these types map to Blob type.

.F. - SQL Pass-Through maps SQL_BINARY and SQL_VARBINARY ODBC types to Character type. (Default)

For remote views, the CREATE SQL VIEW command maps SQL_BINARY and SQL_VARBINARY ODBC data source types to Memo type.

Note:
MapBinary is read/write for nWorkArea set to 0, read-only for SQL Pass-Through cursors, and invalid for table cursors (nWorkArea equal to or greater than 1).

MapVarchar

.T. - At the session level, SQL Pass-Through maps SQL_WVARCHAR and SQL_VARCHAR ODBC types to Varchar type.

For remote views, CREATE SQL VIEW command maps SQL_WVARCHAR and SQL_VARCHAR ODBC data source types to Varchar type.

.F. - SQL Pass-Through maps SQL_WVARCHAR and SQL_VARCHAR ODBC types to Character type. (Default)

For remote views, CREATE SQL VIEW command maps SQL_WVARCHAR and SQL_VARCHAR ODBC data source types to Character type.

Note:
MapVarchar is read/write for nWorkArea set to 0, read-only for SQL Pass-Through cursors, and invalid for table cursors (nWorkArea equal to or greater than 1).

MaxRecords*

Specifies the maximum number of rows fetched when returning result sets. The default value is – 1, and all rows are returned. A value of 0 specifies that the view is executed but no results are fetched.

ParameterList

Specifies a semi-colon delimited list of view parameters and parameter types. For views only.

Prepared

.T. - Prepare SQL statements for subsequent REQUERY( ) function calls.

.F. - Do not prepare SQL statements for subsequent REQUERY( ) calls. (Default).

REQUERY( ) is used to retrieve data again for a SQL view. For additional information about preparing SQL statements, see SQLPREPARE( ) Function.

Refresh

Specifies a numeric refresh value for an individual cursor in the current data session or an initial refresh value for newly opened cursors in the current data session.

Use the SET DATASESSION Command to select a specific data session, and use the cTableAlias or nWorkArea parameter to specify a specific cursor. Use nWorkArea = 0 to change the initial refresh value for all newly opened cursors. Any cursors that are already open will not be affected by the new refresh setting.

SET REFRESH Command allows you to specify a global refresh value. By default, the CURSORSETPROP( ) Refresh setting is -2, which indicates that the current global SET REFRESH value is used. The global SET REFRESH value is specified with its second parameter, nSeconds2.

You can set the CURSORSETPROP( ) Refresh setting to the same values as the nSeconds2 parameter in SET REFRESH.

Note The CURSORSETPROP( ) Refresh setting will be ignored if the nSeconds2 parameter is currently set to zero in the SET REFRESH command.

SendUpdates

.T. – Specifies that a SQL update query is sent to update tables when an update is made using the view.

.F. – Specifies that a SQL update query is not sent to update tables.

Tables

Specifies a comma-delimited list of the names of remote tables. No default. You must include a list of table names for updates to work when using automatic updating.

UpdatableFieldList

Specifies a comma-delimited list of fields in the view. This list can include fields from local and remote tables. You must include a list of fields for updates to work when using automatic updating.

UpdateNameList

Specifies a comma-delimited list of remote field names and the local field names assigned to the cursor. Use this option to specify valid Visual FoxPro names for fields in the cursor that have invalid Visual FoxPro field names.

UpdateType

1 – Update old data with new data. (Default)

2 – Update by deleting old data and inserting new data.

UseMemoSize*

Specifies the minimum size in bytes for result columns to return in memo fields. For example, if the width of a column result is greater than the value of UseMemoSize, the column result is stored in a memo field. UseMemoSize can vary from 1 to 255 bytes. The default value is 255 bytes.

WhereType

The WHERE clause for updates to remote tables. WhereType can assume the following values:

1 or DB_KEY (from FOXPRO.H). The WHERE clause used to update remote tables consists of only the primary fields specified with the KeyFieldList property.

2 or DB_KEYANDUPDATABLE (from FOXPRO.H). The WHERE clause used to update remote tables consists of the primary fields specified with the KeyFieldList property and any updatable fields.

3 or DB_KEYANDMODIFIED (from FOXPRO.H). The WHERE clause used to update remote tables consists of the primary fields specified with the KeyFieldList property and any other fields that are modified. (Default)

4 or DB_KEYANDTIMESTAMP (from FOXPRO.H). The WHERE clause used to update remote tables consists of the primary fields specified with the KeyFieldList property and a comparison of the time stamps.
* This property is primarily used for remote views; setting it has no effect on local views. However, you can preset this property for local views that will be upsized.
cTableAlias

Specifies the alias of the table or cursor for which the property is set.
nWorkArea

Specifies the work area of the table or cursor for which the property is set. If you specify 0 for nWorkArea, CURSORSETPROP( ) sets the environment setting used for all subsequent tables or cursors.
Note:
Buffering is not applied to tables that are opened implicitly, for example, using SQL INSERT/UPDATE/DELETE commands.

Return Value

Logical data type. CURSORSETPROP( ) returns True (.T.) if Visual FoxPro successfully sets the property you specify. Visual FoxPro generates an error if the property you specify cannot be set.

Remarks

The setting of the Buffering property for CURSORSETPROP( ) determines how Visual FoxPro performs record locking and update buffering. For additional information about record locking and update buffering, see How to: Buffer Data.

The setting of the WhereType property for CURSORSETPROP( ) determines how updates are performed on remote tables. For additional information about remote table updates, see Developing Databases.

You can use CURSORSETPROP( ) to override the FetchSize property in the SQLSETPROP( ) function for a cursor. This property is inherited from the cursor's connection handle by default.

Use CURSORGETPROP( ) to return the current property settings for a Visual FoxPro table or a cursor created for a table.

If CURSORSETPROP( ) is issued without the optional cTableAlias or nWorkArea arguments, the property setting is specified for the open table or cursor in the currently selected work area.

Example

When a cursor is opened, the default value for the AutoIncError property is read from the session default value, which is the current default data session setting. The following example shows how you can set the default AutoIncError value for each session by specifying 0 (default session) as the last parameter:

Copy Code
CURSORSETPROP("AutoIncError", .T., 0)

The default session is used when opening a new private data session or cursor. The following example shows how you can set the cursor or table AutoIncError setting for each table by using the cTableAlias or nWorkArea parameter as the last parameter:

Copy Code
CURSORSETPROP("AutoIncError", .F. , cTableAlias | nWorkArea )

The following example demonstrates how you can enable optimistic table buffering with CURSORSETPROP( ). MULTILOCKS is set to ON, a requirement for table buffering. The "Customer" table in the "testdata" database is opened, and CURSORSETPROP( ) is used to set the buffering mode to optimistic table buffering (5). A message box is displayed showing the result of the operation.

Copy Code
CLOSE DATABASES
CLEAR

SET MULTILOCKS ON
OPEN DATABASE (HOME(2) + 'data\testdata')
USE Customer     && Open Customer table.

* Set buffering mode and store logical result
lSuccess=CURSORSETPROP("Buffering", 5, "Customer")
IF lSuccess = .T.
   =MESSAGEBOX("Operation successful!",0,"Operation Status")
ELSE
   =MESSAGEBOX("Operation NOT successful!",0,"Operation Status")
ENDIF

See Also

Reference

SET REFRESH Command

Other Resources

CURSORGETPROP( ) Function
SET MULTILOCKS Command
SQLGETPROP( ) Function
SQLSETPROP( ) Function
Functions
Language Reference


CURSORTOXML( ) Function

Visual FoxPro 9.0 Language Reference
CURSORTOXML( ) Function
See Also

Converts a Visual FoxPro cursor to XML.

CURSORTOXML(nWorkArea | cTableAlias, cOutput [, nOutputFormat
[, nFlags [, nRecords [, cSchemaName [, cSchemaLocation [, cNameSpace ]]]]]])

Parameters

nWorkArea

Specifies the work area of the table from which to create the XML string. If you specify 0 or no value, Visual FoxPro uses the current work area.
cTableAlias

Specifies the alias of the table from which to create the XML string.
cOutput

Specifies the path and file name or memory variable name to which results are sent. If nFlags is set to 0 (default) for memory variable output, XML is returned to the memory variable. If the memory variable does not exist, it is created. If nFlags is set to 512 for file output, and the file does not exist, it is created. If the file already exists, it is overwritten. The setting for SET SAFETY is observed.
nOutputFormat

Specifies the output format of the XML string. The following table lists the values for nOutputFormat.

nOuputFormat Description

1 – ELEMENTS

(Default) Element-centric XML

2 – ATTRIBUTES

Attribute-centric XML

3 – RAW

Generic, attribute-centric XML
nFlags

Specifies the formatting of the XML that is produced and its destination. The following table lists the values for nFlags.

nFlags Bit Output description

0

0000

(Default) Produce XML in UTF-8 format.

This setting creates a memory variable if one does not exist when specified by cOutput and returns XML to the memory variable.

The XML declaration does not contain an Encoding= attribute; that is, no encoding attribute is set to UTF-8.

1

0001

Produce unformatted XML as a continuous string.

2

0010

Enclose empty elements with open and closing elements, for example, <cc04><cc04/>.

4

0100

Preserve white space in fields.

8

1000

Wrap Memo fields in CDATA sections.

16

10000

Output encoding. Output is set to the cursor code page.

To ensure accurate character translation, the Visual FoxPro default code page must match the code page of the cursor. You can accomplish this by setting character and memo fields in the cursor to NOCPTRAN (character binary/memo binary).

When setting this value with tables using any of the code pages, the encoding attribute in the XML is set to an empty string (""). To change to the correct encoding attribute, use the STRTRAN( ) function.

For example, for code page 936, provide the following to the resulting XML string:

Copy Code
strxml=STRTRAN(strxml, 'encoding=""', 'encoding="gb2312"'

32

100000

Output encoding.

512

1000000000

Output to the file specified by cOutput.

If a file does not exist, it is created. If the file already exists, it is overwritten. The setting for SET SAFETY is observed.

4096

1000000000000

Disables base64 encoding.

CURSORTOXML( ) exports Memo (Binary) fields as xsd:base64binary unless you use nFlags set to 4096. In Visual FoxPro, base64 encoding is meant for encoding only binary data.

32768

none

Indicates that a code page should be used.
The following table describes how the encoding attribute is written when output encoding defaults to the cursor or table code page.
Note:
Encoding flags are set by combining bits 4 and 5 (0010000).

Encoding flag Bits 4 and 5 Description

+0

00

(Default) Windows-1252.

+16

01

Set output encoding attribute to the cursor code page.

+32

10

Set output encoding attribute to UTF-8 with no character translation.

+48

11

Set output encoding attribute to UTF-8 and translate character data to UTF-8.
The following table lists common Windows-compatible code pages.

Code page Platform Encoding attribute in XML Declaration Comments

437

MS-DOS, US

ibm437

850

MS-DOS, International

ibm850

865

MS-DOS, Nordic

Empty string ("")

866

MS-DOS, Russian

cp866

932

Windows, Japanese

shift-jis

936

Simplified Chinese

gb2312

949

Windows, Korean

iso-2022-kr

or:

ks_c_5601-1987

950

Windows, Traditional Chinese (Taiwan)

big5

1250

Windows, East European

Windows-1250

Note case.

1251

Windows, Russian

Windows-1251

1252

Windows, U.S., West European

Windows-1252

1253

Windows, Greek

Windows-1253

1254

Windows, Turkish

Windows-1254

1255

Windows, Hebrew

Windows-1255

1256

Windows, Arabic

Windows-1256

Note:
Visual FoxPro uses Windows-1252 as the default encoding. You can specify that the encoding attribute be set to match the code page, such as Big5 (code page 950), when using double-byte character sets (DBCS) for DBCS languages for which Visual FoxPro supports code pages.

When using Windows-1252 and DBCS, no additional character translation is required to display correctly in Internet Explorer. However, to make XML more compliant for Web browsers that can interpret UTF-8, you can optionally set the encoding attribute to UTF-8 instead of Windows-1252. The result set undergoes translation to UTF-8 characters only when you set nFlags to 48 (specify the encoding attribute as UTF-8 and translate character data to UTF-8 format). This is required only when the data actually contains double-byte characters. You do not have to use character translation, STRCONV ( ), for example, if you are outputting only Latin (single byte) characters.
nRecords

Specifies the number of records to output to XML and has a default value is 0. If nRecords is 0, all records are output. If nRecords is greater than the number of records remaining in the table, all remaining records are output.
cSchemaName

Specifies the name and location to contain schema information for the data in cOutput, for example "MySchema.xsd". If no extension is provided, the schema file is created with an .xsd extension. The following table lists the values for cSchemaName.

cSchemaName Description

cSchemaName

Specifies the name and path of the external file for the schema (scoped to the root element of the XML).

Note:
If cSchemaName contains a file name and cSchemaLocation is not provided or is blank, the contents of cSchemaName are written to the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute in the XML.

In the following example, Visual FoxPro generates a generic XML file named MyXMLFile.xml from the Labels.dbf file in the "Labels" alias and the schema file named MySchema in the same folder.

Copy Code
CURSORTOXML("LABELS", "myXMLFile.xml", 1, 512, 0, "mySchema.xsd")

If cSchemaName includes a URI, the schema is written to the current directory and must be uploaded to the server to be accessed by the browser or parser. External schemas always are written to the same location as the XML file.

"1"

Specifies an inline schema is produced. For example, the following code produces an inline schema:

Copy Code
CURSORTOXML("LABELS", "myXMLFile.xml", 1, 512, 0, "1")

""

Specifies that no schema is produced.

cSchemaLocation

Specifies an optional location where the application reading the XML data should look for the schema file.
Note:
Use this parameter only when you are deploying your schema to a location other than the location of the XML data.

The contents of cSchemaLocation are written to the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute of the XML data produced. The cschemaLocation parameter can be an HTTP address or other URI. You need to copy the schema file to the location you have specified in cSchemaLocation. The following example produces XML data:
Copy Code
   CURSORTOXML("LABELS", "myXMLFile.xml", 1, 512, 0, ;
       "mySchema.xsd", "http://www.microsoft.com/mySchema.xsd")
containing the following attribute:
Copy Code
   xsi:noNamespaceSchemaLocation=" http://www.microsoft.com/mySchema.xsd"
Specifying cSchemaLocation when cSchemaName is blank causes the same attributes to be written to the XML data. This makes it possible for you to point to an existing schema without recreating the schema each time CURSORTOXML( ) is called.
cNamespace

Specifies the namespace of the XML or schema to be produced and has an empty string ("") as the default value. Specifying a value for cNameSpace sets the targetNamespace attribute to the same value and adds the elementFormDefault="qualified" attribute to the schema. If you do not specify a cNamespace value, and the schema is external, no namespace declaration is written to the schema. If you do not specify a cNamespace value and the schema is inline, the targetNamespace in the schema is set to an empty string ("").

Return Value

Numeric data type. CURSORTOXML( ) returns the number of bytes written to the file or a memory variable.

Remarks

You can use CURSORTOXML( ) with the OLE DB Provider for Visual FoxPro. However, the _VFP VFPXMLProgID property is not supported because the _VFP system variable is not supported in the OLE DB Provider.

Note:
To use the Visual FoxPro OLE DB Provider with CURSORTOXML( ), you must install MSXML 3.0 on the computer with the OLE DB Provider.

CURSORTOXML( ) output adheres to the cursor index order, SET FIELDS TO, and current filter settings. However, it does not preserve the cursor location. After the calling CURSORTOXML( ), if all records are output, the cursor record pointer reports EOF. If not all records are output, it points to the last record output to XML.

The resulting XML from CURSORTOXML( ) contains the same scale as the exported table if the table contains Double data type values. For example, if a Double column is created with a scale of 6 using the following codem the resulting XML contains six digits to the right of the decimal point:

Copy Code
CREATE TABLE test (col1 b(6))

When you use the CURSORTOXML( ) function to export a table or cursor to XML, the root node is always called "VFPData", regardless of the output format.

For Date types only, you can export "EMPTY" Date and DateTime types using CURSORTOXML( ). However, the XML schema validation might fail because "EMPTY" is not valid for these types in an XML schema definition (XSD) schema. This is an issue only if a schema is required, and the resulting XML is validated against an XML parser that can interpret XSD schemas. To work around this issue, you might need to change the data to a nonempty representation by calling the appropriate SELECT statement and use CURSORTOXML( ) on the created cursor. For example, you can change the empty Date or DateTime values to .NULL.:

Copy Code
SELECT orderid, EVL(shippeddate,.NULL.) as ShippedDate FROM orders

You can also change the empty Date or DateTime to an appropriate representation for "empty":

Copy Code
SELECT orderid, IIF(EMPTY(shippeddate),{^1899-12-30 00:00:00},tc11);
   as ShippedDate FROM orders

When using flag 32768, the flags 16 and 32 settings can affect which code page is applied depending on the type of data you are writing to XML. The following tables show the possible combinations of settings and the code page each combination applies.

For XML documents written with the 32768 flag set, the following code pages are applied.

Flag 16 | Flag 32 | Flag 32768 is Set
Not set | Not set | XML documents: Window-1252. Unicode data: code page 1252. Character data: default code page, unless a field is marked as NOCPTRANS.
True (.T) | Not set | XML documents: Plus-CodePage property of the cursor. If XMLField CodePage property is greater than zero (0) and it doesn’t match the cursor’s code page, an error is reported. Unicode data: the Code page property of the cursor object. Character data: none. Raw data from the Visual FoxPro tables (.dbf) are used instead.
Not set | Set | XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: Default code page unless field is marked as NOCPTRANS, in which case no additional character translation to UTF-8 occurs.
Set | Set | XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: default code page unless a field is marked as NOCPTRANS, in which case the data are translated to UTF-8 using the SYS(3005) setting.

For XML documents written without setting the 32768 flag, the following code pages are applied.

Flag 16 | Flag 32 | Without the 32768 flag
Not set | Not set | XML documents: Window-1252. Unicode data: code page 1252. Character data: default code page unless a field is marked as NOCPTRANS.
True (.T) | Not set | XML documents: CodePage property of the cursor. Character data: none. Raw data from the Visual FoxPro tables (.dbf) are used instead. Unicode data: code page property of the cursor object.
Not set | Set | XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: default code page unless field is marked as NOCPTRANS, in which case no additional character translation to UTF-8 occurs.
Set | Set | XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: default code page unless field is marked as NOCPTRANS, in which case, they are translated to UTF-8 using code page for the current SYS(3005) setting.

See Also

Other Resources

XMLUPDATEGRAM( ) Function
XMLTOCURSOR( ) Function
Converting Between XML and Visual FoxPro Data
XML Data in Visual FoxPro
Functions


CURVAL( ) Function

Visual FoxPro 9.0 Language Reference
CURVAL( ) Function
See Also Example

Returns field values directly from disk for a table or a remote data source.

CURVAL(cExpression [, cTableAlias | nWorkArea])

Parameters

cExpression

Specifies an expression whose value CURVAL( ) returns from a table or a remote data source. cExpression is typically a field or an expression consisting of a set of fields from the table or remote data source.
cTableAlias

Specifies the alias of the table from which the field values are returned from disk for a table or a remote data source.
nWorkArea

Specifies the work area of the table from which the field values are returned from disk for a table or a remote data source.

Return Value

Character, Currency, Date, DateTime, Double, Float, Logical, Numeric, or Memo

Remarks

The field values returned by CURVAL( ) and OLDVAL( ) can be compared to determine if another user on a network changed the field values while the fields were being edited. CURVAL( ) and OLDVAL( ) can only return different values when optimistic row or table buffering is enabled. Optimistic row or table buffering is enabled with CURSORSETPROP( ).

Note:
If you are working with a view in a multiuser environment, the values returned by CURVAL() might not be up to date unless you call the REFRESH() function first. Data returned by a view is buffered, and the CURVAL() function reads values from the buffer. However, if other users have changed data in the underlying tables for the view, the buffered data is not updated until the REFRESH() function is called.

CURVAL( ) returns field values for the current record, and the return value data type is determined by the expression you specify with cExpression.

The value is returned for the table or cursor open in the currently selected work area if CURVAL( ) is issued without the optional cTableAlias or nWorkArea arguments.

Example

This example creates a free table named mytable, and a value of "One" is inserted into the cDigit field. Optimistic table buffering is enabled with SET MULTILOCKS ON and CURSORSETPROP( ).

A value of "Two" is then inserted into the cDigit field, and CURVAL( ) and OLDVAL( ) are used to display the original cDigit values. TABLEUPDATE( ) is used to commit the changes to the table, and CURVAL( ) and OLDVAL( ) are used to display the new cDigit values. Note that because this is a single user example, CURVAL( ) and OLDVAL( ) return the identical values.
Copy Code
CLOSE DATABASES
CLEAR

CREATE TABLE mytable FREE (cDigit C(10))
* Store original value
INSERT INTO mytable (cDigit) VALUES ("One")
SET MULTILOCKS ON        && Allow optimistic table buffering
= CURSORSETPROP("Buffering",5)   && Optimistic table buffering on
REPLACE cDigit WITH "Two"    && New value

? "Current value: " + CURVAL("cDigit", "mytable")
? "Old value: " + OLDVAL("cDigit", "mytable")
= TABLEUPDATE(.T.)       && Commit changes made to table
? "Table changes committed"
? "New current value: " + CURVAL("cDigit", "mytable")
? "New old value: " + OLDVAL("cDigit", "mytable")

See Also

Other Resources

GETFLDSTATE( ) Function
OLDVAL( ) Function
TABLEREVERT( ) Function
TABLEUPDATE( ) Function
CURSORSETPROP( ) Function
Functions
Language Reference


DATE( ) Function

Visual FoxPro 9.0 Language Reference
DATE( ) Function
See Also Example

Returns the current system date, which is controlled by the operating system, or creates a year 2000-compliant Date value.

DATE([nYear, nMonth, nDay])

Parameters

nYear

Specifies the year returned in the year 2000-compliant Date value. nYear can be a value from 100 to 9999.
nMonth

Specifies the month returned in the year 2000-compliant Date value. nMonth can be a value from 1 to 12.
nDay

Specifies the day returned in the year 2000-compliant Date value. nDay can be a value from 1 to 31.

Return Value

Date

Remarks

DATE( ) returns the current system date if it is issued without the optional arguments. Include the optional arguments to return a year 2000-compliant Date value in the format set in the Regional tab of the Options dialog box. Any NULL parameter is replaced with the current system value.

No Microsoft Visual FoxPro commands or functions can directly change the system date.

Example

The following example displays the current system date with and without the century, and then displays a year 2000-compliant date.
Copy Code
CLEAR
SET CENTURY OFF
? DATE( )  && Displays today's date without the century
SET CENTURY ON
? DATE( )  && Displays today's date with the century
? DATE(1998, 02, 16)  && Displays a year 2000-compliant Date value

See Also

Other Resources

CTOD( ) Function
DATETIME( ) Function
DTOC( ) Function
SET CENTURY Command
SET DATE Command
SET MARK TO Command
SYS( ) Functions Overview
Functions
Language Reference


DATETIME( ) Function

Visual FoxPro 9.0 Language Reference
DATETIME( ) Function
See Also Example

Returns the current date and time as a DateTime value, or creates a year 2000-compliant DateTime value.

DATETIME([nYear, nMonth, nDay [, nHours [, nMinutes [, nSeconds]]]])

Parameters

nYear

Specifies the year returned in the year 2000-compliant DateTime value. nYear can be a value from 100 to 9999.
nMonth

Specifies the month returned in the year 2000-compliant DateTime value. nMonth can be a value from 1 to 12.
nDay

Specifies the day returned in the year 2000-compliant DateTime value. nDay can be a value from 1 to 31.
nHours

Specifies the hours returned in the year 2000-compliant DateTime value. nHours can be a value from 0 (midnight) to 23 (11 P.M). Defaults to 0 if omitted.
nMinutes

Specifies the minutes returned in the year 2000-compliant DateTime value. nMinutes can be a value from 0 to 59. Defaults to 0 if omitted.
nSeconds

Specifies the seconds returned in the year 2000-compliant DateTime value. nSeconds can be a value from 0 to 59. Defaults to 0 if omitted.

Return Value

DateTime

Remarks

DATETIME( ) returns the current system DateTime if it is issued without the optional arguments. Any NULL date parameters are replaced with current system values. A NULL time parameter is replaced with 12:00:00.

Include the optional arguments to return a year 2000-compliant DateTime value in the format specified in the Regional tab of the Options dialog box.

Example

This first example stores the Datetime for the New Year to a variable named tNewyear, and stores the current Datetime to a variable named tToday. The number of seconds between the current Datetime and the New Year is then displayed.

The second example uses DATETIME( ) to create a year 2000-compliant DateTime value.
Copy Code
tNewyear = DATETIME(YEAR(DATE( ) ) + 1, 1, 1)  && Next New Year
tToday = DATETIME( )
nSecondstonewyear = tNewyear - tToday
CLEAR
? "There are " + ALLTRIM (STR(nSecondstonewyear)) ;
   + " seconds to the next New Year."

CLEAR
SET CENTURY ON
SET DATE TO AMERICAN
? DATETIME(1998, 02, 16, 12, 34, 56) && Displays 02/16/1998 12:34:56 PM

See Also

Other Resources

CTOT( ) Function
DATE( ) Function
DTOT( ) Function
HOUR( ) Function
SEC( ) Function
SECONDS( ) Function
SET SECONDS Command
SET SYSFORMATS Command
TIME( ) Function
TTOC( ) Function
TTOD( ) Function
Functions
Language Reference


DAY( ) Function

Visual FoxPro 9.0 Language Reference
DAY( ) Function
See Also Example

Returns the numeric day of the month for a given Date or DateTime expression.

DAY(dExpression | tExpression)

Parameters

dExpression

Specifies a date from which DAY( ) returns a day of the month. dExpression can be a date literal, a Date-type variable, an array element, or a date field.
tExpression

Specifies a date or time from which DAY( ) returns a day of the month. dExpression can be a DateTime literal, a DateTime-type variable, an array element, or a DateTime field.

Return Value

Numeric

Remarks

DAY( ) returns a number from 1 through 31.

Example

Copy Code
STORE {^1998-03-05} TO gdBDate

CLEAR
? CDOW(gdBDate)  && Displays Thursday
? DAY(gdBDate) && Displays 5
? 'That date is ', CMONTH(gdBDate), STR(DAY(gdBDate),2)

See Also

Other Resources

CDOW( ) Function
DOW( ) Function
SET FDOW Command
SET FWEEK Command
SYS( ) Functions Overview
Functions
Language Reference


DBC( ) Function

Visual FoxPro 9.0 Language Reference
DBC( ) Function
See Also Example

Returns the name and path of the current database.

DBC( )

Return Value

Character

Remarks

DBC( ) returns the empty string if there is no current database.

Use SET DATABASE to specify the current database.

Example

The following example opens the testdata database and uses DBC( ) to display information about the database.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')  && Opens the DBC.

CLEAR
? DBC( )  && Displays the path and name of the database

See Also

Other Resources

ADD TABLE Command
CLOSE DATABASES Command
CREATE DATABASE Command
DISPLAY TABLES Command
OPEN DATABASE Command
REMOVE TABLE Command
SET DATABASE Command
Functions
Language Reference


DBF( ) Function

Visual FoxPro 9.0 Language Reference
DBF( ) Function
See Also Example

Returns the name of a table open in a specified work area or a table name from a table alias.

DBF([cTableAlias | nWorkArea])

Parameters

cTableAlias

Specifies the table alias.
nWorkArea

Specifies the work area number. If you omit cTableAlias and nWorkArea, DBF( ) returns the name of the table open in the current work area. DBF( ) returns an empty string if a table isn't open in the work area you specify. If a table doesn't have the alias you specify with cTableAlias, Visual FoxPro generates an error message. For information on creating an alias for a table, see USE.

Return Value

Character

Remarks

When SET FULLPATH is ON, DBF( ) returns the path to the table with the table name. When SET FULLPATH is OFF, DBF( ) returns the drive on which the table resides with the table name.

Example

The following example returns the name of a table from its work area and its alias, and returns the empty string after all tables have been closed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer IN 2 ALIAS mycust
CLEAR
? DBF(2)  && Displays customer.dbf with its path
? DBF('mycust')  && Displays customer.dbf with its path
CLOSE DATABASES
? DBF( )      && Displays the empty string

See Also

Other Resources

CDX( ) Function
FIELD( ) Function
NDX( ) Function
SET FULLPATH Command
USE Command
Functions
Language Reference


DBGETPROP( ) Function

Visual FoxPro 9.0 Language Reference
DBGETPROP( ) Function
See Also Example

Retrieves the value of a property for the current database or for fields, named connections, tables, or views in the current database.

Note:
You must open the database before you can retrieve its properties or those of its connections, tables, views, or fields. However, you do not need to open a table or view before retrieving its properties.

DBGETPROP(cName, cType, cProperty)

Parameters

cName

Specifies the name of the current open database or the field, named connection, table, or view in the current open database for which DBGETPROP( ) returns information. To return information about a field in a table or a view, preface the name of the field with the name of the table or view containing the field. For example, to return information about the custid field in the customer table, specify the following for cName:
Copy Code
customer.custid
cType

Specifies whether cName is the current database, or a field, named connection, table, or view in the current database. The following table lists the values for cType.

cType Description

CONNECTION

cName is a named connection in the current database.

DATABASE

cName is the current database.

FIELD

cName is a field in the current database.

TABLE

cName is a table in the current database.

VIEW

cName is a view in the current database.
cProperty

Specifies the name of the property for which DBGETPROP( ) returns information. The following tables list the values you can specify for cProperty, the return value types, and descriptions of each property. Each description includes the read and write privileges for each property. If a property is read-only, its value cannot be changed with DBSETPROP( ). Connection properties

cProperty Type Description

Asynchronous

L

The connection mode. (Default) False (.F.) specifies a synchronous connection. True (.T.) specifies an asynchronous connection.

Read/write.

BatchMode

L

The batch-processing mode. (Default) True (.T.) specifies the connection that operates in batch mode.

Read/write.

Comment

C

The text of the connection comment.

Read/write.

ConnectString

C

The login connection string.

Read/write.

ConnectTimeout

N

The connection timeout interval in seconds. The default is 0 (wait indefinitely).

Read/write.

Database

C

The name of the server database specified with the DATABASE clause in the CREATE CONNECTION command or in the Connection Designer.

Read/write.

DataSource

C

The name of the data source as defined in the Odbc.ini file.

Read/write.

DisconnectRollback

L

Specifies if a pending transaction is committed or rolled back when SQLDISCONNECT( ) is called for the last connection handle.

The default is false (.F.), indicating that a pending transaction is committed when SQLDISCONNECT( ) is called for the last connection handle.

Specify true (.T.) to roll back a pending transaction when SQLDISCONNECT( ) is called for the last connection handle.

Connections with automatic transaction processing are not affected by this setting.

Read/write.

DispLogin

N

Contains a numeric value that determines when the ODBC Login dialog box is displayed. DispLogin may assume the following values:

1 or DB_PROMPTCOMPLETE (from Foxpro.h). 1 is the default.

2 or DB_PROMPTALWAYS (from Foxpro.h).

3 or DB_PROMPTNEVER (from Foxpro.h).

If 1 or DB_PROMPTCOMPLETE is specified, Microsoft Visual FoxPro displays the ODBC Login dialog box only if any required information is missing.

If 2 or DB_PROMPTALWAYS is specified, the ODBC Login dialog box is always displayed, allowing you to change settings before connecting.

If 3 or DB_PROMPTNEVER is specified, the ODBC Login dialog box is not displayed and Visual FoxPro generates an error if the required login information is not available.

Read/write.

DispWarnings

L

Contains a logical value that determines if non-trappable warnings from the remote table, ODBC, or Visual FoxPro are displayed. (Default) True (.T.) specifies that non-trappable errors are displayed.

Read/write.

IdleTimeout

N

The idle timeout interval in minutes. Timeout is checked no more than once per minute, therefore it is possible that active connections might deactivate one or two minutes later after the specified time interval has elapsed. The default value is 0 (wait indefinitely).

Read/write.

PacketSize

N

The size of the network packet used by the connection. Adjusting this value can improve performance. The default value is 4096 bytes (4K).

Read/write

PassWord

C

The connection password.

Read/write.

QueryTimeout

N

The query timeout interval in seconds. The default value is 0 (wait indefinitely).

Read/write.

Transactions

N

Contains a numeric value that determines how the connection manages transactions on the remote table. Transactions may assume the following values:

1 or DB_TRANSAUTO (from Foxpro.h). 1 is the default. Transaction processing for the remote table is handled automatically.

2 or DB_TRANSMANUAL (from Foxpro.h). Transaction processing is handled manually through SQLCOMMIT( ) and SQLROLLBACK( ).

Read/write.

UserId

C

The user identification.

Read/write.

WaitTime

N

The amount of time in milliseconds that elapses before Visual FoxPro checks whether the SQL statement has completed executing. The default is 100 milliseconds.

Read/write.
Database properties

cProperty Type Description

Comment

C

The text of the database comment.

Read/write.

DBCEventFileName

C

Relative path and filename of external program file containing DBC Events code.

DBCEvents

L

Enabled state of DBC Events. Set to True (.T.) to enable.

Version

N

The database version number.

Read-only.
Field properties for tables

cProperty Type Description

Caption

C

The field caption. If an equal sign (=) precedes the value of this property, Visual FoxPro evaluates the value as an expression. Otherwise, it is treated as a string literal.

Read/write.

Comment

C

The text of the field comment.

Read/write.

DefaultValue

C

The field default value.

Read-only.

DisplayClass

C

Name of the class used for field mapping.

Read/write.

DisplayClassLibrary

C

Path to the class library specified with the DisplayClass property.

Read/write.

Format

C

The field display format. See the Format Property for a list of format settings.

Read/write.

InputMask

C

The field input format. See the InputMask Property for a list of input mask settings.

Read/write.

RuleExpression

C

The field rule expression.

Read-only.

RuleText

C

The field rule error text.

Read-only.
Field properties for views

cProperty Type Description

Caption

C

The field caption. If an equal sign (=) precedes the value of this property, Visual FoxPro evaluates the value as an expression. Otherwise, it is treated as a string literal.

Read/write.

Comment

C

The text of the field comment.

Read/write.

DataType

C

The data type for a field in a view. Initially set to the data type for the field in the data source.

To specify a different data type for a field with DBSETPROP( ), use the syntax for creating fields in CREATE TABLE – SQL.

For example, to change the data type of an integer field named iCost in a table named Mytable to numeric type with width 4 and 2 decimal places, use

DBSETPROP('mytable.icost', 'field', ; 'DataType', 'N(4,2)')

You can also include the NOCPTRANS clause to prevent translation of character and memo fields to a different code page.

Read/write for remote views.

DisplayClass

C

Name of the class used for field mapping.

Read/write.

DisplayClassLibrary

C

Path to the class library specified with the DisplayClass property.

Read/write.

DefaultValue

C

The field default value.

Read/write.

KeyField

L

Contains True (.T.) if the field is specified in an index key expression; otherwise, contains False (.F.).

Read/write.

RuleExpression

C

The field rule expression.

Read/write.

RuleText

C

The field rule error text.

Read/write.

Updatable

L

Contains True (.T.) if the field can be updated; otherwise, contains False (.F.).

Read/write.

UpdateName

C

The name of the field used when data in the field is updated to the remote table. By default, the remote table field name.

Read/write.
Table properties

cProperty Type Description

Comment

C

The text of the table comment.

Read/write.

DeleteTrigger

C

The Delete trigger expression.

Read-only.

InsertTrigger

C

The Insert trigger expression.

Read-only.

Path

C

The relative path with respect to the DBC to the table including the name of the file.

Read-only.

PrimaryKey

C

The tag name of the primary key.

Read-only.

RuleExpression

C

The row rule expression.

Read-only.

RuleText

C

The row rule error text.

Read-only.

UpdateTrigger

C

The Update trigger expression.

Read-only.
View properties

cProperty Type Description

AllowSimultaneousFetch

L

Applies when using remote views, a shared connection, and to cursors created using ODBC.

AllowSimultaneousFetch contains True (.T.) when similarly configured cursors sharing the connection are permitted to fetch rows simultaneously.

Otherwise, AllowSimultaneousFetch contains False (.F.) when fetching rows simultaneously is not permitted.

Note:
This property is available in Visual FoxPro 8.0 and later. Views created in Visual FoxPro 8.0 and later are not compatible with earlier versions. Calling the VALIDATE DATABASE command in a version prior to Visual FoxPro 8.0 on a database container with remote views created or modified in Visual FoxPro 8.0 and later generate an error. Calling the VALIDATE DATABASE RECOVER in a version prior to Visual FoxPro 8.0 removes the AllowSimultaneousFetch property from any such views.

BatchUpdateCount

N

The number of update statements sent to the back end for views. 1 is the default. Adjusting this value can greatly increase update performance.

Read/write.

Comment

C

The text of the view comment.

Read/write.

CompareMemo

L

Contains true (.T.) (default) if memo fields (of type Memo, General, or Picture, or, for remote views, type Timestamp) are included in the WHERE clause for updates; otherwise, contains false (.F.).

Read/write.

ConnectName

C

The named connection used when the view is opened.

Read-only.

FetchAsNeeded

L

If True (.T.), data is fetched only when needed, such as when record pointer moves to a row that has not been fetched.

If False (.F.), additional data is fetched during idle time. (Default)

Note:
FetchAsNeeded does not apply when progressive fetching is disabled (FetchSize is -1).

Read/write.

FetchMemo

L

Contains true (.T.) (default) if memo and general fields are fetched with the view results; otherwise, contains false (.F.).

Use the ISMEMOFETCHED( ) Function to determine if the memo field has been fetched.

Read/write.

FetchSize

N

Contains the number of records fetched at a time from the remote tables. The default is 100 records. Setting FetchSize to –1 retrieves the complete result set, limited by the MaxRecords setting.

Note:
Progressive fetching holds the connection until all rows are retrieved. Use caution coding with FetchSize if ShareConnection is True (.T.).

Read/write.

MaxRecords

N

The maximum number of records fetched when result sets are returned. The default is – 1 (all rows are returned). A value of 0 specifies that the view is executed but no results are fetched.

Read/write.

Offline

L

Contains true (.T.) if the view is an offline view.

Read-only.

ParameterList

C

The WHERE clause parameters. The format for the parameters is ''ParameterName1, 'Type1'; ParameterName2, 'Type2'; ...'' where Type is a one of the following characters specifying the parameter type:

C – Character D – Date T – DateTime N – Numeric F – Floating B – Double I – Integer Y – Currency L - Logical

For example, ''MyParam1, 'C' '' specifies a single character type parameter named MyParam1.

For more information about creating parameterized views, see How to: Create Parameterized Views .

Read/write.

Prepared

L

Contains True (.T.) if SQL statements are prepared for subsequent REQUERY( ) function calls. REQUERY( ) is used to retrieve data again for a SQL view. See SQLPREPARE( ) for additional information about preparing SQL statements. The default is false (.F.).

Read/write.

RuleExpression

C

The row rule expression.

Read/write.

RuleText

C

The rule text expression displayed when an error occurs when data is edited in a Browse or Edit window.

Read/write.

SendUpdates

L

Contains true (.T.) if a SQL update query is sent to update remote tables; otherwise, contains false (.F.) (default).

Read/write.

ShareConnection

L

Contains true (.T.) if the view can share its connection handle with other connections; otherwise, contains false (.F.).

Read/write.

SourceType

N

The view source. SourceType may assume the following values: 1 - The view uses local tables.

2 - The view uses remote tables.

Read-only.

SQL

C

The SQL statement executed when the view is opened.

Read-only.

Tables

C

A comma-delimited list of the names of the tables.

Read/write.

UpdateType

N

The update type. Valid values are: 1 or DB_UPDATE (from Foxpro.h). The old data is updated with the new data (default).

2 or DB_DELETEINSERT (from Foxpro.h). The old data is deleted and the new data is inserted.

Read/write.

UseMemoSize

N

The minimum size (in bytes) for which result columns are returned in memo fields. For example, if the width of a column result is greater than the value of UseMemoSize, the column result is stored in a memo field. UseMemoSize may vary from 1 to 255; the default value is 255.

Read/write.

WhereType

N

The WHERE clause for updates to remote tables. WhereType may assume the following values: 1 or DB_KEY (from Foxpro.h). The WHERE clause used to update remote tables consists of only the primary fields specified with the KeyFieldList property.

2 or DB_KEYANDUPDATABLE (from Foxpro.h). The WHERE clause used to update remote tables consists of the primary fields specified with the KeyFieldList property and any updatable fields.

3 or DB_KEYANDMODIFIED (from Foxpro.h) (default). The WHERE clause used to update remote tables consists of the primary fields specified with the KeyFieldList property and any other fields that are modified.

4 or DB_KEYANDTIMESTAMP (from Foxpro.h). The WHERE clause used to update remote tables consists of the primary fields specified with the KeyFieldList property and a comparison of the time stamps.

For more information about the WhereType property, see Managing Updates by Using Views.

Read/write.

Return Value

Character, Numeric, or Logical data type. DBGETPROP( ) returns the value for the specified property.

Remarks

For more information about setting property values, see DBSETPROP( ) Function.

Example

The following example displays the name of the primary key field for the customer table. It then displays the field comments for the cust_id field in the customer table. If there are no comments for the field, a message is displayed indicating there are no field comments. To add comments, see the example for DBSETPROP( ).
Copy Code
CLOSE DATABASES
CLEAR

OPEN DATABASE (HOME(2) + 'Data\testdata')

* Displays the primary key field
cResults = DBGETPROP("customer", "Table", "PrimaryKey")
=MESSAGEBOX(cResults)   && Displays    'cust_id'

* Displays comments for the field 'cust_id'
cResults = DBGETPROP("customer.cust_id", "Field", "Comment")
IF LEN(ALLTRIM(cResults)) = 0
   =MESSAGEBOX("No Comment for this field." + CHR(13) + ;
     CHR (13) + "Use DBSETPROP( ) to add comments.")
ELSE
   =MESSAGEBOX("Cust_id field comments: " + cRESULTS)
ENDIF

See Also

Reference

ISMEMOFETCHED( ) Function

Other Resources

ADD TABLE
CREATE CONNECTION
CREATE DATABASE
CREATE SQL VIEW
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function
DBSETPROP( ) Function
DISPLAY DATABASE
LIST DATABASE
RENAME CONNECTION
SQLCOMMIT( ) Function
SQLROLLBACK( ) Function
Functions
Language Reference


DBSETPROP( ) Function

Visual FoxPro 9.0 Language Reference
DBSETPROP( ) Function
See Also Example

Sets a property for the current database or for fields, named connections, tables, or views in the current database.

DBSETPROP(cName, cType, cProperty, ePropertyValue)

Parameters

cName

Specifies the name of the current open database or the field, named connection, table, or view in the current open database for which DBGETPROP( ) returns information. To set a property for a field in a table or a view, preface the name of the field with the name of the table or view containing the field. For example, to set a property for the custid field in the customer table, specify the following for cName:
Copy Code
customer.custid
cType

Specifies whether cName is the current database or for a field, named connection, table, or view in the current database. The following table lists the values you can specify for cType:

cType Description

CONNECTION

cName is a named connection in the current database.

DATABASE

cName is the current database.

FIELD

cName is a field in the current database.

TABLE

cName is a table in the current database.

VIEW

cName is a view in the current database.
cProperty

Specifies the name of the property to set. If a property is read-only, its value cannot be changed with DBSETPROP( ). If you attempt to set a property that is read-only, Visual FoxPro generates an error message. For more information on properties you can specify with cProperty, including their data types, see DBGETPROP( ).
ePropertyValue

Specifies the value to which cProperty is set. ePropertyValue must be the same data type as the property's data type.
Caution:
Visual FoxPro does not verify that the value you specify is valid for the property. Thus, it is possible to set a property to an invalid value with DBSETPROP( ). For example, DBSETPROP( ) can be used to set a field rule expression to an expression that is not valid for the field, and Visual FoxPro will not generate an error. To avoid an error when setting the Tables property of a view, precede ePropertyValue with the database designation in the following syntax:

Copy Code
         <databaseName>!ePropertyValue

Return Value

Logical data type. DBSETPROP( ) returns True (.T.) if Visual FoxPro successfully sets the property you specify. Visual FoxPro generates an error if the property you specify cannot be set.

Remarks

For more information about retrieving current property values, see DBGETPROP( ) Function.

Example

The following example uses DBSETPROP( ) to specify a comment for the cust_id field in the customer table. DBGETPROP( ) is used to display the comment.
Copy Code
CLOSE DATABASES
CLEAR

OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer     && Open customer table

= DBSETPROP("customer.cust_id", "Field", "Comment", ;
  "Property has been set by DBSETPROP.")  && New field comments

cRESULTS = DBGETPROP("customer.cust_id", "Field", "Comment")
WAIT WINDOW "Cust_id field comments: "+ cRESULTS  && Display comments

See Also

Other Resources

ADD TABLE
CREATE DATABASE
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function
DBGETPROP( ) Function
DISPLAY DATABASE
LIST DATABASE
OPEN DATABASE
SQLCOMMIT( ) Function
SQLROLLBACK( ) Function
Functions
Language Reference


DBUSED( ) Function

Visual FoxPro 9.0 Language Reference
DBUSED( ) Function
See Also Example

Returns true (.T.) if the specified database is open.

DBUSED(cDatabaseName)

Parameters

cDatabaseName

Specifies the name of the database for which DBUSED( ) returns a logical value indicating whether or not the database is open.

Return Value

Logical

Remarks

DBUSED( ) returns true (.T.) if the specified database is open; otherwise, it returns false (.F.).

Example

The following example opens the TESTDATA database, and then uses DBUSED( ) to determine if the TESTDATA database and a database named TEST are open.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')

CLEAR
? 'Testdata database open? '
?? DBUSED('testdata')     && Displays .T.
? 'Test database open? '
?? DBUSED('test')     && Displays .F.

See Also

Other Resources

CLOSE DATABASES
CREATE DATABASE
OPEN DATABASE
Functions
Language Reference


DDE Functions

Visual FoxPro 9.0 Language Reference
DDE Functions
See Also

Exchange data between Visual FoxPro and other Microsoft Windows-based applications.

Remarks

Visual FoxPro can act as both a server and a client to send and receive data to and from other Microsoft Windows-based applications.

The following naming conventions are used in applications that support DDE (dynamic data exchange).

Name | Description
Service Name | A name that the server responds to when a client tries to access the server. A server can support many service names.
Topic Name | A name that specifies a logical set of data. For file-based applications, topic names are usually file names. In other applications, topic names are application-specific. To access the server, the client must specify a topic name in addition to the server's service name.
Item Name | A name that specifies a unit of data that the server can pass to the client requesting the data.

To request data from another application, create a Visual FoxPro program that establishes Visual FoxPro as a client. The following is a brief outline for creating a simple Visual FoxPro program that requests data from another application:

  • Establish a link to the server application with DDEInitiate( ).

  • If the link is successfully established, use DDERequest( ) to request data from the server application. DDERequest( ) can be issued repeatedly to request additional data.

  • After the data has been received, issue DDETerminate( ) to terminate the link to the server application to free up system resources.

The functions above establish a cold link. A cold link exists when the client initiates all the communications between the applications. For a discussion of other types of links, see DDEAdvise( ).

The following is a brief outline for a program that establishes Visual FoxPro as a server:

  • Use DDESetService( ) to create a service and specify the type of service.

  • Use DDESetTopic( ) to create a service topic and specify the procedure to execute when the topic is specified in a client request.

  • Create the procedure specified in DDESetTopic( ) to accept the parameters passed to the procedure.

  • Within the procedure, process the request and, if appropriate, return the requested data to the client.

Note that these DDE functions differ from previous Visual FoxPro function conventions in the following ways:

  • The first four characters of these functions are not unique.

  • The function names exceed 10 characters and cannot be abbreviated.

    DDE Function Description

    DDEAbortTrans( )

    Ends an asynchronous DDE transaction.

    DDEAdvise( )

    Creates a notify link or an automatic link used in DDE.

    DDEEnabled( )

    Enables or disables DDE processing or returns the status of DDE processing.

    DDEExecute( )

    Using DDE, sends a command to another application.

    DDEInitiate( )

    Establishes a DDE channel between Visual FoxPro and another Microsoft Windows-based application.

    DDELastError( )

    Returns an error number for the last DDE function.

    DDEPoke( )

    Sends data between client and server applications in a DDE conversation.

    DDERequest( )

    Requests data from a server application in a dynamic DDE conversation.

    DDESetOption( )

    Changes or returns DDE settings.

    DDESetService( )

    Creates, releases, or modifies service names and settings in Visual FoxPro.

    DDESetTopic( )

    In a DDE conversation, creates or releases a topic name from a service name.

    DDETerminate( )

    Closes a DDE channel established with DDEInitiate( ).

See Also

Other Resources

DDEAbortTrans( ) Function
DDEAdvise( ) Function
DDEEnabled( ) Function
DDEExecute( ) Function
DDEInitiate( ) Function
DDELastError( ) Function
DDEPoke( ) Function
DDERequest( ) Function
DDESetOption( ) Function
DDESetService( ) Function
DDESetTopic( ) Function
DDETerminate( ) Function
Functions
Language Reference


DDEAbortTrans( ) Function

Visual FoxPro 9.0 Language Reference
DDEAbortTrans( ) Function
See Also

Ends an asynchronous dynamic data exchange (DDE) transaction.

DDEAbortTrans(nTransactionNumber)

Parameters

nTransactionNumber

Specifies the transaction number returned by DDEExecute( ), DDEPoke( ), or DDERequest( ) when the transaction is sent to the server application.

Return Value

Logical

Remarks

An asynchronous transaction allows Visual FoxPro program execution to continue without waiting for the server application to respond to a data request.

DDEExecute( ), DDEPoke( ), and DDERequest( ) wait for the period specified by DDESetOption( ) for a server application to respond, unless you specify a user-defined function to execute when the server application responds. Specifying a user-defined function to execute in these functions creates an asynchronous transaction.

If DDEAbortTrans( ) is called before the server has processed the request, the user-defined function will not be called for the transaction.

DDEAbortTrans( ) returns true (.T.) if the asynchronous transaction is successfully ended and returns false (.F.) if the asynchronous transaction cannot be ended. Use DDELastError( ) to determine why the transaction could not be ended.

See Also

Other Resources

DDEExecute( ) Function
DDELastError( ) Function
DDEPoke( ) Function
DDERequest( ) Function
Functions
Language Reference


DDEAdvise( ) Function

Visual FoxPro 9.0 Language Reference
DDEAdvise( ) Function
See Also Example

Creates a notify link or an automatic link used in a dynamic data exchange (DDE).

DDEAdvise(nChannelNumber, cItemName, cUDFName, nLinkType)

Parameters

nChannelNumber

Specifies the channel number.
cItemName

Specifies the item name. For example, Microsoft Excel uses row and column notation to refer to cells in a worksheet. The item name R1C1 designates the cell in the first row and first column of the worksheet.
cUDFName

Specifies the user-defined function that is executed when a notify link or an automatic link is established and the item cItemName is modified. When the user-defined function is executed, it is passed the following six parameters in the order given below:

Parameter Contents

Channel Number

The channel number of the server application.

Action

ADVISE or TERMINATE.

Item

The item name; for example, R1C1 for a Microsoft Excel worksheet cell.

Data

The new data (automatic link) or the empty string (notify link).

Format

The data format; for example, CF_TEXT.

Advise Status

The link type (0 = manual, 1 = notify, 2 = automatic).
The user-defined function should have six parameters in its LPARAMETER or PARAMETER statement to accept the values passed from the server application. If a notify link is established, the user-defined function is executed and the empty string is passed in the Data parameter. You can issue DDERequest( ) later to retrieve the data. If an automatic link is established, the user-defined function is executed and the data is passed in the Data parameter. The Action parameter contains ADVISE when the link is being updated by the server. The user-defined function is called, and the Action parameter contains TERMINATE when the link is closed by the client or server. Any value returned by the user-defined function is ignored.
nLinkType

Specifies the link type in the following way:

nLinkType Link type

0

Manual

1

Notify

2

Automatic
You can turn off notification from the server application by specifying 0 for nLinkType. If the item changes, the user-defined function is not executed.

Return Value

Logical

Remarks

DDEAdvise( ) is used to create a notify link or an automatic link to an item name in a server application. When a notify link is created with DDEAdvise( ), the server application notifies Visual FoxPro that the item name has been modified. If an automatic link is created, the server application notifies Visual FoxPro that the item name has been modified and passes the new data to Visual FoxPro.

Before you can create a link, you must establish a channel to the server application with DDEInitiate( ).

You can also use DDEAdvise( ) to turn off notification from the server.

DDEAdvise( ) returns a true value (.T.) if it executes successfully; otherwise, it returns false (.F.).

Example

The following example demonstrates how you can establish a DDE channel to a Microsoft Excel worksheet named Sheet1. DDEAdvise( ) is used to establish two links to data in two worksheet cells (R1C1 and R1C2). The user-defined function NEWDATA is executed when data in either of the cells changes. The user-defined function tests the item and advise parameters to determine which item changed and what kind of link has been established.
Copy Code
PUBLIC mchannum
mchannum = DDEInitiate('Excel', 'Sheet1')
IF mchannum != -1
   = DDEAdvise(mchannum, 'R1C1', 'newdata', 1)     && Notify link
   = DDEAdvise(mchannum, 'R1C2', 'newdata', 2)     && Automatic link
   WAIT WINDOW 'Enter data in first two cells in Excel.'
ENDIF
PROCEDURE newdata
PARAMETERS channel, action, item, data, format, advise
IF action = 'ADVISE'
   DO CASE
      CASE item = 'R1C1'   && Notify link
         newvalue = DDERequest(channel, item)
         ? 'R1C1 notify link: ' + newvalue
      CASE item = 'R1C2'   && Automatic link
         newvalue = data
         ? 'R1C2 automatic link: ' + newvalue
   ENDCASE
ELSE
   IF action != "TERMINATE"
      = DDETerminate(mchannum)
 ENDIF
ENDIF

See Also

Other Resources

DDEInitiate( ) Function
DDELastError( ) Function
DDESetOption( ) Function
DDETerminate( ) Function
Functions
Language Reference


DDEEnabled( ) Function

Visual FoxPro 9.0 Language Reference
DDEEnabled( ) Function
See Also

Enables or disables dynamic data exchange (DDE) processing or returns the status of DDE processing.

DDEEnabled([lExpression1 | nChannelNumber [, lExpression2]])

Parameters

lExpression1

Specify true (.T.) or false (.F.) to globally enable or disable DDE processing. DDEEnabled( ) returns true (.T.) if DDE processing is successfully enabled or disabled; otherwise false (.F.) is returned.
nChannelNumber

Specifies the channel number for the channel whose DDE processing status DDEEnabled( ) returns. DDEEnabled( ) returns true (.T.) if DDE processing is enabled for the specified channel and returns false (.F.) if DDE processing is disabled.
lExpression2

To enable DDE processing for a specific channel, include the channel number (nChannelNumber) and specify true (.T.) for lExpression2. To disable DDE processing for a specific channel, include the channel number (nChannelNumber) and specify false (.F.) for lExpression2.

Return Value

Logical

Remarks

Using DDEEnabled( ), you can globally enable or disable processing. You can also enable or disable DDE processing for specific channels.

DDEEnabled( ) can be used to protect critical code or disable links for short periods. When DDE processing is disabled, client requests are queued until DDE processing is enabled.

If DDEEnabled( ) is issued without any of its optional arguments, the global DDE processing status is returned. DDEEnabled( ) returns true (.T.) if DDE processing has been globally enabled and false (.F.) if DDE processing has been globally disabled.

See Also

Other Resources

DDEAbortTrans( ) Function
DDEAdvise( ) Function
DDEExecute( ) Function
DDEInitiate( ) Function
DDELastError( ) Function
DDEPoke( ) Function
DDERequest( ) Function
DDESetOption( ) Function
DDESetService( ) Function
DDESetTopic( ) Function
DDETerminate( ) Function
Functions
Language Reference


DDEExecute( ) Function

Visual FoxPro 9.0 Language Reference
DDEExecute( ) Function
See Also Example

Sends a command to another application, using dynamic data exchange (DDE).

DDEExecute(nChannelNumber, cCommand [, cUDFName])

Parameters

nChannelNumber

Specifies the channel number.
cCommand

Specifies the command you want to send to the other application. The format of the command is determined by the application you are sending it to. Consult the application's documentation for the correct syntax.
cUDFName

Allows asynchronous command execution requests. If you omit cUDFName, a client application waits for the period specified with DDESetOption( ). If you specify a user-defined function with cUDFName, client program execution continues immediately after the command execution request is made. When the server application finishes executing the command, the user-defined function you specify with cUDFName is executed. The user-defined function is passed six parameters in the order shown in the following table.

Parameter Contents

Channel Number

The channel number of the server application.

Action

XACTCOMPLETE (successful execution).XACTFAIL (failed command execution).

Item

The item name; for example, R1C1 for a Microsoft Excel worksheet cell.

Data

The new data (REQUEST) or data passed (POKE or EXECUTED).

Format

The data format; for example, CF_TEXT.

Transaction Number

The transaction number returned by DDEExecute( ).
Use DDEAbortTrans( ) to cancel an uncompleted transaction. If the transaction fails, you can use DDELastError( ) to determine why it failed. When you include cUDFName, DDEExecute( ) does not return a logical value. Instead, a transaction number is returned; if an error occurs, –1 is returned.

Return Value

Logical

Remarks

The command sent with DDEExecute( ) must be understood by the application. Before you can execute the command, you must establish a channel to the server application with DDEInitiate( ).

For example, Microsoft Excel has an extensive set of macro commands, including DDE commands that let you request data from Visual FoxPro from within Microsoft Excel. If you establish a channel to Microsoft Excel, you can then use DDEExecute( ) to send macro commands to Excel from within Visual FoxPro.

If the receiving application successfully executes the command, DDEExecute( ) returns true (.T.). If the receiving application cannot successfully execute the command or if the channel number you include is not valid, DDEExecute( ) returns false (.F.). If the optional asynchronous user-defined function cUDFName is included, a transaction number is returned. If an error occurs, DDEExecute( ) returns –1.

Example

The following example uses DDEInitiate( ) to establish a DDE channel between Visual FoxPro and the Microsoft Excel worksheet Sheet1. DDEExecute( ) is used to execute a Microsoft Excel command that maximizes the Microsoft Excel window.
Copy Code
gnChanNum = DDEInitiate('Excel', 'Sheet1')
IF gnChanNum != -1
   glExecute = DDEExecute(gnChanNum, '[App.Maximize]')
   IF glExecute != .F.
      WAIT WINDOW 'EXCEL window has been zoomed out.'
   ENDIF
   = DDETerminate(gnChanNum)   && Close the channel
ENDIF

See Also

Other Resources

DDEAbortTrans( ) Function
DDEInitiate( ) Function
DDELastError( ) Function
DDESetOption( ) Function
DDETerminate( ) Function
Functions
Language Reference


DDEInitiate( ) Function

Visual FoxPro 9.0 Language Reference
DDEInitiate( ) Function
See Also Example

Establishes a dynamic data exchange (DDE) channel between Visual FoxPro and another Microsoft Windows-based application.

DDEInitiate(cServiceName, cTopicName)

Parameters

cServiceName

Specifies the service name of the server application, which, in most cases, is the name of the executable file without its extension. The default service name for Visual FoxPro is Visual FoxPro. If you are establishing a channel to Microsoft Excel, cServiceName is Excel.
cTopicName

Specifies the topic name. The topic is application-specific and must be understood by the application. For example, one topic supplied by most DDE servers is the System topic. See the application documentation for the service and topic names supported by the application.

Return Value

Numeric

Remarks

DDEInitiate( ) establishes a DDE channel between Visual FoxPro and a DDE server application. Once a channel is established, Visual FoxPro can request data from the server by referring to the channel in subsequent DDE functions. Visual FoxPro acts as the client, requesting data from the server application through the channel.

If the channel is successfully established, DDEInitiate( ) returns the channel number. Channel numbers are non-negative, and the number of channels you can establish is limited only by your system resources.

DDEInitiate( ) returns –1 if the channel cannot be established. If the server application is not open, Visual FoxPro asks if you would like to open it. If you choose Yes, Visual FoxPro attempts to open the application. (You can use DDELastError( ) to determine why a channel cannot be established.)

To avoid being asked whether you want to open the application, set the DDESetOption( ) SAFETY option. You can also use RUN with the /N option to start the application.

A channel can be closed with DDETerminate( ).

Example

The following example uses DDEInitiate( ) to establish a DDE channel between Visual FoxPro and a Microsoft Excel worksheet named Sheet1. 'Excel' is the service name, and 'Sheet1' is the topic name. The channel number is stored to the memory variable mchannum for use in subsequent DDE functions.
Copy Code
mchannum = DDEInitiate('Excel', 'Sheet1')
IF mchannum != -1
   * Process client actions
   = DDETerminate(mchannum)  && Close the channel
ENDIF

See Also

Other Resources

DDEAdvise( ) Function
DDEEnabled( ) Function
DDEExecute( ) Function
DDELastError( ) Function
DDEPoke( ) Function
DDERequest( ) Function
DDESetOption( ) Function
DDETerminate( ) Function
RUN | ! Command
Functions
Language Reference


DDELastError( ) Function

Visual FoxPro 9.0 Language Reference
DDELastError( ) Function
See Also

Returns an error number for the last dynamic data exchange (DDE) function.

DDELastError( )

Return Value

Numeric

Remarks

You can use DDELastError( ) to help determine the cause of an error when a DDE function does not execute successfully.

DDELastError( ) returns 0 if the last DDE function executed successfully. It returns a nonzero value if the last DDE function was unsuccessful. The following table lists the error numbers and their descriptions.

Error number | Description
1 | Service busy
2 | Topic busy
3 | Channel busy
4 | No such service
5 | No such topic
6 | Bad channel
7 | Insufficient memory
8 | Acknowledge timeout
9 | Request timeout
10 | No DDEInitiate( )
11 | Client attempted server transaction
12 | Execute timeout
13 | Bad parameter
14 | Low memory
15 | Memory error
16 | Connect failure
17 | Request failure
18 | Poke timeout
19 | Could not display message
20 | Multiple synchronous transactions
21 | Server died
22 | Internal DDE error
23 | Advise timeout
24 | Invalid transaction identifier
25 | Unknown

See Also

Other Resources

DDEAbortTrans( ) Function
DDEAdvise( ) Function
DDEEnabled( ) Function
DDEExecute( ) Function
DDEInitiate( ) Function
DDEPoke( ) Function
DDERequest( ) Function
DDESetOption( ) Function
DDESetService( ) Function
DDESetTopic( ) Function
DDETerminate( ) Function
Functions
Language Reference


DDEPoke( ) Function

Visual FoxPro 9.0 Language Reference
DDEPoke( ) Function
See Also

Sends data between client and server applications in a dynamic data exchange (DDE) conversation.

DDEPoke(nChannelNumber, cItemName, cDataSent
   [, cDataFormat [, cUDFName]])

Parameters

nChannelNumber

Specifies the channel number of the application data is sent to. If the channel number is a server channel, DDEPoke( ) sends the data in response to a request or a previously established notify or automatic link.
cItemName

Specifies the item name to which data is sent. The item name is application-specific and must be understood by the application. For example, Microsoft Excel supports R1C1 as a valid item name that refers to the first cell in a worksheet.
cDataSent

Specifies the data sent to the item name specified with cItemName.
cDataFormat

Specifies the format used to send the data. The default format is CF_TEXT. In this format, fields are delimited with tabs and records are delimited with a carriage return and a linefeed.
cUDFName

Allows asynchronous data transfer. If cUDFName is omitted, a client waits for the period specified with DDESetOption( ). If you specify the name of a user-defined function with cUDFName, client program execution continues immediately after the request is made. When the data is available from the server application, the user-defined function specified with cUDFName is executed. The user-defined function is passed six parameters in this order:

Parameter Contents

Channel Number

The channel number of the server application.

Action

XACTCOMPLETE (successful transaction).XACTFAIL (failed transaction).

Item

The item name; for example, R1C1 for a Microsoft Excel worksheet cell.

Data

The new data (REQUEST) or data passed (POKE or EXECUTED).

Format

The data format; for example, CF_TEXT.

Transaction Number

The transaction number returned by DDEPoke( ).
Use DDEAbortTrans( ) to cancel an uncompleted transaction. If the transaction fails, you can use DDELastError( ) to determine why it failed. When you include cUDFName, DDEPoke( ) returns a transaction number if successful or –1 if an error occurs.

Return Value

Logical

Remarks

DDEPoke( ) sends data as a character string to the item name in the application specified by the channel number.

If the data is successfully sent, DDEPoke( ) returns true (.T.). If the data cannot be sent, DDEPoke( ) returns false (.F.). If the asynchronous user-defined function cUDFName is included, DDEPoke( ) returns a transaction number; if an error occurs, DDEPoke( ) returns –1.

See Also

Other Resources

DDEAbortTrans( ) Function
DDEInitiate( ) Function
DDELastError( ) Function
DDESetOption( ) Function
DDETerminate( ) Function
Functions
Language Reference


DDERequest( ) Function

Visual FoxPro 9.0 Language Reference
DDERequest( ) Function
See Also Example

Requests data from a server application in a dynamic data exchange (DDE) conversation.

DDERequest(nChannelNumber, cItemName [, cDataFormat [, cUDFName]])

Parameters

nChannelNumber

Specifies the channel number of the server application.
cItemName

Specifies the item name. The item name is application-specific and must be understood by the application. For example, Microsoft Excel uses row and column notation to refer to cells in a worksheet. The item name R1C1 designates the cell in the first row and first column of the worksheet.
cDataFormat

Specifies a format for the data requested. The default format is CF_TEXT. In this format, fields are delimited with tabs and records are delimited with a carriage return and a line feed.
cUDFName

Allows an asynchronous data transfer. If you omit cUDFName, Visual FoxPro waits for the data from the server for the period specified with DDESetOption( ). If you specify the name of a user-defined function with cUDFName, Visual FoxPro continues program execution immediately after the request is made. When the data is available from the server application, the user-defined function specified with cUDFName is executed. The user-defined function is passed six parameters in this order:

Parameter Contents

Channel Number

The channel number of the server application.

Action

XACTCOMPLETE (successful transaction).XACTFAIL (failed transaction).

Item

The item name; for example, R1C1 for a Microsoft Excel worksheet cell.

Data

The new data (REQUEST) or data passed (POKE or EXECUTED).

Format

The data format; for example, CF_TEXT.

Transaction Number

The transaction number returned by DDERequest( ).
Use DDEAbortTrans( ) to cancel an uncompleted transaction. If the transaction fails, you can use DDELastError( ) to determine why it failed. When you include cUDFName, DDERequest( ) returns a transaction number equal to or greater than 0 if successful, or –1 if an error occurs.

Return Value

Character

Remarks

Before you can request data using DDERequest( ), you must establish a channel to the server application with DDEInitiate( ).

If the request for data is successful, DDERequest( ) returns the data as a character string. If the request fails, DDERequest( ) returns an empty string and DDELastError( ) returns a nonzero value. If you include the asynchronous user-defined function cUDFName, DDERequest( ) returns a transaction number if successful, or –1 if an error occurs.

Example

The following example uses DDEInitiate( ) to establish a DDE channel between Visual FoxPro and a Microsoft Excel worksheet named Sheet1. 'Excel' is the service name, and 'Sheet1' is the topic name. The channel number is stored to the memory variable mchannum for use in subsequent DDE functions.

DDERequest( ) requests the item name R1C1, the data in the first row and column of the Sheet1 spreadsheet.
Copy Code
mchannum = DDEInitiate('Excel', 'Sheet1')
IF mchannum != -1
   mrequest = DDERequest(mchannum, 'R1C1')
   IF !EMPTY(mrequest) AND DDELastError( ) = 0      && Successful
      WAIT WINDOW 'R1C1 contents: ' + mrequest
   ENDIF
   = DDETerminate(mchannum)            && Close the channel
ENDIF

See Also

Other Resources

DDEAbortTrans( ) Function
DDEInitiate( ) Function
DDELastError( ) Function
DDESetOption( ) Function
DDETerminate( ) Function
Functions
Language Reference


DDESetOption( ) Function

Visual FoxPro 9.0 Language Reference
DDESetOption( ) Function
See Also

Changes or returns dynamic data exchange (DDE) settings.

DDESetOption(cOption [, nTimeoutValue | lExpression])

Parameters

cOption

Specifies the setting options.

cOption Setting Default Description

TIMEOUT

nTimeoutValue (number of milliseconds)

2000

The number of milliseconds DDE functions wait for the server application to respond; the current TIMEOUT value is returned if you omit nTimeoutValue.

SAFETY

lExpression(true (.T.) or false (.F.))

.T.

Specifies whether a dialog is displayed when you use DDEInitiate( ) to establish a channel to a server application and the application does not respond; the current SAFETY setting is returned if you omit lExpression.
nTimeoutValue

Specifies the timeout value.
lExpression

Enables or disables dialog display.

Return Value

Logical or Numeric

Remarks

Use DDESetOption( ) to change or return DDE settings. Two options, TIMEOUT and SAFETY, are available.

See Also

Other Resources

DDEAdvise( ) Function
DDEEnabled( ) Function
DDEExecute( ) Function
DDEInitiate( ) Function
DDEPoke( ) Function
DDERequest( ) Function
DDESetService( ) Function
DDETerminate( ) Function
Functions
Language Reference


DDESetService( ) Function

Visual FoxPro 9.0 Language Reference
DDESetService( ) Function
See Also

Creates, releases, or modifies DDE service names and settings.

DDESetService(cServiceName, cOption [, cDataFormat | lExpression])

Parameters

cServiceName

Specifies the service name to create, release, modify, or return information about.
cOption

Specifies to create, release, or modify a service name or to return information about a service name. The following table lists the options you can specify with cOption, the default values for the options and a description of each option.

Option Default value Description

DEFINE

–

Creates a new service name.

RELEASE

–

Releases an existing service name.

ADVISE

.F.

Enables or disables client notification of changes to item names.

EXECUTE

.F.

Enables or disables command execution.

POKE

.F.

Enables or disables client pokes to the service.

REQUEST

.T.

Enables or disables requests to the service name.

FORMATS

CF_TEXT

Specifies supported data formats.
DEFINE

Creates a new service name. For example, the following command creates the service name myservice:
Copy Code
glNewService = DDESetService('myservice', 'DEFINE')
RELEASE

Releases an existing service name to free up system resources. When a service name is released, all of the service's topic names are also released. The following command releases the service name created in the previous example:
Copy Code
glRelease = DDESetService('myservice', 'RELEASE')
To release the default Visual FoxPro service, issue this command:
Copy Code
glRelFox = DDESetService('FoxPro', 'RELEASE')
ADVISE

Specifies whether a client is notified when data changes in an item name or specifies to return the current advise status for a service name. Refer to DDEAdvise( ) for additional information about advising clients. To enable client notification, specify true (.T.) for lExpression. Specifying false (.F.) for lExpression disables client notification. To return the current client notification status for the service name, omit lExpression. DDESetService( ) returns true if client notification is enabled for the service name; it returns false if client notification is disabled.
EXECUTE

Allows you to enable or disable command execution requests to a service name or to determine the current execute status for a service name. To enable client requests to execute a command, specify true (.T.) for lExpression. Specifying false (.F.) for lExpression disables client requests to execute a command. .F. is the default value. To return the current command execution status for the service name, omit lExpression. DDESetService( ) returns true if client command execution requests are enabled for the service name; otherwise, it returns false. The following commands enable command execution and disable data requests from client applications for the service name myservice. The current command execution status for myservice is then displayed:
Copy Code
glExecute = DDESetService('myservice', 'EXECUTE', .T.)
glRequest = DDESetService('myservice', 'REQUEST', .F.)
? DDESetService('myservice', 'EXECUTE')
POKE

Allows you to enable or disable poke requests to the service name. You can also determine the current poke status for a service name. Refer to DDEPoke( ) for additional information about poking data to a server or a client. To enable client poke requests, specify true (.T.) for lExpression. Specifying false (.F.) for lExpression disables client poke requests. .F. is the default value. To return the current poke status for the service name, omit lExpression. DDESetService( ) returns true if poke requests are enabled for a service name; it returns false if poke requests are disabled.
REQUEST

Use REQUEST to enable or disable client requests to a service name or to return the current request status for the service name. To enable client requests to the service name, specify true (.T.) for lExpression. Specifying false (.F.) disables client requests to the service name. True (.T.) is the default value. To return the current request status for a service name, omit lExpression. DDESetService( ) returns true if client requests are enabled for the service name; it returns false if client requests are disabled. The following commands disable requests from client applications to the service name myservice and display the current request status for myservice:
Copy Code
glRequest = DDESetService('myservice', 'REQUEST', .F.)
? DDESetService('myservice', 'REQUEST')
FORMATS [ cDataFormat]

Specifies the data formats supported by the service name. Server requests for formats not specified with cDataFormat are rejected. When specifying data formats, include a list of the supported formats separated by commas. For example:
Copy Code
=DDESetService('myservice', 'FORMATS', 'CF_TEXT, CF_SYLK')
If you omit cDataFormat, only the CF_TEXT format is supported.
lExpression

Specifies the state of the REQUEST, EXECUTE, POKE, or ADVISE options. Specify true (.T.) for lExpression to enable the option or false (.F.) to disable it.

Return Value

Logical

Remarks

Visual FoxPro can act as a dynamic data exchange (DDE) server to send data to client Microsoft Windows-based applications. DDESetService( ) is used to create, release, or modify service names and settings in Visual FoxPro. Each service name can have a set of topic names created with DDESetTopic( ). Client applications request data from DDE topic names.

DDESetService( ) returns true (.T.) if the service name is successfully created, released, or modified. If the service name cannot be created, released, or modified, DDESetService( ) returns false (.F.).

DDESetService( ) can also be used to return information about a service name. Visual FoxPro has the default service name FoxPro. The Visual FoxPro service name has one topic name called System. The following table lists all the item names supported by the System topic.

Item name | Item
Topics | A list of available topic names
Formats | A list of supported formats
Status | Busy or Ready
SysItems | A list of item names

You can use DDESetTopic( ) to modify the FoxPro service name or to release it. For information about manipulating Visual FoxPro service names, see the DDESetTopic( ) options.

See Also

Other Resources

DDEEnabled( ) Function
DDELastError( ) Function
DDEPoke( ) Function
DDESetTopic( ) Function
Functions
Language Reference


DDESetTopic( ) Function

Visual FoxPro 9.0 Language Reference
DDESetTopic( ) Function
See Also Example

Creates or releases a topic name from a service name in a dynamic data exchange (DDE) conversation.

DDESetTopic(cServiceName, cTopicName [, cUDFName])

Parameters

cServiceName

Specifies the service name. Additional service names can be created with DDESetService( ).
cTopicName

Specifies the topic name to create or release. If you include cUDFName, DDESetTopic( ) creates the topic name cTopicName. If you omit cUDFName, the topic name cTopicName is released. If cTopicName is an empty string, the user-defined function specified with cUDFName is executed for any topic name that is not explicitly declared.
cUDFName

Specifies the name of the user-defined function executed when a client application makes a request to the topic name. If you omit cUDFName, the topic name cTopicName is released from the service name. When the user-defined function is executed, it is passed the following six parameters in the order given below:

Parameter Contents

Channel Number

The client channel number.

Action

ADVISE, EXECUTE, INITIATE, POKE, REQUEST, or TERMINATE.

Item

The item name; for example, R1C1 for a Microsoft Excel worksheet cell.

Data

Data from the client.

Format

The data format; for example, CF_TEXT.

Advise Status

The link type (0 = manual, 2 = notify or automatic).
The values of the Item, Data, and Advise Status parameters depend on the Action parameter. The following table lists the Action parameter values and the values contained in the Item, Data, and Advise Status parameters. A dash (–) indicates that the parameter value is the empty string.

Action value Item value Data value Advise status

INITIATE

–

Topic name

–

TERMINATE

–

–

–

POKE

Item name

New data

–

REQUEST

Item name

–

–

EXECUTE

–

New command

–

ADVISE

Item name

–

Link type
If the user-defined function successfully handles the client request, the user-defined function should return true (.T.). If the request cannot be handled or an error occurs, the user-defined function should return false (.F.). If false is returned when the Action parameter value is INITIATE, the client topic name request is rejected. If false is returned when the value is POKE, REQUEST, or EXECUTE, the request is ignored. If false is returned when the value is ADVISE, the client request for a notify or automatic link is rejected.

Return Value

Logical

Remarks

After a topic name is created, any client requests to the topic name cause Visual FoxPro to execute the user-defined function specified with cUDFName. The user-defined function is passed a set of parameters whose values are determined by the client request. The user-defined function return value is passed to the client with DDEPoke( ). The return value is a logical value indicating whether the topic name can provide the service requested by the client.

DDESetTopic( ) returns true (.T.) if it successfully creates or releases the topic name. It returns false (.F.) if the topic name cannot be created or released. Use DDELastError( ) to determine why a topic name cannot be created or released.

Example

The following example creates a basic sample server called myserver that supports Visual FoxPro command execution from a client application. The client application makes requests to myserver through the DO topic, and macro substitution is used to execute the client's command.

Copy Code
*** Set Visual FoxPro up as a DDE server ***
= DDESetService('myserver', 'DEFINE')
= DDESetService('myserver', 'EXECUTE', .T.)
= DDESetTopic('myserver', 'DO', 'DOTOPIC')
WAIT WINDOW 'Server portion service setup ... ' NOWAIT
*** Use Visual FoxPro as a DDE client ***
gnChannel = DDEInitiate('myserver','DO')
=DDEExecute(gnChannel, 'WAIT WINDOW "Command Executed ... "')
=DDETerminate(gnChannel)
PROCEDURE dotopic
PARAMETERS gnChannel, gcAction, gcItem, gData, gcFormat, gnAdvise
glResult = .F.
*** It's necessary to return .T. from an   ***
*** INITIATE action or no connection is made ***
IF gcAction = 'INITIATE'
   glResult = .T.
ENDIF
IF gcAction = 'EXECUTE'
   &gData
   glResult = .T.
ENDIF
IF gcAction = 'TERMINATE'
   WAIT WINDOW 'Goodbye ... ' NOWAIT
   glResult = .T.
ENDIF
RETURN glResult

After running this example program, you have set up Visual FoxPro service, which other applications can access. If you have Microsoft Excel, you can run the following Excel macro:

Copy Code
gnMyChan = INITIATE("myserver","DO")
=EXECUTE(MyChan,"WAIT WINDOW 'Hi, this is EXCEL speaking'")
=RETURN( )

See Also

Other Resources

DDEEnabled( ) Function
DDELastError( ) Function
DDEPoke( ) Function
DDESetService( ) Function
Functions
Language Reference


DDETerminate( ) Function

Visual FoxPro 9.0 Language Reference
DDETerminate( ) Function
See Also

Closes a dynamic data exchange (DDE) channel established with DDEInitiate( ).

DDETerminate(nChannelNumber | cServiceName)

Parameters

nChannelNumber

Specifies the channel number to close.
cServiceName

Specifies the service name to close.

Return Value

Logical

Remarks

If the channel is successfully closed, DDETerminate( ) returns true (.T.). If the channel cannot be closed, DDETerminate( ) returns false (.F.).

Be sure to close channels as soon as they are no longer needed to conserve system resources.

All channels are automatically closed if you exit Visual FoxPro by choosing Exit from the File menu or by issuing QUIT in the Command window or from within a program.

See Also

Other Resources

DDEAbortTrans( ) Function
DDEAdvise( ) Function
DDEExecute( ) Function
DDEInitiate( ) Function
DDELastError( ) Function
DDEPoke( ) Function
DDERequest( ) Function
DDESetOption( ) Function
Functions
Language Reference


DEFAULTEXT( ) Function

Visual FoxPro 9.0 Language Reference
DEFAULTEXT( ) Function
See Also

Returns a file name with a new extension if one does not already exist.

DEFAULTEXT(cFileName, cDefault)

Parameters

cFileName

Specifies the filename (with or without a path or extension) to be returned.
cDefault

Specifies the default extension without a period.

Return Value

Character

See Also

Other Resources

ADDBS( ) Function
FILE( ) Function
FORCEEXT( ) Function
FORCEPATH( ) Function
JUSTDRIVE( ) Function
JUSTEXT( ) Function
JUSTFNAME( ) Function
JUSTPATH( ) Function
JUSTSTEM( ) Function
Functions
Language Reference


DELETED( ) Function

Visual FoxPro 9.0 Language Reference
DELETED( ) Function
See Also Example

Returns a logical value that indicates whether the current record is marked for deletion.

DELETED([cTableAlias | nWorkArea])

Parameters

cTableAlias| nWorkArea

You can check the status of the current record in a table open in another work area by specifying the work area number with nWorkArea or the table alias with cTableAlias. If a table isn't open in the work area you specify, DELETED( ) returns false. If you omit cTableAlias and nWorkArea, the deleted status is returned for the current record in the current work area.

Return Value

Logical

Remarks

If the record is marked for deletion, DELETED( ) returns true (.T.); otherwise, DELETED( ) returns false (.F.).

Records can be marked for deletion with DELETE and DELETE – SQL, and they can be unmarked with RECALL.

Rushmore Query Optimization optimizes queries that test the deleted status of records if the table is indexed on DELETED( ).

For information on using Rushmore to optimize queries, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access.

Example

The following example opens the customer table in the testdata database. DELETE – SQL is used to mark all records for deletion where the country field contains USA. DELETED( ) is used to display all the records marked for deletion. RECALL ALL is used to unmark all the records marked for deletion.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

DELETE FROM customer WHERE country = 'USA'  && Mark for deletion
CLEAR
LIST FIELDS company, country FOR DELETED( ) && List marked records
RECALL ALL  && Unmark all records marked for deletion

See Also

Other Resources

DELETE Command
DELETE – SQL Command
PACK Command
RECALL Command
SET DELETED Command
Functions
Language Reference


DESCENDING( ) Function

Visual FoxPro 9.0 Language Reference
DESCENDING( ) Function
See Also Example

Returns a logical value that indicates whether an index tag was created with the DESCENDING keyword or whether the DESCENDING keyword was included in USE, SET INDEX, or SET ORDER.

DESCENDING([CDXFileName[, nIndexNumber [, nWorkArea | cTableAlias]]])

Parameters

CDXFileName

Specifies the name of a compound index file with CDXFileName. The compound index file you specify can be the structural compound index file automatically opened with the table or an independent compound index file.
nIndexNumber

Specifies which index tag or index file DESCENDING( ) tests. nIndexNumber is typically an integer that starts at 1 and is increased by 1 to return additional values for each index tag. If nIndexNumber is 1, a value for the master single-entry .idx index file or master index tag (if one is present) is returned. As nIndexNumber increases, values for each tag in the structural compound index (if one is present) are returned. The values are returned for the tags in the order in which the tags were created in the structural compound index. After values for all the tags in the structural compound index are returned, values for each tag in any open independent compound indexes are then returned. The values are returned from the tags in the order in which the tags are created in the independent compound indexes. The empty string is returned if nIndexNumber is greater than the total number of open, single-entry .idx files and structural compound and independent compound index tags.
nWorkArea| cTableAlias

Returns values for index files or tags open in a work area other than the current work area. nWorkArea specifies the work area number and cTableAlias specifies the table alias. If no table has the alias you specify, Visual FoxPro generates an error message.

Return Value

Logical

Remarks

You can order records in a table in descending order in two ways:

  • You can include the DESCENDING keyword in the INDEX command to create a descending order index tag in a compound .cdx.

  • You can include the DESCENDING keyword in USE, SET INDEX or SET ORDER to specify a descending order for the master index tag or the master single-entry index (.idx) file.

DESCENDING( ) can determine if an index tag was created in descending order. DESCENDING( ) returns true (.T.) if the index tag you specify was created with the DESCENDING keyword.

DESCENDING( ) can also determine if the master index tag or master index file is in descending order. DESCENDING( ) returns true (.T.) if the DESCENDING keyword was included in USE, SET INDEX, or SET ORDER for the master index tag or a single-entry index (.idx) file you specify.

If you don't include any of the optional arguments, DESCENDING( ) returns a value for the master index tag or master index file. If you don't include any of the optional arguments and a master index tag or .idx file isn't in effect (for example, you've issued SET ORDER TO to place the table in physical record order), DESCENDING( ) returns false (.F.).

Example

The following example opens the customer table in the testdata database. FOR ... ENDFOR is used to create a loop in which the descending status of each index tag in the customer structural index is checked. The name of each structural index tag is displayed with its descending status.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer     && Open customer table
CLEAR

FOR nCount = 1 TO TAGCOUNT( )
   IF !EMPTY(TAG(nCount))  && Checks for tags in the index
   ? TAG(nCount) + ' Descending? ' && Display tag name
   ?? DESCENDING(nCount)  && Display descending status
   ELSE
      EXIT  && Exit the loop when no more tags are found
   ENDIF
ENDFOR

See Also

Other Resources

INDEX Command
SET INDEX Command
SET ORDER Command
USE Command
Functions
Language Reference


DIFFERENCE( ) Function

Visual FoxPro 9.0 Language Reference
DIFFERENCE( ) Function
See Also Example

Returns an integer, 0 through 4, which represents the relative phonetic difference between two character expressions.

DIFFERENCE(cExpression1, cExpression2)

Parameters

cExpression1, cExpression2

Specifies the character expressions that DIFFERENCE( ) compares.

Return Value

Numeric

Remarks

DIFFERENCE( ) is useful for searching tables when the exact spelling of an entry isn't known.

The more alike the two expressions are spelled, the higher the number DIFFERENCE( ) returns. If the character expressions are spelled very similarly, DIFFERENCE( ) returns 4. For two character expressions with little in common phonetically, DIFFERENCE( ) returns 0.

Example

Copy Code
STORE 'Smith' TO gcName1
STORE 'Smythe'  TO gcName2
STORE 'Smittie' TO gcName3
STORE '' TO gcName4
CLEAR
? DIFFERENCE(gcName1, gcName2)  && Displays 4
? DIFFERENCE(gcName1, gcName3)  && Displays 4
? DIFFERENCE(gcName1, gcName4)  && Displays 1

See Also

Other Resources

SOUNDEX( ) Function
Functions
Language Reference


DIRECTORY( ) Function

Visual FoxPro 9.0 Language Reference
DIRECTORY( ) Function
See Also

Locates the specified directory.

DIRECTORY(cDirectoryName [, nFlags])

Parameters

cDirectoryName

Specifies the name of the directory to locate. If you do not include an absolute path for the directory you specify, Visual FoxPro searches for the directory relative to the Visual FoxPro default directory.
nFlags

Specifies the kind of value DIRECTORY( ) returns when the directory exists but might be marked with the Hidden or System attribute. The following table lists the values for nFlags.

nFlags Description

0

DIRECTORY( ) returns False (.F.) if the directory exists but is marked with a Hidden or System attribute. (Default)

1

DIRECTORY( ) returns True (.T.) if the directory exists, regardless of its attributes. Setting nFlags to 1 allows you to check for hidden or system files.

Return Value

Logical data type. DIRECTORY( ) returns True (.T.) if the specified directory is found on the disk; otherwise, it returns False (.F.).

Remarks

The SET DEFAULT command specifies the Visual FoxPro default directory.

You can use the ADIR( ) function to determine specific attributes for the directory.

You can use the CD and CHDIR commands to switch to hidden files and directories.

See Also

Other Resources

SET DEFAULT Command
ADIR( ) Function
CD | CHDIR Command
FILE( ) Function
GETDIR( ) Function
GETFILE( ) Function
Functions
Language Reference


DISKSPACE( ) Function

Visual FoxPro 9.0 Language Reference
DISKSPACE( ) Function
See Also Example

Retrieves the number of bytes with the specified type that are available on the default or specified hard disk drive or volume.

DISKSPACE([cVolumeName [, nType]])

Parameters

cVolumeName

Specifies the name of the hard disk drive or volume for which the available space is returned. If you omit cVolumeName, the available space is returned for the default disk drive or volume.
nType

Specifies the type of hard disk space to retrieve. The following table lists the values for nType.

Value Description

1

Total amount of space on the hard disk drive.

2

Total amount of free space on the hard disk drive. (Default)

3

Total amount of free space available to the user associated with the calling thread.

Return Value

Numeric. DISKSPACE( ) returns the number of bytes with the type specified. If the hard disk is full, DISKSPACE( ) returns a value of 0 or -1. If an error occurs when reading the hard disk drive or volume, DISKSPACE( ) can also return a value of –1.

Note:
The return value of DISKSPACE( ) might not be accurate for large network drives on some networks. Additionally, DISKSPACE( ) may return -1 for certain long named directories on Windows 98.

Remarks

You can use DISKSPACE( ) to determine if sufficient space is available to back up files or to execute commands such as SORT that require additional disk space for temporary work files.

You can specify the default disk drive or volume using the SET DEFAULT command.

Example

The following example uses DISKSPACE( ) to determine whether sufficient disk space is available to perform a sort operation.
Copy Code
*** Check DISKSPACE before sort ***
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

*** Get size of table header ***
gnTableHead = HEADER( )

*** Calculate size of table ***
gnFileSize = gnTableHead + (RECSIZE( ) * RECCOUNT( ) + 1)
IF DISKSPACE( ) > (gnFileSize * 3)
   WAIT WINDOW 'Sufficient diskspace to sort.'
ELSE
   WAIT WINDOW 'Insufficient diskspace. Sort cannot be done.'
ENDIF

See Also

Other Resources

HEADER( ) Function
RECSIZE( ) Function
SET DEFAULT Command
Functions
Language Reference


DisplayPath( ) Function

Visual FoxPro 9.0 Language Reference
DisplayPath( ) Function
See Also

Truncates long path expressions to a specified length for display.

DisplayPath(cFilename, nMaxLength)

Parameters

cFileName

Specifies the name of the file at the end of the target path. If you specify a string containing only spaces as cFileName, Visual FoxPro returns the current directory. If you specify an empty string as cFileName, DISPLAYPATH( ) returns an empty string. You can obtain the path of the current directory by using the CURDIR( ).
Note:
This function does not check the validity of cFileName and will report the truncated path expression even if no such file exists.

nMaxLength

Specifies the maximum length of the truncated result. nMaxLength must be greater than or equal to 10.

Returns

Character data type. DisplayPath( ) returns a string and displays the path in lower case.

Remarks

DisplayPath( ) returns a string suitable only for display purposes, so you cannot use the result to reference a file. The length of the resulting string is equal to or less than nMaxLength. However, the result does not break directory names. If inclusion of a directory name would exceed nMaxLength, the result is an ellipsis (...). If the filename exceeds nMaxLength, the result is the filename plus extension.

See Also

Reference

CURDIR( ) Function

Other Resources

JUSTPATH( ) Function
ADIR( ) Function
Functions
Language Reference


DMY( ) Function

Visual FoxPro 9.0 Language Reference
DMY( ) Function
See Also Example

Returns a character expression in day-month-year format (for example, 31 May 1998) from a Date or DateTime expression. The month name isn't abbreviated.

DMY(dExpression | tExpression)

Parameters

dExpression

Specifies the Date expression from which DMY( ) returns a character string in day-month-year format.
tExpression

Specifies the DateTime expression from which DMY( ) returns a character string in day-month-year format.

Return Value

Character

Remarks

If SET CENTURY is OFF, DMY( ) returns a character string in a dd-Month-yy format (for example, 16 February 98). If SET CENTURY is ON, the format is dd-Month-yyyy (for example, 16 February 1998).

Example

Copy Code
CLEAR
SET CENTURY OFF
? DMY(DATE( ))
SET CENTURY ON
? DMY(DATE( ))

See Also

Other Resources

MDY( ) Function
SET CENTURY Command
SET DATE Command
Functions
Language Reference


DODEFAULT( ) Function

Visual FoxPro 9.0 Language Reference
DODEFAULT( ) Function
See Also

Executes the parent class event or method of the same name from within a subclass.

For example, if you place DODEFAULT( ) in the Click event of a subclass, Visual FoxPro executes the Click event of the parent class. The scope resolution operator (::), unlike DODEFAULT( ), executes a parent class event or method of a different name.

Note:
You can place DODEFAULT( ) only within an event or method.

DODEFAULT( [ eParameter1 [, eParameter2] ...] )

Parameters

eParameter1[, eParameter2] ...

Specifies parameters that are passed to the parent class event or method.

Return Value

Character, Numeric, Currency, Date, DateTime, Logical, or Memo

Remarks

The value that DODEFAULT( ) returns is determined by the return value of the event or method.

In versions prior to Visual FoxPro 8.0, you could not call DODEFAULT( ) in a method that did not exist in the parent class without Visual FoxPro generating an error, "Property name is not found (Error 1734)", returning True (.T.), and disregarding DODEFAULT( ) and any passed parameters. However, Visual FoxPro now disregards this and does not generate an error, but the following results still occur:

  • Visual FoxPro disregards any parameters that are passed because no code is executed.

  • Visual FoxPro always returns True (.T.), which is the default behavior for any procedure without an explicit RETURN statement.

This behavior affects the following scenarios:

  • Custom methods that are defined in a class. For example, the line, x.Test(), generated an error prior to Visual FoxPro 8.0 but no longer does:

    Copy Code
    CLEAR
x=CREATEOBJECT("s1")
x.ReadMethod("Init")
x.Test()

DEFINE CLASS s1 AS Session
   PROCEDURE Test
      DODEFAULT()
   ENDPROC
   PROCEDURE ReadMethod(cMethod)
      DODEFAULT(cMethod)
   ENDPROC
   PROCEDURE Error(nError, cMethod, nLine)
      ? "Error:", nError, cMethod, nLine
   ENDPROC
ENDDEFINE
  • Native methods that are marked with the HIDDEN key word in the parent class. For example:

    Copy Code
    CLEAR
x=CREATEOBJECT("s2")
x.Test()

DEFINE CLASS s2 AS s1
   PROCEDURE Test
      THIS.ReadMethod("Init")
   ENDPROC
   PROCEDURE ReadMethod(cMethod)
      DODEFAULT(cMethod)
   ENDPROC
ENDDEFINE

DEFINE CLASS s1 AS Session
   HIDDEN PROCEDURE ReadMethod(cMethod)
      DODEFAULT(cMethod)
   ENDPROC
   PROCEDURE Error(nError, cMethod, nLine)
      ? "Error:", nError, cMethod, nLine
   ENDPROC
ENDDEFINE

Starting in Visual FoxPro 7.0, calling a native method in a base class that contains DODEFAULT( ) does not cause an error. For example:

Copy Code
CLEAR
x=CREATEOBJECT("s1")
x.ReadMethod("Init")

DEFINE CLASS s1 AS Session
   PROCEDURE ReadMethod(cMethod)
      DODEFAULT(cMethod)
   ENDPROC
   PROCEDURE Error(nError, cMethod, nLine)
      ? "Error:", nError, cMethod, nLine
   ENDPROC
ENDDEFINE

See Also

Other Resources

:: Scope Resolution Operator
ParentClass Property
Functions
Language Reference


DOW( ) Function

Visual FoxPro 9.0 Language Reference
DOW( ) Function
See Also Example

Returns a numeric day-of-the-week value from a Date or DateTime expression.

DOW(dExpression | tExpression [, nFirstDayOfWeek])

Parameters

dExpression

Specifies the Date expression from which DOW( ) returns the day number.
tExpression

Specifies the DateTime expression from which DOW( ) returns the day number.
nFirstDayOfWeek

Specifies the first day of the week. nFirstDayOfWeek may be one of the following values.

nFirstDayOfWeek Description

0

DOW( ) uses whatever day is currently selected in the Week Starts On list box, which appears on the Regional Tab in the Options dialog box.

1

Sunday. This is the default when nFirstDayOfWeek is omitted, and is the first day of the week used in earlier FoxPro versions.

2

Monday

3

Tuesday

4

Wednesday

5

Thursday

6

Friday

7

Saturday

Return Value

Numeric

Example

Copy Code
STORE DATE( ) TO gdDayNum
CLEAR
? DOW(gdDayNum)
? CDOW(gdDayNum)

See Also

Other Resources

CDOW( ) Function
DAY( ) Function
SET FDOW Command
SET FWEEK Command
SYS( ) Functions Overview
WEEK( ) Function
Functions
Language Reference


DRIVETYPE( ) Function

Visual FoxPro 9.0 Language Reference
DRIVETYPE( ) Function
See Also

Returns the type of the specified drive.

DRIVETYPE(cDrive)

Parameters

cDrive

The drive designator. The colon in drive names (for example, "C:") is optional.

Return Value

Numeric

Remarks

The following table explains the number DRIVETYPE( ) returns and the corresponding drive type description.

Number | Drive Type
1 | No type
2 | Floppy disk
3 | Hard disk
4 | Removable drive or network drive
5 | CD-ROM
6 | RAM disk1

1 Because there are many different types of RAM disks, you might get inconsistent return results.

See Also

Other Resources

SYS(5) - Default Drive or Volume
JUSTDRIVE( ) Function
Functions
Language Reference


DROPOFFLINE( ) Function

Visual FoxPro 9.0 Language Reference
DROPOFFLINE( ) Function
See Also

Discards all changes made to an offline view and takes the offline view back online.

DROPOFFLINE(cViewName)

Parameters

cViewName

Specifies the name of the offline view to take back online.

Return Value

Logical

Remarks

DROPOFFLINE( ) returns a logical true (.T.) if the offline view is successfully taken back online; otherwise it returns false (.F.).

See Also

Other Resources

CREATEOFFLINE( ) Function
DROP VIEW Command
USE Command
Functions
Language Reference


DTOC( ) Function

Visual FoxPro 9.0 Language Reference
DTOC( ) Function
See Also Example

Returns a Character-type date from a Date or DateTime expression.

DTOC(dExpression | tExpression [, 1])

Parameters

dExpression

Specifies a Date-type variable, array element, or field for which DTOC( ) returns a Character-type date.
tExpression

Specifies a DateTime-type variable, array element, or field for which DTOC( ) returns a Character-type date.
1

Returns the date in a format suitable for indexing. This is particularly useful for maintaining the table records in chronological sequence. For example, to order table records in entry sequence, you could issue this command:
Copy Code
INDEX ON DTOC(gdInvDate, 1) + gnInvTime TAG Timeindx
gdInvDate and gnInvTime are fields containing the date and time when the data was entered in the record.

Return Value

Character

Remarks

DTOC( ) returns a character string corresponding to a Date or DateTime expression. The date format is determined by SET CENTURY and SET DATE.

Example

Copy Code
SET STRICTDATE TO 1
STORE CTOD('10/31/98') TO gdThisDate
CLEAR
? DTOC(gdThisDate)
STORE DTOC({^1998-10-31}+90) TO gcExpireDate
? 'Your 90-day warranty expires ', gcExpireDate
? DTOC({^1998-10-31},1)

See Also

Other Resources

CTOD( ) Function
SET CENTURY Command
SET DATE Command
SYS( ) Functions Overview
TTOC( ) Function
Functions
Language Reference


DTOR( ) Function

Visual FoxPro 9.0 Language Reference
DTOR( ) Function
See Also Example

Converts degrees to radians.

DTOR(nExpression)

Parameters

nExpression

Specifies the numeric expression whose value you want to convert to radians. An angle expressed in a degree:minute:second format should be converted to its decimal equivalent.

Return Value

Numeric

Remarks

DTOR( ) converts the value of a numeric expression given in degrees to an equivalent value in radians. DTOR( ) is useful for working with the Microsoft Visual FoxPro trigonometric functions: ACOS( ), ASIN( ), COS( ), SIN( ), TAN( ).

Use RTOD( ) to convert radians to degrees.

Example

Copy Code
CLEAR
? DTOR(0)  && Displays 0.00
? DTOR(45) && Displays 0.79
? DTOR(90) && Displays 1.57
? DTOR(180)  && Displays 3.14
? COS(DTOR(90))  && Displays 0.00

See Also

Other Resources

ACOS( ) Function
ASIN( ) Function
COS( ) Function
RTOD( ) Function
SIN( ) Function
TAN( ) Function
Functions
Language Reference


DTOS( ) Function

Visual FoxPro 9.0 Language Reference
DTOS( ) Function
See Also Example

Returns a character-string date in a yyyymmdd format from a specified Date or DateTime expression.

DTOS(dExpression | tExpression)

Parameters

dExpression

Specifies the Date expression DTOS( ) converts to an eight-digit character string.
tExpression

Specifies the DateTime expression DTOS( ) converts to an eight-digit character string.

Return Value

Character

Remarks

This function is useful for indexing tables on a Date or DateTime field. It is equivalent to DTOC( ) when its optional 1 argument is included.

The character string returned by DTOS( ) isn't affected by SET DATE or SET CENTURY.

Example

Copy Code
CLEAR
? DTOS(DATE( ))

See Also

Other Resources

DATE( ) Function
DATETIME( ) Function
CTOD( ) Function
DTOC( ) Function
Functions
Language Reference


DTOT( ) Function

Visual FoxPro 9.0 Language Reference
DTOT( ) Function
See Also Example

Returns a DateTime value from a Date expression.

DTOT(dDateExpression)

Parameters

dDateExpression

Specifies the Date expression from which a DateTime value is returned.

Return Value

DateTime

Remarks

The format of the DateTime value DTOT( ) returns depends on the current SET DATE and SET MARK settings. If a century isn't supplied, the twentieth century is assumed.

DTOT( ) adds a default time of 12:00:00 AM (if SET HOURS is 12) or 00:00:00 (if SET HOURS is 24) to the date to produce a valid DateTime value.

Example

Copy Code
SET HOURS TO 12
? DTOT({^2004-02-16}) && Displays 02/16/2004 12:00:00 AM

See Also

Reference

SET HOURS Command

Other Resources

CTOT( ) Function
DATE( ) Function
SEC( ) Function
SECONDS( ) Function
SET SECONDS Command
TIME( ) Function
Functions
Language Reference


EDITSOURCE( ) Function

Visual FoxPro 9.0 Language Reference
EDITSOURCE( ) Function
See Also

Opens the Visual FoxPro editor and, optionally positions the cursor.

EditSource(cShortCutID | [ cFilename [, nLineNo] [, cClassName]
[, cMethodName|cProcName]])

Parameters

cShortCutID

Specifies the valid shortcut ID.
cFileName

Specifies the name of the file to open. If the file is already open, Visual FoxPro activates it.
nLineNo

Specifies the line at which to position the cursor. If you use 0, the cursor is positioned at the last location saved in the resource file. If you provide an invalid or non-existent nlineno, the cursor is positioned at the beginning of the current file. A negative nlineno value will generate an error.
cClassName

Specifies the name of a class or data environment to be edited. If you open a class file (.vcx) without naming a class, the Class Designer opens instead of the editor.
cMethodName

Specifies the name of a method to be edited. Use a valid object-referenced method in the form cObject.nMethodName.
cProcName

Specifies the name of a procedure to be edited in a class type file (.vcx, .scx, .frx, .lbx).

Return Value

Logical. Returns true (.T.) if the target file opens successfully, otherwise returns error codes according to the following table:

Value | Description
0 | Successful file opening.
132, 705 | File in use. Cannot be opened.
200 | File not opened due to invalid object reference. Verify the presence of cMethodName in the object referenced by the cClassName parameter.
901, 925 | File opened but invalid object reference in cMethodName. Check the reference in the cMethodName parameter. Use a reference such as MyForm.MyList.CLICK. Forms and classes return 925; reports return 901.

Remarks

You can pass cShortCutID without any additional information and have the editor open at that location. The cShortCutID is the unique ID value for a shortcut record stored in the Foxtask system table (_VFP.FoxTask). The Task List application uses this table to ensure that it can get the latest line position of the shortcut. Visual FoxPro maintains, internally, current shortcut information, but only writes line position updates to Foxtask when a file is saved.

The file extension determines which Visual FoxPro editor opens, according to the following table:

Extension | Editor | Default Settings
PRG | Text Editor | MODIFY COMMAND
MPR | Text Editor | MODIFY COMMAND
QPR | Text Editor | MODIFY COMMAND
TXT | Text Editor | MODIFY FILE
SCX | Code Editor | MODIFY FORM
VCX | Code Editor | MODIFY CLASS
FRX | Code Editor | MODIFY REPORT
LBX | Code Editor | MODIFY LABEL
MNX | Menu Editor | MODIFY MENU
DBC | Stored Procedures | MODIFY PROCEDURE
<other> | Text Editor | MODIFY FILE

Program (.prg), database (.dbc stored procedures) and text files support only the nLineNo parameter.

Menu file (.mnx) are opened as text files without reference to objects or to line numbers.

See Also

Other Resources

Functions
MODIFY COMMAND Command
APROCINFO( ) Function


EMPTY( ) Function

Visual FoxPro 9.0 Language Reference
EMPTY( ) Function
See Also Example

Determines whether an expression evaluates to empty.

EMPTY(eExpression)

Parameters

eExpression

Specifies the expression that EMPTY( ) evaluates. You can specify an expression with Character, Numeric, Date, Varbinary, Blob, or Logical type, or the name of a Memo or General field in an open table.

Return Value

Logical. EMPTY( ) returns True (.T.) if the expression eExpression evaluates to empty; otherwise, EMPTY( ) returns False (.F.).

When expression types evaluate to the values in the following table, EMPTY( ) returns True (.T.).

Expression type | Evaluates to
Blob | Empty (0h) or contains only zero bytes, for example, 0h00, 0h000000, and so on
Character | Empty string, spaces, tabs, carriage returns, linefeeds, or any combination of these
Currency | 0
Date | Empty, for example, CTOD('')
DateTime | Empty, for example, CTOT('')
Double | 0
Float | 0
General | Empty (no OLE object)
Integer | 0
Logical | False (.F.)
Memo | Empty (no contents)
Numeric | 0
Varbinary | Empty (0h) or contains only zero bytes, for example, 0h00, 0h000000, and so on

Remarks

You cannot use EMPTY( ) to determine whether a variable object reference is empty. For example, a variable can contain an object reference for a form. If the form is closed by clicking Close from the form's pop-up menu or by issuing CLEAR WINDOWS, the variable contains the null value.

The following program example demonstrates how to use TYPE( ) and ISNULL( ) to determine if a variable object reference is valid.

Copy Code
goMyForm = CREATEOBJECT('Form')
WAIT WINDOW IIF(TYPE('goMyForm') = 'O' AND !ISNULL(goMyForm), ;
   'goMyForm has valid object reference',;
   'goMyForm does not have valid object reference')

Example

The following example opens the customer table in the testdata database. FOR ... ENDFOR is used to create a loop in which EMPTY( ) s used to determine if TAG( ) returns the empty string. The name of each structural index tag is displayed with its candidate status.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer     && Open customer table

FOR nCount = 1 TO TAGCOUNT( )
   IF !EMPTY(TAG(nCount))  && Checks for empty string
   ? TAG(nCount)  && Display tag name
   ? CANDIDATE(nCount)  && Display candidate status
   ELSE
      EXIT  && Exit the loop when no more tags are found
   ENDIF
ENDFOR

See Also

Other Resources

Functions
LEN( ) Function
TYPE( ) Function
ISNULL( ) Function


EOF( ) Function

Visual FoxPro 9.0 Language Reference
EOF( ) Function
See Also Example

Determines whether the record pointer is positioned past the last record in the current or specified table.

EOF([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area number of the table.
cTableAlias

Specifies the alias of the table. EOF( ) returns false (.F.) if a table isn't open in the work area you specify. If you do not specify a work area or alias, the table that is open in the currently selected work area is tested for the end of the table condition.

Return Value

Logical

Remarks

EOF( ) returns true (.T.) if the record pointer reaches the end of the table file (EOF). The end of the table is reached when the record pointer passes the last record in the table. For example, when a FIND, LOCATE, or SEEK is unsuccessful, Visual FoxPro moves the record pointer past the last record, and EOF( ) returns true (.T.). EOF( ) returns false (.F.) if the record pointer isn't at the end of the table.

Example

The following example opens the customer table and lists the company name one page at a time until the end of the file is reached or you until you choose Cancel.
Copy Code
CLOSE DATABASES
CLEAR
OPEN DATABASE (HOME() + "samples\data\testdata")
USE customer
GO TOP
local recCtr, btnValue
recCtr = 0
btnValue = 1
DO WHILE btnValue = 1 AND NOT EOF()
  ? "Company : " + company
  recCtr = recCtr + 1
  if (recCtr % 20) = 0 then
    btnValue =MESSAGEBOX ("Click OK to continue, ;
     Cancel to quit.",33)
    clear
  endif
  Skip 1    && Move down one record
ENDDO
=MESSAGEBOX("Listing complete.",48)

See Also

Other Resources

Functions
BOF( ) Function
GO | GOTO Command
SKIP Command


ERROR( ) Function

Visual FoxPro 9.0 Language Reference
ERROR( ) Function
See Also Example

Returns the error number for the error that triggered an ON ERROR routine.

ERROR( )

Return Value

Numeric

Remarks

ERROR( ) returns the number of the most recent error. An ON ERROR routine must be active for ERROR( ) to return a value other than 0.

When an error is trapped during program execution, the error type can be returned by ERROR( ) in an ON ERROR routine. The corresponding error message can be returned by MESSAGE( ).

The value ERROR( ) returns is reset by RETURN or RETRY.

Example

The following example demonstrates a simple error-handling routine that displays a message when an error occurs.
Copy Code
CLEAR
ON ERROR DO errhand WITH ERROR( ), MESSAGE( )

*** The next line generates an error - there is no BRWSE command

BRWSE
ON ERROR
RETURN

*** Error handler ***

PROCEDURE errhand
PARAMETER errnum,message
? Message
? 'Error number: '+ ALLTRIM(STR(Errnum))
RETURN

See Also

Other Resources

AERROR( ) Function
ERROR Command
MESSAGE( ) Function
Error Messages A-Z
Error Messages by Number
ON ERROR Command
RETRY Command
RETURN Command
Functions
Language Reference


EVALUATE( ) Function

Visual FoxPro 9.0 Language Reference
EVALUATE( ) Function
See Also Example

Evaluates a character expression and returns the result.

EVALUATE(cExpression)

Parameters

cExpression

Specifies the expression to evaluate. cExpression can be a literal character string, or a valid Visual FoxPro expression, variable, array element, or field of any data type, enclosed in quotation marks. cExpression cannot exceed 255 characters. Whenever possible, use EVALUATE( ) or a name expression to replace macro substitution using the & Command. EVALUATE and name expressions execute faster than macro substitution.

Return Value

Character, Numeric, Currency, Date, DateTime, Logical, or Memo

Remarks

EVALUATE( ) is similar to TYPE( ) but returns the result of an expression instead of the expression type. An expression containing EVALUATE( ) cannot be optimized by Rushmore Query Optimization.

Including the EVALUATE( ) function in the WHERE clause of a SQL query can return incorrect data.

Example

The following example uses the EVALUATE() function to evaluate a math expression stored in a character variable.
Copy Code
cMathFunc="INT(4.33)"
nResult=EVALUATE(cMathFunc)
?nResult

See Also

Other Resources

TYPE( ) Function
_Evaluate( ) API Library Routine
Using Rushmore Query Optimization to Speed Data Access
Functions
Language Reference


EVL( ) Function

Visual FoxPro 9.0 Language Reference
EVL( ) Function
See Also Example

Returns a non-empty value from two expressions.

You can use the EVL( ) function to return an appropriate substitute value instead of an empty value, such as False (.F.) or 0, from two expressions. You can also use this functionality to remove empty values from calculations or operations where empty values are not supported or relevant.

Note:
The Visual FoxPro Logical value, False (.F.), and the Numeric value of 0 also evaluate to empty.

EVL( eExpression1, eExpression2 )

Parameters

eExpression1, eExpression2

Specifies two expressions. eExpression1 and eExpression2 can be any data type except the following:
  • General fields: If eExpression1 or eExpression2 represents a General field, EVL( ) returns an error, "Operation is invalid for a General field. (Error 1912)"

  • Object references.

Return Value

Character, Date, DateTime, Numeric, Currency, Logical, Object. EVL( ) returns eExpression1 if it does not evaluate to an empty value; otherwise, it returns eExpresssion2.

Example

The following examples create the memory variables, glEmptyDate, which contains an empty Date value, and glEmptyNum, which contains an empty Numeric value, 0.

When performing EVL( ) with glEmptyDate, EVL( ) returns an empty string ("") when evaluating glEmptyDate and an empty string, and "None" when evaluating glEmptyDate and "None".

Copy Code
STORE {  /  /  } TO glEmptyDate
? EVL(glEmptyDate,"")
? EVL(glEmptyDate, "None")

When performing EVL( ) with glEmptyNum, EVL( ) returns an empty string when evaluating glEmptyNum and an empty string, and "Empty" when evaluating glEmptyNum and "Empty".

Copy Code
STORE 0 TO glEmptyNum
? EVL(glEmptyNum,"")
? EVL(glEmptyNum, "Empty")

See Also

Other Resources

Functions
EMPTY( ) Function


EVENTHANDLER( ) Function

Visual FoxPro 9.0 Language Reference
EVENTHANDLER( ) Function
See Also Example

Binds a COM server event to implemented interface methods on a Visual FoxPro object.

For information about binding events from native Visual FoxPro objects, see Event Binding for Visual FoxPro Objects.

EVENTHANDLER(oCOMObject, oVFPObject [, lUnbind])

Parameters

oCOMObject

Specifies the object reference to the object whose events are to be bound. oCOMObject must be a valid COM object.
oVFPObject

Specifies the object reference to the Visual FoxPro object that contains user-defined method code, which maps to corresponding COM object events. The class must implement the events interface for the particular COM object being passed in the first parameter. For example, you must implement the RecordsetEvents interface to bind to an ADO Recordset object.
lUnbind

Visual FoxPro automatically releases the COM object when it goes out of scope. By passing this parameter with a value of .T., you can release the event binding while both objects remain in scope.

Return Value

Logical data type. EVENTHANDLER( ) returns True (.T.) if successful and False (.F.) if unsuccessful.

Remarks

You can bind a single COM object to several Visual FoxPro objects, or you can bind several COM objects to the same Visual FoxPro object.

Event handling is automatically unbound when either the Visual FoxPro or the COM object is released. You can explicitly call the EVENTHANDLER( ) function and pass the lUnbind parameter to unbind objects without releasing object references.

Example

Copy Code
LOCAL oEvents
LOCAL oRS AS adodb.recordset
LOCAL oConn AS adodb.Connection

oEvents = NEWOBJECT("myclass")
oConn = NEWOBJECT("adodb.connection")

oConn.Provider="MSDASQL"
* Make sure to set the SourceDB property
* below to your TESTDATA location.
oConn.ConnectionString="DSN=Visual FoxPro Database;" + ;
"SourceType=DBC; SourceDB=D:\VFP\DATA\TESTDATA.DBC"
oConn.Open
oRS = oConn.Execute("select * from customer")
? EVENTHANDLER(oRS, oEvents)
?
? PADR(oRS.Fields(0).Value,20)
? EVENTHANDLER (oRS, oEvents, .T.)
oRS.MoveNext
? PADR(oRS.Fields(0).Value,20)
oRS.MoveNext
CLEAR all
RETURN

DEFINE CLASS myclass AS session
IMPLEMENTS RecordsetEvents IN "adodb.recordset"

PROCEDURE Recordsetevents_WillChangeField(cFields AS Number @, Fields AS VARIANT @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
   ? " "+program() + ' ' + TRANSFORM(DATETIME())

PROCEDURE Recordsetevents_FieldChangeComplete(cFields AS Number @, Fields AS VARIANT @, pError AS VARIANT @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
   ? " "+program() + ' ' + TRANSFORM(DATETIME())

PROCEDURE Recordsetevents_WillChangeRecord(adReason AS VARIANT @, cRecords AS Number @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
   ? " "+program() + ' ' + TRANSFORM(DATETIME())

PROCEDURE Recordsetevents_RecordChangeComplete(adReason AS VARIANT @, cRecords AS Number @, pError AS VARIANT @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
   ? " "+program() + ' ' + TRANSFORM(DATETIME())

PROCEDURE Recordsetevents_WillChangeRecordset(adReason AS VARIANT @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
   ? " "+program() + ' ' + TRANSFORM(DATETIME())
   ?adreason,adstatus,precordset.recordcount

PROCEDURE Recordsetevents_RecordsetChangeComplete(adReason AS VARIANT @, pError AS VARIANT @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
? " "+program() + ' ' + TRANSFORM(DATETIME())

PROCEDURE Recordsetevents_WillMove(adReason AS VARIANT @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
   ? " "+program() + ' ' + TRANSFORM(DATETIME())

PROCEDURE Recordsetevents_MoveComplete(adReason AS VARIANT @, pError AS VARIANT @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
   ? " "+program() + ' ' + TRANSFORM(DATETIME())

PROCEDURE Recordsetevents_EndOfRecordset(fMoreData AS LOGICAL @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
   ? " "+program() + ' ' + TRANSFORM(DATETIME())

PROCEDURE Recordsetevents_FetchProgress(Progress AS Number @, MaxProgress AS Number @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
   ? " "+program() + ' ' + TRANSFORM(DATETIME())

PROCEDURE Recordsetevents_FetchComplete(pError AS VARIANT @, adStatus AS VARIANT @, pRecordset AS VARIANT @) AS VARIANT
   ? " "+program() + ' ' + TRANSFORM(DATETIME())

ENDDEFINE

See Also

Other Resources

DEFINE CLASS Command
Functions
Language Reference


EXECSCRIPT( ) Function

Visual FoxPro 9.0 Language Reference
EXECSCRIPT( ) Function
See Also Example

Enables you to run multiple lines of code from variables, tables, and other text at runtime.

ExecScript(cExpression [, eParameter1, eParameter2, ...])

Parameters

cExpression

Represents the text, a variable, type string, or memo to be executed as code.
eParameter1, eParameter2, ...

Optional. Specify parameters passed to a script that has a parameter statement in first line.

Return Value

The return value is the value returned by the script in cExpression. If the script returns no value, Visual FoxPro returns .T.

Remarks

ExecScript( ), unlike macro expansion, provides the same effect as selecting several lines of code in the command window then pressing the Enter key.

Example

This example creates a form and then shows the value of the AutoCenter property of the new Form object. Note the use of CHR(13), which is used to separate the two code lines.
Copy Code
?EXECSCRIPT("oForm=CREATEOBJECT('Form')"+CHR(13)+"?oForm.AutoCenter")

See Also

Other Resources

COMPILE Command
Handling Run-Time Errors
ON ERROR Command
Functions
Language Reference


EXP( ) Function

Visual FoxPro 9.0 Language Reference
EXP( ) Function
See Also Example

Returns the value of ex where x is a specified numeric expression.

EXP(nExpression)

Parameters

nExpression

Specifies the exponent, x, in the exponential expression ex.

Return Value

Numeric

Remarks

The value of e, the base of natural logarithms, is approximately 2.71828. The number of decimal places returned by EXP( ) is specified with SET DECIMALS.

Example

Copy Code
? EXP(0)  && Displays 1.00
? EXP(1)  && Displays 2.72

See Also

Other Resources

LOG( ) Function
SET DECIMALS Command
Functions
Language Reference


FCHSIZE( ) Function

Visual FoxPro 9.0 Language Reference
FCHSIZE( ) Function
See Also

Changes the size of a file opened with a low-level file function.

FCHSIZE(nFileHandle, nNewFileSize)

Parameters

nFileHandle

Specifies the file handle of the file whose size you wish to change. The file handle is returned by FOPEN( ) when you open the file or by FCREATE( ) when you create the file. If a file is opened with FOPEN( ), it must be opened with write or read/write privileges to be able to change its size.
nNewFileSize

Specifies the new file size in bytes. If nNewFileSize is less than the original file size, the file is truncated. If nNewFileSize is greater than the original file size, the file size is increased.

Return Value

Numeric

Remarks

Use FCHSIZE( ) to increase the file's size or truncate the file after a specified byte.

When a file's size is increased, Microsoft Visual FoxPro allocates sectors for the file on the drive where the file is opened. Since FCHSIZE( ) does not initialize the new file space, the space can contain previous data. Be sure to manage the new file space.

The final size of the file in bytes is returned. Visual FoxPro returns –1 if FCHSIZE( ) is unable to change the file size if, for example, an invalid file handle is specified because of insufficient disk space, or if the file is read-only.

Tip:
This function can be used to truncate a file to length 0.

See Also

Other Resources

FCLOSE( ) Function
FCREATE( ) Function
FEOF( ) Function
FFLUSH( ) Function
FGETS( ) Function
FOPEN( ) Function
FPUTS( ) Function
FREAD( ) Function
FSEEK( ) Function
FWRITE( ) Function
Functions
Language Reference


FCLOSE( ) Function

Visual FoxPro 9.0 Language Reference
FCLOSE( ) Function
See Also

Flushes and closes a file or communication port opened with a low-level file function.

FCLOSE(nFileHandle)

Parameters

nFileHandle

Specifies the file handle of the low-level file to close. The numeric file handle is returned when you create the file with FCREATE( ) or open the file with FOPEN( ).

Return Value

Logical

Remarks

If the file is successfully closed, FCLOSE( ) returns true (.T.) and releases the file handle. If the file cannot be closed, FCLOSE( ) returns false (.F.).

CLOSE ALL also closes low-level files.

See Also

Other Resources

CLOSE ALL Command
FCHSIZE( ) Function
FCREATE( ) Function
FEOF( ) Function
FFLUSH( ) Function
FGETS( ) Function
FOPEN( ) Function
FPUTS( ) Function
FREAD( ) Function
FSEEK( ) Function
FWRITE( ) Function
Functions
Language Reference


FCOUNT( ) Function

Visual FoxPro 9.0 Language Reference
FCOUNT( ) Function
See Also Example

Returns the number of fields in a table.

FCOUNT([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area of the table for which FCOUNT( ) returns the number of fields. FCOUNT( ) returns 0 if a table isn't open in the work area you specify.
cTableAlias

Specifies the alias of the table for which FCOUNT( ) returns the number of fields. Visual FoxPro generates an error message if you specify a table alias that doesn't exist.

Return Value

Numeric

Remarks

If you omit the optional arguments, FCOUNT( ) returns the number of fields in the table open in the currently selected work area.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table
SELECT 0
USE employee  && Opens employee table

CLEAR
? FCOUNT('CUSTOMER')     && Displays 13, # of fields in Customer
? FCOUNT('EMPLOYEE')  && Displays 22, # of fields in Employee

See Also

Other Resources

DBF( ) Function
FIELD( ) Function
FSIZE( ) Function
Functions
Language Reference


FCREATE( ) Function

Visual FoxPro 9.0 Language Reference
FCREATE( ) Function
See Also Example

Creates and opens a low-level file.

FCREATE(cFileName [, nFileAttribute])

Parameters

cFileName

Specifies the name of the file to create. You can include a drive designator and path with the file name. If a drive designator or path isn't included, the file is created in the default directory.
Note:
Visual FoxPro does not recognize a path name properly if a disk or directory name contains an exclamation point (!).

nFileAttribute

Specifies the attributes of the file created. The following table lists the file attributes you can specify.

nFileAttribute File attributes

0

(Default) Read/write

1

Read-only

2

Hidden

3

Read-only/Hidden

4

System

5

Read-only/System

6

System/Hidden

7

Read-only/Hidden/System
Note that a file created with nFileAttribute other than 0 cannot be written to with FPUTS( ) or FWRITE( ) until the file is closed and opened again. Use DISPLAY STATUS or LIST STATUS to display or print information about files created and opened with FCREATE( ). DISPLAY STATUS and LIST STATUS give the following information about each file opened or created with a low-level file function:
  • The drive, directory, and file name

  • The file handle number

  • The file pointer position

  • The read/write attributes

Return Value

Numeric

Remarks

If a file with the name you specify already exists, it is overwritten without warning.

FCREATE( ) assigns a file handle number to the file, which you can use to identify the file in other Visual FoxPro low-level file functions. FCREATE( ) returns the file handle number when a file is created, or returns –1 if the file cannot be created.

Tip:
Assign the file handle number to a memory variable so you can access the file by the variable in other low-level file functions.

You cannot open a communication port with FCREATE( ). Use FOPEN( ) to open a communication port.

Example

Copy Code
IF FILE('errors.txt')  && Does file exist?
   gnErrFile = FOPEN('errors.txt',12)     && If so, open read/write
ELSE
   gnErrFile = FCREATE('errors.txt')  && If not create it
ENDIF
IF gnErrFile < 0     && Check for error opening file
   WAIT 'Cannot open or create output file' WINDOW NOWAIT
ELSE  && If no error, write to file
   =FWRITE(gnErrFile , 'Error information to be written here')
ENDIF
=FCLOSE(gnErrFile )     && Close file
IF gnErrFile > 0
MODIFY FILE errors.txt NOWAIT  && Open file in edit window
ENDIF

See Also

Reference

FCREATE( ) Function

Other Resources

CLOSE ALL Command
FCHSIZE( ) Function
FEOF( ) Function
FFLUSH( ) Function
FGETS( ) Function
FOPEN( ) Function
FPUTS( ) Function
FREAD( ) Function
FSEEK( ) Function
FWRITE( ) Function
Functions
Language Reference


FDATE( ) Function

Visual FoxPro 9.0 Language Reference
FDATE( ) Function
See Also Example

Returns the last modification Date or DateTime for a file.

FDATE(cFileName [, nType])

Parameters

cFileName

Specifies the name of the file whose last modification date FDATE( ) returns. cFileName can include a path with the file name. If a path is not included with the file name, Visual FoxPro searches for the file in the default directory and in any directories or folders specified with SET PATH.
nType

Specifies that FDATE( ) returns the last modification date or DateTime of the file specified with cFileName. If nType is 0, the last modification date is returned. Including 0 is identical to omitting nType. If nType is 1, the last modification DateTime is returned.

Return Value

Date

Remarks

The Date or DateTime value that FDATE( ) returns is assigned to the file by the operating system.

Use LUPDATE( ) to determine the last modification date for an open table.

Example

The following example uses FDATE( ) to display the last modification DateTime for FoxUser.dbf, the Visual FoxPro resource file.
Copy Code
? FDATE('FOXUSER.DBF', 1)  && Displays the last modification DateTime

See Also

Other Resources

FTIME( ) Function
LUPDATE( ) Function
DATE( ) Function
Functions
Language Reference


FEOF( ) Function

Visual FoxPro 9.0 Language Reference
FEOF( ) Function
See Also Example

Determines whether the file pointer is positioned at the end of a file.

FEOF(nFileHandle)

Parameters

nFileHandle

Specifies the file handle number of the file to check for the end-of-file condition. FEOF( ) always returns true (.T.) if you specify a file handle number of a communication port opened with FOPEN( ).

Return Value

Logical

Remarks

This low-level file function returns true (.T.) if the file pointer is positioned at the end of a file opened with a low-level file function. FEOF( ) returns false (.F.) if the file pointer isn't at the end of the file.

Example

Copy Code
*** Open the file test.txt ***

gnFileHandle = FOPEN('test.txt')

*** Move the file pointer to BOF ***

gnPosition = FSEEK(gnFileHandle, 0)

*** If file pointer is at BOF and EOF, the file is empty ***
*** Otherwise the file must have something in it ***

IF FEOF(gnFileHandle)
   WAIT WINDOW 'This file is empty!' NOWAIT
ELSE
   WAIT WINDOW 'This file has something in it!' NOWAIT
ENDIF
= FCLOSE(gnFileHandle)

See Also

Other Resources

FCHSIZE( ) Function
FCLOSE( ) Function
FCREATE( ) Function
FGETS( ) Function
FOPEN( ) Function
FPUTS( ) Function
FREAD( ) Function
FSEEK( ) Function
FWRITE( ) Function
Functions
Language Reference


FERROR( ) Function

Visual FoxPro 9.0 Language Reference
FERROR( ) Function
See Also

Returns a number corresponding to the most recent low-level file function error.

FERROR( )

Return Value

Numeric

Remarks

FERROR( ) returns 0 if a low-level file function executes successfully. A positive value is returned if a function doesn't execute successfully. The following table lists each error number returned by FERROR( ) and the cause of the error.

Error number | Error cause
2 | File not found
4 | Too many files open (out of file handles)
5 | Access denied
6 | Invalid file handle given
8 | Out of memory
25 | Seek error (can't seek before the start of a file)
29 | Disk full
31 | Error opening file

See Also

Other Resources

FCHSIZE( ) Function
FCLOSE( ) Function
FCREATE( ) Function
FEOF( ) Function
FFLUSH( ) Function
FGETS( ) Function
FOPEN( ) Function
FPUTS( ) Function
FREAD( ) Function
FSEEK( ) Function
FWRITE( ) Function
Functions
Language Reference


FFLUSH( ) Function

Visual FoxPro 9.0 Language Reference
FFLUSH( ) Function
See Also Example

Flushes to disk a file opened with a low-level function.

FFLUSH(nFileHandle [, lForce])

Parameters

nFileHandle

Specifies the file handle of the file to flush to disk.
lForce

If you specify a logical true (.T.) for lForce, Windows is used to immediately flush the file to disk. If you specify a logical false (.F.) (the default if lForce is omitted), Visual FoxPro flushes the file to disk at its earliest opportunity.

Return Value

Logical

Remarks

FFLUSH( ) also releases the memory used by the file's buffer.

FLUSH is different from the FFLUSH( ) function. FLUSH doesn't operate on low-level files but rather on tables and indexes.

Example

The following example opens and writes to a file named Input.dat. After writing the first two strings, the program flushes the buffers to ensure that the strings are written to disk. It then writes the next two strings, flushes the buffers again and closes the file.
Copy Code
IF FILE('input.dat')
   gnTestFile = FOPEN('input.dat',2)
ELSE
   gnTestFile = FCREATE('input.dat')
ENDIF
gnIOBytes = FWRITE(gnTestFile,'Test output')
gnIOBytes = FWRITE(gnTestFile,' for low-level file I/O')
glFlushOk = FFLUSH(gnTestFile, .T.)
gnIOBytes = FWRITE(gnTestFile,'Test output2')
gnIOBytes = FWRITE(gnTestFile,' for low-level file I/O')
glFlushOk = FFLUSH(gnTestFile)
glCloseOk = FCLOSE(gnTestFile)
MODIFY FILE input.dat NOWAIT NOEDIT

See Also

Other Resources

FCHSIZE( ) Function
FCLOSE( ) Function
FCREATE( ) Function
FEOF( ) Function
FGETS( ) Function
FOPEN( ) Function
FPUTS( ) Function
FREAD( ) Function
FSEEK( ) Function
FWRITE( ) Function
Functions
Language Reference


FGETS( ) Function

Visual FoxPro 9.0 Language Reference
FGETS( ) Function
See Also Example

Returns a series of bytes from a file or a communication port opened with a low-level file function until it encounters a carriage return.

FGETS(nFileHandle [, nBytes])

Parameters

nFileHandle

Specifies the numeric file handle of the file or communication port from which FGETS( ) returns data.
nBytes

Specifies the number of bytes FGETS( ) returns. FGETS( ) returns nBytes bytes unless a carriage return is encountered first. FGETS( ) returns data between the starting file-pointer position and the carriage return if a carriage return is encountered within nBytes bytes. FGETS( ) returns a maximum of 8192 bytes. If you omit nBytes, FGETS( )returns 254 bytes by default.

Return Value

Character

Remarks

You can read a file line by line by issuing a series of FGETS( ).

FGETS( ) returns a series of bytes as a character string. Data is returned starting from the current file's pointer position and continuing until a carriage return is encountered. The file pointer is then positioned on the byte immediately following the carriage return. The carriage return is not returned as part of the string, and line feeds are discarded.

Example

Copy Code
*** TEST.TXT must exist ***
STORE FOPEN('test.txt') TO gnFileHandle    && Open the file
STORE FSEEK(gnFileHandle, 0, 2) TO gnEnd    && Move pointer to EOF
STORE FSEEK(gnFileHandle, 0) TO gnTop     && Move pointer to BOF
IF gnEnd <= 0  && Is file empty?
   WAIT WINDOW 'This file is empty!' NOWAIT
ELSE  && If not
   gcString = FGETS(gnFileHandle, gnEnd)  && Store contents
   ? gcString
ENDIF
= FCLOSE(gnFileHandle)  && Close the file

See Also

Other Resources

FCHSIZE( ) Function
FCLOSE( ) Function
FCREATE( ) Function
FEOF( ) Function
FFLUSH( ) Function
FILETOSTR( ) Function
FOPEN( ) Function
FPUTS( ) Function
FREAD( ) Function
FSEEK( ) Function
FWRITE( ) Function
Functions
Language Reference


FIELD( ) Function

Visual FoxPro 9.0 Language Reference
FIELD( ) Function
See Also Example

Returns the name of a field, referenced by number, in a table.

FIELD(nFieldNumber | cFieldName [, nWorkArea | cTableAlias [, nFlags]])

Parameters

nFieldNumber

Specifies the field number. If nFieldNumber is 1, the name of the first field in the table is returned; if nFieldNumber is 2, the name of the second field is returned, and so on. The empty string is returned if nFieldNumber is greater than the number of fields. Field names are returned in upper case.
cFieldName

Specifies the name of a field. This is used primarily to retrieve the actual field caption as stored in a database container (DBC) when used with the nFlags parameter. If the field caption is an expression (=), the expression is evaluated. Otherwise, the actual string literal is returned. If the expression cannot be evaluated at run time, an error is raised, and the actual field name is returned.
nWorkArea

Specifies the work area of the table for which FIELD( ) returns field names. FIELD( ) returns the empty string if a table is not open in the work area you specify.
cTableAlias

Specifies the alias of the table for which FIELD( ) returns field names. Visual FoxPro generates an error message if you specify a table alias that does not exist.
nFlags

Specifies whether the actual field name or field caption is returned.

nFlags Value description

0

Return actual field name.

FIELD( ) preserves the case of the returned field name, as long as the table is stored in a DBC.

1

Return field caption. If the field caption is an expression, return its evaluated value.

Return Value

Character data type. If you omit the optional arguments, FIELD( ) returns the names of the fields in the table open in the currently selected work area.

Remarks

You can use the SELECT( ) function to determine the current work area for nWorkArea. You can use the ALIAS( ) function to determine the alias of the table in the current work area for cTableAlias. For more information, see SELECT( ) Function and ALIAS( ) Function.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

CLEAR
FOR gnCount = 1 TO FCOUNT( )  && Loop for number of fields
   ? FIELD(gnCount)  && Display each field
NEXT
?
? 'Number of fields: ' + ALLTRIM(STR(gnCount -1))

See Also

Other Resources

DISPLAY STRUCTURE Command
FCOUNT( ) Function
FSIZE( ) Function
Functions
Language Reference


FILE( ) Function

Visual FoxPro 9.0 Language Reference
FILE( ) Function
See Also Example

Locates the specified file.

FILE(cFileName [, nFlags])

Parameters

cFileName

Specifies the name of the file to locate. cFileName must include the file extension. You can include a path with the file name to search for a file in a directory or on a drive other than the current directory or drive. If you do not include a path with the file name, Visual FoxPro searches in the default directory for the file. If it cannot find the file in the default directory, Visual FoxPro searches along the Visual FoxPro path, which is established with SET PATH.
nFlags

Specifies the kind of value FILE( ) returns when the file exists but might be marked with the Hidden or System attribute. The following table lists the values for nFlags.

nFlags Description

0

FILE( ) returns False (.F.) if the file exists but is marked with a Hidden or System attribute. (Default)

1

FILE( ) returns True (.T.) if the file exists, regardless of its file attributes. Setting nFlags to 1 allows you to check for hidden or system files.

Return Value

Logical data type. FILE( ) returns True (.T.) if the specified file is found on disk; otherwise, it returns False (.F.).

Remarks

You can use the ADIR( ) function to retrieve specific attributes for the file.

You can use the CD and CHDIR commands to switch to hidden files and directories.

Example

The following example displays a message indicating if the Visual FoxPro resource file exists in the Visual FoxPro startup directory.
Copy Code
SET PATH TO HOME( )
CLEAR
IF FILE('foxuser.dbf')
   WAIT WINDOW 'Visual FoxPro resource file present'
ELSE
   WAIT WINDOW 'Visual FoxPro resource file not present'
ENDIF

See Also

Other Resources

ADIR( ) Function
CD | CHDIR Command
FULLPATH( ) Function
GETFILE( ) Function
LOCFILE( ) Function
Functions
Language Reference


FILETOSTR( ) Function

Visual FoxPro 9.0 Language Reference
FILETOSTR( ) Function
See Also Example

Returns the contents of a file as a character string.

FILETOSTR(cFileName)

Parameters

cFileName

Specifies the name of the file whose contents are returned as a character string. If the file is in a directory other than the current default directory, include a path with the file name.

Return Value

Character

Remarks

Note that the size of the character string FILETOSTR( ) returns can be very large. The amount of available memory or disk space determines if you can store the character string to a memory variable, array element, or memo field. Also, character fields in Visual FoxPro are limited to 254 characters. See Visual FoxPro System Capacities for more information about limitations on character type data.

Example

The following code loads REDIST.TXT into a character string, then counts the number of merge modules mentioned in the text. REDIST.TXT ships with Microsoft Visual FoxPro and lists, which Visual FoxPro files, may be redistributed with your applications.
Copy Code
CD HOME()
cRedist=FILETOSTR("REDIST.TXT")
?OCCURS(".MSM",cRedist)

See Also

Other Resources

FGETS( ) Function
FREAD( ) Function
STRTOFILE( ) Function
Visual FoxPro System Capacities
Functions
Language Reference


FILTER( ) Function

Visual FoxPro 9.0 Language Reference
FILTER( ) Function
See Also Example

Returns the table filter expression specified in SET FILTER.

FILTER([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area of the table for which FILTER( ) returns the filter expression. FILTER( ) returns the empty string if a table isn't open in the work area you specify.
cTableAlias

Specifies the alias of the table for which FILTER( ) returns the filter expression. Visual FoxPro generates an error message if you specify a table alias that doesn't exist.

Return Value

Character

Remarks

If you omit the optional arguments, FILTER( ) returns the filter expression for the table open in the currently selected work area. For more information about creating a filter, see SET FILTER.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table
SET TALK ON
SET FILTER TO SUBSTR(cust_id,1) = 'B'

CLEAR
? FILTER( )  && Display filter expression
STORE FILTER('customer') TO gcOldFilter    && Save filter expression
SET FILTER TO country = 'USA'
? FILTER( )  && Display filter expression
SET FILTER TO &gcOldFilter    && Restore filter expression
? FILTER( )  && Display filter expression

LIST FIELDS cust_id, contact  && Demonstrate filter condition

See Also

Other Resources

SET FILTER Command
Filter Property
Functions
Language Reference


FKLABEL( ) Function

Visual FoxPro 9.0 Language Reference
FKLABEL( ) Function
See Also Example

Returns the name of the function key (F1, F2, F3 ...) from the key's corresponding function key number.

FKLABEL(nFunctionKeyNumber)

Parameters

nFunctionKeyNumber

Specifies the function key number. The value of nFunctionKeyNumber should be from 0 through the number of function keys minus 1. FKLABEL( ) returns the empty string if nFunctionKeyNumber is greater than the number of function keys minus 1. The number of function keys can be determined with FKMAX( ).

Return Value

Character

Remarks

Function keys can be programmed with SET FUNCTION.

The value returned by FKLABEL( ) is affected by SET COMPATIBLE. When COMPATIBLE is set to FOXPLUS (the default), FKLABEL( ) returns the function keys. When COMPATIBLE is set to DB4, FKLABEL( ) returns the function key and function key combinations (F1, CTRL+F1, SHIFT+F1, F2, CTRL+F2, SHIFT+F2, ...).

Example

Copy Code
CLEAR
SET COMPATIBLE OFF
? 'COMPATIBLE OFF'
?
FOR nCount = 1 TO FKMAX( )  && Loop for # of function keys
   ? FKLABEL(nCount)  && Display programmable function keys
ENDFOR
SET COMPATIBLE ON

?
? 'COMPATIBLE ON'
?
FOR nCount = 1 TO FKMAX( )  && Loop for # of function keys
   ? FKLABEL(nCount)  && Display programmable function keys
ENDFOR

See Also

Other Resources

FKMAX( ) Function
SET COMPATIBLE Command
SET FUNCTION Command
Functions
Language Reference


FKMAX( ) Function

Visual FoxPro 9.0 Language Reference
FKMAX( ) Function
See Also Example

Returns the number of programmable function keys or function key combinations on your keyboard.

FKMAX( )

Return Value

Numeric

Remarks

The value returned by FKMAX( ) is affected by SET COMPATIBLE. When SET COMPATIBLE is set to FOXPLUS (the default), FKMAX( ) returns the number of function keys. When SET COMPATIBLE is set to DB4, FKMAX( ) returns the number of function key and function key combinations (F1, CTRL+F1, SHIFT+F1, F2, CTRL+F2, SHIFT+F2, ...).

Example

Copy Code
CLEAR
SET COMPATIBLE OFF
? 'COMPATIBLE OFF'
?
FOR nCount = 1 TO FKMAX( )  && Loop for # of function keys
   ? FKLABEL(nCount)  && Display programmable function keys
ENDFOR
SET COMPATIBLE ON

?
? 'COMPATIBLE ON'
?
FOR nCount = 1 TO FKMAX( )  && Loop for # of function keys
   ? FKLABEL(nCount)  && Display programmable function keys
ENDFOR

See Also

Other Resources

FKLABEL( ) Function
SET COMPATIBLE Command
SET FUNCTION Command
Functions
Language Reference


FLDLIST( ) Function

Visual FoxPro 9.0 Language Reference
FLDLIST( ) Function
See Also

Included for compatibility with dBASE.

See Also

Other Resources

Language Reference


FLOCK( ) Function

Visual FoxPro 9.0 Language Reference
FLOCK( ) Function
See Also Example

Attempts to lock the current or specified table.

FLOCK([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area of the table that FLOCK( ) attempts to lock. Omitting nWorkArea or cTableAlias causes FLOCK( ) to attempt locking the table that is open in the currently selected work area.
cTableAlias

Specifies the alias of the table that FLOCK( ) attempts to lock.
Note:
Visual FoxPro generates an error message if you specify a table alias that does not exist.

Return Value

Logical. FLOCK( ) returns True (.T.) if the table is successfully locked. Otherwise, it returns False (.F.) under the following conditions:

  • The table or a record in the table is already locked by another user.

  • A table is not open in the work area you specify.

Note:
If FLOCK() fails to lock a table and returns False (.F.), FLOCK() does not generate an error. As a result, you cannot use FLOCK() to trigger an ON ERROR routine.

Remarks

When a table is locked, the table is available for both read and write access by the user who placed the lock. Other users on the network have read-only access to the table. For information on how to lock a table and prevent access to it by other users, see SET EXCLUSIVE Command and USE Command.

A table remains locked until it is unlocked by the user who placed the lock. The table can be unlocked by issuing UNLOCK, closing the table, or quitting Visual FoxPro. Tables can be closed with USE, CLEAR ALL, or CLOSE DATABASES.

By default, FLOCK( ) attempts to lock a table once. Use SET REPROCESS to automatically retry a table lock when the first attempt fails. SET REPROCESS determines the number of lock attempts, or the length of time during which lock attempts are made when the initial lock attempt is unsuccessful. For more information, see SET REPROCESS Command.

You can establish relations between two or more tables with SET RELATION. Placing a file lock on a table that is related to one or more tables doesn't place a file lock on the related tables. You must explicitly place and remove locks on the related tables.

For additional information about record and file locking and sharing tables on a network, see Programming for Shared Access.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE products  && Opens products table
SET REPROCESS TO 3 SECONDS
SELECT * FROM products INTO TABLE newprods

IF FLOCK( )
   *** New product initialization ***
   REPLACE ALL in_stock  WITH 0.00
   REPLACE ALL on_order WITH 0.00
   WAIT 'Initialization Complete' WINDOW NOWAIT
ELSE
   *** File is locked, warn user ***
   WAIT WINDOW 'Unable to open products file; try again later!' NOWAIT
ENDIF

BROWSE FIELDS in_stock, on_order && Displays newprods table
USE
ERASE newprods.dbf

See Also

Other Resources

LOCK( ) Function
RLOCK( ) Function
SET RELATION Command
UNLOCK Command
ISFLOCKED( ) Function
ISRLOCKED( ) Function
Functions
Language Reference


FLOOR( ) Function

Visual FoxPro 9.0 Language Reference
FLOOR( ) Function
See Also Example

Returns the nearest integer that is less than or equal to the specified numeric expression.

FLOOR(nExpression)

Parameters

nExpression

Specifies the numeric expression for which FLOOR( ) returns the nearest integer that is less than or equal to the numeric expression.

Return Value

Numeric

Example

Copy Code
STORE  10.9 TO gnNumber1
STORE -10.1 TO gnNumber2

CLEAR
? FLOOR(gnNumber1)  && Displays 10
? FLOOR(gnNumber2)  && Displays -11
? FLOOR(10.0)  && Displays 10
? FLOOR(-10.0)  && Displays -10

See Also

Other Resources

CEILING( ) Function
INT( ) Function
ROUND( ) Function
Functions
Language Reference


FONTMETRIC( ) Function

Visual FoxPro 9.0 Language Reference
FONTMETRIC( ) Function
See Also

Returns font attributes for the current installed operating system fonts.

FONTMETRIC(nAttribute [, cFontName, nFontSize [, cFontStyle]])

Parameters

nAttribute

Determines the font attribute FONTMETRIC( ) returns. If you omit cFontName, nFontSize, and cFontStyle, FONTMETRIC( ) returns the attribute for the current font in the active output window. The following table lists values for nAttribute and the corresponding font attributes returned.

NAttribute Attribute

1

Character height in pixels

2

Character ascent (units above baseline) in pixels

3

Character descent (units below baseline) in pixels

4

Leading (space between lines) in pixels

5

Extra leading in pixels

6

Average character width in pixels

7

Maximum character width in pixels

8

Font weight.

9

Italic (0 = no, nonzero = yes)

10

Underlined (0 = no, nonzero = yes)

11

Strikeout (0 = no, nonzero = yes)

12

First character defined in font

13

Last character defined in font

14

Default character (substituted for characters not in font)

15

Word-break character

16

Pitch and family

17

Character set

18

Overhang (extra added width)

19

Horizontal aspect for font device

20

Vertical aspect for font device
For more information about the numeric values returned by FONTMETRIC( ), see the TEXTMETRIC function in the Microsoft Windows Programmer's Reference.
cFontName

Specifies the name of an installed font.
nFontSize

Specifies the point size of the font specified with cFontName.
cFontStyle

Specifies a font style code for the font specified with cFontName. If you omit cFontStyle, FONTMETRIC( ) returns the attribute for the Normal font style. cFontStyle can be a character or a combination of characters listed in the following font style table. For example, the combination BI specifies the Bold Italic font style.

Character Font style

B

Bold

I

Italic

N

Normal

O

Outline

Q

Opaque

S

Shadow

–

Strikeout

T

Transparent

U

Underline

Return Value

Numeric

Remarks

FONTMETRIC( ) returns font attributes for the current font for the active output window. WFONT( ) can be used to determine the current window font.

See Also

Other Resources

AFONT( ) Function
Fonts Overview
GETFONT( ) Function
SYSMETRIC( ) Function
TXTWIDTH( ) Function
Functions
Language Reference


FOPEN( ) Function

Visual FoxPro 9.0 Language Reference
FOPEN( ) Function
See Also Example

Opens a file for use with low-level file functions.

FOPEN(cFileName [, nAttribute])

Parameters

cFileName

Specifies the name of the file to open. cFileName can include a path to open files in directories, folders, drives, or volumes not in the current Microsoft Visual FoxPro search path. If a path isn't included, Visual FoxPro searches for the file in the following locations:
  • Default directory

  • Path established with SET PATH

    Note:
    Visual FoxPro will not recognize a path name properly if a disk or directory name contains an exclamation point (!).

nAttribute

Specifies read/write privileges or a buffering scheme for the file you open. The following table lists each number you can include in nAttribute, and the read/write file privileges and buffering scheme it establishes.

nAttribute Read/Write privileges Buffered/unbuffered

0

(Default) Read-only

Buffered

1

Write-only

Buffered

2

Read and Write

Buffered

10

Read-only

Unbuffered

11

Write-only

Unbuffered

12

Read and Write

Unbuffered
If nAttribute isn't included, or if nAttribute evaluates to 0, the file is opened as read-only and is buffered.
Note:
Visual FoxPro will not recognize a path name properly if a disk or directory name contains an exclamation point (!).

Remarks

If FOPEN( ) successfully opens the file, the file handle number of the file is returned. FOPEN( ) returns –1 if the file cannot be opened.

Tip:
Assign the file handle number to a memory variable so you can access the file by the memory variable in other low-level file functions.

The following information about files opened with FOPEN( ) can be displayed or sent to a printer with DISPLAY STATUS or LIST STATUS.

  • Drive and directory or volume and folder, and file name

  • File handle number

  • File pointer position

  • Read/write attributes

Return Value

Numeric

Example

Copy Code
IF FILE('errors.txt')  && Does file exist?
   gnErrFile = FOPEN('errors.txt',12)  && If so, open read/write
ELSE
   gnErrFile = FCREATE('errors.txt')  && If not, create it
ENDIF
IF gnErrFile < 0  && Check for error opening file
   WAIT 'Cannot open or create output file' WINDOW NOWAIT
ELSE  && If no error, write to file
   =FWRITE(gnErrFile, 'Error information to be written here')
ENDIF
=FCLOSE(gnErrFile)  && Close file
MODIFY FILE errors.txt NOWAIT  && Open file in edit window

See Also

Other Resources

CLOSE ALL Command
FCHSIZE( ) Function
FCLOSE( ) Function
FCREATE( ) Function
FEOF( ) Function
FFLUSH( ) Function
FGETS( ) Function
FPUTS( ) Function
FREAD( ) Function
FSEEK( ) Function
FWRITE( ) Function
Functions
Language Reference


FOR( ) Function

Visual FoxPro 9.0 Language Reference
FOR( ) Function
See Also

Returns the index filter expression, in uppercase, of an open single-entry index (.idx) file or an index tag.

FOR([nIndexNumber [, nWorkArea | cTableAlias]])

Parameters

If you don't include any of the optional arguments, FOR( ) returns the index filter expression for the master index file or index tag. If a master index file or index tag isn't in effect (for example, you've issued SET ORDER TO to place the table in physical record order), FOR( ) returns the empty string.

nIndexNumber

Specifies the index file or tag for which the filter expression is returned. FOR( ) returns filter expressions in the following order as nIndexNumber increases from 1 to the total number of open single-entry files and structural compound and independent compound index tags:
  1. Filter expressions from single-entry index files (if any are open) are returned first. The order the single-entry index files are included in USE or SET INDEX determines the order in which the filter expressions are returned.

  2. Filter expressions for each tag in the structural compound index (if one is present) are returned next. The filter expressions are returned from the tags in the order the tags are created in the structural index.

  3. Filter expressions for each tag in any open independent compound indexes are returned last. The filter expressions are returned from the tags in the order in which the tags are created in the independent compound indexes.

    The empty string is returned if an index or index tag is created without a FOR clause or if nIndexNumber is greater than the total number of open single-entry files and structural compound and independent compound index tags.

nWorkArea

Specifies the work area of the table for which FOR( ) returns the index filter expressions. FOR( ) returns the empty string if a table isn't open in the work area you specify.
cTableAlias

Specifies the alias of the table for which FOR( ) returns the index filter expressions. Visual FoxPro generates an error message if you specify a table alias that doesn't exist.

Return Value

Character

Remarks

You can create filtered indexes in Visual FoxPro. If you include the optional FOR lExpression clause in INDEX, the index file acts as a filter on the table. Only records that match the filter expression lExpression are available for display and access. Index keys are created in the index file for just those records matching the filter expression.

USE and SET INDEX both support an index file name list that makes it possible for you to open multiple index files for a table. Any combination of single-entry index file names, structural compound, or independent compound index file names can be included in the index file name list. FOR( ) is similar to SYS(2021) and is provided for compatibility with dBASE IV.

See Also

Other Resources

INDEX Command
Functions
Language Reference


FORCEEXT( ) Function

Visual FoxPro 9.0 Language Reference
FORCEEXT( ) Function
See Also

Returns a string with the old file name extension replaced by a new extension.

FORCEEXT(cFileName, cExtension)

Parameters

cFileName

Specifies the file name (with or without a path or extension), which will get a new extension.
cExtension

Specifies the new extension (without a period) for cFileName.

Return Value

Character

See Also

Other Resources

ADDBS( ) Function
DEFAULTEXT( ) Function
FILE( ) Function
FORCEPATH( ) Function
JUSTDRIVE( ) Function
JUSTEXT( ) Function
JUSTFNAME( ) Function
JUSTPATH( ) Function
JUSTSTEM( ) Function
Functions
Language Reference


FORCEPATH( ) Function

Visual FoxPro 9.0 Language Reference
FORCEPATH( ) Function
See Also

Returns a file name with a new path name substituted for the old one.

FORCEPATH(cFileName, cPath)

Parameters

cFileName

Specifies the file name (with or without a path or extension), which will get a new path.
cPath

Specifies the new path for cFileName.

Return Value

Character

See Also

Other Resources

ADDBS( ) Function
DEFAULTEXT( ) Function
FILE( ) Function
FORCEEXT( ) Function
JUSTDRIVE( ) Function
JUSTEXT( ) Function
JUSTFNAME( ) Function
JUSTPATH( ) Function
JUSTSTEM( ) Function
Functions
Language Reference


FOUND( ) Function

Visual FoxPro 9.0 Language Reference
FOUND( ) Function
See Also

Determines whether the most recently executed CONTINUE, FIND, LOCATE, or SEEK command was successful or if the record pointer was moved in a related table.

Tip:
You can use FOUND( ) to determine if a child table has a record that matches the parent record.

FOUND([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area of the table that the most recent CONTINUE, FIND, LOCATE, or SEEK command was called on.
cTableAlias

Specifies the alias of the table that the most recent CONTINUE, FIND, LOCATE, or SEEK command was called on.
Note:
If you specify a table alias that does not exist, Visual FoxPro generates an error message.

Return Value

Logical. FOUND( ) returns True (.T.) if the most recent CONTINUE, FIND, LOCATE, or SEEK command was successful; otherwise, it returns False (.F.). If a table is not open in the work area you specify, FOUND( ) returns False. When FOUND( ) encounters an end-of-file, which can be determined by the EOF( ) function, it always returns False.

Remarks

If you call FOUND( ) without arguments, FOUND( ) is called on the table open in the currently selected work area.

Examples

The following example locates and counts all customers whose Country field in the Customer table contains "GERMANY". CLOSE DATABASES closes all databases, and OPEN DATABASE opens the sample Visual FoxPro database, TestData.dbc. USE opens the Customer table.

STORE stores a value of 0 in the variable gnCount. LOCATE searches for the first record in which the Country field contains the value "GERMANY". The DO WHILE loop increments the variable gnCount by 1 and uses CONTINUE to perform another LOCATE operation. When there are no more matching records, the total number of customers is displayed.

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer
STORE 0 TO gnCount
LOCATE FOR UPPER(Country)='GERMANY'
DO WHILE FOUND()
   gnCount = gnCount + 1
   CONTINUE
ENDDO
? "Total customers from Germany: "+LTRIM(STR(gnCount))

See Also

Other Resources

CONTINUE Command
FIND Command
LOCATE Command
SEEK Command
EOF( ) Function
Functions
Language Reference


FPUTS( ) Function

Visual FoxPro 9.0 Language Reference
FPUTS( ) Function
See Also

Writes a character string, carriage return, and line feed to a file opened with a low-level file function.

FPUTS(nFileHandle, cExpression [, nCharactersWritten])

Parameters

nFileHandle

Specifies the file handle number for the file to which FPUTS( ) writes data.
cExpression

Specifies the character expression that FPUTS( ) writes to the file.
nCharactersWritten

Specifies the number of characters in cExpression to write to the file. FPUTS( ) writes the entire character expression cExpression to the file if you omit nCharactersWritten. If you include nCharactersWritten, nCharactersWritten characters are written to the file. If nCharactersWritten is less than the number of characters in cExpression, only nCharactersWritten characters are written to the file. All of cExpression is written to the file if nCharactersWritten is equal to or greater than the number of characters in cExpression.

Return Value

Numeric

Remarks

FPUTS( ) returns the number of bytes written to the file. Zero is returned if FPUTS( ) cannot write to the file for any reason.

See Also

Other Resources

FCHSIZE( ) Function
FCLOSE( ) Function
FCREATE( ) Function
FEOF( ) Function
FFLUSH( ) Function
FGETS( ) Function
FOPEN( ) Function
FREAD( ) Function
FSEEK( ) Function
FWRITE( ) Function
Functions
Language Reference


FREAD( ) Function

Visual FoxPro 9.0 Language Reference
FREAD( ) Function
See Also Example

Returns a specified number of bytes from a file opened with a low-level function.

FREAD(nFileHandle, nBytes)

Parameters

nFileHandle

Specifies the file handle number for the file from which FREAD( ) returns data. You can obtain nFileHandle from the return value of successful FOPEN( ) or FCREATE( ) statements.
nByte s

Specifies the number of bytes returned by FREAD( ) with a limit of 65,535 bytes. FREAD( ) returns data starting from the current file pointer position and continues until it returns nBytes bytes or until it encounters the end of the file.

Return Value

Character

Example

The following example uses FREAD( ) to display the contents of a file. If the file is empty, a message is displayed. Before using this example, you must create a sample text file called Test.txt.
Copy Code
Local gnFileHandle,nSize,cString
gnFileHandle = FOPEN("test.txt")
* Seek to end of file to determine number of bytes in the file.
nSize =  FSEEK(gnFileHandle, 0, 2)     && Move pointer to EOF
IF nSize <= 0
 * If file is empty, display an error message.
 WAIT WINDOW "This file is empty!" NOWAIT
ELSE
 * If file is not empty, store the file's contents in memory
 * and display the text in the main Visual FoxPro window.
 = FSEEK(gnFileHandle, 0, 0)      && Move pointer to BOF
 cString = FREAD(gnFileHandle, nSize)
 ? cString
ENDIF
= FCLOSE(gnFileHandle)         && Close the file

See Also

Other Resources

FCHSIZE( ) Function
FCLOSE( ) Function
FCREATE( ) Function
FEOF( ) Function
FFLUSH( ) Function
FGETS( ) Function
FILETOSTR( ) Function
FOPEN( ) Function
FPUTS( ) Function
FSEEK( ) Function
FWRITE( ) Function
Functions
Language Reference


FSEEK( ) Function

Visual FoxPro 9.0 Language Reference
FSEEK( ) Function
See Also Example

Moves the file pointer in a file opened with a low-level file function.

FSEEK(nFileHandle, nBytesMoved [, nRelativePosition])

Parameters

nFileHandle

Specifies the file handle for the file in which FSEEK( ) moves the file pointer. A file handle number is returned by FCREATE( ) or FOPEN( ) when the file is created or opened.
nBytesMoved

Specifies the number of bytes to move the file pointer. The file pointer is moved toward the end of the file if nBytesMoved is positive. The file pointer is moved toward the beginning of the file if nBytesMoved is negative.
nRelativePosition

Moves the file pointer to a relative position in the file. By default, the file pointer is moved relative to the beginning of the file. You can also move the file pointer relative to the current file pointer or the end of the file by including nRelativePosition. The following table lists values for nRelativePosition and from where the file pointer is moved.

nRelativePosition Moves the file pointer relative to

0

(Default) The beginning of the file.

1

The current file pointer position.

2

The end of the file.

Return Value

Numeric

Remarks

After moving the file pointer, FSEEK( ) returns the number of bytes the file pointer is positioned from the beginning of the file. The file pointer can also be moved with FREAD( ) and FWRITE( ).

Example

The following user-defined function uses FSEEK( ) to return the size of a file. If you don't pass parameters to the user-defined function, it returns –2. If the file cannot be found, the user-defined function returns –1.
Copy Code
FUNCTION fsize2
PARAMETERS gcFileName  && File to be checked
PRIVATE pnHandle,pnSize
IF PARAMETERS( ) = 0
   RETURN -2  && Return -2 if no parameter passed
ELSE
   IF !FILE(gcFileName)
      RETURN -1  && Return -1 if file does not exist
   ENDIF
ENDIF
pnHandle = FOPEN(gcFileName)   && Open file
pnSize = FSEEK(pnHandle,0,2)   && Determine file size, assign to pnSize
=FCLOSE(pnHandle)  && Close file
RETURN pnSize  && Return value

See Also

Other Resources

FCHSIZE( ) Function
FCLOSE( ) Function
FCREATE( ) Function
FEOF( ) Function
FFLUSH( ) Function
FGETS( ) Function
FOPEN( ) Function
FPUTS( ) Function
FREAD( ) Function
FWRITE( ) Function
Functions
Language Reference


FSIZE( ) Function

Visual FoxPro 9.0 Language Reference
FSIZE( ) Function
See Also Example

Returns the size in bytes of a specified field or file.

FSIZE(cFieldName [, nWorkArea | cTableAlias] | cFileName)

Parameters

cFieldName

Specifies the name of the field.
nWorkArea

Specifies the work area of the table for which FSIZE( ) returns a field size. FSIZE( ) returns 0 if a table isn't open in the work area you specify.
cTableAlias

Specifies the alias of the table for which FSIZE( ) returns a field size. Visual FoxPro generates an error message if you specify a table alias that doesn't exist.
cFileName

Specifies a file for which FSIZE( ) returns the size in bytes.

Return Value

Numeric

Remarks

The current setting of SET COMPATIBLE determines if FSIZE( ) returns the size of a field or a file. If SET COMPATIBLE is set to OFF or FOXPLUS (the default), FSIZE( ) returns the size of a field. If SET COMPATIBLE is set to ON or DB4, FSIZE( ) returns the size of a file.

The following table shows the default size (in bytes) for each fixed-length field type.

Field type | Default field size(in bytes)
Currency | 8
Date | 8
DateTime | 8
Double | 8
Integer | 4
Logical | 1
Memo | 4
General | 4

The size of a field can be displayed with DISPLAY STRUCTURE and LIST STRUCTURE.

If you omit the optional nWorkArea and cTableAlias arguments, FSIZE( ) returns the field size for a field in the current table and work area.

Example

The following example uses FSIZE( ) to return the size of two fields in the customer table.
Copy Code
SET COMPATIBLE OFF
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Open Customer table

CLEAR
? FSIZE('contact')  && Displays 30
? FSIZE('cust_id')  && Displays 6

See Also

Other Resources

DISPLAY STRUCTURE Command
FCOUNT( ) Function
LIST Command
Functions
Language Reference


FTIME( ) Function

Visual FoxPro 9.0 Language Reference
FTIME( ) Function
See Also Example

Returns the last modification time for a file.

FTIME(cFileName)

Parameters

cFileName

Specifies the name of the file whose last modification time FTIME( ) returns. cFileName can include a path with the file name. If a path is not included with the file name, Visual FoxPro searches for the file in the default directory and in any directories or folders specified with SET PATH.

Return Value

Character

Remarks

The time that FTIME( ) returns is assigned to the file by the operating system.

Example

The following example uses FTIME( ) to display the last modification time for FoxUser.dbf, the Visual FoxPro resource file.
Copy Code
? FTIME('FOXUSER.DBF')  && Displays the last modification time

See Also

Other Resources

FDATE( ) Function
LUPDATE( ) Function
SET PATH Command
Functions
Language Reference


FULLPATH( ) Function

Visual FoxPro 9.0 Language Reference
FULLPATH( ) Function
See Also

Returns the path to a specified file or the path relative to another file.

FULLPATH(cFileName1 [, nMSDOSPath | cFileName2])

Parameters

cFileName1

Specifies the file for which Visual FoxPro searches. If the file is located in the Visual FoxPro path, the path is returned with the file name. You can specify the Visual FoxPro path using the SET PATH command. If the file cannot be located in the Visual FoxPro path, FULLPATH( ) returns the current directory the path and file name as if the file was located in the current default directory.
nMSDOSPath

Specifies to search the MS-DOS path instead of the Visual FoxPro path. nMSDOSPath can have any numeric value. If the file cannot be located in the MS-DOS path, FULLPATH( ) returns the path and the file name as if the file was located in the current default directory.
cFileName2

Specifies a second file name to search for. FULLPATH( ) returns the path for the first file relative to the second file.

Return Value

Character. FULLPATH( ) returns a file path.

Remarks

Use the FILE( ) function to verify that the file actually exists; otherwise, if the file does not exist, the function returns the file name with the current directory.

See Also

Other Resources

DBF( ) Function
FILE( ) Function
LOCFILE( ) Function
SYS(2014) - Minimum Path
Functions
Language Reference


FV( ) Function

Visual FoxPro 9.0 Language Reference
FV( ) Function
See Also Example

Returns the future value of a financial investment.

FV(nPayment, nInterestRate, nPeriods)

Parameters

nPayment

Specifies the constant periodic payment (which can be negative or positive).
nInterestRate

Specifies the periodic interest rate. If the interest rate is annual but the payments are made monthly, divide the annual interest rate by 12.
nPeriods

Specifies the number of periods over which payments are made. FV( ) assumes that the periodic payments are made at the end of each period.

Return Value

Numeric

Remarks

FV( ) computes the future value of a series of constant periodic payments earning fixed compound interest. The future value is the total of all payments and the interest.

Example

Copy Code
STORE 500 TO gnPayment  && Monthly payment
STORE .075/12 TO gnInterest     && 7.5% annual interest rate
STORE 48 TO gnPeriods  && Four years (48 months)

CLEAR
? FV(gnPayment, gnInterest, gnPeriods)    && Displays 27887.93

See Also

Other Resources

CALCULATE Command
PV( ) Function
STORE Command
Functions
Language Reference


FWRITE( ) Function

Visual FoxPro 9.0 Language Reference
FWRITE( ) Function
See Also

Writes a character string to a file opened with a low-level file function.

FWRITE(nFileHandle, cExpression [, nCharactersWritten])

Parameters

nFileHandle

Specifies the file handle number for the file to which FWRITE( ) writes.
cExpression

Specifies the character expression that FWRITE( ) writes to the file specified with nFileHandle.
nCharactersWritten

FWRITE( ) writes the entire character expression to the file unless you include nCharactersWritten. When you include nCharactersWritten, nCharactersWritten characters are written to the file. If nCharactersWritten is less than the number of characters in cExpression, only nCharactersWritten characters are written to the file. All of the characters in cExpression are written to the file if nCharactersWritten is equal to or greater than the number of characters in cExpression.

Return Value

Numeric

Remarks

Unlike FPUTS( ), FWRITE( ) doesn't place a carriage return and a line feed at the end of the character string.

FWRITE( ) returns the number of bytes written to the file. If FWRITE( ) can't write to the file for any reason, 0 is returned.

See Also

Other Resources

FCHSIZE( ) Function
FCLOSE( ) Function
FCREATE( ) Function
FEOF( ) Function
FFLUSH( ) Function
FGETS( ) Function
FOPEN( ) Function
FPUTS( ) Function
FREAD( ) Function
FSEEK( ) Function
STRTOFILE( ) Function
Functions
Language Reference


GETAUTOINCVALUE( ) Function

Visual FoxPro 9.0 Language Reference
GETAUTOINCVALUE( ) Function

Returns the last value generated for an autoincremented field within a data session.

GETAUTOINCVALUE([nDataSessionNumber | 0])

Parameters

nDataSessionNumber

Specifies the data session number of the data session for which the autoincremented field value is returned. The autoincremented field value is returned for the current data session if you omit the nDataSessionNumber and 0 parameters. Use SET DATASESSION to activate a specific data session.
0

Specifies that the autoincremented field value is returned from within the scope of the current function, procedure, or method.

Return Value

Numeric data type. The value returned by GETAUTOINCVALUE( ) is the last autoincrement value generated, even if a field was not successfully updated with the autoincrement value. .NULL. is returned if an autoincrement value hasn't yet been generated for a data session. For example, .NULL. is returned if a data session is opened and no updates have occurred.

Remarks

The autoincremented field value is updated for table operations such as APPEND Command, INSERT Command, APPEND FROM Command, and BLANK Command when the AUTOINC option is included. See Autoincrementing Field Values in Tables for more information about autoincrementing fields.


GETBAR( ) Function

Visual FoxPro 9.0 Language Reference
GETBAR( ) Function
See Also Example

Returns the number of an item on a menu defined with DEFINE POPUP or the Visual FoxPro system menu.

GETBAR(MenuItemName, nMenuPosition)

Parameters

MenuItemName

Specifies the menu item.
nMenuPosition

Specifies a position on the menu. nMenuPosition can range from 1 through the number of items within the menu. 1 corresponds to the first item on the menu, 2 to the second item, and so on.

Return Value

Numeric

Remarks

Use GETBAR( ) to determine which item occupies a specific position on a menu. This function is useful when items on a menu are added, removed, or rearranged. Use DEFINE BAR to add an item to a menu or RELEASE BAR to remove an item. The position of items in a menu can be changed if MOVER is included when the menu is created with DEFINE POPUP.

Example

The following example creates a menu named popDemo. The MOVER keyword is included so the items in the menu can be rearranged. For information about rearranging menu items, see the MOVER clause in DEFINE POPUP.

The menu is activated, and a series of GETBAR( ) functions are used in PRMBAR( ) to return captions of each item. After you rearrange the items, press CTRL+Z to display the new item order.
Copy Code
CLEAR
ON KEY LABEL CTRL+Z DO showorder
WAIT WINDOW "Press CTRL+Z to refresh." NOWAIT

DEFINE POPUP popDemo MOVER FROM 2,2
DEFINE BAR 1 OF popDemo PROMPT 'One'
DEFINE BAR 2 OF popDemo PROMPT 'Two'
DEFINE BAR 3 OF popDemo PROMPT 'Three'
DEFINE BAR 4 OF popDemo PROMPT 'Four'

DO showorder
ACTIVATE POPUP popDemo

PROCEDURE showorder
CLEAR
@ 3,12 SAY  '1 ' + PRMBAR('popDemo', GETBAR('popDemo',1))
@ 4,12 SAY  '2 ' + PRMBAR('popDemo', GETBAR('popDemo',2))
@ 5,12 SAY  '3 ' + PRMBAR('popDemo', GETBAR('popDemo',3))
@ 6,12 SAY  '4 ' + PRMBAR('popDemo', GETBAR('popDemo',4))
RETURN

See Also

Other Resources

DEFINE BAR Command
DEFINE POPUP Command
RELEASE BAR Command
Functions
Language Reference


GETCOLOR( ) Function

Visual FoxPro 9.0 Language Reference
GETCOLOR( ) Function
See Also Example

Displays the Windows Color dialog box and returns the color number of the chosen color.

GETCOLOR([nDefaultColorNumber])

Parameters

nDefaultColorNumber

Specifies the color that is initially selected when the Color dialog box is displayed. If nDefaultColorNumber doesn't correspond to a color in the Color dialog box, the first color in the Color dialog box is selected. If you omit nDefaultColorNumber, black is selected.

Return Value

Numeric

Remarks

GETCOLOR( ) returns – 1 if you exit the Color dialog box by pressing ESC, choosing the Cancel button, or choosing Close from the Control menu.

Example

The following example displays the Windows Color dialog box with the color red selected. A number corresponding to the color you choose is displayed when you exit the dialog box.
Copy Code
CLEAR
? GETCOLOR(255)

See Also

Other Resources

GETPICT( ) Function
RGB( ) Function
Functions
Language Reference


GETCP( ) Function

Visual FoxPro 9.0 Language Reference
GETCP( ) Function
See Also Example

Prompts for a code page by displaying the Code Page dialog box, and then returns the number of the code page chosen.

GETCP([nCodePage] [, cText] [, cDialogTitle])

Parameters

nCodePage

Specifies the number of the code page that is initially selected when the Code Page dialog box is displayed. If nCodePage is 0 or if you omit nCodePage, a code page isn't selected when the Code Page dialog box is displayed.
cText

Specifies the text displayed in the Code Page dialog box. If you omit cText, Visual FoxPro displays the following text: "Please select a code page for cross-platform data sharing."
cDialogTitle

Specifies the title that appears in the Code Page dialog box title bar. If you omit cDialogTitle, the title "Code Page" is displayed.

Return Value

Numeric

Remarks

GETCP( ) returns 0 if you exit the Code Page dialog box by pressing ESC, choosing the Cancel button, or choosing Close from the Control menu.

The code pages listed in the Code Page dialog box are determined by FOXPRO.INT, the Visual FoxPro International code page support file.

You can include GETCP( ) in commands such as MODIFY COMMAND, APPEND FROM, and COPY TO that support the AS nCodePage clause. The Code Page dialog box is displayed, making it possible for you to specify the code page of the file opened, appended, or created. Because no code page 0 exists, you must trap for 0 in case the user chooses ESC, the Cancel button, or Close from the Control menu.

Example

The following example displays the Code Page dialog box with code page 1252 (Windows ANSI) selected. "Select a Code Page" is displayed as the caption in the Code Page dialog box, and "Code Page Selection" is displayed in the Code Page dialog box title bar.
Copy Code
? GETCP(1252, "Select a Code Page", "Code Page Selection")

See Also

Other Resources

APPEND FROM Command
COPY TO Command
EXPORT Command
IMPORT Command
MODIFY COMMAND Command
MODIFY FILE Command
MODIFY QUERY Command
Functions
Language Reference


GETCURSORADAPTER( ) Function

Visual FoxPro 9.0 Language Reference
GETCURSORADAPTER( ) Function
See Also

Returns an object reference to a CursorAdapter object at run time by referencing the cursor name.

GETCURSORADAPTER( [ cAlias ] )

Parameters

cAlias

Specifies the alias of the cursor. If you do not supply an alias, Visual FoxPro uses the alias for the cursor in the current work area.

Return Value

An object reference to a CursorAdapter object.

Remarks

Applies To: CursorAdapter Class

See Also

Other Resources

Functions
CursorAdapter Object Properties, Methods, and Events


GETDIR( ) Function

Visual FoxPro 9.0 Language Reference
GETDIR( ) Function
See Also

Displays the Select Directory dialog box from which you can choose a directory.

GETDIR([cDirectory [, cText [, cCaption [, nFlags [, lRootOnly]]]]])

Parameters

cDirectory

Specifies the directory that is initially displayed in the dialog box. When cDirectory is not specified, the dialog box opens with the Visual FoxPro default directory displayed.
cText

Specifies the text for the directory list in the dialog box.
cCaption

Specifies the caption to display in the dialog title bar. The Windows default is "Select Directory".
nFlags

Specify the options for the dialog box. nFlags can include zero or an additive combination of the values. The following table includes some of more common flags. For more information, see SHBrowseForFolder in MSDN.

nFlag Value Description

1

BIF_RETURNONLYFSDIRS

Return only file system directories (physical locations). If a user selects folders that are not part of the file system, the OK button is grayed.

2

BIF_DONTGOBELOWDOMAIN

Do not include network folders below the domain level in the tree view control (For example, My Computer and My Networks).

8

BIF_RETURNFSANCESTORS

Return only file system ancestors. If a user selects anything other than a file system ancestor, the OK button is grayed.

16

BIF_EDITBOX

The browse dialog includes an edit control in which the user can type the name of an item. Available on Windows 98 and above, or with Internet Explorer 4.0 or higher (assuming shell integration option selected). Requires version 4.71 of shell32.dll.

32

BIF_VALIDATE

Validates the editbox contents. If the editbox is used, it is necessary to validate the user-specified content. If the user types an invalid name into the edit box, the Cancel button becomes the only selection available. This flag is ignored if BIF_EDITBOX is not specified.

64

BIF_NEWDIALOGSTYLE

Use the new user-interface. Setting this flag provides the user with a larger, resizable dialog box. Additional functionality includes: drag and drop capability within the dialog box, reordering, context menus, new folders, delete, and other context menu commands. Support in Windows 2000 and above. Requires version 5.00 of shell32.dll.

16384

BIF_BROWSEINCLUDEFILES

The browse dialog will display files as well as folders. Available on Windows 98 and above, or with Internet Explorer 4.0 or higher (assuming shell integration option selected). Requires version 4.71 of shell32.dll.
lRootOnly

Specifies that only cDirectory and its subfolders display. This parameter prevents navigation above the root folder. If you do not specify cDirectory, the default directory (SET DEFAULT value) is used.

Return Value

Character

Remarks

GETDIR( ) returns as a character string the name of the directory you choose.

If you do not choose a directory (you click Cancel, press ESC, or choose Close from the window menu), GETDIR( ) returns the empty string.

Beginning with Visual FoxPro 7, GETDIR( ) supports two different dialog boxes. If you provide fewer than three parameters, GETDIR( ) returns the dialog box from earlier versions. If you provide more than two parameters, Visual FoxPro uses the SHBrowseForFolder routine from the Win32 API to provide the dialog.

See Also

Other Resources

DIRECTORY Command
DIRECTORY( ) Function
GETEXPR Command
GETFILE( ) Function
Functions
Language Reference


GETENV( ) Function

Visual FoxPro 9.0 Language Reference
GETENV( ) Function
See Also Example

Returns the contents of the specified MS-DOS environment variable.

GETENV(cVariableName)

Parameters

cVariableName

Specifies the name of the environment variable. The empty string is returned if the environment variable you specify doesn't exist. You can locate the Windows directory with the WINDIR environmental variable, which Windows sets when it starts.

Return Value

Character

Remarks

Two environment variables are always available: COMSPEC and PATH. You can create your own environment variables with the command shell SET command.

For additional information on creating environment variables, see the Windows product documentation.

Example

Copy Code
CLEAR
? GETENV('PATH')  && Displays the search path

See Also

Other Resources

DISKSPACE( ) Function
OS( ) Function
VERSION( ) Function
Functions
Language Reference


GETFILE( ) Function

Visual FoxPro 9.0 Language Reference
GETFILE( ) Function
See Also Example

Displays the Open dialog box.

GETFILE([cFileExtensions] [, cText] [, cOpenButtonCaption]
   [, nButtonType] [, cTitleBarCaption])

Parameters

cFileExtensions

Specifies the file name extensions for the files to display in the Open dialog box when the All Files type is not chosen. When passing a value as a literal, enclose it with quotation marks (""). Do not include a period (.) in front of file name extensions.
Note:
The cFileExtensions parameter cannot exceed 254 characters in length.

cFileExtensions can take a variety of forms:
  • If cFileExtensions contains a single extension, for example, "prg", the Open dialog box displays only those file names with that extension.

  • If cFileExtensions is the empty string, the Open dialog box displays all files in the current directory.

  • cFileExtensions can contain wildcard characters such as * and ?. The Open dialog box displays all file names with extensions that meet the wildcard criteria. For example, if cFileExtensions is "?X?", the Open dialog box displays all file names with the extension .fxp, .exe, and .txt.

  • cFileExtensions can contain a file description followed by a file extension or a list of file extensions separated with commas. The file description appears in the Open dialog box in the Files of Type list. Separate the file description from the file extension or list of file extensions with a colon (:). Separate multiple file descriptions and their file extensions with a semicolon (;).

    For example, if cFileExtensions is "Text:TXT", the Open dialog box displays the file description "Text" in the Files of Type list and displays all files with a .txt extension.

    If cFileExtensions is "Tables:DBF; Files:TXT,BAK" the file descriptions "Tables" and "Files" appear in the Files of Type list. When "Tables" is chosen from the Files of Type list, all files with a .dbf extension are displayed. When "Files" is chosen from the Files of Type list, all files with .txt and .bak extensions are displayed.

  • If cFileExtensions contains just a semicolon (";"), the Open dialog box displays all files without extensions.

cText

Specifies text to display for the File Name label in the Open dialog box.
cOpenButtonCaption

Specifies a caption for the OK button in the Open dialog box.
nButtonType

Specifies the number and type of buttons that appear in the Open dialog box. The following table lists the values for nButtonType.

nButtonType Buttons displayed

0 (or omitted)

OK, Cancel

1

OK, New, Cancel

2

OK, None, Cancel
Note:
GETFILE( ) returns the string "Untitled" with the path specified in the Open dialog box when nButtonType is set to 1 and the user clicks New, or when nButtonType is set to 2 and the user clicks None.

cTitleBarCaption

Specifies the caption for the title bar of the Open dialog box.

Return Value

Character. GETFILE( ) returns the name of the file chosen in the Open dialog box or the empty string if the user closes the Open dialog box by pressing ESC, clicking Cancel or the Close button on the Open dialog box.

Remarks

Example

Copy Code
CLOSE DATABASES
SELECT 0

gcTable=GETFILE('DBF', 'Browse or Create a .DBF:',
   'Browse', 1, 'Browse or Create')
DO CASE
   CASE 'Untitled' $ gcTable
      CREATE (gcTable)
   CASE EMPTY(gcTable)
      RETURN
   OTHERWISE
      USE (gcTable)
      BROWSE
ENDCASE

See Also

Other Resources

FULLPATH( ) Function
GETEXPR Command
GETPICT( ) Function
LOCFILE( ) Function
PUTFILE( ) Function
Functions
Language Reference


GETFLDSTATE( ) Function

Visual FoxPro 9.0 Language Reference
GETFLDSTATE( ) Function
See Also

Returns a numeric value indicating if a field in a table or cursor has been modified or had a record appended, or if the deleted status of the current record has been changed.

GETFLDSTATE(cFieldName | nFieldNumber [, cTableAlias | nWorkArea])

Parameters

cFieldName| nFieldNumber

Specifies the name of the field or the number of the field for which the modification status is returned. The field number nFieldNumber corresponds to the position of the field in the table or cursor structure. DISPLAY STRUCTURE or FIELD( ) can be used to determine a field's number. You can specify –1 for nFieldNumber to return a character string consisting of deletion and modification status values for all fields in the table or cursor. For example, if a table has five fields and only the first field has been changed, GETFLDSTATE( ) returns 121111. The 1 in the first position indicates the deletion status has not been changed. You can also include 0 for nFieldNumber to determine if the deletion status of the current record has changed since the table or cursor was opened.
Note:
Using GETFLDSTATE() only determines if the deletion status of the current record has changed. For example, if you mark a record for deletion and then recall it, GETFLDSTATE() indicates the deletion status has changed even though the record's deletion status has returned to its original state. Use DELETED() to determine the current deletion status of a record.

cTableAlias

Specifies the alias of the table or cursor for which the field modification or record deletion status is returned.
nWorkArea

Specifies the work area of the table or cursor for which the field modification or record deletion status is returned. If you do not specify an alias or work area, GETFLDSTATE( ) returns a value for a field in the currently selected table or cursor.

Return Value

Numeric, Character, or .NULL.

Remarks

The following table lists the character return values and the corresponding modification or deletion status.

Return value | Modification or deletion status
1 | Field has not been modified or deletion status has not changed.
2 | Field has been modified or deletion status has changed.
3 | Field in an appended record has not been modified or deletion status has not changed for the appended record.
4 | Field in an appended record has been modified or deletion status has changed for the appended record.
.NULL. | At EOF( )

Row or table buffering must first be enabled with CURSORSETPROP( ) for GETFLDSTATE( ) to operate on local tables.

The modification or deletion status is returned for the table or cursor open in the currently selected work area if GETFLDSTATE( ) is issued without the optional cTableAlias or nWorkArea arguments.

Any change in a field will cause GETFLDSTATE() to return a value showing that the field has been modified, whether the change is explicit or implicit. An example of an explicit modification would be including the field in a REPLACE or INSERT INTO command. An implicit modification occurs in a field that has a default value when any command is issued that adds a new record.

Example 1

The following example demonstrates how you can use GETFLDSTATE( ) to determine if the contents of a field have changed. MULTILOCKS is set to ON, a requirement for table buffering. The customer table in the testdata database is opened, and CURSORSETPROP( ) is then used to set the buffering mode to optimistic table buffering (5).

GETFLDSTATE( ) is issued to display a value (1) corresponding to the unmodified state of the cust_id field before it is modified. The cust_id field is modified with REPLACE, and GETFLDSTATE( ) is issued again to display a value (2) corresponding to the modified state of the cust_id field. TABLEREVERT( ) is used to return the table to its original state, and GETFLDSTATE( ) is issued again to display a value (1) corresponding to the original state of the cust_id field.

Copy Code
CLOSE DATABASES
CLEAR

SET MULTILOCKS ON         && Allow table buffering
OPEN DATABASE (HOME(2) + 'data\testdata')
USE Customer             && Open customer table
=CURSORSETPROP("Buffering",5,"customer")  && Enable table buffering

* Get field state on original cust_id field and display state
nState=GETFLDSTATE("cust_id")
DO DisplayState WITH nState("Original")

* Change field contents and display state
REPLACE cust_id    WITH "***"
nState=GETFLDSTATE("cust_id")
DO DisplayState WITH nState("After Replace")

* Discard table changes and display state
= TABLEREVERT(.T.)        && Discard all table changes
nState=GETFLDSTATE("cust_id")
DO DisplayState WITH nState("After Revert")

PROCEDURE DisplayState
PARAMETER nState,cOperation
DO CASE
   CASE nState=1
      =MESSAGEBOX("Field has not been modified",0,cOperation)
   OTHERWISE
      =MESSAGEBOX("Field has been modified",0,cOperation)
ENDCASE

Example 2

The following example shows the difference in behavior between fields with and without default values.

Copy Code
SET MULTILOCKS ON
CREATE DATABASE example
CREATE TABLE customer (cust_id C(6),state C(2) DEFAULT "FL")
CLOSE TABLES
USE customer
=CURSORSETPROP("Buffering",5,"customer")

APPEND BLANK
?GETFLDSTATE("cust_id")     && Returns 3, field in an appended record has
                            && not been modified.

?GETFLDSTATE("state")    && Returns 4, field in an appended record has
                         && been modified.

See Also

Other Resources

CURVAL( ) Function
DELETED( ) Function
FIELD( ) Function
OLDVAL( ) Function
CURSORSETPROP( ) Function
SETFLDSTATE( ) Function
Functions
Language Reference


GETFONT( ) Function

Visual FoxPro 9.0 Language Reference
GETFONT( ) Function
See Also Example

Displays the Font dialog box and returns information about the font you choose.

GETFONT([cFontName [, nFontSize [, cFontStyle [, nFontCharSet]]]])

Parameters

cFontName

Specifies the name of the font initially selected in the Font dialog box. If the font you specify is not installed, the default font is selected initially.
nFontSize

Specifies the font size selected initially in the Font dialog box. If the font size you specify is not supported, the default font size is selected initially. If you omit nFontSize or if nFontSize is less than or equal to zero, the font size selected defaults to 10 point.
Note:
The dialog box permits you to select sizes between 4 and 127, inclusive. You can specify other values for nFontSize when calling the GETFONT function; no error occurs. If you do so, however, the user must select a size within the designated range of values before clicking OK in the dialog box. Otherwise, the dialog box displays an alert and does not accept the value.

cFontStyle

Specifies the font style selected initially in the Font dialog box or to display only those fonts available on the selected printer. If the font style you specify is not supported, the default font style is selected initially. The following table lists the values available for cFontStyle.

cFontStyle Description

B

Select Bold font style initially.

I

Select Italic font style initially.

BI

Select Bold Italic font style initially.

P

Display only those fonts available on the current default printer.
nFontCharSet

Specifies a value for the language script. The values you can specify differ depending on your version of Windows.
Note:
Omitting this value disables the script drop-down list in the dialog box.

The following table describes some example values for nFontCharSet.

nFontCharSet Language script

0

Western

1

Default

2

Symbol

128

Japanese

161

Greek

162

Turkish

163

Vietnamese

177

Hebrew

178

Arabic

186

Baltic

204

Cyrillic

238

Central European
Note:
If you specify 1 for nFontCharSet, the dialog box that GETFONT( ) opened displays the default language script on the operating system. GETFONT( ) never returns 1 because it returns the value for the language script selected in the GETFONT( ) dialog box.

For more information, see FontCharSet Property.

Return Value

Character. GETFONT( ) returns one of the following, depending on certain conditions:

  • A character string containing three types of font information with commas separating the items returned: font name, size and style. This behavior occurs when you choose one in the Font dialog box and you have not included the fourth optional argument when calling the GETFONT( ) function.

  • A character string containing four types of font information with commas separating the items returned: font name, size, style and language script. This behavior occurs if you include a value for the nFontCharSet parameter.

Note:
In versions of Visual FoxPro previous to Visual FoxPro 9.0, if you included a value of 0 as the fourth argument to GETFONT(), you received the same return information as if you did not include the fourth argument at all. The script drop-down list was not enabled, and the return value contained only three types of font information. In Visual FoxPro 9.0, a value of 0 explicitly indicates the numeric value corresponding to Western script. The script drop-down list might also initially display Western if you specify 1 for this value, but only if Western is the default script for your regional settings.

  • An empty string if you exit the Font dialog box by clicking Cancel, Close on the Control menu, or pressing the ESC key.

Remarks

Tip:
You can abbreviate some Visual FoxPro commands and functions to four characters when conflicts with other commands and functions do not exist. In the case of GETFONT( ) and GETFILE( ), which both begin with the same four letters, precedence is given to GETFILE( ); therefore, issuing GETF( ) displays the Open dialog box.

Example

The following example illustrates different types of return values you can get from the GETFONT( ) function.
Copy Code
* Invoke the dialog with script drop-down list disabled:
? GETFONT("Arial",12,"B") && press OK in the dialog box
* return value is the string:
* "Arial,12,B"

* Enable the script drop-down list, Western script selected:
? GETFONT("Arial",12,"B",0) && press OK after selections
* sample return value is the string:
* "Verdana,16,N,161"

* Return from the dialog box without making a selection:
? GETFONT("Arial",12,"B") && press Cancel in the dialog box
* return value is an empty string
? GETFONT("Arial",12,"B",0) && press Cancel in the dialog box
* return value is still an empty string

See Also

Other Resources

FONTMETRIC( ) Function
SYSMETRIC( ) Function
TXTWIDTH( ) Function
WFONT( ) Function
Functions
Language Reference


GETINTERFACE( ) Function

Visual FoxPro 9.0 Language Reference
GETINTERFACE( ) Function
See Also Example

Provides access to COM object properties, methods, and events through early binding.

GETINTERFACE(oObject [, cIID | cInterface[, cTypelib | cProgID]])

Parameters

oObject

Specifies the target COM object.
cIID

Specifies the GUID of the target interface of oObject. cIID can be an interface such as "IContextState" or it can be a GUID, such as "{94631BEC-EE81-479A-AE64-A6CFC37B4799}". If it's "IDispatch", then GetInterface() returns an IDispatch (late-bound) reference to the object. If cIID is not specified, then GetInterface() will return the early binding interface for the object.
cInterface

Specifies the interface name.
cTypelib

Specifies the name of the type library containing the oObject class.
cProgID

Specifies the name of the program to be used to lookup the type library.

Returns

COM Object Interface reference

Remarks

GetInterface( ) applies only to COM objects. If you use native Visual FoxPro objects, GetInterface( ) generates an error. GetInterface( ) returns an early-bound Object reference.

When a DLL is built on a Windows 95, Windows 98, or Windows Me platform, Visual FoxPro does not include the type library inside the DLL. When you use GETINTERFACE( ) and refer to a DLL built on one of these platforms, you must use the Type Library name instead of the DLL name as in the following code:

Copy Code
oX = GETINTERFACE(x, "Imyclass", "myclass1.TLB")

You can use the following code for a DLL built on Windows XP, Windows 2000, or Windows NT:

Copy Code
oX = GETINTERFACE(x, "Imyclass", "myclass1.DLL")

Example

The following code example provides a method you can use in your Visual FoxPro COM server to handle transactions in a COM+ application. This sample requires that you add the COM server containing this code to a COM+ application before a client calls it.
Copy Code
LOCAL oMTX, oContext, oContextState
LOCAL lTxnState, lGetTxnState, lDone, lGetDone
lGetDone = .F.     && initialize setting
lGetTxnState = 0  && initialize setting

oMTX = CREATEOBJECT("MTXAS.APPSERVER.1")
oContext = oMTX.GetObjectContext()
oContextState = GetInterface(oContext,"IContextState")

* Handle activation setting (Doneness)
* Values: .T. - Deactivate, .F. - Leave activated
lDone = .T.
oContextState.SetDeactivateOnReturn(lDone)
oContextState.GetDeactivateOnReturn(@lGetDone)

* Handle transaction setting (Consistency)
* Values: 0 - commit, 1 - abort
lTxnState = 1
oContextState.SetMyTransactionVote(lTxnState)
oContextState.GetMyTransactionVote(@lGetTxnState)

See Also

Other Resources

CREATEOBJECTEX( ) Function
Early (vtable) and Late (IDispatch) Binding
GETOBJECT( ) Function
SYS(2333) - ActiveX Dual Interface Support
How to: View Type Library Information
Functions
Language Reference


GETNEXTMODIFIED( ) Function

Visual FoxPro 9.0 Language Reference
GETNEXTMODIFIED( ) Function
See Also Example

Returns the record number for the next modified record in a buffered table or cursor.

GETNEXTMODIFIED(nRecordNumber [, cTableAlias | nWorkArea] [, lNoFire])

Parameters

nRecordNumber

Specifies the record number after which GETNEXTMODIFIED( ) searches for the next modified record. Specify 0 for nRecordNumber to determine the first record in the table or cursor that has been modified.
cTableAlias

Specifies the alias of the table or cursor for which GETNEXTMODIFIED( ) returns the number of the next modified record.
nWorkArea

Specifies the work area of the table or cursor for which GETNEXTMODIFIED( ) returns the number of the next modified record. If you do not specify an alias or work area, GETNEXTMODIFIED( ) returns the record number for the next modified record in the currently selected table or cursor.
lNoFire

Specifies that all firing of rules are suppressed.

Return Value

Numeric

Remarks

GETNEXTMODIFIED( ) returns 0 if there are no modified records after the record you specify. Because of this, if you modify only one record, to verify its modification you must first use the GO TOP command to position the cursor before the changed record. A record is considered modified if the contents of any of its fields are changed in any way (even if the original field contents are restored) or the record's deletion status is changed.

GETNEXTMODIFIED( ) can operate only on tables and cursors for which table buffering is enabled. Table buffering is enabled with CURSORSETPROP( ).

Since triggers are unaffected by GETNEXTMODIFIED( ), lNoFire suppresses only field and record rules, and the "Uniqueness of index ID is violated" error. lNoFire prevents the flushing of temporary data, such as data stored in controls or updates made to the current record, to the underlying cursor.

Example

The following code example uses the GETNEXTMODIFIED( ) Function to examine changes to records in a buffered table. Typically, changes are made through user interaction with a form. For the purposes of this example, the data is updated using the SQL UPDATE command. As preparation to demonstrate the GetNextModified method, the example code opens a table in the sample database, sets optimistic row buffering, and the updates the table.

The GetNextModified( ) function is called with 0 as the parameter to get the record number of the first record updated in the buffer. A loop processes the updated records based on the the value of MaxOrdAmt. Changes are discarded if the value of MaxOrdAmt is greater than 8500. GetNextModified( ) is called again, this time with the current record number, to get the next modified record in the buffer. If GetNextModified( ) returns 0, there are no more modified records to process and the loop ends. TableRevert(.t.) is called to discard all changes and restore the sample data to it's original state.
Copy Code
LOCAL lnCurRec
CLEAR
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE Customer

* Enable table buffering.
SET MULTILOCKS ON
=CURSORSETPROP("Buffering", 5, "customer")

* Increase MAXORDAMT by 10% for customers in Mexico.
UPDATE Customer SET MaxOrdAmt=MaxOrdAmt * 1.1 WHERE Country = "Mexico"

* Start with the first modified record.
lnCurRec = GETNEXTMODIFIED(0)

* DO until all modified records are processed.
DO WHILE .T.

   * Move to the current modified record.
   GOTO (m.lnCurRec)

   * Process modified row here.
   ? Customer.Company, Customer.MaxOrdAmt
   IF Customer.MaxOrdAmt > 8500
      =TABLEREVERT(.F.)
   ENDIF
   ?? Customer.MaxOrdAmt

   * Get the next modified record from here.
   lnCurRec = GETNEXTMODIFIED(m.lnCurRec)

   IF m.lnCurRec = 0 && No more modified records.
      EXIT
   ENDIF

ENDDO

=TABLEREVERT(.T.)  && Restore sample data and discard all changes.

See Also

Reference

SETFLDSTATE( ) Function
TABLEUPDATE( ) Function
TABLEREVERT( ) Function

Other Resources

CURSORSETPROP( ) Function
CURVAL( ) Function
GETFLDSTATE( ) Function
OLDVAL( ) Function
Functions
Language Reference


GETOBJECT( ) Function

Visual FoxPro 9.0 Language Reference
GETOBJECT( ) Function
See Also Example

Activates an Automation object and creates a reference to the object.

GETOBJECT(cFileName | Moniker [, cClassName])

Parameters

cFileName

Specifies the full path and name of the file to activate. The application does not need to be specified, because the OLE dynamic link libraries determine the application to start based on the file name you provide. For example, the following code launches Microsoft Excel, opens a file named BUDGET.XLS, and creates a reference through an object variable named MBUDVAR:
Copy Code
MBUDVAR = GETOBJECT('C:\EXCEL\WORK\BUDGET.XLS')
Moniker

The identifier of a COM object that implements the IMoniker interface. A moniker can be any of the following types: file, item, generic composite, anti-, pointer, and URL. For details about COM monikers, search for "IMoniker" on the Microsoft Developer Network.
cClassName

Specifies the class name of the object to retrieve. Some applications can store more than one object type in the same file, making it possible for you to use the class name to specify the object to activate. For example, if a word processing application stores its documents, macro definitions, and ToolBar objects in the same file, you can create a reference to the document file with the following command:
Copy Code
MDOCFILE = GETOBJECT('C:\WRDPROC\MYDOC.DOC','WrdProc.Document')
With some server applications, each time you issue GETOBJECT( ), an additional instance of the application is started, using additional memory. If the application is already running, you can prevent additional instances of the application from starting by omitting FileName and including ClassName, as in this example:
Copy Code
oleApp = GETOBJECT(, "Excel.Application")

Returns

Object reference

Remarks

Use GETOBJECT( ) to activate an Automation object from a file and to assign a reference to the object through a memory variable or array element.

If you specify an invalid file or class name, an OLE error is displayed, and the GETOBJECT( ) function returns an empty string.

Example

For example, on a network that has implemented Active Directory Services, you can query the network for information on a particular user.
Copy Code
   *  Replace "DomainName" with the domain name, and "UserLoginID"
   *  with the login ID of the user you are looking up.
   oUser = GetObject("WinNT://DomainName/UserLoginID,user")
   ? oUser.FullName

See Also

Other Resources

COMCLASSINFO( ) Function
CREATEOBJECT( ) Function
DEFINE CLASS Command
SET OLEOBJECT Command
GETINTERFACE( ) Function
Functions
Language Reference


GETPAD( ) Function

Visual FoxPro 9.0 Language Reference
GETPAD( ) Function
See Also Example

Returns the menu title for a given position on the menu bar.

GETPAD(cMenuBarName, nMenuBarPosition)

Parameters

cMenuBarName

Specifies the menu bar name.
nMenuBarPosition

Specifies a position on the menu bar. nMenuPosition can range from 1 (the leftmost menu title on the menu bar) through the number of menu titles on the menu bar.

Return Value

Character

Remarks

Menu names on a titles bar can be added, removed, or rearranged. Use DEFINE PAD to add a menu name to a title bar or RELEASE PAD to remove a menu title.

Example

The following program uses GETPAD( ) to test if the Edit menu name is on the Visual FoxPro system menu bar. If it is, GETPAD( ) returns the menu name. (To restore the Edit menu bar to its default state, issue the command SET SYSMENU TO DEFAULT.)
Copy Code
FOR gnCount = 1 TO CNTPAD('_msysmenu')      && Number of pads
   IF PRMPAD('_msysmenu', GETPAD('_msysmenu', gnCount)) = 'Edit'
      RELEASE PAD (GETPAD('_msysmenu', gnCount)) OF _msysmenu
      EXIT
   ENDIF
ENDFOR

See Also

Other Resources

DEFINE MENU Command
DEFINE PAD Command
RELEASE PAD Command
Functions
Language Reference


GETPEM( ) Function

Visual FoxPro 9.0 Language Reference
GETPEM( ) Function
See Also

Returns the current value for a property or program code for an event or method at design time.

GETPEM(oObjectName | cClassName, cProperty | cEvent | cMethod)

Parameters

oObjectName

Specifies the object for which a property value or event or method program code is returned. oObjectName can be any expression that evaluates to an object, such as an object reference, an object memory variable, or an object array element.
cClassName

Specifies the class for which a property value or event or method program code is returned.
cProperty

Specifies the property whose value is returned.
cEvent

Specifies the event for which program code is returned.
cMethod

Specifies the method for which program code is returned.

Return Value

Character, Currency, Date, DateTime, Numeric, or Logical

Remarks

In Visual FoxPro 6.0 and later, using GETPEM( ) to return method code is supported only during an interactive Visual FoxPro session. You can, however, obtain method code from an object by using its Class property, as in the following code:

Copy Code
LOCAL oObject, lcCode
oObject = NEWOBJECT("_form", HOME()+"ffc\_base.vcx")
lcCode = GETPEM(oObject.class, "Release")

See Also

Other Resources

CREATE FORM Command
PEMSTATUS( ) Function
SYS(1269) – Property Information
SYS(1270) – Object Location
SYS(1271) - Object's .SCX File
SYS(1272) – Object Hierarchy
Functions
Language Reference


GETPICT( ) Function

Visual FoxPro 9.0 Language Reference
GETPICT( ) Function
See Also

Displays the Open Picture dialog box and returns the name of the picture file you chose.

Note:
You can preview images in Windows 2000 and later by clicking the View Menu icon and then Thumbnails. Visual FoxPro uses the Thumbnails view as the default setting to provide mini-previews of images. Therefore, the Open Picture dialog box no longer includes a frame for displaying an image. The Preview check box appears in the Open Picture dialog box only when running Visual FoxPro on operating systems earlier than Windows 2000.

GETPICT([cFileExtensions] [, cFileNameCaption] [, cOpenButtonCaption])

Parameters

cFileExtensions

Specifies the file extensions of the picture files displayed in the scrollable list when the All Files menu item isn't chosen. cFileExtensions can take the following forms:
  • If cFileExtensions contains a single extension (for example, .bmp), only files with that extension are displayed.

  • cFileExtensions can also contain wildcards (* and ?). All files with extensions that meet the wildcard criteria are displayed. For example, if cFileExtensions is ?X?, all files with the extension .fxp, .exe, and .txt are displayed.

  • If cFileExtensions contains an empty string (""), all available graphics files (for example, files with the extensions .bmp and .dib ) are displayed.

CFileNameCaption

Specifies the caption displayed to the left of the File Name text box. cFileNameCaption replaces "File Name" that appears when cFileNameCaption is omitted.
cOpenButtonCaption

Specifies a caption for the OK button.

Return Value

Character data type. Returns the name of the picture file you chose.

Remarks

The GETPICT( ) function returns the empty string if you exit the Open Picture dialog box by pressing ESC, choosing the Cancel button, or clicking the Close button. The Open Picture dialog box displayed by typing GETPICT( ) in the Command window makes it possible for you to quickly locate all the graphic files supported in Visual FoxPro. In versions earlier than Visual FoxPro 8.0, check the Preview check box in the Picture Open dialog box to display the currently selected graphics file.

The following table lists the graphic file formats that Visual FoxPro supports.

Graphic format | File extension
Animated Cursor | .ani
Bitmap | .bmp
Cursor | .cur
Device Independent Bitmap | .dib
Exchangeable Image File | .exif
Graphics Interchange Format | .gif, .gfa
Joint Photographic Electronic Group, JPEG File Interchange Format | .jpg, .jpeg, .jpe, .jfif
Icon | .ico
Portable Networks Graphics | .png
Tag Image File Format | .tif, .tiff
Windows Enhanced Metafile | .emf
Note:
In Visual FoxPro, cursor, animated cursor, and icon files can be used as graphics files. For example, you can specify an animated cursor file for the Picture property for the Image control (however, the Image control displays the static representation of the cursor).

Use the CLEAR RESOURCES command to clear all cached graphic files, including .gif and .jpg files.

See Also

Other Resources

GETFILE( ) Function
GETEXPR Command
LOCFILE( ) Function
PUTFILE( ) Function
Functions
Language Reference


GETPRINTER( ) Function

Visual FoxPro 9.0 Language Reference
GETPRINTER( ) Function
See Also Example

Displays the Printer dialog box and returns the name of the selected printer.

GETPRINTER( )

Return Value

Character. GETPRINTER( ) returns the name of the selected printer. If you exit the Printer dialog box by pressing ESC or by clicking Cancel or Close, GETPRINTER( ) returns an empty string.

Remarks

The contents of the Printer dialog box can differ between versions of Windows. For example, the Printer dialog box might contain only the printer name or include a network path.

Example

The following example clears the main Visual FoxPro window using the CLEAR command. The variable cPrinter stores the return value of GETPRINTER( ), which displays the Printer dialog box, and the WAIT WINDOW command displays the name of the selected printer or "No printer chosen" if no printer was chosen.
Copy Code
CLEAR
cPrinter = GETPRINTER( )
WAIT WINDOW IIF(EMPTY(cPrinter), 'No printer chosen', cPrinter)

See Also

Other Resources

APRINTERS( ) Function
SET PRINTER Command
SYS(102) - Printer Setting
SYS(1037) - Page Setup Dialog Box
Functions
Language Reference


GETRESULTSET( ) Function

Visual FoxPro 9.0 Language Reference
GETRESULTSET( ) Function
See Also

Retrieves the work area number of a cursor marked by SETRESULTSET( ) in the current data session.

GETRESULTSET( )

Return Value

Numeric. GETRESULTSET( ) returns the work area number of the marked cursor in the current data session or zero (0) if no cursor is marked in the current data session.

Remarks

GETRESULTSET( ) is supported in Visual FoxPro and the Visual FoxPro OLE DB Provider. You can use GETRESULTSET( ) in a database container (DBC) stored procedure or send it to the Visual FoxPro OLE DB Provider, assuming that the cursor has been previously opened by the OLE DB Provider.

See Also

Other Resources

SETRESULTSET( ) Function
CLEARRESULTSET( ) Function
How to: Use Data Sessions
Supported Visual FoxPro Commands and Functions in OLE DB Provider
Functions


GETWORDCOUNT( ) Function

Visual FoxPro 9.0 Language Reference
GETWORDCOUNT( ) Function
See Also

Counts the words in a string.

GetWordCount(cString[, cDelimiters])

Parameters

cString

Specifies the string whose words will be counted.
cDelimiters

Optional. Specifies one or more optional characters used to separate words in cString. The default delimiters are space, tab, carriage return, and line feed. Note that GetWordCount( ) uses each of the characters in cDelimiters as individual delimiters, not the entire string as a single delimiter.

Return Value

Numeric

Remarks

GetWordCount( ) by default assumes that words are delimited by spaces or tabs. If you specify another character as delimiter, this function ignores spaces and tabs and uses only the specified character.

If you use "AAA aaa, BBB bbb, CCC ccc." as the target string for GetWordCount( ), you can get all the following results.

Copy Code
cString = "AAA aaa, BBB bbb, CCC ccc."
? GetWordCount(cString)               && 6 - character groups, delimited by " "
? GetWordCount(cString, ",")               && 3 - character groups, delimited by ","
? GetWordCount(cString, ".")               && 1 - character group, delimited by "."

See Also

Other Resources

GETWORDNUM( ) Function
Functions
Language Reference


GETWORDNUM( ) Function

Visual FoxPro 9.0 Language Reference
GETWORDNUM( ) Function
See Also

Returns a specified word from a string.

GETWORDNUM(cString, nIndex[, cDelimiters])

Parameters

cString

Specifies the string to be evaluated
nIndex

Specifies the index position of the word to be returned. For example, if nIndex is 3, GetWordNum( ) returns the third word (if cString contains three or more words).
cDelimiters

Optional. Specifies one or more optional characters used to separate words in cString. The default delimiters are space, tab, carriage return, and line feed. Note that GetWordNum( ) uses each of the characters in cDelimiters as individual delimiters, not the entire string as a single delimiter.

Return Value

Character

Remarks

Returns the word at the position specified by nIndex in the target string, cString. If cString contains fewer than nIndex words, GetWordNum( ) returns an empty string.

See Also

Other Resources

GETWORDCOUNT( ) Function
Functions
Language Reference


GOMONTH( ) Function

Visual FoxPro 9.0 Language Reference
GOMONTH( ) Function
See Also Example

Returns the date that is a specified number of months before or after a given Date or Date/Time expression.

GOMONTH(dExpression | tExpression, nNumberOfMonths)

Parameters

dExpression

Specifies a date expression for which GOMONTH( ) returns the date.
tExpression

Specifies a date/time expression for which GOMONTH( ) returns the date.
nNumberOfMonths

Specifies the number of months from the date or date/time. If nNumberOfMonths is positive, GOMONTH( ) returns a date that is nNumberOfMonths months after the date or date/time. If nNumberOfMonths is negative, GOMONTH( ) returns a date that is nNumberOfMonths months before the date or date/time. For example, -1 means -31 days.

Return Value

Date

Remarks

GOMONTH( ) does not support dates earlier than 1753.

Example

Copy Code
SET CENTURY ON
STORE GOMONTH({^1998-02-16}, 5) TO gdDeadLine

CLEAR
? gdDeadLine  && Displays 07/16/1998
? GOMONTH({^1998-12-31}, 2)  && Displays 02/28/1999
? GOMONTH({^1998-12-31}, -2)  && Displays 10/31/1998

See Also

Other Resources

CMONTH( ) Function
BuildDateTime Property
DATETIME( ) Function
Functions
Language Reference


HEADER( ) Function

Visual FoxPro 9.0 Language Reference
HEADER( ) Function
See Also

Returns the number of bytes in the header of the current or specified table file.

HEADER([nWorkArea | cTableAlias])

Parameters

nWorkArea| cTableAlias

Returns the header size for a table open in another work area. nWorkArea specifies the work area number and cTableAlias specifies the table alias. If you omit the work area and alias, HEADER( ) returns the size of the header for the table open in the current work area. HEADER( ) returns 0 if a table isn't open in the work area you specify. If a table doesn't have the alias you specify, Visual FoxPro displays an error message.

Return Value

Numeric

Remarks

A table header contains information about the table itself, such as the field names and sizes and the presence of a memo file or structural index.

See Also

Other Resources

FSIZE( ) Function
RECSIZE( ) Function
HeaderHeight Property
How to: Create and Use Table Aliases
Functions
Language Reference


HOME( ) Function

Visual FoxPro 9.0 Language Reference
HOME( ) Function
See Also Example

Returns the names of the Visual FoxPro and Visual Studio directories.

HOME([nLocation])

Parameters

nLocation

Specifies that HOME( ) returns the name of a specific Visual FoxPro or Visual Studio directory. Omitting nLocation is identical to HOME(0). The following table lists the values for nLocation and the directory that HOME( ) returns. The directories listed below assume that you chose the default installation directory when you installed Visual FoxPro or Visual Studio.

nLocation Directory

0 or omitted

The directory from which Visual FoxPro was started

1

The directory in which Visual FoxPro is installed

2

The directory containing the Visual FoxPro samples. This directory is identical to the samples directory in the _SAMPLES system variable.

3

Visual Studio Common directory

4

Visual FoxPro Graphics directory

5

Visual Studio MSDN directory

6

Visual Studio Tools directory

7

Visual FoxPro subdirectory in the user's Visual FoxPro Application Data directory

8

Visual FoxPro Projects subdirectory in the user's Visual FoxPro My Documents directory. This directory is the default location for new projects and files created by Visual FoxPro.

Return Value

Character data type. HOME( ) returns the names of specific Visual FoxPro and Visual Studio directories.

Example

Copy Code
CLEAR
? 'Visual FoxPro startup directory:           ', HOME( )
? 'Visual FoxPro installation directory:      ', HOME(1)
? 'Visual FoxPro samples directory:           ', HOME(2)
? 'Visual Studio common directory:            ', HOME(3)
? 'Visual FoxPro graphics directory:          ', HOME(4)
? 'MSDN samples directory:                    ', HOME(5)
? 'Visual Studio tools directory:             ', HOME(6)
? 'Visual FoxPro user app data subdirectory:  ', HOME(7)
? 'Visual FoxPro user documents subdirectory: ', HOME(8)

See Also

Other Resources

_SAMPLES System Variable
SYS( ) Functions Overview
SYS(2004) - Visual FoxPro Start Directory
Functions
Language Reference


HOUR( ) Function

Visual FoxPro 9.0 Language Reference
HOUR( ) Function
See Also Example

Returns the hour portion from a DateTime expression.

HOUR(tExpression)

Parameters

tExpression

Specifies a DateTime expression from which HOUR( ) returns the hour.

Return Value

Numeric

Remarks

HOUR( ) returns a numeric value based on a 24 hour format, and is not affected by the current setting of SET HOURS. For example, if SET HOURS is 12 or 24, the following command returns 13:

Copy Code
? HOUR({^1998-02-16 1:00p})

Example

The following example displays the hour portion of the current time and the hour portion of a specific time.
Copy Code
CLEAR
? HOUR(DATETIME( ))
? HOUR({^1998-02-16 10:42a})  && Displays 10

See Also

Other Resources

CTOT( ) Function
DATE( ) Function
DATETIME( ) Function
DTOT( ) Function
MINUTE( ) Function
SEC( ) Function
SECONDS( ) Function
SET SECONDS Command
TIME( ) Function
Functions
Language Reference


ICASE( ) Function

Visual FoxPro 9.0 Language Reference
ICASE( ) Function
See Also Example

Evaluates the results from a list of conditions.

ICASE( lCondition1, eResult1 [, lCondition2, eResult2] ...
   [, eOtherwiseResult])

Parameters

lCondition

Specifies a condition as a logical expression to evaluate. If lCondition evaluates to False (.F.), ICASE( ) continues to evaluate the next condition and returns the corresponding eResult for that condition if it evaluates to True (.T.). If lCondition evaluates to null (.NULL.), Visual FoxPro treats lCondition as if it evaluated to False (.F.).
eResult

Specifies a result to return if lCondition evaluates to True (.T.).
eOtherwiseResult

Contains the result returned if all conditions evaluate to False (.F.).

Return Value

ICASE( ) returns the first eResult as soon as lCondition evaluates to True (.T.).

If all conditions evaluate to False (.F.), ICASE( ) returns eOtherwiseResult.

If eOtherwiseResult is omitted, and all conditions evaluate to False (.F.), ICASE( ) returns null (.NULL.).

Remarks

You must always pass a set of two parameters to ICASE( ). If you pass an odd number of parameters, the last parameter is treated as the return value for eOtherwiseResult.

You can pass up to 100 pairs of parameters for ICASE( ).

If you use a long ICASE( ) expression in a filter expression, such as in a FOR or WHERE clause, make sure that SYS(3055) is set to an appropriate complexity level to avoid generating an error. For more information, see SYS(3055) - FOR and WHERE Clause Complexity.

Example

The following example demonstrates different scenarios using ICASE( ) to evaluate expressions and returning certain values based on the results of those expressions.

The following line of code displays "First is true" because the first expression evaluates to True (.T.).

Copy Code
? ICASE(1+1=2,"First is true",1+1=3,"Second is false","None are true")

The following line of code displays "Second is true" because the first expression evaluates to False (.F.), but the second expression evaluates to True (.T.).

Copy Code
? ICASE(1+2=2,"First is false",1+2=3,"Second is true","None are true")

The following line of code displays "None are true", which is the last result specified, because the first and second expressions evaluate to False (.F.).

Copy Code
? ICASE(1+2=2,"First is false",1+1=3,"Second is false","None are true")

See Also

Other Resources

IIF( ) Function
EVALUATE( ) Function
EVL( ) Function
Functions


ID( ) Function - Network Machine Information

Visual FoxPro 9.0 Language Reference
ID( ) Function - Network Machine Information
See Also

ID( ) returns network machine information when using Visual FoxPro in a network environment. The same functionality is available by using SYS(0).

ID( )

Return Value

Character

Remarks

Computer information must first be assigned by the network software and the network shell must be loaded.

If computer information has not been assigned or the network shell hasn't been loaded, ID( ) returns a character string consisting of 15 spaces, a number sign (#) followed by another space, and then 0. Consult your network documentation for further information on defining machine information.

ID( ) returns 1 when using Visual FoxPro in a stand-alone environment.

When the computer is connected to a network, ID( ) returns the computer name, a space, a number sign (#) followed by another space, and then the id of the current user (or the security context in which Visual FoxPro is running). For example:

Copy Code
? ID( )

returns the following format:

Copy Code
MACHINEID # userid

See Also

Other Resources

SYS(0) - Network Machine Information
Functions
Language Reference


IDXCOLLATE( ) Function

Visual FoxPro 9.0 Language Reference
IDXCOLLATE( ) Function
See Also Example

Returns the collating sequence for an index or index tag.

IDXCOLLATE([cCDXFileName,] nIndexNumber [, nWorkArea | cTableAlias])

Parameters

cCDXFileName

Specifies the name of the compound index file. The compound index file you specify can be the structural compound index file automatically opened with the table or an independent compound index file.
nIndexNumber

Specifies the index or index tag for which IDXCOLLATE( ) returns the collating sequence. IDXCOLLATE( ) returns the collating sequence for indexes and index tags in the following order as nIndexNumber increases from 1 to the total number of open index files and index tags:
  1. Collating sequences for single-entry .idx index files (if any are open) are returned first. The order in which the single-entry index files are included in USE or SET INDEX determines how the collating sequences are returned.

  2. Collation sequences for tags in the structural compound index (if one is present) are returned next. The collating sequences are returned for the tags in the order in which the tags are created in the structural compound index.

  3. Collating sequences for tags in any open independent compound indexes are returned last. The collation sequences are returned for the tags in the order in which the tags are created in the independent compound indexes.

The empty string is returned if nIndexNumber is greater than the total number of open single-entry .idx files and structural compound and independent compound index tags.
nWorkArea

Specifies the work area of the table for which IDXCOLLATE( ) returns index file and index tag collating sequences. IDXCOLLATE( ) returns the empty string if a table isn't open in the work area you specify.
cTableAlias

Specifies the alias of the table for which IDXCOLLATE( ) returns index file and index tag collation sequences. Visual FoxPro generates an error message if you specify a table alias that doesn't exist.

Return Value

Character

Remarks

IDXCOLLATE( ) can be used to return the collating sequence for each tag in multiple-entry compound index files, allowing you to completely delete an index file and rebuild it correctly, using a series of SET COLLATE and INDEX commands.

Note that IDXCOLLATE( ) is not required for the proper functioning of REINDEX, because the collation sequence information is present in existing indexes and index tags.

For additional information about Visual FoxPro's international support, see Developing International Applications.

Example

The following example opens the Customer table in the testdata database. FOR ... ENDFOR is used to create a loop in which IDXCOLLATE( ) is used to display the collation sequence of each index tag in the Customer structural index. The name of each structural index tag is displayed with its collation sequence.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer     && Open Customer table.
CLEAR

FOR nCount = 1 TO TAGCOUNT( )
   IF !EMPTY(TAG(nCount))  && Checks for tags in the index.
   ? TAG(nCount) + ' '  && Display tag name.
   ?? IDXCOLLATE(nCount)  && Display collation sequence.
   ELSE
      EXIT  && Exit the loop when no more tags are found.
   ENDIF
ENDFOR

See Also

Other Resources

SET COLLATE Command
Developing International Applications
CREATE TABLE - SQL Command
CREATE CURSOR - SQL Command
ALTER TABLE - SQL Command
INDEX Command
Functions
Language Reference


IIF( ) Function

Visual FoxPro 9.0 Language Reference
IIF( ) Function
See Also Example

Returns one of two values depending on the value of a logical expression.

IIF(lExpression, eExpression1, eExpression2)

Parameters

lExpression

Specifies the logical expression that IIF( ) evaluates.
eExpression1, eExpression2

If lExpression evaluates to True (.T.), eExpression1 is returned and eExpression2 is not evaluated. If lExpression evaluates to False (.F.) or null (.NULL.), eExpression2 is returned and eExpression1 is not evaluated.

Return Value

Character, Numeric, Currency, Date, or DateTime

Remarks

This function, also known as Immediate IF, evaluates a logical expression and then returns one of two expressions. If the logical expression evaluates to True (.T.), IIF( ) returns the first expression. If the logical expression evaluates to False (.F.) or null (.NULL.), IIF( ) returns the second expression.

Tip:
This function can be used in place of IF ... ENDIF for simple conditional expressions, and is especially useful in report and label expressions that conditionally specify field contents. The IIF( ) function also executes faster than an equivalent IF ... ENDIF.

Example

The following example uses IIF( ) to check if the notes field in the employee table is empty. If it is empty, "No description" is displayed; otherwise, the contents of the memo field are displayed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE employee  && Open Employee table
CLEAR

SCAN
   ? IIF(EMPTY(notes), 'No notes', notes)    && Empty memo field?
ENDSCAN

See Also

Other Resources

IF ... ENDIF Command
#IF ... #ENDIF Preprocessor Directive
IF Statements
Functions
Language Reference


IMESTATUS( ) Function

Visual FoxPro 9.0 Language Reference
IMESTATUS( ) Function
See Also

Turns the IME (Input Method Editor) window on or off or returns the current IME status.

IMESTATUS([nExpression])

Parameters

nExpression

Turns the IME window on or off. The following table lists the values for nExpression and the corresponding state of the IME window.

nExpression IME window action

0

Turns the IME window off.

1

Turns the IME window on.
If nExpression is omitted, IMESTATUS( ) returns the current IME status. The following table lists the values returned for the IME status. Use VERSION(3) to determine the current locale. The following table lists the values returned for the IME status in the Japanese locale.

Return value IME status

0

No IME installed

1

IME on

2

IME off

3

IME disabled

4

Hiragana mode (double-byte)

5

Katakana mode (double-byte)

6

Katakana mode (single-byte)

7

Alphanumeric mode (double-byte)

8

Alphanumeric mode (single-byte)
The following table lists the values returned for the IME status in the Korean locale.

Return value IME status

0

No IME installed

1

Hangul mode (single-btye)

2

English mode (single-btye)

11

English mode (double-btye)

15

Hangul mode (double-btye)

23

Hanja conversion mode (Hangul + single-btye mode)

31

Hanja conversion mode (Hangul + double-btye mode)

Return Value

Numeric

Remarks

For more information, see Developing International Applications.

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

How to: Enter International Data
SET BROWSEIME Command
IMEMode Property
ISLEADBYTE( ) Function
STRCONV( ) Function
Functions
Language Reference


INDBC( ) Function

Visual FoxPro 9.0 Language Reference
INDBC( ) Function
See Also Example

Returns true (.T.) if the specified database object is in the current database; otherwise returns false (.F.).

INDBC(cDatabaseObjectName, cType)

Parameters

cDatabaseObjectName

Specifies the name of a named connection, field, index, table, or SQL view for which INDBC( ) returns a logical value indicating whether or not the object is in the current database.
cType

Specifies the database object type of cDatabaseObjectName. The following table lists the values for cType and the corresponding database object type.

cType Database object type

CONNECTION

Named connection

FIELD

Field

INDEX

Index

TABLE

Table

VIEW

SQL View
The CONNECTION, FIELD, INDEX, TABLE, and VIEW settings cannot be abbreviated.

Return Value

Logical

Remarks

A database must be open and current when INDBC( ) is issued; otherwise Visual FoxPro generates an error message.

Example

In the following example, a temporary database named mydbc is created, and a temporary table named mytable is added to the database. INDBC( ) is used to determine if the new table is in the database. The database and table are closed and erased.
Copy Code
CLOSE DATABASES
CREATE DATABASE mydbc  && Creates a new database
CREATE TABLE mytable (field1 C(10)) && Automatically added to database

? 'MyTable in the database? '
?? INDBC('mytable', 'TABLE')  && Returns .T.

CLOSE DATABASES
DELETE DATABASE mydbc DELETETABLES

See Also

Other Resources

ADBOBJECTS( ) Function
CREATE DATABASE Command
DELETE DATABASE Command
OPEN DATABASE Command
SET DATABASE Command
Functions
Language Reference


INDEXSEEK( ) Function

Visual FoxPro 9.0 Language Reference
INDEXSEEK( ) Function
See Also

Without moving the record pointer, searches an indexed table for the first occurrence of a record whose index key matches a specified expression.

INDEXSEEK(eExpression [, lMovePointer [, nWorkArea | cTableAlias
   [, nIndexNumber | cIDXIndexFileName | cTagName]]])

Parameters

eExpression

Specifies the index key expression for which you want INDEXSEEK( ) to search.
lMovePointer

Specifies if the record pointer is moved to the matching record. If lMovePointer is true (.T.) and a matching record exists, the record pointer is moved to the matching record. If lMovePointer is true (.T.) and a matching record doesn't exist, the record pointer isn't moved. If lMovePointer is false (.F.) or is omitted, the record pointer isn't moved even if a matching record exists.
nWorkArea

Specifies the work area number of the table that is searched for the index key.
cTableAlias

Specifies the alias of the table that is searched. If you omit nWorkArea and cTableAlias, the table in the currently selected work area is searched.
nIndexNumber

Specifies the number of the index file or tag that is used to search for the index key. nIndexNumber refers to the index files as they are listed in USE or SET INDEX. Open .IDX files are numbered first in the order in which they appear in USE or SET INDEX. Tags in the structural .cdx file (if one exists) are then numbered in the order in which they were created. Finally, tags in any open independent .cdx files are numbered in the order in which they were created. For more information about index numbering, see SET ORDER.
cIDXIndexFileName

Specifies an .idx file that is used to search for the index key.
cTagName

Specifies a tag of a .cdx file that is used to search for the index key. The tag name can be from a structural .cdx file or any open independent .cdx file.
Note:
The .idx file takes precedence if duplicate .idx file and tag names exist.

Return Value

Logical

Remarks

INDEXSEEK( ) returns true (.T.) if a match is found; otherwise false (.F.) is returned. You can use INDEXSEEK( ) only with a table with an index order set, and you can search only for an index key. The match must be exact unless SET EXACT is set to OFF.

INDEXSEEK( ) provides a fast way to search for records without moving the record pointer. Because the record pointer isn't moved, rules and triggers aren't executed. If INDEXSEEK( ) returns true (.T.) indicating that a matching record is found, you can execute INDEXSEEK( ) again with the second parameter lMovePointer set to true (.T.) to move to the matching record.

INDEXSEEK( ) returns false (.F.) when you are attempting to find a value in the most recently created record (created with INSERT INTO or APPEND BLANK) until the record pointer is moved. You can execute a GO BOTTOM command to cause INDEXSEEK( ) to find the most recently created record.

See Also

Other Resources

Functions
INDEX Command
KEYMATCH( ) Function
LOCATE Command
SEEK Command
SEEK( ) Function


INKEY( ) Function

Visual FoxPro 9.0 Language Reference
INKEY( ) Function
See Also

Returns a number corresponding to the first mouse click or key press in the type-ahead buffer.

INKEY([nSeconds] [, cHideCursor])

Parameters

nSeconds

Specifies the number of seconds to wait for a keystroke. If you do not specify a value for nSeconds, INKEY( ) returns a value for a keystroke immediately. If nSeconds is 0, INKEY( ) waits indefinitely for a keystroke.
cHideCursor

Shows or hides the cursor, or checks for a mouse click. The following table lists values for cHideCursor.

cHideCursor Description

S

Show cursor.

H

Hide cursor.

M

Check for a mouse click.

E

Expand the keyboard macro if a keyboard macro is assigned to a key or key combination. To return successive values for each keystroke in a macro, execute INKEY( ) repeatedly with E included.

Note:
If both S and H are included in cHideCursor, the latter character specified takes precedence. You can combine values for cHideCursor, for example, to check for a mouse click and show the cursor, include M and S. To check for a mouse click and hide the cursor, include H and M. INKEY( ) disregards characters other than S, H, M, and E in cHideCursor.

Return Value

Numeric. INKEY( ) returns 0 if a key has not been pressed. If several keys are present in the type-ahead buffer, INKEY( ) returns the value of the first key entered in the buffer. INKEY( ) also returns the following values according to certain conditions:

  • If M is included for cHideCursor, INKEY( ) returns the value 151.

  • If E is included, INKEY( ) returns a value corresponding to the first keystroke assigned to the keyboard macro. If you omit E, INKEY( ) returns the value for the key or key combination that triggers the keyboard macro.

  • For single keys and key combinations using the SHIFT, CTRL, and ALT keys, the following table lists the return values for INKEY( ). A dash (–) indicates that the key combination returns no value.

    Key Alone SHIFT CTRL ALT

    F1

    28

    84

    94

    104

    F2

    –1

    85

    95

    105

    F3

    –2

    86

    96

    106

    F4

    –3

    87

    97

    107

    F5

    –4

    88

    98

    108

    F6

    –5

    89

    99

    109

    F7

    –6

    90

    100

    110

    F8

    –7

    91

    101

    111

    F9

    –8

    92

    102

    112

    F10

    –9

    93

    103

    113

    F11

    133

    135

    137

    139

    F12

    134

    136

    138

    140

    1

    49

    33

    –

    120

    2

    50

    64

    –

    121

    3

    51

    35

    –

    122

    4

    52

    36

    –

    123

    5

    53

    37

    –

    124

    6

    54

    94

    –

    125

    7

    55

    38

    –

    126

    8

    56

    42

    –

    127

    9

    57

    40

    –

    128

    0

    48

    41

    –

    19

    a

    97

    65

    1

    30

    b

    98

    66

    2

    48

    c

    99

    67

    3

    46

    d

    100

    68

    4

    32

    e

    101

    69

    5

    18

    f

    102

    70

    6

    33

    g

    103

    71

    7

    34

    h

    104

    72

    127

    35

    I

    105

    73

    9

    23

    j

    106

    74

    10

    36

    k

    107

    75

    11

    37

    l

    108

    76

    12

    38

    m

    109

    77

    13

    50

    n

    110

    78

    14

    49

    o

    111

    79

    15

    24

    p

    112

    80

    16

    25

    q

    113

    81

    17

    16

    r

    114

    82

    18

    19

    s

    115

    83

    19

    31

    t

    116

    84

    20

    20

    u

    117

    85

    21

    22

    v

    118

    86

    22

    47

    w

    119

    87

    23

    17

    x

    120

    88

    24

    45

    y

    121

    89

    25

    21

    z

    122

    90

    26

    44

    INS

    22

    22

    146

    162

    HOME

    1

    55

    29

    151

    DEL

    7

    7

    147

    163

    END

    6

    49

    23

    159

    PAGE UP

    18

    57

    31

    153

    PAGE DOWN

    3

    51

    30

    161

    UP ARROW

    5

    56

    141

    152

    DOWN ARROW

    24

    50

    145

    160

    RIGHT ARROW

    4

    54

    2

    157

    LEFT ARROW

    19

    52

    26

    155

    ESC

    27

    –/27

    –*/27

    –*/1

    ENTER

    13

    13

    10

    –/166

    BACKSPACE

    127

    127

    127

    14

    TAB

    9

    15

    148/*

    *

    SPACEBAR

    32

    32

    32/–

    57

    ` or ~

    96

    126

    41

    - or _

    45

    95

    = or +

    61

    43

    13

    [ or {

    91

    123

    27

    26

    ] or }

    93

    125

    29

    27

    \ or |

    92

    124

    28

    43

    ; or :

    59

    58

    39

    ' or "

    39

    34

    40

    , or <

    44

    60

    51

    . or >

    46

    62

    52

    / or ?

    47

    63

    53
    * Keystroke reserved by Windows.

See Also

Other Resources

Functions
_DBLCLICK System Variable
KEYBOARD Command
KeyPress Event
LASTKEY( ) Function
ON KEY LABEL Command
SET TYPEAHEAD Command


INLIST( ) Function

Visual FoxPro 9.0 Language Reference
INLIST( ) Function
See Also Example

Determines whether an expression matches another expression in a set of expressions.

INLIST(eExpression1, eExpression2 [, eExpression3 ...])

Parameters

eExpression1

Specifies the expression INLIST( ) searches for in the set of expressions.
eExpression2[, eExpression3...]

Specifies the set of expressions to search. You must include at least one expression (eExpression2), and can include up to 25 expressions (eExpression2, eExpression3, and so on). All the expressions in the set of expressions must be of the same data type.

Return Value

Logical or null value

Remarks

INLIST( ) returns true (.T.) if it finds the expression in the set of expressions; otherwise INLIST( ) returns false (.F.). The null value is returned if eExpression1 is the null value. The null value is also returned if eExpression1 is not the null value, eExpression1 does not match another expression, and at least one of the other expressions is the null value.

Example

In this example, INLIST( ) determines the quarter of the year for the current month. The current month is stored to the variable gcMonth. Each CASE statement uses INLIST( ) to determine whether the contents of gcMonth can be found in a list of month names. The name of the quarter returned is stored to the variable gcReporTitle.
Copy Code
SET TALK ON
STORE CMONTH(DATE( )) TO gcMonth
DO CASE
   CASE INLIST(gcMonth,'January','February','March')
      STORE 'First Quarter' TO gcReporTitle
   CASE INLIST(gcMonth,'April','May','June')
      STORE 'Second Quarter' TO gcReporTitle
   CASE INLIST(gcMonth,'July','August','September')
      STORE 'Third Quarter' TO gcReporTitle
   OTHERWISE
      STORE 'Fourth Quarter' TO gcReporTitle
ENDCASE
WAIT WINDOW gcReporTitle

See Also

Other Resources

Functions
BETWEEN( ) Function
CASE Statements
DO CASE ... ENDCASE Command
AT( ) Function
ATLINE( ) Function
RAT( ) Function
RATLINE( ) Function
$ Operator
OCCURS( ) Function


INPUTBOX( ) Function

Visual FoxPro 9.0 Language Reference
INPUTBOX( ) Function
See Also

Displays a modal dialog used by a parameterized view for input of a single string.

INPUTBOX(cInputPrompt [, cDialogCaption [, cDefaultValue [, nTimeout [,cTimeoutValue] [,cCancelValue]]]])

Parameters

cInputPrompt

Specifies the Prompt displayed above the text entry box.
cDialogCaption

Specifies the text to display in the title bar of the dialog box.
cDefaultValue

Specifies a default value to display in the text entry box.
nTimeout

Specifies a timeout value in 1/1000 seconds. Specify zero in nTimeout to prevent the dialog from timing out. This is identical to omitting nTimeout.
cTimeoutValue

Specifies value to return if a timeout occurs. cTimeoutValue isn't returned if nTimeout is set to zero or is omitted.
cCancelValue

Specifies a character value to return if the user exits the dialog box by choosing the Cancel button or pressing the Esc key.

Remarks

The dialog box displays an edit box and OK and Cancel buttons. The OK button returns the contents of the edit box. A timeout returns the text specified in cTimeoutValue or an empty string if cTimeoutValue is unspecified. The Cancel button or the Esc key returns the text specified in cCancelValue or an empty string if cCancelValue is unspecified.

Example 1

Code

Copy Code
Y = "Nothing at all"
Y = INPUTBOX("TypeHere","Input ",Y,5000)
         && Displays dialog box for 5 seconds,

Example 2

The following example displays a dialog box for five seconds and displays the return value in the main Visual FoxPro window. If the user clicks OK, the edit box returns the text which is either the default value, "Nothing at all," or user-specified text. If the user clicks Cancel or hits the ESC key, the edit box returns "Canceled." If the user waits the timeout period, the edit box closes and returns "Timed Out."

Code

Copy Code
CLEAR
Y = INPUTBOX("Type Here:", "Input Title",  ;
"Nothing at all", 5000, 'Timed Out', 'Canceled')
? Y

See Also

Other Resources

Functions
Input and Output
INPUT Command
MESSAGEBOX( ) Function


INSMODE( ) Function

Visual FoxPro 9.0 Language Reference
INSMODE( ) Function
See Also Example

Returns the current insert mode, or sets the insert mode on or off.

INSMODE([lExpression])

Parameters

lExpression

Turns the insert mode on or off. INSMODE(.T.) turns the insert mode on and INSMODE(.F.) turns it off. A logical value corresponding to the insert mode setting before INSMODE(.T.) or INSMODE(.F.) was issued is returned.

Remarks

If you omit the optional argument and the insert mode is on (characters are inserted before the cursor), INSMODE( ) returns true (.T.). If the insert mode is off (characters are overwritten at the insertion point), INSMODE( ) returns false (.F.).

Return Value

Logical

Example

The example below uses INSMODE( ) to set the insert mode on, and then toggles the insert mode to the opposite state.
Copy Code
SET TALK ON
=INSMODE(.T.)  && Set insert mode on
? INSMODE( )
= INSMODE(!INSMODE( ))  && Toggle insert mode to opposite state
? INSMODE( )

See Also

Other Resources

Functions
CAPSLOCK( ) Function
NUMLOCK( ) Function
SET TALK Command


INT( ) Function

Visual FoxPro 9.0 Language Reference
INT( ) Function
See Also Example

Evaluates a numeric expression and returns the integer portion of the expression.

INT(nExpression)

Parameters

nExpression

Specifies the numeric expression for which INT( ) returns the integer portion.

Return Value

Numeric

Example

Copy Code
CLEAR
? INT(12.5)  && Displays 12
? INT(6.25 * 2)  && Displays 12
? INT(-12.5)  && Displays -12
STORE -12.5 TO gnNumber
? INT(gnNumber)  && Displays -12

See Also

Other Resources

CEILING( ) Function
FLOOR( ) Function
ROUND( ) Function
Functions
Language Reference


ISALPHA( ) Function

Visual FoxPro 9.0 Language Reference
ISALPHA( ) Function
See Also Example

Determines whether the leftmost character in a character expression is alphabetic.

ISALPHA(cExpression)

Parameters

cExpression

Specifies the character expression that ISALPHA( ) evaluates. Any characters after the first character in cExpression are ignored.

Return Value

Logical

Remarks

ISALPHA( ) returns true (.T.) if the leftmost character in the specified character expression is an alphabetic character; otherwise ISALPHA( ) returns false (.F.).

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer     && Open customer table
CLEAR

DISPLAY contact
? ISALPHA(contact)  && Displays .T.
DISPLAY maxordamt
? ISALPHA(cust_id)  && Displays .F.

See Also

Other Resources

ISLOWER( ) Function
ISUPPER( ) Function
LOWER( ) Function
UPPER( ) Function
Functions
Language Reference


ISBLANK( ) Function

Visual FoxPro 9.0 Language Reference
ISBLANK( ) Function
See Also Example

Determines whether an expression is blank.

ISBLANK(eExpression)

Parameters

eExpression

Specifies the expression for ISBLANK( ) to evaluate. eExpression can be a field in a table, a variable or array element, or an expression.

Return Value

Logical. ISBLANK( ) returns True (.T.) if the expression eExpression is blank; otherwise, ISBLANK( ) returns False (.F.).

ISBLANK( ) returns True (.T.) for fields when those fields contain certain values. The following table lists the values that field types contain for ISBLANK( ) to return True.

Data type | Values the field contains
Blob | Empty (0h) or contains only zero bytes, for example, 0h00, 0h000000, and so on
Character | Empty string, spaces, or no value, such as a newly appended blank record or cleared with BLANK
Date | Blank date ({ / / }) or no value, such as a newly appended blank record or cleared with BLANK
DateTime | Blank datetime ({ / / : : }) or no value, such as a newly appended blank record or cleared with BLANK
Float | No value, such as a newly appended blank record or cleared with BLANK
General | Empty, for example, no OLE object
Logical | No value, such as a newly appended blank record or cleared with BLANK
Memo | Empty, for example, no memo contents
Numeric | No value, such as a newly appended blank record or cleared with BLANK
Varbinary | Empty (0h) or contains only zero bytes, for example, 0h00, 0h000000, and so on
Note:
Expressions with Currency, Integer, or Double type are never blank; therefore, ISBLANK( ) always returns False (.F.) for these expression types.

Remarks

To create a blank record, use the APPEND BLANK and BLANK commands. You can also use BLANK to clear data from fields in a record.

ISBLANK( ) differs from EMPTY( ) and ISNULL( ). For example, EMPTY( ) returns True (.T.) if a character expression evaluates to empty, for example, it contains spaces, tabs, carriage returns, or line feeds. ISBLANK( ) returns True (.T.) if the character expression contains only the empty string ("") or spaces.

Example

In the following example, a table named mytable is created and a blank record is appended. ISBLANK( ) returns True (.T.) because myfield is blank. A value is placed in myfield, and ISBLANK( ) returns False (.F.) because myfield is no longer blank.
Copy Code
CREATE TABLE mytable FREE (myfield C(20))
APPEND BLANK  && Add new blank record
CLEAR

? ISBLANK(myfield)  && Displays .T.
REPLACE myfield WITH 'John Smith'  && Insert a value in the field
? ISBLANK(myfield)  && Displays .F.

See Also

Other Resources

APPEND Command
BLANK Command
EMPTY( ) Function
ISNULL( ) Function
LEN( ) Function
Functions
Language Reference


ISCOLOR( ) Function

Visual FoxPro 9.0 Language Reference
ISCOLOR( ) Function
See Also

Determines whether a computer can display color.

ISCOLOR( )

Return Value

Logical

Remarks

ISCOLOR( ) returns true (.T.) if the computer has color capability (whether or not a color monitor is actually being used). If the computer doesn't provide color support, ISCOLOR( ) returns false (.F.).

See Also

Other Resources

SET DISPLAY Command
SYS(2006) – Current Graphics Card
Functions
Language Reference


ISDIGIT( ) Function

Visual FoxPro 9.0 Language Reference
ISDIGIT( ) Function
See Also Example

Determines whether the leftmost character of the specified character expression is a digit (0 through 9).

ISDIGIT(cExpression)

Parameters

cExpression

Specifies the character expression that ISDIGIT( ) tests. Any characters after the first character in cExpression are ignored.

Return Value

Logical

Remarks

ISDIGIT( ) returns true (.T.) if the leftmost character of the specified character expression is a digit (0 through 9); otherwise, ISDIGIT( ) returns false (.F.).

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE orders  && Open Orders table
CLEAR

DISPLAY cust_id
? ISDIGIT(cust_id)  && Displays .F.
DISPLAY order_dsc
? ISDIGIT(ALLTRIM(STR(order_dsc)))  && Displays .T.

See Also

Other Resources

ISALPHA( ) Function
CLEAR Commands
Character Functions
USE Command
Functions


ISEXCLUSIVE( ) Function

Visual FoxPro 9.0 Language Reference
ISEXCLUSIVE( ) Function
See Also Example

Returns true (.T.) if a table or database is opened for exclusive use; otherwise, returns false (.F.).

ISEXCLUSIVE([cTableAlias | nWorkArea | cDatabaseName [, nType]])

Parameters

cTableAlias

Specifies the alias of the table for which the exclusive use status is returned. Visual FoxPro generates an error message if you specify a table alias that doesn't exist.
nWorkArea

Specifies the work area of the table for which the exclusive use status is returned. ISEXCLUSIVE( ) returns false (.F.) if a table isn't open in the work area you specify.
cDatabaseName

Specifies the name of the database for which the exclusive use status is returned.
nType

Specifies whether the exclusive status is returned for a table or a database. The following table lists the values for nType and the corresponding status returned.

nType Exclusive Status Returned

1

Table

2

Database
To determine the exclusive status for a database, you must include nType with a value of 2.

Return Value

Logical

Remarks

ISEXCLUSIVE( ) returns a value for the table open in the currently selected work area if you omit the optional cTableAlias, nWorkArea, or cDatabaseName arguments.

A table is opened for exclusive use by including the EXCLUSIVE keyword in USE, or by setting SET EXCLUSIVE to ON before the table is opened.

A database is opened for exclusive use by including the EXCLUSIVE keyword in OPEN DATABASE.

Example

In the following example, the ISEXCLUSIVE( ) function verifies that the table was opened for exclusive use. The table is not reindexed since the one in the current work are was not opened for exclusive use.
Copy Code
cExclusive = SET('EXCLUSIVE')
SET EXCLUSIVE OFF
SET PATH TO (HOME(2) + 'data\')
OPEN DATA testdata  && Opens the test databsase
USE customer     && Not opened exclusively
USE employee IN 0 EXCLUSIVE    && Opened exclusively in another work area
IF ISEXCLUSIVE( )
 REINDEX  && Can only be done if table opened exclusively
ELSE
  WAIT WINDOW 'The table has to be exclusively opened'
ENDIF
SET EXCLUSIVE &cExclusive

See Also

Other Resources

OPEN DATABASE Command
SET EXCLUSIVE Command
USE Command
Functions
Language Reference


ISFLOCKED( ) Function

Visual FoxPro 9.0 Language Reference
ISFLOCKED( ) Function
See Also

Returns the table lock status.

ISFLOCKED([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area number of the table for which the lock status is returned. If you omit cTableAlias and nWorkArea, the lock status is returned for the table open in the current work area.
cTableAlias

Specifies the alias of the table for which the lock status is returned. An "Alias not found" error message is generated if you specify an alias of a table that isn't open.

Return Value

Logical

Remarks

ISFLOCKED( ) returns a logical true (.T.) if the table is locked; otherwise a logical false (.F.) is returned. ISFLOCKED( ) is similar to SYS(2011), but returns a logical value which does not require localization for international applications.

Note:
ISFLOCKED() only returns .T. at the workstation that applied the file lock.

See Also

Other Resources

FLOCK( ) Function
ISRLOCKED( ) Function
LOCK( ) Function
RLOCK( ) Function
SYS(2011) – Current Lock Status
Functions
Language Reference


ISLEADBYTE( ) Function

Visual FoxPro 9.0 Language Reference
ISLEADBYTE( ) Function
See Also

Returns true (.T.) if the first byte of the first character in a character expression is the lead byte of a double-byte character.

ISLEADBYTE(cExpression)

Parameters

cExpression

Specifies the character expression that ISLEADBYTE( ) evaluates. Any bytes after the first byte in the first character in cExpression are ignored.

Return Value

Logical

Remarks

ISLEADBYTE( ) returns true (.T.) if the first byte of the first character in a character expression is the lead byte in a double-byte character. If ISLEADBYTE( ) returns false (.F.), the character being tested is a single-byte character.

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

ISALPHA( ) Function
ISDIGIT( ) Function
ISLOWER( ) Function
ISUPPER( ) Function
Functions
Language Reference


ISLOWER( ) Function

Visual FoxPro 9.0 Language Reference
ISLOWER( ) Function
See Also Example

Determines whether the leftmost character of the specified character expression is a lowercase alphabetic character.

ISLOWER(cExpression)

Parameters

cExpression

Specifies the character expression that ISLOWER( ) tests. ISLOWER( ) ignores any characters after the first character in cExpression.

Return Value

Logical

Remarks

ISLOWER( ) returns true (.T.) if the leftmost character in the specified character expression is a lowercase alphabetic character; otherwise, ISLOWER( ) returns false (.F.).

Example

Copy Code
CLEAR
? ISLOWER('redmond')  && Displays .T.
? ISLOWER('Redmond')  && Displays .F.

See Also

Other Resources

ISALPHA( ) Function
ISUPPER( ) Function
LOWER( ) Function
UPPER( ) Function
Functions
Language Reference


ISMEMOFETCHED( ) Function

Visual FoxPro 9.0 Language Reference
ISMEMOFETCHED( ) Function
See Also

Determines if a memo field has been fetched during a delayed memo fetch.

ISMEMOFETCHED(cFieldName | nFieldNumber [, nWorkArea | cTableAlias])

Parameters

cFieldName

Specifies the name of the memo field for which the fetch status is returned.
nFieldNumber

Specifies the field number (based on the physical structure of the table or cursor) of the memo field for which the fetch status is returned.
nWorkArea

Specifies the work area of the table or cursor containing the memo field for which the fetch status is returned.
cTableAlias

Specifies the alias of the table or cursor containing the memo field for which the fetch status is returned.

Return Value

Logical. A logical true (.T.) is returned if the specified memo field has been fetched, otherwise a logical false (.F.) is returned. True (.T.) is always returned for local data. The null value (.NULL.) is returned for a cursor if the record pointer is positioned at the beginning or end of the cursor. Use the BOF( ) and EOF( ) Function functions to determine if the record pointer is positioned at the beginning or end of the cursor.

Remarks

It can often take a while for a memo field fetch to occur with remote data, so you may choose to not download a memo field until it is absolutely needed.

The FetchMemo setting in the DBGETPROP( ) Function and CURSORGETPROP( ) Function functions determine if a memo field is retrieved with View results or on demand. ISMEMOFETCHED( ) return true (.T.) when the memo field is fetched for delayed Memo data (FetchMemo=.F.).

ISMEMOFETCHED( ) works with both memo and general fields.

See Also

Reference

CURSORGETPROP( ) Function
DBGETPROP( ) Function


ISMOUSE( ) Function

Visual FoxPro 9.0 Language Reference
ISMOUSE( ) Function
See Also Example

Returns true (.T.) if mouse hardware is present.

ISMOUSE( )

Remarks

ISMOUSE( ) returns true (.T.) if mouse hardware is present; otherwise it returns false (.F.).

Example

The following example displays a true value (.T.) if mouse hardware is present; otherwise, it displays false (.F.).
Copy Code
CLEAR
? 'Mouse hardware present? '
?? ISMOUSE( )

See Also

Other Resources

MCOL( ) Function
MDOWN( ) Function
MROW( ) Function
SYSMETRIC( ) Function
Functions
Language Reference


ISNULL( ) Function

Visual FoxPro 9.0 Language Reference
ISNULL( ) Function
See Also Example

Returns true (.T.) if an expression evaluates to a null value; otherwise, ISNULL( ) returns false (.F.).

ISNULL(eExpression)

Parameters

eExpression

Specifies the expression to evaluate.

Return Value

Logical

Remarks

Use ISNULL( ) to determine if the contents of a field, memory variable, or array element contains a null value, or if an expression evaluates to a null value.

Example

In the following example, ISNULL( ) is used to check for a null value.
Copy Code
STORE .NULL. TO mNullvalue  && Store a null value to a memory variable

CLEAR
? mNullvalue  && Display the value of the memory variable
? ISNULL(mNullvalue)  && Returns .T., indicating a null value
? TYPE('mNullvalue')     && Returns L, indicating a logical value
? (mNullvalue = .NULL.)  && Returns .NULL., bad test for null values

See Also

Other Resources

NVL( ) Function
SET NULL Command
Null Value Handling
Functions
Language Reference


ISPEN( ) Function

Visual FoxPro 9.0
ISPEN( ) Function
See Also

Determines if the last Tablet PC mouse event was a pen tap.

ISPEN( )

Remarks

The ISPEN( ) function returns a logical true (.T.) if the last Tablet PC mouse event was a pen tap. A logical false (.F.) is returned if the last mouse event wasn't a pen tap.

See Also

Reference

Click Event
MouseDown Event


ISREADONLY( ) Function

Visual FoxPro 9.0 Language Reference
ISREADONLY( ) Function
See Also Example

Determines whether a table or database is opened read-only.

ISREADONLY([nWorkArea | cTableAlias])

Parameters

nWorkArea| cTableAlias

Returns the read-only status for a table open in another work area. nWorkArea specifies the work area number and cTableAlias specifies the table or work area alias. ISREADONLY( ) returns false (.F.) if a table isn't open in the work area you specify. If you don't specify a work area number or a table or work area alias, the ISREADONLY( ) function returns the read-only status of the table open in the current work area. ISREADONLY(0) returns the status of the current database. If there is no current open database, ISREADONLY(0) returns an error.

Return Value

Logical

Remarks

ISREADONLY( ) returns true (.T.) if a table is opened read-only; otherwise, ISREADONLY( ) returns false (.F.).

You can open a table read-only by including the NOUPDATE option when opening the table with USE, by checking the Read Only check box when opening the table from the Open dialog box, or by assigning MS-DOS read-only attributes to the table.

You cannot pass a non-current database alias to the ISREADONLY( ) function. To ensure that a database is present, you can use code such as the following:

Copy Code
!EMPTY(DBC())

A cursor created with the SELECT – SQL command is always read-only.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer    NOUPDATE  && Open customer table read-only

CLEAR
? ISREADONLY('customer')  && Returns .T.

See Also

Other Resources

USE Command
ReadOnly Property
SELECT - SQL Command
Functions
Language Reference


ISRLOCKED( ) Function

Visual FoxPro 9.0 Language Reference
ISRLOCKED( ) Function
See Also

Returns the record lock status.

ISRLOCKED([nRecordNumber, [nWorkArea | cTableAlias]])

Parameters

nRecordNumber

Specifies the number of the record for which the lock status is returned. If nRecordNumber is omitted, the record lock status is returned for the current record.
nWorkArea

Specifies the work area number of the table for which the record lock status is returned. If you omit cTableAlias and nWorkArea, the record lock status is returned for the table open in the current work area.
cTableAlias

Specifies the alias of the table for which the record lock status is returned.

Return Value

Logical

Remarks

ISRLOCKED( ) returns a logical true (.T.) if the record is locked by the current application; otherwise a logical false (.F.) is returned.

Note:
ISRLOCKED() only returns .T. at the workstation that applied the record lock.

See Also

Other Resources

FLOCK( ) Function
ISFLOCKED( ) Function
LOCK( ) Function
RLOCK( ) Function
SYS(2011) - Current Lock Status
Functions
Language Reference


ISTRANSACTABLE( ) Function

Visual FoxPro 9.0 Language Reference
ISTRANSACTABLE( ) Function
See Also

Returns a logical value indicating if a free table or free cursor supports transactions.

ISTRANSACTABLE([nWorkArea | cAlias])

Parameters

nWorkArea

Specifies the work area of the free table or free cursor for which ISTRANSACTABLE( ) determines if transactions are supported.
cAlias

Specifies the alias of the table or cursor for which ISTRANSACTABLE( ) determines if transactions are supported.

Return Value

Logical. Returns a logical true (.T.) if a free table or free cursor supports transactions, otherwise a logical false (.F.) is returned.

Remarks

Use the MAKETRANSACTABLE( ) Function to allow a free table or free cursor to support transactions.

See Also

Reference

MAKETRANSACTABLE( ) Function
BEGIN TRANSACTION Command
END TRANSACTION Command
ROLLBACK Command


ISUPPER( ) Function

Visual FoxPro 9.0 Language Reference
ISUPPER( ) Function
See Also Example

Determines whether the first character in a character expression is an uppercase alphabetic character.

ISUPPER(cExpression)

Parameters

cExpression

Specifies the character expression that ISUPPER( ) evaluates. Any characters after the first character in cExpression are ignored.

Return Value

Logical

Remarks

ISUPPER( ) returns true (.T.) if the first character in a character expression is an uppercase alphabetic character; otherwise, ISUPPER( ) returns false (.F.).

Example

Copy Code
? ISUPPER('Redmond')  && Displays .T.
? ISUPPER('redmond')  && Displays .F.

See Also

Other Resources

ISALPHA( ) Function
ISLOWER( ) Function
LOWER( ) Function
UPPER( ) Function
Functions
Language Reference


JUSTDRIVE( ) Function

Visual FoxPro 9.0 Language Reference
JUSTDRIVE( ) Function
See Also

Returns the drive letter from a complete path.

JUSTDRIVE(cPath)

Parameters

cPath

Specifies the complete path name for which you want only the drive.

Return Value

Character

See Also

Other Resources

ADDBS( ) Function
DEFAULTEXT( ) Function
FILE( ) Function
FORCEEXT( ) Function
FORCEPATH( ) Function
JUSTEXT( ) Function
JUSTFNAME( ) Function
JUSTPATH( ) Function
JUSTSTEM( ) Function
Functions
Language Reference


JUSTEXT( ) Function

Visual FoxPro 9.0 Language Reference
JUSTEXT( ) Function
See Also

Returns the characters of a file extension from a complete path.

JUSTEXT(cPath)

Parameters

cPath

Specifies the name, which may include the full path, of the file for which you want only the extension. The maximum length of the string passed to cPath is 259 bytes.

Return Value

Character

See Also

Other Resources

ADDBS( ) Function
DEFAULTEXT( ) Function
FILE( ) Function
FORCEEXT( ) Function
FORCEPATH( ) Function
JUSTDRIVE( ) Function
JUSTFNAME( ) Function
JUSTPATH( ) Function
JUSTSTEM( ) Function
Functions


JUSTFNAME( ) Function

Visual FoxPro 9.0 Language Reference
JUSTFNAME( ) Function
See Also

Returns the file name portion of a complete path and file name.

JUSTFNAME(cFileName)

Parameters

cFileName

Specifies the name, which may include the full path, of the file for which you want only the file name. The maximum length of the string passed to cFileName is 259 bytes.

Return Value

Character

See Also

Other Resources

ADDBS( ) Function
DEFAULTEXT( ) Function
FILE( ) Function
FORCEEXT( ) Function
FORCEPATH( ) Function
JUSTDRIVE( ) Function
JUSTEXT( ) Function
JUSTPATH( ) Function
JUSTSTEM( ) Function
Functions
Language Reference


JUSTPATH( ) Function

Visual FoxPro 9.0 Language Reference
JUSTPATH( ) Function
See Also

Returns the path portion of a complete path and file name.

JUSTPATH(cFileName)

Parameters

cFileName

Specifies the full name (including path) of the file for which you want only the path. The maximum length of the string passed to cFileName is 259 bytes.

Return Value

Character

See Also

Other Resources

ADDBS( ) Function
DEFAULTEXT( ) Function
FILE( ) Function
FORCEEXT( ) Function
FORCEPATH( ) Function
JUSTDRIVE( ) Function
JUSTEXT( ) Function
JUSTFNAME( ) Function
JUSTSTEM( ) Function
Functions
Language Reference


JUSTSTEM( ) Function

Visual FoxPro 9.0 Language Reference
JUSTSTEM( ) Function
See Also

Returns the stem name (the file name before the extension) from a complete path and file name.

JUSTSTEM(cFileName)

Parameters

cFileName

Specifies the name (including path) of the file for which you want only the stem. The maximum length of the string passed to cFileName is 259 bytes.

Return Value

Character

See Also

Other Resources

ADDBS( ) Function
DEFAULTEXT( ) Function
FILE( ) Function
FORCEEXT( ) Function
FORCEPATH( ) Function
JUSTDRIVE( ) Function
JUSTEXT( ) Function
JUSTFNAME( ) Function
JUSTPATH( ) Function
Functions
Language Reference


KEY( ) Function

Visual FoxPro 9.0 Language Reference
KEY( ) Function
See Also Example

Returns the index key expression for an index tag or index file.

KEY([CDXFileName,] nIndexNumber [, nWorkArea | cTableAlias])

Parameters

CDXFileName

Specifies the name of a compound index file. KEY( ) returns the index key expressions of the .cdx file's index tag. The compound index file you specify can be the structural compound index file automatically opened with the table, or it can be an independent compound index file.
nIndexNumber

Specifies which index key expression to return. USE and SET INDEX both support an index file list that lets you open multiple indexes for a table. Any combination of single-entry .idx index files, structural compound index files, or independent compound index files can be included in the index file list. The numeric expression nIndexNumber specifies which index expression to return from the open index files. KEY( ) returns index expressions from open index files in the following order as nIndexNumber increases from 1 to the total number of open single-entry .idx files and structural compound and independent compound index tags:
  1. Index expressions from single-entry .idx index files (if any are open) are returned first. The order in which the single-entry index files are included in USE or SET INDEX determines how the index expressions are returned.

  2. Index expressions for each tag in the structural compound index (if one is present) are returned next. The index expressions are returned from the tags in the order in which the tags are created in the structural compound index.

  3. Index expressions for each tag in any open independent compound indexes are returned last. The index expressions are returned from the tags in the order in which the tags are created in the independent compound indexes.

The empty string is returned if nIndexNumber is greater than the total number of open single-entry .idx files and structural compound and independent compound index tags.
nWorkArea

Specifies the work area number of the table whose index key expressions you want KEY( ) to return. If a table isn't open in the work area you specify, KEY( ) returns the empty string.
cTableAlias

Specifies the alias of the table whose index key expressions you want KEY( ) to return. If no table has the alias you specify, Microsoft Visual FoxPro generates an error message. If you omit nWorkArea and cTableAlias, the index key expressions are returned for the table open in the current work area.

Return Value

Character

Remarks

An index key expression is specified when an index tag or index file is created with INDEX. The index key expression determines how a table is displayed and accessed when the index tag or index file is opened as the master controlling index tag or file.

For more information on creating index tags, index files, and index key expressions, see INDEX.

Example

The following example opens the customer table in the testdata database. FOR ... ENDFOR is used to create a loop in which KEY( ) is used to display the index expression of each index tag in the customer structural index. The name of each structural index tag is displayed with its index expression.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer     && Open customer table
CLEAR

FOR nCount = 1 TO TAGCOUNT( )
   IF !EMPTY(TAG(nCount))  && Checks for tags in the index
   ? TAG(nCount) + ' '  && Display tag name
   ?? KEY(nCount)  && Display index expression
   ELSE
      EXIT  && Exit the loop when no more tags are found
   ENDIF
ENDFOR

See Also

Other Resources

DESCENDING( ) Function
INDEX Command
REINDEX Command
SET INDEX Command
SYS(14) - Index Expression
USE Command
Functions
Language Reference


KEYMATCH( ) Function

Visual FoxPro 9.0 Language Reference
KEYMATCH( ) Function
See Also

Searches an index tag or index file for an index key.

KEYMATCH(eIndexKey [, nIndexNumber [, nWorkArea | cTableAlias]])

Parameters

eIndexKey

Specifies the index key that KEYMATCH( ) searches for. The index keys in an index file or index tag are determined by the index expression. An index expression is specified when an index file or index tag is created with INDEX. KEY( ) and SYS(14) can be used to return the index expressions for index files and index tags. For more information on creating index files, index expressions, and index keys, see INDEX. If you don't include any of the optional parameters, KEYMATCH( ) searches the master index file or master index tag for the index key you specify. If a master index file or index tag isn't in effect (for example, you've issued SET ORDER TO without any parameters to place the table in physical record order), Visual FoxPro generates an error message.
nIndexNumber

Specifies which index file or index tag is searched. nIndexNumber is typically an integer that starts at 1 and is increased by 1 to search additional index tags. If nIndexNumber is 1, the master single-entry .idx index file or master index tag (if one is present) is searched. As nIndexNumber increases, subsequent tags in the structural compound index (if one is present) are searched. The tags are searched in the order in which the tags were created in the structural compound index. As nIndexNumber continues to increase and all the tags in the structural compound index have been searched, tags in any open independent compound indexes are then searched. The tags are searched in the order in which the tags were created in the independent compound indexes. An error message is generated if nIndexNumber is greater than the total number of open single-entry .idx files and structural compound and independent compound index tags.
nWorkArea| cTableAlias

Searches index files or tags open in another work area. nWorkArea specifies the work area number and cTableAlias specifies the table alias. If you omit the work area and alias, KEYMATCH( ) searches index files or tags open for the table in the current work area. If no table has the alias you specify, Visual FoxPro generates an error message.

Return Value

Logical

Remarks

KEYMATCH( ) searches an index tag or index file for a specific index key and returns true (.T.) if the index key is found; otherwise, KEYMATCH( ) returns false (.F.). KEYMATCH( ) can be used to prevent duplicate index keys.

KEYMATCH( ) returns the record pointer to the record on which it was originally positioned before KEYMATCH( ) was issued.

See Also

Other Resources

INDEX Command
INDEXSEEK( ) Function
KEY( ) Function
SET INDEX Command
SYS(14) - Index Expression
USE Command
Functions
Language Reference


LASTKEY( ) Function

Visual FoxPro 9.0 Language Reference
LASTKEY( ) Function
See Also

Returns an integer corresponding to the last key pressed.

LASTKEY( )

Return Value

Numeric

Remarks

The values returned by LASTKEY( ) are the same as the values returned by INKEY( ). See INKEY( ) for a list of keys and their return values.

LASTKEY( ) is updated when you move between controls.

See Also

Other Resources

CHRSAW( ) Function
READKEY( ) Function
Functions
Language Reference


LEFT( ) Function

Visual FoxPro 9.0 Language Reference
LEFT( ) Function
See Also Example

Returns a specified number of characters from a character expression, starting with the leftmost character.

LEFT(cExpression, nExpression)

Parameters

cExpression

Specifies the character expression that LEFT( ) returns characters from.
nExpression

Specifies the number of characters returned from the character expression. If nExpression is greater than the length of cExpression, all of the character expression is returned. If nExpression is negative or 0, LEFT( ) returns an empty string. LEFT( ) uses a starting position of 1 and is identical to SUBSTR( ).

Return Value

Character. LEFT( ) returns a character string.

Example

The following example uses two different ways to display the string result from the LEFT( ) function, which returns the first four letters in the string, "Redmond, WA":

Copy Code
? LEFT('Redmond, WA', 4)          && Displays the string, Redm.
myString = LEFT('Redmond, WA', 4) && Stores result in myString.
? myString                        && Displays result in myString.

For more information, see ? | ?? Command.

See Also

Other Resources

AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LTRIM( ) Function
RAT( ) Function
RATLINE( ) Function
RIGHT( ) Function
RTRIM( ) Function
SUBSTR( ) Function
LEFTC( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
Functions


LEFTC( ) Function

Visual FoxPro 9.0 Language Reference
LEFTC( ) Function
See Also

Returns a specified number of characters from a character expression, starting with the leftmost character.

LEFTC(cExpression, nExpression)

Parameters

cExpression

Specifies the character expression from which LEFTC( ) returns characters.
nExpression

Specifies the number of characters returned from the character expression. If nExpression is greater than the length of cExpression, all of the character expression is returned. The empty string is returned if nExpression is negative or 0.

Return Value

Character

Remarks

LEFTC( ) is designed for expressions containing double-byte characters. If the expression contains only single-byte characters, LEFTC( ) is equivalent to LEFT( ).

LEFTC( ) returns a specified number of characters from a character expression containing any combination of single-byte and double-byte characters.

LEFTC( ) is identical to SUBSTRC( ) with a starting position of 1.

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
LTRIM( ) Function
RAT( ) Function
RATLINE( ) Function
RIGHT( ) Function
RTRIM( ) Function
SUBSTR( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
Functions
Language Reference


LEN( ) Function

Visual FoxPro 9.0 Language Reference
LEN( ) Function
See Also Example

Determines the number of characters in a character expression, indicating the length of the expression.

LEN(cExpression)

Parameters

cExpression

Specifies the character expression for which LEN( ) returns the number of characters.

Return Value

Numeric. LEN( ) returns the number of characters in a character expression.

Example

The following example clears the main Visual FoxPro window using the CLEAR command and opens the Customer table in the sample Testdata database located in the Visual FoxPro ..\Samples\Data directory by using the OPEN DATABASE and USE commands. Combined with the ? and ?? commands, LEN( ) displays the number of characters in the fields, Cust_ID and Contact.
Copy Code
CLEAR
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer
? 'Width of contact field: '
?? LEN(contact)
? 'Width of cust_id field: '
?? LEN(cust_id)

See Also

Other Resources

FSIZE( ) Function
TXTWIDTH( ) Function
LENC( ) Function
Functions
Language Reference


LENC( ) Function

Visual FoxPro 9.0 Language Reference
LENC( ) Function
See Also

Returns the number of characters in a character expression or memo field.

LENC(cExpression)

Parameters

cExpression

Specifies the character expression for which LENC( ) returns the number of characters.

Return Value

Numeric

Remarks

LENC( ) is designed for expressions containing double-byte characters. If the expression contains only single-byte characters, LENC( ) is equivalent to LEN( ).

LENC( ) returns the number of characters in a character expression or memo field containing any combination of single-byte and double-byte characters.

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

LEN( ) Function
Application Creation with Double-Byte Character Sets
FSIZE( ) Function
TXTWIDTH( ) Function
Functions
Language Reference


LIKE( ) Function

Visual FoxPro 9.0 Language Reference
LIKE( ) Function
See Also Example

Determines if a character expression matches another character expression.

LIKE(cExpression1, cExpression2)

Parameters

cExpression1

Specifies the character expression that LIKE( ) compares with cExpression2. cExpression1 can contain the wildcards such as * and ?. The question mark (?) matches any single character in cExpression2 and the asterisk (*) matches any number of characters. You can mix any number of wildcards in any combination in cExpression1.
cExpression2

Specifies the character expression LIKE( ) compares with cExpression1. cExpression2 must match cExpression1 letter for letter in order for LIKE( ) to return true (.T.).

Return Value

Logical

Remarks

LIKE( ) returns true (.T.) if cExpression1 matches cExpression2; otherwise, it returns false (.F.).

SET COMPATIBLE determines how LIKE( ) evaluates cExpression1 and cExpression2. If SET COMPATIBLE is set to ON or DB4, cExpression1 and cExpression2 have all trailing blanks removed before they are compared. If SET COMPATIBLE is set to OFF or FOXPLUS, any trailing blanks in cExpression1 and cExpression2 are used in the comparison.

Example

In the following example, all product names in the products table with the first two letters "Ch" are displayed.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE products  && Open Products table

CLEAR
? 'All product names with first two letters Ch:'
?
SCAN FOR LIKE('Ch*', prod_name)
   ? prod_name
ENDSCAN
USE

See Also

Other Resources

$ Operator
AT( ) Function
ATC( ) Function
OCCURS( ) Function
RAT( ) Function
SET COMPATIBLE Command
LIKEC( ) Function
Functions
Language Reference


LIKEC( ) Function

Visual FoxPro 9.0 Language Reference
LIKEC( ) Function
See Also

Determines whether a character expression matches another character expression.

LIKEC(cExpression1, cExpression2)

Parameters

cExpression1

Specifies the character expression that LIKEC( ) compares with cExpression2. cExpression1 can contain wild cards such as * and ?. A question mark (?) matches any single character in cExpression2 and an asterisk (*) matches any number of characters. You can mix any number of wild cards in any combination in cExpression1.
cExpression2

Specifies the character expression LIKEC( ) compares with cExpression1. cExpression2 must match cExpression1 character for character in order for LIKE( ) to return true (.T.).

Return Value

Logical

Remarks

LIKEC( ) is designed for expressions containing double-byte characters. If the expression contains only single-byte characters, LIKEC( ) is equivalent to LIKE( ).

LIKEC( ) determines if a character expression matches another character expression. LIKEC( ) returns true (.T.) if cExpression1 matches cExpression2; otherwise, it returns false (.F.).

SET COMPATIBLE determines how LIKEC( ) compares blanks in cExpression1 and cExpression2. If SET COMPATIBLE is set to ON or DB4, all trailing blanks are removed from cExpression1 and cExpression2 before they are compared. If SET COMPATIBLE is set to OFF or FOXPLUS, any trailing blanks in cExpression1 and cExpression2 are used in the comparison.

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

AT_C( ) Function
ATCC( ) Function
LIKE( ) Function
RATC( ) Function
Functions
Language Reference


LINENO( ) Function

Visual FoxPro 9.0 Language Reference
LINENO( ) Function
See Also Example

Returns the line number of a line being executed in a program relative to the first line of the main program.

LINENO([1])

Parameters

1

Returns the line number relative to the first line of the current program or procedure. If you omit the 1 argument, the line number is returned relative to the first line of the main program.

Return Value

Numeric

Remarks

Program lines are counted starting from the top of the program. Comment lines, continuation lines, and blank lines are included in the line number count. If a program is suspended during execution, LINENO( ) returns the number of the program line at which program execution was suspended. LINENO( ) returns 0 if a program is canceled.

By default, line numbers are returned relative to the beginning of the main program. If a procedure is called, line numbering continues from the top of the calling program.

LINENO( ) is useful for debugging programs. You can set a breakpoint to stop program execution at a specific line number by opening the Breakpoints window, setting the Type to 'Break when expression is true' and adding LINENO( ) = nExpression in the Expression textbox.

Example

The following example is part of a simple error-handling routine.
Copy Code
ON ERROR DO bug_proc WITH LINENO( )
BRWS  && Causes an error
ON ERROR

*** Bug_Proc error handler ***

PROCEDURE bug_proc
PARAMETERS gnBadLine
WAIT WINDOW 'Error occurred at line: ' + ALLTRIM(STR(gnBadLine))
RETURN

See Also

Other Resources

ERROR( ) Function
MESSAGE( ) Function
PROGRAM( ) Function
SYS(16) - Executing Program File Name
Error Messages A-Z
Error Messages by Number
Functions
Language Reference


LOADPICTURE( ) Function

Visual FoxPro 9.0 Language Reference
LOADPICTURE( ) Function
See Also

Creates an object reference for a bitmap, icon, or Windows meta file.

LOADPICTURE([cFileName])

Parameters

cFileName

Specifies the bitmap (.bmp), icon (.ico), or Windows metafile (.wmf) file for which an object reference is created. If cFileName is omitted, the null picture is returned. You can include GETPICT( ) as cFileName to display the Open dialog from which you can choose a bitmap (.bmp) file.

Return Value

Object

Remarks

Many presentation properties of ActiveX controls require an object reference for their settings. For example, the ActiveX Outline control supports the PictureOpen property that requires an object reference for its setting.

See Also

Other Resources

Functions
GETPICT( ) Function
SAVEPICTURE( ) Function
Picture Property


LOCFILE( ) Function

Visual FoxPro 9.0 Language Reference
LOCFILE( ) Function
See Also

Locates a file on disk and returns the file name with its path.

LOCFILE(cFileName [, cFileExtensions] [, cFileNameCaption])

Parameters

cFileName

Specifies the name of the file to locate. If cFileName includes only a file name, LOCFILE( ) searches the Visual FoxPro default directory or folder first. If the file is not found in the default directory or folder, the Microsoft Visual FoxPro path is then searched. Use SET PATH to specify the Visual FoxPro path. If cFileName includes a path and a file name, the specified location is searched. If the file cannot be found in the specified location, LOCFILE( ) searches the Visual FoxPro default directory or folder and then the Visual FoxPro path. If the file is located, LOCFILE( ) returns the file name and path.
cFileExtensions

Specifies file extensions for the file to locate. If the file name you specify with cFileName does not include an extension, Visual FoxPro applies the file extensions listed in cFileExtensions to the file name and searches for the file again. cFileExtensions also specifies the file name extensions of the files displayed in the Open dialog box when the file you specified cannot be located. cFileExtensions can take a variety of forms:
  • If cFileExtensions contains a single extension (for example, PRG), only files with that extension are displayed.

  • cFileExtensions can also contain wildcards (* and ?). All files with extensions that meet the wildcard criteria are displayed. For example, if cFileExtensions is ?X?, all files with the extension .fxp, .exe, or .txt are displayed.

  • In Visual FoxPro for Windows, cFileExtensions can contain a file description followed by a file extension or a list of file extensions separated with commas. The file description appears in the Files of Type list box. Separate the file description from the file extension or list of file extensions with a colon (:). Separate multiple file descriptions and their file extensions with a semicolon (;).

    For example, if cFileExtensions is "Text:TXT" the file description "Text" appears in the Files of Type list box and all files with a .txt extension are displayed.

    If cFileExtensions is "Tables:DBF; Files:TXT,BAK" the file descriptions "Tables" and "Files" appear in the Files of Type list box. When "Tables" is chosen from the Files of Type list box, all files with a .dbf extension are displayed. When "Files" is chosen from the Files of Type list box, all files with .txt and .bak extensions are displayed.

cFileNameCaption

Specifies the text you want to use to prompt the user. The text appears to the left of the textbox in which you enter the file name. If omitted, "File name:" is displayed.

For a list of Visual FoxPro file extensions and corresponding creator types, see the File Extensions and File Types online topic.

Return Value

Character

Remarks

The Open dialog box is displayed if the file cannot be located in the default directory or folder, the Visual FoxPro path, or a specified location. The Open dialog box can be used to locate the file. When a file is chosen from the Open dialog box, the file name is returned with the file's path.

If you exit the Open dialog box by choosing Cancel, pressing ESC, or choosing Close from the Control menu, Visual FoxPro generates an error message and LOCFILE( ) does not return a value.

See Also

Other Resources

Functions
FILE( ) Function
GETFILE( ) Function
GETPICT( ) Function
PUTFILE( ) Function
SET PATH Command


LOCK( ) Function

Visual FoxPro 9.0 Language Reference
LOCK( ) Function
See Also Example

Attempts to lock one or more records in a table.

LOCK([nWorkArea | cTableAlias]|
 [cRecordNumberList, nWorkArea | cTableAlias])

Parameters

nWorkArea| cTableAlias

Attempts a lock on the current record in a table open in a specific work area. nWorkArea specifies the work area number and cTableAlias specifies the table alias. If you do not specify a work area or table alias, LOCK( ) attempts to lock the current record in the table in the current work area.
cRecordNumberList

Specifies a list of one or more record numbers which you must include to attempt to lock multiple records. SET MULTILOCKS must be ON and you must include the work area or alias of the table for which you are attempting to place multiple record locks. LOCK( ) attempts to lock all of the records you specify. The record numbers specified with cRecordNumberList are separated by commas. For example, to attempt record locks on the first four records in a table, cRecordNumberList must contain 1,2,3,4. You can also lock multiple records by moving the record pointer to the record you would like to lock, issuing LOCK( ) or RLOCK( ) and then repeating these steps for each additional record. In Visual FoxPro, you can specify 0 as a record number. Specifying 0 makes it possible for you to attempt to lock the table header.
Note:
Keep the table header locked for as short a time as possible because other users cannot add records to the table when the table header is locked.

Release the table header lock with UNLOCK RECORD 0, UNLOCK or UNLOCK ALL. If all the records specified in cRecordNumbers are successfully locked, LOCK( ) returns true (.T.). If even one of the records specified with cRecordNumbers cannot be locked, LOCK( ) returns false (.F.) and none of the records are locked. However, any existing record locks remain in place. Multiple record locking is an additive process. Placing additional record locks does not release locks on other records. The maximum number of records that can be locked in each work area is approximately 8,000. It is always faster to lock the entire table rather than even a small number of records.

Return Value

Logical

Remarks

LOCK( ) is identical to RLOCK( ).

Changes to explicitly locked records aren't saved until the record is unlocked or the record pointer is moved.

If the lock or locks are successfully placed, LOCK( ) returns true (.T.). Locked records are available for both read and write access to the user who placed the locks; they are available for read-only access to all other users on the network.

Executing LOCK( ) does not guarantee that the record lock or locks will be successfully placed. A record lock cannot be placed on a record already locked by another user or in a table locked by another user. If the record lock or locks cannot be placed for any reason, LOCK( ) returns false (.F.).

By default, LOCK( ) makes one attempt to lock a record. Use SET REPROCESS to automatically retry a record lock when the first attempt fails. SET REPROCESS determines the number of lock attempts or the length of time during which lock attempts are made when the initial lock attempt is unsuccessful. For more information, see SET REPROCESS.

SET MULTILOCKS determines whether you can lock multiple records in a table. If SET MULTILOCKS is OFF (the default), you can lock only a single record in a table. When SET MULTILOCKS is ON, you can lock multiple records in a table. For more information, see SET MULTILOCKS.

Unlocking Records A table record can be unlocked only by the user who placed the lock. You can release record locks by issuing UNLOCK, closing the table, or exiting Visual FoxPro.

UNLOCK can be used to release record locks in the current work area, a specific work area, or in all work areas. For more information, see UNLOCK.

Switching SET MULTILOCKS from ON to OFF or from OFF to ON implicitly performs UNLOCK ALL — all record locks in all work areas are released.

Tables can be closed with USE, CLEAR ALL, or CLOSE DATABASES.

For more information about record and file locking and sharing tables on a network, see Programming for Shared Access.

Example

The following example locks and unlocks the first four records in the customer and employee tables.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
SET REPROCESS TO 3 AUTOMATIC
STORE '1,2,3,4' TO gcRecList
gcOldExc = SET('EXCLUSIVE')
SET EXCLUSIVE OFF
SELECT 0
USE employee  && Open Employee table
SELECT 0
USE customer  && Open Customer table
? LOCK('1,2,3,4', 'customer')  && Lock 1st 4 records in customer
? RLOCK(gcRecList, 'employee')  && Lock 1st 4 records in employee
UNLOCK IN customer
UNLOCK IN employee
SET EXCLUSIVE &gcOldExc

See Also

Other Resources

Functions
CLEAR Command
CLOSE Command
FLOCK( ) Function
RLOCK( ) Function
SET MULTILOCKS Command
SET REPROCESS Command
UNLOCK Command
USE Command
ISFLOCKED( ) Function
ISRLOCKED( ) Function


LOG( ) Function

Visual FoxPro 9.0 Language Reference
LOG( ) Function
See Also Example

Returns the natural logarithm (base e) of the specified numeric expression.

LOG(nExpression)

Parameters

nExpression

Specifies the numeric expression for which LOG( ) returns the value of x in the equation e^x = nExpression. nExpression must be greater than 0.

Return Value

Numeric

Remarks

The base for the natural logarithm is the constant e. The number of decimal places returned in the result is specified with SET DECIMALS.

Example

Copy Code
CLEAR
? LOG(1)  && Displays 0.00
STORE EXP(2) TO gneSquare
? LOG(gneSquare)  && Displays 2.00

See Also

Other Resources

Functions
EXP( ) Function
LOG10( ) Function
SET DECIMALS Command


LOG10( ) Function

Visual FoxPro 9.0 Language Reference
LOG10( ) Function
See Also Example

Returns the common logarithm (base 10) of the specified numeric expression.

LOG10(nExpression)

Parameters

nExpression

Specifies the numeric expression for which LOG10( ) returns the value of x in the equation 10^x = nExpression. nExpression must be greater than 0.

Return Value

Numeric

Remarks

The base for the common logarithm is 10. The number of decimal places returned in the result is specified with SET DECIMALS.

Example

Copy Code
CLEAR
? LOG10(10)  && Displays 1.00
STORE 100 TO gnBaseTen
? LOG10(gnBaseTen)  && Displays 2.00
? LOG10(gnBaseTen^2)  && Displays 4.00

See Also

Other Resources

Functions
EXP( ) Function
LOG( ) Function
SET DECIMALS Command


LOOKUP( ) Function

Visual FoxPro 9.0 Language Reference
LOOKUP( ) Function
See Also Example

Searches a table for the first record with a field matching the specified expression.

LOOKUP(ReturnField, eSearchExpression, SearchedField [, cTagName])

Parameters

ReturnField

Specifies the field whose contents LOOKUP( ) returns when the search is successful. If the search is unsuccessful, LOOKUP( ) returns an empty character string of the same length and data type as ReturnField.
eSearchExpression

Specifies the search expression. The search expression is usually the contents of a field in the table, or it can correspond to the index expression of the active index or compound index tag.
SearchedField

Specifies the field to search. If the table does not have an active index, LOOKUP( ) performs a sequential search through the field specified with SearchedField. If an index file or index tag is open whose index key expression is the search field you specify, LOOKUP( ) uses the index file or index tag to perform a faster search.
cTagName

Specifies the name of a compound index tag for LOOKUP( ) to use in the search. A compound index search is the fastest search LOOKUP( ) can perform.

Return Value

Character, Numeric, Currency, Float, Integer, Double, Date, DateTime, or Logical

Remarks

If the search is successful, LOOKUP( ) moves the record pointer to the matching record and returns the contents of a specified field in the record.

If the search expression is not found, LOOKUP( ) returns a blank character string the same length and data type as ReturnField. The record pointer is positioned at the end of the file.

If LOOKUP( ) is used to search a parent table, record pointers in all related child tables are moved to the related records.

This function cannot be optimized with Rushmore Query Optimization.

Example

In the following example, LOOKUP( ) uses the index tag company to search for the first occurrence of the string "Ernst Handel." If the search is successful, LOOKUP( ) returns the contents of the contact field and @ ... SAY displays the return value.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer ORDER company  && Open Customer table
CLEAR
@ 2,2 SAY LOOKUP(contact, 'Ernst Handel', company, 'company')

See Also

Other Resources

Functions
FIND Command
INDEX Command
LOCATE Command
SEEK Command
SEEK( ) Function


LOWER( ) Function

Visual FoxPro 9.0 Language Reference
LOWER( ) Function
See Also Example

Returns a specified character expression in lowercase letters.

LOWER(cExpression)

Parameters

cExpression

Specifies the character expression LOWER( ) converts.

Return Value

Character

Remarks

LOWER( ) converts all uppercase letters (A – Z) in the character expression to lowercase (a – z). All other characters in the character expression remain unchanged.

Example

Copy Code
STORE 'FOX' TO gcName
CLEAR
? LOWER(gcName)  && Displays fox

See Also

Other Resources

Functions
ISALPHA( ) Function
ISLOWER( ) Function
ISUPPER( ) Function
PROPER( ) Function
UPPER( ) Function


LTRIM( ) Function

Visual FoxPro 9.0 Language Reference
LTRIM( ) Function
See Also Example

Removes all leading spaces or parsing characters from the specified character expression, or all leading zero (0) bytes from the specified binary expression.

LTRIM(Expression [, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

Parameters

Expression

Specifies an expression of Character or Varbinary type to remove leading spaces or 0 bytes from, respectively.
nFlags

Specifies if trimming is case-sensitive when one or more parse characters (cParseChar, cParseChar2, … are included. Trimming is case-sensitive if nFlags is zero or is omitted. Trimming is case-insensitive if nFlags 1.
cParseChar [, cParseChar2 [, ...]]

Specifies one or more character strings that are trimmed from the beginning of cExpression. If cParseChar isn't included, then leading spaces or 0 bytes are removed from Expression. Note The maximum number of strings permitted in cParseChar is 23.

Return Value

Character or Varbinary. LTRIM( ) returns the specified expression without leading spaces or parsing characters, or 0 bytes.

Remarks

LTRIM( ) is particularly useful for removing the leading spaces that are inserted when you use the STR( ) function to convert a Numeric value to a Character string.

Example

Copy Code
STORE 'Redmond' TO gcCity
STORE '   Washington' TO gcState
CLEAR
? gcCity, gcState  && Displays Redmond   Washington
? gcCity, LTRIM(gcState)  && Displays Redmond Washington

See Also

Other Resources

ALLTRIM( ) Function
RTRIM( ) Function
STR( ) Function
TRIM( ) Function
Functions


LUPDATE( ) Function

Visual FoxPro 9.0 Language Reference
LUPDATE( ) Function
See Also Example

Returns the date on which a table was last updated.

LUPDATE([nWorkArea | cTableAlias])

Parameters

nWorkArea| cTableAlias

Returns the last update to a table open in another work area. nWorkArea specifies the work area number and cTableAlias specifies the table alias. LUPDATE( ) returns the date of the last update to the table in the currently selected work area if you omit nWorkArea and cTableAlias. If no table is open in the work area you specify, LUPDATE( ) returns a blank date. If no table has the alias you specify, Visual FoxPro generates an error message.

Return Value

Date

Remarks

This function is useful in update procedures.

LUPDATE( ) queries Windows to determine the date a table was last updated. However, the last two digits of the year the table was last updated are stored the table header.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open Customer table

CLEAR
? LUPDATE( )  && Displays date of last update

See Also

Other Resources

Functions
DIR Command
FDATE( ) Function
FTIME( ) Function


MAKETRANSACTABLE( ) Function

Visual FoxPro 9.0 Language Reference
MAKETRANSACTABLE( ) Function
See Also

Allows a free table or free cursor to support transactions.

MAKETRANSACTABLE([nWorkArea | cAlias])

Parameters

nWorkArea

Specifies the work area of the table or cursor for which transactions will be supported.
cAlias

Specifies the alias of the table or cursor for which transactions will be supported.

Return Value

Logical. Returns a logical true (.T.) if MAKETRANSACTABLE( ) was able to make the free table or cursor support transactions, otherwise a logical false (.F.) is returned.

Remarks

A free table is a table that has not been added to a database with the ADD TABLE Command. A free cursor is a cursor that is created from a free table or with the CREATE CURSOR - SQL Command.

When MAKETRANSACTABLE( ) is used to make a free table or free cursor support transactions, you can use the BEGIN TRANSACTION, END TRANSACTION, and ROLLBACK commands for the free table or free cursor. Use the ISTRANSACTABLE( ) function to determine if a free table or free cursor supports transactions.

Note:
When MAKETRANSACTABLE( ) is used to make a free table or free cursor support transactions, the free table or free cursor supports transactions in all work areas and data sessions in which it is opened. MAKETRANSACTABLE( ) makes all open instances of a free table or free cursor support transactions, including those in other data sessions within a single instance of VFP.

If a free table that does not support transactions is open in more than one data session, the free table cannot be made to support transactions. However, you can open a free table that already supports transactions in additional data sessions.

If row buffering is enabled, then a table update is performed if the free table or free cursor has pending changes before the free table or free cursor is made to support transactions. You cannot use MAKETRANSACTABLE( ) to enable transactions for a free table that has table buffering enabled.

To disable transactions for a free table, you must close the free table in all data sessions.

See Also

Reference

ISTRANSACTABLE( ) Function
BEGIN TRANSACTION Command
END TRANSACTION Command
ROLLBACK Command


MAX( ) Function

Visual FoxPro 9.0 Language Reference
MAX( ) Function
See Also Example

Evaluates a set of expressions and returns the expression with the maximum value.

MAX(eExpression1, eExpression2 [, eExpression3 ...])

Parameters

eExpression1, eExpression2[, eExpression3...]

Specify the expressions from which you want MAX( ) to return the expression with the highest value. All the expressions must be of the same data type.

Return Value

Character, Numeric, Currency, Double, Float, Date, or DateTime

Example

The following example uses APPEND BLANK to create a table with 10 records containing random values, then uses MIN( ) and MAX( ) to display the maximum and minimum values in the table.
Copy Code
CLOSE DATABASES
CREATE TABLE Random (cValue N(3))
FOR nItem = 1 TO 10  && Append 10 records,
   APPEND BLANK
   REPLACE cValue WITH 1 + 100 * RAND( )  && Insert random values
ENDFOR

CLEAR
LIST  && Display the values
gnMaximum = 1  && Initialize minimum value
gnMinimum = 100  && Initialize maximum value
SCAN
   gnMinimum = MIN(gnMinimum, cValue)
   gnMaximum = MAX(gnMaximum, cValue)
ENDSCAN
? 'The minimum value is: ', gnMinimum  && Display minimum value
? 'The maximum value is: ', gnMaximum  && Display maximum value

See Also

Other Resources

Functions
CALCULATE Command
MIN( ) Function
SELECT - SQL Command


MCOL( ) Function

Visual FoxPro 9.0 Language Reference
MCOL( ) Function
See Also

Returns the column position of the mouse pointer in the main Visual FoxPro window or a user-defined window or form.

MCOL([cWindowName | 0 [, nScaleMode]])

Parameters

cWindowName

Specifies the name of the window or form whose mouse-pointer column position MCOL( ) returns.
0

Specifies that the column position of the mouse pointer is returned for the currently active window or form.
nScaleMode

Specifies the unit of measurement for the value MCOL( ) returns. The following table lists the settings for nScaleMode.

nScaleMode Description

0

Foxels. A foxel is equivalent to the average height and width of a character based on the current font of the form in which an object is contained. (Default)

3

Pixels. A pixel is the smallest element that can be displayed on a screen or printer. Pixels are screen-dependent.

Return Value

Numeric. MCOL( ) returns the column position of the mouse pointer in the main Visual FoxPro window, user-defined window, or form.

If you omit cWindowName, and there is no active user-defined window or form, MCOL( ) returns the mouse pointer's column position in the main Visual FoxPro window. If you omit cWindowName, and there is an active user-defined window or form, MCOL( ) returns the mouse pointer's column position in the active user-defined window or form. MCOL() returns –1 if the mouse pointer is positioned outside the user-defined window or form, if no mouse driver is loaded, or there is no output window.

Remarks

Using the MCOL( ) function without the optional argument 0 may affect the behavior of code on forms when the Form AllowOutput property IS set to false (.F.). For example, the placement of a shortcut menu that is defined in the RightClick event may not display in the proper location if you use the MCOL( ) and MROW( ) functions to determine where the menu is displayed. In this case, be sure to include 0 in the MCOL( ) and MROW( ) functions.

See Also

Other Resources

Functions
AMOUSEOBJ( ) Function
COL( ) Function
GridHitTest Method
INKEY( ) Function
ISMOUSE( ) Function
MROW( ) Function
ROW( ) Function
WCOLS( ) Function
WROWS( ) Function


MDX( ) Function

Visual FoxPro 9.0 Language Reference
MDX( ) Function
See Also

Returns the name of the open .cdx compound index file that has the specified index position number.

MDX(nIndexNumber [, nWorkArea | cTableAlias])

Parameters

nIndexNumber

Specifies which compound index file name to return. If the table has a structural compound index file and nIndexNumber is 1, the name of the structural compound index file (which is always the same as the name of the table) is returned. If nIndexNumber is 2, the name of the first compound index file specified with USE or SET INDEX is returned. If nIndexNumber is 3, the second compound index file name is returned, and so on. If nIndexNumber is greater than the number of open compound index files, an empty string is returned. If the table doesn't have a structural compound index file and nIndexNumber is 1, the name of the first compound index file specified with USE or SET INDEX is returned. If nIndexNumber is 2, the second compound index file name is returned, and so on. If nIndexNumber is greater than the number of open compound index files, an empty string is returned.
nWorkArea

Specifies the work area number for compound index files open in work areas other than the current one. If you omit this optional argument, names of compound index files are returned for the current work area.
cTableAlias

Specifies the table alias for compound index files open in work areas other than the current one. If you omit this optional argument, names of compound index files are returned for the current work area.

Return Value

Character

Remarks

MDX( ) is identical to CDX( ).

Index files can be opened for a table with the INDEX clause of the USE command or with SET INDEX. A structural compound index file is automatically opened with its table. MDX( ) ignores any .idx index files specified with USE or with SET INDEX.

Use TAG( ) to return tag names from a compound index file; use NDX( ) to return the name of an open .idx index file.

In Visual FoxPro for Windows, when SET FULLPATH is ON, MDX( ) returns the path to the .cdx file with the .cdx file name. When SET FULLPATH is OFF, MDX( ) returns the drive the .cdx file resides on with the .cdx file name.

See Also

Other Resources

Functions
CDX( ) Function
INDEX Command
NDX( ) Function
SET INDEX Command
SET FULLPATH Command
SYS(14) - Index Expression
TAG( ) Function
USE Command


MDY( ) Function

Visual FoxPro 9.0 Language Reference
MDY( ) Function
See Also Example

Returns the specified date or datetime expression in month-day-year format with the name of the month spelled out.

MDY(dExpression | tExpression)

Parameters

dExpression

Specifies the date expression to return in month-day-year format.
tExpression

Specifies the datetime expression to return in month-day-year format.

Return Value

Character

Remarks

If SET CENTURY is OFF, the character expression is returned in a month dd, yy format. If SET CENTURY is ON, the format is month dd, yyyy.

Example

The following example creates a user-defined function that returns a date with the corresponding weekday.
Copy Code
SET CENTURY OFF

CLEAR
? Longdate({^1998-02-16})  && Displays Monday, February 16, 98

SET CENTURY ON
? Longdate({^1998-02-16})  && Displays Monday, February 16, 1998

*** LongDate ***

FUNCTION longdate
PARAMETERS gdDate
RETURN CDOW(gdDate) + ', ' + MDY(gdDate)

See Also

Other Resources

Functions
DMY( ) Function
SET CENTURY Command
SET DATE Command


MEMLINES( ) Function

Visual FoxPro 9.0 Language Reference
MEMLINES( ) Function
See Also Example

Returns the number of lines in a memo field.

MEMLINES(MemoFieldName)

Parameters

MemoFieldName

Specifies the name of the memo field. If the memo field is in a table that isn't open in the current work area, preface the memo field name with the table alias and a period.

Return Value

Numeric

Remarks

The number of lines in a memo field is determined by the current value of SET MEMOWIDTH.

Example

The following example scans three records in the employee table and uses MEMLINES( ) to determine whether or not there is data in the notes memo field and when page breaks should occur. The last_name data for the record appears, along with the notes (if there is data in the memo field) or a message indicating that there are no notes for that record.
Copy Code
CLOSE DATABASES
CLEAR
SET TALK OFF
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE employee  && Open Employee table

SET MEMOWIDTH TO 65
gnLine = 1
GOTO 2
SCAN NEXT 3
   gnMemoSize = MEMLINES(notes)
   IF gnMemoSize = 0
      STORE .T. TO glNoMemo
      STORE 1 TO gnMemoSize
   ELSE
      STORE .F. TO glNoMemo
   ENDIF
   IF gnLine + gnMemoSize > 65
      EJECT
      gnLine = 1
   ENDIF
   @ gnLine,2 SAY 'Last Name: '+ last_name
   gnLine = gnLine +1
   @ gnLine ,2 SAY 'Notes: '
   ?? IIF(glNoMemo, 'No notes ',notes)
   gnLine = gnLine + gnMemoSize + 2
   IF gnLine > 24
      gnLine = 1
      CLEAR
   ENDIF
ENDSCAN

See Also

Other Resources

Functions
_MLINE System Variable
ALINES( ) Function
ATCLINE( ) Function
ATLINE( ) Function
COPY MEMO Command
MLINE( ) Function
MODIFY MEMO Command
SCATTER Command
SET MEMOWIDTH Command


MEMORY( ) Function

Visual FoxPro 9.0 Language Reference
MEMORY( ) Function
See Also

Returns the amount of memory available to run an external program.

MEMORY( )

Return Value

Numeric

Remarks

In Visual FoxPro, MEMORY( ) always returns 640.

MEMORY( ) is similar to SYS(12), with two exceptions:

  • MEMORY( ) returns the amount of available memory in kilobytes; SYS(12) returns the amount of memory in bytes.

  • MEMORY( ) returns a numeric expression. SYS(12) returns its value as a character string.

See Also

Other Resources

Functions
SYS(12) - Available Memory in Bytes
SYS(1001) - Visual FoxPro Memory


MENU( ) Function

Visual FoxPro 9.0 Language Reference
MENU( ) Function
See Also Example

Returns the name of the active menu bar as an uppercase character string.

MENU( )

Return Value

Character

Remarks

MENU( ) returns an empty string if no menu is active. Use the Menu Designer to create a menu and activate it.

Example

The following example uses MENU( ) to pass the name of a menu bar to a procedure. The current system menu bar is saved to memory with SET SYSMENU SAVE, and all system menu titles are removed with SET SYSMENU TO.

Several system menu titles are created with DEFINE PAD. When you choose a menu title, MENU( ) passes the name of the Microsoft Visual FoxPro system menu bar, _MSYSMENU, to the choice procedure. The choice procedure displays the name of the menu title you chose and the name of the system menu bar. If you choose the Exit menu, the original Visual FoxPro system menu is restored.
Copy Code
*** Save this program as MENUEXAM.PRG in the default VFP directory.***
CLEAR
SET SYSMENU SAVE
SET SYSMENU TO
DEFINE PAD padSys OF _MSYSMENU PROMPT '\<System' COLOR SCHEME 3 ;
   KEY ALT+S, ''
DEFINE PAD padEdit OF _MSYSMENU PROMPT '\<Edit' COLOR SCHEME 3 ;
   KEY ALT+E, ''
DEFINE PAD padRecord OF _MSYSMENU PROMPT '\<Record' COLOR SCHEME 3 ;
   KEY ALT+R, ''
DEFINE PAD padWindow OF _MSYSMENU PROMPT '\<Window' COLOR SCHEME 3 ;
   KEY ALT+W, ''
DEFINE PAD padReport OF _MSYSMENU PROMPT 'Re\<ports' COLOR SCHEME 3 KEY ALT+P, ''
DEFINE PAD padExit OF _MSYSMENU PROMPT 'E\<xit' COLOR SCHEME 3 ;
   KEY ALT+X, ''
ON SELECTION MENU _MSYSMENU ;
   DO choice IN menuexam WITH PAD(), MENU()
PROCEDURE choice
PARAMETER gcPad, gcMenu
WAIT WINDOW 'You chose ' + gcPad + ;
   ' from menu ' + gcMenu NOWAIT
IF gcPad = 'PADEXIT'
   SET SYSMENU TO DEFAULT
ENDIF

See Also

Other Resources

Functions
ACTIVATE MENU Command
CREATE MENU Command
DEFINE MENU Command


MESSAGE( ) Function

Visual FoxPro 9.0 Language Reference
MESSAGE( ) Function
See Also Example

Returns the current error message or the program line that caused the error.

MESSAGE([1])

Parameters

[1]

Return the program source code that caused the error if MESSAGE( ) is included in an ON ERROR routine.
Note:
MESSAGE(1) is not available in the runtime.

If the program source code is not available, MESSAGE(1) returns one of the following:
  • The entire program line if the line is macro-substituted.

  • A command if the line contains a command without any additional clauses.

  • A command followed by three dots (...) if the line contains a command and additional clauses.

Return Value

Character. MESSAGE( ) returns the current error message as a character string or the contents of the program line causing the error.

Remarks

Unlike ERROR( ), MESSAGE( ) is not reset by RETURN or RETRY.

Example

The following example displays output using the MESSAGE( ) function.
Copy Code
ON ERROR DO Errhand
*** The next line should generate an error ***
USE Nodatabase
ON ERROR     && Restore system error handler.
PROCEDURE Errhand
? 'Line of code with error: ' + MESSAGE(1)
? 'Error number: ' + STR(ERROR( ))
? 'Error message: ' + MESSAGE( )

See Also

Other Resources

Functions
ERROR Command
ERROR( ) Function
ON ERROR Command
AERROR( ) Function
Error Messages A-Z
Error Messages by Number


MESSAGEBOX( ) Function

Visual FoxPro 9.0 Language Reference
MESSAGEBOX( ) Function
See Also Example

Displays a user-defined dialog box.

MESSAGEBOX(eMessageText [, nDialogBoxType ][, cTitleBarText][, nTimeout])

Parameters

eMessageText

Specifies the text that appears in the dialog box. You can also specify any valid Visual FoxPro function, object, or data type instead of eMessageText. The maximum amount of text you can specify is 1024 characters.
Note:
Visual FoxPro converts object references to the string, "(Object)". If you specify a function that evaluates to a noncharacter value, Visual FoxPro automatically uses the TRANSFORM( ) function to provide the character equivalent. In the following example, a character type date is returned and passed to MESSAGEBOX( ):

Copy Code
MESSAGEBOX(DATE())
Tip:
To move a portion of the message to the next line in the dialog box, use a carriage return, CHR(13), in eMessageText. The height and width of the dialog box increases as needed to contain eMessageText.

nDialogBoxType

Specifies the buttons and icons that appear in the dialog box, the default button when the dialog box is displayed, and the behavior of the dialog box. In the following tables, the dialog box button values 0 to 5 specify the buttons that appear in the dialog box. The icon values 16, 32, 48, and 64 specify the icon that appears in the dialog box. The default values 0, 256, and 512 specify which button in the dialog box is the default button. The default button is selected when the dialog box is displayed. Omitting nDialogBoxType is identical to specifying a value of 0 for nDialogBoxType.

Value Dialog box buttons

0

OK button only

1

OK and Cancel buttons

2

Abort, Retry, and Ignore buttons

3

Yes, No, and Cancel buttons

4

Yes and No buttons

5

Retry and Cancel buttons

Value Icon

16

Stop sign

32

Question mark

48

Exclamation point

64

Information (i) icon

Value Default button

0

First button

256

Second button

512

Third button
nDialogBoxType can be the sum of up to three values, one value from each of the preceding tables. For example, if nDialogBoxType is 290 (2+32+256), the specified dialog box has the following characteristics:
  • Abort, Retry, and Ignore buttons.

  • The message box displays the question mark icon.

  • The second button, Retry, is the default.

Additional information about the constants is available in the FoxPro.h file, located in the Visual FoxPro home directory. Using defined constants such as MB_ABORTRETRYIGNORE + MB_ICONQUESTION + MB_DEFBUTTON2 can be more readable than 2 + 32 + 256.
Note:
The question mark icon is no longer recommended, because it does not clearly represent a specific type of message and because the phrasing of a message as a question could apply to any message type. In addition, users could confuse the message symbol question mark with Help Information. Therefore, it is not recommended to use the question mark symbol in your message boxes. The system continues to support inclusion only for backwards compatibility.

cTitleBarText

Specifies the text that appears in the title bar of the dialog box. If you omit cTitleBarText, the title "Microsoft Visual FoxPro" appears in the title bar.
nTimeout

Specifies the number of milliseconds Visual FoxPro displays eMessageText without input from the keyboard or the mouse before clearing eMessageText. You can specify any valid timeout value. A value of less than 1 never times out until user enters input and behaves the same as omitting the nTimeout parameter.

Return Value

Numeric data type. MESSAGEBOX( ) returns a value that indicates which button was chosen in the dialog box. The following table lists the values MESSAGEBOX( ) returns for each button.

Return value | Button
1 | OK
2 | Cancel
3 | Abort
4 | Retry
5 | Ignore
6 | Yes
7 | No

In dialog boxes with a Cancel button, pressing ESC to exit the dialog box returns the same value (2) as choosing Cancel.

MESSAGEBOX( ) returns a value of -1 when a timeout occurs.

Remarks

The shortest abbreviation for MESSAGEBOX( ) is MESSAGEB( ).

The MESSAGEBOX( ) function uses smart parameters in that the parameter type determines which parameter is used. The first parameter is required and is always eMessageText. However, the optional second parameter can be nDialogBoxType if the type is Numeric or cTitleBarText if type is Character. The nTimeout parameter is always assumed for the second optional numeric parameter passed. Valid examples include:

Copy Code
MESSAGEBOX("HELLO","MyTitle",68,6000)
MESSAGEBOX("HELLO",68,"MyTitle",6000)
MESSAGEBOX("HELLO",68,6000)
MESSAGEBOX("HELLO",68,6000,"MyTitle")

Example

The following example displays a user-defined dialog box. The message "Record not found. Would you like to search again?" is displayed as the caption in the user-defined dialog box, and "My Application" is displayed in the title bar.

The user-defined dialog box contains Yes and No buttons and the question mark icon, and the second button (No) is the default button. When you choose one of the buttons, your choice is displayed.
Copy Code
eMessageTitle = 'My Application'
eMessageText = 'Record not found. Would you like to search again?'
nDialogType = 4 + 16 + 256
*  4 = Yes and No buttons
*  16 = Stop sign icon
*  256 = Second button is default

nAnswer = MESSAGEBOX(eMessageText, nDialogType, eMessageTitle)

DO CASE
   CASE nAnswer = 6
      WAIT WINDOW 'You chose Yes'
   CASE nAnswer = 7
      WAIT WINDOW 'You chose No'
ENDCASE

See Also

Other Resources

Functions
WAIT Command
DO CASE ... ENDCASE Command
InputBox( ) Function
TRANSFORM( ) Function


MIN( ) Function

Visual FoxPro 9.0 Language Reference
MIN( ) Function
See Also Example

Evaluates a set of expressions and returns the expression with the minimum value.

MIN(eExpression1, eExpression2 [, eExpression3 ...])

Parameters

eExpression1, eExpression2[, eExpression3...]

Specify the set of expressions from which you want MIN( ) to return the expression with the lowest value. All the expressions must be of the same type.

Return Value

Character, Numeric, Currency, Double, Float, Date, or DateTime

Example

The following example uses APPEND BLANK to create a table with 10 records containing random values, then uses MIN( ) and MAX( ) to display the maximum and minimum values in the table.
Copy Code
CLOSE DATABASES
CREATE TABLE Random (cValue N(3))
FOR nItem = 1 TO 10  && Append 10 records,
   APPEND BLANK
   REPLACE cValue WITH 1 + 100 * RAND( )  && Insert random values
ENDFOR

CLEAR
LIST  && Display the values
gnMaximum = 1  && Initialize minimum value
gnMinimum = 100  && Initialize maximum value
SCAN
   gnMinimum = MIN(gnMinimum, cValue)
   gnMaximum = MAX(gnMaximum, cValue)
ENDSCAN
? 'The minimum value is: ', gnMinimum  && Display minimum value
? 'The maximum value is: ', gnMaximum  && Display maximum value

See Also

Other Resources

Functions
CALCULATE Command
MAX( ) Function


MINUTE( ) Function

Visual FoxPro 9.0 Language Reference
MINUTE( ) Function
See Also Example

Returns the minute portion from a DateTime expression.

MINUTE(tExpression)

Parameters

tExpression

Specifies the DateTime expression from which the minute portion is returned.

Return Value

Numeric

Example

The following example displays the minute portion of the current time and the minute portion of a specific time.
Copy Code
CLEAR
? MINUTE(DATETIME( ))
? MINUTE({^1998-02-16 10:42a})  && Displays 42

See Also

Other Resources

Functions
CTOT( ) Function
DATE( ) Function
DATETIME( ) Function
DTOT( ) Function
HOUR( ) Function
SEC( ) Function
SECONDS( ) Function
SET SECONDS Command
TIME( ) Function


MLINE( ) Function

Visual FoxPro 9.0 Language Reference
MLINE( ) Function
See Also Example

Returns a specific line from a Memo field as a character string.

Note:
MLINE( ) is primarily a text processing function; therefore, the results from processing binary values might not be as expected. For example, MLINE( ) might return different results depending on the SET MEMOWIDTH setting. MLINE( ) might interpret binary values as line breaks or truncate binary values unexpectedly. It is recommended that you use the ALINES( ) function instead to manipulate binary values.

MLINE(MemoFieldName, nLineNumber [, nNumberOfCharacters])

Parameters

MemoFieldName

Specifies the name of the memo field from which MLINE( ) returns a line. If the memo field is in a table open in a non-current work area, preface the memo field name with a period and the table alias.
nLineNumber

Specifies the number of the line to return from the memo field. If nLineNumber is negative, 0, or greater than the number of lines in the memo field, MLINE( ) returns an empty string. MLINE( ) trims any trailing spaces from the line specified with nLineNumber.
nNumberOfCharacters

Specifies the number of characters from the beginning of the memo field after which MLINE( ) returns the specified line. The _MLINE system variable is typically used for nNumberOfCharacters. _MLINE is automatically adjusted each time MLINE( ) is called. In recursive procedures that return lines from large memo fields, you can obtain the best performance by including _MLINE as nNumberOfCharacters. For more information, see _MLINE System Variable.

Return Value

Character or Varbinary. MLINE( ) returns a character string from a specific line in a Memo field. When using MLINE( ) with binary values, such as Varbinary and Blob, the return value has type Varbinary.

Remarks

The length and number of the lines in a memo field are determined by the current value of SET MEMOWIDTH (the default line length is 50 characters). If a carriage return is encountered, no additional characters are returned. The current _WRAP setting determines how the memo field line is displayed.

When searching a memo field for a character string, you can use ATLINE( ) or ATCLINE( ) to return the line number of the line in which the character string is found. Use this line number in MLINE( ) to return the contents of the line from the memo field.

Example

In the following example, two methods are used to return lines from a memo field. Two loops use MLINE( ) to return lines from the memo field. Note the improvement in performance in the second loop when the system variable _MLINE is used in MLINE( ).
Copy Code
CLEAR
SET TALK OFF
SET MEMOWIDTH TO 50
CLOSE DATABASES
CREATE TABLE tmemo (name c(10), notes m)
APPEND BLANK                  && Add a record
WAIT WINDOW 'Filling memo field - takes several seconds' NOWAIT
*** Fill the memo field  ***
FOR gnOuterLoop = 1 TO 5         && loop 5 times
   FOR gnAlphabet = 65 TO 75   && letters A to H
      REPLACE notes WITH REPLICATE(CHR(gnAlphabet), 10) ;
         + CHR(13) ADDITIVE
   NEXT
NEXT

*** Display all lines from the memo field ***
STORE MEMLINES(notes) TO gnNumLines   && Number of lines in memo field
STORE SECONDS( ) TO gnBegin      && Beginning time
FOR gnCount = 1 TO gnNumLines   && Loop for # of lines in memo field
   ? MLINE(notes, gnCount)      && Display each line
NEXT
? STR(SECONDS( ) - gnBegin, 4, 2) + ' seconds'   && Total time

*** Preferable method using _MLINE in MLINE( ) ***
*** Display all lines from the memo field ***
WAIT 'Press a key to see the preferred method' WINDOW
CLEAR
STORE 0 TO _MLINE             && Reset _MLINE to zero
STORE SECONDS( ) TO gnBegin      && Beginning time
FOR count = 1 TO gnNumLines      && Loop for # of lines in memo field
   ? MLINE(notes, 1, _MLINE)      && Display each line
NEXT
? STR(SECONDS( ) - gnBegin, 4, 2) + ' seconds'   && Total time
SET TALK ON
CLOSE DATABASES
ERASE tmemo.dbf
ERASE tmemo.fpt

See Also

Other Resources

Functions
ALINES( ) Function
ATCLINE( ) Function
ATLINE( ) Function
COPY MEMO Command
MEMLINES( ) Function
MODIFY MEMO Command
SET MEMOWIDTH Command
_WRAP System Variable


MOD( ) Function

Visual FoxPro 9.0 Language Reference
MOD( ) Function
See Also Example

Divides one numeric expression by another numeric expression and returns the remainder.

MOD(nDividend, nDivisor)

Parameters

nDividend

Specifies the dividend. The number of decimal places in nDividend determines the number of decimal places in the return value.
nDivisor

Specifies the divisor. A positive number is returned if nDivisor is positive, and a negative number is returned if nDivisor is negative.

Return Value

Numeric

Remarks

The modulus function MOD( ) and the % operator return identical results.

Example

Copy Code
CLEAR
? MOD(36,10)  && Displays 6
? MOD((4*9), (90/9))  && Displays 6
? MOD(25.250,5.0)  && Displays 0.250
? IIF(MOD(YEAR(DATE( )), 4) = 0, 'Summer Olympics this year';
   , 'No Summer Olympics this year')

See Also

Other Resources

Functions
% Operator


MONTH( ) Function

Visual FoxPro 9.0 Language Reference
MONTH( ) Function
See Also Example

Returns the number of the month for a given Date or DateTime expression.

MONTH(dExpression | tExpression)

Parameters

dExpression

Specifies the Date expression for which you want MONTH( ) to return the month number.
tExpression

Specifies the DateTime expression for which you want MONTH( ) to return the month number.

Return Value

Numeric

Remarks

MONTH( ) returns a number from 1 through 12. January is month 1, and December is month 12.

Example

Copy Code
CLEAR
? DATE( )  && Displays today's date
? MONTH(DATE( ))  && Displays the month number
STORE {^1998-05-03} TO gdBuy
STORE MONTH(gdBuy + 31) TO gdMonth
? gdMonth  && Displays 6

See Also

Other Resources

Functions
CMONTH( ) Function
DAY( ) Function
QUARTER( ) Function
YEAR( ) Function


MRKBAR( ) Function

Visual FoxPro 9.0 Language Reference
MRKBAR( ) Function
See Also

Determines whether a menu item on a user-defined or Microsoft Visual FoxPro system menu is marked.

MRKBAR(cMenuName, nMenuItemNumber | cSystemMenuItemName)

Parameters

cMenuName

Specifies the name of the menu containing the menu item. The menu can be a Visual FoxPro system menu (such as _MFILE, MEDIT, or _MDATA).
nMenuItemNumber

Specifies the number of a menu item in a user-defined menu. A menu item's number is specified when the menu item is created with DEFINE BAR.
cSystemMenuItemName

Specifies the name of a Visual FoxPro system menu item. For example, the following command displays a logical value specifying if the New menu item on the File menu is marked.
Copy Code
? MRKBAR('_MFILE', _MFI_NEW)

Return Value

Logical

Remarks

Use SET MARK OF to mark or unmark a menu item.

If the specified menu item is marked, MRKBAR( ) returns true (.T.); otherwise, MRKBAR( ) returns false (.F.).

For an example of using MRKBAR( ), see CNTBAR( ).

See Also

Other Resources

Functions
MRKPAD( ) Function
SET MARK OF Command
SET MARK TO Command


MRKPAD( ) Function

Visual FoxPro 9.0 Language Reference
MRKPAD( ) Function
See Also Example

Determines whether a menu title on a user-defined menu bar or on the Visual FoxPro system menu bar is marked.

MRKPAD(cMenuBarName, cMenuTitleName)

Parameters

cMenuBarName

Specifies the name of the menu bar containing the menu title.
cMenuTitleName

Specifies the name of the menu title.

Return Value

Logical

Remarks

Use SET MARK OF to mark or unmark a menu title.

If the specified menu title is marked, MRKPAD( ) returns true (.T.); otherwise, MRKPAD( ) returns false (.F.).

Example

The following program example, named MARKPAD.PRG, uses MRKPAD( ) to toggle the mark character of a menu title when you choose it.

The current system menu bar is first saved to memory with SET SYSMENU SAVE, and all the system menu items are removed with SET SYSMENU TO.

Several system menu items are created with DEFINE PAD. When you choose a menu item, the choice procedure is executed. choice displays the name of the menu item you choose and the name of the menu bar. SET MARK OF is used with MRKPAD( ) to display or remove the menu item's mark character. If you choose the Exit menu, the original Visual FoxPro system menu is restored.
Copy Code
*** Name this program MARKPAD.PRG ***
CLEAR
SET SYSMENU SAVE
SET SYSMENU TO
SET MARK OF MENU _MSYSMENU TO CHR(4)
PUBLIC glMarkPad
glMarkPad = .T.
DEFINE PAD padSys OF _MSYSMENU PROMPT '\<System'  COLOR SCHEME 3 ;
   KEY ALT+S, ''
DEFINE PAD padEdit OF _MSYSMENU PROMPT '\<Edit'  COLOR SCHEME 3 ;
   KEY ALT+E, ''
DEFINE PAD padRecord OF _MSYSMENU PROMPT '\<Record'  COLOR SCHEME 3 ;
   KEY ALT+R, ''
DEFINE PAD padWindow OF _MSYSMENU PROMPT '\<Window'  COLOR SCHEME 3 KEY ALT+W, ''
DEFINE PAD padReport OF _MSYSMENU PROMPT 'Re\<ports' COLOR SCHEME 3 ;
   KEY ALT+P, ''
DEFINE PAD padExit OF _MSYSMENU PROMPT 'E\<xit'  COLOR SCHEME 3 ;
   KEY ALT+X, ''
ON SELECTION MENU _MSYSMENU ;
   DO choice IN markpad WITH PAD( ), MENU( )

PROCEDURE choice
PARAMETER gcPad, gcMenu
WAIT WINDOW 'You chose ' + gcPad + ;
   ' from menu ' + gcMenu NOWAIT
SET MARK OF PAD (gcPad) OF _MSYSMENU TO ;
   ! MRKPAD('_MSYSMENU', gcPad)
glMarkPad= ! glMarkPad
IF gcPad = 'PADEXIT'
   SET SYSMENU TO DEFAULT
ENDIF

See Also

Other Resources

Functions
MRKBAR( ) Function
SET MARK OF Command


MROW( ) Function

Visual FoxPro 9.0 Language Reference
MROW( ) Function
See Also

Returns the row position of the mouse pointer in the main Visual FoxPro window or in a user-defined window or form.

MROW([cWindowName | 0 [, nScaleMode]])

Parameters

cWindowName

Specifies the name of a window whose mouse-pointer row position MROW( )returns.
0

Specifies that the row position of the mouse pointer is returned for the currently active window or form.
nScaleMode

Specifies the unit of measurement for the value MROW( ) returns. The settings for nScaleMode are:

nScaleMode Description

0

Foxels. (Default)

A foxel is equivalent to the average height and width of a character based on the current font of the form in which an object is contained.

3

Pixels.

A pixel is the smallest element that can be displayed on a screen or printer. Pixels are screen-dependent.

Return Value

Numeric. MROW( ) returns the following under specific conditions:

  • If there is no active user-defined window, and you omit the optional argument, MROW( ) returns the main Visual FoxPro window row position of the mouse pointer.

  • If there is an active user-defined window, and you omit the optional argument, MROW( ) returns the mouse-pointer row coordinate relative to the active user-defined window.

  • If the mouse pointer is positioned outside the user-defined window or if no mouse driver is loaded and there is no output window, MROW( ) returns a value of -1.

Remarks

Using the MROW( ) function without the optional argument 0 may affect the behavior of code on forms when the Form AllowOutput property IS set to false (.F.). For example, the placement of a shortcut menu that is defined in the RightClick event may not display in the proper location if you use the MROW( ) and MCOL( ) functions to determine where the menu is displayed. In this case, be sure to include 0 in the MROW( ) and MCOL( ) functions.

See Also

Other Resources

Functions
AMOUSEOBJ( ) Function
COL( ) Function
GridHitTest Method
ISMOUSE( ) Function
MCOL( ) Function
ROW( ) Function
WCOLS( ) Function
WROWS( ) Function


MTON( ) Function

Visual FoxPro 9.0 Language Reference
MTON( ) Function
See Also Example

Returns a Numeric value from a Currency expression.

MTON(mExpression)

Parameters

mExpression

Specifies a Currency expression whose value MTON( ) returns. mExpression must evaluate to a valid Currency value or Visual FoxPro generates an error. Currency values are created by placing a dollar sign ($) prefix immediately before a Numeric value.

Return Value

Numeric type. MTON( ) returns a value of Numeric type with four decimal places.

Example

The following example creates a currency type variable named gyMoney. TYPE( ) displays Y, indicating the variable is a currency type. MTON( ) is used to convert the variable to a numeric type, and TYPE( ) now displays N, indicating the variable is a numeric type after the conversion.
Copy Code
STORE $24.95 TO gyMoney  && Creates a currency type memory variable
CLEAR
? "gyMoney is type: "
?? TYPE('gyMoney')  && Displays Y, currency type value

gyMoney = MTON(gyMoney)     &&  Converts gyMoney to a numeric value
? "gyMoney is now type: "
?? TYPE('gyMoney')  && Displays N, numeric type value

See Also

Reference

Currency Data Type
Numeric Data Type

Other Resources

Functions
NTOM( ) Function
TYPE( ) Function


MWINDOW( ) Function

Visual FoxPro 9.0 Language Reference
MWINDOW( ) Function
See Also

Returns the name of the window over which the mouse pointer is positioned.

MWINDOW([cWindowName])

Parameters

cWindowName

Specifies a window name. If the mouse pointer is positioned over the specified window, MWINDOW( ) returns true (.T.); otherwise, MWINDOW( ) returns false (.F.).

Return Value

Character, Logical

Remarks

If you omit the optional window name, MWINDOW( ) returns the name of the window over which the mouse pointer is positioned, or an empty string if the mouse pointer is positioned over the main Visual FoxPro window or over any other window that is not part of Visual FoxPro.

See Also

Other Resources

Functions
MCOL( ) Function
MDOWN( ) Function
MROW( ) Function
WONTOP( ) Function
WOUTPUT( ) Function


NDX( ) Function

Visual FoxPro 9.0 Language Reference
NDX( ) Function
See Also

Returns the name of an open index (.IDX) file for the current or specified table.

NDX(nIndexNumber [, nWorkArea | cTableAlias])

Parameters

nIndexNumber

Specifies which .idx file name to return. USE and SET INDEX both support an index file list that makes it possible for you to open .idx files for a table. The order of the file names in this index file list determines which .idx file name NDX( ) returns. For example, if nIndexNumber is 1, NDX( ) returns the name of the first .idx file in the index file list; if nIndexNumber is 2, NDX( ) returns the second .idx file name, and so on. NDX( ) ignores names of compound index (.cdx) files in the index file list. NDX( ) returns an empty string if nIndexNumber is greater than the number of .idx files in the index file list.
nWorkArea

Specifies the work area number for .IDX files open in a work area other than the current one. NDX( ) returns an empty string if no table is open in the work area you specify. If you omit nWorkArea, NDX( ) returns the names of .idx files open with the table in the current work area.
cTableAlias

Specifies the table alias for .idx files open in a work area other than the current one. If no table has the alias you include, Visual FoxPro generates an error message. If you omit cTableAlias, NDX( ) returns the names of .idx files open with the table in the current work area.

Return Value

Character

Remarks

The CDX( ) and MDX( ) functions can be used to return the names of open compound (.cdx) index files.

In Visual FoxPro for Windows, when SET FULLPATH is ON, NDX( ) returns the path to the .idx file with the .idx file name. When SET FULLPATH is OFF, NDX( ) returns the drive the .idx file resides on with the .idx file name.

See Also

Other Resources

Functions
CDX( ) Function
INDEX Command
MDX( ) Function
SET FULLPATH Command
SET INDEX Command
SYS(14) - Index Expression
TAG( ) Function
USE Command


NEWOBJECT( ) Function

Visual FoxPro 9.0 Language Reference
NEWOBJECT( ) Function
See Also

Creates a new class or object directly from a visual class library (.vcx) file or program (.prg) file without opening the file.

NEWOBJECT(cClassName [, cModule [, cInApplication | 0
   [, eParameter1, eParameter2, ...]]])

Parameters

cClassName

Specifies the class or object from which the new class or object is created.
cModule

Specifies a .vcx file or Visual FoxPro program (.prg, .fxp, .mpr, .app, .exe, and so on) containing the class or object specified with cClassName. The default is a .vcx file. If you specify a program file, you must include an extension.
Note:
A class library can have an alias. To specify a class or object from a class library with an alias, include the class library alias followed by a period and the object name.

When possible, specify the compiled program name (.fxp) when a class is stored in a program file (.prg). This ensures that the class is loaded from the proper class definition file. If cModule is omitted, or is the empty string or the null value, Visual FoxPro searches for the class or object in the following order:
  • Visual FoxPro base classes.

  • Classes in the current program.

  • Class libraries opened with SET CLASSLIB.

  • Classes in procedure files opened with SET PROCEDURE.

  • Classes in the Visual FoxPro program execution chain.

  • The OLE registry if SET OLEOBJECT is ON.

cInApplication

Specifies the Visual FoxPro application (.exe or .app) containing the .vcx file you specify with cModule. You must include an extension for the application. CInApplication is ignored if cModule is omitted, or if cInApplication is the empty string or the null value. If you want to use the cInApplication parameter, you must specify the name of .vcx file for cModule. You cannot pass the name of a .prg file or compiled program (.fxp).
0

Specifies that the class or object is instantiated without executing any of the event or method code in the class or object. This feature is not supported in runtime applications. All child classes or objects of the parent class are also instantiated. The event or method code in the child class or object isn't executed. This option is provides the ability to view the structure of a class or object (with the AMEMBERS( ) Function, for example) without opening the class or object in the Class or Form Designer. Note that code in the class or object should never be executed - code execution is not supported and can make Visual FoxPro unstable. You should never explicitly call an event or method, or set properties. Setting properties can call Access and Assign methods.
eParameter1, eParameter2, ...

Specifies optional parameters that are passed to the Init event procedure for the class or object.

Return Value

Object

Remarks

To assign the object reference returned by NEWOBJECT( ) to a variable or array element, use the equal sign (=) or STORE command. If an object assigned to a variable or array element is released, the variable or array element contains the null value. To remove the variable or array element from memory, use the RELEASE command.

For NEWOBJECT( ), Visual FoxPro performs an internal SET CLASSLIB or SET PROCEDURE for the second or third parameters using the ADDITIVE clause where the parameters are first used to determine the search order. If these parameters already exist in the SET CLASSLIB or SET PROCEDURE list, Visual FoxPro rearranges the order in the list so they come first. Visual FoxPro then locates all the classes, creates the object, and calls the Init events. Finally, Visual FoxPro restores the original SET CLASSLIB or SET PROCEDURE list if the installation did not change list.

OLE objects are created with the following syntax for cClassName:

Copy Code
ApplicationName.Class

For example, to create a Microsoft Excel worksheet, which supports Automation, use the following syntax:

Copy Code
oExcelSheet = NEWOBJECT('Excel.Sheet')

See Also

Other Resources

Functions
Class Designer
CREATE CLASS Command
CREATE CLASSLIB Command
CREATEOBJECT( ) Function
DEFINE CLASS Command
NewObject Method


NORMALIZE( ) Function

Visual FoxPro 9.0 Language Reference
NORMALIZE( ) Function
See Also

Converts a character expression, supplied by a user, into a form that can be compared with Visual FoxPro function return values.

NORMALIZE(cExpression)

Parameters

cExpression

Specifies the character expression to normalize.

Return Value

Character

Remarks

NORMALIZE( ) returns a character string from the character expression cExpression with the following changes:

  • The character expression is converted to uppercase. However, embedded strings are not changed. An example of an embedded string is "Hello" in the character expression "LEFT('Hello',1)".

  • Any abbreviated Visual FoxPro keywords in the character expression are expanded to their full length.

  • Any -> operators separating aliases from field names are converted to periods.

  • The syntax of any Visual FoxPro commands or functions within the character expression is checked, although the expression is not evaluated. If the syntax is incorrect, Visual FoxPro generates a syntax error. NORMALIZE( ) does not check for the existence of any fields, tables, memory variables, user-defined functions, or other references in the character expression.

For example, a user may enter an index expression like the following in the Expression Builder:

Copy Code
UPPE(cust->lname) + UPPE(cust->fname)

While this is a valid Visual FoxPro index key expression, it's difficult to compare this to the return values from a Visual FoxPro function like KEY( ). NORMALIZE( ) returns the following character string for the expression above:

Copy Code
UPPER(CUST.LNAME) + UPPER(CUST.FNAME)

This can be easily compared to the value returned by a function like KEY( ), making it possible for you, in this example, to determine if an index or index tag with the user-supplied index expression already exists.

See Also

Other Resources

Functions
EVALUATE( ) Function
ISUPPER( ) Function
PROPER( ) Function
UPPER( ) Function


NTOM( ) Function

Visual FoxPro 9.0 Language Reference
NTOM( ) Function
See Also Example

Returns a Currency value from a Numeric expression.

NTOM(nExpression)

Parameters

nExpression

Specifies a numeric expression whose Currency value NTOM( ) returns. If nExpression has more than four decimal places, it is rounded to four decimal places. If nExpression has less than four decimals places, it is padded with zeros until four decimal places are created.

Return Value

Currency type. NTOM( ) returns a value of Currency type with four decimal places.

Example

The following example creates a numeric type variable named gnNumeric. TYPE( ) displays N, indicating the variable is a numeric type. NTOM( ) is used to convert the variable to a currency type, and TYPE( ) now displays Y, indicating the variable is a currency type after the conversion.
Copy Code
STORE 24.95 TO gnNumeric  && Creates a numeric type memory variable
CLEAR
? "gnNumeric is type: "
?? TYPE('gnNumeric')  && Displays N, numeric type value

gnNumeric= NTOM(gnNumeric)     &&  Converts gnNumeric to a currency value
? "gnNumeric is now type: "
?? TYPE('gnNumeric')  && Displays Y, currency type value

See Also

Reference

Currency Data Type
Numeric Data Type

Other Resources

Functions
MTON( ) Function
TYPE( ) Function


NUMLOCK( ) Function

Visual FoxPro 9.0 Language Reference
NUMLOCK( ) Function
See Also Example

Returns the current mode of the NUM LOCK key or sets the mode of the NUM LOCK key on or off.

NUMLOCK([lExpression])

Parameters

lExpression

Turns the NUM LOCK key on or off. If lExpression is true (.T.), the NUM LOCK key is turned on; if lExpression is false (.F.), the NUM LOCK key is turned off. NUMLOCK( ) returns a logical value corresponding to the NUM LOCK key setting before NUMLOCK(.T.) or NUMLOCK(.F.) is issued.

Return Value

Logical

Remarks

NUMLOCK( ) returns true (.T.) if the NUM LOCK key is on (pressing a key on the numeric keypad returns a number), or false (.F.) if NUM LOCK is off (pressing a key on the numeric keypad moves the cursor).

Example

In the following example, the equal sign (=) is used to execute NUMLOCK( ) without returning a value.
Copy Code
gcOldLock = NUMLOCK( )  && Save original setting
WAIT WINDOW 'Press a key to turn Num Lock on'
= NUMLOCK(.T.)  && Turn Num Lock on
WAIT WINDOW 'Press a key to turn Num Lock off'
= NUMLOCK(!NUMLOCK( ))  && Toggle Num Lock to the opposite value
WAIT WINDOW 'Press a key to restore original Num Lock setting'
= NUMLOCK(gcOldLock)     && Return to original setting

See Also

Other Resources

Functions
CAPSLOCK( ) Function
INSMODE( ) Function


NVL( ) Function

Visual FoxPro 9.0 Language Reference
NVL( ) Function
See Also Example

Returns a non-null value from two expressions.

NVL(eExpression1, eExpression2)

Parameters

eExpression1, eExpression2

NVL( ) returns eExpression2 if eExpression1 evaluates to a null value. NVL( ) returns eExpression1 if eExpression1 is not a null value. eExpression1 and eExpression2 may be any data type. NVL( ) returns .NULL. if both eExpression1 and eExpression2 both evaluate to the null value.

Return Value

Character, Date, DateTime, Numeric, Currency, Logical, or the null value

Remarks

Use NVL( ) to remove null values from calculations or operations where null values are not supported or are not relevant.

Example

The following example creates a memory variable named glMyNull that contains the null value. NVL( ) is used to return a non-null value from glMyNull and another expression.
Copy Code
STORE .NULL. TO glMyNull  && A memory variable containing the null value
CLEAR
? NVL(.T., glMyNull)  && Displays .T.
? NVL(glMyNull, glMyNull)  && Displays .NULL.

See Also

Other Resources

Functions
ISNULL( ) Function
SET NULL Command


OBJTOCLIENT( ) Function

Visual FoxPro 9.0 Language Reference
OBJTOCLIENT( ) Function
See Also Example

Returns a position or dimension of a control or object relative to its form.

OBJTOCLIENT(ObjectName, nPosition)

Parameters

ObjectName

Specifies the name of the control or object for which the form position is returned.
nPosition

Specifies which form position or dimension of the control or object is returned. The following table lists the values for nPosition and the corresponding position or dimension returned.

nPosition Position or dimension

1

Top

2

Left

3

Width

4

Height

Return Value

Numeric

Remarks

OBJTOCLIENT( ) returns the position or dimension of a control or object relative to the client area of the form on which it resides. For example, a control or object can be placed on a page in a page frame, and the page frame is placed on a form. The Top, Left, Width, and Height properties return the position or dimension of a control or object relative to the page on which it is placed. However, you can use OBJTOCLIENT( ) to determine the position or dimension of a control or object relative to the form on which the page is placed.

The value returned by OBJTOCLIENT( ) is in pixels.

Example

The following example uses OBJTOCLIENT( ) to display the positions and dimensions of two check boxes relative to the form they're placed on. The Top, Left, Width, and Height properties are also used to display the positions and dimensions of the two check boxes relative to the page frame on which they're placed.

A command button and a page frame are placed on a form. The PageCount property is used to specify the number of pages on the page frame. The Tabs property is set to true (.T.) to specify that the page frame has tabs for each page. Check boxes are placed on each page in different positions.

When a check box is clicked, the Click procedure for the check box is executed. If the check box is checked, the Top, Left, Width, and Height properties are used to display the positions and dimensions of the check box relative to the page frame, and OBJTOCLIENT( ) is used to display the positions and dimensions of the check box relative to the form. If the check box is unchecked, the main Microsoft Visual FoxPro window is cleared.
Copy Code
CLEAR
STORE _DBLCLICK TO gnDblClick  && Save double-click value
STORE 0.05 TO _DBLCLICK  && Make double-click unlikely

frmMyForm = CREATEOBJECT('Form')  && Create a form
frmMyForm.Closable = .f.  && Disable the window pop-up menu

frmMyForm.Move(150,10)  && Move the form

frmMyForm.AddObject('cmbCommand1','cmdMyCmdBtn')  && Add Command button
frmMyForm.AddObject('pgfPageFrame1','pgfMyPageFrame')  && Add PageFrame
frmMyForm.pgfPageFrame1.Page1.AddObject('chkCheckBox1','chkMyCheckBox1')
frmMyForm.pgfPageFrame1.Page2.AddObject('chkCheckBox2','chkMyCheckBox2')

frmMyForm.cmbCommand1.Visible =.T.  && "Quit" Command button visible
frmMyForm.pgfPageFrame1.Visible =.T.  && PageFrame visible
frmMyForm.pgfPageFrame1.Page1.chkCheckBox1.Visible =.T.
frmMyForm.pgfPageFrame1.Page2.chkCheckBox2.Visible =.T.

frmMyForm.SHOW  && Display the form
READ EVENTS  && Start event processing

DEFINE CLASS cmdMyCmdBtn AS CommandButton  && Create Command button
   Caption = '\<Quit'  && Caption on the Command button
   Cancel = .T.  && Default Cancel Command button (Esc)
   Left = 125  && Command button column
   Top = 210  && Command button row
   Height = 25  && Command button height

   PROCEDURE Click
      CLEAR EVENTS  && Stop event processing, close Form
      CLEAR  && Clear main Visual FoxPro window
      STORE gnDblClick TO _DBLCLICK  && Restore double-click value
ENDDEFINE

DEFINE CLASS pgfMyPageFrame AS PageFrame  && Create PageFrame
   Left = 10  && PageFrame  column
   Top = 10  && PageFrame  row
   Height = 175  && PageFrame  height
   Width = 350  && PageFrame  height
   PageCount = 2  && 2 Pages on the PageFrame
   Tabs = .T.  && Tabs visible
ENDDEFINE

DEFINE CLASS chkMyCheckBox1 AS CheckBox  && Create first Check Box
   Top = 0
   Width = 200
   Caption = 'Display Position'

PROCEDURE Click
   DO CASE
      CASE ThisForm.pgfPageFrame1.Page1.chkCheckBox1.Value = 0
         ACTIVATE SCREEN
         CLEAR
      CASE ThisForm.pgfPageFrame1.Page1.chkCheckBox1.Value = 1
         ACTIVATE SCREEN
         CLEAR
         ? 'Positions relative'
         ? 'to PageFrame:'
         ?
         ? 'Top: '
         ?? ALLTRIM(STR;
            (ThisForm.pgfPageFrame1.Page1.chkCheckBox1.Top))
         ? 'Left: '
         ?? ALLTRIM(STR;
            (ThisForm.pgfPageFrame1.Page1.chkCheckBox1.Left))
         ? 'Width: '
         ?? ALLTRIM(STR;
            (ThisForm.pgfPageFrame1.Page1.chkCheckBox1.Width))
         ? 'Height: '
         ?? ALLTRIM(STR;
            (ThisForm.pgfPageFrame1.Page1.chkCheckBox1.Height))
         ?
         ? 'Positions relative'
         ? 'to Form:'
         ?
         ? 'Top: '
         ?? ALLTRIM(STR(OBJTOCLIENT;
            (ThisForm.pgfPageFrame1.Page1.chkCheckBox1,1)))
         ? 'Left: '
         ?? ALLTRIM(STR(OBJTOCLIENT;
            (ThisForm.pgfPageFrame1.Page1.chkCheckBox1,2)))
         ? 'Width: '
         ?? ALLTRIM(STR(OBJTOCLIENT;
            (ThisForm.pgfPageFrame1.Page1.chkCheckBox1,3)))
         ? 'Height: '
         ?? ALLTRIM(STR(OBJTOCLIENT(ThisForm.pgfPageFrame1.Page1.chkCheckBox1,4)))
   ENDCASE
ENDDEFINE

DEFINE CLASS chkMyCheckBox2 AS CheckBox  && Create second Check Box
   Top = 30
   Left = 175
   Width = 200
   Caption = 'Display Position'

PROCEDURE CLICK
   DO CASE
      CASE ThisForm.pgfPageFrame1.Page2.chkCheckBox2.Value = 0
         ACTIVATE SCREEN
         CLEAR
      CASE ThisForm.pgfPageFrame1.Page2.chkCheckBox2.Value = 1
         ACTIVATE SCREEN
         CLEAR
         ? 'Positions relative'
         ? 'to PageFrame:'
         ?
         ? 'Top: '
         ?? ALLTRIM(STR(ThisForm.pgfPageFrame1.Page2.chkCheckBox2.Top))
         ? 'Left: '
         ?? ALLTRIM(STR;
            (ThisForm.pgfPageFrame1.Page2.chkCheckBox2.Left))
         ? 'Width: '
         ?? ALLTRIM(STR;
            (ThisForm.pgfPageFrame1.Page2.chkCheckBox2.Width))
         ? 'Height: '
         ?? ALLTRIM(STR;
            (ThisForm.pgfPageFrame1.Page2.chkCheckBox2.Height))

         ?
         ? 'Positions relative'
         ? 'to Form:'
         ?
         ? 'Top: '
         ?? ALLTRIM(STR(OBJTOCLIENT;
            (ThisForm.pgfPageFrame1.Page2.chkCheckBox2,1)))
         ? 'Left: '
         ?? ALLTRIM(STR(OBJTOCLIENT;
            (ThisForm.pgfPageFrame1.Page2.chkCheckBox2,2)))
         ? 'Width: '
         ?? ALLTRIM(STR(OBJTOCLIENT;
            (ThisForm.pgfPageFrame1.Page2.chkCheckBox2,3)))
         ? 'Height: '
         ?? ALLTRIM(STR(OBJTOCLIENT;
            (ThisForm.pgfPageFrame1.Page2.chkCheckBox2,4)))
   ENDCASE
ENDDEFINE

See Also

Other Resources

Functions
Height Property
Left Property
Top Property
Width Property


OCCURS( ) Function

Visual FoxPro 9.0 Language Reference
OCCURS( ) Function
See Also Example

Returns the number of times a character expression occurs within another character expression.

OCCURS(cSearchExpression, cExpressionSearched)

Parameters

cSearchExpression

Specifies a character expression that OCCURS( ) searches for within cExpressionSearched.
cExpressionSearched

Specifies the character expression OCCURS( ) searches for cSearchExpression.

Return Value

Numeric

Remarks

OCCURS( ) returns 0 (zero) if cSearchExpression isn't found within cExpressionSearched.

Example

Copy Code
STORE 'abracadabra' TO gcstring
CLEAR
? OCCURS('a', gcstring)  && Displays 5
? OCCURS('b', gcstring)  && Displays 2
? OCCURS('c', gcstring)  && Displays 1
? OCCURS('e', gcstring)  && Displays 0

See Also

Other Resources

Functions
$ Operator
AT( ) Function
ATLINE( ) Function
RAT( ) Function
RATLINE( ) Function
INLIST( ) Function


OLDVAL( ) Function

Visual FoxPro 9.0 Language Reference
OLDVAL( ) Function
See Also Example

Returns original field values for fields that have been modified but not updated.

OLDVAL(cExpression [, cTableAlias | nWorkArea])

Parameters

cExpression

Specifies an expression whose original value OLDVAL( ) returns from a table or a remote data source. cExpression is typically a field or an expression consisting of a set of fields from the table or remote data source.
cTableAlias

Specifies the alias of the table or cursor from which the original field values are returned.
nWorkArea

Specifies the work area of the table or cursor from which the original field values are returned.

Return Value

Character, Currency, Date, DateTime, Double, Float, Integer, Logical, Numeric, or Memo

Remarks

OLDVAL( ) returns original field values for records in a Visual FoxPro table or cursor that has row or table buffering enabled with CURSORSETPROP( ).

If a table in a database or a cursor has validation rules, OLDVAL( ) does not require that row or table buffering be enabled in order to return original field values.

If the record pointer is moved to a different record when row buffering is enabled, or if TABLEUPDATE( ) is issued to commit changes to the record, or there is some other action that causes an update, such as ending a transaction, the fields are updated and the original field values are no longer available.

The data type of the value OLDVAL( ) returns is determined by the expression you specify with cExpression.

The original field values are returned for the table or cursor open in the currently selected work area if OLDVAL( ) is issued without the optional cTableAlias or nWorkArea arguments.

Example

The following example demonstrates how you can use OLDVAL( ) to return original field value for a field in a buffered table. A table named employees is created and INSERT – SQL is used insert the value "Smith" into the cLastName field.

MULTILOCKS is set to ON, a requirement for table buffering. CURSORSETPROP( ) is used to set the buffering mode to optimistic table buffering (5).

The original value of the cLastName field (Smith) is displayed and then the cLastName field is modified with REPLACE. The new value of the cLastName field (Jones) is displayed. The original value of the cLastName field (Smith) is displayed with OLDVAL( ). TABLEUPDATE( ) is then used to commit changes to the table. The updated value of the cLastName field (Jones) is then displayed.
Copy Code
CLOSE DATABASES
CLEAR

* Create new table and add blank record
CREATE TABLE employee (cLastName C(10))
APPEND BLANK

* Insert initial value
INSERT INTO employee (cLastName) VALUES ("Smith")

* Enable and set table buffering
SET MULTILOCKS ON  && Allow table buffering
=CURSORSETPROP("Buffering", 5, "employee" )  && Enable table buffering

* Display initial value
=MESSAGEBOX("Original cLastName value: "+ cLastName, 0, "Results")

* Change record value and display results
REPLACE cLastName WITH "Jones"
=MESSAGEBOX("Modified cLastName value: "+ cLastName, 0, "Results")

* Store the old value of the field to cTemp variable and display results
cTemp=OLDVAL("cLastName", "employee")
=MESSAGEBOX("Original cLastName value: "+ cTemp, 0, "Results")

* Update table and display final value
=TABLEUPDATE(.T.)
=MESSAGEBOX("Final cLastName value: "+ cLastName, 0, "Results")

* Close and delete example table file
USE
DELETE FILE employee.dbf

See Also

Other Resources

Functions
CURVAL( ) Function
GETFLDSTATE( ) Function
TABLEREVERT( ) Function
TABLEUPDATE( ) Function
CURSORSETPROP( ) Function


ON( ) Function

Visual FoxPro 9.0 Language Reference
ON( ) Function
See Also Example

Returns the command assigned to each of these event-handling commands: ON ERROR, ON ESCAPE, ON KEY LABEL, or ON PAGE.

ON(cONCommand [, KeyLabelName])

Parameters

cONCommand

Specifies one of the event-handling commands. Here are the commands and corresponding character expressions to use with ON( ):

Command cONCommand

ON ERROR

ERROR

ON ESCAPE

ESCAPE

ON KEY LABEL

KEY

ON PAGE

PAGE
For example, to return the command currently assigned to ON ERROR, use the following:
Copy Code
? ON('ERROR')
KeyLabelName

Used in ON KEY LABEL to specify a key or key combination to which the command is assigned. Specify KEY in cONCommand and the key label name of the key or key combination in KeyLabelName. For a complete list of key label names, see ON KEY LABEL. For example, to return the command currently assigned to the F7 function key with ON KEY LABEL, use the following:
Copy Code
? ON('KEY', 'F7')

Return Value

Character

Remarks

When an event occurs that is trapped by one of the event-handling commands, the command assigned by the event-handling command executes. ON( ) returns the command you assigned to an event-handling command. ON( ) returns an empty string if a command isn't currently assigned to the event-handling command you specify.

Example

The following example uses ON( ) to display ON ERROR and ON KEY LABEL settings.
Copy Code
ON ERROR DO errorhand
ON KEY LABEL CTRL+F2 WAIT WINDOW 'You pressed ^F2'
ON KEY LABEL ALT+Z DISPLAY MEMORY
CLEAR
? ON('ERROR')  && Displays DO errorhand
? ON('KEY', 'CTRL+F2')  && Displays WAIT WINDOW 'You pressed ^F2'
? ON('KEY', 'ALT+Z')  && Displays DISPLAY MEMORY
ON ERROR
ON KEY LABEL CTRL+F2
ON KEY LABEL ALT+Z

See Also

Other Resources

Functions
INKEY( ) Function
LASTKEY( ) Function
ON ERROR Command
ON ESCAPE Command
ON KEY Command
ON KEY LABEL Command
ON PAGE Command
ON READERROR Command
READKEY( ) Function


ORDER( ) Function

Visual FoxPro 9.0 Language Reference
ORDER( ) Function
See Also Example

Returns the name of the controlling index file or tag for the current or specified table.

ORDER([nWorkArea | cTableAlias [, nPath]])

Parameters

nWorkArea

Specifies the work area of a table whose controlling index file name or controlling tag name ORDER( ) returns.
cTableAlias

Specifies a table alias whose controlling index file name or controlling tag name ORDER( ) returns.
nPath

Specifies that the drive and directory are returned along with the single-entry or compound index file name. The numeric expression nPath can have any value.

Return Value

Character

Remarks

A table can have several index files open simultaneously. However, only one single-entry index file (the controlling index file) or tag from a compound index file (the controlling tag) controls the order in which the table is displayed or accessed. Certain commands, such as SEEK, use the controlling index file or controlling tag to search for records. This function returns the name of the controlling index file or controlling tag.

USE and SET INDEX both support opening more than one index with an index file list. A controlling index file or controlling tag can be designated in this index file list. SET ORDER can also be used to designate a controlling index or controlling tag.

By default, ORDER( ) returns the controlling index file name or controlling tag name for the current work area. ORDER( ) returns the empty string if an order has not been set (SET ORDER TO is issued or there is no controlling index file or tag).

Example

The following example displays index tags and files.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer ORDER cust_id && Opens Customer table
? ORDER( )  && Displays CUST_ID
? ORDER('customer', 1)  && Displays CUSTOMER.CDX

See Also

Other Resources

Functions
INDEX Command
SET INDEX Command
DESCENDING( ) Function
SET ORDER Command
USE Command


OS( ) Function

Visual FoxPro 9.0 Language Reference
OS( ) Function
See Also Example

Returns the name and version number of the operating system under which Microsoft Visual FoxPro is running.

OS([nValue])

Parameters

nValue

Specifies the item to return, according to the following table. nValues

Value Description

1

Specifies that the name and version number of the operating system is returned.

2

DBCS Support. If DBCS (double-byte character sets) are supported, "DBCS" is returned. Otherwise, an empty string is returned

3

Identifies the major version number of the operating system. For example, for Windows 2000, the major version number is 5.

4

Identifies the minor version number of the operating system. For example, for Windows 2000, the minor version number is 0.

5

Identifies the build number of the operating system.

6

Identifies the operating system platform.

7

Contains a string, such as "Service Pack 3", that indicates the latest Service Pack installed on the system. If no Service Pack has been installed, the string is empty.

8

Identifies the major version number of the latest Service Pack installed on the system. For example, for Service Pack 3, the major version number is 3. If no Service Pack has been installed, the value is zero.

9

Identifies the minor version number of the latest Service Pack installed on the system. For example, for Service Pack 3, the minor version number is 0.

10

A set of bit flags that identify the product suites available on the system. See Product Suite bit flag table below for values.

11

Indicates additional information about the system. See Product Type settings table below for values.

Product Suite bit flags:

Value | Meaning
1 | Microsoft Small Business Server is installed.
2 | Windows 2000 Advanced Server or Windows Server 2003, Enterprise Edition, is installed.
4 | Microsoft BackOffice components are installed.
16 | Terminal Services is installed.
32 | Microsoft Small Business Server is installed with the restrictive client license in force.
64 | Windows Embedded NT is installed
128 | Windows 2000 or Windows Server 2003, Datacenter Edition, is installed.
256 | Terminal Services is installed.
512 | Windows XP Home Edition is installed.
1024 | Windows Server 2003, Web Edition, is installed.

Product Type settings:

Value | Meaning
1 | The system is running Windows NT 4.0 Workstation, Windows 2000 Professional, Windows XP Home Edition, or Windows XP Professional.
2 | The system is a domain controller.
3 | The system is a server.

Return Value

Character

Remarks

If you omit the optional argument, this function returns the underlying operating system name and its version number.

Some nValues are not applicable to some operating systems. In such cases, the OS( ) function returns "0" or "", an empty string.

Example

Copy Code
? OS( )
? OS(1)
? OS(2)

See Also

Other Resources

Functions
DISKSPACE( ) Function
GETENV( ) Function
VERSION( ) Function


PAD( ) Function

Visual FoxPro 9.0 Language Reference
PAD( ) Function
See Also Example

Returns as an uppercase character string the menu title most recently chosen from a menu bar, or returns a logical value indicating if a menu title is defined for an active menu bar.

PAD([cMenuTitle [, cMenuBarName]])

Parameters

cMenuTitle

Specifies the name of a menu title in a menu bar. Include this argument to test if the menu title is defined for an active menu bar. A logical true (.T.) is returned if the menu title is defined; otherwise a logical false (.F.) is returned.
cMenuBarName

Specifies the name of the menu bar containing the menu title cMenuTitle. If cMenuBarName is omitted, the menu title is assumed to be in the currently active menu bar.

Return Value

Character or Logical

Remarks

A menu bar must be defined and active for PAD( ) to return a menu title. Menu bars are created and activated with DEFINE MENU and ACTIVATE MENU.

You can also use PAD( ) with the Visual FoxPro system menu bar.

PAD( ) (issued without any of its optional arguments) returns an empty string if a menu bar isn't defined and active or you issue PAD( ) from the Command window.

Example

In this example, PAD( ) is used to pass a menu title to a procedure.

The current Visual FoxPro system menu bar is saved to memory with SET SYSMENU SAVE , and all system menu titles are removed with SET SYSMENU TO.

Several system menu titles are created with DEFINE PAD. When a menu title is chosen, PAD( ) is used to pass the menu title to the procedure named choice. choice displays the menu title chosen and the name of the menu bar. If you choose the Exit menu title, the original Visual FoxPro system menu is restored.
Copy Code
*** Name this program PADEXAM.PRG ***
CLEAR
SET SYSMENU SAVE
SET SYSMENU TO
DEFINE PAD padSys OF _MSYSMENU PROMPT '\<System' COLOR SCHEME 3 ;
   KEY ALT+S, ''
DEFINE PAD padEdit OF _MSYSMENU PROMPT '\<Edit' COLOR SCHEME 3 ;
   KEY ALT+E, ''
DEFINE PAD padRecord OF _MSYSMENU PROMPT '\<Record' COLOR SCHEME 3 ;
   KEY ALT+R, ''
DEFINE PAD padWindow OF _MSYSMENU PROMPT '\<Window' COLOR SCHEME 3 ;
   KEY ALT+W, ''
DEFINE PAD padReport OF _MSYSMENU PROMPT 'Re\<ports' COLOR SCHEME 3 KEY ALT+P, ''
DEFINE PAD padExit OF _MSYSMENU PROMPT 'E\<xit' COLOR SCHEME 3 ;
   KEY ALT+X, ''
ON SELECTION MENU _MSYSMENU ;
   DO choice IN padexam WITH PAD( ), MENU( )
PROCEDURE choice
PARAMETERS gcPad, gcMenu
WAIT WINDOW 'You chose ' + gcPad + ;
   ' from menu ' + gcMenu NOWAIT
IF gcPad = 'PADEXIT'
   SET SYSMENU TO DEFAULT
ENDIF

See Also

Other Resources

Functions
ACTIVATE MENU Command
BAR( ) Function
DEFINE PAD Command
DEFINE MENU Command
MENU( ) Function
ON PAD Command
ON SELECTION PAD Command
PROMPT( ) Function


PADL( ) | PADR( ) | PADC( ) Functions

Visual FoxPro 9.0 Language Reference
PADL( ) | PADR( ) | PADC( ) Functions
See Also Example

Returns a string from an expression, padded with spaces or characters to a specified length on the left or right sides, or both.

PADL(eExpression, nResultSize [, cPadCharacter])
PADR(eExpression, nResultSize [, cPadCharacter])
PADC(eExpression, nResultSize [, cPadCharacter])

Parameters

eExpression

Specifies the expression to be padded. This expression can be any expression type except a logical expression or a general or picture field.
nResultSize

Specifies the total number of characters in the expression after it is padded.
cPadCharacter

Specifies the value to use for padding. This value is repeated as necessary to pad the expression to the specified number of characters. If you omit cPadCharacter, spaces (ASCII character 32) are used for padding.

Return Value

Character

Remarks

PADL( ) inserts padding on the left, PADR( ) inserts padding on the right, and PADC( ) inserts padding on both sides.

Example

Copy Code
STORE 'TITLE' TO gcString
CLEAR
? PADL(gcString, 40, '=')
? PADR(gcString, 40, '=')
? PADC(gcString, 40, '=')

See Also

Other Resources

Functions
ALLTRIM( ) Function
LEFT( ) Function
LTRIM( ) Function
RIGHT( ) Function
STUFF( ) Function
TRIM( ) Function


PARAMETERS( ) Function

Visual FoxPro 9.0 Language Reference
PARAMETERS( ) Function
See Also

Returns the number of parameters passed to the most recently called program, procedure, or user-defined function.

PARAMETERS( )

Return Value

Numeric

Remarks

PARAMETERS( ) is useful for determining how many parameters are passed to a program, procedure, or user-defined function.

Note:
The value returned by PARAMETERS() is reset every time a program, procedure, or user-defined function is called or when ON KEY LABEL is executed. Unlike PARAMETERS(), the PCOUNT() function does not get reset, so PCOUNT() may be preferable in most programming situations.

Examples

Example 1 calls a procedure and displays in a wait window the number of parameters passed.

Example 2 uses a procedure to display the average of 4 values.

Copy Code
* Example 1
DO testpar WITH 1,2,3

PROCEDURE testpar
PARAMETERS gn1,gn2,gn3
gcMessage = 'PARAMETERS( ) ='+ALLTRIM(STR(PARAMETERS( )))
WAIT WINDOW (gcMessage)
RETURN

* Example 2
SET TALK OFF
gnVal1 = 10
gnVal2 = 20
gnVal3 = 30
gnVal4 = 15
gnMin = getavg(gnVal1, gnVal2, gnVal3, gnVal4)
? 'Average value is '
?? gnMin

* This user-defined function permits up to 9 parameters to be passed.
* It uses the PARAMETERS( ) function to determine how many
* were passed and returns the average value.

FUNCTION getavg
PARAMETERS gnPara1,gnPara2,gnPara3,gnPara4,gnPara5, ;
   gnPara6,gnPara7,gnPara8,gnPara9
IF PARAMETERS( ) = 0
   RETURN 0
ENDIF
gnResult = 0
FOR gnCount = 1 to PARAMETERS( )
   gcCompare = 'gnPara' +(STR(gnCount,1))
   gnResult = gnResult + EVAL(gcCompare)
ENDFOR
gnResult = gnResult / (gnCount - 1)
RETURN gnResult

See Also

Other Resources

Functions
DO Command
FUNCTION Command
LPARAMETERS Command
LOCAL Command
PARAMETERS Command
PCOUNT( ) Function
PRIVATE Command
PROCEDURE Command
PUBLIC Command
SET UDFPARMS Command


PAYMENT( ) Function

Visual FoxPro 9.0 Language Reference
PAYMENT( ) Function
See Also Example

Returns the amount of each periodic payment on a fixed-interest loan.

PAYMENT(nPrincipal, nInterestRate, nPayments)

Parameters

nPrincipal

Specifies the beginning principal of the loan.
nInterestRate

Specifies the fixed interest rate per period. If monthly payments are made on the loan but the interest rate is annual, divide the annual interest rate by 12.
nPayments

Specifies the total number of payments to be made on the loan.

Return Value

Numeric

Remarks

PAYMENT( ) assumes a constant periodic interest rate and assumes that payments are made at the end of each period.

Example

Copy Code
STORE 100000 to gnPrincipal     && $100,000 beginning principal
STORE .105/12 TO gnInterest  && 10.5% annual interest rate
STORE (20*12) TO gnPayments     && 20 years of monthly payments
CLEAR
? PAYMENT(gnPrincipal, gnInterest, gnPayments)  && Displays 998.38

See Also

Other Resources

Functions
CALCULATE Command
FV( ) Function
PV( ) Function


PCOL( ) Function

Visual FoxPro 9.0 Language Reference
PCOL( ) Function
See Also Example

Returns the current column position of the printer's print head.

PCOL( )

Return Value

Numeric

Remarks

The value PCOL( ) returns is relative to the current setting of the left printer margin. You can set the left margin with SET MARGIN or by storing a value to the system memory variable _PLOFFSET.

PCOL( ) is especially useful for relative addressing of printed text.

You can use the $ operator in place of PCOL( ).

Example

Copy Code
CLEAR
@ PROW( ), PCOL( )+12 SAY 'Contact person'
@ PROW( ), $+12 SAY 'Contact person'

See Also

Other Resources

Functions
COL( ) Function
ROW( ) Function
PROW( ) Function


PCOUNT( ) Function

Visual FoxPro 9.0 Language Reference
PCOUNT( ) Function
See Also

Returns the number of parameters passed to the current program, procedure, or user-defined function.

PCOUNT( )

Return Value

Numeric

Remarks

PCOUNT( ) is useful for determining how many parameters are passed to the current program, procedure, or user-defined function.

Examples

Example 1 calls a procedure and displays in a wait window the number of parameters passed.

Example 2 uses a procedure to display the average of 4 values.

Example 1

Copy Code
DO testpar WITH 1,2,3

PROCEDURE testpar
PARAMETERS gn1,gn2,gn3
gcMessage = 'PCOUNT( ) ='+ALLTRIM(STR(PCOUNT( )))
WAIT WINDOW (gcMessage)
RETURN

Example 2

Copy Code
SET TALK OFF
gnVal1 = 10
gnVal2 = 20
gnVal3 = 30
gnVal4 = 15
gnMin = getavg(gnVal1, gnVal2, gnVal3, gnVal4)
? 'Average value is '
?? gnMin

* This user-defined function permits up to 9 parameters to be passed.
* It uses the PCOUNT( ) function to determine how many
* were passed and returns the average value.

FUNCTION getavg
PARAMETERS gnPara1,gnPara2,gnPara3,gnPara4,gnPara5, ;
   gnPara6,gnPara7,gnPara8,gnPara9
IF PCOUNT( ) = 0
   RETURN 0
ENDIF
gnResult = 0
FOR gnCount = 1 to PARAMETERS( )
   gcCompare = 'gnPara' +(STR(gnCount,1))
   gnResult = gnResult + EVAL(gcCompare)
ENDFOR
gnResult = gnResult / (gnCount - 1)
RETURN gnResult

See Also

Other Resources

Functions
DO Command
FUNCTION Command
LPARAMETERS Command
LOCAL Command
PARAMETERS Command
PARAMETERS( ) Function
PRIVATE Command
PROCEDURE Command
PUBLIC Command
SET UDFPARMS Command


PEMSTATUS( ) Function

Visual FoxPro 9.0 Language Reference
PEMSTATUS( ) Function
See Also

Retrieves an attribute for a property, event, method, or object.

PEMSTATUS(oObjectName | cClassName, cProperty | cEvent | cMethod
   | cObject, nAttribute)

Parameters

oObjectName

Specifies the object for which the property, event, method, or object attribute to return. oObjectName can be any expression that evaluates to an object, such as an object reference, an object memory variable, or an object array element. If oObjectName is a container object such as a form, you can determine attributes for objects in the container object.
cClassName

Specifies the class for which the property, event, or method attribute to return.
cProperty

Specifies the property for which the attribute to return.
cEvent

Specifies the event for which the attribute to return.
cMethod

Specifies the method for which the attribute to return.
cObject

Specifies the object for which the attribute to return. For example, you can use the AddObject method to add an object to a container object, and then use PEMSTATUS( ) to return information about the object added to the container object.
nAttribute

Specifies a numeric value that determines the property, event, or method attribute to return. The following table lists the values for nAttribute and the corresponding property, event, or method attribute returned.

nAttribute Property, event, or method attribute

0

Changed.

If the property value, method, or event has changed, PEMSTATUS( ) returns a logical True (.T.). Otherwise, PEMSTATUS( ) returns logical False (.F.).

1

Read-only (properties only).

If the property is read-only, PEMSTATUS( ) returns a logical True (.T.). Otherwise, PEMSTATUS( ) returns a logical False (.F.).

2

Protected.

If the property, event, or method is protected, PEMSTATUS( ) returns a logical True (.T.). Otherwise, PEMSTATUS( ) returns a logical False (.F.).

3

Type.

PEMSTATUS( ) returns a character string, for example, Property, Event, Method, or Object, indicating whether cProperty, cEvent, cMethod or cObject is a property, event, method or object.

4

User-defined.

If the property, event, or method is a user-defined property, event, or method, PEMSTATUS( ) returns a logical True (.T.). Otherwise, PEMSTATUS( ) returns a logical False (.F.).

5

Defined property, event, method, or object.

If the property, event, method, or object exists for oObjectName or cClassName, PEMSTATUS( ) returns a logical True (.T.). Otherwise, or for hidden native properties, PEMSTATUS( ) returns a logical False (.F.).

6

Inherited property, event, method, or object.

If the property, event, method, or object for oObjectName or cClassName was inherited from another object or class, PEMSTATUS( ) returns logical True (.T.). Otherwise, PEMSTATUS( ) returns a logical False (.F.).

Return Value

Character or Logical. PEMSTATUS( ) returns a character string or logical value for the attribute specified.

Remarks

PEMSTATUS( ) does not detect for changes in specific array elements if the array is passed.

See Also

Other Resources

Functions
CREATE FORM Command
GETPEM( ) Function
SYS(1269) – Property Information
SYS(1270) – Object Location
SYS(1271) - Object's .SCX File
SYS(1272) – Object Hierarchy


PI( ) Function

Visual FoxPro 9.0 Language Reference
PI( ) Function
See Also Example

Returns the numeric constant pi.

PI( )

Return Value

Numeric

Remarks

The numeric constant pi (3.141592) is the ratio of the circumference of a circle to its diameter.

The number of decimal places displayed in the value returned by PI( ) is determined by SET DECIMALS.

Example

Copy Code
CLEAR
? PI( ) && Displays 3.14
STORE 2.30 TO gnRadius
STORE PI( ) * gnRadius^2 TO gnArea
? gnArea  && Displays 16.6190

See Also

Other Resources

Functions
SET DECIMALS Command
STORE Command
Circle Method


POPUP( ) Function

Visual FoxPro 9.0 Language Reference
POPUP( ) Function
See Also

Returns as a string the name of the active menu, or a logical value indicating if a menu has been defined.

POPUP([cMenuName])

Parameters

cMenuName

Returns a logical value indicating if cMenuName has been defined. POPUP( ) returns true (.T.) if the menu you specify has been defined; otherwise POPUP( ) returns false (.F.).

Return Value

Character or Logical

Remarks

POPUP( ) returns the name of the active menu as a character string if you omit the optional cMenuName argument. A menu must be defined and active for POPUP( ) to return its name. Menus are created and activated with DEFINE POPUP and ACTIVATE POPUP. The menu can also be a Visual FoxPro system menu. POPUP( ) returns an empty string if a menu isn't defined and active or you issue POPUP( ) from the Command window.

See Also

Other Resources

Commands
ACTIVATE POPUP Command
BAR( ) Function
DEFINE BAR Command
DEFINE POPUP Command
ON SELECTION POPUP Command


PRIMARY( ) Function

Visual FoxPro 9.0 Language Reference
PRIMARY( ) Function
See Also Example

Returns true (.T.) if an index tag is a primary index tag; otherwise, returns false (.F.).

PRIMARY([nIndexNumber] [, nWorkArea | cTableAlias])

Parameters

nIndexNumber

Specifies the number of the index tag for which PRIMARY( ) returns the primary status. PRIMARY( ) returns the primary status in the following order as nIndexNumber increases from 1 to the total number of structural compound and independent compound index tags.
  1. Primary status for each tag in the structural compound index (if one is present) are returned first. The primary status is returned for the tags in the order the tags are created in the structural index.

  2. Primary status for each tag in any open, independent compound indexes are returned next. The primary status is returned for the tags in the order in which the tags are created in the independent compound indexes.

    If you omit nIndexNumber, PRIMARY( ) checks the master controlling index tag to see if it's a primary index tag. If there is no master controlling index tag, PRIMARY( ) returns false (.F.).

nWorkArea

Specifies the work area of the index tag specified with nIndexNumber.
cTableAlias

Specifies the work area of the index tag specified with nIndexNumber. If you omit nWorkArea and cTableAlias, PRIMARY( ) checks the index tag in the currently selected work area to see if it's a primary index tag.

Return Value

Logical

Example

The following example opens the customer table in the database. FOR ... ENDFOR is used to create a loop in which the primary status of each index tag in the customer structural index is checked. The name of each structural index tag is displayed with its primary status.
Copy Code
CLOSE DATABASES
SET PATH TO (HOME(2) + 'Data\')   && Sets path to database
OPEN DATABASE testdata  && Open testdata database
USE Customer     && Open customer table

FOR nCount = 1 TO TAGCOUNT( )
   IF !EMPTY(TAG(nCount))  && Checks for tags in the index
   ? TAG(nCount)  && Display tag name
   ? PRIMARY(nCount)     && Display primary status
   ELSE
      EXIT  && Exit the loop when no more tags are found
   ENDIF
ENDFOR

See Also

Other Resources

System Variables
ALTER TABLE – SQL Command
CANDIDATE( ) Function
CREATE TABLE – SQL Command
INDEX Command


PRINTSTATUS( ) Function

Visual FoxPro 9.0 Language Reference
PRINTSTATUS( ) Function
See Also Example

Returns the status of the printer. Included for backward compatibility.

PRINTSTATUS( )

Return Value

Logical value. For versions of Visual FoxPro running on Windows, PRINTSTATUS( ) always returns True (.T.) if the printer is connected through the Windows Control Panel.

In prior versions, if the printer or print device is online, PRINTSTATUS( ) returns True (.T.); otherwise, it returns False (.F.).

Remarks

PRINTSTATUS( ) functions similarly to SYS(13). For more information, see SYS(13) - Printer Status.

Example

Copy Code
? PRINTSTATUS( )
*** Program Example ***
STORE PRINTSTATUS( ) TO glReady
IF NOT glReady
   WAIT 'Make sure printer is attached and turned on!' WINDOW
ELSE
   WAIT 'Printer is ready!' WINDOW
ENDIF

See Also

Other Resources

Functions
SET PRINTER Command
SET DEVICE Command
SYS(13) – Printer Status
PRINTJOB ... ENDPRINTJOB Command


PRMBAR( ) Function

Visual FoxPro 9.0 Language Reference
PRMBAR( ) Function
See Also

Returns the text of a menu item.

PRMBAR(cMenuName, nMenuItemNumber)

Parameters

cMenuName

Specifies the menu name.
nMenuItemNumber

Specifies the number of the menu item whose text PRMBAR( ) returns. For example, if nMenuItemNumber is 1, the text of the first menu item is returned; if nMenuItemNumber is 2, the text of the second menu item is returned, and so on. The expression must be at least 1 and no greater than the number of menu items in the menu.

Return Value

Character

Remarks

Menus are created with DEFINE POPUP, which creates the menu, and DEFINE BAR, which creates the menu items in the menu. PRMBAR( ) also works with a Visual FoxPro system menu. PRMBAR( ) returns the text that appears on the menu item. The menu doesn't have to be active.

If a menu item was created using the backslash and less-than characters (\<) to create an access key, or a backslash (\) to disable the menu item, PRMBAR( ) returns only the menu item text; it doesn't include these special characters. PRMBAR( ) returns an empty string when a menu item is a separator created with the backslash and dash (\-) characters.

See Also

Other Resources

Functions
CNTBAR( ) Function
GETBAR( ) Function
DEFINE BAR Command
DEFINE POPUP Command
MRKBAR( ) Function
PRMPAD( ) Function


PRMPAD( ) Function

Visual FoxPro 9.0 Language Reference
PRMPAD( ) Function
See Also Example

Returns the text of a menu title.

PRMPAD(MenuBarName, MenuTitleName)

Parameters

MenuBarName

Specifies the name of the menu bar containing the menu title.
MenuTitleName

Specifies the menu title.

Return Value

Character

Remarks

Menu bars are created with DEFINE MENU, which creates the menu bar, and DEFINE PAD, which creates the menu titles in the menu bar. PRMPAD( ) also works with the Visual FoxPro menu system. A menu bar doesn't have to be active for PRMPAD( ) to return the text for a menu title.

If a menu title was created using the backslash and less-than characters (\<) to create an access key, or a backslash (\) to disable the menu title, PRMPAD( ) returns only the text of the menu title; it doesn't include the special characters.

Example

In the following example, a menu bar named mnuExample is created with three menu titles. The access key and disabled option designators aren't returned from the menu titles named titleTwo and titleThree. The menu bar is activated to show the menu titles and is cleared from the screen and from memory when a menu title is chosen.
Copy Code
CLEAR
SET TALK OFF
STORE 'mnuExample' TO gcPopName

DEFINE MENU mnuExample BAR AT LINE 1
DEFINE PAD titleOne OF mnuExample PROMPT 'This will be returned'
DEFINE PAD titleTwo OF mnuExample PROMPT '\<As will this'
DEFINE PAD titleThree OF mnuExample PROMPT '\And this, too'

=messagebox( PRMPAD('mnuExample', 'titleOne') )
=messagebox( PRMPAD('mnuExample', 'titleTwo') )
=messagebox( PRMPAD(gcPopName, 'titleThree') )

ACTIVATE MENU mnuExample
DEACTIVATE MENU mnuExample
RELEASE MENU mnuExample

See Also

Other Resources

Functions
CNTBAR( ) Function
GETBAR( ) Function
DEFINE BAR Command
DEFINE POPUP Command
MRKPAD( ) Function
PRMBAR( ) Function


PROGRAM( ) Function

Visual FoxPro 9.0 Language Reference
PROGRAM( ) Function
See Also Example

Returns the name of the program at a specified program level, the name of the currently executing program, the current program level, or the name of the program executing when an error occurred.

PROGRAM([nLevel])

Parameters

nLevel

Specifies the number of program levels to search for the program name. The nLevel parameter can range from 0 to the program nesting depth. For more information about program nesting levels, see maximum number of DO calls in Visual FoxPro System Capacities. When nLevel is omitted, PROGRAM( ) returns the name of the currently executing program. If you specify 0 or 1 for nLevel, PROGRAM( ) returns the name of the master program, or the highest-level program. If you specify –1 for nLevel, PROGRAM( ) returns the current program level as a numeric value. However, using PROGRAM(–1) in the Command window always returns zero (0). If nLevel exceeds the program nesting depth, PROGRAM( ) returns an empty string ("").

Return Value

Character or Numeric. PROGRAM( ) returns a program name, the number of the current program level, or an empty string.

Remarks

You can use PROGRAM( ) to help your program recover from errors. The PROGRAM( ) function is similar to SYS(16) - Executing Program File Name.

Example

Copy Code
ON ERROR DO errhand WITH PROGRAM( )
*** The next line should generate an error ***
USE nodatabase
ON ERROR     && Returns to system default error-handling routine
PROCEDURE errhand
PARAMETERS gcProgram
WAIT 'An error occurred in the program ' + gcProgram WINDOW

See Also

Other Resources

Functions
DO Command
LINENO( ) Function
MESSAGE( ) Function
ASTACKINFO( ) Function


PROMPT( ) Function

Visual FoxPro 9.0 Language Reference
PROMPT( ) Function
See Also

Returns the text for a menu title chosen from a menu bar or for a menu item chosen from a menu.

PROMPT( )

Return Value

Character

Remarks

PROMPT( ) returns the text of the menu title last chosen from a menu bar or the menu item last chosen from a menu. The menu bar or menu can be user-defined or a Visual FoxPro system menu bar or menu. If a menu bar or menu isn't active or you press ESC to exit a menu bar or menu, PROMPT( ) returns an empty string.

A menu bar is created with DEFINE MENU, and each menu title in the menu bar is created with DEFINE PAD. A menu is created with DEFINE POPUP, and the menu items in the menu are created with DEFINE BAR.

MENU( ) and POPUP( ) can be used to return the name of the menu bar or menu from which the menu title or menu item is chosen.

See Also

Other Resources

Functions
BAR( ) Function
DEFINE BAR Command
DEFINE MENU Command
DEFINE PAD Command
DEFINE POPUP Command
POPUP( ) Function
PRMBAR( ) Function


PROPER( ) Function

Visual FoxPro 9.0 Language Reference
PROPER( ) Function
See Also Example

Returns from a character expression a string capitalized as appropriate for proper names.

PROPER(cExpression)

Parameters

cExpression

Specifies the character expression from which PROPER( ) returns a capitalized character string.

Return Value

Character

Example

Copy Code
STORE 'Visual FoxPro' TO gcExpr1

CLEAR
? PROPER(gcExpr1)  && Displays "Visual Foxpro"
STORE 'VISUAL FOXPRO' TO gcExpr2
? PROPER(gcExpr2)  && Displays "Visual Foxpro"

See Also

Other Resources

Functions
LOWER( ) Function
UPPER( ) Function
Creating Character Expressions


PROW( ) Function

Visual FoxPro 9.0 Language Reference
PROW( ) Function
See Also Example

Returns the current row number of the printer's print head.

PROW( )

Return Value

Numeric

Remarks

If you issue EJECT, Visual FoxPro resets PROW( ) to 0.

PROW( ) is especially useful for relative addressing of printed text.

Example

In the following example, the two commands return the same result. You can use the $ operator in place of PCOL( ). Both $ and PCOL( ) return the current column position of the printer.
Copy Code
@ PROW( ), PCOL( ) + 12 SAY 'Contact person'
@ PROW( ), $+12 SAY 'Contact person'

See Also

Other Resources

Functions
@ ... SAY Command
COL( ) Function
PCOL( ) Function
ROW( ) Function


PRTINFO( ) Function

Visual FoxPro 9.0 Language Reference
PRTINFO( ) Function
See Also

Returns the current specified printer setting.

PRTINFO(nPrinterSetting [, cPrinterName])

Parameters

nPrinterSetting

Specifies which Visual FoxPro printer setting to return. The following table lists descriptions of the type of printer settings returned.

nPrinterSetting FOXPRO.H Setting returned

1

PRT_ORIENTATION

Paper orientation

2

PRT_PAPERSIZE

Paper size

3

PRT_PAPERLENGTH

Paper length in .1 millimeter increments

4

PRT_PAPERWIDTH

Paper width in .1 millimeter increments

5

PRT_SCALE

Factor by which printer output is scaled

6

PRT_COPIES

Number of copies to print

7

PRT_DEFASOURCE

Default paper source

8

PRT_PRINTQUAL

A positive value that indicates the horizontal resolution in dots per inch (DPI) or a negative value that indicates the print quality.

9

PRT_COLOR

A value that indicates if a color printer rends color or monochrome output

10

PRT_DUPLEX

Duplex mode

11

PRT_YRESOLUTION

The vertical resolution in dots per inch (DPI). If not available, a value of -1 is returned.

12

PRT_TTOPTION

A value that indicates how TrueType® fonts are printed

13

PRT_COLLATE

A value that indicates if output is collated
cPrinterName

Specifies the name of the printer for which information is returned. If cPrinterName is omitted, information is returned for the default printer.

Return Value

Numeric data type. The following tables list values returned when specifying particular values for nPrinterSetting.

If nPrinterSetting is 1, PRTINFO( ) returns the paper orientation as the following:

Return values | Paper orientation
–1 | Information not available
0 | Portrait
1 | Landscape

If nPrinterSetting is 2, PRTINFO( ) returns the paper size as the following:

Return values | Paper size
–1 or value other than listed | Information not available. Use nPrinterSetting = 3 and nPrinterSetting = 4 to return the paper size.
1 | Letter, 8 1/2 x 11 in
2 | Letter Small, 8 1/2 x 11 in
3 | Tabloid, 11 x 17 in
4 | Ledger, 17 x 11 in
5 | Legal, 8 1/2 x 14 in
6 | Statement, 5 1/2 x 8 1/2 in
7 | Executive, 7 1/4 x 10 1/2 in
8 | A3, 297 x 420 mm
9 | A4, 210 x 297 mm
10 | A4, Small 210 x 297 mm
11 | A5, 148 x 210 mm
12 | B4, 250 x 354 mm
13 | B5, 182 x 257 mm
14 | Folio, 8 1/2 x 13 in
15 | Quarto, 215 x 275 mm
16 | 10 x 14 in
17 | 11 x 17 in
18 | Note, 8 1/2 x 11 in
19 | Envelope #9, 3 7/8 x 8 7/8 in
20 | Envelope #10, 4 1/8 x 9 1/2 in
21 | Envelope #11, 4 1/2 x 10 3/8 in
22 | Envelope #12, 4 1/2 x 11 in
23 | Envelope #14, 5 x 11 1/2 in
24 | C size sheet
25 | D size sheet
26 | E size sheet
27 | Envelope DL, 110 x 220 mm
28 | Envelope C5, 162 x 229 mm
29 | Envelope C3, 324 x 458 mm
30 | Envelope C4, 229 x 324 mm
31 | Envelope C6, 114 x 162 mm
32 | Envelope C65, 114 x 229 mm
33 | Envelope B4, 250 x 353 mm
34 | Envelope B5, 176 x 250 mm
35 | Envelope B6, 176 x 125 mm
36 | Envelope, 110 x 230 mm
37 | Envelope Monarch, 3 7/8 x 7.5 in
38 | 6 3/4 Envelope, 3 5/8 x 6 1/2 in
39 | US Std Fanfold, 14 7/8 x 11 in
40 | German Std Fanfold, 8 1/2 x 12 in
41 | German Legal Fanfold, 8 1/2 x 13 in

If nPrinterSetting is 7, PRTINFO( ) returns the default paper source as the following:

Return values | Default paper source
1 | Upper bin
2 | Lower bin
3 | Middle bin
4 | Manual feed
5 | Envelope bin
6 | Manual feed envelope
7 | Automatic feed
8 | Tractor feed
9 | Small format
10 | Large format
11 | Large capacity
14 | Cassette
15 | Default input bin (automatically select)

If nPrinterSetting is 8 and PRTINFO( ) returns a negative value, the return value indicates the print quality as the following:

Return values | Print quality
–1 | Draft
–2 | Low
–3 | Medium
–4 | High

If nPrinterSetting is 9, PRTINFO( ) returns a value indicating if a color printer renders color or monochrome output as the following:

Return values | Color of output
1 | Monochrome
2 | Color

If nPrinterSetting is 10, PRTINFO( ) returns the duplex mode as the following:

Return values | Duplex mode
1 | Simplex printing
2 | Vertical duplex
3 | Horizontal duplex

If nPrinterSetting is 12, PRTINFO( ) returns a value that indicates how TrueType® fonts are printed as the following:

Return values | Printing of TrueType® fonts
1 | Print as bitmapped graphics
2 | Download as soft fonts
3 | Substitute device fonts

If nPrinterSetting is 13, PRTINFO( ) returns a value that indicates if output is collated as the following:

Return values | Collation
0 | No collation
1 | Collated

Remarks

You can set Visual FoxPro printer settings in the printer Page Setup dialog box. For more information, see Page Setup Dialog Box.

See Also

Other Resources

Functions
GETPRINTER( ) Function
PRINTSTATUS( ) Function
SET DEVICE Command
SET PRINTER Command
SYS(13) – Printer Status
SYS(1037) – Page Setup Dialog Box


PUTFILE( ) Function

Visual FoxPro 9.0 Language Reference
PUTFILE( ) Function
See Also Example

Invokes the Save As dialog box and returns the file name you specify.

PUTFILE([cCustomText] [, cFileName] [, cFileExtensions])

Parameters

cCustomText

Specifies custom text to appear in the Save As dialog box.
cFileName

Specifies the default file name displayed in the text box.
cFileExtensions

Specifies file name extensions. Only file names with the specified extension are displayed in the scrollable list of the Save As dialog box when the All Files check box is cleared. The first extension in cFileExtensions is automatically appended to the file name entered if an extension isn't included with the file name. The cFileExtensions parameter cannot exceed 254 characters in length. For a list of Visual FoxPro file extensions and corresponding creator types, see the File Extensions and File Types online topic. The character expression cFileExtensions can take one of the following forms:
  • cFileExtensions can contain a single extension, such as PRG, and only file names with that extension are displayed.

  • cFileExtensions can contain a list of file name extensions separated by semicolons. For example, if you include PRG;FXP, Visual FoxPro displays all file names with the extensions .prg and .fxp.

  • If file names have the same root name but different extensions (for example, Customer.prg and Customer.fxp), Visual FoxPro displays only the file name with the extension that appears first in cFileExtensions.

  • cFileExtensions can contain a list of file name extensions separated by vertical bars, such as PRG|FXP. In such a case, Visual FoxPro displays all file names with listed extensions, even if the files have the same root name.

  • If cFileExtensions contains only a semicolon (;), Visual FoxPro displays all file names that don't have an extension.

  • If cFileExtensions is an empty string, Visual FoxPro displays the names of all files in the current directory or folder.

  • If cFileExtensions contains MS-DOS wildcards, such as the question mark (?) and asterisk (*), Visual FoxPro displays all file names with extensions that meet the wildcard criteria. For example, if cFileExtensions is ?X?, all file names with the extensions .fxp, .exe, .txt, and so on, are displayed.

Return Value

Character

Remarks

Use PUTFILE( ) to choose an existing file name or specify a new file name. PUTFILE( ) returns the file name with its path. If you don't enter a file name, PUTFILE( ) returns the default file name (specified with cFileName) and extension (specified by cFileExtensions). If you choose Cancel or press ESC, PUTFILE( ) returns an empty string. You can use the file name that PUTFILE( ) returns to name a file and save it to disk.

Example

The following example creates a delimited data file from any existing table the user chooses. GETFILE( ) is used to find and open a table and PUTFILE( ) is used to return the name of the target file.
Copy Code
gcTableName = GETFILE('DBF', 'Open Table:')
USE (gcTableName)
gcDelimName = ALIAS( ) + '.DLM'
gcDelimFile = PUTFILE('Delimited file:', gcDelimName, 'DLM')
IF EMPTY(gcDelimFile)  && Esc pressed
   CANCEL
ENDIF
COPY TO (gcDelimFile) DELIMITED   && Create delimited file
MODIFY FILE (gcDelimFile) NOEDIT

See Also

Other Resources

Functions
FILE( ) Function
GETEXPR Command
GETFILE( ) Function
GETPICT( ) Function
LOCFILE( ) Function


PV( ) Function

Visual FoxPro 9.0 Language Reference
PV( ) Function
See Also Example

Returns the present value of an investment.

PV(nPayment, nInterestRate, nTotalPayments)

Parameters

nPayment

Specifies the periodic payment amount. nPayment can evaluate to a positive or negative number. PV( ) assumes that the payments are made at the end of each period.
nInterestRate

Specifies the periodic interest rate. If the interest rate of an investment is annual and the payments are made monthly, divide the annual interest rate by 12.
nTotalPayments

Specifies the total number of payments.

Return Value

Numeric

Remarks

PV( ) computes the present value of an investment based on a series of equal periodic payments at a constant periodic interest rate.

Example

Copy Code
STORE 500 to gnPayment  && Periodic payments made monthly
STORE .075/12 TO gnInterest     && 7.5% annual interest rate
STORE 48 TO gnPeriods  && Four years (48 months)
CLEAR
? PV(gnPayment, gnInterest, gnPeriods)  && Displays 20679.19

See Also

Other Resources

Functions
CALCULATE Command
FV( ) Function
PAYMENT( ) Function


QUARTER( ) Function

Visual FoxPro 9.0 Language Reference
QUARTER( ) Function
See Also

Returns the quarter of the year in which a date or datetime expression occurs.

QUARTER(dExpression | tExpression [, nMonth])

Parameters

dExpression

Specifies the Date expression for which you want QUARTER( ) to return a value.
tExpression

Specifies the DateTime expression for which you want QUARTER( ) to return a value.
nMonth

Specifies an optional starting month to the examined quarter. You can use this to specify quarters based on a fiscal rather than a calendar year.

Return Value

Numeric data type. QUARTER( ) returns the quarter of the year in which a date occurs, and the values can be 0, 1, 2, 3, or 4.

Note:
QUARTER( ) returns 0 if passed an empty Date or DateTime value, for example, QUARTER({//}).

See Also

Other Resources

Functions
CMONTH( ) Function
DATE( ) Function
DATETIME( ) Function
DAY( ) Function
MONTH( ) Function
YEAR( ) Function


RAISEEVENT( ) Function

Visual FoxPro 9.0 Language Reference
RAISEEVENT( ) Function
See Also Example

You can use RAISEEVENT( ) to raise, or trigger, an event from a custom method. Though RAISEEVENT( ) applies primarily to custom methods, you can use it for raising native events and methods.

RAISEEVENT( oEventSource, cEvent [, eParm1...] )

Parameters

oEventSource

Specifies the event source, which must be a valid Visual FoxPro object.
cEvent

Specifies the name of the event, method, or property you want to raise.
eParm1...

Specifies one or more parameters to pass if the method has parameters.

Return Value

Logical data type. RAISEEVENT( ) always returns True (.T.).

Remarks

Visual FoxPro automatically raises events for custom methods that are bound to objects using BINDEVENT( ) if the methods are called directly. For example, the following code does not raise an event:

Copy Code
oForm.GetMyData(cData)

Instead, to raise an event for a custom method, you need to make the following call:

Copy Code
RAISEEVENT( oForm, "GetMyData", cData )

You can also change this behavior by using BINDEVENT( ) with nFlags set to 2 or 3.

The event you wish to raise must be marked Public, not Hidden or Protected.

If you use RAISEEVENT( ) on a property, Visual FoxPro sets the property to itself. The following example sets the Caption property for _SCREEN to the current value for Caption:

Copy Code
RAISEEVENT( _SCREEN, "Caption" )

Raising an event fails if you bind to an event, for example, using BINDEVENT( ), that has parameters that are passed by reference.

Visual FoxPro disregards recursive RAISEEVENT( )calls to an event from within the same raised event.

Example

Activating a form or using Form1.Show triggers the Activate event for the form. However, calling the Activate event directly using a call such as Form1.Activate does not trigger the Activate event. The following example shows how you can use RAISEEVENT( ) to trigger the Activate event:

Copy Code
RAISEEVENT( Form1, "Activate" )

See Also

Other Resources

Functions
Event Binding for Visual FoxPro Objects
BINDEVENT( ) Function
UNBINDEVENTS( ) Function
AEVENTS( ) Function


RAND( ) Function

Visual FoxPro 9.0 Language Reference
RAND( ) Function
See Also Example

Returns a random number between 0 and 1.

RAND([nSeedValue])

Parameters

nSeedValue

Specifies the seed value that determines the sequence of values RAND( ) returns. RAND( ) returns the same sequence of random numbers if you use the same seed value for nSeedValue the first time you issue RAND( ) followed by subsequent RAND( ) function calls without nSeedValue. If nSeedValue is negative the first time you issued RAND( ), a seed value from the system clock is used. To achieve the most random sequence of numbers, issue RAND( ) initially with a negative argument and then issue RAND( ) without an argument. If you omit nSeedValue, RAND( ) uses a default seed value of 100,001.

Return Value

Numeric

Example

The first example below uses RAND( ) to create a table with 10 records containing random values, then uses MIN( ) and MAX( ) to display the maximum and minimum values in the table.

The second example below displays a random number that falls between two values, 1 and 10.
Copy Code
CLOSE DATABASES
CREATE TABLE Random (cValue N(3))
FOR nItem = 1 TO 10  && Append 10 records,
   APPEND BLANK
   REPLACE cValue WITH 1 + 100 * RAND( )  && Insert random values
ENDFOR

CLEAR
LIST  && Display the values
gnMaximum = 1  && Initialize minimum value
gnMinimum = 100  && Initialize maximum value
SCAN
   gnMinimum = MIN(gnMinimum, cValue)
   gnMaximum = MAX(gnMaximum, cValue)
ENDSCAN
? 'The minimum value is: ', gnMinimum  && Display minimum value
? 'The maximum value is: ', gnMaximum  && Display maximum value

CLEAR
gnLower = 1
gnUpper = 10

? INT((gnUpper - gnLower + 1) * RAND( ) + gnLower)

See Also

Other Resources

Functions
EXP( ) Function
PI( ) Function
MIN( ) Function
MAX( ) Function


RAT( ) Function

Visual FoxPro 9.0 Language Reference
RAT( ) Function
See Also Example

Returns the numeric position of the last (rightmost) occurrence of a character string within another character string.

RAT(cSearchExpression, cExpressionSearched [, nOccurrence])

Parameters

cSearchExpression

Specifies the character expression that RAT( ) looks for in cExpressionSearched. The character expression can refer to a memo field of any size.
cExpressionSearched

Specifies the character expression that RAT( ) searches. The character expression can refer to a memo field of any size.
nOccurrence

Specifies which occurrence, starting from the right and moving left, of cSearchExpression RAT( ) searches for in cExpressionSearched. By default, RAT( ) searches for the last occurrence of cSearchExpression (nOccurrence = 1). If nOccurrence is 2, RAT( ) searches for the next to last occurrence, and so on.

Return Value

Numeric

Remarks

RAT( ), the reverse of the AT( ) function, searches the character expression in cExpressionSearched starting from the right and moving left, looking for the last occurrence of the string specified in cSearchExpression.

RAT( ) returns an integer indicating the position of the first character in cSearchExpression in cExpressionSearched. RAT( ) returns 0 if cSearchExpression isn't found in cExpressionSearched, or if nOccurrence is greater than the number of times cSearchExpression occurs in cExpressionSearched.

The search performed by RAT( ) is case-sensitive.

Example

Copy Code
STORE 'abracadabra' TO string
STORE 'a' TO find_str
CLEAR
? RAT(find_str,string)  && Displays 11
? RAT(find_str,string,3)  && Displays 6

See Also

Other Resources

Functions
AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
RATLINE( ) Function
RIGHT( ) Function
SUBSTR( ) Function
ATCC( ) Function
LEFTC( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
$ Operator
OCCURS( ) Function
INLIST( ) Function


RATC( ) Function

Visual FoxPro 9.0 Language Reference
RATC( ) Function
See Also

Returns the numeric position of the last occurrence of a character expression or memo field within another character expression or memo field.

RATC(cSearchExpression, cExpressionSearched [, nOccurrence])

Parameters

cSearchExpression

Specifies the character expression that RATC( ) looks for in cExpressionSearched.
cExpressionSearched

Specifies the character expression that RATC( ) searches. The character expressions cSearchExpression and cExpressionSearched can be memo fields of any size.
nOccurrence

Specifies which occurrence, starting from the right and moving left, of cSearchExpression RATC( ) searches for in cExpressionSearched. By default, RATC( ) searches for the last occurrence of cSearchExpression (nOccurrence equals 1). If nOccurrence is 2, RATC( ) searches for the next to last occurrence, and so on.

Return Value

Numeric

Remarks

RATC( ) is designed for expressions containing double-byte characters. If the expression contains only single-byte characters, RATC( ) is equivalent to RAT( ).

RATC( ) returns the numeric position of the last occurrence of a character expression or memo field within another character expression or memo field. The character expressions or memo fields can contain any combination of single-byte and double-byte characters.

RATC( ) is the reverse of the AT_C( ) function: it searches from right to left.

RATC( ) returns an integer indicating the position of the first character in cSearchExpression in cExpressionSearched. RATC( ) returns 0 if cSearchExpression isn't found in cExpressionSearched, or if nOccurrence is greater than the number of times cSearchExpression occurs in cExpressionSearched.

The search performed by RATC( ) is case-sensitive.

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

Functions
AT_C( ) Function
LEFTC( ) Function
RAT( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function


RATLINE( ) Function

Visual FoxPro 9.0 Language Reference
RATLINE( ) Function
See Also Example

Returns the line number of the last occurrence of a character expression within another character expression or memo field, counting from the last line.

RATLINE(cSearchExpression, cExpressionSearched)

Parameters

cSearchExpression

Specifies the character expression that RATLINE( ) looks for in cExpressionSearched.
cExpressionSearched

Specifies the character expression that RATLINE( ) searches. The character expressions cSearchExpression and cExpressionSearched can be memo fields of any size. Use MLINE( ) to return the line containing cSearchExpression.
Tip:
RATLINE() offers a convenient way to search memo fields.

Return Value

Numeric

Remarks

RATLINE( ), the reverse of the ATLINE( ) function, searches a character expression cExpressionSearched, starting with the last character in cExpressionSearched, for the occurrence of cSearchExpression.

If the search is successful, RATLINE( ) returns the number of the line where the match occurs. If the search is unsuccessful, RATLINE( ) returns 0.

The search performed by RATLINE( ) is case-sensitive.

Caution:
The line number that RATLINE() returns is determined by the value of SET MEMOWIDTH, even if cExpressionSearched isn't a memo field. For more information, see SET MEMOWIDTH.

Example

In the following example, RATLINE( ) returns the line number for the last line in the notes memo field containing the word "graduated." MLINE( ) uses this value to return the contents of the line.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE employee  && Opens Employee table
STORE 'graduated' TO gcString
STORE MLINE(notes, RATLINE(gcString, notes)) TO gnFileLine
? gnFileLine

See Also

Other Resources

Functions
AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
RAT( ) Function
RIGHT( ) Function
SUBSTR( ) Function
LEFTC( ) Function
MLINE( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
$ Operator
OCCURS( ) Function
INLIST( ) Function


RECCOUNT( ) Function

Visual FoxPro 9.0 Language Reference
RECCOUNT( ) Function
See Also Example

Returns the number of records in the current or specified table.

RECCOUNT([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area number for a table open in another work area. RECCOUNT( ) returns 0 if a table isn't open in the work area you specify.
cTableAlias

Specifies the table alias for a table open in another work area.

Return Value

Numeric

Remarks

The value RECCOUNT( ) returns isn't affected by SET DELETED and SET FILTER.

RECCOUNT( ) without the optional arguments nWorkArea or cTableAlias returns the number of records in the table in the currently selected work area.

Example

In the following example, Microsoft Visual FoxPro compares the available disk space with the amount needed to sort customer.
Copy Code
*** Check DISKSPACE before a SORT ***

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

*** Get size of table header ***

gnTableHead = HEADER( )

*** Calculate size of table ***

gnFileSize = gnTableHead + (RECSIZE( ) * RECCOUNT( ) + 1)
IF DISKSPACE( ) > (gnFileSize * 3)
   WAIT WINDOW 'Sufficient diskspace to sort.'
ELSE
   WAIT WINDOW 'Insufficient diskspace. Sort cannot be done.'
ENDIF

See Also

Other Resources

Functions
RECNO( ) Function
RECSIZE( ) Function
SET DELETED Command
SET FILTER Command


RECNO( ) Function

Visual FoxPro 9.0 Language Reference
RECNO( ) Function
See Also Example

Returns the current record number in the current or specified table.

RECNO([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area number for a table open in another work area. RECNO( ) returns 0 if a table isn't open in the work area you specify.
cTableAlias

Specifies the table alias for a table open in another work area.

Return Value

Numeric

Remarks

The current record is the record on which the record pointer is positioned.

RECNO( ) returns negative numbers for records appended in a table buffer.

RECNO( ) returns a value that is one greater than the number of records in the table if the record pointer is positioned beyond the last record in the table. RECNO( ) returns 1 if the record pointer is positioned before the first record in the table or the table has no records. If a table has no records, EOF( ) always returns true (.T.).

RECNO( ) issued without the optional arguments nWorkArea or cTableAlias returns the current record number for the table in the currently selected work area.

If you have issued SEEK unsuccessfully in an indexed table, you can specify 0 for nWorkArea to use "soft seek" logic to return the record number of the closest matching record. RECNO(0) returns 0 if a close match cannot be found. Visual FoxPro generates an error message if you issue GO RECNO(0) when a close match isn't found.

Avoid using RECNO( ) in the index expression for a table buffered cursor. Because RECNO( ) changes for new records when they are committed by TABLEUPDATE( ), index corruption could occur.

Example

The following example searches the customer table for a company name, and, if the company name isn't found, uses RECNO(0) to return the closest matching company.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Opens Customer table
SET ORDER TO company
SEEK 'Ernst'
IF FOUND( )
   DISPLAY company, contact
ELSE
   GOTO RECNO(0)
   CLEAR
   ? 'Closest matching company is ' + company
   ? 'Record number: ' + ALLTRIM(STR(RECNO( )))
ENDIF

See Also

Other Resources

Functions
GO | GOTO Command
RECCOUNT( ) Function
RECSIZE( ) Function
SEEK Command
SKIP Command


RECSIZE( ) Function

Visual FoxPro 9.0 Language Reference
RECSIZE( ) Function
See Also Example

Returns the size (width) of a table record.

RECSIZE([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area number for a table open in another work area. RECSIZE( ) returns 0 if a table isn't open in the work area you specify.
cTableAlias

Specifies the table alias for a table open in another work area.

Return Value

Numeric

Remarks

RECSIZE( ) issued without the optional arguments nWorkArea or cTableAlias returns the record size for the table in the currently selected work area.

Example

In the following example, Microsoft Visual FoxPro compares the available disk space with the amount needed to sort customer.
Copy Code
*** Check DISKSPACE before a SORT ***

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table

*** Get size of table header ***

gnTableHead = HEADER( )

*** Calculate size of table ***

gnFileSize = gnTableHead + (RECSIZE( ) * RECCOUNT( ) + 1)
IF DISKSPACE( ) > (gnFileSize * 3)
   WAIT WINDOW 'Sufficient diskspace to sort.'
ELSE
   WAIT WINDOW 'Insufficient diskspace. Sort cannot be done.'
ENDIF

See Also

Other Resources

Functions
RECCOUNT( ) Function
FSIZE( ) Function
HEADER( ) Function


REFRESH( ) Function

Visual FoxPro 9.0 Language Reference
REFRESH( ) Function
See Also

Refreshes data in an updatable SQL remote or local view, or CursorAdapter cursor.

REFRESH([nRecords [, nRecordOffset]] [, cTableAlias | nWorkArea])

Parameters

nRecords

Specifies the number of records to refresh. If nRecords is 1 or you omit nRecords, only the current record is refreshed. If nRecords is 0, no records are refreshed.
nRecordOffset

Specifies the number of records before the current record where the refresh begins. For example, if the current record is record 10 and nRecordOffset is 4, record refresh begins with record 6. If nRecordOffset is 0 or you omit nRecordOffset, the refresh begins with the current record.
cTableAlias

Specifies the alias of the cursor associated with a SQL remote or local view, or a CursorAdapter cursor where records are refreshed.
nWorkArea

Specifies the work area of cursor where records are refreshed. If you omit nWorkArea and cTableAlias, records are refreshed in the currently selected work area.

Return Value

Numeric. REFRESH( ) returns the number of records refreshed.

Remarks

The records are refreshed with data from the tables that define the SQL view or CursorAdapter. Unless specified, records are refreshed in the SQL view or CursorAdapter cursor open in the currently selected work area.

Note:
REFRESH( ) does not refresh content for buffered records; however, field values that are accessible for the record through the CURVAL( ) function are refreshed. For more information, see CURVAL( ) Function.

Caution:
Records must have unique primary keys. If a key for a record cannot be located in the base table, the corresponding record in the SQL view or CursorAdapter is marked for deletion.

Tip:
Calling the REFRESH( ) function can result in a significant impact on performance because the function re-executes the query on which the view is based. Therefore, do not call this function more than necessary.

See Also

Other Resources

Functions
CREATE SQL VIEW Command
CURSORGETPROP( ) Function
CURSORSETPROP( ) Function


RELATION( ) Function

Visual FoxPro 9.0 Language Reference
RELATION( ) Function
See Also Example

Returns a specified relational expression for a table open in a specific work area.

RELATION(nRelationNumber [, nWorkArea | cTableAlias])

Parameters

nRelationNumber

Specifies which relation is returned. For example, if nRelationNumber is 3, RELATION( ) returns the relational expression for the third relation created.
nWorkArea

Specifies the work area for a table open in another work area. If a table isn't open in the work area you specify, RELATION( ) returns the empty string.
cTableAlias

Specifies the table alias for a table open in another work area.

Return Value

Character

Remarks

RELATION( ) by default returns relational expressions for the table in the currently selected work area. It returns the empty string if no relations exist. For additional information about creating relations between tables, see SET RELATION.

DISPLAY STATUS and LIST STATUS display relational expressions. Issue MODIFY DATABASE to display the Database Designer, allowing you to view and modify relations between tables in the current open database. Issue SET to display the Data Session window, allowing you to view and modify relations between free tables.

Example

In the following example, tables are opened and orders set, and then the relations are displayed using RELATION( ).
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer IN 0 ORDER cust_id  && Opens Customer table
USE employee IN 0 ORDER emp_id  && Opens Customer table
USE orders IN  0 ORDER order_id  && Opens Customer table
SELECT orders
SET RELATION TO emp_id INTO employee
SET RELATION TO cust_id INTO customer ADDITIVE
? RELATION(1)  && Displays CUST_ID
? RELATION(2)  && Displays EMP_ID
? RELATION(3)  && Displays empty string

See Also

Other Resources

Functions
DISPLAY STATUS Command
MODIFY DATABASE Command
LIST STATUS Command
SET Command
SET RELATION Command
SET RELATION OFF Command
TARGET( ) Function


REMOVEPROPERTY( ) Function

Visual FoxPro 9.0 Language Reference
REMOVEPROPERTY( ) Function
See Also

Removes a property from an object at run time.

REMOVEPROPERTY(oObjectName, cPropertyName)

Parameters

oObjectName

Specifies the name of the object from which to remove the property.
cPropertyName

Specifies the name of the existing property to remove from the object. You can specify only a property name, not an event or method name.

Return Value

Logical data type. REMOVEPROPERTY( ) returns True (.T.) if it successfully removes the property; otherwise, it returns False (.F.).

Remarks

You can use REMOVEPROPERTY( ) to remove properties, but not methods or events. You can use REMOVEPROPERTY( ) with object instances created from Visual FoxPro classes, COM classes, SCATTER...NAME command, _VFP, and _SCREEN.

Properties must be visibly Public, not Hidden or Protected and have been added to an instance of an object, typically using the ADDPROPERTY( ) function, the AddProperty method, or SCATTER...NAME command, so that they can be removed using REMOVEPROPERTY( ).

You cannot remove a property if it is a member of the class definition used to create the instance of the object.

REMOVEPROPERTY( ) function does not remove properties that are specific array elements. To remove an array, provide only the array name.

Examples

Example 1

The following example adds a new property to an object created with the SCATTER command and then removes it.

Copy Code
USE customers
SCATTER NAME oCust
ADDPROPERTY(oCust,"MyProperty")
REMOVEPROPERTY(oCust,"MyProperty")

Example 2

The following example creates a property array for the object, oMyForm, displays its contents, 1 and "Two", and then removes it.

Copy Code
oMyForm = CREATEOBJECT('Form')
ADDPROPERTY(oMyForm, 'MyArray(2)', 1)
oMyForm.MyArray(2) = "Two"
CLEAR
? oMyForm.MyArray(1)
? oMyForm.MyArray(2)
REMOVEPROPERTY(oMyForm, 'MyArray')
RELEASE oMyForm
CLEAR

See Also

Other Resources

Functions
ADDPROPERTY( ) Function
AddProperty Method


REPLICATE( ) Function

Visual FoxPro 9.0 Language Reference
REPLICATE( ) Function
See Also Example

Returns a character string that contains a specified character expression repeated a specified number of times.

REPLICATE(cExpression, nTimes)

Parameters

cExpression

Specifies the character expression that is replicated.
nTimes

Specifies the number of times the character expression is replicated.

Return Value

Character

Remarks

In Visual FoxPro, the maximum length of the resulting character string is restricted by the amount of available memory.

Example

Copy Code
CLEAR
? REPLICATE('HELLO ',4) && Displays HELLO HELLO HELLO HELLO

See Also

Other Resources

Functions
SPACE( ) Function
Creating Character Expressions
CLEAR Commands


REQUERY( ) Function

Visual FoxPro 9.0 Language Reference
REQUERY( ) Function
See Also

Retrieves data again for a SQL view.

REQUERY([nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area in which the SQL view is open.
cTableAlias

Specifies the alias of the SQL view. If you omit nWorkArea and cTableAlias, the data for the SQL view open in the currently selected work area is retrieved.

Return Value

Numeric. REQUERY( ) returns 1 if the data is successfully retrieved; otherwise, it returns 0.

Remarks

REQUERY( ) is typically used to refresh a SQL view when data has changed on the data source.

See Also

Other Resources

Functions
CREATE SQL VIEW Command
SELECT - SQL Command
USE Command
CREATE QUERY Command


RGB( ) Function

Visual FoxPro 9.0 Language Reference
RGB( ) Function
See Also Example

Returns a single color value from a set of red, green, and blue color components.

RGB(nRedValue, nGreenValue, nBlueValue)

Parameters

nRedValue

Specifies the intensity of the red color component. nRedValue can range from 0 to 255. Zero is the minimum color intensity; 255 is the maximum color intensity.
nGreenValue

Specifies the intensity of the green color component. nGreenValue can range from 0 to 255.
nBlueValue

Specifies the intensity of the blue color component. nBlueValue can range from 0 to 255.

Remarks

The value returned by RGB( ) can be used to set color properties such as BackColor and ForeColor.

Example

The following example uses RGB( ) to change the background color of a Form to blue.
Copy Code
goMyForm = CREATEOBJECT('FORM')  && Create a form
goMyForm.Show  && Display the form
WAIT WINDOW 'Press a key to change the form color'
goMyForm.BackColor=RGB(0,0,255)  && Change the form background color
WAIT WINDOW 'Press a key to release the form'
RELEASE goMyForm  && Release the form from memory

See Also

Other Resources

Functions
GETCOLOR( ) Function
RGBSCHEME( ) Function
BackColor, ForeColor Properties


RGBSCHEME( ) Function

Visual FoxPro 9.0 Language Reference
RGBSCHEME( ) Function
See Also Example

Returns an RGB color pair or an RGB color pair list from a specified color scheme.

RGBSCHEME(nColorSchemeNumber [, nColorPairPosition])

Parameters

nColorSchemeNumber

Specifies the number of the color scheme for which you want a complete RGB color listing. RGBSCHEME( ) returns 10 RGB color pairs.
nColorPairPosition

Returns a single RGB color pair from a color scheme. nColorPairPosition specifies the position of the RGB color pair in the color scheme. For example, if nColorPairPosition is 4, the fourth RGB color pair is returned.

Return Value

Character

Remarks

Use SCHEME( ) to return a traditional color pair or a color pair list from a color scheme. RGB color pairs use numeric values to specify colors. Traditional color pairs use letters to specify colors.

Example

The following displays the third RGB color pair from color scheme number 4.
Copy Code
CLEAR
? RGBSCHEME(4,3)

See Also

Other Resources

Functions
RGB( ) Function
SCHEME( ) Function


RIGHT( ) Function

Visual FoxPro 9.0 Language Reference
RIGHT( ) Function
See Also Example

Returns the specified number of rightmost characters from a character string.

RIGHT(cExpression, nCharacters)

Parameters

cExpression

Specifies the character expression whose rightmost characters are returned.
nCharacters

Specifies the number of characters returned from the character expression. RIGHT( ) returns the entire character expression if nCharacters is greater than the length of cExpression. RIGHT( ) returns an empty string if nCharacters is negative or 0.

Return Value

Character

Remarks

Characters are returned beginning with the last character on the right and continuing for a specified number of characters.

Example

Copy Code
CLEAR
? RIGHT('Redmond, WA', 2)  && Displays WA

See Also

Other Resources

Functions
AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
LEFTC( ) Function
LTRIM( ) Function
RAT( ) Function
RATLINE( ) Function
RTRIM( ) Function
RIGHTC( ) Function
SUBSTR( ) Function
SUBSTRC( ) Function
TRIM( ) Function


RIGHTC( ) Function

Visual FoxPro 9.0 Language Reference
RIGHTC( ) Function
See Also

Returns the specified number of rightmost characters from a character string.

RIGHTC(cExpression, nCharacters)

Parameters

cExpression

Specifies the character expression whose rightmost characters are returned.
nCharacters

Specifies the number of characters returned from the character expression. RIGHTC( ) returns the entire character expression if nCharacters is greater than the length of cExpression. RIGHTC( ) returns an empty string if nCharacters is negative or 0.

Return Value

Character

Remarks

RIGHTC( ) is designed for expressions containing double-byte characters. If the expression contains only single-byte characters, RIGHTC( ) is equivalent to RIGHT( ).

Characters are returned beginning with the last character on the right and continuing for nCharacters.

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

Functions
AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
LEFTC( ) Function
RAT( ) Function
RATLINE( ) Function
SUBSTR( ) Function
RIGHT( ) Function
SUBSTRC( ) Function


RLOCK( ) Function

Visual FoxPro 9.0 Language Reference
RLOCK( ) Function
See Also Example

Attempts to lock a table record or records.

RLOCK([nWorkArea | cTableAlias] | [cRecordNumberList, nWorkArea
 | cTableAlias])

Parameters

nWorkArea| cTableAlias

Specifies the work area number or table alias for a table open in another work area. If you don't specify a work area or alias, RLOCK( ) attempts to lock the current record in the table in the currently selected work area.
cRecordNumberList

Specifies that RLOCK( ) attempts to lock multiple records. The character expression cRecordNumberList specifies one or more record numbers, separated by commas, that RLOCK( ) attempts to lock. For example, to attempt record locks on the first four records in a table, cRecordNumberList should contain 1, 2, 3, 4. To lock multiple records, you must have SET MULTILOCKS on and you must include the work area number (nWorkArea) or alias (cTableAlias) of the table in which you attempt to lock multiple records. You can also lock multiple records by moving the record pointer to the record you would like to lock, issuing RLOCK( ) or LOCK( ) and then repeating this process for additional records. In Visual FoxPro, you can specify 0 as a record number. Specifying 0 lets you attempt to lock the table header.
Caution:
Keep the table header locked for as short a time as possible because other users cannot add records to the table when the table header is locked.

Release the table header lock with UNLOCK RECORD 0, UNLOCK, or UNLOCK ALL. If all the records specified in cRecordNumberList are successfully locked, RLOCK( ) returns true (.T.). If one or more of the records specified in cRecordNumberList cannot be locked, RLOCK( ) returns false (.F.) and locks none of the records. In either case, existing record locks remain in place. Multiple record locking is an additive process — placing additional record locks doesn't release existing record locks. From a performance perspective, it is always faster to lock the entire table than to lock even a small number of records.

Return Value

Logical

Remarks

RLOCK( ) is identical to LOCK( ).

Changes to explicitly locked records aren't saved until the record is unlocked or the record pointer is moved.

If the lock or locks are successfully placed, RLOCK( ) returns true (.T.). Locked records are available for both read and write access by the user who placed the locks and for read-only access to all other users on the network.

Executing RLOCK( ) doesn't guarantee that the attempted record lock or locks are successfully placed. A record lock cannot be placed on a record already locked by another user or in a table locked by another user. If the record lock or locks cannot be placed for any reason, RLOCK( ) returns false (.F.).

By default, RLOCK( ) makes one attempt to lock a record. Use SET REPROCESS to automatically retry a record lock when the first attempt fails. SET REPROCESS controls the number of lock attempts or the length of time lock attempts are made when the initial lock attempt is unsuccessful. For more information about SET REPROCESS and table locking, see SET REPROCESS.

SET MULTILOCKS determines whether you can lock multiple records in a table. If SET MULTILOCKS is off (the default), you can lock only a single record in a table. If SET MULTILOCKS is on, you can lock multiple records in a table. For more information, see SET MULTILOCKS.

A table record can be unlocked only by the user who placed the lock. Record locks can be released by issuing UNLOCK, closing the table, or exiting Visual FoxPro.

UNLOCK can be used to release record locks in the current work area, a specific work area or in all work areas. For more information, see UNLOCK.

Switching SET MULTILOCKS from ON to OFF or from OFF to ON implicitly performs UNLOCK ALL. All record locks in all work areas are released.

To close tables, use USE, CLEAR ALL, or CLOSE DATABASES.

For more information about record and file locking and sharing tables on a network, see Programming for Shared Access.

Example

The following example locks and unlocks the first four records in the customer and employee tables.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
SET REPROCESS TO 3 AUTOMATIC
STORE '1,2,3,4' TO gcRecList
gcOldExc = SET('EXCLUSIVE')
SET EXCLUSIVE OFF
SELECT 0
USE employee  && Open Employee table
SELECT 0
USE customer  && Open Customer table
? LOCK('1,2,3,4', 'customer')  && Lock 1st 4 records in customer
? RLOCK(gcRecList, 'employee')  && Lock 1st 4 records in employee
UNLOCK IN customer
UNLOCK IN employee
SET EXCLUSIVE &gcOldExc

See Also

Other Resources

Functions
CLEAR Commands
CLOSE Commands
FLOCK( ) Function
LOCK( ) Function
SET MULTILOCKS Command
SET RELATION Command
SET REPROCESS Command
UNLOCK Command
USE Command
ISFLOCKED( ) Function
ISRLOCKED( ) Function


ROUND( ) Function

Visual FoxPro 9.0 Language Reference
ROUND( ) Function
See Also Example

Returns a numeric expression rounded to a specified number of decimal places.

ROUND(nExpression, nDecimalPlaces)

Parameters

nExpression

Specifies the numeric expression whose value is to be rounded.
nDecimalPlaces

Specifies the number of decimal places nExpression is rounded to. If nDecimalPlaces is negative, ROUND( ) returns a whole number containing zeros equal in number to nDecimalPlaces to the left of the decimal point. For example, if nDecimalPlaces is –2, the first and second digits to the left of the decimal point in the value are 0.

Return Value

Numeric data type. ROUND( ) returns a value rounded to the nearest decimal position as specified by nDecimalPlaces.

Remarks

ROUND( ) disregards the number of decimal places specified by the SET DECIMALS command. To display a larger number of decimal places than specified by nDecimalPlaces in ROUND( ), use SET FIXED ON with SET DECIMALS.

Example

The following example specifies that resulting values display with four decimal places using the SET DECIMALS and SET FIXED commands. The example clears the main Visual FoxPro window using the CLEAR command, performs rounding operations with the ROUND( ) function, and displays the results using the ? command. The example restores the default startup values using SET FIXED and SET DECIMALS.
Copy Code
SET DECIMALS TO 4
SET FIXED ON
CLEAR
? ROUND(1234.1962, 3) && Displays 1234.1960
? ROUND(1234.1962, 2) && Displays 1234.2000
? ROUND(1234.1962, 0) && Displays 1234.0000
? ROUND(1234.1962, -1)  && Displays 1230.0000
? ROUND(1234.1962, -2)  && Displays 1200.0000
? ROUND(1234.1962, -3)  && Displays 1000.0000
SET FIXED OFF
SET DECIMALS TO 2

See Also

Other Resources

Functions
STR( ) Function
CEILING( ) Function
FLOOR( ) Function
INT( ) Function
SET DECIMALS Command
SET FIXED Command


ROW( ) Function

Visual FoxPro 9.0 Language Reference
ROW( ) Function
See Also

Included for backward compatibility. Use the CurrentY property.

See Also

Other Resources

Language Reference


RTOD( ) Function

Visual FoxPro 9.0 Language Reference
RTOD( ) Function
See Also Example

Converts radians to its equivalent in degrees.

You can use RTOD( ) when working with the Visual FoxPro trigonometric functions COS( ), SIN( ), and TAN( ).

RTOD(nExpression)

Parameters

nExpression

Specifies a numeric expression representing a radian value.

Return Value

Numeric data type. RTOD( ) returns the number of degrees converted from the number of radians.

Remarks

To convert degrees to radians, use the DTOR( ) function.

Example

Copy Code
CLEAR
? RTOD(ACOS(0))  && Displays 90.00
STORE -1 to gnArcAngle
? RTOD(ACOS(gnArcAngle))  && Displays 180.00
? RTOD(ACOS(SQRT(2)/2)) && Displays 45.00

See Also

Other Resources

Functions
COS( ) Function
DTOR( ) Function
SIN( ) Function
TAN( ) Function


RTRIM( ) Function

Visual FoxPro 9.0 Language Reference
RTRIM( ) Function
See Also Example

Removes all trailing spaces or parsing characters from the specified character expression, or all trailing zero (0) bytes from the specified binary expression.

RTRIM(cExpression [, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

Parameters

cExpression

Specifies an expression of Character or Varbinary type to remove all trailing spaces or 0 bytes from, respectively.
nFlags

Specifies if trimming is case-sensitive when one or more parse characters (cParseChar, cParseChar2, … are included. Trimming is case-sensitive if nFlags is zero or is omitted. Trimming is case-insensitive if nFlags 1.
cParseChar [, cParseChar2 [, ...]]

Specifies one or more character strings that are trimmed from the end of cExpression. If cParseChar isn't included, then trailing spaces or 0 bytes are removed from Expression. Note The maximum number of strings permitted in cParseChar is 23.

Return Value

Character or Varbinary. RTRIM( ) returns the specified expression without trailing spaces or parsing characters, or 0 bytes.

Remarks

You can use RTRIM( ) to ensure that trailing spaces or leading and trailing zero (0) bytes are removed from data entered by a user. RTRIM( ) is identical to TRIM( ).

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table
CLEAR
? 'The contact for '+ RTRIM(company) + ' is ' + contact

See Also

Other Resources

Functions
ALLTRIM( ) Function
LTRIM( ) Function
TRIM( ) Function


SAVEPICTURE( ) Function

Visual FoxPro 9.0 Language Reference
SAVEPICTURE( ) Function
See Also

Creates a bitmap (.bmp) file from a picture object reference.

SAVEPICTURE(oObjectReference, cFileName)

Parameters

oObjectReference

Specifies a picture object reference from which SAVEPICTURE( ) creates a bitmap file.
cFileName

Specifies the name of the bitmap file that SAVEPICTURE( ) creates. If cFileName includes a path, the file is created in the directory specified in the path. If a file with the same name already exists, it is overwritten without warning, even if SET SAFETY is ON.

Return Value

Logical

Remarks

Picture object references are typically created with LOADPICTURE( ). However, certain properties (such as the PictureOpen property for the OLE Outline control) use a default picture object reference, which can be used to create a bitmap file.

See Also

Other Resources

Functions
LOADPICTURE( ) Function
SET SAFETY Command
_ObjectReference( ) API Library Routine


SCHEME( ) Function

Visual FoxPro 9.0 Language Reference
SCHEME( ) Function
See Also Example

Returns a color pair list or a single color pair from a specified color scheme.

SCHEME(nSchemeNumber [, nColorPairNumber])

Parameters

nSchemeNumber

Specifies the number of the color scheme for which you want a complete color-pair list. SCHEME( ) returns ten color pairs.
nColorPairNumber

Specifies the position of one color pair in the color scheme, and SCHEME( ) returns only this color pair. For example, if nColorPairNumber is 4, SCHEME( ) returns the fourth color pair from the color scheme.

Return Value

Character

Example

The following example returns the third color pair from color scheme number 4:
Copy Code
? SCHEME(4,3)

See Also

Other Resources

Functions
ColorScheme Property
GETCOLOR( ) Function


SCOLS( ) Function

Visual FoxPro 9.0 Language Reference
SCOLS( ) Function
See Also

Returns the number of columns available in the main Microsoft Visual FoxPro window.

SCOLS( )

Return Value

Numeric

Remarks

The value returned by SCOLS( ) depends on the current display mode. Display modes can be changed with SET DISPLAY.

See Also

Other Resources

Functions
COL( ) Function
ROW( ) Function
SET DISPLAY Command
SROWS( ) Function
WCOLS( ) Function
WROWS( ) Function


SEC( ) Function

Visual FoxPro 9.0 Language Reference
SEC( ) Function
See Also Example

Returns the seconds portion from a DateTime expression.

SEC(tExpression)

Parameters

tExpression

Specifies the DateTime expression from which SEC( ) returns the second. If tExpression contains only a date and not a time, Visual FoxPro adds a default time of 12:00:00 AM (if SET HOURS is 12) or 00:00:00 (if SET HOURS is 24) to tExpression to produce a valid DateTime value.

Return Value

Numeric

Example

The following example displays the second portion of the current time and the second portion of a specific time.
Copy Code
CLEAR
? SEC(DATETIME( ))
? SEC({^2004-02-16 10:42:16AM})  && Displays 16

See Also

Other Resources

Functions
DATETIME( ) Function
HOUR( ) Function
MINUTE( ) Function
SET SECONDS Command


SECONDS( ) Function

Visual FoxPro 9.0 Language Reference
SECONDS( ) Function
See Also Example

Returns the number of seconds that have elapsed since midnight.

SECONDS( )

Return Value

Numeric. SECONDS( ) returns a numeric value in decimal format with a resolution of 1 millisecond. For versions of Visual FoxPro running on Windows NT 4.0 or later, SECONDS( ) returns a resolution of 10 milliseconds.

Example

Copy Code
CLEAR
? SECONDS( )
? SECONDS( )/(60 * 60)

See Also

Other Resources

Functions
SYS(2) - Seconds Since Midnight
TIME( ) Function
Seconds Property


SEEK( ) Function

Visual FoxPro 9.0 Language Reference
SEEK( ) Function
See Also Example

Searches an indexed table for the first occurrence of a record whose index key matches a specified expression. Issuing SEEK( ) is equivalent to issuing SEEK and FOUND( ) in succession.

Note:
Visual FoxPro does not support seek operations for binary indexes.

SEEK(eExpression [, nWorkArea | cTableAlias
   [, nIndexNumber | cIDXIndexFileName | cTagName]])

Parameters

eExpression

Specifies the index key expression for which you want SEEK( ) to search.
nWorkArea

Specifies the work area number of the table that is searched for the index key.
cTableAlias

Specifies the alias of the table that is searched. If you omit nWorkArea and cTableAlias, the table in the currently selected work area is searched.
nIndexNumber

Specifies the number of the index file or tag that is used to search for the index key. nIndexNumber refers to the index files as they are listed in USE or SET INDEX. Open .idx files are numbered first in the order in which they appear in USE or SET INDEX. Tags in the structural .cdx file (if one exists) are then numbered in the order in which they were created. Finally, tags in any open independent .cdx files are numbered in the order in which they were created. For more information about index numbering, see SET ORDER Command.
cIDXIndexFileName

Specifies an .idx file that is used to search for the index key.
cTagName

Specifies a tag of a .cdx file that is used to search for the index key. The tag name can be from a structural .cdx file or any open independent .cdx file.
Note:
The .idx file takes precedence if duplicate .idx file and tag names exist.

Return Value

Logical. SEEK( ) returns True (.T.) if a match is found and the record pointer moves to the matching record. Otherwise, SEEK( ) returns False (.F.) if a match is not found, and the record pointer moves to the end of the file if SET NEAR is OFF or to the closest matching record if SET NEAR is ON.

Remarks

You can use SEEK( ) on a table with an index order set, or if an index order is not set on the table, set the controlling index with the 3rd parameter, nIndexNumber, cIDXIndexFileName, or cTagName. The match must be exact unless SET EXACT is set to OFF.

If you omit the nIndexNumber, IDXIndexFileName, and cTagName arguments, SEEK( ) uses the master controlling index or index tag to search for the index key.

The SET KEY setting is ignored if SEEK( ) uses a non-active index.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer ORDER cust_id  && Opens Customer table
? SEEK('CHOPS')  && Returns .T., record found

See Also

Reference

SET NEAR Command
SET KEY Command

Other Resources

Functions
EOF( ) Function
FOUND( ) Function
INDEXSEEK( ) Function
LOCATE Command
SEEK Command
SET ORDER Command


SELECT( ) Function

Visual FoxPro 9.0 Language Reference
SELECT( ) Function
See Also Example

Returns the number of the currently selected work area or the highest-numbered unused work area.

SELECT([ 0 | 1 | cTableAlias ])

Parameters

0

Specifies that SELECT( ) return the number of the current work area.
1

Specifies that SELECT( ) return the highest-numbered unused work area.
cTableAlias

Specifies the alias of the table for which SELECT( ) returns the work area.

Return Value

Numeric

Remarks

SELECT( ) returns the number of the current work area if SET COMPATIBLE is set to OFF. If SET COMPATIBLE is set to ON, SELECT( ) returns the number of the unused work area with the highest number.

A work area can be selected (activated) with SELECT.

Example

Copy Code
CLOSE DATABASES
SET COMPATIBLE ON
OPEN DATABASE (HOME(2) + 'data\testdata')

SELECT 0  && Unused work area
USE customer  && Opens Customer table

SELECT 0  && Unused work area
USE orders  && Opens Orders table

CLEAR
? SELECT( )  && Returns 3, lowest available work area

See Also

Other Resources

Functions
ALIAS( ) Function
SELECT Command
SET COMPATIBLE Command


SET( ) Function

Visual FoxPro 9.0 Language Reference
SET( ) Function
See Also

Returns the status of various SET commands.

SET(cSETCommand [, 1 | cExpression | 2 | 3 | 4])

Parameters

cSETCommand

Specifies a character expression of the SET command for which you want to return information. The current setting of the specified command is returned as a character or numeric string.
1 | cExpression| 2 | 3 | 4

Specifies additional information to return about a SET command. The values 1 and cExpression are identical; cExpression can be any expression that evaluates to a character type value.
Note:
Including an argument does not return additional information for all SET commands, only those specifying values of 1, 2, 3, or 4 in the following table.

SET command Value returned

ALTERNATE

ON or OFF

ALTERNATE, 1

FileName

BELL, 1

cWAVFileName

CARRY

ON or OFF

CENTURY

ON or OFF

CENTURY, 1

nCentury

CENTURY, 2

ROLLOVER nYear

CENTURY, 3

System Regional Calendar setting

CLOCK

ON or OFF

CLOCK, 1

nRow and nColumn

COMPATIBLE

ON or OFF

COMPATIBLE, 1

PROMPT or NOPROMPT

COVERAGE, 1

FileName

CURRENCY

LEFT or RIGHT

CURRENCY, 1

cCurrencySymbol

DATE

AMERICAN, ANSI, BRITISH/FRENCH, GERMAN, ITALIAN, JAPAN, USA, MDY, DMY, or YMD

DATE, 1

Date Ordering:0 – MDY1 – DMY2 – YMD

DELIMITERS

ON or OFF

DELIMITERS, 1

cDelimiters

EVENTTRACKING

ON or OFF

EVENTTRACKING, 1

FileName

FIELDS

ON or OFF

FIELDS, 1

FieldName1, FieldName2, ...

FIELDS, 2

LOCAL or GLOBAL

HELP

ON or OFF

HELP, 1

cFileName

HELP, 2

cCollectionURL

HELP, 3

SYSTEM

KEY

eExpression2, eExpression3

KEY, 1

eExpression2

KEY, 2

eExpression3

MESSAGE

nRow

MESSAGE, 1

cMessageText

MOUSE

ON or OFF

MOUSE, 1

nSensitivity

NOTIFY

ON or OFF

NOTIFY, 1

ON or OFF

ORDER

TAG TagName OF CDXFileName, IDXFileName, or blank

PRINTER

ON or OFF

PRINTER, 1

FileName or PortName

PRINTER, 2

Default Windows printer name

PRINTER, 3

Default Visual FoxPro printer name(specified in the Visual FoxPro Print or Print Setup dialog boxes)

REFRESH

nSeconds1

REFRESH, 1

nseconds2

REPROCESS

Current session setting

REPROCESS, 1

System session setting

REPROCESS, 2

Current session setting type

0 is returned if REPROCESS is set to attempts.

1 is returned if REPROCESS is set to seconds.

REPROCESS, 3

System session setting type

0 is returned if REPROCESS is set to attempts.

1 is returned if REPROCESS is set to seconds.

RESOURCE

ON or OFF

RESOURCE, 1

FileName

TALK

ON or OFF

TALK, 1

WINDOW, NOWINDOW or WindowName

TEXTMERGE

ON or OFF

TEXTMERGE, 1

cLeftDelimiter and cRightDelimiter

TEXTMERGE, 2

cFileName

TEXTMERGE, 3

SHOW/NOSHOW

TEXTMERGE, 4

Evaluate source of TEXT ... ENDTEXT call and return TEXTMERGE nesting level.

TOPIC

cHelpTopicName | lExpression

TOPIC, 1

NContextID

Return Value

Character or Numeric data type. SET( ) returns the value of a SET command.

Remarks

SET( ) recognizes the four-character abbreviation for all Visual FoxPro SET keywords, with the exception of HELPFILTER, which can be abbreviated to five characters. For example, you can use STAT and PRIN for SET STATUS and SET PRINTER, respectively.

The SET( ) function is identical to SYS(2001).

See Also

Other Resources

DISPLAY STATUS Command
LIST Command
SET Command
SYS(2001) – SET ... Command Status
Functions
Language Reference


SETFLDSTATE( ) Function

Visual FoxPro 9.0 Language Reference
SETFLDSTATE( ) Function
See Also Example

Assigns a field modification or deletion state value to a field or record in a table or cursor.

SETFLDSTATE(cFieldName | nFieldNumber, nFieldState [, cTableAlias
   | nWorkArea])

Parameters

cFieldName| nFieldNumber

Specifies the name or the number of the field for which the modification or deletion status is assigned. The field number nFieldNumber corresponds to the position of the field in the table or cursor structure. DISPLAY STRUCTURE or FIELD( ) can be used to determine a field's number. To set the deletion status for the record, include 0 as the field number.
nFieldState

Specifies a value for the field modification or deletion status. The following table lists the field modification or deletion state value and the corresponding modification or deletion status:

nFieldState Modification or deletion status

1

Field has not been modified or deletion status has not changed.

2

Field has been modified or deletion status has changed.

3

Field in an appended record has not been modified or deletion status has not changed for the appended record.

4

Field in an appended record has been modified or deletion status has changed for the appended record.
cTableAlias

Specifies the alias of the table or cursor in which the modification or deletion status is assigned.
nWorkArea

Specifies the work area of the table or cursor in which the modification or deletion status is assigned. The field modification or deletion state value is assigned for the table or cursor open in the currently selected work area if SETFLDSTATE( ) is issued without the optional cTableAlias or nWorkArea arguments.

Return Value

Logical

Remarks

Visual FoxPro uses field state values to determine which fields in tables or cursors are updated. SETFLDSTATE( ) makes it possible for you to control which fields Visual FoxPro attempts to update, regardless of which fields have been modified in the table or cursor.

Example

The following example demonstrates how you can use SETFLDSTATE( ) to change the field status. MULTILOCKS is set to ON, a requirement for table buffering. The customer table in the testdata database is opened, and CURSORSETPROP( ) is then used to set the buffering mode to optimistic table buffering (5).

GETFLDSTATE( ) is issued to display a value (1) corresponding to the unmodified state of the cust_id field before it is modified. The cust_id field is modified with REPLACE, and GETFLDSTATE( ) is issued again to display a value (2) corresponding to the modified state of the cust_id field.

SETFLDSTATE( ) is used to change the field status of the cust_id field back to 1 (unmodified). GETFLDSTATE( ) is issued again and displays 1, corresponding to the state of the cust_id field assigned by SETFLDSTATE( ). TABLEREVERT( ) is used to return the table to its original state.
Copy Code
CLOSE DATABASES
SET MULTILOCKS ON  && Must be on for table buffering
SET PATH TO (HOME(2) + 'Data\')     && Sets path to database
OPEN DATABASE testdata  && Open testdata database
USE Customer     && Open customer table
= CURSORSETPROP('Buffering', 5, 'customer')  && Enable table buffering

CLEAR
? GETFLDSTATE('cust_id')  && Displays 1, not modified
REPLACE cust_id    WITH '***'  && Changes field contents
? GETFLDSTATE('cust_id')  && Returns 2, field modified
= SETFLDSTATE('cust_id', 1)  && Change the field status
? GETFLDSTATE('cust_id')  && Displays 1, not modified
= TABLEREVERT(.T.)  && Discard all table changes

See Also

Other Resources

DELETED( ) Function
DISPLAY STRUCTURE Command
FIELD( ) Function
GETFLDSTATE( ) Function
Functions
Language Reference


SETRESULTSET( ) Function

Visual FoxPro 9.0 Language Reference
SETRESULTSET( ) Function
See Also

Marks a cursor as a result set in the current data session.

Note:
Only one cursor per data session can be marked. When marking a new cursor, SETRESULTSET( ) clears the marker from any previously marked cursor.

SETRESULTSET( nWorkArea | cTableAlias )

Parameters

nWorkArea

Specifies a work area number.
cTableAlias

Specifies the alias of the cursor you want to mark.

Return Value

Numeric. SETRESULTSET( ) returns the number of the work area of the previously marked cursor in the current data session or zero (0) if no cursor is marked in the current data session.

Remarks

SETRESULTSET( ) is supported in Visual FoxPro and the Visual FoxPro OLE DB Provider. You can use SETRESULTSET( ) in a database container (DBC) stored procedure or send it to the Visual FoxPro OLE DB Provider, assuming that the cursor has been previously opened by the OLE DB Provider. For example, suppose a previous command opens a cursor named MyCursor in the OLE DB Provider. The following line of code retrieves an ADO RecordSet for the cursor, MyCursor:

Copy Code
oRecordSet = oConn.Execute("SETRESULTSET('MyCursor')")

By using SETRESULTSET( ) to mark a cursor or table opened by the Visual FoxPro OLE DB Provider, you can retrieve a rowset created from the table or cursor from a database container (DBC) stored procedure. When the OLE DB Provider completes command execution, it creates a rowset from the marked cursor, if it exists, then clears the marker flag from the cursor.

Note:
In this scenario, the OLE DB Provider disregards all other return values. For example, if a stored procedure contains a RETURN Value statement and a marked cursor, the OLE DB Provider does not return the value. Instead, it returns the marked cursor as a rowset to the calling application. When the rowset closes, the cursor also closes.

However, even though the OLE DB Provider disregards all return values when a marked cursor exists, you can use SETRESULTSET( ) with the RETURN command. For example:

Copy Code
RETURN SETRESULTSET("MyCursor")

This statement creates and returns a rowset from the marked cursor, not the return value from SETRESULTSET( ).

See Also

Other Resources

GETRESULTSET( ) Function
CLEARRESULTSET( ) Function
How to: Use Data Sessions
Supported Visual FoxPro Commands and Functions in OLE DB Provider
Functions


SIGN( ) Function

Visual FoxPro 9.0 Language Reference
SIGN( ) Function
See Also Example

Returns a numeric value of 1, –1, or 0 if the specified numeric expression evaluates to a positive, negative, or 0 value.

SIGN(nExpression)

Parameters

nExpression

Specifies the numeric expression SIGN( ) evaluates. SIGN( ) returns 1 if nExpression evaluates to a positive number, –1 if nExpression evaluates to a negative number, and 0 if nExpression evaluates to 0.

Return Value

Numeric

Example

Copy Code
STORE 10 TO gnNum1
STORE -10 TO gnNum2
STORE 0 TO gnZero
CLEAR
? SIGN(gnNum1)  && Displays 1
? SIGN(gnNum2)  && Displays -1
? SIGN(gnZero)  && Displays 0

See Also

Other Resources

ABS( ) Function
COS( ) Function
SIN( ) Function
Functions
Language Reference


SIN( ) Function

Visual FoxPro 9.0 Language Reference
SIN( ) Function
See Also Example

Returns the sine of an angle.

SIN(nExpression)

Parameters

nExpression

Specifies an angle whose sine SIN( ) returns. nExpression can assume any value and the value returned by SIN( ) ranges between –1 and 1.
Note:
nExpression is specified in radians. Use DTOR( ) to convert an angle from degrees to radians. The number of decimal places displayed by SIN( ) can be specified with SET DECIMALS.

Return Value

Numeric

Example

Copy Code
CLEAR
? SIN(0)  && Displays 0.00
? SIN(PI( )/2)  && Displays 1.00
? SIN(DTOR(90))  && Displays 1.00

See Also

Other Resources

ACOS( ) Function
COS( ) Function
DTOR( ) Function
RTOD( ) Function
SET DECIMALS Command
Functions
Language Reference


SKPBAR( ) Function

Visual FoxPro 9.0 Language Reference
SKPBAR( ) Function
See Also

Determines if a menu item is enabled or disabled with SET SKIP OF.

SKPBAR(cMenuName, MenuItemNumber)

Parameters

cMenuName

Specifies the name of the menu that contains the item.
MenuItemNumber

Specifies the number of the menu item whose status (enabled or disabled) SKPBAR( ) returns. The menu item number is assigned when the menu item is created with DEFINE BAR.

Return Value

Logical

Remarks

SKPBAR( ) returns true (.T.) if the menu item is disabled, and false (.F.) if the menu item is enabled.

See Also

Other Resources

DEFINE BAR Command
SET SKIP OF Command
SKPPAD( ) Function
Functions
Language Reference


SKPPAD( ) Function

Visual FoxPro 9.0 Language Reference
SKPPAD( ) Function
See Also

Determines whether a menu title is enabled or disabled with SET SKIP OF.

SKPPAD(cMenuBarName, cMenuTitleName)

Parameters

cMenuBarName

Specifies the name of the menu bar that contains the menu title.
cMenuTitleName

Specifies the name of the menu title whose status (enabled or disabled) SKPPAD( ) returns.

Return Value

Logical

Remarks

SKPPAD( ) returns true (.T.) if the menu title is disabled, and false (.F.) if the menu title is enabled.

See Also

Other Resources

DEFINE BAR Command
SET SKIP OF Command
SKPBAR( ) Function
Functions
Language Reference


SOUNDEX( ) Function

Visual FoxPro 9.0 Language Reference
SOUNDEX( ) Function
See Also Example

Returns a phonetic representation of the specified character expression.

SOUNDEX(cExpression)

Parameters

cExpression

Specifies the character expression SOUNDEX( ) evaluates.

Return Value

Character

Remarks

SOUNDEX( ) returns a four-character string. By comparing the results SOUNDEX( ) returns for two character expressions, you can determine if the two expressions are phonetically similar, indicating that they sound alike. This can be useful when searching for duplicate records in a table.

SOUNDEX( ) isn't case sensitive and generally disregards vowels.

Example

Copy Code
CLEAR
? SOUNDEX('Smith') = SOUNDEX('Smyth')  && Displays .T.
? SOUNDEX('Computer')  && Displays C513

See Also

Other Resources

DIFFERENCE( ) Function
Sound Player
Creating Character Expressions
Functions
Language Reference


SPACE( ) Function

Visual FoxPro 9.0 Language Reference
SPACE( ) Function
See Also

Returns a character string composed of a specified number of spaces.

SPACE(nSpaces)

Parameters

nSpaces

Specifies the number of spaces that SPACE( ) returns. The maximum value of nSpaces is limited only by memory in Microsoft Visual FoxPro.

Return Value

Character

See Also

Other Resources

PADC( ) | PADL( ) | PADR( ) Functions
REPLICATE( ) Function
Functions
Language Reference


SQLCANCEL( ) Function

Visual FoxPro 9.0 Language Reference
SQLCANCEL( ) Function
See Also Example

Requests cancellation of an executing SQL statement.

SQLCANCEL( ) cancels the execution of SQLCOLUMNS( ), SQLEXEC( ), SQLMORERESULTS( ), and SQLTABLES( ) in asynchronous mode. To establish asynchronous mode, use the SQLSETPROP( ) function.

SQLCANCEL(nStatementHandle)

Parameters

nStatementHandle

Specifies the active statement handle whose SQL statement is to be canceled.

Return Value

Numeric. SQLCANCEL( ) returns 1 if the SQL statement is successfully canceled, – 1 if there is a connection level error, and – 2 if there is an environment level error.

Example

The following example assumes SQLCONNECT( ) is successfully issued, and its return value is stored to a memory variable named gnHandle.

SQLEXEC( ) is used to sends a SQL statement to the data source and return the results to a cursor. SQLCANCEL( ) is issued to stop the query.
Copy Code
= SQLSETPROP(gnHandle, 'asynchronous', .T.)   && To stop SQLEXEC( )
= SQLEXEC(gnHandle, 'SELECT * FROM authors')
= SQLCANCEL(gnHandle)   && Wrong select statement, cancel

See Also

Other Resources

AERROR( ) Function
SQLCOLUMNS( ) Function
SQLEXEC( ) Function
SQLMORERESULTS( ) Function
SQLSETPROP( ) Function
SQLTABLES( ) Function
SQL Commands and Functions
Language Reference


SQLCOLUMNS( ) Function

Visual FoxPro 9.0 Language Reference
SQLCOLUMNS( ) Function
See Also Example

Stores a list of column names and information about each column for the specified data source table to a Visual FoxPro cursor.

SQLCOLUMNS(nStatementHandle, cTableName
    [, "FOXPRO" | "NATIVE"] [, cCursorName])

Parameters

nStatementHandle

Specifies an active statement handle.
cTableName

Specifies the name of the table from which the column names are returned. TableName can contain the wildcard characters ? and *. The question mark (?) matches any single character and the asterisk (*) matches any number of characters.
FOXPRO | NATIVE

Specifies the format for the column information in the result set. Be sure to enclose FOXPRO or NATIVE in quotation marks. The NATIVE format option stores column information for tables in the same format as the data source. The FOXPRO format option stores the column information in the same format as that used for the Visual FoxPro table or cursor that would be created if you imported the data source table into Visual FoxPro. If you omit FOXPRO or NATIVE, the format option defaults to FOXPRO. The following table shows the columns in the result set for the FOXPRO format.

Column name Description

Field_name

Column name

Field_type

Column data type

Field_len

Column length

Field_dec

Number of decimal places
The columns in the result set for the NATIVE format depend on the data source. If the table you specify with cTableName does not exist and the format is set to NATIVE, SQLCOLUMNS( ) returns true (.T.) and creates an empty table or cursor. If the table you specify with cTableName does not exist and the format is set to FOXPRO, SQLCOLUMNS( ) returns false (.F.).
cCursorName

Specifies the name of the Visual FoxPro cursor for the result set. If you do not include a cursor name, Visual FoxPro uses the default name SQLRESULT.

Return Value

Numeric or Logical. SQLCOLUMNS( ) returns 1 if the cursor is successfully created, 0 if SQLCOLUMNS( ) is still executing, – 1 if a connection level error occurs, and – 2 if an environment level error occurs.

Remarks

SQLCOLUMNS( ) is one of the four functions that you can execute either synchronously or asynchronously. The Asynchronous setting of SQLSETPROP( ) determines if these functions execute synchronously or asynchronously. In asynchronous mode, you must call SQLCOLUMNS( ) repeatedly until a value other than false (.F.) (still executing) is returned.

Example

The following example assumes SQLCONNECT( ) is successfully issued, and its return value is stored to a memory variable named gnHandle. SQLCOLUMNS( ) is used to create a cursor named MyCursor containing information about the columns in the authors table.
Copy Code
= SQLCOLUMNS(gnHandle, 'authors', 'FOXPRO', 'MyCursor')

See Also

Other Resources

AERROR( ) Function
SQLGETPROP( ) Function
SQLSETPROP( ) Function
SQLTABLES( ) Function
SQL Commands and Functions
Language Reference


SQLCOMMIT( ) Function

Visual FoxPro 9.0 Language Reference
SQLCOMMIT( ) Function
See Also Example

Commits a transaction.

SQLCOMMIT(nStatementHandle)

Parameters

nStatementHandle

Specifies the statement handle to the data source returned by SQLCONNECT( ).

Return Value

Numeric. SQLCOMMIT( ) returns 1 if the transaction is successfully committed; otherwise, it returns -1. If SQLCOMMIT( ) returns -1, you can use AERROR( ) to determine why the transaction could not be committed.

Remarks

If manual transactions are in effect (the SQLSETPROP( ) Transactions property is set to Manual), you can send multiple updates to remote tables and commit all the updates with SQLCOMMIT( ).

Updates can be rolled back with SQLROLLBACK( ).

Example

The following example assumes SQLCONNECT( ) is successfully issued, and its return value is stored to a memory variable named gnHandle. SQLSETPROP( ) is used to set the Transactions property to 2 (Manual), allowing you to use SQLCOMMIT( ) and SQLROLLBACK( ).

The authors table is modified with SQLEXEC( ), and the changes to the table are committed with SQLCOMMIT( ).
Copy Code
= SQLSETPROP(gnHandle, 'Transactions', 2)  && Manual transactions
= SQLEXEC(gnHandle, "INSERT INTO authors (au_id, au_lname);
   VALUES ('aupoe', 'Poe')")  && Modify the authors table
= SQLCOMMIT(gnHandle)  && Commit the changes

See Also

Other Resources

AERROR( ) Function
BEGIN TRANSACTION Command
END TRANSACTION Command
SQLCONNECT( ) Function
SQLROLLBACK( ) Function
SQLSETPROP( ) Function
SQL Commands and Functions
Language Reference


SQLCONNECT( ) Function

Visual FoxPro 9.0 Language Reference
SQLCONNECT( ) Function
See Also Example

Establishes a connection to a data source. There are two versions of the syntax.

SQLCONNECT([nStatementHandle])
SQLCONNECT([cConnectionName | cDataSourceName [, cUserID [, cPassword ]][, lShared]])

Parameters

nStatementHandle

Specifies that a new statement handle be created for the underlying shared connection that is represented by nStatementHandle. The new statement handle uses the settings provided from nStatementHandle instead of using the default settings.
Note:
You cannot create a new statement handle for a connection that is not shared. Visual FoxPro generates an error if you attempt to create a new statement handle against a nonshared connection.

You can also use SQLCONNECT( ) to obtain a new statement handle on a shared connection that was opened using SQLSTRINGCONNECT( ).
cConnectionName

Specifies a named connection created by the CREATE CONNECTION command. When using CREATE CONNECTION or the Connection Designer to create a named connection, you can configure the connection by specifying a data source name, user ID, and password. When using the named connection in SQLCONNECT( ) as cConnectionName, you can pass values different from those in the named connection for the optional cUserID and cPassword parameters. These passed values are used instead of the user ID and password in the named connection specified by cConnectionName. For example, suppose you create a named connection called myNamedConnection using CREATE CONNECTION or the Connection Designer and specify the values myUserID and myPassword for the named connection. For SQLCONNECT( ), you can specify myNamedConnection as cConnectionName and then specify myAltUserID and myAltPassword as an alternate user ID and password as in the following code:
Copy Code
SQLCONNECT("myNamedConnection", "myAltUserID", "myAltPassword")
However, if you create a named connection using a connection string with CREATE CONNECTION or the Connection Designer, use the named connection in SQLCONNECT( ), and attempt to pass optional user ID and password parameters to SQLCONNECT( ), Visual FoxPro generates the appropriate message. When creating a new shared connection, the cConnectionName parameter refers to a named connection in the current database container (DBC). When creating a new statement handle based on an existing shared connection, the cConnectionName parameter refers to a previous connection opened in shared mode. If you use the cConnectionName parameter without the lShared parameter or with lShared parameter as False (.F.), you will always create a new connection that is not shared. When using cConnectionName, if lShared is True (.T.) and the named connection is already open in shared mode, the user name and password provided should match those previously used. Otherwise, Visual FoxPro generates the appropriate message.
cDataSourceName

Specifies the name of a data source as defined in your Odbc.ini file. You can also choose a data source from the Select Connection or Data Source Dialog Box, which appears when you call SQLCONNECT( ) without any additional arguments or with only the lShared parameter.
cUserID

Specifies the user identifier used to log on to the data source.
cPassword

Specifies the password for gaining access to the data source.
lShared

Specifies whether or not to create a shared connection.

lShared Description

False (.F.)

SQLCONNECT( ) does not create a shared connection. (Default)

True (.T.)

SQLCONNECT( ) creates a shared connection.

Return Value

Numeric data type. SQLCONNECT( ) returns a positive nonzero numeric value as the statement handle if you successfully connect to the data source. SQLCONNECT( ) returns –1 if it cannot make the connection.

Tip:
You should store this statement handle in a memory variable and use the variable in subsequent function calls that require a connection handle.

Remarks

The SQLCONNECT( ) and SQLSTRINGCONNECT( ) functions return a numeric value as the statement handle rather than a connection handle. You cannot obtain a connection handle directly. You can still set and get connection properties using the SQLSETPROP( ) and SQLGETPROP( ) functions by passing the statement handle for that connection and the string, "Shared", as arguments. All other SQL functions use a statement handle instead of a connection handle.

If you issue a statement such as SQLCONNECT(cConnectionName, .T.), and a shared connection is already open with the same name, then the settings for that connection do not change to the settings stored for that connection in the database container (DBC). However, the new statement handle will use the statement settings from the DBC.

Note:
You must disable the Open Database Connectivity (ODBC) login dialog box to support SQL pass through with Microsoft Transaction Server. To disable the ODBC login dialog box, use the statement SQLSETPROP(nStatementHandle, 'DispLogin', 3), where cStatementHandle is the statement handle returned by SQLCONNECT( ). You can also disable the ODBC login dialog box in the Connection Designer.

Example

Example 1

The following example assumes that an ODBC data source called MyFoxSQLNT exists and is available. SQLCONNECT( ) returns a numeric value, which is stored to a variable named gnConnHandle.

If you successfully connect to the data source, SQLCONNECT( ) returns a positive number, a dialog box appears, and SQLDISCONNECT( ) is called to disconnect from the data source.

If you cannot connect to the data source, SQLCONNECT( ) returns a negative number and displays a message.

Copy Code
STORE SQLCONNECT('MyFoxSQLNT', 'myUserID', 'myPassword') TO gnConnHandle
IF gnConnHandle <= 0
   = MESSAGEBOX('Cannot make connection', 16, 'SQL Connect Error')
ELSE
   = MESSAGEBOX('Connection made', 48, 'SQL Connect Message')
   = SQLDISCONNECT(gnHandle)
ENDIF

Example 2

Each of the following examples create new shared connections. The Choose Data Source Dialog Box appears, and SQLCONNECT( ) creates the resulting connection as shared.

Copy Code
SQLCONNECT(.T.)
SQLCONNECT( myConnectionName, .T. )
SQLCONNECT( myDataSourceName, myUserID, myPassword, .T. )

Example 3

Each of the following examples creates a new statement handle based on an existing shared connection.

Copy Code
SQLCONNECT( nStatementHandleValue )
SQLCONNECT( myConnectionName, .T. )

See Also

Other Resources

AERROR( ) Function
CREATE CONNECTION Command
SQLDISCONNECT( ) Function
SQLGETPROP( ) Function
SQLEXEC( ) Function
SQLSETPROP( ) Function
SQLSTRINGCONNECT( ) Function
SQL Commands and Functions
Language Reference


SQLDISCONNECT( ) Function

Visual FoxPro 9.0 Language Reference
SQLDISCONNECT( ) Function
See Also Example

Terminates a connection to a data source.

SQLDISCONNECT(nStatementHandle)

Parameters

nStatementHandle

Specifies the statement handle to the data source returned by SQLCONNECT( ). Specify 0 for nStatementHandle to terminate all active connections.

Return Value

Numeric. SQLDISCONNECT( ) returns 1 if the connection is successfully terminated, – 1 if there is a connection level error, and – 2 if there is an environment level error.

Remarks

SQLDISCONNECT( ) terminates a connection to a data source. You must supply the statement handle that SQLCONNECT( ) returned when you established the connection.

Note:
If you execute SQLDISCONNECT( ) within an asynchronous function sequence or during a transaction, SQLDISCONNECT( ) generates an error.

Example

The following example assumes an ODBC data source called MyFoxSQLNT is available. SQLCONNECT( ) is issued, and its return value is stored to a variable named gnHandle.

If you successfully connect to the data source, SQLCONNECT( ) returns a positive number, a dialog box is displayed and SQLDISCONNECT( ) is used to disconnect from the data source.

If you cannot connect to the data source, SQLCONNECT( ) returns a negative number and a message is displayed.
Copy Code
STORE SQLCONNECT('MyFoxSQLNT', '<userid>', '<password>') TO gnHandle
IF gnHandle <= 0
   = MESSAGEBOX('Cannot make connection', 16, 'SQL Connect Error')
ELSE
   = MESSAGEBOX('Connection made', 48, 'SQL Connect Message)
   = SQLDISCONNECT(gnHandle)
ENDIF

See Also

Other Resources

AERROR( ) Function
SQLCONNECT( ) Function
SQLSTRINGCONNECT( ) Function
SQL Commands and Functions
Language Reference


SQLEXEC( ) Function

Visual FoxPro 9.0 Language Reference
SQLEXEC( ) Function
See Also Example

Sends a SQL statement to the data source, where the statement is processed.

SQLEXEC(nStatementHandle [, cSQLCommand [, cCursorName[, aCountInfo]]])

Parameters

nStatementHandle

Specifies the statement handle to the data source returned by the SQLCONNECT( ) function. For more information, see SQLCONNECT( ) Function.
cSQLCommand

Specifies the SQL statement passed to the data source. The SQL statement can contain a parameterized WHERE clause, which creates a parameterized view. You must define all parameters in the WHERE clause before issuing SQLEXEC( ). For example, if the parameters are variables, the variables must be created and initialized before SQLEXEC( ) is issued. For more information about parameterized views, see How to: Create Parameterized Views. You can include expressions in the SQL statement. Visual FoxPro evaluates all expressions in the SQL statement that you pass before sending them to the data source. Visual FoxPro can evaluate memory variable names, function calls, and expressions enclosed in parentheses as parameter values.
cCursorName

Specifies the name of the Visual FoxPro cursor to which the result set is sent. If you don't include a cursor name, Visual FoxPro uses the default name SQLRESULT. For multiple result sets, new cursor names are derived by appending an incremented number to the name of the first cursor.
aCountInfo

Specifies the name of the array to populate with row count information. If the array doesn’t exist, it is created. The array has two columns: 1 – Alias, 2 –Count.

Column Array contents Data type Description

Alias

0

Character

Indicates that SQL command did not return any results. Either no records were returned or the SQL command failed before results could be returned. (final SQLMORERESULTS call) or execution failed before any result could be processed. Can be only on the first row. Count column for the row contains value -1.

Non-empty uppercase string

Character

Alias of the cursor – target for the record fetch operation. The Count column for the row contains the number of fetched records or -1 if fetch failed. If Count is -1, cursor may not have been created. During asynchronous execution, the fetch process for a cursor can be split between multiple SQLMORERESULTS or SQLEXEC calls; each call returns its own fetch count for the cursor.

Empty String

Character

Indicates that the SQL command (INSERT, UPDATE, or DELETE) did not return a result set.

Count

Number of affected or fetched records.

Integer

Indicates the number of affected records as returned by the ODBC SQLRowCount function. Returns -1 if the number of records is unavailable.

Return Value

Numeric data type. SQLEXEC( ) returns the number of result sets if there is more than one. SQLEXEC( ) returns 0 if it is still executing and returns 1 when it has finished executing. SQLEXEC( ) returns –1 if a connection level error occurs.

Remarks

If the SQL statement you want to pass is quite long, check to see if it exceeds the maximum length of a string literal in Visual FoxPro, which is 255 characters. Longer strings will cause a "Command contains unrecognized phrase/keyword" error. However, you can pass long SQL statements if you break them up into several concatenated literals. For example:

Copy Code
lnRetVal = SQLEXEC(lnHandle, "SELECT <long list of fields> " + ;
   "FROM <several tables> " + ;
   "WHERE <complex filter expression>")

If SQLEXEC( ) is used to execute a SQL statement prepared with SQLPREPARE( ), only the connection handle argument nStatementHandle is required. The cSQLCommand and CursorName arguments should be omitted. For more information, see SQLPREPARE( ) Function.

If the SQL statement generates one result set, SQLEXEC( ) stores the result set to the specified Visual FoxPro cursor. If the SQL statement generates two or more result sets, you can name each result set by setting the connection's BatchMode property to False (.F.) using the SQLSETPROP( ) function and changing the cursor name each time you call the SQLMORERESULTS( ) function. Otherwise, SQLEXEC( ) names each result set by appending sequential numbers to the name of the first one.

SQLEXEC( ) is one of the four functions that you can execute either synchronously or asynchronously. The Asynchronous setting of SQLSETPROP( ) determines whether these functions execute synchronously or asynchronously. In asynchronous mode, you must call SQLEXEC( ) repeatedly until it returns a value other than 0 (still executing).

Example

The following example shows various ways to use SQLEXEC( ) to execute ad-hoc queries and to call or create stored procedures:

Copy Code
CLEAR
LOCAL lnConn
LOCAL lnPercent AS Int  && Input parameters must be typed.
LOCAL lnOutput
lnPercent = 50
lnOutput = 0

* Make connection, assuming a local trusted connection.
lnConn = SQLCONNECT('local')
IF m.lnConn > 0  && Success.

   * Set the active database to PUBS.
   SQLEXEC(m.lnConn, 'use pubs')

   * Execute SELECT statement.
   SQLEXEC(m.lnConn, 'SELECT * FROM authors', 'PubAuthors')
   BROWSE

   * Execute INSERT statement, get value of identity field.
   SQLEXEC(m.lnConn, "INSERT INTO JOBS (job_desc, min_lvl, max_lvl);
       VALUES ('Developer',75,150)")
   SQLEXEC(m.lnConn, "SELECT SCOPE_IDENTITY()", "job_id")
   ? "ID for added Job is " + LTRIM(STR(job_id.exp))

   * Execute DELETE statement. Get number of records affected.
   SQLEXEC(m.lnConn, "DELETE FROM JOBS WHERE job_desc ='Developer'")
   SQLEXEC(m.lnConn, "SELECT @@ROWCOUNT", 'rowcount')
   ? rowcount.exp, "record(s) deleted"

   * Call a stored procedure with no parameters.
   SQLEXEC(m.lnConn, 'sp_who', 'activeusers')
   BROWSE

   * Execute stored procedure with an INPUT parameter.
   SQLEXEC(m.lnConn, 'exec byroyalty ?lnPercent','HalfOffAuthors')

   * Create temp stored procedure with OUTPUT parameter and call it.
   SQLEXEC(m.lnConn, "CREATE PROCEDURE #MyProc @outparam int OUTPUT AS;
      SELECT @outparam=100")
   SQLEXEC(m.lnConn, "exec #myProc ?@lnOutput")
   ? m.lnOutput

   * Create a temp stored procedure with INPUT and OUTPUT parameters
   * and call it.
    SQLEXEC(m.lnConn, "CREATE PROCEDURE #MyProc2 " + ;
                      "@inputparam INT, " + ;
                      "@outparam int OUTPUT " + ;
                      "AS SET @outparam=@inputparam*10")
    SQLEXEC(m.lnConn, "exec #myProc2 ?lnPercent, ?@lnOutput")
    ? m.lnOutput

   * Get version information.
   SQLEXEC(m.lnConn, 'SELECT @@VERSION','SQLVersion1')
   ? STRTRAN(SQLVersion1.Exp,CHR(0))

   * Disconnect.
   SQLDISCONNECT(m.lnConn)
ELSE
   ? "Unable to connect to SQL Server"
ENDIF
RETURN

See Also

Other Resources

SQL Commands and Functions
Language Reference


SQLGETPROP( ) Function

Visual FoxPro 9.0 Language Reference
SQLGETPROP( ) Function
See Also Example

Retrieves the current or default settings for an active connection.

SQLGETPROP(nStatementHandle, cSetting)

Parameters

nStatementHandle

Specifies the statement handle to the data source returned by SQLCONNECT( ). If you specify 0 for nStatementHandle, SQLGETPROP( ) returns the environment setting.
cSetting

Specifies the setting. For a list of the settings you can specify, see SQLSETPROP( ) Function.

Return Value

Character, Numeric, or Logical data type. SQLGETPROP( ) returns the current or default settings for an active connection. SQLGETPROP( ) returns -1 if a connection level occurs and -2 if an environment level error occurs.

Example

The following example uses SQLCONNECT( ) to display the Select Connection or Data Source Dialog Box. Choose a data source, the data source connection is tested, and the example displays the results using SQLGETPROP( ) and the cSetting for the data source.
Copy Code
CLOSE ALL
CLEAR ALL
CLEAR
nHandle=SQLCONNECT()
IF nHandle > 0
 cSource= SQLGETPROP(nHandle, "datasource")
 =MESSAGEBOX("Current Data Source = "+cSource,0,"Connection Results")
ELSE
 =MESSAGEBOX("Connection Error = " + ;
  ALLTRIM(STR(nHandle)),0,"Connection Results")
ENDIF
=SQLDISCONNECT(nHandle)

See Also

Other Resources

AERROR( ) Function
SQLCONNECT( ) Function
SQLSETPROP( ) Function
SQL Commands and Functions
Language Reference


SQLIDLEDISCONNECT( ) Function

Visual FoxPro 9.0 Language Reference
SQLIDLEDISCONNECT( ) Function
See Also

Allows a SQL pass-through connection or connections to be temporarily disconnected.

SQLIDLEDISCONNECT(nStatementHandle)

Parameters

nStatementHandle

Specifies the statement handle of the connection to be temporarily disconnected. Specify 0 for nStatementHandle to temporarily disconnect all active connections.

Return Value

Numeric.

1 is returned if SQLIDLEDISCONNECT( ) successfully temporarily disconnects the SQL pass-through connection or connections.

-1 is returned if SQLIDLEDISCONNECT( ) was unable to temporarily disconnect the SQL pass-through connection or connections.

Remarks

The function fails (returns -1) if the statement handle is busy or a connection is in manual commit mode. The AERROR( ) Function can be used to obtain information about the cause of the error.

A temporarily disconnected connection is automatically restored as soon as it is needed to perform an operation; the original connection string is used. The ODBC ODBChstmt property returns 0 if the statement handle is temporarily released and the ODBChdbc property returns 0 if the connection is temporarily disconnected. A shared connection is temporarily disconnected as soon as all its statement handles are temporarily disconnected (released).

See Also

Reference

AERROR( ) Function
SQLCONNECT( ) Function

Concepts

Managing Connections with SQL Pass-Through

Other Resources

Enhancing Applications Using SQL Pass-Through Technology


SQLMORERESULTS( ) Function

Visual FoxPro 9.0 Language Reference
SQLMORERESULTS( ) Function
See Also Example

Copies another result set to a Visual FoxPro cursor if more result sets are available.

SQLMORERESULTS(nStatementHandle [, cCursorName [, aCountInfo]]))

Parameters

nStatementHandle

Specifies the statement handle to the data source returned by SQLCONNECT( ).
cCursorName

Specifies the name of the Visual FoxPro cursor to which the result set is sent. If you do not include a cursor name, Visual FoxPro uses the default name SQLRESULT. For multiple result sets, new cursor names are derived by appending an incremented number to the name of the first cursor.
aCountInfo

Specifies the name of the array to populate with row count information. If the array doesn’t exist, it is created. The array has two columns: 1 – Alias, 2 –Count.

Column Array contents Data type Description

Alias

0

Character

Indicates that SQL command did not return any results. Either no records were returned or the SQL command failed before results could be returned. (final SQLMORERESULTS call) or execution failed before any result could be processed. Can be only on the first row. Count column for the row contains value -1.

Non-empty uppercase string

Character

Alias of the cursor – target for the record fetch operation. The Count column for the row contains the number of fetched records or -1 if fetch failed. If Count is -1, cursor may not have been created. During asynchronous execution, the fetch process for a cursor can be split between multiple SQLMORERESULTS or SQLEXEC calls; each call returns its own fetch count for the cursor.

Empty String

Character

Indicates that the SQL command (INSERT, UPDATE, or DELETE) did not return a result set.

Count

Number of affected or fetched records.

Integer

Indicates the number of affected records as returned by the ODBC SQLRowCount function.

Returns -1 if the number of records is unavailable.

Return Value

Numeric. SQLMORERESULTS( ) returns 0 if the SQL statement is still executing, returns 1 if it is finished executing, and returns 2 if no more data is found. In non-batch mode, SQLMORERESULTS( ) should be called after each successful SQLEXEC( ) call until SQLMORERESULTS( ) returns 2 (no more data found). The setting of the SQLSETPROP( ) batch mode option determines whether SQLEXEC( ) executes a SQL statement in batch or non-batch mode.

SQLMORERESULTS( ) returns – 1 if a connection level error occurs, and returns – 2 if an environment level error occurs.

Remarks

SQLMORERESULTS( ) determines if more result sets are available from a SQL statement executed with SQLEXEC( ) in non-batch mode. If more result sets are available, they are copied to a Visual FoxPro cursor, one set at a time.

SQLMORERESULTS( ) is one of the four functions that you can execute either synchronously or asynchronously. The asynchronous setting of SQLSETPROP( ) determines if these functions execute synchronously or asynchronously. In asynchronous mode, you must call SQLMORERESULTS( ) repeatedly until it returns a value other than 0 (still executing).

Example

The following example assumes SQLCONNECT( ) is successfully issued, and its return value is stored to a memory variable named gnHandle. SQLSETPROP( ) is used to set the BatchMode property to False (.F.) so the individual result sets can be retrieved.

SQLMORERESULTS( ) is issued twice to create two cursors containing the results of the SQLEXEC( ) query. SET is used to display the View window and the cursors created by SQLEXEC( ).
Copy Code
= SQLSETPROP(gnHandle, 'BatchMode', .F.)  && Individual result sets
= SQLEXEC(gnHandle, 'SELECT * FROM authors;
   SELECT * FROM titles')
= SQLMORERES(gnHandle)  && First result set
= SQLMORERES(gnHandle)  && Second result set

See Also

Other Resources

AERROR( ) Function
SQLCANCEL( ) Function
SQLCONNECT( ) Function
SQLEXEC( ) Function
SQLGETPROP( ) Function
SQLSETPROP( ) Function
SQL Commands and Functions
Language Reference


SQLPREPARE( ) Function

Visual FoxPro 9.0 Language Reference
SQLPREPARE( ) Function
See Also Example

Prepares a SQL statement for remote execution by SQLEXEC( ).

SQLPREPARE(nStatementHandle, cSQLCommand, [cCursorName])

Parameters

nStatementHandle

Specifies the statement handle to the data source returned by SQLCONNECT( ).
cSQLCommand

Specifies the SQL statement passed to the data source. The SQL statement can contain a parameterized WHERE clause, which creates a parameterized view. All parameters in the WHERE clause must be defined before SQLPREPARE( ) is issued. For example, if the parameters are variables, the variables must be created and initialized before SQLPREPARE( ) is issued. For more information about parameterized views, see How to: Create Parameterized Views.
cCursorName

Specifies the name of the Visual FoxPro cursor to which the result set is sent. If you don't include a cursor name, Visual FoxPro uses the default name SQLRESULT. For multiple result sets, new cursor names are derived by appending an incremented number to the name of the first cursor.

Return Value

Numeric

Remarks

SQLPREPARE( ) sends the SQL statement to the data source where it is compiled for faster execution. After the SQL statement is compiled, it can be executed with SQLEXEC( ). If SQLEXEC( ) is used to execute a SQL statement prepared with SQLPREPARE( ), only the statement handle is required in SQLEXEC( ).

Example

Copy Code
gcAuthor = 'Smith'
= SQLPREPARE(gnHandle, 'SELECT * FROM authors;   WHERE au_lname = ?gcAuthor')
= SQLEXEC(gnHandle)
...
gcAuthor = 'Jones'
= SQLEXEC(gnHandle)

See Also

Other Resources

SQLCONNECT( ) Function
SQLEXEC( ) Function
SQL Commands and Functions
Language Reference


SQLROLLBACK( ) Function

Visual FoxPro 9.0 Language Reference
SQLROLLBACK( ) Function
See Also Example

Cancels any changes made during the current transaction.

SQLROLLBACK(nStatementHandle)

Parameters

nStatementHandle

Specifies the statement handle to the data source returned by SQLCONNECT( ).

Return Value

Numeric. SQLROLLBACK( ) returns 1 if the transaction is successfully rolled back; otherwise, it returns -1. If SQLROLLBACK( ) returns -1, you can use AERROR( ) to determine why the transaction could not be rolled back.

Remarks

If manual transactions are in effect (the SQLSETPROP( ) transaction property is set to manual), you can send multiple updates to remote tables. The updates can all be rolled back with SQLROLLBACK( ).

Updates can be committed with SQLCOMMIT( ).

Example

The following example assumes SQLCONNECT( ) is successfully issued, and its return value is stored to a memory variable named gnHandle. SQLSETPROP( ) is used to set the Transactions property to 2 (manual), making it possible for you to use SQLCOMMIT( ) and SQLROLLBACK( ).

The authors table is modified with SQLEXEC( ), and the changes to the table are cancelled with SQLROLLBACK( ).
Copy Code
= SQLSETPROP(gnHandle, 'Transactions', 2)  && manual
= SQLEXEC(gnHandle, "INSERT INTO authors (au_id, au_lname);
   VALUES ('aupoe', 'Poe')")
= SQLROLLBACK(gnHandle)

See Also

Other Resources

AERROR( ) Function
SQLCOMMIT( ) Function
SQLCONNECT( ) Function
SQLSETPROP( ) Function
SQL Commands and Functions
Language Reference


SQLSETPROP( ) Function

Visual FoxPro 9.0 Language Reference
SQLSETPROP( ) Function
See Also Example

Specifies settings for an active connection. You can use SQLSETPROP( ) to specify settings at the connection level. To specify Visual FoxPro default settings at the environment level, include 0 as the statement handle.

SQLSETPROP(nStatementHandle, cSetting [, eExpression])

Parameters

nStatementHandle

Specifies the statement handle to the data source returned by SQLCONNECT( ).
cSetting

Specifies the setting. The following table lists the values for cSetting.

Setting Description

Asynchronous

Specifies whether result sets are returned synchronously (False (.F.), the default), or asynchronously (True (.T.)). Read/write.

BatchMode

Specifies whether SQLEXEC( ) returns result sets all at once (True (.T.), the default), or individually with SQLMORERESULTS( ) (False (.F.)). Read/write.

ConnectBusy

Contains True (.T.) if a shared connection is busy; otherwise contains False (.F.). Read-only.

ConnectString

The login connection string. Read-only.

ConnectTimeOut

Specifies the time to wait (in seconds) before returning a connection time-out error. If you specify 0, the wait is indefinite and a time-out error is never returned. ConnectTimeOut can be 0 to 600. The default is 15. Read/write.

DataSource

The name of the data source as defined in the ODBC.INI file. Read/write.

DisconnectRollback

Specifies if a pending transaction is committed or rolled back when SQLDISCONNECT( ) is called for the last connection handle.

The default is false (.F.), indicating that a pending transaction is committed when SQLDISCONNECT( ) is called for the last connection handle.

Specify true (.T.) to roll back a pending transaction when SQLDISCONNECT( ) is called for the last connection handle.

Connections with automatic transaction processing are not affected by this setting.

Read/write.

DispLogin

Contains a numeric value that determines when the ODBC Login dialog box is displayed. DispLogin may assume the following values:

1 or DB_PROMPTCOMPLETE (from FOXPRO.H).1 is the default.

2 or DB_PROMPTALWAYS (from FOXPRO.H).

3 or DB_PROMPTNEVER (from FOXPRO.H).

If 1 or DB_PROMPTCOMPLETE is specified, Visual FoxPro displays the ODBC Login dialog box only if any required information is missing.

If 2 or DB_PROMPTALWAYS is specified, the ODBC Login dialog box is always displayed, making it possible for you to change settings before connecting.

If 3 or DB_PROMPTNEVER is specified, the ODBC Login dialog box isn't displayed and Visual FoxPro generates an error if the required login information isn't available. Read/write.

DispWarnings

Specifies if error messages are displayed (True (.T.)) or are not displayed (False (.F.), the default). Read/write.

IdleTimeout

The idle timeout interval in minutes. Active connections are deactivated after the specified time interval. The default value is 0 (wait indefinitely). Read/write.

ODBChdbc

The internal ODBC connection handle, which may be used by external library files (FLL files) to call ODBC. Read-only.

ODBChstmt

The internal ODBC statement handle, which may be used by external library files (FLL files) to call ODBC. Read-only.

PacketSize

The size of the network packet used by the connection. Adjusting this value can improve performance. The default value is 4096 bytes (4K). Read/write

Password

The connection password. Read-only.

QueryTimeOut

Specifies the time to wait (in seconds) before returning a general time-out error. If you specify 0 (the default), the wait is indefinite and a time-out error is never returned. QueryTimeOut can be 0 to 600. Read/write.

Shared

Specifies whether the underlying connection is a shared connection (True (.T.)), or not (False (.F.)).

Read-only.

Transactions

Contains a numeric value that determines how the connection manages transactions on the remote table. Transactions may assume the following values:

1 or DB_TRANSAUTO (from FOXPRO.H).1 is the default. Transaction processing for the remote table is automatically handled.

2 or DB_TRANSMANUAL (from FOXPRO.H). Transaction processing is handled manually through SQLCOMMIT( ) and SQLROLLBACK( ). Read/write.

UserId

The user identification. Read-only.

WaitTime

The amount of time in milliseconds that elapses before Visual FoxPro checks if the SQL statement has completed executing. The default is 100 milliseconds. Read/write.
eExpression

Specifies the value for the setting you designate with cSetting. If you omit eExpression, the default value is restored for the setting.

Return Value

Numeric data type. SQLSETPROP( ) returns 1 if it is successful. Otherwise, it returns – 1 if a connection level error occurs or – 2 if an environment level error occurs.

Remarks

You can use SQLGETPROP( ) to return the current value for a specified setting.

Note:
You must disable the Open Database Connectivity (ODBC) login dialog box to support SQL pass through with Microsoft Transaction Server. To disable the ODBC login dialog box, use the statement SQLSETPROP(cStatementHandle, 'DispLogin', 3), where cStatementHandle is the statement handle returned by SQLCONNECT( ). You can also disable the ODBC login dialog box in the Connection Designer.

The ConnectTimeOut option can be set only at the Visual FoxPro level and has no equivalent at the connection level. You can set all other options at either the connection or the Visual FoxPro level. Each option set at the Visual FoxPro level serves as a default value for subsequent connections.

Example

The following example shows how SQLSETPROP( ) is used to set the packet size for the current connection. SQLCONNECT( ) displays the Select Connection or Data Source Dialog Box for you to choose a connection, and the connection is tested. The packet size is set; the setting is tested; and the results are displayed.
Copy Code
CLOSE ALL
CLEAR ALL
CLEAR
nHandle=SQLCONNECT()
IF nHandle > 0
   nSet=SQLSETPROP(nHandle, "PacketSize", 2048 )
   IF nSet > 0
      =MESSAGEBOX("PacketSize was set to 2048",0,"Connection Results")
   ELSE
      =MESSAGEBOX("Error setting PacketSize",0,"Connection Results")
   ENDIF
ELSE
   =MESSAGEBOX("No Connection",0,"Connection Results")
ENDIF
=SQLDISCONNECT(nHandle)

See Also

Other Resources

AERROR( ) Function
SQLGETPROP( ) Function
Connection Designer
SQL Commands and Functions
Language Reference


SQLSTRINGCONNECT( ) Function

Visual FoxPro 9.0 Language Reference
SQLSTRINGCONNECT( ) Function
See Also Example

Establishes a connection to a data source using a connection string.

SQLSTRINGCONNECT([lShared] | [cConnectString [, lSharable]])

Parameters

lShared

Specifies whether to create a shared connection.

lShared Description

False (.F.)

SQLSTRINGCONNECT( ) does not create a shared connection. (Default)

True (.T.)

SQLSTRINGCONNECT( ) creates a shared connection.
cConnectString

Specifies the data source connection string required by some Open Database Connectivity (ODBC) drivers. Visual FoxPro passes the connection string to the ODBC driver. For more information about data source connection strings, see your ODBC driver documentation. You can also choose a data source from the Select Connection or Data Source Dialog Box, which appears when you call SQLSTRINGCONNECT( ) without cConnectString.
lSharable

Specifies if the data source specified with cConnectString has a shared connection.

Return Value

Numeric data type. SQLSTRINGCONNECT( ) returns a positive nonzero numeric value as the statement handle if you successfully connect to the data source. SQLSTRINGCONNECT( ) returns –1 if it cannot make the connection.

Tip:
You should store this statement handle in a memory variable and use the variable in subsequent function calls that require a connection handle.

Remarks

The SQLCONNECT( ) and SQLSTRINGCONNECT( ) functions return a numeric value as the statement handle rather than a connection handle. You cannot obtain a connection handle directly. You can still set and get connection properties using the SQLSETPROP( ) and SQLGETPROP( ) functions by passing the statement handle for that connection and the string, "Shared", as arguments. All other SQL functions use a statement handle instead of a connection handle.

SQLSTRINGCONNECT( ) always creates a new connection when it successfully makes a connection. However, setting the lShared parameter determines whether you can share the connection later. If you specify a connection as shareable by setting lShared to True (.T.), you can share the connection later by calling SQLCONNECT( ) and passing the numeric value of the connection handle as the first parameter. For more information, see SQLCONNECT( ) Function.

You can use SQLCONNECT( ) to obtain a new statement handle on a shared connection that was opened using SQLSTRINGCONNECT( ).

Example

Example 1

The following example assumes that an ODBC data source called MyFoxSQLNT exists and is available. SQLSTRINGCONNECT( ) returns a numeric value, which is stored to a variable named gnHandle.

If you successfully connect to the data source, SQLSTRINGCONNECT( ) returns a positive number, a dialog box appears, and SQLDISCONNECT( ) is called to disconnect from the data source.

If you cannot connect to the data source, SQLSTRINGCONNECT( ) returns a negative number and displays a message.

Copy Code
STORE SQLSTRINGCONNECT('dsn=MyFoxSQLNT;uid=myUserID;pwd=myPassword')
   TO gnConnHandle
IF gnConnHandle < 0
   = MESSAGEBOX('Cannot make connection', 16, 'SQL Connect Error')
ELSE
   = MESSAGEBOX('Connection made', 48, 'SQL Connect Message')
   = SQLDISCONNECT(gnHandle)
ENDIF

Example 2

The following examples show how you can use the SQLSTRINGCONNECT( ) function without a Data Source Name (DSN).

Copy Code
lcDSNLess="driver = SQL Server;server=<servername>;uid=<userid>;pwd=<password>"

-or-

Copy Code
lcDSNLess="driver = {SQL Server};server=<servername>;uid=<userid>;pwd=<password>"

-or-

Copy Code
lcDSNLess="DRIVER = {SQL Server};" ;
+ "SERVER=<servername>;" ;
+ "UID=<userid>;" ;
+ "PWD=<password>;" ;
+ "DATABASE=PUBS;" ;
+ "WSID=<machine name or userid>;" ;
+ "APP=MicroX(R) Sample App"
lnConnHandle=SQLSTRINGCONNECT(m.lcDSNLess)

Example 3

Each of the following examples creates a new shared connection. In the first statement, the Select Connection or Data Source Dialog Box appears and SQLSTRINGCONNECT( ) creates the resulting connection as shared.

Copy Code
SQLSTRINGCONNECT(.T.)
SQLSTRINGCONNECT('myConnectionString', .T.)

See Also

Other Resources

AERROR( ) Function
SQLCONNECT( ) Function
SQLDISCONNECT( ) Function
SQL Commands and Functions
Language Reference


SQLTABLES( ) Function

Visual FoxPro 9.0 Language Reference
SQLTABLES( ) Function
See Also Example

Stores the names of tables in a data source to a Visual FoxPro cursor.

SQLTABLES(nStatementHandle [, cTableTypes] [, cCursorName])

Parameters

nStatementHandle

Specifies the statement handle to the data source returned by SQLCONNECT( ).
cTableTypes

Specifies one or more table types. Valid table types are 'TABLE,' 'VIEW,' 'SYSTEM TABLE,' or any valid data source-specific table type identifier. If you include a list of table types, separate the table types with commas. All table names in the data source are selected if you omit cTableTypes or if cTableTypes is the empty string. The table type you specify must be delimited with single quotation marks. The following example demonstrates how to specify the 'VIEW' and 'SYSTEM TABLE' table types as a string literal.
Copy Code
? SQLTABLES(handle, "'VIEW', 'SYSTEM TABLE'", "mydbresult")
cCursorName

Specifies the name of the Visual FoxPro cursor to which the result set is sent. If you don't include a cursor name, Visual FoxPro uses the default name SQLRESULT. The structure of the results depends on the internal SQLTABLES( ) function for the ODBC Handle.

Return Value

Numeric. SQLTABLES( ) returns 1 if the cursor is successfully created, 0 if SQLTABLES( ) is still executing, – 1 if a connection level error occurs, and – 2 if an environment level error occurs.

Remarks

SQLTABLES( ) is one of the four functions that you can execute either synchronously or asynchronously. The setting of the SQLSETPROP( ) asynchronous option determines if these functions execute synchronously or asynchronously. In asynchronous mode, you must call SQLTABLES( ) repeatedly until it returns a value other than False (.F.), meaning the function is still executing.

Example

The following example assumes an ODBC data source called MyFoxSQLNT is available. SQLCONNECT( ) is issued, and its return value is stored to a variable named gnHandle.

If you cannot connect to the data source, SQLCONNECT( ) returns a negative number and a message is displayed.

If you successfully connect to the data source, SQLCONNECT( ) returns a positive number and a dialog is displayed. SQLTABLES( ) is used to create a cursor named mycursor that contains information about tables in the data source. LIST is used to display information about the tables.
Copy Code
STORE SQLCONNECT('MyFoxSQLNT', '<userid>', '<password>') TO gnConnHandle
IF gnConnHandle < 0
   = MESSAGEBOX('Cannot make connection', 16, 'SQL Connect Error')
ELSE
   = MESSAGEBOX('Connection made', 48, 'SQL Connect Message')
   STORE SQLTABLES(gnConnHandle, 'TABLE', 'mycursor') TO nTables
   IF nTables = 1
      SELECT mycursor
      LIST
   ENDIF
ENDIF

See Also

Other Resources

AERROR( ) Function
SQLCOLUMNS( ) Function
SQLCONNECT( ) Function
SQLGETPROP( ) Function
SQLSETPROP( ) Function
SQL Commands and Functions
Language Reference


SQRT( ) Function

Visual FoxPro 9.0 Language Reference
SQRT( ) Function
See Also Example

Returns the square root of the specified numeric expression.

SQRT(nExpression)

Parameters

nExpression

Specifies the numeric expression SQRT( ) evaluates. nExpression cannot be negative.

Return Value

Numeric

Remarks

The number of decimal places in the value returned by SQRT( ) is the larger of the current decimal place setting and the number of decimal places contained in nExpression. The current decimal place setting is specified with SET DECIMALS.

Example

Copy Code
CLEAR
? SQRT(4)  && Displays 2.00
? SQRT(2*SQRT(2))  && Displays 1.68

See Also

Other Resources

SET DECIMALS Command
COS( ) Function
SIN( ) Function
Functions
Language Reference


SROWS( ) Function

Visual FoxPro 9.0 Language Reference
SROWS( ) Function
See Also Example

Returns the number of rows available in the main Visual FoxPro window.

SROWS( )

Return Value

Numeric

Remarks

In Visual FoxPro for Windows, the value returned by SROWS( ) depends on the current display mode. The display mode can be changed with SET DISPLAY.

Example

Copy Code
CLEAR
? SROWS( )

See Also

Other Resources

COL( ) Function
ROW( ) Function
SCOLS( ) Function
SET DISPLAY Command
WCOLS( ) Function
WROWS( ) Function
Functions
Language Reference


STR( ) Function

Visual FoxPro 9.0 Language Reference
STR( ) Function
See Also

Returns the character equivalent of a numeric expression.

STR(nExpression [, nLength [, nDecimalPlaces]])

Parameters

nExpression

Specifies the numeric expression to evaluate.
nLength

Specifies the length of the character string returned. If nLength is omitted, nLength defaults to 10 characters.
Note:
If the expression contains a decimal point, the length includes one character for the decimal point and one character for each digit in the character string.

nDecimalPlaces

Specifies the number of decimal places in the character string returned. To specify the number of decimal places using nDecimalPlaces, you must include nLength. If nDecimalPlaces is omitted, the number of decimal places defaults to zero (0).
Note:
Visual FoxPro contains a limit of 16 digits of precision in numeric calculations. For more information about numeric precision in Visual FoxPro, see Visual FoxPro System Capacities.

Return Value

Character data type. STR( ) returns a character string equivalent to the specified numeric expression.

Depending on certain conditions, STR( ) can return the following:

  • If you specify fewer decimal places than exist in nExpression, the return value is rounded up. To round results to the nearest decimal place instead of upward, include the ROUND( ) function. For more information, see ROUND( ) Function.

  • If nExpression is an integer, and nLength is less than the number of digits in nExpression, STR( ) returns a string of asterisks, indicating numeric overflow.

  • If nExpression contains a decimal point, and nLength is equal to or less than the number of digits to the left of the decimal point, STR( ) returns a string of asterisks, indicating numeric overflow.

  • If nLength is greater than the length of the value evaluated by nExpression, STR( ) returns a character string padded with leading spaces.

  • If nExpression has Numeric or Float type, and nLength is less than the number of digits in nExpression, and , STR( ) returns a value using scientific notation.

Examples

Example 1

In the following example, STR( ) evaluates 1.154994 as a character expression, specifies a length of 8 characters and the same number of decimal places that the specified expression contains, and displays 1.154994 using the ? command.

Copy Code
? STR(1.154995,8,6)

Example 2

In the following example, STR( ) evaluates 1.154994 as a character expression and specifies a length of 8 characters and 2 decimal places, four fewer decimal places than the specified expression contains. STR( ) displays 1.16 using the ? command, which represents 1.154994 rounded upward.

Copy Code
? STR(1.154995,8,2)

Example 3

In the following example, STR( ) includes the ROUND( ) function, evaluates 1.154994 as a character expression, and specifies a length of 8 characters 2 decimal places, four fewer decimal places than the specified expression contains. STR( ) displays 1.15 using the ? command, which represents 1.154994, rounded to the nearest significant digit.

Copy Code
? STR(ROUND(1.154995,2),8,2)

See Also

Other Resources

VAL( ) Function
Creating Numeric Expressions
STRCONV( ) Function
Functions
Language Reference


STRCONV( ) Function

Visual FoxPro 9.0 Language Reference
STRCONV( ) Function
See Also

Converts character expressions between single-byte, double-byte, UNICODE, and locale-specific representations.

STRCONV(cExpression, nConversionSetting [, nRegionalIdentifier [, nRegionalIDType]])

Parameters

cExpression

Specifies the character expression that STRCONV( ) converts.
nConversionSetting

Specifies the type of conversion. The following table lists the values of nConversionSetting and the type of conversion performed.

nConversionSetting Conversion

1

Converts single-byte characters in cExpression to double-byte characters.

Supported for Locale ID only (specified with the nRegionalIdentifier or nRegionalIDType parameters).

2

Converts double-byte characters in cExpression to single-byte characters.

Supported for Locale ID only (specified with the nRegionalIdentifier or nRegionalIDType parameters).

3

Converts double-byte Katakana characters in cExpression to double-byte Hiragana characters.

Supported for Locale ID only (specified with the nRegionalIdentifier or nRegionalIDType parameters).

4

Converts double-byte Hiragana characters in cExpression to double-byte Katakana characters.

Supported for Locale ID only (specified with the nRegionalIdentifier or nRegionalIDType parameters).

5

Converts double-byte characters to UNICODE (wide characters).

6

Converts UNICODE (wide characters) to double-byte characters.

7

Converts cExpression to locale-specific lowercase.

Supported for Locale ID only (specified with the nRegionalIdentifier or nRegionalIDType parameters).

8

Converts cExpression to locale-specific uppercase.

Supported for Locale ID only (specified with the nRegionalIdentifier or nRegionalIDType parameters).

9

Converts double-byte characters in cExpression to UTF-8

10

Converts Unicode characters in cExpression to UTF-8

11

Converts UTF-8 characters in cExpression to double-byte characters.

12

Converts UTF-8 characters in cExpression to UNICODE characters.

13

Converts single-byte characters in cExpression to encoded base64 binary.

14

Converts base64 encoded data in cExpression to original unencoded data.

15

Converts single-byte characters in cExpression to encoded hexBinary.

16

Converts single-byte characters in cExpression to decoded hexBinary.
nRegionalIdentifier

Specifies the Locale ID, code page, or FontCharSet value to use for the conversion. If nRegionalIDType is omitted, the Locale ID is used for the conversion. If nRegionalIdentifier is omitted, the system locale ID is used by default. If nRegionalIdentifier is invalid or not supported on the machine, the error "Invalid locale ID" is generated.

nRegionalIdentifier Language

1029

Czech

1031

German

1033

English (Default)

1034

Spanish

1036

French

1040

Italian

1045

Polish

1046

Portuguese (Brazil)

2070

Portuguese (Portugal)
nRegionalIDType

Specifies if a Locale ID, code page, or FontCharSet is used for the conversion. The nRegionalIdentifier parameter, described above, is used to specify the actual Locale ID, code page, or FontCharSet used for the conversion.

nRegionalIDType Description

0

(Default) Specifies that the nRegionalIdentifier parameter is a Locale ID value.

1

Specifies that nRegionalIdentifier is a code page value.

2

Specifies that nRegionalIdentifier is a FontCharSet value.

Return Value

Character data type. STRCONV( ) returns the converted character expression.

Remarks

Visual FoxPro disregards invalid characters or incorrect length in base 64- and hexBinary- encoded strings.

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

CHRTRANC( ) Function
IMESTATUS( ) Function
ISLEADBYTE( ) Function
Functions
Language Reference


STREXTRACT( ) Function

Visual FoxPro 9.0 Language Reference
STREXTRACT( ) Function
See Also Example

Retrieves a string between two delimiters.

STREXTRACT(cSearchExpression, cBeginDelim [, cEndDelim [, nOccurrence
[, nFlag]]]])

Parameters

cSearchExpression

Specifies the string to search.
cBeginDelim

Specifies the character that delimits the beginning of cSearchExpression.
cEndDelim

Specifies the character that delimits the end of cSearchExpression.
nOccurrence

Specifies at which occurrence of cBeginDelim in cSearchExpression to start the extraction.
nFlag

Specify the type of controls placed on the search. The number you specify in nFlag provides a bit-value that determines options according to the following table:

Bit Value (additive) Description

0

1

Case-insensitive search

1

2

End delimiter not required. Specifies that a search, which finds no occurrence of cEndDelim, returns the contents of cSearchExpression from the cBeginDelim location.

2

4

Include the delimiters in the returned expression.

Returns

Character

Remarks

The default is a case sensitive search in which delimiters must be found (no nFlag value).

If cBeginDelim is an empty string, the search is conducted from the beginning of cSearchExpression to the first occurrence of cEndDelim. If cEndDelim is an empty string STREXTRACT( ) returns a string from nOccurrence of cBeginDelim to the end of cSearchExpression.

Example

Copy Code
CLEAR
SET PATH TO (HOME(2) + 'Data\')   &&Set path to the customer table
USE customer && any table
?cursortoxml(0,"x",1,0,2)   && Produce variable "x" that has XML of  first 2 records of table
?x         && show the XML
xmlproc(x,0)      && Parse the XML

PROCEDURE xmlproc(x as String, nLev as Integer)   as void
   LOCAL cTagName, cContents, mterm
   DO WHILE .t.
      cTagName = STREXTRACT(x,"<",">")
      IF LEN(cTagName) = 0   && no tag found
         ??' ',x   && print out raw string as contents
         EXIT
      ENDIF
      IF RIGHT(cTagName,1) = '/'   && like "<region/>"
         cTagName = LEFT(cTagName, LEN(cTagName)-1)
         cContents=""
         mterm = "<"+cTagName+"/>"   && "<region/>"
      ELSE
         mterm = "</"+cTagName+">"   && "</region>"
         cContents = STREXTRACT(x,"<"+cTagName+">", mterm,1,2)
      ENDIF
      ?REPLICATE("  ",nLev),nLev+1,PADR(cTagName,20)
      xmlproc(cContents, nLev+1)
      x = STREXTRACT(x, mterm)   && get the rest of the xml
   ENDDO

See Also

Other Resources

STRTRAN( ) Function
RAT( ) Function
RATC( ) Function
SUBSTR( ) Function
SUBSTRC( ) Function
LIKEC( ) Function
Functions
Language Reference


STRTOFILE( ) Function

Visual FoxPro 9.0 Language Reference
STRTOFILE( ) Function
See Also

Writes the contents of a character string to a file.

Note:
STRTOFILE( ) does not write to hidden files when running Visual FoxPro on Windows 2000 and later.

STRTOFILE(cExpression, cFileName [, lAdditive | nFlag])

Parameters

cExpression

Specifies the character string that is written to the file. cExpression can be a literal character string, an expression that evaluates to a character string, or a character type variable, array element, or field.
cFileName

Specifies the name of the file to which the character string is written. Include a path with the file name if the file is in a directory other than the current default directory. If the file you specify does not exist, Visual FoxPro automatically creates it.
lAdditive (for backward compatibility)

Specifies whether the character string is appended to the end of the file. If lAdditive is true (.T.), the character string is appended to the end of the file. If lAdditive is false (.F.) (the default), the file is overwritten with the character string. You are asked if you want to overwrite an existing file if SET SAFETY is set to ON. If SET SAFETY is set to OFF, the file is overwritten without warning.
nFlag

Beginning with Visual FoxPro 7, you can use the nFlag parameter instead of lAdditive which enables you to also chose to write UTF-8 and Unicode Byte Order Marks. The following table describes the valid nFlag values.

nFlag Bit Description

0 (default)

0000

The file is overwritten with the character string (formerly lAdditive=.f.)

1

0001

The string is appended to the end of the file (formerly lAdditive=.t.).

2

0010

Write Unicode Byte Order Mark (BOM) FF FE at the beginning of file. cExpression is assumed to be UNICODE, therefore no translation is performed. The file is overwritten

4

0100

Write UTF-8 Byte Order Mark (BOM) EF BB BF at the beginning of file. cExpression is assumed to be UTF-8, therefore no translation is performed. The file is overwritten.

Return Value

Numeric; the number of bytes written to the file.

Remarks

An nFlag value of 3 or 5 is not valid. You cannot attempt to write a new Byte Order Mark if nFlag bit 1, Additive, is set.

Unlike earlier versions of Visual FoxPro, STRTOFILE( ) opens a file in Shared rather than Exclusive mode. This is useful when multiple servers attempt to simultaneously write to the same file. Because of this change, you might not need to check for STRTOFILE( ) to return 0 (failure to open a file).

See Also

Other Resources

FILETOSTR( ) Function
FWRITE( ) Function
SET SAFETY Command
Functions
Language Reference


STRTRAN( ) Function

Visual FoxPro 9.0 Language Reference
STRTRAN( ) Function
See Also Example

Searches a character expression or memo field for a second character expression or memo field and replaces each occurrence with a third character expression or memo field. You can specify where the replacement begins and how many replacements are made.

STRTRAN(cSearched, cExpressionSought [, cReplacement]
   [, nStartOccurrence] [, nNumberOfOccurrences] [, nFlags])

Parameters

cSearched

Specifies the character expression to search. cSearched can be a memo field.
cExpressionSought

Specifies the character expression to search for in cSearched. The search is case-sensitive. cExpressionSought can be a memo field.
[, cReplacement]

Specifies the character expression to replace every occurrence of cSearchFor in cSearched. Omitting cReplacement replaces every occurrence of cExpressionSought with an empty string.
[, nStartOccurrence]

Specifies which occurrence of cExpressionSought to replace first. For example, if nStartOccurrence is 4, replacement begins with the fourth occurrence of cExpressionSought in cSearched and the first three occurrences of cExpressionSought remain unchanged. Omitting nStartOccurrence defaults the occurrence where replacement begins to the first occurrence of cExpressionSought.
[, nNumberOfOccurrences]

Specifies the number of occurrences of cExpressionSought to replace. Omitting nNumberOfOccurrences replaces all occurrences of cExpressionSought, starting with the occurrence specified with nStartOccurrence.
[, nFlags]

Specifies the case-sensitivity of a search according to the following values.
Note:
If you need to specify only the nFlags setting along with the required parameters, specify –1 for the optional parameters you want disregarded.

The following table lists the values for nFlags:

nFlags Description

0 or -1

Search is case-sensitive and replacement is performed with exact cReplacement text. (Default)

Note:
This setting specifies the original behavior for STRTRAN( ) in versions prior to Visual FoxPro 7.0. You can also specify default behavior by passing –1 as the nFlags value.

1

Search is case-insensitive and replacement is performed with exact cReplacement text.

2

Search is case-sensitive and replacement is performed with the case of cReplacement changed to match the case of the string found.

3

Search is case-insensitive and replacement is performed with the case of cReplacement changed to match the case of the string found.

Note:
The case of cReplacement changes only if the string found is all uppercase, lowercase, or proper case.

Return Value

Character. STRTRAN( ) returns the resulting character string.

Example

The following example stores the string "abracadabra" to the variable gcString using the STORE command. The STRTRAN( ) function replaces the character "a" with the character "z" and displays the string "zbrzczdzbrz" using the ? command. STRTRAN( ) then replaces three occurrences of the character "a", beginning with the second occurrence, with the character "q" and displays "abrqcqdqbra".
Copy Code
STORE 'abracadabra' TO gcString
? STRTRAN(gcString, 'a', 'z')
? STRTRAN(gcString, 'a', 'q', 2, 3)

See Also

Other Resources

CHRTRAN( ) Function
CHRTRANC( ) Function
STUFF( ) Function
Creating Character Expressions
STUFFC( ) Function
Functions
Language Reference


STUFF( ) Function

Visual FoxPro 9.0 Language Reference
STUFF( ) Function
See Also Example

Returns a character string created by replacing a specified number of characters in a character expression with another character expression.

STUFF(cExpression, nStartReplacement, nCharactersReplaced, cReplacement)

Parameters

cExpression

Specify the character expression in which the replacement occurs.
nStartReplacement

Specifies the position in cExpression where the replacement begins.
nCharactersReplaced

Specifies the number of characters to be replaced. If nCharactersReplaced is 0, the replacement string cReplacement is inserted into cExpression.
cReplacement

Specifies the replacement character expression. If cReplacement is the empty string, the number of characters specified by nCharactersReplaced are removed from cExpression.

Return Value

Character

Example

Copy Code
STORE 'abcdefghijklm' TO gcString1
STORE '12345' TO gcString2
CLEAR
? STUFF(gcString1, 4, 0, gcString2)     && insert
? STUFF(gcString1, 4, 3, gcString2)     && replace
? STUFF(gcString1, 4, 6, '')     && delete
? STUFF(gcString1, 4, 1, gcString2)     && replace and insert
? STUFF(gcString1, 4, 4, gcString2)     && replace and delete
? STUFF(gcString1, 4, LEN(gcString1), gcString2)   && replace, delete rest

See Also

Other Resources

LEFT( ) Function
PADC( ) | PADL( ) | PADR( ) Function
RIGHT( ) Function
STRTRAN( ) Function
SUBSTR( ) Function
Functions
Language Reference


STUFFC( ) Function

Visual FoxPro 9.0 Language Reference
STUFFC( ) Function
See Also

Returns a character string created by replacing a specified number of characters in a character expression with another character expression.

STUFFC(cExpression, nStartReplacement, nCharactersReplaced, cReplacement)

Parameters

cExpression

Specify the character expression in which the replacement occurs.
nStartReplacement

Specifies the character position in cExpression where the replacement begins.
nCharactersReplaced

Specifies the number of characters to be replaced. If nCharactersReplaced is 0, the entire replacement string cReplacement is inserted into cExpression.
cReplacement

Specifies the replacement character expression. If cReplacement is the empty string, the number of characters specified by nCharactersReplaced are removed from cExpression.

Return Value

Character

Remarks

STUFFC( ) is designed for expressions containing double-byte characters. If the expression contains only single-byte characters, STUFFC( ) is equivalent to STUFF( ).

STUFFC( ) returns a character string created by replacing a specified number of characters in a character expression with another character expression. The character expressions can consist of any combination of single-byte and double-byte characters.

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

LEFTC( ) Function
RIGHTC( ) Function
STUFF( ) Function
SUBSTRC( ) Function
Functions
Language Reference


SUBSTR( ) Function

Visual FoxPro 9.0 Language Reference
SUBSTR( ) Function
See Also Example

Returns a character string from the given character expression or memo field, starting at a specified position in the character expression or memo field and continuing for a specified number of characters.

SUBSTR(cExpression, nStartPosition [, nCharactersReturned])

Parameters

cExpression

Specifies the character expression or memo field from which the character string is returned.
nStartPosition

Specifies the position in the character expression or memo field cExpression from where the character string is returned. The first character of cExpression is position 1.
Note:
If nStartPosition is greater than the number of characters in cExpression, SUBSTR( )returns an empty string ("").

nCharactersReturned

Specifies the number of characters to return from cExpression. If you omit nCharactersReturned, characters are returned until the end of the character expression is reached.

Return Value

Character. SUBSTR( ) returns a character string.

Note:
SUBSTR( ) will not return a value for a memo field when issued in the Debug window. To return a value in the Debug window, place the memo field name within ALLTRIM( ), and place ALLTRIM( ) within SUBSTR( ).

Remarks

When using SUBSTR( ) with memo fields in a SQL SELECT command, include the PADR( ) function in SUBSTR( ) so that empty or variable length memo fields produce consistent results when converted to character strings.

Example

The following example stores string 'abcdefghijklm' to the variable myString using the STORE command. CLEAR clears the main Visual FoxPro window. Beginning with the first character as specified by nStartPosition = 1, SUBSTR( ) displays the string 'abcde' with five characters as specified by nCharactersReturned = 5. SUBSTR( ) then displays the string 'fghijklm' beginning with the sixth character in the string as specified by nStartPosition = 6 until the end of the character expression is reached as specified by the omission of a value for nCharactersReturned.
Copy Code
STORE 'abcdefghijklm' TO myString
CLEAR
? SUBSTR(myString, 1, 5)
? SUBSTR(myString, 6)

See Also

Other Resources

AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
PADR( ) Function
RAT( ) Function
RATLINE( ) Function
RIGHT( ) Function
LEFTC( ) Function
RIGHTC( ) Function
SUBSTRC( ) Function
STREXTRACT( ) Function
STRTRAN( ) Function
STUFF( ) Function
Functions
Language Reference


SUBSTRC( ) Function

Visual FoxPro 9.0 Language Reference
SUBSTRC( ) Function
See Also

Returns a character string from the given character expression or memo field.

SUBSTRC(cExpression, nStartPosition [, nCharactersReturned])

Parameters

cExpression

Specifies the character expression or memo field from which the character string is returned.
nStartPosition

Specifies the position in the character expression or memo field cExpression from where the character string is returned. The first character of cExpression is position 1. If TALK is set to ON and nStartPosition is greater than the number of characters in cExpression, Visual FoxPro generates an error message. If TALK is set to OFF, the empty string is returned.
nCharactersReturned

Specifies the number of characters to return from cExpression. If you omit nCharactersReturned, characters are returned until the end of the character expression is reached.

Return Value

Character

Remarks

SUBSTRC( ) is designed for expressions containing double-byte characters. If the expression contains only single-byte characters, SUBSTRC( ) is equivalent to SUBSTR( ).

SUBSTRC( ) returns a character string from the given character expression or memo field. The character expression or memo field can contain any combination of single-byte and double-byte characters.

SUBSTRC( ) will not return a value for a memo field when issued in the Debug window. To return a value in the Debug window, place the memo field name within ALLTRIM( ), and place ALLTRIM( ) within SUBSTRC( ).

This function is useful for manipulating double-byte character sets for languages such as Hiragana and Katakana.

See Also

Other Resources

AT( ) Function
AT_C( ) Function
ATC( ) Function
ATCC( ) Function
ATCLINE( ) Function
ATLINE( ) Function
LEFT( ) Function
RAT( ) Function
RATLINE( ) Function
RIGHT( ) Function
LEFTC( ) Function
RIGHTC( ) Function
SUBSTR( ) Function
STRTRAN( ) Function
STUFFC( ) Function
Functions
Language Reference


SYS( ) Functions Overview

Visual FoxPro 9.0 Language Reference
SYS( ) Functions Overview
See Also

Returns Microsoft Visual FoxPro system information.

SYS( )

Return Value

Character

Remarks

Visual FoxPro SYS( ) functions return character values that contain useful system information.

The following table shows what each SYS( ) function returns:

Function | Information returned
SYS(0) | Network machine information.
SYS(1) | Julian system date.
SYS(2) | Seconds since midnight.
SYS(3) | Legal file name.
SYS(5) | Default drive or volume.
SYS(6) | Current printer device.
SYS(7) | Current format file.
SYS(9) | Visual FoxPro serial number.
SYS(10) | String from Julian day number.
SYS(11) | Julian day number.
SYS(12) | Available memory in bytes.
SYS(13) | Printer status.
SYS(14) | Index expression.
SYS(15) | Character translation.
SYS(16) | Executing program file name.
SYS(17) | Processor in use.
SYS(18) | Current control.
SYS(20) | Transform German text.
SYS(21) | Controlling index number.
SYS(22) | Controlling tag or index name.
SYS(23) | FoxPro EMS memory usage.
SYS(24) | EMS memory limit.
SYS(100) | Console setting. Included for backward compatibility. Use SET("CONSOLE") instead.
SYS(101) | Device setting. Included for backward compatibility. Use SET("DEVICE") instead.
SYS(102) | Printer setting. Included for backward compatibility. Use SET("PRINTER") instead.
SYS(103) | Talk setting. Included for backward compatibility. Use SET("TALK") instead.
SYS(602) | Bitmap Configuration.
SYS(987) | Map Remote Data to ANSI.
SYS(1001) | Visual FoxPro memory.
SYS(1011) | Number of Memory Handles.
SYS(1016) | User object memory use.
SYS(1023) | Enable Help diagnostic mode.
SYS(1024) | Disable Help diagnostic mode.
SYS(1037) | Page Setup Dialog Box.
SYS(1104) | Purge Cached Memory.
SYS(1269) | Property Information.
SYS(1270) | Object Location.
SYS(1271) | Object's .SCX File.
SYS(1272) | Object Hierarchy.
SYS(1500) | Activate a menu item.
SYS(2000) | File name wildcard match.
SYS(2001) | SET command status.
SYS(2002) | Turn insertion point on or off.
SYS(2003) | Current directory.
SYS(2004) | Visual FoxPro start directory.
SYS(2005) | Current resource file.
SYS(2006) | Current graphics card.
SYS(2007) | Checksum value.
SYS(2010) | CONFIG.SYS file settings.
SYS(2011) | Current lock status.
SYS(2012) | Memo field block size.
SYS(2013) | System menu name string.
SYS(2014) | Minimum path.
SYS(2015) | Unique procedure name.
SYS(2016) | SHOW GETS WINDOW name.
SYS(2017) | Checksum value based on the current record in the current work area.
SYS(2018) | Error message parameter.
SYS(2019) | Configuration file name and location.
SYS(2020) | Default disk free space.
SYS(2021) | Filtered index expression.
SYS(2022) | Disk cluster (block) size.
SYS(2023) | Temporary Path.
SYS(2024) | Detect report cancellation
SYS(2029) | Table type.
SYS(2030) | Debug.
SYS(2040) | Detect Report Status.
SYS(2060) | Mouse wheel event handling setting.
SYS(2300) | Add or Remove Code Page.
SYS(2325) | Returns the hWnd of a client window from the parent window's WHANDLE.
SYS(2326) | Returns a Visual FoxPro WHANDLE from a window’s hWnd.
SYS(2327) | Returns a window's hWnd from a Visual FoxPro window’s WHANDLE.
SYS(2333) | ActiveX Dual Interface Support.
SYS(2334) | Automation Server Invocation Mode.
SYS(2335) | Unattended Server Mode.
SYS(2336) | Critical Section Support.
SYS(2339) | Call CoFreeUnusedLibraries when COM object is released.
SYS(2340) | NT Service Support.
SYS(2410) | Error handler type for an error.
SYS(2450) | Application Search Path Order.
SYS(2600) | Return Pointer As String.
SYS(2700) | Enables Windows XP Themes.
SYS(2800) | Accessibility Support.
SYS(2801) | Event Tracking Support.
SYS(2910) | Sets or returns the number of items to display in drop down list boxes.
SYS(3004) | Return Locale ID.
SYS(3005) | Set Locale ID.
SYS(3006) | Set Language and Locale IDs.
SYS(3007) | Specifies a font language script for ToolTips.
SYS(3008) | Hyperlink Tooltips.
SYS(3009) | Bidirectional text justification for ToolTips.
SYS(3050) | Set Buffer Memory Size.
SYS(3051) | Set Lock Retry Interval.
SYS(3052) | Override SET REPROCESS Locking.
SYS(3053) | ODBC Environment Handle.
SYS(3054) | Rushmore Query Optimization Level.
SYS(3055) | FOR and WHERE Clause Complexity.
SYS(3056) | Read Registry Settings.
SYS(3065) | Internal Program Cache.
SYS(3092) | Output Rushmore Query Optimization Level
SYS(3095) | IDispatch Pointer.
SYS(3096) | IDispatch Object Reference.
SYS(3097) | Add Reference to Object.
SYS(3098) | Release Object Reference.
SYS(3099) | SQL Data Engine Compatibility Mode.
SYS(3101) | COM Code Page Translation

See Also

Other Resources

Command Window
SET Command
SET SYSFORMATS Command
SET SYSMENU Command
Functions


SYS(0) - Network Machine Information

Visual FoxPro 9.0 Language Reference
SYS(0) - Network Machine Information
See Also

SYS(0) returns network machine information when using Visual FoxPro in a network environment. The same functionality is available by using ID( ).

SYS(0)

Return Value

Character

Remarks

Machine information must first be assigned by the network software and the network shell must be loaded.

If machine information has not been assigned or the network shell hasn't been loaded, SYS(0) returns a character string consisting of 15 spaces, a number sign (#) followed by another space, and then 0. Consult your network documentation for further information on defining machine information.

SYS(0) returns 1 when using Visual FoxPro in a stand-alone environment.

When the machine is connected to a network, SYS(0) returns the machine name, a space, a number sign (#) followed by another space, and then the id of the current user (or the security context in which Visual FoxPro is running). For example:

Copy Code
? SYS(0)

returns the following format:

Copy Code
MACHINEID # userid

See Also

Other Resources

SYS( ) Functions Overview
ID( ) - Network Machine Information
Preparation for Distributing Applications


SYS(1) - Julian System Date

Visual FoxPro 9.0 Language Reference
SYS(1) - Julian System Date
See Also Example

Returns the current system date as a Julian day number character string.

SYS(1)

Return Value

Character

Remarks

The value returned by SYS(1) is valid in USA versions of Visual FoxPro for any system date after September 14, 1752, and before December 31, 9999.

Example

Copy Code
? SYS(1)
? SYS(10,VAL(SYS(1)))

See Also

Other Resources

CDOW( ) Function
CTOD( ) Function
DATE( ) Function
DATETIME( ) Function
DAY( ) Function
DOW( ) Function
DTOC( ) Function
SYS( ) Functions Overview
SYS(10) - String from Julian Day Number
SYS(11) - Julian Day Number


SYS(2) - Seconds Since Midnight

Visual FoxPro 9.0 Language Reference
SYS(2) - Seconds Since Midnight
See Also Example

Returns the number of seconds elapsed since midnight.

SYS(2)

Return Value

Character

Example

Copy Code
? TIME( )
? SYS(2)

See Also

Other Resources

DATETIME( ) Function
SECONDS( ) Function
SYS( ) Functions Overview
TIME( ) Function


SYS(3) - Legal File Name

Visual FoxPro 9.0 Language Reference
SYS(3) - Legal File Name
See Also

Returns a legal file name that can be used to create temporary files.

SYS(3)

Return Value

Character

Remarks

SYS(3) returns file names that begin with numbers. If your code uses SYS(3) with commands such as CREATE TABLE, CREATE CURSOR, SELECT INTO CURSOR, the code may fail because FoxPro cursors or alias names cannot begin with numbers. You can use SYS(2015) instead.

SYS(3) may return a non-unique name when issued successively on a fast computer.

See Also

Other Resources

FILE( ) Function
SYS( ) Functions Overview
SYS(2015) - Unique Procedure Name


SYS(5) - Default Drive

Visual FoxPro 9.0 Language Reference
SYS(5) - Default Drive
See Also Example

Returns the current Visual FoxPro default drive.

SYS(5)

Return Value

Character

Remarks

This function returns the current Visual FoxPro default drive. Use SET DEFAULT or CD to specify a default drive.

Example

Copy Code
CD "C:\Program Files"
?SYS(5)

SET DEFAULT TO C:
?SYS(5)

See Also

Reference

CD | CHDIR Command

Other Resources

DRIVETYPE( ) Function
SET DEFAULT Command
SYS( ) Functions Overview


SYS(6) - Current Printer Device

Visual FoxPro 9.0 Language Reference
SYS(6) - Current Printer Device
See Also Example

Returns the current print device.

SYS(6)

Return Value

Character

Remarks

This function returns the current SET PRINTER TO setting.

Example

Copy Code
? SYS(6)
SET PRINTER TO output.txt
? SYS(6)

See Also

Other Resources

SET PRINTER Command
SYS( ) Functions Overview
GETPRINTER( ) Function


SYS(7) - Current Format File

Visual FoxPro 9.0 Language Reference
SYS(7) - Current Format File
See Also

Returns the name of the current format file.

SYS(7 [, nWorkArea])

Parameters

nWorkArea

Specifies the work area number for which SYS(7) returns the format file name. The format file name for the current work area is returned if you omit nWorkArea.

Return Value

Character

Remarks

A format file is opened with SET FORMAT. The empty string is returned if a format file isn't open for the work area you specify.

See Also

Other Resources

SET FORMAT Command
SYS( ) Functions Overview
SET SYSFORMATS Command


SYS(9) - Visual FoxPro Serial Number

Visual FoxPro 9.0 Language Reference
SYS(9) - Visual FoxPro Serial Number
See Also

Returns your Visual FoxPro serial number.

SYS(9)

Return Value

Character

See Also

Other Resources

SYS( ) Functions Overview
VERSION( ) Function
Customizing the Visual FoxPro Environment


SYS(10) - String from Julian Day Number

Visual FoxPro 9.0 Language Reference
SYS(10) - String from Julian Day Number
See Also Example

Converts a Julian day number to a character string.

SYS(10, nJulianDayNumber)

Return Value

Character

Remarks

SYS(10) returns a Character-type date from a Julian day number nJulianDayNumber.

Example

Copy Code
? SYS(1)
? SYS(10,VAL(SYS(1)))

See Also

Other Resources

CDOW( ) Function
CTOD( ) Function
DATE( ) Function
DATETIME( ) Function
DAY( ) Function
DOW( ) Function
DTOC( ) Function
SYS( ) Functions Overview
SYS(1) - Julian System Date
SYS(11) - Julian Day Number


SYS(11) - Julian Day Number

Visual FoxPro 9.0 Language Reference
SYS(11) - Julian Day Number
See Also Example

Converts a date expression or character string in date format to a Julian day number.

SYS(11, dExpression | tExpression | cExpression)

Return Value

Character

Remarks

SYS(11) returns a Julian day number from a date expression dExpression, a datetime expression tExpression, or a character expression cExpression in a date format. The day number is returned as a character string.

Example

Copy Code
? SYS(11, {^1998-06-06})
? SYS(11,'06/06/1998')

See Also

Other Resources

CDOW( ) Function
CTOD( ) Function
DATE( ) Function
DATETIME( ) Function
DAY( ) Function
DOW( ) Function
DTOC( ) Function
SYS( ) Functions Overview
SYS(10) - String from Julian Day Number


SYS(12) - Available Memory in Bytes

Visual FoxPro 9.0 Language Reference
SYS(12) - Available Memory in Bytes
See Also

Returns the amount of memory below 640K that is available to execute an external program.

SYS(12)

Return Value

Character

Remarks

In Visual FoxPro, SYS(12) always returns 655,360.

SYS(12) is similar to MEMORY( ), with two exceptions:

  • SYS(12) returns the amount of available memory in bytes. MEMORY( ) returns available memory in kilobytes.

  • SYS(12) returns a character string. MEMORY( ) returns a numeric value.

See Also

Other Resources

MEMORY( ) Function
RUN | ! Command
SYS( ) Functions Overview
SYS(23) - FoxPro EMS Memory Usage
SYS(24) - EMS Memory Limit
SYS(1001) - Visual FoxPro Memory
SYS(1016) - User Object Memory Use


SYS(13) - Printer Status

Visual FoxPro 9.0 Language Reference
SYS(13) - Printer Status
See Also Example

Returns the status of the printer. Included for backward compatibility.

SYS(13)

Return Value

Character value. For versions of Visual FoxPro running on Windows, SYS(13) always returns READY.

In prior versions, if the printer is not ready, SYS(13) returns OFFLINE. If the printer is ready, SYS(13) returns READY. SYS(13) can also return the following values under the specified conditions:

  • If the printer is connected to a COM port and if the printer returns Clear To Send Data or Data Set Ready, SYS(13) returns READY.

  • If the printer is connected to a parallel port and if the printer returns Out of Paper, I/O Error, Time Out, Printer Busy, or Printer Not Selected, SYS(13) returns OFFLINE.

Example

Copy Code
IF SYS(13) = 'OFFLINE'
   WAIT WINDOW 'Printer is offline'
ENDIF

See Also

Other Resources

SYS( ) Functions Overview
PRINTSTATUS( ) Function
SET PRINTER Command


SYS(14) - Index Expression

Visual FoxPro 9.0 Language Reference
SYS(14) - Index Expression
See Also

Returns index expression of an open single-entry .idx index file or index expressions for tags in compound .cdx index files.

SYS(14, nIndexNumber [, nWorkArea | cTableAlias])

Parameters

nIndexNumber

Specifies which index expression to return from the open index files or tags. SYS(14) returns index expressions from open index files and tags in the following order as nIndexNumber increases from 1 to the total number of open single-entry files and structural compound and independent compound index tags:
  1. Index expressions from single-entry index files (if any are open) are returned first. The order the single-entry index files are included in USE or SET INDEX determines the order the index expressions are returned.

  2. Index expressions for each tag in the structural compound index (if one is present) are returned next. The index expressions are returned from the tags in the order that the tags were created in the structural index.

  3. Index expressions for each tag in any open independent compound indexes are returned last. The index expressions are returned from the tags in the order that the tags were created in the independent compound indexes.

The empty string is returned if nIndexNumber is greater than the total number of open single-entry files and structural compound and independent compound index tags.
nWorkArea| cTableAlias

Specifies a work area number or work area alias. If you omit nWorkArea and cTableAlias, index expressions are returned from index files open in the current work area. If a table doesn't have the alias you specify, Visual FoxPro generates an error message.

Return Value

Character

Remarks

An index expression is specified when an index file or tag is created with INDEX. The index expression determines how a table is displayed and accessed when an index file or tag is used to order the table.

For more information on index expressions and creating index files and tags, see INDEX. SYS(14) is similar to the KEY( ) function.

USE and SET INDEX both support an index file name list that makes it possible for you to open index files for a table. Any combination of single-entry index files, structural compound or independent compound index file names can be included in the index file list.

See Also

Other Resources

CDX( ) Function
KEY( ) Function
MDX( ) Function
NDX( ) Function
REINDEX Command
SET INDEX Command
SET ORDER Command
SYS( ) Functions Overview
TAG( ) Function


SYS(15) - Character Translation

Visual FoxPro 9.0 Language Reference
SYS(15) - Character Translation
See Also

Included for backward compatibility. Use SET COLLATE instead.

Copy Code
SYS(15, cTranslationExpression, cTranslated)

Parameters

cTranslationExpression

Specifies the character expression that SYS(15) uses for the translation of cTranslated.
cTranslated

Specifies the character expression that is translated. SYS(15) takes the first character in cTranslated and determines the character's ASCII value. The character in the same position in cTranslationExpression as the ASCII value is returned. This process is repeated for each additional character in cTranslated. If a character in cTranslated does not have a corresponding character in cTranslationExpression, then the character is not translated.

Return Values

Character

Remarks

This function is intended primarily for the convenience of European users who must use accented characters. Because there are different versions of most vowels, indexing on fields containing accented characters does not preserve the expected alphabetical order.

Included with Visual FoxPro is a memory variable file called EUROPEAN.MEM that contains sample translation characters. In FoxPro for MS-DOS and Visual FoxPro, EUROPEAN.MEM is located in the HOME( ) directory. In FoxPro for Macintosh, EUROPEAN.MEM is located in the Goodies:Misc folder.

Stored in EUROPEAN.MEM is a character memory variable called EUROPEAN, for use with SYS(15) in FoxPro for MS-DOS. Another character memory variable, EUROANSI, is provided for use with SYS(15) in Visual FoxPro and FoxPro for Macintosh. These memory variables can be used with SYS(15) to translate accented characters to the corresponding characters without the accents.

As an example, the following command can be used in FoxPro for MS-DOS to index a table on a field containing accented characters while preserving normal alphabetical order:

Copy Code
INDEX ON SYS(15, european, field) TO european

See Also

Other Resources

SYS( ) Functions Overview
SET COLLATE


SYS(16) - Executing Program File Name

Visual FoxPro 9.0 Language Reference
SYS(16) - Executing Program File Name
See Also Example

Returns the file name of the program being executed. You can use SYS(16) to recover from errors.

SYS(16 [, nProgramLevel])

Parameters

nProgramLevel

Indicates from how many levels back the program name is fetched. This value can range from 1 to the depth at which programs are nested. For more information about program nesting levels, see maximum number of DO calls in Visual FoxPro System Capacities. If nProgramLevel is 0 or 1, SYS(16) returns the name of the main program (the program first executed). The name of the currently executing program is returned if nProgramLevel is omitted. The empty string is returned if nProgramLevel is greater than the program nesting depth.

Return Value

Character

Remarks

SYS(16) is similar to PROGRAM( ) except that SYS(16) returns a path with the program name. When the executing program is part of an application (.app), SYS(16) returns only the name of the program, that is, without the path. SYS(16) returns the name of the executable file if called from an executable (.exe) file; whereas PROGRAM( ) returns just the program name. If a procedure or function is being executed, SYS(16) returns the name of the file containing the procedure or function after the procedure or function name.

Example

The program nesting is returned in the following short program example:
Copy Code
STORE 1 TO gnX
DO WHILE LEN(SYS(16,gnX)) != 0
   ? SYS(16,gnX)
   STORE gnX+1 TO gnX
ENDDO

See Also

Other Resources

LINENO( ) Function
ON ERROR Command
PROGRAM( ) Function
SYS( ) Functions Overview


SYS(17) - Processor in Use

Visual FoxPro 9.0 Language Reference
SYS(17) - Processor in Use
See Also Example

Returns the central processing unit (CPU) being used.

SYS(17)

Return Value

Character

Remarks

This function returns the type of central processing unit you are using.

Example

Copy Code
? 'Processor in use: ', SYS(17)

See Also

Other Resources

SYS( ) Functions Overview
SET DEVICE Command
SYS(100) - Console Setting


SYS(18) - Current Control

Visual FoxPro 9.0 Language Reference
SYS(18) - Current Control
See Also

Included for backward compatibility. Use the ActiveControl property instead.

See Also

Other Resources

Language Reference


SYS(20) - Transform German Text

Visual FoxPro 9.0 Language Reference
SYS(20) - Transform German Text
See Also

Included for backward compatibility. Use SET COLLATE instead.

See Also

Other Resources

Language Reference


SYS(21) - Controlling Index Number

Visual FoxPro 9.0 Language Reference
SYS(21) - Controlling Index Number
See Also

Returns, as a character string, the index position number of the master controlling .cdx compound index tag or .idx index file for the currently selected work area.

SYS(21)

Return Value

Character

Remarks

The index position number is determined by the order in which the .idx index files and .cdx compound index tags are specified in USE and SET INDEX.

You can use SET INDEX, SET ORDER, and USE to specify which .idx index file or .cdx compound index tag is the master controlling index file or tag. For more information on specifying a master controlling index or tag, see SET INDEX, SET ORDER, and USE.

"0" is returned if there isn't a master controlling .cdx compound index tag or .idx index file (for example, SET ORDER TO is issued to display and access the table in natural record order).

See Also

Other Resources

CDX( ) Function
KEY( ) Function
INDEX Command
MDX( ) Function
NDX( ) Function
REINDEX Command
SYS( ) Functions Overview
SYS(22) - Controlling Tag or Index Name
TAG( ) Function
USE Command


SYS(22) - Controlling Tag or Index Name

Visual FoxPro 9.0 Language Reference
SYS(22) - Controlling Tag or Index Name
See Also

Returns the name of the master controlling .cdx compound index tag or .idx index file for a table.

SYS(22 [, nWorkArea])

Return Value

Character

Remarks

You can use SET INDEX, SET ORDER, and USE to specify which .idx index file or .cdx compound index tag is the master controlling index file or tag. For more information on specifying a master controlling index or tag, see SET INDEX, SET ORDER, and USE.

The empty string is returned if there isn't a master controlling .cdx compound index tag or .idx index file (for example, SET ORDER TO is issued to display and access the table in natural record order).

nWorkArea

Specifies the work area number of the table for which SYS(22) returns the name of the master controlling .cdx compound index tag or .idx index file.

See Also

Other Resources

CDX( ) Function
KEY( ) Function
INDEX Command
MDX( ) Function
NDX( ) Function
REINDEX Command
SYS( ) Functions Overview
SYS(21) - Controlling Index Number
TAG( ) Function


SYS(23) - FoxPro EMS Memory Usage

Visual FoxPro 9.0 Language Reference
SYS(23) - FoxPro EMS Memory Usage
See Also

Included for backward compatibility.

See Also

Other Resources

Language Reference


SYS(24) - EMS Memory Limit

Visual FoxPro 9.0 Language Reference
SYS(24) - EMS Memory Limit
See Also

Included for backward compatibility.

See Also

Other Resources

Language Reference


SYS(602) - Bitmap Configuration

Visual FoxPro 9.0 Language Reference
SYS(602) - Bitmap Configuration
See Also

Returns the current setting of the bitmap in the current configuration file and turns off-screen bitmaps off or on at run time.

SYS(602 [, 0 | 1 ])

Parameters

0

Turns off off-screen bitmaps at run time.
1

Turns on off-screen bitmaps at run time.

Return Value

Character data type. The following table lists the possible settings that SYS(602) can return.

Return value | Setting
0 | Off-screen bitmaps are turned off.
1 | Off-screen bitmaps are turned on. (Default)

Remarks

You can use off-screen bitmaps to store an image of the current desktop and forms so that you can render them if another element, such as a window, is drawn over them. However, off-screen bitmaps use a lot of memory, so you can improve performance on Terminal Server applications by turning these bitmaps off using SYS(602).

However, be aware that toggling off-screen bitmaps can affect your application. For example, form controls can appear normal, however, writing directly to a form using a method such as Line requires off-screen bitmaps to be turned on.

If you want to determine whether an application is running on a Terminal Server, use OS(10).

See Also

Other Resources

SYS( ) Functions Overview
OS( ) Function
Special Terms for Configuration Files


SYS(987) - Map Remote Data to ANSI

Visual FoxPro 9.0
SYS(987) - Map Remote Data to ANSI
See Also

Maps remote Unicode data retrieved through SQL pass-through or remote views to ANSI.

SYS(987 [, lExpr])

Parameters

lExpr

True (.T.) - Unicode data is always fetched as ANSI. The ODBC driver performs the conversion from Unicode to ANSI. False (.F.) (Default) - Unicode data is fetched as Unicode.

Return Value

Logical data type. SYS(987) returns the previous setting.

If you call SYS(987) without the lExpr parameter, it returns current setting.

Remarks

SYS(987) can be used to return remote Varchar data as ANSI for use with Memo fields.

The SYS(987) setting is a global setting across all data sessions. After a remote cursor is created, changing the SYS(987) setting does not affect subsequent data fetches for the cursor even if REQUERY( ) is executed.

See Also

Reference

REQUERY( ) Function


SYS(1001) - Visual FoxPro Memory

Visual FoxPro 9.0 Language Reference
SYS(1001) - Visual FoxPro Memory
See Also

Returns the total amount of memory available to the Visual FoxPro memory manager.

SYS(1001)

Return Value

Character

Remarks

In Visual FoxPro, SYS(1001) returns the virtual memory pool size, which is approximately four times the amount of physical memory.

See Also

Other Resources

SYS( ) Functions Overview
SYS(12) - Available Memory in Bytes
SYS(23) - FoxPro EMS Memory Usage
SYS(24) - EMS Memory Limit
SYS(1016) - User Object Memory Use


SYS(1011) - Number of Memory Handles

Visual FoxPro 9.0 Language Reference
SYS(1011) - Number of Memory Handles
See Also

Returns the number of memory handles in use.

SYS(1011)

Return Value

Character

Remarks

You can use SYS(1011) to check memory usage as you repeatedly run a test. Increasing values only between the first two runs can be evidence of memory caching. Increasing values beyond this can be evidence of a problem.

See Also

Other Resources

SYS( ) Functions Overview
SYS(12) - Available Memory in Bytes
SYS(1016) - User Object Memory Use


SYS(1016) - User Object Memory Use

Visual FoxPro 9.0 Language Reference
SYS(1016) - User Object Memory Use
See Also

Returns amount of memory being used by objects you define.

SYS(1016)

Return Value

Character

Remarks

User-defined objects include: user-defined windows, menu bars, menus, variables, arrays, open tables, files opened with low-level file functions, and so on.

See Also

Other Resources

SYS( ) Functions Overview
SYS(12) - Available Memory in Bytes
SYS(23) - FoxPro EMS Memory Usage
SYS(24) - EMS Memory Limit
SYS(1001) - Visual FoxPro Memory


SYS(1023) - Enable Help Diagnostic Mode

Visual FoxPro 9.0 Language Reference
SYS(1023) - Enable Help Diagnostic Mode
See Also

Enables the Help diagnostic mode, making it possible for you to trap the HelpContextID passed to the Visual FoxPro Help system.

SYS(1023)

Return Value

Character

Remarks

SYS(1023) is useful for debugging a custom Help system for your application. SYS(1023) returns the empty string.

When the Help diagnostic mode is enabled with SYS(1023), a dialog box is displayed whenever you press F1 or issue HELP. The dialog box displays the HelpContextID to be passed to the Visual FoxPro Help system, and you are given the option of passing the HelpContextID to the Visual FoxPro Help system.

If you choose Yes, the HelpContextID is passed to the Visual FoxPro Help system and the corresponding Help topic (if available) is displayed. If you choose No, the HelpContextID is not passed to the Visual FoxPro Help system and the corresponding Help topic is not displayed.

Use SYS(1024) to disable the Help diagnostic mode and restore the default Visual FoxPro Help system processing.

See Also

Other Resources

HELP Command
HelpContextID Property
SET HELP Command
SYS(1024) - Disable Help Diagnostic Mode
SYS( ) Functions Overview


SYS(1024) - Disable Help Diagnostic Mode

Visual FoxPro 9.0 Language Reference
SYS(1024) - Disable Help Diagnostic Mode
See Also

Disables the Help diagnostic mode enabled by issuing SYS(1023).

SYS(1024)

Return Value

Character

Remarks

Use SYS(1024) to disable the Help diagnostic mode enabled with SYS(1023) and restore the default Visual FoxPro Help system processing. SYS(1023) is used to debug a custom Help system for your application.

SYS(1024) returns the empty string.

See Also

Other Resources

HELP Command
HelpContextID Property
SET HELP Command
SYS(1023) - Enable Help Diagnostic Mode
SYS( ) Functions Overview


SYS(1037) - Page Setup Dialog Box

Visual FoxPro 9.0 Language Reference
SYS(1037) - Page Setup Dialog Box
See Also

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.

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

Other Resources

GETPRINTER() Function
PRINTSTATUS() Function
SET DEVICE Command
SET PRINTER Command
SYS() Functions Overview


SYS(1104) - Purge Memory Cache

Visual FoxPro 9.0 Language Reference
SYS(1104) - Purge Memory Cache
See Also

Purges memory cached by programs and data, and clears and refreshes buffers for open tables.

SYS(1104 [, cAlias | nWorkArea])

Parameters

cAlias

Specifies the alias of a specific table or cursor for which cached memory is purged.
nWorkArea

Specifies the work area of a specific table or cursor for which cached memory is purged.

Return Value

Character. SYS(1104) returns the number of bytes that could not be purged. SYS(1104) returns "0" if all memory is purged.

Remarks

You can improve performance by calling SYS(1104) after executing commands that make extensive use of memory buffers. This function also clears internal buffers for open tables, forcing the tables to be refreshed, which is useful with large tables and in multiuser environments.

Note:
The use of SYS(1104) will slow performance in applications that have a large number of buffered tables open.

Include the optional cAlias or nWorkArea parameter to purge the memory cache for a specific table or cursor. This can be useful in multiuser scenarios that use the INDEXSEEK( ) Function to search indexed tables.

See Also

Other Resources

SYS( ) Functions Overview
CLEAR Command
RELEASE Command
CLOSE Command
FLUSH Command
SET REFRESH


SYS(1269) - Property Information

Visual FoxPro 9.0 Language Reference
SYS(1269) - Property Information
See Also

Returns a value that indicates whether a property setting has changed from its default setting or whether the property is read-only.

SYS(1269, oObjectName, cProperty, nPropertyAttribute)

Parameters

oObjectName

Specifies the object for which the property setting information is returned.
cProperty

Specifies the property for which SYS(1269) returns information.
nPropertyAttribute

Specifies a numeric value that determines the behavior of the return values of SYS(1269). The following table lists the values for nPropertyAttribute.

nPropertyAttribute Description

0

Return True (.T.) if the property setting has changed from its default setting.

Return False (.F.) if the property setting has not changed from its default setting.

1

Return True (.T.) if the property setting is read-only.

Return False (.F.) if the property is read/write.

Return Value

Character. SYS(1269) returns True (.T.) or False (.F.), whose meaning depends on the value of nPropertyAttribfsute.

Remarks

SYS(1269) is useful for determining whether a property setting has changed or whether it is read/write before you attempt to set the property programmatically.

See Also

Other Resources

GETPEM( ) Function
PEMSTATUS( ) Function
SYS(1270) - Object Location
SYS(1272) - Object Hierarchy
SYS( ) Functions Overview


SYS(1270) - Object Location

Visual FoxPro 9.0 Language Reference
SYS(1270) - Object Location
See Also

Returns a reference for an object at the specified point.

SYS(1270 [, nXCoord, nYCoord])

Parameters

nXCoord

Specifies the horizontal coordinate in pixels relative to the Windows desktop.
nYCoord

Specifies the vertical coordinate in pixels relative to the Windows desktop.

Return Value

Character or object reference. SYS(1270) returns a reference to the object at the location specified by nXCoord and nYCoord, if included. If nXCoord and nYCoord are omitted, SYS(1270) returns a reference to the object in the location of the current mouse position. If no object is located at either position, SYS(1270) returns False (.F.).

Note:
For dockable forms, SYS(1270) will not return the proper object if the form is docked with other forms and the mouse (or nXCoord, nYCoord) is over the titlebar of the docking container.

See Also

Other Resources

AMOUSEOBJ( ) Function
CREATE FORM Command
GETPEM( ) Function
PEMSTATUS( ) Function
SYS(1269) - Property Information
SYS(1271) - Object's .SCX File
SYS(1272) - Object Hierarchy
ASELOBJ( ) Function
SYS( ) Functions Overview


SYS(1271) - Object's .SCX File

Visual FoxPro 9.0 Language Reference
SYS(1271) - Object's .SCX File
See Also

Returns the name of the .SCX file in which the specified instantiated object is stored.

SYS(1271, oObjectName)

Parameters

oObjectName

Specifies the name of the object for which the .scx file is returned.

Return Value

Character, Logical

Remarks

SYS(1271) returns the name of the .scx file in which the specified instantiated object is stored.

SYS(1271) returns a logical false (.F.) if the object cannot be located in an .scx file (for example, if the object was created from the Command window).

See Also

Other Resources

CREATE FORM Command
GETPEM( ) Function
PEMSTATUS( ) Function
SYS(1269) - Property Information
SYS(1270) - Object Location
SYS(1272) - Object Hierarchy
SYS( ) Functions Overview


SYS(1272) - Object Hierarchy

Visual FoxPro 9.0 Language Reference
SYS(1272) - Object Hierarchy
See Also

Returns the object hierarchy for a specified object. Not available at design time.

SYS(1272, oObjectName)

Parameters

oObjectName

Specifies the name of the object for which the hierarchy is returned.

Return Value

Character

See Also

Other Resources

CREATE FORM Command
GETPEM( ) Function
PEMSTATUS( ) Function
SYS(1269) - Property Information
SYS(1270) - Object Location
SYS(1271) - Object's .SCX File
SYS( ) Functions Overview


SYS(1500) - Activate a System Menu Item

Visual FoxPro 9.0 Language Reference
SYS(1500) - Activate a System Menu Item
See Also Example

Activates a Visual FoxPro system menu item.

SYS(1500, cSystemItemName, cMenuName)

Parameters

cSystemItemName

Specifies the name of the Visual FoxPro system menu item to activate.
cMenuName

Specifies the name of the Visual FoxPro system menu or submenu containing the menu item.

Return Value

Character

Remarks

See System Menu Names for a list of Visual FoxPro menu and menu item names. You can also use SYS(2013) - System Menu Name String to display a list of Visual FoxPro menu and menu item names.

User-defined menu items and disabled system menu items cannot be activated with SYS(1500).

SYS(1500) returns the empty string.

Example

The following example uses SYS(1500) to paste a command into a program file.
Copy Code
_CLIPTEXT = "MESSAGEBOX('TEST')"  && Command to paste
MODIFY COMMAND myprog NOWAIT  && Open a program file
SYS(1500, '_MED_PASTE', '_MEDIT')  && Paste menu item

See Also

Other Resources

MODIFY COMMAND Command
_CLIPTEXT System Variable
SYS( ) Functions Overview


SYS(2000) - File Name Wildcard Match

Visual FoxPro 9.0 Language Reference
SYS(2000) - File Name Wildcard Match
See Also Example

Returns the name of the first file in alphabetic order by file name and extension, that matches a file name skeleton.

SYS(2000, Skeleton [, 1])

Parameters

Skeleton

Specifies the file name skeleton. The file skeleton can contain the wildcards ? and *.
1

Returns the name of the next matching file.

Return Value

Character

Remarks

The empty string is returned if a matching file can't be found.

Example

Copy Code
? SYS(2000,'FOX.*')
? SYS(2000,'FOX.*',1)

See Also

Other Resources

LOCFILE( ) Function
SYS( ) Functions Overview


SYS(2001) - SET ... Command Status

Visual FoxPro 9.0 Language Reference
SYS(2001) - SET ... Command Status
See Also Example

Returns the status of the specified SET commands.

SYS(2001, cSETCommand [, 1 | 2])

Parameters

cSETCommand

Specifies the SET command whose status SYS(2001) returns.
1 | 2

Some SET commands have two or more settings; for example, SET PRINTER ON, SET PRINTER OFF, and SET PRINTER TO FileName. Use SYS(2001) without 1 or 2 to return the ON or OFF switch setting. Use SYS(2001) with 1 or 2 to return the additional settings. See SET( ) Function for a list of SET commands for which additional information is returned when 1 or 2 is included.

Return Value

Character

Remarks

SYS(2001) is identical to SET( ).

Example

Copy Code
? SYS(2001,'PRINTER')
? SYS(2001,'PRINTER',1)

See Also

Other Resources

SYS( ) Functions Overview
SET PRINTER Command
SET Command


SYS(2002) - Turn Insertion Point On or Off

Visual FoxPro 9.0 Language Reference
SYS(2002) - Turn Insertion Point On or Off
See Also

Turns the insertion point on or off.

SYS(2002 [, 1])

Return Value

None

Remarks

SYS(2002) turns the insertion point off. SYS(2002, 1) turns the insertion point on. For more information about turning the insertion point on and off, see SET CURSOR Command.

See Also

Other Resources

INKEY( ) Function
SYS( ) Functions Overview


SYS(2003) - Current Directory

Visual FoxPro 9.0 Language Reference
SYS(2003) - Current Directory
See Also

Returns the name of the current directory on the default drive.

SYS(2003)

Return Value

Character

Remarks

You can use SYS(5) to determine the current drive.

See Also

Other Resources

SYS( ) Functions Overview
Cannot rename the current directory (Error 1253)
SYS(5) - Default Drive


SYS(2004) - Visual FoxPro Start Directory

Visual FoxPro 9.0 Language Reference
SYS(2004) - Visual FoxPro Start Directory
See Also Example

Returns the name of the directory from which Visual FoxPro was started.

SYS(2004)

Return Value

Character. SYS(2004) returns the location of the VFPVersionNumberR.dll or VFPVersionNumberT.dll file in a run-time Visual FoxPro application. VersionNumber represents the version number of this release.

Example

Copy Code
? 'Visual FoxPro launch directory: ', SYS(2004)

See Also

Other Resources

HOME( ) Function
SET PATH Command
SYS( ) Functions Overview


SYS(2005) - Current Resource File

Visual FoxPro 9.0 Language Reference
SYS(2005) - Current Resource File
See Also Example

Returns the name of the current Visual FoxPro resource file.

SYS(2005)

Return Value

Character

Remarks

The Visual FoxPro resource file is a Visual FoxPro table that contains information on system and user-defined resources like keyboard macros, preferences, system window locations and sizes, diary entries, and so on.

The Visual FoxPro resource file defaults to FoxUser.dbf. Use SET RESOURCE to specify a different Visual FoxPro resource file.

Example

Copy Code
? 'Current resource file: ', SYS(2005)

See Also

Other Resources

SET RESOURCE Command
SYS( ) Functions Overview


SYS(2006) - Current Graphics Card

Visual FoxPro 9.0 Language Reference
SYS(2006) - Current Graphics Card
See Also Example

Returns the type of graphics card and monitor you are using.

SYS(2006)

Return Value

Character

Example

Copy Code
? 'Current graphics card/monitor: ', SYS(2006)

See Also

Other Resources

ISCOLOR( ) Function
SET DISPLAY Command
SYS( ) Functions Overview


SYS(2007) - Checksum Value

Visual FoxPro 9.0 Language Reference
SYS(2007) - Checksum Value
See Also

Returns the checksum value of a character expression. You can use a checksum to test the validity of data or to compare two character expressions. You can also generate checksum values greater than 16 bits for large strings.

SYS(2017) offers complementary functionality by generating checksum values based on the current record in the current work area. For more information, see SYS(2017) - Record Checksum Value.

SYS(2007, cExpression, [, nSeed, [, nFlags]])

Parameters

cExpression

Specifies a character expression (string) for which SYS(2007) returns a checksum value.
nSeed

Specifies a numeric seed value of 0 that is used to calculate the checksum and is included for backward compatibility. Passing a value of -1 for nSeed uses the default system value of 0. For CRC32 calculations, Visual FoxPro disregards nSeed.
nFlags

Set an additional bit value for generating the checksum. Versions of Visual FoxPro earlier than 8.0 used a CRC16 16-bit algorithm to calculate the checksum values of strings. Visual FoxPro now includes the CRC32 routine to calculate larger 32-bit values. You can control the setting of this algorithm by setting the first bit value of the nFlags parameter. The following table lists the bit value you can set to produce one of the values for nFlags.

Value Bit Description

1

001

Calculate checksum value using CRC32 checksum algorithm.
The following table lists the possible values for nFlags, produced by setting the bit flag.

nFlags Description

0

Calculate checksum based on cExpression parameter using CRC16 checksum algorithm. (Default)

1

Calculate checksum based on cExpression parameter using CRC32 checksum algorithm.
For example, if you want use checksum using the CRC32 checksum algorithm to calculate the checksum based on cExpression, you should specify an nFlags value of 1. To use the CRC16 checksum algorithm, set the nFlags value to 0.

Return Value

Character data type

See Also

Other Resources

SYS( ) Functions Overview
Creating Character Expressions


SYS(2010) - CONFIG.SYS File Settings

Visual FoxPro 9.0 Language Reference
SYS(2010) - CONFIG.SYS File Settings
See Also

Returns the files setting in CONFIG.SYS.

SYS(2010)

Return Value

Character

Remarks

In FoxPro for MS-DOS, SYS(2010) returns as a character string the files setting in your CONFIG.SYS configuration file.

In Visual FoxPro, SYS(2010) always returns 255.

Most Config.sys files contain a line specifying the maximum number of files that can be opened at the same time under MS-DOS. This line usually reads FILES=NNN, where NNN is a number. SYS(2010) returns this number.

A Config.sys configuration file doesn't have to have a files setting; furthermore, you need not have a Config.sys file. SYS(2010) returns the default MS-DOS files setting in either case.

The number returned by SYS(2010) isn't the number of files you can open in Visual FoxPro, FoxPro for Windows, and FoxPro for MS-DOS. MS-DOS opens files for its own use. Visual FoxPro and FoxPro for Windows also open files for their own internal use, and the number of these open files can vary throughout a FoxPro session. The files setting in your Config.sys file must be somewhat greater than the number of files you would like to open in Visual FoxPro.

For more information on the Config.sys configuration file, see your MS-DOS manual.

See Also

Reference

Using a Configuration File

Other Resources

SYS( ) Functions Overview
SYS(2019) - Configuration File Name and Location


SYS(2011) - Current Lock Status

Visual FoxPro 9.0 Language Reference
SYS(2011) - Current Lock Status
See Also

Returns the record or table lock status for the current work area.

SYS(2011)

Return Value

Character

Remarks

Unlike the FLOCK( ), LOCK( ), and RLOCK( ) functions, SYS(2011) doesn't attempt to lock the table or record.

The character string returned by SYS(2011) is identical to the message displayed in the status bar (Exclusive, Record Unlocked, Record Locked ...).

SYS(2011) returns Exclusive only at the workstation that opened the table exclusively, and Record Locked only at the workstation that applied the record lock.

See Also

Other Resources

FLOCK( ) Function
LOCK( ) Function
RLOCK( ) Function
SYS( ) Functions Overview
ISFLOCKED( ) Function
ISRLOCKED( ) Function


SYS(2012) - Memo Field Blocksize

Visual FoxPro 9.0 Language Reference
SYS(2012) - Memo Field Blocksize
See Also

Returns the memo field block size for a table.

SYS(2012 [, nWorkArea | cTableAlias])

Parameters

nWorkArea| cTableAlias

Specifies the work area number or table alias for the table for which the memo field block size is returned. nWorkArea specifies a work area number and cTableAlias specifies a table alias. If you do not specify a work area or alias, SYS(2012) returns the memo field block size for the table open in the currently selected work area. SYS(2012) returns 0 if a table isn't open in the specified work area or the table doesn't have a memo field.

Return Value

Character

Remarks

For more information on specifying the memo field block size for a table, see SET BLOCKSIZE Command.

See Also

Other Resources

Memo Field Type
Memo Field Input and Output Routines
SYS( ) Functions Overview


SYS(2013) - System Menu Name String

Visual FoxPro 9.0 Language Reference
SYS(2013) - System Menu Name String
See Also

Returns a space-delimited character string containing the internal names of the Visual FoxPro menu system.

SYS(2013)

Return Value

Character

Remarks

SYS(2013) facilitates utilization of the Visual FoxPro system menu bar and system menus. The character string returned contains the name of the system menu bar, its menu titles, and the name of each item on the menus.

SYS(2013) returns the names of the menu titles and menu items for every FoxPro platform. See System Menu Names for a listing of Visual FoxPro menu titles and menu items.

See Also

Other Resources

DEFINE BAR Command
DEFINE MENU Command
DEFINE POPUP Command
SYS( ) Functions Overview
SYS(1500) - Activate a System Menu Item


SYS(2014) - Minimum Path

Visual FoxPro 9.0 Language Reference
SYS(2014) - Minimum Path
See Also

Returns the minimum path relative to the current or specified directory for a specified file.

SYS(2014, cFileName [, Path])

Parameters

cFileName

Specifies the name of the file for which SYS(2014) returns the minimum path. If you omit Path, SYS(2014) returns the minimum path between the file and the current directory. You can change the current directory with SET DEFAULT.
Path

Specifies a directory for which SYS(2014) returns the minimum path between the specified directory and the file specified with cFileName.

Return Value

Character

Remarks

SYS(2014) can be used with FULLPATH( ) to make applications portable. That is, when given the location of the current program and the location of other files used by the program, FULLPATH( ) and SYS(2014) obtain the proper paths for these files. Once the files' paths are determined, the files can be accessed by the program.

See Also

Other Resources

FULLPATH( ) Function
SET DEFAULT Command
SET PATH Command
SYS( ) Functions Overview


SYS(2015) - Unique Procedure Name

Visual FoxPro 9.0 Language Reference
SYS(2015) - Unique Procedure Name
See Also

Returns a unique 10-character procedure name that begins with an underscore followed by a combination of letters and numbers.

SYS(2015)

Return Value

Character

Remarks

Use SYS(2015) to create unique names for items such as procedures, functions, files, tables or cursors. You can add a prefix or change the length of the name using the SUBSTR( ) function. For example, the code "tmp"+SUBSTR(SYS(2015),4,3) returns tmpCIOS.

The name that SYS(2015) returns is created from the system date and system time. Calling SYS(2015) more than once during the same millisecond interval returns a unique character string.

See Also

Other Resources

SYS( ) Functions Overview
SYS(3) - Legal File Name
SYS(1) - Julian System Date


SYS(2016) - SHOW GETS WINDOW Name

Visual FoxPro 9.0 Language Reference
SYS(2016) - SHOW GETS WINDOW Name
See Also

Included for backward compatibility. Use the Refresh method instead of SHOW GETS.

See Also

Other Resources

Language Reference


SYS(2017) - Record Checksum Value

Visual FoxPro 9.0 Language Reference
SYS(2017) - Record Checksum Value
See Also

Returns a checksum value based on the current record in the current work area. You can use a checksum to test the validity of data. You can also generate checksum values greater than 16 bits for large strings.

SYS(2017) offers complementary functionality to SYS(2007) - Checksum Value.

SYS(2017, cExpression [, nSeed [, nFlags]])

Parameters

cExpression

Specifies a comma-delimited list, with or without spaces, containing one or more fields to exclude from the checksum calculation. The maximum length of the field string is limited to 256 characters. If cExpression is empty, Visual FoxPro does not exclude fields except for Memo and General fields.
nSeed

Specifies a numeric seed value of 0 that is used to calculate the checksum and is included for backward compatibility. Passing a value of -1 for nSeed uses the default system value of 0. For CRC32 calculations, Visual FoxPro disregards nSeed.
nFlags

Specifies additive bit values for generating the checksum. Versions of Visual FoxPro earlier than 8.0 used a CRC16 16-bit algorithm to calculate the checksum values of strings. Visual FoxPro now includes the CRC32 routine to calculate larger 32-bit values. You can control the setting of this algorithm by setting the first bit value of the nFlags parameter. The following table lists the bit values you can add to produce a value for nFlags.

Value Bits Description

1

001

Calculate checksum value using CRC32 checksum algorithm.

2

010

Include Memo fields in the checksum calculation.
You can use the second nFlags bit to include Memo fields in the CRC calculation. Visual FoxPro includes all Memo fields except any specified by cExpression in the calculation. The following table lists the possible values for nFlags, produced by the sum of the bit flags.

nFlags Description

0

Calculate checksum based on cExpression parameter using CRC16 checksum algorithm. (Default)

1

Calculate checksum based on cExpression parameter using CRC32 checksum algorithm.

2

Calculate checksum based on current record contents including Memo fields using CRC16.

3

Calculate checksum based on current record contents including Memo fields using CRC32.

Return Value

Character data type. SYS(2017) returns a checksum value.

Remarks

When calculating the checksum value from the current record, Visual FoxPro disregards Memo and General fields unless nFlags is set to 2 or 3.

Visual FoxPro generates the checksum based on the current record in the current work area and passes the byte values of the string into the CRC32 routine.

Visual FoxPro returns a value of "0" if no cursor is open in the current work area or if the record pointer is not valid, for example, pointing to a phantom record.

When you create a string expression from a record, Visual FoxPro removes trailing blank spaces and returns the expression as a character string, similar to the ALLTRIM( ) function.

Usually, Visual FoxPro uses any excluded fields specified by cExpression to store the checksum value and does not include them in the calculation. Visual FoxPro does not perform any checks on the data type of these fields. If cExpression contains an invalid field, Visual FoxPro disregards that field.

Visual FoxPro calculates the checksum from all the fields included except for Memo, General, and those specified by cExpression. You can determine the fields used and their order using the FIELD( ) function. If you specified a setting for SET FIELDS, the checksum is calculated based on the current list specified by SET FIELDS which could include calculated fields.

Calculated fields are temporary fields that exist in the current cursor based on an expression but are not defined in the actual table structure. For example, the field LOCATION is a calculated field:

Copy Code
Use Customer
SET FIELDS TO LOCATION = ALLTRIM(city) + ',' + state

See Also

Other Resources

SYS( ) Functions Overview
SYS(2007) - Checksum Value
SET FIELDS Command
FIELD( ) Function
SET RESOURCE Command
Creating Character Expressions


SYS(2018) - Error Message Parameter

Visual FoxPro 9.0 Language Reference
SYS(2018) - Error Message Parameter
See Also Example

Returns the error message parameter for the most recent error message.

For certain error messages, SYS(2018) returns information about the cause of the most recent error, such as the names of variables and files, which are called error message parameters. These error messages generally have placeholder in the error message, for example, "Class file "name" is invalid." Therefore, if you reference a file name that does not exist, the name of the variable is included in the error message.

SYS(2018)

Return Value

Character. SYS(2018) returns the error message parameter.

Example

Suppose you try to run a program named REPORTS, but the program doesn't exist and the error message "File REPORTS does not exist." appears. SYS(2018) returns the word "REPORTS" The word "REPORTS" is the error message parameter.
Copy Code
? SYS(2018)

See Also

Other Resources

SYS( ) Functions Overview
ERROR( ) Function
MESSAGE( ) Function
ON ERROR Command


SYS(2019) - Configuration File Name and Location

Visual FoxPro 9.0 Language Reference
SYS(2019) - Configuration File Name and Location
See Also

Returns the name and location of the Visual FoxPro internal and external configuration files.

SYS(2019 [, 1 | 2])

Parameters

Parameter | Description
1 | (Default) Include this parameter to return the name and location of Config.fpw, the external Visual FoxPro configuration file. Issuing SYS(2019,1) is equivalent to issuing SYS(2019) without any parameters.
2 | Include this parameter to return the name and location of the internal configuration file.

Return Value

Character

Remarks

The Visual FoxPro external configuration file is named Config.fpw, and it is not installed by default. You can create your own Config.fpw configuration file with MODIFY FILE.

If an internal or external configuration file cannot be located, SYS(2019) returns an empty string.

The Visual FoxPro external configuration file is typically located in the directory where Visual FoxPro, or a Visual FoxPro application, is started, but can be located elsewhere. Visual FoxPro first looks for it in the startup directory. If the configuration file is not located in the startup directory, the MS-DOS path is searched. When you start Visual FoxPro or a Visual FoxPro application, you can also use the -C switch to designate an external configuration file. Include the location and name of the configuration file immediately after -C.

For Visual FoxPro applications, you can also create an internal configuration file, which is built into the application's executable file. The internal configuration file must be called Config.fpw. When an internal configuration file is used, it will be read by default and any external configuration file that may exist will be ignored. You can allow your Visual FoxPro application to read an external configuration file after reading the internal configuration file by using the ALLOWEXTERNAL directive in the internal configuration file. When you include the setting ALLOWEXTERNAL=ON in the internal configuration file, Visual FoxPro searches for an external configuration file using the search criteria listed above, and reads its settings. The -C startup switch is ignored when used with an application that includes an internal configuration file unless the ALLOWEXTERNAL=ON setting is included in the internal configuration file.

Note:
For .exe and .dll file servers, Visual FoxPro supports only configuration files that are bound inside the server. Therefore, Visual FoxPro disregards the ALLOWEXTERNAL setting.

For more information about command-line switches, see How to: Use Command-Line Options When Starting Visual FoxPro.

The settings in an external configuration file take precedence over those in the internal configuration file, if duplicate settings exist, because the external configuration file is read after the internal file. Visual FoxPro does not begin initialization until it reads both files.

If you want to specify the configuration file as read-only, place the file in your project and mark it as Included. If you want to specify that the file can be modified, place the file in your project and mark it as Excluded. You can then distribute the file separately with your application or executable file. By convention, configuration files use the .fpw extension.

For more information, see Special Terms for Configuration Files and Setting Configuration Options at Startup.

For more information about the Visual FoxPro configuration file, see Customizing the Visual FoxPro Environment.

See Also

Other Resources

MODIFY FILE Command
SYS( ) Functions Overview


SYS(2020) - Default Disk Free Space

Visual FoxPro 9.0 Language Reference
SYS(2020) - Default Disk Free Space
See Also

Returns the free space in bytes on the default disk.

SYS(2020)

Return Value

Character. SYS(2020) returns the free space in bytes on the default disk.

Remarks

You can specify the default disk using the SET DEFAULT command. For more information, see SET DEFAULT Command.

See Also

Other Resources

SYS( ) Functions Overview
DISKSPACE( ) Function


SYS(2021) - Filtered Index Expression

Visual FoxPro 9.0 Language Reference
SYS(2021) - Filtered Index Expression
See Also

Returns the filter expression for an open single-entry index (.idx) file or filter expressions for tags in compound index (.cdx) files.

SYS(2021, nIndexNumber [, nWorkArea | cTableAlias])

Parameters

nIndexNumber

The numeric expression nIndexNumber specifies which filter expression to return from the open index files. SYS(2021) returns filter expressions from open index files in the following order as nIndexNumber increases from 1 to the total number of open single-entry .idx files and structural compound and independent compound index tags:
  1. Filter expressions from single-entry .idx files (if any are open) are returned first. The order in which the single-entry .idx files are included in USE or SET INDEX determines the order in which the filter expressions are returned.

  2. Filter expressions for each tag in the structural .cdx file (if one is present) are returned next. The filter expressions are returned from the tags in the order the tags were created in the structural index.

  3. Filter expressions for each tag in any open independent .cdx files are returned last. The filter expressions are returned from the tags in the order the tags were created in the independent compound indexes.

The empty string is returned if nIndexNumber is greater than the total number of open single-entry .idx files and structural and independent .Cdx file tags.
nWorkArea

Specifies the work area number for a table open in another work area.
cTableAlias

Specifies a table alias for a table open in another work area. If a table doesn't have the alias you specify, Visual FoxPro displays an error message.

Return Value

Character

Remarks

You can create filtered indexes in Visual FoxPro. If you include the optional FOR clause in INDEX, the index file acts as a filter on the table. Only records that match the filter expression lExpression in the FOR clause are available for display and access. Index keys are created in the index file for only those records matching the filter expression.

The empty string is returned if an index or index tag was created without a FOR clause.

USE and SET INDEX both support an index file name list that makes it possible for you to open index files for a table. Any combination of single-entry .idx file names, structural .cdx file names, and independent .cdx file names may be included in the index file name list.

SYS(2021) returns filter expressions from index files open in the current work area unless you include a specific work area or alias.

See Also

Other Resources

CDX( ) Function
KEY( ) Function
INDEX Command
MDX( ) Function
NDX( ) Function
REINDEX Command
SET INDEX Command
SET ORDER Command
SYS( ) Functions Overview
TAG( ) Function


SYS(2022) - Disk Cluster Size

Visual FoxPro 9.0 Language Reference
SYS(2022) - Disk Cluster Size
See Also

Returns the cluster size in bytes of a specified disk.

SYS(2022 [, cDiskName])

Parameters

cDiskName

Specifies a drive letter (A, B, C, ...) for a disk other than the current default disk.

Return Value

Character

See Also

Other Resources

SET DEFAULT Command
SYS( ) Functions Overview
SYS(2020) - Default Disk Free Space


SYS(2023) - Temporary Path

Visual FoxPro 9.0 Language Reference
SYS(2023) - Temporary Path
See Also

Returns the path in which Visual FoxPro stores its temporary files.

SYS(2023)

Return Value

Character. SYS(2023) returns a path name.

Remarks

SYS(2023) uses the Windows API GetTempPath to search for the path containing the temporary files. GetTempPath searches a sequence of variables that differ depending on the operating system. For more information, see Optimizing the Operating Environment.

See Also

Other Resources

How to: Specify the Location of Temporary Files
SYS(2019) - Configuration File Name and Location
SYS( ) Functions Overview


SYS(2024) - Detect Report Cancellation

Visual FoxPro 9.0
SYS(2024) - Detect Report Cancellation
See Also Example

This function provides information about whether a report finished normally or was cancelled.

SYS(2024)

Parameters

None.

Return Value

Character. Returns "Y" if the current report was interrupted before processing its full data scope. Returns "N" if there is no current report or if the current report has not been interrupted.

Remarks

A report is considered "interrupted" by the Visual FoxPro Report System if one of the following actions occur:

  1. The report is running in object-assisted reporting mode, and a program invokes a ReportListener CancelReport method before the report is completely processed. For more information, see CancelReport Method.

  2. A user presses ESC or the Cancel button in backward-compatible reporting mode. When this happens, the SYS(2024) value is available to the report engine internally, although there may be no way for users to access the value.

  3. A program error occurs in code running during a report, whether in a user-defined function or ReportListener methods, and the user opts to Cancel from the resulting error dialog box.

During an interrupted report, SYS(2024) continues to return "Y" until after the complete sequence of report events. The return value of this function is reset to "N" after the UnloadReport Event finishes. For more information, see UnloadReport Event.

Example

The following example code is from the utilityReportListener class, which is responsible for file-handling procedures. When it closes a file at the conclusion of a report run, it checks to see what type of message should be displayed to the user regarding the success or failure of the report run. If the report run did not have any errors, the class uses SYS(2024) to determine whether the results of the report run are complete before assembling an appropriate message. For more information about this class, see ReportListener Utility and File-handling Foundation Class.
Copy Code
* excerpted from
* utilityReportListener.closeTargetFile method
IF THIS.HadError
   THIS.DoMessage(OUTPUTCLASS_CREATEERRORS_LOC, ;
                  MB_ICONEXCLAMATION )
ELSE
   THIS.DoMessage( OUTPUTCLASS_SUCCESS_LOC + ;
                   IIF(SYS(2024)="Y", ;
                   CHR(13)+OUTPUTCLASS_REPORT_INCOMPLETE_LOC,""),;
                   MB_ICONINFORMATION)
ENDIF

See Also

Concepts

Understanding Visual FoxPro Object-Assisted Reporting


SYS(2029) - Table Type

Visual FoxPro 9.0 Language Reference
SYS(2029) - Table Type
See Also Example

Returns a value corresponding to the table type.

SYS(2029 [, nWorkArea | cTableAlias])

Parameters

nWorkArea

Specifies the work area in which the table is open.
cTableAlias

Specifies the alias of the table. If you omit nWorkArea and cTableAlias, SYS(2029) returns a value for the table open in the currently selected work area.

Return Value

Character

Remarks

The following table lists the values returned by SYS(2029) and the corresponding table type:

Return value | Table type
0 | No table open.
3 | Previous versions of FoxPro, FoxBASE+, dBASE III PLUS, and dBASE IV with no memo field.
48 | Visual FoxPro with or without a memo field.
49 | Visual FoxPro with an Autoinc field (Visual FoxPro 8 and greater).
50 | Visual FoxPro with a Varchar, Varbinary or Blob field (Visual FoxPro 9 and greater).
67 | dBASE IV SQL table with no memo field.
99 | dBASE IV SQL System table with a memo field.
131 | FoxBASE+ and dBASE III PLUS table with a memo field.
139 | dBASE IV table with a memo field.
203 | dBASE IV SQL table with a memo field.
245 | Previous versions of FoxPro with a memo field.

Example

The following example opens the customer table in the testdata database.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer     && Open customer table

CLEAR
DO CASE
   CASE SYS(2029) = '3'
      ? 'Previous versions of FoxPro'
   CASE SYS(2029) = '48'
      ? 'Visual FoxPro Table'
   CASE SYS(2029) = '67'
      ? 'dBASE IV SQL table, no memo fields'
   CASE SYS(2029) = '99'
      ? 'dBASE IV SQL System table with a memo field'
   CASE SYS(2029) = '131'
      ? 'FoxBASE+ table with a memo field'
   CASE SYS(2029) = '139'
      ? 'dBASE IV table with a memo field'
   CASE SYS(2029) = '203'
      ? 'dBASE IV SQL table with a memo field'
   CASE SYS(2029) = '245'
      ? 'Previous versions of FoxPro with a memo field'
ENDCASE

See Also

Other Resources

ALTER TABLE - SQL Command
CREATE Command
CREATE TABLE - SQL Command
USE Command
SYS( ) Functions Overview


SYS(2030) - Debug

Visual FoxPro 9.0 Language Reference
SYS(2030) - Debug
See Also

Enable or disable debug features within system component user code.

SYS(2030[, 0 | 1])

Parameters

0

Disables the debug features.
1

Enables debug features so you can debug system component code.

Returns

Numeric. Value of the current setting.

Remarks

Starting with Visual FoxPro 7, whenever user code directly runs a system component, such as _GENMENU or _BROWSER, certain debugging features (profiling, dohistory, breakpoints, and single step) are disabled. SYS(2030, 1) enables you to run debugger on this type of user code by disabling the default behavior, then re-enabling the behavior after debugging by issuing SYS(2030, 0).

See Also

Other Resources

Debugger
SET ASSERTS Command
SET STEP Command
SYS( ) Functions Overview


SYS(2040) - Detect Report Status

Visual FoxPro 9.0 Language Reference
SYS(2040) - Detect Report Status
See Also Example

Detects whether a report is being printed or is in preview mode.

SYS(2040)

Return Value

Character data type. Returns the current status of the report as follows.

Value | Description
0 | There is no active report.
1 | Report is in Preview Mode
2 | Report is being sent as output (such as a printer or file).

Remarks

The SYS(2040) function is useful when you want to control content in a report depending on how it is being viewed. For example, you can print a message such as Confidential or Classified but not display it when the report is in Preview Mode.

Note:
The value returned by SYS(2040) does not provide information about whether there is an active preview window displayed. It provides information about whether the Visual FoxPro Report System is in process of generating output only, not with what happens to those results after they were generated. For example, SYS(2040) returns "0" after you use the command REPORT FORM OBJECT TYPE 1 (invoking an object-assisted report preview), even though the preview window is still on-screen, and it returns "0" after it sends output to a printer and closes the print queue, even though some of that output is not yet completely printed. By contrast, if your error handler is triggered, you can use SYS(2040) to determine whether the error was triggered by code occurring during a report run. Your error handler can use the value to determine whether it should do any report-specific cleanup before it exits your application.

Example

The following example displays how SYS(2040) can be used to suppress the _PAGETOTAL system variable when the report is in Preview Mode.
Copy Code
"Page: " + TRANS(_PAGENO) + ;
IIF( SYS(2040) = "1", "", " of " + TRANS(_PAGETOTAL))

See Also

Concepts

Understanding Visual FoxPro Object-Assisted Reporting

Other Resources

SYS( ) Functions Overview
REPORT Command


SYS(2060) - Mouse Wheel Events

Visual FoxPro 9.0 Language Reference
SYS(2060) - Mouse Wheel Events
See Also

Enables or disables the accumulation of mouse wheel events in the event queue.

SYS(2060 [, 0 | 1])

Parameters

0

Enables the combining of mouse wheel events in the event queue. (Default)
1

Disables the combining of mouse wheel events in the event queue.

Return Value

Character data type. Returns the current value of SYS(2060).

Remarks

When SYS(2060) is set to 0, mouse wheel events are added together in the event queue, rather than adding a new event. This creates smoother scrolling on slower computers.

See Also

Other Resources

SYS( ) Functions Overview
MouseWheel Event


SYS(2300) - Add or Remove Code Page

Visual FoxPro 9.0 Language Reference
SYS(2300) - Add or Remove Code Page
See Also Example

Adds or removes a code page from the National Language Support (NLS) list.

SYS(2300, nCodePage [, nAction])

Parameters

nCodePage

Specifies the integer code page value.
nAction

Specifies the action to perform on the specified code page. 0 removes the code page; 1 adds the code page.

Return Value

Character. SYS(2300) returns 1 if nCodePage appears in the NLS list; otherwise, it returns 0.

Remarks

When a code page is included in the list of those supported by Visual FoxPro, NLS routines are employed for proper indexing, string comparisons, collate keying, and so on. With certain collate sequences (for example, Russian, Czech, or Hungarian), string comparisons can result in unexpected values, depending on which code page is set. To make sure these operations proceed correctly you can use SYS(2300) in your applications to determine whether the correct code page is set.

If you create indexes after using SYS(2300) to enable NLS support for a specific code page, you will get odd behavior in previous versions of Visual FoxPro which do not have NLS support for that code page. Make sure all Visual FoxPro data access is made from clients with SYS(2300) configured in a similar manner.

The NLS list includes 874, 932, 936, 949, 950, 1255, and 1256. For more information, see Code Pages Supported by Visual FoxPro.

Example

Code page 1250 is not included in the NLS list by default. Therefore, certain string comparisons might return unexpected values. To demonstrate this, follow these steps:

  1. Enable code page support for non-NLS code page 1250 by adding the following line to your config.fpw file:

    Copy Code
    CODEPAGE = 1250
  2. Restart Visual FoxPro.

  3. Run the following code from a program file:

    Copy Code
    SET COLLATE TO 'HUNGARY'  && Requires CODEPAGE = 1250 in config file
CLEAR

? UPPER("B")=LOWER("B"), LOWER("B")=UPPER("B")
? UPPER("F")=LOWER("F"), LOWER("F")=UPPER("F")
? UPPER("H")=LOWER("H"), LOWER("H")=UPPER("H")

=SYS(2300,1250,1)  && Add code page 1250 to NLS list

? UPPER("B")=LOWER("B"), LOWER("B")=UPPER("B")
? UPPER("F")=LOWER("F"), LOWER("F")=UPPER("F")
? UPPER("H")=LOWER("H"), LOWER("H")=UPPER("H")

=SYS(2300,1250,0)  && Restore default setting for code page 1250
RETURN

With the default settings, LOWER("B")=UPPER("B"), LOWER("F")=UPPER("F"), and LOWER("H")=UPPER("H") return .T..

After enabling NLS support for code page 1250, LOWER("B")=UPPER("B"), LOWER("F")=UPPER("F"), and LOWER("H")=UPPER("H") return .F..

See Also

Other Resources

CPCURRENT( ) Function
CPCONVERT( ) Function
CPDBF( ) Function
SET COLLATE Command
SET CPDIALOG Command
SYS( ) Functions Overview


SYS(2325) - WCLIENTWINDOW from Visual FoxPro WHANDLE

Visual FoxPro 9.0 Language Reference
SYS(2325) - WCLIENTWINDOW from Visual FoxPro WHANDLE
See Also

Returns the hWnd of a client window from the parent window's WHANDLE.

SYS(2325, nWHANDLE)

Parameters

nWHANDLE

Specifies an integer WHANDLE to a FoxPro window. A WHANDLE is an internal Visual FoxPro structure (represented by an integer) that is a wrapper around an inner client window's hWnd.

Return Value

Numeric.

SYS(2325) returns the hWnd (Window Handle) for a client window (WCLIENTWINDOW) of a specified Visual FoxPro parent window. nWHANDLE is returned if nWHANDLE is valid but there is no WCLIENTWINDOW. 0 is returned if nWHANDLE is invalid.

Remarks

This function is intended for use with routines in the Visual FoxPro API Library Construction Kit. See the API Library Construction topic for more information about creating API libraries.

In Visual FoxPro 9.0, BINDEVENT( ) supports binding to Window Message (Win Msg) events. BINDEVENT( ) catches events passed to a hWnd (Window Handle). Many Visual FoxPro windows have an inner client window of type WCLIENTWINDOW which has its own hWnd. SYS(2325) lets you determine the hWnd of an inner client window.

SYS(2327) and SYS(2326) can be used to convert between a hWnd (Window Handle) and a Visual FoxPro WHANDLE.

See Also

Reference

AEVENTS( ) Function
BINDEVENT( ) Function
SYS(2326) - WHANDLE from a Window's hWnd
SYS(2327) - Window's hWnd from Visual FoxPro WHANDLE
UNBINDEVENTS( ) Function


SYS(2326) - WHANDLE from a Window's hWnd

Visual FoxPro 9.0 Language Reference
SYS(2326) - WHANDLE from a Window's hWnd
See Also

Returns a Visual FoxPro WHANDLE from a window’s hWnd.

SYS(2326, nhWnd)

Parameters

nhWnd

Specifies the integer hWnd (Window Handle) of the window for which the internal Visual FoxPro WHANDLE is returned.

Return Value

Numeric. The integer WHANDLE returned by SYS(2326) is an internal Visual FoxPro structure that is a wrapper around an hWnd.

Remarks

This function is intended for use with routines in the Visual FoxPro API Library Construction Kit. See the API Library Construction topic for more information about creating API libraries.

See Also

Reference

AEVENTS( ) Function
BINDEVENT( ) Function
SYS(2325) - WCLIENTWINDOW from Visual FoxPro WHANDLE
SYS(2327) - Window's hWnd from Visual FoxPro WHANDLE
UNBINDEVENTS( ) Function


SYS(2327) - Window's hWnd from Visual FoxPro WHANDLE

Visual FoxPro 9.0 Language Reference
SYS(2327) - Window's hWnd from Visual FoxPro WHANDLE
See Also

Returns a window's hWnd from a Visual FoxPro window’s WHANDLE.

SYS(2327, nWHANDLE)

Parameters

nWHANDLE

Specifies an integer WHANDLE to a FoxPro window. A WHANDLE is an internal Visual FoxPro structure (represented by an integer) that is a wrapper around an inner client window's hWnd.

Return Value

Numeric. SYS(2327) returns an integer hWnd value.

Remarks

The integer WHANDLE returned by is an internal Visual FoxPro structure that is a wrapper around an hWnd.

This function is intended for use with routines in the Visual FoxPro API Library Construction Kit. See the API Library Construction topic for more information about creating API libraries.

See Also

Reference

AEVENTS( ) Function
BINDEVENT( ) Function
SYS(2325) - WCLIENTWINDOW from Visual FoxPro WHANDLE
SYS(2326) - WHANDLE from a Window's hWnd
UNBINDEVENTS( ) Function


SYS(2333) - ActiveX Dual Interface Support

Visual FoxPro 9.0 Language Reference
SYS(2333) - ActiveX Dual Interface Support
See Also

Enables or disables ActiveX dual interface (VTABLE binding) support.

SYS(2333 [, 0 | 1 | 2])

Parameters

0

Disables ActiveX dual interface support. If 0 or 1 is omitted, ActiveX dual interface support is disabled. 0 is the startup default for Visual FoxPro 6.0 or later.
1

Enables ActiveX dual interface support. 1 is the startup default for Visual FoxPro 5.0.
2

Returns the current SYS(2333) setting (0 or 1).

Return Value

Character

Remarks

The ActiveX control dual interface (VTABLE binding) is an optimization supported by Visual FoxPro. If an ActiveX control doesn't use the dual interface, you can disable the optimization while using that control.

If an ActiveX control does not perform properly when the control is instantiated, issue SYS(2333) or SYS(2333, 0) before the control is instantiated to disable dual interface support for the control. After the control has been instantiated, issue SYS(2333, 1) to enable ActiveX dual interface support for any controls that are later instantiated.

See Also

Other Resources

ActiveX Controls Overview
OLE Container Control
Early (vtable) and Late (IDispatch) Binding
SYS( ) Functions Overview


SYS(2334) - Automation Server Invocation Mode

Visual FoxPro 9.0 Language Reference
SYS(2334) - Automation Server Invocation Mode
See Also

Returns a value indicating how a Visual FoxPro automation server method was invoked.

SYS(2334)

Return Value

Character

Remarks

The following table lists the values SYS(2334) returns for automation servers:

Return value | Invocation method
0 | Unknown (for example, invoked from the INIT method, which is neither VTable or IDispatch)
1 | OLEPUBLIC method invoked via VTable binding
2 | IDispatch

SYS(2334) also returns zero when executed from within a stand-alone executable (.exe). Use the StartMode property to determine how an instance of Visual FoxPro was started.

See Also

Other Resources

StartMode Property
Automation Server Programming Notes
SYS( ) Functions Overview


SYS(2335) - Unattended Server Mode

Visual FoxPro 9.0 Language Reference
SYS(2335) - Unattended Server Mode
See Also

Enables or disables modal states for distributable Visual FoxPro .exe automation servers.

SYS(2335 [, 0 | 1])

Parameters

0

Enables unattended mode. When unattended mode is enabled, a Visual FoxPro error is generated whenever a modal state occurs. Your .exe automation server can trap for these errors with an ON ERROR routine.
1

(Default) Disables unattended mode. Modal states, which require user intervention, can occur. Unattended mode is disabled at startup.

Return Value

Character

Remarks

Use SYS(2335) to enable or disable modal states in Visual FoxPro .exe automation servers. Automation servers are created with the Project Manager. For additional information about using Visual FoxPro to create .exe automation servers, see Sharing Information and Adding OLE.

Modal states occur when dialogs or errors messages are displayed, requiring input from a user to exit the dialog or error message and continue program execution. Modal states can be undesirable in .exe servers that are deployed remotely, possibly without intervention from a user. Program execution is halted, and requires intervention for program execution to continue.

The following table lists some typical examples of modal states that can occur in an .exe server.

Modal State | Examples
WAIT command or MESSAGEBOX( ) function | Can occur in program code.
Visual FoxPro errors such as "File access is denied" or "Allowed DO nesting level exceeded" | Can occur in program code.
Open dialog boxes | Can occur when files included in a SQL statement cannot be located.
SQL Connection Login dialog box | Can occur after a connection cannot be established.

SYS(2335 ,0) should be executed as soon as possible in unattended .exe automation server program code because a modal state can occur anytime after program execution begins.

Note that SYS(2335) applies only to .exe automation servers for which the StartMode property equals two. Unattended mode is always enabled for in-process .dll automation servers (for which the StartMode property equals three).

Issuing SYS(2335) without an argument in a runtime application returns its current setting.

See Also

Other Resources

SYS( ) Functions Overview
ON ERROR Command
StartMode Property


SYS(2336) - Critical Section support

Visual FoxPro 9.0 Language Reference
SYS(2336) - Critical Section support
See Also

Controls entries to or exits from a critical section in MTDLL servers.

SYS(2336 [, nAction])

Parameters

nAction

Specifies the action performed by the SYS(2336) function according to the following table.

nAction Description

(none)

Returns the current reference count. (Default)

1

Calls EnterCriticalSection.

2

Calls LeaveCriticalSection.

3

Calls LeaveCriticalSection as many times as necessary to reduce the reference count to 0, thereby freeing the critical section.

Return Value

Character. SYS(2336) returns the reference count for all values of nAction.

Remarks

SYS(2336) accesses EnterCriticalSection and LeaveCriticalSection Windows API calls. You can find details of these functions in the MSDN Library Platform SDK reference at http://msdn.microsoft.com/library.

See Also

Other Resources

SYS(3095) - IDispatch Pointer
Accessing APIs
BUILD MTDLL Command
SYS( ) Functions Overview


SYS(2339) - Call CoFreeUnusedLibraries when COM object is released

Visual FoxPro 9.0 Language Reference
SYS(2339) - Call CoFreeUnusedLibraries when COM object is released
See Also

Sets or returns whether Visual FoxPro calls the operating system function CoFreeUnusedLibraries when a COM object is released.

SYS(2339 [, 0 | 1 ])

Parameters

0

Specifies that CoFreeUnusedLibraries is not called (Default).
1

Specifies that CoFreeUnusedLibrariesis called.

Return Value

Character

Remarks

If you have problems releasing a COM server even though all references are released, you might need to change this setting. You can also use the DLL DECLARE command to call CoFreeUnusedLIbraries directly.

See Also

Other Resources

Visual FoxPro Run-Time Libraries
BUILD MTDLL Command
DECLARE - DLL Command
SYS( ) Functions Overview


SYS(2340) - NT Service Support

Visual FoxPro 9.0 Language Reference
SYS(2340) - NT Service Support
See Also

Disables or enables support for NT service.

SYS(2340 [,0 | 1 ])

Parameters

0

Disables support for NT Service (default).
1

Enables support for NT Service.

Return Value

Character

Remarks

This function intercepts Windows logoff messages (WM_QUERYENDSESSION and WM_ENDSESSION) to Visual FoxPro and specifies whether to keep Visual FoxPro COM Server instances running or to shut them down. A Visual FoxPro application will terminate when the current user logs off Windows. If the application is a Windows Service, then that service will terminate. Enabling support for NT service will make it possible for Visual FoxPro applications to continue even if the current user logs off Windows.

See Also

Other Resources

SYS( ) Functions Overview


SYS(2410) - Error Handler

Visual FoxPro 9.0 Language Reference
SYS(2410) - Error Handler
See Also

Returns the error handler type for an error. You can use SYS(2410) in your TRY...CATCH...FINALLY code to determine a course of action, for example, by using a DO CASE structure, depending on the type of handler that handles the exception.

SYS(2410)

Return Value

Character data type. The following table lists possible values returned by SYS(2410).

Value | Description
0 | System handler
1 | TRY...CATCH...FINALLY
2 | Error event
3 | ON ERROR command

Remarks

If a TRY...CATCH...FINALLY structure does not contain any CATCH statements or CATCH statements in which the WHEN lExpression evaluates to True (.T.), SYS(2410) might erroneously return an incorrect value.

See Also

Other Resources

SYS( ) Functions Overview
DO CASE ... ENDCASE Command
Exception Class
TRY...CATCH...FINALLY Command
Structured Error Handling


SYS(2450) - Application Search Path Order

Visual FoxPro 9.0 Language Reference
SYS(2450) - Application Search Path Order
See Also

Specifies how an application searches for data and resources such as functions, procedures, executable files, and so on.

You can use SYS(2450) to specify that Visual FoxPro searches within an application for a specific procedure or user-defined function (UDF) before it searches along the SET DEFAULT and SET PATH locations. Setting SYS(2450) can help improve performance for applications that run on a local or wide area network.

SYS(2450 [, 0 | 1 ])

Parameters

0

Search along path and default locations before searching in the application. (Default)
1

Search within the application for the specified procedure or UDF before searching the path and default locations.

Return Value

Character data type. Calling SYS(2450) without parameters returns a value of "0" or "1" specifying whether Visual FoxPro searches along the path and default locations before searching in the application or within the application first.

Remarks

You can use SET PROCEDURE to make sure that the file is found before path searching takes place. However, you must call SET PROCEDURE for each file.

See Also

Other Resources

SET DEFAULT Command
SET PATH Command
SET PROCEDURE Command
SYS( ) Functions Overview
DO Command


SYS(2600) - Return Pointer as String

Visual FoxPro 9.0 Language Reference
SYS(2600) - Return Pointer as String
See Also

Interprets an integer as pointer into memory and returns the contents of that memory as a string, or writes new data to that memory location.

SYS(2600, dwAddress, nLength [, cNewString])

Parameters

dwAddress

Specifies the pointer to a memory address. This value is interpreted as an integer.
nLength

Specifies the number of bytes to read from dwAddress.
cNewString

Specifies a value to be returned to dwAddress.

Remarks

This function is for advanced programmers only.

Examples

The following code returns the string cRes, which contains the nLen bytes starting at nAddress:

Copy Code
   cRes = SYS(2600, nAddress, nLen)

The following code returns the string cRes and also places nLen bytes of cSrc at nAddress:

Copy Code
   cRes = SYS(2600, nAddress, nLen, cSrc)

See Also

Other Resources

SYS( ) Functions Overview


SYS(2700) - Enables Windows XP Themes

Visual FoxPro 9.0 Language Reference
SYS(2700) - Enables Windows XP Themes
See Also

Enables or disables Windows XP Themes support in Visual FoxPro entirely.

SYS(2700 [, nValue ])

Parameters

nValue

Specifies a numeric value that determines whether to disable or enable Themes support. The following table lists the values for nValue.

nValue Setting

0

Disables Themes support.

1

Enables Themes support. (Default)

Return Value

Character data type. If Themes is not turned on or if you are running an older operating system that does not support Themes, SYS(2700) returns a value of 0 when arguments are omitted. If Themes is turned on, SYS(2700) returns a value of 1.

Remarks

The behavior of calling SYS(2700) without any arguments to return the current setting differs from the _SCREEN system variable in that it always returns the state of Themes on the computer. Therefore, if you use SYS(2700,1) to turn on Themes for Visual FoxPro and disable Themes using the Display control panel in Windows, SYS(2700) returns a value of 0 whereas _SCREEN.Themes still returns True (.T.).

When you change Themes support using the SYS(2700) function, Visual FoxPro might not refresh the user interface automatically. However, when Themes is turned on, certain effects such as those that appear when moving the mouse over controls will work. Therefore, it is recommended that you set Themes support at the beginning of an application before the user interface is rendered.

Note:
If you change Themes support while a form is running, you can call the form's Refresh method to redraw themed controls.

See Also

Other Resources

SYS( ) Functions Overview
_SCREEN System Variable
Refresh Method
Themes Property


SYS(2800) - Accessibility Support

Visual FoxPro 9.0 Language Reference
SYS(2800) - Accessibility Support
See Also

Disables or enables Microsoft Active Accessibility support and sets certain options to track the keyboard focus of the currently selected control in a Visual FoxPro form.

SYS(2800 [,nFlag] )

Parameters

nFlag

Disables accessibility support or enables various accessibility functionality according to the following table.
Note:
The flags are additive.

nFlags Description

0

Disables Active Accessibility (AA).

1

Enables WM_GETOBJECT.

2

Enables NotifyWinEvent.

4

Causes Visual FoxPro to not return to Accessibility clients until a specified action is complete. Overrides the messages of certain methods of IAccessible, such as accDoDefaultAction or accSelect, to process the client's request and return to the client immediately.

16

Enables ACCNAME. Returns object Name rather than Caption. Use for testing.

32

For backward compatibility only.
The default for nFlag is 3, which is the sum of "Enables WM_GETOBJECT" (2) + "Enables NotifyWinEvent" (3). For details on WM_GETOBJECT, NotifyWinEvent, and accDoDefaultAction, see the Accessibility topic in the User Interface Services section of Platform SDK in the MSDN Online Library.

Return Value

Character

Remarks

SYS(2800) returns a numeric value as a character string for the current Active Accessibility setting.

This function enables you to verify the functionality of accessibility aids, such as the Microsoft Magnifier, when you are designing an application to comply with Windows Logo requirements.

This function is only effective for native Visual FoxPro controls. Third party ActiveX controls may or may not correctly track keyboard focus with accessibility aids enabled. Contact the control vendor for information on the accessibility behavior of a specific control.

See Also

Other Resources

SYS( ) Functions Overview


SYS(2801) - Event Tracking Support

Visual FoxPro 9.0 Language Reference
SYS(2801) - Event Tracking Support
See Also

Extends event tracking of mouse and keyboard events.

SYS(2801 [, 1 | 2 | 3 ] )

Parameters

1

Record only Visual FoxPro object events.
2

Record only Windows mouse and keyboard events
3

Record both Visual FoxPro and Windows events

Remarks

You can use SYS(2801) to specify which user events are tracked when your code is executed. You can set up event tracking in the Visual FoxPro debugger or use the SET EVENTTRACKING command.

See Also

Other Resources

SET EVENTLIST Command
SYS(2800) - Accessibility Support
Understanding the Event Model
SYS( ) Functions Overview


SYS(2910) - List Display Count

Visual FoxPro 9.0 Language Reference
SYS(2910) - List Display Count
See Also

Sets or returns the number of items to display in drop-down list boxes.

SYS(2910 [, nValue])

Parameters

nValue

The nValue parameter determines how many items appear visible in a drop-down list box. This includes drop-down list boxes for AutoComplete, IntelliSense, Method Editor drop-down list boxes, Properties Window object drop-down list boxes, etc. The range for nValue is 5 to 200. The default value is 15. Omitting nValue returns the current setting.

Return Value

Character. The current drop-down list box display count is returned as a character string.

Remarks

At design-time, the display count value is stored in the registry when you choose the Set As Default button in the Options Dialog Box (Visual FoxPro), and is restored the next time you run Visual FoxPro. Setting a value with this function does not write the value to the registry unless you choose the Set As Default button in Options dialog box.

See Also

Reference

Options Dialog Box
AutoComplete Property


SYS(3004) - Return Locale ID

Visual FoxPro 9.0 Language Reference
SYS(3004) - Return Locale ID
See Also

Returns the Locale ID used by automation and ActiveX controls.

SYS(3004)

Return Value

Character

Remarks

SYS(3004) returns the current Visual FoxPro Locale ID (LCID), which is determined by the Visual FoxPro Language ID (LangID) and Sort ID.

The Locale ID determines the language in which automation and ActiveX controls exchange information. The default Visual FoxPro Locale ID is 1033, English.

For example, assume you have installed the German version of Microsoft Excel 5.0, which supports both English and German commands. In this case, the following example makes it possible for you to start and close the German version of Microsoft Excel 5.0:

Copy Code
oleExcel1 = CREATEOBJECT('Excel.Application')  && Starts Excel

? SYS(3005, 1033)  && English Locale ID
oleExcel1.Quit  && Closes Excel with English command

oleExcel2 = CREATEOBJECT('Excel.Application')  && Starts Excel

? SYS(3005, 1031)  && German Locale ID
oleExcel2.Beenden  && Closes Excel with German command

For a list of Visual FoxPro Locale IDs, see SYS(3005) - Set Locale ID. For additional information about Locale, Language, and Sort IDs, see the Microsoft Windows Software Development Kit documentation.

See Also

Other Resources

DefOLELCID Property
OLELCID Property
SYS(3005) - Set Locale ID
SYS(3006) - Set Language and Locale IDs
SYS( ) Functions Overview


SYS(3005) - Set Locale ID

Visual FoxPro 9.0 Language Reference
SYS(3005) - Set Locale ID
See Also

Sets the Locale ID used by automation and ActiveX controls.

SYS(3005, nLocaleID)

Parameters

nLocaleID

Specifies the Locale ID. The following list contains the Locale IDs supported in Visual FoxPro:

nLocaleID Language

1029

Czech

1031

German

1033

English (Default)

1034

Spanish

1036

French

1040

Italian

1045

Polish

1046

Portuguese (Brazil)

2070

Portuguese (Portugal)

Return Value

Character

Remarks

SYS(3005) sets the global Locale ID (LCID). The Locale ID determines the language in which automation and ActiveX controls exchange information. The default Visual FoxPro Locale ID is 1033, English.

Note:
Using the DefOLELCID Property is the preferred method for setting a Locale ID for a form or the main Visual FoxPro window. The automation command language is affected only by the Global LocaleID, set with SYS(3005). The DefOLELCID and OLELCID properties affect only the language of the user interface, which ActiveX controls display, and not the language of the automation commands.

For example, assume you have installed the German version of Microsoft Excel 5.0, which supports both English and German commands. In this case, the following example makes it possible for you to start and close the German version of Microsoft Excel 5.0:

Copy Code
LOCAL loExcel_Enu AS Excel.APPLICATION, ;
loExcel_Deu AS Excel.APPLICATION

loExcel_Enu = CREATEOBJECT('Excel.Application')  && Starts Excel
? SYS(3005, 1033)  && English Locale ID
loExcel_Enu.QUIT  && Closes Excel with English command

loExcel_Deu = CREATEOBJECT('Excel.Application')
? SYS(3005, 1031)  && German Locale ID
loExcel_Deu.Beenden  && Closes Excel with German command

For additional information about Locale IDs, see the Microsoft Windows Software Development Kit documentation.

See Also

Other Resources

DefOLELCID Property
OLELCID Property
SYS(3004) - Return Locale ID
SYS(3006) - Set Language and Locale IDs
SYS( ) Functions Overview


SYS(3006) - Set Language and Locale IDs

Visual FoxPro 9.0 Language Reference
SYS(3006) - Set Language and Locale IDs
See Also

Sets the Language ID and the Locale ID.

SYS(3006, nLanguageID)

Parameters

nLanguageID

Specifies the Language ID.

Return Value

Character

Remarks

SYS(3006) sets the Visual FoxPro Language ID (LangID), and then sets the Locale ID (LCID) based on the Language ID and the current value of the Sort ID.

Note:
Using the DefOLELCID Property is the preferred method for setting a Locale ID for a form or the main Visual FoxPro window.

For additional information about Language, Locale, and Sort IDs, see the Microsoft Windows Software Development Kit documentation.

See Also

Other Resources

DefOLELCID Property
OLELCID Property
SYS(3004) - Return Locale ID
SYS(3005) - Set Locale ID
SYS( ) Functions Overview


SYS(3007) - ToolTipText Property Font Language Script

Visual FoxPro 9.0 Language Reference
SYS(3007) - ToolTipText Property Font Language Script
See Also

Specifies a font language script for the text that appears as a ToolTip for a control.

SYS(3007 [, nFontCharSet])

Parameters

nFontCharSet

Specifies a font language script for the text that appears as a ToolTip for all controls. The ToolTip text is specified with the ToolTipText Property. See the GETFONT( ) Function for a list of available language font script values.

Return Value

Character. If the nFontCharSet parameter is omitted, SYS(3007) returns the current font language script setting.

See Also

Reference

FontCharSet Property
GETFONT( ) Function
SYS(3009) - Bidirectional Text Justification for ToolTips
ToolTipText Property


SYS(3008) - Hyperlink Tooltips

Visual FoxPro 9.0 Language Reference
SYS(3008) - Hyperlink Tooltips

Enables or disables Hyperlink tooltips.

SYS(3008 [, 0 | 1]

Parameters

Parameter | Description
0 | Disables hyperlink tooltips.
1 | (Default) Enables hyperlink tooltips.

Remarks

Issue SYS(3008) without a parameter to return its current setting. SYS(3008) affects all hyperlink tooltips in Visual FoxPro, including editors opened with MODIFY COMMAND Command, MODIFY FILE Command, and MODIFY MEMO Command and the EditBox Control.

SYS(3008) does not affect the _Hyperlink foundation class library included with Visual FoxPro.


SYS(3009) - Bidirectional Text Justification for ToolTips

Visual FoxPro 9.0 Language Reference
SYS(3009) - Bidirectional Text Justification for ToolTips
See Also

Enables or disables bidirectional text justification for ToolTips.

SYS(3009 [, 0 | 1])

Parameters

0

(Default) Disables bidirectional text justification for ToolTips. Text in ToolTips is justified in a left to right direction.
1

Enables bidirectional text justification for ToolTips. Text in ToolTips is justified in a right to left direction.

Return Value

Character. If the 0 or 1 options are omitted, SYS(3009) returns the current bidirectional text justification setting.

Remarks

SYS(3009) affects the ToolTips text justification for all controls and memo fields in an interactive or runtime Visual FoxPro session.

See Also

Reference

SYS(3007) - ToolTipText Property Font Language Script


SYS(3050) - Set Buffer Memory Size

Visual FoxPro 9.0 Language Reference
SYS(3050) - Set Buffer Memory Size
See Also

Sets the foreground or background buffer memory size.

SYS(3050, nType, [nBuffMemSize])

Parameters

nType

Specifies the buffer. The following table lists the values for nType and the corresponding buffer:

nType Buffer

1

Foreground

2

Background
nBuffMemSize

Specifies the maximum buffer memory size in bytes. If you specify a value for nBuffMemSize that is less than 256K bytes, Visual FoxPro sets the buffer memory size to 256K bytes. Specify 0 for nBuffMemSize to return the buffer memory size to the Visual FoxPro startup value. The startup value depends on the amount of your computer's memory. If you omit nBuffMemSize, SYS(3050) returns the buffer memory size for the buffer specified with nType.

Return Value

Character

Remarks

SYS(3050) makes it possible for you to optimize Visual FoxPro performance by adjusting the amount of memory Visual FoxPro allocates for the foreground and background buffers. The foreground memory buffer is the memory available to Visual FoxPro when it is operating in the foreground as the currently active application. The background memory buffer is the memory available to Visual FoxPro when it is operating in the background when another application is the foreground application.

SYS(3050) returns a numeric value as a character string that indicates the maximum amount of memory Visual FoxPro allocates for the foreground or background buffers.

See Also

Other Resources

SYS(1001) - Visual FoxPro Memory
DISPLAY MEMORY Command
MEMORY( ) Function
How to: Manage Memory
SYS( ) Functions Overview


SYS(3051) - Set Lock Retry Interval

Visual FoxPro 9.0 Language Reference
SYS(3051) - Set Lock Retry Interval
See Also

Specifies the time in milliseconds that Visual FoxPro waits before attempting to lock a record, table, memo, or index file after an unsuccessful locking attempt.

SYS(3051, [nWaitMilliseconds])

Parameters

nWaitMilliseconds

Specifies the wait time in milliseconds; can be a value from 100 to 1000 milliseconds. Specify 0 for nWaitMilliseconds to return the lock attempt time interval to the Visual FoxPro default startup value (333 milliseconds). If you omit nWaitMilliseconds, SYS(3051) returns the current lock attempt time interval.

Return Value

Character

Remarks

SYS(3051) returns a numeric value as a character string that indicates the lock attempt time interval.

See Also

Other Resources

SET REPROCESS Command
SYS(3052) - Override SET REPROCESS Locking
How to: Lock Data
SYS( ) Functions Overview


SYS(3052) - Override SET REPROCESS Locking

Visual FoxPro 9.0 Language Reference
SYS(3052) - Override SET REPROCESS Locking
See Also

Specifies whether Visual FoxPro uses the SET REPROCESS setting when attempting to lock an index or memo file.

SYS(3052, nFileType, [lHonorReprocess])

Parameters

nFileType

Specifies the type of file. The following table lists the values for nType and the corresponding file type:

nFileType File type

1

Index

2

Memo
lHonorReprocess

Specifies whether Visual FoxPro uses the SET REPROCESS setting for unsuccessful lock attempts for index and memo files. Specify true (.T.) to use the SET REPROCESS setting when Visual FoxPro attempts to lock files specified with nFileType. Specify false (.F.), the default, to override the SET REPROCESS setting when Visual FoxPro attempts to lock files specified with nFileType. When set to false, Visual FoxPro waits indefinitely for locks on the specified files; this option is the same as locking behavior in previous versions of FoxPro. If you omit lHonorReprocess, SYS(3052) returns the current setting for the file type specified with nFileType.

Return Value

Character

Remarks

SYS(3052) provides additional control over file locking in Visual FoxPro. It's best to set lHonorReprocess to true (.T.) in order to reduce the risk of file lock contention if your application uses transaction processing.

SYS(3052) returns as a character string a numeric value of 0 (corresponding to false (.F.)) or 1 (corresponding to true (.T.)). If lHonorReprocess is included in SYS(3052), the value returned is identical to the logical value you specify for lHonorReprocess. If you omit lHonorReprocess, the value returned is the current setting for the file type specified with nFileType.

See Also

Other Resources

SET REPROCESS Command
SYS(3051) - Set Lock Retry Interval
How to: Lock Data
SYS( ) Functions Overview


SYS(3053) - ODBC Environment Handle

Visual FoxPro 9.0 Language Reference
SYS(3053) - ODBC Environment Handle
See Also

Returns the ODBC environment handle.

SYS(3053)

Return Value

Character

Remarks

If ODBC isn't loaded, SYS(3053) loads it and returns the ODBC environment handle.

The environment handle returned by SYS(3053) provides access to ODBC through ODBC API calls. Access to the ODBC API is available in Visual FoxPro through DECLARE - DLL, and through external Visual FoxPro API library routines.

Only one ODBC environment handle should be used at any time. A Visual FoxPro program using ODBC calls should use SYS(3053) to get the ODBC environment handle rather than reallocating and freeing the ODBC environment handle through ODBC API calls.

Exercise care when manipulating an ODBC environment handle. For further information about the ODBC API, see the Microsoft ODBC SDK documentation.

See Also

Other Resources

DECLARE - DLL Command
SET LIBRARY Command
Execution of ODBC Extensions to SQL
Read ODBC Registry Values
SYS( ) Functions Overview


SYS(3054) - Rushmore Query Optimization Level

Visual FoxPro 9.0 Language Reference
SYS(3054) - Rushmore Query Optimization Level
See Also Example

Enables or disables display of Rushmore optimization levels for queries.

SYS(3054 [, 0 | 1 | 11 | 2 | 12] [, cMEMVAR])

Parameters

0

(Default) Disables the display of Rushmore optimization levels.
1

Enables the display of the Rushmore filter optimization levels.
11

Enables the display of Rushmore join optimization levels.
2

Includes SQL statement with the display of the Rushmore filter optimization levels.
12

Includes SQL statement with the display of Rushmore join optimization levels.
cMEMVAR

Specifies an undeclared or declared PUBLIC or LOCAL memory variable in which to store the showplan information. If you have not declared cMEMVAR, Visual FoxPro creates it as a PRIVATE variable.

Return Value

Character

Remarks

SYS(3054) returns the current Rushmore optimization level setting as a character string to the active screen or to a memory variable.

The showplan output displays the table alias as reference for table name.

Use SYS(3054) to improve query performance by determining the extent to which the query is optimized by Rushmore technology.

Issue SYS(3054, 1) to display the Rushmore filter optimization level after a query is executed. The filter optimization level is displayed in the active window.

The following table lists the three levels of Rushmore optimization:

Optimization Level | Description
None | The query could not be optimized with Rushmore technology.
Partial | Some expressions in the query could be optimized with Rushmore technology. The index tags used for Rushmore optimization are listed.
Full | The query was fully optimized with Rushmore technology. The index tags used for Rushmore optimization are listed.

If SYS(3054,1) indicates that a query could not be optimized or could be optimized only partially, you can modify the query to take advantage of Rushmore optimization.

Issue SYS(3054, 11) to display the Rushmore join optimization level after a query is executed. The optimization level is displayed in the active window.

Issue SYS(3054, 0) to stop display of the Rushmore optimization level after a query is executed.

For more information about Rushmore technology and optimizing queries, see Using Rushmore Query Optimization to Speed Data Access.

Example

The following code displays the Rushmore Optimization level after performing a query:
Copy Code
LOCAL cmemvar
=SYS(3054,11,"cmemvar")
SELECT * FROM HOME()+"labels.dbf"
? cmemvar

See Also

Other Resources

PUBLIC Command
LOCAL Command
PRIVATE Command
SELECT - SQL Command
Using Rushmore Query Optimization to Speed Data Access
SYS( ) Functions Overview


SYS(3055) - FOR and WHERE Clause Complexity

Visual FoxPro 9.0 Language Reference
SYS(3055) - FOR and WHERE Clause Complexity
See Also

Sets the complexity level of the FOR and WHERE clauses in commands and functions that support those clauses.

SYS(3055 [, nComplexity])

Parameters

nComplexity

Specifies the complexity level. The valid range for nComplexity is 320 to 2040. The default value is 320. If you specify an odd value, it is rounded down to the closest even integer.

Return Value

Character

Remarks

If you receive the error Insufficient stack space (Error 1308) or SQL: Statement too long (Error 1812), you can increase the FOR and WHERE clause complexity to help prevent the error.

For example, calling TABLEUPDATE( ) for a local table or view that doesn't use key fields generates a long WHERE clause to find the update row. The default number of fields supported in the WHERE clause is 40. If you receive the error SQL: Statement too long (Error 1812), you should either use a key field for the update or increase the complexity of the WHERE clause with SYS(3055). If you use SYS(3055), increase its value to 8 times the number of fields in the table:

Copy Code
= SYS(3055, 8 * MIN(40, FCOUNT( )))

If SYS(3055) is issued without the nComplexity argument, its current setting is returned.

Note:
This function also determines the number of items you can list in the IN clause of a query.

The following commands and functions support the FOR or WHERE clauses:

APPEND FROM | APPEND FROM ARRAY | AVERAGE
BLANK | BROWSE | CALCULATE
CHANGE | COPY TO ARRAY | COPY TO
COUNT | DEFINE PAD | DELETE
DELETE - SQL | DISPLAY | EXPORT
FOR( ) | INDEX | LABEL
LIST | LOCATE | RECALL
REPLACE | REPLACE FROM ARRAY | REPORT
SCAN ... ENDSCAN | SELECT - SQL | SORT
SUM | TABLEUPDATE( ) | UPDATE - SQL

See Also

Reference

SELECT - SQL Command
SELECT - SQL Command - WHERE Clause

Other Resources

TABLEUPDATE( ) Function
SYS( ) Functions Overview
Insufficient stack space (Error 1308)
SQL: Statement too long (Error 1812)


SYS(3056) - Read Registry Settings

Visual FoxPro 9.0 Language Reference
SYS(3056) - Read Registry Settings
See Also

Forces Visual FoxPro to read its registry settings again and update itself with the current registry settings, or to write its settings to the registry.

SYS(3056 [, nValue])

Parameters

nValue

The following table describes the values for nValue.

Value Description

1

(Default) Include the 1 option to update only from registry settings, with the exception of SET commands and file locations.

2

Include the 2 option to write Visual FoxPro settings to the registry. Including the 2 option is identical to choosing Set As Default in the Options Dialog Box (Visual FoxPro).

Return Value

Character

Remarks

Returns the empty string.

Visual FoxPro stores the Options dialog box settings in the Windows registry. You can also store additional Visual FoxPro configuration settings in a text file, normally named Config.fpw. Visual FoxPro is configured when it is started by reading these registry settings and its configuration file (if one exists).

The settings you specify in the Options dialog box are written to the registry when you choose SetAs Default. Some settings, such as those for Syntax Coloring, are stored in the registry but have no corresponding SET commands. Other settings do have corresponding SET commands (such as SET BELL, SET CLOCK, and so on) that affect the Visual FoxPro environment. The settings made from the File Locations tab in the Options dialog box are also stored in the registry, and some are accessible through system variables such as _COVERAGE and _SAMPLES.

Issuing SYS(3056) updates information from the registry settings and the corresponding SET commands, registry settings from the Options dialog File Locations tab, and the Visual FoxPro configuration file (if one exists). SYS(3056) reads the registry information first, and then the configuration file.

Issuing SYS(3056,1) updates information from the Visual FoxPro registry settings that don't have corresponding SET commands. The SET commands, File Locations registry settings, and configuration file information aren't updated if the 1 argument is included.

Issuing SYS(3056,2) writes the Options dialog box settings to the Windows registry.

Note that registry settings can also be changed directly through the Windows API. See the Windows API section of Solution.app, located in the Visual FoxPro ...\Samples\Solution directory, for an example of how you can use the Windows API to modify registry settings.

See Also

Other Resources

SET Command
Options Dialog Box
Read and Write Visual FoxPro Registry Values
How to: Change Configuration Settings in the Windows Registry
SYS( ) Functions Overview


SYS(3065) - Internal Program Cache

Visual FoxPro 9.0
SYS(3065) - Internal Program Cache
See Also

Returns the current internal program cache (PROGCACHE) setting. This setting determines the amount of memory available to run programs.

SYS(3065 [, 1])

Parameters

1

Returns the total memory of all loaded programs.

Returns

Numeric. Returns the current PROGCACHE setting specified in the configuration file. If no setting is specified, the default is returned (-2 for MTDLL, otherwise 144).

Sample

The following sample shows how you can exceed the default Visual FoxPro program cache and cause an Error 1202 to occur. If you specify a PROGCACHE=0 setting in your config.fpw file, no error occurs.

Copy Code
CLEAR ALL
LOCAL lcBigStr,lcSafe
ON KEY LABEL F5 ? SYS(3065)+" "+SYS(3065,1)
? SYS(3065)+" "+SYS(3065,1)
SET TEXTMERGE ON NOSHOW
SET TEXTMERGE TO MEMVAR lcBigStr
      FOR i = 1 TO 39000
\           x="<<REPLICATE('a ',120)>>"
      ENDFOR
SET TEXTMERGE to
? LEN(lcBigStr)
lcSafe=SET("Safety")
SET SAFETY OFF
STRTOFILE(lcBigStr,"bigprg.prg")
SET SAFETY &lcSafe
COMPILE bigprg
DO bigprg
? SYS(3065)+" "+SYS(3065,1)
ON KEY LABEL F5

See Also

Reference

Special Terms for Configuration Files
Program is too large (Error 1202)


SYS(3092) - Output Rushmore Query Optimization Level

Visual FoxPro 9.0 Language Reference
SYS(3092) - Output Rushmore Query Optimization Level
See Also

Specifies a file to which Rushmore optimization levels for queries are output.

SYS(3092 [,cFileName [, lAdditive]])

Parameters

cFileName

The name of the file to which the Rushmore optimization levels are output. Specify the empty string ("") to turn off output and close a file created earlier with this function.
lAdditive

A logical value that specifies if the file is overwritten when a new query is executed. If lAdditive is set to true (.T.), the query optimization levels are appended to previous output. If lAdditive is set to false (.F.) (the default setting), any previous output is overwritten.

Return Value

SYS(3092) returns the empty string if Rushmore optimization levels for queries are not being output to a file. If query optimization levels are being output to a file, SYS(3092) returns the path and name of the file to which output is directed.

Remarks

Use SYS(3054) - Rushmore Query Optimization Level to specify the type of Rushmore optimization information that is sent to the output file.

SYS(3092) is scoped to a thread in a multithreaded runtime application. Both SYS(3092) and SYS(3054) are unavailable in the OLE DB Provider for Visual FoxPro.

See Also

Tasks

How to: Optimize Filters and Joins

Reference

SYS(3054) - Rushmore Query Optimization Level


SYS(3095) - IDispatch Pointer

Visual FoxPro 9.0 Language Reference
SYS(3095) - IDispatch Pointer
See Also

Returns an outgoing IDispatch pointer for a COM object

SYS(3095, oObject)

Parameters

oObject

Represents a reference to a COM object such as _VFP or Excel.Application.

Return Value

Character

Remarks

This pointer is provided for experienced developers who need an object pointer for use in API routines.

See Also

Other Resources

Early (vtable) and Late (IDispatch) Binding
API Library Routines A-Z
API Library Routines by Category
DECLARE - DLL Command
SYS( ) Functions Overview


SYS(3096) - IDispatch Object Reference

Visual FoxPro 9.0 Language Reference
SYS(3096) - IDispatch Object Reference
See Also

Returns a Visual FoxPro COM object reference for an IDispatch pointer.

SYS(3096, nPointer)

Parameters

nPointer

Represents a pointer to a COM object such as _VFP or Excel.Application.

Return Value

Object reference. SYS(3096) returns a Visual FoxPro COM object reference.

Remarks

This pointer is provided so experienced developers who need to determine an object reference for use in API routines. The refcount for the COM object is NOT changed.

See Also

Other Resources

SYS( ) Functions Overview
Early (vtable) and Late (IDispatch) Binding
API Library Routines A-Z
API Library Routines by Category
DECLARE - DLL Command
SYS(3097) - Add Reference to Object
SYS(3098) - Release Object reference


SYS(3097) - Add Reference to Object

Visual FoxPro 9.0 Language Reference
SYS(3097) - Add Reference to Object
See Also

Performs an IDispatch AddRef call on a COM object.

SYS(3097, oObject)

Parameters

oObject

Object reference to COM object.
Note:
This function is provided for experienced developers. Invalid COM object reference counts can yield problems such as objects not being released correctly or calls to objects that no longer exist.

Returns

Numeric. Returns the current Refcount after adding a new object reference.

See Also

Other Resources

SYS(3098) - Release Object reference
DECLARE - DLL Command
SYS( ) Functions Overview


SYS(3098) - Release Object reference

Visual FoxPro 9.0 Language Reference
SYS(3098) - Release Object reference
See Also

Performs an IDispatch Release call on a COM object.

SYS(3098, oObject)

Parameters

oObject

Object Reference to COM Object.
Note:
This function is provided for experienced developers. Invalid COM object reference counts can yield problems such as objects not being released correctly or calls to objects that no longer exist.

Returns

Numeric. Returns the current Refcount after releasing an object reference.

See Also

Other Resources

SYS(3097) - Add Reference to Object
DECLARE - DLL Command
SYS( ) Functions Overview


SYS(3099) - SQL Data Engine Compatibility Mode

Visual FoxPro 9.0 Language Reference
SYS(3099) - SQL Data Engine Compatibility Mode
See Also

Enables SQL data engine compatibility with Visual FoxPro 7.0, 8.0, or 9.0.

SYS(3099 [, 70 | 80 | 90])

Parameters

70

Specifies that Visual FoxPro treat SQL commands with behavior as in versions prior to Visual FoxPro 8.0.
80

Specifies that Visual FoxPro treat SQL commands with behavior as in Visual FoxPro 8.0.
90

Specifies that Visual FoxPro treat SQL commands with standard Visual FoxPro 9.0. (Default)

See Also

Other Resources

SELECT - SQL Command
SET ENGINEBEHAVIOR Command
Special Terms for Configuration Files
SYS( ) Functions Overview


SYS(3101) - COM Code Page Translation

Visual FoxPro 9.0
SYS(3101) - COM Code Page Translation
See Also

Sets the default code page to use for character data translation during COM interoperability in the current data session.

SYS(3101 [, nCodePage])

Parameters

nCodePage

The code page (integer) to use for translating character data during COM interoperability. An error will occur if an invalid code page is passed.

Return Value

SYS(3101) returns the current code page. If an nCodePage parameter is included, the code page previously set is returned. The default setting is 0 (machine).

Remarks

If a COMPROP(,"UTF8",1) setting is in effect, it will take precedence over the SYS(3101) setting.

The CursorAdapter ADOCodePage property allows you to control the code page used for character translation when working with ADO data.

Note:
It is recommended that you limit use of this function to your specific COM translation needs and restore it to the previous default setting when done.

See Also

Reference

COMPROP( ) Function

Other Resources

Code Pages in Visual FoxPro
SYS( ) Functions Overview


SYSMETRIC( ) Function

Visual FoxPro 9.0 Language Reference
SYSMETRIC( ) Function
See Also

Returns the size of the operating system's screen elements.

SYSMETRIC(nScreenElement)

Parameters

nScreenElement

Specifies a screen element. The following table shows values for nScreenElement and the corresponding screen element:

nScreenElement Screen Element

1

Screen width

2

Screen height.

3

Width of sizable window frame

4

Height of sizable window frame

5

Width of scroll arrows on vertical scroll bar

6

Height of scroll arrows on vertical scroll bar

7

Width of scroll arrows on horizontal scroll bar

8

Height of scroll arrows on horizontal scroll bar

9

Height of window title

10

Width of non-sizable window frame

11

Height of non-sizable window frame

12

Width of DOUBLE or PANEL window frame

13

Height of DOUBLE or PANEL window frame

14

Scroll box width on horizontal scroll bar in text editing windows

15

Scroll box height on vertical scroll bar in text editing windows

16

Minimized window icon width

17

Minimized window icon height

18

Maximum insertion point width

19

Maximum insertion point height

20

Single-line menu bar height

21

Maximized window width

22

Maximized window height

23

Kanji window height

24

Minimum sizable window width

25

Minimum sizable window height

26

Minimum window width

27

Minimum window height

28

Window controls width

29

Window controls height

30

1 if mouse hardware present; otherwise 0

31

1 for Microsoft Windows debugging version; otherwise 0

32

1 if mouse buttons swapped; otherwise 0

33

Width of a button in a half-caption window's caption or title bar

34

Height of half-caption window caption area

Return Value

Character

Remarks

SYSMETRIC( ) returns the size of screen elements. Screen elements include menus, windows, window controls, and the insertion point. Values are returned in pixels unless otherwise noted and can vary for different displays, display drivers, and video hardware. For further information on screen elements, refer to the GetSystemMetrics function in the MSDN Library at http://msdn.microsoft.com/library.

SYSMETRIC( ) enables you to determine the size of menus, windows, and window controls you create in Visual FoxPro. Windows and menus created with DEFINE WINDOW and DEFINE MENU use the same screen element sizes as the operating system's windows and menus.

See Also

Other Resources

FONTMETRIC( ) Function
GETFONT( ) Function
TXTWIDTH( ) Function
WFONT( ) Function
Functions
Language Reference


TABLEREVERT( ) Function

Visual FoxPro 9.0 Language Reference
TABLEREVERT( ) Function
See Also Example

Discards changes made to a buffered row or a buffered table or cursor and restores the OLDVAL( ) data for remote cursors and the current disk values for local tables and cursors.

Note:
On a network, the data currently on disk might differ from the data on the disk when the table was opened or the cursor was created. Other users on the network might have changed the data after the table was opened or the cursor was created.

TABLEREVERT( [lAllRows [, cTableAlias | nWorkArea] ] )

Parameters

lAllRows

Determines whether all changes made to the table or cursor are discarded. The following table describes the values for lAllRows.

lAllRows Description

False (.F.)

If table buffering is enabled, only changes made to the current record in the table or cursor are discarded. (Default)

True (.T.)

If table buffering is enabled, changes made to all records are discarded in the table or cursor.
If row buffering is enabled, Visual FoxPro disregards the value of lAllRows, and changes made to the current record in the table or cursor are discarded.
cTableAlias

Specifies the alias of the table or cursor in which the changes are discarded.
nWorkArea

Specifies the work area of the table or cursor in which the changes are discarded.

Return Value

Numeric data type. TABLEREVERT( ) returns the number of records for which changes were discarded.

Remarks

TABLEREVERT( ) cannot discard changes made to a table or cursor that does not have row or table buffering enabled. If you issue TABLEREVERT( ) and row or table buffering is not enabled, Visual FoxPro generates an error message. Use CURSORSETPROP( ) to enable or disable row and table buffering.

Changes are discarded in the table or cursor open in the currently selected work area if TABLEREVERT( ) is issued without the optional cTableAlias or nWorkArea arguments.

TABLEREVERT( ) does not return the record pointer to its original position.

TABLEREVERT( ) operates on CursorAdapter objects in the same way as other buffered cursors.

In Visual FoxPro 9.0, you cannot issue the TABLEREVERT( ) function when a TABLEUPDATE( ) is in operation.

Example

The following example demonstrates how you can use TABLEREVERT( ) to discard changes made to a buffered table. MULTILOCKS is set to ON, a requirement for table buffering. The customer table in the testdata database is opened, and CURSORSETPROP( ) is then used to set the buffering mode to optimistic table buffering (5).

The value of the cust_id field is displayed and then the cust_id field is modified with REPLACE. The new value of the cust_id field is displayed. TABLEREVERT( ) is then used to return the table to its original state (TABLEUPDATE( ) could be issued instead to commit the changes). The reverted value of the cust_id field is then displayed.
Copy Code
CLOSE DATABASES
SET MULTILOCKS ON  && Must be on for table buffering
SET PATH TO (HOME(2) + 'data\')     && Sets path to database
OPEN DATABASE testdata  && Open testdata database
USE Customer     && Open customer table
= CURSORSETPROP('Buffering', 5, 'customer')  && Enable table buffering

CLEAR
? 'Original cust_id value: '
?? cust_id  && Displays current cust_id value
REPLACE cust_id    WITH '***'  && Changes field contents
? 'New cust_id value: '
?? cust_id  && Displays new cust_id value
= TABLEREVERT(.T.)  && Discard all table changes
? 'Reverted cust_id value: '
?? cust_id  && Displays reverted cust_id value

See Also

Other Resources

CURSORSETPROP( ) Function
CURVAL( ) Function
OLDVAL( ) Function
TABLEUPDATE( ) Function
Functions
Language Reference


TABLEUPDATE( ) Function

Visual FoxPro 9.0 Language Reference
TABLEUPDATE( ) Function
See Also Example

Commits changes made to a buffered row, a buffered table, cursor, or cursor adapter.

TABLEUPDATE( [nRows [, lForce]] [, cTableAlias | nWorkArea] [, cErrorArray] )

Parameters

nRows

Specifies which changes made to the table or cursor should be committed.
Note:
Visual FoxPro enables Optimistic Row Buffering by default for those cursors associated with a CursorAdapter object.

The following table describes the values for nRows.

nRows Description

0

If row or table buffering is enabled, commit only the changes made to the current row in the cursor. (Default)

When working with CursorAdapter objects, Visual FoxPro executes the appropriate command in the InsertCmd, UpdateCmd, or DeleteCmd property for that row only.

1

If table buffering is enabled, commit changes made to all records to the table or cursor.

If row buffering is enabled, commit only changes made to the current record in the table or cursor.

When working with CursorAdapter objects, Visual FoxPro executes the appropriate commands in the InsertCmd, UpdateCmd, and DeleteCmd properties for each affected row.

2

Commit changes made to the table or cursor in the same manner as when nRows = 1. However, an error does not occur when a change cannot be committed. Visual FoxPro continues to process any remaining records in the table or cursor.

If cErrorArray is included, an array containing error information is created when an error occurs.
For compatibility with previous Visual FoxPro applications, the nRows parameter also accepts False (.F.) and True (.T.) instead of 0 and 1 respectively. When specifying 0 or 1 for nRows, the record pointer remains on the record where changes could not be committed. To determine why the changes could not be committed, use the AERROR( ) function. When working with CursorAdapter objects and specifying 1 or 2 for nRows, all changes made to the cursor in the following CursorAdapter events must be committed during the same call to TABLEUPDATE( ) unless an error occurs:
  • BeforeInsert

  • AfterInsert

  • BeforeDelete

  • AfterDelete

  • BeforeUpdate

  • AfterUpdate

Visual FoxPro passes the values of nRows to the CursorAdapter BeforeCursorUpdate event.
lForce

Determines whether Visual FoxPro overwrites changes made to the table or cursor by another user on a network. The following table describes the values for lForce.

lForce Description

False (.F.)

Commits changes to the table or cursor, starting with the first record and continuing towards the end of the table or cursor. (Default)

True (.T.)

Overwrites any changes made to the table or cursor by another user on a network. The WHERE clause uses only key fields.
When working with CursorAdapter objects, Visual FoxPro passes the value of lForce to the following CursorAdapter events:
  • BeforeCursorUpdate

  • BeforeInsert

  • BeforeUpdate

  • BeforeDelete

  • AfterInsert

  • AfterUpdate

  • AfterDelete

cTableAlias

Specifies the alias of the table or cursor in which the changes are committed. If you include a table or cursor alias, you must include the lForce argument.
nWorkArea

Specifies the work area of the table or cursor in which the changes are committed. If you include a work area, you must include the lForce argument.
cErrorArray

Specifies the name of an array created when nRows = 2 and changes to a record cannot be committed. The array contains a single column containing the record numbers of the records for which changes could not be committed. If you include an array name, you must include either a table or cursor alias cTableAlias or a work area number nWorkArea.
Note:
If an error other than a simple commit error occurs while updating records, the first element of cErrorArray will contain –1, and you can then use AERROR( ) to determine the why the changes could not be committed.

Visual FoxPro passes the value of cErrorArray, when it exists, to the CursorAdapter AfterCursorUpdate event.

Return Value

Logical data type. TABLEUPDATE( ) returns True (.T.) if changes to all records are committed.

Otherwise, TABLEUPDATE( ) returns False (.F.) indicating a failure. An ON ERROR routine isn't executed. The AERROR( ) function can be used to retrieve information about the cause of the failure.

Note:
TABLEUPDATE( ) always returns True (.T.) when you are updating data, using Table Buffering, and updating the table or tables in the data source from multiple clients when setting BatchUpdateCount to a value greater than 1. Therefore, avoid setting BatchUpdateCount to a value greater than 1 in these scenarios.

Remarks

TABLEUPDATE( ) cannot commit changes made to a table or cursor that does not have row or table buffering enabled. If you issue TABLEUPDATE( ) and row or table buffering is not enabled, Visual FoxPro generates an error message. However, TABLEUPDATE( ) can still commit changes to a table or cursor that has validation rules. To enable or disable row and table buffering, use CURSORSETPROP( ).

Changes are committed to the table or cursor open in the currently selected work area if TABLEUPDATE( ) is issued without the optional cTableAlias or nWorkArea arguments.

If table buffering is used and multiple records are updated, TABLEUPDATE( ) moves the record pointer to the last record updated.

Note:
Calling TABLEUPDATE( ) for a local table or view that does not use key fields generates a long WHERE clause to find the update row. The default number of fields supported in the WHERE clause is 40. If you receive the error SQL: Statement too long (Error 1812), you should either use a key field for the update or increase the complexity of the WHERE clause with SYS(3055). If you use the SYS(3055) function, increase its value to a number that is eight times the number of fields in the table as shown in the following example:

Copy Code
SYS(3055, 8 * MIN(40, FCOUNT( ))

When performing a batched TABLEUPDATE( ) operation, due to the way that Open Database Connectivity (ODBC) behaves, Visual FoxPro is unable to detect conflicts when no error is generated by the server, yet nothing is updated, for example, no row matches the WHERE clause. This can occur when you use WhereType set to DB_KEYANDUPDATABLE, DB_KEYANDMODIFIED, or DB_KEYANDTIMESTAMP, and another user has changed one of the underlying values in the WHERE clause such that the row is not found by the update statement.

Interaction with CursorAdapter Objects The following behaviors apply when working with CursorAdapter objects:

  • TABLEUPDATE( ) operates only on the cursor associated with the CursorAdapter object.

  • TABLEUPDATE( ) executes commands according to the data source type and those stored in the CursorAdapterInsertCmd, UpdateCmd, or DeleteCmd properties against the current cursor row or rows as appropriate.

  • TABLEUPDATE( ) passes the value of GETFLDSTATE(1) to the following CursorAdapter events of each row affected:

    • BeforeInsert

    • BeforeUpdate

    • BeforeDelete

    For more information about GETFLDSTATE( ), see GETFLDSTATE( ) Function.

  • The successful completion of TABLEUPDATE( ) resets the field states according to usual TABLEUPDATE( )behavior.

  • When table buffering is enabled, you can move away from the current record in the following CursorAdapter events:

    • BeforeInsert

    • AfterInsert

    • BeforeUpdate

    • AfterUpdate

    • BeforeDelete

    • AfterDelete

    You can also modify data in the cursor. This functionality supports scenarios such as retrieving the autoincrement value from the base table and inserting it into the cursor. When this scenario occurs, the CursorAdapter object should automatically return to the record whose changes are about to be committed after the event has occurred and commit the changes.

    In Visual FoxPro 9.0, you cannot issue the TABLEREVERT( ) Function when a TABLEUPDATE( ) is in operation.

    Typically, the CursorAdapter object uses the transaction management functionality provided by the ADO or ODBC API's and Visual FoxPro closes transactions when the TABLEUPDATE( ) function completes successfully. However, if you want to send transaction management commands directly to the backend, you can set the UseTransactions property of the CursorAdaptor object to False (.F.) and the CursorAdapter does not use transactions to send Insert, Update, or Delete commands.

Example

The following example demonstrates how you can use TABLEUPDATE( ) to commit changes made to a buffered table. A table named employees is created, and a SQL INSERT statement inserts the value "Smith" into the cLastName field.

MULTILOCKS is set to ON, which is a requirement for table buffering. CURSORSETPROP( ) is used to set the buffering mode to Optimistic Table Buffering (5).

The original value of the cLastName field (Smith) is displayed, and the cLastName field is modified with REPLACE. The new value of the cLastName field (Jones) is displayed. TABLEUPDATE( )is used to commit changes to the table (TABLEREVERT( ) could be issued instead to discard the changes). The updated value of the cLastName field (Jones) is then displayed.
Copy Code
CLOSE DATABASES
CREATE TABLE employee (cLastName C(10))
SET MULTILOCKS ON  && Must turn on for table buffering.
= CURSORSETPROP('Buffering', 5, 'employee' )  && Enable table buffering.
INSERT INTO employee (cLastName) VALUES ('Smith')

CLEAR
? 'Original cLastName value: '
?? cLastName  && Displays current cLastName value (Smith).

REPLACE cLastName WITH 'Jones'
? 'New cLastName value: '
?? cLastName  && Displays new cLastName value (Jones).

= TABLEUPDATE(.T.)  && Commits changes.
? 'Updated cLastName value: '
?? cLastName  && Displays current cLastName value (Jones).

See Also

Other Resources

Functions
CURSORSETPROP( ) Function
CURVAL( ) Function
OLDVAL( ) Function
TABLEREVERT( ) Function
Cursor Object
Language Reference


TAG( ) Function

Visual FoxPro 9.0 Language Reference
TAG( ) Function
See Also Example

Returns a tag name from an open compound index (.cdx) file or the name of an open single-entry (.idx) index file.

TAG([CDXFileName[, nTagNumber[, nWorkArea | cTableAlias]]])

Parameters

CDXFileName

Specifies the name of the .cdx file to return a tag name from.
nTagNumber

Specifies a number corresponding to the order in which a tag was created in the compound index file. For example, if nTagNumber is 1, TAG( ) returns the name of the first tag created in the compound index file. If nTagNumber is 2, TAG( ) returns the name of the second tag created, and so on. TAG( ) returns the empty string when nTagNumber exceeds the number of tag names. If you omit CDXFileName, TAG( ) returns compound index file tag names and single-entry index file names in a specific order as follows:
  • Names of single-entry index files are returned based on their order in the INDEX clause of USE or SET INDEX. For more information, see USE Command and SET INDEX Command.

  • Tag names from the structural compound index file (if one exists for the table) are returned.

  • Tag names from other open compound index files are returned, again in the order in which the tags were created in the compound index files and in the order in which the compound index files are specified in the INDEX clause for USE or SET INDEX.

nWorkArea| cTableAlias

Returns tag names and index file names from files open in another work area. nWorkArea specifies a work area number and cTableAlias specifies a table alias. By default, tag names and index file names are returned from files in the current work area.

Return Value

Character. TAG( ) returns an index tag name as an uppercase character string.

Remarks

Tags are index entries in compound index (.cdx) files created with the INDEX command. Single-entry index (.idx) files contain only one entry; therefore, TAG( ) returns the file name for .idx files.

Note:
A structural compound index (.cdx) file opens with its table automatically. You can open non-structural .cdx files and .idx index files for a table using the INDEX clause in the USE command or using the SET INDEX command.

Example

The following example closes all other open databases and opens the Customer table in the Visual FoxPro sample TestData database located in the directory, ..\Microsoft Visual FoxPro\Samples\Data. The FOR ... ENDFOR command uses the TAGCOUNT( ) function to create a loop numbering from the first index tag to the total number of index tags in the open structural compound index (.cdx) file. The TAG( ) and file CDX( ) functions retrieve the index tags from the file and displays them using the ? command.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\TestData')
USE Customer

CLEAR
FOR nCount = 1 TO TAGCOUNT()
   ? TAG(CDX(1),nCount)
ENDFOR

For more information, see FOR ... ENDFOR Command, TAGCOUNT( ) Function, CDX( ) Function, and ? | ?? Command.

See Also

Other Resources

CANDIDATE( ) Function
PRIMARY( ) Function
UNIQUE( ) Function
CDX( ) Function
DESCENDING( ) Function
INDEX Command
MDX( ) Function
NDX( ) Function
SYS(14) - Index Expression
ATAGINFO( ) Function
Functions
Language Reference


TAGCOUNT( ) Function

Visual FoxPro 9.0 Language Reference
TAGCOUNT( ) Function
See Also

Returns the number of .cdx compound index file tags and open .idx single-entry index files.

TAGCOUNT([CDXFileName [, nWorkArea | cTableAlias]])

Parameters

CDXFileName

Specifies the name of a compound index file for which TAGCOUNT( ) returns the number of tags. If CDXFileName does not exist for the current table, you must specify the nWorkarea or cTableAlias in which it does exist. If you omit CDXFileName, TAGCOUNT( ) returns the number of tags in all .cdx compound index files and open .idx single-entry index files in the currently selected work area or alias.
nWorkarea

Specifies the work area of the table for which TAGCOUNT( ) returns the number of tags for the .cdx compound index file.
cTableAlias

Specifies the alias of the table for which TAGCOUNT( ) returns the number of tags for the .cdx compound index file.

Return Value

Numeric

Remarks

Included for compatibility with dBASE.

See Also

Other Resources

INDEX Command
TAGNO( ) Function
Functions
Language Reference


TAGNO( ) Function

Visual FoxPro 9.0 Language Reference
TAGNO( ) Function
See Also

Returns the index position for .cdx compound index file tags and open .idx single-entry index files.

TAGNO([IndexName [, CDXFileName [, nExpression | cExpression]]])

Parameters

IndexName

Specifies the name of a .cdx compound index file tag or an open .idx single-entry index file for which TAGNO( ) returns the index position.
CDXFileName

Specifies the name of a .cdx compound index file containing the name of the tag you specify with IndexName.
nExpression

Specifies the work area of the table for which TAGNO( ) returns the index position for .cdx compound index file tags and .idx single-entry index files.
cExpression

Specifies the alias of the table for which TAGNO( ) returns the index position for .cdx compound index file tags and .idx single-entry index files.

Return Value

Numeric

Remarks

TAGNO( ) returns 0 if a master index is not set (the table is in natural record number order) and the optional parameters are omitted.

Included for compatibility with dBASE.

See Also

Other Resources

INDEX Command
TAGCOUNT( ) Function
Functions
Language Reference


TAN( ) Function

Visual FoxPro 9.0 Language Reference
TAN( ) Function
See Also Example

This trigonometric function returns the tangent of an angle.

TAN(nExpression)

Parameters

nExpression

Specifies the angle in radians for which TAN( ) returns the tangent. To convert an angle from degrees to radians, use DTOR( ). The number of decimal places returned by TAN( ) can be specified with SET DECIMALS.

Return Value

Numeric

Example

Copy Code
CLEAR
? TAN(0)  && Displays 0.00
? TAN(PI( )/4)  && Displays 1.00
? TAN(PI( )*3/4)  && Displays -1.00

See Also

Other Resources

COS( ) Function
DTOR( ) Function
RTOD( ) Function
SET DECIMALS Command
SIN( ) Function
Functions
Language Reference


TARGET( ) Function

Visual FoxPro 9.0 Language Reference
TARGET( ) Function
See Also Example

Returns the alias of a table that is the target for a relation as specified in the INTO clause of SET RELATION.

TARGET(nRelationshipNumber [, nWorkArea | cTableAlias])

Parameters

nRelationshipNumber

Specifies the number of a relationship. Include a number from 1 to the number of relationships out of the specified work area. The aliases of the target tables are returned (in no specific order) until nRelationshipNumber is greater than the number of relationships. When nRelationshipNumber is greater than the number of relationships, the empty string is returned.
nWorkArea| cTableAlias

Returns the alias of the target table in another work area. nWorkArea specifies a work area number and cTableAlias specifies a table alias. By default, the alias of the target table from the current work area is returned if you don't specify the work area or alias.

Return Value

Character

Example

In the following example, a relation is set on the field order_id from orders into customer. The TARGET( ) function is then used to return the alias of the target table.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE orders IN 0 ORDER order_id
USE customer IN 0 ORDER cust_id
SELECT orders
SET RELATION TO cust_id INTO customer
? TARGET(1)  && Displays customer
? TARGET(2)  && Empty string

See Also

Other Resources

RELATION( ) Function
SET RELATION Command
SELECT Command
Functions
Language Reference


TEXTMERGE( ) Function

Visual FoxPro 9.0 Language Reference
TEXTMERGE( ) Function
See Also Example

Provides evaluation of a character expression.

TEXTMERGE(cExpression [, lRecursive [, cLeftDelim [, cRightDelim]]])

Parameters

cExpression

Specifies the string expression to be evaluated.
lRecursive

Specifies whether to repeatedly iterate through all levels of delimiters in cExpression, evaluating until no text merge delimiters remain.
cLeftDelim

Specifies the left delimiter to use for the text merge search. cLeftDelim is limited to two characters.
cRightDelim

Specifies the right delimiter to use for the text merge search. cRightDelim is limited to two characters.

Return Value

Character string. Represents the value of cExpression, the merged text.

Remarks

The cLeftDelim and cRightDelim parameters temporarily override any SET TEXTMERGE DELIMITERS values.

The TEXTMERGE( ) function responds to current settings of SET TEXTMERGE SHOW | NOSHOW.

Example

The following example creates a text string, then outputs the TEXTMERGE of that function.
Copy Code
SET TEXTMERGE OFF
TEXT to myvar noshow &&textm
   this is a test   <<datetime()>>
   <<program(-1)>>
   <<myvar>>
   textmerge(myvar) (this line is literal)
   <<doit(myvar)>>   (cause recursion
   END of orig text
endtext
?myvar
?"Now starting textmerge"
?textmerge(myvar)

PROCEDURE doit(myvar)
*  r=i   && cause an error
   if program(-1) > 3
     return "THEEND*********"
   endif
   return textmerge(myvar)

See Also

Other Resources

EVALUATE( ) Function
SET DELIMITERS Command
SET TEXTMERGE Command
SET TEXTMERGE DELIMITERS Command
Creating Character Expressions
TEXT ... ENDTEXT Command
Functions
Language Reference


TIME( ) Function

Visual FoxPro 9.0 Language Reference
TIME( ) Function
See Also

Returns the current system time in 24-hour, eight-character string (hh:mm:ss) format.

TIME([nExpression])

Parameters

nExpression

The time returned includes hundredths of a second if nExpression is included. The numeric expression nExpression can be any value. However, the actual maximum resolution is about 1/18 second. Use SECONDS( ) for greater resolution.

Return Value

Character

See Also

Other Resources

CTOT( ) Function
DATE( ) Function
DATETIME( ) Function
DTOT( ) Function
HOUR( ) Function
SEC( ) Function
SECONDS( ) Function
SET SECONDS Command
SYS(2) - Seconds Since Midnight
Functions
Language Reference


TRANSFORM( ) Function

Visual FoxPro 9.0 Language Reference
TRANSFORM( ) Function
See Also Example

Returns a character string from an expression in a format determined by a format code.

Note:
Using TRANSFORM( ) with a large negative number that contains a decimal might result in numeric overflow when that number is passed in as a memory variable. You should use the STR( ) function instead with such numbers.

TRANSFORM(eExpression, [cFormatCodes])

Parameters

eExpression

Specifies the expression to format.
cFormatCodes

Specifies one or more format codes that determine how to format the expression.
Note:
The following table lists the available format codes for cFormatCodes.

cFormatCodes Description

@B

Left-justifies Numeric data within the display region.

@C

Appends a CR to positive Currency or Numeric values to indicate a credit.

@D

Converts Date and DateTime values to the current SET DATE format.

@E

Converts Date and DateTime values to a BRITISH date format.

@L

Pads numeric data with leading zeroes.

@R

The transformation uses a format mask. The mask characters are not stored to the transformed value. Use only with character or numeric data. Mask characters include:

  • 9 or # Represents a character or number.

  • ! Converts lower-case letters to uppercase letters.

Note:
Visual FoxPro does not display specified mask characters that exceed the converted string length of the passed expression.

@T

Trims leading and trailing spaces from character values.

@X

Appends DB to negative currency or numeric values to indicate a debit.

@YL

Use Long Date system setting.

@YS

Use Short Date system setting.

@Z

If 0, converts currency or numeric values to spaces.

@(

Encloses negative currency or numeric values in parentheses.

@^

Converts currency or numeric values to scientific notation.

@0

Converts numeric or currency values to their hexadecimal equivalents. The numeric or currency value must be positive and less than 4,294,967,296.

@!

Converts an entire character string to uppercase.

@$

Adds the current currency symbol specified by SETCURRENCY to currency and numeric values. By default, the symbol is placed immediately before or after the value. However, the currency symbol and its placement (specified with SET CURRENCY), the separator character (specified with SET SEPARATOR) and the decimal character (specified with SET POINT) can all be changed.

X

Specifies the width of character values. For example, if cFormatCodes is 'XX', 2 characters are returned.

Y

Converts logical True (.T.) and False (.F.) values to Y and N, respectively.

!

Converts a lowercase character to uppercase in the corresponding position in a character string.

.

Specifies the decimal point position in currency and numeric values.

,

Separates digits to the left of the decimal point in currency and numeric values.

9

Specifies width of numeric values.

For example, if cFormatCodes is '999.99', the numeric characters are formatted with three characters to the left of the decimal point, and two characters to the right.

Note:
When specifying cFormatCodes for numeric values, the format code must be at least the size of the value you want to display.

The following example shows the results when the format code is missing, less than, and equal to the size of the value you want to display.

Copy Code
CREATE CURSOR myCursor (col1 n(5,2))
INSERT INTO myCursor VALUES (-555.5)
* No format code and returns **.**
? TRANSFORM(myCursor.col1 )
* A format code 1 less than value returns ***.**
? TRANSFORM(myCursor.col1,'999.99' )
* A format code same size as value returns -556.00
? TRANSFORM(myCursor.col1,'9999.99' )

When the expression value is longer than the width of the numeric field, Visual FoxPro forces the value to fit by performing the following steps:

  • Truncate decimal places and round the remaining decimal portion of the field.

  • If the value does not fit, store the field contents using scientific notation.

  • If the value still does not fit, replace the field contents with asterisks.

For more information about format codes, see InputMask Property and Format Property.

If you omit cFormatCodes, Visual FoxPro performs a default transformation on eExpression. The following table describes the transformation performed for each data type eExpression can assume.

Data type Transformation description

Blob

Outputs character string representation of the binary value without the hexadecimal prefix. For example, the following line of code outputs the character string "FEOAF2":

Copy Code
TRANSFORM(0hFE0AF2)

For binary values, TRANSFORM( ) disregards format codes except for those that restrict width. For example, the following lines of code output "FE0A":

Copy Code
TRANSFORM(0hFE0AF2, "XXXX")
TRANSFORM(0hFE0AF2, "9999")
TRANSFORM(0hFE0AF2, "####")

For those format codes that restrict width, the maximum output length is 255 characters.

Character

Performs no transformation.

Currency

Transformation is determined by the settings specified in the Regional tab of the Options dialog box.

Date

Performs a DTOC( ) transformation on the date.

DateTime

Performs a TTOC( ) transformation on the date time.

General

Returns "Gen" if the General field contains an object or "gen" if the General field does not contain an object.

Logical

Transforms logical True (.T.) and False (.F.) values to the character strings ".T." and ".F." respectively.

Memo

Performs no transformation.

Numeric (includes Double, Float, or Integer data types)

Removes trailing zeros from the decimal portion of a numeric value when all the numbers following the decimal point are zeros.

If the numeric value is a whole number, a decimal point is not included in the transformed value, for example, 4.0 is transformed to 4.

If the numeric value is less than one but greater than negative one, zero is included before the decimal point, for example, .4 is transformed to 0.4.

Object

Returns the character string "(Object)".

Varbinary

Outputs character string representation of the binary value without the hexadecimal prefix. For example, the following line of code outputs the character string "FEOAF2":

Copy Code
TRANSFORM(0hFE0AF2)

For binary values, TRANSFORM( ) disregards format codes except for those that restrict width. For example, the following lines of code output "FE0A":

Copy Code
TRANSFORM(0hFE0AF2, "XXXX")
TRANSFORM(0hFE0AF2, "9999")
TRANSFORM(0hFE0AF2, "####")

Return Value

Character data type. TRANSFORM( ) returns character string from an expression in a format determined by a format code.

Example

Copy Code
STORE 12.34 TO gnPrice
CLEAR
? TRANSFORM(gnPrice, '$$$$.99')  && Displays $12.34
? TRANSFORM(_SCREEN)   && Displays (Object)

See Also

Other Resources

DTOC( ) Function
TTOC( ) Function
InputMask Property
Functions
Language Reference


TRIM( ) Function

Visual FoxPro 9.0 Language Reference
TRIM( ) Function
See Also Example

Removes all trailing spaces or parsing characters from the specified character expression, or all trailing zero (0) bytes from the specified binary expression.

TRIM(cExpression [, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

Parameters

cExpression

Specifies an expression of Character or Varbinary type to remove all trailing spaces or 0 bytes from, respectively.
nFlags

Specifies if trimming is case-sensitive when one or more parse characters (cParseChar, cParseChar2, … are included. Trimming is case-sensitive if nFlags is zero or is omitted. Trimming is case-insensitive if nFlags 1.
cParseChar [, cParseChar2 [, ...]]

Specifies one or more character strings that are trimmed from the end of cExpression. If cParseChar isn't included, then trailing spaces or 0 bytes are removed from Expression. Note The maximum number of strings permitted in cParseChar is 23.

Return Value

Character or Varbinary. TRIM( ) returns the specified expression without trailing spaces or parsing characters, or 0 bytes.

Remarks

TRIM( ) is identical to RTRIM( ).

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table
CLEAR
? 'The contact for '+ TRIM(company) + ' is ' + contact

See Also

Other Resources

ALLTRIM( ) Function
LTRIM( ) Function
RTRIM( ) Function
Functions
Language Reference


TTOC( ) Function

Visual FoxPro 9.0 Language Reference
TTOC( ) Function
See Also Example

Converts a DateTime expression to a Character value with the specified format.

TTOC(tExpression [, 1 | 2 | 3])

Parameters

tExpression

Specifies a DateTime expression to convert into a character string. If tExpression contains only a time, Visual FoxPro adds the default date of 12/30/1899 to tExpression. If tExpression contains only a date, Visual FoxPro adds a default time of 12:00:00 AM (if SET HOURS is 12) or 00:00:00 (if SET HOURS is 24) to tExpression to produce a valid DateTime value.
1

Returns tExpression as a character string in a format suitable for indexing. The character string returned has a 14-character format, yyyymmddhhmmss, that is not affected by the SET CENTURY, the SET HOURS, or SET SECONDS commands. For more information, see SET CENTURY, SET HOURS, and SET SECONDS.
2

Returns tExpression as a character string containing only the time portion of tExpression. To control whether to include the seconds of the time portion in the character string, set the SET SECONDS and SET DATE commands. The SET HOURS command determines if AM or PM is appended to the time portion returned. For more information, see SET DATE and SET HOURS.
Note:
If SET DATE is set to LONG or SHORT, the format of the time setting in the Windows Control Panel determines the format of the character string.

3

Returns tExpression as a character string with the XML DateTime format. The character string returned has a 19-character yyyy-mm-ddThh:mm:ss format that is not affected by the settings of the SET CENTURY, SET HOURS, or SET SECONDS commands.

Return Value

Character. TTOC( ) returns a DateTime expression as a character string.

Note:
When passing the value 1 or 3 as the second parameter, the character string returned does not include the AM or PM designations to indicate times before or after noon, respectively. Instead, the string uses a 24-hour clock, also known as military time. For example, the time 18:30:00 is equivalent to 06:30:00 PM.

Remarks

If an invalid value is passed as the second parameter, TTOC( ) handles the invalid value as if it was a value of 1.

Example

The following example converts a DateTime value to a Character value. The STORE command stores the results of the DATETIME( ) function, which returns the current date and time as a DateTime value, to a variable named gtDateTime. The ? command displays text and the results of the TYPE( ) function, which returns the letter T as the type of the gtDateTime variable. The TTOC( ) function converts gtDateTime to a character string, and the TYPE( ) functions returns the letter T as the current type of gtDateTime.
Copy Code
STORE DATETIME( ) TO gtDateTime
? "gtDateTime has type: "+TYPE('gtDateTime')
gtDateTime = TTOC(gtDateTime)
? "gtDateTime is now type: "+TYPE('gtDateTime')

See Also

Reference

SET HOURS Command
SET DATE Command

Other Resources

DateTime Data Type
Character Data Type
DATE( ) Function
DATETIME( ) Function
HOUR( ) Function
MINUTE( ) Function
SEC( ) Function
SECONDS( ) Function
TIME( ) Function
TTOD( ) Function
Functions
Language Reference


TTOD( ) Function

Visual FoxPro 9.0 Language Reference
TTOD( ) Function
See Also Example

Returns a Date value from a DateTime expression.

TTOD(tExpression)

Parameters

tExpression

Specifies a date and time expression from which TTOD( ) returns a Date value. tExpression must evaluate to a valid DateTime. If tExpression contains only a time, Visual FoxPro adds the default date of 12/30/1899 to tExpression and returns this default date.

Return Value

Date

Example

The following example creates a Datetime type variable named gtDtime. TYPE( ) displays T, indicating the variable is a Datetime type. TTOD( ) is used to convert the variable to a date type, and TYPE( ) now displays D, indicating the variable is a date type after the conversion.
Copy Code
STORE DATETIME( ) TO gtDtime  && Creates a Datetime type memory variable
CLEAR
? "gtDtime is type: "
?? TYPE('gtDtime')  && Displays T, Datetime type value

gtDtime = TTOD(gtDtime)     &&  Converts gtDtime to a date value
? "gtDtime is now type: "
?? TYPE('gtDtime')  && Displays D, character type value

See Also

Other Resources

DATE( ) Function
DATETIME( ) Function
HOUR( ) Function
MINUTE( ) Function
SEC( ) Function
SECONDS( ) Function
SET CENTURY Command
SET SECONDS Command
TIME( ) Function
TTOC( ) Function
Functions
Language Reference


TXNLEVEL( ) Function

Visual FoxPro 9.0 Language Reference
TXNLEVEL( ) Function
See Also Example

Returns a numeric value indicating the current transaction level.

TXNLEVEL( )

Return Value

Numeric

Remarks

Use BEGIN TRANSACTION to create a transaction. Transactions are nested by issuing BEGIN TRANSACTION when another transaction is in progress. Transactions can be nested in this manner to five levels. Use TXNLEVEL( ) to determine the current transaction level.

TXNLEVEL( ) returns a value from 0 to 5. TXNLEVEL( ) returns 0 if a transaction is not in progress.

Example

In the following example, the customer table in the testdata database is opened. BEGIN TRANSACTION is issued to start a transaction, and TXNLEVEL( ) is used to display the transaction level (1). BEGIN TRANSACTION is issued again to start a nested transaction, and TXNLEVEL( ) displays 2 for the current transaction level.
Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer     && Open customer table
CLEAR

BEGIN TRANSACTION
   tLevel = ALLTRIM(STR(TXNLEVEL()))
   =MESSAGEBOX("Current Transaction: " + tLevel, 0, "Trasaction Level")
   BEGIN TRANSACTION
      tLevel = ALLTRIM(STR(TXNLEVEL()))
      =MESSAGEBOX("Current Transaction: " + tLevel, 0, ;
         "Trasaction Level")
   END TRANSACTION
END TRANSACTION

See Also

Other Resources

BEGIN TRANSACTION Command
END TRANSACTION Command
ROLLBACK Command
Functions
Language Reference


TXTWIDTH( ) Function

Visual FoxPro 9.0 Language Reference
TXTWIDTH( ) Function
See Also

Returns the length of a character expression with respect to the average character width for a font.

TXTWIDTH(cExpression [, cFontName, nFontSize [, cFontStyle]])

Parameters

cExpression

Specifies a character expression for which TXTWIDTH( ) returns the length. If you include only cExpression, the length of the character expression is returned for the current font for the main Visual FoxPro window or the active output window. A non-proportional font always returns a value equal to the number of characters in cExpression. Include the optional arguments cFontName, nFontSize and cFontStyle to determine the length of a character expression with a specific font, font point size, or font style.
cFontName

Specifies the name of the font. Include cFontName to return the length of a character expression with a specific font.
nFontSize

Specifies a number that corresponds to the point size of the font. Include nFontSize to return the length of a character expression with a specific point size.
cFontStyle

Specifies a special font style for the character expression. cFontStyle is a font style code specified by a character or a set of characters. The Normal font style is used if cFontStyle isn't included. Here are the characters for each font style:

Character Font Style

B

Bold

I

Italic

N

Normal

O

Outline

Q

Opaque

S

Shadow

-

Strikeout

T

Transparent

U

Underline
You can include more than one character to specify a combination of font styles. For example, BI specifies a Bold Italic font style. The following command displays a message in a Courier normal 24-point font, centered horizontally in the main Visual FoxPro window:
Copy Code
@ 25,(WCOLS( )-TXTWIDTH('Hello!','Courier ',24)* ;
   FONTMETRIC(6,'Courier ',24)/FONTMETRIC(6))/2  ;
   SAY 'Hello!' FONT 'Courier ',24

Return Value

Numeric

Remarks

TXTWIDTH( ) returns the number of characters a character expression cExpression occupies, based on the average character width of a specified font (the average character width of a font is called a foxel). Use FONTMETRIC(6) to determine the average character width of a font.

If you don't include a font in TXTWIDTH( ), the value returned by TXTWIDTH( ) is determined by the current font for the main Visual FoxPro window, as long as output is directed to the main Visual FoxPro window when TXTWIDTH( ) is issued. If output is being directed to a user-defined window, the value returned is determined by the window's current font.

See Also

Other Resources

FONTMETRIC( ) Function
GETFONT( ) Function
LEN( ) Function
SYSMETRIC( ) Function
WFONT( ) Function
Functions
Language Reference


TYPE( ) Function

Visual FoxPro 9.0 Language Reference
TYPE( ) Function
See Also Example

Returns the data type of an expression.

Note:
VARTYPE( ) is similar to the TYPE( ) function, but VARTYPE( ) is faster and does not require quotation marks ("") to enclose the specified expression.

TYPE(cExpression [, 1])

Parameters

cExpression

Specifies the expression, which can be a variable, array, field, memo field, or other expression, for which the data type is returned.
Note:
You must pass the expression as a character string by enclosing the expression with quotation marks (""). If you do not enclose the expression with quotation marks, TYPE( ) evaluates the contents of the expression.

1

Include the optional parameter 1 to determine if cExpression is an array or a Collection Class. COM objects are not supported with the 1 parameter.

Return Value

Character. TYPE( ) returns a character representing the data type of the specified expression.

The following table lists the character values that TYPE( ) returns and their corresponding data types.

Return value Data type

A

Array (only returned when the optional 1 parameter is included)

C

Character, Varchar, Varchar (Binary)

If the optional 1 parameter is included, a return value of C indicates that the data type is a collection.

D

Date

G

General

L

Logical

M

Memo

N

Numeric, Float, Double, or Integer

O

Object

Q

Blob, Varbinary

S

Screen

Note:
The Screen type is created when using the SAVE SCREEN command. For more information, see SAVE SCREEN Command.

T

DateTime

U

Undefined type of expression or cannot evaluate expression.

If the optional 1 parameter is included, a return value of U indicates that the data type is not an array.

Y

Currency

Remarks

If you pass an array as a parameter to TYPE( ), the data type returned corresponds to the first element in the array. If you want to check the data type for a specific array element, you must specify that element in the parameter. For example:

Copy Code
? TYPE("myarray[3]")

You can also use the TYPE( ) function to check if a memory variable is an array. For example:

Copy Code
? TYPE("myarray[1]")#"U"
Note:
TYPE( ) cannot be used to evaluate UDFs (user-defined functions).

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Opens Customer table
nTest = 1.01
cTest = "String"

CLEAR
? TYPE('customer.contact')  && Displays C
? TYPE('(12 * 3) + 4')  && Displays N
? TYPE('DATE( )')  && Displays D
? TYPE('.F. OR .T.')  && Displays L
? TYPE('ANSWER=42')  && Displays U
? TYPE('$19.99')  && Displays Y
? TYPE('nTest')  && Displays N
? TYPE('cTest')  && Displays C

See Also

Other Resources

EVALUATE( ) Function
VARTYPE( ) Function
Data and Field Types
Functions
Language Reference


UNBINDEVENTS( ) Function

Visual FoxPro 9.0 Language Reference
UNBINDEVENTS( ) Function
See Also Example

You can use UNBINDEVENTS( ) to unbind, or detach, an event that was originally bound to a Visual FoxPro object using BINDEVENT( ). To detach events from Component Object Model (COM) objects, use the EVENTHANDLER( ) function. There are three versions of the syntax.

UNBINDEVENTS(oEventSource, cEvent, oEventHandler, cDelegate)
UNBINDEVENTS(oEventObject)
UNBINDEVENTS(hWnd [, nMessage])

Parameters

oEventSource

Specifies the event source, which must be a valid Visual FoxPro object.
oEventObject

Specifies an object reference, which can be used as the event source or event handler.
cEvent

Specifies the name of the event, method, or property you want to unbind.
oEventHandler

Specifies the object that is handling the event.
cDelegate

Specifies the delegate method handling the event for oEventHandler.
hWnd

Specifies the integer handle of the window for which events are unbound. If hWnd is 0, all hWnds are unbound. If the nMessage parameter isn't included, then all Windows message bindings for the window handle hWnd are unbound.
nMessage

Specifies a valid Windows message (Win Msg) that is unbound. See MSDN (the Microsoft Developer Network) for information about Windows messages.

Return Value

Numeric data type. UNBINDEVENTS( ) returns the number of events that are unbound if unbinding succeeds. UNBINDEVENTS( ) returns a value of 0 if no events exist for unbinding. Visual FoxPro generates an error if UNBINDEVENTS( ) fails to unbind events that are available for unbinding.

Remarks

The following table describes the ways you can use UNBINDEVENTS( ).

Syntax | Action
UNBINDEVENTS(oEventSource, cEvent, oEventHandler, cDelegate) | Unbinds a specific event from an event handler.
UNBINDEVENTS(oEventObject) | Unbinds all events associated with this object. This includes events that are bound to it as an event source and its delegate methods that serve as event handlers.
UNBINDEVENTS(hWnd [, nMessage]) | Unbinds all or specific Windows Message (Win Msg) events.

If an event is occurring, and UNBINDEVENTS( ) or the delegate method handling the event is called, the event and its delegate method finish running before UNBINDEVENTS( ) unbinds the event.

You can call the AEVENTS( ) function retrieve information about all the events and delegate methods attached to a particular object.

Example

The following example shows how to undo a BINDEVENTS( ) call that keeps the Class Browser positioned to the right side of the Visual FoxPro desktop, regardless of how the desktop is resized. UNBINDEVENTS( ) detaches the Resize event of the _SCREEN system variable from the object, oHandler:
Copy Code
PUBLIC oHandler
oHandler=NEWOBJECT("myhandler")
DO (_browser)
BINDEVENT(_SCREEN,"Resize",oHandler,"myresize")
UNBINDEVENTS(_SCREEN,"Resize",oHandler,"myresize")

DEFINE CLASS myhandler AS Session
   PROCEDURE myresize
   _obrowser.left = _SCREEN.Width - _obrowser.width
   RETURN
ENDDEFINE

See Also

Reference

SYS(2325) - WCLIENTWINDOW from Visual FoxPro WHANDLE
SYS(2326) - WHANDLE from a Window's hWnd
SYS(2327) - Window's hWnd from Visual FoxPro WHANDLE

Other Resources

Functions
Event Binding for Visual FoxPro Objects
AEVENTS( ) Function
BINDEVENT( ) Function
EVENTHANDLER( ) Function
RAISEEVENT( ) Function


UNIQUE( ) Function

Visual FoxPro 9.0 Language Reference
UNIQUE( ) Function
See Also

Included for compatibility with dBASE.

See Also

Other Resources

Language Reference


UPPER( ) Function

Visual FoxPro 9.0 Language Reference
UPPER( ) Function
See Also Example

Returns the specified character expression in uppercase.

UPPER(cExpression)

Parameters

cExpression

Specifies the character expression UPPER( ) converts to uppercase.

Return Value

Character

Remarks

Each lowercase letter (a – z) in the character expression is converted to uppercase (A – Z) in the returned string. This is true for high-ASCII characters as well, even if the current font does not display them as lowercase accented characters.

Example

Copy Code
CLEAR
? UPPER('abcdefgh')  && Displays ABCDEFGH

See Also

Reference

PROPER( ) Function

Other Resources

ISLOWER( ) Function
ISUPPER( ) Function
LOWER( ) Function
Functions
Language Reference


USED( ) Function

Visual FoxPro 9.0 Language Reference
USED( ) Function
See Also Example

Determines if an alias is in use or a table is open in a specific work area.

USED([nWorkArea | cTableAlias])

Parameters

nWorkArea| cTableAlias

Specifies a table's work area or alias. USED( ) returns a logical true (.T.) if a table is opened in the work area you specify with nWorkArea; otherwise a logical false (.F.) is returned. USED( ) returns a logical true (.T.) if an alias is in use with the alias you specify with cTableAlias; otherwise false (.F.) is returned. If you omit nWorkArea and cTableAlias, USED( ) returns a logical true (.T.) if a table is open in the currently selected work; otherwise false (.F.) is returned.

Return Value

Logical

Remarks

USED( ) can determine if an alias is in use or if a table is open in a specific work area.

Example

Copy Code
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
SELECT A
USE customer  && Opens Customer table
SELECT B
USE orders  && Opens Orders table
SELECT C
USE employee  && Opens Employee table
? USED('A')  && Displays .T.
? USED('B')  && Displays .T.
? USED(4)  && Displays .F.

See Also

Other Resources

ALIAS( ) Function
SELECT( ) Function
AUSED( ) Function
Functions
Language Reference


VAL( ) Function

Visual FoxPro 9.0 Language Reference
VAL( ) Function
See Also Example

Returns a numeric or currency value from a character expression composed of numbers. You can use VAL( ) to convert the character strings returned by the Visual FoxPro SYS( ) functions to numeric values.

VAL(cExpression)

Parameters

cExpression

Specifies a character expression composed of up to 16 numbers. Rounding occurs if more than 16 numbers are included in cExpression. If the first character of cExpression is a dollar sign ($),VAL( ) returns a currency value. In all other situations VAL( ) returns a numeric value.

Return Value

Numeric or Currency data type. VAL( ) returns the numbers in the character expression from left to right until a non-numeric character is encountered. Leading blanks are ignored. VAL( ) returns 0 if the first character of the character expression is not a number, a dollar sign ($), a plus sign (+), or minus sign (-). You can control the result of VAL( ) by issuing the SET DECIMALS command before using the VAL( ) function.

Example

Copy Code
CLEAR
STORE '12' TO A
STORE '13' TO B
? VAL(A) + VAL(B)  && Displays 25.00
STORE '1.25E3' TO C
? 2 * VAL(C)  && Displays 2500.00

See Also

Other Resources

SET DECIMALS Command
STR( ) Function
SYS( ) Functions Overview
Functions
Language Reference


VARTYPE( ) Function

Visual FoxPro 9.0 Language Reference
VARTYPE( ) Function
See Also

Returns the data type of an expression.

Note:
VARTYPE( ) is similar to the TYPE( ) function, but VARTYPE( ) is faster and does not require quotation marks to enclose the expression for which the data type is returned.

VARTYPE(eExpression [, lNullDataType])

Parameters

eExpression

Specifies the expression for which the data type is returned. VARTYPE( ) returns a single character indicating the data type of the expression. The following table lists the characters that VARTYPE( ) returns for each data type.

Return value Data type

C

Character, Memo, Varchar, Varchar (Binary)

D

Date

G

General

L

Logical

N

Numeric, Float, Double, or Integer

O

Object

Q

Blob, Varbinary

T

DateTime

U

Unknown or variable does not exist

X

Null

Y

Currency

Note:
If eExpression is an array, the first element in the array is evaluated.

lNullDataType

Specifies whether VARTYPE( ) returns the data type when eExpression contains the null value. The following table lists the values of lNullDataType.

lNullDataType Description

True (.T.)

Return data type for eExpression.

False (.F.) or omitted

Return 'X' to indicate eExpression contains a null value.

Return Value

Character. VARTYPE( ) returns a character representing the data type of the specified expression.

See Also

Other Resources

EVALUATE( ) Function
TYPE( ) Function
Data Types
Functions
Language Reference


VERSION( ) Function

Visual FoxPro 9.0 Language Reference
VERSION( ) Function
See Also Example

Returns information about the Visual FoxPro version you are using.

VERSION(nExpression)

Parameters

nExpression

Specifies that VERSION( ) returns additional information about Visual FoxPro. If you omit nExpression, VERSION( ) returns the Visual FoxPro version number. The following table lists values for nExpression and the additional Visual FoxPro information returned.

nExpression Additional Visual FoxPro information returned

1

Visual FoxPro date and serial number.

2

Visual FoxPro version type:

0 - Run time version

1 - Standard Edition (earlier versions)

2 - Professional Edition (earlier versions)

3

Localized Visual FoxPro language. The following two character values indicate the language for which Visual FoxPro is localized:

00 - English

07 - Russian

33 - French

34 - Spanish

39 - Czech

48 - German

55 - Korean

86 - Simplified Chinese

88 - Traditional Chinese

4

The Visual FoxPro version number in a standard, easily parsed format.

For versions prior to Visual FoxPro 8.0, the standard format is "MM.mm.0000.DDDD" where MM is the major release number, mm is the incremental minor revision number, 0000 is a fixed placeholder, and DDDD is the four digit product date for the day the version was created.

For Visual FoxPro 8.0, the formula for calculating the product date, DDDD, is 8000 + number of days since the beginning of 1998. For example, 8397 corresponds to February 1, 1999.

For Visual FoxPro 9.0, the formula for calculating the product date, DDDD, is number of months since January 1, 2003 concatenated with the day of the current month. For example, 2215 corresponds to October 15, 2004.

The format for Visual FoxPro 8.0 and 9.0 is "MM.mm.0000.NNNN" where MM is the major release number, mm is the incremental minor revision number, 0000 is a fixed placeholder, and NNNN is the build number.

5

The Visual FoxPro release version in the format Mmm where M is the major release number and mm is the incremental minor revision number. For example, VERSION(5) returns 700 in Visual FoxPro 7.0.

Return Value

Character, Numeric

Remarks

Use VERSION( ) to conditionally execute version-specific portions of code.

VERSION( ), VERSION(1), VERSION(3), and VERSION(4) return character strings; VERSION(2) and VERSION(5) return numeric values.

Example

Copy Code
CLEAR
? VERSION( )
? VERSION(1)
? VERSION(2)
? VERSION(3)
? VERSION(4)
? VERSION(5)

See Also

Other Resources

GETCP( ) Function
GETENV( ) Function
OS( ) Function
AGETFILEVERSION Command
Functions
Language Reference


WBORDER( ) Function

Visual FoxPro 9.0 Language Reference
WBORDER( ) Function
See Also

Determines whether the active or specified window has a border.

WBORDER([WindowName])

Parameters

WindowName

Specifies the name of the window for which WBORDER( ) returns a logical value. WBORDER( ) returns a logical value for the active output window if you omit a window name.

Return Value

Logical

Remarks

WBORDER( ) returns true (.T.) if the specified window has a border; otherwise WBORDER( ) returns false (.F.). By default, windows have borders. Include the NONE clause in DEFINE WINDOW to create a window without a border.

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
SET BORDER Command
Functions
Language Reference


WCHILD( ) Function

Visual FoxPro 9.0 Language Reference
WCHILD( ) Function
See Also

Returns either the number of child windows in a parent window or the names of the child windows in the order in which they are stacked in the parent window.

WCHILD([WindowName] [nChildWindow])

Parameters

WindowName

Specifies a window other than the active output window for which WCHILD( ) returns the number of child windows. The number of child windows in the specified window is returned if you include just a window name without the numeric expression nChildWindow. If you include both WindowName and nChildWindow, WCHILD( ) returns the names of the child windows in the specified window. If you include both WindowName and nChildWindow, separate WindowName and nChildWindow with a comma. You can also include the empty string in WindowName to specify the main Visual FoxPro window.
nChildWindow

Specifies a numeric expression included to return the names of child windows in the active output window when you omit WindowName. The numeric expression nChildWindow can be 0 or any positive value. The name of the child window at the bottom of the stack of child windows in the current output window is returned if nChildWindow is 0. If nChildWindow is a positive number, WCHILD( ) returns the name of the next child window in the window stack. The name of next child window in the stack is returned if you issue WCHILD( ) again with a positive number, and so on. The empty string is returned if WCHILD( ) is called more times than the number of child windows in the parent window. For more information on window stacking, see ACTIVATE WINDOW.
Note:
In Visual FoxPro for Windows, if the main Visual FoxPro window is active, all windows are children of the main Visual FoxPro window. In Visual FoxPro, toolbars that are not docked in the border of the main Visual FoxPro window are children of the main Visual FoxPro window. Issuing a series of WCHILD() functions with positive numbers returns the names of the active windows and toolbars.

If you include both WindowName and nChildWindow, separate WindowName and nChildWindow with a comma.

Return Value

Character or Numeric

Remarks

You can create a window (the parent window) and place other windows (child windows) inside. Including the IN or IN WINDOW clause in DEFINE WINDOW creates a child window inside the parent window. A child window created and activated inside a parent window cannot be moved outside the parent window. If the parent window is moved, the child window moves with it.

The number of child windows in the active output window is returned if you issue WCHILD( ) without any arguments.

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
WPARENT( ) Function
Functions
Language Reference


WCOLS( ) Function

Visual FoxPro 9.0 Language Reference
WCOLS( ) Function
See Also Example

Returns the number of columns within the active or specified window.

WCOLS([WindowName])

Parameters

WindowName

Specifies the window for which WCOLS( ) returns the number of columns. In Visual FoxPro, you can also specify the name of a toolbar. If you do not specify a window, the number of columns in the active output window is returned. If no window is active, WCOLS( ) returns the number of columns in the main Visual FoxPro window. You can specify the name of a system window (the Command window, the Data Session window, a Browse window, and so on) in WCOLS( ) if the system window has been activated and is visible or hidden. In Visual FoxPro, you can specify the name of a toolbar (the Standard toolbar, the Color Palette toolbar, and so on) in WCOLS( ) if the toolbar has been activated and is visible or hidden. If you specify the name of a system window or toolbar that has not been activated, Visual FoxPro generates an error message. The Debug window is an exception. Once the Debug window has been opened, its name can be included in WCOLS( ) if it is visible, hidden or closed. You can also include the empty string as the window name to return the number of columns in the main Visual FoxPro window. The empty string can be used to specify the main Visual FoxPro window in functions such as WLCOL( ), WLROW( ), and WROWS( ), which return window locations or sizes.

Return Value

Numeric

Remarks

In Visual FoxPro, the value returned by WCOLS( ) depends on the font specified for the window. Many fonts can be displayed in a wide variety of sizes, and some are proportionally spaced. A column corresponds to the average width of a letter in the current font. For more information, see the Fonts Overview topic.

Example

The following example centers a short output message in the last row of a window of unknown size.
Copy Code
CLEAR
DO SendMesg WITH 'Message', WCOLS( ), WROWS( ) –1

*** SendMesg ***

PROCEDURE SendMesg
PARAMETERS gcMsg, gnCol, gnRow
STORE (gnCol – LEN(gcMsg))/2 TO gnCol
@ gnRow, gnCol SAY gcMsg
RETURN

See Also

Other Resources

SCOLS( ) Function
SROWS( ) Function
WLCOL( ) Function
WLROW( ) Function
WROWS( ) Function
Fonts Overview
Functions
Language Reference


WDOCKABLE( ) Function

Visual FoxPro 9.0 Language Reference
WDOCKABLE( ) Function
See Also

Returns the dockable state of the specified window

WDOCKABLE(cWindowName [, lEnable])

Parameters

cWindowName

Specifies the name of the window to evaluate.
lEnable

Specifies the dockable state for the window specified with the cWindowName parameter. If the specified window does not support docking, then Visual FoxPro ignores the lEnable parameter.

Return Value

Logical data type. Returns the current dockable state for the specified window.

Remarks

The WDOCKABLE( ) function always returns False (.F.) for undockable windows. Use the WDOCKABLE( ) function on Visual FoxPro windows that support docking. For a list of dockable Visual FoxPro windows, see How to: Dock Windows.

See Also

Other Resources

Windows
Functions
Language Reference


WEEK( ) Function

Visual FoxPro 9.0 Language Reference
WEEK( ) Function
See Also Example

Returns a number representing the week of the year from a Date or DateTime expression.

WEEK(dExpression | tExpression [, nFirstWeek] [, nFirstDayOfWeek])

Parameters

dExpression| tExpression

Specifies the Date or DateTime expression for which WEEK( ) returns the week of the year. When you omit nFirstWeek and nFirstDayOfWeek, WEEK( ) uses Sunday as the first day of the week.
[, nFirstWeek]

Specifies the requirements for the first week of the year. The following table lists the values for nFirstWeek.

nFirstWeek Description

0

Specifies that WEEK( ) return the week that is currently selected in the First Week of Year box on the Regional tab of the Options dialog box.

1

First week contains January 1st. This is the default when you omit nFirstWeek.

2

The larger half (four days) of the first week is in the current year.

3

First week has seven days.
[, nFirstDayOfWeek]

Specifies the first day of the week. The following table lists the values for nFirstDayOfWeek.

nFirstDayOfWeek Description

0

Specifies that WEEK( ) return the day that is currently selected in the Week Starts on box on the Regional tab of the Options dialog box.

1

Sunday. This is the default when you omit nFirstDayOfWeek and is the first day of the week used in earlier FoxPro versions.

2

Monday

3

Tuesday

4

Wednesday

5

Thursday

6

Friday

7

Saturday

Return Value

Numeric type. WEEK( ) returns a number representing the week of the year.

Remarks

WEEK( ) returns a number from 1 to 53 that represents the week of the year. For example, WEEK( ) returns 1 for the first week of the year, 2 for the second week of the year, and so on. Note that a week can be split between years — the first week of the year can be in the current year and the previous year.

Example

The following example displays the week of the year for today's date and for a specific date.
Copy Code
CLEAR
? WEEK(DATE( ))
? WEEK({^1998-02-16})  && Displays 8

See Also

Other Resources

CDOW( ) Function
DAY( ) Function
DOW( ) Function
SET FDOW Command
SET FWEEK Command
Functions
SYS( ) Functions Overview


WEXIST( ) Function

Visual FoxPro 9.0 Language Reference
WEXIST( ) Function
See Also Example

Determines whether the specified user-defined window exists.

WEXIST(WindowName)

Parameters

WindowName

Specifies the name of the user-defined window. You can also specify the name of a Visual FoxPro system window (the Command window, the Data Session window, a Browse window, and so on), and in Visual FoxPro, the name of a toolbar. WEXIST( ) returns true (.T.) if the system window or toolbar you specify is visible or hidden. WEXIST( ) returns false (.F.) if the specified system window or toolbar is closed. Two exceptions are the Command and Debug windows. Including the Command window's name in WEXIST( ) always returns a true value. If the Debug window has been opened, WEXIST( ) returns true, even if the Debug window is closed.

Return Value

Logical

Remarks

WEXIST( ) returns true (.T.) if the user-defined window you specify has been created with DEFINE WINDOW; otherwise WEXIST( ) returns false (.F.). The specified window does not have to be active or visible for WEXIST( ) to return true (.T.), but it must exist.

Example

Copy Code
DEFINE WINDOW wScreen1 FROM 10,10 TO 20,69
DEFINE WINDOW wScreen2 FROM 1,0 TO 19,79
CLEAR

? WEXIST('wScreen1')  && Displays .T.
STORE 'wScreen2' TO gcWinName
? WEXIST('win_name')  && Displays .F.
? WEXIST(gcWinName)  && Displays .T.
RELEASE WINDOWS wScreen1, wScreen2

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
WONTOP( ) Function
WOUTPUT( ) Function
WVISIBLE( ) Function
Functions
Language Reference


WFONT( ) Function

Visual FoxPro 9.0 Language Reference
WFONT( ) Function
See Also Example

Returns the name, size, or style of the current font for a window in Visual FoxPro for Windows.

WFONT(nFontAttribute [, WindowName])

Parameters

nFontAttribute

Specifies the font attribute you want to return. If nFontAttribute is 1, WFONT( ) returns the name of the current font for the active or specified window. If nFontAttribute is 2, WFONT( ) returns the font size. If nFontAttribute is 3, WFONT( ) returns a code that identifies the font style. The font style code is a character or set of characters that correspond to the current font style. For example, the current font style is Bold Italic if WFONT(3) returns BI. The following table lists the codes for each font style:

Character Font Style

B

Bold

I

Italic

N

Normal

O

Outline

Q

Opaque

S

Shadow

–

StrikeThru

T

Transparent

U

Underline
WindowName

Specifies the name of the window for which you want to determine the current font, font size, or font style. In Visual FoxPro, you can also include the name of a toolbar. Include the empty string to return the current font, font size, or font style for the main Visual FoxPro window. WindowName can be the name of a user-defined window created with DEFINE WINDOW or a text- or memo-editing window. You can also include the name of a system window (View, Trace, Debug, and so on). WFONT( ) can return font attributes only for a system window that has been opened and is currently visible or hidden. If the system window you specify is closed, Visual FoxPro generates an error message. WFONT( ) returns the current font, font size or font style for the active output window if you omit WindowName.

Return Value

Character and Numeric

Example

The following example creates a user-defined window called wFontChar. The window is activated and its font characteristics are displayed in the window. The font characteristics are then displayed for the main Visual FoxPro window.
Copy Code
CLEAR
DEFINE WINDOW wFontChar ;
   FROM 1,1 TO 3,35 ;
   FONT 'MS SANS SERIF',8 ;
   STYLE 'BI'  && Define window with font and style
ACTIVATE WINDOW wFontChar
? WFONT(1), WFONT(2), WFONT(3)  && wFontChar window
ACTIVATE SCREEN
?
?
?
? 'Font characteristics for the window wFontChar'
?
?
? WFONT(1,''), WFONT(2,''), WFONT(3,'')  && Main Visual FoxPro window
?
? 'Font characteristics for the main Visual FoxPro window'
WAIT WINDOW
RELEASE WINDOW wFontChar
CLEAR

See Also

Other Resources

FONTMETRIC( ) Function
GETFONT( ) Function
SYSMETRIC( ) Function
TXTWIDTH( ) Function
Functions
Language Reference


WLAST( ) Function

Visual FoxPro 9.0 Language Reference
WLAST( ) Function
See Also

Returns the name of the window that was active prior to the current window or determines whether the specified window was active prior to the current window.

WLAST([WindowName])

Parameters

WindowName

Specifies a window that WLAST( ) evaluates. In Visual FoxPro, you can also specify the name of a toolbar. WLAST( ) returns true (.T.) if the specified window was active prior to the current window; otherwise false (.F.) is returned. False (.F.) is also returned if the window you specify doesn't exist. The name of the window that was active prior to the current window is returned if you omit WindowName.

Return Value

Character or Logical

Remarks

WLAST( ) returns the empty string if the window that was active prior to the current window is the Debug, Trace, or Command window. Program execution isn't affected by bringing these windows forward when you are debugging a program that uses WLAST( ).

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
WEXIST( ) Function
WONTOP( ) Function
WOUTPUT( ) Function
WVISIBLE( ) Function
Functions
Language Reference


WLCOL( ) Function

Visual FoxPro 9.0 Language Reference
WLCOL( ) Function
See Also

Returns the column coordinate of the upper-left corner of the active or specified window.

WLCOL([WindowName])

Parameters

WindowName

Specifies the window for which WLCOL( ) returns the column coordinate. In Visual FoxPro, you can also specify the name of a toolbar. If you omit WindowName, WLCOLS( ) returns the column coordinate of the active output window. You can also use the empty string for WindowName to specify the main Visual FoxPro window. In Visual FoxPro, if no window is active, WLCOLS( ) returns the column coordinate of the main Visual FoxPro window relative to the Windows desktop. If a system window (the Command window, the Data Session window, a Browse window, and so on) has been opened and is visible or hidden (its name appears on the Window menu), you can include its name in WLCOL( ). If you specify the name of a system window that is closed, Visual FoxPro generates an error message. The Debug window is an exception. Once the Debug window has been opened, its name can be included in WLCOL( ) if it is visible, hidden, or closed.

Return Value

Numeric

Remarks

The value returned by WLCOL( ) depends on the current video display mode, and is relative to the main Visual FoxPro window. The display mode can be changed with SET DISPLAY.

Windows can be positioned outside the main Visual FoxPro window. If the specified window is to the left of the main Visual FoxPro window, WCOL( ) returns a negative value. If the window's left border is to the right of the main Visual FoxPro window, WCOL( ) returns a positive value greater than the width of the main Visual FoxPro window.

See Also

Other Resources

SET DISPLAY Command
WCOLS( ) Function
WLROW( ) Function
WROWS( ) Function
Functions
Language Reference


WLROW( ) Function

Visual FoxPro 9.0 Language Reference
WLROW( ) Function
See Also

Returns the row coordinate of the upper-left corner of the active or specified window.

WLROW([WindowName])

Parameters

WindowName

Specifies the window for which WLROW( ) returns the row coordinate. In Visual FoxPro, you can also specify the name of a toolbar. If you omit WindowName, WLROW( ) returns the row coordinate of the active output window. You can also use the empty string for WindowName to specify the main Visual FoxPro window. In Visual FoxPro, if no window is active, WLROW( ) returns the row coordinate of the main Visual FoxPro window relative to the Windows desktop. If a system window (the Command window, the Data Session window, a Browse window, and so on) has been opened and is visible or hidden (its name appears on the Window menu), you can include its name in WLROW( ). If you specify the name of a system window that is closed, Visual FoxPro generates an error message. The Debug window is an exception. Once the Debug window has been opened, its name can be included in WLROW( ) if it is visible, hidden, or closed.

Return Value

Numeric

Remarks

The value returned by WLROW( ) depends on the current video display mode, and the row coordinate is relative to the main Visual FoxPro window. The display mode can be changed with SET DISPLAY.

Windows can be positioned off the main Visual FoxPro window. If the top of the window is above the main Visual FoxPro window, WLROW( ) returns a negative value. If the top of the window is below the bottom of the main Visual FoxPro window, WLROW( ) returns a positive value greater than the height of the main Visual FoxPro window.

See Also

Other Resources

SET DISPLAY Command
WCOLS( ) Function
WLCOL( ) Function
WROWS( ) Function
Functions
Language Reference


WMAXIMUM( ) Function

Visual FoxPro 9.0 Language Reference
WMAXIMUM( ) Function
See Also

Determines whether the active or specified window is maximized.

WMAXIMUM([WindowName])

Parameters

WindowName

Specifies the name of the window WMAXIMUM( ) evaluates. You can specify the name of a Visual FoxPro system window (the Command window, the Data Session window, a Browse window, and so on). If you omit WindowName, WMAXIMUM( ) returns a logical value for the active window. You can also use the empty string for WindowName to specify the main Visual FoxPro window.

Remarks

Windows can be enlarged to fill the window that contains them. In Visual FoxPro for Windows, the default container window is the main window.

A user-defined window created with DEFINE WINDOW can be maximized only if the ZOOM keyword is included in its definition.

WMAXIMUM( ) returns true (.T.) if the current or specified window is maximized; otherwise WMAXIMUM( ) returns false (.F.). In Visual FoxPro, you can include the name of a toolbar. However, WMAXIMUM( ) always returns false (.F.) for a toolbar because toolbars cannot be maximized.

See Also

Other Resources

DEFINE WINDOW Command
WMINIMUM( ) Function
ZOOM WINDOW Command
Functions
Language Reference


WMINIMUM( ) Function

Visual FoxPro 9.0 Language Reference
WMINIMUM( ) Function
See Also

Determines whether the active or specified window is minimized.

WMINIMUM([WindowName])

Parameters

WindowName

Specifies the name of the window WMINIMUM( ) evaluates. You can specify the name of a Visual FoxPro system window (the Command window, the Data Session window, a Browse window, and so on). If you omit WindowName, WMINIMUM( ) returns a logical value for the active window. You can also include the empty string in WindowName to specify the main Visual FoxPro window.

Return Value

Logical

Remarks

In Visual FoxPro for Windows, windows can be reduced to an icon.

A user-defined window created with DEFINE WINDOW can be minimized only if the MINIMIZE keyword is included in its definition.

WMINIMUM( ) returns true (.T.) if the current or specified window is minimized; otherwise it returns false (.F.). In Visual FoxPro, you can include the name of a toolbar. However, WMINIMUM( ) always returns false (.F.) for a toolbar because toolbars cannot be minimized.

See Also

Other Resources

DEFINE WINDOW Command
WMAXIMUM( ) Function
ZOOM WINDOW Command
Functions
Language Reference


WONTOP( ) Function

Visual FoxPro 9.0 Language Reference
WONTOP( ) Function
See Also Example

Determines whether the active or specified window is in front of all other windows.

WONTOP([WindowName])

Parameters

WindowName

Specifies the name of the window WONTOP( ) evaluates. You can specify the name of a user-defined window created with DEFINE WINDOW or a system window (the Command window, the Data Session window, a Browse window, and so on). If you omit WindowName, WONTOP( ) returns the name of the "frontmost" or active window. You can also include the empty string in WindowName to specify the main Visual FoxPro window. If the Debug, Trace, or Command window is active and you don't specify a window name, WONTOP( ) returns the name of the window most recently in front. When you are debugging a program that uses WONTOP( ), program execution isn't affected by bringing these windows forward.

Return Value

Character or Logical

Remarks

WONTOP( ) returns true (.T.) if the specified window is active. It returns false (.F.) if the window isn't active or doesn't exist.

Historically in prior versions of Visual FoxPro, the Data Session window has always been referred to as the View window. Additionally, language used to control this window, such as HIDE WINDOW, ACTIVATE WINDOW, WONTOP( ), also refers to this window as the View window. Visual FoxPro continues to refer to the View window for the WONTOP( ) function.

Example

The following example uses WONTOP( ) to display the name of the active window. Before you run this program, open some windows (Browse windows, the Data Session window, and so on), then run the example.
Copy Code
IF NOT EMPTY(WONTOP( ))
   WAIT WINDOW 'Frontmost window: ' + WONTOP( )
ELSE
   WAIT WINDOW 'No windows are open'
ENDIF

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
WEXIST( ) Function
WOUTPUT( ) Function
WVISIBLE( ) Function
Functions
Language Reference


WOUTPUT( ) Function

Visual FoxPro 9.0 Language Reference
WOUTPUT( ) Function
See Also Example

Determines whether output is being directed to the active or specified window.

WOUTPUT([WindowName])

Parameters

WindowName

Specifies the window WOUTPUT( ) evaluates for output. Output cannot be directed to a system window or toolbar. If you omit WindowName, WOUTPUT( ) returns the name of the window to which output is currently directed. You can also include the empty string in WindowName to specify the main Visual FoxPro window. WOUTPUT( ) returns the empty string if output is being directed to the main Visual FoxPro window.

Return Value

Logical and Character

Remarks

WOUTPUT( ) returns true (.T.) if the specified user-defined window is the active output window. WOUTPUT( ) returns false (.F.) if the window you specify doesn't exist or is a system window. The last user-defined window activated with ACTIVATE WINDOW is the active output window.

Example

In the following example, a window is created and activated. WOUTPUT( ) is used to display the name of this active output window. The window is closed and removed from memory. If another window is active, its name is displayed. If another window isn't active, a message is displayed indicating that output is directed to the main Visual FoxPro window.
Copy Code
DEFINE WINDOW wOutput1 FROM 2,2 TO 12,32 TITLE 'Output Window'
ACTIVATE WINDOW wOutput1
WAIT WINDOW 'wOutput1 window: ' + WOUTPUT( )
RELEASE WINDOW wOutput1
IF EMPTY(WOUTPUT( ))
   WAIT WINDOW 'Output being directed to the main Visual FoxPro window'
ELSE
   WAIT WINDOW 'Output window: ' + WOUTPUT( )
ENDIF

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
WEXIST( ) Function
WONTOP( ) Function
WVISIBLE( ) Function
Functions
Language Reference


WPARENT( ) Function

Visual FoxPro 9.0 Language Reference
WPARENT( ) Function
See Also Example

Returns the name of the parent window of the active or specified window.

WPARENT([WindowName])

Parameters

WindowName

Specifies a window whose parent window name WPARENT( ) returns. WPARENT( ) returns the empty string if the specified window doesn't have a parent window. If you omit WindowName, WPARENT( ) returns the name of the parent window of the active output window. WPARENT( ) returns the empty string if the active output window doesn't have a parent window.

Return Value

Character

Remarks

You can use DEFINE WINDOW to create a window and place it in a parent window. The child window becomes integrated with its parent window. For example, a child window defined and activated inside a parent window can't be moved outside the parent window. If the parent window is moved, the child window moves with it.

Example

The following example defines a parent and child window. It then uses WPARENT( ) to identify which window is the parent.
Copy Code
CLEAR ALL
CLEAR
DEFINE WINDOW wParent ;
   FROM 1,1 TO 20,20 ;
   TITLE 'wParent'     && Parent window
ACTIVATE WINDOW wParent
DEFINE WINDOW wChild ;
   FROM 1,1 TO 10,10 ;
   TITLE 'wChild' ;
   IN WINDOW wParent  && Child window
ACTIVATE WINDOW wChild
WAIT WINDOW 'The parent window is ' + WPARENT( )
RELEASE WINDOW wParent, wChild

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
WCHILD( ) Function
Functions
Language Reference


WREAD( ) Function

Visual FoxPro 9.0 Language Reference
WREAD( ) Function
See Also

Included for backward compatibility. Use the Form Designer instead.

See Also

Other Resources

Language Reference


WROWS( ) Function

Visual FoxPro 9.0 Language Reference
WROWS( ) Function
See Also

Returns the number of rows within the active or specified window.

WROWS([WindowName])

Parameters

WindowName

Specifies the window for which WROWS( ) returns the number of rows. In Visual FoxPro, you can also specify the name of a toolbar. In Visual FoxPro, the value returned by WROWS( ) depends on the font specified for the window. Most fonts can be displayed in a wide variety of sizes, and some are proportionally spaced. A row corresponds to the height of the current font. For more information, see the Fonts Overview topic. You can specify the name of a system window (the Command window, the Data Session window, a Browse window, and so on) in WROWS( ) if the system window has been opened and is visible or hidden. If you specify the name of a system window that is closed, FoxPro generates an error message. The Debug window is an exception. Once the Debug window has been opened, its name can be included in WROWS( ) if it is visible, hidden, or closed. You can also include the empty string in WindowName to return the number of rows in the main Visual FoxPro window. The empty string can be used to specify the main Visual FoxPro window in functions such as WLCOL( ), WLROW( ), and WCOLS( ), which return window locations or sizes.

Return Value

Numeric

Remarks

If you don't specify a window name, the number of rows in the active output window is returned. If no window is active, the number of rows in the main Visual FoxPro window is returned.

See Also

Other Resources

SCOLS( ) Function
SROWS( ) Function
WCOLS( ) Function
WLCOL( ) Function
WLROW( ) Function
Fonts Overview
Functions
Language Reference


WTITLE( ) Function

Visual FoxPro 9.0 Language Reference
WTITLE( ) Function
See Also

Returns the title assigned to the active or specified window.

WTITLE([WindowName])

Parameters

WindowName

Specifies a window whose title WTITLE( ) returns. The title assigned to the window with the TITLE clause is returned if you include the name of a user-defined window created with DEFINE WINDOW. When you issue BROWSE WINDOW to open a Browse window in a user-defined window, WTITLE( ) returns the title of the user-defined window if the Browse window doesn't have a title. WTITLE( ) returns the title of the Browse window if the Browse window does have a title. You can also use the empty string for WindowName to specify the main Visual FoxPro window.

Return Value

Character

Remarks

WTITLE( ) can be used to return a window's title, which appears in the top border of the window. The title is returned for the active window if you omit WindowName. WTITLE( ) returns the empty string if the Debug, Trace or Command window is active or output is being directed to the main Visual FoxPro window.

Window Names and Titles Names are assigned to user-defined windows, system windows, toolbars (in Visual FoxPro), and Browse windows in the following manner:

User-defined windows are assigned names when they are created with DEFINE WINDOW. There is a distinction between user-defined window names and titles. By default, user-defined windows don't have titles. If the TITLE clause is included when the window is created, the specified title appears in the top border of the window, but isn't the name of the window.

By default, each system window, which is part of the Visual FoxPro interface, derives its name from the title of the window. Examples of system windows include the Command window, the Data Session window, and the Trace window. In Visual FoxPro, each toolbar derives its name from the title of the toolbar.

Program and editing windows and the Label and Report Designer windows derive their names from the name of the file being created or modified.

A Browse window derives its name from the title of the window. The name and title of the Browse window is assigned in one of three ways: either by the default title assignment of the table alias, or by the window title (if any exists), or by the Browse title (if any exists).

By default, the Browse window name is the table alias.

To specify a system window and toolbar names in commands and functions, enclose the entire system window or toolbar name in quotation marks. For example, to hide the Report Controls toolbar in Visual FoxPro, issue the following command:

Copy Code
HIDE WINDOW "Report Controls"

Additional Notes on Window Names If you are unsure of the name assigned to a window, check the Window menu. All window names are listed at the bottom of the Window menu.

Two windows exist if you issue BROWSE WINDOW WindowName. The Browse window is a separate window and takes on the attributes of the specified user-defined window. If a window is active when you issue BROWSE and you don't include the WINDOW clause, the Browse window takes on the attributes of the active window. You can override this behavior by including NORMAL in BROWSE.

You can include window names that contain spaces in commands and functions that accept window names, such as MOVE WINDOW, DEACTIVATE WINDOW, and WONTOP( ), by specifying the part of the window name that begins with the first non-space character and continuing until the last non-space character is encountered.

For example, a Browse window with the name Invoice Entry can be moved with this command:

Copy Code
MOVE WINDOW invoice BY 1,1

The names of user-defined windows cannot contain spaces, but the names of Browse and system windows can.

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
WEXIST( ) Function
WLAST( ) Function
WONTOP( ) Function
WOUTPUT( ) Function
WREAD( ) Function
Functions
Language Reference


WVISIBLE( ) Function

Visual FoxPro 9.0 Language Reference
WVISIBLE( ) Function
See Also Example

Determines if the specified window has been activated and isn't hidden.

WVISIBLE(WindowName)

Parameters

WindowName

Specifies the name of the window WVISIBLE( ) evaluates. In Visual FoxPro, you can also specify the name of a toolbar. You can also include the empty string in WindowName to specify the main Visual FoxPro window.

Return Value

Logical

Remarks

WVISIBLE( ) returns true (.T.) if the specified window is shown or activated and isn't hidden. Windows are shown and activated with SHOW WINDOW and ACTIVATE WINDOW.

WVISIBLE( ) returns false (.F.) if the window has not been activated, has been hidden with HIDE WINDOW, has been deactivated with DEACTIVATE WINDOW, or doesn't exist.

Example

The follow example activates the Data Session window (represented by the name View). Using the WVISIBLE() function, you can print to screen the visible state of the window. The Deactivate window is used to close the Data Session window, and the WVISIBLE() function is used again to print the visible state of the window.

Copy Code
ACTIVATE WINDOW View
? WVISIBLE( "View" ) && return .T.
DEACTIVATE WINDOW View
? WVISIBLE( "View" ) && return .F.

See Also

Other Resources

ACTIVATE WINDOW Command
DEFINE WINDOW Command
WEXIST( ) Function
WONTOP( ) Function
WOUTPUT( ) Function
Functions
Language Reference


XMLTOCURSOR( ) Function

Visual FoxPro 9.0 Language Reference
XMLTOCURSOR( ) Function
See Also

Converts XML text into a Visual FoxPro cursor or table.

XMLTOCURSOR(eExpression | cXMLFile [, cCursorName [, nFlags ]])

Parameters

eExpression

Specifies the XML text or an expression that evaluates to valid XML data. The eExpression parameter can be a Visual FoxPro memory variable, memo field contents, the return from an HTTP request, the return result from a SOAP method call, XML from the XMLDOM, or an ADO stream.
Note:
XMLCURSOR( ) generates an error if eExpression is not found or if eExpression does not parse to valid XML.

cXMLFile

Specifies the name, and, optionally, the path of a physical XML file that resides on your local computer or network. If you do not specify a path, Visual FoxPro searches the path along the Visual FoxPro directory for the XML file.
cCursorName

Specifies the name of the cursor to store the result and creates the cursor in the current work area. If the cursor name already exists or is open, Visual FoxPro closes the cursor and creates a new one in an unused work area. If you omit or pass an empty string ("") for cCursorName, Visual FoxPro creates a cursor named "XMLRESULT" for returning the result. If cCursorName contains data and nFlags is set to 8192, Visual FoxPro appends the data being imported from the XML file to the existing table or cursor. The table or cursor must be open or in use. If cCursorName is an empty string (""), Visual FoxPro imports XML into the table or cursor that is open in the current work area.
nFlags

Specifies how XMLSource eExpression is handled in XMLTOCURSOR( ). The following table describes the values for nFlags.

nFlags Bit Description

0

0000

(Default) Treats the first parameter as a string containing XML data.

4

0100

Preserves white space in data and overrides the xml:space attribute of the XML data.

512

01000000000

Specifies that the first parameter, either an eExpression or a cXMLFile, is a string containing the name and path of an XML data file.

1024

10000000000

NOCPTRANS – Creates Character and Memo fields in the resultant cursor with the NOCPTRANS option and inserts the text or XML values in the incoming elements into the Character or Memo field on an untranslated, byte-for-byte basis.

When used with flag 1024, XMLTOCURSOR( ) returns a string padded with trailing spaces equal to the actual string, that is, a string twice the length.

2048

100000000000

Use when the imported schema has an XML schema definition (XSD) schema containing decimal data type with restrictions, or facets, of totalDigits="19" and fractionDigits="4."

XSD data type values are mapped to the Visual FoxPro Currency data type in the resulting cursor.

4096

1000000000000

Disables base64 decoding.

In Visual FoxPro, base64 encoding is intended for encoding only binary data.

8192

1100000000

Specifies that cCursorName is the name or alias of an existing table or cursor and imports the data from the specified XML file into an existing table or predefined cursor.

If cCursorName contains data, the data imported from the XML file is appended to the existing data. If cCursorName is an empty string (""), the data from the XML file is imported into the table or cursor in the current work area.

Setting nFlags to 8192 can be useful when an XML schema is not available or not practical for use.

32768

0x8000

Indicates that a code page should be used.

65536

0x10000

Maps XML Char fields to native Fox Varchar fields. If not specified, XML Char fields are mapped to Fox Character fields.

131072

0x20000

Maps XML base64Binary fields to native Fox Varbinary fields if less than 255 bytes or Blob fields if greater than this length. If not specified, XML base64Binary fields are mapped to Fox Memo fields.
When you use flag 8192, be aware of the following:
  • You must make sure the table schema matches the incoming XML elements in the appropriate manner. Visual FoxPro enforces the data types in cCursorName as described in the Data Type Matching table in this topic but makes no other assumptions about data types. Attempting to import incompatible values generates the appropriate message.

  • If the XML contains or references a schema, and the data types in the schema conflict with the data types of the cursor or table, the data types in the cursor or table are used.

  • Element names in the XML file are mapped to the column names in cCursorName. In addition, Visual FoxPro imports only data from the element names in the XML file that match the column names in cCusorName.

  • The cursor or table can have fewer columns than those in the XML file, but it must have at least one matching column. The cursor or table can have additional columns that do not correspond to an element in the XML file.

  • If the table contains autoincrementing fields, XMLTOCURSOR( ) fails if AUTOINCERROR is set to ON. Setting AUTOINCERROR to OFF or turning off autoincrementing in the target table by using CURSORSETPROP( ) allows XMLTOCURSOR( ) to succeed. The target table's autoincrementing field or fields are incremented according to the values specified, and the values in the source table are not copied.

The following table describes data type matching restrictions when setting nFlags to 8192.

Visual FoxPro data type | Behavior
Character, Character (Binary), Memo, Memo (Binary) | Accepts any data but truncates any data exceeding the length of a Character column.
Currency | Accepts numeric data within accepted range of the Currency type but truncates numbers outside this range.
Date | Accepts XML format date and dateTime values. Visual FoxPro converts the XML date and dateTime formats to the corresponding Visual FoxPro date. Visual FoxPro preserves only the M/D/Y portion of the XML date or dateTime value.
DateTime | Accepts XML format date and dateTime values. Visual FoxPro converts the XML date and dateTime formats to the corresponding Visual FoxPro date and discards precision beyond the extent supported by Visual FoxPro.
Double | Accepts numeric data within the accepted range of the Double type but truncates numbers outside this range.
Integer | Accepts integer data within the accepted range of the Integer type but truncates numbers outside this range.
Logical | Accepts the values True, .T., 1, False, .F., and 0.
Numeric, Float | Accepts numeric data with or without decimals but truncates numbers outside the accepted range for these types according to Visual FoxPro rules or replaces with the numeric overflow indicator ("*************").

Return Value

Numeric data type. XMLTOCURSOR( ) returns the number of records created.

Remarks

You can use XMLTOCURSOR( ) with the OLE DB Provider for Visual FoxPro. However, the _VFP VFPXMLProgID property is not supported because the _VFP system variable is not supported in the OLE DB Provider.

Note:
To use the Visual FoxPro OLE DB Provider with XMLTOCURSOR( ), you must install MSXML 3.0 on the computer with the OLE DB Provider.

XMLTOCURSOR( ) generates a syntax error for record lengths greater than approximately 160 columns. The exact number of columns that cause an error depends on the length of the column names.

XMLTOCURSOR( ) does not use the Varchar type when creating a cursor from an XML document. However, XMLTOCURSOR( ) supports appending data into an existing cursor with Varchar fields.

When calling XMLTOCURSOR( ) in append mode, Visual FoxPro adds an empty row if no XML element name matches any table or cursor column.

XMLTOCURSOR( ) converts Decimal data type to Numeric 20,19 (width, precision). In versions prior to Visual FoxPro 8.0, Decimal mapped to Numeric 8,0.

Numeric Overflow Conditions XMLTOCURSOR( ) imports XML data containing Visual FoxPro numeric overflow conditions, for example, "*******", in place of a numeric or integer value. If a schema is provided, Visual FoxPro creates the correct data type in the resulting cursor but changes the overflow from asterisk (*) characters to 0.0 or 0 values. Therefore, the XML parser used by XMLTOCURSOR( ) does not throw an error as a result of character values stored in a decimal type element.

For more information about converting XML to Visual FoxPro data, see Converting Between XML and Visual FoxPro Data.

See Also

Other Resources

CURSORTOXML( ) Function
XMLUPDATEGRAM( ) Function
XML Data in Visual FoxPro
Functions


XMLUPDATEGRAM( ) Function

Visual FoxPro 9.0 Language Reference
XMLUPDATEGRAM( ) Function
See Also

Mirrors changes made in a buffered table or cursor in an XML UpdateGram and returns a character string that contains the UpdateGram.

An XML UpdateGram represents the before and after conditions of the changed portion of a Visual FoxPro table or cursor. Through additional processes, you can use an UpdateGram to commit these changes to the data represented by the XML UpdateGram document.

Note:
To use XMLUPDATEGRAM( ), you must use SET MULTILOCKS ON and enable table buffering.

Tip:
Before calling XMLUPDATEGRAM( ), you should specify the key field list by calling CURSORSETPROP( ) with the KeyFieldList property against existing cursors and tables. If you do not specify key fields, both the before and after representations contains all the fields in the table. If you specify one or more key fields, only those fields appear in the before section.

XMLUPDATEGRAM( [ cAliasList [, nFlags [, cSchemaLocation]]])

Parameters

cAliasList

Specifies a comma-separated list of open tables or cursors, listed either by name or work area numbers in any combination, to include in the XML UpdateGram. If you specify no value or an empty string ("") for cAliasList, Visual FoxPro uses all open tables and cursors in the current data session that contain buffered changes.
nFlags

Specifies whether to return a formatted file. The following table lists the additive flags for nFlags.

nFlag Bit Output description

0

0000

(Default) Use UTF-8 formatted XML.

1

0001

Use unformatted, for example, continuous string XML.

2

0010

Enclose empty elements with both open and closing elements, for example, <cc04><cc04/>.

4

0100

Preserve white space in fields.

8

1000

Wrap Memo fields in CDATA sections.

16

10000

Output encoding.

32

100000

Output encoding.

32768

none

Indicates that a code page should be used.
Note:
When output encoding is UTF-8 (default), the XML Declaration does not contain an Encoding= attribute (no encoding attribute = UTF-8).

When output encoding is set to default to the code page of the cursor or table, the encoding attribute will be written according to the following table.
Note:
Encoding flags are set by combining bits 4 and 5 (0010000).

Encoding flag Bits 4 and 5 Description

+0

00

(Default) Windows 1252

+16

01

Set output encoding attribute to the code page of the cursor.

+32

10

Set output encoding attribute to UTF-8 (no character translation).

+48

11

Set output encoding attribute to UTF-8 and translate double-byte characters to UTF-8.
cSchemaLocation

Specifies the name and location of the mapping schema, if it exists.
Note:
You must supply the mapping schema.

For example, suppose you pass the a schema called mySchema.xsd to cSchemaLocation, the UpdateGram created contains a mapping schema attirbute as it appears in the following XML:
Copy Code
<ROOT xmlns:updg="urn:schemas-microsoft-com:xml-updategram">
  <updg:sync mapping-schema="mySchema.xsd" >
    <updg:before>

Return Value

Character data type. XMLUPDATEGRAM( ) returns a character string that contains the XML UpdateGram.

Remarks

You can use XMLUPDATEGRAM( ) with the OLE DB Provider for Visual FoxPro. However, the _VFP VFPXMLProgID property is not supported because the _VFP system variable is not supported in the OLD EB Provider.

Note:
To use the Visual FoxPro OLE DB Provider with XMLUPDATEGRAM( ), you must install MSXML 3.0 on the computer with the OLE DB Provider.

SQL Server and Visual Studio support the DiffGram format for updating XML. However, SQL XML requires a mapping schema to support this format. Therefore, XMLUPDATEGRAM( ) does not support this format.

To avoid possible errors generated by XMLUPDATEGRAM( ) on tables containing Memo or General fields, use the CURSORSETPROP( ) function. The following example shows how to include memo data in an XML UpdateGram by setting the KeyFieldList property using CURSORSETPROP( ):

Copy Code
SET MULTILOCKS ON
CREATE CURSOR Test (mField M, cField I AUTOINC)
INSERT INTO Test (mField) VALUES ("123456789")
INSERT INTO Test (mField) VALUES ("23456789")
INSERT INTO Test (mField) VALUES ("3456789")
INSERT INTO Test (mField) VALUES ("456789")
CURSORSETPROP("Buffering",5)
CURSORSETPROP("keyfieldlist",'cField')
UPDATE Test SET mField = "XXXXXXX" WHERE cField < 3
STRTOFILE(XMLUPDATEGRAM(),'xmlupdate.txt')
MODIFY FILE xmlupdate.txt
RETURN

To write memo data in the XML UpdateGram to SQL Server, you must use an explicit schema on the SQL Server and reference the schema in the XML UpdateGram.

Unlike the CURSORTOXML( ) function, XMLUPDATEGRAM( ) disregards SET FIELDS statements and reads from the underlying cursor directly. To change the table structure before calling XMLUPDATEGRAM( ), you must copy the data into a new cursor. For example, to change a Numeric field to a Currency field, the following example uses a SQL SELECT statement to create a new cursor and uses that cursor with XMLUPDATEGRAM( ). The example makes the Total_Price field a currency field, enables buffering with CURSORSETPROP( ), adds sales tax with the REPLACE command, and creates an XML UpdateGram using the XMLUPDATEGRAM( ) function.

Copy Code
SELECT OrderID, CustID, NTOM(Total_Price) as Total_Price;
      FROM Orders INTO CURSOR New_Orders READWRITE
   CURSORSETPROP("Buffering", 5, "New_Orders")
   REPLACE Total_Price WITH (Total_Price * 1.083)
   cXMLUpdg = XMLUPDATEGRAM("New_Orders")

When using flag 32768, the flag's 16 and 32 settings can affect which code page is applied depending on the type of data you are writing to XML. The following tables show the possible combinations of settings and the code page each combination applies.

For XML documents written with the 32768 flag set, the following code pages are applied.

Flag 16 | Flag 32 | Flag 32768 is Set
Not set | Not set | XML documents: Window-1252. Unicode data: code page 1252. Character data: default code page, unless a field is marked as NOCPTRANS.
True (.T) | Not set | XML documents: Plus-CodePage property of the cursor. If XMLField CodePage property is greater than zero (0) and it doesn’t match the cursor’s code page, an error is reported. Unicode data: the Code page property of the cursor object. Character data: none. Raw data from the Visual FoxPro tables (.dbf) are used instead.
Not set | Set | XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: Default code page unless field is marked as NOCPTRANS, in which case no additional character translation to UTF-8 occurs.
Set | Set | XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: default code page unless a field is marked as NOCPTRANS, in which case the data are translated to UTF-8 using the SYS(3005) setting.

For XML documents written without setting the 32768 flag, the following code pages are applied.

Flag 16 | Flag 32 | Without the 32768 flag
Not set | Not set | XML documents: Window-1252. Unicode data: code page 1252. Character data: default code page unless a field is marked as NOCPTRANS.
True (.T) | Not set | XML documents: CodePage property of the cursor. Character data: none. Raw data from the Visual FoxPro tables (.dbf) are used instead. Unicode data: code page property of the cursor object.
Not set | Set | XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: default code page unless field is marked as NOCPTRANS, in which case no additional character translation to UTF-8 occurs.
Set | Set | XML documents: UTF-8 code page. Unicode data: UTF-8 code page. Character data: default code page unless field is marked as NOCPTRANS, in which case, they are translated to UTF-8 using code page for the current SYS(3005) setting.

For more information about converting XML to Visual FoxPro data, see Converting Between XML and Visual FoxPro Data.

See Also

Other Resources

CURSORTOXML( ) Function
XMLTOCURSOR( ) Function
Converting Between XML and Visual FoxPro Data
XML Data in Visual FoxPro
Functions


YEAR( ) Function

Visual FoxPro 9.0 Language Reference
YEAR( ) Function
See Also Example

Returns the year from the specified date or datetime expression.

YEAR(dExpression | tExpression)

Parameters

dExpression

Specifies a date expression from which YEAR( ) returns the year. dExpression can be a function that returns a date, or a Date-type memory variable, array element, or field. It can also be a literal date string, such as {^1998-06-06}.
tExpression

Specifies a datetime expression from which YEAR( ) returns the year.

Return Value

Numeric

Remarks

YEAR( ) always returns the year with the century. The CENTURY setting (ON or OFF) doesn't affect the returned value.

Example

Copy Code
CLEAR
? YEAR(DATE( ))

See Also

Other Resources

DATE( ) Function
DATETIME( ) Function
DOW( ) Function
SET CENTURY Command
Functions
Language Reference


Operators (Visual FoxPro)

Visual FoxPro 9.0
Operators (Visual FoxPro)
See Also

Operators make it possible for you to manipulate data of the same type. Visual FoxPro operators can be grouped according to the following data types and functions:

  • Character Operators

  • Date and Time Operators

  • Logical Operators

  • Relational Operators

  • Numeric Operators

See Also

Other Resources

Language Reference


Character Operators

You can join and compare character data using the character operators +, -, and $. The following table lists the character expression operators in order of precedence.

Character Operators

Operator | Action | Code
+ | Concatenation. Joins two strings, a string and a field, or a string and a variable. | ? 'Good ' + 'morning'
- | Concatenation. Removes trailing blanks from the element preceding the operator then joins two elements. | ? customer.first - customer.last
$ | Comparison. Seeks one character expression within another. | ? 'father' $ 'grandfather' ? 'Main' $ customer.address

See Also

Other Resources

$ Operator
Character Data Type
Creating Character Expressions
Operators


Date and Time Operators

The following operators act on dates and times.

Date and Time Operators

Operator Action Code

+

Addition
Copy Code
tNewTime = tTime1 + nSeconds
dNewDate = dDate1 + nDays

-

Subtraction
Copy Code
nSeconds = tTime1 - tTime2
tNewTime = tTime1 - nSeconds
dNewDate = dDate1 - nDays

See Also

Other Resources

Date Data Type
DateTime Data Type
Date and Time Functions
Operators


Logical Operators

Logical operators work with all data types and return a Logical value. The following table lists the logical operators in order of precedence.

Logical Operators

Operator | Action | Code
( ) | Expression groups | cVar AND (cVar2 AND cVAR3)
NOT, ! | Logical negative | IF NOT cVarA = cVarB IF ! nVar1 = nVar2
AND | Logical AND | lVar0 AND lVar9
OR | Logical inclusive OR | lVarX OR lVarY
Note:
The Not Equal operator ( # ) can be used to perform XOR comparison (such as lVarX # lVarY).

See Also

Other Resources

BITAND( ) Function
BITNOT( ) Function
BITOR( ) Function
BITXOR( ) Function
Relational Operators
Operators


Numeric Operators

Numeric operators function with all numeric values. The following table lists the numeric operators in order of precedence.

Numeric Operators

Operator | Action | Code
( ) | Group subexpressions | (4-3) * (12/nVar2)
**, ^ | Exponentiation | ? 3 ** 2 ? 3 ^ 2
*, / | Multiplication and division | ? 2 * 7 ? 14 / 7
% | Modulus (remainder) | ? 15 % 4
+, - | Addition and subtraction | ? 4 + 15

See Also

Other Resources

% Operator
Currency Data Type
Double Field Type
Float Field Type
Numeric Data Type
Operators


Relational Operators

Relational operators work with all data types and return a Logical value. The following table lists the relational operators.

Relational Operators

Operator | Action | Code
< | Less than | ? 23 < 54
> | Greater than | ? 1 > 2
= | Equal to | ? cVar1 = cVar
<>, #, != | Not equal to | ? .T. <> .F.
<= | Less than or equal to | ? {^1998/02/16} <= {^1998/02/16}
>= | Greater than or equal to | ? 32 >= nHisAge
== | Character string comparison | ? status == "Open"

The == operator can be used when an exact comparison of character strings is needed. If two character expressions are compared with the == operator, the expressions on both sides of the == operator must contain exactly the same characters, including blanks, to be considered equal. The SET EXACT setting is ignored when character strings are compared using ==. See SET EXACT for more information on using the == operator to compare character strings.

You also can use the equal to (=) operator to determine if two object references refer to the same object. The following example demonstrates a simple usage:

Copy Code
CLEAR ALL
X = CREATEOBJECT('Form')
Y = CREATEOBJECT('Form')
? X = Y  && Displays false (.F.)
Z = X
? X = Z  && Displays true (.T.)

See Also

Other Resources

Logical Operators
CREATEOBJECT( ) Function
SET EXACT Command
Operators


Preprocessor Directives (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
Preprocessor Directives (Visual FoxPro)
See Also

#DEFINE ... #UNDEF Preprocessor Directive

#IF ... #ENDIF Preprocessor Directive

#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive

#INCLUDE Preprocessor Directive

#INSERT Preprocessor Directive

#NAME Preprocessor Directive

Coverage Preprocessor Directives

For information about backward compatible-only language reference, see Backward-Compatible Language Elements.

See Also

Other Resources

Language Reference


#DEFINE ... #UNDEF Preprocessor Directive

Visual FoxPro 9.0 Language Reference
#DEFINE ... #UNDEF Preprocessor Directive
See Also Example

Creates and releases compile-time constants.

You can use the #DEFINE and #UNDEF preprocessor directives to create compile-time constants in programs. By creating constants with #DEFINE instead of using variables, you can reduce memory consumption, increase performance, and simplify programs.

To create a constant with #DEFINE, specify the constant's name with ConstantName and its value with eExpression. When the program is compiled, text substitution is performed and the constant value expression is substituted for the constant name wherever it appears in the program. You can stop the substitution for the constant by issuing #UNDEF.

#DEFINE ConstantName eExpression...
#UNDEF ConstantName

Parameters

ConstantName

Specifies a compile-time constant name. The constant name must be a legitimate Microsoft Visual FoxPro name that begins with a letter or an underscore and consists of up to 254 letters, digits, or underscores. To improve program readability and simplify debugging, capitalize your constant names and use a standard naming convention for them.
Caution:
Do not use Visual FoxPro keywords for constant names.

To stop text substitution for a constant created with #DEFINE, issue #UNDEF ConstantName.
eExpression

Specifies the value of the compile-time constant. eExpression can be a name or an expression that evaluates to a character, numeric, currency, date, datetime, or logical value.
Caution:
Do not use system variables for eExpression. System variables are not evaluated until run time.

Remarks

Visual FoxPro performs substitution only in code that follows the #DEFINE statement that creates the constant and that precedes the #UNDEF statement for that constant. The constant is available only to the program that creates the constant.

If you place #DEFINE within an event or method procedure in a form, the #DEFINE compile-time constant is available within the event or method procedure. Additionally, it may also be available in other events or methods since these code snippets are all written out together to the same Memo field within the form or class library file. You should not depend on this behavior since the order in which methods are written out may change in a subsequent save. To make #DEFINE compile-time constants available to all event and method procedures in a form or class, choose the Include File menu item from the Form (or Class) menu and specify a header file containing the #DEFINE compile-time constants.

Note:
Compile time constants are not recognized when placed within quotation marks.

You can redefine a #DEFINE only if you do not change the value. If you change the #DEFINE to a different value, Visual FoxPro generates an error.

Example

The following program creates a compile-time constant named MAXITEMS. This constant is used in a FOR ... NEXT loop to display the numbers 1 through 10.
Copy Code
#DEFINE MAXITEMS 10
CLEAR
FOR gnCount = 1 TO MAXITEMS
   ? gnCount
NEXT

See Also

Other Resources

COMPILE Command
#IF ... #ENDIF Preprocessor Directive
#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive
Preprocessor Directives


#IF ... #ENDIF Preprocessor Directive

Visual FoxPro 9.0 Language Reference
#IF ... #ENDIF Preprocessor Directive
See Also Example

Conditionally includes source code at compile-time.

#IF nExpression1 | lExpression1
      Commands
[#ELIF nExpression2 | #ELIF lExpression2
      Commands...
#ELIF nExpressionN | #ELIF lExpressionN
      Commands]
[#ELSE
      Commands]
#ENDIF

Parameters

#IF nExpression1| lExpression1Commands

nExpression1 specifies the numeric expression that is evaluated.
  • If the expression is nonzero, the commands immediately following #IF are included in the compiled code. The #IF ... #ENDIF structure is exited and the first program line following #ENDIF is then compiled.

  • If the expression is 0, the commands immediately following #IF are not included in the compiled code. Any following #ELIF directives are evaluated.

lExpression1 specifies the logical expression that is evaluated.
  • If the expression is True (.T.), the commands immediately following #IF are included in the compiled code. The #IF ... #ENDIF structure is exited, and the first program line following #ENDIF is then compiled.

  • If the expression is False (.F.), the commands immediately following #IF are not included in the compiled code. Any following #ELIF directives are evaluated.

    Note:
    Do not specify system variables for nExpression1 or lExpression1. System variables are not evaluated until run time.

#ELIF nExpression2| #ELIF lExpression2Commands

...
#ELIF nExpressionN| #ELIF lExpressionNCommands

If nExpression1 is 0 or lExpression1 is False (.F.), the #ELIF directives are evaluated. The first #ELIF expression nExpression2 or lExpression2, if present, is evaluated. If nExpression2 is nonzero or lExpression2 is True (.T.), the commands following #ELIF are included in the compiled code. The #IF ... #ENDIF structure is exited, and the first program line following #ENDIF is then compiled. If nExpression2 is 0 or lExpression2 is False (.F.), the commands following #ELIF are not included in the compiled code. The next #ELIF directive is evaluated.
#ELSE Commands

If no #ELIF directives are included, or, if those that are included evaluate to 0 or False (.F.), the presence or absence of #ELSE determines whether any additional commands are included in the compiled code:
  • If #ELSE is included, the commands following #ELSE are included in the compiled code.

  • If #ELSE is not included, none of the commands between #IF and #ENDIF are included in the compiled code. The #IF ... #ENDIF structure is exited, and compilation continues on the first program line following #ENDIF.

#ENDIF

Indicates the end of the #IF statement.

Remarks

#IF ... #ENDIF can improve the readability of source code, reduce compiled program size, and, in some cases, improve performance.

When the #IF ... #ENDIF structure is compiled, successive logical or numeric expressions within the structure are evaluated. The evaluation results determine which set of Visual FoxPro commands (if any) are included in the compiled code.

Example

In the following example, the #IF ... #ENDIF structure determines which version of Visual FoxPro compiles the program and then displays the appropriate message.
Copy Code
#If SYS(3004) = "1033"
? "Locale ID is English"
#Elif SYS(3004) = "1034"
? "Locale ID is Spanish"
#Elif SYS(3004) = "1031"
? "Locale ID is German"
#Elif SYS(3004) = "1036"
? "Locale ID is French"
#Endif

See Also

Other Resources

COMPILE Command
#DEFINE ... #UNDEF Preprocessor Directive
#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive
Preprocessor Directives


#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive

Visual FoxPro 9.0 Language Reference
#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive
See Also Example

Conditionally includes a set of commands at compile time if a compile-time constant is defined.

#IFDEF | #IFNDEF ConstantName
      Commands
[#ELSE
      Commands]
#ENDIF

Parameters

#IFDEF

Specifies that a set of commands is included at compile time when the ConstantName is defined. The following items describe how a set of commands is included at compile time when you include #IFDEF:
  • If ConstantName is defined, the set of commands following #IFDEF and preceding #ELSE or #ENDIF (whichever occurs first) is included at compile time.

  • If ConstantName is not defined and #ELSE is included, the set of commands following #ELSE and preceding #ENDIF is included at compile time.

  • If ConstantName is not defined and #ELSE is not included, no commands within the #IFDEF ... #ENDIF structure are included at compile time.

#IFNDEF

Specifies that a set of commands is included at compile time when the ConstantName is not defined. The following items describe how a set of commands is included at compile time when you include #IFNDEF:
  • If ConstantName is not defined, the set of commands following #IFNDEF and preceding #ELSE or #ENDIF (whichever occurs first) is included at compile time.

  • If ConstantName is defined and #ELSE is included, the set of commands following #ELSE and preceding #ENDIF is included at compile time.

  • If ConstantName is defined and #ELSE is not included, no commands within the #IFNDEF ... #ENDIF structure are included at compile time.

ConstantName

Specifies the compile-time constant whose existence determines whether a set of commands is included at compile time. Compile-time constants are defined with #DEFINE.
Commands

Specifies the set of commands that is included at compile time.

Remarks

You can nest an #IFDEF | #IFNDEF ... #ENDIF structure within another #IFDEF | #IFNDEF ... #ENDIF structure.

Comments can be placed on the same line after #IFDEF, #IFNDEF, #ELSE, and #ENDIF. These comments are ignored during compilation and program execution.

Example

The following example creates a compile-time constant named MYDEFINE. #IFDEF ... #ENDIF displays a message if the compile-time constant has been defined.
Copy Code
#DEFINE MYDEFINE 1

#IFDEF MYDEFINE
   WAIT WINDOW "MYDEFINE exists"
#ELSE
   WAIT WINDOW "MYDEFINE does not exist"
#ENDIF

See Also

Other Resources

COMPILE Command
#DEFINE ... #UNDEF Preprocessor Directive
#IF ... #ENDIF Preprocessor Directive
#INCLUDE Preprocessor Directive
Preprocessor Directives


#INCLUDE Preprocessor Directive

Visual FoxPro 9.0 Language Reference
#INCLUDE Preprocessor Directive
See Also Example

Instructs the Visual FoxPro preprocessor to treat the contents of a specified header file as if it appeared in a Visual FoxPro program.

Note:
The maximum number of compiler levels for #INCLUDE is 4.

#INCLUDE FileName

Parameters

FileName

Specifies the name of the header file that is merged into the program during compilation. You can include a path with the header file name. When you include a path with the header file name, Visual FoxPro searches for the header file only in the specified location. If you do not include a path with the header file name, Visual FoxPro searches for the header file in the default Visual FoxPro directory, and then along the Visual FoxPro path. The Visual FoxPro path is specified with SET PATH.

Remarks

You can create header files containing preprocessor directives and then use #INCLUDE to merge the contents of the header file into a program when the program is compiled. The contents of the header file are inserted into the program during compilation at the point where #INCLUDE appears in the program.

Only the #DEFINE ... #UNDEF, #IF ... #ENDIF, and #INCLUDE preprocessor directives are recognized in a header file. Comments and Visual FoxPro commands included in a header file are ignored.

A program can contain any number of #INCLUDE directives. These directives can appear anywhere within the program. Putting #INCLUDE directives in header files makes it possible for you to nest #INCLUDE directives.

Header files typically have an .h extension, although they can have any extension. A Visual FoxPro header file, Foxpro.h, is included. It contains many of the constants described throughout this documentation.

Example

In the following example, two files are used: Const.h, a header file, and Myprog.prg, a program file. The header file contains several #DEFINE directives that create compile-time constants. The program file uses #INCLUDE to merge the Const.h header file at compilation, making the compile-time constants in the header file available to the program.
Copy Code
*** Header file CONST.H ***
#DEFINE ERROR_NODISK     1
#DEFINE ERROR_DISKFULL  2
#DEFINE ERROR_UNKNOWN  3

*** Program file MYPROG.PRG ***
#INCLUDE CONST.H

FUNCTION chkerror
PARAMETER errcode
  DO CASE
  CASE errcode = ERROR_NODISK
  ?"Error - No Disk"
  CASE errcode = ERROR_DISKFULL
  ?"Error - Disk Full"
  CASE errcode = ERROR_UNKNOWN
  ?"Unknown Error"
  ENDCASE
RETURN

See Also

Other Resources

Preprocessor Directives
#DEFINE ... #UNDEF Preprocessor Directive
#IF ... #ENDIF Preprocessor Directive
#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive
Preprocessor Directives


#INSERT Preprocessor Directive

Visual FoxPro 9.0 Language Reference
#INSERT Preprocessor Directive
See Also

Places text from a text file into a generated menu file.

#INSERT FileName

Parameters

FileName

Specifies the name of the header file that is merged into the program during menu generation.

Remarks

The #INSERT menu generator directive inserts the contents of FileName into generated menu code.

Use #INSERT to include a file in a generated menu program. For example, use #INSERT to place #DEFINE ... #UNDEF statements from a file in the beginning of a generated menu program.

This directive can appear in any procedure; it does not have to be in a particular procedure, such as the setup code. Additionally, the directive can appear anywhere in a procedure.

FileName must be a text file. The generator searches for the file in the current directory, in the FoxPro directory and subdirectories and along the MS-DOS path. If the file cannot be found, the menu generator comments your code - indicating that the file could not be found - and then continues the generation process.

See Also

Other Resources

#DEFINE ... #UNDEF Preprocessor Directive
#IF ... #ENDIF Preprocessor Directive
#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive
Preprocessor Directives


#NAME Preprocessor Directive

Visual FoxPro 9.0 Language Reference
#NAME Preprocessor Directive
See Also

This screen and menu generator directive names a snippet produced by clauses such as SHOW, WHEN and VALID, whether the snippet is produced at the object or READ level.

#NAME SnippetName

Parameters

SnippetName

Specifies the name assigned to the snippet. SnippetName must conform to the rules for naming procedures and functions.

Remarks

The #NAME directive must appear at the top of a snippet, before any code statements. You can precede the #NAME directive with blank lines or comments.

Note:
Visual FoxPro does not check for duplicate names.

See Also

Other Resources

#DEFINE ... #UNDEF Preprocessor Directive
#IF ... #ENDIF Preprocessor Directive
#IFDEF | #IFNDEF ... #ENDIF Preprocessor Directive
Preprocessor Directives


Coverage Preprocessor Directives

Visual FoxPro 9.0 Language Reference
Coverage Preprocessor Directives
See Also

The following #DEFINE statements support this enhancement of Coverage Profiler.

*COV_LOCS.H

Added four #DEFINEs in the section handling wait window nowait/statusbar messages:

Copy Code
#DEFINE COV_LOADING_STACKINFO_LOC "Loading log for StackLevel analysis"
#DEFINE COV_GENERATING_STACKXML_LOC "Generating StackLevel XML..."
#DEFINE COV_WRITING_STACKXML_LOC "Writing StackLevel XML to disk"
#DEFINE COV_WRITING_TRANSFORM_LOC "Writing transformed file to disk"

Added four #DEFINEs to the shortcut prompts section:

Copy Code
#DEFINE COV_SC_STACKLEVEL_LOC "\<Generate StackLevel XML"
#DEFINE COV_SC_VIEW_STACKLEVEL_LOC "View Stac\<klevel XML"
#DEFINE COV_SC_STACK_TRANSFORM_LOC "\<Transform StackLevel XML"
#DEFINE COV_SC_STACKLEVEL_EXTENDED_LOC "E\<xtended StackLevel XML"

Added seven #DEFINEs to the section handling GETFILE/PUTFILE dialog titles, filters, and so on:

Copy Code
#DEFINE COV_SETSTACKXML_TITLE_LOC "Please specify location to save Coverage StackLevel XML for"
#DEFINE COV_XMLFILES_LOC "XML Files"
#DEFINE COV_XSLFILES_LOC "XSL Transforms"
#DEFINE COV_HTMFILES_LOC "HTML Files"
#DEFINE COV_SAVEDSTACKXML_AS_LOC "Your coverage stack analysis is saved as"
#DEFINE COV_SETTRANSFORMEDXML_TITLE_LOC "Please specify location to save transformed file for"
#DEFINE COV_GETXSLTFILE_TITLE_LOC "Please specify an XSL Transformation file"

Added three #DEFINES to the section handling options dialog prompts and captions:

Copy Code
#DEFINE COV_OPT_STACK_LOC "StackLevel XML analysis"
#DEFINE COV_OPT_STACK_EXTENDED_LOC "\<Generate extended StackLevel XML tree"
#DEFINE COV_OPT_STACK_XSLT_LOC "XSL \<Transform..."

COV_TUNE.H

New tunable settings (and associated comments) supporting the new feature:

Two settings are used for in tagname creation:

Copy Code
* the first two represent element node prefixes
#DEFINE COV_STACKROOT "VFPCallStackLog"
#DEFINE COV_STACK_ONEVENT_TAG event

* these are similar to COV_SKIPFILEDBF_SUFFIX and COV_TARGETDBF_SUFFIX

Copy Code
*the next items are used to help identify the XML and HTM files written to
* disk as being generated from this particular process.
#DEFINE COV_STACKXML_SUFFIX "_STACK"
#DEFINE COV_STACKXMLEXT_SUFFIX "_STACKX"
#DEFINE COV_TRANSFORM_SUFFIX "_XSL"

The following is a performance option that, like COV_TOPSPEED, is rarely needed.

Copy Code
* the next item indicates whether lines are loaded from the Coverage
* source workfile .dbf file or are gathered directly by from the original
* text log. Coverage Profiler has a very slight speed advantage but will
* not include ON ... events, since those lines are ignored by the
* Coverage source and target workfiles (there is no code
* to mark or profile for these lines).
#DEFINE COV_LOAD_STACK_FROM_DBF .F.

This definition provides an expression for the tags in the XML derived from the items available in the source log.

Copy Code
* the variables in the next item have the same meaning as the columns
* of the same name in the Coverage source workfile .dbf file
* -- equivalents for these items are read in from the source text log
* when COV_LOAD_STACK_FROM_DBF is .F., and this expression stays the same.
* You can change it as long as you ensure that the result will  be empty
* only for ON ... events.
* Load a log into COVERAGE.APP,
* SET DATASESSION TO _oCoverage.DataSessionID, and refer to the
* source workfile (by default, its alias is FromLog) for some indication
* on the possible contents of these columns.
#DEFINE COV_STACKEXPR ALLTR(IIF(INLIST(FileType,".fxp",".mpx",".qpx",".spx"), ;
                      IIF(EMPTY(ObjClass), ;
                      IF(NOT EMPTY(Executing),ALLTR(Executing),""),;
                      IIF(LEFT(Executing,1)=".",ALLTR(ObjClass),"")+ALLTR(Executing)), ;
                      ALLTR(Executing)))

See Also

Other Resources

Preprocessor Directives
Coverage Profiler Application


System Variables Overview

Visual FoxPro 9.0 Language Reference
System Variables Overview
See Also

System variables are built-in variables that Visual FoxPro creates and maintains automatically. They are designated as PUBLIC by default, but you can declare them as PRIVATE.

Note:
Recent Visual FoxPro features have replaced the functionality of many system variables. For more information, see the description for each system variable and Backward-Compatible Language Elements.

The following table lists the types of Visual FoxPro system variables and their designation in expressions.

Variable type | Description | Expression
C | Character | cExpression
D | Date | dExpression
L | Logical | lExpression
N | Numeric | nExpression
O | Object | oExpression

The following table lists all system variables, their types, and default values.

Variable | Type | Default value
_ALIGNMENT | C | LEFT
_ASCIICOLS | N | 80
_ASCIIROWS | N | 63
_ASSIST | C | Empty string
_BEAUTIFY | C | Empty string
_BOX | L | .T.
_BROWSER | C | Browser.app
_BUILDER | C | Builder.app
_CALCMEM | N | 0.0
_CALCVALUE | N | 0.0
_CLIPTEXT | C | Empty string
_CONVERTER | C | Empty string
_COVERAGE | C | Coverage.app
_CUROBJ | N | -1
_DBLCLICK | N | 0.5
_DIARYDATE | D | Current date
_DOS | L | .T. in FoxPro for MS-DOS
_FOXDOC | C | Empty string
_FOXREF | C | FoxRef.app
_GALLERY | C | Gallery.app
_GENGRAPH | C | Empty string
_GENHTML | C | Genhtml.prg
_GENMENU | C | Genmenu.prg
_GENPD | C | Empty string
_GENSCRN | C | Genscrn.prg
_GENXTAB | C | Empty string
_GETEXPR | C | Empty string
_INCLUDE | C | Empty string
_INCSEEK | N | .5
_INDENT | N | 0
_LMARGIN | N | 0
_MAC | L | .T. in Visual FoxPro for Macintosh
_MENUDESIGNER | C | Empty string
_MLINE | N | 0
_PADVANCE | C | FORMFEED
_PAGENO | N | 1
_PAGETOTAL | N | 0
_PBPAGE | N | 1
_PCOLNO | N | Current column
_PCOPIES | N | 1
_PDRIVER | C | Empty string
_PDSETUP | C | Empty string
_PECODE | C | Empty string
_PEJECT | C | NONE
_PEPAGE | N | 32767
_PLENGTH | N | 66
_PLINENO | N | 0
_PLOFFSET | N | 0
_PPITCH | C | DEFAULT
_PQUALITY | L | .F.
_PRETEXT | C | Empty string
_PSCODE | C | Empty string
_PSPACING | N | 1
_PWAIT | L | .F.
_RMARGIN | N | 80
_REPORTBUILDER | C | HOME() + "REPORTBUILDER.APP"
_REPORTOUTPUT | C | HOME() + "REPORTOUTPUT.APP"
_REPORTPREVIEW | C | HOME() + "REPORTPREVIEW.APP"
_SAMPLES | C | HOME() + "SAMPLES"
_SCCTEXT | C | Scctext.prg
_SCREEN | O | FORM
_SHELL | C | Empty string
_SPELLCHK | C | Spellchk.app
_STARTUP | C | Empty string
_TABS | C | Empty string
_TALLY | N | 0
_TASKPANE | C | Taskpane.app
_TEXT | C | –1
_THROTTLE | N | 0
_TOOLBOX | C | Toolbox.app
_TOOLTIPTIMEOUT | N | -1
_TRANSPORT | C | Empty string
_TRIGGERLEVEL | N | 0
_UNIX | L | .T. in FoxPro for UNIX
_VFP | O | Microsoft Visual FoxPro
_WINDOWS | L | .T. in Visual FoxPro for Windows
_WIZARD | C | Wizard.app
_WRAP | L | .F.

See Also

Other Resources

PUBLIC Command
PRIVATE Command
STORE Command


_ASCIICOLS System Variable

Visual FoxPro 9.0 Language Reference
_ASCIICOLS System Variable
See Also

Specifies the number of columns in an ASCII text file created with the ASCII keyword in the REPORT FORM command.

_ASCIICOLS = nExpression

Parameters

nExpression

Specifies the number of columns in the text file to create. The default value is 80.

See Also

Other Resources

REPORT Command
_ASCIIROWS Command
CREATE REPORT Command
MODIFY REPORT Command
System Variables A-Z
System Variables Overview


_ASCIIROWS System Variable

Visual FoxPro 9.0 Language Reference
_ASCIIROWS System Variable
See Also

Specifies the number of rows in an ASCII text file created with the ASCII keyword in the REPORT FORM command.

_ASCIIROWS = nExpression

Parameters

nExpression

Specifies the number of rows in the text file to create. The default value is 63.

See Also

Other Resources

REPORT Command
_ASCIICOLS Command
CREATE REPORT Command
MODIFY REPORT Command
REPORT Command
System Variables A-Z
System Variables Overview


_BEAUTIFY System Variable

Visual FoxPro 9.0 Language Reference
_BEAUTIFY System Variable
See Also

Specifies the beautification application for Visual FoxPro programs and runs when you choose the Beautify command on the Tools menu.

_BEAUTIFY = cProgramName, aOptions

Parameters

cProgramName

Specifies a beautification application. If your beautification application is in a directory other than the current default directory, include a path with the application name. You can also specify a beautification application in your configuration file by including a line using this syntax:
Copy Code
_BEAUTIFY = cProgramName
Note that your beautification application must accept a single parameter, the name of the program to beautify. Your beautification application can modify the program, write the modifications to a temporary file, and then return the name of the temporary file to FoxPro. FoxPro reads the temporary file back into the editing session under the original FoxPro program name and then deletes the temporary file.
aOptions

Internal use only

Remarks

The Beautify command appears on the Tools menu when you open a program or text file in an editing window.

See Also

Other Resources

Documenting Wizard
Beautify Options Dialog Box
System Variables Overview
Language Reference


_BROWSER System Variable

Visual FoxPro 9.0 Language Reference
_BROWSER System Variable
See Also

Specifies the name of the class browser application to use for browsing classes.

_BROWSER = cProgramName

Parameters

cProgramName

Specifies the name of a class browser application. By default, _BROWSER is set to Browser.app, which is installed in the same directory as Visual FoxPro. For more information, see Operating the Class Browser.
Note:
If the class browser is in a directory or folder other than the current default directory or folder, include a path when specifying the class browser application name.

See Also

Other Resources

System Variables Overview


_BUILDER System Variable

Visual FoxPro 9.0 Language Reference
_BUILDER System Variable
See Also

Contains the name of the Visual FoxPro builder application.

_BUILDER = cProgramName

Parameters

cProgramName

Specifies a builder application. If your builder application is in a directory other than the current Visual FoxPro default directory, include a path with the application name.

Remarks

The _BUILDER system variable contains the name of the application that Visual FoxPro uses when you choose a builder in the Form Designer. By default, _BUILDER contains BUILDER.APP, installed in your Visual FoxPro directory. You can specify a different name for the builder application.

See Also

Other Resources

System Variables Overview
How to: Add Visual FoxPro Controls to a Form
Form Designer


_CALCMEM System Variable

Visual FoxPro 9.0 Language Reference
_CALCMEM System Variable
See Also Example

Contains the numeric value that Microsoft Visual FoxPro stores in the Calculator's memory.

_CALCMEM = nCalculatorValue

Parameters

nCalculatorValue

Specifies the numeric value that _CALCMEM stores in memory.

Remarks

You can save the result of a calculation in the Calculator's memory and return the result to a program, or you can place a specific value in the Calculator's memory before using the Calculator.

To initialize the Calculator's memory, store a numeric value to _CALCMEM with STORE or the = assignment operator. When you use the Calculator, its memory contains the value you specified.

Example

The following program example stores the numeric constant 1234 to _CALCMEM. The program then displays the Calculator and stuffs the keyboard with the letter R. The keystroke R displays the value stored in the Calculator's memory.
Copy Code
STORE 1234 TO _CALCMEM
ACTIVATE WINDOW calculator
CLEAR TYPEAHEAD
KEYBOARD CHR(82)

See Also

Other Resources

ACTIVATE WINDOW Command
_CALCVALUE System Variable
STORE Command
CALCULATE Command
System Variables Overview
Language Reference


_CALCVALUE System Variable

Visual FoxPro 9.0 Language Reference
_CALCVALUE System Variable
See Also Example

Contains the numeric value that the Calculator displays.

_CALCVALUE = nCalculatorDisplayValue

Parameters

nCalculatorDisplayValue

Specifies the numeric value that the Calculator displays.

Remarks

You can return the result of a calculation to a program or you can place a specific value in the Calculator's display before using the Calculator.

To initialize the Calculator's display, store a numeric value to _CALCVALUE with STORE or the = assignment operator. When you use the Calculator, it displays the value you specified.

Example

In the following example, the numeric value 1234 is stored to _CALCVALUE. The Calculator then displays the value 1234.
Copy Code
STORE 1234 TO _CALCVALUE
ACTIVATE WINDOW calculator

See Also

Other Resources

ACTIVATE WINDOW Command
_CALCMEM
STORE Command
CALCULATE Command
Display Calculated Values in a Column


_CLIPTEXT System Variable

Visual FoxPro 9.0 Language Reference
_CLIPTEXT System Variable
See Also Example

Contains the contents of the Clipboard.

_CLIPTEXT = cExpression

Parameters

cExpression

Specifies the character expression to store in the Clipboard.

Remarks

You can place a character expression cExpression on the Clipboard with STORE or the = assignment operator.

Example

These examples will put long pathnames on the clipboard.

Copy Code
_cliptext=_vfp.ServerName

or

Copy Code
_cliptext=getfile()

See Also

Other Resources

PRIVATE Command
PUBLIC Command
STORE Command
Text Editor and Clipboard Manipulation Routines
= Command
DataToClip Method
System Variables Overview
Language Reference


_CODESENSE System Variable

Visual FoxPro 9.0 Language Reference
_CODESENSE System Variable
See Also

Contains the name of the application that provides functionality for the IntelliSense Manager.

_CODESENSE = [cFilename]

Parameters

cFilename

Specifies the name of the Visual FoxPro application that provides functionality for the IntelliSense Manager. By default, _CODESENSE specifies FoxCode.app, located in the Windows user application folder or HOME( ) directory.

See Also

Other Resources

Visual FoxPro IntelliSense Manager Window
IntelliSense Overview
System Variables


_CONVERTER System Variable

Visual FoxPro 9.0 Language Reference
_CONVERTER System Variable
See Also

Contains the name of the Microsoft Visual FoxPro converter application.

_CONVERTER = cProgramName

Parameters

cProgramName

Specifies a converter application. If your converter application is in a directory other than the current Visual FoxPro default directory, include a path with the application name. You can also specify a converter application in your Visual FoxPro configuration file by including a line using the following syntax:
Copy Code
_CONVERTER = cProgramName

Remarks

The _CONVERTER system memory variable contains the name of the application that Visual FoxPro uses when you attempt to open a screen, report, or project created in an earlier FoxPro version. By default, _CONVERTER contains Convert.app, installed in your Visual FoxPro directory. You can specify a different name for the converter application.

See Also

Reference

Specifying the Configuration File to Use

Other Resources

Visual FoxPro Converter Dialog Box
System Variables Overview
Language Reference


_COVERAGE System Variable

Visual FoxPro 9.0 Language Reference
_COVERAGE System Variable
See Also

Contains the name of the Visual FoxPro application that creates the Debugger coverage and profiler output.

_COVERAGE = cProgramName

Parameters

cProgramName

Specifies a coverage output application. If your coverage output application is in a directory other than the current Visual FoxPro default directory, include a path with the application name. You can also specify a coverage output application in your Visual FoxPro configuration file by including a line using this syntax:
Copy Code
_COVERAGE = cProgramName

Remarks

By default, _COVERAGE contains Coverage.app, installed in your Visual FoxPro directory. You can specify a different name for the coverage output application.

See Also

Other Resources

SET COVERAGE Command
SET EVENTTRACKING Command
Coverage Profiler Modification
Coverage Profiler Application
System Variables Overview
Language Reference


_DBLCLICK System Variable

Visual FoxPro 9.0 Language Reference
_DBLCLICK System Variable
See Also

Specifies the time interval between double and triple mouse clicks.

_DBLCLICK = nTicks

Parameters

nTicks

Specifies the time interval in seconds. Internal timing is measured in clock "ticks," which are each about 1/18th of a second. If you store an integer or decimal value to _DBLCLICK, Visual FoxPro may store it as a slightly different value due to rounding to ticks. At the startup of Visual FoxPro, the double-click setting in the Windows Mouse Properties Control Panel determines the _DBLCLick default value. _DBLCLICK can range from 0.05 to 5.5 seconds (1 to 100 ticks). _DBLCLICK applies to double click rate only and not to incremental search key capture period as in versions of Visual FoxPro prior to version 7.

Remarks

The _DBLCLICK setting overrides the setting specified in the Windows Mouse Control Panel.

_DBLCLICK contains a numeric value that determines the time interval Visual FoxPro uses to check for a double or triple mouse click. _DBLCLICK is the time interval between mouse clicks. For example, if _DBLCLICK is set to 0.5 seconds, you have one half second to click twice for a double-click, and 1 second to click three times for a triple-click.

The larger the value of _DBLCLICK, the longer you can wait between the first and second click for Visual FoxPro to interpret the two clicks as a double-click. If _DBLCLICK is set to a very small value, even quick double-(or triple-) clicks may be interpreted as two (or three) single clicks.

See Also

Other Resources

INKEY( ) Function
DblClick Event
MouseUp Event
MouseDown Event
Click Event
_INCSEEK System Variable
System Variables Overview
Language Reference


_DIARYDATE System Variable

Visual FoxPro 9.0 Language Reference
_DIARYDATE System Variable
See Also Example

Contains the current date in the Calendar/Diary.

_DIARYDATE = dExpression

Parameters

dExpression

Specifies the date for the Calendar/Diary.

Remarks

With _DIARYDATE, you can display the Calendar/Diary with a specific date selected, or you can return the selected Calendar/Diary date.

By default, the current date is stored in _DIARYDATE. When you open the Calendar/Diary, the current date is selected. You can store a different date to _DIARYDATE so that the Calendar/Diary opens with this new date selected.

Selecting a new date when the Calendar/Diary is open causes the new date to be stored to _DIARYDATE. When you close the Calendar/Diary, _DIARYDATE contains the last selected date.

Example

In the following program example, the Calendar/Diary opens with March 28, 2001, selected and the value of _DIARYDATE appears below. July 4, 1776, is then stored to _DIARYDATE and _DIARYDATE displays again. The program then uses the DATE( ) function to select the current date, and displays _DIARYDATE.
Copy Code
SET CENTURY ON
STORE {^2001-03-28} TO _DIARYDATE
=MESSAGEBOX(DTOC(_DIARYDATE),64)
ACTIVATE WINDOW calendar
=MESSAGEBOX("Change date to July 4, 1776",48))
STORE {^1776-07-04} TO _DIARYDATE
=MESSAGEBOX(DTOC(_DIARYDATE),64)
=MESSAGEBOX("Change date to today's date",48)
STORE DATE( ) TO _DIARYDATE
=MESSAGEBOX(DTOC(_DIARYDATE),64)
RELEASE WINDOW calendar

See Also

Other Resources

STORE Command
Add a Data-Bound Calendar Sample
SET CENTURY Command
ACTIVATE WINDOW Command
System Variables Overview
Language Reference


_DOS System Variable

Visual FoxPro 9.0 Language Reference
_DOS System Variable
See Also

Included for backward compatibility. Always returns false (.F.) in Visual FoxPro.

See Also

Other Resources

_MAC System Variable
_UNIX System Variable
VERSION( )
_WINDOWS System Variable
System Variables Overview
Language Reference


_FOXCODE System Variable

Visual FoxPro 9.0 Language Reference
_FOXCODE System Variable
See Also

Specifies the name of the table file used for Visual FoxPro IntelliSense.

_FOXCODE [= cDBFFileName]

Parameters

cDBFFileName

Specifies the name of the file containing the table that defines IntelliSense functionality. By default, _FOXCODE specifies a file named FoxCode.dbf, which is stored in your Windows user application folder or HOME(1) location.

Remarks

Like the resource file FoxUser.dbf, FoxCode.dbf opens at Visual FoxPro startup.

For information about accessing information in FoxCode.dbf, see Customizing IntelliSense in Visual FoxPro.

See Also

Other Resources

HOME( ) Function
System Variables Overview


_FOXREF System Variable

Visual FoxPro 9.0 Language Reference
_FOXREF System Variable
See Also

Contains the name of the application that provides the Code References tool.

_FOXREF = cFoxRefApplication

Parameters

cFoxRefApplication

Specifies the name of the Visual FoxPro program used to handle Code Reference searches.

Remarks

By default, the _FOXREF system variable points to the following file:

HOME( ) + "FoxRef.app"

You can change this setting in the File Locations tab of the Options dialog box.

You can call this application directly as follows:

Copy Code
DO (_FOXREF) WITH oAction

oAction is an object with the following properties: Mode, Word, FileName, LineNo, Class, Proc, and hWnd. Refer to the FoxRef source in the Tools/XSource directory for more information about how these parameters should be populated.

See Also

Other Resources

System Variables
DO Command
File Locations Tab, Options Dialog Box
Look Up Reference Dialog Box
Code References Window
How to: View Code Definitions


_FoxTask System Variable

Visual FoxPro 9.0 Language Reference
_FoxTask System Variable
See Also Example

Specifies the name of the FOXTASK table that supports Visual FoxPro Task Manager.

_FoxTask [= cDBFFileName]

Parameters

cDBFFileName

Specifies the name of the file to be used by the Visual FoxPro Editor and the Task List Manager to store Tasklist Shortcuts.

Remarks

By default, the file is named foxtask.dbf and stored in your Windows user application folder or HOME( ) location. The following table describes the structure of foxtask.dbf

Field Name | Type | Width | Description
UNIQUEID | C | 10 | Specifies the Visual FoxPro Unique ID
TIMESTAMP | N | 10 | Specifies the Visual FoxPro timestamp
FILENAME | M | 4 | Specifies file name
CLASS | M | 4 | Specifies the class name (.vcx, .scx)
METHOD | M | 4 | Method name (.vcx, .scx)
LINE | N | 6 | Specifies the line number
CONTENTS | M | 4 | Specifies the contents of the line
TYPE | C | 1 | "S" – for shortcut; others can be user-defined
DUEDATE | D | 8 | User-defined Date due
PRIORITY | N | 1 | Specifies a user-defined priority setting for the item 0 = low1 = medium2 = high
STATUS | N | 1 | Completion state of a task 0 = not completed1 = completed

You can specify a different name for the tasklist table by using the FoxTask property as in the following example:

Example

Copy Code
_FOXTASK = MyTasks.dbf

See Also

Other Resources

_TASKLIST System Variable
System Variables Overview
Language Reference


_GALLERY System Variable

Visual FoxPro 9.0 Language Reference
_GALLERY System Variable
See Also

Specifies the program that is executed when you choose Component Gallery from the Tools menu.

_GALLERY = ProgramName

Parameters

ProgramName

Specifies a program. If your program is in a directory other than the current default directory, include a path with the program name.

Remarks

_GALLERY contains GALLERY.APP by default.

See Also

Other Resources

Using the Component Gallery
System Variables A-Z
System Variables Overview


_GENHTML System Variable

Visual FoxPro 9.0 Language Reference
_GENHTML System Variable
See Also

Specifies an HTML (Hypertext Markup Language) generation program.

_GENHTML = ProgramName

Parameters

ProgramName

Specifies a program that generates HTML. If your HTML generation program is in a directory other than the current default directory, include a path with the program name.

Remarks

_GENHTML contains Genhtml.prg by default. Genhtml.prg is executed when you choose Save As HTML from the File menu. A text file that contains a hypertext markup language version of the form, menu, report, or table is created. The Save As HTML option is available only when the Form, Menu, or Report designers are active and the form, menu, or report has been saved, or when a Browse window is open.

See Also

Other Resources

CREATE FORM Command
CREATE MENU Command
CREATE REPORT Command
USE Command
System Variables Overview
Language Reference


_GENMENU System Variable

Visual FoxPro 9.0 Language Reference
_GENMENU System Variable
See Also

Specifies a menu generation program.

_GENMENU = ProgramName

Parameters

ProgramName

Specifies a program that previous versions used to generate menu code from an .mnx menu definition table. If your program is in a directory other than the current default directory, include a path with the program name.

Remarks

_GENMENU contains Genmenu.prg by default. A directive (#IMAGEPATHS) controls if full paths are generated for menu images.

See Also

Other Resources

CREATE MENU Command
_GENSCRN System Variable
System Variables A-Z
Language Reference


_GETEXPR System Variable

Visual FoxPro 9.0 Language Reference
_GETEXPR System Variable
See Also

Specifies the program that is executed when you issue the GETEXPR command or invoke the Expression Builder dialog box from within Visual FoxPro.

_GETEXPR = ProgramName

Parameters

ProgramName

Specifies a program that is executed when you issue the GETEXPR command or invoke the Expression Builder dialog box from within Visual FoxPro. If your program is in a directory other than the current default directory, include a path with the program name.

Remarks

_GETEXPR contains the empty string by default; the empty string indicates that the standard Visual FoxPro Expression Builder dialog box is displayed when the GETEXPR command is executed or when you invoke the Expression Builder dialog box from within Visual FoxPro.

You can create your own Expression Builder program that is executed when the GETEXPR command is executed or when you invoke the Expression Builder dialog box from within Visual FoxPro. Your Expression Builder program must contain an LPARAMETERS or PARAMETERS statement as the first executable line of the program to accept four parameters that Visual FoxPro passes to the program. The parameters are listed below in the order they are passed:

Parameter | Description
cExpressionType | Specifies the expression type.
cErrorMessageText | Specifies the error message displayed if the expression isn't valid.
cDefaultExpression | Specifies the initial default expression in the Expression Builder.
cCaptionText | Specifies the caption that appears in the Expression Builder.

For example, the following could be the first executable line of your Expression Builder program:

Copy Code
LPARAMETERS cExpressionType, cErrorMessageText, ;
   cDefaultExpression, cCaptionText

If your Expression Builder program is executed when the Expression Builder dialog box is invoked from within Visual FoxPro, the first three parameters contain the empty string and the fourth parameter contains cCaptionText, the caption that appears in the Expression Builder.

Note that the Visual FoxPro Expression Builder is a modal dialog. Your Expression Builder program should set its form properties to the following values to create a modal dialog:

Form property | Property value
AlwaysOnTop | True (.T.)
Desktop | True (.T.)
WindowType | 1 – Modal

See Also

Other Resources

GETEXPR Command
LPARAMETERS Command
PARAMETERS Command
System Variables A-Z
Language Reference


_INCLUDE System Variable

Visual FoxPro 9.0 Language Reference
_INCLUDE System Variable
See Also

Specifies a default header file included with user-defined classes, forms, or form sets.

_INCLUDE = HeaderFileName

Parameters

HeaderFileName

Specifies a default header file of predefined compile-time constants automatically included with user-defined classes, forms, or form sets. If your header file is in a directory other than the current default directory, include a path with the header file name. Contains the empty string by default.

Remarks

You can also specify the default header file with the Default Include File item in the File Locations tab of the Options dialog box.

See Also

Other Resources

CREATE CLASS Command
CREATE FORM Command
File Locations Tab, Options Dialog Box
#INCLUDE Preprocessor Directive
System Variables A-Z


_INCSEEK System Variable

Visual FoxPro 9.0 Language Reference
_INCSEEK System Variable
See Also

Specifies the time interval that is open for keystrokes within an incremental seek such as within a Listbox or ComboBox control.

_INCSEEK = nTicks

Parameters

nTicks

Specifies the time interval in seconds. Internal timing is measured in clock "ticks," which are each about 1/18th of a second. If you store an integer or decimal value to _INCSEEK, Visual FoxPro may store it as a slightly different value due to rounding to ticks. _INCSEEK can range from 0.05 to 5.5 seconds (1 to 100 ticks).

Remarks

Applies To: IncrementalSearch Property

In earlier versions of Visual FoxPro, the value for _DBLCLICK also determined the incremental search interval. The default value for _INCSEEK is 0.50.

See Also

Other Resources

_DBLCLICK System Variable
System Variables A-Z
System Variables Overview


_MAC System Variable

Visual FoxPro 9.0 Language Reference
_MAC System Variable
See Also

Included for backward compatibility. Always returns False (.F.) in Visual FoxPro.

See Also

Other Resources

_DOS System Variable
_UNIX System Variable
VERSION( ) Function
_WINDOWS System Variable


_MENUDESIGNER System Variable

Visual FoxPro 9.0 Language Reference
_MENUDESIGNER System Variable
See Also

Specifies an external application for creating menus.

_MENUDESIGNER = cProgramName

Parameters

cProgramName

Specifies the file name for the external menu designer. If the application is in a directory other than the current default directory, include the path with the application name. You can also specify the application in your Visual FoxPro Config.fpw configuration file by including a line using this syntax:
Copy Code
_MENUDESIGNER = cProgramName
If _MENUDESIGNER contains the default empty string, the Visual FoxPro menu designer is opened.

Remarks

The application specified in _MENUDESIGNER runs during an interactive design-time Visual FoxPro session. The application is executed when you choose Menu from the New Dialog Box, new Menu from the Project Manager, execute CREATE MENU, MODIFY MENU, or EDITSOURCE( ) in the Command window or a program, or call the Modify method for a file object accessed via a ProjectHook object.

Note:
When an external menu designer runs, the menu items normally associated with the Visual FoxPro designers are not available.

An external menu designer must include a PARAMETERS statement to accept three parameters that Visual FoxPro passes to the application.

Parameter Description

cFileName

A character type parameter that contains the file name of the menu to be opened in the menu design application.

If CREATE MENU menuname is issued to run the menu designer, cFileName contains the menuname with a fully qualified path to the file's location.

If CREATE MENU is issued without a menuname, the New Menu dialog box is displayed. After the user chooses a Menu or Shortcut Menu option, the menu design application is run and cFileName contains an internally generated menu name Menu1, Menu2, and so on. The menu name is incremented each time CREATE MENU is issued without a menuname.

If CREATE MENU ? is issued to run the menu design application, a dialog box is displayed allowing the user to specify a menu name. When the user enters a menu name and chooses Save, the NewMenu dialog box is displayed. After the user chooses a Menu or Shortcut Menu option, cFileName contains the user's menu name with a fully qualified path to the file's location.

nCommandType

A numeric type parameter that indicates the how the menu design application was invoked.

nCommandType | Description
1 | The Menu option was chosen in the New Menu dialog box.
2 | The Shortcut option was chosen in the New Menu dialog box.
3 | The MODIFY MENU command was used to invoke the menu design application. The cFileName parameter contains the name of the menu specified in MODIFY MENU with a fully qualified path to the file's location.

aDetail

An array with additional information about the command that invoked the menu design application.

An array is only created if the menu design application is invoked by choosing new Menu from the Project Manager, or by issuing CREATE MENU or MODIFY MENU with the optional NOWAIT, SAVE, WINDOW or IN clauses.

When no array is created, the third parameter is a memory variable containing a logical false (.F.).

When the menu design application is invoked by choosing new Menu from the Project Manager, a two element array is created. The first element of the array contains "PROJECT." The second element contains the name of the project with a fully qualified path to the file's location.

When the menu design application is invoked by issuing CREATE MENU or MODIFY MENU with the optional NOWAIT, SAVE, WINDOW or IN clauses, the array contains a row for each clause. Each row in the array has two elements.

The following table describes the contents of each of the two elements.

1st Element | 2nd Element
NOWAIT | Contains a logical true (.T.).
SAVE | Contains a logical true (.T.).
WINDOW | Contains the name of the window specified in the WINDOW clause.
IN | Contains SCREEN or the name of the specified window.

The external menu designer should return a logical true (.T.) if the application successfully creates the user's menu. If a logical false (.F.) is returned, the Visual FoxPro Menu Designer is opened.

See Also

Reference

CREATE MENU Command
MODIFY MENU Command
EDITSOURCE( ) Function
Modify Method
Project Manager Window


_MLINE System Variable

Visual FoxPro 9.0 Language Reference
_MLINE System Variable
See Also

Contains the memo field offset for the MLINE( ) function.

_MLINE = nNumberOfCharacters

Parameters

nNumberOfCharacters

Specifies the memo field offset. For more information about the use of _MLINE and an example of its use, see MLINE( ).

Remarks

MLINE( ) returns one line of text from a memo field. MLINE( ) stores the location of its memo field offset to the _MLINE system variable. Use _MLINE as the second numeric argument in the MLINE( ) function to increase the performance of MLINE( ).

The startup default value for _MLINE is 0. Be sure to reset _MLINE to 0 before using _MLINE again with the MLINE( ) function.

See Also

Other Resources

System Variables
ALINES( ) Function
MEMLINES( ) Function
MLINE( ) Function
SET MEMOWIDTH Command


_ObjectBrowser System Variable

Visual FoxPro 9.0 Language Reference
_ObjectBrowser System Variable
See Also

Contains the name of the object browser application.

_ObjectBrowser = cObjectBrowserApplication

Parameters

cObjectBrowserApplication

Specifies the name of the Visual FoxPro program that makes it possible for you to view COM type libraries.

Remarks

By default, _ObjectBrowser contains objectbrowser.app, installed in your Windows user application folder or HOME( ) location. You can specify a different name for the object browser application.

See Also

Other Resources

System Variables Overview
Object Browser
How to: Use the Object Browser


_PAGENO System Variable

Visual FoxPro 9.0 Language Reference
_PAGENO System Variable
See Also

Contains the current page number.

_PAGENO = nCurrentPageNumber

Parameters

nCurrentPageNumber

Specifies a numeric value from 1 to 32,767 for the current page number. _PAGENO, _PBPAGE and _PEPAGE work in unison. If _PAGENO is set (or incremented) such that it falls outside the range of _PBPAGE to _PEPAGE, no pages are printed.

Remarks

_PAGENO contains a numeric value that determines the current page number. The startup default is 1. _PAGENO allows you to print page numbers in streaming output without defining, initializing, and incrementing a memory variable for that purpose.

See Also

Other Resources

System Variables
ON PAGE Command
_PBPAGE System Variable
_PEPAGE System Variable
_PLENGTH System Variable
_PLINENO System Variable
_PAGETOTAL System Variable


_PAGETOTAL System Variable

Visual FoxPro 9.0 Language Reference
_PAGETOTAL System Variable
See Also Example

Contains the total number of pages in a report.

You can use _PAGETOTAL to set up "Page X of Y" numbering in reports. _PAGETOTAL is supported in both development and run-time versions of Visual FoxPro and in all reporting operations, including REPORT FORM...TO FILE...ASCII and with optional arguments such as RANGE.

_PAGETOTAL [ = nValue ]

Parameters

nValue

Specifies a positive number representing the total number of pages in a report.

Remarks

You can set _PAGETOTAL at any time. Visual FoxPro evaluates and updates _PAGETOTAL only when a report operation such as REPORT FORM occurs. At the beginning of the report operation, Visual FoxPro initializes _PAGETOTAL to a value of 0, regardless of whether _PAGETOTAL is used on the report.

If you include _PAGETOTAL anywhere in a Visual FoxPro report, Visual FoxPro performs two passes through the report. The first pass is not visible or printed and calculates the _PAGETOTAL variable. During the first pass, _PAGETOTAL is set to a value of -1.

For performance reasons, you can suppress a two-pass report by not calling _PAGETOTAL in a print preview using an expression such as the following:

Copy Code
TRANS(_PAGENO) + IIF(SYS(2040)="1", "", " OF " + TRANS(_PAGETOTAL))

If you do not include a reference to _PAGETOTAL in the report, Visual FoxPro sets the value of _PAGETOTAL to the total number of pages at the end of printing and performs only one pass through the report.

You can force a second pass through the report using an expression such as the following:

Copy Code
IIF( _PAGETOTAL = 0, "","" )

Initiating another pass allows for additional operations using report variables such as reporting % of the total number of pages.

Tip:
For a second pass to occur, in previous versions of Visual FoxPro, you needed a reference to _PAGETOTAL in the report layout. In Visual FoxPro 9.0, you can also use a ReportListener reference on your REPORT FORM command. By setting the ReportListener's TwoPassProcess property to .T. before a report run, you can force the report to perform two passes, even if you have not used _PAGETOTAL in any expressions in the report. For more information, see TwoPassProcess Property.

The value of _PAGETOTAL should equal the value of _PAGENO at the end of printing a report, regardless whether the report includes _PAGETOTAL.

Example

The following example illustrates how to include "Page X of Y" numbering in your report by using the _PAGETOTAL system variable and adding the following expression in the report textbox:
Copy Code
"Page " + TRANS(_PAGENO) + " of " + TRANS( _PAGETOTAL)

See Also

Reference

ReportListener Object Properties, Methods, and Events
REPORT FORM Command

Other Resources

System Variables Overview
_PAGENO System Variable


_PRETEXT System Variable

Visual FoxPro 9.0 Language Reference
_PRETEXT System Variable
See Also

Specifies a character expression to preface text merge lines.

_PRETEXT = cExpression

Remarks

Used with SET TEXTMERGE, you can merge text within a program. You can output lines of text, the contents of variables, and the results of expressions and functions to the screen, a window, a printer, a text file, or a low-level file.

If you store a character expression to _PRETEXT, the character expression is added to the beginning of the output text line. To facilitate program indentation, you can store a tab or tabs to _PRETEXT.

See Also

Other Resources

\ | \\ Command
SET TEXTMERGE Command
_TEXT System Variable


_REPORTBUILDER System Variable

Visual FoxPro 9.0
_REPORTBUILDER System Variable
See Also Example

Specifies the application used by the Report Designer to handle builder events.

For more information on report builders, see How to: Extend or Replace the Report Builder

_REPORTBUILDER = cProgramName

Parameters

cProgramName

Specifies the name of an application or program that the Report Designer calls when a builder event occurs. You can also specify an empty string (""), which causes dialog boxes to appear as in versions prior to Visual FoxPro 9.0.
Note:
If the application is located in a directory other than the current default directory, include a path name with the program name.

Remarks

By default, _REPORTBUILDER specifies the path and file name for the ReportBuilder.app located in the main Visual FoxPro directory.

You can also specify a builder application file using the File Locations tab in the Options dialog box. For more information, see File Locations Tab, Options Dialog Box.

The application you specify with _REPORTBUILDER must be modal in operation, accept parameters passed to it from the Report Designer and return appropriate values for the first parameter, which is passed by reference.

Visual FoxPro does not generate an error if it does not locate an application for _REPORTBUILDER. The Report Designer raises builder events only if you specify a valid application or program file.

Note:
When distributing report builders with your applications, you may find it convenient to explicitly set _REPORTBUILDER in the Visual FoxPro configuration file, Config.fpw. For more information, see Including Report Files for Distribution and Setting Configuration Options at Startup.

Example

The following line of code sets the _REPORTBUILDER system variable to the default Report Builder application:
Copy Code
_REPORTBUILDER = HOME(1)+"ReportBuilder.app"

See Also

Tasks

How to: Extend or Replace the Report Builder

Reference

System Variables
System Variables Overview


_REPORTOUTPUT System Variable

Visual FoxPro 9.0
_REPORTOUTPUT System Variable
See Also Example

Specifies the Visual FoxPro handler application providing ReportListener derived classes to be used with the REPORT FORM command, maintaining a registry of ReportListener derived classes for different output results.

_REPORTOUTPUT = cProgramName

Parameters

cProgramName

Specifies the name of an application or program that the Visual FoxPro Report System calls when a suitable REPORT FORM command occurs.

Remarks

The Visual FoxPro Report System invokes the application specified by this value when one of the following conditions occur:

  • You invoke the REPORT FORM or LABEL command with an explicit OBJECT TYPE<N> clause. The Report Engine passes the numeric value you use to the application named in _REPORTOUTPUT.

  • You invoke a REPORT FORM command after having used the command SET REPORTBEHAVIOR 90. This setting indicates that you want to use object-assisted mode for all REPORT FORM or LABEL commands. The Report Engine uses the other keywords on the output command (such as TO PRINT or PREVIEW) to establish the appropriate numeric value for the equivalent OBJECT TYPE<N> clause.

In both scenarios, the Report Engine also passes a variable to the application specified in _REPORTOUTPUT. The application stores a reference to an appropriate ReportListener object to this variable. In the subsequent report or label processing run, the Report Engine partners with this object to handle output rendering.

By default, _REPORTOUTPUT specifies the path and file name for the ReportOutput.app located in the main Visual FoxPro directory, as indicated by the HOME() function.

You can also specify a report output application using the File Locations tab in the Options dialog box. For more information, see File Locations Tab, Options Dialog Box.

When distributing applications, you may find it convenient to explicitly set _REPORTOUTPUT in the Visual FoxPro configuration file, Config.fpw. You can also set the _REPORTOUTPUT value to the name of a program built into your application. For more information, see Including Report Files for Distribution and Setting Configuration Options at Startup.

Note:
If you use a REPORT FORM or LABEL command and include the OBJECT TYPE <N> clause, or have previously used the command SET REPORTBEHAVIOR 90, without a valid value in _REPORTOUTPUT, Visual FoxPro generates an error.

Requirements

The application you specify with _REPORTOUTPUT must fulfill the following conditions:

  1. It must accept at least two parameters. The Report Engine passes a numeric value, indicating the type of output required, as the first parameter. The Report Engine passes a variable, to hold a reference to an appropriate ReportListener, as the second parameter.

  2. It must store a NULL value (.NULL.) to the second parameter if it cannot understand the value in the first parameter, or does not have the ability to supply a reference to a ReportListener-derived object meeting the requirements of the first parameter.

  3. It must be able to provide ReportListener-derived object references for (at minimum) numeric types matching the native ListenerType values supported by Visual FoxPro. For more information, see ListenerType Property.

  4. If successful in obtaining a ReportListener object reference according to the numeric type requested by the ReportListener, it must store this reference to the second parameter. It must also store the numeric type supplied by the Report Engine or calling application to this object's OutputType property. For more information, see OutputType Property (Visual FoxPro).

  5. It must be modal, because it must provide an appropriate reference back to the Report Engine. If it provides any user interface elements, for example allowing the user to select an appropriate ReportListener from a list, this interface should be modal as well.

Recommendations

The following additional conditions are not required for an application to function as _REPORTOUTPUT. However, fulfilling these conditions is highly recommended for any application in this capacity:

  1. The application should maintain some type of ReportListener registry, to allow users to specify classes they prefer to use for various types of output.

  2. The application should bubble errors to the calling application in a manner that permits the caller to determine what action to take when the Report Output Application cannot meet its responsibilities.

Example

The following example sets the value of the _REPORTOUTPUT system variable to the default Report Output application.
Copy Code
_REPORTOUTPUT = HOME() + "ReportOutput.app"

See Also

Reference

HOME( ) Function
ReportListener Object

Other Resources

Extending Report Output Functionality


_REPORTPREVIEW System Variable

Visual FoxPro 9.0
_REPORTPREVIEW System Variable
See Also Example

Specifies the application used by Visual FoxPro to generate instances of a report preview user interface in order to satisfy requests from instances of the ReportListener class.

For more information on custom report previews, see Extending Report Preview Functionality

_REPORTPREVIEW = cProgramName

Parameters

cProgramName

Specifies the object factory application invoked by Visual FoxPro.
Note:
If the application is located in a directory other than the current default directory, include a path name with the program name.

Remarks

By default, _REPORTPREVIEW refers to ReportPreview.App, located in the main Visual FoxPro directory.

You can also specify an application to use in _REPORTPREVIEW using the File Locations tab in the Options dialog box. For more information, see File Locations Tab, Options Dialog Box.

The application in _REPORTPREVIEW is passed a NULL reference parameter, into which it must place an object reference to an instance of a class supporting the The Preview Container API. The application must then terminate, returning the Preview Container object reference:

Copy Code
pc = .NULL.
DO (_REPORTPREVIEW) WITH pc

The variable pc will now contain an object reference.

Consider the following statements:

Copy Code
    rl = NEWOBJECT("Reportlistener")
    rl.ListenerType = 1
    REPORT FORM customers.frx OBJECT rl

When Visual FoxPro executes these commands, it checks the Reportlistener's PreviewContainer property for a valid object reference. If it does not find one, it obtains one by calling the _REPORTPREVIEW application.

Visual FoxPro will generate an error if it does not locate an application for _REPORTPREVIEW during a report preview.

Note:
When distributing report preview factory programs with your applications, you may find it convenient to explicitly set _REPORTPREVIEW in the Visual FoxPro configuration file, Config.fpw. For more information, see Including Report Files for Distribution and Setting Configuration Options at Startup.

Example

The following line of code sets the _REPORTPREVIEW system variable to the default Report Preview application:
Copy Code
_REPORTPREVIEW = HOME()+"ReportPreview.app"

See Also

Reference

SET REPORTBEHAVIOR Command
ReportListener Object
System Variables
System Variables Overview


_SAMPLES System Variable

Visual FoxPro 9.0 Language Reference
_SAMPLES System Variable
See Also

Contains the path of the directory in which the Microsoft Visual FoxPro samples are installed.

_SAMPLES = cPath

Parameters

cPath

Specifies the complete path to the directory containing the Visual FoxPro samples.

Remarks

_SAMPLES specifies the path of the directory that contains the samples for Visual FoxPro. This path is usually the \Samples subdirectory in your Visual FoxPro root directory, which you can determine by using the HOME() function. If you do not install the Visual FoxPro samples, _SAMPLES still points to the \Samples subdirectory because it is the default location for installing samples.

The path that _SAMPLES contains is read from an MSDN registry key in the Windows Registry. If this registry key doesn't exist (for example, if you didn't install the samples), _SAMPLES contains the empty string.

You can also specify a path to the samples directory with the SamplesDirectory item in the File Locations tab of the Options dialog box. If you use the Options dialog box to specify a path to the samples directory, _SAMPLES contains the path you specify. If you choose Set As Default, the path is saved for subsequent Visual FoxPro sessions.

HOME(2) returns the path contained in _SAMPLES.

See Also

Other Resources

System Variables
HOME( ) Function
File Locations


_SCCTEXT System Variable

Visual FoxPro 9.0 Language Reference
_SCCTEXT System Variable
See Also

Specifies a Visual FoxPro conversion program that handles translating Visual FoxPro binary files into text equivalents and back.

_SCCTEXT = cProgramName

Parameters

cProgramName

Specifies a source control conversion program. If your source control conversion program is in a directory other than the current default directory, include a path with the program name. You can also specify a source control conversion program in your configuration file by including a line using this syntax:
Copy Code
_SCCTEXT = cProgramName

Remarks

By default, _SCCTEXT contains Scctext.prg, a Visual FoxPro conversion program that handles translating Visual FoxPro binary files into text equivalents and back. These text files are used as the basis for comparing and merging versions of Visual FoxPro binary files through a source control application.

See Also

Other Resources

System Variables
Projects Tab, Options Dialog Box
Data Conversion Functions
CREATEBINARY( ) Function


_SCREEN System Variable

Visual FoxPro 9.0 Language Reference
_SCREEN System Variable
See Also

Specifies properties and methods for the main Visual FoxPro window. You can use _SCREEN to manipulate the main Visual FoxPro window as an object. There are two versions of the syntax.

_SCREEN.PropertyName [= eValue]
_SCREEN.MethodName

Parameters

PropertyName

Specifies a property for the main Visual FoxPro window.
eValue

Specifies a value for the property.
MethodName

Specifies a method to execute for the main Visual FoxPro window.

Remarks

You cannot create events procedures for _SCREEN. However, you can use the BINDEVENT( ) Function to bind _SCREEN events to other object events and methods. _SCREEN is an object type system variable.

In versions of Visual FoxPro 7.0 and later, the Top, Height, Left, Width, and hWnd properties of _SCREEN apply only to the Visual FoxPro client area, which is the area that can display text. In versions prior to Visual FoxPro 7.0, the Top and Left properties reference the entire Visual FoxPro application window.

CLEAR WINDOWS or RELEASE WINDOWS sets the ReleaseType property for _SCREEN to 1. Closing the Windows operating system sets ReleaseType to 2. For more information, see CLEAR Commands and RELEASE WINDOWS Command.

Note:
The value returned by ReleaseType for _SCREEN can differ from the value returned by ReleaseType for forms because it is the main Visual FoxPro window.

Examples

The following example demonstrates the use of _SCREEN to customize the main Visual FoxPro window. The following lines of code declare local variables for storing the current settings:

Copy Code
Local oldScreenLeft
Local oldScreenTop
Local oldScreenHeight
Local oldScreenWidth
Local oldScreenColor

The following code saves the current settings of the main Visual FoxPro window:

Copy Code
WITH _SCREEN
 oldScreenLeft=.Left
 oldScreenTop=.Top
 oldScreenHeight=.Height
 oldScreenWidth=.Width
 oldScreenColor = .Backcolor

The following codes disable redrawing of the window, change the background color to grey, changes the border style, sets properties for the window's control buttons, makes the window movable at run time, specifies the height and width of the window, sets a caption for the window, and enables redrawing of the screen:

Copy Code
 .LockScreen=.T.
 .BackColor=rgb(192,192,192)
 .BorderStyle=2
 .Closable=.F.
 .ControlBox=.F.
 .MaxButton=.F.
 .MinButton=.T.
 .Movable=.T.
 .Height=285
 .Width=550
 .Caption="Custom Screen"
 .LockScreen=.F.
ENDWITH
=MESSAGEBOX("Return to normal  ",48,WTITLE())

The following code sets the properties of the window to its original settings:

Copy Code
WITH _SCREEN
 .Left = oldScreenLeft
 .Top = oldScreenTop
 .Height = oldScreenHeight
 .Width  = oldScreenWidth
 .BackColor=oldScreenColor
 .LockScreen=.T.
 .BorderStyle=3
 .Closable=.T.
 .ControlBox=.T.
 .MaxButton=.T.
 .MinButton=.T.
 .Movable=.T.
 .Caption="Microsoft Visual FoxPro"
 .LockScreen=.F.
ENDWITH

See Also

Other Resources

System Variables
_SCREEN System Variable Properties, Methods and Events
BINDEVENT( ) Function
MODIFY WINDOW Command
Form Object


_SCREEN System Variable Properties, Methods and Events

Visual FoxPro 9.0 Language Reference
_SCREEN System Variable Properties, Methods and Events
See Also

Properties

ActiveControl | ActiveForm | AlwaysOnBottom
AlwaysOnTop | Application |
AutoCenter | BackColor | BaseClass
BorderStyle | BufferMode | Caption
Class | ClassLibrary | ClipControls
Closable | Comment | ControlBox
ControlCount | Controls | CurrentX
CurrentY | DataSession | DataSessionID
DefOLELCID Property | Desktop | DisplayOrientation
DrawMode | DrawStyle | DrawWidth
Enabled | FillColor | FillStyle
FontBold | FontCharSet | FontItalic
FontName | FontOutline | FontShadow
FontSize | FontStrikeThru | FontUnderline
Forecolor | FormCount | Forms
HalfHeightCaption | Height | HelpContextID
HWnd | Icon | KeyPreview
Left | LockScreen | MaxButton
MaxHeight | MaxLeft | MaxTop
MaxWidth | MDIForm | MinButton
MinHeight | MinWidth | MousePointer
Movable | Name | Objects
ParentClass | Picture | ReleaseType
RightToLeft | ScaleMode | ShowTips
TabIndex | TabStop | Tag
Themes | Top | Visible
Width | WindowState | WindowType

Methods

AddObject | AddProperty | Box
Circle | Cls | Draw
Hide | Line | Move
Point | Print | Pset
Refresh | Release | RemoveObject
SaveAs | SaveAsClass | SetAll
Show | TextHeight | TextWidth
ZOrder |  |

Events

Activate | Click | DblClick
Deactivate | Destroy | DragDrop
DragOver | Error | GotFocus
Init | KeyPress | Load
LostFocus | MiddleClick Event | MouseDown
MouseMove | MouseUp | MouseWheel
Moved | OLECompleteDrag | OLEDragDrop
OLEDragOver | OLEGiveFeedBack | OLESetData
OLEStartDrag | Paint | QueryUnload
Resize | RightClick | Scrolled
Unload |  |

See Also

Other Resources

_SCREEN System Variable
MODIFY WINDOW Command
Form Object


_SHELL System Variable

Visual FoxPro 9.0 Language Reference
_SHELL System Variable
See Also

Specifies a program shell.

_SHELL = cCommand

Remarks

The _SHELL system memory variable is used to prevent access to the Command window while a program is running in Visual FoxPro. The DO command with the name of a program to execute is usually stored to _SHELL.

You can also specify a command to execute when Visual FoxPro is started by placing the SHELL configuration item in your Visual FoxPro configuration file.

The following example demonstrates how _SHELL typically can be used.

  1. A startup program named Mystart.prg is used to launch another program named Myapp.prg. Mystart.prg stores the command to run Myapp.prg to _SHELL. This starts Myapp.prg. Before Visual FoxPro displays the Command window, _SHELL is checked for a command. If _SHELL contains a command, it is executed and Visual FoxPro then stores the empty string to _SHELL.

  2. After the initialization code in Myapp.prg is successfully executed, the command to launch Myapp.prg is stored again to _SHELL. Visual FoxPro does not execute the command or store the empty string to _SHELL, and access to the Command window is prevented. (The Command window cannot be accessed when _SHELL contains anything but the empty string).

  3. Before Myapp.prg finishes execution, it stores the empty string to _SHELL to restore access to the Command window.

    Copy Code
    *** MYSTART.PRG ***
...
_SHELL = "DO MYAPP.PRG"

*** MYAPP.PRG ***
*** Initialization Code ***
...
*** Initialization Code successfully completed? ***
_SHELL = "DO MYAPP.PRG" && Prevents access to Command window
...
*** Clean up Code ***
_SHELL = ""

See Also

Other Resources

DO Command
RUN | ! Command
_STARTUP System Variable
System Variables Overview
Language Reference


_SPELLCHK System Variable

Visual FoxPro 9.0 Language Reference
_SPELLCHK System Variable
See Also

Specifies a spelling checker program for the Visual FoxPro text editor.

_SPELLCHK = ProgramName

Parameters

ProgramName

Specifies a spelling checker program. If your spelling checker program is in a directory other than the current default directory, include a path with the program name. You can also specify a spelling checker program in your Visual FoxPro configuration file. Include the line:
Copy Code
_SPELLCHK = ProgramName

Remarks

By default, _SPELLCHK is unassigned. You can use a spelling checking program by providing the program name and its path in _SPELLCHK. Once you specify a program programmatically or in the File Locations tab of the Tools, Options menu, access the program with the DO command as in the following sample.

Copy Code
DO (_Spellchk)

See Also

Other Resources

MODIFY COMMAND Command
MODIFY FILE Command
MODIFY MEMO Command
System Variables Overview
Language Reference


_STARTUP System Variable

Visual FoxPro 9.0 Language Reference
_STARTUP System Variable
See Also

Specifies the name of the application that runs when you start Visual FoxPro.

_STARTUP = ProgramName

Parameters

ProgramName

Specifies the application that is run when you start Visual FoxPro. You must include _STARTUP in your Visual FoxPro configuration file. You can also specify a command or program to run when Visual FoxPro starts by including one of the following in your configuration file:
Copy Code
COMMAND = cVisualFoxProCommand
- Or -
Copy Code
COMMAND = DO ProgramName
A startup application specified with _STARTUP always runs before a command or program specified with COMMAND in your configuration file.

Remarks

You can also specify a startup application in the Files Location tab of the Options dialog.

See Also

Other Resources

DO Command
Options Dialog Box
System Variables Overview
Language Reference


_TALLY System Variable

Visual FoxPro 9.0 Language Reference
_TALLY System Variable
See Also Example

Contains the number of records processed by the most recently executed table command.

_TALLY = nRecords

Parameters

nRecords

Contains a numeric value indicating the number of records processed by the most recently executed table command. When you start Visual FoxPro, _TALLY is set to zero (0).

Remarks

Certain table processing commands return information about their status while they execute. When such a command finishes executing, it displays the number of records processed if the SET TALK command is set to ON. If the command is executed against local views and tables, it stores this number to the _TALLY system variable.

The INSERT - SQL command changes _TALLY if a SQL SELECT command is used to specify the data to insert.

The following table lists the commands and functions that return status information and store the number of records processed in _TALLY only when executed against local tables and views.

APPEND FROM Command | REINDEX Command
AVERAGE Command | REPLACE Command
CALCULATE Command | REQUERY( ) Function
COPY TO Command | SELECT - SQL Command
COUNT Command | SUM Command
DELETE Command | SORT Command
DELETE - SQL Command | TOTAL Command
INDEX Command | UPDATE Command
INSERT - SQL Command (Used with SELECT) | UPDATE – SQL Command
PACK Command |

Example

The following example returns the number of U.S. customers from a Customer table using the SQL SELECT command and stores the to _TALLY automatically. The ? command displays the value stored in _TALLY.
Copy Code
SELECT * FROM customer ;
   WHERE country = 'USA' ;
   INTO CURSOR temp
? _TALLY

For more information, see ? | ?? Command.

See Also

Other Resources

SET TALK Command
System Variables
Language Reference


_TASKLIST System Variable

Visual FoxPro 9.0 Language Reference
_TASKLIST System Variable
See Also

This system variable contains the name of the task list manager program.

_TASKLIST = cTasklistApplication

Parameters

cTasklistApplication

Name of the Visual FoxPro program that manages the task list information. The task list manager program enables you to manage the list of persistent bookmarks (Tasklist Shortcuts) for an open document, and to add or delete task list items. Task list items are records in foxtask.dbf that contain timestamp, filename, class, method, line number and line contents information.

Remarks

By default, _TASKLIST contains tasklist.app, installed in your Windows user application folder or HOME( ) location. You can specify a different name for the task list manager application.

The main difference between persistent bookmarks (Shortcuts) and Bookmarks is that Shortcuts are available between editing sessions.

See Also

Other Resources

How to: Use the Task List Manager
_FoxTask System Variable
System Variables Overview


_TASKPANE System Variable

Visual FoxPro 9.0 Language Reference
_TASKPANE System Variable
See Also

Contains the path and file name for the Visual FoxPro Task Pane Manager.

_TASKPANE = cPath

Parameters

cPath

Specifies the complete path and file name for the Visual FoxPro Task Pane Manager.

Remarks

_TASKPANE specifies the path and file name for the Visual FoxPro Task Pane Manager. This path is usually your Visual FoxPro root directory, and the file name is usually Taskpane.app.

You can specify a path and file name for _TASKPANE on the File Locations tab in the Options dialog box. For more information, see File Locations and Options Dialog Box.

See Also

Other Resources

System Variables
Task Pane Manager


_TEXT System Variable

Visual FoxPro 9.0 Language Reference
_TEXT System Variable
See Also Example

Directs output from the \ | \\ and TEXT ... ENDTEXT text merge commands to a low-level file.

_TEXT = nFileHandle

Parameters

nFileHandle

Specifies a numeric value that determines the low-level file to which output is directed.

Remarks

\ | \\ and TEXT ... ENDTEXT facilitate the merging of text with the contents of tables, memory variables, and the results of functions and expressions. Output generated by these text merge commands can be directed to the screen or a window or to a low-level file. The _TEXT system memory variable lets you direct text merge output from these commands to a low-level file.

To send output from the \ and \\ and TEXT ... ENDTEXT text merge commands to a low-level file, include the TO FileName clause in SET TEXTMERGE. The file handle of FileName is stored to _TEXT. If the file handle of another low-level file was previously stored in _TEXT, that low-level file is closed.

FCREATE( ) creates and opens low-level files and FOPEN( ) opens existing files. These functions return a positive file handle if the file is successfully created or opened. Storing this file handle to _TEXT directs any subsequent output from the \, \\ and TEXT ... ENDTEXT text merge commands to the file. Use STORE or = to store a file handle to _TEXT. You must open a low-level file with write privileges in order for it to accept output from the text merge commands.

You can close low-level files with FCLOSE( ) or CLOSE ALL. You can also use SET TEXTMERGE TO without a file name to close the low-level file whose handle is stored in _TEXT.

The startup default value of _TEXT is –1. If you are directing text merge output to a file whose file handle is stored in _TEXT, you can turn off the output to that file without closing the file by storing –1 to _TEXT. By storing different file handles and –1 to _TEXT, you can direct text merge output to alternate files.

Example

The following program demonstrates how to direct text merge output to alternate files:
Copy Code
SET TALK OFF
SET TEXTMERGE ON NOSHOW      && Enable text merge, no output to screen
SET TEXTMERGE DELIMITERS TO   && Default text merge delimiters <<,>>
SET TEXTMERGE TO date.txt   && Create and send output to date.txt
STORE _TEXT TO gcDateHandle   && Save date.txt's file handle
STORE -1 TO _TEXT         && Output off to date.txt; keep it open
SET TEXTMERGE TO time.txt   && Create and send output to time.txt
STORE _TEXT TO gcTimeHandle   && Save time.txt's file handle
*** Send the following text to time.txt ***
\The time is:
STORE gcDateHandle TO _TEXT    && Now direct output to date.txt
*** Send the following text to date.txt ***
\Today's date is:
STORE gcTimeHandle TO _TEXT   && Now direct output to time.txt
*** Output the time on the same line ***
\\ <<TIME( )>>
STORE gcDateHandle TO _TEXT   && Now direct output to date.txt
*** Output the date on the same line ***
\\ <<DATE( )>>
CLOSE ALL  && Close all files
TYPE date.txt  && See what's in this file...
WAIT WINDOW  && Pause
TYPE time.txt  && ...and what's in this file
ERASE date.txt
ERASE time.txt

See Also

Other Resources

\ | \\ Command
FOPEN( ) Function
FCLOSE( ) Function
FCREATE( ) Function
_PRETEXT System Variable
SET TEXTMERGE Command
SET TEXTMERGE DELIMITERS
System Variables Overview


_THROTTLE System Variable

Visual FoxPro 9.0 Language Reference
_THROTTLE System Variable
See Also

Specifies the execution speed of programs when the Trace window is open.

_THROTTLE = nSeconds

Parameters

nSeconds

Specifies the delay in seconds between execution of each program line. The startup default value is 0, with no pause between execution of program lines. nSeconds can range from 0 to 5.5 seconds. For example, if nSeconds is 0.5 seconds, a 1/2-second delay occurs between execution of program lines.

Remarks

The Trace window, one of the debugging tools available in Visual FoxPro, displays a program's source code as the program executes. The Trace window highlights each line in the program when the line executes. The numeric value of _THROTTLE determines the delay between execution of each program line when the Trace window is open.

Note:
The Trace Between Breaks option on the Trace window's Program menu must be on for a delay to occur.

See Also

Other Resources

SET DEBUG Command
SET STEP Command
System Variables A-Z
Trace Window


_TOOLBOX System Variable

Visual FoxPro 9.0 Language Reference
_TOOLBOX System Variable
See Also

Contains the path and file name for the Visual FoxPro Toolbox. _TOOLBOX specifies the path and file name for the Visual FoxPro Toolbox. This path is usually the Visual FoxPro root directory, and the file name is usually Toolbox.app.

_TOOLBOX = cPath

Parameters

cPath

Specifies the complete path and file name for the Visual FoxPro Toolbox.

Remarks

You can specify a path and file name for _TOOLBOX on the File Locations tab in the Options dialog box. For more information, see File Locations Tab, Options Dialog Box.

See Also

Other Resources

Customize Toolbox Dialog Box
How to: Customize the Toolbox
System Variables Overview
Toolbox


_TOOLTIPTIMEOUT System Variable

Visual FoxPro 9.0 Language Reference
_TOOLTIPTIMEOUT System Variable
See Also

Specifies how long a ToolTip is displayed if the mouse pointer is left stationary.

_TOOLTIPTIMEOUT = [nValue]

Parameters

nValue

The settings for the nValue are:

Setting Description

-1

(Default) Displays the ToolTip for the amount of time specified by Windows.

0

Displays the ToolTip until the mouse is moved.

> 0

Amount of time in milliseconds to display the ToolTip.
Omit the nValue parameter to determine the current _TOOLTIPTIMEOUT value.

Remarks

The _TOOLTIPTIMEOUT setting only applies to controls that have the ToolTipText property set, and fields in Browse windows that are sized smaller than their contents.

See Also

Reference

ToolTipText Property


_TRIGGERLEVEL System Variable

Visual FoxPro 9.0 Language Reference
_TRIGGERLEVEL System Variable
See Also

Contains a read-only numeric value indicating the current trigger procedure nesting level.

_TRIGGERLEVEL = nExpression

Parameters

nExpression

Contains the current trigger procedure nesting level. _TRIGGERLEVEL contains 1 when the initial trigger procedure is executing. If a trigger procedure causes another trigger procedure to fire, _TRIGGERLEVEL is incremented by 1. _TRIGGERLEVEL contains 0 if a trigger procedure is not executing.

Remarks

Use CREATE TRIGGER to create a Delete, Insert, or Update trigger for a table. You can use APPEND PROCEDURES and MODIFY PROCEDURES to create stored procedures that are executed when a Delete, Insert, or Update trigger occurs.

_TRIGGERLEVEL contains a numeric value that is read-only. If you use STORE or = to assign a value to _TRIGGERLEVEL, the value is ignored.

See Also

Other Resources

APPEND PROCEDURES Command
CREATE TRIGGER Command
MODIFY PROCEDURE Command
System Variables Overview
Language Reference


_UNIX System Variable

Visual FoxPro 9.0 Language Reference
_UNIX System Variable
See Also

Included for backward compatibility. Always returns (.F.) in Visual FoxPro.

See Also

Other Resources

Language Reference


_VFP System Variable

Visual FoxPro 9.0 Language Reference
_VFP System Variable
See Also

References the Application object for the current instance of Visual FoxPro. There are two versions of the syntax.

_VFP.PropertyName[ = eValue]
_VFP.Method

Parameters

PropertyName

Specifies a property for the application object.
eValue

Specifies a value for the property.
Method

Specifies a method to execute for the application object.

Remarks

Applies To: Projects Collection

_VFP provides access to the Objects and Projects collections.

Beginning with Visual FoxPro 7, the Top, Height, Left, Width, and hWnd properties of _VFP apply only to main Visual FoxPro window properties. In prior versions of Visual FoxPro, the Height and Width properties referred to those of the Visual FoxPro client area (area where text can be displayed). Now, the Top, Height, Left, and Width properties of _SCREEN are those of the Visual FoxPro Client area.

See Also

Other Resources

_VFP System Variable Properties, Methods and Events
Application Object
CREATEOBJECT( ) Function
_SCREEN System Variable Properties, Methods and Events
System Variables Overview


_VFP System Variable Properties, Methods, and Events

Visual FoxPro 9.0 Language Reference
_VFP System Variable Properties, Methods, and Events
See Also

The following tables list the properties, methods, and events reference topics for this system variable.

Properties

ActiveForm | ActiveProject | Application
AutoYield | Caption | Count
DefaultFilePath | EditorOptions | Forms
FullName | Height | HWND
LanguageOptions | Left | Name
Objects Collection | OLERequestPendingTimeout | OLEServerBusyRaiseError
OleServerBusyTimeout | Parent | ProcessID
Projects Collection | ServerName | StartMode
StatusBar | ThreadID | Top
Version | VFPXMLProgID | Visible
Width |  |

Methods

DataToClip | DoCmd | Eval
Help | Item | Quit
RequestData | SetVar |

See Also

Other Resources

_VFP System Variable
Application Object
CREATEOBJECT( ) Function
Objects Collection
Projects Collection
Objects, Collections, and Classes
Language Reference


_WINDOWS System Variable

Visual FoxPro 9.0 Language Reference
_WINDOWS System Variable
See Also

Included for backward compatibility. Always contains True (.T.) when using Visual FoxPro.

See Also

Other Resources

Language Reference


_WIZARD System Variable

Visual FoxPro 9.0 Language Reference
_WIZARD System Variable
See Also

Contains the name of the Visual FoxPro wizard application.

_WIZARD = cProgramName

Parameters

cProgramName

Specifies a wizard application. If your wizard application is in a directory other than the current Visual FoxPro default directory, include a path with the application name. You can also specify a wizard application in your Visual FoxPro configuration file by including a line using the following syntax:
Copy Code
_WIZARD = cProgramName

Remarks

The _WIZARD system variable contains the name of the application that Visual FoxPro uses when you choose a wizard to run. By default, _WIZARD contains Wizard.app, installed in your Visual FoxPro directory. You can specify a different name for the wizard application.

See Also

Other Resources

System Variables Overview
Wizards Overview


API Library Construction

Visual FoxPro 9.0
API Library Construction

This section includes topics on API library routines, system events, and key codes.

In This Section

API Library Routines A-Z

Contains an alphabetical listing of the API Library Routines.
API Library Routines by Category

Contains a categorized list of the API Library Routines.
Visual FoxPro System Events (API Library Construction)

Lists each Microsoft Visual FoxPro event along with the layout of its event record fields and a description of when the event occurs.
Visual FoxPro Key Codes (API Library Construction)

Provides information about keyboard keys and how Visual FoxPro interprets them depending on the modifier with which they are combined.

Related Sections

Accessing the Visual FoxPro API

Describes how you can write your own Microsoft ActiveX control or Visual FoxPro -specific dynamic-link library (.fll file). By calling the functions available in the API available in Visual FoxPro, you can create controls or libraries that are tightly integrated with and optimized for use in Visual FoxPro
Extending Visual FoxPro with External Libraries

Discusses how you can add Microsoft ActiveX controls (.ocx files) to your application easily, providing you with new objects to use in forms, to subclass, and to manage the way you work with native Visual FoxPro controls.
Language Reference

Includes topics on controls, objects, properties, methods, events, statements, functions, and constants.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


API Library Routines A-Z

Visual FoxPro 9.0 Language Reference
API Library Routines A-Z
See Also

A

_ActivateHandler( )

_ActivateIdle( )

_ActivateMenu( )

_ALen( )

_Alloca( )

_AllocHand( )

_AllocMemo( )

B

_BreakPoint( )

C

_CountItems( )

D

_DBAppend( )

_DBLock( )

_DBRead( )

_DBRecCount( )

_DBRecNo( )

_DBReplace( )

_DBRewind( )

_DBSeek( )

_DBSkip( )

_DBStatus( )

_DBUnlock( )

_DBUnwind( )

_DBWrite( )

_DeActivateHandler( )

_DeActivateIdle( )

_DeActivateMenu( )

_DefaultProcess( )

_Dialog( )

_DisposeItem( )

_DisposeMenu( )

E

_EdActive( )

_EdCloseFile( )

_EdCopy( )

_EdCut( )

_EdDelete( )

_EdGetChar( )

_EdGetEnv( )

_EdGetLineNum( )

_EdGetLinePos( )

_EdGetPos( )

_EdGetStr( )

_EdIndent( )

_EdInsert( )

_EdLastError( )

_EdOpenFile( )

_EdPaste( )

_EdPosInView( )

_EdRedo( )

_EdRevert( )

_EdSave( )

_EdScrollToPos( )

_EdScrollToSel( )

_EdSelect( )

_EdSendKey( )

_EdSetEnv( )

_EdSetPos( )

_EdSkipLines( )

_EdUndo( )

_EdUndoOn( )

_Error( )

_ErrorInfo( )

_Evaluate( )

_Execute( )

F

_FCHSize( )

_FClose( )

_FCopy( )

_FCreate( )

_FEOF( )

_FError( )

_FFlush( )

_FGets( )

_FindMemo( )

_FindVar( )

_FindWindow( )

_FindWindowP( )

_FOpen( )

_FPuts( )

_FRead( )

_FreeHand( )

_FreeObject( )

_FSeek( )

_FWrite( )

G

_GetAPIHandle( )

_GetHandSize( )

_GetItemCmdKey( )

_GetItemId( )

_GetItemSubMenu( )

_GetItemText( )

_GetNewItemId( )

_GetNewMenuId( )

_GetNextEvent( )

_GetObjectProperty( )

_GlobalToLocal( )

_GlobalToLocalP( )

H

_HandToPtr( )

_HLock( )

_HUnLock( )

I

_InKey( )

J

K

L

_Load( )

M

_MemAvail( )

_MemCmp( )

_MemFill( )

_MemMove( )

_MemoChan( )

_MemoSize( )

_MenuId( )

_MenuInteract( )

_MousePos( )

_MousePosP( )

N

_NameTableIndex( )

_NewItem( )

_NewMenu( )

_NewVar( )

O

_ObjectCmp( )

_ObjectReference( )

_ObjectRelease( )

_OnSelection( )

P

_PutChr( )

_PutStr( )

_PutValue( )

Q

R

_Release( )

_RetChar( )

_RetCurrency( )

_RetDateStr( )

_RetDateTimeStr( )

_RetFloat( )

_RetInt( )

_RetLogical( )

_RetVal( )

S

_SetHandSize( )

_SetItemCmdKey( )

_SetItemSubMenu( )

_SetItemText( )

_SetMenuPoint( )

_SetMenuPointP( )

_SetObjectProperty( )

_Store( )

_StrCmp( )

_StrCpy( )

_StrLen( )

T

U

_UserError( )

V

W

_WAttr( )

_WBottom( )

_WBottomP( )

_WClear( )

_WClearRect( )

_WClearRectP( )

_WClose( )

_WFindTitle( )

_WGetCursor( )

_WGetCursorP( )

_WGetObjectClientWindow( )

_WGetObjectWindow( )

_WGetPort( )

_WHeight( )

_WHeightP( )

_WHide( )

_WhToHwnd( )

_WLeft( )

_WLeftP( )

_WMainWindow( )

_WMove( )

_WMoveP( )

_WOnTop( )

_WOpen( )

_WOpenP( )

_WPosCursor( )

_WPosCursorP( )

_WPutChr( )

_WPutStr( )

_WRight( )

_WRightP( )

_WScroll( )

_WScrollP( )

_WSelect( )

_WSendBehind( )

_WSetAttr( )

_WSetPort( )

_WSetTitle( )

_WShow( )

_WSize( )

_WSizeP( )

_WTitle( )

_WTop( )

_WTopP( )

_WWidth( )

_WWidthP( )

_WZoom( )

X

Y

Z

See Also

Other Resources

API Library Construction


_ActivateHandler( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_ActivateHandler( ) API Library Routine
See Also Example

Adds a handler function to the end of the list of event handlers.

unsigned int _ActivateHandler(FPFI handler)
FPFI handler               /* Event handler to be added. */

Remarks

_ActivateHandler( ) returns an integer identifier for this handler. Use this identifier to remove the handler from the event processor list with _DeActivateHandler( ).

The handler is invoked with two parameters: the WHANDLE of the window to which the event belongs, and a FAR (32-bit) pointer to an event record. If your handler doesn't look for an event, or modifies an event for subsequent event handlers, it returns False (0) to indicate that the event must still be passed on to other handlers or to the Visual FoxPro interface routines. If the handler determines that the event doesn't need to be passed on, it returns True (an integer other than 0) to indicate that the event has been handled.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example activates an event handler when the library is loaded. The event handler prints a message for every event and lets Visual FoxPro process the event as it does normally. The event handler is deactivated when the library is unloaded.

Visual FoxPro Code

Copy Code
SET LIBRARY TO ACTIHAND
WAIT WINDOW TO m.test TIMEOUT 5
SET LIBRARY TO

C Code

Copy Code
#include <pro_ext.h>

static int HandlerID;

//   This is the routine that is registered as an event handler.
FAR EventHandler(WHandle theWindow, EventRec FAR *ev)
{
   _PutStr("\nEventHandler() called.");
   return NO;   // event still needs to be handled by Visual FoxPro
}

FAR Activate()
{
   HandlerID = _ActivateHandler(EventHandler);
}

//   When the library is unloaded we must deactivate the event handler
//   in a CALLONUNLOAD function.
FAR DeActivate()
{
   _DeActivateHandler(HandlerID);
}

FoxInfo myFoxInfo[] = {
   {"ACTIVATE",  Activate,   CALLONLOAD, ""},
   {"DEACTIVATE", DeActivate, CALLONUNLOAD, ""}
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DeActivateHandler( ) API Library Routine
_FindWindow( ) API Library Routine
_GlobalToLocal( ) API Library Routine
_MousePos( ) API Library Routine
Event Handlers
EventHandler( ) Function
API Library Routines A-Z
API Library Routines by Category


_ActivateIdle( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_ActivateIdle( ) API Library Routine
See Also Example

Adds an idle handler function to the end of the list of idle event handlers called when Visual FoxPro is waiting for user input or for an event to time out.

unsigned int _ActivateIdle(FPFI handler)
FPFI handler               /* Event handler. */

Remarks

_ActivateIdle( ) returns an integer identifier for this routine. Use the identifier to remove the idle event handler from the idle loop with _DeActivateIdle( ).

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example activates an idle event handler when the library is loaded. The idle event handler just prints a message. The idle event handler is deactivated when the library is unloaded.

Visual FoxPro Code

Copy Code
SET LIBRARY TO ACTIIDLE
WAIT WINDOW TO m.test TIMEOUT 5
SET LIBRARY TO

C Code

Copy Code
#include <pro_ext.h>

static unsigned IdlerID;

//   This is the routine that is registered as an idle event handler.
void FAR IdleHandler(WHandle wh, EventRec *ev)
{
   _PutStr("\nIdleHandler() called.");
}

void FAR Activate(ParamBlk FAR *parm)
{
   IdlerID = _ActivateIdle((FPFI) IdleHandler);
}

//   When the library is unloaded we must deactivate the idle event
//   handlerin a CALLONUNLOAD function.
void FAR DeActivate(ParamBlk FAR *parm)
{
   _DeActivateIdle(IdlerID);
}

FoxInfo myFoxInfo[] = {
   {"ACTIVATE",  (FPFI) Activate, CALLONLOAD,   ""},
   {"DEACTIVATE",  (FPFI) DeActivate, CALLONUNLOAD, ""}
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DeActivateIdle( ) API Library Routine
_FindWindow( ) API Library Routine
_GlobalToLocal( ) API Library Routine
_MousePos( ) API Library Routine
Event Handlers
EventHandler( ) Function
API Library Routines A-Z
API Library Routines by Category


_ActivateMenu( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_ActivateMenu( ) API Library Routine
See Also Example

Displays the specified menu on the screen and immediately returns control to the calling routine.

void _ActivateMenu(MENUID menuid)
MENUID menuid            /* Menu identifier.

Remarks

If you detect the press of a mouse button or a keystroke on the menu, you can call _MenuInteract( ) to determine which menu item the user chose.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example builds a menu with three items. _ActivateMenu( ) displays the menu. This menu is non-modal in that interaction is not forced as with _MenuInteract( ). Rather, when the user makes a selection the _OnSelection( ) routine is called, the selected item is printed on the screen, and the menu is disposed of.

Visual FoxPro Code

Copy Code
SET LIBRARY TO ACTIMENU
WAIT WINDOW "Make selection from menu." NOWAIT
SUSPEND

C Code

Copy Code
#include <pro_ext.h>

static MENUID menuId;

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR onSelection(long menuId, long itemId)
{
   _PutStr("\nitemId = "); putLong(itemId);
}

FAR deactivateMenu(ParamBlk FAR *parm)
{
   _DeActivateMenu(menuId);
   _DisposeMenu(menuId);
}

FAR activateMenu(ParamBlk FAR *parm)
{
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);
   _OnSelection(menuId, -1, onSelection);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) activateMenu, CALLONLOAD, ""},
   {"ONUNLOAD", (FPFI) deactivateMenu, CALLONUNLOAD, ""},
};

FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DeActivateMenu( ) API Library Routine
_MenuId( ) API Library Routine
_NewItem( ) API Library Routine
_NewMenu( ) API Library Routine
_OnSelection( ) API Library Routine
_MenuInteract( ) API Library Routine
_OnSelection( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_ALen( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_ALen( ) API Library Routine
See Also Example

Returns information about the dimensions of the array whose name table index is nti.

long _ALen(NTI nti, int mode)
NTI nti;                     /* Array name table index. */
int mode;                     /* Mode to determine return value. */

Remarks

If mode is AL_ELEMENTS, _ALen( ) returns the total number of elements in the array. If mode is AL_SUBSCRIPT1, _ALen( ) returns the value of the first subscript used to declare the array. If mode is AL_SUBSCRIPT2, _ALen( ) returns the value of the second subscript used to declare the array.

If nti doesn't represent the name of an existing array, _ALen( ) returns – 1 regardless of the value of mode.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example provides a Visual FoxPro API routine for each of the three possible mode values.

Visual FoxPro Code

Copy Code
SET LIBRARY TO ALEN
DIMENSION a[10, 11]
? ALENELEM(@a)  && returns 110
? ALENSUB1(@a)  && returns 10
? ALENSUB2(@a)  && returns 11

DIMENSION b[3]
? ALENELEM(@b)  && returns 3
? ALENSUB1(@b)  && returns 3
? ALENSUB2(@b)  && returns 0; no second subscript

c = .F.
? ALENELEM(@c)  && returns -1 because variable "c" is not an array
? ALENSUB1(@c)  && returns -1 because variable "c" is not an array
? ALENSUB2(@c)  && returns -1 because variable "c" is not an array

C Code

Copy Code
#include <pro_ext.h>

void FAR alenElem(ParamBlk FAR *parm)
{
   _RetInt(_ALen(parm->p[0].loc.l_NTI, AL_ELEMENTS), 10);
}

void FAR alenSub1(ParamBlk FAR *parm)
{
   _RetInt(_ALen(parm->p[0].loc.l_NTI, AL_SUBSCRIPT1), 10);
}

void FAR alenSub2(ParamBlk FAR *parm)
{
   _RetInt(_ALen(parm->p[0].loc.l_NTI, AL_SUBSCRIPT2), 10);
}

FoxInfo myFoxInfo[] = {
   {"ALENELEM", (FPFI) alenElem, 1, "R"},
   {"ALENSUB1", (FPFI) alenSub1, 1, "R"},
   {"ALENSUB2", (FPFI) alenSub2, 1, "R"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_FindVar( ) API Library Routine
_Load( ) API Library Routine
_NameTableIndex( ) API Library Routine
_NewVar( ) API Library Routine
_ObjectRelease( ) API Library Routine
_Store( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_Alloca( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_Alloca( ) API Library Routine
See Also Example

Allocates a block of stack space for the calling routine.

void FAR * _Alloca(unsigned int size)
unsigned int size;            /* Size of stack space to allocate in
bytes. */

Remarks

_Alloca( ) returns a pointer to the block if the block is successfully allocated, or returns zero if the block isn't allocated. _Alloca( ) automatically frees memory when the routine ends, so no corresponding release routine is necessary.

Caution:
Some C compilers, such as MPW C, do not support memory allocation from the stack; calls to _Alloca() using such compilers will have unpredictable results. Instead, use local variables, or calls to _AllocHand() and _FreeHand(), in your code to reserve memory.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example duplicates the action of the Visual FoxPro REPLICATE( ) function. The memory temporarily used to duplicate the character comes from _Alloca( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO ALLOCA
x = xREPLICATE("x", 120)
? x
? LEN(x)

C Code

Copy Code
#include <pro_ext.h>

void FAR allocaEx(ParamBlk FAR *parm)
{
   char FAR *rep;
   char c = *(char *) _HandToPtr(parm->p[0].val.ev_handle);

   rep = _Alloca((int) parm->p[1].val.ev_long + 1);
   _MemFill(rep, c, (int) parm->p[1].val.ev_long);
  rep[parm->p[1].val.ev_long] = '\0';  // null terminate

   _RetChar(rep);
}

FoxInfo myFoxInfo[] =
{
   {"XREPLICATE", (FPFI) allocaEx, 2, "C,I"},
};

FoxTable _FoxTable =
{
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_AllocHand( ) API Library Routine
_FreeHand( ) API Library Routine
REPLICATE( ) Function
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_AllocHand( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_AllocHand( ) API Library Routine
See Also Example

Returns a new MHANDLE of size hsize.

MHANDLE _AllocHand(unsigned int hsize)
unsigned int hsize;            /* Size of new memory handle in bytes. */

Remarks

_AllocHand( ) returns 0 when there is insufficient memory to fulfill the request. Memory allocated with _AllocHand( ) isn't initialized, and must be freed after use.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

In The following example, a character is replicated in memory supplied by _AllocHand( ). The API function REPLTOMH( ) below returns the memory handle to Visual FoxPro. From Visual FoxPro the memory handle is passed to API functions, which expect a memory handle argument (passed as an integer, "I").

Visual FoxPro Code

Copy Code
SET LIBRARY TO ALLOCHAN
mh = REPLTOMH("x", 120)
? MHTOFOX(mh)
? LEN(MHTOFOX(mh))
? MHTOFOX(mh)
= FREEMH(mh)

C Code

Copy Code
#include <pro_ext.h>

//   Replicate char argument to memory allocated with _AllocHand().
//   Return the memory handle to Visual FoxPro.
void FAR replToMH(ParamBlk FAR *parm)
{
   char FAR *rep;
   char c = *(char *) _HandToPtr(parm->p[0].val.ev_handle);
   MHANDLE mh;

   if ((mh = _AllocHand((int) parm->p[1].val.ev_long + 1)) == 0)
   {
      _Error(182);  // "Insufficient memory"
   }
   _HLock(mh);
   rep = _HandToPtr(mh);
   _MemFill(rep, c, (int) parm->p[1].val.ev_long);
   rep[parm->p[1].val.ev_long] = '\0';  // null terminate
   _HUnLock(mh);

   _RetInt(mh, 10);
}

//   Returns characters in memory handle.
//   Argument in call from Visual FoxPro
//   must be a valid Visual FoxPro memory handle.
void FAR MHToFoxString(ParamBlk FAR *parm)
{
   char FAR *string;
   MHANDLE mh = parm->p[0].val.ev_long;

   _HLock(mh);
   string = _HandToPtr(mh);
   _RetChar(string);
   _HUnLock(mh);
}

//   Frees memory handle.  Argument in call from
//   Visual FoxPro must be a valid
//   Visual FoxPro memory handle.
void FAR freeMH(ParamBlk FAR *parm)
{
   _FreeHand((MHANDLE) parm->p[0].val.ev_long);
}

FoxInfo myFoxInfo[] = {
   {"REPLTOMH", (FPFI) replToMH, 2, "C,I"},
   {"MHTOFOX", (FPFI) MHToFoxString, 1, "I"},
   {"FREEMH", (FPFI) freeMH, 1, "I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_FreeHand( ) API Library Routine
_GetHandSize( ) API Library Routine
_HandToPtr( ) API Library Routine
_HLock( ) API Library Routine
_HUnLock( ) API Library Routine
_MemAvail( ) API Library Routine
_SetHandSize( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_AllocMemo( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_AllocMemo( ) API Library Routine
See Also Example

Allocates size bytes of space in the memo file for a field and inserts the new block number in the associated record in the database.

long _AllocMemo(Locator FAR *fld, long size)
Locator FAR *fld;            /* Pointer to locator
 that defines the memo field. */
long size;                     /* Size of allocated space in bytes. */

Remarks

When _AllocMemo( ) is successful, it returns the location in the file to begin writing; otherwise, it returns – 1.

Caution:
Writing more than size bytes causes memo file corruption.

If you plan to replace a memo field using direct methods, be sure your routine calls _AllocMemo( ) before writing to the memo file, even if the new value is the same length or smaller than the original. This prevents problems in multiuser situations. _AllocMemo( ) reuses the previously allocated space when it's safe to do so.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates new memo field contents.

Visual FoxPro Code

Copy Code
SET LIBRARY TO ALLOMEMO
CREATE TABLE wMemo (memoField M)
APPEND BLANK
= NewMemo(@MemoField, "Hello, World.")
APPEND BLANK
= NewMemo(@MemoField, "Isn't this fun?")

C Code

Copy Code
#include <pro_ext.h>

FAR newMemo(ParamBlk FAR *parm)
{
   Locator FAR *memoFldLoc;
   FCHAN fchMemo;
   int memoLen;
   long loc;

   if ((fchMemo = _MemoChan(-1)) == -1)
   {
      _UserError("_MemoChan() failed");
   }
   memoFldLoc = &parm->p[0].loc;
   memoLen = parm->p[1].val.ev_length;

   if ((loc = _AllocMemo(memoFldLoc, memoLen)) == -1)
   {
      _UserError("_AllocMemo() failed");
   }
   _FSeek(fchMemo, loc, FS_FROMBOF);
   _HLock(parm->p[1].val.ev_handle);
   _FWrite(fchMemo, _HandToPtr(parm->p[1].val.ev_handle), memoLen);
   _HUnLock(parm->p[1].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"NEWMEMO", (FPFI) newMemo, 2, "R,C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBReplace( ) API Library Routine
_FindMemo( ) API Library Routine
_MemoChan( ) API Library Routine
_MemoSize( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_BreakPoint( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_BreakPoint( ) API Library Routine
See Also Example

_BreakPoint( ) is a macro that generates the debugger breakpoint instruction, INT 3 and can be helpful for debugging external routines.

void _BreakPoint(void any)
void any;                     /* Pointer. */

Remarks

When a _BreakPoint( ) call is encountered, control transfers to your debugger. Most debuggers return control to the program line that includes the INT3 instruction, and you have to manually increment the instruction pointer (IP) past this instruction. At that time you can use your debugger to set additional breakpoints. Always remove any breakpoints before exiting the external routine. For more information about debugging, see Accessing the Visual FoxPro API.

Example

The following example uses the macro _BreakPoint( ) to place an INT 3 that debuggers recognize as a breakpoint.

Visual FoxPro Code

Copy Code
SET LIBRARY TO BPOINT

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   int RetValue;

   _BreakPoint(); // debugger breaks execution here

   _HLock(parm->p[0].val.ev_handle);
   _HLock(parm->p[1].val.ev_handle);

   RetValue = _StrCmp(_HandToPtr(parm->p[0].val.ev_handle),
      _HandToPtr(parm->p[1].val.ev_handle));

   _RetInt(RetValue, 10); // does return control here

   _HUnLock(parm->p[0].val.ev_handle);
   _HUnLock(parm->p[1].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"STRCMP", (FPFI) Example, 2, "C,C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

Accessing the Visual FoxPro API
Debugging Routines
Debugging and Error-Handling Language
API Library Routines A-Z
API Library Routines by Category


_CountItems( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_CountItems( ) API Library Routine
See Also Example

Returns the number of menu titles or bars on the specified menu.

int _CountItems(MENUID menuid)
MENUID menuid;            /* Menu identifier. */

Example

The following example creates a menu with three items, and calls _CountItems( ) to show that the function correctly returns the number of items on the menu. The routine then disposes of menu items, and calls _CountItems( ) again.

Visual FoxPro Code

Copy Code
SET LIBRARY TO CNTITEMS

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR CountItemsEx(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);
   _PutStr("\n_CountItems() ="); putLong(_CountItems(menuId));
   _Execute("WAIT");

   _DisposeItem(menuId, _GetItemId(menuId, 1));
   _PutStr("\n_CountItems() ="); putLong(_CountItems(menuId));
   _Execute("WAIT");

   _DisposeItem(menuId, _GetItemId(menuId, 0));
   _PutStr("\n_CountItems() ="); putLong(_CountItems(menuId));
   _Execute("WAIT");

   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) CountItemsEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_GetNewMenuId( ) API Library Routine
_GetNewMenuId( ) API Library Routine
_NewMenu( ) API Library Routine
Creating Menus, Shortcut Menus, Menu Items, and Submenus
API Library Routines A-Z
API Library Routines by Category


_DBAppend( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBAppend( ) API Library Routine
See Also Example

Attempts to append a new record to the table open in the specified workarea.

int _DBAppend(int workarea, int carryflag)
int workarea;               /* Work area number. */
int carryflag;               /* SET CARRY setting. */

Remarks

The current work area is represented by – 1. _DBAppend( ) returns 0 if the routine is successful. If the routine fails, _DBAppend( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

Values for

Value | Effect
1 | Carries information from the previous record into the new record.
0 | Makes the new record blank.
– 1 | Uses the setting of SET CARRY to determine whether information from the previous record is carried to the new record.

_DBAppend( ) automatically performs any necessary locking. If it's unable to lock the file header, _DBAppend( ) fails and returns a negative integer whose absolute value is a Visual FoxPro error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _DBAppend( ) to append a record to the table open in the current work area.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBAPPEND
DO CreateTest

SET CARRY ON
= DBAPPEND(-1)   && SET CARRY is ON, so carry
SET CARRY OFF
= DBAPPEND(1)   && carry regardless of SET CARRY
= DBAPPEND(-1)   && SET CARRY is OFF, so no carry

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "Golly month of"
   APPEND BLANK
   REPLACE ABC WITH "A twelfth of"
   APPEND BLANK
   REPLACE ABC WITH "Hello, world"
   APPEND BLANK
   REPLACE ABC WITH "When in the"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   int RetCode;
   if ((RetCode = _DBAppend(-1, (int) parm->p[0].val.ev_long)) < 0) {
      _Error(-RetCode);
   }
}

FoxInfo myFoxInfo[] = {
   {"DBAPPEND", (FPFI) Example, 1, "I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBLock( ) API Library Routine
_DBUnlock( ) API Library Routine
How to: Append Data to Existing Tables
SET CARRY Command
APPEND Command
API Library Routines A-Z
API Library Routines by Category


_DBLock( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBLock( ) API Library Routine
See Also Example

Attempts to lock the current record or the table open in the work area specified by workarea.

int _DBLock(int workarea, int RecOrFile)
int workarea;               /* Work area. */
int RecOrFile;               /* What is to be locked. */

Remarks

The RecOrFile parameter can be DBL_RECORD, to specify the current record, or DBL_FILE, to specify the table file. _DBLock( ) returns True (an integer other than 0) if the lock is successful, or False (0) if the lock isn't successful.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example provides two API functions you can call from Visual FoxPro: XRLOCK( ), which locks the current record of the current work area; and XFLOCK( ), which locks the table open in the current work area. XRLOCK( ) calls _DBLock( – 1, DBL_RECORD( )), and XFLOCK( ) calls _DBLock( – 1, DBL_FILE( )).

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBLOCK
DO CreateTest
USE Test SHARED
GO 2
= XRLOCK()
LIST STAT  && shows that record #2 is locked
= XFLOCK()
LIST STAT  && shows that whole DBF is locked

PROCEDURE CreateTest

CREATE TABLE test (ABC C(20))
APPEND BLANK
REPLACE ABC WITH "Golly month of"
APPEND BLANK
REPLACE ABC WITH "A twelfth of"
APPEND BLANK
REPLACE ABC WITH "Hello, world"
APPEND BLANK
REPLACE ABC WITH "When in the"
GO TOP

RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR xLockRecord(ParamBlk FAR *parm)
{
   _DBLock(-1, DBL_RECORD);
}

FAR xLockFile(ParamBlk FAR *parm)
{
   _DBLock(-1, DBL_FILE);
}

FoxInfo myFoxInfo[] =
{
   {"XRLOCK", (FPFI) xLockRecord, 0, ""},
   {"XFLOCK", (FPFI) xLockFile, 0, ""},
};

FoxTable _FoxTable =
{
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBAppend( ) API Library Routine
_DBUnlock( ) API Library Routine
Accessing the Visual FoxPro API
Passing Parameters to Visual FoxPro API Functions
API Library Routines A-Z
API Library Routines by Category


_DBRead( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBRead( ) API Library Routine
See Also Example

Moves the current record pointer to the specified record in the specified work area.

int _DBRead(int workarea, long record)
int workarea;               /* Work area. */
long record;                  /* Record number. */

Remarks

_DBRead( ) returns 0 if the routine is successful. If the routine fails, _DBRead( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

Specifying 0 for record is equivalent to issuing GO TOP; specifying – 1 for record is equivalent to issuing GO BOTTOM.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example provides similar functionality to that of the Visual FoxPro command GO. XGO(n) moves the current record pointer to record number n in the current work area.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBREAD
DO CreateTest
USE Test SHARED
GO BOTTOM
? RECNO()
= XGO(2)
? RECNO()

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _DBRead(-1, parm->p[0].val.ev_long);
}

FoxInfo myFoxInfo[] = {
   {"XGO", (FPFI) Example, 1, "I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBRewind( ) API Library Routine
_DBSkip( ) API Library Routine
_DBUnwind( ) API Library Routine
GO | GOTO Command
API Library Routines A-Z
API Library Routines by Category


_DBRecCount( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBRecCount( ) API Library Routine
See Also Example

Returns the total number of records in the table open in the specified work area.

long _DBRecCount(int workarea)
int workarea;               /* Work area. */

Remarks

If no table is open in the specified work area, _DBRecCount( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example calls _DBRecCount( ) to count the number of records in the table open in the current work area.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBRECCNT
DO CreateTest
? DBRECCOUNT()   && call API routine
? RECCOUNT()   && call built-in Visual FoxPro Function

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _RetInt(_DBRecCount(-1), 10);
}

FoxInfo myFoxInfo[] = {
   {"DBRECCOUNT", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBRecNo( ) API Library Routine
Accessing the Visual FoxPro API
Working with Records
Records
Field and Record Manipulation
API Library Routines A-Z
API Library Routines by Category


_DBRecNo( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBRecNo( ) API Library Routine
See Also Example

Returns the number of the current record in the table open in the specified work area.

long _DBRecNo(int workarea)
int workarea;               /* Work area. */

Remarks

If no table is open in the specified work area, _DBRecNo( ) returns a negative integer whose absolute value is a Visual FoxPro error number. If the record pointer is at the end of file, _DBRecNo( ) returns a number that is 1 greater than that returned by _DBRecCount( ).

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example provides functionality similar to that of the Visual FoxPro RECNO( ) function.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBRECNO
DO CreateTest
GO 3
? DBRECNO()
GO 6
? DBRECNO()
USE
? DBRECNO()  && returns -119

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   APPEND BLANK
   REPLACE ABC WITH "This is record 5"
   APPEND BLANK
   REPLACE ABC WITH "This is record 6"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _RetInt(_DBRecNo(-1), 10);
}

FoxInfo myFoxInfo[] = {
   {"DBRECNO", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBRecCount( ) API Library Routine
Accessing the Visual FoxPro API
Working with Records
Records
Field and Record Manipulation
API Library Routines A-Z
API Library Routines by Category


_DBReplace( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBReplace( ) API Library Routine
See Also Example

_DBReplace( ) places a new value in a field.

int _DBReplace(Locator FAR *fld, Value FAR *val)
Locator FAR *fld;            /* Field to be replaced. */
Value FAR *val;            /* Value to be placed in field. */

Remarks

_DBReplace( ) returns 0 if the replacement is successful. If the replacement fails, _DBReplace( ) returns a negative integer whose absolute value is a Visual FoxPro error number. _DBReplace( ) can be used on a memo field to replace its value with a new value that's shorter than 65,000 bytes. To perform operations on memo fields that are larger than 65,000 bytes, you must use direct memo field routines and buffered file input/output routines.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example provides functionality similar to the Visual FoxPro REPLACE command, but replaces the value of only one record at a time.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBREPLAC
DO CreateTest
? DBREPLACE(@ABC, "Replacement record 1")
? DBREPLACE(@ABC, 2)  && returns -302 - field ABC is character field

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _RetInt(_DBReplace(&parm->p[0].loc, &parm->p[1].val), 10);
}

FoxInfo myFoxInfo[] = {
   {"DBREPLACE", (FPFI) Example, 2, "R,?"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBLock( ) API Library Routine
_DBUnlock( ) API Library Routine
REPLACE Command
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_DBRewind( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBRewind( ) API Library Routine
See Also Example

Works like the Visual FoxPro GO TOP command in the specified work area, and then returns the current record number.

long _DBRewind(int workarea)
int workarea;               /* Work area. */

Example

The following example calls _DBRewind( ) for the table open in the current work area. This has the same effect as the Visual FoxPro GO TOP command.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBREWIND
DO CreateTest
GO BOTTOM
? RECNO()
? DBREWIND()    && returns 1
? RECNO()  && yes, we're at record 1

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _RetInt(_DBRewind(-1), 10);
}
FoxInfo myFoxInfo[] = {
   {"DBREWIND", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBSkip( ) API Library Routine
_DBUnwind( ) API Library Routine
GO | GOTO Command
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_DBSeek( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBSeek( ) API Library Routine
See Also Example

Searches an indexed table in the current work area for the first record whose index key matches the value val.

long _DBSeek(Value FAR *val)
Value FAR *val;            /* Sought value. */

Remarks

If _DBSeek( ) finds a matching record, it moves the record pointer to the matching record and returns the record number. The match must be exact unless you SET EXACT is set to OFF. If _DBSeek( ) doesn't find a matching record, it returns 0. If no match is found and SET NEAR is set to ON, the record pointer is positioned immediately after the closest matching record. If SET NEAR is set to OFF, the record pointer is positioned at the end of the file.

If the matching record is an added buffered record that has not been committed, the value returned by _DBSeek( ) differs from the value returned by RECNO( ). RECNO( ) returns a negative value, indicating the record is buffered. The value returned by _DBSeek( ) is one greater than the number of records in the table plus the number of buffered records before the matching record.

If an error occurs, _DBSeek( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

When seeking a numeric field, val must be set to ev_type 'N', even if that field has no decimal digits. If val has an ev_type of 'I', _DBSeek( ) will return the internal error number -302, "Data type mismatch".

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example performs a seek on whatever index controls the order of the table open in the current work area. Note the "?" in the FoxInfo structure is required because the type of index expression is not known.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBSEEK
DO CreateTest

INDEX ON ABC TAG ABC
SET ORDER TO TAG ABC
= DBSEEK("This is record 3")  && seeks ABC = "This is record 3"
LIST NEXT 1
USE

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _DBSeek(&parm->p[0].val);
}

FoxInfo myFoxInfo[] = {
   {"DBSEEK", (FPFI) Example, 1, "?"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBRecCount( ) API Library Routine
_DBRecNo( ) API Library Routine
_DBSkip( ) API Library Routine
SET EXACT Command
API Library Routines A-Z
API Library Routines by Category


_DBSkip( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBSkip( ) API Library Routine
See Also Example

_DBSkip( ) moves the record pointer in the specified work area the specified number of records.

long _DBSkip(int workarea, long distance)
int workarea;               /* Work area. */
long distance;               /* Number of records to skip. */

Remarks

_DBSkip( ) respects the active index and filter expressions, just like the Visual FoxPro SKIP command. The distance may be positive or negative. _DBSkip( ) returns the record number of the new record.

Use _DBStatus( ) to check for end of file and beginning of file conditions. If you try to skip forward from the end of the file, or skip backwards from the beginning of the file, _DBSkip( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example works like the Visual FoxPro SKIP command.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBSKIP
ON ERROR DO expectError
DO CreateTest
USE
= DBSKIP(1)       && _Error() called: no DBF in use
USE test
GO TOP
= DBSKIP(-1)
= DBSKIP(-1)      && _Error() called: at top of file
GO BOTT
= DBSKIP(1)
= DBSKIP(1)      && _Error() called: at bottom of file
ON ERROR

PROCEDURE expectError
   ? "ERROR: " + MESSAGE()
RETURN

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *pblk)
{
   int RetCode;

   if ((RetCode = _DBSkip(-1, pblk->p[0].val.ev_long)) < 0) {
      _PutStr("\nError encountered in example program.");
      _Error(-RetCode);  // _DBSkip() returns negative error code
   }
   _RetInt(RetCode, 10);
}

FoxInfo myFoxInfo[] = {
   {"DBSKIP", (FPFI) Example, 1, "I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBRecCount( ) API Library Routine
_DBRecNo( ) API Library Routine
Accessing the Visual FoxPro API
_DBStatus( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_DBStatus( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBStatus( ) API Library Routine
See Also Example

Returns status flags for the specified work area.

int _DBStatus(int workarea)
int workarea;               /* Work area. */

Remarks

If no table is open in the specified work area, _DBStatus( ) returns a negative integer whose absolute value is a Visual FoxPro error number. The following table shows returned status flags:

Flag | Setting
DB_BOF | Set under the same conditions as the Visual FoxPro function BOF( ).
DB_EOF | Set under the same conditions as the Visual FoxPro function EOF( ).
DB_RLOCKED | Set when the current record is locked, the table is locked, or the table is open exclusively.
DB_FLOCKED | Set when the table is locked or the table is open exclusively.
DB_EXCLUSIVE | Set when the table is open exclusively.
DB_READONLY | Set when the table is open without write access.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays the status of the table open in the current work area. It checks each bit in the value returned by _DBStatus( ) and displays an appropriate message to the screen.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBSTATUS
= DBSTATUS()  && displays status of DBF in current work area

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   int dbstatus = _DBStatus(-1);
   _PutStr("\nStatus of DBF in current work area:");
   if (dbstatus & DB_BOF)
      _PutStr("\nBOF()");
   if (dbstatus & DB_EOF)
      _PutStr("\nEOF()");
   if (dbstatus & DB_RLOCKED)
      _PutStr("\nCurrent record is RLOCKed");
   if (dbstatus & DB_FLOCKED)
      _PutStr("\nDatabase is FLOCKed");
   if (dbstatus & DB_EXCLUSIVE)
      _PutStr("\nDatabase is open EXCLUSIVEly");
   if (dbstatus & DB_READONLY)
      _PutStr("\nDatabase is READONLY");
}

FoxInfo myFoxInfo[] = {
   {"DBSTATUS", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBLock( ) API Library Routine
_DBUnlock( ) API Library Routine
Accessing the Visual FoxPro API
BOF( ) Function
EOF( ) Function
ISRLOCKED( ) Function
ISFLOCKED( ) Function
ISEXCLUSIVE( ) Function
ISREADONLY( ) Function
API Library Routines A-Z
API Library Routines by Category


_DBUnlock( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBUnlock( ) API Library Routine
See Also Example

Releases all user-obtained locks on records or the file in the work area specified by workarea.

void _DBUnlock(int workarea)
int workarea;               /* Work area. */

Example

The following example uses _DBUnlock( ) to unlock all records of the table open in the current work area. The Visual FoxPro code demonstrates _DBUnlock( ) and verifies that it's working properly.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBUNLOCK
DO CreateTest
USE Test SHARED
GO 2
= XRLOCK()
LIST STAT  && shows that record #2 is locked
= XUNLOCK()
LIST STAT  && shows no records are locked
= XFLOCK()
LIST STAT  && shows that whole DBF is locked
= XUNLOCK()
LIST STAT  && shows no records are locked

PROCEDURE CreateTest

CREATE TABLE test (ABC C(20))
APPEND BLANK
REPLACE ABC WITH "Golly month of"
APPEND BLANK
REPLACE ABC WITH "A twelfth of"
APPEND BLANK
REPLACE ABC WITH "Hello, world"
APPEND BLANK
REPLACE ABC WITH "When in the"
GO TOP

RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR xLockRecord(ParamBlk FAR *parm)
{
   _DBLock(-1, DBL_RECORD);
}
FAR xLockFile(ParamBlk FAR *parm)
{
   _DBLock(-1, DBL_FILE);
}
FAR xUnLockFile(ParamBlk FAR *parm)
{
   _DBUnLock(-1);
}
FoxInfo myFoxInfo[] = {
   {"XRLOCK",  (FPFI) xLockRecord, 0, ""},
   {"XFLOCK",  (FPFI) xLockFile, 0, ""},
   {"XUNLOCK", (FPFI) xUnLockFile, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBAppend( ) API Library Routine
_DBLock( ) API Library Routine
_DBReplace( ) API Library Routine
_DBStatus( ) API Library Routine
_DBWrite( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_DBUnwind( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBUnwind( ) API Library Routine
See Also Example

Works like the Visual FoxPro GO BOTTOM command in the specified work area, and then returns the current record number.

long _DBUnwind(int workarea)
int workarea;               /* Work area. */

Example

The following example calls _DBUnwind( ) for the table open in the current work area.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBUNWIND
DO CreateTest
? DBUNWIND()   && returns new record #
SKIP
? EOF()       && now EOF() returns .T.

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _RetInt(_DBUnwind(-1), 10);
}

FoxInfo myFoxInfo[] = {
   {"DBUNWIND", (FPFI) Example, 0, ""},
};

FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBRewind( ) API Library Routine
_DBWrite( ) API Library Routine
Field and Record Manipulation
Records
API Library Routines A-Z
API Library Routines by Category


_DBWrite( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DBWrite( ) API Library Routine
See Also Example

Writes to disk the current record in the specified work area and updates all affected indexes.

int _DBWrite(int workarea)
int workarea;               /* Work area. */

Remarks

Any time the record pointer is moved to another record, this updating occurs automatically. If no field data has been replaced, _DBWrite( ) has no effect. _DBWrite( ) returns 0 if the routine is successful. If the routine fails, _DBWrite( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example carries out a _DBReplace( ) using the two calling parameters, one a table field passed by reference, the other a value of the appropriate type. It executes a LIST NEXT 1 Visual FoxPro command before and after a call to _DBWrite( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO DBWRITE
DO CreateTest
GO 3
=DBWRITE( @ABC, "Replacement Record 1")

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   int RetValue;

   if (RetValue = _DBReplace(&parm->p[0].loc, &parm->p[1].val)) {
      _UserError("\n_DBReplace() failed");
   }

   if (RetValue = _DBWrite(-1)) {
      _Error(-RetValue);
   }
   _Execute("LIST NEXT 1");
}

FoxInfo myFoxInfo[] = {
   {"DBWRITE", (FPFI) Example, 2, "R,?"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_DBLock( ) API Library Routine
_DBReplace( ) API Library Routine
_DBUnlock( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_DeActivateHandler( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DeActivateHandler( ) API Library Routine
See Also Example

_DeActivateHandler( ) removes the specified event handler from the event processor list.

void _DeActivateHandler(unsigned int EventIdentifier)
unsigned int EventIdentifier;      /* ID of event handler
 to be removed from list. */

Remarks

You must remove each event handler, indicated by EventIdentifier, from the handler list when its library is unloaded.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example activates an event handler when the library is loaded. The event handler prints a message for every event and lets Visual FoxPro process the message. The event handler is deactivated when the library is unloaded. As in the following example, _DeActivateHandler( ) is usually called from a CALLONUNLOAD function.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DEACTHAN

C Code

Copy Code
#include <pro_ext.h>

static int HandlerID;

//   This is the routine that is registered as an event handler.
FAR EventHandler(WHandle theWindow, EventRec FAR *ev)
{
   _PutStr("\nEventHandler() called.");
   return NO;   // event still needs to be handled by Visual FoxPro
}

FAR Activate()
{
   HandlerID = _ActivateHandler(EventHandler);
}

//   When the library is unloaded we must deactivate the event handler
//   in a CALLONUNLOAD function.
FAR DeActivate()
{
   _DeActivateHandler(HandlerID);
}

FoxInfo myFoxInfo[] = {
   {"ACTIVATE",  (FPFI) Activate, CALLONLOAD, ""},
   {"DEACTIVATE", (FPFI)  DeActivate, CALLONUNLOAD, ""}
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_ActivateHandler( ) API Library Routine
_FindWindow( ) API Library Routine
_GlobalToLocal( ) API Library Routine
_MousePos( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_DeActivateIdle( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DeActivateIdle( ) API Library Routine
See Also Example

Removes the specified routine from the idle loop.

void _DeActivateIdle(unsigned int IdleIdentifier)
unsigned int IdleIdentifier;         /* Routine to be removed
 from idle list. */

Remarks

You must remove each idle routine from the idle routine list when its library is unloaded.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example activates an idle event handler when the library is loaded. The idle event handler simply prints a message and is deactivated when the library is unloaded. As in the following example, _DeActivateIdle( ) is usually called from a CALLONUNLOAD function.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DEACTIDL

C Code

Copy Code
#include <pro_ext.h>

static unsigned IdlerID;

//   This is the routine that is registered as an idle event handler.
void FAR IdleHandler(WHandle wh, EventRec *ev)
{
   _PutStr("\nIdleHandler() called.");
}

void FAR Activate(ParamBlk FAR *parm)
{
   IdlerID = _ActivateIdle((FPFI) IdleHandler);
}

//   When the library is unloaded we must deactivate the idle event
//   handler in a CALLONUNLOAD function.
void FAR DeActivate(ParamBlk FAR *parm)
{
   _DeActivateIdle(IdlerID);
}

FoxInfo myFoxInfo[] = {
   {"ACTIVATE",  (FPFI) Activate, CALLONLOAD,   ""},
   {"DEACTIVATE",  (FPFI) DeActivate, CALLONUNLOAD, ""}
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_ActivateIdle( ) API Library Routine
_FindWindow( ) API Library Routine
_GlobalToLocal( ) API Library Routine
_MousePos( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_DeActivateMenu( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DeActivateMenu( ) API Library Routine
See Also Example

Removes a menu from the screen.

void _DeActivateMenu(MENUID menuid)
MENUID menuid;            /* Menu identifier. */

Remarks

The menu isn't released from memory and can be reactivated with _ActivateMenu( ).

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example activates and deactivates a menu several times.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DEACTMEN

C Code

Copy Code
#include <pro_ext.h>

FAR DeActMenuEx(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);
   _Execute("WAIT WINDOW 'Menu activated'");
   _DeActivateMenu(menuId);
   _Execute("WAIT WINDOW 'Menu deactivated'");
   _ActivateMenu(menuId);
   _Execute("WAIT WINDOW 'Menu activated'");
   _DeActivateMenu(menuId);
   _Execute("WAIT WINDOW 'Menu deactivated'");

   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) DeActMenuEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_ActivateMenu( ) API Library Routine
Accessing the Visual FoxPro API
DEACTIVATE MENU Command
ACTIVATE MENU Command
HIDE MENU Command
API Library Routines A-Z
API Library Routines by Category


_DefaultProcess( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DefaultProcess( ) API Library Routine
See Also Example

Provides the default event processing for an event returned by _GetNextEvent( ) when the event does not need special handling.

void _DefaultProcess(EventRec FAR *event)
EventRec FAR *event;      /* Event to be processed. */

Remarks

This makes it easier for an external routine to use windows and still have them act consistently with the rest of the product.

Note:
Don't call _DefaultProcess() from an event handler.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example is a loop consisting of a call to _GetNextEvent( ) followed by a call to _DefaultProcess( ). All events during this procedure receive their default processing.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DEFAPROC

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   EventRec ev;
   int i;

   for (i = 0; i < 16; i++)
{
      _GetNextEvent(&ev);
      _DefaultProcess(&ev);
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_FindWindow( ) API Library Routine
_GetNextEvent( ) API Library Routine
_GlobalToLocal( ) API Library Routine
Events in Visual FoxPro
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_Dialog( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_Dialog( ) API Library Routine
See Also Example

Displays on the screen a dialog box that is the specified color scheme and contains the specified body text and button text.

int _Dialog(int scheme, char FAR *body_text, char FAR *button1,
            char FAR *button2, char FAR *button3, int default, int
 escape)
int scheme;                  /* Color scheme number. */
char FAR *body_text;         /* Text in dialog. */
char FAR *button1;         /* Button prompt. */
char FAR *button2;         /* Button prompt. */
char FAR *button3;         /* Button prompt. */
int default;                  /* Number of the default button. */
int escape;                  /* Number of the button to press if Esc. */

Remarks

_Dialog( ) returns the number of the button the user chooses.

To specify fewer than three buttons for the displayed dialog box, specify 0 as a button prompt to leave any of the three buttons blank. The default parameter specifies which button to highlight in the dialog box as the default button, and the escape parameter specifies which button to process as chosen if the user presses ESC.

If you specify no buttons, Visual FoxPro displays the dialog box and waits for the user to press a key or click the left mouse button. If the user presses Esc, _Dialog( ) returns the escape value; otherwise, it returns the default value.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates four dialog boxes with three, two, one, and no buttons.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DIALOG

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

void FAR dialogEx(ParamBlk FAR *parm)
{
   int selection;

   selection = _Dialog(DIALOG_SCHEME, "Example dialog with 3 buttons.",
      "First", "Second", "Third", 2, 3);

   _PutStr("\nItem selected ="); putLong(selection);

   selection = _Dialog(DIALOG_SCHEME, "Example dialog with 2 buttons.",
      "First", "Second", 0, 2, 2);

   _PutStr("\nItem selected ="); putLong(selection);

   selection = _Dialog(DIALOG_SCHEME, "Example dialog with 1 button.",
      "First", (char *)0, (char *)0, 1, 1);

   _PutStr("\nItem selected ="); putLong(selection);

   selection = _Dialog(DIALOG_SCHEME, "Example dialog no buttons.",
      (char *)0, (char *)0, (char *)0, 1, 2);

   _PutStr("\nItem selected ="); putLong(selection);
}

FoxInfo myFoxInfo[] = {
   {"DIALOGEX", (FPFI) dialogEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
Accessing the Visual FoxPro API
SET LIBRARY Command


_DisposeItem( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DisposeItem( ) API Library Routine
See Also Example

Releases from memory the specified menu item, and frees all memory storage associated with this item.

void _DisposeItem(MENUID menuid, ITEMID itemid)
MENUID menuid;            /* Menu identifier. */
ITEMID itemid;            /* Menu item identifier. */

Remarks

_DisposeItem( ) doesn't release any submenus that are associated with the item.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a menu with three items and then uses _DisposeItem( ) to remove two of the items.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DISPITEM

C Code

Copy Code
#include <pro_ext.h>

FAR DisposeItemEx(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);
   _Execute("WAIT WINDOW 'Menu has three items'");

   _DisposeItem(menuId, _GetItemId(menuId, 1));
   _Execute("WAIT WINDOW 'Menu has two items'");

   _DisposeItem(menuId, _GetItemId(menuId, 0));
   _Execute("WAIT WINDOW 'Menu has one item'");

   _DisposeMenu(menuId);
}
FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) DisposeItemEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_NewItem( ) API Library Routine
_GetItemId( ) API Library Routine
How to: Enable and Disable Menu Items
Creating Menus, Shortcut Menus, Menu Items, and Submenus


_DisposeMenu( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_DisposeMenu( ) API Library Routine
See Also Example

Releases the specified menu and all its items and frees all memory associated with this menu.

void _DisposeMenu(MENUID menuid)
MENUID menuid;            /* Menu identifier. */

Remarks

_DisposeMenu( ) doesn't release any submenus that are associated with the menu.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example calls _DisposeMenu( ) after the user chooses a menu item.

Visual FoxPro Code

Copy Code
SET LIBRARY TO DISPMENU

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR onSelection(long menuId, long itemId)
{
   _PutStr("\nitemId = "); putLong(itemId);
   _DisposeMenu(menuId);
}

FAR activateMenu(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);
   _OnSelection(menuId, -1, onSelection);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) activateMenu, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_GetNewMenuId( ) API Library Routine
_NewMenu( ) API Library Routine
Accessing the Visual FoxPro API


_EdActive( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdActive( ) API Library Routine
See Also Example

Allows you to hide (deactivate) or show (activate) the selection range or the insertion point position in the specified window.

void _EdActive(WHANDLE wh, int Show)
WHANDLE wh;            /* Handle of editing window.*/
int Show;                     /* Boolean hide or show selection. */

Remarks

Specifying the Show parameter as TRUE shows the selection range or insertion point position, and specifying Show as FALSE hides the selection range or insertion point position.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens an edit window for a file whose name is passed as a parameter and selects the first character in the file. Using _EdActive( ), the example activates and then deactivates the selection.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDACTIVE
fc = FCREATE("x", 0)
FOR i = 1 TO 90
   = FPUTS(fc, REPL(ALLT(STR(i)), i), i)
ENDFOR
= FCLOSE(fc)

= EDACTIVE("x")   && Call our API routine

C Code

Copy Code
#include <pro_ext.h>

FAR EdActiveEx(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   pFILENAME[parm->p[0].val.ev_length] = '\0';
   wh = _EdOpenFile(pFILENAME, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSelect(wh, 0, 1);

   _EdActive(wh, TRUE);
   _Execute("WAIT WINDOW 'Selection active'");

   _EdActive(wh, FALSE);
   _Execute("WAIT WINDOW 'Selection inactive'");
}

FoxInfo myFoxInfo[] = {
   {"EDACTIVE", (FPFI) EdActiveEx, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdSelect( ) API Library Routine
_EdCloseFile( ) API Library Routine
SYS(2002) - Turn Insertion Point On or Off
_EdCopy( ) API Library Routine


_EdCloseFile( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdCloseFile( ) API Library Routine
See Also Example

Closes both the specified editing window and the file displaying in the window.

int _EdCloseFile(WHANDLE wh, int option)
WHANDLE wh;            /* Handle of editing window. */
int option;                  /* Closing options. */

Remarks

The option parameter can be one of the following:

Option parameter values

int | result
0 | Immediately save.
1 | Save after dialog box confirmation.
2 | Open Save As dialog box.

_EdCloseFile( ) returns one of the following:

_EdCloseFile( ) return values

int | meaning
1 | Cancel without saving file.
0 | Save and close file.
– 1 | Discard changes and close file.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens for editing a single file specified by a parameter, deletes a character, and closes the edit session three times. The first time, the routine calls _EdCloseFile( ) with the "Immediately save" option, the second time with the "Save after dialog box" option, and the third time with the "Open Save As dialog box" option. Each time, the routine shows the return value of _EdCloseFile( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDCLOSE
= EDCLOSE("x")

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 5;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   int retValue;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   // Open, delete a character, close "save without asking"
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);

   _HUnLock(parm->p[0].val.ev_handle);

   _EdSelect(wh, 0, 1);
   _EdDelete(wh);
   retValue = _EdCloseFile(wh, 0); // save without asking
   _PutStr("\n_EdCloseFile() ="); putLong(retValue);

   // Open, delete a character, close "save with asking"
   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSelect(wh, 0, 1);
   _EdDelete(wh);
   retValue = _EdCloseFile(wh, 1); // save with asking
   _PutStr("\n_EdCloseFile() ="); putLong(retValue);

   // Open, delete a character, close "save as"
   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSelect(wh, 0, 1);
   _EdDelete(wh);
   retValue = _EdCloseFile(wh, 2); // save as
   _PutStr("\n_EdCloseFile() ="); putLong(retValue);
}

FoxInfo myFoxInfo[] = {
   {"EDCLOSE", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdOpenFile( ) API Library Routine
_EdRevert( ) API Library Routine
_EdSave( ) API Library Routine
_EdSelect( ) API Library Routine


_EdCopy( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdCopy( ) API Library Routine
See Also Example

Copies the selected portion of the file in the specified editing window to the clipboard.

void _EdCopy(WHANDLE wh)
WHANDLE wh;            /* Handle of editing window. */

Example

The following example opens for editing a file specified by a parameter, copies the first character to the clipboard using _EdCopy( ), and pastes the character after the second character using _EdPaste( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDCOPY
= EDCOPY("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSelect(wh, 0, 1);
   _EdCopy(wh);
   _EdSetPos(wh, 2);
   _EdPaste(wh);
}

FoxInfo myFoxInfo[] = {
   {"EDCOPY", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetPos( ) API Library Routine
_EdPaste( ) API Library Routine
_EdSelect( ) API Library Routine
_EdSetPos( ) API Library Routine
_EdCloseFile( ) API Library Routine


_EdCut( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdCut( ) API Library Routine
See Also Example

Copies the selected portion of the file in the specified editing window to the clipboard, and deletes it from the specified window.

void _EdCut(WHANDLE wh)
WHANDLE wh;            /* Handle of editing window. */

Example

The following example opens for editing a file specified by a parameter, cuts the first character to the clipboard using _EdCut( ), and pastes the character after the second character using _EdPaste( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDCUT
= EDCUT("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSelect(wh, 0, 1);
   _EdCut(wh);
   _EdSetPos(wh, 2);
   _EdPaste(wh);
}

FoxInfo myFoxInfo[] = {
   {"EDCUT", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetPos( ) API Library Routine
_EdPaste( ) API Library Routine
_EdSelect( ) API Library Routine
_EdSetPos( ) API Library Routine


_EdDelete( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdDelete( ) API Library Routine
See Also Example

Deletes the selected portion of the file in the specified editing window.

void _EdDelete(WHANDLE wh)
WHANDLE wh;            /* Handle of editing window. */

Remarks

If nothing is selected, _EdDelete( ) deletes the character at the current insertion point position.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens for editing a file specified by a parameter and deletes the first character in the file using _EdDelete( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDDELETE
= EDDELETE("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   int retValue;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSelect(wh, 0, 1);
   _EdDelete(wh);
}

FoxInfo myFoxInfo[] = {
   {"EDDELETE", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetPos( ) API Library Routine
_EdSelect( ) API Library Routine
_EdSetPos( ) API Library Routine
Accessing the Visual FoxPro API


_EdGetChar( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdGetChar( ) API Library Routine
See Also Example

_EdGetChar( ) returns the character at the specified offset position in the file in the specified editing window.

TEXT _EdGetChar(WHANDLE wh, EDPOS thePos)
WHANDLE wh;         /* Handle of editing window. */
EDPOS thePos;            /* Offset position in file of character
 to be returned. */

Example

The following example opens for editing a file specified by a parameter and displays on the screen the entire contents of the file.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDGETCHA
= EDGETCHAR("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDENV EdEnv;
   EDPOS edpos;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   pFILENAME[parm->p[0].val.ev_length] = '\0';
   wh = _EdOpenFile(pFILENAME, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdGetEnv(wh, &EdEnv);

   for (edpos = 0; edpos <= EdEnv.length; edpos++)
   {
      _PutChr(_EdGetChar(wh, edpos));
   }
}

FoxInfo myFoxInfo[] = {
   {"EDGETCHAR", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetPos( ) API Library Routine
_EdSetPos( ) API Library Routine
_EdGetStr( ) API Library Routine
_EdGetEnv( ) API Library Routine


_EdGetEnv( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdGetEnv( ) API Library Routine
See Also Example

_EdGetEnv( ) provides the editor environment information in *EDENV.

int _EdGetEnv(WHANDLE wh, *EDENV theEdEnv)
WHANDLE wh;            /* Handle of editing window. */
*EDENV theEdEnv;         /* Environment settings. */

Remarks

The structure of *EDENV is listed below.

Note:
In the comments below, an (R) indicates that this member is read-only and can't be set using _EdSetEnv( ). A (B) indicates that this member takes on one of two Boolean values: 1 (True) or 0 (False).

Copy Code
typedef struct
{
   char            filename[MAXFILENAME];   // (R)
   EDPOS         length;         // # of bytes in text. (R)
   unsigned short   lenLimit;         // Max allowable length.
 0 = infinite.

   unsigned short   dirty,            // Has the file been changed?
 (R, B)
                  autoIndent,      // Auto indent? (B)
                  backup,         // Make backup files? (B)
                  addLineFeeds,   // Add line feeds when saving? (B)
                  autoCompile,      // Shall we auto compile this thing?
 (B)
                  addCtrlZ,         // Add end of file ctrl-z? (B)
                  savePrefs,      // Save edit preferences? (B)
                  dragAndDrop,   // Allow drag-and-drop. (B)
                  readOnly,         // 0 = not r/o, 1 = file is r/o,
                                 // 2 = file is r/w, opened r/o,
                                 // 3 = file is r/o, opened r/o. (R)
                  status,            // Display status bar? (B)
                  lockPrefs,         // Can update the preferences ? (B)
                  insertMode;      // (B)

   short            wrap;            // If < 0, new line at Return only.
   EDPOS         selStart;         // Selection start. (R)
   EDPOS         selEnd;         // Selection end. (R)
   EDPOS         selAnchor;      // Selection anchor point. (R)
   short            justMode;      // Justification (0 = left, 1 =
 right, 2 = center).
   short            tabWidth;      // TAB size in spaces.

   char            fontName[MAXFONTNAME];
   short            fontSize;
   short            fontStyle;      // 0 = plain, 1 = bold, 2 =
 italic, 3 = bold italic.
   short            kind;         // Kind of editor session (R);
                              // EDCOMMAND, EDPROGRAM, etc.
} EDENV;

1 is returned if called in a Command or Editor session, otherwise 0 is returned.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens an editing session for a file specified by a parameter and displays each field of the EDENV structure for that file as returned by _EdGetEnv( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDGETENV
= EDGETENV("x")

C Code

Copy Code
#include <pro_ext.h>

void putLong(unsigned long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 6;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDENV EdEnv;
   EDPOS edpos;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdGetEnv(wh, &EdEnv);

   _PutStr("\nfilename: ");    _PutStr(EdEnv.filename);
   _PutStr("\nlength: ");    putLong(EdEnv.length);
   _PutStr("\nlenLimit: ");    putLong(EdEnv.lenLimit);
   _PutStr("\ndirty: ");     putLong(EdEnv.dirty);
   _PutStr("\nautoIndent: ");  putLong(EdEnv.autoIndent);
   _PutStr("\nbackup: ");    putLong(EdEnv.backup);
   _PutStr("\naddLineFeeds: ");  putLong(EdEnv.addLineFeeds);
   _PutStr("\nautoCompile: ");   putLong(EdEnv.autoCompile);
   _PutStr("\naddCtrlZ: ");    putLong(EdEnv.addCtrlZ);
   _PutStr("\nsavePrefs: ");   putLong(EdEnv.savePrefs);
   _PutStr("\ndragAndDrop: ");   putLong(EdEnv.dragAndDrop);
   _PutStr("\nreadOnly: ");    putLong(EdEnv.readOnly);
   _PutStr("\nstatus: ");    putLong(EdEnv.status);
   _PutStr("\nlockPrefs: ");   putLong(EdEnv.lockPrefs);
   _PutStr("\ninsertMode: ");  putLong(EdEnv.insertMode);
   _PutStr("\nwrap: ");    putLong(EdEnv.wrap);
   _PutStr("\nselStart: ");    putLong(EdEnv.selStart);
   _PutStr("\nselEnd: ");    putLong(EdEnv.selEnd);
   _PutStr("\nselAnchor: ");   putLong(EdEnv.selAnchor);
   _PutStr("\njustMode: ");    putLong(EdEnv.justMode);
   _PutStr("\ntabWidth: ");    putLong(EdEnv.tabWidth);
   _PutStr("\nfontName: ");    _PutStr(EdEnv.fontName);
   _PutStr("\nfontSize: ");    putLong(EdEnv.fontSize);
   _PutStr("\nfontStyle: ");   putLong(EdEnv.fontStyle);
   _PutStr("\nkind: ");    putLong(EdEnv.kind);
}

FoxInfo myFoxInfo[] = {
   {"EDGETENV", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdLastError( ) API Library Routine
_EdSetEnv( ) API Library Routine
_EdGetLineNum( ) API Library Routine
_EdGetChar( ) API Library Routine


_EdGetLineNum( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdGetLineNum( ) API Library Routine
See Also Example

Returns the line number of the passed offset position thePos in the file in the specified editing window.

EDLINE _EdGetLineNum(WHANDLE wh, EDPOS thePos)
WHANDLE wh;            /* Handle of editing window. */
EDPOS thePos;               /* Offset position in the file. */

Example

The following example opens an editing session for a file specified by a parameter and gets the EDPOS for line 12 by calling _EdGetLinePos( ). It then calls _EdGetLineNum( ) on this EDPOS, and this returns 12. Next, it increments the EDPOS and each time calls _EdGetLineNum( ) until the returned EDLINE changes. At this point, it calls _EdGetLinePos( ) for line 13.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDGETLIN
= EDGETLPOS("x")

C Code

Copy Code
#include <pro_ext.h>

void putLong(unsigned long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 6;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDENV EdEnv;
   EDPOS edpos;
   EDLINE edlin, original;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);

   edpos = _EdGetLinePos(wh, 12);
   _PutStr("\n_EdGetLinePos(wh, 12) =");
   putLong(edpos);

   original = edlin = _EdGetLineNum(wh, edpos);

   for (;;)
   {
      _PutStr("\n_EdGetLineNum(wh,");
      putLong(edpos);
      _PutStr(") = ");
      putLong(edlin);

      if (edlin != original)
      {
         break;
      }
      edpos++;
      edlin = _EdGetLineNum(wh, edpos);
   }

   edpos = _EdGetLinePos(wh, 13);
   _PutStr("\n_EdGetLinePos(wh, 13) ="); putLong(edpos);
}

FoxInfo myFoxInfo[] = {
   {"EDGETLPOS", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetChar( ) API Library Routine
_EdGetLinePos( ) API Library Routine
_EdGetEnv( ) API Library Routine


_EdGetLinePos( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdGetLinePos( ) API Library Routine
See Also Example

Returns the offset position of the first character of the specified line in the file in the specified editing window.

EDPOS _EdGetLinePos(WHANDLE wh, EDLINE theLine)
WHANDLE wh;            /* Handle of editing window. */
EDLINE theLine;            /* Line number. */

Example

The following example opens an editing session for a file specified by a parameter and gets the EDPOS for line 12 by calling _EdGetLinePos( ). It then calls _EdGetLineNum( ) on this EDPOS, and this returns 12. Next, it increments the EDPOS and each time calls _EdGetLineNum( ) until the EDLINE returned is changed. At this point, it calls _EdGetLinePos( ) for line 13.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDGETLPO
= EDGETLPOS("x")

C Code

Copy Code
#include <pro_ext.h>

void putLong(unsigned long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 6;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDENV EdEnv;
   EDPOS edpos;
   EDLINE edlin, original;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);

   edpos = _EdGetLinePos(wh, 12);
   _PutStr("\n_EdGetLinePos(wh, 12) =");
   putLong(edpos);

   original = edlin = _EdGetLineNum(wh, edpos);

   for (;;)
   {
      _PutStr("\n_EdGetLineNum(wh,");
      putLong(edpos);
      _PutStr(") = ");
      putLong(edlin);

      if (edlin != original)
      {
         break;
      }
      edpos++;
      edlin = _EdGetLineNum(wh, edpos);
   }

   edpos = _EdGetLinePos(wh, 13);
   _PutStr("\n_EdGetLinePos(wh, 13) ="); putLong(edpos);
}
FoxInfo myFoxInfo[] = {
   {"EDGETLPOS", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetLineNum( ) API Library Routine
_EdGetPos( ) API Library Routine
_EdGetChar( ) API Library Routine


_EdGetPos( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdGetPos( ) API Library Routine
See Also Example

Returns the current offset position of the insertion point in the file in the specified editing window.

EDPOS _EdGetPos(WHANDLE wh)
WHANDLE wh;            /* Handle of editing window. */

Remarks

If text is selected, _EdGetPos( ) returns the offset position of the anchor.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens an edit session for a file specified by a parameter. After setting the current insertion point with _EdSetPos( ), a call to _EdGetPos( ) is made to verify that it returns the insertion point offset position. After selecting text with _EdSelect( ), a call to _EdGetPos( ) is made to verify that it returns the anchor point offset position.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDGETPOS
= EDGETPOS("x")

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 6;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDPOS edpos;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSetPos(wh, 19);
   _PutStr("\n_EdSetPos(wh, 19)");
   edpos = _EdGetPos(wh);
   _PutStr("\n_EdGetPos(wh) ="); putLong(edpos);

   _EdSelect(wh, 5, 12);
   _PutStr("\n_EdSelect(wh, 5, 12)");
   edpos = _EdGetPos(wh);
   _PutStr("\n_EdGetPos(wh) ="); putLong(edpos);
}

FoxInfo myFoxInfo[] = {
   {"EDGETPOS", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetChar( ) API Library Routine
_EdSetPos( ) API Library Routine
_EdGetLinePos( ) API Library Routine


_EdGetStr( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdGetStr( ) API Library Routine
See Also Example

Places the text between and including the specified offset positions into the specified address.

void _EdGetStr(WHANDLE wh, EDPOS thePos, EDPOS thePos,
               TEXT *theStr)
WHANDLE wh;            /* Handle of editing window. */
EDPOS thePos;               /* Starting offset position. */
EDPOS thePos;               /* Stopping offset position. */
TEXT *theStr;               /* Where to put the text. */

Example

The following example takes a file name as a parameter and returns the first 16 bytes of the file.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDGETSTR
? EDGETSTR("x") && returns the first 16 characters of file "x"

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh;
   char FAR *buffer;
   char FAR *pFileName;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   pFileName = _HandToPtr(parm->p[0].val.ev_handle);
   pFileName[parm->p[0].val.ev_length] = '\0';
   wh = _EdOpenFile(pFileName, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);
   if ((buffer = _Alloca(17)) == 0) {
      _Error(182); // "Insufficient memory"
   }
   _EdGetStr(wh, 0, 15, buffer);
   buffer[16] = '\0';
   _RetChar(buffer);
}

FoxInfo myFoxInfo[] = {
   {"EDGETSTR", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetChar( ) API Library Routine
_EdSetPos( ) API Library Routine
_EdGetLinePos( ) API Library Routine


_EdIndent( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdIndent( ) API Library Routine
See Also Example

Indents the selected text in the file in the specified window the specified number of tab stops.

void _EdIndent(WHANDLE wh, int tabstops)
WHANDLE wh;            /* Handle of editing window. */
int tabstops;                  /* Number of tab stops. */

Remarks

You can specify a negative number for tabstops to cause a hanging indent for the selection.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens an editing session for a file specified by a parameter, and indents lines 13 and 15 in the file by a single tab stop.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDINDENT
= EDINDENT("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1)) {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSelect(wh, _EdGetLinePos(wh, 12), _EdGetLinePos(wh, 14));
   _EdIndent(wh, 1);
}
FoxInfo myFoxInfo[] = {
   {"EDINDENT", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetLineNum( ) API Library Routine
_EdGetLinePos( ) API Library Routine
_EdGetPos( ) API Library Routine
_EdSetPos( ) API Library Routine


_EdInsert( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdInsert( ) API Library Routine
See Also Example

Inserts the specified number of bytes, starting with the specified TEXT * address, at the insertion point.

void _EdInsert(WHANDLE wh, TEXT *theStr, unsigned long Bytes)
WHANDLE wh;            /* Handle of editing window. */
TEXT *theStr;               /* Address of beginning of insertion
 text. */
unsigned long Bytes;         /* Number of bytes to insert. */

Example

The following example opens an editing session for a file specified by a parameter and inserts the line of text "Hello, world" as the new fourteenth line in the file.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDINSERT
= EDINSERT("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1)) {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSetPos(wh, _EdGetLinePos(wh, 13));
   _EdInsert(wh, "Hello, world\n", _StrLen("Hello, world\n"));
}
FoxInfo myFoxInfo[] = {
   {"EDINSERT", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetPos( ) API Library Routine
_EdSetPos( ) API Library Routine
Accessing the Visual FoxPro API


_EdLastError( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdLastError( ) API Library Routine
See Also Example

_EdLastError( ) returns the error number of the most recent editor error associated with the specified editing window.

int _EdLastError(WHANDLE wh)
WHANDLE wh;            /* Handle of editing window. */

Example

The following example displays the error code returned by _EdLastError( ) after a number of editor operations. Since editor errors are reserved for severe situations, such as low memory, the following example will usually display an error code of 0.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDLASTER
= EDLASTERR("x")  && displays _EdLastError() after operations on file "x"

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;
   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
   char FAR *pFileName;
   WHANDLE wh;
   EDENV EdEnv;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   pFileName = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   pFileName[parm->p[0].val.ev_length] = '\0';

   wh = _EdOpenFile(pFileName, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);

//   Position past end of file
   _EdGetEnv(wh, &EdEnv);
   _EdSetPos(wh, EdEnv.length + 128);
   _PutStr("\n_EdLastError() ="); putLong(_EdLastError(wh));

//   _EdCopy() with no selection
   _EdSetPos(wh, 1);
   _EdCopy(wh);
   _PutStr("\n_EdLastError() ="); putLong(_EdLastError(wh));

//   _EdScrollToSel() with no selection
   _EdScrollToSel(wh, TRUE);
   _PutStr("\n_EdLastError() ="); putLong(_EdLastError(wh));
}

FoxInfo myFoxInfo[] = {
   {"EDLASTERR", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetEnv( ) API Library Routine
_EdSetEnv( ) API Library Routine
Accessing the Visual FoxPro API


_EdOpenFile( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdOpenFile( ) API Library Routine
See Also Example

Opens the specified file in a window, in order to begin an editing session.

WHANDLE _EdOpenFile(TEXT *filename, int mode)
TEXT *filename;            /* File to open. */
int mode;                     /* Mode option. */

Remarks

The following mode options are available: FO_READONLY, FO_WRITEONLY, and FO_READWRITE.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens an editor session for a file specified by a parameter.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDOPEN
= EDOPEN("x")  && opens editor session for file "x"

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"EDOPEN", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdCloseFile( ) API Library Routine
_EdRevert( ) API Library Routine
_EdSave( ) API Library Routine


_EdPaste( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdPaste( ) API Library Routine
See Also Example

Copies the contents of the clipboard into the file in the specified editing window at the insertion point.

void _EdPaste(WHANDLE wh)
WHANDLE wh;            /* Handle of editing window. */

Example

The following example opens for editing a file specified by a parameter, copies the first character to the clipboard using _EdCopy( ), and pastes the character after the second character using _EdPaste( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDPASTE
= EDCOPY("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSelect(wh, 0, 1);
   _EdCopy(wh);
   _EdSetPos(wh, 2);
   _EdPaste(wh);
}

FoxInfo myFoxInfo[] = {
   {"EDCOPY", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdCopy( ) API Library Routine
_EdCut( ) API Library Routine
_EdGetPos( ) API Library Routine
_EdSelect( ) API Library Routine
_EdSetPos( ) API Library Routine


_EdPosInView( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdPosInView( ) API Library Routine
See Also Example

int _EdPosInView(WHANDLE wh, EDPOS thePos)
WHANDLE wh;            /* Handle of editing window. */
EDPOS thePos;               /* Offset position. */

Remarks

_EdPosInView( ) returns True (an integer other than 0) if the offset position in the file in the specified editing window is visible, or False (0) if not.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens for editing a file specified by a parameter. After scrolling to the top of the file, the example calls _EdPosInView( ) to check whether the top of file and bottom of file are in view and the results are printed to the screen. Then the example scrolls to the bottom of the file, and again calls _EdPosInView( ) to check whether the top of file and bottom of file are in view.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDPOSINV
= POSINVIEW("x")

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDENV EdEnv;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdGetEnv(wh, &EdEnv);

   _EdScrollToPos(wh, 0, FALSE);
   _PutStr("\n_EdScrollToPos(wh, 0)");
   _PutStr("\n_EdPosInView(wh, 0) =");
   putLong(_EdPosInView(wh, 0));
   _PutStr("\n_EdPosInView(wh, EdEnv.length) =");
   putLong(_EdPosInView(wh, EdEnv.length));

   _EdScrollToPos(wh, EdEnv.length, FALSE);
   _PutStr("\n_EdScrollToPos(wh, EdEnv.length)");
   _PutStr("\n_EdPosInView(wh, 0) =");
   putLong(_EdPosInView(wh, 0));
   _PutStr("\n_EdPosInView(wh, EdEnv.length) =");
   putLong(_EdPosInView(wh, EdEnv.length));
}

FoxInfo myFoxInfo[] = {
   {"POSINVIEW", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetPos( ) API Library Routine
_EdSetPos( ) API Library Routine
Accessing the Visual FoxPro API


_EdRedo( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdRedo( ) API Library Routine
See Also Example

Performs again the change made to the file in the specified editing window that was undone by the most recent _EdUndo( ).

void _EdRedo(WHANDLE wh)
WHANDLE wh;            /* Handle of editing window. */

Example

The following example opens for editing a file specified by a parameter. After inserting a new line, the new line is removed using _EdUndo( ), and then inserted again using _EdRedo( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDREDO
= EDREDO("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSetPos(wh, _EdGetLinePos(wh, 13));
   _EdInsert(wh, "Hello, world\n", _StrLen("Hello, world\n"));

   _Execute("WAIT WINDOW 'New line inserted.  Press any key to undo.'");
   _EdUndo(wh);

   _Execute("WAIT WINDOW 'Insertion undone.  Press any key to redo.'");
   _EdRedo(wh);
}

FoxInfo myFoxInfo[] = {
   {"EDREDO", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdUndo( ) API Library Routine
_EdUndoOn( ) API Library Routine
_EdRevert( ) API Library Routine


_EdRevert( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdRevert( ) API Library Routine
See Also Example

Discards all changes made to the file displaying in the specified editing window since it was most recently saved with _EdSave( ).

void _EdRevert(WHANDLE wh)
WHANDLE wh;            /* Handle of editing window. */

Example

The following example opens for editing a file specified by a parameter. After some editing, insertion of a new line, indenting of two lines, and deletion of two lines, the changes are discarded using _EdRevert( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDREVERT
= EDREVERT("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSetPos(wh, _EdGetLinePos(wh, 13));
   _EdInsert(wh, "Hello, world\r\n", _StrLen("Hello, world\n"));

   _EdSelect(wh, _EdGetLinePos(wh, 14), _EdGetLinePos(wh, 16));
   _EdIndent(wh, 1);

   _EdSelect(wh, _EdGetLinePos(wh, 9), _EdGetLinePos(wh, 12));
   _EdDelete(wh);

   _EdRevert(wh);
}

FoxInfo myFoxInfo[] = {
   {"EDREVERT", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdRedo( ) API Library Routine
_EdUndo( ) API Library Routine
_EdUndoOn( ) API Library Routine
_EdSave( ) API Library Routine


_EdSave( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdSave( ) API Library Routine
See Also Example

_EdSave( ) saves the file in the specified window without ending the editing session.

void _EdSave(WHANDLE wh)
WHANDLE wh;            /* Handle of editing window. */

Example

The following example opens for editing a file specified by a parameter. The example inserts a new line, indents two lines, and deletes two lines. After the insertion of the new line, the example calls _EdSave( ). Then, after the indentation and deletion, the example calls _EdUndo( ) three times in an attempt to undo all of the editing, but the insertion made before the call to _EdSave( ) can't be undone. The example performs two more editing operations, inserting two lines and deleting two lines, with a call to _EdSave( ) between them. Last, the example calls _EdRevert( ), but it too can only undo changes made since the last _EdSave( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDSAVE
= EDSAVE("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSetPos(wh, _EdGetLinePos(wh, 13));
   _EdInsert(wh, "Hello, world\r\n", _StrLen("Hello, world\n"));

   _EdSave(wh);

   _EdSelect(wh, _EdGetLinePos(wh, 14), _EdGetLinePos(wh, 16));
   _EdIndent(wh, 1);

   _EdSelect(wh, _EdGetLinePos(wh, 9), _EdGetLinePos(wh, 12));
   _EdDelete(wh);

   _Execute("WAIT WINDOW 'Press any key to undo changes.'");
   _EdUndo(wh);  // undo deletion
   _EdUndo(wh);  // undo indent
   _EdUndo(wh);  // attempt to undo insertion, but can't

   _EdSelect(wh, _EdGetLinePos(wh, 14), _EdGetLinePos(wh, 16));
   _EdIndent(wh, 1);

   _EdSave(wh);

   _EdSelect(wh, _EdGetLinePos(wh, 9), _EdGetLinePos(wh, 12));
   _EdDelete(wh);

   _EdRevert(wh);   // undoes deletion
}

FoxInfo myFoxInfo[] = {
   {"EDSAVE", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdCloseFile( ) API Library Routine
_EdOpenFile( ) API Library Routine
_EdRevert( ) API Library Routine
_EdUndo( ) API Library Routine


_EdScrollToPos( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdScrollToPos( ) API Library Routine
See Also Example

Ensures that the offset position you specify in the file in the designated editing window is visible.

void _EdScrollToPos(WHANDLE wh, EDPOS thePos, int Center)
WHANDLE wh;            /* Handle of editing window. */
EDPOS thePos;               /* Offset position to make visible. */
int Center;                  /* Whether or not to center position
 in window. */

Remarks

_EdScrollToPos( ) doesn't move the insertion point. Specify Center as TRUE to center the position vertically in the window, or as FALSE to not center the position vertically.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens for editing a file specified by a parameter. After scrolling to the top of the file by calling _EdScrollToPos( ), the procedure calls _EdPosInView( ) to check whether the top of file and bottom of file are in view, and prints the results on the screen. Then it scrolls to the bottom of the file by calling _EdScrollToPos( ), and again calls _EdPosInView( ) to check whether the top of file and bottom of file are in view.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDSCTOPO
= POSINVIEW("x")

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDENV EdEnv;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1)) {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdGetEnv(wh, &EdEnv);

   _EdScrollToPos(wh, 0, FALSE);
   _PutStr("\n_EdScrollToPos(wh, 0)");
   _PutStr("\n_EdPosInView(wh, 0) =");
   putLong(_EdPosInView(wh, 0));
   _PutStr("\n_EdPosInView(wh, EdEnv.length) =");
   putLong(_EdPosInView(wh, EdEnv.length));

   _EdScrollToPos(wh, EdEnv.length, FALSE);
   _PutStr("\n_EdScrollToPos(wh, EdEnv.length)");
   _PutStr("\n_EdPosInView(wh, 0) =");
   putLong(_EdPosInView(wh, 0));
   _PutStr("\n_EdPosInView(wh, EdEnv.length) =");
   putLong(_EdPosInView(wh, EdEnv.length));
}

FoxInfo myFoxInfo[] = {
   {"POSINVIEW", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdPosInView( ) API Library Routine
Accessing the Visual FoxPro API
SYS(2002) - Turn Insertion Point On or Off
_EdInsert( ) API Library Routine


_EdScrollToSel( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdScrollToSel( ) API Library Routine
See Also Example

Ensures that the selected text in the designated window is visible.

void _EdScrollToSel(WHANDLE wh, int Center)
WHANDLE wh;            /* Handle of editing window. */
int Center;                  /* Whether to center anchor point in
 window. */

Remarks

Specify Center as TRUE to center the anchor point vertically in the window, or as FALSE to not center the anchor point.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens for editing a file specified by a parameter. The example makes a selection near the bottom of the file. After the user presses a key in response to a Visual FoxPro WAIT command, the example scrolls the editing window to the selection by calling _EdScrollToSel( ). The example then repeats the operation for a selection made near the top of the file.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDSCTOSE
= TOSEL("x")

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDENV EdEnv;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READONLY);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdScrollToPos(wh, 0, TRUE);

   _EdGetEnv(wh, &EdEnv);
   _EdSelect(wh, EdEnv.length - 16, EdEnv.length);

   _PutStr("\nMade selection at end of file.");
   _Execute("WAIT WINDOW 'Press any key to scroll to selection.'");

   _EdScrollToSel(wh, TRUE);
   _EdSelect(wh, 1, 16);

   _PutStr("\nMade selection at beginning of file.");
   _Execute("WAIT WINDOW 'Press any key to scroll to selection.'");

   _EdScrollToSel(wh, TRUE);
}

FoxInfo myFoxInfo[] = {
   {"TOSEL", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetPos( ) API Library Routine
_EdSelect( ) API Library Routine
_EdSetPos( ) API Library Routine


_EdSelect( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdSelect( ) API Library Routine
See Also Example

Selects the range between the two specified offset positions, inclusive, of the file in the designated editing window.

void _EdSelect(WHANDLE wh, EDPOS startPos, EDPOS endPos)
WHANDLE wh;            /* Handle of editing window. */
EDPOS startPos;         /* Beginning offset position of selection. */
EDPOS endPos;         /* Ending offset position of selection. */

Example

The following example opens for editing a file specified by a parameter, selects the first character in the file using _EdSelect( ), copies the selection to the clipboard using _EdCopy( ), and pastes it after the second character using _EdPaste( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDSELECT
= EDCOPY("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSelect(wh, 0, 1);
   _EdCopy(wh);
   _EdSetPos(wh, 2);
   _EdPaste(wh);
}

FoxInfo myFoxInfo[] = {
   {"EDCOPY", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdCopy( ) API Library Routine
_EdCut( ) API Library Routine
_EdPaste( ) API Library Routine


_EdSendKey( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdSendKey( ) API Library Routine
See Also Example

Simulates the key press associated with the ASCII character number specified by charNum.

void _EdSendKey(WHANDLE wh, int charNum)
WHANDLE wh;            /* Handle of editing window. */
int charNum;               /* Number of character. */

Example

The following example opens for editing a file specified by a parameter. It inserts a line of text, "Hello, World", by sending the individual characters with _EdSendKey( ). It then uses _EdSendKey( ) to send a carriage return and linefeed and to insert an ASCII escape character. Notice that the escape character isn't interpreted as "discard editing session."

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDSENDKE
= SENDKEY("x")

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDENV EdEnv;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   // Insert a line of text using _EdSendKey()
   _EdSetPos(wh, 0);
   _EdSendKey(wh, 'H');
   _EdSendKey(wh, 'e');
   _EdSendKey(wh, 'l');
   _EdSendKey(wh, 'l');
   _EdSendKey(wh, 'o');
   _EdSendKey(wh, ',');
   _EdSendKey(wh, ' ');
   _EdSendKey(wh, 'W');
   _EdSendKey(wh, 'o');
   _EdSendKey(wh, 'r');
   _EdSendKey(wh, 'l');
   _EdSendKey(wh, 'd');
   _EdSendKey(wh, '.');
   _EdSendKey(wh, 0x0d); // carriage return
   _EdSendKey(wh, 0x0a); // line feed
   _EdSendKey(wh, 0x1b); // esc char code is inserted in file
}

FoxInfo myFoxInfo[] = {
   {"SENDKEY", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdInsert( ) API Library Routine
_EdGetChar( ) API Library Routine
_ASCIICOLS System Variable
_ASCIIROWS System Variable


_EdSetEnv( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdSetEnv( ) API Library Routine
See Also Example

Determines various editor settings.

int _EdSetEnv(WHANDLE wh, *EDENV theEdEnv)
WHANDLE wh;            /* Handle of editing window. */
*EDENV theEdEnv;         /* Editor settings. */

Remarks

For the structure of *EDENV, see _EdGetEnv( ) API Library Routine.

1 is returned if called in a Command or Editor session, otherwise 0 is returned.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens for editing a file specified by a parameter. After indenting the first two lines of the file, it uses _EdSetEnv( ) to change the size of a tab stop to 6 characters and then to 9 characters.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDSETENV
= EDSETENV("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDENV EdEnv;
   EDPOS edpos;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
{
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdGetEnv(wh, &EdEnv);

   _EdSelect(wh, _EdGetLinePos(wh, 1), _EdGetLinePos(wh, 3));
   _EdIndent(wh, 1);

   _Execute("WAIT WINDOW 'Press any key\
      to change tabs to 6 characters.'");
   EdEnv.tabWidth = 6;
   _EdSetEnv(wh, &EdEnv);

   _Execute("WAIT WINDOW 'Press any key \
      to change tabs to 9 characters.'");
   EdEnv.tabWidth = 9;
   _EdSetEnv(wh, &EdEnv);
}

FoxInfo myFoxInfo[] = {
   {"EDSETENV", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetEnv( ) API Library Routine
_EdLastError( ) API Library Routine
Accessing the Visual FoxPro API


_EdSetPos( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdSetPos( ) API Library Routine
See Also Example

Moves the insertion point to the specified offset position in the file in the specified editing window, unselecting any selected text.

void _EdSetPos(WHANDLE wh, EDPOS thePos)
WHANDLE wh;            /* Handle of editing window. */
EDPOS thePos;               /* Specified offset position. */

Example

The following example opens for editing a file specified by a parameter. Using _EdSetPos( ), it sets the insertion point to position 19 of the file. It calls _EdGetPos( ) and inserts some text to verify that the insertion point has been set.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDSETPOS
= EDSETPOS('x')

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 6;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDPOS edpos;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSetPos(wh, 19);
   _PutStr("\n_EdSetPos(wh, 19)");
   edpos = _EdGetPos(wh);
   _PutStr("\n_EdGetPos(wh) ="); putLong(edpos);
   _EdInsert(wh, "*** Inserted at EDPOS = 19 ***",
      _StrLen("*** Inserted at EDPOS = 19 ***"));
}

FoxInfo myFoxInfo[] = {
   {"EDSETPOS", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_EdGetLineNum( ) API Library Routine
_EdGetChar( ) API Library Routine
_EdGetPos( ) API Library Routine


_EdSkipLines( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdSkipLines( ) API Library Routine
See Also Example

Moves the insertion point to the beginning of the line int lines from its current offset position thePos.

EDPOS _EdSkipLines(WHANDLE wh, EDPOS thePos, int offset)
WHANDLE wh;            /* Handle of editing window. */
EDPOS thePos;               /* Current offset position. */
int offset;                     /* Number of lines to skip. */

Remarks

You can specify a positive or negative number of lines.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens for editing a file specified by a parameter. It uses _EdSkipLines( ) to find the offset positions, then selects lines 3 and 4.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDSKIPLI
= SKIPLINE("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;
   EDPOS edpos;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   // select next two lines
   edpos = _EdSkipLines(wh, 0, 2); // skip to two lines from top
   _EdSelect(wh, edpos, _EdSkipLines(wh, edpos, 2));
   _Execute("WAIT WINDOW 'Using _EdSkipLines() \
      to select lines 3 and 4'");
}

FoxInfo myFoxInfo[] = {
   {"SKIPLINE", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdGetPos( ) API Library Routine
_EdSetPos( ) API Library Routine
Accessing the Visual FoxPro API


_EdUndo( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdUndo( ) API Library Routine
See Also Example

Undoes the single most recent change made to the file in the specified window.

void _EdUndo(WHANDLE wh)
WHANDLE wh;            /* Handle of editing window. */

Remarks

When the user makes changes to a file, these changes are recorded in the undo buffer. _EdUndo( ) can be issued multiple times to undo multiple changes. You can't undo a change made prior to issuing _EdSave( ).

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens a file specified by a parameter for editing. After inserting a new line, it uses _EdUndo( ) to delete the line, and then calls _EdRedo( ) to restore the inserted line.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDUNDO
= EDREDO("x")

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define pFILENAME ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   pFILENAME[parm->p[0].val.ev_length] = '\0';

   _HLock(parm->p[0].val.ev_handle);
   wh = _EdOpenFile(pFILENAME, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdSetPos(wh, _EdGetLinePos(wh, 13));
   _EdInsert(wh, "Hello, world\n", _StrLen("Hello, world\n"));

   _Execute("WAIT WINDOW 'New line inserted.\
      Press any key to undo.'");
   _EdUndo(wh);

   _Execute("WAIT WINDOW 'Insertion undone.  Press any key to redo.'");
   _EdRedo(wh);
}

FoxInfo myFoxInfo[] = {
   {"EDREDO", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdRedo( ) API Library Routine
_EdUndoOn( ) API Library Routine
_EdSave( ) API Library Routine
Accessing the Visual FoxPro API


_EdUndoOn( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_EdUndoOn( ) API Library Routine
See Also Example

Enables you to group a series of actions as a single action for use with _EdUndo( ) and _EdRedo( ).

void _EdUndoOn(WHANDLE wh, int Grouped)
WHANDLE wh;            /* Window handle. */
int Grouped;                  /* Toggle grouping off. */

Remarks

Actions that occur after you pass the Grouped parameter as FALSE with _EdUndoOn( ), or after you issue _EdUndo( ), are no longer grouped as a single action.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example shows how to use _EdUndoOn( ) to group edit operations that you can undo as a group using _EdUndo( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EDUNDOON
= EDUNDOON("x")  && edit file "x"

C Code

Copy Code
#include <pro_ext.h>
#define TRUE   1
#define FALSE   0

FAR Example(ParamBlk FAR *parm)
{
   char FAR *pFileName;
   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   pFileName = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   pFileName[parm->p[0].val.ev_length] = '\0';
   wh = _EdOpenFile(pFileName, FO_READWRITE);
   _HUnLock(parm->p[0].val.ev_handle);

   _EdUndoOn(wh, TRUE); // start undo group

   _EdSetPos(wh, _EdGetLinePos(wh, 13));
   _EdInsert(wh, "Hello, world\n", _StrLen("Hello, world\n"));
   _EdSelect(wh, _EdGetLinePos(wh, 14), _EdGetLinePos(wh, 16));
   _EdIndent(wh, 1);

   _EdUndoOn(wh, FALSE); // end undo group
   _EdUndoOn(wh, TRUE); // start another undo group

   _EdSelect(wh, _EdGetLinePos(wh, 9), _EdGetLinePos(wh, 12));
   _EdDelete(wh);
   _EdSetPos(wh, _EdGetLinePos(wh, 13));
   _EdInsert(wh, "Hello, world\n", _StrLen("Hello, world\n"));

   _Execute("WAIT WINDOW 'Press any key to undo changes.'");
   _EdUndoOn(wh, TRUE); // undoes to start of undo group
}

FoxInfo myFoxInfo[] = {
   {"EDUNDOON", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_EdRedo( ) API Library Routine
_EdUndo( ) API Library Routine
Accessing the Visual FoxPro API


_Error( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_Error( ) API Library Routine
See Also Example

Signals the error specified by the value in code to the Visual FoxPro run time.

void _Error(int code)
int code;                     /* Internal Visual FoxPro
 error number. */

Remarks

The code parameter is a Visual FoxPro internal error number and can be passed as a positive or negative value. _Error( ) gives control to the Visual FoxPro error handler so that the error can be handled like any other Visual FoxPro error. Control of program flow doesn't return to the routine that called _Error( ), even when the user chooses to ignore the error. Execution resumes at the next Visual FoxPro statement.

See the Visual FoxPro Error Numbers topic in Help for error numbers and their meanings.

Note:
Do not use _Error() from an event handler.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example calls _Error( ) when _DBSkip( ) returns an error number. The Visual FoxPro code shows how to cause _Error( ) to be called.

Visual FoxPro Code

Copy Code
SET LIBRARY TO ERROR
DO CreateTest

ON ERROR DO expectError
USE
= DBSKIP(1)  && _Error() called: no DBF in use
USE test
GO TOP
= DBSKIP(-1)
= DBSKIP(-1)    && _Error() called: at top of file
GO BOTT
= DBSKIP(1)
= DBSKIP(1)  && _Error() called: at bottom of file
ON ERROR

PROCEDURE expectError
   ? "ERROR: " + MESSAGE()
RETURN

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   GO TOP
RETURN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *pblk)
{
   int RetCode;

   if ((RetCode = _DBSkip(-1, pblk->p[0].val.ev_long)) < 0) {
      _PutStr("\nError encountered in example program.");
      _Error(-RetCode);  // _DBSkip() returns negative error code
   }
   _RetInt(RetCode, 10);
}

FoxInfo myFoxInfo[] = {
   {"DBSKIP", (FPFI) Example, 1, "I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_ErrorInfo( ) API Library Routine
_UserError( ) API Library Routine
_DBSkip( ) API Library Routine


_ErrorInfo( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_ErrorInfo( ) API Library Routine
See Also Example

Returns the external error number that corresponds to the Visual FoxPro internal error number specified by code.

int _ErrorInfo(int code, char FAR *message)
int code;                     /* Internal Visual FoxPro error number. */
char FAR *message;         /* Pointer to space for an error message. */

Remarks

The message parameter is a pointer to a character string that is the Visual FoxPro error message. If message isn't a null pointer, Visual FoxPro fills in the error message text associated with the external error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example shows the information returned by _ErrorInfo( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO ERRORINF
= ERRORINFO(0)
= ERRORINFO(1)

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

void FAR ErrorInfo(ParamBlk FAR *parm)
{
   int ext;
   char FAR *message;

   if ((message =_Alloca(128)) == 0)
   {
      _Error(182); // "Insufficient memory"
   }
   ext = _ErrorInfo((int) parm->p[0].val.ev_long, message);

   _PutChr('\n'); putLong(ext); _PutStr(" "); _PutStr(message);
}

FoxInfo myFoxInfo[] = {
   {"ERRORINFO", (FPFI) ErrorInfo, 1, "I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_Error( ) API Library Routine
_UserError( ) API Library Routine
Accessing the Visual FoxPro API


_Evaluate( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_Evaluate( ) API Library Routine
See Also Example

Compiles and executes a Visual FoxPro expression you specify with expr, placing the result in res.

int _Evaluate(Value FAR *res, char FAR *expr)
Value FAR *res;            /* Address for result. */
char FAR *expr;            /* Expression. */

Remarks

You can specify any expression that can be evaluated by the Visual FoxPro EVALUATE( ) function. After the expression is evaluated, control usually returns to the C statement immediately following the call to _Evaluate( ). Exceptions include evaluating a Visual FoxPro expression that carries out a Visual FoxPro CANCEL or QUIT command.

_Evaluate( ) returns the Visual FoxPro internal error number for any errors that occur during evaluation of the Visual FoxPro expression, or returns 0 if no errors occur. The contents of res are valid only when _Evaluate( ) returns a value of 0.

Note:
Do not call _Evaluate() from an event handler.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example has the same functionality as the Visual FoxPro EVALUATE( ) function.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EVALUATE
? XEVAL("2 + 3")
? XEVAL("'a' + 'b'")
? XEVAL("SIN(PI()/2))")

C Code

Copy Code
#include <pro_ext.h>

FAR EvaluateEx(ParamBlk FAR *parm)
{
   char FAR *expr;
   Value result;

//   Null terminate character string
   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length + 1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   expr = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   expr[parm->p[0].val.ev_length] = '\0';

   _Evaluate(&result, expr);
   _RetVal(&result);

   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"XEVAL", (FPFI) EvaluateEx, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_Execute( ) API Library Routine
CANCEL Command
QUIT Command
Accessing the Visual FoxPro API


_Execute( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_Execute( ) API Library Routine
See Also Example

Compiles and executes the null-terminated statement you specify in stmt.

int _Execute(char FAR *stmt)
char FAR *stmt;            /* Statement to execute. */

Remarks

The stmt parameter can be any command or function that can be executed from the Command window. When execution of the statement is complete, control normally returns to the C statement immediately following the call to _Execute( ). Exceptions include executing code that performs a Visual FoxPro CANCEL or QUIT command.

_Execute( ) returns the Visual FoxPro internal error number for any error that occurs during execution of the statement, or 0 if no error occurs.

Note:
Do not call _Execute() from an event handler.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _Execute( ) to execute the passed Visual FoxPro statement.

Visual FoxPro Code

Copy Code
SET LIBRARY TO EXECUTE
= EXEC("? 'Hello, world.'")
= EXEC("DISPLAY STATUS")

C Code

Copy Code
#include <pro_ext.h>

FAR ExecuteEx(ParamBlk FAR *parm)
{
   char FAR *cmd;

   // Null terminate character string
   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   cmd = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   cmd[parm->p[0].val.ev_length] = '\0';

   _Execute(cmd);

   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"EXEC", (FPFI) ExecuteEx, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_Evaluate( ) API Library Routine
CANCEL Command
QUIT Command
Accessing the Visual FoxPro API


_FCHSize( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FCHSize( ) API Library Routine
See Also Example

Sets the size on disk of the specified file to the specified length.

int _FCHSize(FCHAN chan, long length)
FCHAN chan;               /* File to change. */
long length;                  /* New length for the file in bytes. */

Remarks

The specified length may extend or truncate the file. _FCHSize( ) returns 0 if it's successful in changing the length of the file, or – 1 if it fails.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a file Temp.txt and sets its size to 8196 bytes using _FCHSize( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO FCHSIZE
DIR  temp.txt

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan = _FCreate("temp.txt", FC_NORMAL);
   _FCHSize(fchan, 8196);
   _FClose(fchan);
}

FoxInfo myFoxInfo[] = {
   {"FCHSIZE", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FGets( ) API Library Routine
_FPuts( ) API Library Routine
_FWrite( ) API Library Routine


_FClose( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FClose( ) API Library Routine
See Also Example

Terminates access to a file.

int _FClose(FCHAN chan)
FCHAN chan;               /* File channel of file to close. */

Remarks

Any buffers that have been modified while the buffer is open are automatically flushed to disk. If the file has the TEMPORARY attribute, FClose( ) deletes the file. _FClose( ) returns 0 if the file is closed successfully, or – 1 if the file isn't closed successfully.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a file Temp.txt, sets its size to 8196 bytes, and closes it using _FClose( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO FCLOSE
DIR temp.txt

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan = _FCreate("temp.txt", FC_NORMAL);
   _FCHSize(fchan, 8196);
   _FClose(fchan);
}

FoxInfo myFoxInfo[] = {
   {"FCHSIZE", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FOpen( ) API Library Routine
_FCopy( ) API Library Routine
Accessing the Visual FoxPro API


_FCopy( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FCopy( ) API Library Routine
See Also Example

Attempts to copy len bytes from the offset position spos in source file sc to the offset position dpos in destination file dc.

int _FCopy(FCHAN dc, long dpos, FCHAN sc, long spos, long len)
FCHAN dc;                  /* File channel of destination file. */
long dpos;                  /* Offset position to start copying to. */
FCHAN sc;                  /* File channel of source file. */
long spos;                  /* Offset position to start copying from. */
long len;                     /* Number of bytes to copy. */

Remarks

_FCopy( ) returns True (an integer other than 0) if it succeeds, or False (0) if it fails.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates two files. It writes the text "Hello, world" to the first of these files and then copies the contents of this file, beginning with the third byte, to the second file.

Visual FoxPro Code

Copy Code
SET LIBRARY TO FCOPY

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan1, fchan2;
   int len;

   fchan1 = _FCreate("temp1.txt", FC_NORMAL);
   _FPuts(fchan1, "Hello, world.");
   _FFlush(fchan1);

   len = _FSeek(fchan1, 0, FS_FROMEOF); // determine length of file

   fchan2 = _FCreate("temp2.txt", FC_NORMAL);
   _FCopy(fchan2, 0, fchan1, 2, len - 2);

   _FClose(fchan1);
   _FClose(fchan2);
}

FoxInfo myFoxInfo[] = {
   {"FCOPY", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FPuts( ) API Library Routine
_FWrite( ) API Library Routine
_FCreate( ) API Library Routine
Accessing the Visual FoxPro API


_FCreate( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FCreate( ) API Library Routine
See Also Example

Assigns a Visual FoxPro channel to a new file.

FCHAN _FCreate(char FAR *filename, int mode)
char FAR *filename;         /* Name of file to create. */
int mode;                     /* File attributes. */

Remarks

If a file with the specified name already exists, _FCreate( ) truncates the existing file to zero bytes.

The mode parameter may be one or more of the following flags: FC_READONLY, FC_SYSTEM, FC_HIDDEN, and FC_TEMPORARY. You can combine these flags using the C or + operator. An additional flag, FC_NORMAL, specifies that the file has none of the other attributes. FC_TEMPORARY files are automatically deleted when you call _FClose( ) to close the file.

_FCreate( ) returns the file channel if it succeeds in creating the file, or – 1 if it fails.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _FCreate( ) to create a number of files using the various mode flags of _FCreate( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO FCREATE

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan;

   fchan = _FCreate("normal.tmp", FC_NORMAL);
   _FClose(fchan);

   fchan = _FCreate("readonly.tmp", FC_READONLY);
   _FClose(fchan);

   fchan = _FCreate("hidden.tmp", FC_HIDDEN);
   _FClose(fchan);

   fchan = _FCreate("system.tmp", FC_SYSTEM);
   _FClose(fchan);

   fchan = _FCreate("temp.tmp", FC_TEMPORARY);
   _FClose(fchan);

   fchan = _FCreate("multi.tmp", FC_SYSTEM | FC_READONLY);
   _FClose(fchan);
}

FoxInfo myFoxInfo[] = {
   {"FCREATE", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FClose( ) API Library Routine
_FOpen( ) API Library Routine
Accessing the Visual FoxPro API


_FEOF( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FEOF( ) API Library Routine
See Also Example

int _FEOF(FCHAN chan)
FCHAN chan;               /* File channel of file. */

Remarks

_FEOF( ) returns True (an integer other than 0) if the file pointer in the specified file is currently at the end of the file; or False (0) if not.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a file and sets its length to 8192 bytes. Then it moves the file pointer to the beginning of the file and calls _FEOF( ), which returns 0 (False). Next, it moves the file pointer to the end of the file and again calls _FEOF( ), which this time returns 1 (True).

Visual FoxPro Code

Copy Code
SET LIBRARY TO FEOF

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

    PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan =  FCreate("temp.txt", FC NORMAL);
    FCHSize(fchan, 8196);
    FFlush(fchan);

    FSeek(fchan, 0, FS FROMBOF);
    PutStr("\n FSeek(fchan, 0, FS FROMBOF)");
    PutStr("\n FEOF(fchan) ="); putLong(_FEOF(fchan));

   _FSeek(fchan, 0, FS_FROMEOF);
   _PutStr("\n_FSeek(fchan, 0, FS_FROMEOF)");
   _PutStr("\n_FEOF(fchan) ="); putLong(_FEOF(fchan));
}

FoxInfo myFoxInfo[] = {
   {"FEOF", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FSeek( ) API Library Routine
_FCopy( ) API Library Routine
_FWrite( ) API Library Routine
Accessing the Visual FoxPro API


_FError( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FError( ) API Library Routine
See Also Example

Returns the number of the last file operation error recorded for any file channel.

int _FError(void any)
void any;                     /* Pointer. */

Example

The following example uses _FOpen( ) to attempt to open a file called Nofile.abc, which presumably doesn't exist. It then calls _FError( ), which returns error number 2, for "file not found."

Visual FoxPro Code

Copy Code
SET LIBRARY TO FERROR

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan = _FOpen("nofile.abc", FC_READONLY);
   _PutStr("\nAttempted to _FOpen() a file which does not exist.");
   _PutStr("\n_FError() ="); putLong(_FError());
}

FoxInfo myFoxInfo[] = {
   {"FERROR", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FClose( ) API Library Routine
_FCreate( ) API Library Routine
_FOpen( ) API Library Routine


_FFlush( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FFlush( ) API Library Routine
See Also Example

Flushes to disk all modified buffers in memory for the specified file.

int _FFlush(FCHAN chan)
FCHAN chan;               /* File channel of file to flush. */

Remarks

_FFlush( ) returns 0 if it is successful in flushing the buffers, or – 1 if it fails.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a file and sets its length to 8196 bytes. Executing the Visual FoxPro command line DIR TEMP.TXT in the Command window shows that the size of the file on disk is still 0. However, after executing = XFFLUSH( ), issuing the command line DIR TEMP.TXT shows that the file on disk reflects the _FCHSize( ) call, and has a file size of 8196 bytes.

Visual FoxPro Code

Copy Code
SET LIBRARY TO FFLUSH
DIR temp.txt  && size on disk is still 0
WAIT WINDOW "File Size = 0"
= XFFLUSH()
DIR temp.txt  && size on disk is 8196
WAIT WINDOW "File Size Does Not Equal 0"
CLOSE ALL

C Code

Copy Code
#include <pro_ext.h>

static FCHAN fchan;

FAR CreateIt(ParamBlk FAR *parm)
{
   fchan = _FCreate("temp.txt", FC_NORMAL);
   _FCHSize(fchan, 8196);
}

FAR FFlushEx(ParamBlk FAR *parm)
{
   _FFlush(fchan);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) CreateIt, CALLONLOAD, ""},
   {"XFFLUSH", (FPFI) FFlushEx, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FPuts( ) API Library Routine
_FWrite( ) API Library Routine
_FError( ) API Library Routine
Accessing the Visual FoxPro API


_FGets( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FGets( ) API Library Routine
See Also Example

Copies to the buffer a single line from the specified file, starting at the current position in the file.

unsigned int _FGets(FCHAN chan, char FAR *buffer, int maxlen)
FCHAN chan;               /* File channel of file from which to copy. */
char FAR *buffer;            /* Buffer address. */
int maxlen;                  /* Maximum length of line in bytes. */

Remarks

_FGets( ) copies a line of maxlen length, delimited with a carriage return. The carriage return is translated to a null terminator and stored in the buffer. Line feeds are ignored and aren't copied into the buffer. _FGets( ) returns the number of bytes copied to the buffer.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens a file specified by a parameter, and copies and shows each line in the file.

Visual FoxPro Code

Copy Code
SET LIBRARY TO FGETS
fc = FCREATE("x", 0)
= FPUTS(fc, REPL("X", 512), 512)
= FCLOSE(fc)
= XFGETS("x")
DELETE FILE x

C Code

Copy Code
#include <pro_ext.h>

#define BUFFSIZE 256
static char lineBuffer[BUFFSIZE];

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan;

//   Null terminate file name
   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);

   ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))
      [parm->p[0].val.ev_length] = '\0';

   if ((fchan=_FOpen((char FAR*)_HandToPtr(parm->p[0].val.ev_handle),
      FC_NORMAL)) < 0)
   {
      _UserError("Could not open file.");
   }
   _HUnLock(parm->p[0].val.ev_handle);

   while (!_FEOF(fchan))
   {
      _FGets(fchan, lineBuffer, BUFFSIZE);
      _PutStr(lineBuffer); _PutChr('\n');
   }
   _FClose(fchan);
}

FoxInfo myFoxInfo[] = {
   {"XFGETS", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FRead( ) API Library Routine
_FSeek( ) API Library Routine
Accessing the Visual FoxPro API


_FindMemo( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FindMemo( ) API Library Routine
See Also Example

Returns the memory address of the first character in the memo field fld for the current record in the selected work area.

long _FindMemo(Locator FAR *fld)
Locator FAR *fld;            /* Memo field name. */

Remarks

_FindMemo( ) enables you to directly gain access to memo field contents for the current record. When the memo field for the current record is empty, or when fld is not the name of a memo field, _FindMemo( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example retrieves the contents of a memo field for the current record. It uses FindMemo( ) to find the location of the memo contents for the current record within the memo file. The example then moves the file pointer to this location with _FSeek( ), and stores the memo field contents in memory using _FRead( _MemoSize( )).

Visual FoxPro Code

Copy Code
SET LIBRARY TO FINDMEMO
CREATE TABLE WMemo (MemoField M)
APPEND BLANK
REPLACE MemoField WITH "Hello, World."
? GETMEMO(@MemoField)

C Code

Copy Code
#include <pro_ext.h>

FAR FindMemoEx(ParamBlk FAR *parm)
{

   Locator FAR *memoFldLoc;
   FCHAN fchMemo;
   char FAR *memoContents;
   int memoLen;
   long loc;

   if ((fchMemo = _MemoChan(-1)) == -1)
   {
      _UserError("_MemoChan() failed");
   }
   memoFldLoc = &parm->p[0].loc;

   if ((loc = _FindMemo(memoFldLoc)) < 0)
   {
      _UserError("_FindMemo() failed");
   }
   if ((memoLen = _MemoSize(memoFldLoc)) < 0)
   {
      _UserError("_MemoSize() failed");
   }
   if ((memoContents = _Alloca(memoLen + 1)) == 0)
   {
      _Error(182); // "Insufficient memory"
   }
   _FSeek(fchMemo, loc, FS_FROMBOF);
   _FRead(fchMemo, memoContents, memoLen);
   memoContents[memoLen] = '\0';
   _RetChar(memoContents);
}

FoxInfo myFoxInfo[] = {
   {"GETMEMO", (FPFI) FindMemoEx, 1, "R"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_AllocMemo( ) API Library Routine
_DBReplace( ) API Library Routine
_MemoChan( ) API Library Routine
_MemoSize( ) API Library Routine


_FindVar( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FindVar( ) API Library Routine
See Also Example

Provides a way to initialize a Locator so you can use _Store( ) to place data in an existing memory variable or field.

int _FindVar(NTI nti, int where, Locator FAR *loc)
NTI nti;                     /* NTI number of variable or field. */
int where;                  /* Work area number. */
Locator FAR *loc;            /* Locator. */

Remarks

_FindVar( ) fills in the passed Locator with information about a variable or field named nti that exists in a work area specified by where.

  • If where is – 1, nti is assumed to be a memory variable.

  • If where is 1 – 225, nti is assumed to be a field in the work area of the specified number.

  • If where is 0, _FindVar first checks to see if nti is a memory variable. If it's not a memory variable, the current work area is checked for a field with the specified NTI.

_FindVar( ) returns True (an integer other than 0) if a variable or field nti is found in where; otherwise, _FindVar( ) returns False (0).

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays the value of a Visual FoxPro variable in a very roundabout way.

Visual FoxPro Code

Copy Code
SET LIBRARY TO FINDVAR
TestVar= "This is a test"
= QMARK("TestVar")

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR NameTableIndexEx(ParamBlk FAR *parm)
{
   NTI nti;
   char FAR *name;
   Locator loc;
   Value val;

//   Null terminate character string, name of variable
   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   name = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   name[parm->p[0].val.ev_length] = '\0';

   nti = _NameTableIndex(name);

   _FindVar(nti, 0, &loc);
   _Load(&loc, &val);
   _PutValue(&val);
}

FoxInfo myFoxInfo[] = {
   {"QMARK", (FPFI) NameTableIndexEx, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_ALen( ) API Library Routine
_Load( ) API Library Routine
_NameTableIndex( ) API Library Routine
_NewVar( ) API Library Routine
_ObjectRelease( ) API Library Routine
_Store( ) API Library Routine


_FindWindow( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FindWindow( ) API Library Routine
See Also Example

Places the handle of the window that the point pt belongs to on the screen into wh.

int _FindWindow(WHANDLE FAR *wh, Point pt)
WHANDLE FAR *wh;      /* Pointer to window handle. */
Point pt;                     /* Point. */

Remarks

_FindWindow( ) returns an integer indicating the portion of the window where the point is located. For example, _FindWindow( ) returns the value inContent if the point is inside the window.

Possible return values, as defined in PRO_EXT.H, are listed in the following table.

_FindWindow( ) Return Values

Value | Point Location
inBorder | In the window border
inHelp | In the help region
inContent | In the content/text area
inDrag | On the title bar
inGrow | On the size control
inGoAway | On the close box
inZoom | On the zoom control
inVUpArrow | On the up arrow in the vertical scroll bar
inVDownArrow | On the down arrow in the vertical scroll bar
inVPageUp | In the page up region of the vertical scroll bar
inVPageDown | In the page down region of the vertical scroll bar
inVThumb | On the thumb in the vertical scroll bar
inHUpArrow | On the right arrow in the horizontal scroll bar
inHDownArrow | On the left arrow in the horizontal scroll bar
inHPageUp | In the page right region of the horizontal scroll bar
inHPageDown | In the page left region of the horizontal scroll bar
inHThumb | On the thumb in the horizontal scroll bar
inMenuBar | On the menu bar

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example waits for a left mouse button click and then uses _FindWindow( ) to get the window handle for the mouse down position.

Visual FoxPro Code

Copy Code
WAIT WINDOW  "Click mouse on a window" NOWAIT
SET LIBRARY TO FINDWIND

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}
FAR FindWindowFn(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point mousePos;
   int where;

//  Get mouse position when left button goes down
   while (_InKey(0, MOUSEACTIVE | HIDECURSOR) != 151);
   while (!_MousePos(&mousePos));

   switch (where = _FindWindow(&wh, mousePos))
   {
      case inBorder:
         _PutStr("\nMouse down inBorder"); break;
      case inHelp:
         _PutStr("\nMouse down inHelp"); break;
      case inContent:
         _PutStr("\nMouse down inContent"); break;
      case inDrag:
         _PutStr("\nMouse down inDrag"); break;
      case inGrow:
         _PutStr("\nMouse down inGrow"); break;
      case inGoAway:
         _PutStr("\nMouse down inGoAway"); break;
      case inZoom:
         _PutStr("\nMouse down inZoom"); break;
      case inVUpArrow:
         _PutStr("\nMouse down inVUpArrow"); break;
      case inVDownArrow:
         _PutStr("\nMouse down inVDownArrow"); break;
      case inVPageUp:
         _PutStr("\nMouse down inVPageUp"); break;
      case inVPageDown:
         _PutStr("\nMouse down inVPageDown"); break;
      case inVThumb:
         _PutStr("\nMouse down inVThumb"); break;
      case inHUpArrow:
         _PutStr("\nMouse down inHUpArrow"); break;
      case inHDownArrow:
         _PutStr("\nMouse down inHDownArrow"); break;
      case inHPageUp:
         _PutStr("\nMouse down inHPageUp"); break;
      case inHPageDown:
         _PutStr("\nMouse down inHPageDown"); break;
      case inHThumb:
         _PutStr("\nMouse down inHThumb"); break;
      case inMenuBar:
         _PutStr("\nMouse down inMenuBar"); break;
      default:
         _PutStr("\nMouse down someplace else"); break;
   }
   _GlobalToLocal(&mousePos, wh);
   _PutStr("\nPosition relative to window:");
   putLong(mousePos.v, 5);
   _PutChr(' ');
   putLong(mousePos.h, 5);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) FindWindowFn, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_MousePos( ) API Library Routine
Accessing the Visual FoxPro API
_FindWindowP( ) API Library Routine


_FindWindowP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FindWindowP( ) API Library Routine
See Also Example

Places the handle of the window that the point pt belongs to on the screen into wh.

int _FindWindowP(WHANDLE FAR *wh, Point pt)
WHANDLE FAR *wh;      /* Pointer to window handle. */
Point pt;                     /* Point in pixels. */

Remarks

_FindWindowP( ) returns an integer indicating the portion of the window where the point is located. For possible return values, see _FindWindow( ) API Library Routine.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example waits for a left mouse button click and then uses _FindWindowP( ) to get the window handle for the mouse down position.

Visual FoxPro Code

Copy Code
WAIT WINDOW "Click Mouse In Window" NOWAIT
SET LIBRARY TO FINDWINP

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR FindWindowEx(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point mousePos;
   int where;

//  Get mouse position when left button goes down
   while (_InKey(0, MOUSEACTIVE | HIDECURSOR) != 151);
   while (!_MousePosP(&mousePos));

   switch (where = _FindWindowP(&wh, mousePos))
   {
      case inBorder:
         _PutStr("\nMouse down inBorder"); break;
      case inHelp:
         _PutStr("\nMouse down inHelp"); break;
      case inContent:
         _PutStr("\nMouse down inContent"); break;
      case inDrag:
         _PutStr("\nMouse down inDrag"); break;
      case inGrow:
         _PutStr("\nMouse down inGrow"); break;
      case inGoAway:
         _PutStr("\nMouse down inGoAway"); break;
      case inZoom:
         _PutStr("\nMouse down inZoom"); break;
      case inVUpArrow:
         _PutStr("\nMouse down inVUpArrow"); break;
      case inVDownArrow:
         _PutStr("\nMouse down inVDownArrow"); break;
      case inVPageUp:
         _PutStr("\nMouse down inVPageUp"); break;
      case inVPageDown:
         _PutStr("\nMouse down inVPageDown"); break;
      case inVThumb:
         _PutStr("\nMouse down inVThumb"); break;
      case inHUpArrow:
         _PutStr("\nMouse down inHUpArrow"); break;
      case inHDownArrow:
         _PutStr("\nMouse down inHDownArrow"); break;
      case inHPageUp:
         _PutStr("\nMouse down inHPageUp"); break;
      case inHPageDown:
         _PutStr("\nMouse down inHPageDown"); break;
      case inHThumb:
         _PutStr("\nMouse down inHThumb"); break;
      case inMenuBar:
         _PutStr("\nMouse down inMenuBar"); break;
      default:
         _PutStr("\nMouse down someplace else"); break;
   }
   _GlobalToLocalP(&mousePos, wh);
   _PutStr("\nPosition relative to window:");
   putLong(mousePos.v, 5);
   _PutChr(' ');
   putLong(mousePos.h, 5);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", FindWindowEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FindWindow( ) API Library Routine
_MousePos( ) API Library Routine
Accessing the Visual FoxPro API


_FOpen( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FOpen( ) API Library Routine
See Also Example

Assigns a Visual FoxPro channel to an existing file.

FCHAN _FOpen(char FAR *filename, int mode)
char FAR *filename;         /* Name of existing file */
int mode;                     /* Mode option. */

Remarks

The following mode options are available: FO_READONLY, FO_WRITEONLY, and FO_READWRITE. _FOpen( ) opens a file with exclusive access. _FOpen( ) returns the file channel if it's successful in opening the file, or returns – 1 if it can't open the file.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a test file. It then opens the file in FO_READONLY mode and attempts to write to it. As a result _FError( ) returns 5 for "Access denied." Next, the example opens the test file in FO_WRITEONLY mode, and attempts to read from it. Again, _FError( ) returns 5.

Visual FoxPro Code

Copy Code
SET LIBRARY TO FOPEN

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

#define BUFFSIZE 256
static char lineBuffer[BUFFSIZE];

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan;

   fchan = _FCreate("temp.tmp", FC_NORMAL);
   _FCHSize(fchan, 8192);
   _FClose(fchan);

   fchan = _FOpen("temp.tmp", FO_READONLY);
   _FPuts(fchan, "Hello, world");
   _PutStr("\nAttempt to _FPuts() to file _FOpen()d FO_READONLY");
   _PutStr("\n_FError() ="); putLong(_FError());
   _FClose(fchan);

   fchan = _FOpen("temp.tmp", FO_WRITEONLY);
   _FGets(fchan, lineBuffer, BUFFSIZE);
   _PutStr("\nAttempt to _FGets() from file _FOpen()d FO_WRITEONLY");
   _PutStr("\n_FError() ="); putLong(_FError());
   _FClose(fchan);
}

FoxInfo myFoxInfo[] = {
   {"FOPEN", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FClose( ) API Library Routine
_FCreate( ) API Library Routine
_FError( ) API Library Routine
Accessing the Visual FoxPro API


_FPuts( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FPuts( ) API Library Routine
See Also Example

Writes a specified null-terminated string to a file, followed by a carriage return/line feed pair.

unsigned int _FPuts(FCHAN chan, char FAR *buffer)
FCHAN chan;               /* File channel of file to write to. */
char FAR *buffer;            /* String to write. */

Remarks

_FPuts( ) returns the total number of bytes it writes to the file.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a file, and writes the text "Hello, world." to the file using _FPuts( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO FPUTS

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan;

   fchan = _FCreate("temp.tmp", FC_NORMAL);
   _FPuts(fchan, "Hello, world.");
   _FClose(fchan);
}

FoxInfo myFoxInfo[] = {
   {"FPUTS", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FFlush( ) API Library Routine
_FSeek( ) API Library Routine
_FWrite( ) API Library Routine
Accessing the Visual FoxPro API


_FRead( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FRead( ) API Library Routine
See Also Example

Copies to the buffer exactly length bytes from a file into buffer.

unsigned int _FRead(FCHAN chan, char FAR *buffer, int length)
FCHAN chan;               /* File channel of file from which to copy. */
char FAR *buffer;            /* Buffer address. */
int length;                  /* Number of bytes to be copied. */

Remarks

_FRead( ) doesn't add a terminator to the end of the bytes in the buffer. No translation is performed on the bytes when they are stored in the buffer. _FRead( ) returns the number of bytes read.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a test file and places text in it. The example then attempts to read 32 bytes from the file using _FRead( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO FREAD

C Code

Copy Code
#include <pro_ext.h>

#define BUFFSIZE 32
static char buffer[BUFFSIZE];

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan;
   int bytesRead;

   fchan = _FCreate("temp.tmp", FC_NORMAL);
   _FPuts(fchan, "Hello, world.");
   _FPuts(fchan, "Hello, world.");
   _FPuts(fchan, "Hello, world.");
   _FPuts(fchan, "Hello, world.");
   _FPuts(fchan, "Hello, world.");

   _FSeek(fchan, 0, FS_FROMBOF);

   bytesRead = _FRead(fchan, buffer, BUFFSIZE - 1);
   buffer[bytesRead] = '\0';
   _PutStr(buffer);

   _FClose(fchan);
}

FoxInfo myFoxInfo[] = {
   {"FREAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FGets( ) API Library Routine
_FSeek( ) API Library Routine
Accessing the Visual FoxPro API


_FreeHand( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FreeHand( ) API Library Routine
See Also Example

Releases a memory handle hand previously allocated by means such as _AllocHand( ).

void _FreeHand(MHANDLE hand)
MHANDLE hand;            /* Memory handle. */

Example

The following example allocates 1024 blocks of 16384-byte memory blocks, for a total of 16 MB, freeing each memory block using _FreeHand( ) before allocating the next.

Visual FoxPro Code

Copy Code
SET LIBRARY TO FREEHAND

C Code

Copy Code
#include <pro_ext.h>

void FAR Example(ParamBlk FAR *parm)
{
   MHANDLE mh;
   int i;

   for (i = 0; i < 1024; i++)
   {
      if ((mh = _AllocHand(16384)) == 0)
      {
         _Error(182);  // "Insufficient memory"
      }
      _FreeHand(mh);
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_AllocHand( ) API Library Routine
_GetHandSize( ) API Library Routine
_HandToPtr( ) API Library Routine
_HLock( ) API Library Routine
_HUnLock( ) API Library Routine
_MemAvail( ) API Library Routine
_SetHandSize( ) API Library Routine


_FreeObject( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FreeObject( ) API Library Routine
See Also

Releases an object from the Visual FoxPro API data pool.

void _FreeObject(Value FAR *objct)

Remarks

Use _FreeObject( ) to free an object from the Visual FoxPro API object table.

_FreeObject( )is used in the following cases:

1. If an object reference is returned from any Visual FoxPro API function (for example, _Evaluate( ) or _GetObjectProperty( )), you must use _FreeObject( ) to release the object when you are no longer using it.

2. If you keep a reference to an object across different Visual FoxPro API calls, you must first use _ObjectReference( ) to increment the count for the object. When you are no longer using the object, you must then use _ObjectRelease( ) to decrement the count for the object and then use _FreeObject( ) to release the object.

In addition to the previous rules, you should always clear the Value structure you pass to any Visual FoxPro API function that returns a value into the passed Value structure. For example, you can create and call a function that clears the structure prior to calling any function that returns a value into your structure. You can also create and call a function to cleanup any object references or unused handles.

0 is returned unless an error occurs. When an error occurs, a negative number representing an internal error code is returned.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

See Also

Other Resources

API Library Construction
_ObjectReference( ) API Library Routine
_ObjectRelease( ) API Library Routine
_GetObjectProperty( ) API Library Routine
_Evaluate( ) API Library Routine


_FSeek( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FSeek( ) API Library Routine
See Also Example

Moves the file pointer to a new location as specified by position and mode.

long _FSeek(FCHAN chan, long position, int mode)
FCHAN chan;               /* File channel. */
long position;               /* Position in file. */
int mode;                     /* How to determine new location */

Remarks

If mode is 0 (absolute), the file pointer is set to the value of position. If mode is 1, (relative to file pointer), the value of position is added to the current file pointer position. If mode is 2 (relative to the end of the file), _FSeek( ) moves the file pointer past the end of the file. _FSeek( ) returns the new position of the file pointer. For example, _FSeek(chan, 0L, 2) moves the file pointer to the end of the file and returns the file length in bytes.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example consists of one API routine, which takes two parameters, a file name, and an integer. It opens the file. Using _FSeek( ) with the FS_FROMBOF flag, it then moves the file pointer to the offset position specified by the integer parameter, and reads a single byte from the file at that position.

Visual FoxPro Code

Copy Code
SET LIBRARY TO FSEEK
fc = FCREATE("x", 0)
= FPUTS(fc, "abcdefghijklmnopqrstuvwxyz", 26)
= FCLOSE(fc)

? XFSEEK("x", 2)  && displays 3rd byte of file x as an integer
? XFSEEK("x", 4)  && displays 5th byte of file x as an integer

DELETE FILE x

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan;
   char x;

   // Null terminate file name
   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);

   ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))
      [parm->p[0].val.ev_length] = '\0';

   if ((fchan=_FOpen((char FAR*)_HandToPtr(parm->p[0].val.ev_handle),
      FC_NORMAL)) < 0)
   {
      _UserError("Could not open file.");
   }
   _HUnLock(parm->p[0].val.ev_handle);

   _FSeek(fchan, parm->p[1].val.ev_long, FS_FROMBOF);
   _FRead(fchan, &x, 1);
   _RetInt(x, 10);
   _FClose(fchan);
}

FoxInfo myFoxInfo[] = {
   {"XFSEEK", (FPFI) Example, 2, "C,I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FCopy( ) API Library Routine
_FFlush( ) API Library Routine
_FGets( ) API Library Routine
_FPuts( ) API Library Routine


_FWrite( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_FWrite( ) API Library Routine
See Also Example

Writes exactly length bytes from your buffer to a file specified by chan.

unsigned int _FWrite(FCHAN chan, char FAR *buffer, int length)
FCHAN chan;               /* File channel of file to write to. */
char FAR *buffer;            /* Buffer address. */
int length;                  /* Number of bytes to write. */

Remarks

_FWrite( ) doesn't add a terminator to the file. No translation is performed on the bytes before they are written. _FWrite( ) returns the number of bytes written.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a test file and writes some data to it using _FWrite( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO FWRITE

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   FCHAN fchan;

   fchan = _FCreate("temp.tmp", FC_NORMAL);
   _FWrite(fchan, "Hello, world.", _StrLen("Hello, world."));
   _FWrite(fchan, "\xd\xa", 2);
   _FWrite(fchan, "1234567890", 10);
   _FClose(fchan);
}

FoxInfo myFoxInfo[] = {
   {"FWRITE", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FFlush( ) API Library Routine
_FPuts( ) API Library Routine
_FSeek( ) API Library Routine
Accessing the Visual FoxPro API


_GetAPIHandle( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetAPIHandle( ) API Library Routine
See Also Example

Returns the handle of the current FLL.

void _GetAPIHandle( )

Example

The following example returns the handle of the current FLL.

Visual FoxPro Code

Copy Code
SET LIBR TO GETAPIHA.FLL
? GETAPIHAND( )

C Code

Copy Code
#include <pro_ext.h>

void getAPIHandle()
{
_RetInt((int) _GetAPIHandle(),15);

}

FoxInfo myFoxInfo[] =
{
   {"GETAPIHAND",  (FPFI) getAPIHandle, 0, ""},
};

FoxTable _FoxTable =
{
   (FoxTable  *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
Creating Visual FoxPro Dynamic-Link Libraries
_ActivateHandler( ) API Library Routine
_DeActivateHandler( ) API Library Routine


_GetHandSize( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetHandSize( ) API Library Routine
See Also Example

Returns the usable number of bytes associated with a specified memory block handle hand.

unsigned long _GetHandSize(MHANDLE hand)
MHANDLE hand;            /* Handle of memory block. */

Remarks

The usable number of bytes is always greater than or equal to the number of bytes most recently requested for this MHANDLE by _AllocHand( ) or by a successful _SetHandSize( ) call.

Note:
_GetHandSize() doesn't cause memory reorganization.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example allocates memory blocks of various size from 1 to 215 and shows the value returned by _GetHandSize( ) for these allocations. Notice that the value returned by _GetHandSize( ) is only sometimes exactly equal to the size requested by _AllocHand( ); usually it's a bit more.

Visual FoxPro Code

Copy Code
SET LIBRARY TO GETHANDS

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 5;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   MHANDLE mh;
   unsigned int allocSize;

   for (allocSize = 1;; allocSize *= 2)
   {
      if ((mh = _AllocHand(allocSize)) == 0)
      {
         _Error(182);  // "Insufficient memory"
      }
      _PutStr("\n_AllocHand("); putLong(allocSize); _PutStr(")");
      _PutStr("\n_GetHandSize() ="); putLong(_GetHandSize(mh));
      _FreeHand(mh);
      if (allocSize == 32768)
      {
         break;
      }
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_AllocHand( ) API Library Routine
_FreeHand( ) API Library Routine
_HandToPtr( ) API Library Routine
_HLock( ) API Library Routine
_HUnLock( ) API Library Routine
_MemAvail( ) API Library Routine
_SetHandSize( ) API Library Routine


_GetItemCmdKey( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetItemCmdKey( ) API Library Routine
See Also Example

Copies the displayed keyboard shortcut string for the specified menu item to the buffer pointed to by the text parameter.

int _GetItemCmdKey(MENUID menuid, ITEMID itemid, char FAR *text)
MENUID menuid;            /* Menu identifier. */
ITEMID itemid;            /* Menu item identifier. */
char FAR *text;            /* Where to store the shortcut string. */

Remarks

_GetItemCmdKey( ) returns the internal keyboard code for the keyboard shortcut. If there is no keyboard shortcut for the specified menu item, _GetItemCmdKey( ) returns 0.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a menu with three items, setting up a keyboard shortcut for each item. It uses _GetItemCmdKey( ) to display the shortcut keys.

Visual FoxPro Code

Copy Code
SET LIBRARY TO GETICMDK

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;
   _PutValue(&val);
}

FAR GetItemCmdKeyEx(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;
   char FAR *shortcutString;
   int intKeyCode;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");
   _SetItemCmdKey(menuId, itemId, altKey | 0x78, "Alt+1");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");
   _SetItemCmdKey(menuId, itemId, altKey | 0x79, "Alt+2");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");
   _SetItemCmdKey(menuId, itemId, altKey | 0x7a, "Alt+3");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);

   if ((shortcutString = _Alloca(64)) == 0)
   {
      _DisposeMenu(menuId);
      _Error(182); // "Insufficient memory"
   }
   intKeyCode = _GetItemCmdKey(menuId, _GetItemId(menuId, 0),
      shortcutString);
   _PutStr("\nShortcut string = "); _PutStr(shortcutString);
   _PutStr("\nInternal key code ="); putLong(intKeyCode);

   intKeyCode = _GetItemCmdKey(menuId, _GetItemId(menuId, 1),
      shortcutString);
   _PutStr("\nShortcut string = "); _PutStr(shortcutString);
   _PutStr("\nInternal key code ="); putLong(intKeyCode);

   intKeyCode = _GetItemCmdKey(menuId, _GetItemId(menuId, 2),
      shortcutString);
   _PutStr("\nShortcut string = "); _PutStr(shortcutString);
   _PutStr("\nInternal key code ="); putLong(intKeyCode);
   _Execute("WAIT");
   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) GetItemCmdKeyEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_GetItemSubMenu( ) API Library Routine
_NewItem( ) API Library Routine
_SetItemCmdKey( ) API Library Routine
Accessing the Visual FoxPro API


_GetItemId( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetItemId( ) API Library Routine
See Also Example

Returns the item identifier of the specified item in the specified menu.

ITEMID _GetItemId(MENUID menuid, long index)
MENUID menuid;            /* Menu identifier. */
long index;                  /* Menu item number. */

Remarks

You can use _GetItemId( ) to gather menu bar or menu identifiers, so you can perform an operation on all the items. _GetItemId( ) returns 0 when index exceeds the number of items on the menu.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a menu with three items. It uses _GetItemId( ) to get the ITEMID of each menu item. After removing one item from the menu, you can see that the ITEMID isn't always equal to the item index.

Visual FoxPro Code

Copy Code
SET LIBRARY TO GETIID

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR GetItemIdEx(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);

   _PutStr("\nitemid for index 0 ="); putLong(_GetItemId(menuId, 0));
   _PutStr("\nitemid for index 1 ="); putLong(_GetItemId(menuId, 1));
   _PutStr("\nitemid for index 2 ="); putLong(_GetItemId(menuId, 2));

   _Execute("WAIT WINDOW");
   _DisposeItem(menuId, _GetItemId(menuId, 1));

   _PutStr("\nitemid for index 0 ="); putLong(_GetItemId(menuId, 0));
   _PutStr("\nitemid for index 1 ="); putLong(_GetItemId(menuId, 1));

   _Execute("WAIT WINDOW");
   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) GetItemIdEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_GetItemSubMenu( ) API Library Routine
_GetNewItemId( ) API Library Routine
Accessing the Visual FoxPro API
NewItemID Property


_GetItemSubMenu( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetItemSubMenu( ) API Library Routine
See Also Example

Returns the menu item identifier of a submenu assigned to a menu item.

MENUID _GetItemSubMenu(MENUID menuid, ITEMID itemid);
MENUID menuid;            /* Menu identifier */
ITEMID itemid;            /* Menu item identifier*/

Remarks

A submenu is treated as an independent menu. _GetItemSubMenu( ) returns the MENUID of the submenu assigned to a specified menu item, or a – 1 if there is no submenu assigned to the menu item.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a menu system and returns the sub menu ID.

Visual FoxPro Code

Copy Code
SET LIBRARY TO GETITEMS

C Code

Copy Code
#include <pro_ext.h>

MENUID SysMenuId, retMenuId;
MENUID PopupId;
ITEMID PadId;

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR onSelection(long menuId, long itemId)
{
   _PutStr("\nitemId = "); putLong(itemId);
}

void FAR StartUp()
{
      ITEMID Bar1Id;
      ITEMID Bar2Id;

    int Error;
//
//   Add new menu title to SYSMENU.
//
  SysMenuId = _MenuId(_SYSMENU);
  PadId = _GetNewItemId(SysMenuId);

   if (_NewItem(SysMenuId, PadId, _LASTITEM, "\\<Added menu title"))
  {
    _Error(623); /* "Menu item cannot be defined." */
  }
//
//   Define menu.
//
  PopupId = _GetNewMenuId();

  if (Error = _NewMenu(MPOPUP, PopupId))
  {
    _Error(-Error);
  }
   Bar1Id = _GetNewItemId(PopupId);
//
//      WARNING: Call _NewItem() before another _GetNewItemId().
//
   if (_NewItem(PopupId, Bar1Id, _LASTITEM, "\\<1st item"))
  {
    _Error(623); /* "Menu item cannot be defined." */
  }
   Bar2Id = _GetNewItemId(PopupId);

   if (_NewItem(PopupId, Bar2Id, _LASTITEM, "\\<2nd item"))
  {
    _Error(623); /* "Menu item cannot be defined." */
  }
//
//   Attach menu to menu title.
//
  _SetItemSubMenu(SysMenuId, PadId, PopupId);

  _PutStr("\nSubMenu Id = "); putLong(PopupId);

//
//  Set up selection action.
//
   retMenuId = _GetItemSubMenu(SysMenuId,PadId);
   _PutStr("\nThis is the return value from  _GetItemSubMenu.  retMenuId = "); putLong(retMenuId);

   _OnSelection(PopupId, -1, onSelection);
}

void FAR ShutDown()
{
  _DisposeItem(SysMenuId, PadId);
  _DisposeMenu(PopupId);
}

FoxInfo myFoxInfo[] =
{
   {"STARTUP",   (FPFI) StartUp,  CALLONLOAD, ""},
   {"SHUTDOWN",  (FPFI) ShutDown, CALLONUNLOAD, ""},
};

FoxTable _FoxTable =
{
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_GetItemId( ) API Library Routine
_NewItem( ) API Library Routine
_SetItemText( ) API Library Routine
Accessing the Visual FoxPro API


_GetItemText( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetItemText( ) API Library Routine
See Also Example

Copies the text of a menu bar or menu title to the buffer pointed to by text.

void _GetItemText(MENUID menuid, ITEMID itemid, char FAR *text)
MENUID menuid;            /* Menu identifier. */
ITEMID itemid;            /* Menu item identifier. */
char FAR *text;            /* Buffer address for text. */

Remarks

The buffer must be at least 80 bytes long.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a menu with three items and then retrieves the text of each item with _GetItemText( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO GETITEXT

C Code

Copy Code
#include <pro_ext.h>

FAR GetItemTextEx(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;
   char FAR *itemText;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);

   if ((itemText = _Alloca(80)) == 0)
   {
      _Error(182); // "Insufficient memory"
   }
   _GetItemText(menuId, _GetItemId(menuId, 0), itemText);
   _PutStr("\nItem text of 1st item = "); _PutStr(itemText);

   _GetItemText(menuId, _GetItemId(menuId, 1), itemText);
   _PutStr("\nItem text of 2nd item = "); _PutStr(itemText);

   _GetItemText(menuId, _GetItemId(menuId, 2), itemText);
   _PutStr("\nItem text of 3rd item = "); _PutStr(itemText);

   _Execute("WAIT WINDOW");
   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) GetItemTextEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_GetItemSubMenu( ) API Library Routine
_NewItem( ) API Library Routine
_SetItemText( ) API Library Routine
Accessing the Visual FoxPro API


_GetNewItemId( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetNewItemId( ) API Library Routine
See Also Example

Returns an identifier that's currently available for use as an item identifier in the specified menu.

ITEMID _GetNewItemId(MENUID menuid)
MENUID menuid;            /* Menu identifier. */

Remarks

Every item in a menu must have an identifier that's unique to that menu.

After using _GetNewItemId( ), add the new item to the menu with _NewItem( ) before using _GetNewItemId( ) again. If you don't add the item to the menu, subsequent calls to _GetNewItemId( ) return the same ITEMID.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a menu with three items. Before each item is added to the menu, a unique ITEMID is generated by calling _GetNewItemId( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO GETNWIID

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR GetNewItemId(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _MenuInteract(&menuId, &itemId);

   _PutStr("\nmenuId ="); putLong(menuId);
   _PutStr("\nitemId ="); putLong(itemId);

   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) GetNewItemId, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_GetItemId( ) API Library Routine
Accessing the Visual FoxPro API
_SetItemText( ) API Library Routine
_NewItem( ) API Library Routine
_GetNewMenuId( ) API Library Routine


_GetNewMenuId( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetNewMenuId( ) API Library Routine
See Also Example

Returns a menu identifier for use with other menu-related functions.

MENUID _GetNewMenuId(void any)
void any;                     /* Pointer. */

Remarks

Every menu must have a unique identifier.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example builds a menu with three items. Before the example can create a menu using _NewMenu( ), it must use _GetNewMenuId( ) to generate a unique MENUID.

Visual FoxPro Code

Copy Code
SET LIBRARY TO GETNWMID

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR GetNewItemId(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _MenuInteract(&menuId, &itemId);

   _PutStr("\nmenuId ="); putLong(menuId);
   _PutStr("\nitemId ="); putLong(itemId);

   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) GetNewItemId, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_DisposeMenu( ) API Library Routine
_MenuId( ) API Library Routine
Accessing the Visual FoxPro API


_GetNextEvent( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetNextEvent( ) API Library Routine
See Also Example

Reads the next event into the EventRec and returns the event type.

int _GetNextEvent(EventRec FAR *event)
EventRec FAR *event;   /* Event. */

Remarks

Null events are generated when no other activity has taken place. Idle routines shouldn't call _GetNextEvent( ). You can call _GetNextEvent( ) from an event handler but you must be careful, because _GetNextEvent( ) calls the event handler recursively.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example is a loop consisting of a call to _GetNextEvent( ), followed by a call to _DefaultProcess( ). All events during this procedure receive their default processing.

Visual FoxPro Code

Copy Code
SET LIBR TO GETNXEV

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   EventRec ev;
   int i;

   for (i = 0; i < 16; i++) {
      _GetNextEvent(&ev);
      _DefaultProcess(&ev);
   }
}
FoxInfo myFoxInfo[] = {
   {"ONLOAD", Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_ActivateHandler( ) API Library Routine
_FindWindow( ) API Library Routine
_GlobalToLocal( ) API Library Routine
_MousePos( ) API Library Routine
Accessing the Visual FoxPro API
_DefaultProcess( ) API Library Routine


_GetObjectProperty( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetObjectProperty( ) API Library Routine
See Also

Returns a property value for an object.

int _GetObjectProperty(Value FAR *retval, Value FAR *objct,
   char FAR *prop)

Remarks

The object to return a property for is specified with *objct, and the property to return is specified with *prop.

The value returned is placed in the *retval value structure.

Note:
You must always fill the *retval structure with 0 prior to calling _GetObjectProperty().

_GetObjectProperty( ) returns 0 if it is successful; otherwise, the negative value of the corresponding Visual FoxPro error code is returned.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

See Also

Other Resources

API Library Construction
_SetObjectProperty( ) API Library Routine
Object Property
ReadObject Property


_GetOSPrompt( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GetOSPrompt( ) API Library Routine
See Also Example

Returns the text of a specified menu item. If the menu item contains an access key definition, the ampersand character is returned as well.

void _GetOSPrompt(MENUID menuid, ITEMID itemid, char FAR *text)
MENUID menuid;            /* ID of menu from which to get prompt */
MENUID itemuid ;            /* Index (0-based) of menu item. */
char FAR *text;               /* Text of menu command. */

Remarks

Can be used for developing applications with language-independent access keys.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example returns the text of the first command on the File menu.

Visual FoxPro Code

Copy Code
SET LIBRARY TO MENUPROMPT

C Code

Copy Code
#include <pro_ext.h>

void FAR menuprompt(ParamBlk FAR *parm)
{
   char prompt[256] ;
   MenuId men ;

   men = _MenuId(_FILE);
   _GetOSPrompt(men, 0, prompt); //File New...

   _RetChar(prompt);
}
FoxInfo myFoxInfo[] = {
   {"MENUPROMPT", (FPFI) menuprompt, 0, ""}
};

FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_GetNewMenuId( ) API Library Routine
_MenuId( ) API Library Routine
_NewMenu( ) API Library Routine
Accessing the Visual FoxPro API


_GlobalToLocal( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GlobalToLocal( ) API Library Routine
See Also Example

Translates a point in screen-relative coordinates to window-relative coordinates.

void _GlobalToLocal(Point FAR *pt, WHANDLE wh)
Point FAR *pt;               /* Point. */
WHANDLE wh;            /* Window handle. */

Remarks

Before calling _GlobalToLocal( ), call _FindWindow( ) to determine which window owns the point.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example waits for a left mouse button click and then uses _FindWindow( ) to get the window handle for the mouse position. _GlobalToLocal( ) takes both the window handle and the absolute mouse position as parameters, and returns the mouse position to a position relative to the window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO GLTOLOC

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR FindWindowEx(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point mousePos;
   int where;

   // Get mouse position when left button goes down
   _Execute("WAIT WINDOW 'Click In A Window' NOWAIT");
   while (_InKey(0, MOUSEACTIVE | HIDECURSOR) != 151);
   while (!_MousePos(&mousePos));

   switch (where = _FindWindow(&wh, mousePos))
   {
      case inBorder:
         _PutStr("\nMouse down inBorder"); break;
      case inHelp:
         _PutStr("\nMouse down inHelp"); break;
      case inContent:
         _PutStr("\nMouse down inContent"); break;
      case inDrag:
         _PutStr("\nMouse down inDrag"); break;
      case inGrow:
         _PutStr("\nMouse down inGrow"); break;
      case inGoAway:
         _PutStr("\nMouse down inGoAway"); break;
      case inZoom:
         _PutStr("\nMouse down inZoom"); break;
      case inVUpArrow:
         _PutStr("\nMouse down inVUpArrow"); break;
      case inVDownArrow:
         _PutStr("\nMouse down inVDownArrow"); break;
      case inVPageUp:
         _PutStr("\nMouse down inVPageUp"); break;
      case inVPageDown:
         _PutStr("\nMouse down inVPageDown"); break;
      case inVThumb:
         _PutStr("\nMouse down inVThumb"); break;
      case inHUpArrow:
         _PutStr("\nMouse down inHUpArrow"); break;
      case inHDownArrow:
         _PutStr("\nMouse down inHDownArrow"); break;
      case inHPageUp:
         _PutStr("\nMouse down inHPageUp"); break;
      case inHPageDown:
         _PutStr("\nMouse down inHPageDown"); break;
      case inHThumb:
         _PutStr("\nMouse down inHThumb"); break;
      case inMenuBar:
         _PutStr("\nMouse down inMenuBar"); break;
      default:
         _PutStr("\nMouse down someplace else"); break;
   }
   _GlobalToLocal(&mousePos, wh);
   _PutStr("\nPosition relative to window:");
   putLong(mousePos.v, 5);
   _PutChr(' ');
   putLong(mousePos.h, 5);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) FindWindowEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FindWindow( ) API Library Routine
_MousePos( ) API Library Routine
Accessing the Visual FoxPro API
_GlobalToLocalP( ) API Library Routine


_GlobalToLocalP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_GlobalToLocalP( ) API Library Routine
See Also Example

Translates a point in screen-relative pixel coordinates to window-relative pixel coordinates.

void _GlobalToLocalP(Point FAR *pt, WHANDLE wh)
Point FAR *pt;               /* Point. */
WHANDLE wh;            /* Window handle. */

Remarks

Before calling _GlobalToLocalP( ), call _FindWindow( ) to determine which window owns the point.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example waits for a left mouse button click and then uses _FindWindowP( ) to get the window handle for the mouse position. _GlobalToLocalP( ) takes the window handle and the absolute mouse position as parameters, and returns the mouse position to a position relative to the window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO GLTOLOCP

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR FindWindowEx(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point mousePos;
   int where;

   // Get mouse position when left button goes down
   _Execute("WAIT WINDOW 'Click In A Window' NOWAIT" );
   while (_InKey(0, MOUSEACTIVE | HIDECURSOR) != 151);
   while (!_MousePosP(&mousePos));

   switch (where = _FindWindowP(&wh, mousePos))
   {
      case inBorder:
         _PutStr("\nMouse down inBorder"); break;
      case inHelp:
         _PutStr("\nMouse down inHelp"); break;
      case inContent:
         _PutStr("\nMouse down inContent"); break;
      case inDrag:
         _PutStr("\nMouse down inDrag"); break;
      case inGrow:
         _PutStr("\nMouse down inGrow"); break;
      case inGoAway:
         _PutStr("\nMouse down inGoAway"); break;
      case inZoom:
         _PutStr("\nMouse down inZoom"); break;
      case inVUpArrow:
         _PutStr("\nMouse down inVUpArrow"); break;
      case inVDownArrow:
         _PutStr("\nMouse down inVDownArrow"); break;
      case inVPageUp:
         _PutStr("\nMouse down inVPageUp"); break;
      case inVPageDown:
         _PutStr("\nMouse down inVPageDown"); break;
      case inVThumb:
         _PutStr("\nMouse down inVThumb"); break;
      case inHUpArrow:
         _PutStr("\nMouse down inHUpArrow"); break;
      case inHDownArrow:
         _PutStr("\nMouse down inHDownArrow"); break;
      case inHPageUp:
         _PutStr("\nMouse down inHPageUp"); break;
      case inHPageDown:
         _PutStr("\nMouse down inHPageDown"); break;
      case inHThumb:
         _PutStr("\nMouse down inHThumb"); break;
      case inMenuBar:
         _PutStr("\nMouse down inMenuBar"); break;
      default:
         _PutStr("\nMouse down someplace else"); break;
   }
   _GlobalToLocalP(&mousePos, wh);
   _PutStr("\nPosition relative to window:");
   putLong(mousePos.v, 5);
   _PutChr(' ');
   putLong(mousePos.h, 5);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", FindWindowEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_FindWindow( ) API Library Routine
_MousePos( ) API Library Routine
_GlobalToLocal( ) API Library Routine
Accessing the Visual FoxPro API


_HandToPtr( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_HandToPtr( ) API Library Routine
See Also Example

Translates a memory handle to a FAR (32-bit) pointer, which points to the memory allocated to this handle.

void FAR * _HandToPtr(MHANDLE hand)
MHANDLE hand;            /* Memory handle. */

Remarks

Visual FoxPro may reorganize memory any time control is passed to it or to another routine outside of the current module.

Note:
_HandToPtr() doesn't cause memory reorganization. The pointer returned by _HandToPtr() may become invalid any time control is passed back to Visual FoxPro, unless the MHANDLE is locked. Don't keep pointers to unlocked memory handles across an external function call, unless it is documented that the call doesn't cause memory reorganization.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays its character parameter on the screen. It uses _HandToPtr( ) to translate the memory handle of the API parameter to a C pointer.

Visual FoxPro Code

Copy Code
SET LIBRARY TO HANDTOPT
= HANDTOPTR("Hello, world.")  && displays "Hello, world" on screen

C Code

Copy Code
#include <pro_ext.h>

void NullTerminate(Value FAR *cVal)
{
   if (!_SetHandSize(cVal->ev_handle, cVal->ev_length + 1))
   {
      _Error(182); // "Insufficient memory"
   }
   ((char FAR *) _HandToPtr(cVal->ev_handle))[cVal->ev_length] = '\0';
}

FAR Example(ParamBlk FAR *parm)
{
   NullTerminate(&parm->p[0].val);
   _HLock(parm->p[0].val.ev_handle);
   _PutStr(_HandToPtr(parm->p[0].val.ev_handle));
   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"HANDTOPTR", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_AllocHand( ) API Library Routine
_FreeHand( ) API Library Routine
_GetHandSize( ) API Library Routine
_HLock( ) API Library Routine
_HUnLock( ) API Library Routine
_MemAvail( ) API Library Routine
_SetHandSize( ) API Library Routine
Accessing the Visual FoxPro API


_HLock( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_HLock( ) API Library Routine
See Also Example

Locks a memory handle to prevent it from moving if Visual FoxPro requires memory reorganization.

void _HLock(MHANDLE hand)
MHANDLE hand;            /* Memory handle. */

Remarks

_HLock( ) doesn't cause memory reorganization. Unlock the MHANDLE as soon as the lock has served its purpose.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays its character parameter on the screen. It uses _HandToPtr( ) to translate the memory handle of the API parameter to a C pointer. Because Visual FoxPro may decide to reorganize memory during the call to _PutStr( ), to insure proper execution, the example locks the memory handle with _HLock( ). The example also calls _HUnLock( ) at the end, because the performance of Visual FoxPro can be adversely affected by locked memory handles.

Visual FoxPro Code

Copy Code
SET LIBRARY TO HLOCK
= HLOCK("Hello, world.") && displays "Hello, world" on screen

C Code

Copy Code
#include <pro_ext.h>

void NullTerminate(Value FAR *cVal)
{
   if (!_SetHandSize(cVal->ev_handle, cVal->ev_length + 1))
   {
      _Error(182); // "Insufficient memory"
   }
   ((char FAR *) _HandToPtr(cVal->ev_handle))[cVal->ev_length] = '\0';
}

FAR Example(ParamBlk FAR *parm)
{
   NullTerminate(&parm->p[0].val);
   _HLock(parm->p[0].val.ev_handle);
   _PutStr(_HandToPtr(parm->p[0].val.ev_handle));
   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"HLOCK", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_AllocHand( ) API Library Routine
_FreeHand( ) API Library Routine
_GetHandSize( ) API Library Routine
_HandToPtr( ) API Library Routine
_HUnLock( ) API Library Routine
_MemAvail( ) API Library Routine
_SetHandSize( ) API Library Routine
Accessing the Visual FoxPro API


_HUnLock( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_HUnLock( ) API Library Routine
See Also Example

Unlocks a memory handle so that Visual FoxPro can access it during memory reorganization.

void _HUnLock(MHANDLE hand)
MHANDLE hand;            /* Memory handle. /

Remarks

_HUnLock( ) doesn't cause memory reorganization.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _RetDateStr( ) to return a Visual FoxPro date type, assuming that the character parameter is a proper date. It issues _HUnLock( ) when memory handles no longer need to be locked, because the performance of Visual FoxPro can be adversely affected by locked memory handles.

Visual FoxPro Code

Copy Code
SET LIBRARY TO HUNLOCK
? DATES("2/16/95")  && returns date {02/16/95}

C Code

Copy Code
#include <pro_ext.h>

void FAR dates(ParamBlk FAR *parm)
{
   MHANDLE mh;
   char FAR *instring;

   if ((mh = _AllocHand(parm->p[0].val.ev_length + 1)) == 0)
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   instring = _HandToPtr(parm->p[0].val.ev_handle);
   instring[parm->p[0].val.ev_length] = '\0';
   _RetDateStr(instring);
   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"DATES", (FPFI) dates, 1, "C"}
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_AllocHand( ) API Library Routine
_FreeHand( ) API Library Routine
_GetHandSize( ) API Library Routine
_HandToPtr( ) API Library Routine
_HLock( ) API Library Routine
_MemAvail( ) API Library Routine
_SetHandSize( ) API Library Routine


_InKey( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_InKey( ) API Library Routine
See Also Example

Returns the first key typed during the timeout period.

int _InKey(int timeout, int flag)
int timeout;                  /* Timeout period. */
int flag;                     /* Option(s). */

Remarks

The timeout period is specified as a number of operating system timer ticks (1000/second). A timeout period of 0 causes Visual FoxPro to wait until the user presses a key. A negative timeout value causes _InKey( ) to return to the calling program immediately if the user doesn't press a key.

You can specify flag as one or both of the following options:

  • SHOWCURSOR or HIDECURSOR

  • MOUSEACTIVE

Use SHOWCURSOR to force the cursor to appear, or HIDECURSOR to force the cursor to disappear. If neither is specified, the cursor respects the SYS(2002) setting. The additional flag value MOUSEACTIVE causes _InKey( ) to treat mouse clicks as keystrokes. _InKey returns 151 for a mouse click. To specify two flag values, use the C | or + operator.

Note:
Idle routines must not call _InKey().

You can write event handlers that call _InKey( ), but you must be careful because _InKey( ) calls the event handler recursively.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example calls _InKey( ) from Visual FoxPro with two flags.

Visual FoxPro Code

Copy Code
SET LIBRARY TO INKEY
#define SHOWCURSOR   1
#define HIDECURSOR   2
#define MOUSEACTIVE 4
= XINKEY(0, SHOWCURSOR + MOUSEACTIVE)

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _RetInt(_InKey((int) parm->p[0].val.ev_long,
      (int) parm->p[1].val.ev_long), 10);
}

FoxInfo myFoxInfo[] = {
   {"XINKEY", (FPFI) Example, 2, "I,I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

INKEY( ) Function
Accessing the Visual FoxPro API
ReadTimeout Property
API Library Routines A-Z
API Library Routines by Category


_Load( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_Load( ) API Library Routine
See Also Example

Places the value of the memory variable or current record field specified by loc into val.

int _Load(Locator FAR *loc, Value FAR *val)
Locator FAR *loc;         /* Variable location. */
Value FAR *val;            /* Holds value of the variable. */

Remarks

_Load( ) returns 0 if the routine is successful. If the routine fails, it returns a negative integer whose absolute value is a Visual FoxPro error number. You can use _Load( ) to retrieve the contents of a memo field, but it doesn't retrieve characters in the field after the first 65,000 bytes. If loc specifies a one-dimensional array, Visual FoxPro returns the value of the first element of the array.

_Load( ) doesn't work with objects. If loc specifies an object reference, _Load( ) returns 0 without filling the val Value structure. Use _Evaluate( ) to obtain an object reference.

If the setting of the Locator field l_offset is – 1, Visual FoxPro returns a logical value structure that indicates whether the current record in the specified work area is deleted:

  • ev_length = .T. = DELETED( )

  • ev_length = .F. = NOT DELETED( )

    Note:
    _Load() creates a handle only when the memory variable your program is loading is a character string (ev_type = 'C'). All other data types store their values in the Value structure itself. Your program must free the handles created with _Load().

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example converts to uppercase a string argument passed by reference.

Visual FoxPro Code

Copy Code
SET LIBRARY TO LOAD
x = "abc"
= XUPPER(@x)
? x

C Code

Copy Code
#include <pro_ext.h>

void FAR Upper(ParamBlk FAR *parm)
{
      char FAR *pString;
      Value val;
      int i;
//
//   _Load() and _Store are the functions of interest for pass-by-reference.
//
   _Load(&parm->p[0].loc, &val);
//
//   FoxPro doesn't check the type of pass-by-reference arguments, so we do.
//
  if (val.ev_type != 'C')
   {
      _Error(9); // "Data type mismatch"
   }
  pString = _HandToPtr(val.ev_handle);

   for (i = 0; i < val.ev_length; i++)
   {
      if ('a' <= *pString && *pString <= 'z')
      {
         *pString += ('A' - 'a');
      }
      pString++;
   }
   _Store(&parm->p[0].loc, &val);
   //
   // We need to free the handle that we created with  _LOAD()
   //
   _FreeHand(val.ev_handle);
}

FoxInfo myFoxInfo[] =
{
   {"XUPPER", (FPFI) Upper, 1, "R"},
};

FoxTable _FoxTable =
{
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_ALen( ) API Library Routine
_FindVar( ) API Library Routine
_NameTableIndex( ) API Library Routine
_NewVar( ) API Library Routine
_Release( ) API Library Routine
_Store( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_MemAvail( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_MemAvail( ) API Library Routine
See Also Example

Determines whether enough memory is available for you to allocate a memory handle of size bytes.

BOOL _MemAvail(unsigned long size)
unsigned int size;            /* Size of memory handle in bytes. */

Remarks

The function returns True (an integer other than 0) if enough memory is available, or False (0) if not.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example builds a linked list of 1K memory handle allocations until available memory is used. It then frees allocations and returns the number of allocations made. _MemAvail( ) is used to terminate the first while loop.

Visual FoxPro Code

Copy Code
SET LIBRARY TO MEMAVAIL
? MEMAVAIL()  && displays approx. memory available in K

C Code

Copy Code
#include <pro_ext.h>

#define ALLOCSIZE 1024

FAR Example(ParamBlk FAR *parm)
{
   int nHandles = 0;
   MHANDLE head = 0, mh;

   while (_MemAvail(ALLOCSIZE))
   {
      mh = _AllocHand(ALLOCSIZE);
      *((MHANDLE *) _HandToPtr(mh)) = head;
      head = mh;
      nHandles++;
   }
   _RetInt(nHandles, 10);
   while (head != 0)
   {
      mh = *((MHANDLE *) _HandToPtr(head));
      _FreeHand(head);
      head = mh;
   }
}

FoxInfo myFoxInfo[] = {
   {"MEMAVAIL", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_AllocHand( ) API Library Routine
_FreeHand( ) API Library Routine
_GetHandSize( ) API Library Routine
_HandToPtr( ) API Library Routine
_HLock( ) API Library Routine
_HUnLock( ) API Library Routine
_SetHandSize( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_MemCmp( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_MemCmp( ) API Library Routine
See Also Example

Compares two length byte memory areas.

int _MemCmp(void FAR *ptr1, void FAR *ptr2, unsigned int length)
void FAR *ptr1;            /* First point to start compare. */
void FAR *ptr2;            /* Second point to start compare. */
unsigned int length;         /* How much to compare in bytes. */

Remarks

_MemCmp( ) compares each byte in the two areas, starting with the leftmost byte in each, until two bytes don't match. _MemCmp( ) returns 0 if all bytes in the areas match, a positive number if the first unmatched byte in the first area is greater than the corresponding byte in the second area, or a negative number if the first unmatched byte in the second area is greater than the corresponding byte in the first area.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _MemCmp( ) to compare two character parameters up to the length of the first unmatched byte.

Visual FoxPro Code

Copy Code
SET LIBRARY TO MEMCMP
? MEMCMP("Hello, world.", "Hello, world.")  && returns 0
? MEMCMP("Hello, world.", "Hello, wurld.")  && returns non-0

C Code

Copy Code
#include <pro_ext.h>

#define min(a, b) ((a) < (b) ? (a) : (b))

FAR Example(ParamBlk FAR *parm)
{
   int LenToCmp, RetValue;

   LenToCmp = min(parm->p[0].val.ev_length, parm->p[1].val.ev_length);

   _HLock(parm->p[0].val.ev_handle);
   _HLock(parm->p[1].val.ev_handle);

   RetValue = _MemCmp(_HandToPtr(parm->p[0].val.ev_handle),
      _HandToPtr(parm->p[1].val.ev_handle), LenToCmp);

   _RetInt(RetValue, 10); // does return control here

   _HUnLock(parm->p[0].val.ev_handle);
   _HUnLock(parm->p[1].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"MEMCMP", (FPFI) Example, 2, "C,C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_MemFill( ) API Library Routine
_MemMove( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_MemFill( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_MemFill( ) API Library Routine
See Also Example

Fills an area of memory starting at the location pointed to by ptr with length copies of the byte in character.

void _MemFill(void FAR *ptr, int character, unsigned int length)
void FAR *ptr;               /* Starting point for fill. */
int character;               /* Character for fill. */
unsigned int length;         /* How many bytes to fill. */

Example

The following example uses _MemFill( ) to duplicate the functionality of the Visual FoxPro function REPLICATE( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO MEMFILL
x = xREPLICATE("x", 120)
? x
? LEN(x)

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   char FAR *rep;
   char c = *(char *) _HandToPtr(parm->p[0].val.ev_handle);

   rep = _Alloca((int) parm->p[1].val.ev_long + 1);

   _MemFill(rep, c, (int) parm->p[1].val.ev_long);

  rep[parm->p[1].val.ev_long] = '\0';
   _RetChar(rep);
}
FoxInfo myFoxInfo[] = {
   {"XREPLICATE", (FPFI) Example, 2, "C,I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_MemCmp( ) API Library Routine
_MemMove( ) API Library Routine
_MemAvail( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_MemMove( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_MemMove( ) API Library Routine
See Also Example

Copies length bytes starting from src to dest.

void _MemMove(void FAR *dest, void FAR *src, unsigned int length)
void FAR *dest;            /* Destination. */
void FAR *src;               /* Starting position. */
unsigned int length;         /* How many bytes to move. */

Remarks

Overlapping moves are performed in the appropriate direction to prevent data corruption.

For more information on how to create an API library and integrate it with Visual FoxPro, see see Accessing the Visual FoxPro API.

Example

The following example uses _MemMove( ) to implement a substring function. From Visual FoxPro, MEMMOVE(s, n1, n2) returns the substring of s starting from position n1 and through position n2.

Visual FoxPro Code

Copy Code
SET LIBRARY TO MEMMOVE
? MEMMOVE("Hello, world.", 8, 10)  && returns "wor"

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   int SubstrLen;
   MHANDLE bufferHandle;
   char FAR *FirstDest;

   SubstrLen = parm->p[2].val.ev_long - parm->p[1].val.ev_long + 1;
   if ((bufferHandle = _AllocHand(SubstrLen + 1)) == 0)
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(bufferHandle);
   _HLock(parm->p[0].val.ev_handle);
   FirstDest = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle) +
      parm->p[1].val.ev_long - 1;

   _MemMove(_HandToPtr(bufferHandle), FirstDest, SubstrLen);

   ((char FAR *) _HandToPtr(bufferHandle))[SubstrLen] = '\0';
   _RetChar(_HandToPtr(bufferHandle));
   _HUnLock(bufferHandle);
   _HUnLock(parm->p[0].val.ev_handle);
}
FoxInfo myFoxInfo[] = {
   {"MEMMOVE", (FPFI) Example, 3, "C,I,I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_MemCmp( ) API Library Routine
_MemFill( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_MemoChan( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_MemoChan( ) API Library Routine
See Also Example

Returns the file channel of the memo file associated with the specified workarea.

FCHAN _MemoChan(int workarea)
int workarea;               /* Work area number. */

Remarks

If no database is open in that work area or the database has no memo file, _MemoChan( ) returns – 1.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example retrieves the contents of a memo field. _MemoChan( – 1) returns a file channel to the memo file for the current work area. This FCHAN is used as an argument to the low-level file I/O API callbacks.

Visual FoxPro Code

Copy Code
SET LIBRARY TO MEMOCHAN
CREATE TABLE WMemo (MemoField M)
APPEND BLANK
REPLACE MemoField WITH "Hello, World."
? GETMEMO(@MemoField)

C Code

Copy Code
#include <pro_ext.h>

FAR FindMemoEx(ParamBlk FAR *parm)
{
   Locator FAR *memoFldLoc;
   FCHAN fchMemo;
   char FAR *memoContents;
   int memoLen;
   long loc;

   if ((fchMemo = _MemoChan(-1)) == -1)
   {
      _UserError("_MemoChan() failed");
   }
   memoFldLoc = &parm->p[0].loc;

   if ((loc = _FindMemo(memoFldLoc)) < 0)
   {
      _UserError("_FindMemo() failed");
   }
   if ((memoLen = _MemoSize(memoFldLoc)) < 0)
   {
      _UserError("_MemoSize() failed");
   }
   if ((memoContents = _Alloca(memoLen + 1)) == 0)
   {
      _Error(182); // "Insufficient memory"
   }
   _FSeek(fchMemo, loc, FS_FROMBOF);
   _FRead(fchMemo, memoContents, memoLen);
   memoContents[memoLen] = '\0';
   _RetChar(memoContents);
}

FoxInfo myFoxInfo[] = {
   {"GETMEMO", (FPFI) FindMemoEx, 1, "R"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_AllocMemo( ) API Library Routine
_DBReplace( ) API Library Routine
_FindMemo( ) API Library Routine
_FOpen( ) API Library Routine
_MemoSize( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_MemoSize( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_MemoSize( ) API Library Routine
See Also Example

Returns the length of the specified memo field in the memo file for the current record.

long _MemoSize(Locator FAR *fld)
Locator FAR *fld;            /* Memo field address. */

Remarks

When the memo field for the current record is empty, or when fld isn't a memo field, _MemoSize( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example retrieves the contents of a memo field for the current record. _MemoSize( ) is used to determine how much memory should be allocated for a buffer, and how many bytes should be read from the memo file.

Visual FoxPro Code

Copy Code
SET LIBRARY TO MEMOSIZE
CREATE TABLE WMemo (MemoField M)
APPEND BLANK
REPLACE MemoField WITH "Hello, World."
? GETMEMO(@MemoField)

C Code

Copy Code
#include <pro_ext.h>

FAR FindMemoEx(ParamBlk FAR *parm)
{

   Locator FAR *memoFldLoc;
   FCHAN fchMemo;
   char FAR *memoContents;
   int memoLen;
   long loc;

   if ((fchMemo = _MemoChan(-1)) == -1)
   {
      _UserError("_MemoChan() failed");
   }
   memoFldLoc = &parm->p[0].loc;

   if ((loc = _FindMemo(memoFldLoc)) < 0)
   {
      _UserError("_FindMemo() failed");
   }
   if ((memoLen = _MemoSize(memoFldLoc)) < 0)
   {
      _UserError("_MemoSize() failed");
   }
   if ((memoContents = _Alloca(memoLen + 1)) == 0)
   {
      _Error(182); // "Insufficient memory"
   }
   _FSeek(fchMemo, loc, FS_FROMBOF);
   _FRead(fchMemo, memoContents, memoLen);
   memoContents[memoLen] = '\0';
   _RetChar(memoContents);
}

FoxInfo myFoxInfo[] = {
   {"GETMEMO", (FPFI) FindMemoEx, 1, "R"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_AllocMemo( ) API Library Routine
_DBReplace( ) API Library Routine
_FindMemo( ) API Library Routine
_MemoChan( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_MenuId( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_MenuId( ) API Library Routine
See Also Example

Returns the menu identifier that corresponds to the system-defined literal for the system menu or menu title.

MENUID _MenuId(long literal)
long literal;                  /* System-defined literal. */

Remarks

Literals are defined in the API include file PRO_EXT.H.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example adds a menu title to the system menu. It then attaches a drop-down menu with two items on it. _MenuId( ) is used to obtain the MENUID of the system menu.

Visual FoxPro Code

Copy Code
SET LIBRARY TO MENUID

C Code

Copy Code
#include <pro_ext.h>

MENUID SysMenuId;
MENUID PopupId;
ITEMID PadId;

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR onSelection(long menuId, long itemId)
{
   _PutStr("\nitemId = "); putLong(itemId);
}

void FAR StartUp()
{
   ITEMID Bar1Id;
   ITEMID Bar2Id;
   int Error;

   // Add new menu title to SYSMENU.
   SysMenuId = _MenuId(_SYSMENU);
   PadId = _GetNewItemId(SysMenuId);

   if (_NewItem(SysMenuId, PadId, _LASTITEM, "\\<Added menu title"))
   {
      _Error(623); /* "Menu item cannot be defined." */
   }

   // Define menu.
   PopupId = _GetNewMenuId();

   if (Error = _NewMenu(MPOPUP, PopupId))
   {
      _Error(-Error);
   }
   Bar1Id = _GetNewItemId(PopupId);

   // WARNING: Call _NewItem() before another _GetNewItemId().
   if (_NewItem(PopupId, Bar1Id, _LASTITEM, "\\<1st item"))
   {
      _Error(623); /* "Menu item cannot be defined." */
   }
   Bar2Id = _GetNewItemId(PopupId);

   if (_NewItem(PopupId, Bar2Id, _LASTITEM, "\\<2nd item"))
   {
      _Error(623); /* "Menu item cannot be defined." */
   }

   // Attach menu to menu title
   _SetItemSubMenu(SysMenuId, PadId, PopupId);

   // Set up selection action.
   _OnSelection(PopupId, -1, onSelection);
}

void FAR ShutDown()
{
   _DisposeItem(SysMenuId, PadId);
   _DisposeMenu(PopupId);
}

FoxInfo myFoxInfo[] = {
   {"STARTUP",   (FPFI) StartUp,   CALLONLOAD,""},
   {"SHUTDOWN",   (FPFI) ShutDown,   CALLONUNLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

SYS(1500) - Activate a System Menu Item
_GetNewMenuId( ) API Library Routine
System Menu Names
_MenuInteract( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_MenuInteract( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_MenuInteract( ) API Library Routine
See Also Example

Sets the itemid and the menuid to indicate which menu item was chosen, if any.

int _MenuInteract(MENUID FAR *menuid, ITEMID FAR *itemid)
MENUID FAR *menuid;      /* Pointer to menu identifier. */
ITEMID FAR *itemid;      /* Pointer to menu item identifier. */

Remarks

If the user chooses any menu item, _MenuInteract( ) returns 1. If no item is chosen (for example, if the user presses ESC) _MenuInteract( ) returns 0.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example builds a menu with three items, and then requires the user to interact with the menu by calling _MenuInteract( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO MENUINTE

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR GetNewItemId(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _MenuInteract(&menuId, &itemId);

   _PutStr("\nmenuId ="); putLong(menuId);
   _PutStr("\nitemId ="); putLong(itemId);

   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) GetNewItemId, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_MenuId( ) API Library Routine
Accessing the Visual FoxPro API
_OnSelection( )
_GetNewMenuId( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_MousePos( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_MousePos( ) API Library Routine
See Also Example

Fills in pt with the current position of the mouse pointer.

int _MousePos(Point FAR *pt)
Point FAR *pt;               /* Pointer. */

Remarks

_MousePos( ) returns True (an integer other than 0) if the left mouse button is down when the function is called, or False (0) if the left mouse button isn't down.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays the current mouse pointer position until it detects a left mouse button click.

Visual FoxPro Code

Copy Code
SET LIBRARY TO MOUSEPOS

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR MousePosEx(ParamBlk FAR *parm)
{
   Point mousePos;

   while (!_MousePos(&mousePos))
   {
      _PutStr("\nvertical =");
      putLong(mousePos.v, 5);
      _PutStr("; horizontal =");
      putLong(mousePos.h, 5);
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) MousePosEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_FindWindow( ) API Library Routine
_GlobalToLocal( ) API Library Routine
_MousePosP( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_MousePosP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_MousePosP( ) API Library Routine
See Also Example

Fills in pt with the current position of the mouse pointer in pixels.

int _MousePosP(Point FAR *pt)
Point FAR *pt;               /* Pointer. */

Remarks

_MousePosP( ) returns True (an integer other than 0) if the left mouse button is down when the function is called, or False (0) if the left mouse button isn't down.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays the current mouse pointer position until it detects a left mouse button click.

Visual FoxPro Code

Copy Code
SET LIBRARY TO MOUSEPOP

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR MousePosPEx(ParamBlk FAR *parm)
{
   Point mousePos;

   while (!_MousePosP(&mousePos))
   {
      _PutStr("\nvertical =");
      putLong(mousePos.v, 5);
      _PutStr("; horizontal =");
      putLong(mousePos.h, 5);
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) MousePosPEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_FindWindow( ) API Library Routine
_GlobalToLocal( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_NameTableIndex( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_NameTableIndex( ) API Library Routine
See Also Example

Returns the name table index that corresponds to a given name, or returns – 1 if that name isn't in the name table.

NTI _NameTableIndex(char FAR *name)
char FAR *name;            /* Name. */

Remarks

The name may be found in the name table even though a variable with the name name doesn't exist. To determine whether a variable with the name name exists, use _FindVar( ), specifying the name table index returned by _NameTableIndex( ) as the nti parameter.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example releases a memory variable whose name is given as a character argument. Note that _NameTableIndex( ) finds the variable name after it has been released. Therefore, _NameTableIndex( ) is used in combination with _FindVar( ) to make sure the memory variable is currently defined.

Visual FoxPro Code

Copy Code
SET LIBRARY TO NTI
x = 123
= XRELEASE("x")

C Code

Copy Code
#include <pro_ext.h>

FAR ReleaseEx(ParamBlk FAR *parm)
{
   NTI nti;
   char FAR *name;
   int exitCode;
   Locator loc;

   //   Null terminate character string, name of variable
   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   name = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   name[parm->p[0].val.ev_length] = '\0';

   if ((nti = _NameTableIndex(name)) == -1)
   {
      _HUnLock(parm->p[0].val.ev_handle);
      _UserError("Cannot find variable in name table.");
   }
   _HUnLock(parm->p[0].val.ev_handle);

   if (_FindVar(nti, -1, &loc))
   {
      _PutStr("\nVariable exists prior to _Release().");
   }
   if ((exitCode =_Release(nti)) < 0)
   {
      _Error(-exitCode);
   }

   _HLock(parm->p[0].val.ev_handle);
   name = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   name[parm->p[0].val.ev_length] = '\0';

   if ((nti = _NameTableIndex(name)) != -1)
   {
      _PutStr("\n_NameTableIndex() still finds variable \
         after it is released.");
   }
   _HUnLock(parm->p[0].val.ev_handle);

   if (!_FindVar(nti, -1, &loc))
   {
      _PutStr("\nVariable does not exist after _Release().");
   }
}

FoxInfo myFoxInfo[] = {
   {"XRELEASE", (FPFI) ReleaseEx, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_ALen( ) API Library Routine
_FindVar( ) API Library Routine
_Load( ) API Library Routine
_NewVar( ) API Library Routine
_ObjectRelease( ) API Library Routine
_Store( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_NewItem( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_NewItem( ) API Library Routine
See Also Example

Adds an item with the specified identifier itemid to the menu specified by menuid.

int _NewItem(MENUID menuid, ITEMID itemid, ITEMID
beforeid, char FAR *prompt)
MENUID menuid;            /* Menu identifier. */
ITEMID itemid;            /* New item identifier. */
ITEMID beforeid;            /* Identifier of item the new item
 precedes. */
char FAR *prompt;         /* Text for new menu item. */

Remarks

The type of the new menu item is automatically a menu title or a bar, depending on the type of menu into which the item is being inserted.

The beforeid parameter specifies the identifier of the item the new item is to precede. Specify beforeid as – 1 to specify the new item will be the first item in the list, or as -2 to specify the item is to be added at the end of the list. The prompt specifies the text for the new menu item. _NewItem( ) returns 0 if it succeeds in adding an item, or – 1 if not.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example builds a menu with three items. It uses _NewItem( ) to add each item to the menu.

Visual FoxPro Code

Copy Code
SET LIBRARY TO NEWITEM

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR GetNewItemId(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -1, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _MenuInteract(&menuId, &itemId);

   _PutStr("\nmenuId ="); putLong(menuId);
   _PutStr("\nitemId ="); putLong(itemId);

   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) GetNewItemId, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_SetItemCmdKey( ) API Library Routine
_SetItemSubMenu( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_NewMenu( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_NewMenu( ) API Library Routine
See Also Example

Creates a new menu of the specified menu type.

int _NewMenu(int mtype, MENUID menuid)
int mtype;                  /* Menu type. */
MENUID menuid;            /* Menu identifier. */

Remarks

You can specify MPOPUP or MBAR as the mtype parameter. The menu identifier must be unique.

Use _GetNewMenuId( ) to obtain an available menu id. _NewMenu( ) returns 0 if it succeeds in creating a new menu. If it's unsuccessful, _NewMenu( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _NewMenu( ) to create a menu.

Visual FoxPro Code

Copy Code
SET LIBRARY TO NEWMENU

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR GetNewItemId(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -1, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _MenuInteract(&menuId, &itemId);

   _PutStr("\nmenuId ="); putLong(menuId);
   _PutStr("\nitemId ="); putLong(itemId);

   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) GetNewItemId, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_ActivateMenu( ) API Library Routine
_GetNewMenuId( ) API Library Routine
_GetNewMenuId( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_NewVar( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_NewVar( ) API Library Routine
See Also Example

Creates a variable or an array.

NTI _NewVar(char FAR *name, Locator FAR *loc, int flag)
char FAR *name;            /* Variable name. */
Locator FAR *loc;            /* Place. */
int flag;                     /* Scope. */

Remarks

The NTI type definition stands for Name Table Index. See _NameTableIndex( ) API Library Routine for more information about Name Table Index use.

The variable or array name must follow standard Visual FoxPro rules for variable names. The new variable is initialized to the logical value False.

The setting of the Locator field l_subs determines the variable or array type:

  • 0 – a scalar variable

  • 1 – a one-dimensional array of size l_sub1

  • 2 – an array of size l_sub1 by l_sub2 For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

The flag parameter can be NV_PUBLIC or NV_PRIVATE. NV_PRIVATE variables are created as though they were created by the Visual FoxPro routine that called the external routine.

If _NewVar( ) successfully creates the variable, the field l_NTI is filled in with the non-negative NTI of the created variable, and _NewVar( ) returns this number. If _NewVar( ) fails, it returns a negative integer whose absolute value is an internal Visual FoxPro error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _NewVar( ) to create three variables.

Visual FoxPro Code

Copy Code
SET LIBRARY TO NEWVAR
*
* As defined in "pro_ext.h"
*
#define NV_PUBLIC   0
#define NV_PRIVATE   1

= xNewVar('var', 0, 0, 0, NV_PUBLIC)
DISPLAY MEMORY LIKE var

= xNewVar('onedim', 1, 5, 0, NV_PUBLIC)
DISPLAY MEMORY LIKE onedim

= xNewVar('twodim', 2, 5, 6, NV_PUBLIC)
DISPLAY MEMORY LIKE twodim

C Code

Copy Code
#include <pro_ext.h>

void FAR NewVarEx(ParamBlk FAR *parm)
{
   char FAR *varName;
   Locator loc;
   int flag;
   int retValue;

   // Null terminate character string
   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   varName = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   varName[parm->p[0].val.ev_length] = '\0';
   loc.l_subs = parm->p[1].val.ev_long;
   loc.l_sub1 = parm->p[2].val.ev_long;
   loc.l_sub2 = parm->p[3].val.ev_long;
   flag = parm->p[4].val.ev_long;
   if ((retValue = _NewVar(varName, &loc, flag)) < 0)
   {
      // _NewVar() returns negative Visual FoxPro error number
      _Error(-retValue);
   }
   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"XNEWVAR", (FPFI) NewVarEx, 5, "C,I,I,I,I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_ALen( ) API Library Routine
_FindVar( ) API Library Routine
_Load( ) API Library Routine
_NameTableIndex( ) API Library Routine
_ObjectRelease( ) API Library Routine
_Store( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_ObjectCmp( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_ObjectCmp( ) API Library Routine
See Also

Compares the properties of two objects and returns 0 if their properties and property values are identical.

int _ObjectCmp(Value FAR *objct1, Value FAR *objct2)

Remarks

0 is returned if the objects have identical properties and property values. -1 is returned if an object has a property that the other object doesn't have, or if the objects have identical properties but the values of one or more properties differ.

If an error occurs (for example, if you omit one of the objects), the negative value of the corresponding Visual FoxPro error code is returned.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

See Also

Other Resources

_GetObjectProperty( ) API Library Routine
_SetObjectProperty( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_ObjectReference( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_ObjectReference( ) API Library Routine
See Also

Increments the reference count of an object.

int _ObjectReference(Value FAR *objct)

Remarks

CLEAR MEMORY or CLEAR ALL releases an API object from memory.

0 is returned unless an error occurs. When an error occurs, a negative number representing an internal error code is returned.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

See Also

Other Resources

_FreeObject( ) API Library Routine
_ObjectRelease( ) API Library Routine
Accessing the Visual FoxPro API


_ObjectRelease( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_ObjectRelease( ) API Library Routine
See Also

Decrements the reference count of an object.

int _ObjectRelease(Value FAR *objct)

Remarks

0 is returned unless an error occurs. When an error occurs, a negative number representing an internal error code is returned.

See Also

Other Resources

_FreeObject( ) API Library Routine
_ObjectReference( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_OnSelection( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_OnSelection( ) API Library Routine
See Also Example

Specifies a routine to execute when the user chooses the specified menu and item.

void _OnSelection(MENUID menuid, ITEMID itemid, FPFI routine)
MENUID menuid;            /* Menu identifier. */
ITEMID itemid;            /* Item identifier. */
FPFI routine;               /* Routine to execute. */

Remarks

If you specify itemid as – 1, the routine executes when the user chooses any item on the menu. A routine associated with an individual item overrides one associated with the entire menu. To cancel a selection routine for a specified menu and item, pass (FPFI)0 as the routine parameter.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a menu with three items. It calls _OnSelection( ) with an ITEMID parameter of –1, indicating that the function USERCHOICE( ) is to be called when the user chooses any item from this menu.

Visual FoxPro Code

Copy Code
SET LIBRARY TO ONSELECT

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR onSelection(long menuId, long itemId)
{
   _PutStr("\nitemId = "); putLong(itemId);
   _DisposeMenu(menuId);
}

FAR activateMenu(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);
   _OnSelection(menuId, -1, onSelection);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) activateMenu, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

Accessing the Visual FoxPro API
_ActivateMenu( ) API Library Routine
_MenuInteract( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_PutChr( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_PutChr( ) API Library Routine
See Also Example

Displays the one character char at the output position in the current output window in its normal attribute (color 0).

void _PutChr(int char)
int char;                     /* Character to display. */

Remarks

_PutChr( ) treats special characters such as newline, carriage return, and bell as control characters and doesn't display them on the screen.

To display the character that corresponds to one of these control characters, add 256 to the value of the character.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _PutChr( ) to display all 8-bit characters on the screen.

Visual FoxPro Code

Copy Code
SET LIBRARY TO PUTCHR

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   int ch;

   for (ch = 0; ch < 256; ch++)
   {
      _PutChr(ch);
   }
}

FoxInfo myFoxInfo[] = {
   {"PUTCHR", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_PutStr( ) API Library Routine
_PutValue( ) API Library Routine
Accessing the Visual FoxPro API
API Library Routines A-Z
API Library Routines by Category


_PutStr( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_PutStr( ) API Library Routine
See Also Example

Displays a null-terminated string at the output position in the current output window in its normal attribute (color 0).

void _PutStr(char FAR *str)
char FAR *str;               /* String to display. */

Remarks

_PutStr( ) treats special characters such as newline, carriage return, and bell as control characters and doesn't display them on the screen.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _PutStr( ) to display its character type parameter in uppercase on the screen.

Visual FoxPro Code

Copy Code
SET LIBRARY TO PUTSTR
= XUPPER("upper")  && displays "UPPER" on the screen

C Code

Copy Code
#include "pro_ext.h"

void NullTerminate(Value FAR *cVal)
{
   if (!_SetHandSize(cVal->ev_handle, cVal->ev_length + 1))
   {
      _Error(182); // "Insufficient memory"
   }
   ((char FAR *) _HandToPtr(cVal->ev_handle))[cVal->ev_length] = '\0';
}

FAR Example(ParamBlk FAR *parm)
{
   char FAR *pString;
   int i;

   NullTerminate(&parm->p[0].val);
   pString = _HandToPtr(parm->p[0].val.ev_handle);
   for (i = 0; i < parm->p[0].val.ev_length; i++)
   {
      if ('a' <= *pString && *pString <= 'z')
      {
         *pString += ('A' - 'a');
      }
      pString++;
   }
   _HLock(parm->p[0].val.ev_handle);
   _PutStr(_HandToPtr(parm->p[0].val.ev_handle));
   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"XUPPER", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

_PutChr( ) API Library Routine
_PutValue( ) API Library Routine
Accessing the Visual FoxPro API
_WPutChr( ) API Library Routine
_WPutStr( ) API Library Routine
API Library Routines A-Z
API Library Routines by Category


_PutValue( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_PutValue( ) API Library Routine
See Also Example

Writes the value val at the output position in the current output window.

void _PutValue(Value FAR *val)
Value FAR *val;            /* Value to display. */

Example

The following example uses _PutValue( ) to display its Character-type parameter in uppercase on the screen.

Visual FoxPro Code

Copy Code
SET LIBRARY TO PUTVALUE
= XUPPER("upper")  && displays "UPPER" on screen

C Code

Copy Code
#include "pro_ext.h"

void NullTerminate(Value FAR *cVal)
{
   if (!_SetHandSize(cVal->ev_handle, cVal->ev_length + 1))
   {
      _Error(182); // "Insufficient memory"
   }
   ((char FAR *) _HandToPtr(cVal->ev_handle))[cVal->ev_length] = '\0';
}
FAR Example(ParamBlk FAR *parm)
{
   char FAR *pString;
   int i;

   NullTerminate(&parm->p[0].val);
   pString = _HandToPtr(parm->p[0].val.ev_handle);
   for (i = 0; i < parm->p[0].val.ev_length; i++)
   {
      if ('a' <= *pString && *pString <= 'z')
      {
         *pString += ('A' - 'a');
      }
      pString++;
   }
   _PutValue(&parm->p[0].val);
}

FoxInfo myFoxInfo[] = {
   {"XUPPER", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_PutChr( ) API Library Routine
_PutStr( ) API Library Routine
Accessing the Visual FoxPro API
_WPutChr( ) API Library Routine
_WPutStr( ) API Library Routine


_Release( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_Release( ) API Library Routine
See Also Example

Releases from memory the specified memory variable or array.

int _Release(NTI n)
NTI n;                     /* NTI number of variable or array
 to release. */

Remarks

_Release( ) returns 0 if it successfully releases the memory variable or array, or an integer whose absolute value is a Visual FoxPro error number if it fails.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example releases a memory variable whose name is given as a character argument. _NameTableIndex( ) is used to find the NTI of the variable.

Visual FoxPro Code

Copy Code
SET LIBRARY TO RELEASE
x = 123
= XRELEASE("x")

C Code

Copy Code
#include <pro_ext.h>

FAR ReleaseEx(ParamBlk FAR *parm)
{
   NTI nti;
   char FAR *name;
   int exitCode;
   Locator loc;

   // Null terminate character string, name of variable
   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   name = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   name[parm->p[0].val.ev_length] = '\0';

   if ((nti = _NameTableIndex(name)) == -1)
   {
      _HUnLock(parm->p[0].val.ev_handle);
      _UserError("Cannot find variable in name table.");
   }

   _HUnLock(parm->p[0].val.ev_handle);
   if (_FindVar(nti, -1, &loc))
   {
      _PutStr("\nVariable exists prior to _Release().");
   }
   if ((exitCode =_Release(nti)) < 0)
   {
      _Error(-exitCode);
   }
   _HLock(parm->p[0].val.ev_handle);
   name = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   name[parm->p[0].val.ev_length] = '\0';

   if ((nti = _NameTableIndex(name)) != -1)
   {
      _PutStr("\n_NameTableIndex() still finds variable \
         after it is released.");
   }
   _HUnLock(parm->p[0].val.ev_handle);

   if (!_FindVar(nti, -1, &loc))
   {
      _PutStr("\nVariable does not exist after _Release().");
   }
}

FoxInfo myFoxInfo[] = {
   {"XRELEASE", (FPFI) ReleaseEx, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_ALen( ) API Library Routine
_RetCurrency( ) API Library Routine
_RetDateTimeStr( ) API Library Routine
_FindVar( ) API Library Routine
_Load( ) API Library Routine
_NameTableIndex( ) API Library Routine
_NewVar( ) API Library Routine
_Store( ) API Library Routine


_RetChar( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_RetChar( ) API Library Routine
See Also Example

Sets the library return value to a null-terminated string.

void _RetChar(char FAR *string)
char FAR *string;            /* String. */

Remarks

If you need to return a string that might contain embedded null characters, use the _RetVal( ) function.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example makes two calls to _RetChar( ), demonstrating that control returns to the API routine from _RetChar( ) and that the last _RetChar( ) determines the value returned to Visual FoxPro.

Visual FoxPro Code

Copy Code
SET LIBRARY TO RETCHAR

C Code

Copy Code
#include <pro_ext.h>

void FAR chars(ParamBlk FAR *parm)
{
   char message[] = "Hello, world";
   _RetChar(message);
}
FoxInfo myFoxInfo[] = {
   {"CHARS", (FPFI) chars, 0, ""}
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_RetCurrency( ) API Library Routine
_RetDateStr( ) API Library Routine
_RetDateTimeStr( ) API Library Routine
_RetFloat( ) API Library Routine
_RetInt( ) API Library Routine
_RetLogical( ) API Library Routine
_RetVal( ) API Library Routine


_RetCurrency( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_RetCurrency( ) API Library Routine
See Also Example

Sets the library return value to a currency value.

void _RetCurrency(CCY money, int width)
CCY money;         /* CCY - LARGE_INTEGER. */
int width;         /* Number of columns to display. */

Remarks

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example converts a numeric type value to currency type value.

Visual FoxPro Code

Copy Code
SET LIBRARY TO RETCURR
? xntom(100.1)

C Code

Copy Code
#include <pro_ext.h>
#include <math.h>

void FAR retcurr(ParamBlk FAR *parm)
{
   CCY money;

   money.HighPart = (long) (parm->p[0].val.ev_real*10000 / pow(2,32));

   money.LowPart = (unsigned long) ((parm->p[0].val.ev_real - (double) (money.HighPart * pow(2,32)/10000.0)) *10000);

   _RetCurrency(money,25);
}

FoxInfo myFoxInfo[] = {
   {"XNTOM", (FPFI) retcurr, 1, "N"}
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_RetChar( ) API Library Routine
_RetDateStr( ) API Library Routine
_RetDateTimeStr( ) API Library Routine
_RetFloat( ) API Library Routine
_RetInt( ) API Library Routine
_RetLogical( ) API Library Routine
_RetVal( ) API Library Routine


_RetDateStr( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_RetDateStr( ) API Library Routine
See Also Example

Sets the library return value to a date.

void _RetDateStr(char FAR *string)
char FAR *string;            /* Date string. */

Remarks

Specify the date string in mm/dd/year format, in which the year may be either two or four digits.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example converts a character string into a date data type and returns it to Visual FoxPro.

Visual FoxPro Code

Copy Code
SET LIBRARY TO RETDATES
? DATES("02/16/95")  && returns date {02/16/95}

C Code

Copy Code
#include <pro_ext.h>

void FAR dates(ParamBlk FAR *parm)
{
   MHANDLE mh;
   char FAR *instring;

   if ((mh = _AllocHand(parm->p[0].val.ev_length + 1)) == 0)
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   instring = _HandToPtr(parm->p[0].val.ev_handle);
   instring[parm->p[0].val.ev_length] = '\0';
   _RetDateStr(instring);
   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"DATES", (FPFI) dates, 1, "C"}
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_RetChar( ) API Library Routine
_RetCurrency( ) API Library Routine
_RetDateTimeStr( ) API Library Routine
_RetFloat( ) API Library Routine
_RetInt( ) API Library Routine
_RetLogical( ) API Library Routine
_RetVal( ) API Library Routine


_RetDateTimeStr( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_RetDateTimeStr( ) API Library Routine
See Also Example

Sets the library return value to a datetime.

void _RetDateTimeStr(char FAR *string)
char FAR *string;            /* Datetime string. */

Remarks

Specify the datetime string in mm/dd/year hh:mm:ss format, in which the year may be either two or four digits. See CTOT( ) Function for a list of valid datetime formats for the datetime string.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example converts a date type value to datetime type value.

Visual FoxPro Code

Copy Code
SET LIBRARY TO RETDT
? xctot("2/16/95 12:07am")

C Code

Copy Code
#include <pro_ext.h>

void FAR datetime(ParamBlk FAR *parm)
{
  MHANDLE mh;
  char FAR *instring;

   if ((mh = _AllocHand(parm->p[0].val.ev_length + 1)) == 0) {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   instring = _HandToPtr(parm->p[0].val.ev_handle);
   instring[parm->p[0].val.ev_length] = '\0';
   _RetDateTimeStr(instring);
   _HUnLock(parm->p[0].val.ev_handle);
}
FoxInfo myFoxInfo[] = {
   {"XCTOT", (FPFI) datetime, 1, "C"}
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
CTOT( ) Function
_RetChar( ) API Library Routine
_RetCurrency( ) API Library Routine
_RetFloat( ) API Library Routine
_RetInt( ) API Library Routine
_RetLogical( ) API Library Routine
_RetVal( ) API Library Routine


_RetFloat( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_RetFloat( ) API Library Routine
See Also Example

Sets the library return value to a float value.

void _RetFloat(double flt, int width, int dec)
double flt;                  /* Double precision floating point
 value. */
int width;                     /* Number of columns for number
 display. */
int dec;                     /* Number of decimal places. */

Remarks

The width parameter specifies the number of columns Visual FoxPro uses when displaying the number, including a decimal point if one is needed. If you don't know the width, use 20. The dec parameter specifies the number of decimal places in the number. You must correctly set the number of decimal places to guarantee that Visual FoxPro correctly processes the number. If the number of decimal places isn't zero, the width must be at least two greater than dec.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _RetFloat( ) to return the floating point representation of a Visual FoxPro date parameter.

Visual FoxPro Code

Copy Code
SET LIBRARY TO RETFLOAT
? RETFLOAT({2/16/95})  && returns float representation of date {2/16/95}

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _RetFloat(parm->p[0].val.ev_real, 20, 4);
}

FoxInfo myFoxInfo[] = {
   {"RETFLOAT", (FPFI) Example, 1, "D"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_RetChar( ) API Library Routine
_RetCurrency( ) API Library Routine
_RetDateStr( ) API Library Routine
_RetDateTimeStr( ) API Library Routine
_RetInt( ) API Library Routine
_RetLogical( ) API Library Routine
_RetVal( ) API Library Routine


_RetInt( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_RetInt( ) API Library Routine
See Also Example

Sets the library return value to a numeric value.

void _RetInt(long ival, int width)
long ival;                     /* Long integer value. */
int width;                     /* Number of columns to display number. */

Remarks

The width parameter specifies the number of columns Visual FoxPro uses when displaying the number. If you don't know the width, use 10.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example performs some operations on the table open in the current work area. It displays the value returned by _RecCount( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO RETINT
? CTEST()

C Code

Copy Code
#include  <pro_ext.h>
#define nl _PutChr('\n')

long FAR CTest()
{
   long rc,rec;
   int workarea = -1;
   int flag = 0;
   int rn,recn;

   rc = _DBRewind(workarea);
   _PutStr("top");  nl;
   rc = _DBSkip(workarea, 5);
   _PutStr("skipped 5");  nl;

   rc = _DBAppend(workarea,flag);
   _PutStr("Appending"); nl;
   rc = _DBRewind(workarea);
   _PutStr("top");  nl;
   rn = _DBRecCount(workarea);
   _RetInt(rn, 10);
   rec = rn;
   return rn;
}

FoxInfo myFoxInfo[] = {
   {"CTEST", (FPFI) CTest,0 , ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *)0, sizeof(myFoxInfo) / sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_RetChar( ) API Library Routine
_RetCurrency( ) API Library Routine
_RetDateStr( ) API Library Routine
_RetDateTimeStr( ) API Library Routine
_RetFloat( ) API Library Routine
_RetLogical( ) API Library Routine
_RetVal( ) API Library Routine


_RetLogical( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_RetLogical( ) API Library Routine
See Also Example

Sets the library return value to a logical value.

void _RetLogical(int flag)
int flag;                     /* Flag. */

Remarks

_RetLogical( ) considers zero to be False, and any non-zero value to be True.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example is a coin flip. It returns .T. or .F. based on the library function RAND( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO RETLOGIC
? RETLOGICAL()  && returns .T. or .F. pseudo-randomly

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _RetLogical(rand() % 2);
}

FoxInfo myFoxInfo[] = {
   {"RETLOGICAL", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_RetChar( ) API Library Routine
_RetCurrency( ) API Library Routine
_RetDateStr( ) API Library Routine
_RetDateTimeStr( ) API Library Routine
_RetFloat( ) API Library Routine
_RetInt( ) API Library Routine
_RetVal( ) API Library Routine


_RetVal( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_RetVal( ) API Library Routine
See Also Example

Returns any Visual FoxPro data type, except Memo.

void _RetVal(Value FAR *val)
Value FAR *val;            /* Pointer to value structure. */

Remarks

_RetVal( ) passes a complete Visual FoxPro Value structure. You must call _RetVal( ) to return a string that contains embedded null characters.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _RetVal( ) to return its Character-type parameter converted to uppercase.

Visual FoxPro Code

Copy Code
SET LIBRARY TO RETVAL
? XUPPER("upper")  && returns "UPPER"

C Code

Copy Code
#include "pro_ext.h"

void NullTerminate(Value FAR *cVal)
{
   if (!_SetHandSize(cVal->ev_handle, cVal->ev_length + 1)) {
      _Error(182); // "Insufficient memory"
   }
   ((char FAR *) _HandToPtr(cVal->ev_handle))[cVal->ev_length] = '\0';
}

FAR Example(ParamBlk FAR *parm)
{
   char FAR *pString;
   int i;

   NullTerminate(&parm->p[0].val);
   pString = _HandToPtr(parm->p[0].val.ev_handle);
   for (i = 0; i < parm->p[0].val.ev_length; i++)
   {
      if ('a' <= *pString && *pString <= 'z')
      {
         *pString += ('A' - 'a');
      }
      pString++;
   }
   _RetVal(&parm->p[0].val);
}

FoxInfo myFoxInfo[] = {
   {"XUPPER", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_RetChar( ) API Library Routine
_RetCurrency( ) API Library Routine
_RetDateStr( ) API Library Routine
_RetDateTimeStr( ) API Library Routine
_RetFloat( ) API Library Routine
_RetInt( ) API Library Routine
_RetLogical( ) API Library Routine


_SetHandSize( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_SetHandSize( ) API Library Routine
See Also Example

Changes the amount of memory allocated to the memory block handle hand.

unsigned short _SetHandSize(MHANDLE hand, unsigned long size)
MHANDLE hand;            /* Memory block handle. */
unsigned int size;            /* New number of bytes. */

Remarks

_SetHandSize( ) returns True (an integer other than 0) if the reallocation is successful, or False (0) if the reallocation fails. The data associated with the MHANDLE is preserved. If hand is a locked MHANDLE, _SetHandSize( ) fails.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _SetHandSize( ) to change the amount of memory allocated to an MHANDLE.

Visual FoxPro Code

Copy Code
SET LIBRARY TO SETHANDS
= HANDTOPTR("Hello, world.") && displays "Hello, world" on screen

C Code

Copy Code
#include <pro_ext.h>

void NullTerminate(Value FAR *cVal)
{
   if (!_SetHandSize(cVal->ev_handle, cVal->ev_length + 1))
   {
      _Error(182); // "Insufficient memory"
   }
   ((char FAR *) _HandToPtr(cVal->ev_handle))[cVal->ev_length] = '\0';
}

FAR Example(ParamBlk FAR *parm)
{
   NullTerminate(&parm->p[0].val);

   _HLock(parm->p[0].val.ev_handle);
   _PutStr(_HandToPtr(parm->p[0].val.ev_handle));
   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"HANDTOPTR", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_AllocHand( ) API Library Routine
_FreeHand( ) API Library Routine
_GetHandSize( ) API Library Routine
_HandToPtr( ) API Library Routine
_HLock( ) API Library Routine
_HUnLock( ) API Library Routine
_MemAvail( ) API Library Routine


_SetItemCmdKey( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_SetItemCmdKey( ) API Library Routine
See Also Example

Sets both the keyboard shortcut for the specified menu item, and the displayed text for the keyboard shortcut.

void _SetItemCmdKey(MENUID menuid, ITEMID itemid, int key,
 char FAR *text)
MENUID menuid;            /* Menu identifier. */
ITEMID itemid;            /* Menu item identifier. */
int key;                     /* Shortcut key. */
char FAR *text;            /* Displayed text. */

Remarks

If you don't want to display a keyboard shortcut, pass text as a pointer to a null string. If you want the system to generate the default displayed text, pass (char FAR *)0.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example sets up a menu with three items and assigns a keyboard shortcut to each item.

Visual FoxPro Code

Copy Code
SET LIBRARY TO SETICMDK

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR onSelection(long menuId, long itemId)
{
   _PutStr("\nitemId = "); putLong(itemId);
   _DisposeMenu(menuId);
}

FAR SetItemCmdKeyEx(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");
   _SetItemCmdKey(menuId, itemId, altKey
0x178, "Alt+1");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");
   _SetItemCmdKey(menuId, itemId, altKey
0x179, "Alt+2");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");
   _SetItemCmdKey(menuId, itemId, altKey
0x17a, "Alt+3");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);
   _OnSelection(menuId, -1, onSelection);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) SetItemCmdKeyEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_GetItemCmdKey( ) API Library Routine
_GetItemId( ) API Library Routine
Accessing the Visual FoxPro API
_SetItemSubMenu( ) API Library Routine
_SetItemText( ) API Library Routine


_SetItemSubMenu( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_SetItemSubMenu( ) API Library Routine
See Also Example

Assigns a submenu to the specified menu item.

void _SetItemSubMenu(MENUID menuid, ITEMID itemid,
                        MENUID submenuid)
MENUID menuid;            /* Menu identifier. */
ITEMID itemid;            /* Menu item identifier. */
MENUID submenuid;         /* Submenu identifier. */

Remarks

You can use _SetItemSubMenu( ) to attach a menu to a menu title or to a submenu to a menu item.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example adds a menu title to the system menu. Using _SetItemSubMenu( ), it then attaches a menu with two items to this menu title.

Visual FoxPro Code

Copy Code
SET LIBRARY TO SETISUBM

C Code

Copy Code
#include <pro_ext.h>

MENUID SysMenuId;
MENUID PopupId;
ITEMID PadId;

void putLong(long n)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = 10;

   _PutValue(&val);
}

FAR onSelection(long menuId, long itemId)
{
   _PutStr("\nitemId = "); putLong(itemId);
}

void FAR StartUp()
{
      ITEMID Bar1Id;
      ITEMID Bar2Id;
      int Error;

   // Add new menu title to SYSMENU.
   SysMenuId = _MenuId(_SYSMENU);
   PadId = _GetNewItemId(SysMenuId);

   if (_NewItem(SysMenuId, PadId, _LASTITEM, "\\<Added menu title"))
   {
      _Error(623); /* "Menu item cannot be defined." */
   }

   // Define menu.
   PopupId = _GetNewMenuId();

   if (Error = _NewMenu(MPOPUP, PopupId))
   {
      _Error(-Error);
   }
   Bar1Id = _GetNewItemId(PopupId);

   // WARNING: Call _NewItem() before another _GetNewItemId().
   if (_NewItem(PopupId, Bar1Id, _LASTITEM, "\\<1st item"))
   {
      _Error(623); /* "Menu item cannot be defined." */
   }
   Bar2Id = _GetNewItemId(PopupId);

   if (_NewItem(PopupId, Bar2Id, _LASTITEM, "\\<2nd item"))
   {
      _Error(623); /* "Menu item cannot be defined." */
   }

   // Attach menu to menu title
   _SetItemSubMenu(SysMenuId, PadId, PopupId);

   // Set up selection action.
   _OnSelection(PopupId, -1, onSelection);
}

void FAR ShutDown()
{
   _DisposeItem(SysMenuId, PadId);
   _DisposeMenu(PopupId);
}

FoxInfo myFoxInfo[] = {
   {"STARTUP",    (FPFI) StartUp,   CALLONLOAD, ""},
   {"SHUTDOWN",   (FPFI) ShutDown, CALLONUNLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_GetNewMenuId( ) API Library Routine
_NewMenu( ) API Library Routine
_SetItemText( ) API Library Routine
_SetItemCmdKey( ) API Library Routine


_SetItemText( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_SetItemText( ) API Library Routine
See Also Example

Changes the displayed text for the specified menu item.

void _SetItemText(MENUID menuid, ITEMID itemid, char FAR *text)
MENUID menuid;            /* Menu identifier. */
ITEMID itemid;            /* Menu item identifier. */
char FAR *text;            /* Text. */

Remarks

The menu item can be either a menu title or a bar.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example builds a menu with three items. It then changes the item text using _SetItemText( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO SETITEXT

C Code

Copy Code
#include <pro_ext.h>

FAR SetItemTextEx(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);

   _ActivateMenu(menuId);
   _Execute("WAIT WINDOW 'Original item text'");

   _SetItemText(menuId, _GetItemId(menuId, 0),
      "This was the 1st item");
   _SetItemText(menuId, _GetItemId(menuId, 1),
      "This was the 2nd item");
   _SetItemText(menuId, _GetItemId(menuId, 2),
      "This was the 3rd item");

   _Execute("WAIT WINDOW 'New item text'");
   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) SetItemTextEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_GetItemId( ) API Library Routine
_GetItemText( ) API Library Routine
_SetItemCmdKey( ) API Library Routine
Accessing the Visual FoxPro API


_SetMenuPoint( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_SetMenuPoint( ) API Library Routine
See Also Example

Specifies the screen position of the upper-left corner, loc, of a menu.

void _SetMenuPoint(MENUID menuid, Point loc)
MENUID menuid;            /* Menu identifier. */
Point loc;                  /* Position of upper-left corner
 of the menu. */

Remarks

Normally, a menu is automatically positioned based upon its size and how the user invoked it. This routine is provided to override automatic positioning.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

A menu is created and then activated at three different screen positions specified by _SetMenuPoint( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO SETMNPNT

C Code

Copy Code
#include <pro_ext.h>

FAR SetMenuPointEx(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 10; loc.h = 20;
   _SetMenuPoint(menuId, loc);
   _MenuInteract(&menuId, &itemId);

   loc.v = 15; loc.h = 30;
   _SetMenuPoint(menuId, loc);
   _MenuInteract(&menuId, &itemId);

   loc.v = 20; loc.h = 40;
   _SetMenuPoint(menuId, loc);
   _MenuInteract(&menuId, &itemId);

   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) SetMenuPointEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_NewMenu( ) API Library Routine
Accessing the Visual FoxPro API
_SetItemCmdKey( ) API Library Routine
_SetMenuPointP( ) API Library Routine


_SetMenuPointP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_SetMenuPointP( ) API Library Routine
See Also Example

Specifies in pixels the screen position of the upper-left corner, loc, of a menu.

void _SetMenuPointP(MENUID menuid, Point loc)
MENUID menuid;            /* Menu identifier. */
Point loc;                  /* Position of upper left corner
 of the menu. */

Remarks

Normally, a menu is automatically positioned based upon its size and how the user invoked it. This routine is provided to override automatic positioning.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a menu and then activates it at three different screen positions specified by _SetMenuPointP( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO SETMNPTP

C Code

Copy Code
#include <pro_ext.h>

FAR SetMenuPointPEx(ParamBlk FAR *parm)
{
   MENUID menuId;
   ITEMID itemId;
   Point loc;

   menuId = _GetNewMenuId();
   _NewMenu(MPOPUP, menuId);

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<1st item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<2nd item");

   itemId = _GetNewItemId(menuId);
   _NewItem(menuId, itemId, -2, "\\<3rd item");

   loc.v = 40; loc.h = 80;
   _SetMenuPointP(menuId, loc);
   _MenuInteract(&menuId, &itemId);

   loc.v = 80; loc.h = 160;
   _SetMenuPointP(menuId, loc);
   _MenuInteract(&menuId, &itemId);

   loc.v = 160; loc.h = 320;
   _SetMenuPointP(menuId, loc);
   _MenuInteract(&menuId, &itemId);

   _DisposeMenu(menuId);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", SetMenuPointPEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_NewMenu( ) API Library Routine
Accessing the Visual FoxPro API
_SetMenuPoint( ) API Library Routine
_GetNewItemId( ) API Library Routine


_SetObjectProperty( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_SetObjectProperty( ) API Library Routine
See Also

Sets a property for an object.

int _SetObjectProperty(Value FAR *objct, char FAR *prop, Value FAR *val,
   int fAdd)

Remarks

The first parameter *objct is an object reference; the second parameter *prop is the name of the property to set; the third parameter *val is the new property value.

The last parameter fAdd is either 0 or a non-zero value that specifies if the property is added to the object if the property does not exist. If fAdd is a non-zero value and property you specify does not exist for the object, the property is added to the object as a user-defined property, and contains the property value you specify with *val. If fAdd is 0 and the property you specify does not exist for the object, the property isn't added to the object.

_SetObjectProperty( ) returns 0 if it is successful; otherwise, the negative value of the corresponding Visual FoxPro error code is returned.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

See Also

Other Resources

API Library Construction
_GetObjectProperty( ) API Library Routine
Accessing the Visual FoxPro API
Object Property
ReadObject Property


_Store( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_Store( ) API Library Routine
See Also Example

Replaces the memory variable specified by loc with the value val.

int _Store(Locator FAR *loc, Value FAR *val)
Locator FAR *loc;            /* Memory variable locator. */
Value FAR *val;               /* Value to store. */

Remarks

Reference individual array elements by setting l_subs to the number of subscripts you specified and l_sub1 and l_sub2 to the actual subscripts. The first element of an array is numbered 1. If loc specifies an array and l_subs is 0, _Store( ) stores the value in val to all elements in the array.

_Store( ) returns 0 if it is successful. If it fails, _Store( ) returns a negative integer whose absolute value is a Visual FoxPro error number. If _Store( ) runs out of memory while storing to an array, some values of some array elements may have been set, and others may not have been.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example converts to uppercase a string argument passed by reference.

Visual FoxPro Code

Copy Code
SET LIBRARY TO STORE
x = "abc"
= XUPPER(@x)
? x

C Code

Copy Code
#include <pro_ext.h>

void FAR Upper(ParamBlk FAR *parm)
{
      char FAR *pString;
      Value val;
      int i;
//
//   _Load() and _Store are the functions of interest for pass-by-reference.
//
   _Load(&parm->p[0].loc, &val);
//
//   FoxPro doesn't check the type of pass-by-reference arguments, so we do.
//
   if (val.ev_type != 'C') {
      _Error(9); // "Data type mismatch"
   }
  pString = _HandToPtr(val.ev_handle);

   for (i = 0; i < val.ev_length; i++)  {
      if ('a' <= *pString && *pString <= 'z') {
         *pString += ('A' - 'a');
      }
      pString++;
   }
   _Store(&parm->p[0].loc, &val);
   //
   // We need to free the handle that we created with  _LOAD()
   //
   _FreeHand(val.ev_handle);

}
FoxInfo myFoxInfo[] = {
   {"XUPPER", (FPFI) Upper, 1, "R"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_ALen( ) API Library Routine
_FindVar( ) API Library Routine
_Load( ) API Library Routine
_NameTableIndex( ) API Library Routine
_NewVar( ) API Library Routine
_ObjectRelease( ) API Library Routine


_StrCmp( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_StrCmp( ) API Library Routine
See Also Example

Compares each byte in two null-terminated strings, starting with the leftmost byte.

int _StrCmp(char FAR *string1, char FAR *string2)
char FAR *string1;         /* First comparison string. */
char FAR *string2;         /* Second comparison string. */

Remarks

_StrCmp( ) returns 0 if string1 and string2 match, a positive number if the first unmatched byte in string1 is greater than the corresponding byte in string2, or a negative number if the first unmatched byte in string1 is less than the corresponding byte in string2.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _StrCmp( ) to compare two strings passed as parameters.

Visual FoxPro Code

Copy Code
SET LIBRARY TO STRCMP
? STRCMP("Hello, world.", "Hello, world.")  && matches; returns 0
? STRCMP("Hello, world.", "Hello, wurld.")  && no match; returns non-0

C Code

Copy Code
#include <pro_ext.h>

void NullTerminate(Value FAR *cVal)
{
   if (!_SetHandSize(cVal->ev_handle, cVal->ev_length + 1))
   {
      _Error(182); // "Insufficient memory"
   }
   ((char FAR *) _HandToPtr(cVal->ev_handle))[cVal->ev_length] = '\0';
}

FAR Example(ParamBlk FAR *parm)
{
   int RetValue;

   NullTerminate(&parm->p[0].val);
   NullTerminate(&parm->p[1].val);

   _HLock(parm->p[0].val.ev_handle);
   _HLock(parm->p[1].val.ev_handle);

   RetValue = _StrCmp(_HandToPtr(parm->p[0].val.ev_handle),
      _HandToPtr(parm->p[1].val.ev_handle));

   _RetInt(RetValue, 10); // does return control here

   _HUnLock(parm->p[0].val.ev_handle);
   _HUnLock(parm->p[1].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"STRCMP", (FPFI) Example, 2, "C,C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_StrCpy( ) API Library Routine
_StrLen( ) API Library Routine
_PutStr( ) API Library Routine
_WPutStr( ) API Library Routine
_SetHandSize( ) API Library Routine
String Manipulation Routines


_StrCpy( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_StrCpy( ) API Library Routine
See Also Example

Copies a null-terminated string from src to dest.

void _StrCpy(char FAR *dest, char FAR *src)
char FAR *dest;            /* Destination location. */
char FAR *src;               /* Source location. */

Remarks

_StrCpy( ) doesn't support overlapping moves. Overlapping moves are required when src and dest have some bytes in common. If overlapping moves are required, use _MemMove( ).

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example is passed a Visual FoxPro array of type Character. It then replaces the second element using _Store( ).

Before calling MYFUNC( ), the Visual FoxPro example code creates an array and initializes it to type Character. MYFUNC( ) passes this array by reference.

Visual FoxPro Code

Copy Code
SET LIBRARY TO STRCPY
? STRCPY("Hello", " world")   && returns "Hello world"

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
#define p0 (parm->p[0].val)
#define p1 (parm->p[1].val)

   if (!_SetHandSize(p0.ev_handle, p0.ev_length + p1.ev_length))
      _Error(182); // "Insufficient memory"
   _HLock(p0.ev_handle);
   _HLock(p1.ev_handle);
   ((char FAR *) _HandToPtr(p1.ev_handle))[p1.ev_length] = '\0';

   _StrCpy((char FAR *) _HandToPtr(p0.ev_handle) + p0.ev_length,
      _HandToPtr(p1.ev_handle));

   _RetChar(_HandToPtr(p0.ev_handle));
   _HUnLock(p0.ev_handle);
   _HUnLock(p1.ev_handle);
}
FoxInfo myFoxInfo[] = {
   {"STRCPY", (FPFI) Example, 2, "C,C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_StrCmp( ) API Library Routine
_StrLen( ) API Library Routine
String Manipulation Routines
_PutStr( ) API Library Routine
_WPutStr( ) API Library Routine


_StrLen( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_StrLen( ) API Library Routine
See Also Example

Returns the length in bytes of the specified null-terminated string.

int _StrLen(char FAR *string)
char FAR *string;            /* String to be measured. */

Example

The following example is similar to the Visual FoxPro function LEN( ), but can't handle strings with embedded '\0'.

Visual FoxPro Code

Copy Code
SET LIBRARY TO STRLEN
? STRLEN("Hello") && returns 5

C Code

Copy Code
#include <pro_ext.h>

void NullTerminate(Value FAR *cVal)
{
   if (!_SetHandSize(cVal->ev_handle, cVal->ev_length + 1)) {
      _Error(182); // "Insufficient memory"
   }
   ((char FAR *) _HandToPtr(cVal->ev_handle))[cVal->ev_length] = '\0';
}

FAR Example(ParamBlk FAR *parm)
{
   NullTerminate(&parm->p[0].val);
   _HLock(parm->p[0].val.ev_handle);
   _RetInt(_StrLen(_HandToPtr(parm->p[0].val.ev_handle)), 10);
   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"STRLEN", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_StrCmp( ) API Library Routine
_StrCpy( ) API Library Routine
LEN( ) Function
String Manipulation Routines


_UserError( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_UserError( ) API Library Routine
See Also Example

Reports an error with the null-terminated text you specify in message.

void _UserError(char FAR *message)
char FAR *message;         /* Error message. */

Remarks

The Visual FoxPro internal code for this error is 98. The code returned by the Visual FoxPro ERROR( ) function is 1098. The Visual FoxPro MESSAGE( ) function returns to the user your specified message. Control is passed to the Visual FoxPro error handler and doesn't return.

Note:
Do not call _UserError() in a CALLUNLOAD routine: the library will not load, due to the _UserError() call, and no message will be displayed.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example calls _UserError( ), demonstrating that execution doesn't return to the API routine after _UserError( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO EXAMPLE
= EXAMPLE()

C Code

Copy Code
#include <pro_ext.h>

FAR UserErrorEx(ParamBlk FAR *parm)
{
   _UserError("This is a _UserError() example.");
   _PutStr("This should never be displayed.");
}

FoxInfo myFoxInfo[] = {
   {"EXAMPLE", (FPFI) UserErrorEx, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_Error( ) API Library Routine
_ErrorInfo( ) API Library Routine
ERROR( ) Function
MESSAGE( ) Function
Accessing the Visual FoxPro API


_WAttr( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WAttr( ) API Library Routine
See Also Example

Returns the attribute byte for the specified color index in the specified window's color scheme.

int _WAttr(WHANDLE wh, int color)
WHANDLE wh;            /* Window handle. */
int color;                     /* Color index. */

Example

The following example goes through each color of each color scheme, showing its attribute byte as returned by _WAttr( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO WATTR

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR WAttrEx(ParamBlk FAR *parm)
{
   int scheme;
   int color;
   WHANDLE wh;
   int attrib, savePen;

   for (scheme = 0; scheme <= 25; scheme++)
   {
      wh = _WOpen(2, 10, 23, 70, WEVENT, scheme, (Scheme FAR *) 0,
         WO_SYSTEMBORDER);

      for (color = WA_NORMAL; color <= WA_ISSHADOW; color++)
      {
         attrib  = _WAttr(wh, color);
         savePen = _WAttr(_WGetPort(), WA_PENCOLOR);

         _WSetAttr(_WGetPort(), WA_PENCOLOR, attrib);

         _PutStr("\nScheme:"); putLong(scheme, 5);
         _PutStr("; Color:"); putLong(color, 5);
         _PutStr("; Attribute byte:"); putLong(attrib, 5);

         _WSetAttr(_WGetPort(), WA_PENCOLOR, savePen);
      }
      _WClose(wh);
      _Execute("WAIT");
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) WAttrEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WSetAttr( ) API Library Routine
Change Font Attributes Sample
Accessing the Visual FoxPro API


_WBottom( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WBottom( ) API Library Routine
See Also Example

Returns the row on the screen where the bottom of the specified window is located.

unsigned int _WBottom(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Example

The following example displays the position of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WBOTTOM
= WPOSITION()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\ntop   ="); putLong(_WTop(wh), 5);
   _PutStr("\nleft ="); putLong(_WLeft(wh), 5);
   _PutStr("\nbottom ="); putLong(_WBottom(wh), 5);
   _PutStr("\nright  ="); putLong(_WRight(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WPOSITION", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WHeight( ) API Library Routine
_WLeft( ) API Library Routine
_WRight( ) API Library Routine
_WTop( ) API Library Routine
_WWidth( ) API Library Routine
_WBottomP( ) API Library Routine


_WBottomP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WBottomP( ) API Library Routine
See Also Example

Returns the position on the screen in pixels where the bottom of the specified window is located.

unsigned int _WBottomP(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays the position of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WBOTTOM
=WPOSITION()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\ntop   ="); putLong(_WTopP(wh), 5);
   _PutStr("\nleft ="); putLong(_WLeftP(wh), 5);
   _PutStr("\nbottom ="); putLong(_WBottomP(wh), 5);
   _PutStr("\nright  ="); putLong(_WRightP(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WPOSITION", Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WHeightP( ) API Library Routine
_WLeftP( ) API Library Routine
_WRightP( ) API Library Routine
_WTopP( ) API Library Routine
_WWidthP( ) API Library Routine
_WBottom( ) API Library Routine


_WClear( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WClear( ) API Library Routine
See Also Example

Erases the contents of the specified window by changing the content area to the default background color.

void _WClear(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

The logical cursor position is unchanged.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a window and fills it with Xs. When the user presses a key in response to a Visual FoxPro WAIT command, _WClear( ) clears the window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WCLEAR

C Code

Copy Code
#include <pro_ext.h>

FAR WClearEx(ParamBlk FAR *parm)
{
   WHANDLE wh;
   int row, col;

   wh = _WOpen(2,2,20,70,WEVENT | CLOSE,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   for (row = 0; row < _WHeight(wh); row++)
   {
      for (col = 0; col < _WWidth(wh); col++)
      {
         _WPutChr(wh, 'X');
      }
      _WPutChr(wh, '\n');
   }
   _Execute("WAIT WINDOW 'Press any key to clear window'");
   _WClear(wh);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) WClearEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WClearRect( ) API Library Routine
_WClearRectP( ) API Library Routine
Accessing the Visual FoxPro API
WAIT Command


_WClearRect( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WClearRect( ) API Library Routine
See Also Example

Erases the specified rectangular area of the specified window by changing the area to the default background color.

void _WClearRect(WHANDLE wh, Rect r)
WHANDLE wh;            /* Window handle. */
Rect r;                     /* Rectangle to clear. */

Remarks

The output position is unchanged.

The area of the rectangle extends from the top left coordinate to, but not including, the bottom right coordinate. This means that you should declare the bottom and right coordinates to be one more than the intended size of the rectangle.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a window and fills it with Xs. After the user presses a key in response to a Visual FoxPro WAIT command, _WClearRect( ) clears a rectangular region of the window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WCLRECT

C Code

Copy Code
#include <pro_ext.h>

FAR WClearEx(ParamBlk FAR *parm)
{
   WHANDLE wh;
   int row, col;
   Rect r;

   wh = _WOpen(2,2,20,70,WEVENT | CLOSE,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   for (row = 0; row < _WHeight(wh); row++)
   {
      for (col = 0; col < _WWidth(wh); col++)
      {
         _WPutChr(wh, 'X');
      }
   }
   _Execute("WAIT WINDOW 'Press any key to clear window rectangle'");

   r.top    = 2;W
   r.left    = 2;
   r.bottom = 15;
   r.right  = 65;

   _WClearRect(wh, r);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) WClearEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WClear( ) API Library Routine
WAIT Command
_WClearRectP( ) API Library Routine
Accessing the Visual FoxPro API


_WClearRectP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WClearRectP( ) API Library Routine
See Also Example

Erases the specified rectangular area of a window by changing it to the default background color.

void _WClearRectP(WHANDLE wh, Rect r)
WHANDLE wh;            /* Window handle. */
Rect r;                     /* Rectangle to clear. */

Remarks

The rectangular area is specified in pixels. The output position is unchanged.

The area of the rectangle extends from the top left position to, but not including, the bottom right position. This means that you should declare the bottom and right positions to be one pixel more than the intended size of the rectangle.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a window and fills it with Xs. After the user presses a key in response to the Visual FoxPro WAIT command, _WClearRectP( ) clears a rectangular region of the window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WCLRECTP

C Code

Copy Code
#include <pro_ext.h>

FAR WClearEx(ParamBlk FAR *parm)
{
   WHANDLE wh;
   int row, col;
   Rect r;

   wh = _WOpen(2, 2, 20, 70, CLOSE, WINDOW_SCHEME, (Scheme FAR *) 0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   for (row = 0; row < _WHeight(wh); row++)
   {
      for (col = 0; col < _WWidth(wh); col++)
      {
         _WPutChr(wh, 'X');
      }
   }
   _Execute("WAIT WINDOW 'Press any key to clear window rectangle'");

   r.top    = 20;
   r.left    = 20;
   r.bottom = 100;
   r.right  = 300;

   _WClearRectP(wh, r);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", WClearEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WClear( ) API Library Routine
WAIT Command
_WClearRect( ) API Library Routine
Accessing the Visual FoxPro API


_WClose( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WClose( ) API Library Routine
See Also Example

Closes the specified window and releases all memory associated with the window.

void _WClose(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

If the window is displayed on the screen, _WClose( ) removes it from the screen.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates and displays a window. After the user presses a key in response to a Visual FoxPro WAIT command, _WClose( ) closes the window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WCLOSE

C Code

Copy Code
#include <pro_ext.h>

FAR Ex(ParamBlk FAR *parm)
{
   WHANDLE wh;
   int row, col;
   Rect r;

   wh = _WOpen(2, 2, 20, 70, 0, WINDOW_SCHEME, (Scheme FAR *) 0,
      WO_SYSTEMBORDER);
   _WShow(wh);
   _Execute("WAIT WINDOW 'Press any key to close window'");
   _WClose(wh);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Ex, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WOpen( ) API Library Routine
WAIT Command
Accessing the Visual FoxPro API


_WFindTitle( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WFindTitle( ) API Library Routine
See Also Example

Returns the WHANDLE of the window with the specified title.

WHANDLE _WFindTitle(TEXT *title)
TEXT *title;               /* Window title. */

Example

The following example hides the window whose title is passed as an argument.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WFINDTIT
CREATE TABLE X (X C(10))
BROWSE NOWAIT
SET LIBR TO WFINDTIT
= WHIDE("X")

C Code

Copy Code
#include <pro_ext.h>

void FAR WFindTitleEx(ParamBlk FAR *parm)
{
//   For readability:
#define pTITLE ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   pTITLE[parm->p[0].val.ev_length] = '\0';
   wh = _WFindTitle(pTITLE);
   _HUnLock(parm->p[0].val.ev_handle);
   _WHide(wh);
}

FoxInfo myFoxInfo[] = {
   {"WHIDE", (FPFI) WFindTitleEx, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WSetTitle( ) API Library Routine
_HUnLock( ) API Library Routine
_WHide( ) API Library Routine
_WTitle( ) API Library Routine


_WGetCursor( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WGetCursor( ) API Library Routine
See Also Example

Returns the current output position in the specified window.

Point _WGetCursor(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Example

The following example creates a window and draws a diagonal pattern of Xs in this window. It positions the cursor before writing each X using _WPosCursor( ), and gets that same position using _WGetCursor( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO WGETCURS

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point putPos, getPos;

   wh = _WOpen(4,4,20,70,0,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   for (putPos.v = 2; putPos.v < 14; putPos.v++)
   {
      putPos.h = putPos.v;

      _WPosCursor(wh, putPos);
      getPos = _WGetCursor(wh);
      _WPutChr(wh, 'X');

      _PutStr("\nCursor position:");
      putLong(getPos.v, 5);
      putLong(getPos.h, 5);

      _Execute("WAIT WINDOW");
   }
   _WClose(wh);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WPosCursor( ) API Library Routine
Accessing the Visual FoxPro API
_WGetCursorP( ) API Library Routine


_WGetCursorP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WGetCursorP( ) API Library Routine
See Also Example

Returns in pixels the current output position in the specified window.

Point _WGetCursorP(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a window and draws a diagonal pattern of Xs in this window. It positions the cursor before writing each X using _WPosCursorP( ), and gets that same position using _WGetCursorP( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO WGETCURP

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point putPos, getPos;

   wh = _WOpen(4,4,20,70,0,WINDOW_SCHEME,(Scheme FAR *)0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   for (putPos.v = 10; putPos.v < 100; putPos.v += 10)
   {
      putPos.h = putPos.v;

      _WPosCursorP(wh, putPos);
      _WPutChr(wh, 'X');

      getPos = _WGetCursorP(wh);

      _PutStr("\nCursor position:");
      putLong(getPos.v, 5);
      putLong(getPos.h, 5);

      _Execute("WAIT");
   }
   _WClose(wh);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WPosCursor( ) API Library Routine
Accessing the Visual FoxPro API
SET CURSOR Command
_WGetCursor( ) API Library Routine
_WPosCursorP( ) API Library Routine


_WGetObjectClientWindow( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WGetObjectClientWindow( ) API Library Routine
See Also

Returns the handle of the client window in which the specified object is contained.

WHANDLE _WGetObjectClientWindow(Value FAR *objct)

Remarks

Use the _WhToHwnd( ) API Library Routine function to convert the WHANDLE to a Windows HWND.

See Also

Other Resources

API Library Construction
_WGetObjectWindow( ) API Library Routine
Accessing the Visual FoxPro API
_WGetPort( ) API Library Routine
_GetObjectProperty( ) API Library Routine
GETOBJECT( ) Function


_WGetObjectWindow( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WGetObjectWindow( ) API Library Routine
See Also

Returns the handle of the frame window in which the specified object is contained.

WHANDLE _WGetObjectWindow(Value FAR *objct)

Remarks

Use the _WhToHwnd( ) API Library Routine function to convert the WHANDLE to a Windows HWND.

See Also

Other Resources

API Library Construction
_WGetObjectClientWindow( ) API Library Routine
Accessing the Visual FoxPro API
_WGetPort( ) API Library Routine
_GetObjectProperty( ) API Library Routine
GETOBJECT( ) Function


_WGetPort( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WGetPort( ) API Library Routine
See Also Example

Returns the WHANDLE of the window that is currently selected for user output.

WHANDLE _WGetPort(void any)
void any;                     /* Pointer. */

Example

The following example displays the window handle returned by _WGetPort( ) as the current output port is changed.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WGETPORT

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{

   WHANDLE wh;
   WHANDLE oldPort;

   wh = _WOpen(2,10,23,70,WEVENT | CLOSE,WINDOW_SCHEME,(Scheme FAR *)0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   _PutStr("\n1) _WGetPort() ="); putLong(_WGetPort(), 10);

   oldPort = _WSetPort(wh);
   _PutStr("\n2) _WSetPort(wh) ="); putLong(oldPort, 10);
   _PutStr("\n3) _WGetPort() ="); putLong(_WGetPort(), 10);

   oldPort = _WSetPort(oldPort);
   _PutStr("\n4) _WSetPort(oldPort) =");  putLong(oldPort, 10);

   _PutStr("\nShould be back where we started.");
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WhToHwnd( ) API Library Routine
_WGetObjectClientWindow( ) API Library Routine
_GetObjectProperty( ) API Library Routine
GETOBJECT( ) Function


_WHeight( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WHeight( ) API Library Routine
See Also Example

Returns the number of rows in the content area of the specified window.

unsigned int _WHeight(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Example

The following example shows the height and width in rows and columns of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WHEIGHT
=WDIMEN()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\nheight ="); putLong(_WHeight(wh), 5);
   _PutStr("\nwidth  ="); putLong(_WWidth(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WDIMEN", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottom( ) API Library Routine
_WLeft( ) API Library Routine
_WRight( ) API Library Routine
_WTop( ) API Library Routine
_WWidth( ) API Library Routine


_WHeightP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WHeightP( ) API Library Routine
See Also Example

Returns the height in pixels of the content area of the specified window.

unsigned int _WHeightP(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays the height and width in pixels of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WHEIGHTP
=WDIMEN()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\nheight ="); putLong(_WHeightP(wh), 5);
   _PutStr("\nwidth  ="); putLong(_WWidthP(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WDIMEN", Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottomP( ) API Library Routine
_WLeftP( ) API Library Routine
_WRightP( ) API Library Routine
_WTopP( ) API Library Routine
_WWidthP( ) API Library Routine


_WHide( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WHide( ) API Library Routine
See Also Example

Removes a window from the screen, but keeps track of its contents so you can display it again.

void _WHide(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Example

The following example hides the window whose title is passed as an argument.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WHIDE
CREATE TABLE X (X C(10))
BROWSE NOWAIT
WAIT WINDOW "Press A Key To Hide Window"
SET LIBR TO WFINDTIT
= WHIDE("X")
WAIT WINDOW "Window Is Hidden"

C Code

Copy Code
#include <pro_ext.h>

void FAR Example(ParamBlk FAR *parm)
{
//   For readability---
#define pTITLE ((char FAR *) _HandToPtr(parm->p[0].val.ev_handle))

   WHANDLE wh;

   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+ 1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   pTITLE[parm->p[0].val.ev_length] = '\0';
   wh = _WFindTitle(pTITLE);
   _HUnLock(parm->p[0].val.ev_handle);
   _WHide(wh);
}
FoxInfo myFoxInfo[] = {
   {"WHIDE", (FPFI) Example, 1, "C"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WShow( ) API Library Routine
HIDE WINDOW Command
SHOW WINDOW Command


_WhToHwnd( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WhToHwnd( ) API Library Routine
See Also Example

Returns the Windows HWND of the specified WHANDLE.

HWND_WhToHwnd(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a window and then obtains the Windows HWND for the window with the callback _WhToHwnd( ). Then, to verify the value returned by _WhToHwnd( ), the example uses the HWND as an argument to a Windows function.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WHTOHWND

C Code

Copy Code
#include <windows.h>
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR WhToHwndEx(ParamBlk FAR *parm)
{
   RECT Rect;
   HWND hwnd;
   WHANDLE wh;
   Value val;

   wh = _WOpenP(10,10,120,240,CLOSE,WINDOW_SCHEME, (Scheme FAR *) 0,
      WO_SYSTEMBORDER);
   _WShow(wh);

//   Get Windows window handle and use as a parameter
//   to a Windows function
   hwnd = _WhToHwnd(wh);
   GetWindowRect(hwnd, &Rect); // Windows function

   _PutStr("\ntop   ="); putLong(Rect.top, 5);
   _PutStr("\nleft ="); putLong(Rect.left, 5);
   _PutStr("\nbottom ="); putLong(Rect.bottom, 5);
   _PutStr("\nright  ="); putLong(Rect.right, 5);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", WhToHwndEx, CALLONLOAD,  ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WFindTitle( ) API Library Routine
_WOpen( ) API Library Routine
Accessing the Visual FoxPro API


_WLeft( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WLeft( ) API Library Routine
See Also Example

Returns the column on the screen where the left edge of the specified window is located.

unsigned int _WLeft(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Example

The following example shows the position of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WLEFT
=WPOSITION()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\ntop   ="); putLong(_WTop(wh), 5);
   _PutStr("\nleft ="); putLong(_WLeft(wh), 5);
   _PutStr("\nbottom ="); putLong(_WBottom(wh), 5);
   _PutStr("\nright  ="); putLong(_WRight(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WPOSITION", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottom( ) API Library Routine
_WHeight( ) API Library Routine
_WRight( ) API Library Routine
_WTop( ) API Library Routine
_WWidth( ) API Library Routine


_WLeftP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WLeftP( ) API Library Routine
See Also Example

Returns the position on the screen in pixels where the left edge of the window is located.

unsigned int _WLeftP(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example shows the position in pixels of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WLEFTP
=WPOSITION()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\ntop   ="); putLong(_WTopP(wh), 5);
   _PutStr("\nleft ="); putLong(_WLeftP(wh), 5);
   _PutStr("\nbottom ="); putLong(_WBottomP(wh), 5);
   _PutStr("\nright  ="); putLong(_WRightP(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WPOSITION", Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottomP( ) API Library Routine
_WHeightP( ) API Library Routine
_WRightP( ) API Library Routine
_WTopP( ) API Library Routine
_WWidthP( ) API Library Routine


_WMainWindow( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WMainWindow( ) API Library Routine
See Also Example

Returns the WHANDLE of the main Visual FoxPro window.

WHANDLE _WMainWindow(void any)
void any;                     /* Pointer. */

Remarks

Use the _WhToHwnd( ) API Library Routine function to convert the WHANDLE to a Windows HWND.

Example

The following example writes a message to the main Visual FoxPro window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WMAIN
= EXWMAIN()

C Code

Copy Code
#include <pro_ext.h>

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WMainWindow();
   _WPutStr(wh, "\nThis is the FoxPro main window or desktop.");
}

FoxInfo myFoxInfo[] = {
   {"EXWMAIN", Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WhToHwnd( ) API Library Routine
How to: Hide the Main Visual FoxPro Window


_WMove( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WMove( ) API Library Routine
See Also Example

Moves the specified window to the new location specified by pt.

void _WMove(WHANDLE wh, Point pt)
WHANDLE wh;            /* Window handle. */
Point pt;                     /* New location. */

Remarks

The pt parameter specifies the position of the upper-left corner of the window in rows and columns. The new position can place the window partially or completely off the screen.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example moves the active window diagonally 10 rows down and 10 columns to the right.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WMOVE
=WMOVE()

C Code

Copy Code
#include <pro_ext.h>

void FAR WMoveEx(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();
   Point newPos;

   newPos.v = _WTop(wh)  + 10;
   newPos.h = _WLeft(wh) + 10;

   _WMove(wh, newPos);
}

FoxInfo myFoxInfo[] = {
   {"WMOVE", (FPFI) WMoveEx, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WSize( ) API Library Routine
_WMoveP( ) API Library Routine
_MemMove( ) API Library Routine
MOVE WINDOW Command
Accessing the Visual FoxPro API


_WMoveP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WMoveP( ) API Library Routine
See Also Example

Moves the specified window to a new location specified by pt.

void _WMoveP(WHANDLE wh, Point pt)
WHANDLE wh;            /* Window handle. */
Point pt;                     /* New location. */

Remarks

The pt parameter specifies the location of the upper-left corner of the window in pixels. The new position can place the window partially or completely off the screen.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example moves the active window diagonally 40 pixels down and 40 pixels to the right.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WMOVEP
=WMOVEP()

C Code

Copy Code
#include <pro_ext.h>

void FAR WMovePEx(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();
   Point newPos;

   newPos.v = _WTopP(wh)  + 40;
   newPos.h = _WLeftP(wh) + 40;

   _WMoveP(wh, newPos);
}

FoxInfo myFoxInfo[] = {
   {"WMOVEP", WMovePEx, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WSizeP( ) API Library Routine
_MemMove( ) API Library Routine
MOVE WINDOW Command
Accessing the Visual FoxPro API


_WOnTop( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WOnTop( ) API Library Routine
See Also Example

Returns the WHANDLE of the active window.

WHANDLE _WOnTop(void any)
void any;                     /* Pointer. */

Remarks

Normally, keystrokes belong to the active window. Handler routines need to act appropriately.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays position information about the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WONTOP
=WPOSITION()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}
void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\ntop   ="); putLong(_WTop(wh), 5);
   _PutStr("\nleft ="); putLong(_WLeft(wh), 5);
   _PutStr("\nbottom ="); putLong(_WBottom(wh), 5);
   _PutStr("\nright  ="); putLong(_WRight(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WPOSITION", Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WSendBehind( ) API Library Routine
_WShow( ) API Library Routine
_WTop( ) API Library Routine
Accessing the Visual FoxPro API


_WOpen( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WOpen( ) API Library Routine
See Also Example

Creates a new window at the coordinates specified by the top, left, bottom, and right parameters.

WHANDLE _WOpen(int top, int left, int bottom, int right, int flag,
         int scheme_num, Scheme FAR *scheme, char FAR *bord)
int top;                     /* Row of top coordinate. */
int left;                     /* Column of left coordinate. */
int bottom;                  /* Row of bottom coordinate.  */
int right;                     /* Column of right coordinate. */
int flag;                     /* Attributes. */
int scheme_num;            /* Color scheme. */
Scheme FAR *scheme;      /* Points to color scheme to use. */
char FAR *bord;            /* Border type. */

Remarks

The window coordinates may be off the screen, but the height can't exceed 120 and the width can't exceed 264. Additional memory is allocated to hold the off-screen image of this window.

The flag parameter determines the attributes for this window. The flag may be one or more of the following flag values. You can combine multiple flag values using the C-language | or + operator. Typical window borders are defined in PRO_EXT.H.

flag Value | Window attribute
WCURSOR | The insertion point may be displayed in this window.
ZOOM | The user may zoom the window.
ADJ | The user may adjust the size of the window.
CLOSE | The user may close the window.
MOVE | The user may move the window.
AUTOSCROLL | The window scrolls when output rolls off the bottom line.
WEVENT | The window receives, activates, and deactivates events.
SHADOW | The window casts a shadow.
WMODAL | The user can't send this window to the back.
WMINIMIZE | The user can minimize this window.

The scheme_num may be any valid color scheme number, or – 1 to indicate that the scheme parameter points to the color scheme to use.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates windows using a number of different color schemes and borders. In particular, note the custom color scheme.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WOPEN

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh;

   Scheme customScheme =
   {
      (char) (BLACK_ON      | WHITE),
      (char) (RED_ON      | BLACK      | BLINK),
      (char) (WHITE_ON      | WHITE      | BRIGHT),
      (char) (CYAN_ON      | BLUE      | BRIGHT),
      (char) (GREEN_ON      | BROWN),
      (char) (BROWN_ON      | BROWN      | BRIGHT),
      (char) (MAGENTA_ON   | MAGENTA   | BRIGHT),
      (char) (RED_ON      | MAGENTA   | BRIGHT | BLINK),
      (char) (BROWN_ON      | GREEN      | BRIGHT),
      (char) (BLACK_ON      | CYAN),
      (char) (BLUE_ON      | CYAN),
   };

   _Execute("WAIT WINDOW 'Press any key to see a window \
      in WINDOW_SCHEME with WO_DOUBLEBOX border'");

   wh = _WOpen(2,2,20,70,WEVENT | CLOSE,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_DOUBLEBOX);
   _WShow(wh);

   _Execute("WAIT WINDOW 'Press any key to see a window \
      in ALERT_SCHEME with WO_SINGLEBOX border'");
   _WClose(wh);

   wh = _WOpen(2,2,20,70,WEVENT | CLOSE,ALERT_SCHEME, (Scheme FAR *) 0,
      WO_SINGLEBOX);
   _WShow(wh);

   _Execute("WAIT WINDOW 'Press any key to see a window \
      in WINDOW_SCHEME with WO_PANELBORDER border'");
   _WClose(wh);

   wh = _WOpen(2,2,20,70,WEVENT | CLOSE,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_PANELBORDER);
   _WShow(wh);

   _Execute("WAIT WINDOW 'Press any key to see a window \
      in a custom scheme with WO_SYSTEMBORDER border'");
   _WClose(wh);

   wh = _WOpen(2,2,20,70,WEVENT | CLOSE,-1,(Scheme FAR *) customScheme,
      WO_SYSTEMBORDER);
   _WShow(wh);

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WClose( ) API Library Routine
_WSelect( ) API Library Routine
_WSetTitle( ) API Library Routine
_WShow( ) API Library Routine
Accessing the Visual FoxPro API


_WOpenP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WOpenP( ) API Library Routine
See Also Example

Creates a new window at the positions specified by the top, left, bottom, and right parameters.

WHANDLE _WOpenP(int top, int left, int bottom, int right, int flag,
         int scheme_num, Scheme FAR *scheme, char FAR *bord)
int top;                     /* Top coordinate in pixels. */
int left;                     /* Left coordinate in pixels. */
int bottom;                  /* Bottom coordinate in pixels. */
int right;                     /* Right coordinate in pixels. */
int flag;                     /* Attributes. */
int scheme_num;            /* Color scheme. */
Scheme FAR *scheme;      /* Points to color scheme to use. */
char FAR *bord;            /* Border type. */

Remarks

The window positions may be off the screen. Additional memory is allocated to hold the off-screen image of this window.

The flag parameter determines the attributes for this window. The flag may be one or more of the flag values in the table below. You can combine multiple flag values using the C | or + operator. Typical window borders are defined in PRO_EXT.H.

flag Value | Window attribute
WCURSOR | The insertion point may be displayed in this window.
ZOOM | The user may zoom the window.
ADJ | The user may adjust the size of the window.
CLOSE | The user may close the window.
MOVE | The user may move the window.
AUTOSCROLL | The window scrolls when output rolls off the bottom line.
WEVENT | The window receives, activates, and deactivates events.
SHADOW | The window casts a shadow.
WMODAL | The user can't send this window to the back.
WMINIMIZE | The user can minimize this window.

The scheme_num may be any valid color scheme number, or – 1 to indicate that the scheme parameter points to the color scheme to use.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates windows using a number of different color schemes and borders. In particular, note the custom color scheme.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WOPENP

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh;

   char customScheme[12] =
   {
      BLACK_ON      | WHITE,
      RED_ON      | BLACK      | BLINK,
      WHITE_ON      | WHITE      | BRIGHT,
      CYAN_ON      | BLUE      | BRIGHT,
      GREEN_ON      | BROWN,
      BROWN_ON      | BROWN      | BRIGHT,
      MAGENTA_ON   | MAGENTA   | BRIGHT,
      RED_ON      | MAGENTA   | BRIGHT | BLINK,
      BROWN_ON      | GREEN      | BRIGHT,
      BLACK_ON      | CYAN,
      BLUE_ON      | CYAN,
   };

   _Execute("WAIT WINDOW 'Press any key to see a window \
      in WINDOW_SCHEME with WO_DOUBLEBOX border'");

   wh = _WOpenP(10, 10, 160, 320, WEVENT | CLOSE, WINDOW_SCHEME,
      (Scheme FAR *)0, WO_DOUBLEBOX);
   _WShow(wh);

   _Execute("WAIT WINDOW 'Press any key to see a window \
      in ALERT_SCHEME with WO_SINGLEBOX border'");
   _WClose(wh);

   wh = _WOpenP(10, 10, 160, 320, WEVENT | CLOSE, ALERT_SCHEME,
      (Scheme FAR *)0, WO_SINGLEBOX);
   _WShow(wh);

   _Execute("WAIT WINDOW 'Press any key to see a window \
      in WINDOW_SCHEME with WO_PANELBORDER border'");
   _WClose(wh);

   wh = _WOpenP(10, 10, 160, 320, WEVENT | CLOSE, WINDOW_SCHEME,
      (Scheme FAR *)0, WO_PANELBORDER);
   _WShow(wh);

   _Execute("WAIT WINDOW 'Press any key to see a window \
      in a custom scheme with WO_SYSTEMBORDER border'");
   _WClose(wh);

   wh = _WOpenP(10,10,160,320,WEVENT | CLOSE,-1,customScheme,
      WO_SYSTEMBORDER);
   _WShow(wh);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WClose( ) API Library Routine
_WSelect( ) API Library Routine
_WSetTitle( ) API Library Routine
_WShow( ) API Library Routine
Accessing the Visual FoxPro API


_WPosCursor( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WPosCursor( ) API Library Routine
See Also Example

Positions the output position in the specified window at the location specified in rows and columns by pt.

void _WPosCursor(WHANDLE wh, Point pt)
WHANDLE wh;            /* Window handle. */
Point pt;                     /* Location for the output position. */

Remarks

_WPosCursor( ) doesn't make the insertion point appear. Normally, the insertion point is visible only when Visual FoxPro is waiting for input.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a window and draws a diagonal pattern of Xs in this window. It positions the cursor before writing each X using _WPosCursor( ), and gets that same position using _WGetCursor( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO WPOSCUR

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point putPos, getPos;

   wh = _WOpen(4,4,20,70,0,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   for (putPos.v = 2; putPos.v < 14; putPos.v++)
   {
      putPos.h = putPos.v;

      _WPosCursor(wh, putPos);
      _WPutChr(wh, 'X');

      getPos = _WGetCursor(wh);

      _PutStr("\nCursor position:");
      putLong(getPos.v, 5);
      putLong(getPos.h, 5);

      _Execute("WAIT");
   }
   _WClose(wh);
}
FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WGetCursor( ) API Library Routine
Accessing the Visual FoxPro API
_WPosCursorP( ) API Library Routine
_WPutChr( ) API Library Routine
_WPutStr( ) API Library Routine


_WPosCursorP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WPosCursorP( ) API Library Routine
See Also Example

Positions the output position of the specified window at the location specified in pixels by pt.

void _WPosCursorP(WHANDLE wh, Point pt)
WHANDLE wh;            /* Window handle. */
Point pt;                     /* Location for output position. */

Remarks

_WPosCursor( ) doesn't make the insertion point appear. Normally, the insertion point is visible only when Visual FoxPro is waiting for input.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a window and draws a diagonal pattern of Xs in this window. It positions the cursor before writing each X using _WPosCursorP( ), and gets that same position using _WGetCursorP( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO WPOSCURP

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}
FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point putPos, getPos;

   wh = _WOpen(4,4,20,70,0,WINDOW_SCHEME,(Scheme FAR *)0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   for (putPos.v = 10; putPos.v < 100; putPos.v += 10)
   {
      putPos.h = putPos.v;

      _WPosCursorP(wh, putPos);
      _WPutChr(wh, 'X');

      getPos = _WGetCursorP(wh);

      _PutStr("\nCursor position:");
      putLong(getPos.v, 5);
      putLong(getPos.h, 5);

      _Execute("WAIT");
   }
   _WClose(wh);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Reference

_WPosCursor( ) API Library Routine

Other Resources

API Library Construction
_WGetCursorP( ) API Library Routine
Accessing the Visual FoxPro API
_WPutChr( ) API Library Routine
_WPutStr( ) API Library Routine


_WPutChr( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WPutChr( ) API Library Routine
See Also Example

Displays one character char at the output position in the specified window and in the current color.

void _WPutChr(WHANDLE wh, int char)
WHANDLE wh;            /* Window handle. */
int char;                     /* Character to display. */

Remarks

Special characters such as newline, carriage return, and bell are treated as control characters and aren't displayed on the screen.

To show the character that corresponds to one of these control characters, add 256 to the value of the character.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _WPutChr( ) to display all 8-bit values in a new window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WPUTCHR

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   int i;
   WHANDLE wh;

   wh = _WOpen(2,2,20,70,WEVENT | CLOSE,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   for (i = 0; i < 256; i++)
      _WPutChr(wh, i);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WPutStr( ) API Library Routine
_WGetCursorP( ) API Library Routine
Accessing the Visual FoxPro API
_WPosCursor( ) API Library Routine


_WPutStr( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WPutStr( ) API Library Routine
See Also Example

Displays a null-terminated string at the output position in the specified window and in the current color.

void _WPutStr(WHANDLE wh, char FAR *theStr)
WHANDLE wh;            /* Window handle. */
char FAR *theStr;               /* String to display. */

Remarks

Output that normally causes the window to scroll produces undefined results in windows that don't have the AUTOSCROLL attribute set.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _WPutStr( ) to display a string containing all 8-bit values (except '\0') in a new window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WPUTSTR

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   int i;
   WHANDLE wh;
   char String[256];

   wh = _WOpen(2,2,20,70,WEVENT | CLOSE,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   for (i = 0; i < 255; i++)
      String[i] = i + 1;
   String[255] = '\0';
   _WPutStr(wh, String);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WPutChr( ) API Library Routine
_WGetCursorP( ) API Library Routine
Accessing the Visual FoxPro API
_WPosCursor( ) API Library Routine


_WRight( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WRight( ) API Library Routine
See Also Example

Returns the column on the screen where the right edge of the specified window is located.

unsigned int _WRight(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Example

The following example shows the position of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WRIGHT
=WPOSITION()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\ntop   ="); putLong(_WTop(wh), 5);
   _PutStr("\nleft ="); putLong(_WLeft(wh), 5);
   _PutStr("\nbottom ="); putLong(_WBottom(wh), 5);
   _PutStr("\nright  ="); putLong(_WRight(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WPOSITION", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottom( ) API Library Routine
_WHeight( ) API Library Routine
_WLeft( ) API Library Routine
_WTop( ) API Library Routine
_WWidth( ) API Library Routine


_WRightP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WRightP( ) API Library Routine
See Also Example

Returns the position on the screen in pixels where the right edge of the specified window is located.

unsigned int _WRightP(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays the position of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WRIGHTP
=WPOSITION()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\ntop   ="); putLong(_WTopP(wh), 5);
   _PutStr("\nleft ="); putLong(_WLeftP(wh), 5);
   _PutStr("\nbottom ="); putLong(_WBottomP(wh), 5);
   _PutStr("\nright  ="); putLong(_WRightP(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WPOSITION", Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottomP( ) API Library Routine
_WHeightP( ) API Library Routine
_WLeftP( ) API Library Routine
_WTopP( ) API Library Routine
_WWidthP( ) API Library Routine


_WScroll( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WScroll( ) API Library Routine
See Also Example

Scrolls a portion of the contents of a window left or right and up or down.

void _WScroll(WHANDLE wh, Rect r, int dv, int dh)
WHANDLE wh;            /* Window handle. */
Rect r;                     /* Portion to scroll. */
int dv;                        /* Left or right. */
int dh;                     /* Up or down. */

Remarks

  • The r parameter describes the portion of the window to be scrolled.

  • The dv parameter describes the number of characters to scroll the window left or right. If dv is negative, the window contents scroll to the left. If dv is positive, the window contents scroll to the right.

  • The dh parameter describes the number of characters to scroll the window up or down. If dh is negative, the window contents scroll up. If dh is positive, the window contents scroll down.

If both dv and dh are 0, _WScroll( ) clears the characters inside the rectangle.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens a window and draws a rectangular pattern of Xs. This rectangle is also the scroll rectangle. First, the example scrolls the rectangle up two positions and to the left two positions. Next, it scrolls the rectangle down by four positions and to the right four positions.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WSCROLL

C Code

Copy Code
#include <pro_ext.h>

FAR WScrollEx(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point pos;
   Rect rect;

   wh = _WOpen(2,2,20,70,WEVENT | CLOSE,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   rect.top   = 6;
   rect.left   = 6;
   rect.bottom = 12;
   rect.right   = 12;

   for (pos.v = rect.top; pos.v < rect.bottom; pos.v++)
   {
      for (pos.h = rect.left; pos.h < rect.right; pos.h++)
      {
         _WPosCursor(wh, pos);
         _WPutChr(wh, 'X');
      }
   }
   _Execute("WAIT WINDOW 'Press any key to _WScroll(wh,rect,-2,-2)'");
   _WScroll(wh, rect, -2, -2);
   _Execute("WAIT WINDOW 'Press any key to _WScroll(wh,rect,+4,+4)'");
   _WScroll(wh, rect, +4, +4);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) WScrollEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WClear( ) API Library Routine
Accessing the Visual FoxPro API
_WScrollP( ) API Library Routine
_WPosCursor( ) API Library Routine
_WPutChr( ) API Library Routine


_WScrollP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WScrollP( ) API Library Routine
See Also Example

Scrolls a portion of the contents of a window left or right and up or down.

void _WScrollP(WHANDLE wh, Rect r, int dv, int dh)
WHANDLE wh;            /* Window handle. */
Rect r;                     /* Portion to scroll. */
int dv;                        /* Left or right. */
int dh;                     /* Up or down. */

Remarks

  • The r parameter describes the portion of the window to be scrolled.

  • The dv parameter describes the number of pixels to scroll the window left or right. If dv is negative, the window contents scroll to the left. If dv is positive, the window contents scroll to the right.

  • The dh parameter describes the number of pixels to scroll the window up or down. If dh is negative, the window contents scroll up. If dh is positive, the window contents scroll down.

If both dv and dh are 0, _WScrollP( ) clears the characters inside the rectangle.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example opens a window and draws a rectangular pattern of Xs. This rectangle is also the scroll rectangle. First, _WScrollP( ) scrolls the rectangle up and left. Next, it scrolls the rectangle down and right.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WSCROLLP

C Code

Copy Code
#include <pro_ext.h>

FAR WScrollEx(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point pos;
   Rect rect;

   wh = _WOpenP(2, 2, 160, 320, WEVENT | CLOSE, WINDOW_SCHEME,
      (char *) 0, WO_SYSTEMBORDER);

  _WShow(wh);

   rect.top   = 40;
   rect.left   = 40;
   rect.bottom = 100;
   rect.right   = 100;

   for (pos.v = rect.top; pos.v < rect.bottom; pos.v += 6)
   {
      for (pos.h = rect.left; pos.h < rect.right; pos.h +=6)
      {
         _WPosCursorP(wh, pos);
    _WPutChr(wh, 'X');
      }
   }
   _Execute("WAIT 'Press any key to _WScroll(wh, rect, -20, -20)'");
   _WScrollP(wh, rect, -20, -20);
   _Execute("WAIT 'Press any key to _WScroll(wh, rect, +40, +40)'");
   _WScrollP(wh, rect, +40, +40);
}

FoxInfo myFoxInfo[] =
{
   {"ONLOAD", WScrollEx, CALLONLOAD, ""},
};

FoxTable _FoxTable =
{
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WClear( ) API Library Routine
Accessing the Visual FoxPro API
_WPosCursor( ) API Library Routine
_WPutChr( ) API Library Routine


_WSelect( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WSelect( ) API Library Routine
See Also Example

Brings the specified window to the active position on the screen.

void _WSelect(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Example

The following example creates five overlapping windows. The windows are each moved to the active position using _WSelect( ), starting with the first window created.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WSELECT

C Code

Copy Code
#include <pro_ext.h>

FAR WSelectEx(ParamBlk FAR *parm)
{
   WHANDLE wh[5];
   int i;

   for (i = 0; i < 5; i++)
   {
      wh[i] = _WOpen(4 + 2*i,4 + 2*i,12 + 2*i,40 + 2*i,WEVENT | CLOSE,
         WINDOW_SCHEME, (Scheme FAR *) 0, WO_SYSTEMBORDER);
      _WShow(wh[i]);
   }
   for (i = 0; i < 5; i++)
   {
      _Execute("WAIT WINDOW 'Press key to _WSelect() next window'");
      _WSelect(wh[i]);
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) WSelectEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WOnTop( ) API Library Routine
_WShow( ) API Library Routine
_WOpen( ) API Library Routine
_Execute( ) API Library Routine


_WSendBehind( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WSendBehind( ) API Library Routine
See Also Example

Sends the specified window to the backmost position on the screen.

void _WSendBehind(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Example

The following example creates five overlapping windows. _WSendBehind( ) sends each window to the backmost position, starting with the last window created.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WSENDBEH

C Code

Copy Code
#include <pro_ext.h>

FAR WSendBehindEx(ParamBlk FAR *parm)
{
   WHANDLE wh[5];
   int i;

   for (i = 0; i < 5; i++)
   {
      wh[i] = _WOpen(4 + 2*i,4 + 2*i,12 + 2*i,40 + 2*i,WEVENT | CLOSE,
         WINDOW_SCHEME, (Scheme FAR *) 0, WO_SYSTEMBORDER);
      _WShow(wh[i]);
   }
   for (i = 4; i >= 0; i--)
   {
      _Execute("WAIT WINDOW 'Press key to _WSendBehind() next window'");
      _WSendBehind(wh[i]);
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) WSendBehindEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WOnTop( ) API Library Routine
_WSelect( ) API Library Routine
_WShow( ) API Library Routine
_Execute( ) API Library Routine


_WSetAttr( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WSetAttr( ) API Library Routine
See Also Example

Changes the attribute for the specified color scheme index in the indicated window's color scheme to the new attribute attr.

void _WSetAttr(WHANDLE wh, int color, int attr)
WHANDLE wh;            /* Window handle. */
int color;                     /* Color scheme. */
int attr;                     /* Attribute. */

Example

The following example goes through each color of each scheme, using _WSetAttr( ) to set the pen color, and then displaying some text in each color.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WSETATTR

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR WAttrEx(ParamBlk FAR *parm)
{
   int scheme;
   int color;
   WHANDLE wh;
   int attrib, savePen;

   for (scheme = 0; scheme <= 25; scheme++)
   {
      wh = _WOpen(2,10,23,70,WEVENT,scheme,(Scheme FAR *)0,
         WO_SYSTEMBORDER);

      for (color = WA_NORMAL; color <= WA_ISSHADOW; color++)
      {
         attrib  = _WAttr(wh, color);
         savePen = _WAttr(_WGetPort(), WA_PENCOLOR);

         _WSetAttr(_WGetPort(), WA_PENCOLOR, attrib);

         _PutStr("\nScheme:"); putLong(scheme, 5);
         _PutStr("; Color:"); putLong(color, 5);
         _PutStr("; Attribute byte:"); putLong(attrib, 5);

         _WSetAttr(_WGetPort(), WA_PENCOLOR, savePen);
      }
      _WClose(wh);
      _Execute("WAIT");
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) WAttrEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WClear( ) API Library Routine
_WClearRect( ) API Library Routine
_WAttr( ) API Library Routine
_PutStr( ) API Library Routine


_WSetPort( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WSetPort( ) API Library Routine
See Also Example

Changes the user output window to be the specified window.

WHANDLE _WSetPort(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

_WSetPort( ) returns the handle of the previous user output window.

Note:
If your routine changes the user output window, be sure to restore the user output window before returning to Visual FoxPro.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a window and makes this the output port. It writes some text to this window before switching back to the original output port.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WSETPORT

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

FAR Example(ParamBlk FAR *parm)
{

   WHANDLE wh;
   WHANDLE oldPort;

   wh = _WOpen(2,10,23,70,WEVENT | CLOSE,WINDOW_SCHEME,(Scheme FAR *)0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   _PutStr("\n1) _WGetPort() ="); putLong(_WGetPort(), 10);

   oldPort = _WSetPort(wh);
   _PutStr("\n2) _WSetPort(wh) ="); putLong(oldPort, 10);

   _PutStr("\n3) _WGetPort() ="); putLong(_WGetPort(), 10);

   oldPort = _WSetPort(oldPort);
   _PutStr("\n4) _WSetPort(oldPort) =");  putLong(oldPort, 10);

   _PutStr("\nShould be back where we started.");
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WGetPort( ) API Library Routine
_PutStr( ) API Library Routine
_WShow( ) API Library Routine
Input and Output


_WSetTitle( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WSetTitle( ) API Library Routine
See Also Example

Changes the title of the specified window to title.

void _WSetTitle(WHANDLE wh, char FAR *title)
WHANDLE wh;            /* Window handle. */
char FAR *title;            /* Window title. */

Remarks

To remove a title from a window, pass (char FAR *)0 as the new title.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a window and defines its title text with _WSetTitle( ).

Visual FoxPro Code

Copy Code
SET LIBRARY TO WSETTITL

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh;
   char FAR *buffer;

   wh = _WOpen(4,4,20,70,CLOSE | WEVENT,WINDOW_SCHEME,(Scheme FAR *)0,
      WO_SYSTEMBORDER);

   _WSetTitle(wh, "This is a window title");

   _WShow(wh);

   if ((buffer = _Alloca(128)) == 0)
   {
      _Error(182); // "Insufficient memory"
   }
   _WTitle(wh, buffer);

   _PutStr("\nThe window title is \"");
   _PutStr(buffer);
   _PutChr('"');

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WFindTitle( ) API Library Routine
_WTitle( ) API Library Routine
_WShow( ) API Library Routine
Accessing the Visual FoxPro API


_WShow( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WShow( ) API Library Routine
See Also Example

Displays a hidden window on the screen.

void _WShow(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

When you create a window, it is hidden by default until you use _WShow( ) to make it visible.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example contains two API routines. WINOPEN( ) opens a window but doesn't call _WShow( ), illustrating that the window is hidden until _WShow( ) displays it on the screen.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WSHOW
wh = WOPEN()
= WSHOW(wh)

C Code

Copy Code
#include <pro_ext.h>

FAR WOpen(ParamBlk FAR *parm)
{
   _RetInt(_WOpen(2, 2, 20, 70, WEVENT | CLOSE, WINDOW_SCHEME,
      (Scheme FAR *) 0, WO_SYSTEMBORDER), 10);
}

FAR WShow(ParamBlk FAR *parm)
{
   _WShow(parm->p[0].val.ev_long);
}

FoxInfo myFoxInfo[] = {
   {"WOPEN", (FPFI) WOpen, 0, ""},
   {"WSHOW", (FPFI) WShow, 1, "I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WHide( ) API Library Routine
_WOpen( ) API Library Routine
_WSelect( ) API Library Routine
Accessing the Visual FoxPro API
_WOpen( ) API Library Routine


_WSize( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WSize( ) API Library Routine
See Also Example

Sets new dimensions of the specified window to the height and width specified by h and v in the pt parameter.

void _WSize(WHANDLE wh, Point pt)
WHANDLE wh;            /* Window handle. */
Point pt;                     /* Position. */

Example

The following example creates a window, and then expands its width and height.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WSIZE

C Code

Copy Code
#include <pro_ext.h>

FAR WSizeEx(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point dim;

   wh = _WOpen(2,2,10,10,CLOSE | WEVENT,WINDOW_SCHEME,(Scheme FAR *)0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   dim.v = 8;

//   Grow in width
   for (dim.h = 8; dim.h < 60; dim.h += 4)
   {
      _WSize(wh, dim);
      _Execute("WAIT WINDOW 'Press Any Key To Change Size'");
   }

//   Grow in height
   for (dim.v = 8; dim.v < 20; dim.v += 2)
   {
      _WSize(wh, dim);
      _Execute("WAIT WINDOW 'Press Any Key To Change Size'");
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) WSizeEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WMove( ) API Library Routine
_WSizeP( ) API Library Routine
_WShow( ) API Library Routine
_Execute( ) API Library Routine


_WSizeP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WSizeP( ) API Library Routine
See Also Example

Sets the new dimensions of the window to the height and width specified in pixels by h and v in the pt parameter.

void _WSizeP(WHANDLE wh, Point pt)
WHANDLE wh;            /* Window handle. */
Point pt;                     /* Position. */

Remarks

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates a window, and expands its width and then its height.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WSIZEP

C Code

Copy Code
#include <pro_ext.h>

FAR WSizeEx(ParamBlk FAR *parm)
{
   WHANDLE wh;
   Point dim;

   wh = _WOpenP(6,6,20,20,CLOSE | WEVENT,WINDOW_SCHEME,(Scheme FAR *)0,
      WO_SYSTEMBORDER);
   _WShow(wh);

   dim.v = 14;

//   Grow in width
   for (dim.h = 14; dim.h < 480; dim.h += 40)
   {
      _WSizeP(wh, dim);
      _Execute("WAIT");
   }

//   Grow in height
   for (dim.v = 14; dim.v < 240; dim.v += 40)
   {
      _WSizeP(wh, dim);
      _Execute("WAIT WINDOW 'Press Any Key To Change Window Size'");
   }
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", WSizeEx, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottomP( ) API Library Routine
_WLeftP( ) API Library Routine
_WRightP( ) API Library Routine
_WTopP( ) API Library Routine
_WSize( ) API Library Routine


_WTitle( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WTitle( ) API Library Routine
See Also Example

Puts the null-terminated title of the window wh in title.

void _WTitle(WHANDLE wh, char FAR *title)
WHANDLE wh;            /* Window handle. */
char FAR *title;            /* Window title. */

Example

The following example creates and shows a window with both a title and a footer. _WTitle( ) retrieves the title text, which is then displayed on the screen.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WTITLE

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh;
   char FAR *buffer;

   wh = _WOpen(4,4,20,70,CLOSE | WEVENT,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_SYSTEMBORDER);

   _WSetTitle(wh, "This is a window title");

   _WShow(wh);

   if ((buffer = _Alloca(128)) == 0)
   {
      _Error(182); // "Insufficient memory"
   }
   _WTitle(wh, buffer);

   _PutStr("\nThe window title is \"");
   _PutStr(buffer);
   _PutChr('"');
}
FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WSetTitle( ) API Library Routine
_PutStr( ) API Library Routine
_WShow( ) API Library Routine


_WTop( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WTop( ) API Library Routine
See Also Example

Returns the row on the screen where the top of the window is located.

unsigned int _WTop(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Example

The following example displays the row position of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WTOP
=WPOSITION()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\ntop   ="); putLong(_WTop(wh), 5);
   _PutStr("\nleft ="); putLong(_WLeft(wh), 5);
   _PutStr("\nbottom ="); putLong(_WBottom(wh), 5);
   _PutStr("\nright  ="); putLong(_WRight(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WPOSITION", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottom( ) API Library Routine
_WHeight( ) API Library Routine
_WLeft( ) API Library Routine
_WRight( ) API Library Routine
_WWidth( ) API Library Routine
_WTopP( ) API Library Routine


_WTopP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WTopP( ) API Library Routine
See Also Example

Returns the position on the screen in pixels where the top of the window is located.

unsigned int _WTopP(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays the position of the active window in pixels.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WTOPP
=WPOSITION()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\ntop   ="); putLong(_WTopP(wh), 5);
   _PutStr("\nleft ="); putLong(_WLeftP(wh), 5);
   _PutStr("\nbottom ="); putLong(_WBottomP(wh), 5);
   _PutStr("\nright  ="); putLong(_WRightP(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WPOSITION", Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottomP( ) API Library Routine
_WHeightP( ) API Library Routine
_WLeftP( ) API Library Routine
_WRightP( ) API Library Routine
_WWidthP( ) API Library Routine
_WTop( ) API Library Routine


_WWidth( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WWidth( ) API Library Routine
See Also Example

Returns the number of columns in the content area of the specified window.

unsigned int _WWidth(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Example

The following example shows the height and width in rows and columns of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WWIDTH
=WDIMEN()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\nheight ="); putLong(_WHeight(wh), 5);
   _PutStr("\nwidth  ="); putLong(_WWidth(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WDIMEN", (FPFI) Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottom( ) API Library Routine
_WHeight( ) API Library Routine
_WLeft( ) API Library Routine
_WRight( ) API Library Routine
_WTop( ) API Library Routine
_WWidthP( ) API Library Routine


_WWidthP( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WWidthP( ) API Library Routine
See Also Example

Returns the width in pixels of the content area of the specified window.

unsigned int _WWidthP(WHANDLE wh)
WHANDLE wh;            /* Window handle. */

Remarks

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example displays the height and width in pixels of the active window.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WWIDTHP
=WDIMEN()

C Code

Copy Code
#include <pro_ext.h>

void putLong(long n, int width)
{
   Value val;

   val.ev_type = 'I';
   val.ev_long = n;
   val.ev_width = width;

   _PutValue(&val);
}

void FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh = _WOnTop();

   _PutStr("\nheight ="); putLong(_WHeightP(wh), 5);
   _PutStr("\nwidth  ="); putLong(_WWidthP(wh), 5);
}

FoxInfo myFoxInfo[] = {
   {"WDIMEN", Example, 0, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WBottom( ) API Library Routine
_WHeightP( ) API Library Routine
_WLeftP( ) API Library Routine
_WRightP( ) API Library Routine
_WTopP( ) API Library Routine


_WZoom( ) API Library Routine

Visual FoxPro 9.0 Language Reference
_WZoom( ) API Library Routine
See Also Example

Minimizes or maximizes the specified window, or returns it to normal.

void _WZoom(WHANDLE wh, int newstate)
WHANDLE wh;            /* Window handle. */
int newstate;                  /* State of window after zoom. */

Remarks

You can specify the newstate parameter as WZ_MINIMIZE, WZ_NORMAL, or WZ_MAXIMIZE, which are defined in the PRO_EXT.H file.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example creates and displays a window. It then calls _WZoom( ) for this window with each possible parameter.

Visual FoxPro Code

Copy Code
SET LIBRARY TO WZOOM

C Code

Copy Code
#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   WHANDLE wh;
   int row, col;

   wh = _WOpen(2,2,20,70,WEVENT | CLOSE,WINDOW_SCHEME,(Scheme FAR *) 0,
      WO_SYSTEMBORDER);

   _WShow(wh);

   _Execute("WAIT WINDOW 'Press any key to minimize window'");
   _WZoom(wh, WZ_MINIMIZED);

   _Execute("WAIT WINDOW 'Press any key to normalize window'");
   _WZoom(wh, WZ_NORMAL);

   _Execute("WAIT WINDOW 'Press any key to maximize window'");
   _WZoom(wh, WZ_MAXIMIZED);

   _Execute("WAIT WINDOW 'Press any key to normalize window'");
   _WZoom(wh, WZ_NORMAL);
}

FoxInfo myFoxInfo[] = {
   {"ONLOAD", (FPFI) Example, CALLONLOAD, ""},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Other Resources

API Library Construction
_WMove( ) API Library Routine
_WSize( ) API Library Routine
_WShow( ) API Library Routine
Accessing the Visual FoxPro API
ZOOM WINDOW Command


API Library Routines by Category

Visual FoxPro 9.0 Language Reference
API Library Routines by Category
See Also

Debugging Routines

Environment Routines

Error Handling Routines

Event Handling Routines

File Input and Output Routines

Memory Management Routines

Memo Field Input and Output Routines

Menu Routines

Object Routines

Routines to Return Results to Visual FoxPro

Statement and Expression Routines

String Manipulation Routines

Table Input and Output Routines

Text Editor and Clipboard Manipulation Routines

Variable and Array Routines

Window Manipulation Routines

See Also

Other Resources

Language Reference


Debugging Routines

Visual FoxPro 9.0 Language Reference
Debugging Routines
See Also

These API routines allow you to debug your API libraries.

_BreakPoint( )

A macro that generates the debugger breakpoint instruction, INT 3. This can be helpful for debugging external routines.

See Also

Other Resources

API Library Construction


Environment Routines

Visual FoxPro 9.0 Language Reference
Environment Routines
See Also

These API routines allow you to return information about the Visual FoxPro environment.

_GetAPIHandle( )

Returns the handle of the current FLL.

See Also

Other Resources

API Library Construction


Error Handling Routines

Visual FoxPro 9.0 Language Reference
Error Handling Routines
See Also

These API routines allow you to determine the cause of an error and the error type.

_Error( )

Signals the error specified by the value in code to the Visual FoxPro runtime.
_ErrorInfo( )

Returns the external error number that reflects the internal error number specified by code.
_UserError( )

Reports an error with the null-terminated text specified in the message.

See Also

Other Resources

API Library Construction


Event Handling Routines

Visual FoxPro 9.0 Language Reference
Event Handling Routines
See Also

These API routines allow you to create event handlers and process Visual FoxPro events.

_ActivateHandler( )

Adds a function handler to the end of the list of event handlers.
_ActivateIdle( )

Adds a routine to the list of routines called when Visual FoxPro is waiting for user input or for an event to time out.
_DeActivateHandler( )

Removes the specified handler from the event processor list.
_DeActivateIdle( )

Removes the specified routine from the idle loop.
_DefaultProcess( )

Provides the default event processing for an event returned by _GetNextEvent( ) when the event doesn't need special handling.
_GetNextEvent( )

Reads the next event into the EventRec and returns the event type.
_InKey( )

Returns the next key typed during the timeout period. The timeout period is specified as a number of MS-DOS timer ticks.
_MousePos( )

Fills in pt with the current position of the mouse.
_MousePosP( )

Fills in pt with the current position of the mouse in pixels.

See Also

Other Resources

API Library Construction


File Input and Output Routines

Visual FoxPro 9.0 Language Reference
File Input and Output Routines
See Also

These API routines allow you to directly create and manipulate files.

_FCHSize( )

Sets the file size on disk to the specified length. The specified length may extend or truncate the file.
_FClose( )

Terminates access to a file. Any buffers that have been modified while the buffer is open are automatically flushed to disk.
_FCopy( )

Attempts to copy len bytes from position spos in file sc to position dpos in file dc.
_FCreate( )

Assigns a Visual FoxPro channel to a new file.
_FEOF( )

Returns True if the file is currently at the end of file; otherwise, returns False.
_FError( )

Returns the last file operation error recorded for any channel.
_FFlush( )

Ensures that all modified buffers in memory have been flushed out to disk.
_FGets( )

Reads a single line of maxlen length, delimited with a carriage return, from a file.
_FOpen( )

Assigns a Visual FoxPro channel to an existing file.
_FPuts( )

Writes a null-terminated string to a file, followed by a carriage return/line feed pair.
_FRead( )

Reads exactly length bytes from a file into buffer.
_FSeek( )

Moves the file pointer to a new location as specified by position and mode.
_FWrite( )

Writes exactly length bytes from your buffer to a file. No terminator is added to the file.

See Also

Other Resources

API Library Construction


Memo Field Input and Output Routines

Visual FoxPro 9.0 Language Reference
Memo Field Input and Output Routines
See Also

These API routines allow you to manipulate memo fields in a Visual FoxPro table.

_AllocMemo( )

Allocates size bytes of space in the memo file for a field and inserts the new block number in the associated record in the table.
_FindMemo( )

Returns the location in the memo file to begin reading to access a memo field directly.
_MemoChan( )

Returns the Visual FoxPro channel of the memo file associated with the specified workarea.
_MemoSize( )

Returns the length of the memo field in the memo file.

See Also

Other Resources

API Library Construction


Memory Management Routines

Visual FoxPro 9.0 Language Reference
Memory Management Routines
See Also

These API routines allow you to manipulate and allocate memory for your API functions.

_Alloca( )

Allocates a block of stack space for the calling routine. Memory is automatically freed when the routine exits.
_AllocHand( )

Returns a new MHANDLE of size hsize. A value of zero is returned when there is insufficient memory to fulfill the request. Memory allocated with _AllocHand( ) isn't initialized.
_FreeHand( )

Releases an MHANDLE previously allocated by means such as _AllocHand( ).
_GetHandSize( )

Returns the usable number of bytes associated with an MHANDLE.
_HandToPtr( )

Translates an MHANDLE to a FAR (32-bit) pointer, which points to the memory allocated to this MHANDLE.
_HLock( )

Locks an MHANDLE to prevent it from moving if Visual FoxPro requires memory reorganization.
_HUnLock( )

Unlocks an MHANDLE, allowing it to participate in Visual FoxPro memory reorganization.
_MemAvail( )

Returns True if a request to allocate a handle of size bytes will succeed. Otherwise, _MemAvail( ) returns False.
_MemCmp( )

Compares two length byte memory areas.
_MemFill( )

Fills an area of memory starting at the location pointed to by ptr with length copies of the byte in character.
_MemMove( )

Copies length bytes from src to dest.
_SetHandSize( )

Changes the amount of memory allocated to an MHANDLE. The routine returns True if the reallocation is successful or False if the reallocation fails.

See Also

Other Resources

API Library Construction


Menu Routines

Visual FoxPro 9.0 Language Reference
Menu Routines
See Also

These API routines allow you to create, manipulate, and release menus.

_ActivateMenu( )

Displays the specified menu on the screen and immediately returns control to the calling routine.
_CountItems( )

Returns the number of menu titles or bars on the specified menu.
_DeActivateMenu( )

Removes a menu from the screen.
_DisposeItem( )

Releases the specified menu item and frees all storage associated with this item.
_DisposeMenu( )

Releases the specified menu and all its items and frees all storage associated with this menu.
_GetItemCmdKey( )

Copies the displayed keyboard shortcut string for the specified menu item to the buffer pointed to by the text parameter.
_GetItemId( )

Returns the item identifier of the index item in the specified menu.
_GetItemSubMenu( )

Returns the menu item identifier or a submenu assigned to a menu item.
_GetItemText( )

Copies the text of a menu bar or menu title to the buffer pointed to by text.
_GetNewItemId( )

Returns an identifier that is currently available for use as an item identifier in the specified menu.
_GetNewMenuId( )

Returns an identifier that's available for use as a menu identifier.
_MenuId( )

Returns the actual menu identifier that corresponds to the system-defined literal for the system menu title or menu.
_MenuInteract( )

Sets the itemid and the menuid to indicate which menu item was selected, if any.
_NewItem( )

Adds an item with the specified itemid to the menu specified by menuid.
_NewMenu( )

Creates a new menu of the specified menu type.
_OnSelection( )

Specifies a routine to execute when the specified menu and item are selected.
_SetItemCmdKey( )

Sets the keyboard shortcut for the specified menu item, as well as the displayed text for the keyboard shortcut.
_SetItemSubMenu( )

Assigns a submenu to a menu item. This can be used to attach a menu to a title, or a submenu to a menu item.
_SetItemText( )

Changes the displayed text for a menu item. The item may either be a pad or a bar.
_SetMenuPoint( )

Specifies the upper left corner, loc, of a menu.
_SetMenuPointP( )

Specifies in pixels the screen position of the upper left corner, loc, of a menu.

See Also

Other Resources

API Library Construction


Object Routines

Visual FoxPro 9.0 Language Reference
Object Routines
See Also

These API routines allow you to manipulate Visual FoxPro objects and controls.

_FreeObject( )

Releases an object from the Visual FoxPro API data pool.
_GetObjectProperty( )

Returns a property value for an object.
_ObjectCmp( )

Compares the properties of two objects and returns 0 if their properties and property values are identical.
_ObjectReference( )

Increments the reference count of an object.
_ObjectRelease( )

Decrements the reference count of an object.
_SetObjectProperty( )

Sets a property for an object.
_WGetObjectClientWindow( )

Returns the handle of the client window in which the specified object is contained.
_WGetObjectWindow( )

Returns the handle of the frame window in which the specified object is contained.

See Also

Other Resources

API Library Construction


Routines to Return Results to Visual FoxPro

Visual FoxPro 9.0 Language Reference
Routines to Return Results to Visual FoxPro
See Also

These API routines allow you to return results to Visual FoxPro as a specified data type.

_RetChar( )

Sets the function return value to a null-terminated string.
_RetCurrency( )

Sets the library return value to a currency value.
_RetDateStr( )

Sets the function return value to a date. The date is specified in mm/dd/year format, where the year may be either two or four digits.
_RetDateTimeStr( )

Sets the library return value to a datetime.
_RetFloat( )

Sets the function return value to a float value.
_RetInt( )

Sets the function return value to a numeric value.
_RetLogical( )

Sets the function return value to a logical value. Zero is considered False. Any non-zero value is considered True.
_RetVal( )

Passes a complete Visual FoxPro Value structure, so it can return any Visual FoxPro data type except for memo. You must call _RetVal( ) to return a string that contains embedded null characters.

See Also

Other Resources

API Library Construction


Statement and Expression Routines

Visual FoxPro 9.0 Language Reference
Statement and Expression Routines
See Also

These API routines allow you to compile and execute Visual FoxPro commands.

_Execute( )

Compiles and executes the null-terminated statement in stmt.
_Evaluate( )

Compiles and executes a Visual FoxPro expression contained in expr, placing the result in res.

See Also

Other Resources

API Library Construction


String Manipulation Routines

Visual FoxPro 9.0 Language Reference
String Manipulation Routines
See Also

These API routines allow you to manipulate strings.

_StrCmp( )

Compares two null-terminated strings.
_StrCpy( )

Copies a null-terminated string from src to dest.
_StrLen( )

Returns the length in bytes of a null-terminated string.

See Also

Other Resources

API Library Construction


Table Input and Output Routines

Visual FoxPro 9.0 Language Reference
Table Input and Output Routines
See Also

These API routines allow you manipulate Visual FoxPro tables.

_DBAppend( )

Attempts to append a new record to the table in the specified workarea.
_DBLock( )

Attempts to lock the current table record or file in a work area specified by workarea.
_DBRead( )

Moves the current record pointer to the specified record in the specified workarea.
_DBRecCount( )

Returns the total number of records in the table open in the specified workarea.
_DBRecNo( )

Returns the number of the current record in the table in the specified workarea.
_DBReplace( )

Places a new value in a field.
_DBRewind( )

Performs a GOTO TOP in the specified workarea and returns the resultant record number.
_DBSeek( )

Searches an indexed table in the current work area for the first record whose index key matches the value val.
_DBSkip( )

Performs a SKIP in the specified workarea of the distance specified.
_DBStatus( )

Returns status flags for the specified workarea.
_DBUnlock( )

Releases all user-obtained locks on records or the file in the work area specified by workarea.
_DBUnwind( )

Performs a GOTO BOTTOM in the specified workarea and returns the resultant record number.
_DBWrite( )

Writes to disk the current record in the specified workarea and updates any affected indexes.

See Also

Other Resources

API Library Construction


Text Editor and Clipboard Manipulation Routines

Visual FoxPro 9.0 Language Reference
Text Editor and Clipboard Manipulation Routines
See Also

These API routines allow you to manipulate the Visual FoxPro text editor, the file open in the text editor, and the clipboard.

_EdActive( )

Hides or shows the selection range or insertion point.
_EdCloseFile( )

Closes the specified file while saving without asking, prompting before saving, or saving as another file.
_EdCopy( )

Copies selected area to the clipboard.
_EdCut( )

Copies selected area to the clipboard and deletes it from the editor.
_EdDelete( )

Deletes the selected area. If there is no selection, deletes character at current pos.
_EdGetChar( )

Gets the character at EDPOS.
_EdGetEnv( )

Reads various editor settings.
_EdGetLineNum( )

Returns the line number for the position EDPOS.
_EdGetLinePos( )

Returns the EDPOS for the beginning of the line EDLINE.
_EdGetPos()

Returns current editor POS, or returns anchor point if there's a selection.
_EdGetStr( )

Gets the text between EDPOS and EDPOS inclusive, and places it in TEXT.
_EdIndent( )

Indents the selected text by int tab stops. Int can be negative in order to format a hanging indent.
_EdInsert( )

Inserts BYTES of TEXT.
_EdLastError( )

Returns the error number of the last editor error.
_EdOpenFile( )

Starts an editor session on this file.
_EdPaste( )

Copies clipboard text into the editor at current position.
_EdPosInView( )

Returns TRUE if the editor position is visible.
_EdRedo( )

Redoes the most recent undo.
_EdRevert( )

Reverts to a saved file.
_EdSave( )

Saves the file without closing the editing window.
_EdScrollToPos( )

Makes sure that EDPOS passed is on the screen, but doesn't move insertion point. BOOL means center EDPOS vertically.
_EdScrollToSel( )

Makes sure the selection anchor point is on the screen. BOOL means center anchor point vertically.
_EdSelect( )

Selects the range from EDPOS to EDPOS. To move the insertion point, set both EDPOSes the same.
_EdSendKey( )

Simulates key press given by int.
_EdSetEnv( )

Sets various editor settings.
_EdSetPos( )

Moves insertion point, and has side affect of unselecting anything currently selected.
_EdSkipLines( )

Moves insertion point from EDPOS to beginning of line int.
_EdUndo( )

Undoes the most recent changes.
_EdUndoOn( )

Groups the actions performed after _EdUndoOn( ) is passed until it is passed again as a single action for undo purposes.

See Also

Other Resources

API Library Construction


Variable and Array Routines

Visual FoxPro 9.0 Language Reference
Variable and Array Routines
See Also

These API routines allow you to manipulate memory variables and memory variable arrays.

_ALen( )

Returns information about the dimensions of the array whose name table index is nti.
_FindVar( )

Provides a way to initialize a Locator so you can use _Store( ) to place data in an existing memory variable.
_Load( )

Fetches the value of the memory variable or table variable specified by loc and places it into val.
_NameTableIndex( )

Returns the name table index that corresponds to a given name, or -1 if that name isn't in the name table.
_NewVar( )

Creates a variable or an array.
_Release( )

Frees a memory variable or an array.
_Store( )

Replaces the memory variable specified by loc with the value val.

See Also

Other Resources

API Library Construction


Window Manipulation Routines

Visual FoxPro 9.0 Language Reference
Window Manipulation Routines
See Also

These API routines allow you to create, manipulate, and release windows, and manipulate the main Visual FoxPro window.

_Dialog( )

Presents the user with a dialog that is the specified color scheme number scheme and contains the specified body text and button text.
_FindWindow( )

Places the WHANDLE of the window that the point pt belongs to on the screen into wh.
_FindWindowP( )

Places the handle of the window that the point pt belongs to on the screen into wh.
_GlobalToLocal( )

Translates a point in screen-relative coordinates to window-relative coordinates.
_GlobalToLocalP( )

Translates a point in screen-relative coordinates to window-relative pixel coordinates.
_PutChr( )

Writes one character char to the current output window in its normal attribute (color 0).
_PutStr( )

Writes a null-terminated string to the current output window in its normal attribute (color 0).
_PutValue( )

Formats the value val and writes it to the current output window.
_WAttr( )

Returns the attribute byte for the color index in the specified window's scheme.
_WBottom( )

Returns the row on the screen where the bottom of the window is located.
_WBottomP( )

Returns the position on the screen in pixels where the bottom of the specified window is located.
_WClear( )

Erases the contents of the specified window by changing the content area to the default background color.
_WClearRect( )

Erases a rectangular area of a window by changing it to the default background color.
_WClearRectP( )

Erases the specified rectangular portion of a window by changing it to the default background color.
_WClose( )

Closes a window and releases all memory associated with that window.
_WFindTitle( )

Passes the title of a window, and returns the WHANDLE.
_WGetCursor( )

Returns the position of the logical cursor in the specified window.
_WGetCursorP( )

Returns in pixels the current output position in the specified window.
_WGetPort( )

Returns the WHANDLE of the window that's currently selected for user output.
_WHeight( )

Returns the number of rows in the content area of a window.
_WHeightP( )

Returns the height in pixels of the content area of the specified window.
_WHide( )

Removes a window from the screen but keeps track of its contents so that it can be displayed again if desired.
_WLeft( )

Returns the column on the screen where the left edge of the window is located.
_WLeftP( )

Returns the position on the screen in pixels where the left edge of the window is located.
_WMainWindow( )

Returns the WHANDLE of the main Visual FoxPro window.
_WMove( )

Moves the specified window to a new location specified by pt.
_WMoveP( )

Moves the specified window to a new location specified by pt.
_WhToHwnd( )

Passes the WHANDLE, and returns the Windows HWND.
_WOnTop( )

Returns the WHANDLE of the frontmost window.
_WOpen( )

Creates a new window at the coordinates specified by top, left, bottom and right.
_WOpenP( )

Creates a new window at the coordinates specified by top, left, bottom and right.
_WPosCursor( )

Positions the logical cursor of the specified window at the location specified by pt.
_WPosCursorP( )

Positions the logical cursor of the specified window at the location specified in pixels by pt.
_WPutChr( )

Writes one character char to the specified window in the current color.
_WPutStr( )

Writes a null-terminated string to the specified window in the current color.
_WRight( )

Returns the column on the screen where the right edge of the window is located.
_WRightP( )

Returns the position on the screen in pixels where the right edge of the window is located.
_WScroll( )

Scrolls a portion of the contents of a window left or right and up or down.
_WScrollP( )

Scrolls a portion of the contents of a window left or right and up or down.
_WSetAttr( )

Changes the attribute for the specified color scheme index in the indicated window's color scheme to the new attribute attr.
_WSelect( )

Brings the specified window to the frontmost position on the screen.
_WSendBehind( )

Sends the specified window to the rearmost position on the screen.
_WSetPort( )

Changes the user output window to be the specified window.
_WSetTitle( )

Changes the title of a window.
_WShow( )

Redisplays a hidden window on the screen.
_WSize( )

Sets the new dimensions of the window to the height and width specified by h and v in pt.
_WSizeP( )

Sets the new dimensions of the window to the height and width specified by h and v in pt.
_WTitle( )

Puts the null-terminated title of the window wh in title.
_WTop( )

Returns the row on the screen where the top of the window is located.
_WTopP( )

Returns the position on the screen in pixels where the top of the window is located.
_WWidth( )

Returns the number of columns in the content area of a window.
_WWidthP( )

Returns the width in pixels of the content area of the specified window.
_WZoom( )

Zooms a window to a new state.

See Also

Other Resources

API Library Construction


Visual FoxPro System Events (API Library Construction)

Visual FoxPro 9.0 Language Reference
Visual FoxPro System Events (API Library Construction)
See Also

In this table, each Visual FoxPro event is listed along with the layout of its event record fields and a description of when the event occurs.

Event | EventRec Fields | Description
nullEvent | what = nullEvent where.h = horizontal mouse location where.v = vertical mouse location when = ticks since startup | Occurs when no other events are pending. This is the most frequently occurring event and, for performance reasons, should be used sparingly.
mouseDownEvent | what = mouseDownEvent where.h = horizontal mouse location where.v = vertical mouse location mbState = left mouse button when = ticks since startup | Occurs whenever the left mouse button is pressed. Trap for the mouseDownEvent and use this in combination with the where point and _FindWindow function to see if the user clicked on the close menu box or on other parts of a window. (A closeEvent is not generated when you click on the close menu box of a window.)
keyDownEvent | what = keyDownEvent where.h = horizontal mouse location where.v = vertical mouse location message = key code (see Appendix A) modifier = modifier key when = ticks since startup | Occurs whenever a key is pressed on the keyboard or whenever the keyboard buffer is played.
deactivateEvent | what = deactivateEvent where.h = horizontal mouse location where.v = vertical mouse location message = WHANDLE to window when = ticks since startup | Occurs whenever a window becomes deactivated by clicking on the close menu box, activating another window or using the DEACTIVATE WINDOW command. A deactivateEvent is usually followed by an activateEvent.
activateEvent | what = activateEvent where.h = horizontal mouse location where.v = vertical mouse location message = WHANDLE to window when = ticks since startup | Occurs whenever a window is activated. This includes system and user windows as well as dialogs, so it is suggested that whenever you receive this type of event, you check to see if it pertains to your window. An activateEvent is usually preceded by a deactivateEvent.
menuHitEvent | what = menuHitEvent misc = MENUID misc2 = BAR # when = ticks since startup modifier = modifier key | Occurs when a user makes a selection from a menu-type item. Menu-type items include menus, popups and scrollable lists. Because menuHitEvents occur very often, it is best to use the _OnSelection function to do a certain task upon a menu selection so you can eliminate a lot of extra event checking.
closeEvent | what = closeEvent message = WHANDLE to window when = ticks since startup | Occurs when a window is removed from memory with the RELEASE WINDOW command or by exiting Visual FoxPro. To check if a user closed a window by clicking on the close menu box, check for a mouseDownEvent.
hideEvent | what = hideEvent when = ticks since startup | Occurs when a window is hidden with the HIDE WINDOW command.
showEvent | what = showEvent when = ticks since startup | Occurs when a window is shown with the SHOW WINDOW command.
hotkeyEvent | what = hotkeyEvent where.h = horizontal mouse location where.v = vertical mouse location message = key code (see FoxPro Key Codes chapter) modifier = modifier key when = ticks since startup | Occurs when the user presses a key that has actions assigned to it with the ON KEY LABEL command.
sizeEvent | what = sizeEvent when = ticks since startup | Occurs only when a ZOOM WINDOW or SIZE WINDOW command is issued. To check for an instance of a user clicking on the size control of a window, check for a mouseDownEvent.
zoomEvent | what = zoomEvent when = ticks since startup | Occurs only when the ZOOM WINDOW command is executed. To check for the instance of a user clicking on the zoom control, check for a mouseDownEvent.

See Also

Other Resources

Visual FoxPro Key Codes (API Library Construction)
Activate Event
API Library Routines A-Z
API Library Routines by Category


Visual FoxPro Key Codes (API Library Construction)

Visual FoxPro 9.0 Language Reference
Visual FoxPro Key Codes (API Library Construction)
See Also Example

Most keyboard keys have a constant value even when combined with different modifier keys (SHIFT, CTRL and ALT). All regular keys on the keyboard (alphabet and special characters) have a key code of their ASCII value.

Key code and key modifier values are returned in the EventRec structure. The key code can be found in EventRec.message and the key modifiers can be found in EventRec.modifiers.

Visual FoxPro interprets some keys as having a different value depending on the modifier with which they are combined. For example, if SHIFT+F10 is pressed, the corresponding fields in the EventRec would be:

  • EventRec.message = 15D (Hex)

  • EventRec.modifier = 1000 (Hex)

Similarly, if CTRL+F10 is pressed, the EventRec values would be:

  • EventRec.message = 167 (Hex)

  • EventRec.modifiers = 2000 (Hex)

When more than one modifier is used with a key, the modifier values are added together. For example, if you press CTRL+SHIFT+F10, the following values are returned:

  • EventRec.message = 167 (Hex)

  • EventRec.modifiers = 3000 (Hex)

The EventRec.modifiers value in the preceding example is 0x3000 because both the CTRL and SHIFT modifiers were included in the key press. Thus, the SHIFT key modifier (0x1000) was added to the CTRL key modifier (0x2000) to produce a value of 0x3000.

Note:
The manner in which Visual FoxPro interprets keys (specifically keys with modifiers) is inherent to Visual FoxPro. Other programs may interpret keys differently. If a key is pressed in combination with one or multiple modifier keys (SHIFT, CTRL and ALT), the uppermost nibble represents the modifiers that were used.

The following table demonstrates that the F8 key has a different key code depending on the modifier used.

Keys pressed | Modifier | Key value of F8
F8 | None | \x142
SHIFT+F8 | SHIFT | \x15B
CTRL+F8 | CTRL | \x165
ALT+F8 | ALT | \x16F

Each special key that can be combined with modifiers has a unique value when combined with each modifier. If a special key is combined with multiple modifiers, the unique value assigned to the key is its value for one of the modifiers according to the following rules:

  1. First check to see if the key combination pressed includes the ALT key because the main key will be assigned its ALT key value.

  2. If the key combination does not include ALT, check to see if the CTRL key modifier was used because the main key will be assigned its CTRL key value.

  3. If no ALT or CTRL key modifier is used, check to see if the SHIFT key modifier was used because the main key will be assigned its SHIFT key value.

  4. Finally, if no modifiers were used, the main key is assigned its value based on no modifiers.

Special Key Codes

The following table lists the key values assigned by Visual FoxPro to special keys on the keyboard.

Key | Key code (Hex) | Key modifier
LEFTMOUSE | 100 | None
F1 | 13B | None
F2 | 13C | None
F3 | 13D | None
F4 | 13E | None
F5 | 13F | None
F6 | 140 | None
F7 | 141 | None
F8 | 142 | None
F9 | 143 | None
F10 | 144 | None
HOME | 147 | None
UPARROW | 148 | None
PGUP | 149 | None
LEFTARROW | 14B | None
RIGHTARROW | 14D | None
END | 14F | None
DNARROW | 150 | None
PGDN | 151 | None
INS | 152 | None
DEL | 153 | None
F11 | 185 | None
F12 | 186 | None
BACKTAB | 10F | shiftKey
SHIFT+F1 | 154 | shiftKey
SHIFT+F2 | 155 | shiftKey
SHIFT+F3 | 156 | shiftKey
SHIFT+F4 | 157 | shiftKey
SHIFT+F5 | 158 | shiftKey
SHIFT+F6 | 159 | shiftKey
SHIFT+F7 | 15A | shiftKey
SHIFT+F8 | 15B | shiftKey
SHIFT+F9 | 15C | shiftKey
SHIFT+F10 | 15D | shiftKey
SHIFT+F11 | 187 | shiftKey
SHIFT+F12 | 188 | shiftKey
CTRL+A | 001 | ctrlKey
CTRL+B | 002 | ctrlKey
CTRL+C | 003 | ctrlKey
CTRL+D | 004 | ctrlKey
CTRL+E | 005 | ctrlKey
CTRL+F | 006 | ctrlKey
CTRL+G | 007 | ctrlKey
CTRL+H | 008 | ctrlKey
CTRL+I | 009 | ctrlKey
CTRL+ENTER | 00A | ctrlKey
CTRL+J | 00A | ctrlKey
CTRL+K | 00B | ctrlKey
CTRL+L | 00C | ctrlKey
CTRL+M | 00D | ctrlKey
CTRL+N | 00E | ctrlKey
CTRL+O | 00F | ctrlKey
CTRL+P | 010 | ctrlKey
CTRL+Q | 011 | ctrlKey
CTRL+R | 012 | ctrlKey
CTRL+S | 013 | ctrlKey
CTRL+T | 014 | ctrlKey
CTRL+U | 015 | ctrlKey
CTRL+V | 016 | ctrlKey
CTRL+W | 017 | ctrlKey
CTRL+X | 018 | ctrlKey
CTRL+Y | 019 | ctrlKey
CTRL+Z | 01A | ctrlKey
CTRL+LBRACKET | 01B | ctrlKey
CTRL+BACKSLASH | 01C | ctrlKey
CTRL+RBRACKET | 01D | ctrlKey
CTRL+CARET | 01E | ctrlKey+shiftKey
CTRL+HYPHEN | 01F | ctrlKey
CTRL+SPACEBAR | 020 | ctrlKey
CTRL+F1 | 15E | ctrlKey
CTRL+F2 | 15F | ctrlKey
CTRL+F3 | 160 | ctrlKey
CTRL+F4 | 161 | ctrlKey
CTRL+F5 | 162 | ctrlKey
CTRL+F6 | 163 | ctrlKey
CTRL+F7 | 164 | ctrlKey
CTRL+F8 | 165 | ctrlKey
CTRL+F9 | 166 | ctrlKey
CTRL+F10 | 167 | ctrlKey
CTRL+LEFTARROW | 173 | ctrlKey
CTRL+RIGHTARROW | 174 | ctrlKey
CTRL+END | 175 | ctrlKey
CTRL+PGDN | 176 | ctrlKey
CTRL+HOME | 177 | ctrlKey
CTRL+PGUP | 184 | ctrlKey
CTRL+F11 | 189 | ctrlKey
CTRL+F12 | 18A | ctrlKey
CTRL+UPARROW | 18D | ctrlKey
CTRL+DNARROW | 191 | ctrlKey
CTRL+INS | 192 | ctrlKey
CTRL+DEL | 193 | ctrlKey
CTRL+TAB | 194 | ctrlKey
ALT+Q | 110 | altKey
ALT+W | 111 | altKey
ALT+E | 112 | altKey
ALT+R | 113 | altKey
ALT+T | 114 | altKey
ALT+Y | 115 | altKey
ALT+U | 116 | altKey
ALT+I | 117 | altKey
ALT+O | 118 | altKey
ALT+P | 119 | altKey
ALT+A | 11E | altKey
ALT+S | 11F | altKey
ALT+D | 120 | altKey
ALT+F | 121 | altKey
ALT+G | 122 | altKey
ALT+H | 123 | altKey
ALT+J | 124 | altKey
ALT+K | 125 | altKey
ALT+L | 126 | altKey
ALT+Z | 12C | altKey
ALT+X | 12D | altKey
ALT+C | 12E | altKey
ALT+V | 12F | altKey
ALT+B | 130 | altKey
ALT+N | 131 | altKey
ALT+M | 132 | altKey
ALT+F1 | 168 | altKey
ALT+F2 | 169 | altKey
ALT+F3 | 16A | altKey
ALT+F4 | 16B | altKey
ALT+F5 | 16C | altKey
ALT+F6 | 16D | altKey
ALT+F7 | 16E | altKey
ALT+F8 | 16F | altKey
ALT+F9 | 170 | altKey
ALT+F10 | 171 | altKey
ALT+1 | 178 | altKey
ALT+2 | 179 | altKey
ALT+3 | 17A | altKey
ALT+4 | 17B | altKey
ALT+5 | 17C | altKey
ALT+6 | 17D | altKey
ALT+7 | 17E | altKey
ALT+8 | 17F | altKey
ALT+9 | 180 | altKey
ALT+0 | 181 | altKey
ALT+F11 | 18B | altKey
ALT+F12 | 18C | altKey
ALT+HOME | 197 | altKey
ALT+UPARROW | 198 | altKey
ALT+PGUP | 199 | altKey
ALT+LEFTARROW | 19B | altKey
ALT+RIGHTARROW | 19D | altKey
ALT+END | 19F | altKey
ALT+DNARROW | 1A0 | altKey
ALT+PGDN | 1A1 | altKey
ALT+INS | 1A2 | altKey
ALT+DEL | 1A3 | altKey

Example

Copy Code
FAR EventHandler(WHandle theWindow, EventRec FAR *ev)
{
switch(ev->what)
{
case keyDownEvent:                  /* Check the keyDownEvent */
if (ev->modifiers & shiftCodeMask)      /* A modifier was pressed. */
{
if (ev->modifiers & altKey)            /* Check for the ALT Key */
_PutStr("ALT Key Code should be used.\n");
else
if (ev->modifiers & ctrlKey)         /* CTRL Key */
_PutStr("CTRL Key Code should be used.\n");
else
if (ev->modifiers & shiftKey)         /* SHIFT Key */
_PutStr("SHIFT Key Code should be used.\n");
}
else
_PutStr("Regular Key Code should be used.\n");
return NO;                        /* Let Visual FoxPro have Key also */
break;
default:
return NO;
}
}
Note:
shiftCodeMask, altKey, ctrlKey, and shiftKey are all defined in PRO_EXT.H and PRO_EXT.INC as follows:

  • #define shiftCodeMask 0xf000

  • #define shiftKey 0x1000

  • #define ctrlKey 0x2000

  • #define altKey 0x4000

See Also

Other Resources

API Library Routines A-Z
API Library Routines by Category
_PutStr( ) API Library Routine
_ASCIICOLS System Variable
_ASCIIROWS System Variable
Visual FoxPro System Events (API Library Construction)
KeyPress Event


SQL Commands and Functions

Visual FoxPro 9.0 Language Reference
SQL Commands and Functions
See Also

Visual FoxPro supports Structured Query Language (SQL) commands and functions. Visual FoxPro's SQL commands make use of Rushmore Query Optimization technology to optimize performance, and a single SQL command can be used to replace multiple Visual FoxPro commands.

Visual FoxPro supports the following:

ALTER TABLE - SQL Command

Modifies an existing table. You can modify the name, type, precision, scale, null value support, and referential integrity rules for each field in the table.
ASQLHANDLES( ) Function

Stores numeric references to all active SQL connection statement handles in an array.
CREATE CURSOR - SQL Command

Creates a temporary table. Each field in the temporary table is defined with a name, type, precision, scale, null value support, and referential integrity rules. These definitions can be obtained from the command itself or from an array.
CREATE SQL VIEW Command

Displays the View Designer, allowing you to create an SQL view.
CREATE TABLE -SQL Command

Creates a table. Each new table field is defined with a name, type, precision, scale, null value support, and referential integrity rules. These definitions can be obtained from the command itself or from an array.
DELETE - SQL Command

Marks records in a table for deletion using SQL syntax.
INSERT - SQL Command

Appends a new record to the end of an existing table. The new record contains data listed in the INSERT command or from an array.
SELECT - SQL Command

Specifies the criteria on which a query is based and issues the query. Visual FoxPro interprets the query and retrieves the specified data from the table(s). The SELECT command is built into Visual FoxPro like any other Visual FoxPro command. You can create a SELECT command query in these areas:
  • In the Command window.

  • In a Visual FoxPro program (like any other Visual FoxPro command).

  • In the Query Designer.

SQL Pass Through Foundation Class

Makes it possible for you to execute stored procedures on a host database such as Microsoft SQL Server.
SQLCANCEL( ) Function

Requests cancellation of an executing SQL statement
SQLCOLUMNS( ) Function

Stores a list of column names and information about each column for the specified data source table to a Visual FoxPro cursor.
SQLCOMMIT( ) Function

Commits a transaction.
SQLCONNECT( ) Function

Establishes a connection to a data source.
SQLDISCONNECT( ) Function

Terminates a connection to a data source.
SQLEXEC( ) Function

Sends an SQL statement to the data source, where the statement is processed.
SQLGETPROP( ) Function

Returns current or default settings for an active connection.
SQLIDLEDISCONNECT( ) Function

Allows a SQL pass-through connection to be temporarily disconnected.
SQLMORERESULTS( ) Function

Copies another result set to a Visual FoxPro cursor if more result sets are available.
SQLPREPARE( ) Function

Prepares an SQL statement for remote execution by SQLEXEC( ).
SQLROLLBACK( ) Function

Cancels any changes made during the current transaction.
SQLSETPROP( ) Function

Specifies settings for an active connection.
SQLSTRINGCONNECT( ) Function

Establishes a connection to a data source through a connection string.
SQLTABLES( ) Function

Stores the names of tables in a data source to a Visual FoxPro cursor.
UPDATE - SQL Command

Updates records in a table. The records can be updated based on the results of a SELECT - SQL statement.

See Also

Other Resources

CREATE QUERY Command
MODIFY QUERY Command
Language Reference


Language Reference for OLE DB Development

Visual FoxPro 9.0
Language Reference for OLE DB Development

Visual FoxPro contains language you can use with the OLE DB Provider for Visual FoxPro.

In This Section

Visual FoxPro OLE DB Provider Data Support

Describes data types as well as file and code characteristics supported by the Visual FoxPro OLE DB Provider.
Supported Visual FoxPro Commands and Functions in OLE DB Provider

Lists Visual FoxPro language you can use against the Visual FoxPro OLE DB Provider and in stored procedures, triggers, rules, and default values.
Unsupported Visual FoxPro Commands and Functions in OLE DB Provider

Lists Visual FoxPro language not supported by the Visual FoxPro OLE DB Provider.
Supported OLE DB Objects

Describes OLE DB objects supported by the Visual FoxPro OLE DB Provider.
Standard and Custom OLE DB Properties

Lists OLE DB properties supported by the Visual FoxPro OLE DB Provider.

Related Sections

Visual FoxPro Data Access Using the OLE DB Provider

Introduces using the Visual FoxPro OLE DB Provider to access Visual FoxPro data from other programming languages and applications.


Visual FoxPro OLE DB Provider Data Support

Visual FoxPro 9.0
Visual FoxPro OLE DB Provider Data Support
See Also

The following table describes the types and other file and code characteristics of data supported by the Visual FoxPro OLE DB Provider.

Data type | Indicator | Size | Range | OLE DB type
Character | C | 1 byte per char to 254 | Any Characters | DBTYPE_STR
Character (binary) | C NOCPTRANS | 1 byte per char to 254 | Any Characters | DBTYPE_BYTES
Date | D | 8 bytes | 0001-01-01 to 9999-12-31 | DBTYPE_DATE
DateTime | T | 8 bytes | 0001-01-01 to 9999-12-31; 00:00:00 a.m. to 11:59:59 p.m. | DBTYPE_DBTIMESTAMP
Numeric | N | 1 to 20 bytes | - .9999999999E+19 to .9999999999E+20 | DBTYPE_DECIMAL
Float | F | 1 to 20 bytes | - .9999999999E+19 to .9999999999E+20 | DBTYPE_DECIMAL
Integer | I | 4 bytes | 2147483647 to 2147483647 | DBTYPE_I4
Double | B | 8 bytes | +/-4.94065645841247E-324 to +/-8.9884656743115E307 | DBTYPE_R8
Currency | Y | 8 bytes | - 922337203685477.5807 to 922337203685477.5807 | DBTYPE_CY
Logical | L |  | .T./.F. | DBTYPE_BOOL
Memo | M | 4 bytes in table | Available memory | DBTYPE_BYTES
Memo (binary) | M NOCPTRANS | 4 bytes in table | Available memory | DBTYPE_BYTES
General (blob) | G | 4 bytes in table | Available memory | DBTYPE_BYTES

The following table describes the mapping of Visual FoxPro OLE DB types to Visual Studio types:

Indicator | OLE DB type | Visual Studio type
C | DBTYPE_STR | System.String
C NOCPTRANS | DBTYPE_BYTES | System.String
D | DBTYPE_DATE | System.DateTime
T | DBTYPE_DBTIMESTAMP | System.DateTime
N | DBTYPE_NUMERIC | System.Decimal
F | DBTYPE_NUMERIC | System.Decimal
I | DBTYPE_I4 | System.Int32
B | DBTYPE_R8 | System.Double
Y | DBTYPE_CY | System.Decimal
M | DBTYPE_STR | System.String
M NOCPTRANS | DBTYPE_BYTES | System.Byte
G | DBTYPE_BYTES | System.Byte

See Also

Other Resources

Language Reference for OLE DB Development
Supported Visual FoxPro Commands and Functions in OLE DB Provider
Unsupported Visual FoxPro Commands and Functions in OLE DB Provider
Supported OLE DB Objects
Standard and Custom OLE DB Properties
OLE DB Provider for Visual FoxPro


Supported Visual FoxPro Commands and Functions in OLE DB Provider

Visual FoxPro 9.0
Supported Visual FoxPro Commands and Functions in OLE DB Provider
See Also

Visual FoxPro contains language you can use with the OLE DB Provider for Visual FoxPro. Some of these language elements are for use only against the OLE DB Provider; while others can be used in stored procedures, triggers, rules, and default values.

Note:
You can determine the state of many SET commands, supported and unsupported except for SET ANSI, by querying the database. For example, the following line of code returns the value for SET PATH in the resultant cursor:

Note:
SELECT SET('PATH') FROM Table WHERE RECNO()=1

Commands Called Against the Visual FoxPro OLE DB Provider

The Visual FoxPro OLE DB Provider supports native Visual FoxPro language syntax for commands you can execute against the provider. The following tables list these commands.

For more information about the syntax for these commands, see the Visual FoxPro Language Reference.

SQL Commands

ALTER TABLE - SQL Command | CREATE TABLE - SQL Command | DELETE - SQL Command
INSERT - SQL Command (Using the SQL INSERT command with an array, memory variable, or an object is not supported.) | SELECT - SQL Command | UPDATE - SQL Command

Other Commands

DROP TABLE Command | SET ANSI Command | SET AUTOINCERROR Command
SET BLOCKSIZE Command | SET COLLATE Command | SET DELETED Command
SET ENGINEBEHAVIOR Command | SET EXACT Command | SET EXCLUSIVE Command
SET FULLPATH Command | SET MULTILOCKS Command | SET NULL Command
SET PATH Command | SET REPROCESS Command | SET UNIQUE Command

Commands and Functions for Stored Procedures, Rules, Triggers, and Default Values

You can use a larger set of commands in stored procedures, rules, triggers, and defalut values. The following tables list these commands and functions.

$ Operator | % Operator | & Command
&& Command | * Command | = Command

A

ABS( ) Function | ACOPY( ) Function | ACOS( ) Function
ADATABASES( ) Function | ADBOBJECTS( ) Function | ADD TABLE Command
ADEL( ) Function | AELEMENT( ) Function | AERROR( ) Function
AFIELDS( ) Function | AINS( ) Function | ALEN( ) Function
ALIAS( ) Function | ALLTRIM( ) Function | ALTER TABLE - SQL Command
AND Operator | APPEND Command | APPEND FROM ARRAY Command
APPEND GENERAL Command | APPEND GENERAL Command | APPEND MEMO Command
APPEND PROCEDURES Command | ASC( ) Function | ASCAN( ) Function
ASIN( ) Function | ASORT( ) Function | ASQLHANDLES( ) Function
ASUBSCRIPT( ) Function | AT( ) Function | AT_C( ) Function
ATAN( ) Function | ATC( ) Function | ATCC( ) Function
ATCLINE( ) Function | ATLINE( ) Function | ATN2( ) Function
AUSED( ) Function | AVERAGE Command |

B

BEGIN TRANSACTION Command | BETWEEN( ) Function | BITAND( ) Function
BITCLEAR( ) Function | BITLSHIFT( ) Function | BITNOT( ) Function
BITOR( ) Function | BITRSHIFT( ) Function | BITSET( ) Function
BITTEST( ) Function | BITXOR( ) Function | BLANK Command
BOF( ) Function |  |

C

CALCULATE Command | CANDIDATE( ) Function | CDX( ) Function
CEILING( ) Function | CHR( ) Function | CHRTRAN( ) Function
CHRTRANC( ) Function | CLEARRESULTSET( ) Function | CLOSE Commands
CMONTH( ) Function | CONTINUE Command | COPY INDEXES Command
COPY PROCEDURES Command | COPY STRUCTURE Command | COPY STRUCTURE EXTENDED Command
COPY TO Command | CURSORGETPROP("AutoIncError") Function | CURSORTOXML( ) Function

D

DATE( ) Function | DATETIME( ) Function | DAY( ) Function
DBC( ) Function | DBF( ) Function | DBUSED( ) Function
DELETE - SQL Command | DELETE Command | DELETE TAG Command
DELETED( ) Function | DESCENDING( ) Function | DIFFERENCE( ) Function
DIMENSION Command | DISKSPACE( ) Function | DMY( ) Function
DO CASE ... ENDCASE Command | DO Command | DO WHILE ... ENDDO Command
DOW( ) Function | DTOC( ) Function | DTOR( ) Function
DTOS( ) Function | DTOT( ) Function |

E

EMPTY( ) Function | END TRANSACTION Command | EOF( ) Function
ERROR( ) Function | EVALUATE( ) Function | EXIT Command
EXECSCRIPT( ) Function | EXP( ) Function |

F

FCOUNT( ) Function | FDATE( ) Function | FIELD( ) Function
FILE( ) Function | FILTER( ) Function | FLDLIST( ) Function
FLOCK( ) Function | FLOOR( ) Function | FLUSH Command
FOR ... ENDFOR Command | FOR( ) Function | FOUND( ) Function
FREE TABLE Command | FSIZE( ) Function | FTIME( ) Function
FULLPATH( ) Function | FUNCTION Command | FV( ) Function

G

GATHER Command | GETCP( ) Function | GETFLDSTATE( ) Function
GETNEXTMODIFIED( ) Function | GETRESULTSET( ) Function | GO | GOTO Command
GOMONTH( ) Function |  |

H

HEADER( ) Function

HOUR( ) Function

I

ICASE( ) Function | IDXCOLLATE( ) Function | IF ... ENDIF Command
IIF( ) Function | INDBC( ) Function | INDEX Command
INLIST( ) Function | INSERT - SQL Command | INT( ) Function
ISALPHA( ) Function | ISBLANK( ) Function | ISDIGIT( ) Function
ISEXCLUSIVE( ) Function | ISLEADBYTE( ) Function | ISLOWER( ) Function
ISREADONLY( ) Function | ISUPPER( ) Function |

K

KEY( ) Function

KEYMATCH( ) Function

L

LEFT( ) Function | LEFTC( ) Function | LEN( ) Function
LENC( ) Function | LIKE( ) Function | LIKEC( ) Function
LOCAL Command | LOCATE Command | LOCK( ) Function
LOG( ) Function | LOG10( ) Function | LOOKUP( ) Function
LOWER( ) Function | LPARAMETERS Command | LTRIM( ) Function
LUPDATE( ) Function |  |

M

_MLINE System Variable | MAX( ) Function | MDX( ) Function
MDY( ) Function | MEMLINES( ) Function | MESSAGE( ) Function
MIN( ) Function | MINUTE( ) Function | MLINE( ) Function
MOD( ) Function | MONTH( ) Function | MTON( ) Function

N

NDX( ) Function | NORMALIZE( ) Function | NOT Operator
NOTE Command | NTOM( ) Function | NVL( ) Function

O

OCCURS( ) Function | OLDVAL( ) Function | ON ERROR Command
ON KEY Command | ON( ) Function | OPEN DATABASE Command
OR Operator | ORDER( ) Function | OS( ) Function

P

PACK Command | PADL( ) | PADR( ) | PADC( ) Functions | PARAMETERS Command
PARAMETERS( ) Function | PAYMENT( ) Function | PI( ) Function
PRIMARY( ) Function | PRIVATE Command | PROCEDURE Command
PROGRAM( ) Function | PROPER( ) Function | PUBLIC Command
PV( ) Function |  |

R

RAND( ) Function | RAT( ) Function | RATC( ) Function
RATLINE( ) Function | RECALL Command | RECCOUNT( ) Function
RECNO( ) Function | RECSIZE( ) Function | RELATION( ) Function
REMOVE TABLE Command | REPLACE Command | REPLACE FROM ARRAY Command
REPLICATE( ) Function | RETRY Command | RETURN Command
RIGHT( ) Function | RIGHTC( ) Function | RLOCK( ) Function
ROLLBACK Command | ROUND( ) Function | RTOD( ) Function
RTRIM( ) Function |  |

S

SCAN ... ENDSCAN Command | SCATTER Command | SEC( ) Function
SECONDS( ) Function | SEEK Command | SEEK( ) Function
SELECT - SQL Command | SELECT Command | SELECT( ) Function
SET AUTOINCERROR Command | SET BLOCKSIZE Command | SET COLLATE Command
SET DATABASE Command | SET DEFAULT Command | SET DELETED Command
SET ENGINEBEHAVIOR Command | SET EXACT Command | SET EXCLUSIVE Command
SET FDOW Command | SET FIELDS Command | SET FILTER Command
SET FIXED Command | SET FULLPATH Command | SET FWEEK Command
SET HOURS Command | SET INDEX Command | SET LOCK Command
SET MULTILOCKS Command | SET NEAR Command | SET NOCPTRANS Command
SET NOTIFY Command | SET NULL Command | SET OPTIMIZE Command
SET ORDER Command | SET PATH Command | SET PROCEDURE Command
SET REFRESH Command | SET RELATION Command | SET RELATION OFF Command
SET REPROCESS Command | SET SKIP Command | SET UDFPARMS Command
SET UNIQUE Command | SET VOLUME Command | SET( ) Function
SETFLDSTATE( ) Function | SETRESULTSET( ) Function | SIGN( ) Function
SIN( ) Function | SKIP Command | SORT Command
SPACE( ) Function | SQRT( ) Function | STORE Command
STR( ) Function | STRCONV( ) Function | STRTRAN( ) Function
STUFF( ) Function | STUFFC( ) Function | SUBSTR( ) Function
SUBSTRC( ) Function | SUM Command | SYS(0) - Network Machine Information
SYS(1) - Julian System Date | SYS(2) - Seconds Since Midnight | SYS(3) - Legal File Name
SYS(5) - Default Drive | SYS(10) - String from Julian Day Number | SYS(11) - Julian Day Number
SYS(12) - Available Memory in Bytes | SYS(1104) - Purge Memory Cache | SYS(2001) – SET ... Command Status
SYS(2003) – Current Directory | SYS(2004) – Visual FoxPro Start Directory | SYS(2007) - Checksum Value
SYS(2011) - Current Lock Status | SYS(2015) - Unique Procedure Name | SYS(2029) - Table Type
SYS(3050) - Set Buffer Memory Size |  |

T

_TALLY System Variable | _TRIGGERLEVEL System Variable | TABLEREVERT( ) Function
TABLEUPDATE( ) Function | TAG( ) Function | TAGCOUNT( ) Function
TAGNO( ) Function | TAN( ) Function | TARGET( ) Function
TIME( ) Function | TOTAL Command | TRIM( ) Function
TTOC( ) Function | TTOD( ) Function | TXNLEVEL( ) Function
TYPE( ) Function |  |

U

UNIQUE( ) Function | UNLOCK Command | UPDATE - SQL Command
UPDATE Command | UPPER( ) Function | USE Command
USED( ) Function |  |

V

VAL( ) Function

VERSION( ) Function

W

WEEK( ) Function

X

XMLTOCURSOR( ) Function

XMLUPDATEGRAM( ) Function

Y

YEAR( ) Function

Z

ZAP Command

See Also

Other Resources

Language Reference for OLE DB Development
Visual FoxPro OLE DB Provider Data Support
Unsupported Visual FoxPro Commands and Functions in OLE DB Provider
Supported OLE DB Objects
Standard and Custom OLE DB Properties
OLE DB Provider for Visual FoxPro


Unsupported Visual FoxPro Commands and Functions in OLE DB Provider

Visual FoxPro 9.0
Unsupported Visual FoxPro Commands and Functions in OLE DB Provider
See Also

Certain Visual FoxPro commands and functions are not supported by the OLE DB Provider. The OLE DB Provider supports data-related Visual FoxPro language, and does not support object or user interface language.

The following tables list the most commonly used commands and functions not supported by the OLE DB Provider.

#, ::, !, ?, \, @

#DEFINE ... #UNDEF | #IF ... #ENDIF Preprocessor Directive | #IFDEF | #IFNDEF
#INCLUDE Preprocessor Directive | :: Scope Resolution Operator | ! Command (see RUN | ! Command)
? | ?? Command | ??? Command | \ | \\ Command
@ ... BOX Command | @ ... CLASS Command | @ ... CLEAR Command
@ ... EDIT - Edit Boxes Command | @ ... FILL Command | @ ... GET
@ ... MENU Command | @ ... PROMPT Command | @ ... SAY Command
@ ... SCROLL Command | @ ... TO Command |

A

_ALIGNMENT System Memory Variable | ACCEPT Command | ACLASS( ) Function
ACTIVATE MENU Command | ACTIVATE POPUP Command | ACTIVATE SCREEN Command
ACTIVATE WINDOW Command | ActivateCell Method | ADD CLASS Command
ADIR( ) Function | AFONT( ) Function | AINSTANCE( ) Function
AMEMBERS( ) Function | ANSITOOEM( ) Function | APRINTERS( ) Function
ASELOBJ( ) Function | ASSIST Command | ATAGINFO( ) Function

B

_BEAUTIFY System Memory Variable | _BOX System Memory Variable | _BROWSER System Memory Variable
_BUILDER System Memory Variable | BAR( ) Function | BARCOUNT( ) Function
BARPROMPT( ) Function | BROWSE Command | BUILD APP Command
BUILD EXE Command | BUILD PROJECT Command |

C

_CALCVALUE System Memory Variable | _CLIPTEXT System Memory Variable | _CONVERTER System Memory Variable
_CUROBJ System Memory Variable | CALL Command | CANCEL Command
CAPSLOCK( ) Function | CAST( ) Function | CD Command
CHANGE Command | CHDIR Command | CHRSAW( ) Function
CLOSE MEMO Command | CNTBAR( ) Function | CNTPAD( ) Function
COL( ) Function | COMPILE Command | COMPOBJ( ) Function
Container Object | Control Object | COPY FILE Command
COPY MEMO Command | CREATE CLASS Command | CREATE CLASSLIB Command
CREATE COLOR SET Command | CREATE Command | CREATE CONNECTION Command
CREATE DATABASE Command | CREATE FORM Command | CREATE FROM Command
CREATE LABEL Command | CREATE MENU Command | CREATE PROJECT Command
CREATE QUERY Command | CREATE REPORT Command | CREATE SCREEN Command
CREATE SQL VIEW Command | CREATE TRIGGER Command | CREATE VIEW Command
CREATEOBJECT( ) Function | CURDIR( ) Function |

D

_DBLCLICK System Memory Variable | _DIARYDATE System Memory Variable | DBSETPROP( ) Function
DDE Functions | DEACTIVATE MENU Command | DEACTIVATE POPUP Command
DEACTIVATE WINDOW Command | DECLARE - DLL Command | DECLARE Command
DEFINE BAR Command | DEFINE BOX Command | DEFINE CLASS Command
DEFINE MENU Command | DEFINE PAD Command | DEFINE POPUP Command
DEFINE WINDOW Command | DELETE CONNECTION Command | DELETE DATABASE Command
DELETE FILE Command | DELETE TAG Command | DELETE TRIGGER Command
DELETE VIEW Command | DIR Command | DIRECTORY Command
DISPLAY Command | DISPLAY CONNECTIONS Command | DISPLAY DATABASE Command
DISPLAY DLLS Command | DISPLAY FILES Command | DISPLAY MEMORY Command
DISPLAY OBJECTS Command | DISPLAY PROCEDURES Command | DISPLAY STATUS Command
DISPLAY STRUCTURE Command | DISPLAY TABLES Command | DISPLAY VIEWS Command
DO FORM Command |  |

E

EDIT Command | EJECT Command | EJECT PAGE Command
ERASE Command | ERROR Command | EXPORT Command
EXTERNAL Command |  |

F

_FOXDOC System Memory Variable | _FOXGRAPH System Memory Variable | FCHSIZE( ) Function
FCLOSE( ) Function | FCREATE( ) Function | FEOF( ) Function
FERROR( ) Function | FFLUSH( ) Function | FGETS( ) Function
FILER Command | FIND Command | FKLABEL( ) Function
FKMAX( ) Function | FONTMETRIC( ) Function | FOPEN( ) Function
FPUTS( ) Function | FREAD( ) Function | FSEEK( ) Function
FWRITE( ) Function |  |

G

_GENGRAPH System Memory Variable | _GENMENU System Memory Variable | _GENPD System Memory Variable
_GENSCRN System Memory Variable | _GENXTAB System Memory Variable | GETBAR( ) Function
GETCOLOR( ) Function | GETDIR( ) Function | GETENV( ) Function
GETEXPR Command | GETFILE( ) Function | GETFONT( ) Function
GETOBJECT( ) Function | GETPAD( ) Function | GETPICT( ) Function
GETPRINTER( ) Function |  |

H

HELP Command | HIDE MENU Command | HIDE POPUP Command
HIDE WINDOW Command | HOME( ) Function |

I

_INDENT System Memory Variable | IMESTATUS( ) Function | IMPORT Command
INDEX ON Command | INKEY( ) Function | INPUT Command
INSERT - SQL Command (Applies only to using the SQL INSERT command with an array, memory variable, or an object.) | INSERT Command | INSMODE( ) Function
ISCOLOR( ) Function | ISMOUSE( ) Function |

J

JOIN Command

K

KEYBOARD Command

L

_LMARGIN System Memory Variable | LABEL Command | LASTKEY( ) Function
LINENO( ) Function | LIST Commands | LIST CONNECTIONS Command
LOAD Command | LOCFILE( ) Function |

M

MCOL( ) Function | MD Command | MDOWN( ) Function
MEMORY( ) Function | MENU Command | MENU TO Command
MENU( ) Function | MESSAGEBOX( ) Function | MKDIR Command
MODIFY CLASS Command | MODIFY COMMAND Command | MODIFY CONNECTION Command
MODIFY DATABASE Command | MODIFY FILE Command | MODIFY FORM Command
MODIFY GENERAL Command | MODIFY LABEL Command | MODIFY MEMO Command
MODIFY MENU Command | MODIFY PROCEDURE Command | MODIFY PROJECT Command
MODIFY QUERY Command | MODIFY REPORT Command | MODIFY SCREEN Command
MODIFY STRUCTURE Command | MODIFY VIEW Command | MODIFY WINDOW Command
MOUSE Command | MOVE POPUP Command | MOVE WINDOW Command
MRKBAR( ) Function | MRKPAD( ) Function | MROW( ) Function
MWINDOW( ) Function |  |

N

NEWOBJECT( ) Function

NUMLOCK( ) Function

O

OBJNUM( ) Function | OBJTOCLIENT( ) Function | OBJVAR( ) Function
OEMTOANSI( ) Function | ON APLABOUT Command | ON BAR Command
ON ESCAPE Command | ON EXIT BAR Command | ON EXIT MENU Command
ON EXIT PAD Command | ON EXIT POPUP Command | ON KEY = Command
ON KEY LABEL Command | ON MACHELP Command | ON PAD Command
ON PAGE Command | ON READERROR Command | ON SELECTION BAR Command
ON SELECTION MENU Command | ON SELECTION PAD Command | ON SELECTION POPUP Command
ON SHUTDOWN Command |  |

P

_PADVANCE System Memory Variable | _PAGENO System Memory Variable | _PBPAGE System Memory Variable
_PCOLNO System Memory Variable | _PCOPIES System Memory Variable | _PDRIVER System Memory Variable
_PDSETUP System Memory Variable | _PECODE System Memory Variable | _PEJECT System Memory Variable
_PEPAGE System Memory Variable | _PLENGTH System Memory Variable | _PLINENO System Memory Variable
_PLOFFSET System Memory Variable | _PPITCH System Memory Variable | _PQUALITY System Memory Variable
_PRETEXT System Memory Variable | _PSCODE System Memory Variable | _PSPACING System Memory Variable
_PWAIT System Memory Variable | PACK DATABASE Command | PAD( ) Function
PCOL( ) Function | PEMSTATUS( ) Function | PLAY MACRO Command
POP KEY Command | POP MENU Command | POP POPUP Command
POPUP( ) Function | PRINTJOB ... ENDPRINTJOB Command | PRINTSTATUS( ) Function
PRMBAR( ) Function | PRMPAD( ) Function | PROMPT( ) Function
PROW( ) Function | PRTINFO( ) Function | PUSH KEY Command
PUSH MENU Command | PUSH POPUP Command | PUTFILE( ) Function

Q

QUIT Command

R

_RMARGIN System Memory Variable | RD Command | RDLEVEL( ) Function
READ Command | READ MENU Command | READKEY( ) Function
REFRESH() Function | REINDEX Command | RELEASE BAR Command
RELEASE CLASSLIB Command | RELEASE Command | RELEASE LIBRARY Command
RELEASE MENUS Command | RELEASE MODULE Command | RELEASE PAD Command
RELEASE POPUPS Command | RELEASE PROCEDURE Command | RELEASE WINDOWS Command
REMOVE CLASS Command | RENAME CLASS Command | RENAME Command
RENAME CONNECTION Command | RENAME TABLE Command | RENAME VIEW Command
REPORT FORM Command | REQUERY( ) Function | RESTORE FROM Command
RESTORE MACROS Command | RESTORE SCREEN Command | RESTORE WINDOW Command
RESUME Command | RGB( ) Function | RGBSCHEME( ) Function
RMDIR Command | ROW( ) Function | RUN | ! Command

S

_SCREEN System Memory Variable | _SHELL System Memory Variable | _SPELLCHK System Memory Variable
_STARTUP System Memory Variable | SAVE MACROS Command | SAVE SCREEN Command
SAVE TO Command | SAVE WINDOWS Command | SCHEME( ) Function
SCOLS( ) Function | SCROLL Command | SET ALTERNATE Command
SET APLABOUT Command | SET AUTOSAVE Command | SET BELL Command
SET BLINK Command | SET BORDER Command | SET BRSTATUS Command
SET CARRY Command | SET CLASSLIB Command | SET CLEAR Command
SET CLOCK Command | SET COLOR OF Command | SET COLOR OF SCHEME Command
SET COLOR SET Command | SET COLOR TO Command | SET Command
SET COMPATIBLE Command | SET CONFIRM Command | SET CONSOLE Command
SET CPCOMPILE | SET CPDIALOG | SET CURRENCY Command
SET CURSOR Command | SET DATASESSION Command | SET DATE Command
SET DATE Command | SET DEBUG Command | SET DECIMALS Command
SET DELIMITERS Command | SET DEVELOPMENT Command | SET DEVICE Command
SET DISPLAY Command | SET DOHISTORY Command | SET ECHO Command
SET ESCAPE Command | SET FORMAT Command | SET FUNCTION Command
SET HEADINGS Command | SET HELP Command | SET HELPFILTER Command
SET INTENSITY Command | SET KEY Command | SET KEYCOMP Command
SET LOGERRORS Command | SET MACDESKTOP Command | SET MACHELP Command
SET MACKEY Command | SET MARGIN Command | SET MARK OF Command
SET MARK TO Command | SET MEMOWIDTH Command | SET MESSAGE Command
SET MOUSE Command | SET ODOMETER Command | SET OLEOBJECT Command
SET PALETTE Command | SET PDSETUP Command | SET POINT Command
SET PRINTER Command | SET READBORDER Command | SET REFRESH Command
SET RESOURCE Command | SET SAFETY Command | SET SCOREBOARD Command
SET SECONDS Command | SET SEPARATOR Command | SET SHADOWS Command
SET SKIP OF Command | SET SPACE Command | SET STATUS BAR Command
SET STATUS Command | SET STEP Command | SET STICKY Command
SET SYSFORMATS Command | SET SYSMENU Command | SET TALK Command
SET TEXTMERGE Command | SET TEXTMERGE DELIMITERS Command | SET TOPIC Command
SET TOPIC ID Command | SET TRBETWEEN Command | SET TYPEAHEAD Command
SET VIEW Command | SET WINDOW OF MEMO Command | SET XCMDFILE Command
SHOW GET Command | SHOW GETS Command | SHOW MENU Command
SHOW OBJECT Command | SHOW POPUP Command | SHOW WINDOW Command
SIZE POPUP Command | SIZE WINDOW Command | SKPBAR( ) Function
SKPPAD( ) Function | SOUNDEX( ) Function | SQL functions
SROWS( ) Function | STRTOFILE( ) function | SUSPEND Command
SYSMETRIC( ) Function |  |

T

_TABS System Memory Variable | _THROTTLE System Memory Variable | _TRANSPORT System Memory Variable
TEXT ... ENDTEXT Command | TRANSFORM( ) Function | TXTWIDTH( ) Function
TYPE Command |  |

U

UPDATED( ) Function

V

VALIDATE DATABASE Command

VARREAD( ) Function

W

_WINDOWS System Memory Variable | _WIZARD System Memory Variable | _WRAP System Memory Variable
WAIT Command | WBORDER( ) Function | WCHILD( ) Function
WCOLS( ) Function | WEXIST( ) Function | WFONT( ) Function
WITH ... ENDWITH Command | WLAST( ) Function | WLCOL( ) Function
WLROW( ) Function | WMAXIMUM( ) Function | WMINIMUM( ) Function
WONTOP( ) Function | WOUTPUT( ) Function | WPARENT( ) Function
WREAD( ) Function | WROWS( ) Function | WTITLE( ) Function
WVISIBLE( ) Function |  |

X

Z

ZOOM WINDOW Command

See Also

Other Resources

Language Reference for OLE DB Development
Visual FoxPro OLE DB Provider Data Support
Supported Visual FoxPro Commands and Functions in OLE DB Provider
Supported OLE DB Objects
Standard and Custom OLE DB Properties
OLE DB Provider for Visual FoxPro


Supported OLE DB Objects

Visual FoxPro 9.0
Supported OLE DB Objects
See Also

The Visual FoxPro OLE DB Provider supports the following OLE DB objects that are based on the OLE DB 2.1 Spec. Implementation.

Object | Description
Data Source Object | Establish a link to a data store.
Session Object | Provide methods for creating commands and rowsets and for creating and modifying tables and indexes.
Command Object | Provide collections, properties, and methods for issuing commands and returning rowsets.
Rowset Object | Expose data in a tabular form as rowsets, rows that each contain columns of data.
Error Object | Provides the ability to return multiple error records from a single call and the ability to return provider-specific error information.
ConnectionPage Object | Provides access to a Microsoft DataLink (UDL) Configuration dialog box.

See Also

Other Resources

Language Reference for OLE DB Development
Visual FoxPro OLE DB Provider Data Support
Supported Visual FoxPro Commands and Functions in OLE DB Provider
Unsupported Visual FoxPro Commands and Functions in OLE DB Provider
Standard and Custom OLE DB Properties
OLE DB Provider for Visual FoxPro


Standard and Custom OLE DB Properties

Visual FoxPro 9.0
Standard and Custom OLE DB Properties
See Also

Following is an alphabetical list of OLE DB Properties supported by the Visual FoxPro OLE DB Provider and Visual FoxPro custom properties. Refer to the OLE DB Programmers Reference for detailed descriptions of these properties.

Property | Description
DBPROP_ABORTPRESERVE | Preserve on Abort
DBPROP_ACCESSORDER | Access Order
DBPROP_ACTIVESESSIONS | Active Sessions
DBPROP_ALTERCOLUMN | Alter Column Support
DBPROP_APPENDONLY | Append-Only Rowset
DBPROP_ASYNCTXNABORT | Asynchable Abort
DBPROP_ASYNCTXNCOMMIT | Asynchable Commit
DBPROP_AUTH_CACHE_AUTHINFO | Cache Authentication
DBPROP_AUTH_ENCRYPT_PASSWORD | Encrypt Password
DBPROP_AUTH_INTEGRATED | Integrated Security
DBPROP_AUTH_MASK_PASSWORD | Mask Password
DBPROP_AUTH_PASSWORD | Password
DBPROP_AUTH_PERSIST_ENCRYPTED | Persist Encrypted
DBPROP_AUTH_PERSIST_SENSITIVE_AUTHINFO | Persist Security Info
DBPROP_AUTH_USERID | User ID
DBPROP_BLOCKINGSTORAGEOBJECTS | Blocking Storage Objects
DBPROP_BOOKMARKINFO | Bookmark Information
DBPROP_BOOKMARKS | Use Bookmarks
DBPROP_BOOKMARKSKIPPED | Skip Deleted Bookmarks
DBPROP_BOOKMARKTYPE | Bookmark Type
DBPROP_BYREFACCESSORS | Pass By Ref Accessors
DBPROP_CACHEDEFERRED | Cache Deferred Columns
DBPROP_CANFETCHBACKWARDS | Fetch Backwards
DBPROP_CANHOLDROWS | Hold Rows
DBPROP_CANSCROLLBACKWARDS | Scroll Backwards
DBPROP_CATALOGLOCATION | Catalog Location
DBPROP_CATALOGTERM | Catalog Term
DBPROP_CATALOGUSAGE | Catalog Usage
DBPROP_CHANGEINSERTEDROWS | Change Inserted Rows
DBPROP_COL_AUTOINCREMENT | Autoincrement
DBPROP_COL_DEFAULT | Default
DBPROP_COL_DESCRIPTION | Description
DBPROP_COL_FIXEDLENGTH | Fixed Length
DBPROP_COL_NULLABLE | Nullable
DBPROP_COL_PRIMARYKEY | Primary Key
DBPROP_COL_UNIQUE | Unique
DBPROP_COLUMNDEFINITION | Column Definition
DBPROP_COLUMNRESTRICT | Column Privileges
DBPROP_COMMANDTIMEOUT | Command Time Out
DBPROP_COMMITPRESERVE | Preserve on Commit
DBPROP_CONCATNULLBEHAVIOR | NULL Concatenation Behavior
DBPROP_CURRENTCATALOG | Current Catalog
DBPROP_DATASOURCENAME | Data Source Name
DBPROP_DATASOURCEREADONLY | Read-Only Data Source
DBPROP_DBMSNAME | DBMS Name
DBPROP_DBMSVER | DBMS Version
DBPROP_DEFERRED | Defer Column
DBPROP_DELAYSTORAGEOBJECTS | Delay Storage Object Updates
DBPROP_DSOTHREADMODEL | Data Source Object Threading Model
DBPROP_GROUPBY | GROUP BY Support
DBPROP_HETEROGENEOUSTABLES | Heterogeneous Table Support
DBPROP_IAccessor | IAccessor
DBPROP_IColumnsInfo | IColumnsInfo
DBPROP_IColumnsRowset | IColumnsRowset
DBPROP_IConnectionPointContainer | IConnectionPointContainer
DBPROP_IConvertType | IConvertType
DBPROP_IDENTIFIERCASE | Identifier Case Sensitivity
DBPROP_ILockBytes | ILockBytes
DBPROP_IMMOBILEROWS | Immobile Rows
DBPROP_INDEX_AUTOUPDATE | Auto-Update
DBPROP_INDEX_CLUSTERED | Clustered
DBPROP_INDEX_FILLFACTOR | Fill Factor
DBPROP_INDEX_INITIALSIZE | Initial Size
DBPROP_INDEX_NULLCOLLATION | NULL Collation
DBPROP_INDEX_NULLS | NULL Keys
DBPROP_INDEX_PRIMARYKEY | Primary Key
DBPROP_INDEX_SORTBOOKMARKS | Sort Bookmarks
DBPROP_INDEX_TEMPINDEX | Temporary Index
DBPROP_INDEX_TYPE | Index Type
DBPROP_INDEX_UNIQUE | Unique
DBPROP_INIT_CATALOG | Initial Catalog
DBPROP_INIT_DATASOURCE | Data Source
DBPROP_INIT_HWND | Window Handle
DBPROP_INIT_IMPERSONATION_LEVEL | Impersonation Level
DBPROP_INIT_LCID | Locale Identifier
DBPROP_INIT_LOCATION | Location
DBPROP_INIT_MODE | Mode
DBPROP_INIT_PROMPT | Prompt
DBPROP_INIT_PROTECTION_LEVEL | Protection Level
DBPROP_INIT_PROVIDERSTRING | Extended Properties
DBPROP_INIT_TIMEOUT | Connect Timeout
DBPROP_IProvideMoniker | IProvideMoniker
DBPROP_IRowset | IRowset
DBPROP_IRowsetChange | IRowsetChange
DBPROP_IRowsetCurrentIndex | IRowsetCurrentIndex
DBPROP_IRowsetFind | IRowsetFind
DBPROP_IRowsetIdentity | IRowsetIdentity
DBPROP_IRowsetIndex | IRowsetIndex
DBPROP_IRowsetInfo | IRowsetInfo
DBPROP_IRowsetLocate | IRowsetLocate
DBPROP_IRowsetRefresh | IRowsetRefresh
DBPROP_IRowsetResynch | IRowsetResynch
DBPROP_IRowsetScroll | IRowsetScroll
DBPROP_IRowsetUpdate | IRowsetUpdate
DBPROP_ISequentialStream | ISequentialStream
DBPROP_IStorage | IStorage
DBPROP_IStream | IStream
DBPROP_ISupportErrorInfo | ISupportErrorInfo
DBPROP_LITERALBOOKMARKS | Literal Bookmarks
DBPROP_LITERALIDENTITY | Literal Row Identity
DBPROP_LOCKMODE | Lock Mode
DBPROP_LOCKMODES | Lock Modes
DBPROP_MAXINDEXSIZE | Maximum Index Size
DBPROP_MAXOPENROWS | Maximum Open Rows
DBPROP_MAXPENDINGROWS | Maximum Pending Rows
DBPROP_MAXROWS | Maximum Rows
DBPROP_MAXROWSIZE | Maximum Row Size
DBPROP_MAXROWSIZEINCLUDESBLOB | Maximum Row Size Includes BLOB
DBPROP_MAXTABLESINSELECT | Maximum Tables in SELECT
DBPROP_MAYWRITECOLUMN | Column Writable
DBPROP_MEMORYUSAGE | Memory Usage
DBPROP_MULTIPLEPARAMSETS | Multiple Parameter Sets
DBPROP_MULTIPLERESULTS | Multiple Results
DBPROP_MULTIPLESTORAGEOBJECTS | Multiple Storage Objects
DBPROP_MULTITABLEUPDATE | Multi-Table Update
DBPROP_NOTIFICATIONGRANULARITY | Notification Granularity
DBPROP_NOTIFICATIONPHASES | Notification Phases
DBPROP_NOTIFYCOLUMNSET | Column Set Notification
DBPROP_NOTIFYROWDELETE | Row Delete Notification
DBPROP_NOTIFYROWFIRSTCHANGE | Row First Change Notification
DBPROP_NOTIFYROWINSERT | Row Insert Notification
DBPROP_NOTIFYROWRESYNCH | Row Resynchronization Notification
DBPROP_NOTIFYROWSETFETCHPOSITIONCHANGE | Rowset Fetch Position Change Notification
DBPROP_NOTIFYROWSETRELEASE | Rowset Release Notification
DBPROP_NOTIFYROWUNDOCHANGE | Row Undo Change Notification
DBPROP_NOTIFYROWUNDODELETE | Row Undo Delete Notification
DBPROP_NOTIFYROWUNDOINSERT | Row Undo Insert Notification
DBPROP_NOTIFYROWUPDATE | Row Update Notification
DBPROP_NULLCOLLATION | NULL Collation Order
DBPROP_OLEOBJECTS | OLE Object Support
DBPROP_OPENROWSETSUPPORT | Open Rowset Support
DBPROP_ORDERBYCOLUMNSINSELECT | ORDER BY Columns in Select List
DBPROP_ORDEREDBOOKMARKS | Bookmarks Ordered
DBPROP_OTHERINSERT | Others' Inserts Visible
DBPROP_OTHERUPDATEDELETE | Others' Changes Visible
DBPROP_OUTPUTPARAMETERAVAILABILITY | Output Parameter Availability
DBPROP_OWNINSERT | Own Inserts Visible
DBPROP_OWNUPDATEDELETE | Own Changes Visible
DBPROP_PERSISTENTIDTYPE | Persistent ID Type
DBPROP_PREPAREABORTBEHAVIOR | Prepare Abort Behavior
DBPROP_PREPARECOMMITBEHAVIOR | Prepare Commit Behavior
DBPROP_PROCEDURETERM | Procedure Term
DBPROP_PROVIDERFRIENDLYNAME | Provider Friendly Name
DBPROP_PROVIDERNAME | Provider Name
DBPROP_PROVIDEROLEDBVER | OLE DB Version
DBPROP_PROVIDERVER | Provider Version
DBPROP_QUICKRESTART | Quick Restart
DBPROP_QUOTEDIDENTIFIERCASE | Quoted Identifier Sensitivity
DBPROP_REENTRANTEVENTS | Reentrant Events
DBPROP_REMOVEDELETED | Remove Deleted Rows
DBPROP_REPORTMULTIPLECHANGES | Report Multiple Changes
DBPROP_RETURNPENDINGINSERTS | Return Pending Inserts
DBPROP_ROWRESTRICT | Row Privileges
DBPROP_ROWSETCONVERSIONSONCOMMAND | Rowset Conversions on Command
DBPROP_ROWTHREADMODEL | Row Threading Model
DBPROP_SCHEMATERM | Schema Term
DBPROP_SCHEMAUSAGE | Schema Usage
DBPROP_SERVERCURSOR | Server Cursor
DBPROP_SERVERDATAONINSERT | Server Data on Insert
DBPROP_SERVERNAME | Server Name
DBPROP_SESS_AUTOCOMMITISOLEVELS | Autocommit Isolation Levels
DBPROP_SQLSUPPORT | SQL Support
DBPROP_STRONGIDENTITY | Strong Row Identity
DBPROP_STRUCTUREDSTORAGE | Structured Storage
DBPROP_SUBQUERIES | Subquery Support
DBPROP_SUPPORTEDTXNDDL | Transaction DDL
DBPROP_SUPPORTEDTXNISOLEVELS | Isolation Levels
DBPROP_SUPPORTEDTXNISORETAIN | Isolation Retention
DBPROP_TABLETERM | Table Term
DBPROP_TBL_TEMPTABLE | Temporary Table
DBPROP_TRANSACTEDOBJECT | Objects Transacted
DBPROP_UPDATABILITY | Updatability
DBPROP_USERNAME | User Name
DBPROP_VFPOLEDB_ANSI | SET ANSI
DBPROP_VFPOLEDB_BLOCKSIZE | SET BLOCKSIZE
DBPROP_VFPOLEDB_COLLATE | SET COLLATE setting
DBPROP_VFPOLEDB_Column_Caption | Column Caption
DBPROP_VFPOLEDB_Column_Comment | Column Comment
DBPROP_VFPOLEDB_Column_Default | Default Value
DBPROP_VFPOLEDB_Column_Error |
DBPROP_VFPOLEDB_Column_Format | Format
DBPROP_VFPOLEDB_Column_FormDisplay | DisplayClass
DBPROP_VFPOLEDB_Column_FormPath | DisplayClassLibrary
DBPROP_VFPOLEDB_Column_InputMask | InputMask
DBPROP_VFPOLEDB_Column_RuleExpression | RuleExpression
DBPROP_VFPOLEDB_Column_RuleText | RuleText
DBPROP_VFPOLEDB_DELETED | SET DELETED
DBPROP_VFPOLEDB_EXACT | SET EXACT
DBPROP_VFPOLEDB_INDEX | SET INDEX
DBPROP_VFPOLEDB_INIT_COLLATE | Collating Sequence
DBPROP_VFPOLEDB_NULL | SET NULL
DBPROP_VFPOLEDB_ORDER | SET ORDER
DBPROP_VFPOLEDB_PATH | SET PATH
DBPROP_VFPOLEDB_REPROCESS | SET REPROCESS
DBPROP_VFPOLEDB_Rowset_SP | Stored Procedure
DBPROP_VFPOLEDB_SESS_ID | Internal Session ID
DBPROP_VFPOLEDB_SETDEBUGOUTTO | Debug Output File
DBPROP_VFPOLEDB_SETDEFAULTTO | Default Drive and Folder
DBPROP_VFPOLEDB_SETFULLPATH | Set Fullpath ON/OFF
DBPROP_VFPOLEDB_Table_Comment | Comment
DBPROP_VFPOLEDB_Table_DeleteTrigger | DeleteTrigger
DBPROP_VFPOLEDB_Table_InsertTrigger | InsertTrigger
DBPROP_VFPOLEDB_Table_Path | Path
DBPROP_VFPOLEDB_Table_PrimaryKey | PrimaryKey
DBPROP_VFPOLEDB_Table_RuleExpression | RuleExpression
DBPROP_VFPOLEDB_Table_RuleText | RuleText
DBPROP_VFPOLEDB_Table_UpdateTrigger | UpdateTrigger
DBPROP_VFPOLEDB_UNIQUE | SET UNIQUE

See Also

Other Resources

Language Reference for OLE DB Development
Visual FoxPro OLE DB Provider Data Support
Supported Visual FoxPro Commands and Functions in OLE DB Provider
Unsupported Visual FoxPro Commands and Functions in OLE DB Provider
Supported OLE DB Objects
OLE DB Provider for Visual FoxPro


Backward-Compatible Language Elements

Visual FoxPro 9.0 Language Reference
Backward-Compatible Language Elements
See Also

The following language elements are included for backward compatibility with previous versions of FoxPro.

Controls and Objects Created in Earlier Versions

@ ... BOX Command

@ ... EDIT - Edit Boxes Command

@ ... GET - Check Boxes Command

@ ... GET - Combo Boxes Command

@ ... GET - Command Buttons Command

@ ... GET - List Boxes Command

@ ... GET - Option Buttons Command

@ ... GET - Spinners Command

@ ... GET - Text Boxes Command

@ ... GET - Transparent Buttons Command

@ ... MENU Command

@ ... PROMPT Command

@ ... SAY - Pictures & OLE Objects Command

@ ... SAY Command

@ ... TO Command

_ALIGNMENT System Variable

_ASSIST System Variable

_BOX System Variable

_CUROBJ System Variable

_FOXDOC System Variable

_GENGRAPH System Variable

_GENPD System Variable

_GENSCRN System Variable

_GENXTAB System Variable

_INDENT System Variable

_LMARGIN System Variable

_PADVANCE System Variable

_PBPAGE System Variable

_PCOLNO System Variable

_PCOPIES System Variable

_PDRIVER System Variable

_PDSETUP System Variable

_PECODE System Variable

_PEJECT System Variable

_PEPAGE System Variable

_PLENGTH System Variable

_PLINENO System Variable

_PLOFFSET System Variable

_PPITCH System Variable

_PQUALITY System Variable

_PSCODE System Variable

_PSPACING System Variable

_PWAIT System Variable

_RMARGIN System Variable

_TABS System Variable

_TRANSPORT System Variable

_WRAP System Variable

ACCEPT Command

ANSITOOEM( ) Function

ASSIST Command

CALL Command

CLEAR READ Command

COL( ) Function

ColorScheme Property

CREATE SCREEN - Quick Screen Command

CREATE SCREEN Command

DEFINE BOX Command

ErrorMessage Event

FIND Command

INPUT Command

INSERT Command

JOIN Command

LOAD Command

MDOWN( ) Function

MemoWindow Property

MENU Command

MENU TO Command

Message Event

MODIFY SCREEN Command

OBJNUM( ) Function

OBJVAR( ) Function

OEMTOANSI( ) Function

ON KEY = Command

ON KEY Command

ON READERROR Command

OpenWindow Property

RDLEVEL( ) Function

READ Command

READ MENU Command

ReadActivate Event

ReadBackColor Property

ReadCycle Property

ReadDeactivate Event

ReadForeColor Property

READKEY( ) Function

ReadLock Property

ReadMouse Property

ReadObject Property

ReadSave Property

ReadShow Event

ReadTimeout Property

ReadValid Event

ReadWhen Event

ROW( ) Function

SET BORDER Command

SET BRSTATUS Command

SET CLEAR Command

SET COLOR OF Command

SET COLOR TO Command

SET DEBUG Command

SET DELIMITERS Command

SET DISPLAY Command

SET DOHISTORY Command

SET FORMAT Command

SET INTENSITY Command

SET VOLUME Command

SET WINDOW OF MEMO Command

SHOW GET Command

SHOW GETS Command

SHOW OBJECT Command

SizeBox Property

SYS(100) - Console Setting

SYS(101) - Device Setting

SYS(102) - Printer Setting

SYS(103) - Talk Setting

SYS(15) - Character Translation

SYS(18) - Current Control

SYS(20) - Transform German Text

SYS(2016) - SHOW GETS WINDOW Name

SYS(23) - FoxPro EMS Memory Usage

SYS(24) - EMS Memory Limit

UPDATE Command

UPDATED( ) Function

VARREAD( ) Function

WindowList Property

WREAD( ) Function

ZoomBox Property

See Also

Other Resources

Language Reference


Controls and Objects Created in Earlier Versions

Visual FoxPro 9.0 Language Reference
Controls and Objects Created in Earlier Versions
See Also

This topic describes support for controls and objects created in earlier FoxPro versions. Some controls behave slightly differently depending on whether you are using Visual FoxPro for Windows or Visual FoxPro for Macintosh; by default, controls in Visual FoxPro for Macintosh follow user interface conventions common to Macintosh applications. For example, by default the CheckBox, ComboBox, and OptionButton controls cannot receive the focus in Visual FoxPro for Macintosh. For more details about differences in control behavior, see the topic for the SET KEYCOMP command.

In Visual FoxPro, a NAME clause is available for each of the controls created in previous FoxPro versions. The NAME clause creates an object reference for controls created with @ ... GET and @ ... EDIT and allows you to manipulate the controls with Visual FoxPro properties, events, and methods. The NAME clause provides an intermediate step to upgrade your applications using Visual FoxPro object-oriented programming techniques.

Compatibility with FoxPro 2.x Controls

The following table lists the controls available in earlier FoxPro versions and the base class you can use to programmatically create the same control in Visual FoxPro.

FoxPro 2.x controls | Equivalent VisualFoxPro controls | Visual FoxPro base class names
@ ... GET - Check Boxes | CheckBox Control | CheckBox
@ ... GET - Lists | ListBox Control | ListBox
@ ... GET - Popups | ComboBox Control | ComboBox
@ ... GET - Push Buttons | CommandButton Control | CommandButton
@ ... GET - Radio Buttons | OptionButton Control | OptionButton
@ ... GET - Spinners | Spinner Control | Spinner
@ ... GET - Text Boxes | TextBox Control | TextBox
@ ... EDIT - Text Edit Regions | EditBox Control | EditBox

For a complete list of base classes in Visual FoxPro, see Base Classes in Visual FoxPro.

See Also

Other Resources

CREATE CLASS Command
CREATE FORM Command
DEFINE CLASS Command
Objects, Collections, and Classes
Language Reference
Backward-Compatible Language Elements


@ ... BOX Command

Visual FoxPro 9.0 Language Reference
@ ... BOX Command
See Also

Included for backward compatibility. Use the Shape control instead.

See Also

Other Resources

Language Reference


@ ... EDIT - Edit Boxes Command

Visual FoxPro 9.0 Language Reference
@ ... EDIT - Edit Boxes Command
See Also

Included for backward compatibility. Use the EditBox Control instead.

See Also

Other Resources

Language Reference


@ ... GET - Check Boxes Command

Visual FoxPro 9.0 Language Reference
@ ... GET - Check Boxes Command
See Also

Included for backward compatibility. Use the CheckBox Control instead.

See Also

Other Resources

Language Reference


@ ... GET - Combo Boxes Command

Visual FoxPro 9.0 Language Reference
@ ... GET - Combo Boxes Command
See Also

Included for backward compatibility. Use the ComboBox Control instead.

See Also

Other Resources

Language Reference


@ ... GET - Command Buttons Command

Visual FoxPro 9.0 Language Reference
@ ... GET - Command Buttons Command
See Also

Included for backward compatibility. Use the CommandButton Control instead.

See Also

Other Resources

Language Reference


@ ... GET - List Boxes Command

Visual FoxPro 9.0 Language Reference
@ ... GET - List Boxes Command
See Also

Included for backward compatibility. Use the ListBox Control instead.

See Also

Other Resources

Language Reference


@ ... GET - Option Buttons Command

Visual FoxPro 9.0 Language Reference
@ ... GET - Option Buttons Command
See Also

Included for backward compatibility. Use the OptionGroup Control instead.

See Also

Other Resources

Language Reference


@ ... GET - Spinners Command

Visual FoxPro 9.0 Language Reference
@ ... GET - Spinners Command
See Also

Included for backward compatibility. Use the Spinner Control instead.

See Also

Other Resources

Language Reference


@ ... GET - Text Boxes Command

Visual FoxPro 9.0 Language Reference
@ ... GET - Text Boxes Command
See Also

Included for backward compatibility. Use the TextBox Control instead.

See Also

Other Resources

Language Reference


@ ... GET - Transparent Buttons Command

Visual FoxPro 9.0 Language Reference
@ ... GET - Transparent Buttons Command
See Also

Included for backward compatibility. Use the CommandButton Control instead.

See Also

Other Resources

Language Reference


@ ... MENU Command

Visual FoxPro 9.0 Language Reference
@ ... MENU Command
See Also

Included for backward compatibility. Use the Menu and Shortcut Designers and CREATE MENU Command instead.

See Also

Other Resources

Language Reference


@ ... PROMPT Command

Visual FoxPro 9.0 Language Reference
@ ... PROMPT Command
See Also

Included for backward compatibility. Use the Menu and Shortcut Designers and CREATE MENU Command instead.

See Also

Other Resources

Language Reference


@ ... SAY - Pictures & OLE Objects Command

Visual FoxPro 9.0 Language Reference
@ ... SAY - Pictures & OLE Objects Command
See Also

Included for backward compatibility. Use the Image Control, OLE Bound Control, and OLE Container Control instead.

See Also

Other Resources

Language Reference


@ ... SAY Command

Visual FoxPro 9.0 Language Reference
@ ... SAY Command
See Also

Included for backward compatibility. Use the Label Control to display text and the TextBox Control to display the contents of fields and variables.

See Also

Other Resources

Language Reference


@ ... TO Command

Visual FoxPro 9.0 Language Reference
@ ... TO Command
See Also

Included for backward compatibility. Use the Shape Control instead.

See Also

Other Resources

Language Reference


_ALIGNMENT System Variable

Visual FoxPro 9.0 Language Reference
_ALIGNMENT System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_ASSIST System Variable

Visual FoxPro 9.0 Language Reference
_ASSIST System Variable
See Also

Included for backward compatibility. Use the DO Command instead.

See Also

Other Resources

Language Reference


_BOX System Variable

Visual FoxPro 9.0 Language Reference
_BOX System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_CUROBJ System Variable

Visual FoxPro 9.0 Language Reference
_CUROBJ System Variable
See Also

Included for backward compatibility. Use the ActiveControl Property for new forms instead.

See Also

Other Resources

Language Reference


_FOXDOC System Variable

Visual FoxPro 9.0 Language Reference
_FOXDOC System Variable
See Also

Included for backward compatibility. Use the Documenting Wizard instead.

See Also

Other Resources

Language Reference


_GENGRAPH System Variable

Visual FoxPro 9.0 Language Reference
_GENGRAPH System Variable
See Also

Included for backward compatibility. Use the Graph Wizard instead.

See Also

Other Resources

Language Reference


_GENPD System Variable

Visual FoxPro 9.0 Language Reference
_GENPD System Variable
See Also

Included for backward compatibility. Use the TO FILE ASCII argument in REPORT.

See Also

Other Resources

Language Reference


_GENSCRN System Variable

Visual FoxPro 9.0 Language Reference
_GENSCRN System Variable
See Also

Included for backward compatibility. Use the Form Designer instead.

See Also

Other Resources

Language Reference


_GENXTAB System Variable

Visual FoxPro 9.0 Language Reference
_GENXTAB System Variable
See Also

Included for backward compatibility. Use the Cross-tab Wizard instead.

See Also

Other Resources

Language Reference


_INDENT System Variable

Visual FoxPro 9.0 Language Reference
_INDENT System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference
System Variables Overview


_LMARGIN System Variable

Visual FoxPro 9.0 Language Reference
_LMARGIN System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PADVANCE System Variable

Visual FoxPro 9.0 Language Reference
_PADVANCE System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PBPAGE System Variable

Visual FoxPro 9.0 Language Reference
_PBPAGE System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PCOLNO System Variable

Visual FoxPro 9.0 Language Reference
_PCOLNO System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PCOPIES System Variable

Visual FoxPro 9.0 Language Reference
_PCOPIES System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PDRIVER System Variable

Visual FoxPro 9.0 Language Reference
_PDRIVER System Variable
See Also

Included for backward compatibility. Use the TO FILE ASCII argument in REPORT.

See Also

Other Resources

Language Reference


_PDSETUP System Variable

Visual FoxPro 9.0 Language Reference
_PDSETUP System Variable
See Also

Included for backward compatibility. Use the TO FILE ASCII argument in REPORT.

See Also

Other Resources

Language Reference


_PECODE System Variable

Visual FoxPro 9.0 Language Reference
_PECODE System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PEJECT System Variable

Visual FoxPro 9.0 Language Reference
_PEJECT System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PEPAGE System Variable

Visual FoxPro 9.0 Language Reference
_PEPAGE System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PLENGTH System Variable

Visual FoxPro 9.0 Language Reference
_PLENGTH System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PLINENO System Variable

Visual FoxPro 9.0 Language Reference
_PLINENO System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PLOFFSET System Variable

Visual FoxPro 9.0 Language Reference
_PLOFFSET System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PPITCH System Variable

Visual FoxPro 9.0 Language Reference
_PPITCH System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PQUALITY System Variable

Visual FoxPro 9.0 Language Reference
_PQUALITY System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PSCODE System Variable

Visual FoxPro 9.0 Language Reference
_PSCODE System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PSPACING System Variable

Visual FoxPro 9.0 Language Reference
_PSPACING System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_PWAIT System Variable

Visual FoxPro 9.0 Language Reference
_PWAIT System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_RMARGIN System Variable

Visual FoxPro 9.0 Language Reference
_RMARGIN System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_TABS System Variable

Visual FoxPro 9.0 Language Reference
_TABS System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


_TRANSPORT System Variable

Visual FoxPro 9.0 Language Reference
_TRANSPORT System Variable
See Also

Included for backward compatibility.

See Also

Other Resources

Language Reference


_WRAP System Variable

Visual FoxPro 9.0 Language Reference
_WRAP System Variable
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


ACCEPT Command

Visual FoxPro 9.0 Language Reference
ACCEPT Command
See Also

Included for backward compatibility. Use the TextBox Control instead.

See Also

Other Resources

Language Reference


ANSITOOEM( ) Function

Visual FoxPro 9.0 Language Reference
ANSITOOEM( ) Function
See Also

Included for backward compatibility. Use GETCP( ) instead.

See Also

Other Resources

Language Reference


ASSIST Command

Visual FoxPro 9.0 Language Reference
ASSIST Command
See Also

Included for backward compatibility. Use the DO Command instead.

See Also

Other Resources

Language Reference


CALL Command

Visual FoxPro 9.0 Language Reference
CALL Command
See Also

Included for backward compatibility. Use SET LIBRARY instead.

See Also

Other Resources

Language Reference


COL( ) Function

Visual FoxPro 9.0 Language Reference
COL( ) Function
See Also

Included for backward compatibility. Use the CurrentX, CurrentY Properties.

See Also

Other Resources

Language Reference


ColorScheme Property

Visual FoxPro 9.0 Language Reference
ColorScheme Property
See Also

Included for backward compatibility. Use the BackColor, ForeColor Properties instead.

See Also

Other Resources

Language Reference


CREATE SCREEN - Quick Screen Command

Visual FoxPro 9.0 Language Reference
CREATE SCREEN - Quick Screen Command

Included for backward compatibility. Use the Form Designer instead.


CREATE SCREEN Command

Visual FoxPro 9.0 Language Reference
CREATE SCREEN Command
See Also

Included for backward compatibility. Use CREATE FORM instead.

See Also

Other Resources

Language Reference


DEFINE BOX Command

Visual FoxPro 9.0 Language Reference
DEFINE BOX Command
See Also

Included for backward compatibility. Use the Report Designer instead.

See Also

Other Resources

Language Reference


ErrorMessage Event

Visual FoxPro 9.0 Language Reference
ErrorMessage Event
See Also

Included for backward compatibility with FoxPro 2.x. Use the Valid Event instead.

See Also

Other Resources

Language Reference


FIND Command (Visual FoxPro)

Visual FoxPro 9.0 Language Reference
FIND Command (Visual FoxPro)
See Also

Included for backward compatibility. Use SEEK instead.

See Also

Other Resources

Language Reference


INPUT Command

Visual FoxPro 9.0 Language Reference
INPUT Command
See Also

Included for backward compatibility. Use the TextBox control instead.

See Also

Other Resources

Language Reference


INSERT Command

Visual FoxPro 9.0 Language Reference
INSERT Command
See Also

Included for backward compatibility. Use APPEND or INSERT - SQL instead.

See Also

Other Resources

Language Reference


JOIN Command

Visual FoxPro 9.0 Language Reference
JOIN Command
See Also

Included for backward compatibility. Use SELECT - SQL instead.

See Also

Other Resources

Language Reference


LOAD Command

Visual FoxPro 9.0 Language Reference
LOAD Command
See Also

No longer available. Use SET LIBRARY instead.

See Also

Other Resources

Language Reference


MDOWN( ) Function

Visual FoxPro 9.0 Language Reference
MDOWN( ) Function
See Also

Included for backward compatibility. Use the Click, MouseDown, MouseUp, and RightClick events instead.

See Also

Other Resources

Language Reference


MemoWindow Property

Visual FoxPro 9.0 Language Reference
MemoWindow Property
See Also

Included for backward compatibility. Use an EditBox control instead.

See Also

Other Resources

Language Reference


MENU TO Command

Visual FoxPro 9.0 Language Reference
MENU TO Command
See Also

Included for backward compatibility. Use the Visual FoxPro Menu Designer instead.

See Also

Other Resources

Language Reference


Message Event

Visual FoxPro 9.0 Language Reference
Message Event
See Also

Included for backward compatibility. Use the StatusBarText property instead.

See Also

Other Resources

Language Reference


MODIFY SCREEN Command

Visual FoxPro 9.0 Language Reference
MODIFY SCREEN Command
See Also

Included for backward compatibility. Use MODIFY FORM instead.

See Also

Other Resources

Language Reference


OBJNUM( ) Function

Visual FoxPro 9.0 Language Reference
OBJNUM( ) Function
See Also

Included for backward compatibility. Use the TabIndex Property for controls instead.

See Also

Other Resources

Language Reference


OBJVAR( ) Function

Visual FoxPro 9.0 Language Reference
OBJVAR( ) Function
See Also

Included for backward compatibility. Use the Name property for controls instead.

See Also

Other Resources

Language Reference


OEMTOANSI( ) Function

Visual FoxPro 9.0 Language Reference
OEMTOANSI( ) Function
See Also

Included for backward compatibility. Use the GETCP( ) Function instead.

See Also

Other Resources

Language Reference


ON KEY = Command

Visual FoxPro 9.0 Language Reference
ON KEY = Command
See Also

Included for backward compatibility. Use ON KEY LABEL instead.

See Also

Other Resources

Language Reference


ON KEY Command

Visual FoxPro 9.0 Language Reference
ON KEY Command
See Also

Included for backward compatibility. Use ON KEY LABEL instead.

See Also

Other Resources

Language Reference


ON READERROR Command

Visual FoxPro 9.0 Language Reference
ON READERROR Command
See Also

Included for backward compatibility. Use the Valid event instead.

See Also

Other Resources

Language Reference


OpenWindow Property

Visual FoxPro 9.0 Language Reference
OpenWindow Property
See Also

Included for backward compatibility. Use an EditBox control instead.

See Also

Other Resources

Language Reference


RDLEVEL( ) Function

Visual FoxPro 9.0 Language Reference
RDLEVEL( ) Function
See Also

Included for backward compatibility. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


READ MENU Command

Visual FoxPro 9.0 Language Reference
READ MENU Command
See Also

Included for backward compatibility. Use the Menu Designer to create menus.

See Also

Other Resources

Language Reference


ReadActivate Event

Visual FoxPro 9.0 Language Reference
ReadActivate Event
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadBackColor, ReadForeColor Properties

Visual FoxPro 9.0 Language Reference
ReadBackColor, ReadForeColor Properties
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadCycle Property

Visual FoxPro 9.0 Language Reference
ReadCycle Property
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadDeactivate Event

Visual FoxPro 9.0 Language Reference
ReadDeactivate Event
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


READKEY( ) Function

Visual FoxPro 9.0 Language Reference
READKEY( ) Function
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadLock Property

Visual FoxPro 9.0 Language Reference
ReadLock Property
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadMouse Property

Visual FoxPro 9.0 Language Reference
ReadMouse Property
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadObject Property

Visual FoxPro 9.0 Language Reference
ReadObject Property
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadSave Property

Visual FoxPro 9.0 Language Reference
ReadSave Property
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadShow Event

Visual FoxPro 9.0 Language Reference
ReadShow Event
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadTimeout Property

Visual FoxPro 9.0 Language Reference
ReadTimeout Property
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadValid Event

Visual FoxPro 9.0 Language Reference
ReadValid Event
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


ReadWhen Event

Visual FoxPro 9.0 Language Reference
ReadWhen Event
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


SET BORDER Command

Visual FoxPro 9.0 Language Reference
SET BORDER Command
See Also

Included for backward compatibility. Use the BorderStyle Property instead.

See Also

Other Resources

Language Reference


SET BRSTATUS Command

Visual FoxPro 9.0 Language Reference
SET BRSTATUS Command
See Also

Included for backward compatibility. Use the StatusBarText Property instead.

See Also

Other Resources

Language Reference


SET CLEAR Command

Visual FoxPro 9.0 Language Reference
SET CLEAR Command
See Also

Included for backward compatibility. Use the Refresh Method instead.

See Also

Other Resources

Language Reference


SET COLOR OF Command

Visual FoxPro 9.0 Language Reference
SET COLOR OF Command
See Also

Included for backward compatibility. Use SET COLOR OF SCHEME instead.

See Also

Other Resources

Language Reference


SET COLOR TO Command

Visual FoxPro 9.0 Language Reference
SET COLOR TO Command
See Also

Included for backward compatibility. Use SET COLOR OF SCHEME instead.

See Also

Other Resources

Language Reference


SET DEBUG Command

Visual FoxPro 9.0 Language Reference
SET DEBUG Command
See Also

Included for backward compatibility. Makes the Debug and Trace windows either available or unavailable from the Visual FoxPro menu system in versions prior to 5.0.

SET DEBUG ON | OFF

Parameters

ON

(Default) Makes the Debug and Trace windows either available or unavailable from the Visual FoxPro menu system.
OFF

Makes the Debug and Trace windows unavailable from the Visual FoxPro system menu. However, when SET DEBUG is set to OFF, you can open the Debug window with SET ECHO ON or ACTIVATE WINDOW DEBUG, and you can open the Trace window with SET STEP ON or ACTIVATE WINDOW TRACE.

Remarks

For more information on using the Trace and Debug windows, see Testing and Debugging Applications.

See Also

Other Resources

CLEAR DEBUG Command
DEBUG Command
SET_ECHO Command
SET Command Overview
Commands
Language Reference


SET DELIMITERS Command

Visual FoxPro 9.0 Language Reference
SET DELIMITERS Command
See Also

Included for backward compatibility. Use the Format Property instead.

See Also

Other Resources

Language Reference


SET DISPLAY Command

Visual FoxPro 9.0 Language Reference
SET DISPLAY Command
See Also

Included for backward compatibility. Use the font properties of the _SCREEN System Variable instead.

See Also

Other Resources

Language Reference


SET DOHISTORY Command

Visual FoxPro 9.0 Language Reference
SET DOHISTORY Command
See Also

Included for backward compatibility. Use the Trace Window instead.

See Also

Other Resources

Language Reference


SET FORMAT Command

Visual FoxPro 9.0 Language Reference
SET FORMAT Command
See Also

Included for backward compatibility. Use the Format Property instead.

See Also

Other Resources

Language Reference


SET INTENSITY Command

Visual FoxPro 9.0 Language Reference
SET INTENSITY Command
See Also

Included for backward compatibility. Use SET COLOR OF SCHEME instead.

See Also

Other Resources

Language Reference


SET VOLUME Command

Visual FoxPro 9.0 Language Reference
SET VOLUME Command
See Also Example

Included for backward compatibility. Maps MS-DOS drive designators (A:, B:, C:, and so on) to volumes or folders in FoxPro for Macintosh.

Copy Code
SET VOLUME cMS-DOSDrive TO [cMacintoshPath]

Parameters

cMS-DOSDrive

Specifies an MS-DOS drive designator, and can be any letter from A through Z. The drive delimiter colon, as in A: or C:, is optional.
cMacintoshPath

Specifies a volume name, a volume name with a folder name, a nested folder, or Macintosh shorthand notation (: or ::) or MS-DOS shorthand notation (\ or ..). If cMacintoshPath includes a volume or folder name that contains a space, cMacintoshPath must be enclosed in quotation marks. If you include a path in cMacintoshPath that is not fully qualified, the path is relative to the current default folder.

Remarks

Most effective in FoxPro for Macintosh.

SET VOLUME helps move applications created in FoxPro for MS-DOS and Visual FoxPro to FoxPro for Macintosh. For every occurrence of a specified MS-DOS drive designator, FoxPro for Macintosh internally substitutes the Macintosh volume or folder you designate.

When you start FoxPro for Macintosh, there is no default volume or folder designation. However, you can specify a default volume or folder in your Visual FoxPro configuration file with the VOLUME configuration item.

Use DISPLAY STATUS to display the current volume or folder mapping.

Example

The following commands map every occurrence of an MS-DOS C drive to a Macintosh volume named MacHD or Mac HD:

Copy Code
SET VOLUME C: TO MacHD:
SET VOLUME C: TO 'Mac HD:'
SET VOLUME C TO 'Mac HD:'

You can also specify a folder with a Macintosh volume:

Copy Code
SET VOLUME C: TO MacHD:FolderOne
SET VOLUME C TO 'MacHD:Folder One'

You can use MS-DOS and Macintosh shorthand notation as well. To map every occurrence of an MS-DOS C drive to the current Macintosh volume, issue the following command:

Copy Code
SET VOLUME C TO \

To map every occurrence of an MS-DOS C drive to the FoxPro for Macintosh startup volume, issue SET VOLUME without cMacintoshPath:

Copy Code
SET VOLUME C TO

See Also

Other Resources

SYS(5) – Default Drive
SYS(2003) – Current Directory


SET WINDOW OF MEMO Command

Visual FoxPro 9.0 Language Reference
SET WINDOW OF MEMO Command
See Also

Included for backward compatibility. Use the TextBox Control instead.

See Also

Other Resources

Language Reference


SHOW GET Command

Visual FoxPro 9.0 Language Reference
SHOW GET Command
See Also

Included for backward compatibility. Use the Refresh method to redisplay a control after changing the control's properties.

See Also

Other Resources

Language Reference


SHOW GETS Command

Visual FoxPro 9.0 Language Reference
SHOW GETS Command
See Also

Included for backward compatibility. Use the Refresh method to redisplay all controls on a form or formset after changing the control's properties.

See Also

Other Resources

Language Reference


SHOW OBJECT Command

Visual FoxPro 9.0 Language Reference
SHOW OBJECT Command
See Also

Included for backward compatibility. Use the Refresh method to redisplay a control after changing the control's properties.

See Also

Other Resources

Language Reference


SYS(100) - Console Setting

Visual FoxPro 9.0 Language Reference
SYS(100) - Console Setting
See Also Example

Included for backward compatibility. Use SET("CONSOLE") instead.

Copy Code
SYS(100)

Return Values

Character

Example

Copy Code
IF SYS(100) != 'ON'
   SET CONSOLE ON
ENDIF

See Also

Other Resources

SET CONSOLE Command
SYS( ) Functions Overview
PREVIEW clause is not allowed with OFF/NOCONSOLE or TO PRINT/FILE (Error 1681)
SET( ) Function


SYS(101) - Device Setting

Visual FoxPro 9.0 Language Reference
SYS(101) - Device Setting
See Also Example

Included for backward compatibility. Use SET("DEVICE") instead.

Copy Code
SYS(101)

Return Values

Character

Example

Copy Code
IF SYS(101) != 'SCREEN'
   SET DEVICE TO SCREEN
ENDIF

See Also

Other Resources

SET DEVICE
SYS( ) Functions Overview
SYS(100) - Console Setting
SYS(102) - Printer Setting
SET( ) Function


SYS(102) - Printer Setting

Visual FoxPro 9.0 Language Reference
SYS(102) - Printer Setting
See Also Example

Included for backward compatibility. Use SET("PRINTER") instead.

Copy Code
SYS(102)

Return Values

Character

Example

Copy Code
IF SYS(102) != 'OFF'
   SET PRINTER OFF
ENDIF

See Also

Other Resources

SET PRINTER
SYS( ) Functions Overview
GETPRINTER( )
SET( ) Function


SYS(103) - Talk Setting

Visual FoxPro 9.0 Language Reference
SYS(103) - Talk Setting
See Also Example

Included for backward compatibility. Use SET("TALK") instead.

Copy Code
SYS(103)

Return Values

Character

Example

Copy Code
IF SYS(103) != 'ON'
   SET TALK ON
ENDIF

See Also

Other Resources

SET TALK
SYS( ) Functions Overview
SET( ) Function


WindowList Property

Visual FoxPro 9.0 Language Reference
WindowList Property
See Also

Included for backward compatibility with READ. Use the Form Designer instead of READ.

See Also

Other Resources

Language Reference


TerminateRead Property

Visual FoxPro 9.0 Language Reference
TerminateRead Property
See Also

Included for backward compatibility with the READ command.

See Also

Other Resources

Language Reference


UPDATE Command

Visual FoxPro 9.0 Language Reference
UPDATE Command
See Also

Included for backward compatibility. Use UPDATE - SQL instead.

See Also

Other Resources

Language Reference


UPDATED( ) Function

Visual FoxPro 9.0 Language Reference
UPDATED( ) Function
See Also

Included for backward compatibility. Use the InteractiveChange event or ProgrammaticChange event instead.

See Also

Other Resources

Language Reference


VARREAD( ) Function

Visual FoxPro 9.0 Language Reference
VARREAD( ) Function
See Also

Included for backward compatibility in Visual FoxPro. Use the ControlSource property or Name property instead.

See Also

Other Resources

Language Reference


User Interface Reference (Visual FoxPro)

Visual FoxPro 9.0
User Interface Reference (Visual FoxPro)

User interface (UI) reference topics explain the options that appear on various dialog boxes, windows, and other user interface elements. These topics generally appear when you press F1 in a dialog box or window.

In This Section

Builders

Describes the builders included in Visual FoxPro and how you can use them for controls, forms, and for creating referential integrity between database tables.
Designers

Discusses designers, which make it possible for you to design the windows, dialog boxes, and components in your application visually.
Dialog Boxes

Explains the options that appear on various Visual FoxPro dialog boxes.
Task Pane Manager

Describes the Task Pane Manager, which contains information and exposes essential tasks for easy use. Individual panes can contain static or dynamic information, gather content from the Internet, expose wizards to accomplish routine tasks, display Help, and present samples. You can create customized panes that can be shared with other users.
Toolbox

Describes the Visual FoxPro Toolbox, which displays items used in the creation of applications. Items are displayed in toolsets (collections of tools) by category.
Wizards

Discusses the Visual FoxPro wizards, which are interactive programs that help you quickly accomplish common tasks such as creating forms, formatting reports, setting up queries, importing and upsizing data, publishing in HTML, and so on.
Windows

Describes the options that appear on various dialog boxes, windows, and other user interfaces.

Related Sections

Reference

Includes topics on productivity tools, as well as the controls, objects, properties, methods, events, statements, functions, and constants available.
General Reference

Includes Visual FoxPro related technical information, including file types, file structures, and other reference information about Visual FoxPro elements.
Error Messages

Provides information about some of the more common error messages in Visual FoxPro.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks.
Programming in Visual FoxPro

Discusses how you can access the full power of Visual FoxPro by creating applications. Understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity.


Builders

Visual FoxPro 9.0
Builders

Builders are tools that aid in setting properties of controls on a form. Unlike wizards, builders are reentrant, so you can reopen a builder on a particular control repeatedly.

Visual FoxPro includes a number of generic builders for many of the common form controls including grids, list boxes, combo boxes, check boxes, command groups, and option groups.

Visual FoxPro offers a wide selection of builders. For details, consult the list below.

In This Section

How to: Use Builders

Provides instructions for creating controls and using the builders.
Application Builder

Displays a tabbed dialog box to simplify creating and modifying forms, complex controls, and other optional elements of effective and satisfying applications.
AutoFormat Builder

Allows you to apply a set of styles to selected controls of the same type.
Combo Box Builder

Makes it easy for you to set properties for a Combo Box control.
Command Group Builder

Makes it easy for you to set properties for a Command Group control.
CursorAdapter Builder

Makes it easy for you to build CursorAdapter objects more quickly.
DataEnvironment Builder

Makes it easy for you to build DataEnvironment objects that use the capabilities of CursorAdapter objects.
Edit Box Builder

Makes it easy for you to set properties for an Edit Box control.
Form Builder

Makes it easy for you to add fields as new controls to a form.
Grid Builder

Makes it possible for you to set properties for a Grid control.
List Box Builder

Makes it easy for you to set properties for a List Box control.
Option Group Builder

Makes it easy for you to set properties for an Option Group control.
Referential Integrity Builder

Helps you to ensure referential integrity by setting up triggers to control how records are inserted, updated, or deleted in related tables.
Text Box Builder

Makes it easy for you to set properties for a Text Box control.
XML Web Service Builder

Makes it possible for you to bind an XML Web service to a control on a Visual FoxPro form or to an object, such as a cursor adapter in the form's data environment, without writing code.

Related Sections

User Interface Reference

Explains the options that appear on various dialog boxes, windows, and other user interfaces. These types of topics generally appear when you press F1 in a dialog box or window.
Creating Applications with the Application Framework

Explains how to create applications with the Application Framework using the Application Wizard and the Application Builder.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.


How to: Use Builders

Visual FoxPro 9.0
How to: Use Builders
See Also

You can use builders for some controls, for forms, for formatting controls, and for creating referential integrity between database tables.

To build a control

  • From the Form Controls toolbar, choose the Builder Lock button. Each time you add a new control to a form, Visual FoxPro displays the appropriate builder.

    -or-

  • Select a control on the form, and choose the Builder button in the Properties window.

To use the Form Builder

  • From the Form menu, choose Quick Form.

When you have several controls on a form, you can format them all at the same time with the AutoFormat Builder.

To format several controls

  1. In the Form Designer, select controls.

  2. From the Form Designer Toolbar, choose the AutoFormat button.

When a builder is displayed, select the options for each tab and then choose OK to register the changes.

See Also

Other Resources

Builders


Application Builder

Visual FoxPro 9.0
Application Builder
See Also

The Application builder tabbed dialog box simplifies creating and modifying forms, complex controls, and other optional, elements of effective and satisfying applications.

To use the Application builder

  1. On the Tools menu, point to Wizards, and then click All Wizards. The Wizard Selection dialog box appears.

  2. In the Wizard Selection dialog box, choose Application Builder.

The Application builder integrates with the application framework files created by the Application Wizard so you can build a complete application without having to write code. You also can do the following:

  • Add, edit, or remove such application-specific components as tables, forms, and reports.

  • Specify visual styles for forms and reports.

  • Add common application elements including a splash screen, an About dialog box, a Favorites menu, a User Login dialog box, and a standard toolbar.

  • Specify production credits and version information for the application.

  • View table files in a database from the Data tab.

As in all Visual FoxPro builders, the Application builder is reentrant, meaning that you can close it and then reopen it to modify any settings the builder makes. You can reopen the Application builder by right-clicking the project and selecting Builder.

Note:
Additional changes made by means of the builder will not appear in the application until the application is rebuilt.

For more information, see Creating Applications with the Application Framework.

Builder Tabs

General

Specifies the application name and other optional features such as splash screen, startup form, and the type of application.

Credits

Specifies application production credits such as author, company, version, copyright, and trademark.

Data

Specifies the data source and the format for forms and reports you include in your application.

Forms

Specifies menu types, the menu from which a form is called, toolbars, and whether a form can be instanced multiple times.

Reports

Specifies friendly names for reports in your application.

Advanced

Specifies the Help file name and the default directory for your application. You can also specify the inclusion of a standard toolbar and a Favorites menu in your application.

See Also

Other Resources

Builders
Application Framework Files
Application Wizard
Advanced Tab, Application Builder
Credits Tab, Application Builder
Data Tab, Application Builder
Forms Tab, Application Builder
General Tab, Application Builder
Reports Tab, Application Builder


General Tab, Application Builder

Visual FoxPro 9.0
General Tab, Application Builder
See Also

On this tab of the Application builder, you specify the application name and such other optional features as splash screen, startup form, and the type of application.

Name

Specifies the friendly name of your application used in the application title bar, About dialog box, and throughout your application.
Image

Specifies the file name and the location of the image used in the splash screen and the About dialog box of your application. You can use icon (.ico) files shipped in your Visual FoxPro \Graphics\ICO folder or such other graphic files as .bmp, .gif, or .jpg files.

Application Type

The following option buttons enable you to specify the way your application runs:

Normal

Application will run in the main Visual FoxPro window, taking over the entire Visual FoxPro environment including the system menu.
Module

Application is added to an existing project or called from another application. The application adds a single menu pad and menu to the existing system menu, and therefore functions as a component of another application.
Note:
Because modules do not issue READ EVENTS or alter existing Visual FoxPro environment settings, they function well when called by other applications or at design time in the Visual FoxPro development environment. For more information, see READ EVENTS Command.

Top-Level

Application will run on the Microsoft Windows-based desktop. With top-level applications, the Visual FoxPro-based desktop is not necessarily visible. Provides a Windows multiple-document interface (MDI) with more flexibility than _SCREEN because you can subclass it. For more information, see _SCREEN System Variable.

Common Dialogs

The following check boxes let you include certain dialog boxes in your application:

Splash Screen

Specifies whether the application starts by displaying the image file designated in the Image field and credits in an opening screen.
Quick Start form

Specifies whether to use a Quick Start form that provides access to application documents and other disk files. You might use this to route users through the application.
About dialog

Specifies whether an About dialog box appears in the application.
User Logins

Specifies whether the application prompts for user password login and maintains preference information for multiple users, such as Options dialog box settings and Favorites menu contents.
Icon

Specifies the graphic that appears in the main desktop (_SCREEN) of typical applications, in the top form frame of top-level applications, and in the title bar of forms to which you have not assigned a specific icon.

If you choose OK, the builder closes, applying the property settings from all tabs.

See Also

Other Resources

Application Builder
Creating Applications with the Application Framework


Credits Tab, Application Builder

Visual FoxPro 9.0
Credits Tab, Application Builder
See Also

On this tab of the Application builder, you can specify application production credits such as author, company, version, copyright, and trademark. This information will appear in the splash screen and the About dialog box.

Author

Specifies the name of the application author.
Company

Specifies the name of the company writing or using the application.
Version

Specifies the build edition of the application.
Copyright

Specifies any copyright information.
Trademark

Specifies any trade or service mark.

Because these entries are retained as text, you can enter any information you want — up to 50 characters — and not only information prompted by the tab option labels.

If you choose OK, the builder closes, applying the property settings from every tab.

See Also

Other Resources

Application Builder
Creating Applications with the Application Framework


Data Tab, Application Builder

Visual FoxPro 9.0
Data Tab, Application Builder
See Also

On this tab of the Application builder, you can specify the data source and the format for forms and reports you include in your application. The grid displays the tables you select for your application.

Database Wizard

Makes it possible to create a new database for your application using the Database wizard. When the wizard closes, the tables and views in the new database are listed in the grid.
Table Wizard

Makes it possible to create a new table for your application using the Table wizard. When the wizard closes, the tables and views in the new database are listed in the grid.
Select

Makes it possible to select an existing database, table, or view to use in your application.
Clear

Removes all tables from the grid.
Generate

Generates new reports or forms from the selected table, for all checked forms or reports, in the specified form style or report style.
Form Style

Makes it possible to select a form style to use for one or more tables listed in the grid.
Report Style

Makes it possible to select a report style for one or more tables listed in the grid. To use different styles for each form or report, select the forms or reports and the styles, and then generate the reports. Repeat this procedure for as many different styles as you want in your application.

If you choose OK, the builder closes, applying the property settings from all tabs.

See Also

Other Resources

Application Builder
Creating Applications with the Application Framework


Forms Tab, Application Builder

Visual FoxPro 9.0
Forms Tab, Application Builder
See Also

On this tab of the Application builder, you can specify menu types, the menu from which a form is called, toolbars, and whether a form can be instanced multiple times.

For each form listed, check the options you want to apply.

Name

Makes it possible to specify the friendly name for the selected form.
Add

Makes it possible to select a form to add to your application. When you select a form to add, the check box options are enabled. Application Builder automatically creates a list of all the forms you generated in the Application Builder Data tab.
Edit

Makes it possible to modify the selected form in the Form designer. You might want to do this to modify the size or shape of images in a form. For more information, see Form Designer.
Remove

Removes a form from your application.
Single Instance

Specifies whether you can open only a single instance of a form in the application. If you do not check this box, you can open the same form on different records in order to make comparisons.
Use Navigation Toolbar

Specifies that the builder include a navigation toolbar for the selected form.
Use Navigation Menu

Specifies that the builder include a navigation menu for the selected form.
Appear in File New dialog

Specifies that the form name appears in the built application's New dialog box.
Appear in File Open dialog

Specifies that the form name appears in the built application's Open dialog box.

If you choose OK, the builder closes, applying the property settings from all tabs.

See Also

Other Resources

Application Builder
Creating Applications with the Application Framework


Reports Tab, Application Builder

Visual FoxPro 9.0
Reports Tab, Application Builder
See Also

On this tab of the Application builder, you can specify friendly names for reports in your application.

Name

Makes it possible to specify the friendly name for the selected report.
Appear in Print Reports dialog

Specifies whether the friendly name of the selected report appears in the Print Reports dialog box of your application.
Add

Makes it possible to add an existing report to your application.
Edit

Makes it possible to edit the selected report in the Report designer. For more information, see Report Designer.
Remove

Removes the selected report from your application.

If you choose OK, the builder closes, applying the property settings from all tabs.

See Also

Other Resources

Application Builder
Creating Applications with the Application Framework


Advanced Tab, Application Builder

Visual FoxPro 9.0
Advanced Tab, Application Builder
See Also

On this tab of the Application builder, you can specify the Help file name and the default directory for your application. You can also specify the inclusion of a standard toolbar and a Favorites menu in your application.

Help file

Makes it possible to specify the name and path to the Help file for your application.
Default data directory

Makes it possible to specify the default directory for the data files of your application. If you specify this directory before you select your data source, it can make it easier to specify multiple tables.

Menus

Standard toolbar

Specifies whether the standard toolbar appears in your application.
Favorites menu

Specifies whether the Favorites menu is available from your application.
Cleanup

Runs a routine to reconcile any changes that have been made in the Application Builder with the active project.

If you choose OK, the builder closes, applying the property settings from all tabs.

See Also

Other Resources

Application Builder
Creating Applications with the Application Framework


AutoFormat Builder

Visual FoxPro 9.0
AutoFormat Builder
See Also

The AutoFormat builder of the Form designer applies a set of styles to selected controls of the same type. For example, you can select two or more text box controls on the form and use the AutoFormat builder to apply the same styles; or you can specify whether the styles apply to all or just some of the controls' borders, colors, fonts, layout, or 3D effect.

To use the AutoFormat builder

  1. From the New menu, choose Form, and then click New file. At this point, you can manually build your form or you can immediately use the Autoformat Builder shortcut.

To start by manually building your form

  1. Using the Form Controls toolbar, place multiple controls of the same kind on the form.

  2. Select and right-click all the controls you want to format, and then choose Builder from the Form Designer shortcut menu.

    A dialog box appropriate to the selected control appears.

  3. Choose the options you want from the dialog box, and then choose OK.

    When you choose OK, the builder closes and applies the selected configuration.

To start with the Autoformat builder

  1. In the open Form designer, on the Form Designer toolbar, select the Autoformat icon.

  2. When the Autoformat builder opens, choose a style from the listed options, and clear any items you want to leave unformatted.

  3. Click OK.

You can specify whether to use Embossed, Standard, or Professional style. When you click a style, the display to the left is updated to show you how the style looks. You can apply Style to the following:

Borders

Applies the selected style to the control borders. This option corresponds to the BorderStyle property.
Colors

Applies the selected style to the control colors. This option corresponds to the BackColor and ForeColor properties, the BackStyle property, and the BorderColor property.
Fonts

Applies the selected style to the control fonts.
Layout

Applies the selected style to the control alignment.
3D Effect

Applies the selected style to the control 3D effect.
Apply Now

Applies the style to the selected controls without leaving the AutoFormat Builder.

See Also

Other Resources

Builders
BackColor, ForeColor Properties
BackStyle Property
BorderColor Property
BorderStyle Property


Combo Box Builder

Visual FoxPro 9.0
Combo Box Builder
See Also

The Combo Box builder of the Form designer makes it easy to set properties for a combo box control. You set properties by choosing options from the Combo Box Builder dialog box.

To use the Combo Box builder

  1. From the New menu, choose Form, and then click New file.

  2. Using the Form Controls toolbar, place one or more combo box controls on the form.

  3. Select and right-click all the combo box controls you want to format, and then choose Builder from the Form Designer shortcut menu.

  4. Choose the options on each tab of the dialog box that appears, and then choose OK.

    When you choose OK, the builder closes, applying the property settings to the control.

Builder Tabs

List Items

Specifies items from a table, an array, or manual selection to appear in the combo box.
Style

Specifies Style and SpecialEffect properties of the control, including 3D or plain style, drop-down combo or list, and single-key or incremental searching.
Layout

Specifies the control width and column widths properties.
Value

Specifies which column returns a value and where to store it.

See Also

Other Resources

Builders
ComboBox Control
Layout Tab, Combo Box Builder
List Items Tab, Combo Box Builder
Style Tab, Combo Box Builder
Value Tab, Combo Box Builder


List Items Tab, Combo Box Builder

Visual FoxPro 9.0
List Items Tab, Combo Box Builder
See Also

This tab in the Combo Box builder specifies items that go into the combo box.

Fill the List With

Specifies the kind of data with which to fill the combo box list. The selection you make here determines which choices appear on this tab. Choose Fields From a Table or View, Data Entered by Hand, or Values From an Array.
Fields From a Table or View

Allows you to select free tables or tables and views from a database to use in the combo box.
Databases and Tables

Lists the available databases and gives the option to select Free Tables. To find a database or table, click the dialog button, which displays the Open dialog box. This option appears when you have selected Fields From a Table or View in the Fill the List With drop-down list.
List of Tables

Displays tables and views in the selected database, or free tables. This option appears when you have selected Fields From a Table or View in the Fill the List With drop-down list.
Available Fields

Shows all fields in the selected table or view. Select the fields whose data you want in your combo box. This option appears when you have selected Fields From a Table or View in the Fill the List With drop-down list.
Arrow Buttons

Adds fields to and removes fields from the Selected Fields box. This option appears when you have selected Fields From a Table or View in the Fill the List With drop-down list. You also can double-click an item to move it between lists.
Selected Fields

Displays the fields that will be used to fill the combo box list. The order of the fields selected will correspond to the order of the columns in the combo box. This option appears when you have selected Fields From a Table or View in the Fill the List With drop-down list.
Data Entered By Hand

Allows you to select the number of columns to be displayed in the combo box and enter the information to be displayed.
Columns

Specifies the number of columns in the combo box list. This option appears when you have selected Data Entered By Hand in the Fill the List With drop-down list.
Column Grid

Displays the columns in which to enter data. Type the data in the column cells. You can size the columns by dragging the lines between them with the mouse. This option appears when you have selected Data Entered By Hand in the Fill the List With drop-down list.
Values From An Array

Allows you to use data from an array within the combo box.
Array Name

Specifies the name of an array. This option appears when you have selected Values From An Array in the Fill the List With drop-down list.
Entire Array

Specifies that the entire array will fill the combo box list. This option appears when you have selected Values From An Array in the Fill the List With drop-down list.
Range Of The Array

Specifies that a part of the array will fill the combo box list based on the column and row settings. This option appears when you have selected Values From An Array in the Fill the List With drop-down list.
Column and Row Range

Specifies the starting and ending column and row as the array range. These options are only available when you select Range of the Array. This option appears when you have selected Values From An Array in the Fill the List With drop-down list.

See Also

Other Resources

Combo Box Builder
ControlSource Property
Layout Tab, Combo Box Builder
Open Dialog Box
RowSource Property
RowSourceType Property
Style Tab, Combo Box Builder
Value Tab, Combo Box Builder


Style Tab, Combo Box Builder

Visual FoxPro 9.0
Style Tab, Combo Box Builder
See Also

This tab in the Combo Box builder specifies special effects, drop-down combo, drop-down list, and incremental searching support for the combo box.

Three-dimensional

Specifies a left and top edge highlight and a right and lower edge shadow for the combo box.
Plain

Specifies that the combo box is an unshadowed box on the form. Three-dimensional and Plain determine the value of the SpecialEffect property.
Drop-down Combo

Specifies that the combo box will be a drop-down combo, where the user can click the drop-down arrow to see a list of choices or enter a new item directly in the text box. This option corresponds to setting the Style property to 0.
Drop-down List

Specifies that the combo box will be a drop-down list, where the user may select only from the list. This option corresponds to setting the Style property to 2.
Yes, Enable Incremental Searching

Specifies whether the control tries to match an item in the list as the user types each letter. This option corresponds to setting the IncrementalSearch property.
No, Don't Enable Incremental Searching

Disables incremental searching so that each keystroke initiates a search for a beginning character.

See Also

Other Resources

Combo Box Builder
IncrementalSearch Property
List Items Tab, Combo Box Builder
Layout Tab, Combo Box Builder
Style Property
Value Tab, Combo Box Builder


Layout Tab, Combo Box Builder

Visual FoxPro 9.0
Layout Tab, Combo Box Builder
See Also

This tab in the Combo Box builder controls column width and display.

Adjust the Width of the Combo Box to Display All Columns

Specifies that all selected columns will display even if the open combo box must extend beyond the form boundary. This controls the Width property of the combo box.
Column Grid

Controls the values in the ColumnWidths property. You can adjust the column width by dragging the right edge of a column heading with the mouse. Double-click a column heading to hide the column. The grid shows actual data if it is available. If no data is available, the grid displays a message to that effect. To change column order, return to the List Items tab, remove the fields, and add them back in the desired order.

See Also

Other Resources

Combo Box Builder
List Items Tab, Combo Box Builder
Style Tab, Combo Box Builder
Value Tab, Combo Box Builder


Value Tab, Combo Box Builder

Visual FoxPro 9.0
Value Tab, Combo Box Builder
See Also

This tab in the Combo Box builder specifies where to get return values and where to store them.

Return the Value From

Specifies the column whose value is stored to a table field when the user selects a combo box item. This option corresponds to the BoundColumn property.
Field Name

Specifies a table or view field in which to store the value specified in the ReturntheValueFrom box. By default, the list includes fields from tables in the data environment. Choose the dialog button to display the Open dialog box so you can select another table. This option corresponds to the ControlSource property. For example, if you fill the combo box with a list of 50 states, when the user chooses a state, you could write it to the STATE field of an address table.

See Also

Other Resources

BoundColumn Property
Combo Box Builder
ControlSource Property
Layout Tab, Combo Box Builder
List Items Tab, Combo Box Builder
Open Dialog Box
Style Tab, Combo Box Builder


Command Group Builder

Visual FoxPro 9.0
Command Group Builder
See Also

The Command Group builder makes it easy to set properties for a command group control. You set properties by selecting options in the Command Group Builder dialog box.

To use the Command Group builder

  1. Using the Form Controls toolbar, place a command group control on a form.

  2. Select and right-click the command group control, and then choose Builder from the Form Designer shortcut menu.

    A dialog box appropriate to the selected control appears.

  3. Choose the options you want from the dialog box, and then choose OK.

    When you choose OK, the builder closes, applying the property settings from every tab.

Builder Tabs

Buttons

Specifies the number of buttons and the Caption and Picture properties of each.
Layout

Specifies button layout (vertical or horizontal), spacing, and border style by controlling the Height and Width properties of the command group.
Note:
Command buttons may have captions, or graphics, or both. You can also specify graphics to be displayed when the button is disabled and when it is pressed, but you must do so programmatically or in the Properties window. For more details, see the DisabledPicture and DownPicture properties.

See Also

Other Resources

Builders
Buttons Tab, Command Group Builder
CommandButton Control
CommandGroup Control
Layout Tab, Command Group Builder
Properties Window


Buttons Tab, Command Group Builder

Visual FoxPro 9.0
Buttons Tab, Command Group Builder
See Also

This tab in the Command Group builder specifies the number of buttons and their captions and graphics.

Number of Buttons

Specifies the number of buttons the command group will have. This option corresponds to the ButtonCount property. Range is from 0 to 100.
Caption Column

Specifies the caption to go on the button. Type the caption in the grid cell. This option corresponds to the Caption property.
Graphic Column

Specifies the path and file name of the bitmap to display on the button. Type the path and file name in the box, or click the dialog button to display the Open dialog box so you can select a file. This picture will be displayed on the command button all the time, regardless of the button's state. This option corresponds to the Picture property. Buttons automatically resize to accommodate new captions and pictures. The group container also automatically resizes, and neighboring buttons are repositioned, if necessary, to preserve desired spacing.

See Also

Other Resources

ButtonCount Property
Caption Property
Command Group Builder
DisabledPicture Property
DownPicture Property
Layout Tab, Command Group Builder
Picture Property
Properties Window


Layout Tab, Command Group Builder

Visual FoxPro 9.0
Layout Tab, Command Group Builder
See Also

This tab in the Command Group builder specifies button layout (vertical or horizontal), spacing, and border style.

Button Layout

Specifies vertical or horizontal layout of command group buttons. You can also customize the location of buttons within a Command Group by selecting Edit from the shortcut menu and dragging buttons within the Command Group boundary. Return to Command Group editing by first clicking outside the Command Group boundary. If you have customized the button layout, neither Vertical nor Horizontal is selected. If you then select Vertical or Horizontal, the buttons snap into alignment and you lose the custom pattern. Choose Cancel to retrieve the custom pattern.
Spacing Between Buttons

Specifies spacing between buttons. If you have customized the button spacing, this option is disabled. If you snap the buttons into horizontal or vertical alignment, this option is enabled.
Border Style

Specifies a single-line border or no border around the command group.

See Also

Other Resources

Buttons Tab, Command Group Builder
Command Group Builder
Edit Box Builder
Combo Box Builder


CursorAdapter Builder

Visual FoxPro 9.0
CursorAdapter Builder
See Also

The CursorAdapter Builder makes it possible for you to build CursorAdapter objects more quickly. You can open the CursorAdapter Builder from the Form Designer or Class Designer.

To open the CursorAdapter Builder from the Form Designer

  1. Create a new form or open an existing form.

  2. In the Form Designer, right-click the form, and click DataEnvironment.

    For a form with an empty DataEnvironment object, the Open dialog box appears.

  3. In the Open dialog box, click Cancel.

  4. Right-click the Data Environment surface, and click Builder.

  5. In the DataEnvironment Builder, click the Cursors tab to make it visible.

  6. To create a new CursorAdapter object, click New.

You can now set properties for the CursorAdapter object you created, add a CursorAdapter object from a class library, or edit an existing CursorAdapter object.

You can also open the CursorAdapter Builder from a form by right-clicking an existing CursorAdapter object in the form's Data Environment and clicking Builder.

To open the CursorAdapter Builder from the Class Designer

  1. In the Class Designer, create a new CursorAdapter class or open an existing CursorAdapter class.

  2. Right-click the new or existing CursorAdapter class and select Builder.

Builder Tabs

Properties

Specifies the properties of the CursorAdapter object.
Data Access

Specifies how the CursorAdapter object retrieves data from the data source.
Auto-Update

Specifies how the CursorAdapter object updates records automatically in the data source.

See Also

Other Resources

Builders
Class Designer
CursorAdapter Class
DataEnvironment Builder
Form Designer


Properties Tab, CursorAdapter Builder

Visual FoxPro 9.0
Properties Tab, CursorAdapter Builder
See Also

Displays the name and properties of the CursorAdapter class and specifies whether to use the Data Environment data source and use connection settings only in the builder.

Class

Displays the name of the class the CursorAdapter object is based on. The class can be the base class, the CursorAdapter object, or a class in a class library or program file, in which case, the file name and path are also displayed.
Name

Specifies the name assigned to the CursorAdapter object by the builder. You can change this name.
Alias

Specifies the alias assigned to the CursorAdapter object by the builder. The default name is the same as the one that appears in the Name box. You can change this name.
Note:
Make sure that the alias is unique at run time. The CursorAdapter CursorFill method fails if a table or cursor using the same alias name is already open. For more information, see CursorFill Method.

Use DataEnvironment data source

Specifies whether you want to use the data source of the DataEnvironment object. When the CursorAdapterDataSourceType property is "ADO", you should not select this check box unless the DataEnvironment object contains only one CursorAdapter that uses this data source.
Use connection settings in builder only

Specifies whether you want to use connection settings only in the builder. If you select this option, you need to add code to set up a custom connection environment at run time. Selecting this option makes it possible to have a connection open at design time so that you can select tables, build queries, and so forth.
Data source type

Specifies a data source type. Depending on the data source type selected, you can select or build one of the following data sources:
  • ADO

    Specifies one of the following ways to establish an ActiveX Data Objects (ADO) connection.

    Use existing ADO Recordset Specify a reference to a valid ADO RecordSet object. This reference must be valid at design time if the CursorAdapter Builder is to use this RecordSet.

    Use DSN Specifies a data source name (DSN) from the Data source list and values in the User ID and Password boxes, if applicable.

    In most cases, selecting a DSN for an ADO connection results in using the Open Database Connectivity (ODBC) driver specified by the DSN through the MSDASQL OLE DB Provider for ODBC. Certain OLE DB providers can map the ODBC DSN settings to the corresponding settings in the corresponding OLE DB provider.

    Note:
    You should not use a DSN name if the OLE DB provider cannot map ODBC DSN settings. You can use an ODBC driver for a data source that does not have an OLE DB provider.

    Use connection string Specifies a valid connection string. This is the same type of connection string that you enter for the ADO ConnectionString property.

    Alternatively, you can display the Data Link Properties dialog box by clicking Build. You can then select the appropriate OLE DB Provider and other necessary connection string parameters.

  • Native

    Specifies a valid database name and path in the Database box. You can select a database to use by clicking the ellipsis (...) button to display the Select Database dialog box.

  • ODBC

    Specifies one of the following ways to establish a database connection.

    Use existing connection handle Specifies a property, memory variable, value, or expression that evaluates to a valid connection handle at run time.

    Use DSN Specifies a data source name (DSN) from the Data source list and values in the User ID and Password boxes, if applicable.

    Use connection string Specifies a valid connection string. This is the same type of connection string that you enter for the SQLSTRINGCONNECT( ) function. For more information, see SQLSTRINGCONNECT( ) Function.

  • XML

    Specifies XML as the data source.

See Also

Other Resources

Auto-Update Tab, CursorAdapter Builder
CursorAdapter Builder
Data Access Tab, CursorAdapter Builder


Data Access Tab, CursorAdapter Builder

Visual FoxPro 9.0
Data Access Tab, CursorAdapter Builder
See Also

Sets the Select command and CursorAdapter object schema values and other data access properties.

Select command

Type or construct an appropriate Select command. When the data source type is XML, type the Select command. In this case, the Select command should be an expression that resolves to a valid and well-formed XML string. When the data source type is Native, ODBC, or ADO, the Build button is available. Clicking the Build button opens the Select Command Builder dialog box. Select Command Builder Specifies tables and fields to include in the Select command.
  • Table Specifies a table you want to use. The tables in the list correspond to the tables in the selected data source.

  • Add table Available when the data source type is Native and can be used to add tables not in the current database to the table list.

  • Available fields list Specifies fields to include in the Select command after selecting a table, or view, if appropriate. This list appears on the left side of the Select Command Builder dialog box.

  • Add single/Add all/Remove single/Remove all Adds a single field or all fields to the selected fields list or removes a single or all fields from the selected fields list.

  • Selected fields list Displays selected fields, which can be reorganized by clicking and dragging the mover buttons that appear along the left side of the selected fields list. This list appears on the right side of the Select Command Builder dialog box.

Schema

Type the schema for the CursorAdapter object, if needed. The schema is generated automatically when the Select command is constructed using the Select Command Builder. If you typed the Select command, you can click the Build button, and the builder attempts to construct the schema by matching the table and column names with the available tables. When the data source type is XML, you cannot build a Select command, and no schema is automatically generated. When you click the Build button, the Open dialog box appears, and you can specify an XML file from which to build the schema. This XML file must be a valid XML Schema Definition (XSD) schema, a valid XML with inline XSD schema, or a valid XML with reference to a valid external XSD schema.
Use CursorSchema when filling cursor

Specifies the default setting to use for the lUseCursorSchema parameter in the CursorFill Method. For more information, see UseCursorSchema Property.
Data fetching

Specifies properties relating to how to retrieve remote data when using the Open Database Connectivity (ODBC) data source type. The following settings are available:
  • Number of records to fetch at a time Retrieve all or a number of records at a time. For more information, see FetchSize Property.

  • Maximum number of records to fetch Retrieve all or a maximum number of records. For more information, see MaxRecords Property.

  • Use memo when character field length >= Use memo field size when character field length exceeds the specified value. For more information, see UseMemoSize Property.

  • Fetch remote data as needed Retrieve data only when needed. For more information, see FetchAsNeeded Property.

  • Precompile SQL on backend server Specifies whether to prepare SQL statements for subsequent REQUERY( ) function calls. For more information, see Prepared Property and REQUERY( ) Function.

  • Map Varchar Enables default data type mapping from ODBC and ADO data types to the Visual FoxPro Varchar data type. For more information, see MapVarchar Property.

  • Initially open with no data Specifies the default setting to use for the lNoData parameter in the CursorFill Method. For more information, see NoData Property.

  • Fetch memo fields Specifies whether to retrieve memo fields. For more information, see FetchMemo Property.

  • Memo… Brings up the Memo Fetching dialog box.

  • Allow simultaneous fetch Specifies whether to permit simultaneous data retrieval. For more information, see AllowSimultaneousFetch Property.

  • Map Binary Enables default data type mapping from ODBC and ADO data types to the Visual FoxPro Varbinary and Blob data types. For more information, see MapBinary Property.

The Memo Fetching Properties dialog box lets you specify how the DelayedMemoFetch Method fetches Memo fields. The following settings are available:
  • Memo fetch command Specifies the commands to use for the Memo fields fetch performed by the DelayedMemoFetch method. For more information, see FetchMemoCmdList Property.

  • Memo fetch data source type Specifies the data source type used for the DelayedMemoFetch method. For more information, see FetchMemoDataSourceType Property.

  • Connection Settings These three option buttons let you specify the data source for the DelayedMemoFetch method. For more information, see FetchMemoDataSource Property.

Buffer mode override

Specifies a buffer mode. Optimistic row buffering Allows edits to a single record and locks the record only when written to disk. This is the default setting. Optimistic table buffering Allows edits to all records and does not lock them until written to disk.
Break on error

Specifies whether to permit errors to break program execution at the location where they occurred or send them to the CursorAdapter object. For more information, see BreakOnError Property.
XML flags

Specifies the flag settings to pass to the XMLUPDATEGRAM( ) function, which is called when the data source type is XML and updating occurs. For more information about automatic updating, see Data Access Management Using CursorAdapters and XMLUPDATEGRAM( ) Function.

See Also

Other Resources

Auto-Update Tab, CursorAdapter Builder
CursorAdapter Builder
Properties Tab, CursorAdapter Builder


Auto-Update Tab, CursorAdapter Builder

Visual FoxPro 9.0
Auto-Update Tab, CursorAdapter Builder
See Also

Specifies how the CursorAdapter object automatically updates records in the data source. For more information about CursorAdapter objects, see CursorAdapter Class.

Send updates

Specifies whether the CursorAdapter object is available for updating. Send updates is selected by default.
Auto-update

Specifies whether to enable automatic updating capability for the CursorAdapter object.
Advanced

Displays the Advanced Update Properties dialog box, which contains four tabs: Update, Delete, Insert, and Conflict. The Update, Delete, and Insert tabs allow you to specify the following information:
  • Allow (update/delete/insert)

    Specifies whether to permit the update, delete, or insert operation. This option is selected by default.

  • Update/Delete/Insert command

    Specifies a custom update/delete/insert command text. These commands can be SQL UPDATE/ DELETE/INSERT statements, stored procedure names, calls to custom methods or procedures, and so forth.

  • Update data source type

    Specifies an appropriate data source type if you need a different data source type for your Update/Insert/Delete commands.

    Note:
    When you select ADO or ODBC, you must also enter data source information as specified on the Properties tab.

The Conflict tab allows you to specify the following information:
  • Conflict check type Specifies how to handle conflict checking during an update or delete operation. For more information, see ConflictCheckType Property.

  • Conflict check command Specifies a custom command to use for checking update or delete conflicts. For more information, see ConflictCheckCmd Property.

Refresh

Displays the Refresh Properties dialog box, which contains four tabs: Record Refresh, Fields Refresh, Refresh After Insert, and Refresh After Update. The Record Refresh tab allows you to specify the following information:
  • Refresh command Specifies the command to use for the record Refresh performed by the RecordRefresh Method. For more information, see RefreshCmd Property.

  • Refresh data source type Specifies the data source type used for the RecordRefresh method. Depending on the data source type selected, you can select or build a specific data source (see Properties Tab, CursorAdapter Builder for more details on these options). For more information, see RefreshCmdDataSourceType Property.

The Fields Refresh tab allows you to specify the following information:
  • Refresh timestamp Specifies if the fields selected in the fields list are automatically refreshed when an Insert or Update command is executed. For more information, see RefreshTimeStamp Property.

  • Fields list Specifies a list of fields that are ignored by the refresh process when the RecordRefresh Method is executed. For more information, see RefreshIgnoreFieldList Property.

The Refresh After Insert/Update tabs allow you to specify the following information:
  • Insert/Update refresh command Specifies the command to automatically refresh the record after an Insert/Update command is executed. For more information, see InsertCmdRefreshCmd Property and UpdateCmdRefreshCmd Property.

  • Fields list Specifies the fields in the cursor to refresh after an Insert/Update command is executed. You can also specify key fields used. For more information, see InsertCmdRefreshFieldList Property, InsertCmdRefreshKeyFieldList Property, UpdateCmdRefreshFieldList Property and UpdateCmdRefreshKeyFieldList Property.

  • Refresh all fields Enables all fields in the list to be refreshed.

Tables

Specifies a comma-delimited list of tables for updating. The builder usually supplies the table list.
Key field column (key symbol)

Displays check boxes for selecting primary key fields. This column is available only when Auto-update is selected.
Automatic updating column (pencil symbol)

Displays check boxes for selecting fields for automatic updating. This column is available only when Auto-update is selected.
Cursor field

Displays the fields available for automatic updating. This column is available only when Auto-update is selected.
Update name

Specifies the field names, as tableName.FieldName, used for automatic updating. This column is available only when Auto-update is selected. For more information, see UpdateNameList Property.
Update all fields

Specifies that all fields are selected and updated automatically. You must still specify a key field.
Update using

Specifies the preferred update method: SQL UPDATE or SQL DELETE then INSERT. For more information, see UPDATE - SQL Command, DELETE - SQL Command, and INSERT - SQL Command.
SQL WHERE clause includes

Specifies the type of WHERE clause used for updating: key fields only, key and updatable fields, key and modified fields, or key and timestamp. For more information, see the WhereType property.
Batch update count

Sets the BatchUpdateCount property value. For more information, see BatchUpdateCount Property.
Compare memo

Sets the CompareMemoproperty value to either on or off. For more information, see CompareMemo Property.
Use transactions

Specifies if the CursorAdapter uses transactions when sending Insert, Update or Delete commands through ADO or ODBC. For details, see the UseTransactions Property.
Timestamp fields

Specifies the timestamp fields in the cursor. For details, see the TimestampFieldList Property.
Conversion functions

Specifies a comma-delimited list of field name and function name pairs separated by spaces. For details, see the ConversionFunc Property.
UpdateGram schema

Specifies the mapping schema name and location passed to the XMLUPDATEGRAM( ) function. This setting applies only when the CursorAdapter DataSourceType is "XML". For details, see the UpdateGramSchemaLocation Property.

See Also

Other Resources

CursorAdapter Builder
Data Access Tab, CursorAdapter Builder
Properties Tab, CursorAdapter Builder


DataEnvironment Builder

Visual FoxPro 9.0
DataEnvironment Builder
See Also

The DataEnvironment Builder makes it possible for you to build DataEnvironment objects that use the capabilities of CursorAdapter objects. You can open the DataEnvironment Builder in the Form Designer or Class Designer.

To open the DataEnvironment Builder

  1. Create a new form or open an existing form.

  2. In the Form Designer, right-click the form, and click DataEnvironment.

    For a form with an empty DataEnvironment object, the Open dialog box appears.

  3. In the Open dialog box, click Cancel.

  4. Right-click the Data Environment surface, and click Builder.

You can now use the builder to create DataEnvironment objects.

You can also open the DataEnvironment Builder by right-clicking a new or existing DataEnvironment class in the Class Designer and selecting Builder.

Builder Tabs

Data Source Tab, DataEnvironment Builder

Specifies the data source type and data source for the DataEnvironment object.

Cursors Tab, DataEnvironment Builder

Adds, creates, or removes CursorAdapter objects from the DataEnvironment object. You can also open the CursorAdapter Builder to edit existing CursorAdapter objects.

See Also

Other Resources

Builders
DataEnvironment Object
Form Designer
Class Designer
CursorAdapter Builder


Data Source Tab, DataEnvironment Builder

Visual FoxPro 9.0
Data Source Tab, DataEnvironment Builder
See Also

Specifies the data source type and data source to use, if needed.

Note:
When accessing tables in Microsoft Access, particularly tables that have spaces in column names, you should use the Microsoft OLE DB Provider for Access instead of the Microsoft Access ODBC driver and specify ADO as the data source type. To choose the OLE DB Provider for Access, on the Data Source tab, select ADO in the Data source type box. Click Use connection string, then the Build button to continue constructing the connection string to the Access database.

Data source type

Specifies the data source type. Depending on the data source type selected, you can select or build one of the following data sources:
  • ADO

    Specifies one of the following ways to establish an ActiveX Data Objects (ADO) connection.

    Use existing ADO Recordset Specify a reference to a valid ADO RecordSet object. This reference must be valid at design time if the CursorAdapter Builder is to use this RecordSet.

    Use DSN Specifies a data source name (DSN) from the Data source list and values in the User ID and Password boxes, if applicable.

    In most cases, selecting a DSN for an ADO connection results in using the Open Database Connectivity (ODBC) driver specified by the DSN through the MSDASQL OLE DB Provider for ODBC. Certain OLE DB providers can map the ODBC DSN settings to the corresponding settings in the corresponding OLE DB provider.

    Note:
    You should not use a DSN name if the OLE DB provider cannot map ODBC DSN settings. You can use an ODBC driver for a data source that does not have an OLE DB provider.

    Use connection string Specifies a valid connection string. This is the same type of connection string that you enter for the ADO ConnectionString property.

    Alternatively, you can select the Build button to display the Data Link Properties dialog box. You can then select the appropriate OLE DB Provider and other necessary connection string parameters.

  • Native

    Specifies a valid database name and path in the Database box. You can browse for and select a database to use by clicking the ellipsis (...) button to display the Select Database dialog box.

  • ODBC

    Specifies one of the following ways to establish a database connection.

    Use existing connection handle Specifies a property, memory variable, value, or expression that evaluates to a valid connection handle at run time.

    Use DSN Specify a data source name (DSN) from the Data source list and values in the User ID and Password boxes, if applicable.

    Use connection string Specifies a valid connection string. This is the same type of connection string that you enter for the SQLSTRINGCONNECT( ) function. For more information, see SQLSTRINGCONNECT( ) Function.

  • XML

    Specifies XML as the data source.

See Also

Other Resources

DataEnvironment Builder
Cursors Tab, DataEnvironment Builder


Cursors Tab, DataEnvironment Builder

Visual FoxPro 9.0
Cursors Tab, DataEnvironment Builder
See Also

Use to create new CursorAdapter objects, add CursorAdapter objects from a class library, remove CursorAdapter objects, or open the CursorAdapter Builder for an existing CursorAdapter object.

Add

Displays the Open dialog box so that you can select an existing CursorAdapter class from a class library or program file.
New

Displays the CursorAdapter Builder so that you can create and configure a new CursorAdapter object.
Remove

Removes the currently selected CursorAdapter object. You can also select a different CursorAdapter object from the list appearing on the Cursors tab.
Builder

Opens the CursorAdapter Builder for the currently selected CursorAdapter object.
Class

Read-only. Displays the class name for the currently selected CursorAdapter object.
Name

Read/write. Displays the name of the currently selected CursorAdapter object. The default name is Cursor<CursorNumber>.

See Also

Other Resources

DataEnvironment Builder
Data Source Tab, DataEnvironment Builder


Edit Box Builder

Visual FoxPro 9.0
Edit Box Builder
See Also

The Edit Box builder makes it easy to set properties for an edit box control. Edit boxes are commonly used to display long Character fields or Memo fields and allow the user to edit text. An edit box can also display text from a text file or from the clipboard. You set properties for the edit box control by selecting options in the Edit Box Builder dialog box.

To use the Edit Box builder

  1. Using the Form Controls toolbar, place an edit box control on a form.

  2. Select and right-click the edit box control, and then choose Builder from the Form Designer shortcut menu.

    A dialog box appropriate to the selected control appears.

  3. Choose the options you want from the dialog box, and then choose OK.

    When you choose OK, the builder closes, applying the property settings from every tab.

Builder Tabs

Format

Specifies miscellaneous format options for the edit box.
Style

Specifies edit box visual effect, border, and alignment.
Value

Specifies a field in which to store the edit box's value.

See Also

Other Resources

Builders
EditBox Control
Format Tab, Edit Box Builder
Style Tab, Edit Box Builder
Value Tab, Edit Box Builder
Properties Window


Format Tab, Edit Box Builder

Visual FoxPro 9.0
Format Tab, Edit Box Builder
See Also

This tab in the Edit Box builder specifies miscellaneous format options for the edit box, such as adding vertical scrollbars and making the box read-only.

Allow User to Insert Tabs

Permits inserting of tabs in the edit box. This prevents the focus from moving to the next control when the TAB key is pressed. Press CTRL+TAB to move to the next control. This option corresponds to the AllowTabs property.
Add Vertical Scrollbars

Adds vertical scrollbars to the edit box. This option corresponds to the ScrollBars property.
Select on Entry

Specifies that the text in the edit box be selected when the edit box has the focus. This adds the setting "K" to the Format property.
Use Current SET DATE

Adds the setting "D" to the Format property so that date entries will conform to the current SET DATE or Date Format of the International tab of the Options dialog box.
Hide Selection

Specifies whether or not selected text in the edit box remain visibly selected when the edit box doesn't have the focus. This option corresponds to the HideSelection property.
Enable at Run time

Specifies whether or not the edit box is enabled when the form is run. This option corresponds to the Enabled property.
Make Read-Only

Prevents the user from changing the text in the edit box. This option corresponds to the ReadOnly property.
British Date

Adds the setting "E" to the Format property so date entries will conform to British formatting of SET DATE or of the Date Format of the International tab of the Options dialog box.

See Also

Other Resources

AllowTabs Property
Edit Box Builder
Enabled Property
Format Property
HideSelection Property
ReadOnly Property
ScrollBars Property
Style Tab, Edit Box Builder
Value Tab, Edit Box Builder


Style Tab, Edit Box Builder

Visual FoxPro 9.0
Style Tab, Edit Box Builder
See Also

This tab in the Edit Box builder specifies edit box visual effect, border, and alignment.

Special Effect

3D

Specifies a left and top edge highlight and a right and lower edge shadow for the combo box. This option corresponds to the 3D setting of the SpecialEffect property.
Plain

Specifies that the combo box is an unshadowed box on the form. This option corresponds to the Plain setting of the SpecialEffect property.

Border

Single

Specifies a single line around the edit box. This option corresponds to the Fixed-Single setting of the BorderStyle property.
None

Specifies no line around the edit box. This option corresponds to the None setting of the BorderStyle property.

Character Alignment

Left

Specifies that text in the edit box will be left-aligned. This option corresponds to the Left setting of the Alignment property.
Right

Specifies that text in the edit box will be right-aligned. This option corresponds to the Right setting of the Alignment property.
Center

Specifies that text in the edit box will be centered. This option corresponds to the Center setting of the Alignment property.

See Also

Other Resources

Edit Box Builder
Format Tab, Edit Box Builder
Value Tab, Edit Box Builder
Alignment Property
BorderStyle Property
SpecialEffect Property


Value Tab, Edit Box Builder

Visual FoxPro 9.0
Value Tab, Edit Box Builder
See Also

This tab in the Edit Box builder specifies a field in which to store the edit box's value.

Field Name

Specifies a table or view field in which to store the edit box's value. Type the field name, or click the dialog button to display the Open dialog box, where you can select another table or view. In the Edit Box builder, click the drop-down arrow next to the Field Name list box to select a field. The default contents of this tab are all the fields in the data environment. This option corresponds to the ControlSource property.

For more information, see Creating Forms.

See Also

Other Resources

Edit Box Builder
Format Tab, Edit Box Builder
Open Dialog Box
Style Tab, Edit Box Builder
ControlSource Property


Form Builder

Visual FoxPro 9.0
Form Builder
See Also

The Form builder makes it easy to add fields as new controls to a form. You add controls and specify style by selecting options displayed in the Form Builder dialog box.

To use the Form builder

  1. Right-click on a new or existing form in the Form designer.

    -or-

  2. Choose Quick Form from the Form menu.

    When you choose OK, the builder closes, applying the property settings from every tab.

Builder Tabs

Field Selection

Specifies fields to be added as form controls.
Style

Offers several style choices for your controls and the option to enlarge the form if necessary. The form size will only enlarge to fit the size of the Maximum Design Area as set in the Forms tab of the Options dialog box.

The styles correspond to those offered by the Form wizards. If you created a form with a wizard, and then wish to add a new control of the same style, use the Form builder. You may also add new controls with a different style. The style chosen in the Form builder does not affect existing controls on a form. To format them, use the AutoFormat builder.

See Also

Other Resources

Builders
AutoFormat Builder
Field Selection Tab, Form Builder
Forms Tab, Options Dialog Box
Style Tab, Form Builder


Field Selection Tab, Form Builder

Visual FoxPro 9.0
Field Selection Tab, Form Builder
See Also

This tab in the Form builder specifies fields to be added as form controls.

Databases and Tables

Lists the available databases or lets you select free tables. To find a database or table, click the dialog button, which displays the Open dialog box.
List of Tables

Displays tables and views in the selected database, or free tables.
Available Fields

Shows all fields in the selected table or view. Select the fields whose data you want on your form.
Arrow Buttons

Adds fields to and removes fields from the Selected Fields box.
Selected Fields

Displays the fields that will appear on your form as controls.

See Also

Other Resources

Form Builder
Style Tab, Form Builder
Open Dialog Box
Grid Builder


Style Tab, Form Builder

Visual FoxPro 9.0
Style Tab, Form Builder
See Also

This tab in the Form builder offers several style choices for your controls and the option to enlarge the form to accommodate data. The form size will only enlarge to fit the size of the Maximum Design Area as set in the Forms tab of the Options dialog box.

Style

Specifies the style of the form controls, which is determined by the class of the control. Select a form style to see a preview of what the style will look like.
Enlarge Form as Needed check box

Specifies that the builder enlarge the form to accommodate the selected fields; up to the maximum size determined by the design area of the form, if necessary.

See Also

Other Resources

Form Builder
Field Selection Tab, Form Builder
Forms Tab, Options Dialog Box
Edit Box Builder


Grid Builder

Visual FoxPro 9.0
Grid Builder
See Also

The Grid builder makes it easy to set properties for a grid control. The grid control allows you to present and manipulate rows and columns of data in a form or page. You set grid properties by selecting options displayed in the Grid Builder dialog box.

To use the Grid builder

  1. Using the Form Controls toolbar, place a grid control on a form.

  2. Select and right-click the grid control, and then choose Builder from the Form Designer shortcut menu.

  3. Choose the options you want from the dialog box, and then choose OK.

    When you choose OK, the builder closes, applying the property settings from every tab.

    Note:
    Before running your form, make sure you have sized the grid control to adequately display your data.

Builder Tabs

Grid Items

Specifies fields to be displayed in the grid.
Style

Specifies a style for the grid display.
Layout

Specifies column captions and control types.
Relationship

Specifies relationships between grid fields and table fields.

See Also

Other Resources

Builders
Grid Control
Grid Items Tab, Grid Builder
Layout Tab, Grid Builder
RecordSource Property
RecordSourceType Property
Relationship Tab, Grid Builder
Style Tab, Grid Builder


Grid Items Tab, Grid Builder

Visual FoxPro 9.0
Grid Items Tab, Grid Builder
See Also

This tab in the Grid builder specifies fields to be displayed in the grid.

Note:
In the Grid builder, you can select fields from a single table only. To set a relationship between Grids, you must use the Grid builder on each Grid separately, and then use the Relationship tab of one Grid builder to establish the relationship.

Databases and Tables Lists the available databases and gives the option to select free tables. To find a database or table, click the dialog button, which displays the Open dialog box.

List of Tables

Displays tables and views in the selected database, or free tables.
Available Fields

Shows all fields in the selected table. You may select fields from only one table.
Arrow Buttons

Add fields to and remove fields from the Selected Fields list.
Selected Fields

Displays the fields that will appear in the grid. Each field displays in one column in the grid.

See Also

Other Resources

Grid Builder
Layout Tab, Grid Builder
Open Dialog Box
Relationship Tab, Grid Builder
Style Tab, Grid Builder


Style Tab, Grid Builder

Visual FoxPro 9.0
Style Tab, Grid Builder
See Also

This tab in the Grid builder specifies a style for the grid display.

Style

Specifies the Professional, Standard, Embossed, or Ledger style for the grid display. You can choose to preserve the current style.

See Also

Other Resources

Grid Builder
Grid Items Tab, Grid Builder
Layout Tab, Grid Builder
Relationship Tab, Grid Builder


Layout Tab, Grid Builder

Visual FoxPro 9.0
Layout Tab, Grid Builder
See Also

This tab in the Grid builder specifies column captions and the type of control you can add to the Grid.

Note:
You must select a column before you can change its heading.

Caption

Specifies the caption for the selected column. Type a caption in the box. If you do not specify a caption, the field names will be the column headings.
Control Type

Specifies the type of control to add to the selected column. Text or edit boxes are available for character data, text or check boxes are available for logical data, and text boxes or spinners are available for numeric data.
Grid Display

Shows the grid columns as currently specified. The display automatically updates according to your Caption and Control Type selections. You can set the columns to the desired width by dragging the right edge of a heading.

See Also

Other Resources

Grid Builder
Grid Items Tab, Grid Builder
Style Tab, Grid Builder
Relationship Tab, Grid Builder


Relationship Tab, Grid Builder

Visual FoxPro 9.0
Relationship Tab, Grid Builder
See Also

This tab in the Grid builder specifies a relationship between grid fields and table fields.

Key Field in Parent Table

Specifies the key field of the controlling table in a relationship. This option corresponds to the LinkMaster property. To find a table, click the dialog button, which displays the Open dialog box.
Related Index in Child Table

Specifies the index tag name of the controlled table in a relationship. This option corresponds to the ChildOrder property.

See Also

Other Resources

ChildOrder Property
Grid Builder
Grid Items Tab, Grid Builder
Style Tab, Grid Builder
Layout Tab, Grid Builder
LinkMaster Property


List Box Builder

Visual FoxPro 9.0
List Box Builder
See Also

The List Box builder makes it easy to set properties for a list box control. List boxes provide the user with a scrollable list that contains a number of options or pieces of information. In a list box, multiple items can be visible at all times. You set list box properties by selecting options displayed in the List Box Builder dialog box.

To use the List Box builder

  1. Using the Form Controls toolbar, place a list box control on a form.

  2. Select and right-click the list box control, and then choose Builder from the Form Designer shortcut menu.

  3. Choose the options you want from the dialog box, and then choose OK.

    When you choose OK, the builder closes, applying the property settings from every tab.

Builder Tabs

List Items

Specifies items to fill the list box and the sources of that data.
Style

Specifies style (3D or plain) and number of rows, and enables or disables incremental searching.
Layout

Controls column width and display.
Value

Specifies from which column to get return values and which field to store them in.

See Also

Other Resources

Builders
Layout Tab, List Box Builder
ListBox Control
List Items Tab, List Box Builder
Properties Window
Style Tab, List Box Builder
Value Tab, List Box Builder


List Items Tab, List Box Builder

Visual FoxPro 9.0
List Items Tab, List Box Builder
See Also

This tab in the List Box builder specifies items to fill the list box.

In the Fill the List With box, you specify the kind of data with which to fill the list. The selection you make here determines which options appear on this tab. The options are Fields from a Table or View, Data Entered by Hand, and Values from an Array.

Fields from a Table or View

Databases and Tables

Lists the available databases and the option to select free tables. To find a database or table, click the dialog button, which displays the Open dialog box.
List of Tables

Displays tables and views in the selected database or free tables.
Available Fields

Shows all fields in the selected table or view. Select the fields whose data you want in your list box.
Arrow Buttons

Adds fields to and removes fields from the Selected Fields list.
Selected Fields

Displays the fields that will be used to fill the list. This option corresponds to the RowSource property.
Note:
You must choose this option in order to hide the column from the Layout tab.

Data Entered by Hand

Columns

Specifies the number of columns in the list. This option corresponds to the ColumnCount property.
Column Grid

Displays the columns in which to enter data. Type the data in the grid cells. You can size the columns by dragging the lines between the column headers with the mouse. Use the arrow keys to move through the columns. This option corresponds to the RowSource property.

Values from an Array

Array Name

Specifies the name of an array. This option corresponds to the RowSource property.
Entire Array

Specifies that the entire array will fill the list.
Range of the Array

Specifies that a part of the array will fill the list.
Column and Row Range

Specifies the starting and ending column and row as the array range. These options are available when you select Range of the Array. This option corresponds to the FirstElement property, NumberOfElements property, and ColumnCount property.

For more information, see Creating Forms.

See Also

Other Resources

Layout Tab, List Box Builder
List Box Builder
Open Dialog Box
RowSource Property
RowSourceType Property
Style Tab, List Box Builder
Value Tab, List Box Builder


Style Tab, List Box Builder

Visual FoxPro 9.0
Style Tab, List Box Builder
See Also

This tab in the List Box builder specifies style, number of rows to display, and incremental searching.

Three-dimensional

Specifies a three-dimensional look for the list box. This option corresponds to the SpecialEffect property.
Plain

Specifies a plain look for the list box. This option corresponds to the SpecialEffect property.
Rows to Display

Sets the Height property of the list box so it displays only the specified number of rows at a time.
Yes, Enable Incremental Searching

Specifies whether the control tries to match an item in the list as the user types each letter. This option corresponds to setting the IncrementalSearch property to .T.
No, Don't Enable Incremental Searching

Disables incremental searching. This option corresponds to setting the IncrementalSearch property to .F.

See Also

Other Resources

Height Property
IncrementalSearch Property
Layout Tab, List Box Builder
List Box Builder
List Items Tab, List Box Builder
SpecialEffect Property
Value Tab, List Box Builder


Layout Tab, List Box Builder

Visual FoxPro 9.0
Layout Tab, List Box Builder
See Also

This tab in the List Box builder controls column width and display.

Adjust the Width of the List Box to Display All Columns

Specifies that all columns will be displayed, and the list box will be automatically sized as required. This option corresponds to the Width property.
Column Grid

Shows the columns defined on the List Items tab. You can adjust the column width by dragging the right edge of a column heading with the mouse. You can hide a column by double-clicking a column heading if you have chosen "Fill the list with fields from a table or view" in the List Items tab. This option corresponds to the ColumnWidths property.

See Also

Other Resources

ColumnWidths Property
List Box Builder
List Items Tab, List Box Builder
Style Tab, List Box Builder
Value Tab, List Box Builder
Width Property


Value Tab, List Box Builder

Visual FoxPro 9.0
Value Tab, List Box Builder
See Also

This tab in the List Box builder specifies where to get return values and where to store them.

Return the Value From

Specifies the column or field from which to get a value when the user selects a list box item. This option corresponds to the BoundColumn property.
Field Name

Specifies a table or view field in which to store the value specified in the Return the Value From box. By default, the list includes fields from a table or view selected on the List Items tab. Choose the dialog button to display the Open dialog box so you can select another file. This option corresponds to the ControlSource property.

See Also

Other Resources

BoundColumn Property
ControlSource Property
Layout Tab, List Box Builder
List Box Builder
List Items Tab, List Box Builder
Open Dialog Box
Style Tab, List Box Builder


Option Group Builder

Visual FoxPro 9.0
Option Group Builder
See Also

The Option Group builder makes it easy to set properties for an option group control. Option buttons allow users to choose one of several mutually exclusive options. You set properties by selecting options displayed in the Option Group Builder dialog box.

To use the Option Group builder

  1. Using the Form Controls toolbar, place an option group control on a form.

  2. Select and right-click the option group control, and then choose Builder from the Form Designer shortcut menu.

  3. Choose the options you want from the dialog, and then choose OK.

    When you choose OK, the builder closes, applying the property settings from every tab.

Builder Tabs

Buttons

Specifies number of buttons, captions, and graphics.
Layout

Specifies option button layout (vertical or horizontal), spacing, and border style.
Value

Specifies a table or view field in which to store the option group's value.

See Also

Other Resources

Builders
Buttons Tab, Option Group Builder
Layout Tab, Option Group Builder
OptionGroup Control
Value Tab, Option Group Builder


Buttons Tab, Option Group Builder

Visual FoxPro 9.0
Buttons Tab, Option Group Builder
See Also

This tab in the Option Group builder specifies the number of buttons, captions, and graphics.

Number of Buttons

Specifies the number of buttons the option group will have. This option corresponds to the ButtonCount property.
Standard

Specifies radio-style option buttons. The Graphic column is disabled when Standard is selected.
Graphical

Specifies rectangular option buttons. You can specify both caption and graphic in the columns when this is selected.
Caption Column

Specifies the caption to display next to the button. Type the caption in the box, or leave it blank if you don't want a caption. This option corresponds to the Caption property.
Graphic Column

Specifies the path and file name of the bitmap to display on the button. Type the path and file name in the box, or click the dialog button to display the Open dialog box so you can select a file. This option corresponds to the Picture property of the Option button.
Note:
Option buttons may have both captions and graphics. You can also specify graphics to be displayed when the button is disabled and when it is pressed, but you must do so programmatically or in the Properties window.

See Also

Other Resources

ButtonCount
Caption Property
DisabledPicture Property
DownPicture Property
Layout Tab, Option Group Builder
Option Group Builder
Picture Property
Properties Window
Value Tab, Option Group Builder


Layout Tab, Option Group Builder

Visual FoxPro 9.0
Layout Tab, Option Group Builder
See Also

This tab in the Option Group builder specifies button layout (vertical or horizontal), spacing, and border style.

Button Layout

Specifies vertical or horizontal layout of option group buttons by adjusting the Width property.
Spacing Between Buttons

Specifies spacing between buttons by adjusting the Width property or the Height property.
Border Style

Specifies a single-line border around the option group, or no border. This option corresponds to the BorderStyle property.

See Also

Other Resources

BorderStyle Property
Buttons Tab, Option Group Builder
Option Group Builder
Value Tab, Option Group Builder


Value Tab, Option Group Builder

Visual FoxPro 9.0
Value Tab, Option Group Builder
See Also

This tab in the Option Group builder specifies a table or view field in which to place the option group's value.

Field Name

Specifies a table or view field in which to store the option group's value. By default, the list includes fields from a table. Choose the dialog button to display the Open dialog box so you can select another file. This option corresponds to the ControlSource property.

See Also

Other Resources

Buttons Tab, Option Group Builder
ControlSource Property
Layout Tab, Option Group Builder
Open Dialog Box
Option Group Builder


Referential Integrity Builder

Visual FoxPro 9.0
Referential Integrity Builder
See Also

The Referential Integrity (RI) Builder helps you create a set of rules that control how records are inserted, updated, or deleted in related tables. The RI Builder generates code for these rules as triggers that reference stored procedures. For more information, see How to: Build Referential Integrity Between Tables.

Builder Tabs

Rules for Updating

Specifies rules to apply when the key value in the parent table is modified.
Rules for Deleting

Specifies rules to apply when a record in the parent table is deleted.
Rules for Inserting

Specifies rules to apply when a new record is inserted or an existing record is updated in the child table.

For more information, see Developing Databases and Trigger Usage.

See Also

Other Resources

Builders


Rules for Updating Tab, RI Builder

Visual FoxPro 9.0
Rules for Updating Tab, RI Builder
See Also

This tab in the Referential Integrity (RI) builder specifies rules to apply when the key value in the parent table is modified.

Cascade

Specifies that changes in the fields of the Primary or Candidate key of the parent table are reflected in related child tables. If you select this option, any time you change any of those fields in the parent table, Microsoft Visual FoxPro automatically changes the corresponding values in all related child table records.
Restrict

Prevents modification of values in fields of the Primary or Candidate key of the parent table so there are no orphaned records in the child table.
Ignore

Makes it possible for you to update records in the parent table, even if there are related records in the child table.
Referential Integrity Grid

Parent Table displays the name of the table in the database relation containing the primary or candidate index. Child Table displays the name of the child table in the database relation. Update displays the update rules for referential integrity for the relation. Possible values are Cascade, Restrict, or Ignore. You can change the settings by selecting the field, which will present a drop-down list of the choices. Delete displays the delete rules for the referential integrity for the relation. Possible values are Cascade, Restrict, or Ignore. You can change the settings by selecting the field, which will present a drop-down list of the choices. Insert displays the insert rules for the referential integrity for the relation. Possible values are Cascade, Restrict, or Ignore. You can change the settings by selecting the field, which will present a drop-down list of the choices. Parent Tag grid column displays the tag name of the index in the Primary or Candidate in the Parent table. Child Tag grid column displays the tag name of the index in the child table.

See Also

Other Resources

Referential Integrity Builder
Rules for Deleting Tab
Rules for Inserting Tab


Rules for Deleting Tab, RI Builder

Visual FoxPro 9.0
Rules for Deleting Tab, RI Builder
See Also

This tab in the Referential Integrity (RI) builder specifies rules to apply when a record in the parent table is deleted.

Cascade

Specifies that deletions in the parent table are reflected in the related child tables. If you select Cascade Delete for a relationship, whenever you delete records in the parent table, records in the related child table are automatically deleted.
Restrict

Prevents you from deleting records in the parent table that have related records in the child table. If you select Restrict Delete for a relationship, an attempt to delete records in the parent table generates an error if there are related records in the child table.
Ignore

Makes it possible for you to delete records in the parent table, even if there are related records in the child table.
Referential Integrity Grid

Parent Table displays the name of the table in the database relation containing the primary or candidate index. Child Table displays the name of the child table in the database relation. Update displays the update rules for referential integrity for the relation. Possible values are Cascade, Restrict, or Ignore. You can change the settings by selecting the field, which will present a drop-down list of the choices. Delete displays the delete rules for the referential integrity for the relation. Possible values are Cascade, Restrict, or Ignore. You can change the settings by selecting the field, which will present a drop-down list of the choices. Insert displays the insert rules for the referential integrity for the relation. Possible values are Cascade, Restrict, or Ignore. You can change the settings by selecting the field, which will present a drop-down list of the choices. Parent Tag grid column displays tag name of the index in the Primary or Candidate in the Parent table. Child Tag grid column displays the tag name of the index in the child table.

See Also

Other Resources

Referential Integrity Builder
Rules for Inserting Tab
Rules for Updating Tab


Rules for Inserting Tab, RI Builder

Visual FoxPro 9.0
Rules for Inserting Tab, RI Builder
See Also

This tab in the Referential Integrity (RI) builder specifies rules to apply when a new record is inserted or an existing record is updated in the child table.

Restrict

Prevents you from adding records in the child table for which there are no matching records in the parent table. If you select Restrict Insert for a relationship, an attempt to add records in the child table generates an error if there is no matching parent record.
Ignore

Makes it possible for you to insert records into the child table regardless of whether there is a matching record in the parent table.
Referential Integrity Grid

Parent Table displays the name of the table in the database relation containing the primary or candidate index. Child Table displays the name of the child table in the database relation. Update displays the update rules for referential integrity for the relation. Possible values are Cascade, Restrict, or Ignore. You can change the settings by selecting the field, which will present a drop-down list of the choices. Delete displays the delete rules for the referential integrity for the relation. Possible values are Cascade, Restrict, or Ignore. You can change the settings by selecting the field, which will present a drop-down list of the choices. Insert displays the insert rules for the referential integrity for the relation. Possible values are Cascade, Restrict, or Ignore. You can change the settings by selecting the field, which will present a drop-down list of the choices. Parent Tag grid column displays tag name of the index in the Primary or Candidate in the Parent table. Child Tag grid column displays the tag name of the index in the child table.

See Also

Reference

Rules for Inserting Tab

Other Resources

Referential Integrity Builder
Rules for Updating Tab


Text Box Builder

Visual FoxPro 9.0
Text Box Builder
See Also

The Text Box builder makes it easy to set properties for a text box control. The text box is the basic control that allows users to add or edit data in a Character, Numeric, or Date field in a table. You set properties by selecting options displayed in the Text Box Builder dialog box.

To use the Text Box builder

  1. Using the Form Controls toolbar, place a text box control on a form.

  2. Select and right-click the text box control, and then choose Builder from the Form Designer shortcut menu.

  3. Choose the options you want from the dialog box, and then choose OK.

    When you choose OK, the builder closes, applying the property settings from every tab.

Builder Tabs

Format

Specifies miscellaneous format options for the text box and the type of input mask.
Style

Specifies text box visual effect, border, and character alignment.
Value

Specifies a field in which to store the text box's value.

See Also

Other Resources

Builders
Format Tab, Text Box Builder
Style Tab, Text Box Builder
TextBox Control
Value Tab, Text Box Builder


Format Tab, Text Box Builder

Visual FoxPro 9.0
Format Tab, Text Box Builder
See Also

This tab in the Text Box builder specifies miscellaneous format options for the text box and the type of input mask.

Data Type

Specifies a Character, Date, Logical, or Numeric data type for your text box. If you choose a value in the Value tab, make sure it is the same data type as the value specified here.
Enable at Run Time

Specifies that the text box be enabled when the form is run. This option is available for all data types and is checked by default. This option corresponds to the Enabled property.
Alphabetic Characters Only

Specifies that only alphabetic characters be allowed in the text box (no numbers or symbols). This option is available for Character data type only. This option corresponds to the "A" setting of the Format property.
Make Read-Only

Prevents the user from changing the text in the text box. This option corresponds to the ReadOnly property and is available for all data types.
Select on Entry

Specifies that the text in the text box be selected when the text box has the focus. This option is available for the Character data type only. This option corresponds to the "K" setting of the Format property.
Hide Selection

Specifies whether or not selected text in the text box remains visibly selected when the text box doesn't have the focus. This option corresponds to the HideSelection property and is available for all data types.
Display Leading Zeros

Specifies that zeros to the left of the decimal point be displayed. This is available for the Numeric data type only. This option corresponds to the "L" setting of the Format property.
Use Current SET DATE

Adds the setting "D" to the Format property so that date entries will conform to the current SET DATE or Date Format of the Regional tab of the Options dialog box. This option appears when you select Date in the Data Type drop-down box.
British Date

Adds the setting "E" to the Format property so that date entries will conform to British formatting of SET DATE or of the Date Format of the Regional tab of the Options dialog box. This option appears when you select Date in the Data Type drop-down box.
Input Mask

Specifies format of user input for Numeric, Character, and Logical fields. Several options are available from the drop-down list; an example of the selected input mask appears to the right of the drop-down list. For example, an input mask for a Numeric data type is North American phone number format: (###) ###-####.

See Also

Other Resources

Enabled Property
Format Property
HideSelection Property
InputMask Property
ReadOnly Property
Style Tab, Text Box Builder
Text Box Builder
Value Tab, Text Box Builder


Style Tab, Text Box Builder

Visual FoxPro 9.0
Style Tab, Text Box Builder
See Also

This tab in the Text Box builder specifies text box visual effect, border, and character alignment.

Visual Effect

3D

Specifies a bold left and top edge for the text box. This option corresponds to the 3D setting of the SpecialEffect property.
Plain

Specifies that the text box is an unshadowed box on the form. This option corresponds to the Plain setting of the SpecialEffect property.

Border

Single

Specifies a single line around the text box. This option corresponds to the Fixed-Single setting of the BorderStyle property.
None

Specifies no line around the text box. This option corresponds to the None setting of the BorderStyle property.

Character Alignment

Left

Specifies that text in the text box will be left-aligned. This option corresponds to the Left setting of the Alignment property.
Right

Specifies that text in the text box will be right-aligned. This option corresponds to the Right setting of the Alignment property.
Center

Specifies that text in the text box will be centered. This option corresponds to the Center setting of the Alignment property.
Automatic

Specifies that text in the text box will be aligned according to the data type of the control source. This option corresponds to the Automatic (Default) setting of the Alignment property.
Size Text Box to Fit

Automatically sizes the text box. If an input mask is specified, the input mask settings are used to fit the text box. If not, then the ControlSource property field length is used to fit the text box.
Note:
If you specified an input mask on Format tab of the Text Box builder, the text box will enlarge to fit the length of the input mask. If you did not specify an input mask, the text box will enlarge to fit the field length.

See Also

Other Resources

BorderStyle Property
ControlSource Property
Format Tab, Text Box Builder
SpecialEffect Property
Text Box Builder
Value Tab, Text Box Builder


Value Tab, Text Box Builder

Visual FoxPro 9.0
Value Tab, Text Box Builder
See Also

This tab in the Text Box builder specifies a field in which to store the text box's value.

Field Name

Specifies a table or view field in which to store the text box's value. Choose the dialog button to display the Open dialog box so you can select a file. This option corresponds to the ControlSource property.

See Also

Other Resources

ControlSource Property
Format Tab, Text Box Builder
Open Dialog Box
Style Tab, Text Box Builder
Text Box Builder


XML Web Service Builder

Visual FoxPro 9.0
XML Web Service Builder
See Also

Makes it possible for you to bind an XML Web service to a control on a Visual FoxPro form or to an object, such as a cursor adapter in the form's data environment, without writing code.

You can open the XML Web Service Builder from the Form Designer or Class Designer.

To open the XML Web Service Builder

  1. Create a new or open an existing form.

  2. From the Tools menu, click Toolbox.

  3. From My XML Web Services in the Toolbox, drag and drop the Generic Handler control or a registered XML Web service to a form.

You can also open the XML Web Service Builder for an existing XML Web service by registering the XML Web service in the Toolbox, dragging the XML Web service from the Toolbox and dropping it on a form, right-clicking the XML Web service, and, from the shortcut menu, right-click Builder.

Note:
As with other Visual FoxPro builders, you can use the XML Web Service Builder to modify the XML Web service again. Not only does the builder set properties for a control, it writes information to the custome SetupOperations method.

Builder Tabs

Services Tab, XML Web Service Builder

Specifies an XML Web service to use for a form or class.
Operations Tab, XML Web Service Builder

Specifies the XML Web service operations to use and their bindings between the controls or objects on a form or class.

See Also

Other Resources

Builders
How to: Access XML Web Services


Services Tab, XML Web Service Builder

Visual FoxPro 9.0
Services Tab, XML Web Service Builder
See Also

Specifies the XML Web service to use in your application. You can also view the operations, or method calls, available for the XML Web service.

Select an XML Web service

Specifies the XML Web service that you want to bind to controls or objects on the form and displays other XML Web services that are available in the Toolbox.
Refresh

Updates the selected XML Web service so it can be registered properly on your computer. This option is available only when all registered XML Web services are listed.
Add a new XML Web service

Makes it possible for you to register and add a new XML Web service. This option is available only when all registered XML Web services are listed.
Change XML Web service

Lists all registered XML Web services. This option appears if an XML Web service is selected when opening the builder.
Note:
Changing the XML Web service removes all settings from the Operations tab for that XML Web service.

View operations

Displays the operations, or method calls, available for the selected XML Web service.
Note:
The selected operation appears in the View operations box only for informational purposes. You can set bindings for the operation on the Operations tab. For more information, see Operations Tab, XML Web Service Builder.

View service description (WSDL)

Displays the WSDL description for the XML Web service.

See Also

Other Resources

XML Web Service Builder
Operations Tab, XML Web Service Builder


Operations Tab, XML Web Service Builder

Visual FoxPro 9.0
Operations Tab, XML Web Service Builder
See Also

Specifies the XML Web service operations, or method calls, you want to use in your form or class. You can supply parameter information for the operation calls in advance and specify a control, or client, to which you want to bind the results of the operation call.

Note:
Settings for the Operations and Clients tabs are stored in the custom SetupOperations method.

Operations

Lists all registered operations for the XML Web service. You can call these operations automatically when the form or class is instantiated or programmatically when needed. You can associate each operation with multiple clients.
  • Add Displays a dialog box with options for adding a new operation. For more information, see XML Web Service - Operation Detail Dialog Box.

  • Edit Displays a dialog box with options for editing the selected operation. For more information, see XML Web Service - Operation Detail Dialog Box.

  • Remove Removes the selected operation. If you remove an operation, you are prompted to remove any clients associated with the operation.

Clients

Lists all registered clients for the selected operation. Clients are controls or objects on a form or in a class that use the XML Web service operation. You can specify when binding occurs between the operation and client and to which property of the control operation results are assigned. For XML Web services that return ADO.NET DataSets, you can also specify complex type information such as table or field settings.
  • Add Displays a dialog box with options for adding a new client. For more information, see XML Web Service - Client Detail Dialog Box.

  • Edit Displays a dialog box with options for editing the selected client. For more information, see XML Web Service - Client Detail Dialog Box.

  • Remove Removes the selected client.

See Also

Other Resources

XML Web Service Builder
Services Tab, XML Web Service Builder


Designers

Visual FoxPro 9.0
Designers

Designers make it possible for you to design the windows, dialog boxes, and components in your application visually.

In This Section

Class Designer

Allows you to create and modify classes visually.
Connection Designer

Allows you to create and modify named connections. Because connections are stored as part of a database, you only can use the Connection designer if you have a database open.
Data Environment Designer

Allows you to create and modify the data environment of forms, form sets, and reports visually.
Database Designer

Displays and allows you to create and modify tables, views, and relationships that are contained in a database.
Form Designer

Allows you to create and modify forms and form sets visually. A form set consists of one or more forms that can be manipulated as a unit.
Label Designer

Allows you to create and modify labels. When the Label designer window is active, Microsoft Visual FoxPro displays the Report menu and the Report Controls toolbar.
Menu and Shortcut Designers

Allows you to create menus, menu items, submenus of menu items, lines that separate groups of related menu items, and so on.
Query and View Designers

Allows you to create and modify queries and views. When the Query or View designer is active, Microsoft Visual FoxPro displays the Query menu and the Query toolbar or View designer toolbar.
Report Designer

Allows you to create and modify reports. When the Report designer window is active, Microsoft Visual FoxPro displays the Report menu and the Report Controls toolbar.
Table Designer

Allows you to create and modify database tables, free tables, fields, and indexes.

Related Sections

User Interface Reference

Explains the options that appear on various dialog boxes, windows, and other user interfaces. These types of topics generally appear when you press F1 in a dialog box or window.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.
Reference

Includes topics on productivity tools, as well as the controls, objects, properties, methods, events, statements, functions, and constants available.
Utility Programs

Describes tools that are provided with Microsoft Visual FoxPro to help speed the process of application development.


Class Designer

Visual FoxPro 9.0
Class Designer
See Also

Use the Class Designer to create and modify classes visually. When the Class Designer window is active, Microsoft Visual FoxPro displays the Class Menu. The View Menu makes it possible for you to open complementary class design tools such as the Properties window, the Form Controls Toolbar, and the Layout Toolbar.

Classes are stored in class library (.vcx) files. To modify more than one class, you can open multiple class designers at the same time.

You can save classes by pressing CTRL+E while in the code editor. When you reopen the class, the code editor reopens to the same location in the code.

For detailed information on designing classes, see Object-Oriented Programming, and the topics How to: Create Classes and Subclasses and How to: Save Forms.

The Class Designer window consists of the Class window, which displays a single class. The Class window is anchored to the top-left corner of the Class Designer and cannot be moved unless the window contains toolbar types.

See Also

Other Resources

Designers
Data Session Window
Form Designer
PageFrame Control
Connection Designer
Database Designer
Data Environment Designer


Connection Designer

Visual FoxPro 9.0
Connection Designer
See Also

Makes it possible for you to create and modify named connections. For more information, see How to: Define Connections to Remote Data Sources.

The Connection Designer is available only when a database is open because connections are stored as part of a database.

Specify Datasource

Data Source, Userid, Password

Specifies that Visual FoxPro display the following three boxes:
  • Data Source Makes it possible for you to choose a data source from the list of installed ODBC data sources.

  • Userid Makes it possible for you to enter a user name or ID if the data source requires one.

  • Password Makes it possible for you to enter a password if the data source requires one.

  • Database Makes it possible for you to choose a database for the selected data source to connect to.

Connection String

Specifies that Visual FoxPro display the Connect Stringtextbox in which you type a connection string. Choosing the dialog button displays the Select Connection or Data Source Dialog Box, allowing you to select an existing file or machine data source.
Verify Connection

Makes it possible for you to check the connection you have just entered information for. If the connection was made successfully, a dialog box appears to indicate this. If the connection was not successful, an error message appears. If no information has been specified for the connection, the Select Database dialog box appears, which makes it possible for you to select a data source.
New Data Source

Displays the Data Sources dialog box, which makes it possible for you to add, delete, or configure data sources.

Display ODBC Login Prompts

When Login Info Is Not Specified

Specifies that Visual FoxPro prompt the user with the ODBC Data Source Login dialog box if the user ID and password are not stored in the named connection definition.
Always

Specifies that Visual FoxPro always prompt the user with the ODBC Data Source Login dialog box. This enables the user to use a different login ID and password from those stored in the named connection.
Never

Specifies that Visual FoxPro never prompt the user. This option ensures higher security.

Data Processing

These options correspond to connection properties that you can also set with the DBSETPROP( ) Function. For more information about these properties, see the connection properties in the DBGETPROP( ) Function.

Asynchronous Execution

Specifies an asynchronous connection. This option corresponds to the Asynchronous connection property.
Display Warnings

Specifies the display of non-trappable warnings. This option corresponds to the DispWarnings connection property.
Batch Processing

Specifies that the connection operate in batch mode. This option corresponds to the BatchMode connection property.
Automatic Transactions

Specifies that the transaction processing is automatically handled. This option corresponds to the Transactions connection property.
Packet Size

Makes it possible for you to specify the network packet size (in bytes) for information transmitted to and from the remote data site. Select a choice from the drop-down list, or type a value.

Timeout Intervals

These options set values for connection properties that you can also set with the DBSETPROP( ) function. For more information about these properties, see connection properties in the DBGETPROP( ) Function.

Connection (sec)

Specifies the connection timeout interval in seconds. This option corresponds to the ConnectTimeout connection property.
Query (sec)

Specifies the query timeout interval in seconds. This option corresponds to the QueryTimeout connection property.
Idle (min)

Specifies the idle timeout interval in minutes. Active connections are deactivated after the specified time interval. This option corresponds to the IdleTimeout connection property.
Wait Time (ms)

Specifies the amount of time in milliseconds that elapses before Visual FoxPro determines whether the SQL statement has completed executing. This option corresponds to the WaitTime connection property.

See Also

Other Resources

Designers
CREATE CONNECTION command
DELETE CONNECTION Command
DISPLAY CONNECTIONS Command
LIST CONNECTIONS Command
MODIFY CONNECTION Command
RENAME CONNECTION Command


Data Environment Designer

Visual FoxPro 9.0
Data Environment Designer
See Also

Use the Data Environment Designer to visually create and modify the data environment of forms, form sets, and reports. When the Data Environment Designer window is active, Visual FoxPro displays the Data Environment menu, which makes it possible for you to manipulate data environment objects. To display the Properties window and Code window, right-click to display the Data Environment shortcut menu, and then click Properties and Code.

A data environment defines the source for the data used in a form or report. This can include tables, views, and relationships. The data environment is saved with the form or report and can be modified whenever you are using the Report Designer or Form Designer.

When the data environment of a form or report is defined, Visual FoxPro automatically opens the tables or views when you open or run the file and closes them when the file is closed or released.

  • For forms, Visual FoxPro populates the ControlSource property list in the Properties window with all the fields in your data environment.

  • For reports, Visual FoxPro populates the data set your report needs based on associated tables and views.

  • For more information about using the Data Environment Designer with forms, see Creating Forms.

See Also

Other Resources

Designers
Code Window
ControlSource Property
Properties Window
Report Designer
Form Designer
Database Designer
Label Designer


Database Designer (Visual FoxPro)

Visual FoxPro 9.0
Database Designer (Visual FoxPro)
See Also

The Database Designer displays all the tables, views, and relationships contained in a database. When the Database Designer window is active, Visual FoxPro displays the Database Menu and the Database Designer toolbar.

Each table is represented by a resizeable window that lists the table's fields and indexes, if any exist. The Database Designer shows persistent relationships by displaying lines between tables that connect the indexes.

You can position the tables and views by dragging them into place, or using the Arrange command on the Database menu. If you want to show or hide objects in the window, you can use the Properties command on the Database menu.

See Also

Other Resources

Designers
CREATE DATABASE Command
How to: Set Temporary Relationships Between Tables
Developing Databases


Form Designer

Visual FoxPro 9.0
Form Designer
See Also

Use the Form Designer to visually create and modify forms and form sets. A form set consists of one or more forms that can be manipulated as a unit. Forms and form sets are objects with their own properties, events, and methods.

When the Form Designer window is active, Visual FoxPro displays the Form menu, the Form Controls toolbar, the Form Designer toolbar, and the Properties window.

You can run the form by clicking the ! icon in the toolbar or by pressing CTRL+E while in the code editor. When reopening the Form designer, the code editor reopens to the same location in the code.

For information about editing event and method code, see Creating Forms.

The Form Designer window consists of:

Form Window

Contains a single form on which you add and modify controls. More than one form window is displayed in the Form Designer when you modify a form set containing multiple forms. Form windows can be moved around within the FormDesigner.

See Also

Other Resources

Designers
Class Designer
Forms Tab, Options Dialog Box
Form Wizard
PageFrame Control
Properties Window
How to: Add Visual FoxPro Controls to a Form


Label Designer

Visual FoxPro 9.0
Label Designer
See Also

You can create and modifying labels using the Label Designer. The Label Designer is the same as the Report Designer and uses the same menus and toolbars. The main difference is that the Label Designer automatically defines the page layout and its columns based on the label size you select. For information about opening the Label Designer, see How to: Create Labels.

The Label Designer uses bands and controls to manage the layout of data on a label page.

Bands

Bands make it possible for you to specify where and when data displays on the label page. The Label Designer contains three bands by default:

  • Page Header Displays information or data that displays once per page at the beginning of the page.

  • Detail Displays information or data that displays once per record in the underlying table.

  • Page Footer Displays information or data that displays once per page at the end of a page.

Each band is followed by a separator, which contains the name of the band and an upward-pointing arrow indicating the space that the band occupies. Detail bands are indicated by filled arrows, while all other bands are indicated by empty arrows.

You can add other bands to your layout. For more information, see Working with Report Bands.

Ruler

The Label Designer displays a vertical and horizontal ruler that you can use to position objects more precisely in bands. The scale for the ruler is determined by your system measurement settings.

See Also

Other Resources

Designers
Label Wizard
CREATE LABEL Command
MODIFY LABEL Command


Menu and Shortcut Designers

Visual FoxPro 9.0
Menu and Shortcut Designers
See Also

You can create menus, menu items, submenus, lines that separate groups of related menu items, shortcut menus, and so on using the Menu Designer and the Shortcut Designer. By creating your own menus and shortcut menus, you can customize your copy of Visual FoxPro or design menus for applications you intend to distribute.

The Menu and Shortcut Designers contain the following elements and options:

Prompt

Specifies menu titles and menu items in menus or shortcut menus.
Mover Control

Appears as a double-headed arrow button to the left of the Prompt column when you insert at least one item. You can use the mover control to arrange the order of menu items at design time.
Result

Specify the action that occurs when you choose a menu title or menu item. For example, you can execute a command, open a submenu, or run a procedure.
Create

Appears when you select Submenu or Procedure in the Result column. You can use the Create button to specify a submenu or procedure for a menu title or menu item.
Edit

Appears only after you have created a submenu or procedure in the Result column for a menu item. Clicking the Edit button switches the Menu Designer to the submenu or procedure associated with a menu title or menu item.
Options

Opens the Prompt Options dialog box, which you can use to define keyboard shortcuts and other menu options.
Menu level

Specifies the menu, submenu, or shortcut you are editing.
Preview

Displays the menu you are creating.

Item Group

Insert

Inserts a new item in the Menu Designer window.
Insert Bar

Available only when an item is selected in the Shortcut Designer and opens the Insert System Menu Bar dialog box, which makes it possible for you to select and insert standard Visual FoxPro menu items.
Delete

Available only when an item is selected and deletes the selected row from the Menu Designer.
Move Item

Available only when an item is selected and opens the Move Item dialog box, which you can use to change the location of the menu item.

See Also

Other Resources

Designers
Dialog Boxes
Prompt Options Dialog Box
Creating Menus, Shortcut Menus, Menu Items, and Submenus
Insert System Menu Bar Dialog Box
Move Item Dialog Box
General Options Dialog Box
Menu Options Dialog Box


Query and View Designers

Visual FoxPro 9.0
Query and View Designers

To create and modify queries and views, use the Query Designer and View Designer. When the Query or View Designer is active, the Query menu and the Query Designer or the View Designer toolbar are visible.

The top pane of the designer displays the tables in the query or view. A resizable window representing each table lists the fields and indexes in the table. The designer shows join conditions by displaying lines that connect fields between tables. You can drag indexed fields between tables to create join conditions. To display the Join Condition Dialog Box for editing the condition, double-click a line.

In This Section

Fields Tab, Query and View Designers

Specifies fields, aggregate functions, such as SUM Command or COUNT Command, or other expressions.
Join Tab, Query and View Designers

Specifies join expressions for matching records between two or more tables or views.
Filter Tab, Query and View Designers

Specifies conditions for selecting records, such as specific values in a field, or join conditions defining temporary relationships between tables.
Order By Tab, Query and View Designers

Specifies fields, aggregate functions, such as SUM Command or COUNT Command, or other expressions used to set the order of records retrieved in the query.
Group By Tab, Query and View Designers

Specifies fields, aggregate functions, such as SUM Command or COUNT Command, or other expressions used to combine records into a group based on identical values in those fields.
Update Criteria Tab, View Designer

Specifies fields to be updated and criteria for fields to be updated (View Designer only).
Miscellaneous Tab, Query and View Designers

Specifies if duplicates should be retrieved and limits on records, such as the top quantity or percentage.

Related Sections

Designers

Provides information about Visual FoxPro designers, which make it possible for you to design windows, dialog boxes, and components visually for your application.


Fields Tab, Query and View Designers

Visual FoxPro 9.0
Fields Tab, Query and View Designers
See Also

Specifies fields, aggregate functions, and other expressions for query or view output. This tab appears in the Query and View Designers.

Available fields

Lists all the fields available in the tables of the query or view. You can select all available tables and their fields by choosing the asterisk (*), all fields in a particular table by choosing table.*, or individual fields for your query or view. Your selections appear in the SELECT statement in the SQL window when you click the SQL button or choose View SQL from the Query menu. If you select a field in the Available Fields list, its name automatically appears in the Functions and expressions edit box and in the Expression edit box of the Expression Builder, which opens when you click the ellipsis (...) button.
Functions and expressions

Specifies a function or expression. You can either type an expression directly into the box or select a function from a list in the Expression Builder, which opens when you click the ellipsis (...) button. After creating your expression, you can add it to the Selected fields box by clicking the Add button.
Selected fields

Lists the selected fields, aggregate functions, and other expressions that appear in the query or view results. You can rearrange the order of the output by dragging the vertical double arrow to the left of the fields.
Add

Adds the selected item from the Available fields box or the Functions and expressions box to the Selected fields box.
Add All

Adds all fields from the Available fields box to the Selected fields box.
Remove

Removes the selected item from the Selected fields box.
Remove All

Removes all items from the Selected fields box.
Properties

Displays the View Field Properties Dialog Box, which makes it possible for you to specify options for fields in a view just as you do for fields in database tables. This option is available only in the View Designer.

See Also

Other Resources

Filter Tab, Query and View Designers
Group By Tab, Query and View Designers
Order By Tab, Query and View Designers
Update Criteria Tab, View Designers
Join Tab, Query and View Designers


View Field Properties Dialog Box

Visual FoxPro 9.0
View Field Properties Dialog Box
See Also

Use to specify options for fields in a view just as you can for fields in database tables. You can define properties to determine the type of data the field stores, to control data entry for updatable views, and to control the display of the field.

This dialog box appears when you select a field and click the Properties button on the Fields tab of the Query and View Designers.

Field

Specifies the name of the selected field in the view. To set properties on other selected fields, you can choose from the drop-down list. The field appears with its sequential field number.

Field Validation Options

These options allow you to control the contents of the field.

Rule

Specifies the expression for the field-level rule that controls which values can be entered into the field.
Message

Specifies the error message displayed when the field-level rule is violated.
Default value

Specifies a quantity or string that is the content for a field when a new record is added. The default value remains in the field until you enter a new value.

Display Options

These options allow you to control how values are entered or displayed in the field.

Format

Specifies the expression for case, size, and style for display of the field in the Browse window, forms, or reports. Property settings within the form and report can override this expression.
Input Mask

Specifies the format for values as they are entered into the field. For example, telephone numbers might have a format of (999) 999-9999.
Caption

Specifies the label that appears for the field in the Browse window, forms, or reports. Property settings within the form or report can override this setting. To specify an expression for a field caption, include the equal sign (=) preceding the caption string. If an equal sign is not found, it is treated as a string literal. Expressions cannot exceed 254 characters. If the expression exceeds 254 characters, the caption defaults to the field name.
Note:
Support for using expressions as field captions should be used only with DBC tables in applications running on Visual FoxPro 8.0 or later. In earlier versions, the expression appears as a string literal.

Map Field Type to Classes Options

If you plan to use the view field in forms, these options allow you to specify a default control type that appears when you drop the field on a form.

Display library

Specifies the class library file (.vcx) containing the control class you want to associate with the field.
Display class

Specifies the type of control that is created when the field is dropped onto a form.

Data Mapping Options

By default, the view field has the same property settings as its associated field in a table. These options are only enabled for remote views.

Data type (remote views only)

Specifies the kind of data this field can hold.
Width (remote views only)

Specifies the number of characters this field can hold.
Decimal (remote views only)

For numeric data types, specifies the number of places to the right of the decimal point this field can hold.
Comment (remote views only)

Provides space for you to type a comment about the field.

See Also

Other Resources

Join Tab, Query and View Designers
Fields Tab, Query and View Designers
How to: Create Default Values for View Fields
Filter Tab, Query and View Designers


Join Tab, Query and View Designers

Visual FoxPro 9.0
Join Tab, Query and View Designers
See Also

Specifies join conditions for matching and selecting records in one or more tables or views, for example, specific values in a field or join conditions that define temporary relationships between tables. This tab appears in the Query and View Designers.

Settings in the Join tab determine the join conditions that appear in the FROM clause of the SELECT - SQL Command that is generated and that appears in the SQL window. The View Designer loads and generates any FROM clause with or without the JOIN option, using parentheses where needed in the ON clause.

Condition Button

Appears if two or more tables are joined in the query. Click the double-headed horizontal arrow to edit the selected condition or query criterion in the Join Condition Dialog Box, which will update entries in the other columns.
Left Table

Contains the alias of the left table in the join or "<Prev join>", which means the left table in the join is actually the previous subjoin.
Join type

Specifies the type of join condition. By default, the join type is Inner Join. When creating a new join condition, click the field to display a drop-down list of the join types.
  • Inner Join Specifies that only the records that match the join condition are included in the results. This type is the default and most commonly used type of join.

  • Left Outer Join Specifies that all the records in the left table, regardless whether they match the join condition, and only those records in the right table that match the join condition, are included with the results.

  • Right Outer Join Specifies that all the records in the right table, regardless whether they match the join condition, and only those records in the left table that match the join condition, are included with the results.

  • Full Join Specifies that both records that match and do not match the join condition are included in the results. The field must match the example text, character for character.

  • Cross Join Specifies that each record in the left table is matched with all records in an existing right table. When a WHERE clause does not exist, setting a cross join produces a Cartesian product result set. A Cartesian product contains the set of all possible combinations of each element in a set with all elements in another set.

    The Cross Join option makes it possible to modify the table sequence appearing in the FROM clause of the SQL SELECT statement in the SQL window for the query or view. Selecting Cross Join inserts a comma (,) that separates tables in the FROM clause.

    Note:
    You can specify a cross join only for the left table, which cannot be a previous join (<Prev join>). You cannot specify a cross join when adding new tables to the query or view, so if you want to set a specific sequential position for the table, you must manually add the cross join for the table.

    Outside the Query and View designers, cross joins are not supported in Visual FoxPro SQL SELECT command syntax. Cross joins are supported only for modifying the sequence of tables in Query and View Designers.

    When parsing the SQL SELECT statement, Visual FoxPro puts every table from the FROM clause that is not involved in the join into the Join tab. A row with "<alias> Cross join" appears in the join list. The sequence of tables in the FROM clause of the SQL SELECT statement matches the sequence of joins in the Join tab. When generating queries, Visual FoxPro uses this information to place a table in the correct position as specified by the FROM clause. When changes are reloaded in the Query and View designers, they are updated in the Join tab.

    If a table is not referenced in the Join tab, Visual FoxPro places it at the beginning of the FROM clause. If several unreferenced tables exist, all such tables are placed randomly at the beginning of the FROM clause.

Pri. (Priority)

Specifies a number ranging from 0 to 99, which indicates a priority for the join operation. The number 0 specifies the highest priority, while the number 99 specifies the lowest priority. Setting priorities for join operations determines the order in which joins are performed and uses parentheses (()) to group operations. For example, suppose you specify a priority of 0 for a join operation, a priority of 1 for a second join operation, and a priority of 0 for a third join operation. The first and third join operations, which have a priority of 0, are performed before the second join operation, which has a priority of 1.
Right Table

Contains the alias of the right table in the join or "<Next join>", which means the right table in the join is actually the next subjoin.
Field Name

Specifies the first field of the join condition. When creating a new join condition, click the field to display a drop-down list of the available fields. You can also specify an expression.
Not

Reverses the condition to exclude records matching the condition.
Criteria

Specifies a condition operator:
  • Equal (=) Specifies that field and the value in the Example field have the same value.

  • Like Specifies that the field must include characters that match characters in the text in the Example field.

    For example, Customer.state Like O matches records from Ohio, Oklahoma, and Oregon.

  • Exactly Like (==) Specifies that the field must match, character for character, the text in the Example field.

  • Greater Than (>) Specifies that the field must be more than the value in the Example field.

  • Less Than (<) Specifies that the field must be the same or less than the value in the Example field.

  • Greater Than or Equal To (>=) Specifies that the field must be the same or more than the value in the Example field.

  • Less Than or Equal To (<=) Specifies that the field must be the same or less than the value in the Example field.

  • Is NULL Specifies that the field must contain a null value.

  • Is True Specifies the left field or expression evaluates to True, assuming the field or expression evaluates to a logical value.

  • Between Specifies that the field must be greater than or equal to the lower value, and less than or equal to the higher value, in the condition appearing in the Example column. You must separate the two values in the Example field with the word AND. Visual FoxPro creates the query with the word BETWEEN.

    For example, Invoices.idate Between 05/10/97 AND 05/12/97 matches records for the 10th, 11th, and 12th of May, 1997.

  • In Specifies that the field must match one of several values in the comma-separated list appearing in the Example field.

    For example, Customer.name In Al,George,Mary matches records in which the customer's name is Al, George, or Mary.

Value

Specifies the other table and field in the join condition. You can also specify an expression.
Logical

Adds an AND or OR condition to the list of join conditions.
Pri. (Priority)

Specifies a number ranging from 0 to 99, which indicates the priority for logical operations. The number 0 indicates the highest priority, while the number 99 indicates the lowest priority. Setting priorities for logical operations determines the order in which logical operations are performed and uses parentheses (()) for grouping operations. For example, suppose you specify a priority of 0 for a logical operation, a priority of 1 for a second logical operation, and a priority of 0 for a third logical operation. The first and third logical operations, which have a priority of 0, are performed before the second logical operation, which has a priority of 1.
Insert button

Inserts a blank join condition above the selected condition.
Remove button

Removes the selected condition from the query.

See Also

Other Resources

Join Conditions for Tables, Queries, and Views
How to: Query Multiple Tables and Views
Fields Tab, Query and View Designers
Group By Tab, Query and View Designers
Order By Tab, Query and View Designers
Update Criteria Tab, View Designer
Filter Tab, Query and View Designers


Filter Tab, Query and View Designers

Visual FoxPro 9.0
Filter Tab, Query and View Designers
See Also

Determines the conditions for selecting records as listed in the WHERE clause of the SELECT - SQL Command in the SQL window. You can load and save a query or view with a subquery in the WHERE clause. This tab appears in the Query and View Designers.

Mover box

Drag the mover box to move the selected item up or down within the grid.

Condition Button

Click the double-headed horizontal arrow to edit the selected filter.
Field Name

Specifies the first field of the filter condition. When creating a new filter condition, click the field to display a drop-down list of the available fields.
Not

Reverses the condition to exclude records matching the condition.
Criteria

Specifies a comparison operator:
  • Equal (=) Specifies that field and the value in the Example field have the same value.

  • Like Specifies that the field must include characters that match characters in the text in the Example field.

    For example, Customer.state Like O matches records from Ohio, Oklahoma, and Oregon.

  • Exactly Like (==) Specifies that the field must match, character for character, the text in the Example field.

  • Greater Than (>) Specifies that the field must be more than the value in the Example field.

  • Less Than (<) Specifies that the field must be the same or less than the value in the Example field.

  • Greater Than or Equal To (>=) Specifies that the field must be the same or more than the value in the Example field.

  • Less Than or Equal To (<=) Specifies that the field must be the same or less than the value in the Example field.

  • Is NULL Specifies that the field must contain a null value.

  • Is True Constructs a WHERE clause containing only the left field where the field or expression evaluates to True, assuming the field or expression evaluates to a logical value.

  • Between Specifies that the field must be greater than or equal to the lower value, and less than or equal to the higher value, in the condition appearing in the Example column. You must separate the two values in the Example field with the word AND. Visual FoxPro creates the query with the word BETWEEN.

    For example, Invoices.idate Between 05/10/97 AND 05/12/97 matches records for the 10th, 11th, and 12th of May, 1997.

  • In Specifies that the field must match one of several values in the comma-separated list appearing in the Example field.

    For example, Customer.name In Al,George,Mary matches records in which the customer's name is Al, George, or Mary.

  • Exists Specifies that the records returned contain the criterion in the Example field. When the filter condition specifies Exists, the filter condition evaluates to True (.T.) unless the subquery returns an empty set.

    In the following example, specifying Exists returns every customer that has an order:

    Copy Code
    SELECT Customer.cust_id, Customer.company;
 FROM testdata!customer;
 WHERE Exists (select * from orders where customer.cust_id = ;
   orders.cust_id)
Example

Specifies the value or text with which you want to compare the field. To match the text casing of the example, use the UPPER( ), LOWER( ), and PROPER( ) functions.
Logical

Adds an AND or OR condition to the filter condition list.
Pri. (Priority)

Specifies a number ranging from 0 to 99, which indicates the priority for logical operations. The number 0 indicates the highest priority, while the number 99 indicates the lowest priority. Setting priorities for logical operations assigns the order in which each logical operation is performed. In effect, the behavior is similar to using parentheses (()) to group operations. For example, suppose you specify a priority of 0 for a logical operation, a priority of 1 for a second logical operation, and a priority of 0 for a third logical operation. The first and third logical operations with priority 0 are performed before the logical operation with priority 1.
Insert button

Inserts a blank filter condition above the selected condition.
Remove button

Removes the selected condition from the query.

See Also

Other Resources

Filter Conditions for Queries and Views
Fields Tab, Query and View Designers
Group By Tab, Query and View Designers
Join Condition Dialog Box
Order By Tab, Query and View Designers
Update Criteria Tab, View Designer


Order By Tab, Query and View Designers

Visual FoxPro 9.0
Order By Tab, Query and View Designers
See Also

Specifies fields, aggregate functions such as SUM Command or COUNT Command, or other expressions used to set the order of records retrieved in the query.

You can select fields from the Order By tab that are not included in the SELECT list. This tab appears in the Query and View Designers.

Selected Output

Lists the selected fields and expressions that will appear in the query results.
Ordering Criteria

Specifies the fields and expressions used in the query's sort order. The arrow that appears to the left of each field specifies an ascending (up) or descending (down) sort. A mover box appears to the left of the arrow for changing the order of the fields.

Order Options

Ascending

Sets the selected item in the Ordering Criteria box to sort in ascending order.
Descending

Sets the selected item in the Ordering Criteria box to sort in descending order.
Add

Adds the selected item in the Selected Output box to the Ordering Criteria box.
Remove

Removes the selected item from the Ordering Criteria box.

See Also

Other Resources

COUNT Command
Fields Tab, Query and View Designers
Filter Tab, Query and View Designers
Group By Tab, Query and View Designers
SELECT - SQL Command
SUM Command
Update Criteria Tab, View Designer


Group By Tab, Query and View Designers

Visual FoxPro 9.0
Group By Tab, Query and View Designers
See Also

Groups rows of query or view results. This tab appears in the Query and View Designers. For more information, see the GROUP BY clause in the SELECT - SQL Command.

Available Fields

Lists all the available fields in the tables of a query or view and other expressions.
Grouped Fields

Lists the fields, aggregate functions, and other expressions for determining the grouping of the query results. Fields are grouped in the order they appear in the list. You can change the field order and the grouping hierarchy by dragging the double-headed arrow to the left of each field.
Add

Adds the selected item in the Available Fields box to the Group By Fields box.
Remove

Removes the selected item from the Group By Fields box.
Having

Displays the Having Dialog Box for setting selection criteria on groups rather than on individual records.

See Also

Other Resources

Fields Tab, Query and View Designers
Filter Tab, Query and View Designers
Having Dialog Box
Order By Tab, Query and View Designers
SELECT - SQL Command
Update Criteria Tab, View Designer


Update Criteria Tab, View Designer

Visual FoxPro 9.0
Update Criteria Tab, View Designer
See Also

Specifies conditions for sending changes in the view to the original records in the tables used in the view. The Update Criteria tab appears only in the View Designer.

Table

Specifies which tables used in the view can accept changes. The list shows the tables that have fields in the Selected fields list of the Fields Tab, Query and View Designers.
Reset Key

Selects the primary key field from each table as the key fields for the view and places a check mark under the key symbol in the Field name list for each primary key field. Key fields are used for matching the changes in the view to the original record in the table.
Update All

Selects all fields other than the key fields for updating and places a check mark under the pencil symbol in the Field name list.
Send SQL Updates

Specifies whether changes to the records in the view are actually sent to the original tables.
Field Name Pane

Shows the fields that you have selected for output and, therefore, are available to update.
  • Key Field (marked with a key symbol) Specifies whether the field is a key field.

  • Updatable (marked with a pencil symbol) Specifies whether the field is updatable.

  • Field Name Displays the name of the output fields available to mark as key fields or updatable.

SQL WHERE Clause Includes

Controls which fields are added to the WHERE clause to detect update conflicts on the server when the changes to the view are sent to the original tables.

A conflict is based on a comparison between the old values in the view, OLDVAL( ), and the current values in the original table, CURVAL( ). If the values are equal, the original table is considered unchanged and no conflict exists. If they are not equal, a conflict exists and the data source returns an error.

The error returned for a conflict between the old value and the current value is Error 1585 "Record has been modified by another" or Error 1494 "Update conflict. Use TABLEUPDATE( ) to force the update or TABLEREVERT( ) to rollback".

Key Fields Only

Sets the WHERE clause to detect a conflict if a key field has been changed in the original table. Changes made by another user to any other field in the original record of the table are not compared.
Key and Updatable Fields

Sets the WHERE clause to detect a conflict if another user changed any of the fields that were updatable.
Key and Modified Fields

Sets the WHERE clause to detect a conflict if the key field or one of the modified fields in the record in the original table has changed since the view was first retrieved (default).
Key and Timestamp

Sets the WHERE clause to detect a conflict if the timestamp of the record on the original table has changed since it was first retrieved. This option is only available if the remote table has a timestamp column.

Update Using

Specifies how updates are performed on the back-end server.

SQL DELETE then INSERT

Deletes the record from the original table, and then creates a new record from the modified record in the view.
SQL UPDATE

Uses the changes in the fields of the view to modify the fields in the original table.

See Also

Other Resources

Fields Tab, Query and View Designers
Filter Tab, Query and View Designers
Group By Tab, Query and View Designers
Order By Tab, Query and View Designers
Query and View Designers


Miscellaneous Tab, Query and View Designers

Visual FoxPro 9.0
Miscellaneous Tab, Query and View Designers
See Also

Specifies other record selection conditions for the query or view. This tab appears in the Query and View Designers.

Note:
It is possible to add multiple conflicting options by clicking the Cross tabulate, Report, and Label buttons multiple times. The Query Designer will attempt to warn you and provide the option to remove the previous command if it is the first conflict found. You should make sure that only the desired optional code appears in the query.

No duplicates

Eliminates duplicate records from the query or view results. Duplicate records are records in which every field matches.
Force join

Changes statement parsing or generation to support the FORCE option in the FROM clause, that is, to specify that tables are joined in the order in which they appear in the FROM clause. To enable the force join option, select Force join.
Top

Selects a quantity or percentage of records from the result set. When specifying a number or percentage, use the Order By Tab, Query and View Designers to choose which records are at the top of the result set. All Specifies that all of the records selected by the query or view should be included in the results set. Number of records Sets a quantity of records of the selected records to include in the results set. Percent Changes the number in the box above to a percentage of records.
Cross tabulate (Queries only)

Sends the results of the query or view to Microsoft Graph, a report, or a table in cross-tabular format. You query must contain exactly three items that represent the X-axis, the Y-axis, and the cell value for the graph. Visual FoxPro inserts the following example code:
Copy Code
INTO CURSOR SYS(2015)
* To execute the following command, result should have three columns.
DO (_GENXTAB) WITH 'T2 t1'
Note:
The INTO CURSOR clause is added only if the query does not already have such a clause.

For example, you could generate a report that shows the amount billed to clients by month. You would create a graph that displays clients down the left side of the page, the twelve months across the top of the page, and, within the graph, the amount billed to each client each month.
Report (Queries only)

Generates the appropriate REPORTFORM command and opens the Report dialog box that makes it possible for you to set report and certain option settings. Visual FoxPro inserts following example code:
Copy Code
INTO CURSOR SYS(2015)
REPORT FORM tbl2.frx TO PRINTER PLAIN
Note:
The INTO CURSOR clause is added only if the query does not already have such a clause.

Note:
An existing REPORT FORM command in the Query window is not parsed, and its settings are not reflected in the dialog box. You must re-enter the desired dialog box options. After clicking OK, you will be prompted to replace the existing command. You will be presented with this option only if the REPORT FORM command is the first item after the query. If you insert any code before the REPORT FORM command, a new REPORT FORM command is placed immediately after the SQL statement.

Label (Queries only)

Generates the appropriate LABEL FORM command and opens the Label dialog box that makes it possible for you to set label and certain option settings. Visual FoxPro inserts the following example code:
Copy Code
INTO CURSOR SYS(2015)
LABEL FORM tbl2.lbx TO PRINTER
Note:
The INTO CURSOR clause is added only if the query does not already have such a clause.

Note:
An existing LABEL command in the Query window is not parsed, and its settings are not reflected in this dialog box. You must re-enter the desired dialog box options. After clicking OK, you will be prompted to replace the existing command. You will be presented with this option only if the LABEL command is the first item after the query. If you insert any code before the LABEL command, a new LABEL command is placed immediately after the SQL statement.

See Also

Other Resources

Fields Tab, Query and View Designers
Filter Tab, Query and View Designers
Group By Tab, Query and View Designers
Order By Tab, Query and View Designers
Report Dialog Box
Label Dialog Box


Report Designer

Visual FoxPro 9.0
Report Designer
See Also

You can create and modify reports using the Report Designer. When the Report Designer window is active, Visual FoxPro displays the Report menu and the Report Controls toolbar. For more information, see Working with Reports.

The Report Designer uses report bands and report controls to manage the layout of information and data on the report page.

Bands

Bands make it possible for you to specify where and when data displays on the report page. The Report Designer contains three bands by default:

  • Page Header Displays information or data that displays once per page at the beginning of the page.

  • Detail Displays information or data that displays once per record in the underlying table.

  • Page Footer Displays information or data that displays once per page at the end of a page.

Each band is followed by a separator, which contains the name of the band and an upward-pointing arrow indicating the space that the band occupies. Detail bands are indicated with filled arrows; all other bands are indicated with empty arrows.

You can add other bands to your layout. For more information, see Working with Report Bands.

Ruler

The Report Designer displays a vertical and horizontal ruler that you can use to position objects more precisely in bands. The scale for the ruler is determined by your system measurement settings.

See Also

Other Resources

Report Wizard
CREATE REPORT – Quick Report Command
CREATE REPORT Command
Designers


Table Designer (Visual FoxPro)

Visual FoxPro 9.0
Table Designer (Visual FoxPro)

Use the Table Designer to create and modify database tables, free tables, fields, and indexes. The Table Designer helps you implement advanced features, such as validation rules, default values, and default control classes.

In This Section

Fields Tab, Table Designer

Displays table fields in a scrollable grid.
Indexes Tab, Table Designer

Contains a scrollable grid for defining indexes.
Table Tab, Table Designer

Displays the information about the table and makes it possible for you to specify triggers and record-level rules.

Related Sections

Designers

Provides information about Visual FoxPro designers, which make it possible for you to design windows, dialog boxes, and components visually for your application.


Fields Tab, Table Designer

Visual FoxPro 9.0
Fields Tab, Table Designer
See Also

The Fields tab displays slightly different information depending on whether you open a database table or a free table. If you are creating a database table, the Fields tab includes options for setting validation rules. If you are creating a free table, the Fields tab contains only basic field name, type, and formatting options.

The Fields tab displays table fields in a scrollable grid. Each row contains the field's name, data type, character width, decimal width, and support for null values. Click a cell in the grid to modify a field.

Mover Button

This is the double-headed arrow button at the extreme left of the row. Once you have entered two or more rows, use the mover button to move a row up or down in the list.
Name

Specifies the name of the field. Spaces are not accepted. For database tables, the length of the name can be up to 128 characters. For more information, see Creating Visual FoxPro Names.
Type

Specifies the field's data type. Click the drop-down arrow to select a data type from the list.
Width

Specifies the number of characters or digits the field can store.
Decimal

Specifies the number of digits to the right of the decimal point. The Decimal column applies to numeric and double data types.
Index

Specifies a regular index on the field for ordering the data.
NULL

When checked, specifies that the field can accept a null value.
Insert Button

Inserts a new field above the selected field.
Delete Button

Deletes the selected field from the table.
Display

Specifies the format properties for entering and displaying the field. Format Specifies the expression for case, size, and style for display of the field in the Browse window, forms, or reports. Property settings within the form and report can override this expression. Input mask Specifies the format for values as they are entered into the field. For example, telephone numbers might have a format of (999) 999-9999. Caption Specifies the label that appears for the field in the Browse window, forms, or reports. Property settings within the form or report can override this setting. To specify an expression for a field caption, include an equal sign (=) preceding the caption string. Expressions cannot exceed 254 characters. If the expression exceeds 254 characters, the caption defaults to the field name.
Note:
Support for using expressions as field captions should be used only with DBC tables in applications running on Visual FoxPro 8.0 or later. In earlier versions, the expression appears as a string literal.

Field validation

If you are modifying a database table, the Field Properties option group appears below the scrollable grid. Properties settings for the selected field are specified in this area. Choose the dialog button to the right of each property setting to display the Expression Builder Dialog Box, or just type the expression directly. Entries for these options are not required. Rule Specifies the field-level rule for enforcing data validation. Message Specifies the error message to be displayed if an entry violates the field-level validation rule. Default value Specifies the default value for the field.
Map field type to classes

To specify a default control class, set the library and class you want to create when you drag the field onto a form. Display library Specifies the path and file name for the class library. To browse for a file, use the dialog button. Display class Specifies the default control class for the field.
AutoIncrement

To set the start and increment values after enabling autoincrementing for a field, select values from the Next Value and Step spin boxes. For more information about autoincrementing, see Autoincrementing Field Values in Tables. Next Value Specifies the start value for a field using autoincrementing. You can select a positive or a negative integer value from 2,147,483,647 to -2,147,483,647. The default value is 1. Step Specifies the increment value for a field using autoincrementing. You can select a positive, nonzero integer value from 1 to 255. The default value is 1.
Field comment

Provides a space to enter notes about the field.

See Also

Other Resources

Expression Builder Dialog Box
Indexes Tab, Table Designer
Table Wizard
Creating Visual FoxPro Names
Table Designer


Indexes Tab, Table Designer

Visual FoxPro 9.0
Indexes Tab, Table Designer
See Also

The Indexes tab in the Table Designer makes it possible for you to create indexes for a table.

Mover button

Moves an index entry up or down the list. Appears as button with a double-headed arrow to the left of the index row after you enter two or more rows.
Order

Specifies the sort order for the index. An up arrow indicates an ascending sort; a down arrow, descending.
Name

Specifies the index tag name for the index. The arrow button to the left of the index name specifies ascending or descending order. Select the index, and then click on the arrow button to change the order.
Type

Specifies an optional index type. A table can have only one index set as the primary index in the Type column.
Note:
If a table contains an index with Unique type, the Table Designer displays that type; however, the designer no longer provides the Unique type as an available option.

For more information about index types, see Visual FoxPro Index Types.
Expression

Specifies the index expression, such as a field name. Click the button to create or edit an expression in the Expression Builder Dialog Box. An expression can be up to 240 characters.
Filter

Specifies the filter expression. Click the button to create or edit an expression in the Expression Builder dialog box.
Collate

Specifies a collating sequence for the index tag. Click the arrow to select a Visual FoxPro collating sequence from the drop-down list. The default setting is "Machine".
Insert Button

Inserts a new index above the selected index in the grid.
Delete button

Deletes the selected index from the grid.

See Also

Other Resources

Table Tab, Table Designer
Fields Tab, Table Designer
INDEX Command
SYS(14) - Index Expression
SYS(2021) - Filtered Index Expression
Table Designer


Table Tab, Table Designer

Visual FoxPro 9.0
Table Tab, Table Designer
See Also

The Table tab appears in the Table Designer. It contains read-only information about the table and areas for setting the record-level rule and validation error text, triggers, and comments.

Note:
If you are modifying a free table, only the read-only statistics for the table are displayed on this tab. Free tables cannot have associated rules, triggers, or comments.

Name

Specifies the name of the table being created or modified. For database tables, the table name appears in the Project Manager; it is not the file name. Long names up to 128 characters are supported.
Database

Displays the name of the database to which the table belongs if the table is not a free table. This box is read-only.

Statistics

Displays read-only about the table.

Table file

Displays the path and file name for the table.
Records

Displays the quantity of rows currently stored in the table.
Fields

Displays the quantity of columns defined in the table structure.
Length

Displays the length of the table.

Record Validation

Sets the row-level rule, validation error text, and a comment for the table. The button to the right of each setting displays the Expression Builder Dialog Box.

Validation Rule

Specifies a record-level rule for enforcing data validation.
Validation Text

Specifies the error message to be displayed if an entry fails to conform to the record-level validation rule.

Triggers

Specifies rules for updates, inserts, and deletes.

INSERT Trigger

Specifies a rule to be triggered every time a record is inserted or appended to the table. Click the dialog button to display the Expression Builder Dialog Box.
UPDATE Trigger

Specifies a rule to be triggered every time a record is updated in the table. Click the dialog button to display the Expression Builder Dialog Box.
DELETE Trigger

Specifies a rule to be triggered every time a record is deleted from the table. Click the dialog button to display the Expression Builder Dialog Box.
Table Comment

Provides space for you to type a comment about the table. Whatever you type here appears as the description at the bottom of the Project Manager when this table is selected.

See Also

Reference

Table Tab, Table Designer

Other Resources

Expression Builder Dialog Box
FOR( ) Function
INDEX Command
SYS(14) - Index Expression
SYS(2021) - Filtered Index Expression
Table Wizard


Dialog Boxes (Visual FoxPro)

Visual FoxPro 9.0
Dialog Boxes (Visual FoxPro)

This section explains the options that appear on various dialog boxes.

In This Section

About Microsoft Visual FoxPro Dialog Box

Displays the Visual FoxPro copyright, licensing, and version information, as well as your product identification number.
Add Files to Source Control Dialog Box

Adds a file or selected files in your project to source code control.
Add Table or View Dialog Box

Allows you to select one or more existing tables or views on which to base your new query or local view.
Advanced Options Dialog Box

Makes it possible for you to fine-tune how records are retrieved in a view or how updates are made to the server or source tables.
Append From Dialog Box

Makes it possible for you to add records to the current table or view from another table, a spreadsheet, or text file.
Append From Options Dialog Box

Specifies fields to append and allows you to build an expression that must be met by records that are to be appended.
Arrange Tables and Views Dialog Box

Allows you to change the layout of tables and views in your database.
Beautify Options Dialog Box

Makes it possible for you to specify capitalization and indentation styles for editing window text.
Breakpoints Dialog Box

Allows you to specify options for breakpoints.
Build Options Dialog Box

Allows you to create a custom application or refresh an existing project.
Calculate Field Dialog Box

Makes it possible for you to select a mathematical operation to create a computed field.
Change Icon Dialog Box

Specifies an icon to be used for a linked or embedded object on a form or in a General field of a table.
Check In Files Dialog Box

Checks in changes made in your development environment working directory to your source code control database.
Check Out Files Dialog Box

Checks out a copy of the selected files from your source code control provider and places a writable copy in the corresponding development environment working directory.
Choose Field/Variable Dialog Box

Specifies a table field or variable.
Class Info Dialog Box

Shows various attributes of class members, their design-time appearance, and whether or not they are protected.
Code Page Dialog Box

Allows you to assign a code page to a .dbf file or text file that does not have one.
Comment Dialog Box

Allows you to enter notes or comments to identify the query or view and its purpose.
Compile Dialog Box

Allows you to compile program, menu, or query files.
Connections Dialog Box

Allows you to create and maintain database connections.
Coverage Dialog Box

Makes it possible for you to specify options for logging program execution.
Create Dialog Box

Allows you to specify the directory, name, and type of the new file.
Create One-To-Many Relationships Dialog Box

Establishes a one-to-many relationship, in which the child table can contain multiple records that correspond to one record in the parent table.
Customize Toolbox Dialog Box

Displays options for changing settings and editing categories or items for the Toolbox.
Data Grouping Dialog Box

Makes it possible for you to create group bands for separating groups of records visually, and displaying summary data for each group.
Database Properties Dialog Box

Allows you to choose the types of database objects that are displayed in the Database Designer.
Define Window Layout Dialog Box

Allows you to name and save window and toolbar configurations for reuse.
Delete (Records) Dialog Box

Makes it possible to mark records for deletion.
Description Dialog Box

Provides a text box where you can type a brief description identifying a file.
Detail Dialog Box

Sets height and other options for the Detail band in a report or label.
Do Dialog Box

Allows you to specify a program or form file to run.
Edit Bands Dialog Box

Displays a list of available bands so you can directly modify height, as well as entry and exit actions.
Edit Links Dialog Box

Makes it possible for you to change or break an object link.
Edit Properties Dialog Box

Allows you to set editing options for the current editing window or set color and font options for all editing sessions.
Edit Property/Method Dialog Box

Allows you to add new properties and methods or edit existing ones.
Edit Relationship Dialog Box

Allows you to alter a persistent relationship between tables.
Event Tracking Dialog Box

Makes it possible for you to see when each event occurs in relation to other events.
EXE Version Dialog Box

Displays information about the build number as well as other information that you supply.
Execution Throttle Dialog Box

Makes it possible for you to specify the delay in seconds between the execution of each line of code located in the Trace Window.
Export Dialog Box

Allows you to export data from Visual FoxPro tables to a text file, spreadsheet, or common table format.
Export Options Dialog Box

Specifies which records and fields to export.
Expression Builder Dialog Box

Makes it possible for you to create and edit expressions. An expression can be as simple as a field name or as complex as a calculation involving immediate IF functions, concatenations, and data type conversions.
Expression Builder Options Dialog Box

Sets preferences for the items displayed in the Expression Builder.
File Finder Dialog Box

Enables searches based on specified criteria.
Find Dialog Box

Makes it possible to search for text.
Find Table or View Dialog Box

Allows you to select a table or views you cannot locate in the database schema displayed in the Database Designer.
Font Dialog Box

Controls the type, style, and size of fonts in a text file, field, or label control in a report, label, or in the Command window.
Format (Field) Dialog Box

Specifies the value of an expression in a field control.
General Options Dialog Box

Allows you to specify code for an entire menu system.
Generate Menu Dialog Box

Lets you specify a name for the generated menu program and then generate the program.
Get Latest Version of Files Dialog Box

Gets the latest files from the source code control provider and places a local copy in the Project Manager.
Go To Line Dialog Box

Makes it possible for you to move the insertion point to the designated line in a text or program file or in the Command window.
Go To Record Dialog Box

Specifies which record to move the record pointer to.
Having Dialog Box

Specifies the conditions for selecting the groups of records to include in query output.
Import Dialog Box

Allows you to import data to a table from a spreadsheet or another table format.
Include File Dialog Box

Allows you to specify an include file containing predefined compile-time constants for a user-defined class, form, or form set.
Insert Object Dialog Box

Lists the OLE objects you can link or embed in your application for forms or General fields in tables.
Insert Object Reference Dialog Box

Makes it possible for you to see the name of all objects in the designer and insert a fully qualified reference to the object in your code.
Insert System Menu Bar Dialog Box

Allows you to add menus and menu options to the Menu Designer window.
Join Condition Dialog Box

Specifies a join condition between tables.
Label Dialog Box

Displays the resuls of a query in an existing label.
Locate Database Dialog Box

Makes it possible for you to locate or ignore a missing table or view.
Locate File Dialog Box

Makes it possible for you to locate or ignore a missing file or group of files.
Locate Record Dialog Box

Searches for a record in the active table or view that matches specified conditions.
Look Up Reference Dialog Box

Makes it possible for you to search for and replace code references or text in your projects or folders.
Look Up Reference Dialog Box, Options Dialog Box

Sets additional options for a code reference search.
Macros Dialog Box

Makes it possible for you to define key combinations using the CTRL key, ALT key, or function keys to perform a series of keystrokes.
Menu Options Dialog Box

Allows you to specify code for a specific menu.
More Windows Dialog Box

Displays a list of active windows from which you can choose.
Move Item Dialog Box

Makes it possible for you to change the location of a menu or menu item.
New Class Dialog Box

Specifies information for a new class, which is then used by the Class Designer.
New Dialog Box

Allows you to create new files using designers and wizards.
New File Dialog Box

Lets you create a new form, report, label, or query, depending on the type of file currently selected in the Project Designer.
New Label Dialog Box

Displays predefined Avery label types.
New Local View Dialog Box

Lets you create a view of local tables or other views in a database using either the Local View wizard or View designer.
New Method Dialog Box

Allows you to create a new method and specify the description and visibility of the method.
New Property Dialog Box

Allows you to create a new property and specify the description and visibility of the property.
New Remote View Dialog Box

Allows you to create a new remote view using the View designer or the Remote View wizard.
New Table Dialog Box

Allows you to create a new table in the database using the Table designer or the Table wizard.
Open Dialog Box

Allows you to open an existing file or create a new file.
Open Picture Dialog Box

Allows you to open an existing graphics file.
Options Dialog Box

Makes it possible for you to set different categories of options.
Page Setup Dialog Box

Makes it possible for you to specify paper, page, and printer settings.
Pane Customization Dialog Box

Used to create, modify, and delete panes in the Task Pane Manager.
Paste Special Dialog Box

Makes it possible for you to link or embed an OLE object from the Clipboard.
Print Dialog Box

Lets you print a text file, report, label, or the contents of the Command window or the Clipboard.
Print File Dialog Box

Allows you to search a drive or directory for a file to print.
Print Options Dialog Box

Lets you print a text file, report, label, or the contents of the Command window or the Clipboard.
Print When Dialog Box

Enables the conditional printing of an object based on the value of an expression and controls how objects print when bands are continued.
Project Information Dialog Box

Makes it possible for you to view and edit information about the project and its files.
Prompt Options Dialog Box

Lets you specify options for prompts in a customized menu system.
Report Page Setup Dialog Box

Makes it possible for you to specify page layout settings for reports.
Query Destination Dialog Box

Makes it possible for you to send the results of your query to seven different outputs. This command is available only for queries.
Quick Report Dialog Box

Makes it possible for you to select fields and a field layout for a report.
Recall (Records) Dialog Box

Lets you unmark records that are marked for deletion.
Rectangle/Line Dialog Box

Specifies position and printing options for rectangle and line controls.
Remove Files from Source Control Dialog Box

Removes selected files in your project from source code control.
Rename File Dialog Box

Allows you to rename the selected file.
Replace Dialog Box

Makes it possible for you to search for and replace specified text in the current file.
Replace Field Dialog Box

Changes values stored in one record or in a range of records.
Report and Label Print Options Dialog Box

Allows you to specify how much to print and create expressions that the selected records must meet in order to print.
Report Band Properties Dialog Box

Include options for column, group, and page headers and footers, titles, and so on.
Report Dialog Box

Displays the results of a query in a report layout.
Report Expression Dialog Box

Defines the contents of a field control in a report.
Report Picture Dialog Box

Makes it possible for you to include bitmaps, icons, or other information from a General table field in your report or label.
Report Variables Dialog Box

Makes it possible for you to create variables within a report.
Round Rectangle Dialog Box

Specifies the exact shape, position, and printing options for round rectangle controls.
Save As Class Dialog Box

Lets you save a form, or selected controls on a form, as a class definition.
Save As Dialog Box

Saves a new file or saves an existing file with a different name.
Save As HTML Dialog Box

Enables you to create a new HTML version of the current form, menu, report, or table.
Scope Dialog Box

Specifies the records that Visual FoxPro acts on in the current table or view.
Select Connection or Data Source Dialog Box

Allows you to select a data source or an existing connection to a data source to create a new remote view.
Select Dialog Box

Makes it possible for you to select an XML Web service and insert code for it in a program or code editing window.
Set Grid Scale Dialog Box

Lets you define horizontal and vertical increments of the grid in pixels and specifies whether the ruler displays in system units or pixels.
Set Index Order Dialog Box

Sets the index order for a child table.
Tab Order Dialog Box

Adjusts the order in which objects are accessed in the form when you use the keyboard.
Task Pane Options Dialog Box

Customizes the Task Pane Manager and the individual panes that it contains.
Optional Bands Dialog Box

Makes it possible for you to include a Title, Summary, or additional Detail bands in a report or label.
Toolbars Dialog Box

Makes it possible for you to create, edit, hide, and customize toolbars.
Undo Check Out of Files Dialog Box

Overwrites your changes to a file and copies the latest checked-in version to your development-environment working directory.
Update Project List Dialog Box

Displays the results of a project list update.
View Parameters Dialog Box

Sets up views that prompt for a value entry to complete the view.
Visual FoxPro Converter Dialog Box

Makes it possible for you to open files created in an earlier version of Visual FoxPro.
Visual FoxPro Transporter Dialog Box

Makes it possible to transport forms, labels, and reports across different Visual FoxPro platforms and versions.
Visual FoxPro XML Web Service Location Dialog Box

Specifies a local Uniform Resource Locator (URL) or virtual directory for publishing an XML Web service.
Visual FoxPro XML Web Services Publisher Dialog Box

Specifies information for publishing Visual FoxPro COM (.dll) Servers as XML Web services that can be accessed on the Web.
Visual FoxPro XML Web Services Registration Dialog Box

Specifies information for registering an XML Web service so you can use it in your applications.
Wizard Selection Dialog Box

Displays a list of wizards from which you can choose.
Work Area Properties Dialog Box

Makes it possible for you to modify the structure of a table, select index files and fields, and define data filters. This dialog box appears when you choose Properties from the Table Menu.
XML Web Service - Client Detail Dialog Box

Makes it possible for you to specify the control, or client, to which you want to bind the results of the XML Web service operation.
XML Web Service - Complex Types Dialog Box

Makes it possible for you to specify information for complex types such as table and field names for XML Web service operations that return ADO.NET DataSets or property names for a returned object.
XML Web Service - Operation Detail Dialog Box

Makes it possible for you to choose specific XML Web service operations, or methods, you want to call from your application. You can also specify parameter values for these operations.
XML Web Service - Parameter Values Dialog Box

Makes it possible for you to set parameter values or specify a control and its property as a parameter source for a selected XML Web service operation.
Zoom <property> Dialog Box

Displays the text value of the selected property.

Related Sections

User Interface Reference

Explains the options that appear on various dialog boxes, windows, and other user interfaces. These types of topics generally appear when you press F1 in a dialog box or window.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.
Reference

Includes topics on productivity tools, as well as the controls, objects, properties, methods, events, statements, functions, and constants available.
Utility Programs

Describes how these tools that are provided with Microsoft Visual FoxPro help speed the process of application development.


About Microsoft Visual FoxPro Dialog Box

Visual FoxPro 9.0
About Microsoft Visual FoxPro Dialog Box
See Also

Displays the Visual FoxPro copyright, licensing, and version information, as well as your product identification number.

To display this dialog box from the Help menu, choose About Microsoft Visual FoxPro.

System Info

Displays the Microsoft System Information tool which contains your system configuration information. To access help information about Microsoft System Information, press F1 or, choose Help Topics from the Microsoft System Information Help menu.

See Also

Other Resources

Dialog Boxes
SET HELP Command
HELP Command


Add Files to Source Control Dialog Box

Visual FoxPro 9.0
Add Files to Source Control Dialog Box
See Also

Adds a file or selected files in your project to source code control.

Files to add

Lists all the files you can add to source control.
Keep Checked out

Updates the source code control database with your changes but keeps the file checked out to you.
Comment

Displays comment associated with a file, or allows you to add or change one.

See Also

Other Resources

Dialog Boxes
Undo Check Out of Files Dialog Box
Remove Files from Source Control Dialog Box
Compiling Source Code


Add Table or View Dialog Box

Visual FoxPro 9.0
Add Table or View Dialog Box
See Also

Appears when you select Query or Local View in the New dialog box and then choose New File. In this dialog box, you select one or more existing tables or views on which to base your new query or local view.

Database

Displays the current database by default and lets you select another database.
Tables/Views in database

Displays the tables or views from the current database, depending on whether you select the Tables or Views option.
Alias

Specify an alias instead of the automatically generated alias to use for the table or view you select.
Add

Adds the table or view.
Other

Displays the Open dialog box, from which you can select a free table to add to the query.
Tables

Displays the tables from the current database in the Tables in database box.
Views

Displays the views from the current database in the Views in database box.

See Also

Other Resources

Dialog Boxes
Join Condition Dialog Box
Arrange Tables and Views Dialog Box
How to: Query Multiple Tables and Views
New Dialog Box
Open Dialog Box


Advanced Options Dialog Box

Visual FoxPro 9.0
Advanced Options Dialog Box
See Also

Allows you to fine-tune how records are retrieved in a view or how updates are made to the server or source tables. This command is available with views only.

Connection Information

Connection Name/Data source

Displays the name of the connection or data source being used to access the data in the view.
Share Connection

Specifies that Visual FoxPro is to use the same connection for new views you create. This option applies only to remote (ODBC) data. If you currently have a connection set up, you can set this option to Uses Current Connection for new views.

Data Fetching

Number of Records to Fetch at a Time

Controls how many records are returned at a time from the ODBC server or remote data source. For example, if you run a query that returns 1000 records, and you set this option to 100, the first 100 records will be displayed when you run the view, and the remaining records will be fetched in blocks of 100 as you continue to browse the results. Clicking All sets this value to –1, indicating that all records should be returned in the first fetch operation.
Maximum Number of Records to Fetch

Limits total number of records returned by a view. Clicking All sets this value to indicate that all records should be returned.
Use Memo When Character Field Length >=

Determines when long character fields should be converted to Memo fields in the output of your view.

Performance

Number of Records to Batch Update

Specifies number of records to update with a single command. For more information, see the REPLACE command and Scope Clauses.
Fetch Memo

Fetches Memo fields from the data source only when a memo field is activated in the view output.
Fetch remote data as needed

Disables progressive fetching and fetches rows only on an as-needed basis
Include Memo Fields in WHERE Clause

Specifies that when Visual FoxPro compares a record held locally to one on the server, it check for changes; memo fields should be included in this comparison. Some data sources don't support this option; in this case, including a memo field can cause the server to report changes, even if the records are the same.
Precompile SQL on Back-end Server

Specifies that Visual FoxPro pass the SQL query to the server to be compiled before being executed. If the server supports this option, queries can be executed substantially faster than if they are not compiled.

See Also

Other Resources

Dialog Boxes
View Parameters Dialog Box
Comment Dialog Box
Query and View Designers
REPLACE Command
Scope Clauses
Query Destination Dialog Box


Append From Dialog Box

Visual FoxPro 9.0
Append From Dialog Box
See Also

Lets you add records to the current table or view from another table, a spreadsheet, or text file. This dialog displays when you select Append Records from the Table menu.

Type

Specifies the file type from which to append records.
From

Provides space for you to type the name of the file from which to append records. If you do not know the name, choose the dialog button to display the Open Dialog Box and select the desired file.
To

Displays the path and file name of the table or view to which the records will be appended.
Options

Displays the Append From Options Dialog Box, in which you specify fields to append, and build an expression, which records to be appended must meet.

For more information, see Appending Data in Importing and Exporting Data.

See Also

Other Resources

Dialog Boxes
Append From Options Dialog Box
APPEND FROM Command
Browse Window
How to: Add Records to Tables
APPEND Command


Append From Options Dialog Box

Visual FoxPro 9.0
Append From Options Dialog Box
See Also

Specifies fields to append and allows you to build an expression that must be met by records to be appended. This dialog box appears when you choose Options in the Append From Dialog Box.

Criteria

Fields

Displays the Field Picker Dialog Box, where you select fields to append.
For

Displays the Expression Builder Dialog Box, where you create a For expression that every record must meet to be appended.

See Also

Other Resources

Dialog Boxes
Delete (Records) Dialog Box
APPEND FROM Command
APPEND Command


Arrange Tables and Views Dialog Box

Visual FoxPro 9.0
Arrange Tables and Views Dialog Box
See Also

This dialog box allows you to change the layout of tables and views in your database. Use it to arrange, align, or resize the tables and views in your database layout. For more information, see How to: Arrange Tables and Views in Databases.

This dialog box appears when you select Arrange from the Database menu.

Arrange

These options allow you to order the contents of the database layout.

By Name

Orders the tables and views by name.
By Type

Orders the tables together and the views together.

Align Objects

These options allow you to position the contents of the database layout in a line.

Vertically

Positions the objects in a line vertically in the Database Designer window.
Horizontally

Positions the objects in a line horizontally in the Database Designer window.
Resize objects to default height and width

By default, the objects in the database show five of the fields. If you changed the size of the objects to view more of the contents of the object, you can return to the default size.

See Also

Other Resources

Dialog Boxes
Database Designer


Beautify Options Dialog Box

Visual FoxPro 9.0
Beautify Options Dialog Box
See Also

Makes it possible for you to specify capitalization and indentation styles for program code appearing in an editing window. When a program file is open in the editing window, selecting the Beautify command from the Tools menu opens the Beautify Options dialog box.

Capitalization

Keywords

Provides ways to format keywords: UPPERCASE, lowercase, Mixed Case, or No change
Symbols

Provides ways to represent symbols: UPPERCASE, lowercase, Match with first occurrence, or No change. Match with first occurrence only affects the symbols available within the current editing window.

Indentation

Types of indent

Provides ways to indent text using Tabs, Spaces, or No Change. When selecting Spaces, type or select the number of spaces used to indent the text.
Text to indent

Makes it possible for you to specify what types of text should be indented. Comment Indents all text lines beginning with the comment identifier (*). Continuation lines Indents lines following the semicolon (;), which indicates the first line continuation mark. The indentation for Continuation lines continues at the same level until a new command line is entered.
Extra indent beneath

Provides extra indentation for the lines following the beginning of procedures and DO CASE control structures.

See Also

Other Resources

Dialog Boxes
Editing Window
_BEAUTIFY System Variable
Macros Dialog Box


Breakpoints Dialog Box

Visual FoxPro 9.0
Breakpoints Dialog Box
See Also

Makes it possible for you to specify options for breakpoints.

This dialog box appears when you choose Breakpoints from the Tools Menu, Debugger Window.

Type

The type of breakpoint. Choose one of the following settings:

Setting Description

Break at location

Stops execution at a line of code.

Break at location if expression is true

Stops execution at a line of code when an expression becomes true.

Break when '

Stops execution when an expression becomes true.

Break when expression has changed

Stops execution when the value of an expression changes.
Location

Where to suspend execution. The location can be a program, a procedure, or a specific method or event. You can suspend program execution at a particular line in the location by including the line number after the location and a comma.
Tip:
To display line numbers in the Trace Window, choose Show line numbers in the Debug Tab, Options Dialog Box.

File

The file that the location is in. The file can be a program, form, or class file. If you don't specify a file name, the breakpoint is evaluated for any method or procedure with the same name as the method or procedure in the Location box.
Pass Count

Number of times the line of code in the Location box must execute before program execution suspends.
Tip:
Use Pass Count with loops that encounter problems only after a certain number of iterations.

Expression

Any valid Visual FoxPro expression. When you choose Break when expression is true or Break at location if expression is true from the Type list, specify the expression here.
Breakpoints

Lists all breakpoints you have added. Enabled breakpoints are marked with a check and are toggled with the Enable and Disable buttons. All breakpoints listed in the Breakpoints list are saved to a debug configuration file when you choose Save Configuration from the File menu in the Debugger window.
Add

Adds the breakpoint specified by the Type, Location, File, Pass Count, and Expression boxes to the Breakpoints list. Only added breakpoints are saved when you exit the dialog box.
Remove

Removes the selected breakpoint from the Breakpoints list.
Disable

Clears the check mark beside the selected breakpoint in the Breakpoints list. When you disable a breakpoint, program execution is not suspended at the location or condition specified by the breakpoint.
Enable

Sets the check mark beside the selected breakpoint in the Breakpoints list and activates the breakpoint.
Clear All

Removes all the breakpoints from the Breakpoints list.
Display Breakpoint Messages

Makes it possible for you to toggle whether breakpoint message boxes display when a breakpoint is encountered. Breakpoint messages do not display when the break at location breakpoint is encountered.

See Also

Other Resources

Dialog Boxes
Debug Tab, Options Dialog Box
Trace Window
Debugger Window
Debugger Keyboard Shortcuts and Menus


Build Options Dialog Box

Visual FoxPro 9.0
Build Options Dialog Box
See Also

Makes it possible for you to create a custom application or rebuild an existing project.

This dialog box appears when you choose Build on the Project menu, which appears when a project is open, or Build in the Project Manager.

Build Action

Rebuild project

Creates and builds a project file. This option corresponds to the BUILDPROJECT command. For more information, see BUILD PROJECT Command.
Application (app)

Builds the project, compiles outdated files, and creates an application (.app) file. This option corresponds to the BUILD APP command. For more information, see BUILD APP Command.
Win32 executable / COM Server (exe)

Creates an executable (.exe) file from a project. This option corresponds to the BUILD EXE command. For more information, see BUILD EXE Command.
Single-threaded COM server (dll)

Creates a dynamic-link library (.dll) file using class information from the project file. This option corresponds to the BUILD DLL command that points to the run-time library, VFPVersionNumberR.dll. VersionNumber represents the version number for this release of Visual FoxPro. For more information, see BUILD DLL Command.
Multi-threaded COM server (dll)

Creates a multithreaded dynamic-link library (.dll) file using class information from a project file. This option corresponds to the BUILD MTDLL command that points to the run-time library, VFPVersionNumberT.dll. VersionNumber represents the version number for this release of Visual FoxPro. For more information, see BUILD MTDLL Command.

Options

Recompile All Files

Recompiles all files in the project, creates an object file for each source file, and includes compilation error messages in an error (.err) file during the build process. Otherwise, only files that have been modified since the last build are recompiled. For more information, see How to: View and Save Build Messages.
Display Errors

Displays compilation errors in an editing window after the build process completes and includes build status and error messages in an error (.err) file during the build process. For more information, see How to: View and Save Build Messages.
Run After Build

Specifies whether you want the application to run after it has been built.
Regenerate Component IDs

Installs and registers Automation servers contained in the project. When selected, this option specifies that new Globally Unique Identifiers (GUIDs) are generated when you build a program. Only those classes marked OLE Public in the Class Info dialog box of the Class menu will be created and registered. This option is enabled when you have marked Build OLE DLL or Build Executable and have already built a program containing the OLEPublic keyword. For more information, see Class Info Dialog Box.
Version

Displays the EXE Version dialog box, which makes it possible for you to specify information for the version number and the type of version. This button is available when you select Build Executable or Build OLE DLL in the Build Options dialog box. For more information, see EXE Version Dialog Box.

See Also

Other Resources

Dialog Boxes
Editing Window
Project Manager


Calculate Field Dialog Box

Visual FoxPro 9.0
Calculate Field Dialog Box
See Also

Makes it possible for you to select a mathematical operation to create a computed field. This dialog box is displayed when you choose Calculations in the Report Expression dialog box.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

Reset

Specifies the point at which to reset any cumulative calculations. The default value is "End of Report".
Note:
If you have specified data groups in the report, Detail bands, or target alias expressions for Detail bands, the Reset based on list displays those items.

Calculate

Specifies additional calculation operations that can be applied to the values of a Field control expression to obtain the value rendered in the output.

Nothing

(Default) No additional calculations are performed. The result of the Field expression is directly passed to the report engine for output.
Count

The value displayed is a count of the number of times the expression has been evaluated for the records traversed thus far. (The Field expression is not evaluated.)
Sum

The value displayed is a running total of the values of the Field expression for the records traversed thus far.
Average

Computes the arithmetic mean of the value of the Field expression for each record traversed thus far and displays the results.
Lowest

Displays the lowest value of the expression for a group, page, column, report, or Detail band, depending on the option selected in the Reset list and uses the value of the first record in the group in the expression. When a lower value is encountered, the expression's value changes accordingly.
Highest

The value displayed is the highest value of the Field expression evaluated for the records traversed thus far.
Standard deviation

Computes the square root of the variance of the evaluated Field expression for each record traversed thus far and displays the results.
Variance

Measures the degree to which the evaluated Field expression value varies from the average for the records traversed thus far and displays the result.

See Also

Other Resources

Dialog Boxes
Report Expression Dialog Box


Change Icon Dialog Box

Visual FoxPro 9.0
Change Icon Dialog Box
See Also

This dialog box specifies an icon to be used for a linked or embedded object on a form or in a General field of a Visual FoxPro table. This dialog box is displayed when you select Display as Icon in the Insert Object dialog box or the Paste Special dialog box and choose Change Icon.

Icon

Current Specifies that the current icon be used. Default Specifies that the default icon be used. From File Specifies the file from which the new icon is to be obtained. Type the path and file name in the box, and then click OK to show all available icons. Scroll through the icons, select the icon you want to use, and then click OK.
Label

Specifies the label that will be displayed beneath the icon. Type the desired label in the box.
Browse

Displays the Browse dialog box so you can select a file containing the icon you want.

See Also

Other Resources

Dialog Boxes
Insert Object Dialog Box
Edit Links Dialog Box
General Field Window
How to: Edit OLE Objects in Forms and Tables
Icon Property
Paste Special Dialog Box


Check In Files Dialog Box

Visual FoxPro 9.0
Check In Files Dialog Box
See Also

Checks in changes made in your development-environment working directory to your source code control database.

Files To Be Checked In

Lists the files available for check in. Click the files you want to check in, or click Select All to select all the files listed.
Comment

Type an optional comment.
Keep Checked Out

Updates the source code control database with your changes but keeps the file checked out to you.

See Also

Other Resources

Dialog Boxes
Get Latest Version of Files Dialog Box
Check Out Files Dialog Box
Compiling Source Code


Check Out Files Dialog Box

Visual FoxPro 9.0
Check Out Files Dialog Box
See Also

Checks out a copy of the selected files from your source code control provider and places a writable copy in the corresponding development-environment working directory.

Files to be Checked Out

Lists the files available for check out. Click the files you want to check out, or click Select All to select all files listed.
Comment

Type a brief description of the reason for the check out.
Select All

Selects all files listed.
Advanced

Displays the source code control provider's Advanced Check Out Options dialog box.

See Also

Other Resources

Dialog Boxes
Check In Files Dialog Box
Undo Check Out of Files Dialog Box
Compiling Source Code


Choose Field/Variable Dialog Box

Visual FoxPro 9.0
Choose Field/Variable Dialog Box
See Also

Specifies a table field or variable.

Choose a Field or Variable

Enter the desired field or variable.
Fields

Displays fields in the table specified in the Field box of the Report Picture dialog box. Double-click the desired field to move the field to the Choose a Field or Variable box.
Variables

Displays available variables. Double-click the desired variable to move it to the Choose a Field or Variable text box.
Comment

Makes it possible for you to add comments. Comments are entirely for your reference and do not appear in the printed report or label.

See Also

Other Resources

Dialog Boxes
Report Picture Dialog Box
Table Field Naming Conventions
Access to Visual FoxPro Variables and Fields
Variables
Round Rectangle Dialog Box


Class Info Dialog Box

Visual FoxPro 9.0
Class Info Dialog Box
See Also

This dialog box displays attributes for classes and class members. The following table describes the tabs available in the Class Info dialog box.

Tab | Description
Class | Displays and specifies general class information and associated icons.
Members | Displays information about individual members of the class.

See Also

Other Resources

Dialog Boxes
Working with Classes in Visual FoxPro


Class Tab, Class Info Dialog Box

Visual FoxPro 9.0
Class Tab, Class Info Dialog Box
See Also

Gives general information about the class and its associated icons. The dialog box that contains this tab appears when you choose Class Info from the Class menu.

Toolbar Icon

Displays the name of the class toolbar icon. Choose the dialog button to select an icon for the class. The class toolbar icon is displayed in the Form Controls toolbar in the Form Designer, and in the Class Designer when you populate the Form Controls toolbar with the classes in your class library. The class toolbar icon also appears in the Project container when the class is part of a project.
Container Icon

Displays the name of the class container toolbar icon. Choose the dialog button to select an icon for the class container. The container icon is displayed only in the Class Browser window.
OLE Public

Specifies that when a program containing the OLEPublic keyword is built through the Project Manager, a custom Automation server is generated. A Globally Unique Identifier, or GUID, is also generated for the program.
Description

Displays comments about the selected class. You can type a new description in the box or edit an existing one.
Class Name

Displays the name of the class selected in the Class Designer.
Parent Class

Displays name of parent class.
Class Library

Displays path and file name of class library.

See Also

Other Resources

Class Info Dialog Box
Members Tab, Class Info Dialog Box
Class Browser Window
Class Designer
Form Designer
Project Manager Window


Members Tab, Class Info Dialog Box

Visual FoxPro 9.0
Members Tab, Class Info Dialog Box
See Also

Displays information about individual members of the class. The dialog box that contains this tab appears when you choose Class Info from the Class menu.

The Members tab consists of a list box with the following columns:

Class

Displays the class name.
Name

Displays the class property or method name. Access and Assign methods created for properties also appear in the Name column.
Visibility

Specifies whether the class member is protected, public, or hidden. If you select Protected from the Visibility drop-down list in the Edit Property/Method dialog box, access and changes to class properties are prevented from outside the class or subclass definition.
No Init

Specifies whether the Init method is executed when an object is added. When true (.T.), the Init method is not executed. This option only applies to subclasses of the class.
Modify

Opens the Edit Property/Method dialog box where you can edit an existing property or method.

See Also

Other Resources

Class Info Dialog Box
Class Tab, Class Info Dialog Box
Access and Assign Methods
Protecting and Hiding Class Members
Edit Property/Method Dialog Box


Code Page Dialog Box

Visual FoxPro 9.0
Code Page Dialog Box
See Also

Allows you to assign a code page to a .dbf or text file that does not have one.

.Dbf and text files display properly only if they have the correct code pages. Visual FoxPro automatically assigns code pages to these files when you create them. However, .dbf and text files created in previous versions of FoxPro or in other products might not have code pages.

If you check Prompt for Code Page in the Data tab of the Options dialog box, Visual FoxPro prompts you to specify a code page when opening tables or text files that are not marked with a code page. You can also display the Code Page dialog box with the GETCP( ) function.

Platform

Refers to the type of operating system you are using. Your selection determines which code pages are displayed in the Code Page box.
  • All Displays code pages for all platforms.

  • Windows Displays only Windows code pages.

  • MS-DOS Displays only MS-DOS code pages.

  • Macintosh Displays only Macintosh code pages.

Code Page

Lists all the code pages for the selected platform.
Select

Designates the currently selected code page as the default.

See Also

Other Resources

Dialog Boxes
Open Picture Dialog Box
Save As Dialog Box
Data Tab, Options Dialog Box
GETCP( ) Function
Open Dialog Box
Save As Dialog Box
Developing International Applications


Comment Dialog Box

Visual FoxPro 9.0
Comment Dialog Box
See Also

Allows you to enter notes or comments to identify the query or view and its purpose.

Add Comment

Allows you to type a comment or note about the query or view.

See Also

Other Resources

Dialog Boxes
Query Destination Dialog Box
Advanced Options Dialog Box
Comment Property
Comments


Compile Dialog Box

Visual FoxPro 9.0
Compile Dialog Box
See Also

Makes it possible for you to compile program, menu, or query files.

Note:
If you have a program open in the Edit window, the Compile command compiles the current program without displaying any options.

This dialog box appears when you choose Compile on the Program menu.

File name

Displays files you can select to compile. To compile files, select the file name from the list and choose Compile, or double-click the file name. To choose multiple files, press and hold the CTRL key while selecting file names. The files displayed are those in the current directory that match the type specified in the List files of type box.
Directories

Displays the current directory. You can select a different directory that contains the files you want to compile.
Drives

Displays the current drive. You can select a different hard disk drive that contains the files you want to compile.
List files of type

Lists the available file types with Program (.prg) as the default. If you have given your programs, forms, menus, or queries an extension different from the Visual FoxPro default, you can see them by choosing All Files.
Compile

Compiles selected files.
Select All

Selects all files in the File name box for compiling.
Deselect All

Clears selection of all files in the File name box.
More

Expands the Compile dialog box so you can specify other options.

Options

Encrypt compiled files

Encodes compiled files to prevent decompile programs from reconstructing source code.
Include debugging information

Specifies whether to include debugging information with the compiled file. If this check box is not selected, you cannot view program execution in the Trace window of the Debugger. This check box corresponds to the NODEBUG keyword in the COMPILE command.
Compile updated files only

Compiles only those files from those selected that are new or have been updated since the last time they were compiled.

Error message location

.ERR File

Stores error messages for each selected file in a separate error (.err) file with the same base name as the original file. The .err file is stored in the same directory as the source file. If you do not select this box, error messages for all selected files are stored together in a file that you specify in the File box.
Append

Adds error messages for each selected file to an existing log file. This check box is enabled if you uncheck the .err File check box.
File

Stores error messages for all selected files in one log file. Type the log file name in the box, or choose the dialog button to find and specify an existing log file. This text box is enabled if you uncheck the .err File check box.

Compiled files location

Directory

Specifies a path to store compiled output files. Type the path in the box or choose the ellipsis (...) button to browse and select a directory and file name.

See Also

Other Resources

Dialog Boxes
COMPILE Command
Trace Window
Do Dialog Box
Testing and Debugging Applications
Compiling an Application


Connections Dialog Box

Visual FoxPro 9.0
Connections Dialog Box
See Also

This dialog box allows you to create and maintain database connections. It appears when you select Connections from the Database menu.

Connections in <database>

Lists the connections associated with the database currently opened.
New

Opens the Connection designer, which allows you to create and modify named connections.
Modify

Opens the Connection designer, which allows you to modify the existing database connection.
Delete

Allows you to delete the connection from the database.

See Also

Other Resources

Dialog Boxes
Connection Designer
Edit Relationship Dialog Box
Arrange Tables and Views Dialog Box
How to: Manage Connections with SQL Pass-Through
How to: Share Connections for Multiple Remote Views
Developing Databases
Database Designer


Coverage Dialog Box

Visual FoxPro 9.0
Coverage Dialog Box
See Also

Makes it possible for you to specify options for logging program execution. Use this dialog box to retrieve information on how many times each line of code was executed, which lines of code were not executed in your testing, and how long each line took to execute.

This dialog box appears when you choose Coverage Logging from the Tools Menu, Debugger Window.

File

Specifies the file to write the coverage log to. The dialog button displays the Open Dialog Box, which makes it possible for you to select a file to which to write the coverage log.
Append

Specifies that the coverage log is written after the current contents of an existing file, preserving the original contents.
Overwrite

Specifies that coverage log replaces the contents of the specified file.

See Also

Other Resources

Dialog Boxes
Coverage Profiler Application
_COVERAGE System Variable
Debugger Window
Debugger Keyboard Shortcuts and Menus


Create Dialog Box

Visual FoxPro 9.0
Create Dialog Box
See Also

Appears when you select Project, Database, or Table in the New dialog box and then choose New File. Allows you to specify the directory, name, and type of the new file.

Code Page

Displays the Code Page dialog box so that you can specify the code page needed to view the file correctly. This command applies only to text files such as program (.prg), query (.qpr), and text (.txt) files.

See Also

Other Resources

Dialog Boxes
New Dialog Box
Code Page Dialog Box


Create One-To-Many Relationships Dialog Box

Visual FoxPro 9.0
Create One-To-Many Relationships Dialog Box
See Also

Establishes a one-to-many relationship, in which the child table can contain multiple records that correspond to one record in the parent table. Corresponds to the SET SKIP Command.

This dialog box appears when you choose the 1-To-Many button in the Data Session Window.

The 1-To-Manybutton is enabled when there is at least one relation originating from the selected table.

Child Aliases

Lists the child aliases of the parent alias, whose name is given at the top of the dialog box.
Selected Aliases

Lists aliases of all tables currently involved in a one-to-many relationship with the parent table.
Move

Copies the selected child aliases in the ChildAliases box to the SelectedAliases box. To enable this button, you must select an alias in the ChildAliases box.
All

Copies all the child aliases in the ChildAliases box to the SelectedAliases box.
Remove

Removes the selected aliases from the SelectedAliases box. To enable this button, you must select an alias in the SelectedAliases box.
Remove All

Removes all aliases from the SelectedAliases box.

See Also

Other Resources

Dialog Boxes
Data Session Window
One-To-Many Form Wizard
SET RELATION Command
SET SKIP Command
Set Index Order Dialog Box
Table Creation


Customize Toolbox Dialog Box

Visual FoxPro 9.0
Customize Toolbox Dialog Box
See Also

Displays options to change settings for the Toolbox and to edit categories and items displayed in the Toolbox.

Selection Treeview

Displays the areas that you can modify and change settings for the Toolbox.

Options

Displays the general options for setting the Toolbox behavior.

Run associated builders

Specifies that builders are displayed automatically in the Forms Designer when you create a control that has a builder registered to it.
Display toolbox help text section

Specifies if the help text section in the Toolbox is displayed.
Show tooltips

Specifies whether ToolTips are displayed for category items.
Always on top

Specifies whether the Toolbox should appear in front of other windows.
Double-click to open an item

Specifies whether a hyperlink item in the Toolbox needs a double-click or a single-click to open it.
Set CurrentControl property when a control is dropped on a grid column

Specifies that Visual FoxPro should automatically change the value of the CurrentControl property when a control is dropped on a grid column from the Toolbox.
Prompt to remove Text1 control when dropping new control on a grid column

Specifies that Visual FoxPro should automatically remove the Text1 control from the grid column when a new control is dropped on a grid column from the Toolbox.
Allow toolbox to be minimized

Specifies if the Toolbox minimize control button should be displayed so that the Toolbox can be minimized.
Category scroll speed

Specifies the speed, in milliseconds, that a category will scroll when the mouse is over a scroll up or down widget in the Toolbox.
Toolbox table

Specifies the table for the Toolbox to save settings.
Font

Sets the font attributes used for the Toolbox.
Clean Up Toolbox

Removes deleted items from the Toobox table.
Restore to Default

Restores the Toolbox to its default state.

Class Items

Displays options for how classes are displayed and used from the Toolbox.

Default naming convention for classes added to Toolbox

Specifies the naming convention for how a class is displayed in the Toolbox.
Drag and drop text template

Specifies what text will be added when you drag and drop a class from the Toolbox.
CTRL+Drag and drop text template

Specifies the text to be added when you CTRL+Drag a class from the Toolbox.
Edit

Opens an editor, which has IntelliSense and color coding, to change the drag-and-drop or CTRL+Drag text.

Filters

Displays options for managing your filters for the Toolbox.

New Filter

Creates a new filter and selects it for editing.
Delete Filter

Prompts to delete the currently selected filter.
Apply Filter

Applies the currently selected filter to the Toolbox.
Clear Filter

Removes the effects of a filter from the Toolbox.
Filter Name

Specifies the name for the currently selected filter.
Update

Saves any changes made to the filter name that were made in the filter name field.
Defined Filters

Displays a list of filters that can be applied to the Toolbox.
Select toolbox categories that belong to this filter.

Displays a list of filter options that can be applied with a filter.

Categories

Displays options for managing the categories in the Toolbox.

Add Category

Displays a dialog box to add a new category to the Toolbox.
Remove Category

Prompts to delete the currently selected category.
Category Properties

Displays a dialog box that contains information on the properties for the currently selected category.
Refresh Category

Updates the Toolbox with any changes made to the currently selected category.
Refresh Toolbox

Updates the Toolbox with any changes made to all of the categories displayed in the Toolbox.
Select an item to view

Specifies the type of items that are shown in the item list for a specific category.
Show checked items only

Specifies that only items in the item list that are selected and show in the category are visible.
Add Item

Displays a dialog box used to add a new item to the currently selected category.
Remove Item

Prompts to remove an item from the currently selected category.
Item Properties

Displays a dialog box that contains information on the properties for the currently selected item.
Sort Alphabetically

Sorts the items in the item list to be displayed in alphabetical order.

See Also

Other Resources

Dialog Boxes
Toolbox


Data Grouping Dialog Box

Visual FoxPro 9.0
Data Grouping Dialog Box
See Also

Allows you to specify nested regions of the report or label layout that are rendered only when an expression changes its value.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

How to: Add Data Groups to Reports

Group expressions

Lists the expressions that determine breaks between data groups. The mover button allows you to change the nesting order of the group expressions.

You can type the expression directly or build an expression by clicking the ellipsis (…) button. Empty expressions are not valid. For more information, see Expression Builder Dialog Box.

Group properties

Specifies output options for data groups.

Start group on new column

Specifies that the group expression change will force the information to be rendered as a new column. Available only when the page layout contains more than one column.
Start each group on a new page

Specifies that the group expression change will force the information to be rendered as a new page.
Reset page number to 1 for each group

Starts a new page and restarts page numbering every time the data group expression value changes.
Reprint group header on each page

Specifies that the group header follow the page header on all pages for the data group when the data group spans more than one page.
Start group on new page when less than

Specifies the minimum distance from the bottom of the page that determines when to begin the group header on the next page.
Tip:
Use this option to prevent a "orphaned" group header, and potentially inappropriate data, at the end of a page with no accompanying detail information. An orphaned group header may display data from a record not shown elsewhere on the page, since the page footer will display information appropriate to the previous group.

Insert

Inserts a blank text box in the Group expressions box so you can type a new group expression.
Delete

Deletes the selected group expression from the Group expressions box.

See Also

Other Resources

Working with Report Data Groups
Dialog Boxes


Database Properties Dialog Box

Visual FoxPro 9.0
Database Properties Dialog Box
See Also

This dialog box allows you to choose the type of database objects that are displayed in the Database designer. You can choose from tables, relations, local views, and remote views. You can also add a comment. Use this dialog box to show or hide database objects in your database schema.

This dialog box appears when you select Properties from the Database menu.

Event

Lists the available events.
Set Events On

Specifies whether DBC Events are enabled at design time and run time in the current Visual FoxPro session.
Events File

Enables you to specify an external file that contains DBC Event code.
Edit Code button

Opens the Visual FoxPro editor so you can add code to the currently selected DBC Event in the stored procedures file or in the specified external file.
Tables

Shows or hides the tables in the database schema.
Relations

Shows or hides the relationship lines between tables in the database schema.
Local Views

Shows or hides the views created on data stored in local tables.
Remote Views

Shows or hides the views created on data stored in a remote data source.
Comment

Provides space for you to type a comment about the database schema.

See Also

Other Resources

Dialog Boxes
Connections Dialog Box
Arrange Tables and Views Dialog Box
Database Designer
New Local View Dialog Box
New Remote View Dialog Box
Edit Relationship Dialog Box
Find Table or View Dialog Box
How to: View and Set Database Properties


Define Window Layout Dialog Box

Visual FoxPro 9.0
Define Window Layout Dialog Box
See Also

Allows you to name and save window and toolbar configurations for reuse.

View Name

Specifies the name of the current window layout.
View

Lists the available window layouts.
Apply

Configures the current windows to the selected window layout.
Add

Adds the currently named layout to the list of available window layouts.
Delete

Deletes the currently select layout from the list of available window layouts.
Rename

Allows you to change the name of the current window layout.

See Also

Other Resources

Dialog Boxes
General Options Dialog Box
DEFINE WINDOW Command
How to: Configure Visual FoxPro Toolbars
Menu Designer
Tab Order Dialog Box
Toolbars Dialog Box


Delete (Records) Dialog Box

Visual FoxPro 9.0
Delete (Records) Dialog Box
See Also

Lets you mark records for deletion. Corresponds to the DELETE command.

This command does not physically delete records, but only marks them for deletion in the future. To permanently delete records from the hard disk, use Remove Deleted Records in the Table Menu.

Scope

Allows you to specify the records on which Visual FoxPro is to act. Choose Next, All, Record or Rest from the drop-down list. Choose a number from the spinner on the right when you select Next or Record from the Scope drop-down list.
For

Displays the Expression Builder Dialog Box, where you create the logical expression that every record must meet to be affected by the command. Every record in the table is tested using the For expression.
While

Displays the Expression Builder Dialog Box. The While expression specifies that the action affects records only as long as the logical expression is true. The first time the expression evaluates to false, the action ceases without considering remaining records.
Delete

Deletes records using the Scope, For, and While values.

See Also

Other Resources

Dialog Boxes
DELETE Command
Expression Builder Dialog Box
Recall (Records) Dialog Box
Scope Dialog Box
Replace Field Dialog Box


Description Dialog Box

Visual FoxPro 9.0
Description Dialog Box
See Also

Provides a text box for specifying a brief file description.

This dialog box appears when you select a file in the Project Manager and choose Edit Description on the Project menu.

Description

Specifies the description of the file.

See Also

Other Resources

Dialog Boxes
Description Property


Do Dialog Box

Visual FoxPro 9.0
Do Dialog Box
See Also

Lets you specify a program or form file to run.

This dialog box appears when you select Do from the Program menu.

Shortcut

CTRL+D

Do (text box)

Specifies the program or form file to run. To run the program or form, select a name from the list and choose Do, or double-click the file name. The program files displayed are those in the current directory with the .app, .fxp, .mpr, .prg, .qpr, or .src extension that matches the type specified in the Files of Type box.
Do (button)

Sets the default folder to the one that contains the selected program or form and runs the program or form.

See Also

Other Resources

Dialog Boxes
DO Command
Compiling an Application
Testing and Debugging Applications
DoCmd Method


Edit Bands Dialog Box

Visual FoxPro 9.0
Edit Bands Dialog Box
See Also

Displays a list of available report bands so you can change settings for the report band you select.

Report band list

Displays a list of bands in the report or label layout. Double-click or press Enter on a band name to edit it.

See Also

Other Resources

Working with Report Bands
Working with Reports
Dialog Boxes


Edit Links Dialog Box

Visual FoxPro 9.0
Edit Links Dialog Box
See Also

This dialog box makes it possible for you to change or break an object link. This menu option is enabled when you open a general field that contains a linked OLE object you generated in a separate application.

Links

Displays the name and path of the linked file, the type of application, and the type of updating selected for the link.
Source

Displays the complete name and location of the object file selected in the Link box.
Type

Displays the object application or type of application to which the file selected in the Link box is linked.
Update

Specifies how you want to update information.
  • Select Automatic to have Visual FoxPro update the information whenever new information becomes available.

  • Select Manual to update the information only when you select a link and click Update Now.

Update Now

Updates the link selected in the Link box. If information has changed in the object document, the new information shows in your form or report.
Open Source

Opens the selected file in the object application for editing.
Change Source

Displays the Change Source dialog box, where you can specify a different object file for the selected link or change item information.
Break Link

Breaks the link selected in the Link box. This changes the object to a picture, which can no longer be edited by the OLE application that created it.

See Also

Other Resources

Dialog Boxes
Edit Properties Dialog Box
General Field Window
How to: Add OLE Objects to Applications
Change Icon Dialog Box
How to: Update Table and Database Links
Dynamic Information Sharing


Edit Properties Dialog Box

Visual FoxPro 9.0
Edit Properties Dialog Box
See Also

This dialog box makes it possible for you to set editing options for the current editing window or set color and font options for all editing sessions.

This dialog box appears when you choose Properties from the shortcut menu of any editing window or when you click Properties on the Edit menu.

Behavior

The options in this area affect the current editing window only.

Drag-and-drop editing

Enables drag-and-drop text editing for manipulating text with the mouse.
Wordwrap

Wraps text lines within the window. Wordwrap is only available when the syntax coloring is set to OFF. For more information, see Editor Tab, Options Dialog Box.
Automatic indent

Automatically indents text according to the first line's indent. This does not affect how the text is saved.
Embedded hyperlinks

Makes it possible for you to specify whether hyperlinks can be included in the selected file type.

Appearance

Makes it possible for you to control the size, style, color and other text characteristics.

Alignment

Specifies left, center, or right alignment of text.
Font

Changes the font in the edit window. Click the ellipsis (...) button to open the Font dialog box.
Show line/column position

Enables the display of line number and column position in the status bar. The line number isn't displayed if wordwrap is enabled.
Syntax coloring

Toggles whether colors are shown for syntax elements. You can only select if wordwrap is set to OFF. For more information, see Editor Tab, Options Dialog Box.
Display white space

Specifies whether spaces, tabs, and paragraphs appear as characters in the currently active editor. This option is available when you work in the text editor. Paragraph markers (line feeds) appear only if the wordwrap option is enabled. To display white space, click View White Space on the Format menu.
Note:
The View White Space option is not supported on double-byte character set (DBCS) platforms.

Save Options

Makes it possible for you to manage characteristics of saved files. The available save options depend on the type of file you open.

Make backup copy

Specifies that Visual FoxPro create a backup copy each time you save a file. The backup copy is saved with the file name and a .bak extension in your Visual FoxPro Projects folder.
Save with line feeds

Saves the file with line feeds that have been entered into it. If this box is not selected, line feeds are removed when the file is saved. For more information, see AddLineFeeds Property.
Save with end-of-file marker

Places a CTRL+Z character at the end of a file when the file is saved. This extra character, when saved with the file, helps resolve the difference between normal editing activity and MODIFY MEMO activity. For more information, see MODIFY MEMO Command.
Compile before saving (Program editor)

Specifies that Visual FoxPro automatically compile the program and check for syntax errors when the file is saved.
Save preferences

Determines if the settings for an open file and all other windows of that same type are saved for the next time they are opened. If Save preferences is not selected, the preferences are only saved for the individual open window.
Apply to method code (Form or Class Designer)

Specifies the current settings as the default for all form or class methods.
Apply to menu code (Menu Designer)

Specifies the current settings as the default for all menu procedures.
Apply to .PRG or .TXT files (Program or text editor)

Specifies the current settings as the default for .prg or .txt files.
Apply to memos (Memo field editor)

Specifies the current settings as the default for memo fields.

Indentation

Makes it possible for you to specify the size and behavior of spaces and tabs.

Tab size

Specifies the width, in characters, of a tab for the currently selected file type. The range is 1 to 50. The default value is 4.
Indent size

Specifies the width, in characters, of a paragraph indent for the currently selected file type. If this is different from the tab size, extra tabs and/or spaces are used to create the specified value. The range is 1 to 50. The default value is 4.
Insert spaces

Specifies that spaces be inserted by the tab key for the currently selected file type. The default value is 4.
Keep tabs

Specifies that tabs be inserted by the tab key for the currently selected file type (default).

File Information (Program or text editor)

Makes it possible for you to specify the system characteristics of saved files.

File Name

Specifies the name and directory of the program or text file being edited.
Size

Specifies the size of the program or text file being edited.
Last Saved

The date and time the program or text file was last saved to disk.

See Also

Other Resources

Dialog Boxes
MODIFY MEMO Command
Edit Links Dialog Box
Font Dialog Box
Change Icon Dialog Box
How to: View and Set Database Properties
Edit Property/Method Dialog Box
EditorOptions Property
How to: Set Editor Options


Edit Property/Method Dialog Box

Visual FoxPro 9.0
Edit Property/Method Dialog Box
See Also

Makes it possible for you to edit existing properties and methods or add new properties and methods.

This dialog box appears when you choose Edit Property/Method on the Form menu that appears when the Form Designer is open or the Class menu that appears when the Class Designer is open.

Note:
For forms and form sets, the property or method is scoped to the standalone form or form set, as applicable.

Property/Method Information

Displays information about properties and methods added to a form, form set, or class. You can sort columns in ascending or descending alphabetical order by clicking the column header. You can resize the columns by clicking and dragging between column headers.

Column Description

Name

The name of each property and method.

Type

Property (P) or method (M).

Access

Indicates if a property has a corresponding Access method. Yes indicates the property has an Access method, No indicates the property doesn't have an Access method.

Assign

Indicates if a property has a corresponding Assign method. Yes indicates the property has an Assign method, No indicates the property doesn't have an Assign method.

Visibility

Indicates the visibility of a property or method. For a form or form set, the visibility of properties and methods is always Public. For a class, the visibility can be Public, Protected, or Hidden.

For more information, see Protecting and Hiding Class Members.

Tip:
In the Class Designer, you can set the same level of visibility for all selected properties and methods by selecting multiple properties and methods.

Note:
All public properties and methods appear in type libraries created for in-process .dll files and out-of-process executable (.exe) files. By selecting multiple properties and methods and setting their visibility level to Protected or Hidden, you can prevent the selected properties and methods from appearing in the type libraries.
New Property

Displays the New Property dialog box, allowing you to create a new property. For more information, see New Property Dialog Box.
New Method

Displays the New Method dialog box, making it possible for you to create a new method. For more information, see New Method Dialog Box.
Remove

Removes the selected property or method.
Property/Method Name

Displays the name of the currently selected property or method.
Access Method

Specifies if a property has an Access method whose code is executed whenever the property is queried. Select this check box to create an Access method for a property. Clear the check box to remove an Access Method.
Assign Method

Specifies if a property has an Assign method whose code is executed whenever you attempt to change the value of the property. Select this check box to create an Assign method for a property. Clear the check box to remove an Assign Method.
Description

Contains the property or method description that displays at the bottom of the Properties Window in the Class Designer and, if the property is not protected, in the Form Designer.
Visibility (Classes Only)

Specifies whether the class is Public, Protected, or Hidden.
Apply

Applies changes made to a property or method.
Close

Closes the dialog box.

See Also

Other Resources

How to: Modify Class and Class Member Attributes
How to: Add Properties and Methods to a Form
Access and Assign Methods
Class Designer
Form Designer
Properties Window
Dialog Boxes


Edit Relationship Dialog Box

Visual FoxPro 9.0
Edit Relationship Dialog Box
See Also

This dialog box makes it possible for you to edit a persistent relationship between tables. For more information, see How to: Manage Persistent Relationships Between Tables.

This dialog box appears when you select a relationship line in the Database Designer and select Edit Relationship from the Database menu, or double-click the relationship line.

Table

Shows the name of the current parent table and allows you to select a different index tag.
Related Table

Shows the name of the current child table and allows you to select a different index tag.
Relationship Type

Shows the type of relationship between the parent and child tables.
Referential Integrity

Displays the Referential Integrity builder so you can set up rules to control how records are inserted, updated, or deleted in related tables.
Note:
If your tables are not already indexed, you need to open them in the Table designer and create indexes before you use the Referential Integrity builder.

See Also

Other Resources

Dialog Boxes
Database Designer


Event Tracking Dialog Box

Visual FoxPro 9.0
Event Tracking Dialog Box
See Also

Makes it possible for you to see when each event occurs in relation to other events. Use this dialog box to determine the most efficient place to include your code.

This dialog box appears when you choose Event Tracking from the Tools Menu, Debugger Window.

Turn event tracking on

Toggles event tracking on or off. When event tracking is enabled, every time a system event in the Events to track list occurs, the name of the event is displayed in the Debug Output window or written to a file.
Available events

Displays all available events that are not selected for tracking.
Tip:
If you are not specifically working with mouse movements, remove the MouseMove event from the Events to track list. MouseMove events typically occur very frequently.

Events to track

Displays all events that you want to track.

Send Output To

Debugger Output Window

Toggles whether tracked events are listed in the Debug Output window. If the Debug Output window is not open, events will not be listed, even if the Debug Output Window box is set.
File

Specifies a file for the tracked events to be written to. The dialog button makes it possible for you to select a file from the Open dialog box.
Append

Specifies that tracked events are written after the current contents of an existing file, preserving the original contents.
Overwrite

Specifies that tracked events replace the contents of the specified file.

See Also

Other Resources

Dialog Boxes
Open Dialog Box
Debug Output Window
Debugger Window
Debugger Keyboard Shortcuts and Menus
Coverage Dialog Box
MouseMove Event


EXE Version Dialog Box

Visual FoxPro 9.0
EXE Version Dialog Box
See Also

Displays the build number of a program and other information about the program that you can provide.

This dialog box appears when you click the Version button in the Build Options dialog box.

Version Number

Major

Displays a four-digit number that can be edited. This number corresponds to a major version.
Minor

Displays a four-digit number that can be edited. This number corresponds to a minor version.
Revision

Displays an editable four-digit number. This number corresponds to incremental updates.
Auto Increment

When checked, this option allows for automatic updates to the Revision number with every build of the program.

Version Information

Type

Lists seven categories of version information, which you can define. These categories are Comments, Company Name, File Description, Legal Copyright, Legal Trademarks, Product Name, and Language ID.
Value

Displays the information entered about a single category. Click a category in the Type list to display, enter, or edit the information.

See Also

Other Resources

Dialog Boxes
How to: Get the Latest Versions of Files
GetLatestVersion Method
VersionNumber Property
VersionTrademarks Property
VersionCopyright Property
Build Options Dialog Box
Project Information Dialog Box


Execution Throttle Dialog Box

Visual FoxPro 9.0
Execution Throttle Dialog Box
See Also

Makes it possible for you to specify the delay in seconds between the execution of each line of code located in the Trace Window. This dialog box appears when you select Throttle from the Debug Menu, Debugger Window.

Delay (seconds)

Makes it possible for you to set the delay of execution from 0.0 seconds to 5.0 seconds between each line of code.

See Also

Other Resources

Dialog Boxes
Trace Window
Debugger Window
Debugger Keyboard Shortcuts and Menus


Export Dialog Box

Visual FoxPro 9.0
Export Dialog Box
See Also

Lets you export data from Visual FoxPro tables to a text file, spreadsheet, or common table format.

This dialog box appears when you select Export from the File menu.

Type

Specifies the type of file to export. Select a file type from the list.
To

Specifies the path and name of the destination file. Type the path and name, or click the dialog button to find the destination file.
Text delimiter

Allows you to delimit strings of text in the output file. The default text delimiter is the double-quote (") character. This option only appears if you choose Delimited Text from the Type drop-down list.
Field separator

Makes it possible for you to separate data fields in the output file. The default field separator is the comma (,) character. This option only appears if you choose Delimited Text from the Type drop-down list.
From

Specifies the path and name of the source file. Type the path and name, or click the dialog button to find the source file.
Options

Displays the Export Options dialog box, where you specify which records and fields to export.

The following table shows the file types you can export with this command, and their equivalents that you would type in the Command window.

File Types | Command Equivalent
Data Interchange Format (DIF) | COPY TO FileName TYPE DIF
DBASE IV (DBF) | COPY TO FileName FOX2X
Delimited Text | COPY TO FileName TYPE DELIMITED
FoxBASE+ (DBF) | COPY TO FileName FOXPLUS
FoxPro for Windows 2.x (DBF) | COPY TO FileName FOX2X
Lotus 1-2-3 1-A (WKS) | COPY TO FileName TYPE WKS
Lotus 1-2-3 2.x (WK1) | COPY TO FileName TYPE WK1
Microsoft Excel 2.0, 3.0, and 4.0 (XLS) | COPY TO FileName TYPE XLS
MultiPlan 4.01 (MOD) | COPY TO FileName TYPE MOD
Symbolic Link Format | COPY TO FileName TYPE SYLK
Symphony 1.01 (WRK) | COPY TO FileName TYPE WRK
Symphony 1.10 (WR1) | COPY TO FileName TYPE WR1
System Data Format (SDF) | COPY TO FileName TYPE SDF
Visual FoxPro (DBF) | COPY TO FileName

See Also

Other Resources

Dialog Boxes
Export Options Dialog Box
Command Window
COPY TO Command
EXPORT Command
Import Dialog Box
Exporting Data


Export Options Dialog Box

Visual FoxPro 9.0
Export Options Dialog Box
See Also

Specifies which records and fields to export. This dialog box is displayed when you choose Options in the Export dialog box. For more information, see Export Dialog Box.

Criteria

Specifies options that control which records and fields to export and the conditions under which they export.

Scope

Displays the Scope dialog box so you can specify which records to export. For more information, see Scope Dialog Box.
For

Displays the Expression Builder dialog box so you can create a logical expression that that must be true for every record to export. For more information, see Expression Builder Dialog Box.
While

Displays the Expression Builder dialog box so you can create a logical expression that must be true to continue exporting records. For more information, see Expression Builder Dialog Box
Fields

Displays the Field Picker dialog box so you can choose fields to export. For more information, see Field Picker Dialog Box.

See Also

Other Resources

Dialog Boxes
EXPORT Command
Exporting Data


Expression Builder Dialog Box

Visual FoxPro 9.0
Expression Builder Dialog Box
See Also

Makes it possible for you to create and edit expressions. The Expression Builder provides lists of appropriate options and can be opened from various designers, windows, builders, and wizards.

To create an expression, type it into the Expression box or select items from the Functions lists. An expression can be simple, such as a field name, or complex, such as a calculation involving IIF( ) functions, concatenations, and data type conversions.

Expression

Displays the expression that you are creating or editing.
Tip:
You can enter more than 255 characters as well as extended characters, such as CHR(13) (carriage return) and CHR(10) (linefeed), for expressions in the Expression Builder. The Expression box in the Expression Builder supports color syntax and background compilation when turned on. For more information, see How to: Display and Print Source Code in Color.

Caution:
Property values that exceed 255 characters or include extended characters contain padding with CHR(1) characters. However, classes in visual class library (.vcx) files that contain properties with such values cannot be used in versions prior to Visual FoxPro 9.0. If you attempt to modify these classes in a prior version, an error occurs. You can still use other classes in the same visual class library (.vcx) files with previous versions of Visual FoxPro as long as they do not contain property values exceeding 255 characters or include extended characters.

Functions

Displays lists of function types. When you select a function from one of the four types, Visual FoxPro automatically pastes it into the expression box. When you are building expressions for remote views, Visual FoxPro lists only the functions specific to the target back-end data.
  • String Lists available character string functions.

  • Logical Lists available logical functions.

  • Math Lists available math functions.

  • Date Lists available date and time functions.

Fields

Lists the fields in the current table or view. To paste a field into the Expression box, double-click the field or select the field and press ENTER. To display fields from a different table, select a different table in the From Table box.
From Table

Lists tables and views that are open. Select a table or view to update the Fields box.
Variables

Lists system memory variables, arrays, and memory variables that you have created. To paste a variable into the Expression box, either double-click the variable, or select the variable and press ENTER.
Verify

Validates the syntax of the expression in the expression box if the corresponding table is open. If the expression is valid, "Expression is valid" is displayed in the status bar. If it is not valid or if the corresponding table is not open, Visual FoxPro displays an error message. This option is not enabled for remote views.
Caution:
If you include a user-defined function call in the expression, an error is indicated; however, an error does not necessarily occur when the expression is evaluated at run time.

Options

Displays the Expression Builder Options dialog box, which you can use to set preferences for the Expression Builder. For more information, see Expression Builder Options Dialog Box.

The following table describes some useful functions for manipulating strings in expressions.

If you want to | Use this function
Remove leading and trailing blanks from character expressions | ALLTRIM( ) Function
Remove leading blanks | LTRIM( ) Function
Remove trailing blanks | RTRIM( ) Function
Add specified characters to the left, right, or both sides of a string | PADL( ) | PADR( ) | PADC( ) Functions
Work with parts of a character string for comparisons | SUBSTR( ) Function
Use a specified number of characters starting with the left of a string | LEFT( ) Function
Use a specified number of characters starting from the right of a string | RIGHT( ) Function
Change uppercase to lowercase, or lowercase to uppercase | UPPER( ) Function, LOWER( ) Function
Convert a string to initial capitals | PROPER( ) Function
Have a numeric field interpreted as a character string | STR( ) Function

See Also

Other Resources

Dialog Boxes
IIF( ) Function
ISLOWER( ) Function
SET ANSI Command
SET EXACT Command


Expression Builder Options Dialog Box

Visual FoxPro 9.0
Expression Builder Options Dialog Box
See Also

Sets preferences for the items displayed in the Expression Builder. This dialog box appears when you click Options in the Expression Builder Dialog Box.

Functions

Enables you to change what appears on the String, Math, Logical, and Date functions in the Expression Builder. You can choose to display all of these in the Expression Builder String box, or select only those you want. To select or deselect multiple items, press CTRL as you make your selections.

String

Displays all string functions in the box. All selected string functions will be displayed in the Expression Builder.
Math

Displays all math functions in the box. All selected math functions will be displayed in the Expression Builder.
Logical

Displays all logical functions in the box. All selected logical functions will be displayed in the Expression Builder.
Date

Displays all date functions in the box. All selected date functions will be displayed in the Expression Builder.
Note:
Select individual items by pressing CTRL+left mouse button. Select a consecutive group of items by left-clicking the first item and pressing SHIFT+left mouse button on the last item.

All

Selects all functions in the box so that they all appear as choices in the Expression Builder.
Clear

Deselects all functions in the box so that they don't appear as choices in the Expression Builder.

Field Aliases

These options specify whether and how table or view aliases appear in your expressions.

Always Add Alias

Specifies that the table or view name is always included with fields used in the expression.
Add Non-Selected Alias Only

Specifies that when more than one table or view is open, Visual FoxPro only includes the name of any table or view that is not selected in the Aliases list of the Data Session Window with any of its fields in the expression. Table or view names are not added for tables that are selected in the Aliases list.
Never Add Alias

Specifies that table or view names are not included with any field when you create the expression.
Show System Memory Variables

Specifies whether system memory variables are displayed in the Expression Builder. Turn this option off if you want to see only the system memory variables that have been defined.

See Also

Other Resources

Dialog Boxes
Data Session Window
Expression Builder Dialog Box
_TEXT System Variable


Field Picker Dialog Box

Visual FoxPro 9.0
Field Picker Dialog Box
See Also

Makes it possible for you to select fields.

When this dialog box opens by selecting Only fields specified by field filter and then clicking Field Filter in the Work Area Properties dialog box, this dialog box makes it possible for you to select fields that display or can be accessed in a browse window. Fields not chosen cannot be accessed, examined, or modified. However, data in the table is not affected. For more information, see Work Area Properties Dialog Box.

This dialog box appears when you click Field Filter in the Work Area Properties dialog box or Fields in the Quick Report Dialog Box, Append From Options Dialog Box, or Export Options Dialog Box.

All Fields

Displays all field names in the current table.
Selected Fields

Displays field names you select in the All Fields box and copy with the Move button.
From Table

Specifies which table's fields are displayed in the All Fields box.
Move

Copies the selected fields from the All Fields box to the Selected Fields box.
All

Copies all fields from the All Fields box to the Selected Fields box.
Remove

Removes the selected fields from the Selected Fields box.
Remove All

Removes all fields from the Selected Fields box.

See Also

Other Resources

Dialog Boxes
Append From Options Dialog Box
Export Options Dialog Box
Quick Report Dialog Box
Work Area Properties Dialog Box


File Finder Dialog Box

Visual FoxPro 9.0
File Finder Dialog Box
See Also

Enables searches based on specified criteria.

Find Now

Performs a file search based on the options you specify on the Filer tabs.
Edit

Opens the files selected in the Search results list for editing.
New Search

Clears the options specified on the Text Search, Date Modified, and File Attributes tabs.
Search result

Displays the files located by the search. Double-click a file in the Searchresult list to open the file for editing. To open multiple files for editing, select the files and click the Edit button.

The Filer options are grouped onto the following tabs.

Tab | To access these features
Name and Location | Specify the names, extensions, and locations of the files you search for.
Text Search | Specify text strings to search for.
Date Modified | Specify the creation, modification, or access dates for the files you search for.
File Attributes | Specify the file size and file attributes of the files you search for.

Name and Location Tab

Named

Specifies the files you want to search for. Specify a file name and extension or any portion of a file name and extension that includes wildcard characters. Separate multiple file specifications with semicolons. For example, to display all .prg and .app files, use *.prg;*.app. Click the down arrow to display a list of commonly used Visual FoxPro file extensions.
Look in

Specifies the folder in which the search occurs. Click the down arrow to display a list of folders you've specified during the current Filer session.
Browse

Displays the Select Directory dialog box, making it possible for you to select the folder in which the search occurs.
Include Subfolders

If checked, specifies that subfolders are also searched. Note that Filer ignores System folders.

Text Search Tab

Expression 1

A text string to search for in the files that match the file specification on the Name and Location tab.
Expression 2

An additional text string to search for. Ignored if Expression 1 is empty.
Expression 3

An additional text string to search for. Ignored if Expression 1 and Expression 2 are empty.
Contains any matching words

If chosen, specifies that any of the text in the text strings specified in Expression 1, Expression 2, and Expression 3 must match for the search to be successful.
Contains all matching words

If chosen, specifies that all the text in the text strings specified in Expression 1, Expression 2, and Expression 3 must match for the search to be successful.
Match case

If checked, specifies that the word case isn't ignored for text in the text strings specified in Expression 1, Expression 2, and Expression 3.
Match whole words

If checked, specifies that the text in the text strings specified in Expression 1, Expression 2, and Expression 3 must match whole words for the search to be successful.

Date Modified Tab

All Files

If chosen, specifies that the dates that files are created, modified, or accessed are ignored in the search.
Find all files created or modified

If chosen, includes in the search all files created or modified between or before the specified dates.
Find all files last accessed

If chosen, includes in the search all files accessed between or before the specified dates.
Between

Available when Find all files created ormodified or Find all files last accessed is chosen. Includes in the search all files created, modified, or accessed between the two specified dates.
During the previous month(s)

Available when Find all files created or modified or Findall files last accessed is chosen. Includes in the search all files created, modified, or accessed during the specified number of months.
During the previous day(s)

Available when Find all files created or modified or Find all files last accessed is chosen. Includes in the search all files created, modified, or accessed during the specified number of days.

File Attributes Tab

Size is

Specifies that the files included in the search are at least or at most a specified size (in kilobytes).

Exclude files with these attributes

Read-only

Excludes files in the search that have the read-only file attribute set.
Archive

Excludes files in the search that have the archive file attribute set.
Hidden

Excludes files in the search that have the hidden file attribute set.
System

Excludes files in the search that have the system file attribute set.

See Also

Other Resources

Dialog Boxes
Options Dialog Box
Debugger Window
Beautify Options Dialog Box
Macros Dialog Box
Wizard Selection Dialog Box


Find Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Find Dialog Box (Visual FoxPro)
See Also

This dialog box contains options that make it possible for you to search for text. Visual FoxPro adds several ways to access the Find dialog box from the keyboard.

Keys | Description
CTRL+F | Find.
CTRL+L | Replace.
F3 | Find Again or open Find dialog box.
CTRL+F3 | Update Find with the word or selected characters at the cursor position.
CTRL+SHIFT+F3 | Update Find with the word or selected characters at the cursor position for a previous occurrence.
Look For

Specifies the text string for which to search. To search for special characters, type the following C language representations in the text boxes in the Find dialog box.

To search for Type

Enter

\r

Tab

\t

Backslash

\\

New line (line feed)

\n

In Visual FoxPro, searches support wildcards.

Options

These options define the limits and direction of the search. If you specify text to search for and do not get the expected results, make sure you have the correct options selected.
  • Match Case Locates text that exactly matches the combination of uppercase and lowercase letters you type in the Look For box.

  • Wrap Around Searches the current file from the insertion point to the end of the file and then from the beginning of the file to the original insertion point.

  • Match Whole Word Locates distinct occurrences of words, not groups of characters inside words.

  • Search Backward Searches backwards from the current insertion point position to the beginning of the file.

  • Use wildcards Makes it possible for you to use wildcard characters in your search text.

    With Use wildcards cleared, a literal search is conducted for any characters. When Use wildcards is selected, the following rules apply:

    Character Description Usage

    ?

    Any single character

    Specified in place of the missing character.

    *

    Zero or more characters

    Specified in place of the missing character/s.

    #

    Any single digit

    Specified in place of the missing digit.

    <

    Beginning of a word

    Finds expression at beginning of a word.

    >

    End of a word

    Finds expression at end of a word. Must be placed after characters to search.

    [charlist]

    Set of characters

    Matches any one of the specified characters in the brackets. Set can be a range, separated by a dash (–) (for example, [a-d]).

    [!charlist]

    Exclude characters

    Matches any character except those following the exclamation mark in brackets.

    \

    Escape

    Matches the character following the backslash (\). This makes it possible for you to find characters used in the regular expression notation, such as * and >.
Scope

Defines how extensive the search is. The Scope options are enabled when you are editing a procedure in a Code window.
  • Current Procedure Searches only the current procedure, which is displayed in the Code window.

  • Current Object Searches all procedures (event code) in the current (selected) object.

  • All Objects Searches all procedures (event code) in all objects in the current form or form set. If Wrap Around is selected, only the current method or event, will be searched.

Find Next

Finds the next occurrence of the string you typed in the Look For box.
Replace

Expands the dialog box by adding a Replace All button and the Replace With text entry box, in which you can specify replacement text.

See Also

Other Resources

Dialog Boxes
Replace Dialog Box
Paste Special Dialog Box
Go To Line Dialog Box
Insert Object Dialog Box
Change Icon Dialog Box
Edit Links Dialog Box
Code window


Find Table or View Dialog Box

Visual FoxPro 9.0
Find Table or View Dialog Box
See Also

Makes it possible for you to a table or view that you cannot locate easily in the Database Designer. This dialog box appears when you click Find Object on the Database menu. For more information, see How to: Find Tables or Views in Databases.

Tables or Views

Shows a list of objects in your database layout that you can find. If the table or view you want does not appear in this list, it has not been added to the database.
Find button

Selects and displays the object in the database schema.

See Also

Other Resources

Dialog Boxes


Font Dialog Box

Visual FoxPro 9.0
Font Dialog Box
See Also

Controls the font type, style, and size.

You can change fonts in a text file, field or label control in a report or label, or the Command window. To change fonts in reports and labels, you must create a label control or field control and then select it.

Font

Displays the available fonts.
Font Style

Displays the styles (Regular, Bold, Italic, or Bold Italic) you can apply to the font or selected text.
Size

Displays a list of point sizes for the font. Effects
  • Strikeout Strikes through text using a horizontal line. This option appears only when you are working with a report or label.

  • Underline Underlines the selected text. This option appears only when you are working with a report or label.

Color

Specifies text color of selected text. This option appears only when you are working with a report or label.
Sample

Displays a sample of the selected font's letter style for both uppercase and lowercase letters.
Script

Lists the available language scripts for a specific font. Pick the one appropriate for the language your computer is set up for.

See Also

Other Resources

Dialog Boxes
Browse Window
Edit Window
Fonts Overview
FontBold, FontItalic, FontStrikethru, FontUnderline Properties


Format (Field) Dialog Box

Visual FoxPro 9.0
Format (Field) Dialog Box
See Also

Makes it possible for you to specify format expressions for output generated from Field report controls in the Report Designer or Label Designer. For more information, see Format Expressions for Field Controls.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

General formatting options

Format

Specifies a format expression, which can include format codes and format template characters, instead of selecting options from the Editing options group.
Character

Specifies that the output from the Field report control has Character type and displays the appropriate options in the Editing options group.
Numeric

Specifies that the output from the Field report control has Numeric type and displays the appropriate options in the Editing options group.
Date

Specifies that the output from the Field report control has Date type and displays the appropriate options in the Editing options group.

Editing options

Displays format options depending on the data type selected. Selecting these options inserts a formatting code in the Format box in the Report Expression dialog box. For more information, see Report Expression Dialog Box.

To upper case

Displays output with Character type in uppercase characters.
Ignore input mask

Determines how additional format templates display with output of Character type. If Ignore input mask is checked, additional characters in the format template characters display interleaved between characters from the evaluated field expression. If Ignore input mask is cleared, additional characters in the format template function replace (or overlay) characters from the evaluated field expression. For example, suppose a record in the underlying table contains the characters ABC1234, and you specify the format template NNN-NNNN. Selecting the Ignore input mask check box displays ABC1234 as ABC-1234; while clearing the Ignore input mask check box displays ABC1234 as ABC-234.
Left justify

Aligns output with Character or Numeric type with the leftmost position in the Field control.
Right justify

Aligns output with Character type with the rightmost position in the Field control.
Right justify

Aligns output with Character type with the center of the Field control.
Blank if zero

Does not display output with Numeric type that consists only of zeroes.
(Negative)

Displays and encloses negative values in output with Numeric type with parentheses (()).
SET DATE format

Specifies that output appear as a date using the current format setting of the SET DATE command. For more information, see SET DATE Command.
British date

Displays output as a date in British date format. For more information, see SET DATE Command.
CR if positive

Displays and follows positive values in output with Numeric type with the text, "CR (credit)".
DB if negative

Displays and follows negative values in output with Numeric type with the text, "DB (debit)".
Leading zeros

Displays all leading zeroes in output with Numeric type.
Currency

Displays output with Numeric type using the currency format specified on the Regional tab in the Options dialog box. For more information, see Regional Tab, Options Dialog Box.
Scientific

Displays output with Numeric type in scientific notation, which can be useful for very large or small numbers.

See Also

Other Resources

How to: Specify Data Types for Field Controls
Dialog Boxes
Report Designer


FRX Cursor Browser Dialog Box (Report Builder)

Visual FoxPro 9.0
FRX Cursor Browser Dialog Box (Report Builder)
See Also

Allows you to browse the records in FRX table underlying your report layout. This modal dialog is available on the Browse FRX… option from the context menu of any Report Builder dialog.

Dialog options

The following dialog options provide you with ways of customizing the dialog's display.

Grid

Displays the records in the FRX cursor underlying the current report layout. You can scroll vertically through the records and horizontally through the columns.
Name

Displays the contents of the NAME column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
Expr

Displays the contents of the EXPR column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
Style

Displays the contents of the STYLE column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
Picture

Displays the contents of the PICTURE column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
Order

Displays the contents of the ORDER column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
Comment

Displays the contents of the COMMENT column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
Tag

Displays the contents of the TAG column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
Tag2

Displays the contents of the TAG2 column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
Fontface

Displays the contents of the FONTFACE column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
SupExpr

Displays the contents of the SUPEXPR column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
User

Displays the contents of the USER column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
CURPOS=.T. (Object selected in layout)

Displays the value of the CURPOS column of the current record of the FRX cursor. The value is refreshed as you scroll through the grid.
OK

Closes the Browse FRX dialog.

Displaying the FRX Cursor Browser using command-line parameters

You can use the report builder's command-line parameters to display the FRX Cursor Browser dialog box directly from the Command window:

To display the FRX Cursor browser

  1. Open the Command window.

  2. Type the following command:

DO (_REPORTBUILDER) WITH 2 [, cFileName ]

If the second parameter is omitted, you will be prompted to select a report file with the Open File dialog box.

See Also

Reference

_REPORTBUILDER System Variable

Other Resources

Report Layout and Design


General Options Dialog Box

Visual FoxPro 9.0
General Options Dialog Box
See Also

Allows you to specify code for an entire menu system. You can access this dialog box by selecting General Options from the View Menu in the Menu Designer.

Procedure

Creates menu procedure code. If code exceeds the displayed editing region, the scroll bar is activated.
Edit

Opens an editing window so you can create code there instead of in the GeneralOptions dialog box. To activate the editing window, click Edit, and then click OK in the GeneralOptions dialog box.

Location

Replace

Replaces the existing menu system with a new menu system.
Append

Adds a new menu system to the right of the active menu system.
Before

Inserts a new menu before the specified menu. This option displays a drop-down list containing the names in the active menu system. To insert the new menu, select the menu name you want the new menu to precede.
After

Insert a new menu after the specified menu. This option displays a drop-down list containing the names in the active menu system. To insert the new menu, select the menu name you want the new menu to follow.

Menu Code

Setup

Opens an editing window in which you can add setup code to a menu system. To make the editing window active, click OK in the GeneralOptions dialog box.
Cleanup

Opens an editing window in which you can add cleanup code to a menu system. To make the editing window active, click OK in the GeneralOptions dialog box.
Top-Level Form

If checked, allows the menu to be used in a top-level (SDI) form. If not checked, allows the menu to only be used on the Visual FoxPro frame.

For more information, see Designing Menus and Toolbars.

See Also

Other Resources

Dialog Boxes
Menu Designer
Menu Options Dialog Box
Define Window Layout Dialog Box
Tab Order Dialog Box
Toolbars Dialog Box


Generate Menu Dialog Box

Visual FoxPro 9.0
Generate Menu Dialog Box
See Also

Lets you specify a name for the generated menu program and then generate the program. If you have not saved your menu, you are prompted to do so.

This dialog box appears when you select Generate from the Menu menu.

Output File

Specifies the path to the generated menu program. Choose the dialog button to select a directory and file name, or substitute a file name of your choice by typing over the name displayed.
Generate

Produces a menu program file, which has the .mpr extension.

See Also

Other Resources

Dialog Boxes
Do Dialog Box
Menu Designer
Menu System Creation
Menu System Design Guidelines
Creating Menus, Shortcut Menus, Menu Items, and Submenus
CREATE MENU Command


Get Latest Version of Files Dialog Box

Visual FoxPro 9.0
Get Latest Version of Files Dialog Box
See Also

Gets the selected files from the source code control provider and places a local copy in the Project Manager.

File(s) to Get Latest Version

Lists available files in the source code control project.
Select All

Selects all available files.
Advanced

Displays the source code control provider's Advanced Get Options dialog box.

See Also

Other Resources

Dialog Boxes
Check In Files Dialog Box
Check Out Files Dialog Box
Undo Check Out of Files Dialog Box
Project Manager Hooks


Go To Line Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Go To Line Dialog Box (Visual FoxPro)
See Also

This dialog box makes it possible for you to move the insertion point to the designated line in a text or program file or in the Command window.

Line Number

Specifies the line number where you want the insertion point to appear.

See Also

Other Resources

Dialog Boxes
Command Window
Find Dialog Box
Options Dialog Box
SYS(2002) - Turn Insertion Point On or Off
Insert Object Dialog Box
Replace Dialog Box


Go To Record Dialog Box

Visual FoxPro 9.0
Go To Record Dialog Box
See Also

Specifies which record to move the record pointer to. Type the record number in the Record Number box, or use the up and down arrows as required until the desired number displays in the Record Number box. Choose OK to return to the Browse window with the record pointer on the specified record.

This dialog box appears when you choose the Record # command from the Go to Record submenu.

See Also

Other Resources

Dialog Boxes
Browse Window
Locate Record Dialog Box
Scope Dialog Box
Field Picker Dialog Box
Working with Records
Record Manipulation


Having Dialog Box

Visual FoxPro 9.0
Having Dialog Box
See Also

Specifies conditions for selecting which groups of records to include in query output.

The Having dialog box appears when you choose Having in the Group By Tab, Query and View Designers.

Field Name

Specifies a function, field name, or other expression. When creating a Having clause, select the field to display a list of functions, a list of field names for each table, or use the expression command to display the Expression Builder dialog box. If you choose a function, a submenu displays a list of field names available to use with that function.
Not

Reverses the comparison criterion.
Comparison criterion

Specifies the operator for the selection criterion. The comparison criteria are as follows:
  • Equal (=) Specifies that field and the value in the Example field have the same value.

  • Like Specifies that the field must include characters that match characters in the text in the Example field.

    For example, Customer.state Like O matches records from Ohio, Oklahoma, and Oregon.

  • Exactly Like (==) Specifies that the field must match, character for character, the text in the Example field.

  • Greater Than (>) Specifies that the field must be more than the value in the Example field.

  • Less Than (<) Specifies that the field must be the same or less than the value in the Example field.

  • Greater Than or Equal To (>=) Specifies that the field must be the same or more than the value in the Example field.

  • Less Than or Equal To (<=) Specifies that the field must be the same or less than the value in the Example field.

  • Is NULL Specifies that the field must contain a null value.

  • Is True Specifies the left field or expression evaluates to True, assuming the field or expression evaluates to a logical value.

  • Between Specifies that the field must be greater than or equal to the lower value, and less than or equal to the higher value, in the condition appearing in the Example column. You must separate the two values in the Example column with the word AND. Visual FoxPro creates the query with the word BETWEEN.

    For example, Invoices.idate Between 05/10/97 AND 05/12/97 matches records for the 10th, 11th, and 12th of May, 1997.

  • In Specifies that the field must match one of several values in the comma-separated list appearing in the Example field.

    For example, Customer.name In Al,George,Mary matches records in which the customer's name is Al, George, or Mary.

Example

Specifies the value or text with which you want to compare the field. To match the text casing of the example, use the UPPER( ), LOWER( ), and PROPER( ) functions.
Logical

Adds an AND or OR condition to the list of conditions.
Pri. (Priority)

Specifies a number ranging from 0 to 99, which indicates the priority for logical operations. The number 0 indicates the highest priority, while the number 99 indicates the lowest priority. Setting priorities for logical operations determines the order in which logical operations are performed and uses parentheses (()) for grouping operations. For example, suppose you specify a priority of 0 for a logical operation, a priority of 1 for a second logical operation, and a priority of 0 for a third logical operation. The first and third logical operations, which have a priority of 0, are performed before the second logical operation, which has a priority of 1.
Insert

Inserts a blank row above the selected condition.
Remove

Removes the selected row from the Field Name list.

See Also

Other Resources

Dialog Boxes
Group By Tab, Query and View Designers
Query and View Designers
SELECT - SQL Command
CREATE QUERY Command
How to: Create Queries


Import Dialog Box

Visual FoxPro 9.0
Import Dialog Box
See Also

Lets you import data to a Visual FoxPro table from a spreadsheet or another table format. You can also use the Import Wizard to import files.

Note:
You cannot import text files with this menu command. To import text files, use the Import Wizard, or create a table and then append the text file to the new table.

This dialog box appears when you select Import from the File menu.

Type

Specifies the type of file to import. Select a file type from the list.
From

Specifies the path and name of the source file. Type the path and name, or click the dialog button to find the source file.
Sheet

Specifies a Microsoft Excel worksheet to import. This box appears only if you select Microsoft Excel in the Type box.
To

Displays the path, as defined in the File Locations tab, Options dialog box, and the file name of the imported file. The file name is that of the source file, but with a .dbf extension.
Import Wizard

Starts the Import Wizard, which prompts you with simple questions as you go through a brief series of steps. You must use the Import Wizard to import text files, or create a table and then append the text file to the new table.

The following table shows the file types you can import with this command, and their equivalents that you would type in the Command window.

File Types | Command Equivalent
FrameWork II (FW2) | IMPORT FROM FileName TYPE FW2
Lotus 1-2-3 1-A (WKS) | IMPORT FROM FileName TYPE WKS
Lotus 1-2-3 2.x (WK1) | IMPORT FROM FileName TYPE WK1
Lotus 1-2-3 3.x (WK3) | IMPORT FROM FileName TYPE WK3
Microsoft Excel 2.0, 3.0, and 4.0 (XLS) | IMPORT FROM FileName TYPE XLS
MultiPlan 4.01 (MOD) | IMPORT FROM FileName TYPE MOD
Paradox 3.5, 4.0, 4.5 (DB) | IMPORT FROM FileName TYPE PDOX
RapidFile (RPD) | IMPORT FROM FileName TYPE RPD
Symphony 1.01 (WRK) | IMPORT FROM FileName TYPE WRK
Symphony 1.10 (WR1) | IMPORT FROM FileName TYPE WR1

See Also

Other Resources

Dialog Boxes
Append From Dialog Box
Command Window
Export Dialog Box
Import Wizard
IMPORT Command
File Locations Tab, Options Dialog Box
Importing and Exporting Data


Include File Dialog Box

Visual FoxPro 9.0
Include File Dialog Box
See Also

Makes it possible for you to specify a header file containing predefined compile-time constants for a user-defined class, form, or form set.

This dialog box appears when you select Include File from the Class or Form menus.

Include File

Specifies a header file containing predefined compile-time constants for a user-defined class, form, or form set. Type the name of the header file in the box, or use the dialog button to select an existing header file.

See Also

Other Resources

#INCLUDE Preprocessor Directive
#DEFINE Preprocessor Directive
Constants
Dialog Boxes


Insert Object Dialog Box

Visual FoxPro 9.0
Insert Object Dialog Box
See Also

This dialog box lists the OLE objects you can link or embed in your application for forms or General fields in Visual FoxPro tables.

In a browse window, double-click a General field to bring up an editing window and enable the Insert Object command.

For a form, select an OLE Container control while a form is displayed. This displays the Insert Object dialog box and the new object is stored in the field to which the control is bound.

Create New

Displays the Object Type box so you can choose an OLE application in which to create a new object.
Object Type

Appears when you select Create New, and displays the OLE applications installed on your computer. Select an application in which to create the object.
Create From File

Displays the File box so you can specify an existing object to insert.
File

Appears when you select Create From File. Type the object's file name and path, or click Browse to select the appropriate file.
Browse

Opens the Browse dialog box that makes it possible for you to select a table or view.
Link

Links the object. If you don't select this option, the object is embedded.
Display As Icon

Displays the inserted object as an icon. The icon comes from the application in which the object was created.
Results

Depending on the radio button selected, can display a description of action to be performed on the contents of the file after you click OK, a Unique Identifier, and a path to the Control or Object Type selection. You can alter the description displayed by choosing the Create New, Create from File, or Display As Icon options.
Change Icon

Displays the Change Icon dialog box, which makes it possible for you to select a different icon for the OLE object. Appears when you select the Display As Icon option.
Insert Control (forms only)

Displays the Control Type box so you can insert an ActiveX control.
Control Type (forms only)

Appears when Insert Control is selected, and lists the ActiveX controls you can insert.
Add Control (forms only)

Appears when Insert Control is selected, and displays the Browse dialog box so you can find and select an ActiveX control not listed under Control Type.

See Also

Other Resources

Dialog Boxes
Controls Tab, Options Dialog Box
General Field Type
Properties Window
Change Icon Dialog Box
Dynamic Information Sharing


Insert Object Reference Dialog Box

Visual FoxPro 9.0
Insert Object Reference Dialog Box
See Also

Makes it possible for you to see the name of all objects in the designer and insert a fully qualified reference to the object in your code.

This dialog box appears when you choose Objects List from the shortcut menu of the Code Window in the Form Designer or Class Designer.

Objects list

All the objects contained in the highest-level container in the Form Designer or Class Designer. Contained objects are indented to indicate the container hierarchy.
Insert

Inserts a string with the full object reference at the cursor in the editing window.

See Also

Other Resources

Dialog Boxes
Document View Window
Insert Object Dialog Box


Insert System Menu Bar Dialog Box

Visual FoxPro 9.0
Insert System Menu Bar Dialog Box
See Also

Allows you to add menus and menu options to the Menu Designer window. This dialog box appears when you choose Insert Bar from the Menu menu or select the Insert Bar button on the Menu Designer window.

Menu List Box

Lists the available menu names and menu option names, depending on whether you have chosen Usage or Prompt in the Order by area.

Order By

Usage

Designates that the Menu List Box display the available menu items in the order that they would appear on their respective menu titles. For example, all of the File menu items are listed first, in the order that they appear on the actual File menu. Edit menu items appear next, and so on.
Prompt

Designates that the Menu List Box display the available menu items in alphabetical order.
Insert

Inserts the selected menu item on the designated row in the Menu Designer window.

See Also

Other Resources

Dialog Boxes
Generate Menu Dialog Box
Menu Options Dialog Box
Menus and Menu Bars
Menu Designer


Join Condition Dialog Box

Visual FoxPro 9.0
Join Condition Dialog Box
See Also

Specifies a join condition between tables. This dialog box appears when you add more than one table in your query or view, and those tables do not have a join condition already specified.

For more information about join conditions, see Join Conditions for Tables, Queries, and Views.

Right Field List

Shows the fields from the table you have added. Select a field from the list by which to join the tables.
Left Field List

Shows the fields from all of the tables previously added into the Query Designer. Select a field from the list by which to join the tables.

Type of Join

Inner Join

Creates a join that will list only the records from the Left Field List that match the records from the Right Field List for the fields selected.
Left Join

Creates a join that includes the Left Field List records and the matching Right Field List records for the fields selected.
Right Join

Creates a join that includes the Right Field List records and the matching Left Field List records for the fields selected.
Full Join

Creates a join that includes all the records from both list boxes for the fields selected in the list boxes.
Description

Specifies how the fields of each table will relate to each other when you select the different join options.

See Also

Other Resources

Dialog Boxes
Add Table or View Dialog Box
SELECT - SQL Command
SET ANSI Command
Query Destination Dialog Box
Query Designer


Label Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Label Dialog Box (Visual FoxPro)
See Also

Displays the results of the query in an existing label. This dialog box appears on the Miscellaneous tab of the Query Designer and is available for queries only.

Note:
You must have previously set up the label file (.lbx) to accommodate the columns of output in the query. For more information, see Working with Reports.

Open Label

Displays the Open dialog box for you to select a label file to use for your query. You can click the button or type a file name in the text box.
Wizard Icon

Displays the Label Wizard.
Page Preview

Displays the output in the Page Preview window.
Console On

Displays the output in the active output window.

Secondary Output

None

Specifies that the output not be sent to the printer or saved as a text file.
To Printer

Sends the results of the query to the printer.
To Text File

Saves the results of the query as a text file. Click the button to select an existing file that you want to overwrite, or type the name of a new file in the text box.

See Also

Other Resources

Miscellaneous Tab, Query and View Designers
Label Wizard
Label Designer
Dialog Boxes


Locate Database Dialog Box

Visual FoxPro 9.0
Locate Database Dialog Box
See Also

Makes it possible for you to locate or ignore a missing table or view.

This dialog box appears when you open or run a form and Visual FoxPro is unable to locate a table or view in the data environment of the form.

Locate

Displays the Open Dialog Box, so you can find the table or view.
Ignore

Visual FoxPro will continue to load the form without instantiating the cursor object in data environment. If there are controls bound to fields in the table or view, additional errors will be generated.
Cancel

Visual FoxPro will stop loading the form.
Help

Displays Help on the dialog box.

See Also

Other Resources

Dialog Boxes
Open Dialog Box
LOCATE Command
Locate Record Dialog Box
Locate Button
Find Table or View Dialog Box
Add Table or View Dialog Box


Locate File Dialog Box

Visual FoxPro 9.0
Locate File Dialog Box
See Also

Makes it possible for you to locate or ignore a missing file or group of files. This dialog box appears when you run a program and Visual FoxPro is unable to locate a needed file to successfully run the program.

Locate

Displays the Open Dialog Box, so you can find the file.
Ignore

Visual FoxPro will continue to run the program without the required file.
Ignore all

Visual FoxPro will continue to run the program without the required group of files.
Cancel

Visual FoxPro will stop running the program.

See Also

Other Resources

Dialog Boxes
Open Dialog Box
LOCATE Command
Locate Record Dialog Box
Locate Button
Find Table or View Dialog Box
Add Table or View Dialog Box
Locate Database Dialog Box


Locate Record Dialog Box

Visual FoxPro 9.0
Locate Record Dialog Box
See Also

Searches for a record in the active table or view that matches specified conditions. Use this command when you want to search a table or view record-by-record on an indexed or unindexed field, or when you want to find more than one record in a table.

This dialog box appears when you choose the Locate command from the Go to Record Submenu.

Scope

Allows you to specify the records on which Visual FoxPro is to act. ChooseAll, Next, Record, or Rest from the drop-down list. Choose a number from the spinner on the right when you select Next or Record from the Scope drop-down list.
For

Displays the Expression Builder dialog box, in which you create the logical expression that every record must meet to be affected by the command.
While

Displays the Expression Builder Dialog Box. The While expression specifies that the action affects records only as long as the logical expression is true. The first time the expression evaluates to false, the action ceases without considering remaining records.
Locate

Carries out the command using the Scope, For, and While values.

See Also

Tasks

How to: Add Records to Tables

Other Resources

Dialog Boxes
Browse Window
CONTINUE Command
Expression Builder Dialog Box
LOCATE Command
Scope Dialog Box
Working with Records
Record Manipulation


Look Up Reference Dialog Box

Visual FoxPro 9.0
Look Up Reference Dialog Box
See Also

Provides a way for you to search for occurrences of a code reference in a project, specific folder or subfolder. You can filter your search by file type.

The Look Up Reference dialog box appears only in design mode when you select Code References on the Tools menu. You can also select Look Up Reference when you right-click inside the editing window for programs or open the Look Up Reference dialog box programmatically for the first time using the following code:

Copy Code
DO(_FOXREF)

For more information about calling the _FOXREF system variable, see _FOXREF System Variable.

Look for

Specifies the target search expression. Visual FoxPro populates the Look for box with the expression selected in the Editing window. The Look for box contains any recently selected or previously searched expressions. When you select the Use regular expressions check box, an arrow button next to the Look for box becomes available. Selecting the Use regular expressions check box allows for wildcard character searches. For more information, see "Use regular expressions" in this topic.
Scope

Specifies the range of the search and contains the following options:
  • Folder Search the current folder and optionally, subfolders.

  • Project Search the set of files in the selected project. Only opened projects appear in the drop-down list.

Look in

Specifies the current folder and contains a drop-down list with the history of previously selected folders when Folder is selected in the Scope box. To select a different folder, click the ellipsis (...) button to open the Select Directory dialog box. The Look in box is not available when Project is selected in the Scope box.
Search subfolders

Includes subfolders of the selected folder in your search. The Search subfolders check box is available only when Folder is selected in the Scope box.
Limit search to project home directory and subfolders

Includes only those files in the project that are located within the project's home folder and subfolders. Shared files are excluded. This check box is available only when Project is selected in the Scope box.
Overwrite prior results

Controls whether results from an earlier search are included or overwritten in the new search. This option functions similarly to selecting Clear All Results from the context menu in the Code References window to replace all the content in the Search pane. The Overwrite prior results check box is available when Folder or Project scope is selected.
File Types

Specifies a set of file types for limiting your search. File types are separated by commas. The most recent value used in a search is used in the next search. You can add custom file types using the FoxRefAddin.dbf file. The FoxRefAddin table allows for specific file type extensions that are excluded when doing a wildcard file name (*.*) search. The following table lists all Visual FoxPro file types that are supported and how searches on a file type are conducted.

File extension Behavior

.cdx

Search index expressions. Selecting this extension requires a table to be open to find the expression.

.dbc

Search stored procedures, remote view source, connections, and other .dbc data, excluding .dbf files and structures.

.dbf

Search field names and any extended .dbc file metadata such as trigger expressions but not table contents. Visual FoxPro might need to temporarily open or close tables if you select this extension.

.frx, .lbx

Search report and label expressions, label values, and data environment.

.mnx

Search menu names and associated code.

.prg

Search program files and display the line number for the reference if found.

.scx

Search all method code, data environment, and non-default property values.

.vcx

Search all method code and non-default property values.

Other file types

Treat search expressions as strict text.
The following table lists default file type groups appearing in the drop-down list in the File Types box.

File types File extensions

All Files

*.*

Common

*.scx, *.vcx, *.prg, *.frx, *.lbx, *.mnx, *.dbc, *.qpr, *.h

All Source

*.scx, *.vcx, *.prg, *.frx, *.lbx, *.mnx, *.dbc, *.dbf, *.cdx, *.qpr, *.h

Forms and Classes

*.scx, *.vcx, *.prg

Reports and Labels

*.frx, *.lbx

Menus

*.mnx

Programs

*.prg, *.h, *.qpr, *.mpr

Data Structures

*.dbc, *.dbf, *.cdx

Text

*.txt, *.xml, *.xsl, *.html, *.log, *.asp, *.aspx
Note:
The Common source file type group includes only .dbc files as a data source option by default. The default behavior is to search only stored procedures. You can change this behavior by clicking the Options button in the Look Up Reference dialog box.

Options

Opens the Options dialog box to set additional options for your search. For more information, see Look Up Reference Dialog Box, Options Dialog Box.

Options Group

The Options group box includes additional options you can specify to customize your search.

Match case

Specifies whether your search is sensitive to text casing.
Match whole word

Specifies whether your search must match entire words exactly.
Use regular expressions

Allows for wildcard character searches. Selecting the Use regular expressions check box enables the arrow button next to the Look for box. Clicking the arrow button opens a menu from which you can select a regular expression type to insert in the Look for box. For more information about regular expressions, see Regular Expressions and Operators.
Comments

Specifies whether to include code comments in your search. Comments begin with an asterisk (*), double ampersand (&&), or NOTE keyword. The Comments drop-down list includes the following options:
  • Include Comments Include comments in your search.

  • Ignore Comments Ignore comments in your search.

  • Comments Only Search comments only.

See Also

Other Resources

Dialog Boxes
Code References Window
How to: View Code Definitions
_FOXREF System Variable


Look Up Reference Dialog Box, Options Dialog Box

Visual FoxPro 9.0
Look Up Reference Dialog Box, Options Dialog Box
See Also

Sets additional options for a code reference search.

The Options dialog box appears when you click the Options button in the Look Up Reference dialog box or the Code References window. You can obtain descriptions of each option by clicking the option text.

Create symbol definition table during search

Specifies collecting code symbol definitions from processed files during a reference search. Otherwise, definitions are collected on demand when viewing code definitions. This option performs a full definition scan during a reference search and saves time when viewing code definitions. For more information, see How to: View Code Definitions.
Limit definition collection to project home directory and below

Specifies that a collection of code symbol definitions for a project include only those files that are in the project's home directory tree. This prevents including definitions from framework and other files that are not immediately relevant to the current project.
Search only source code and expressions

Specifies that searching is performed only on source code and expressions. Otherwise, values such as field names in tables, label values in reports, captions, and other text are included in the search.
Search form/class property names and values

Specifies that properties names and values of visual forms (.scx) and visual classes (.vcx) are included in a reference search.
Display number of references found per line in search results

Specifies that an indicator is displayed in the references window next to results that have more than one match per line.
Show history of file types searched

Specifies that a history of recently selected file types is displayed in the Look Up Reference window. Otherwise, only common file types and the most recent file type selected are displayed.
Show separate columns for class, method, and line

Specifies that the class, method, and line are displayed in separate columns rather than being concatenated into a single column in the results grid. If the the class, method, and line are displayed in separate columns, you can sort the methods by right-clicking in the Methods column and choosing Sort by Method.
Backup Style

Specifies how files are named when backing them up during global code reference replacement.
Font

Displays the Font dialog box, which you can use to change the font of the Code References window.
Folder for code references tables

Specifies and contains the location for core code reference tables. To select a different folder, click the ellipsis (...) button to display the Select Directory dialog box.
Clean Up Source Tables

Cleans up Visual FoxPro reference tables by looking for old and outdated records. Specifically, this option performs the following actions:
  • Removes all Inactive and Error records from the RefFile.dbf file except where UniqueID="WINDOW", which always remains.

  • Removes all records that reference files that do not exist on the disk from the RefFile.dbf file and any corresponding records in the RefDef.dbf file.

  • Removes all Inactive records from the RefDef.dbf file.

  • Performs a PACK operation on the RefFile.dbf and RefDef.dbf files.

See Also

Other Resources

Dialog Boxes
Look Up Reference Dialog Box
Code References Window
PACK Command


Macros Dialog Box

Visual FoxPro 9.0
Macros Dialog Box
See Also

Makes it possible for you to define key combinations using the CTRL key, ALT key, or function keys to perform a series of keystrokes. You can combine individual macros in sets and store them in files.

Individual Macro

Displays macros available for use.
Record

Displays the Record Macro Dialog Box, in which you can create a macro.
New

Displays the New Macro Dialog Box, in which you can manually create a macro.
Edit

Displays the Edit Macro Dialog Box, in which you can edit the selected macro.
Clear

Prompts you to erase or keep the selected macro.

Macro Set

Save

Displays the Save Macros dialog box, in which you can name and save individual macros or macro sets.
Restore

Displays the RestoreMacros dialog box, in which you can add a saved macro set to the current macros (that is, those in the Individual macro box in the Macros dialog box).
Set Default

Prompts you to overwrite the default macro set with a new macro set.
Clear All

Prompts you to erase all macros in the Individual Macro list.

See Also

Other Resources

Dialog Boxes
APPEND Command
DIR or DIRECTORY Command
DISPLAY Command
DISPLAY MEMORY Command
DISPLAY STATUS Command
DISPLAY STRUCTURE Command
LIST Commands
Macro File Format (.fky)
Macro Substitution
PLAY MACRO Command
SET Command Overview
Overwrite Macro Dialog Box
Stop Recording Macro Dialog Box


Record Macro Dialog Box

Visual FoxPro 9.0
Record Macro Dialog Box
See Also

Automatically creates a macro by recording your keystrokes until you stop recording.

This dialog box appears when you choose Record in the Macros Dialog Box.

Defined Key

Displays the key combination you press that will run the macro. To assign your macro to a particular keystroke, put the cursor in this field, and then press the key or key combination. Visual FoxPro puts the name of the key or key combination you pressed into this field and assigns the macro you are about to record to that key or key combination.
Macro Name

Displays the default macro name, which is based on the defined key. For example, if the defined key is CTRL+D, the macro name will be CTRL_D. If you want to rename the macro, type the new name (up to 20 characters) in the box. The recording does not begin until you click OK, which puts the insertion point in the command window where you record the macro.

See Also

Other Resources

Dialog Boxes
Overwrite Macro Dialog Box
SET FUNCTION Command
Stop Recording Macro Dialog Box
New Macro Dialog Box
Edit Macro Dialog Box


Stop Recording Macro Dialog Box

Visual FoxPro 9.0
Stop Recording Macro Dialog Box
See Also

Interrupts the process of recording a macro. From this dialog box, you can choose OK to stop recording the macro as it is, or you can take advantage of some other options.

This dialog box appears when you select Macros from the Tools Menu while recording a macro.

Insert Literal

Records the literal meaning of the next keystroke, instead of a meaning currently assigned to the key with a macro. Use this when you want to circularly define two keys.
Insert Pause

Records a pause in the macro. Before you choose InsertPause, choose either Key To Resume or Seconds to define how macro execution will resume.
Key to Resume

Prompts for a key that resumes execution of a macro that has been paused. This prompt appears only if you have implemented the SET MACKEY Command.
Seconds

Specifies how long the pause in macro execution lasts before it automatically resumes. In the spinner control, type or select a number.
Continue

Returns to the point before the Stop Recording Macro dialog box appeared so you can continue recording the macro.
Discard

Deletes the macro you are recording and puts your insertion point in the last entered text box.
OK

Confirms that the macro is completed and ready for use.

See Also

Other Resources

Dialog Boxes
Macros Dialog Box
Overwrite Macro Dialog Box
New Macro Dialog Box
Edit Macro Dialog Box


Overwrite Macro Dialog Box

Visual FoxPro 9.0
Overwrite Macro Dialog Box
See Also

Replaces an existing macro with a new one of the same name. This dialog box appears when you define an already existing key combination in the Record Macro Dialog Box and click OK.

Overwrite

Replaces the existing macro definition with the new definition.
Append Keystrokes

Adds keystrokes to the end of the existing macro. The insertion point is placed in the last entered text box so you can type the keystrokes to append.

See Also

Other Resources

Dialog Boxes
New Macro Dialog Box
Edit Macro Dialog Box
Stop Recording Macro Dialog Box
Macros Dialog Box


New Macro Dialog Box

Visual FoxPro 9.0
New Macro Dialog Box
See Also

Manually creates a macro instead of recording your keystrokes.

Defined Key

Displays the key combination you press that will launch the macro.
Macro Name

Displays the default macro name, which is based on the defined key. For example, if the defined key is CTRL+D, the macro name will be CTRL_D. If you want to rename the macro, type the new name (up to 20 characters) in the box.
Macro Contents

Provides space for you to type the keystrokes the macro executes. Use the key label assignments listed in the ON KEY LABEL Command topic and enclose them in braces to represent the desired keystrokes. Place all key combinations (such as CTRL+F2) in braces also. For example:
Copy Code
MODIFY{SPACEBAR}COMMAND{ENTER}
{HOME}{SHIFT+END}
Note:
The key combinations SHIFT+CTRL+\, CTRL+–, CTRL+^, and SHIFT+CTRL+ENTER are not supported in Visual FoxPro.

See Also

Other Resources

Dialog Boxes
Edit Macro Dialog Box
Macros Dialog Box
Overwrite Macro Dialog Box
Stop Recording Macro Dialog Box
Record Macro Dialog Box


Edit Macro Dialog Box

Visual FoxPro 9.0
Edit Macro Dialog Box
See Also

Makes it possible for you to manually edit a preexisting macro.

Defined Key

Displays the key combination you press that will launch the macro.
Macro Name

Displays the default macro name, which is based on the defined key. For example, if the defined key is CTRL+D, the macro name will be CTRL_D. If you want to rename the macro, type the new name (up to 20 characters) in the box.
Macro Contents

Provides space for you to type the keystrokes the macro executes. Use the key label assignments listed in the ON KEY LABEL Command topic and enclose them in braces to represent the desired keystrokes. Place all key combinations (such as CTRL+F2) in braces also. For example:
Copy Code
MODIFY{SPACEBAR}COMMAND{ENTER}
{HOME}{SHIFT+END}
Note:
The key combinations SHIFT+CTRL+\, CTRL+–, CTRL+^, and SHIFT+CTRL+ENTER are not supported in Visual FoxPro.

See Also

Other Resources

Dialog Boxes
Macros Dialog Box
Overwrite Macro Dialog Box
Stop Recording Macro Dialog Box
Record Macro Dialog Box


Menu Options Dialog Box

Visual FoxPro 9.0
Menu Options Dialog Box
See Also

Allows you to specify code for a specific menu. You can access this dialog box by selecting Menu Options from the View Menu in the Menu Designer.

Name

Contains the name of the menu. By default, this is the same as the text in the Prompt column of the MenuDesigner. Change it by typing a new name in the Prompt column.
Procedure

Provides space for menu procedure code, or displays existing code. If code exceeds the displayed editing region, the scroll bar is activated.
Edit

Opens an editing window so you can create code there instead of in the MenuOptions dialog box. To activate the editing window, click OK in the MenuOptions dialog box.

For more information, see Designing Menus and Toolbars.

See Also

Other Resources

Dialog Boxes
General Options Dialog Box
Define Window Layout Dialog Box
Tab Order Dialog Box
Toolbars Dialog Box


More Windows Dialog Box

Visual FoxPro 9.0
More Windows Dialog Box
See Also

Displays a list of active windows from which you can choose. This dialog box appears when you choose More Windows from the Windows menu. Choose one of the active window names listed in the Select window to view the active window.

See Also

Other Resources

Dialog Boxes
HIDE WINDOW Command
MODIFY WINDOW Command
Command Window
Data Session Window
SHOW WINDOW Command


Move Item Dialog Box

Visual FoxPro 9.0
Move Item Dialog Box
See Also

Makes it possible for you to change the location of a menu or menu item.

The Move Item dialog box appears when you select a row in the Menu Designer or Shortcut Designer and click Move Item.

Move Group

Name

Displays the name of the menu or menu item.
Type

Displays the type of the menu or menu item.

To Location Group

To Location box

Displays a list of valid locations to which you can move a menu item.

See Also

Other Resources

Dialog Boxes
Menu and Shortcut Designers


Multiple Selection Dialog Box (Report Builder)

Visual FoxPro 9.0
Multiple Selection Dialog Box (Report Builder)
See Also

Allows you to set properties on multiple selected controls at once in the report layout. The Multiple Selection dialog box appears when you select more than one control in the report layout and double-click on one of the selected controls. (Alternatively, you can right-click on one of the controls to display the context menu and select Properties.)

See How to: Select Multiple Report Controls for more information.

Note:
This dialog box is only displayed if the _REPORTBUILDER system variable is set to the default Report Builder application. If it is empty, or has been set to a third-party report builder, then the native Visual FoxPro property dialog box for the control that you double-clicked on may appear. For more information, see _REPORTBUILDER System Variable .

Tabs

The following table describes the tabs that appear in the Multiple Selection dialog box:

Tab | Options available
Selection Tab, Multiple Selection Dialog Box (Report Builder) | Allows you to review the selected controls; sort by control type or location; and remove controls from the list if you decide they should no longer be included in the selection.
Properties Tab, Multiple Selection Dialog Box (Report Builder) | Allows you to set protection options or a conditional printing expression for the currently selected controls.

See Also

Tasks

How to: Select Multiple Report Controls

Reference

_REPORTBUILDER System Variable

Other Resources

Report Layout and Design


Selection Tab, Multiple Selection Dialog Box (Report Builder)

Visual FoxPro 9.0
Selection Tab, Multiple Selection Dialog Box (Report Builder)
See Also

Allows you to review your currently selected controls in the report layout. You can:

  • Sort the list by control type or location.

  • Remove controls from the list if you decide they should no longer be included in the selection.

Object

Lists the selected report controls in the designer.
Start band

Indicates the report layout band in which the report control's top edge is located. (Some controls may span multiple report bands.)
Sort by: Type

Re-displays the object list by control type.
Sort by: Location

Re-displays the object list by control location, i.e. the band in which the top of the control is positioned.
Remove from list

Removes highlighted elements from the list of currently selected report controls. Only enabled if the list has highlighted elements.

See Also

Tasks

How to: Select Multiple Report Controls

Reference

Multiple Selection Dialog Box (Report Builder)
Properties Tab, Multiple Selection Dialog Box (Report Builder)


Properties Tab, Multiple Selection Dialog Box (Report Builder)

Visual FoxPro 9.0
Properties Tab, Multiple Selection Dialog Box (Report Builder)
See Also

Makes it possible for you to set certain attributes on multiple selected report controls in the Report Designer or Label Designer. The attributes that can be set include protection flags, and the Print When (conditional printing) expression.

Apply these protection settings to the selected objects

Specifies whether protection settings will be applied to the currently selected report controls.
When in PROTECTED mode

Exposes logical flags that specify how the selected report controls will be able to be modified in the Report Designer when in protected mode.
Apply these conditions to the selected objects upon saving

Specifies whether the conditional print expression will be applied to each of the currently selected report controls.
Remove line if blank

Specifies that the report engine may contract the report band vertically if the evaluation of the report control results in no renderable content, and no other renderable controls occupy the empty space on either side of the control.
Print only when expression is true

Provides space for typing a logical expression that will be evaluated at report run time to control whether the control is rendered in the output. You may click the ellipsis (…) button to bring up the Expression Builder dialog box to assist you in writing the logical expression.

See Also

Tasks

How to: Select Multiple Report Controls
How to: Protect Report Controls

Reference

MODIFY REPORT Command
Multiple Selection Dialog Box (Report Builder)
Protection Tab, Report Control Properties Dialog Box (Report Builder)
Print When Tab, Report Control Properties Dialog Box (Report Builder)


New Class Dialog Box

Visual FoxPro 9.0
New Class Dialog Box
See Also

Specifies information for a new class, which is used by the Class Designer to create a class. This dialog box appears when you create a new class by selecting Class in the New dialog box and then choosing New File or by typing CREATE CLASS in the Command window.

Class Name

Specifies the name of the class definition to create.
Note:
The name that you specify is converted to lowercase when the class is saved.

Based On

Specifies the class to use as the base class for the new class definition. Choose an available Visual FoxPro base class from the list or click the ellipsis (...) button to select a visual class library (.vcx) file.
From

Displays the path to the class library that you specified in the Based On box.
Store In

Specifies the name of class library to save the new class in. To select a visual class library, click the ellipsis (...) button to select a class library.

See Also

Other Resources

Command Window
Class Designer
CREATE CLASS Command
Open Dialog Box
New Dialog Box
How to: Create Classes and Subclasses
Dialog Boxes


New Dialog Box

Visual FoxPro 9.0
New Dialog Box
See Also

Makes it possible for you to create a new file. The New dialog box appears when you select New from the File menu.

Shortcut

CTRL+N

File Type

The following table lists the file types and the features available for creating them, depending on whether you click New File or Wizards.

File Type Created With

Project

Project Manager

Database

Database Designer

Table

Table Designer, Table Wizard

Query

Query Designer, Cross-Tab Wizard, Query Wizard, Local View Wizard, Remote View Wizard, PivotTable Wizard

Connection*

Connection Designer

View*

View Designer, Local View Wizard

Remote View*

Remote View Wizard

Form

Form Designer, Form Wizard, One-to-Many Form Wizard

Report

Report Designer, Report Wizard, One-to-Many Report Wizard

Label

Label Designer, Label Wizard

Program

Editing Window

Class

Class Designer

Text File

Editing Window

Menu

Menu Designer

* You must have a database open to enable this option.

New File

Displays a dialog box, designer, or editing window so you can create the selected file type.
Wizard

Opens a wizard that creates the selected file type. If there is a group of wizards to choose from, Visual FoxPro will prompt you to select the wizard you want.

See Also

Other Resources

Create Dialog Box
Dialog Boxes
Wizards


New File Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
New File Dialog Box (Visual FoxPro)
See Also

Lets you create a new form, report, label, or query, depending on the type of file currently selected in the Project Manager.

If you check Prompt for Wizard in the Projects tab, Options dialog box, Visual FoxPro prompts you with the option of running a wizard if there is a wizard associated with the selected file type.

Note:
File names preceded by a slashed circle are excluded when the project is built. If there is no slashed circle by the file name, that file will be included in the build. The main program file name is in bold.

This dialog box appears when you select New File from the Project menu.

File Type Wizard

Opens a wizard that creates the selected file type. If there is a group of wizards to choose from, Visual FoxPro will prompt you to select the wizard you want. Displayed only if you check Prompt for Wizard in the Projects tab, Options dialog box.
New File Type

Displays a dialog box, designer, or editing window so you can create the selected file type.

See Also

Other Resources

Dialog Boxes
New Dialog Box
Options Dialog Box
Project Manager Window
Projects Tab, Options Dialog Box
CREATE FORM Command
Creating Forms
CREATE REPORT Command
CREATE LABEL Command
How to: Create a New Form
How to: Create Queries
CREATE QUERY Command
Rename File Dialog Box
Description Dialog Box
Wizards


New Label Dialog Box

Visual FoxPro 9.0
New Label Dialog Box
See Also

Displays predefined Avery label types. This dialog box appears when you select Label from the New dialog box and then choose New File. The type you select becomes the basis for the new label you create in the Label Designer. The Columns column refers to how many columns of that label type will fit on a page.

The following columns display information about the label (you cannot change these settings):

Avery No.

The manufacturer's identification number for a particular label type.
Height

The height in inches of an individual label.
Width

The width in inches of an individual label.
Columns

How many columns of that label type will fit on an 8 1/2 inch x 11 inch page.
Note:
You can add a new label size to the list using the ADDLABEL.APP application located in the Visual FoxPro ...\Tools directory.

See Also

Other Resources

Dialog Boxes
New Dialog Box


New Local View Dialog Box

Visual FoxPro 9.0
New Local View Dialog Box
See Also

This dialog box lets you create a view of local tables or other views in the database using either the Local View wizard or View designer. Local views can include native Visual FoxPro .dbf format tables, existing local or remote views, any tables in a .dbf format, and other tables stored on local servers.

The New Local View dialog box only displays the Local View Wizard option when you have selected Prompt for Wizards in the Projects tab of the Options dialog box.

View Wizard

Opens the Local View wizard, which creates a local view.
New View

Opens the View designer so you can create a local view.

See Also

Other Resources

Dialog Boxes
Database Designer
Local View Wizard
Options Dialog Box
Projects Tab, Options Dialog Box
View Designer
New Remote View Dialog Box
Find Table or View Dialog Box
How to: Create Local Views


New Method Dialog Box

Visual FoxPro 9.0
New Method Dialog Box
See Also

Makes it possible for you to create a custom method and specify attributes for that method.

This dialog box appears when you choose New Method on the Form menu that appears when the Form Designer is open or the Class menu that appears when the Class Designer is open.

Name

Specifies the name of the new method.
Visibility (Class Designer only)

Specifies the level of visibility for the method:
  • Public Access is available from anywhere in an application.

  • Protected Restricts access to the method to class members and subclasses can access protected properties. Object instances cannot access protected methods.

  • Hidden Restricts access to the method to class members only. Object instances and subclasses cannot access hidden methods.

For more information, see Protecting and Hiding Class Members.
Description

Contains the method description to be displayed at the bottom of the Properties Window in the Class Designer and, if the property is not protected, in the Form Designer.

See Also

Other Resources

How to: Add Properties and Methods to a Form
How to: Add Methods to Classes
Class Designer
Form Designer
New Property Dialog Box
Edit Property/Method Dialog Box
Dialog Boxes


New Property Dialog Box

Visual FoxPro 9.0
New Property Dialog Box
See Also

Makes it possible for you to create a custom property and specify attributes for that property.

This dialog box appears when you choose New Property on the Form menu that appears when the Form Designer is open or the Class menu that appears when the Class Designer is open.

You can also create Access and Assign methods. For more information, see Access and Assign Methods and How to: Create Access and Assign Methods.

Name

Specifies the name of the new property.
Visibility (Class Designer only)

Specifies the level of visibility for the property:
  • Public Access is available from anywhere in an application.

  • Protected Restricts access to the property to class members and subclasses can access protected properties. Object instances cannot access this property.

  • Hidden Restricts access to the property to class members only. Object instances and subclasses cannot access hidden properties.

For more information, see Protecting and Hiding Class Members.
Access Method

Specifies if an Access method is created for the new property. The code in an Access method is executed whenever the property is queried. Select this check box to create an Access method for a property.
Assign Method

Specifies if an Assign method is created for the new property. The code in an Assign method is executed whenever you attempt to change the value of the property. Select this check box to create an Assign method for a property.
Default Value

Specifies a default value for the property. The default value is preset to False (.F.).
Description

Contains the method description to be displayed at the bottom of the Properties window in the Class Designer and, if the property is not protected, in the Form Designer.

See Also

Other Resources

How to: Add Properties and Methods to a Form
How to: Add Properties to Classes
Class Designer
Form Designer
New Method Dialog Box
Edit Property/Method Dialog Box
Dialog Boxes


New Remote View Dialog Box

Visual FoxPro 9.0
New Remote View Dialog Box
See Also

This dialog box lets you create a new remote view using the View Designer or the Remote View Wizard.

Note:
Before you can create a new remote view, you must establish a connection or ODBC data source. To establish a connection, use the Connection Designer.

For more information, see Working with Views.

View Wizard

Opens the Remote View wizard, which creates a remote view.
New View

Opens the Select Connection Or Data Source dialog box so you can select a remote data source to use in your remote view. For more information, see Select Connection or Data Source Dialog Box.

See Also

Other Resources

Dialog Boxes
Connection Designer
Database Designer
Options Dialog Box
Remote View Wizard
View Designer


New Table Dialog Box

Visual FoxPro 9.0
New Table Dialog Box
See Also

Makes it possible for you to create a new table using the Table Designer or Table Wizard.

Note:
For projects, the NewTable dialog box displays the Table Wizard button only when the Prompt for Wizards check box on the Projects tab in the Options dialog box is selected.

Table Wizard

Opens the Table Wizard, which uses your answers to a series of questions to create a table. For more information, see Table Wizard.
New Table

Opens the Table Designer so you can create an empty table. For more information, see Table Designer.

See Also

Other Resources

Creating Tables
Dialog Boxes


Open Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Open Dialog Box (Visual FoxPro)
See Also

Use to open an existing file or create a new file. This dialog box appears when you select Open from the File menu.

Previously opened projects appear at the bottom of the File menu. You can open a previously opened project by choosing its name from the bottom of the File menu.

Note:
Files created with the Open command are not added to a project.

The GETFILE( ) function corresponds to the Open Dialog Box. For example, this dialog box appears when you type ? GETFILE( ) in the Command window.

Shortcut

FoxPro OpenFolderButton screenshot

CTRL+O

Look in

Displays a drop-down list of locations where you can look for your file. On Windows 2000 and Windows XP operating systems, the Places bar on the left side of the dialog box displays common locations such as My Documents and Desktop. Click one of these icons to make the corresponding location appear in the drop-down list.
File name

Displays the name of the currently selected file or allows you to specify the file you want to open.
Class Library

Specifies the name of the class library. This box appears only when opening a class library or when using AGETCLASS( ) or MODIFY CLASS.
Files of type

Displays a list of file types. You can select a file type from the drop-down list to display only files of a particular type. The following extensions are no longer used in this version of Visual FoxPro: .lbl, .fpc, .cat, and .frm.
Class Name

Displays classes stored in the class library displayed in the Class Name box. This list appears only when opening a class library or when using AGETCLASS( ) or MODIFY CLASS.
Open as read-only

Specifies that the file you open can be viewed but not modified.
Environment

Saves all environment settings with the file and opens the associated environment when you open the file.
Note:
The Environment check box appears only in versions prior to Visual FoxPro 8.0.

This option is available when you choose Form, Label, or Report from the List Files of Type list and is checked by default. To open a form, label, or report without opening an associated environment, clear the check box.
Open exclusive

Specfies that you can use a table (.dbf) or database (.dbc) file exclusively so that no other user can open the file. This option is available only when opening a table. Corresponds to the USE command.
Code Page

Displays the Code Page dialog box so you can specify the code page needed to view the file correctly. This command applies only to text files such as program (.prg), query (.qpr), and text (.txt) files.
Preview

Specifies that you can preview graphic files when they are selected in the files list. This check box appears only when you can open or select a graphics file. For example, this check box appears in the Open dialog when you add an Image control to a form and double-click the Picture property in the Properties window.
Note:
The Preview check box appears only when running Visual FoxPro on operating systems earlier than Windows 2000. You can preview images in Windows 2000 and later by clicking the View Menu icon near the top of the dialog box and then Thumbnails.

See Also

Other Resources

Dialog Boxes
Open Picture Dialog Box
New Class Dialog Box
Code Page Dialog Box
GETFILE( ) Function
Open Picture Dialog Box
USE Command


Open Picture Dialog Box

Visual FoxPro 9.0
Open Picture Dialog Box
See Also

Use to open an existing graphic file.

The GETPICT( ) function corresponds to the Open Picture dialog box. For example, this dialog box appears when you type ? GETPICT( ) in the Command window.

Look in

Displays a drop-down list of locations where you can look for your file. On Windows 2000 and Windows XP operating systems, the Places bar on the left side of the dialog box displays common locations such as My Documents and Desktop. Click one of these icons to make the corresponding location appear in the drop-down list.
File name

Displays the name of the currently selected file or allows you to specify the file you want to open.
Files of type

Displays a list of file types. You can select a file type from the drop-down list to display files of a particular type. The following extensions are no longer used in this version of Visual FoxPro: .lbl, .fpc, .cat, and .frm.
Picture

Displays a preview of the selected graphic file when the Preview check box is selected.
Note:
Picture appears only when running Visual FoxPro on operating systems earlier than Windows 2000. Otherwise, the Open Picture dialog box shows a thumbnail (smaller) version of the graphic file. Double-click the thumbnail to view a larger version of the file.

Preview

Allows you to preview the selected graphic file.
Note:
The Preview check box appears only when running Visual FoxPro on operating systems earlier than Windows 2000. You can preview images in Windows 2000 and later by clicking the View Menu icon near the top of the dialog box and then Thumbnails.

See Also

Other Resources

Dialog Boxes
Open Dialog Box
Code Page Dialog Box
GETPICT( ) Function
Command Window
Graphics Support in Visual FoxPro
Report Picture Dialog Box


Optional Bands Dialog Box

Visual FoxPro 9.0
Optional Bands Dialog Box
See Also

Makes it possible for you to include a Title, Summary, or additional Detail bands in a report or label.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

  • How to: Add Bands to Reports

  • How to: Configure Output for Report Bands

  • How to: Delete Bands from Reports

Report Title

Makes it possible for you to include a Title band and specify page break options for the Title band.

Title band

Specifies whether the layout includes a Title band for displaying information once at the beginning of the report.
New page

Specifies that a page break will be sent to the printer after the Title band information has rendered. Available only when the Title band check box is selected.

Report Summary

Makes it possible for you to include a Summary band and specify options for the Summary band.

Summary band

Specifies whether the layout includes a Summary band for displaying information once at the end of the report.
New page

Specifies that a page break will be sent to the printer before the Summary band information is rendered. Available only when the Summary band check box is selected.
Page header

Specifies that the Page Header band information will be rendered on the separate page along with the Summary band information.
Page footer

Specifies that the Page Footer band information will be rendered on the separate page along with the Summary band information.

Details

Makes it possible for you to add Detail bands.

Details

Specifies the number of Detail bands to include in the report. The default is set to 1. A report layout must contain at least 1 detail band.
Note:
You can include a maximum of 20 Detail bands in a report.

See Also

Other Resources

Label Designer
Report Designer
Dialog Boxes


Options Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Options Dialog Box (Visual FoxPro)
See Also

Makes it possible for you to set different categories of options. The Options dialog box appears when you select Options from the Tools menu.

When you click Set As Default, Visual FoxPro saves all the options on all tabs.

The following table describes tabs that appear in the Options dialog box.

Tab | Options available
Controls Tab, Options Dialog Box | Set options for the visual class libraries and ActiveX controls to make available from the View Classes button on the Form Controls toolbar.
Data Tab, Options Dialog Box | Set table options, such as whether to use Rushmore Query Optimization, enforce unique records in indexes, and specify the collating sequence, memo block size, record counter interval for searches, and locking/buffering options to use.
Debug Tab, Options Dialog Box | Set debugger display and trace options, such as windows, font, and colors.
Editor Tab, Options Dialog Box | Set font and color options for identifying program elements, such as comments and keywords in the Command window and in all editing windows, except those opened with the MODIFY FILE or MODIFY MEMO commands.
Field Mapping Tab, Options Dialog Box | Set options for the controls to create when dragging tables or fields to a form from the Data Environment Designer, Database Designer, or Project Manager Window.
File Locations Tab, Options Dialog Box | Set locations for the default Visual FoxPro directory, where Help is stored, and where auxiliary files are stored.
Forms Tab, Options Dialog Box | Set Form Designer options, such as the grid spacing, the scale units to use, the maximum design area, and what template classes to use.
General Tab, Options Dialog Box | Set data entry and programming options, such as specifying the warning sound, whether to log compilation errors, whether to automatically fill new records, what navigation keys to use, what color palette to use, and whether to warn before overwriting files.
IDE Tab, Options Dialog Box | Set formatting, appearance, and behavior settings for Visual FoxPro file types.
Projects Tab, Options Dialog Box | Set Project Manager options, such as whether to prompt for wizards, whether to run or modify files on double-click, and options for source control. For more information, see Project Manager Window.
Regional Tab, Options Dialog Box | Set formats for dates, times, currency, and numbers.
Remote Data Tab, Options Dialog Box | Set remote data access options, such as connection timeout values, the number of records to fetch at once, and how to use SQL for updates.
Reports Tab, Options Dialog Box | Configure settings for the Report Designer when creating reports.
View Tab, Options Dialog Box | Set interface options, such as whether to display a status bar, clock, command results, system messages, or a recently used project list.

See Also

Other Resources

Dialog Boxes
How to: View and Change Environment Settings
Visual FoxPro Environment Settings


Controls Tab, Options Dialog Box

Visual FoxPro 9.0
Controls Tab, Options Dialog Box
See Also

Contains options to register visual class libraries for specifying template classes on the Forms Tab, Options Dialog Box. These options also specify what can be selected from the View Classes button on the Form Controls Toolbar to make adding custom controls to forms easy.

When you choose Set As Default — which appears on every tab in the dialog box — Visual FoxPro saves the option settings in the registry (system Windows registration database).

Visual class libraries

Specifies that class libraries (.vcx files) are displayed in the Selected list.
ActiveX controls

Specifies that ActiveX controls are displayed in the Selected list.
Selected

Lists files that you can add or remove to your Visual FoxPro environment. If you have chosen Visual class libraries, the list displays the .vcx files that you have already added, and specifies which libraries appear on the shortcut menu when you click the View Classes button on the Form Controls Toolbar. If you have chosen ActiveX controls, the list displays the classes of objects and controls available on your system. ActiveX objects and controls that you have already added are checked, and appear on the shortcut menu when you click the View Classes button on the Form Controls toolbar.
Label

Appears when the Visual class libraries option is selected. Specifies the name for the class library. By default, Visual FoxPro uses the file name without the .vcx extension.
Library

Appears when the Visual class libraries option is selected. Displays the path and file name for of the .vcx files for the currently selected class library.
Show

Appears when the ActiveX is selected. Makes it possible for you to specify what types of ActiveX objects appear in the Selected list.
  • Insertable Objects Specifies that the Selected list displays classes of objects that you can insert as ActiveX objects into Visual FoxPro applications.

  • Controls Specifies that the Selected list displays ActiveX controls.

Add

Choose this button to display the Open Dialog Box so you can add libraries (.vcx files) or ActiveX controls to the Selected list. Adding an ActiveX control also registers it so it will be available in the list of controls in the Insert Object Dialog Box and in other applications.
Remove

Appears when the Visual class libraries option is selected. Choose this button to remove the selected library from the Selected box.

See Also

Other Resources

Forms Tab, Options Dialog Box
Insert Object Dialog Box
Open Dialog Box
Options Dialog Box


Data Tab, Options Dialog Box

Visual FoxPro 9.0
Data Tab, Options Dialog Box
See Also

Contains options for controlling data in tables.

When you choose Set As Default, which appears on every tab in the dialog box, Visual FoxPro saves all options on all tabs.

Open exclusive

Specifies whether Visual FoxPro opens tables and databases exclusively, so that no one else can view or modify them while you are working on them. Opening files exclusively can result in better performance. Use this option when processing large numbers of records under circumstances when other users do not need access to data (such as at night). This option corresponds to the SET EXCLUSIVE Command.
Show field names

Specifies whether Visual FoxPro displays a field name as a column heading above each field in the output of the AVERAGE Command, CALCULATE Command, DISPLAY Command, LIST Commands, and SUM Command. This option corresponds to the SET HEADINGS Command.
Prompt for code page

Specifies whether Visual FoxPro prompts you to attach a code page when you open tables that do not already have one attached. This option corresponds to the SET CPDIALOG Command.
Ignore deleted records

Specifies whether Visual FoxPro ignores records marked for deletion when executing commands that use a scope clause. If this option is cleared, Visual FoxPro includes the marked records. This option corresponds to the SET DELETED Command.
Rushmore Query Optimization

Specifies whether Visual FoxPro uses Rushmore optimization when executing commands that include a FOR clause. This option corresponds to the SET OPTIMIZE Command. For more information, see Optimizing Applications.
Unique records in indexes

Specifies whether Visual FoxPro allows records with duplicate index key values in an index file. If you choose this option, only the first record containing the original key index is indexed. This option corresponds to the SET UNIQUE Command.
Collating sequence

Specifies a collation sequence (sort order) for character fields in indexing and sorting operations. This option corresponds to the SET COLLATE Command.
Record counter interval

Specifies how many records should be processed during commands such as COPY TO before Visual FoxPro updates the record counter display in the status line. The range is from 1 to 32,767 records. The higher the number you specify, the longer the delay between updates, but the command can run faster. You must choose the Status Bar option on the View tab for this option to have effect. This option corresponds to the SET ODOMETER Command.
Memo block size (bytes)

Specifies the block size in which disk space for memo fields is allocated. The value you enter specifies the minimum disk space required for a memo field, and the size by which memo fields increase as data is added to them. If you specify a value between 1 and 32, Visual FoxPro multiplies your value by 512, and then allocates disk space in a block of that size. If you specify a value greater than 32, Visual FoxPro allocates blocks of only that size; specifying a number greater than 32 can therefore save disk space. This option corresponds to the SET BLOCKSIZE Command.
Browse refresh interval (sec)

Specifies how often Visual FoxPro updates the display of records in an active Browse window, which is useful in a multiuser environment. Possible values are 0 to 3600. Set this value to 0 to prevent updates. Set this value to a high number to update the Browse window less often, which can increase performance. This option corresponds to the SET REFRESH Command.
Table refresh interval (sec)

Specifies how often Visual FoxPro should refresh local memory buffers with current data from the network, which is useful in a multiple-user environment. Possible values are -1, which specifies to always read data from disk, and 0 to 3600. Fractional values to a minimum of .001 are accepted. To prevent refreshes, set this value to 0. To refresh local memory buffers less often and increase performance, set this value to a high number. This option corresponds to the second parameter of the SET REFRESH command. For more information, see SET REFRESH Command.

String comparisons

SET NEAR on

Specifies that Visual FoxPro positions the record pointer on the closest matching record after an unsuccessful FIND or SEEK command. This option corresponds to the SET NEAR Command.
SET EXACT on

Specifies that Visual FoxPro uses the full length of both string expressions (except for trailing blanks) when using the comparison operator (=). If you clear this option, Visual FoxPro stops comparing two strings when the end of the expression on the right side of the comparison operator (=) is reached. This option corresponds to the SET EXACT Command.
Note:
This setting has no effect on the results of the = operator.

SET ANSI on

Specifies whether Visual FoxPro pads strings when comparing them with the SQL = operator, which compares character by character until the shorter string is finished. If you choose this option, Visual FoxPro pads the shorter string with spaces, so a SQL comparison fails ("Tommy" is not equivalent to "Tom "). If you clear this option, the shorter string is not padded, so strings of unequal length can be equivalent ("Tommy" is equivalent to "Tom"). This option corresponds to the SET ANSI Command.

Locking and buffering

Automatic file locking

Specifies that Visual FoxPro automatically locks files for certain commands that do not change data including AVERAGE, COPY TO, INDEX, REPORT, SORT, and TOTAL. If you clear this option, the file is not locked during these commands, and other users can change records while your command is being executed. This option corresponds to the SET LOCK Command.
Multiple record locks

Specifies whether Visual FoxPro locks multiple records concurrently. If you clear this option, Visual FoxPro clears all current locks and makes it possible for you to lock only one record at a time; the current record is unlocked when you lock the next one. This option corresponds to the SET MULTILOCKS Command.
Buffering

Specifies for multiuser environments whether to buffer record changes locally, and if so, whether to do so optimistically or pessimistically. Buffering can improve performance and provide greater concurrency control. You must choose the Multiple Record Locks option for this option to have effect. It corresponds to the CURSORSETPROP( ) Function. Options are:
  • Off Changes are not buffered, and record updates are made immediately to disk. This mode is recommended only when working in a single-user environment.

  • Record (Pessimistic) The current record is locked when the user makes a change to it, and changes are buffered. Other users can read but not change the record on disk. When the record pointer moves to another record, the current record is written back automatically from the buffer to the source table, and then unlocked. Pessimistic record locking is useful for interactive editing in a table subject to many updates by other users.

  • Record (Optimistic) Changes for a single record are buffered but not locked when the user moves the record pointer to the record. Other users can read and change the record on disk. When the user moves the record pointer to another record, Visual FoxPro checks changes in the current record against the record on disk. If the record on disk has been changed, Visual FoxPro offers options to discard current changes or overwrite the record on disk. Optimistic record buffering is recommended primarily when updating tables in which there is little activity.

  • Table (Pessimistic) Record changes are buffered and locked when the user moves the record pointer to them, and remain so until TABLEUPDATE( ) Function is called. Pessimistic table buffering is the safest mode for updating multiple records in a table, but because it locks every changed record, it can limit other users' access to the data. It is therefore recommended only to help speed data entry when users will be entering new records in batches, or when it is essential for the application that all currently used records be held exclusively by the application.

    Note:
    When using table buffering, you must issue TABLEUPDATE() to write buffered record changes to the disk. If you don't, the changed records are discarded when the user quits Visual FoxPro.

  • Table (Optimistic) Record changes are buffered, but not locked, when the user moves the record pointer to the record. Other users can read and change the records on disk. When TABLEUPDATE( ) is issued, Visual FoxPro checks for changes in each record as the record is written to disk; records that have changed are not written. Optimistic table buffering is useful for optimizing update performance in tables in which there is little activity. When using this option, issue TABLEUPDATE( ) often so that the chances of buffered records changing on disk is minimized.

    Note:
    When using table buffering, you must issue TABLEUPDATE() to write buffered record changes to the disk. If you don't, the changed records are discarded when the user quits Visual FoxPro.

Reprocessing

Specifies how many times or for how long Visual FoxPro attempts to lock a record or table that is already locked by another user. This option corresponds to the SET REPROCESS Command. Choices are:
  • Attempt Lock (Default). Attempts to lock one time only.

  • Attempt Lock (Automatic). Continues to attempt the lock until successful or until the user cancels the attempt by pressing ESC. Equivalent to SET REPROCESS TO AUTO.

  • Wait for Lock. Continues to attempt a lock until the record becomes available. This option does not provide a way for the user to stop trying to lock the record. Equivalent to SET REPROCESS TO -1.

  • Retry Attempts. Attempts to lock the record or table the specified number of times. If the lock is still unsuccessful, an error message is displayed. SET REPROCESS TO n, where n is the number of retry attempts.

  • Retry Seconds. Attempts to lock the record or table for the specified number of seconds. If the lock is still unsuccessful, an error message is displayed. SET REPROCESS TO n SECONDS, where n is the number of seconds to retry.

See Also

Other Resources

Options Dialog Box


Debug Tab, Options Dialog Box

Visual FoxPro 9.0
Debug Tab, Options Dialog Box
See Also

Makes it possible for you to set options to customize the Visual FoxPro debugger windows, including:

  • Font and colors.

  • Whether to trace Timer event code.

  • Whether line numbers are displayed.

  • Whether to log Debug Output window output to a file.

When you choose Set As Default — which appears on every tab in the dialog box — Visual FoxPro saves the option settings in the registry (system Windows registration database).

Environment

Specifies the debugging environment.
  • Debug frame All debugger windows appear in one big frame that is external to the Visual FoxPro main window, with their own menus and toolbars. This makes the debugger less intrusive on your application's run-time environment. If you choose this option, you can open the debugger by choosing Debugger on the Tools Menu.

  • FoxPro frame Debugger windows appear in the Visual FoxPro main window. The FoxPro environment is most useful if you want just a single window open, for example the Watch window. If you choose this option, Visual FoxPro replaces the Debugger command on the Tools Menu with commands to open individual debug windows, and toolbars for individual debug windows are tiled to the main Visual FoxPro window.

    Note:
    You cannot change this option if the full debugger or any debugger window is open, or if the debug toolbar is open in the Visual FoxPro desktop.

Display timer events

Choose this option if you want Timer Control timer events displayed in the Trace Window when their interval value is reached. If you clear this option, the timer event still occurs, but is not displayed; it is treated as if you had specified Step Over for that event. With this check box cleared, Visual FoxPro filters timer events even when you are stepping through a timer event currently. This is by design. Visual FoxPro steps inside a timer event in the following situations:
  • SET STEP is ON.

  • A breakpoint is set on a line of code.

  • A breakpoint is set on a value that is changed.

  • A new method or procedure is called.

Specify Window

Choose an option to specify which debugger window you want to set options for. The window you choose here affects the following available options.

Call Stack

Displays the following options for the window:
  • Show call stack order Displays a number beside each program listed in the Call Stack Window window, with the highest number indicating the currently executing program.

  • Show current line indicator Indicates whether the current line indicator is displayed in the Call Stack window.

  • Show Call Stack indicator Indicates whether an arrow is displayed in the Call Stack window to indicate the procedure displayed in the Trace Window window. If the current line and call stack procedures are the same, Visual FoxPro displays only the current line indicator.

Locals

No additional options are available for this window.
Output

Displays the Log debug output area, which contains the following options:
  • Log Debug Output Copies the values written in the Debug Output Window to a text file. If you choose to log output values, you need to specify a file to log them to. The default file extension for a log file is .log. Visual FoxPro will log output to a file only if the Output window is displayed. You can display information in the Output window (and send it to the log file) using the DEBUGOUT Command or SET PRINTER Command in a program.

    When you quit Visual FoxPro, this option is cleared, so that you do not inadvertently overwrite a log file the next time you start Visual FoxPro.

  • Append Specifies that the debug output is written after the current contents of an existing file, preserving the original contents.

  • Overwrite Specifies that the debug output replaces the contents of the specified file.

Trace

Displays the following options for the window:
  • Show line numbers Displays line numbers to the left of the lines of code in the Trace Window.

  • Trace between breakpoints Executes code between breakpoints at the throttle speed. The throttle speed indicates the pause in seconds between the execution of each line of code. If you clear this option, code between breakpoints is executed at normal speed, the default setting of _THROTTLE System Variable, which is 0. Equivalent to using the SET TRBETWEEN command.

  • Pause between line execution Sets the throttle, which is the delay in seconds between the execution of each line of code. This option makes it possible for you to slow program execution so you can watch the lines of code without having to step through each line individually. Trace between breakpoints must be on for this setting to have any effect. Equivalent to setting the _THROTTLE system memory variable.

Wa tch

No additional options are available for this window.
Font

Choose a font and style for the specified debugger window. For example, to set the font of the debugger's Trace window, choose Trace under Specify Window, and then choose Font to select the font, size, and style.

Colors

Area

Select the text element for which you want to specify a color. For example, to specify a color for the text used for changed values, select ChangedValue. The choices in the Area list depend on what window has been specified under Specify Window.
Foreground

Choose a color for the text of the selected area. To use the default color established in the Windows control panel, select Automatic.
Background

Choose a background color for the selected area. For example, to show comments in yellow text on a blue background, select yellow in Foreground and blue in Background. To use the default color established in the Windows control panel, select Automatic.

For more information, see Testing and Debugging Applications.

See Also

Other Resources

Call Stack Window
Debug Output Window
Debugger Window
Trace Window
Watch Window
Options Dialog Box


Editor Tab, Options Dialog Box

Visual FoxPro 9.0
Editor Tab, Options Dialog Box
See Also

Provides options for customizing editing functionality in the Command window and most Visual FoxPro editors. For example, these options do not apply to editing windows opened with the MODIFY FILE command and MODIFY MEMO command except where noted.

When you choose Set As Default, which appears on every tab in the dialog box, Visual FoxPro saves the settings in the Windows registry.

Editor options

Provides options for specifying functionality for editing windows.

Selection margin

Specifies whether editors display a selection margin so you can select a line and specify breakpoints, bookmarks, or task list shortcuts. For more information, see How to: Create Bookmarks and Task List Shortcuts.
Drag drop between words

Specifies whether drag operations permit dragging into words or only between words.
Enable hyperlinks

Specifies whether editors recognize lines beginning with "http:/" as hyperlinks.
Comment string

Specifies the character that identifies a comment in code. The default comment string is *!*.
Background Compile

Specifies a formatting style used to indicate invalid syntax when syntax coloring is turned on. When the current line of code that you are typing contains invalid syntax, Visual FoxPro displays the line of code with one of the following formatting styles:
  • Red Inversion Invalid syntax appears red in color while valid keywords appear pink in color. (Default)

  • Gray Line containing invalid syntax appears gray in color.

  • Underline Line containing invalid syntax appears underlined.

  • None Invalid syntax is not indicated.

The Background Compile setting is supported for editing windows opened with the MODIFY MEMO command. For more information, see How to: Display and Print Source Code in Color.
Highlight duration

Specifies the number of milliseconds to highlight statements in parenthetical or bracket delimiters. You can select one of the settings from the list or type any specific duration into the box manually.

Syntax color settings

Provides options for syntax coloring.

Area

Specifies the program element to set font and color styles for. When you make your selection, the other options are updated with values appropriate for the selected area.
Font style

Specifies a font style for the selected area. For example, to display all comments in programs in italic, select Comments in the Area box, then select Italic in the Font style box.
Foreground

Specifies a color for the text of the selected area. To use the default color set in the Control Panel, select Automatic.
Background

Specifies a background color for the selected area. For example, to show comments in yellow text on a blue background, choose Comments in the Area box, select yellow in Foreground, and then select blue in Background. To use the default color set in the Control Panel, select Automatic.
Sample area

Displays the effect of your settings.
Reset All

Sets syntax coloring to the Visual FoxPro default settings.

See Also

Other Resources

How to: Display and Print Source Code in Color
Edit Properties Dialog Box
MODIFY FILE Command
MODIFY MEMO Command
Options Dialog Box


Field Mapping Tab, Options Dialog Box

Visual FoxPro 9.0
Field Mapping Tab, Options Dialog Box
See Also

Makes it possible for you to specify what type of control Visual FoxPro creates when you drag a table or field to a form from the Data Environment Designer, Database Designer, or Project Manager Window. For example, you can specify that Visual FoxPro create an edit box when you drag a Character field onto a form.

When you choose Set As Default — which appears on every tab in the dialog box — Visual FoxPro saves the option settings in the registry (system Windows registration database). Note that in this tab, choosing OK also saves the option settings in the registry.

Map fields to classes for drag-and-drop operations

Displays the current mappings between field types and classes (controls). The list includes:
  • Type All supported data types for database fields. The field type Multiple is used to specify the class that will be created if you drag an entire table or multiple fields onto a control at once. The field type Label is used to specify the class that will be created for the field captions.

  • Class Library The library containing the class definition to map to a field type. If this column is blank, the field type is mapped to a Visual FoxPro base class.

  • Class Name The class to which a field type is mapped, which specifies the type of control that will be created.

Modify

Choose this button to display the Modify Field Mapping Dialog Box, where you can specify a different mapping for the selected field type.
To modify field mappings

  1. In the Field Mapping tab of the Options dialog box, choose Modify.

  2. In the Modify Field Mappingdialog box, select a field type from the Type list.

  3. To set the class that is created whenever you drag a table or multiple fields, select Multiple.

  4. To select the class library (.vcx file) that contains the control you want to associate with the selected field type, choose Browse.

  5. Select a class name from the Name list. The class you specify here will be created any time a field of the selected type is dragged onto a form.

  6. Choose OK or Apply to accept the mapping.

Database options

Drag-and-drop field caption

Choose this option if you want Visual FoxPro to use the name of the field as the caption of the class being created. If you clear this option, Visual FoxPro will not create field captions.
Copy field comment

Choose this option to have Visual FoxPro copy the comment from a field (if any) to the Comment property of the new class when creating it.
Copy field input mask

Choose this option to have Visual FoxPro copy the input mask of a field (if any) to the InputMask property of the new class when creating it.
Copy field format

Choose this option to have Visual FoxPro copy the format specification from a field (if any) to the Format property of the new class when creating it.

See Also

Other Resources

Modify Field Mapping Dialog Box
Options Dialog Box
Data Environment Designer
Database Designer
Project Manager Window
How to: Add Visual FoxPro Controls to a Form
How to: Add Controls to a Form with the Component Gallery


Modify Field Mapping Dialog Box

Visual FoxPro 9.0
Modify Field Mapping Dialog Box
See Also

Use this dialog box to change the mapping between a database field type and the type of class (control) that Visual FoxPro creates when you drag a table or field onto a form from the Data Environment Designer, Database Designer, or Project Manager Window.

This dialog box appears when you choose Modify in the Field Mapping Tab, Options Dialog Box.

Type

Select the database field type for which you want to change the mapping. By default, the field type is selected that was selected in the Field Type Mapping tab.

Class information

Library

Enter a class library that contains the class that you want to have Visual FoxPro create when a field of the specified type is dragged onto a form. If this box is blank, the field type is mapped to a Visual FoxPro base class.
Browse

Choose this to display the Open Dialog Box, from which you can select a class library.
Name

Select the name of a class to map to the specified field type. The list contains only the classes in the library you chose; to display the Visual FoxPro base classes in this box, clear the Library box. The base class and description of the selected class, if available, is displayed below the class name.
Apply

Choose this to create the mapping. Choose Apply if you want to change a mapping but keep the Field Type Mapping dialog box open to change another mapping. To change a single mapping, choose OK.

See Also

Other Resources

Field Mapping Tab, Options Dialog Box
Options Dialog Box
Data Environment Designer
Database Designer
Project Manager Window
How to: Add Visual FoxPro Controls to a Form


File Locations Tab, Options Dialog Box

Visual FoxPro 9.0
File Locations Tab, Options Dialog Box
See Also

Contains and specifies directory locations for programs and files used by Visual FoxPro. For information about changing and saving settings, see How to: View and Change Environment Settings.

File Type list

Beautify

Specifies the file name of the application that is called when you choose Beautify on the Tools menu and is set to Beautify.app by default. When you open a program or text file in an editing window, the Beautify command appears on the Tools menu. This option corresponds to the _BEAUTIFY System Variable.
Builders

Specifies the file name of the application that is called when you choose Builder on the shortcut menu when working in the Form Designer. A builder consists of one or more dialog boxes that help you set properties for a specific control or combine clauses to create a specific expression. This option corresponds to the _BUILDER System Variable. Builders can be displayed automatically if you choose the Builder lock option in the Forms Tab, Options Dialog Box.
Class Browser

Specifies the file name of the application that is called when you choose Class Browser on the Tools menu and is set to Browser.app by default. This file corresponds to the _BROWSER System Variable.
Code References

Specifies the name of the application that is called when you choose Code References on the Tools menu, or when you select the Look Up Reference or View Definition command on the shortcut menu in the editing window of a program. This file corresponds to the _FOXREF System Variable and is set to FoxRef.app by default.
Component Gallery

Specifies the file name of the application that is called when you choose Component Gallery on the Tools menu and is set to Gallery.app by default. This option corresponds to the _GALLERY System Variable.
Converter

Specifies the file name of the application that is called when you open a form, report, or other application component created in an earlier version of FoxPro or Visual FoxPro. The specified application converts the component to the current file format. This option corresponds to the _CONVERTER System Variable.
Coverage Profiler

Specifies the file name of the application that is called when you choose Coverage Profiler on the Tools menu and is set to Coverage.app, which creates the Debugger coverage and profiler output, by default. This option corresponds to the _COVERAGE System Variable.
CrossTab Generator

Specifies the name and location of the program that creates cross tabs.
Default Directory

Specifies the default Visual FoxPro directory. This option corresponds to the SET DEFAULT Command.
Default Include File

Specifies a default header file of predefined compile-time constants included automatically with user-defined classes, forms, or form sets. This option is empty by default and corresponds to the _INCLUDE System Variable.
Expression Builder

Specifies the file name of the application that is called when you issue the GETEXPR command or open the Expression Builder dialog box from within Visual FoxPro. This option is empty by default and corresponds to the _GETEXPR System Variable. For more information, see Expression Builder Dialog Box.
FoxCode

Specifies the name and location of the table that provides IntelliSense functionality and is set to FoxCode.dbf by default. This option corresponds to the _FOXCODE System Variable.
FoxTask

Specifies the name and location of the table that contains task list records and is set to FoxTask.dbf by default. This option corresponds to the _FoxTask System Variable.
HTML Generator

Specifies the file name of the application that is called when you choose Save As HTML on the File menu and is set to Genhtml.prg by default. This option corresponds to the _GENHTML System Variable.
Help File

Specifies the name and location of the default Help file that opens when you choose Microsoft Visual FoxPro Help on the Help menu or press F1 and is set to dv_FoxHelp.chm by default. This option corresponds to the SET HELP Command.
Note:
If the file name extension is .hlp, then graphical Help is used. If the file name extension is .dbf, then .dbf-style Help is used. If no extension is specified, the default is graphical Help.

IntelliSense Manager

Specifies the name and location of the program that is called when you choose IntelliSense Manager on the Tools menu and is set to FoxCode.app, which provides Visual FoxPro IntelliSense, by default. This option corresponds to the _CODESENSE System Variable.
Menu Builder

Specifies the file name of the menu builder program and is set to GenMenu.prg by default. This option corresponds to the _GENMENU System Variable.
Menu Designer

Specifies an external menu design application. This option corresponds to the _MENUDESIGNER System Variable.
Object Browser

Specifies the name and location of the program that is called when you choose Object Browser on the Tools menu and is set to ObjectBrowser.app by default. This option corresponds to _ObjectBrowser System Variable.
Report Builder

Specifies the file name of the program invoked in response to builder events in the Report and Label Designers. This option corresponds to _REPORTBUILDER System Variable.
Report Output

Specifies the file name of the program invoked by the report engine in object-assisted mode to obtain a Reportlistener reference when none has been specified. This option corresponds to _REPORTOUTPUT System Variable.
Report Preview

Specifies the file name of the program invoked by Reportlistener objects to obtain a preview container reference when none has been specified. This option corresponds to _REPORTPREVIEW System Variable.
Resource File

Specifies whether Visual FoxPro stores its current state, such as macros, size and location of windows, and so on, into a resource file, and if so, what file to use. This option is set to FoxUser.dbf by default.
Note:
If this setting is not specified, Visual FoxPro resets the system state to its default each time you start the program. In addition, some options in the Options dialog box will be unavailable.

This option corresponds to the SET RESOURCE Command.
Samples Directory

Specifies the directory containing the Visual FoxPro sample files. This option corresponds to the _SAMPLES System Variable.
Search Path

Specifies the directories that Visual FoxPro searches for files that it does not find in the default directory and is empty by default. The directories specified must be separated by commas or semicolons. This option corresponds to the SET PATH Command.
Tip:
To browse for and select multiple directories, in the Change File Location dialog box, click the ellipsis (...) button. Semicolons are automatically inserted when browsing for and selecting multiple directories.

Startup Program

Specifies the file name of the application that is called when you start Visual FoxPro and is set to empty by default. This option corresponds to the _STARTUP System Variable.
Task List

Specifies the name and location of the program that is called when you choose Task List on the Tools menu and is set to TaskList.app, which manages the task list, by default. This option corresponds to the _TASKLIST System Variable.
Task Pane

Specifies the name and location of the program that is called when you choose Task Pane on the Tools menu and is set to TaskPane.app, which displays areas that contain information and expose essential tasks for easy use, by default. This option corresponds to _TASKPANE System Variable.
Temporary Files

Specifies the directory in which Visual FoxPro saves temporary files, for example, when sorting or indexing. Because temporary files can grow quite large, specify a directory with plenty of free space. For best performance, specify a fast drive, for example, in a multiuser environment, you might specify a local drive.
Toolbox

Specifies the name and location of the program that is called when you choose Toolbox on the Tools menu and is set to Toolbox.app, which displays items and toolsets for creating applications, by default. This option corresponds to the _TOOLBOX System Variable.
Wizards

Specifies the file name of the application that is called when you run or choose a wizard from the Tools menu. This option corresponds to the _WIZARD System Variable.

See Also

Other Resources

Options Dialog Box
Visual FoxPro Configuration
Customizing the Visual FoxPro Environment


Forms Tab, Options Dialog Box

Visual FoxPro 9.0
Forms Tab, Options Dialog Box
See Also

Contains options for the Form Designer.

When you choose Set As Default, which appears on every tab in the dialog box, Visual FoxPro saves the option settings in the registry (system Windows registration database).

Note:
If an instance of the Form Designer is already open when you change settings in the Forms tab of the Options dialog box, the Form Designer does not reflect the changes until you close that instance and reopen it.

Grid

Grid lines

Specifies that the Form Designer displays grid lines to help you align controls.
Note:
These are defaults for new forms only. Settings for existing forms are saved in the resource file.

Snap to grid

Specifies that when you draw new controls, their edges align with the nearest grid lines.
Note:
These are defaults for new forms only. Settings for existing forms are saved in the resource file.

Horizontal spacing (pixels)

Specifies the width of the space between horizontal grid lines. The width is based on the Scale units option on the Forms tab.
Note:
These are defaults for new forms only. Settings for existing forms are saved in the resource file.

Vertical spacing (pixels)

Specifies the height of the space between vertical grid lines. The height is based on the Scale Units option on the Forms tab.
Note:
These are defaults for new forms only. Settings for existing forms are saved in the resource file.

Show position

Specifies whether object position and dimensions are displayed on the status bar.
Tab ordering

Specifies how to set tab order in a form. To order controls by clicking on them, choose Interactive. To order controls using the Tab Order Dialog Box, choose By List.
Note:
Specifies how the Set Tab Order button on the Form Designer toolbar sets the order.

Scale units

Specifies Pixels or Foxels, which sets the default scale mode for the Form Designer and Class Designer.
Maximum design area

Specifies the maximum size of the form at design time. The default setting is None, which prevents the form from appearing cropped inside the Form Designer. You cannot size a form that is bigger than the specified resolution. It is a good idea to specify the smallest resolution your users will want so that all users can see your forms.

Template classes

Specifies a class library and class to base your new forms and form sets on. The default is that Visual FoxPro uses its base class.

Form set

Displays the Form Set Template dialog box, where you select a form set template.
Form

Displays the Form Template dialog box, where you select a form template.
Builder lock

Specifies that builders are displayed automatically in the Form Designer when you create a control that has a builder registered to it.
Prompt to save changes before running form

Specifies that when you run a form from the Form Designer, you are prompted to save changes to the form made since the last time you saved it. If you clear this option, the Form Designer saves changes automatically before running the form.

See Also

Other Resources

Form Designer
Options Dialog Box
Tab Order Dialog Box
Form Set Template Dialog Box
Form Template Dialog Box


Form Set Template Dialog Box

Visual FoxPro 9.0
Form Set Template Dialog Box
See Also

Specifies a form set template to use for form sets.

Class

Specifies the file name of the form set template.
Class name

Lists classes in the currently selected class library.

See Also

Other Resources

Forms Tab, Options Dialog Box
Options Dialog Box
Form Designer
Form Template Dialog Box


Form Template Dialog Box

Visual FoxPro 9.0
Form Template Dialog Box
See Also

Specifies a form template to use for forms.

Class

Specifies the file name of the form template.
Class name

Lists classes in the currently selected class library.

See Also

Other Resources

Forms Tab, Options Dialog Box
Options Dialog Box
Form Set Template Dialog Box
IDE Tab, Options Dialog Box


General Tab, Options Dialog Box

Visual FoxPro 9.0
General Tab, Options Dialog Box
See Also

Contains sound, programming, data entry, and other options in Visual FoxPro.

When you choose Set As Default — which appears on every tab in the dialog box — Visual FoxPro saves all the options on all tabs.

Warning Sound

Off

Turns the error sound off. Corresponds to the SET BELL Command.
Default

Sets the error sound to your system default. Corresponds to the SET BELL Command.
Play

Sets the error sound to a .wav file. Type the name of the file in the box, or click the dialog button to select an existing .wav file. Corresponds to the SET BELL Command.

Programming

Cancel programs on Escape

Specifies that you can cancel a running program by pressing the ESC key. Corresponds to the SET ESCAPE Command.
Log compilation errors

Specifies that Visual FoxPro logs compilation errors in a file with the same name as the project file, but with an .err extension. Corresponds to the SET LOGERRORS Command.
SET DEVELOPMENT

Specifies that Visual FoxPro recompiles a program before running it if the object code is older than the source code. Corresponds to the SET DEVELOPMENT Command.
dBASE compatibility

Specifies compatibility with FoxBASE+ and dBASE languages. Corresponds to the SET COMPATIBLE Command.
Use Visual FoxPro color palette

Specifies that Visual FoxPro applies the default color palette to all bitmaps and OLE objects, which prevents palette shift when several pictures are displayed at once. Corresponds to the SET PALETTE Command.
Confirm file replacement

Specifies that Visual FoxPro prompts you for verification when you are about to overwrite existing files with new ones. Corresponds to the SET SAFETY Command.
Browse IME control

Specifies that Visual FoxPro displays an Input Method Editor when you navigate to a text box in the Browse window. This setting has no effect if you are not working in a double-byte character sets (DBCS) environment. Corresponds to the SET BROWSEIME Command.

Data Entry

Navigation keys

Specifies whether to use Windows- or MS-DOS–compatible navigation keys for tasks such as moving between controls in forms. Corresponds to the SET KEYCOMP Command.
Fill new records with current values

Specifies that Visual FoxPro automatically copies values from the current record to a new record that you are inserting or appending. Corresponds to the SET CARRY Command.
Enter or tab to exit fields

Specifies that you want to exit text boxes only by pressing ENTER or TAB. Otherwise, you can exit text boxes by typing past the last character in the text box. Corresponds to the SET CONFIRM Command.

Year 2000 Compliance

Strict Date Level

Specifies if ambiguous date and DateTime constants generate errors. Corresponds to the SET STRICTDATE Command.

See Also

Other Resources

Options Dialog Box
IMEStatus( ) Function
Trace Window


IDE Tab, Options Dialog Box

Visual FoxPro 9.0
IDE Tab, Options Dialog Box
See Also

Contains options for Visual FoxPro editors.

Specify file/window

Makes it possible for you to specify which file types are affected by setting made in this tab.

Type:

Makes it possible for you to specify the editors or the types of files for which you are specifying default editing conditions.
Extensions:

Specifies the file extensions of the type of files selected.
Override individual settings

Makes it possible for you to temporarily override default FoxUser settings.

Indentation

Makes it possible for you to specify the size and behavior of spaces and tabs.

Tab size

Specifies the width, in characters, of a tab for the currently selected file type. The range is 1 to 50. The default value is 4.
Indent size

Specifies the width, in characters, of a paragraph indent for the currently selected file type. If this is different from the tab size, extra tabs and/or spaces are used to create the specified value. The range is 1 to 50. The default value is 4.
Insert spaces

Specifies that spaces be inserted by the tab key for the currently selected file type. The default value is 4.
Keep tabs

Specifies that tabs be inserted by the tab key for the currently selected file type (default).

Save options

Makes it possible for you to specify how files of the selected type are saved.

Make backup

For some file types, specifies whether a backup file is created whenever you save a file of that file type.
Save with line feeds

Specifies that the current file type be saved with return and linefeed characters CHR(13)+CHR(10).
Save with end-of-file marker

Specifies that the current file type be saved with CTRL+Z at the end of the file.
Compile before saving

Specifies that a compile be attempted before the current file type is saved.

Appearance and behavior

Makes it possible for you to specify how text appears in the selected file type.

Alignment:

Specifies whether the current file type is left-, center-, or right-formatted.
Font:

Specifies the font, style, size, and script of the current file type.
Use font script

Specifies that the current font script is used globally throughout Visual FoxPro. If this check box is not selected, Visual FoxPro uses the Windows default font script.
Drag-and-drop editing

Specifies whether subsequent files of the selected file type provide drag-and-drop behavior. To disable drag-and-drop, you must also select the override individual settings check box. These selections, once applied, work on all files of the selected file types subsequently opened.
Automatic indent

Makes it possible for you to specify that an indent is automatically retained in lines subsequent to an indented line.
Show line/column position

Makes it possible for you to display, in the main window status line, the line and column number of the cursor in Memo fields
Word wrap

For some file types, makes it possible for you to specify whether words wrap to the next line at the editor window boundary.
Syntax coloring

Makes it possible for you to specify whether syntax coloring is available for the selected file type. You can manage syntax color parameters in the Editor Tab, Options Dialog Box.
Embedded hyperlinks

Makes it possible for you to specify whether hyperlinks can be included in the selected file type. Unvisited, visited, and hover attributes are available if you have Internet Explorer installed.
Display white space

Makes it possible for you to specify whether space, tab, paragraph, and other non-character markers are displayed in editors for the selected file type.

Apply button

Saves pending settings for the currently selected file type.

Reset All button

Resets the Visual FoxPro defaults for the selected file type. To reset all type settings, you must use the Specify file/window list, then click Reset All for each file type in the list.

See Also

Other Resources

Editor Tab, Options Dialog Box
Options Dialog Box
Projects Tab, Options Dialog Box


Projects Tab, Options Dialog Box

Visual FoxPro 9.0
Projects Tab, Options Dialog Box
See Also

Contains options for the Project Manager.

When you choose Set As Default — which appears on every tab in the dialog box — Visual FoxPro saves the option settings in the registry (system Windows registration database).

Project double-click action

Specifies whether Visual FoxPro runs or modifies a file when you double-click it in the Project Manager.

Run Selected File

Visual FoxPro runs the selected file when you double-click it.
Modify Selected File

Visual FoxPro opens the appropriate designer or editor when you double-click a file.
Prompt for Wizards

Specifies that Visual FoxPro prompts you to use a wizard, if applicable, when you choose New File from the Project Menu or choose New in the Project Manager.
Display user-defined container icons

Specifies that Visual FoxPro displays user-defined container icons in the Project Manager.

Source control options

Options in this box make it possible for you to specify what source control application to use, and how the source control application works when you add, modify, or remove components of your project.

Active source control provider

Specifies the name of the source control application to use. The name you specify here will apply to new projects. When you create a project, the name of the source control application in effect at the time is stored with the project so that Visual FoxPro knows what source control application to use each time the project is opened. To disable source control, choose None.
Automatically add new projects to source control

Specifies that you are prompted to put a project under source control when you create it. If you clear this option, new projects are not automatically put under source control and you must add them manually.
Check out files upon modify

Specifies that files are automatically checked out to a user who modifies them from the Project Manager. If a file is already checked out, Visual FoxPro displays an error. If you clear this option, users who attempt to modify files, which are not checked out from the ProjectManager can view the files but cannot change them.
Note:
If users modify project files using commands in the Command window (such as MODIFY), they must check the files out first.

Add files to source control upon add

Specifies that files added to the project are automatically put under source control for that project. If you clear this option, files that you add become part of the project (the .pjx file), but are not put under source control. However, you can manually place project files under source control at any time.
Note:
Database (.dbc), table (.dbf), API library, and application (.app) files are not put under source control automatically when added to a project. However, you can put these files under source control manually.

Remove files from source control upon removal from project

Specifies that when you remove a file from a project, it is removed from source control as well. If you clear this option, when you remove a file from the project, the source control information for the file remains in the source control database. Doing so maintains archive information about this file, and if the file is not deleted from disk, makes it possible for you to access it using the source control system outside of Visual FoxPro.
Display dialog box for shortcut menu commands

Specifies that when you choose a source control command from the project shortcut menu, Visual FoxPro makes it possible for you to select more than one file on which to carry out the selected command. If you clear this option, the command applies only to the file selected in the project, but this can be overridden by pressing SHIFT+Right Mouse Click and choosing the command.
Text generation

Specifies the name of the application used to create a text representation of binary files (form, label, menu, report, or class library) each time the file is checked in. The resulting text file is checked in along with the table source file, and can be used to create a report of the differences between multiple versions of a file.
Project class

Displays the Project Reference dialog, making it possible for you to specify a default ProjectHook class as a template for new projects.

See Also

Other Resources

Project Manager Hooks
Controls Tab, Options Dialog Box
New File Dialog Box
Options Dialog Box
Project Manager Window


Regional Tab, Options Dialog Box

Visual FoxPro 9.0
Regional Tab, Options Dialog Box
See Also

Contains options for date, time, and numeric formatting. You can temporarily or persistently override system settings in Visual FoxPro. The option settings on this tab are reflected in time, date, and currency output.

When you choose Set As Default — which appears on every tab in the dialog box — Visual FoxPro saves the option settings in the registry (system Windows registration database).

Use System Settings

Specifies that all settings on this tab are read from the system (as established in the Control Panel). In this mode, most options are read-only. If you clear this option, you can specify settings that override system settings.

Date and time

Specifies how date and time data is displayed by default. An example of the current settings appears in the top-right box of the option group.

Date format

Specifies the order of the day, month, and year in a date. Choose Short to remove leading zeros from the date. Choose Long to display the date written out. Corresponds to the SET DATE Command.
Date Separator

Specifies the character that appears between portions of a date. Clear this option to use the default separator. Corresponds to the SET MARK TO Command.
Century

Specifies that the year is displayed with century information (for example, 1997). Clear this option to display the year as 2 digits (for example, 97). Corresponds to the SET CENTURY Command.
12-Hour

Specifies that hours are displayed in 12-hour format with "AM" or "PM."
24-Hour

Specifies that hours are displayed in 24-hour format.
Seconds

Specifies that seconds are included in the time display.

Currency and numbers

Specifies how currency data is displayed by default. An example of the current settings appears in the top-right box of the option group.

Currency Format

Specifies the location of the currency symbol. Corresponds to the SET CURRENCY Command.
Currency Symbol

Specifies the character or characters used for currency. Corresponds to the SET CURRENCY Command.
1000 Separator

Specifies the character inserted at every third digit left of the decimal separator. Corresponds to the SET SEPARATOR Command.
Decimal Separator

Specifies a character used to indicate the decimal. Corresponds to the SET POINT Command.
Decimal Digits

Specifies the number of digits to follow the decimal separator. Corresponds to the SET DECIMALS Command.
Week Starts on

Specifies which day the week starts on. Corresponds to the SET FDOW Command.
First Week of Year

Specifies where a yearly calendar begins. Corresponds to the SET FWEEK Command.

See Also

Other Resources

Options Dialog Box
SET DATE Command
SET MARK TO Command
SET CENTURY Command
SET CURRENCY Command
SET SEPARATOR Command
SET POINT Command
SET DECIMALS Command
SET FDOW Command
SET FWEEK Command


Remote Data Tab, Options Dialog Box

Visual FoxPro 9.0
Remote Data Tab, Options Dialog Box
See Also

Contains options for remote views and connection settings.

When you choose Set As Default — which appears on every tab in the dialog box — Visual FoxPro saves all the options on all tabs.

Remote View Defaults

Settings in the Remote view defaults box represent Visual FoxPro cursor settings for the current session. If you choose Set As Default, the settings become the defaults for subsequent sessions. The options in this box correspond to settings you make or get using the CURSORSETPROP( ) Function and CURSORGETPROP( ) Function.

Share connection

Specifies that Visual FoxPro use a shared connection, if one is available. If a shared connection is not available, Visual FoxPro creates a unique connection when the view opens and cannot be shared with other views.
Fetch memo

Specifies that Visual FoxPro does not fetch memo and general fields from the data source until a memo or general field is activated in the view output. Clear this option to reduce the amount of data downloaded initially from the remote table — this results in faster performance.
SQL updates: Criteria

Specifies what fields Visual FoxPro checks on a remote server to determine whether a record has changed before you attempt to update it. The update fails if the data in the fields you specify has changed.
SQL updates: Method

Specifies whether Visual FoxPro uses SQL UPDATE or SQL DELETE and then INSERT to update information on the remote server.
Records to fetch at a time

Specifies how many records Visual FoxPro should return at a time from the remote data source. Choose All to specify that all records should be returned in the first fetch operation. This setting is limited by the value specified in Maximum records to fetch.
Maximum records to fetch

Specifies the total number of records returned by a view, which can help prevent you from downloading an excessive amount of data if you have constructed a query incorrectly. Choose All to specify that all records should be returned.
Use memo for fields >=

Specifies the maximum length of data in long Character fields. If character data exceeds the specified length, Visual FoxPro converts it to a memo field in the output of your view. The default is 255, the maximum size of a character field in Visual FoxPro.
Records to batch update

Specifies the number of update statements sent at once for views. The default is 1. Adjusting this value can greatly increase update performance. For more information, see the REPLACE command and Scope Clauses.

Connection Defaults

Settings in the Connection defaults box represent Visual FoxPro global default settings for connections. The options in this box correspond to settings you make or get using the SQLSETPROP( ) Function and SQLGETPROP( ) Function.

Asynchronous execution

Specifies that Visual FoxPro executes SQL pass-through commands (using SQLEXEC( ) Function, SQLMORERESULTS( ) Function, SQLTABLES( ) Function, and SQLCOLUMNS( ) Function) in the background after returning control to your application. If you choose this option, your application can display progress information and can make it possible for users to interrupt a command with the ESC key if SET ESCAPE Command has been set to true. You can determine the status of a SQL command executing asynchronously by calling one of the pass-through functions repeatedly until it reports that the command is done. The default is that this option is disabled (synchronous execution), which specifies that Visual FoxPro waits until the pass-through SQL command is complete before returning control to your application.
Display warnings

Enables the display of warning messages.
Batch processing

Specifies that when you send multiple SQL pass-through statements using SQLEXEC( ) Function Visual FoxPro does not return any results until all individual result sets have been retrieved. Corresponds to setting BatchMode in the SQLSETPROP( ) Function. If this option is disabled, you must call SQLMORERESULTS( ) Function to determine whether data is available.
Automatic transactions

Specifies that transactions are handled automatically by the connection on remote tables. If you clear this option, you must handle transaction processing manually using SQLCOMMIT( ) Function and SQLROLLBACK( ) Function.
Show login

Specifies whether to display login prompts when a connection is activated (if the connection requires users to be logged in). For example, Only When Necessary specifies that login prompts appear only for login information not specified in the connection or view definition.
Connection timeout (sec)

Specifies the number of seconds (between 0 and 600) to wait for a connection to be established with the remote server. If the connection cannot be established within the specified time, Visual FoxPro generates an error. Specify 0 to wait indefinitely for a connection.
Idle timeout (min)

Specifies the number of minutes of idle time allowed before the connection is deactivated. If a request to the server is not made within the specified time, Visual FoxPro terminates the connection. However, Visual FoxPro attempts to reconnect automatically if a request to the server is made after the connection has timed out.
Query timeout (sec)

Specifies the number of seconds (between 0 and 600) to wait for the server to respond to a request. If the server takes longer than the specified number of seconds to process the query, Visual FoxPro generates an error. Specify 0 to wait indefinitely for query results.
Wait time (ms)

Specifies the number of milliseconds that elapse before Visual FoxPro checks if the SQL statement has completed executing.

See Also

Other Resources

Working with Views
How to: Share Connections for Multiple Remote Views
Memo Field Type
Options Dialog Box


Reports Tab, Options Dialog Box

Visual FoxPro 9.0
Reports Tab, Options Dialog Box
See Also

Contains default initial options and global settings for the Report Designer to use when creating reports.

When you choose Set As Default, which appears on every tab in the Options dialog box, Visual FoxPro saves all the options on all tabs.

Data and output defaults

Use private data sessions

Run the report using a private data session. You can also select Private Data Session from the Report menu. For more information about private data sessions, see How to: Use Data Sessions.
Save printer environment

Save the current printer environment setting with a report. In earlier versions of Visual FoxPro, the printer environment was saved with the report by default. In Visual FoxPro 9, it is not saved by default. For more information, see How to: Save the Printer Environment for Reports.
Use DBC field captions

Use database container (DBC) field captions when you drop fields onto a report.

Expression Builder

Always add alias

Specifies that the table or view name is always included with fields used in the expression.
Add non-selected alias only

Specifies that when more than one table or view is open, Visual FoxPro only includes the name of any table or view that is not selected in the Aliases list of the Data Session Window with any of its fields in the expression. Table or view names are not added for tables that are selected in the Aliases list.
Never add alias

Specifies that table or view names are not included with any field when you create the expression.

Report Engine behavior

Specifies the initial setting of SET REPORTBEHAVIOR when Visual FoxPro starts up.

See SET REPORTBEHAVIOR Command for more information.

80 (Backward compatible)

Sets REPORTBEHAVIOR to 80
90 (Object assisted)

Sets REPORTBEHAVIOR to 90

Designer defaults

Ruler scale

Specifies the measurement units for the ruler along the top and left edges of the Report Designer or Label Designer window.

None

The rulers are not displayed. The measurement units displayed in various dialog boxes will be in inches.
Inches

The measurement ruler and other dimensions are displayed in Inches.
Centimeters

The measurement ruler and other dimensions are displayed in Centimeters.
Pixels

The measurement ruler and other dimensions are displayed in Pixels.
System default

Specifies inches or centimeters as the unit of measurement displayed on the ruler depending on your language setting.

Show position in status bar

Specifies whether to show the mouse cursor position or currently selected control position (in ruler units) in the status bar.

Grid

Snap to grid

Align edges of newly drawn controls with the nearest grid lines in the Report Designer. You can also select Snap to Grid from the Format menu to enable this option when in the Designer.
Show grid lines

Specifies whether to display visible snap-to-grid lines in the Designer. The resolution of the visible grid is half that of the actual snap-to grid. (For example, if the Horizontal spacing is set to 12 pixels, the vertical grid lines will be drawn every 24 pixels.) You can also select Grid Lines from the View menu when in the Designer.
Horizontal spacing (pixels)

Specifies the number of pixels to horizontally space each grid section. You can also set horizontal spacing by selecting Set Grid Scale from the Format menu.
Vertical spacing (pixels)

Specifies the number of pixels to vertically space each grid section. You can also set vertical spacing by selecting Set Grid Scale from the Format menu.

Default font

Displays the default font settings for new reports or label layouts. Clicking the ellipsis(…) button opens the Font dialog box so you can select a different default font.

Use font script

Indicates that the language character set be enabled in the Font dialog box, and saved with the report. You can choose not to save the specific font script selection with the layout by clearing this check box. For more information, see Font Dialog Box.

See Also

Other Resources

Options Dialog Box
Set Grid Scale Dialog Box
Visual FoxPro Environment Settings
How to: View and Change Environment Settings


View Tab, Options Dialog Box

Visual FoxPro 9.0
View Tab, Options Dialog Box
See Also

Contains options for controlling the display of Visual FoxPro features.

When you choose Set As Default, which appears on every tab in the dialog box, Visual FoxPro saves all the options on all tabs.

Show

Status bar

Specifies whether Visual FoxPro displays the status bar at the bottom of the main window. Corresponds to the SET STATUS BAR Command.
Clock

Specifies whether the system clock appears in the status bar. You must choose the StatusBar option for this option to have effect. Corresponds to the SET CLOCK Command.
Command results

Specifies that Visual FoxPro displays the results of certain commands including APPEND FROM, AVERAGE, CALCULATE, COUNT, INDEX, SUM, and TOTAL, in the main Visual FoxPro window, the system message window, the graphical status bar, or a user-defined window. Corresponds to the SET TALK Command.
System messages

Specifies that Visual FoxPro displays certain system messages in the status bar. This option corresponds to the SET NOTIFY Command.
Open last project on startup

Open the most recently used project when starting Visual FoxPro. This option is unavailable if any of the following conditions exist:
  • The Resource File setting on the File Locations tab in the Options dialog box is empty. For more information, see File Locations Tab, Options Dialog Box.

  • The SET RESOURCE command is set to OFF. For more information, see SET RESOURCE Command.

  • On a computer running Windows XP or 2000, the systems policy for not keeping a history of recently opened files has been set.

Most Recently Used list contains

Makes it possible for you to specify the number of files displayed in the most recently used (MRU) list. The default setting is 4. This option is unavailable if any of the following conditions exist:
  • The Resource File setting on the File Locations tab in the Options dialog box is empty. For more information, see File Locations Tab, Options Dialog Box.

  • The SET RESOURCE command is set to OFF. For more information, see SET RESOURCE Command.

  • On a computer running Windows XP or 2000, the systems policy for not keeping a history of recently opened files has been set.

List display count

Specifies the maximum number of items to display initially in IntelliSense drop-down list boxes. The default value is 15. The minimum value is 5.

See Also

Other Resources

Options Dialog Box
Visual FoxPro Environment Settings


Page Setup Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Page Setup Dialog Box (Visual FoxPro)
See Also

Specifies paper size and page orientation settings in Visual FoxPro. The settings available in this dialog box depend on the installed printer.

This dialog box appears when you select Page Setup from the File menu or from the Report Page Setup dialog box. For more information, see Report Page Setup Dialog Box.

Paper

Specifies paper settings for the page.

Size

Specifies the paper size.
Source

Specifies the paper source location in the printer.

Orientation

Specifies page orientation settings.

Portrait

Prints the page in a vertical position with the shortest side at the top.
Landscape

Prints the page in a horizontal position with the longest side at the top.

Margins

Margin settings in this dialog box are unavailable in Visual FoxPro.

Printer

Displays the printer Page Setup dialog box so you can specify printer settings.

Printer Page Setup Dialog Box

Specifies printer settings in Visual FoxPro. The settings available in this dialog box depend on the installed printer.

This dialog box appears when you click Printer in the Page Setup dialog box.

Printer

Specifies and displays printer information.

Name

Displays the names of the printers currently installed on your computer.
Status

Displays the printer status.
Type

Displays the model of the selected printer. The printer model is specified when you install the printer.
Where

Displays the network printer path.
Comment

Displays additional printer information, for example, printer location.

See Also

Other Resources

SYS(1037) - Page Setup Dialog Box
Dialog Boxes


Paste Special Dialog Box

Visual FoxPro 9.0
Paste Special Dialog Box
See Also

This dialog box makes it possible for you to link or embed an OLE object from the Clipboard. Visual FoxPro places the object in the current General field. You must open the General Field window to paste the data.

To use Paste Special, you must first copy the object you want to paste to the Clipboard and then open the General Field window; this will enable the command. Paste Special opens the Paste Special dialog box.

Source

Displays the application, directory, and file you are pasting from.
As

Displays the available formats for the object you are pasting. Select the format for the object according to what you want to be able to do with the stored object within Visual FoxPro. The Object format makes it possible for you to edit the object (for example, a Microsoft Excel worksheet object) by opening its source application from a field. If an object is in a Picture or Bitmap format, you cannot edit it from a table field. The Picture or Bitmap formats display the object and minimize the space it occupies in your file. If you plan to change the size of the object, choose the Picture format.
Paste

Embeds the object from the Clipboard in the current General field.
Paste Link

Links the object to Visual FoxPro so you can modify the object from within Visual FoxPro. Paste Link is only available when copying a saved object.
Note:
With a Microsoft Word document, both Paste and Paste Link are enabled.

Display As Icon

Displays the application icon instead of the data. This saves disk space when linking or embedding.
Change Icon

Displays the Change Icon dialog box, which makes it possible for you to specify the icon to be used for a linked or embedded object on a form or in a General field of a Visual FoxPro table. This button appears when you select the Display As Icon check box.
Results

Describes what actions will be performed on the contents of the clipboard after you click OK. You can alter the description displayed by choosing the Paste, Paste Link, or Display As Icon options.

See Also

Other Resources

Dialog Boxes
General Field Window
Find Dialog Box
Change Icon Dialog Box
General Field Type
How to: Add OLE Objects to Applications
Text Editor and Clipboard Manipulation Routines
Dynamic Information Sharing


Pane Customization Dialog Box

Visual FoxPro 9.0
Pane Customization Dialog Box
See Also

The Pane Customization dialog box is used to create, modify, and delete panes in the Task Pane Manager.

New

Displays the Pane dialog box for you to enter basic information about the new pane to create. The following options are displayed:
  • Vendor Specifies the name of the company that is creating the new pane.

  • Unique ID Specifies a unique ID number for the pane content. It is recommended that you accept the default value.

  • Name Specifies the name of the new pane. This name appears at the top of the Task Pane Manager. To specify a hot key for the link at the top of the Task Pane Manager, include an escape character in the Name box. For example, \<My Pane would specify the letter M as the hot key in the panes link.

  • Pane Type Specifies the type of pane you want to create. The four types of panes you can create are explained in the following table.

    Pane Type Description

    Web Page

    Displays an Internet URL using the Internet Explorer ActiveX control.

    HTML

    The pane and its content sections are displayed as HTML in the Internet Explorer ActiveX control.

    XML

    The pane and its content sections are displayed as XML in the Internet Explorer ActiveX control. A local Extensible Stylesheet Language (XSL) file must be distributed with this type of pane.

    VFP Controls

    Specify a Visual FoxPro class library and class to create as the pane. This class should inherit from the PaneContainer class of the FoxPane library.

    Copy Code
    DEFINE CLASS MyPane AS PaneContainer OF FoxPane
Delete

Delete a pane from the Task Pane Manager. When selected, a dialog box appears prompting you to delete the selected pane.
Publish

Displays the Publish Pane dialog box where you can publish the selected pane by wrapping the pane's content and its associated files into a manifest XML file for easy distribution. The following options are displayed:
  • Publish all content in pane Specifies that all content sections of the pane are published into the manifest XML file.

  • Publish selected content Specifies that only the content sections selected in the list are published into the manifest XML file.

  • Publish files associated with the pane Specifies that files associated with the pane are published into the manifest XML file.

  • Publish files common to all panes Specifies that files that are common to all panes are published into the manifest XML file. This option should be selected only if you need to distribute content in the root PaneCache folder.

View Content

Displays the Pane Content section on the right side of the Pane Customization dialog box.
View Files

Displays the Pane Files section on the right side of the Pane Customization dialog box.
Pane List

Lists all the installed panes in the Task Pane Manager. Selecting a pane updates the controls of the Pane Content and Pane Files sections with information on the selected pane.
Inactive

Specifies that the selected pane is inactive. Inactive panes do not show in the Pane List toolbar at the top of the Task Pane Manager or the Task Pane Options dialog box.
Save

Saves any changes to the selected pane, applies them to the Task Pane Manager, and closes the Pane Customization dialog box.
Apply

Saves any changes to the selected pane and applies them to the Task Pane Manager.

Pane Content

The Pane Content section is displayed when you select View Content. In this section, you can specify settings for the panes.

Add

Adds a new content section, which is displayed in Content Sections List below the button.
Remove

Prompts you to delete the selected content section.
Up Arrow

Moves the selected section up in the Content Sections List.
Down Arrow

Moves the selected section down in the Content SectionsList.
Content Sections List

Lists the content sections for a pane. Selecting a content section updates the controls of the Pane Content section with information on the selected pane.

General Tab

Displays options for the root pane content or section content in which you specify general information on the selected item. For more information, see General Tab, Pane Customization Dialog Box.

Data Tab

Displays the URL for panes based on Web pages, or contains the XML data used to render a page for HTML- or XML-based panes. This pane is available only when the root pane type is Web Page, HTML, or XML. For more information, see Data Tab, Pane Customization Dialog Box.

Transform Data Tab

Specifies the XML transformation that is used to render panes based on HTML or XML. This pane is available only when the root pane type is HTML or XML. For more information, see Transform Data Tab, Pane Customization Dialog Box.

Default Data Tab

Specifies the data to be used when the pane is rendered if the pane's online content cannot be downloaded. This pane is available only when the root pane type is HTML or XML. For more information, see Default Data Tab, Pane Customization Dialog Box.

Handler Code Tab

Specifies handler code to handle user input in panes. This pane is available only when the root pane type is HTML or XML. For more information, see Handler Code Tab, Pane Customization Dialog Box.

Options Tab

Specifies custom options for a content section. For XML- and HTML-based panes, options can be specified only on subsection content. For Web Page and VFP Control panes, options can be specified only on the root content section. For more information, see Options Tab, Pane Customization Dialog Box.

Pane Files

The Pane Files section is displayed when you select View Files. In this section, you can add, edit, and remove files associated with a pane.

Add

Prompts the user to select a file to add to a pane.
Edit

Opens a file and its associated default editor for editing.
Remove

Prompts the user to remove the selected file from the pane.

See Also

Other Resources

Dialog Boxes
Task Pane Manager
Task Pane Options Dialog Box


Data Tab, Pane Customization Dialog Box

Visual FoxPro 9.0
Data Tab, Pane Customization Dialog Box
See Also

The Data tab contains the data that Web Page, HTML, and XML panes are based on.

Source

Specifies the data source type for the pane. The five data source types are explained in the following table.

Data source type Description

Static Text

Specifies that the data is well-formed XML. The default static text for XML Pane type is:

Copy Code
<VFPData>
   <!-- CONTENT -->
</VFPData>

You can type well-formed XML data instead of the comment. If the root pane has subsections, the default static text can remain because Visual FoxPro concatenates and places the XML data for the subsection here.

If you need to wrap your subcontent in XML so that the content sections can be further transformed by the root before finally displaying on the pane, use the following syntax in the root content section.

Copy Code
<VFPData>
   <!-- XMLCONTENT -->
</VFPData>

This wraps each subcontent in XML CDATA sections with the content between <HTMLText> tags. For example, a pane with two subcontent records might look like the following example:

Copy Code
<VFPData>
   <PaneContent id="uniqueid1">
   <PaneTitle>Content Title goes here</PaneTitle>
   <HTMLText><![CDATA[Transformed sub-content is placed here]]>
   </HTMLText>
   </PaneContent>
      <PaneContent id="uniqueid2">
   <PaneTitle>Content Title goes here</PaneTitle>
   <HTMLText><![CDATA[Transformed sub-content is placed here]]>
   </HTMLText>
   </PaneContent>
</VFPData>

The root content section's transformation then determines whether to handle transforming this XML data or distribute an XML file in the files section.

URL

The data is contained in a file on the Internet. You can then push dynamic content to the pane from a file on the Internet.

Script

Specifies Visual FoxPro code to generate XML data. The code returns an XML string to be used as the data and accepts a parameter object to expose options set for the pane to the code.

Copy Code
LPARAMTERS oContent

The object exposes the following properties and methods:

  • CacheDir The directory of the user's pane cache

  • ContentTitle The name of the selected content section

  • Unique ID The unique ID of the selected content section

  • TaskPaneID The unique ID of the pane the content section belongs to

  • User User data that is contained in the User field in the PaneContent table

  • GetOption(cOptionName , xDefaultValue) Returns the value of the option specified. You can optionally specify the default value to be returned if the option is empty. All option values are returned as strings, unless xDefaultValue specifies a different data type.

File

Specifies a local file as the data source. This file is added to the list of associated files for the pane and copied to the pane's cache directory.

Web Service

Specifies that the data is obtained through an XML Web service on the Internet.
Modify

Opens a window to modify the Visual FoxPro Code or XML data.
Edit Box

Displays Visual FoxPro code or XML data.
Source of this content is from the Internet

Specifies that a Visual FoxPro code script is downloading content from the Internet. This enables the Check for New Internet Content option for the pane.
File

Specifies the name of the data file.
Ellipsis (...)

Prompts you to select a data file.
WSDL URL

Specifies the Web Services Description Language (WSDL) file URL for the XML Web service that provides the data for the pane. The WSDL describes the services offered by the server.
Method

Specifies the XML Web service method to call. The appropriate parameters for the method must also be specified. To specify pane options, use the ## delimiters. For example, GetPaneXML(##daysold##) references the GetPaneXML XML Web service method and uses the DaysOld option for a pane as the parameter.
Service

Specifies the service in the WSDL file that contains the operation specified in the Simple Object Access Protocol (SOAP) request. If this option is blank, the first service in the specified WSDL file is used when initializing the SoapClient object. (Optional)
Port

Specifies the name of the port in the WSDL file that contains the operation specified in the SOAP request. If this option is blank, the first port in the specified service is used when initializing the SoapClient object. (Optional)
WSML

Specifies the URL of the Web Services Meta Language (WSML) file. This is a required parameter only when using custom type mappers. For more information about custom type mappers, see the SOAP Toolkit documentation distributed with Visual FoxPro.

See Also

Other Resources

Pane Customization Dialog Box
Task Pane Manager


Default Data Tab, Pane Customization Dialog Box

Visual FoxPro 9.0
Default Data Tab, Pane Customization Dialog Box
See Also

The Default Data tab specifies the default data to display if live data cannot be retrieved from the Internet when a pane first displays. This information is optional and is used only if the data is not stored locally. If a pane successfully retrieves data from the Internet but fails on subsequent attempts, the pane uses the data stored in the PaneCache directory, not the default XML data.

Modify

Opens a window to edit the default XML data.
Edit Box

Displays the default XML data.

See Also

Other Resources

Pane Customization Dialog Box
Task Pane Manager


General Tab, Pane Customization Dialog Box

Visual FoxPro 9.0
General Tab, Pane Customization Dialog Box
See Also

The General tab contains general information for the root pane content and sub-content sections.

Unique ID

Specifies a unique identifier assigned to the selected pane. A default ID is assigned when a pane is created. It is recommended that you accept the default value.
Name

Specifies the name of the content section. If the selected content section is the root content section, the name appears at the top of the Task Pane Manager. Hot keys can be assigned by placing an escape character in the Name box. For example, \<My Pane as the name of the root content section specifies the letter M as the hot key for this pane in the Task Pane Manager.
Help URL

Specifies the URL for help on the selected pane. The Help hyperlink to the URL appears in the Task Pane Options dialog box when the pane is selected.
Select Image

Displays a dialog box to select an image that will be associated with the selected pane. The selected image is shown along with the link to the pane at the top of the Task Pane Manager.
Class Library

Specifies the program file (.prg) or library file (.vcx) that contains the class and associated code to run the pane. The file is automatically copied to the selected pane's PaneCache folder, and the files are automatically added to the list of files associated with the selected pane. This field appears only if the selected pane is based on the VFP Controls type.
Class Name

Specifies the name of the container class to instantiate when creating the pane from the specified class library. This field appears only if the selected pane is based on the VFP Controls type.
Modify

Opens the class library for editing. This control appears only if the selected pane is based on the VFP Controls type.

See Also

Other Resources

Pane Customization Dialog Box
Task Pane Manager


Handler Code Tab, Pane Customization Dialog Box

Visual FoxPro 9.0
Handler Code Tab, Pane Customization Dialog Box
See Also

The Handler Code tab specifies handlers to hyperlinks that are selected in a pane when the pane type is XML or HTML, and the hyperlink begins with vfps:. For example, the following code opens a browser window to the specified URL:

<a href="vfps:linkto?url=http://msdn.microsoft.com/vfoxpro/">Go to the VFP site</a>

The following table lists default handlers built into the Task Pane Manager.

Default handler | Description
vfps:refresh | Reloads the current pane.
vfps:linkto | Opens a browser window to the specified URL. The URL is specified with the url=cURL parameter.
vfps:gotopane | Switches the Task Pane Manager to the specified pane. The pane is specified with the uniqueid=cPaneUniqueID parameter.
vfps:help | Displays the specified Help by topic or ID. The Help is displayed by using the ID=cTopicID or Topic=cTopicName parameters.
vfps:options | Displays the Task Pane Options dialog box for the specified pane. The pane is specified with the uniqueid=cPaneUniqueID parameter.
vfps:message | Displays an informational message box. The message is specified with the msg=cMessage parameter.

You can include the refresh parameter with any handler code so that the pane reloads immediately after the handler is called. This is useful when the result of the link might affect the pane's content. You can use the refresh parameter with other parameters as shown in the following example:

vfps:message?msg=This is a message&refresh

The following table lists the parameters passed to the code when you use custom handler code.

Parameter | Description
cAction | Specifies the action, which is the text following vfps: but preceding any parameters. For example, the following specifies to use a custom handler called MyAction: <a href="vfps:MyAction?Param=Value">This is my handler</a>
oParameters | A collection of the specified parameters. Additionally, if this is a form submit, the collection also includes the form values. To retrieve a value, call the GetParam( ) function with the parameter name as shown in the following example: oParameters.GetParam("ParameterName")
oBrowser | Contains the object reference to the Window object in the browser control on the pane. You can use this to access DHTML methods and properties. For example: oBrowser.document.all("SearchResults").style.display = "none"
oContent | Contains a reference to the pane content definition so you can retrieve option values and the PaneCache folder specified in the Task Pane Options dialog box. This is the same object that is passed into a script on the Data Tab, Pane Customization dialog box.
Modify

Opens a window to edit the handler code.
Edit Box

Displays the handler code.

See Also

Other Resources

Pane Customization Dialog Box
Task Pane Manager


Options Tab, Pane Customization Dialog Box

Visual FoxPro 9.0
Options Tab, Pane Customization Dialog Box
See Also

The Options tab specifies custom options for a content section.

For XML and HTML pane types, options can be specified only on subsection content. For Web Page and Visual FoxPro Controls pane types, options can be specified on the root content section because these pane types do not have subcontent sections.

New

Opens the New Option dialog box prompting you for information on the new option. The NewOption dialog box has the following fields.
  • Options name The name of the option that is referred to in code.

  • Type The type of control you want to create in the Task Pane Options dialog box. This can be a textbox, checkbox, spinner, or password control

  • Caption The label that appears next to the control in the Task Pane Options dialog box.

Delete

Prompts you to delete the selected option.
New Property

Displays a message box prompting you to enter the name of the new property. You can enter the value of the property using the Property List after you have added the property.
Delete

Prompts you to delete the selected property.
Options List

Displays a list of options for the selected pane or content section.
Property List

Displays list of properties and their default values for the selected pane or content section.

See Also

Other Resources

Pane Customization Dialog Box
Task Pane Manager


Transform Data Tab, Pane Customization Dialog Box

Visual FoxPro 9.0
Transform Data Tab, Pane Customization Dialog Box
See Also

The Transform Data tab contains the XML transformation that is used to render a content section.

Type

Specifies the type of transformation data. The following are the two types of transformation data.

Type Description

XML

Specifies that the transformation is Extensible Stylesheet Language (XSL).

Script

Specifies that the transformation is Visual FoxPro code.
Source

Specifies the source of the transformation data. The XML transformation data can come from the same sources as specified on the Data Tab, Pane Customization Dialog Box.
Modify

Opens a window to modify the Visual FoxPro code or XSL data.
Edit Box

Displays Visual FoxPro code or XSL data.

See Also

Other Resources

Pane Customization Dialog Box
Task Pane Manager


Print Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Print Dialog Box (Visual FoxPro)
See Also

Makes it possible for you to select printer options when printing a file. This dialog box appears when you select Print from the File menu.

Note:
The settings available depend on the Windows operating system that you are running Visual FoxPro on. For versions of Windows prior to Windows 2000, the setting names for this dialog box are indicated in parentheses. Settings that are available only when running Windows 2000 and later are indicated.

Shortcut

CTRL+P

General Tab (Printer)

Specifies printer-specific settings.

Select Printer (Name)

Displays printers connected to your computer.
Status

Displays the printer status.
Location (Where)

Displays the network printer path.
Comment

Displays additional printer information, for example, printer location.
Preferences (Properties)

Opens the system Printing Preferences (Document Properties) dialog box so you can set page preferences.
Find Printer

Opens the Find Printers dialog box so you can locate a printer. Available on Windows 2000 or later.

Page Range (Print range)

Specifies page selection settings.

All

Prints all pages in the file.
Selection

Prints selected text in the file. This option is available only when text is selected.
Note:
If a partial line of text is selected, the entire line is printed.

Pages

Specifies a range of pages in the file to print.
Number of copies

Specifies the number of copies of the file to print.
Collate

Specifies to collate the printed copies when printing multiple copies of the file.
Options

Displays the Print Options dialog box. For more information, see Print Options Dialog Box.
Print (OK)

Print the file.

See Also

Other Resources

Dialog Boxes


Print File Dialog Box

Visual FoxPro 9.0
Print File Dialog Box
See Also

Makes it possible for you to browse for and select a file to print.

This dialog box appears when you click the ellipsis (...) button to the right of the File box in the Print Options dialog box. The file types are filtered by the file type you select in the Print Options dialog box. For more information, see Print Options Dialog Box.

Code Page

Displays the Code Page dialog box so you can attach the correct code page. If the file you want to print uses the extended character set, click Code Page and make the appropriate selections.

See Also

Other Resources

Code Page Dialog Box
Dialog Boxes


Print Options Dialog Box

Visual FoxPro 9.0
Print Options Dialog Box
See Also

Makes it possible for you to specify options for printing files or the contents of the Command window or Clipboard.

This dialog box appears when you select Options in the Print dialog box. For more information, see Print Dialog Box.

Print What

Specifies the type and the file to print.

Type

Specifies the type of file to print.
Caution:
The ASCII File option bypasses the printer driver and sends the contents of the selected file directly to the printer. Make sure that the file contains valid printer commands. Sending invalid printer commands to the printer device might cause the printer to fail and require a reset.

File

Specifies the path and file name of the file you want to print. To browse for and select a file, click the ellipsis (...) button to open the Print File dialog box. For more information, see Print File Dialog Box.

Print Options

Specifies output options for the file.

Line numbers

Prints line numbers in the left margin. This option is available for printing contents of the Command window and the Clipboard.
Page eject before

Advances the printer to the top of the next page before printing the file.
Page eject after

Advances the printer to the top of the next page after printing the file. This option is not available for reports and labels.
Restore environment

When running FoxPro version 2.x reports, makes sure that the data environment settings previously saved with the report are used to run the report. This option does not apply to Visual FoxPro reports because they use their own data environments.
Options

Displays the Report and Label Print Options dialog box for selecting records you wan to print from a report or label. Available only when printing reports and labels. For more information, see Report and Label Print Options Dialog Box.

See Also

Other Resources

Dialog Boxes


Print When Dialog Box

Visual FoxPro 9.0
Print When Dialog Box
See Also

Makes it possible for you to set options for conditions that control output in report controls.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

Print repeated values

Specifies whether the report engine tracks changes between successive values of the report control's output and renders only when the value changes.

Yes

Render output for the control every time the band is processed by the report engine.
No

Render output for the control only if the value is different from the last time the control output was evaluated.

Also print

Specifies additional conditions for repeating report control values.

In first whole band of new page/column

Specifies that the control output should be rendered if the band that contains it is rendering for the first time on a new page or column, overriding the setting of Print repeated values. For more information, see Working with Report Bands.
When this group changes

Specifies that the control output should be rendered if a specific data group expression evaluates to a different value, overriding the setting of Print repeated values. For more information, see Working with Report Data Groups.
When detail overflows to new page/column

Specifies that the report control output be rendered when the band that contains it overflows to a new page or column.

Additional options

The following additional options make it possible for you to suppress blank lines and control output for report controls and data in report controls.

Remove line if blank

Specifies that the report engine may contract the report band vertically if the evaluation of the report control results in no renderable content, and no other renderable controls occupy the empty space on either side of the control.
Print only when expression is true

Specifies a logical expression that the report engine evaluates in order to decide whether to render output for the report control.
Note:
When you add an expression to the Print only when expression is true box, all other options in the Print When dialog box become unavailable except the Remove line if blank box.

See Also

Other Resources

Dialog Boxes
Expression Builder Dialog Box
Rectangle/Line Dialog Box
Report Designer
Report Expression Dialog Box


Project Information Dialog Box

Visual FoxPro 9.0
Project Information Dialog Box
See Also

Lets you view and edit information about the project and its files. This dialog box appears when you select Project Information from the Project menu.

Shortcut

CTRL+J in the Project Manager or ALT+ENTER.

See Also

Other Resources

Dialog Boxes
Update Project List Dialog Box
Project Tab, Project Information Dialog Box
Select Directory Dialog Box
Build Options Dialog Box
EXE Version Dialog Box
Files Tab, Project Information Dialog Box
Projects Tab, Options Dialog Box
Servers Tab, Project Information Dialog Box


Project Tab, Project Information Dialog Box

Visual FoxPro 9.0
Project Tab, Project Information Dialog Box
See Also

Displays status information about the project.

Author

Displays the author's name, which you can change by typing it in the box.
Company

Displays the company name, which you can change by typing it in the box.
Address/City/State/Country/Postal Code

Displays the company address information, which you can change by typing it in the boxes.
Home

Displays the directory that contains the project file. To change the directory, type another name in the box or click the dialog button to display the Select Directory dialog box.
Last Built

Displays the date and time of the last project build. This information cannot be edited.
Files

Displays the number of files in the project. This information cannot be edited.
Debug Info

Specifies whether debugging information is included with the compiled file. If this is not checked, you cannot view program execution in the Trace window. Corresponds to the NODEBUG argument in the COMPILE command.
Encrypted

Specifies whether to scramble compiled files for security.
Attach Icon

Specifies whether to display a selected icon when the application is run. When checked, displays the Open dialog box if an icon has never been assigned to the application.
Icon

Displays the Open dialog box so that you can choose an icon. This button is available only if you select the Attach Icon check box. To display the icon correctly in the Windows Explorer, the icon file should contain both 32 x 32 and 16 x 16 icon images. The 32 x 32 image is used in the Explorer Large Icons view, and the 16 x 16 image is used in the Explorer Small Icons, List, and Detail views. The following table lists the icon image formats that Visual FoxPro supports.

Colors Size (pixels)

True Color (24 bit)

16 x 16

True Color (24 bit)

32 x 32

True Color (24 bit)

48 x 48

True Color (16 bit)

16 x 16

True Color (16 bit)

32 x 32

True Color (16 bit)

48 x 48

256 Color

16 x 16

256 Color

32 x 32

256 Color

48 x 48

16 Color

16 x 16

16 Color

32 x 32

16 Color

48 x 48
Project Class

Displays the Project Reference dialog, allowing you to specify a default ProjectHook class as a template for new projects.

See Also

Other Resources

Dialog Boxes
COMPILE Command
Files Tab, Project Information Dialog Box
Project Manager
Select Directory Dialog Box
Trace Window
Servers Tab, Project Information Dialog Box
Project Information Dialog Box
Project Manager Hooks
Development Productivity Tools


Select Directory Dialog Box

Visual FoxPro 9.0
Select Directory Dialog Box
See Also

Allows you to set the home directory of the project. This dialog box appears when you choose the dialog button on the Project tab of the Project Information dialog box. The dialog button is associated with the Home option.

Directory

Displays a directory tree, where you click on the directory you want to set as the project home directory.
Drive

Allows you to select a drive so you can choose a directory on that drive.
Select

Makes the selected drive/directory combination the project home directory. This directory is then displayed in the Home box of the Project tab.
New Folder

Available when the nflag value of the GETDIR( ) function = 64. Allows you to create a new folder in the dialog box.

See Also

Other Resources

Dialog Boxes
Project Information Dialog Box
Project Manager
Project Tab, Project Information Dialog Box
Files Tab, Project Information Dialog Box
Project Information Dialog Box


Files Tab, Project Information Dialog Box

Visual FoxPro 9.0
Files Tab, Project Information Dialog Box
See Also

Displays an alphabetical list of all project files, their type and include/exclude status, date and time last modified, and code page information.

Type

Displays an icon representing the file type.
Name

Displays the file name.
Last Modified

Displays the date and time the file was last modified.
Included

If you select this box, the file is included. If you clear the box, the file is excluded.
Code Page

Displays the code page number.
Update native code page

Updates the code pages for each file listed.

See Also

Other Resources

Dialog Boxes
Project Manager
Project Tab, Project Information Dialog Box
Servers Tab, Project Information Dialog Box
Select Directory Dialog Box
Build Options Dialog Box
EXE Version Dialog Box
How to: Determine the Code Page of a Project File
Code Pages in Visual FoxPro
Developing International Applications


Servers Tab, Project Information Dialog Box

Visual FoxPro 9.0
Servers Tab, Project Information Dialog Box
See Also

Displays classes located on servers, their class library, instancing, description, type, and Help information.

Note:
Changes you make in the Servers tab requires you to rebuild the .dll or .exe for the new settings to take effect.

Server Classes

Displays a list of all the available classes, both .vcx and in code, which are marked as OLEPublic. Each class in the list has a corresponding .pjx file.
Class Library

Displays the directory path of the class library in which the selected class is stored.
Class Name

Displays the name of the class.
Instancing

Displays one of following options: Single Use Specifies that you can create an instance of the class both inside Visual FoxPro and outside of Visual FoxPro using Automation. Each request for an instance of the class by an Automation client outside of the project causes a separate copy of the Automation server to start. Each instance has a single thread of execution. Although separate instances require more memory, choosing Single Use allows the operating system to apply preemptive multitasking. Instancing defaults to Single Use when you create a new project containing OLEPUBLIC classes. This setting is appropriate for building EXE servers. Not Creatable Specifies that you can create instances of the class only inside Visual FoxPro. Multi Use Specifies that you can create an instance of the class both inside Visual FoxPro and outside of Visual FoxPro using Automation. Each request for an instance of the class by an Automation client outside of the project causes an already running copy of the Automation server to be provided as the source for the new instance. Once the server has been created, other applications can use the same instance. Instancing defaults to Multi Use when you create a .dll COM Server.
Description

Displays a small description of the class. By default Visual FoxPro registers the full Project.Server notation as the description. This ensures consistent registry keys. You can specify a different Description here.
Help file

Displays the Help file associated with the server. Select the dialog button to display the Open dialog box if no file is listed.
Help context ID

Displays the context ID of the Help file associated with the application, if a Help file is distributed with the application.
Project name

Displays the name of the project associated with the server classes.
Typelib description

Displays a description of the class library the selected class is based on.

See Also

Other Resources

Dialog Boxes
Files Tab, Project Information Dialog Box
Project Manager
Project Tab, Project Information Dialog Box
Select Directory Dialog Box
EXE Version Dialog Box


Prompt Options Dialog Box

Visual FoxPro 9.0
Prompt Options Dialog Box
See Also

Makes it possible for you to specify options for prompts in a customized menu system. Use this dialog box to define keyboard shortcuts, determine when the menu or menu item is disabled, include a message in the status bar when the menu or menu item is selected, specify a name for a menu title, and control menu title location during OLE visual editing.

This dialog box appears when you choose the Options button in the Menu and Shortcut Designers.

Commen t

Provides space for adding a comment for personal use only. Comments do not affect generated code in any way; Microsoft Visual FoxPro ignores them when running the menu program.
Shortcut

Defines the optional shortcut key for a menu or menu item. Keyboard shortcuts for Visual FoxPro menu items are a combination of the CTRL key and another key.
Key Label

Displays your key combination. If a menu item does not have a keyboard shortcut, Visual FoxPro displays "(press the key)" in the KeyLabel box. Press the key combination you want for your shortcut key.
Key Text

Displays the text you want to appear beside the menu item. Unless you change it, this box repeats the keyboard shortcut from the KeyLabel box. For example, if both the KeyLabel and the KeyText were CTRL+R, you could change the KeyText to ^R.
Note:
You cannot assign CTRL+J as a keyboard shortcut for a menu item.

Skip For

Displays the Expression Builder Dialog Box. In the SkipFor box of the ExpressionBuilder, type the expression that determines whether the menu or menu item is disabled or enabled. The menu or menu item is disabled if the expression is true (.T.).
Negotiate

Specifies the location of menu titles when the user edits an OLE object in your application.
Container

Specifies how the menu title will be merged when Visual FoxPro is the container of an in-place active object.
Note:
Menu negotiation options are available only for OLE objects that can be edited in place.

The following table lists the menu title placement for each negotiation setting.

Setting Placement

None

Specifies that the menu title not be placed on the menu bar. This is the same as not choosing any option.

Left

Specifies that the menu title be placed in the left group of menu titles on the menu bar.

Middle

Specifies that the menu title be placed in the middle group of menu titles on the menu bar.

Right

Specifies that the menu title be placed in the right group of menu titles on the menu bar.
For more information about object menu negotiation, see DEFINE PAD Command.
Message

Displays the ExpressionBuilder dialog box. In the Message box of the ExpressionBuilder, type the message that will appear in the Visual FoxPro status bar that describes the menu choice.
Pad Name

Makes it possible for you to specify an optional menu title. The name or number used in the generated menu program is optional, and Visual FoxPro provides one if you do not. Using this name or number, you can reference a menu or menu item at run time. This option is available for menus only.
Note:
This option is available only if the Result area in the Menu Designer window shows Command, Submenu, or Procedure.

Picture

Makes it possible for you to specify a graphics file to be displayed to the left of the menu bar text, or beside the resource in the Visual FoxPro system menu.
Bar #

Makes it possible for you to specify an optional shortcut menu title. This option is available for shortcut menus only.

See Also

Other Resources

Dialog Boxes
Expression Builder Dialog Box
Menu and Shortcut Designers
PROMPT( ) Function
DEFINE PAD Command
Having Dialog Box
Set Index Order Dialog Box
Create One-To-Many Relationships Dialog Box


Query Destination Dialog Box

Visual FoxPro 9.0
Query Destination Dialog Box
See Also

Lets you send the results of your query to seven different outputs.

This dialog box appears when you select Query Destination from the Query menu and is available only for queries.

Output destinations

Displays buttons for you to choose the type of output for the results of your query. The following table lists and describes the output types.

Button Description

Browse Button, Query Destination Dialog Box

Displays the results of your query in a Browse window.

Cursor Button, Query Destination Dialog Box

Saves the results of your query in a cursor.

Table Button, Query Destination Dialog Box

Saves the results of your query as a table file.

Screen Button, Query Destination Dialog Box

Displays the results of your query in the active output window.

See Also

Other Resources

Dialog Boxes
Query and View Designers


Browse Button, Query Destination Dialog Box

Visual FoxPro 9.0
Browse Button, Query Destination Dialog Box
See Also

Displays the results of your query in a Browse Window for examination and editing.

See Also

Other Resources

Dialog Boxes
Query Destination Dialog Box
Browse Window
BROWSE Command
Cursor Button, Query Destination Dialog Box
Class Browser Buttons


Cursor Button, Query Destination Dialog Box

Visual FoxPro 9.0
Cursor Button, Query Destination Dialog Box
See Also

Saves the results of your query in a cursor with the name you assign it. The cursor is read-only, appears in the View window, and is available for browsing, reporting, or other uses until you close it. This command is available only for queries.

Cursor Name

Specifies the name of the cursor.

See Also

Other Resources

Dialog Boxes
Query Destination Dialog Box
Browse Button, Query Destination Dialog Box,
Table Button, Query Destination Dialog Box
How to: Store Query Results in a Table, Array, or Cursor
SET CURSOR Command
Query and View Designers


Table Button, Query Destination Dialog Box

Visual FoxPro 9.0
Table Button, Query Destination Dialog Box
See Also

Saves the results of your query as a table file (.dbf) with the name you assign to it. This command is available only for queries.

Table Name

Specifies the name of the table. You can either type the name in the text box or use the dialog button to select an existing table that you want to overwrite.

See Also

Other Resources

Dialog Boxes
Query Destination Dialog Box
Cursor Button, Query Destination Dialog Box,
Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)


Screen Button, Query Destination Dialog Box

Visual FoxPro 9.0
Screen Button, Query Destination Dialog Box
See Also

Displays the results of your query in the active output window. This command is available only for queries.

Secondary Output

None

Specifies that the output not be sent to the printer or saved as a text file.
To Printer

Sends the results of the query to the printer as well as to the screen.
To Text File

Saves the results of the query as a text file. Click the button to select an existing file to overwrite, or type the name of a new file in the text box.

Options

Suppress Column Headings

Keeps headings from appearing at the top of the query results.
Pause Between Screens

Pauses at the end of each screen and displays a prompt for you to continue to the next screen. At the prompt, you can cancel the query by pressing ESC.

See Also

Other Resources

Dialog Boxes
Query Destination Dialog Box


Quick Report Dialog Box

Visual FoxPro 9.0
Quick Report Dialog Box
See Also

Makes it possible for you to select fields and a field layout for a report.

Field layout

Specifies whether to display fields from left to right across the page as columns or from top to bottom as rows.
Titles

Determines whether to display field names as titles in label controls that appear above or next to the corresponding field.
Add alias

Adds the alias to all field names automatically in the Report Designe.
Add table to data environment

Adds the table to the data environment automatically.
Fields

Displays the Field Picker dialog box so you can select the fields to include in the report. For more information, see Field Picker Dialog Box.

See Also

Other Resources

Dialog Boxes
How to: Create Reports
CREATE REPORT – Quick Report Command


Recall (Records) Dialog Box

Visual FoxPro 9.0
Recall (Records) Dialog Box
See Also

Lets you unmark records that are marked for deletion. Corresponds to the RECALL command.

Scope

Allows you to specify the records on which Visual FoxPro is to act. Choose Next, All, Record or Rest from the drop-down list. Choose a number from the spinner on the right when you select Next or Record from the Scope drop-down list.
For

Displays the Expression Builder dialog box, where you create the logical expression that every record must meet to be affected by the command. Every record in the table is tested using the For expression.
While

Displays the Expression Builder dialog box. The While expression specifies that the action affects records only as long as the logical expression is true. The first time the expression evaluates to false, the action ceases without considering remaining records.
Recall

Recalls records using the Scope, For, and While values.

See Also

Other Resources

Dialog Boxes
Delete Records Dialog Box
Expression Builder Dialog Box
RECALL Command
Scope Dialog Box


Rectangle/Line Dialog Box

Visual FoxPro 9.0
Rectangle/Line Dialog Box
See Also

Specifies position and output options for Rectangle and Line report controls.

This dialog box appears when you draw a rectangle or line on a report or label and then double-click it while it's selected.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

Print When

Displays the Print When dialog box so you can control exactly when the line or rectangle is printed in your report or label.

Object Position

Float

Specifies that the control moves down the page when a control that appears above it extends downward.
Fix Relative to Top of Band

Specifies that the control remain in position relative to the top of the band that contains it.
Fix Relative to Bottom of Band

Specifies that the control remain in position relative to the bottom of the band that contains it.

Stretch Downwards

No Stretch

Specifies that the bottom of the control does not expand vertically as the band stretches to display field data.
Stretch Relative to Tallest Object In Group

Specifies that the rectangle stretch to accommodate the tallest object in the group.
Stretch Relative to Height of Band

Specifies that the bottom of the control stretch vertically downward when the band stretches to accommodate data in Field controls.

Comment

Makes it possible for you to add comments to the .frx or .lbx file. Comments are for reference only and do not appear anywhere in the printed report or label.

See Also

Other Resources

Dialog Boxes
Print When Dialog Box
Round Rectangle Dialog Box
Report Picture Dialog Box
How to: Add Shapes and Lines to Forms


Remove Files from Source Control Dialog Box

Visual FoxPro 9.0
Remove Files from Source Control Dialog Box
See Also

Removes a file or selected files in your project from source code control.

Files to Remove

Lists the source-controlled files in your project.
Select All

Selects all files listed.

See Also

Other Resources

Dialog Boxes
Add Files to Source Control Dialog Box
Update Project List Dialog Box
Compiling Source Code


Rename File Dialog Box

Visual FoxPro 9.0
Rename File Dialog Box
See Also

Lets you rename the selected file.

This dialog box appears when you select Rename File from the Project menu.

Rename

Displays the selected file's current file name.
To

Displays the current file name, which can be replaced by typing a new name into the box.
Note:
Exercise care when renaming files. If you rename a table that is referenced in the DataEnvironment property of a form, that form will not be able to find the table. If you rename a class that has been added to a form, the form will not be able to locate the class.

See Also

Other Resources

Dialog Boxes
Project Manager
Description Dialog Box
New File Dialog Box
RENAME Command
DataEnvironment Property
RENAME TABLE Command


Replace Dialog Box

Visual FoxPro 9.0
Replace Dialog Box
See Also

This dialog box makes it possible for you to search for and replace specified text in the current file. To replace within tables, click Replace Field on the Table menu. The keyboard shortcut to access this dialog box is CTRL+L.

Look For

Specifies the text string to search for.
Replace With

Specifies the replacement text.
Options

Defines the limits and direction of the search and replace. If you specify text to search for and do not get the expected results, make sure you have the following options selected:
  • Match Case Replaces text that exactly matches the combination of uppercase and lowercase letters you type in the Look For box.

  • Wrap Around Searches the current file, from the insertion point to the end of the file, and then from the beginning of the file to the original insertion point.

  • Match Whole Word Replaces distinct occurrences of words, except for embedded text.

  • Search Backward Searches backwards from the current insertion point to the beginning of the file.

  • Use wildcards Makes it possible for you to use wildcard characters in your search text.

Scope

Defines how extensive the search is. The Scope options are enabled when you are editing a procedure in a Code window.
  • Current Procedure Searches only the current procedure, which is displayed in the Code window.

  • Current Object Searches all procedures (event code) in the current (selected) object.

  • All Objects Searches all procedures (event code) in all objects in the current form or form set.

Find Next

Finds the next occurrence of the string you typed in the Look For box. This button is not enabled until you type text in the Look For box.
Replace

Changes the selected text to the text in the Replace With box. If you want to leave the selected text unchanged and move to the next occurrence, click Find Next.
Replace All

Finds and replaces all instances of the text in the Find What box with the text in the Replace With box. You can undo the replacements by choosing the Undo command.

See Also

Other Resources

Dialog Boxes
Find Dialog Box
Go To Line Dialog Box
Replace Field Dialog Box
Code Window
Insert Object Dialog Box


Replace Field Dialog Box

Visual FoxPro 9.0
Replace Field Dialog Box
See Also

Changes values stored in one record or in a range of records.

Field

Displays the name of table fields from the current table. When you click the down arrow, the types and sizes of fields are displayed.
With

Specifies the expression that describes the replacement values. Type the expression or choose the dialog button to display the Expression Builder dialog box and create a replacement expression.

Replacement Criteria

Scope

Allows you to specify the records on which Visual FoxPro is to act. Next, All, Record or Rest from the drop-down list. Choose a number from the spinner on the right when you select Next or Record from the Scope drop-down list.
For

Displays the Expression Builder dialog box, where you create the logical expression that every record must meet to be affected by the command. Every record in the table is tested using the For expression.
While

Displays the Expression Builder dialog box. The While expression specifies that the action affects records only as long as the logical expression is true. The first time the expression evaluates to false, the action ceases without considering remaining records.
Replace

Replaces records using the Scope, For, and While values. Enabled only when you have a field name or expression in both the Field and With text boxes.

See Also

Other Resources

Dialog Boxes
Expression Builder Dialog Box
REPLACE Command
Scope Dialog Box
Recall (Records) Dialog Box
Delete (Records) Dialog Box


Report and Label Print Options Dialog Box

Visual FoxPro 9.0
Report and Label Print Options Dialog Box
See Also

Specifies print options for reports and labels.

This dialog box appears when clicking Options in the Print Options dialog box. For more information, see Print Options Dialog Box.

Scope

Specifies the range of records to print. When selecting Next or Record in the Scope list, type or select a number in the spin box to specify the next number of records or a record number. The settings available for the Scope setting are the following:
  • All Print every record from the source file.

  • Next Print a range of records starting with 1.

  • Record Print a specific record number.

  • Rest Print the current record and all of those after it until the end of the file.

For

Specifies a logical expression that must be true for records to include for printing. To build an expression, click the ellipsis (…) button to open the Expression Builder dialog box.
Tip:
Do not include the FOR command in the expression. For example, you can specify country = "Canada" to see only Canadian data.

While

Specifies a logical expression that must be true to continue printing records. To build an expression, click the ellipsis (…) button to open the Expression Builder dialog box.
Tip:
Do not include the WHILE command in the expression. For example, you can specify sales > 1000 to see only sales greater than one-thousand dollars.

See Also

Other Resources

Dialog Boxes
Expression Builder Dialog Box


Report Band Properties Dialog Box

Visual FoxPro 9.0
Report Band Properties Dialog Box
See Also

Makes it possible for you to set properties and options for a band in a report or label page layout.

This dialog box appears when you choose Properties from the context menu of a report band separator; when you double-click on a report band separator; or when you double-click on the band name in the Edit Bands Dialog Box.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

Report band layout options

Height

Specifies the height of the band. The report band height determines the amount of space each report band uses on the page within the page margins. When selecting a height value by clicking the Height arrows, values change in increments of .05 in the measurement unit set for the ruler/grid. For more information, see How to: Configure the Page Layout Grid for Reports. For example, if the Title band is set at half an inch, information in the Title band appears in the first half inch of the page after the top margin.
Tip:
When adding items to a report band, you might need to change the report band height to accommodate its contents. As a guide to determine the height, use the ruler to the left of the band. The ruler's measurement is specific to the height of the band and does not include the page margins.

Note:
When reducing the height of a band, you cannot make a band shorter than the height of the controls in the layout. If controls in the band prevent you from resizing the band, move the controls in the band and then reduce the height.

Constant band height

Prevents the band from stretching to fit lengthy data or adjusting for blank lines that have been removed.

Run expression

Specifies expressions to evaluate when processing the report band.

On entry

Specifies an expression to evaluate before processing the band. To build an expression, click the ellipsis (…) button to open the Expression Builder. For more information, see Expression Builder Dialog Box.
On exit

Specifies an expression to evaluate after processing the band. To build an expression, click the ellipsis (…) button to open the Expression Builder. For more information, see Expression Builder Dialog Box.

Detail Band Properties

Specifies options for the Detail band or Detail band set. A Detail band set includes its associated header and footer bands, if they have been specified.

Important
The options listed above Target alias in the following group do not apply unless you specify at least one of the detail band conditions new in Visual FoxPro 9: the band set must include a header and footer, or it must have an assigned target alias, or there must be more than one detail band in the report. If none of these conditions exist, the report runs in backward compatibility mode and these options, which in previous versions applied only to group bands, are not evaluated for the report's detail band.

Start on a new column

Starts a new column when the Detail band set changes. Selecting this check box makes it possible for you to create side-by-side Detail bands. Available only when the page layout contains more than one column.
Note:
Column breaks occur before the Detail Header band, if any exist.

Start on a new page

Starts a new page when the Detail band set changes.
Note:
Page breaks occur before the Detail Header band, if any exist.

Reset page number to 1 for each detail set

Starts a new page and restarts page numbering every time the detail band set changes.
Detail Header/Footer

Specifies that separate Detail Header and Detail Footer bands exist for the detail band, comprising a detail band set.
Reprint detail header on each page

Specifies that the Detail Header follow the Page Header on all pages for the Detail band when the Detail band spans more than one page.
Start detail set on new page when less than

Sets the minimum distance from the page bottom that must be available to prevent a detail band set from being forced to render on a new page.
Target alias

Specifies a target alias expression for the Detail band. To build an expression, click the ellipsis (…) button to open the Expression Builder. For more information, see Expression Builder Dialog Box.
Note:
Remember to enclose a simple table name or cursor alias in quotation marks ("") to ensure the expression evaluates correctly. Values without quotation marks will be interpreted as a variable or field containing the alias value.

Refer to How to: Specify Target Aliases for Detail Bands and Working with Related Tables using Multiple Detail Bands in Reports. for more information.

See Also

Concepts

Working with Related Tables using Multiple Detail Bands in Reports

Other Resources

Report Bands
Working with Report Bands
Dialog Boxes


Report Band Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Report Band Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to set properties and options for a Band in a report or label page layout in the Report Designer or Label Designer.

This dialog box appears when you choose Properties from the context menu of a report band separator, when you double-click on a report band separator, or when you double-click on the band name in the Edit Bands Dialog Box.

Note:
This dialog box is only displayed if the _REPORTBUILDER system variable is set to the default Report Builder application. If it is empty, or has been set to a third-party report builder, the native Visual FoxPro dialog box (or a third-party dialog box) may appear. For more information, see _REPORTBUILDER System Variable .

The following table lists each of the tabs that exist in the Report Band Properties dialog box. Some tabs may only be present for specific types of bands.

Note:
When modifying the report or label in protected mode, some or all tabs might not be available as specified by protection mode settings.

Tab | Description
General Tab, Report Band Properties Dialog Box (Report Builder) | Makes it possible for you to change the report band height, control whether the report band expands or contracts to fit data or adjust for suppressed blank lines, and expressions to evaluate before or after processing the band.
Band Tab, Report Band Properties Dialog Box (Report Builder) | (Detail bands only) Allows you to specify how a Detail band is processed at run time.
Data Grouping Tab, Report Properties Dialog Box (Report Builder) | (Group Header and Group Footer bands only.) Makes it possible for you to create and specify how the data is grouped within the report or label layout.
Protection Tab, Report Band Properties Dialog Box (Report Builder) | Makes it possible for you to set protection options for a report band in the Report Designer or Label Designer that restrict the user from making changes when modifying the layout in protected mode.
Other Tab, Report Band Properties Dialog Box (Report Builder) | Allows you to add comments and user data to a report band in the Report Designer or Label Designer.

See Also

Other Resources

Working with Report Bands
Dialog Boxes (Visual FoxPro)


General Tab, Report Band Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
General Tab, Report Band Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to specify general options for report bands in the Report Designer or Label Designer.

Note:
This tab replaces the functionality of the native Visual FoxPro Report Band Properties Dialog Box when the Report Builder is active.

  • How to: Change Report Band Height

  • How to: Specify Expressions to Evaluate When Processing Bands

  • How to: Configure Output for Report Bands

Band options

The following options allow you to specify the formatting and behavior of report bands.

Group expression

(Group Header and Group Footer bands only) Specifies the expression used by the report engine to determine when to "break" from detail band rendering. The group header and footer information is rendered each time the result of the expression changes. Empty expressions are not valid. You can type or build an expression by clicking the ellipsis (…) button. For more information, see Expression Builder Dialog Box.
Height

Specifies the height of the band. The report band height determines the amount of space each report band uses on the page within the page margins. The units of this spinner control depend on the setting of measurement ruler units for the report layout. For more information, see How to: Configure the Page Layout Grid for Reports. For example, if the title band is set at half an inch, information in the title band appears in the first half inch of the page after the top margin.
Tip:
When adding items to a report band, you might need to change the report band height to accommodate its contents. As a guide to determine the height, use the ruler to the left of the band. The ruler's measurement is specific to the height of the band and does not include the page margins.

Note:
When reducing the height of a band, you cannot make a band shorter than the height of the controls in the layout. If controls in the band prevent you from resizing the band, move the controls in the band and then reduce the height.

Constant band height

Prevents the band from stretching to fit lengthy data or adjusting for suppressed blank lines. For more information, see How to: Suppress Blank Lines in Report Controls.

Run expression

Specifies expressions to evaluate before and after processing the report band.

On entry

Specifies an expression to evaluate before processing the band. To build an expression, click the ellipsis (…) button to open the Expression Builder. For more information, see Expression Builder Dialog Box.
On exit

Specifies an expression to evaluate after processing the band. To build an expression, click the ellipsis (…) button to open the Expression Builder. For more information, see Expression Builder Dialog Box.

See Also

Reference

Report Band Properties Dialog Box (Report Builder)

Other Resources

Working with Report Bands


Band Tab, Report Band Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Band Tab, Report Band Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to set options for a Detail band in the Report Designer or Label Designer.

Note:
This tab replaces the functionality of the native Visual FoxPro Report Band Properties Dialog Box when the Report Builder is active.

  • How to: Configure Output for Report Bands

  • How to: Specify Target Aliases for Detail Bands

Detail properties

Specifies options for the Detail band or Detail band set. A Detail band set includes its associated header and footer bands, if they have been specified.

Important
The options listed above Target alias expression in the following group do not apply unless you specify at least one of the detail band conditions new in Visual FoxPro 9: the band set must include a header and footer, or it must have an assigned target alias, or there must be more than one detail band in the report. If none of these conditions exist, the report runs in backward compatibility mode and these options, which in previous versions applied only to group bands, are not evaluated for the report's detail band.

Start on new column

Starts a new column when the Detail band set changes. Selecting this check box makes it possible for you to create side-by-side Detail bands. Available only when the page layout contains more than one column.
Note:
Column breaks occur before the Detail Header band, if any exist.

Start on new page

Starts a new page when the Detail band set changes.
Note:
Page breaks occur before the Detail Header band, if any exist.

Reset page number to 1 for each detail set

Starts a new page and restarts page numbering every time the detail band set changes.
Associated header and footer bands

Specifies that separate Detail Header and Detail Footer bands exist for the detail band, comprising a detail band set.
Reprint detail header on each page

Specifies that the Detail Header follow the page header on all pages for the Detail band when the Detail band spans more than one page.
Start detail set on new page when less than

Sets the minimum distance from the page bottom that must be available to prevent a Detail band set from being forced to render on a new page.
Target alias expression

Specifies a target alias expression for the Detail band. To build an expression, click the ellipsis (...) button to open the Expression Builder. For more information, see Expression Builder Dialog Box.
Note:
Remember to enclose a simple table name or cursor alias in quotation marks ("") to ensure the expression evaluates correctly. Values without quotation marks will be interpreted as a variable or field containing the alias value.

Refer to How to: Specify Target Aliases for Detail Bands and Working with Related Tables using Multiple Detail Bands in Reports for more information.

See Also

Reference

Report Band Properties Dialog Box (Report Builder)

Concepts

Working with Related Tables using Multiple Detail Bands in Reports

Other Resources

Working with Report Bands


Protection Tab, Report Band Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Protection Tab, Report Band Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to restrict certain actions for a report band in the Report Designer or Label Designer, preventing the user from changing the band when modifying the report or label in protected mode. For more information, see Setting Protection for Reports.

  • How to: Protect Report Bands

When in PROTECTED mode

Specifies protection options for the report band.

Band cannot be resized

Specifies that users cannot resize the report band when modifying the report or label in protected mode. The Band cannot be resized check box is currently unavailable.
Properties dialog box is not available

Specifies that users cannot change properties of the band when modifying the report or label in protected mode.

See Also

Reference

Protection Tab, Report Control Properties Dialog Box (Report Builder)
Protection Tab, Report Properties Dialog Box (Report Builder)
Report Band Properties Dialog Box (Report Builder)


Other Tab, Report Band Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Other Tab, Report Band Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to add comments and user data for a report band in the Report Designer or Label Designer.

  • How to: Add Comments to Report Bands

  • How to: Add User Data to Report Bands

Edit comment

Opens a Comment dialog box so that you can add or edit comments for the report band.
Note:
Comments are stored in the COMMENTS memo field of the report structure table and are not used by the report engine by default. However, the COMMENTS field is available for use by ReportListener subclasses.

Edit user data

Opens a User data dialog box so that you can add or edit user-defined data for the report band.
Note:
User data is not visible and cannot be changed when modifying a report layout in protected mode.

Note:
User data is stored in the USER memo field of the report structure table and is not used by the report engine by default. However, the USER field is available for use by ReportListener subclasses.

See Also

Reference

Report Band Properties Dialog Box (Report Builder)


Report Builder Debug Event Dialog Box (Report Builder)

Visual FoxPro 9.0
Report Builder Debug Event Dialog Box (Report Builder)
See Also

Handles Label or Report Designer events with a comprehensive dialog box that allows you to explore the contents of the FRX cursor and decide how to set the return flags to control the designer's response.

The Debug Handler form displays the contents of the FRX cursor using the same basic layout as the FRX Cursor Browser dialog box, but with some additional controls:

Event Details

Displays a MESSAGEBOX() dialog box containing the contents of the parameters passed to the Report Builder from the designer. See Understanding Report Builder Events for more information on report builder parameters.
Options

Displays the report builder's Options dialog box.
FRX Changes

Controls the setting of Bit 1 of the ReturnFlags parameter:
  • Save will instruct the designer to reload the changes in the FRX cursor into the report layout.

  • Discard will instruct the designer to discard any changes.

Native Behavior

Controls the setting of Bit 0 of the ReturnFlags parameter:
  • Allow will instruct the designer to continue responding to the event as though the Report Builder was not active.

  • Suppress will instruct the designer to ignore the event.

Continue

Dismisses the Debug Handler dialog and returns control to the designer.

See Also

Tasks

How to: Configure the Report Builder's Event Handling

Reference

Report Builder Options Dialog Box (Report Builder)
FRX Cursor Browser Dialog Box (Report Builder)


Report Builder Options Dialog Box (Report Builder)

Visual FoxPro 9.0
Report Builder Options Dialog Box (Report Builder)
See Also

Allows you to specify how the Report Builder responds to events in the Report Designer.

  • How to: Configure the Report Builder's Event Handling

  • How to: Specify an Alternate Report Event Handler Table

  • How to: Add Your Own Handler to the Report Builder's Registry

Report Designer event handling

Specifies how the Report Builder will respond to events in the Report Designer.
Handler Registry Table

Specifies whether or not the Report Builder uses its internal lookup table or an external, alternative customizable table. The textbox will contain the fully qualified file name of the current report builder event handler registry table. Click the ellipsis (…) to display a file chooser dialog box to select an alternate event handler registry table. This setting will not persist between sessions of Visual FoxPro.
Create copy

Prompts for a file name and location into which will be placed a copy of the default, internal event handler registry table, that is ready for customization.
Registry Explorer

Displays the Event Handler Registry Dialog Box (Report Builder).
Close

Closes the Report Builder Options dialog box.

See Also

Reference

Event Handler Registry Dialog Box (Report Builder)
_REPORTBUILDER System Variable

Other Resources

Report Layout and Design


Event Handler Registry Dialog Box (Report Builder)

Visual FoxPro 9.0
Event Handler Registry Dialog Box (Report Builder)
See Also

Allows you to browse the Report Builder's current event handler registry table. If the Report Builder is using its internal registry table, then this dialog box is read-only, and you will not be able to customize the settings.

When the Report Builder has been configured to use an external registry table, the grid becomes editable and you may customize the behavior of the Report Builder for each individual Report Designer event.

Make sure that you have read and understood the Report Builder Event Handler Registry Table topic before you make changes to the table.

  • How to: Add Your Own Handler to the Report Builder's Registry

Grid

Displays the current Report Designer event handler registry table for editing. This will be read-only unless the Report Builder How to: Specify an Alternate Report Event Handler Table.

Type

Specifies the Handler Type. Valid values are H,F,X,G,E.
Class

Specifies the class name.
Library

Specifies the class library file. This can be a visual (.vcx) or non-visual (.prg) filename.
Description

Allows miscellaneous notes to be entered against each record. Not used by the Report Builder.
Event

Specifies the event type that the handler class is registered to. Use a value of -1 to represent a "wild card" match.
Objtype

Specifies the value of OBJTYPE that the handler class is registered to. Use a value of -1 to represent a "wild-card" match.
Objcode

Specifies the value of OBJCODE that the handler class is registered to. Use a value of -1 to represent a "wild-card" match.
Native

Specifies that, for this event type and object type combination, the Report Builder will not intercept the event but will pass it back to the Designer for "normal" processing.
Note:
This is not the same as deleting the record from the table. You can use this to force native event handling for a specific event/object, even if more generic/wild-card matches are registered.

Debug

Specifies that, for this event type and object type combination, the Report Builder will use the DebugHandler class rather than that specified by the Class and Library columns.

Add Record

Appends a record to the current event handler registry table and highlights it in the grid, ready for editing. This option will be disabled if the event lookup table is read-only. This is true when the Report Builder's internal lookup table is being used by default.

See Also

Reference

Report Builder Options Dialog Box (Report Builder)

Concepts

Understanding Report Builder Events


Report Control Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Report Control Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to set options for report controls on your report layout.

This dialog box appears when you choose Properties from the context menu of a report control, or when you double-click a report control.

Note:
This dialog box is only displayed if the _REPORTBUILDER system variable is set to the default Report Builder application. If it is empty, or has been set to a third-party report builder, the native Visual FoxPro dialog box (or a third-party dialog box) may appear. For more information, see _REPORTBUILDER System Variable .

The following table lists the tabs that exist in the Report Control Properties dialog box and are available as appropriate.

Note:
When modifying the report or label in protected mode, some or all tabs might not be available as specified by protection mode settings.

Tab | Description
General Tab, Report Control Properties Dialog Box (Report Builder) | Makes it possible for you to set general options for report controls in the Report Designer or Label Designer.
Style Tab, Report Control Properties Dialog Box (Report Builder) | (Label, Field, Line, and Shape controls only.) Makes it possible for you to set style options for report controls in the Report Designer or Label Designer.
Format Tab, Report Control Properties Dialog Box (Report Builder) | (Label and Field controls only.) Makes it possible for you to specify format expressions for output generated from Field report controls in the Report Designer or Label Designer.
Print When Tab, Report Control Properties Dialog Box (Report Builder) | Makes it possible for you to specify whether to repeat display of report controls or values in output for reports and labels.
Calculate Tab, Report Control Properties Dialog Box (Report Builder) | (Field controls only.) Makes it possible for you to specify a calculation to perform on Field control expressions and display the calculation results instead of the expression. You can also specify the point at which to reset the calculation in the report.
Protection Tab, Report Control Properties Dialog Box (Report Builder) | Makes it possible for you to set protection options for a report control that prevent the user from changing the control in the Report Designer or Label Designer when modifying the report or label in protected mode.
Other Tab, Report Control Properties Dialog Box (Report Builder) | Makes it possible for you to add comments, user data, and code elements that you can run using ReportListener objects for report controls in the Report Designer or Label Designer.

See Also

Other Resources

Working with Report Controls
Dialog Boxes (Visual FoxPro)


General Tab, Report Control Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
General Tab, Report Control Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to set general options for report controls in the Report Designer or Label Designer.

Note:
This tab replaces the functionality of a number of native Visual FoxPro dialog boxes when the Report Builder is active.

  • How to: Add Field Controls to Reports

  • How to: Specify Expressions in Field Controls

  • How to: Add Label Controls to Reports

  • How to: Add Pictures to Reports

  • How to: Add General Fields to Reports

Caption

(Label controls only) Specifies label text. Clicking the ellipsis (…) button opens an editing dialog box so that you can view and edit the entire text for the Label control.
Expression

(Field controls only) Specifies an expression, such as the name of a variable or table field. The expression is evaluated at report run time as the report engine renders output from the Field control. Clicking the ellipsis (…) button opens the Expression Builder so that you can build an expression. For more information, see Expression Builder Dialog Box.

Control source type

(Picture/OLE Bound controls only) Specifies the source for a Picture/OLE Bound report control. Valid sources include the name of an image file, the name of a General field in a table, or an expression or variable that contains a file name or non-General character field for the report control. For more information, see How to: Add Pictures to Reports, and How to: Add General Fields to Reports.

Image file name

Specifies that the control source should contain a literal image file name.
Important
Do not enclose the file name in quotation marks ("").

General field name

Specifies that the control source should evaluate to the name of a table or cursor's General field.
Expression or variable name

Specifies that the control source should be an expression or variable that evaluates to:
  • An image filename.

  • A non-General character field.

  • A string literal containing an explicit file name.

  • An object reference to a form Image object that has its PictureVal property set appropriately.

    Tip:
    The use of an Image object's PictureVal property as a image source in a report is only supported in object-assisted output mode. It will work in backward-compatible mode, in some cases, but results are not guaranteed. For example, in backward-compatible mode, Picture/OLE Bound controls with this source may not respect the Clip sizing option. For more information, see SET REPORTBEHAVIOR Command.

Control source

(Picture/OLE Bound controls only) Specifies a string, expression or variable name that evaluates to the source of the Picture/OLE Bound control. Clicking the ellipsis (...) button performs a different action depending on the value of the Control source type:

  • Image file name

    Displays the Open dialog box so you can select a file. For more information, see Open Dialog Box.

  • General field name

    Opens the Expression Builder so that you can select a General field. For more information, see Expression Builder Dialog Box, and General Field Type.

  • Expression or variable name

    Opens the Expression Builder so that you can build an expression or select a variable. For more information, see Expression Builder Dialog Box.

If source and frame are different sizes

(Picture/OLE Bound controls only) Specifies how the control should be displayed when the dimensions of the control do not match the default size of the control source:

  • Clip picture (Default)

    The rendered output of the control source always appears anchored at the upper left corner of the control frame.

    If the control source is larger than the frame, only the upper left region of the control source that fits inside the dimensions on the control is displayed.

    If the control source is smaller than the control outline, the control will resize to fit, or remain transparent in the area not covered by the rendered control source.

  • Scale picture, retain shape

    The rendered output of the control is displayed reduced in size so that the largest dimension fits inside the constraints of the frame of the control. The rendered output retains its relative proportions.

    Tip:
    This option protects the picture or General field from vertical or horizontal distortion.

  • Scale picture, fill the frame

    The rendered output of the control is scaled to completely fill the dimensions of the control frame, stretching it vertically or horizontally as necessary.

    Note:
    This setting might cause vertical or horizontal distortion

Center general field horizontally in frame

(Picture/OLE Bound controls only) Centers the General field when it is smaller than the frame that contains it. Otherwise, the General field displays in the upper-left corner of the frame.

Object position

Specifies position settings for the report control.

Float

Specifies that the control moves down the page when a control that appears above it extends downward.
Fix relative to top of band

Specifies that the control remain in position relative to the top of the band that contains it.
Fix relative to bottom of band

Specifies that the control remain in position relative to the bottom of the band that contains it.

Stretch with overflow

(Field controls only) Specifies that the bottom of a Field control is extended vertically down the page to contain the full value of the evaluated expression.

Stretch downwards

(Rectangle controls only) Specifies how a rectangle control should change its shape as the evaluated content of a band forces the band to extend.

No stretch

Specifies that the bottom of the Rectangle control does not expand vertically as the band stretches to accommodate data in Field controls.
Stretch relative to tallest object in group

Specifies that the bottom of the Rectangle control stretch vertically to adjust to the tallest object in the group.
Stretch relative to height of band

Specifies that the bottom of the Rectangle control stretch vertically downward when the band stretches to accommodate data in Field controls.

Size and position in layout

Specifies positioning and size for the report control in the Report Designer.

From page top

Specifies a value from the top of the page to position the report control.
From left

Specifies a value from the left of the page to position the report control.
Height

Specifies a value for the height of the report control.
Width

Specifies a value for the width of the report control.

See Also

Reference

Report Control Properties Dialog Box (Report Builder)


Style Tab, Report Control Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Style Tab, Report Control Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to set style options for report controls in the Report Designer or Label Designer. As you change style settings for the report control, you can view those changes in the Sample area.

Note:
This tab complements the functionality provided by the Visual FoxPro Report Designer Format menu when the Report Builder is active. Some features are still only available from the Format menu.

  • How to: Change Line Styles of Report Controls

  • How to: Change Colors in Report Controls

  • How to: Change Font Settings in Report Controls

  • How to: Change Opacity of Report Controls

Font

(Label and Field controls only) Specifies the font settings for text controls. Clicking the ellipsis (…) button opens the Font dialog box so that you can select a different font.

Use Font Script

Indicates that the language font script specified in the Script combobox of the Font dialog box will be saved with the report. When you select a default font from the Font dialog box, the font script selection will be saved by default. You can choose not to save the specific font script selection with the layout by clearing this check box. For more information, see Font Dialog Box.
Strikethrough

Specifies that the control output text will be crossed through with a horizontal line.
Underline

Specifies that the control output text will be underlined.

Pen style

(Line and Rectangle controls only) Allows you to change rendering options for shapes and lines.

Style

Specifies the line style for a Line or Rectangle report control.
Weight

Specifies the line width for a Line or Rectangle report control.
Note:
Any line style selection other than Normal (solid line) will force a line weight of 1 point and this option will be disabled.

Curvature

  • (Rectangle controls only) Specifies curvature of a Rectangle/Shape control. 0-98 is varying degrees of roundedness, and 99 results in an oval shape rather than a rectangle. A curvature setting of 16 is the default for a new Rounded Rectangle control. For more information, see Curvature Property.

Color

Specifies color settings for the report control.

Use default foreground (pen) color

Specifies whether to use the default foreground color. Clearing this check box allows you to click the ellipsis (…) button to open the Color Picker dialog box.
Use default background (fill) color

Specifies whether to use the default background color. Clearing this check box allows you to click the ellipsis (…) button to open the Color Picker dialog box.

Backstyle

Specifies whether objects that appear behind a report control are visible.

Important
Rectangle controls only respect Backstyle if they have been assigned a Fill Pattern. Empty rectangles are always transparent, and solid rectangles are always opaque.

Opaque

Specifies that objects appearing behind the report control are not visible.
Transparent

Specifies that objects appearing behind the report control are visible.

Sample

Displays an approximate example of your selected style options as you make changes.

See Also

Reference

Report Control Properties Dialog Box (Report Builder)


Format Tab, Report Control Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Format Tab, Report Control Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to specify format expressions for output generated from Field report controls in the Report Designer or Label Designer. For more information, see Format Expressions for Field Controls., and TRANSFORM( ) Function.

Note:
This tab replaces the functionality of the native Visual FoxPro Format (Field) Dialog Box when the Report Builder is active.

  • How to: Specify Data Types for Field Controls

  • How to: Set Alignment of Report Control Contents

General formatting options

Format expression

Specifies a format expression, which can include format codes and format template characters, instead of selecting options from the Format options group.
Character

Specifies that the output from the Field report control has Character type and displays the appropriate options in the Format options group.
Numeric

Specifies that the output from the Field report control has Numeric type and displays the appropriate options in the Format options group.
Date

Specifies that the output from the Field report control has Date type and displays the appropriate options in the Format options group.

Data type-specific formatting options

Displays format options available depending on the data type selected.

Template characters

Determines how additional format templates display with output of Character type:
  • Overlay

    Specifies that additional characters in the format template function replace output from the Field report control.

  • Interleave

    Specifies that additional characters in the format template characters display with output from the Field report control.

For example, suppose a record in the underlying table contains the characters ABC1234, and you specify the format template NNN-NNNN. Choosing Overlay displays ABC1234 as ABC-234; while choosing Interleave displays ABC1234 as ABC-1234.
To upper case

Displays output with Character type in uppercase characters.
SET DATE format

Specifies that output appear as a date using the current format setting of the SET DATE command. For more information, see SET DATE Command.
British date

Displays output as a date in British date format. For more information, see SET DATE Command.
Blank if empty

Does not display output with Date types that are empty.
Justification

Specifies that output with Character type use one of the following text alignment settings:
  • Left

    Aligns output with the leftmost position in the Field control.

  • Right

    Aligns output with the rightmost position in the Field control.

  • Center

    Aligns output with the center of the Field control.

Left justify

Aligns output with Numeric type with the leftmost position in the Field control.
Blank if zero

Does not display output with Numeric type that consists only of zeroes.
(Negative)

Displays and encloses negative values in output with Numeric type with parentheses (()).
CR if positive

Displays and follows positive values in output with Numeric type with the text, "CR (credit)".
DB if negative

Displays and follows negative values in output with Numeric type with the text, "DB (debit)".
Leading zeros

Displays all leading zeroes in output with Numeric type.
Currency

Displays output with Numeric type using the currency format specified on the Regional tab in the Options dialog box. For more information, see Regional Tab, Options Dialog Box.
Scientific

Displays output with Numeric type in scientific notation, which can be useful for very large or small numbers.
Trim mode for character expressions

Specifies how character expressions that have insufficient rendering room in the field expression control are trimmed. Possible values are:
  • Default (as in earlier versions of Visual FoxPro)

  • Trim to nearest character

  • Trim to nearest word

  • Trim to nearest character, append ellipsis

  • Trim to nearest word, append ellipsis

  • Trim "filespec" style with an intermediate ellipsis

Refer to the Using GDI+ in Reports topic for more information on string trimming options.

See Also

Reference

Report Control Properties Dialog Box (Report Builder)
TRANSFORM( ) Function

Concepts

Format Expressions for Field Controls


Print When Tab, Report Control Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Print When Tab, Report Control Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to set options that suppress the rendering of output from report controls under various conditions.

Note:
This tab replaces the functionality of the native Visual FoxPro Print When Dialog Box when the Report Builder is active.

  • How to: Suppress Repeated Values for Report Controls

  • How to: Suppress Blank Lines in Report Controls

  • How to: Specify Conditional Output for Report Controls

Print repeated values

Specifies whether the report engine tracks changes between successive values of the report control's output and renders only when the value changes.

Yes

Render output for the control every time the band is processed by the report engine.
No

Render output for the control only if the value is different from the last time the control output was evaluated.

Also print

Specifies additional conditions for repeating report control values.

In first whole band of a new page/column

Specifies that the control output should be rendered if the band that contains it is rendering for the first time on a new page or column, overriding the setting of Print repeated values. For more information, see Working with Report Bands.
When this data group expression changes

Specifies that the control output should be rendered if a specific data group expression evaluates to a different value, overriding the setting of Print repeated values. For more information, see Working with Report Data Groups.
When band content overflows to new page/column

Specifies that the report control output be rendered when the band that contains it overflows to a new page or column.

Additional options

The following additional options make it possible for you to suppress blank lines and control output for report controls and data in report controls.

Remove line if blank

Specifies that the report engine may contract the report band vertically if the evaluation of the report control results in no renderable content, and no other renderable controls occupy the empty space on either side of the control.
Print only when expression is true

Specifies a logical expression that the report engine evaluates in order to decide whether to render output for the report control.
Note:
When you add an expression to the Print only when expression is true box, all other options in the Print When dialog box become unavailable except the Remove line if blank box.

See Also

Reference

Report Control Properties Dialog Box (Report Builder)


Calculate Tab, Report Control Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Calculate Tab, Report Control Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to specify a calculation to perform on Field control expressions and display the calculation results instead of the expression. You can also specify the point at which to reset the calculation in the report.

Note:
This tab replaces the functionality of the native Visual FoxPro Calculate Field Dialog Box when the Report Builder is active.

How to: Perform Calculations in Field Controls

Calculation type

Specifies additional calculation operations that can be applied to the values of a Field control expression to obtain the value rendered in the output:

Note:
Cumulative calculations are reset depending on the Reset value based on option.

  • None (Default)

    No additional calculations are performed. The result of the Field expression is directly passed to the report engine for output.

  • Count

    The value displayed is a count of the number of times the expression has been evaluated for the records traversed thus far. (The Field expression is not evaluated.)

  • Sum

    The value displayed is a running total of the values of the Field expression for the records traversed thus far.

  • Average

    Computes the arithmetic mean of the value of the Field expression for each record traversed thus far and displays the results.

  • Lowest

    The value displayed is the lowest value of the Field expression evaluated for the records traversed thus far.

  • Highest

    The value displayed is the highest value of the Field expression evaluated for the records traversed thus far.

  • Std Deviation

    Computes the square root of the variance of the evaluated Field expression for each record traversed thus far and displays the results.

  • Variance

    Measures the degree to which the evaluated Field expression value varies from the average for the records traversed thus far and displays the result.

Reset based on

Specifies the point at which to reset any cumulative calculations. The default value is "End of Report."

Note:
If you have specified data groups in the report, Detail bands, or target alias expressions for Detail bands, the Reset based on list displays those items.

See Also

Reference

Report Control Properties Dialog Box (Report Builder)


Protection Tab, Report Control Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Protection Tab, Report Control Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to set restrictions on selected actions for a report control in the Report Designer or Label Designer, preventing the user from changing the control when modifying the report or label in protected mode. For more information, see Setting Protection for Reports.

  • How to: Protect Report Controls

When in PROTECTED mode

Specifies protection options for the report control.

Object cannot be moved or resized

Specifies that users cannot move or resize the report control when modifying the report or label in protected mode.
Properties dialog box is not available

Specifies that users cannot edit the report control when modifying the report or label in protected mode.
Objects cannot be deleted

Specifies that users cannot delete the report control when modifying the report or label in protected mode.
Objects cannot be selected

Specifies that users cannot select the report control when modifying the report or label in protected mode.
Object is not visible in Designer

Specifies that the report control is not visible in the designer when modifying the report or label in protected mode.
Design-time caption

(Field controls only) Specifies a text string that is displayed in the Field control instead of the Field Expression when modifying the layout in protected mode.

See Also

Reference

Protection Tab, Report Band Properties Dialog Box (Report Builder)
Protection Tab, Report Properties Dialog Box (Report Builder)
Report Control Properties Dialog Box (Report Builder)


Other Tab, Report Control Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Other Tab, Report Control Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to add comments, user data, tooltips, and code elements that you can leverage at report run time for report controls in the Report Designer or Label Designer.

  • How to: Add Comments to Report Controls

  • How to: Add User Data to Report Controls

  • How to: Add Tooltips to Report Controls

Edit comment

Opens the Comment dialog box so that you can add or edit comments for the report control.
Note:
Comments are stored in the COMMENTS memo field of the report structure table and are not used by the report engine by default. However, the COMMENTS field is available for use by ReportListener subclasses.

Edit user data

Opens the User data dialog box so that you can add or edit user-defined data for the report control.
Note:
User data is not visible and can not be changed when modifying a report layout in protected mode.

Note:
User data is stored in the USER memo field of the report structure table and is not used by the report engine by default. However, the USER field is available for use by ReportListener subclasses.

Edit tooltip

Opens a Tooltip dialog box so that you can add or edit tooltip text that will appear in the report layout as you point to the report control with the mouse.
Edit settings

Opens a Run-time extensions dialog box so that you can add or edit arbitrary code resources to the report control.

See Also

Reference

Run-time Extensions Dialog Box (Report Builder)
Report Control Properties Dialog Box (Report Builder)


Run-time Extensions Dialog Box (Report Builder)

Visual FoxPro 9.0
Run-time Extensions Dialog Box (Report Builder)
See Also

Makes it possible for you to assign code elements and expressions to a report control that you can leverage at report run time.

  • How to: Assign Structured Metadata to Report Controls

Run-time extensions

Specifies arbitrary code that ReportListener objects can execute.
Execute when

Specifies an expression that ReportListener objects can evaluate to determine whether to run the extensions. Clicking the ellipsis (…) button opens the Expression Builder so you can build an expression. For more information, see Expression Builder Dialog Box.

See Also

Reference

ReportListener Object
Other Tab, Report Control Properties Dialog Box (Report Builder)

Concepts

Report XML MemberData Extensions


Report Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Report Dialog Box (Visual FoxPro)
See Also

Displays the results of your query as a report layout. This dialog box appears on the Miscellaneous tab of the Query Designer and is available only for queries. For more information, see Miscellaneous Tab, Query and View Designers.

Note:
You must have previously set up a report file (.frx) that accommodates the fields of output in the query. For more information, see Working with Reports.

Open Report

Displays the Open dialog box for you to select a report file to use for your query. You can click the button or type the file name in the text box.
Wizard Icon

Displays the Wizard Selection dialog box, from which you can choose a report wizard to run.
Page Preview

Displays the output in the Page Preview window.
Console On

Displays the output in the active output window.
Eject Page Before Report

Prints a blank page at the beginning of the report to separate documents at the printer.

Secondary Output

None

Specifies that the output not be sent to the printer or saved as a text file.
To Printer

Sends the results of the query to the printer.
To Text File

Saves the results of the query as a text file. Click the button to select an existing file that you want to overwrite, or type the name of a new file in the text box.

Options

Suppress Column Headings

Keeps column headings from appearing at the top of the output.
Summary Information Only

Suppresses detail line printing. The report produced includes the headings, footers, totals, and so on, but excludes the detail lines.

See Also

Other Resources

Dialog Boxes


Report Expression Dialog Box

Visual FoxPro 9.0
Report Expression Dialog Box
See Also

Defines the contents of a field control in a report. This dialog box appears when you place a field control on a report or label.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

Expression

Specifies an expression, such as the name of a variable or table field. The expression is evalulated at report run-time as the report engine renders output from the Field control. Clicking the ellipsis (…) button opens the Expression Builder so that you can build an expression. For more information, see Expression Builder Dialog Box.
Format

When a valid expression is displayed in the Expression box, you can specify a format in this text box. Choose the dialog button to display the Format (Field) dialog box if you want to specify the format for the field in your report. For more information, see Format Expressions for Field Controls.
Field position

Specifies position of the field in the report.
  • Float Specifies that the selected field move relative to the size of the surrounding fields.

  • Fix Relative to Top of Band Causes the field to remain in the position you give it in the Report or Label Designer and maintain that position relative to the top of the band.

  • Fix Relative to Bottom of Band Causes the field to remain in the position you give it in the Report or Label Designer and maintain that position relative to the bottom of the band.

Stretch with overflow

Specifies that the bottom of a Field control is extended vertically down the page to contain the full value of the evaluated expression.
Comment

Makes it possible for you to add comments to the .frx or .lbx file. Comments are for reference only and do not appear anywhere in the printed report or label.
Calculations

Displays the Calculate Field dialog box so you can select a calculation type to perform on the Field control expression and when to reset the calculation. For more information, see Calculate Field Dialog Box.
Print When

Displays the Print When dialog box so that you can specify the conditions that must be met before the text is printed in your report or label. For more information, see Print When Dialog Box.

See Also

Other Resources

Dialog Boxes
Expression Builder Dialog Box
Calculate Field Dialog Box
Format (Field) Dialog Box
Print When Dialog Box
Report Designer
Quick Report Dialog Box


Report Page Setup Dialog Box

Visual FoxPro 9.0
Report Page Setup Dialog Box
See Also

Makes it possible for you to specify settings for the report page that are saved with the report, for example, to adjust column width and print area.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

Page Layout Section

Provides a graphical representation of the page, which reflects your layout in the Report Designer and Label Designer and the settings you choose in the Report Page Setup dialog box.

Columns

Specifies options for columns on the page.

Number

Specifies the number of columns to print across the page.
Width

Specifies the width of the layout within a column.
Spacing

Specifies the space between columns, when multiple columns have been specified.
Page Setup

Displays the Page Setup dialog box where you can select paper and printer settings. For more information, see Page Setup Dialog Box.
Print order

Determines whether to print records from top to bottom or left to right when the layout contains multiple columns.

Print Area

Specifies options for the print area on the page.

Printable page

Specifies that the layout uses the current printer's printable page dimensions. Printing begins immediately following the nonprintable margin area. Printing begins immediately following the nonprintable margin area.
Whole page

Specifies that the physical paper size attributes of the current printer determines the dimensions of the layout.
Note:
For printers that have a smaller printing area than the physical paper size, you will need to check your report layouts to ensure that the rendered output is not truncated by the printer.

Left margin

Specifies the width of the left margin. Increasing this value will correspondingly reduce the layout width.
Dimensions

Displays the measurement units for specifying column width, spacing, and the left margin.

See Also

Other Resources

Dialog Boxes


Report Picture Dialog Box

Visual FoxPro 9.0
Report Picture Dialog Box
See Also

Makes it possible for you to include pictures or contents of General fields in your report or label.

This dialog box appears when you choose Picture/OLE Bound Control from the Report Controls toolbar and place the control on a report or label. For more information, see How to: Add Pictures to Reports and How to: Add General Fields to Reports.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

Print When

Specifies an expression controlling the suppression or display of an image.

Print When

Displays the Print When dialog box so you can control when to print picture or the General field. For more information, see Print When Dialog Box.

Picture from

Specifies the source as an image file or a General field.

File

Specifies the name of an image file. Clicking the ellipsis (...) button displays the Open dialog box so you can select a file. For more information, see Open Dialog Box (Visual FoxPro) and How to: Add Pictures to Reports.
Field

Specifies the name of a General field. Clicking the ellipsis (...) button displays the Choose Field/Variable dialog box so you can select a field. For more information, see Choose Field/Variable Dialog Box, General Field Type, and How to: Add General Fields to Reports.

If picture and frame are different sizes

Specifies how to display an image file or a General field when resizing it or when the size of the image or General field differs from the frame that contains it.

Clip picture (Default)

The rendered output of the control source always appears anchored at the upper left corner of the control frame. If the control source is larger than the frame, only the upper left region of the control source that fits inside the dimensions on the control is displayed. If the control source is smaller than the control outline, the control will resize to fit, or remain transparent in the area not covered by the rendered control source.
Scale picture, retain shape

The rendered output of the control is displayed reduced in size so that the largest dimension fits inside the constraints of the frame of the control. The rendered output retains its relative proportions.
Tip:
This option protects the picture or General field from vertical or horizontal distortion.

Scale picture, fill the frame

The rendered output of the control is scaled to completely fill the dimesions of the control frame, stretching it vertically or horizontally as necessary.
Note:
This option can cause vertical or horizontal distortion.

Object Position

Specifies position settings for the report control.

Float

Specifies that the control moves down the page when a control that appears above it expands downward.
Fixed relative to top of band

Specifies that the control remain in position relative to the top of the band that contains it.
Fixed relative to bottom of band

Specifies that the control remain in position relative to the bottom of the band that contains it.
Center picture

Centers a General field when it is smaller than the frame that contains it. Otherwise, the General field displays in the upper-left corner of the frame.
Comment

Specifies comment text for the control as reference only. They are saved with the layout file but do not appear in the report or label.

See Also

Other Resources

Adding Report Controls
Dialog Boxes


Report Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Report Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to set options for reports and labels.

This dialog box appears when you choose Properties from the context menu of a report layout window or when you click Properties on the Report menu.

Note:
This dialog box is only displayed if the _REPORTBUILDER system variable is set to the default Report Builder application. If it is empty, or has been set to a third-party report builder, the native Visual FoxPro dialog box (or a third-party dialog box) may appear. For more information, see _REPORTBUILDER System Variable .

The following table lists the tabs that exist in the Report Properties dialog box.

Note:
When modifying the report or label in protected mode, some or all tabs might not be available as specified by protection mode settings.

Tab | Description
Page Layout Tab, Report Properties Dialog Box (Report Builder) | Makes it possible for you to specify page layout and printer setup settings for the report or label layout.
Optional Bands Tab, Report Properties Dialog Box (Report Builder) | Allows you to specify the band structure of the layout, such as whether it includes a Title, Summary, or additional Detail bands, and how they are processed when the layout is processed at run time.
Data Grouping Tab, Report Properties Dialog Box (Report Builder) | Makes it possible for you to create and specify how the data is grouped within the report or label layout.
Variables Tab, Report Properties Dialog Box (Report Builder) | Allows you to create variables that are initialized and assigned values as the layout is processed at run time.
Protection Tab, Report Properties Dialog Box (Report Builder) | Makes it possible for you to hide or show tabs in the Report Properties dialog box or prevent users from taking certain actions when modifying the report or label in protected mode.
Ruler/Grid Tab, Report Properties Dialog Box (Report Builder) | Makes it possible to specify layout-specific settings for the ruler and page layout grid in the Report Designer and Label Designer.
Data Environment Tab, Report Properties Dialog Box (Report Builder) | Allows you to load a data environment into the current layout, and specify data session settings.

See Also

Other Resources

Working with Reports
Dialog Boxes (Visual FoxPro)


Page Layout Tab, Report Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Page Layout Tab, Report Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to specify settings for the report or label page layout.

The Page Setup tab displays a graphical representation of the page, which reflects your layout in the Report Designer or Label Designer.

This tab is pre-selected when you choose Page Setup from the File menu; Properties from the Report menu or the report layout context menu.

Note:
This tab replaces the functionality of the native Visual FoxPro Report Page Setup Dialog Box when the Report Builder is active.

  • How to: Define Columns in Reports

  • How to: Change Page Settings for Reports

  • How to: Save the Printer Environment for Reports

Columns

Specifies options for columns in the page layout.

Number

Specifies the number of columns to print across the page.
Width

Specifies the width of the layout within a column.
Spacing

Specifies the space between columns, when multiple columns have been specified.
Left margin

Specifies the width of the left margin. Increasing this value will correspondingly reduce the layout width.

Print area

Specifies options for the print area on the page.

Printable page

Specifies that the layout uses the current printer's printable page dimensions. Printing begins immediately following the nonprintable margin area.
Whole page

Specifies that the physical paper size attributes of the current printer determines the dimensions of the layout.
Note:
For printers that have a smaller printing area than the physical paper size, you will need to check your report layouts to ensure that the rendered output is not truncated by the printer.

Column print order

Specifies whether multi-column layouts are processed from top to bottom or left to right.

Top to bottom

Print records from top to bottom (default).
Left to right

Print records from left to right. Also known as "label style."

Default font

Displays the default font settings for the report. Clicking the ellipsis (…) button opens the Font dialog box so you can select a different default font.

Use font script

Indicates that the language character set specified in Script box of the Font dialog box will be saved with the report. When you select a default font from the Font dialog box, the font script selection will be saved by default. You can choose not to save the specific font script selection with the layout by clearing this check box. For more information, see Font Dialog Box.

Printer

Displays the name of the printer in the layout's printer environment. For newly created reports, this will be the current default Visual FoxPro printer selection.

Page setup

Opens the Page Setup dialog box so you can select an alternate printer, and configure additional page and printer settings. For more information, see Page Setup Dialog Box (Visual FoxPro).
Save printer environment

Printer environments are saved with the layout by default. Clearing this check box will ensure that no printer environment information is stored in the layout's FRX file.

See Also

Reference

Report Properties Dialog Box (Report Builder)

Other Resources

Working with Page Layouts


Optional Bands Tab, Report Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Optional Bands Tab, Report Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to include a Title, Summary, or additional Detail bands in the report or label page layout and specify settings for them.

This tab is pre-selected when you choose Optional Bands from the Report menu or report layout context menu.

Note:
This tab replaces the functionality of the native Visual FoxPro Optional Bands Dialog Box when the Report Builder is active.

  • How to: Add Bands to Reports

  • How to: Change Detail Band Order

  • How to: Configure Output for Report Bands

  • How to: Delete Bands from Reports

Title

Contains options for the Title band.

Report has title band

Specifies whether the layout includes a Title band for displaying information once at the beginning of the report.
New page after title has printed

Specifies that a page break will be sent to the printer after the Title band information has rendered. Available only when the Report has title band check box is selected.

Summary

Contains options for the Summary band.

Report has summary band

Specifies whether the layout includes a Summary band for displaying information once at the end of the report.
Summary prints as new page

Specifies that a page break will be sent to the printer before the Summary band information is rendered. Available only when the Report has summary band check box is selected.
Include page header with summary

Specifies that the Page Header band information will be rendered on the separate page along with the Summary band information.
Include page footer with summary

Specifies that the Page Footer band information will be rendered on the separate page along with the Summary band information.

Detail bands

Contains options for Detail bands in the layout. The list box shows the Detail bands in the page layout and allows you to change their order, add them, or remove them.

Detail Bands List

Allows you to change the order of the Detail bands.
Add

Adds a new Detail band to the page layout. You can include a maximum of 20 separate detail bands in the layout.
Remove

Removes the selected Detail band from the page layout. You will not be able to delete the first band in the list. The layout must contain at least on Detail band.

See Also

Reference

Report Properties Dialog Box (Report Builder)

Other Resources

Working with Report Bands


Data Grouping Tab, Report Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Data Grouping Tab, Report Properties Dialog Box (Report Builder)
See Also

Allows you to specify nested regions of the layout that are rendered only when an expression changes its value.

This tab is pre-selected when you choose Data Grouping from the Report menu or the report layout context menu.

This tab also appears on the Properties dialog box of Detail bands.

Note:
This tab replaces the functionality of the native Visual FoxPro Data Grouping Dialog Box when the Report Builder is active.

  • How to: Add Data Groups to Reports

  • How to: Edit Data Groups in Reports

  • How to: Configure Output for Data Groups

  • How to: Delete Data Groups in Reports

Group nesting order

Lists the expressions that determine breaks between data groups. The mover button allows you to change the nesting order of the group expressions.
Add

Adds a new data group expression to the Group nesting order list.
Remove

Deletes the selected data group expression from the Group nesting order list.
Group on

Displays the data group expression selected in the Group nesting order list. Empty expressions are not valid. You can type or build an expression by clicking the ellipsis(…) button. For more information, see Expression Builder Dialog Box.

Group starts on

Specifies where the grouped bands' information will be rendered when the group expression value changes.

New line

Specifies that the group will start immediately on the next line of the output.
New column

Specifies that the group expression change will force the information to be rendered as a new column. Available only when the page layout contains more than one column.
New page

Specifies that the group expression change will force the information to be rendered as a new page.
New page number 1

Starts a new page and restarts page numbering every time the data group expression value changes.

Reprint group header on each page

Specifies that the group header follows the page header on all pages for the data group when the data group spans more than one page.

Start group on new page when less than

Specifies the minimum distance from the bottom of the page that determines when to begin the group header on the next page.

Tip:
Use this option to prevent a "orphaned" group header, and potentially inappropriate data, at the end of a page with no accompanying detail information. An orphaned group header may display data from a record not shown elsewhere on the page, since the page footer will display information appropriate to the previous group.

See Also

Reference

Report Properties Dialog Box (Report Builder)

Other Resources

Working with Report Data Groups


Variables Tab, Report Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Variables Tab, Report Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to create, change, or delete variables for a report or label. You can also change the order in which report variables are evaluated.

This tab is pre-selected when you choose Variables from the Report menu or the report layout context menu.

Note:
This tab replaces the functionality of the native Visual FoxPro Report Variables Dialog Box when the Report Builder is active.

  • How to: Define Report Variables

  • How to: Change Report Variable Order

  • How to: Reset Report Variables

Variables

Displays the names of variables defined in the report layout, and allows you to change the order of report variable evaluation.
Add

Opens an input box for you to specify the name of a new report variable.
Remove

Deletes the currently selected variable in the Variables list box.
Value to store

Specifies an expression that is used to determine the value of the report variable during a report run. The report engine evaluates this expression each time it moves the record pointer as it processes the records in the current scope. Clicking the ellipsis (…) button opens the Expression Builder so you can build an expression. For more information, see Expression Builder Dialog Box.
Initial value

Specifies an expression that is used to determine the initial value of the report variable. Clicking the ellipsis (…) button opens the Expression Builder.
Reset value based on

Specifies the point at which to reset the variable to its initial value. The default value is End of Report.
Note:
If you have specified data groups in the report, Detail bands, or target alias expressions for Detail bands, the Reset value based on list displays those items.

Calculation type

Specifies additional calculations to perform when determining the next value of the report variable as the report engine moves the record pointer during a report run.
Note:
Cumulative calculations are reset depending on the Reset value based on option.

  • None

    The result of the Value to store expression is assigned directly to the value of the report variable.

  • Count

    The value of the report variable is incremented by 1. (The Value to store expression is not evaluated.)

  • Sum

    Adds the result of the Value to store expression to the current value of the report variable.

  • Average

    Computes the arithmetic mean of the result of the Value to store expression for each record traversed thus far and assigns it to the report variable. (The Initial value of the report variable is not included in this calculation.)

  • Lowest

    Compares the current value of the report variable with the result of the Value to store expression and assigns the lesser of the two values to the report variable.

  • Highest

    Compares the current value of the report variable with the result of the Value to store expression and assigns the greater of the two values to the report variable.

  • Std Deviation

    Computes the square root of the variance of the result of the Value to store expression for each record traversed thus far and assigns it to the report variable. (The Initial value of the report variable is not included in this calculation.)

  • Variance

    Measures the degree to which the result of the Value to store expression varies from the average for the records traversed thus far and assigns it to the report variable. (The Initial value of the report variable is not included in this calculation.)

Release after report

Releases the report variable from memory after the report has completed processing. When this option is not selected, the report variable remains in memory until Visual FoxPro quits or the CLEAR ALL or CLEAR MEMORY commands are called. For more information, see CLEAR Commands

See Also

Reference

Report Properties Dialog Box (Report Builder)

Other Resources

Working with Report Variables


Protection Tab, Report Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Protection Tab, Report Properties Dialog Box (Report Builder)
See Also

Makes it possible for you restrict selected activities in the Report or Label Designer when modifying the layout in protected mode. For more information, see Setting Protection for Reports.

  • How to: Protect Report Layouts

In PROTECTED mode

Specifies the protection settings you can configure for the report or label.

Report can not be run or printed

Specifies that the user cannot print the report or label layout when modifying the report or label layout in protected mode. Disables the Print… option on the File menu, and the Run Report options on the Report menu and the designer's right-click context menu.
Report can not be previewed

Specifies that the user cannot preview the report or label layout when modifying the report or label layout in protected mode. Disables the Print Preview option on the File, Report, and designer's right-click context menus, and the Preview option on the View menu.
Data Environment can not be modified

Specifies that the user cannot modify the report layout's data environment when modifying the report or label in protected mode. Disables the Data Environment… option on the View and designer's right-click context menus; Hides the Data Environment tab in the Report Builder's Report Properties dialog box; and disables the Load Data Environment… option on the Report menu.
Page Layout is not available

Specifies that the user cannot change the printer setup or page size, margins, etc, of the layout when modifying the report or label layout in protected mode. Disables the Page Setup option on the File menu, and hides the Page Layout tab in the Report Builder's Report Properties dialog box.
Optional Bands can not be changed

Specifies that the user cannot change the number of detail bands, title or summary band, and other layout settings when modifying the report or label layout in protected mode. Disables the Optional Bands option on the Report menu and hides the Optional Bands tab of the Report Builder's Report Properties dialog box.
Data Grouping can not be modified

Specifies that the user cannot change the data grouping settings of the layout when modifying the report or label layout in protected mode. Disables the Data Grouping option on the Report menu and hides the Data Grouping tab of the Report Builder's Report Properties dialog box.
Report Variables can not be edited

Specifies that the user cannot view or modify report variables when modifying the report or label layout in protected mode. Disables the Variables option on the Report menu and hides the Variables tab of the Report Builder's Report Properties dialog box.

See Also

Reference

MODIFY REPORT Command
Protection Tab, Report Band Properties Dialog Box (Report Builder)
Protection Tab, Report Control Properties Dialog Box (Report Builder)
Report Properties Dialog Box (Report Builder)


Ruler/Grid Tab, Report Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Ruler/Grid Tab, Report Properties Dialog Box (Report Builder)
See Also

Allows you to configure the ruler and layout grid in the Report Designer or Label Designer.

This tab is pre-selected when you choose Set Grid Scale from the Format menu.

Note:
This tab replaces the functionality of the native Visual FoxPro Set Grid Scale Dialog Box when the Report Builder is active.

You can set the default ruler and layout grid settings for newly created report and label layouts on the Reports tabs in the Options dialog box. For more information, see Reports Tab, Options Dialog Box.

  • How to: Configure the Page Layout Grid for Reports

Ruler Units

Specifies the measurement units for the ruler along the top and left edges of the Report Designer or Label Designer window.

None

The rulers are not displayed. The measurement units displayed in various dialog boxes will be in inches.
Inches

The measurement ruler and other dimensions are displayed in inches.
Centimeters

The measurement ruler and other dimensions are displayed in centimeters.
Pixels

The measurement ruler and other dimensions are displayed in pixels.
System default

Specifies inches or centimeters as the unit of measurement displayed on the ruler depending on your language setting.

Show position in status bar

Specifies whether to show the mouse cursor position or currently selected control position (in ruler units) in the status bar.

Grid

Specifies settings for the page layout "snap-to" grid.

Show grid lines

Specifies whether to display visible snap-to-grid lines in the Designer. The resolution of the visible grid is half that of the actual snap-to grid. (For example, if the Horizontal spacing is set to 12 pixels, the vertical grid lines will be drawn every 24 pixels.)
Snap to grid

Specifies whether the Designer forces objects to be aligned with the snap-to grid.
Horizontal spacing

Specifies the horizontal resolution of the snap-to grid in pixels. The default setting is 12 pixels.
Vertical spacing

Specifies the vertical resolution of the snap-to grid in pixels. The default setting is 12 pixels.

See Also

Reference

Report Properties Dialog Box (Report Builder)

Other Resources

Working with Page Layouts


Data Environment Tab, Report Properties Dialog Box (Report Builder)

Visual FoxPro 9.0
Data Environment Tab, Report Properties Dialog Box (Report Builder)
See Also

Makes it possible for you to specify data environment and data session settings for the report or label.

This tab is pre-selected when you choose Load data environment from the Report menu.

  • How to: Load Data Environments for Reports

  • How to: Specify a Report's Data Session

Load data environment

Specifies options for loading a data environment for the report or label.

Copy from another report file

Specifies to replace the layout's current data environment with a copy of the data environment from another report (.frx) or label (.lbx) file.
Link to a DataEnvironment class

Specifies to link to a DataEnvironment class in a visual class library (.vcx) file or programmatic class library (.prg) file.
Select

Displays the Open dialog box so you can select a report, label, or visual class library file containing the data environment you want to use.
Class

Displays the chosen DataEnvironment class.
Class Library / Source

Displays the visual class library (.vcx) or program (.prg) file containing the DataEnvironment class, or the source report (.frx) or label (.lbx) file the data environment was loaded from.
Report uses a private data session

Specifies that the report engine should use a unique data session when running the report. The only tables available will be those in the report's Data Environment or explicitly opened in method code.

See Also

Reference

SET DATASESSION Command
Report Properties Dialog Box (Report Builder)


Report Variables Dialog Box

Visual FoxPro 9.0
Report Variables Dialog Box
See Also

The Report Variables dialog box makes it possible for you to create, change, or delete variables for a report or label. You can also change the order for evaluating report variables.

This dialog box appears when you choose Variables from the context menu of a report layout window or when you click Variables on the Report menu.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog box may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

Variables

Displays the names of variables defined in the report layout, and allows you to change the order of report variable evaluation by dragging the mover button.
Value to store

Specifies an expression that is used to determine the value of the report variable during a report run. The report engine evaluates this expression each time it moves the record pointer as it processes the records in the current scope. Clicking the ellipsis (…) button opens the Expression Builder so you can build an expression. For more information, see Expression Builder Dialog Box.
Initial value

Specifies an expression that is used to determine the initial value of the report variable. Clicking the ellipsis (…) button opens the Expression Builder. For more information, see Expression Builder Dialog Box.
Release after report

Releases the report variable from memory after generating output for the report.
Reset based on

Specifies the point at which to reset the variable to its initial value. The default value is End of Report.
Insert

Inserts a blank text box in the Variables box so you can type a new variable name.
Delete

Deletes the variable selected in the Variables box.
Calculate

Specifies the type of calculation to perform when determining the next value of the report variable. Some calculation types are cumulative as the report engine moves the record pointer during a report run.
Note:
Cumulative calculations are reset depending on the Reset value based on option.

  • None

    The result of the Value to store expression is assigned directly to the value of the report variable.

  • Count

    The value of the report variable is incremented by 1. (The Value to store expression is not evaluated.)

  • Sum

    Adds the result of the Value to store expression to the current value of the report variable.

  • Average

    Computes the arithmetic mean of the result of the Value to store expression for each record traversed thus far and assigns it to the report variable. (The Initial value of the report variable is not included in this calculation.)

  • Lowest

    Compares the current value of the report variable with the result of the Value to store expression and assigns the lesser of the two values to the report variable.

  • Highest

    Compares the current value of the report variable with the result of the Value to store expression and assigns the greater of the two values to the report variable.

  • Std Deviation

    Computes the square root of the variance of the result of the Value to store expression for each record traversed thus far and assigns it to the report variable. The Initial value of the report variable is not included in this calculation.

  • Variance

    Measures the degree to which the result of the Value to store expression varies from the average for the records traversed thus far and assigns it to the report variable. The Initial value of the report variable is not included in this calculation.

See Also

Other Resources

Dialog Boxes
CLEAR Commands
Data Grouping Dialog Box
Expression Builder Dialog Box
Quick Report Dialog Box
How to: Define Report Variables
Access to Visual FoxPro Variables and Fields
Variables


Round Rectangle Dialog Box

Visual FoxPro 9.0
Round Rectangle Dialog Box
See Also

Specifies the exact shape, position, and printing options for round rectangle controls. This dialog box appears when you draw a round rectangle in a report or label and then double-click it while it's selected.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

Style

Style

Specifies the style of the round rectangle.

Object Position

Float

Specifies that the control moves down the page when a control that appears above it extends downward.
Fix Relative to Top of Band

Specifies that the control remain in position relative to the top of the band that contains it.
Fix Relative to Bottom of Band

Specifies that the control remain in position relative to the bottom of the band that contains it.

Stretch Downwards

No Stretch

Specifies that the round rectangle not stretch vertically as the band stretches to display field data.
Stretch Relative to Tallest Object In Group

Specifies that the round rectangle stretch to accommodate the tallest object in the group.
Stretch Relative to Height of Band

Specifies that the round rectangle stretch to fit in the band.

Print When

Displays the Print When dialog box so you can control exactly when the round rectangle is printed in your report or label.

Comment

Makes it possible for you to add comments to the .frx or .lbx file. Comments are for reference only, and do not appear anywhere in the printed report or label.

See Also

Other Resources

Dialog Boxes
Print When Dialog Box
How to: Add Shapes and Lines to Forms
Report Picture Dialog Box


Save As Class Dialog Box

Visual FoxPro 9.0
Save As Class Dialog Box
See Also

Makes it possible for you to save a form or selected controls on a form as a class definition. If you plan to create subclasses based on the form or reuse the controls for other forms, save the form as a class.

This dialog box appears when you select Save As Class on the File menu.

Save

Specifies the part of the form to save as a class definition.
  • Selected Controls Saves only the selected controls as a class definition.

  • Current Form Saves the active form as a class definition.

  • Entire Form Set Saves a collection of related forms as a class definition. This command is enabled after you use the Create FormSet command on the Form menu.

  • DataEnvironment Saves a form's data environment and any contained cursors or cursor adapters in the specified visual class library (.vcx) file.

As Class

Specifies the class definition to which to save the selected controls, entire form, or form set.
  • Name Specifies the name assigned to the class.

  • File Specifies the name of the .vcx file in which to store the class definition.

  • Description Specifies the optional description for the class.

See Also

Other Resources

Dialog Boxes
Working with Classes in Visual FoxPro
How to: Save Forms


Save As Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Save As Dialog Box (Visual FoxPro)
See Also

Saves a new file or saves an existing file with a different name. Corresponds to the PUTFILE( ) function.

The Save As command is enabled for the following file types:

  • Project

  • Query

  • Connection (see the following note)

  • View (see the following note)

  • Form

  • Report

  • Label

  • Program

  • Text File

  • Menu

    Note:
    When you choose Save or Save As for a connection or view, the Save dialog box appears.

This dialog box appears when you select Save As from the File menu.

Code Page

This option is available if you are saving a text file or a table that has no code page. The Code Page dialog box is displayed so that you can attach the correct code page. If your existing text file uses the extended character set, choose Code Page and make the appropriate selections.

See Also

Other Resources

Dialog Boxes
Code Page Dialog Box
Save As Class Dialog Box
Code Page Dialog Box
PUTFILE( ) Function
Save As HTML Dialog Box


Save As HTML Dialog Box

Visual FoxPro 9.0
Save As HTML Dialog Box
See Also

Enables you to create a new HTML (Hypertext Markup Language) version of the current form, menu, report, or table. Available from the Form Designer, Menu Designer, and Report Designer when the active form, menu, or report has been saved, or from a Browse window.

Save file for later use

Saves the file to disk as an .htm file.
Save and edit file

Saves the file to disk as an .htm file and opens the file in an editing window.
Save file and view in Web browser

Saves the file as an .htm file and displays the file in your Web browser.

See Also

Other Resources

Dialog Boxes
_GENHTML System Variable
Save As Class Dialog Box
Save As Dialog Box
Print File Dialog Box
HTML Item Dialog Box
How to: Save a Form as HTML
How to: Save a Menu as HTML
How to: Generate Output for Reports
How to: Save a Table as HTML
Form Designer
Report Designer
Browse Window


Scope Dialog Box

Visual FoxPro 9.0
Scope Dialog Box
See Also

Specifies which records Visual FoxPro acts on in the current table or view. This dialog box appears when you choose Scope from the Export Options Dialog Box.

All

The action affects all records in the table or view.
Next

The action affects a range of records beginning with the current record and continuing for the number of records you specify. Type a value of 1 to act on the current record.
Record

The action affects only the specified record number.
Rest

The action affects a range of records beginning with the current record and ending with the last record in the table or view.

See Also

Other Resources

Dialog Boxes
Browse Window
Export Options Dialog Box
Record Manipulation
Append From Dialog Box
Delete (Records) Dialog Box


Select Connection or Data Source Dialog Box

Visual FoxPro 9.0
Select Connection or Data Source Dialog Box
See Also

Allows you to select a data source or an existing connection to a data source to create a new remote view. You can also access the Connection Designer to create a new connection.

Appears when you select Remote View in the New Dialog Box, and then choose New File.

Connections in Database/Available Data Sources

Lists available ODBC data sources or existing connections, depending on which option you select in the Select option group. Select the data source or connection you want and choose OK.

Select

Connections

Displays existing connections for you to choose in the active database.
Available Data Sources

Displays the available ODBC data sources for creating a remote view.
New

Displays the Connection Designer, in which you can create and save a connection to a data source.

See Also

Other Resources

Dialog Boxes
Create Dialog Box
New Label Dialog Box
Connection Designer
CREATE CONNECTION Command
Visual FoxPro as an Application Back End
New Dialog Box


Select Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Select Dialog Box (Visual FoxPro)
See Also

Makes it possible for you to select an XML Web service and insert code for it in a program or code editing window.

This dialog box appears when you type the characters, ws, followed by pressing the SPACEBAR in the editing window of a program.

Select an XML Web service

Specifies the XML Web service for which to generate proxy code.
Use Custom class

Specifies whether to include code that uses the WSHandler Foundation Class to wrap Simple Object Access Protocol (SOAP) client calls. Otherwise, code is generated to call the SOAP Toolkit 3.0 COM client directly.
Include error handling

Specifies whether to include structured error handling using TRY...CATCH...FINALLY code around SOAP client calls. For more information, see TRY...CATCH...FINALLY Command.
New

Opens the Visual FoxPro XML Web Services Registration dialog box so that you can register a new XML Web service. For more information, see Visual FoxPro XML Web Services Registration Dialog Box.

See Also

Other Resources

Dialog Boxes
How to: Access XML Web Services


Set Grid Scale Dialog Box

Visual FoxPro 9.0
Set Grid Scale Dialog Box
See Also

Makes it possible to specify horizontal and vertical increments in pixels for the designer grid. For reports and labels, you can specify whether to display the ruler in pixels or the default system units.

You can also set the default setting on the Forms and Reports tabs in the Options dialog box.

Note:
Depending on the setting of the _REPORTBUILDER system variable, this dialog box may be replaced by an alternative user interface. For more information, see _REPORTBUILDER System Variable .

Grid in pixels

Specifies the number of pixels per inch of the "snap-to" alignment grid horizontally and vertically.

Horizontal

Specifies the number of pixels per inch horizontally. The default setting is 12 pixels, and the range is from 1 to 48 pixels.
Vertical

Specifies the number of pixels per inch vertically. The default setting is 12 pixels, and the range is from 1 to 48 pixels.
Note:
The resolution of the visible grid is half that of the actual snap-to grid. (For example, if the Horizontal spacing is set to 12 pixels, the vertical grid lines will be drawn every 24 pixels.)

Ruler scale

Specifies the measurement units for the ruler along the top and left edges of the Report Designer or Label Designer window.

None

The rulers are not displayed. The measurement units displayed in various dialog boxes will be in inches.
Inches

The measurement ruler and other dimensions are displayed in inches.
Centimeters

The measurement ruler and other dimensions are displayed in centimeters.
Pixels

The measurement ruler and other dimensions are displayed in pixels.
System default

Specifies inches or centimeters as the unit of measurement displayed on the ruler depending on your language setting.

See Also

Other Resources

Dialog Boxes
Form Designer
Grid Builder
Working with Page Layouts


Set Index Order Dialog Box

Visual FoxPro 9.0
Set Index Order Dialog Box
See Also

Sets the index order for a child table. This dialog box appears when you set the parent table of a relation in the Data Session Window and then click a child table in the Aliases list of the Data Session window if the child table has no index order already set.

Set Index Order List

Lists any predefined index orders, which exist for the selected child table.
No Order Button

Opens the Expression Builder Dialog Box where you can set your own relationship for the child table. You can also double-click on a table index listed in the dialog box to open the ExpressionBuilder dialog box.

See Also

Other Resources

Dialog Boxes
SET INDEX Command
Data Session Window
Expression Builder Dialog Box
Indexes Tab, Table Designer
Create One-To-Many Relationships Dialog Box


Tab Order Dialog Box

Visual FoxPro 9.0
Tab Order Dialog Box
See Also

Adjusts the order in which objects are accessed in the form when you use the keyboard. This dialog box appears when you choose the Assign by List option in Tab Order from the View menu.

Object List

Lists all objects except graphic and text objects in the form or class. Objects are listed in the order in which they are currently accessible via the keyboard. Change the order by clicking the button to the left of the object picture and dragging the object to the position in the list that corresponds to its place in the desired access order.
By Row

Adjusts object order so objects are accessed by row, from left to right, across the form starting at the top.
By Column

Adjusts object order so objects are accessed by column, from top to bottom, down the form starting at the left side.

For more information, see How to: Set Tab Order for Controls.

See Also

Other Resources

Dialog Boxes
TabIndex
General Options Dialog Box
Menu Options Dialog Box
Define Window Layout Dialog Box


Task Pane Options Dialog Box

Visual FoxPro 9.0
Task Pane Options Dialog Box
See Also

The Task Pane Options dialog box allows you to customize the Task Pane Manager and the individual panes that it contains. Additionally, you can add new panes to your Task Pane Manager and access the Pane Customization dialog box to create your own panes.

Move Up

Moves the selected item in the tree view up.
Move Down

Moves the selected item in the tree view down.
Tree View

Displays the different areas of the Task Pane Manager where you can set options. When you click an item in the tree view, it expands the node to show additional categories for the selected item; it also displays the appropriate options for the selected item on the right side of the dialog box. Additionally, the order that panes appear in the tree view is the order they are shown at the top of the Task Pane Manager.
Help

Opens the Visual FoxPro Help file.

Task Pane Manager, General

Displays options that can be set for the Task Pane Manager.

Pane

Specifies the initial pane to be displayed when the Take Pane Manager is opened.
Check for New Internet Content

Selects how often to check for new content for Web-based panes. This option is the default for Web-based panes; however, different settings are available depending on the pane.
Open the Task Pane when Visual FoxPro starts

Specifies whether the Task Pane Manager is automatically opened when Visual FoxPro starts.

Task Pane Manager, Customize

Displays options for customizing panes and managing the Task Pane Manager.

Install Pane

Displays a dialog box to select a Microsoft or third-party pane to add to the Task Pane Manager.
Customize Panes

Displays the Pane Customization dialog box, which enables you to view and customize panes and to create your own custom panes.
Cleanup Tables

Removes deleted records from the Task Pane Manager tables and clears the Task Pane Manager's cache directory.
Restore to Default

Restores the Task Pane Manager to its default settings and panes.
Folder for Take Pane Manager content tables

Specifies the folder in which the Task Pane Manager accesses its tables.
Folder for cached files

Specifies the folder in which the Task Pane Manager stores its cached files.

Start, General

Displays options that can be set for the Start pane.

Start

Specifies whether the Start section of the Start pane is displayed.
My Tools

Specifies whether the My Tools section of the Start pane is displayed.
Recent Projects

Specifies whether your recently used projects are displayed on the Start pane.
Recent Databases

Specifies whether your recently used databases are displayed on the Start pane.
Check for New Internet Content

Selects how often to check for new Internet-based content.

Community, General

Displays options that can be set for the Community pane.

FoxCentral News

Specifies whether news from the FoxCentral Web site is displayed in the Community pane.
Universal Thread News

Specifies whether content from the Universal Thread Web site is displayed in the Community pane.
Wiki

Specifies whether content from the Visual FoxPro Wiki Web site is displayed in the Community pane.
Check for New Internet Content

Selects how often to check for new Internet-based content.

Community, FoxCentral News

Displays options that can be set for displaying news from the FoxCentral Web site.

Number of days to look back for news

Specifies how many days, of back news, from the FoxCentral Web site, the Community pane should display.

Community, Universal Thread News

Displays options that can be set for displaying content from the Universal Thread Web site.

Login name

Specifies the login name that the Community pane should use when downloading content from the Universal Thread Web site.
Password

Specifies the password that the Community pane should use when downloading content from the Universal Thread Web site.
Number of days to look back for news

Specifies how many days of back content from the Universal Thread Web site the Community pane should display.
News

Specifies whether the Community pane should list news content from the Universal Thread Web site.
Articles

Specifies whether the Community pane should list articles from the Universal Thread Web site.
Downloads

Specifies whether the Community pane should list downloads from the Universal Thread Web site.
Training

Specifies whether the Community pane should list Training announcements from the Universal Thread Web site.

Community, Wiki

Displays options for displaying content from the Visual FoxPro Wiki Web site.

Number of days to look back for news

Specifies how many days, of back content, from the Visual FoxPro Wiki Web site, the Community pane should display.

Solution Samples, General

Displays options that can be set for the Solution Samples pane.

Solution Samples

Specifies whether the Solution Samples section is displayed in the Solutions Samples pane.
Add-In Links

Specifies whether the Solution Samples Add-In section is displayed in the Solution Samples pane.
Check for New Internet Content

Selects how often to check for new Internet-based content.

XML Web Services, General

Displays options that can be set for the XML Web Services pane.

XML Web Services Tools

Specifies whether the XML Web Services Tools section should be displayed in the XML Web Services pane.
Explore an XML Web Service

Specifies whether the Explore an XML Web Service section should be displayed in the XML Web Services pane.
XML Web Services Resources

Specifies whether the XML Web Services Resources section should be displayed in the XML Web Services pane.
Check for New Internet Content

Selects how often to check for new Internet-based content.

Minesweeper

Displays options that can be set for the Minesweeper pane.

Size of matrix

Specifies how large the default game area is.

See Also

Other Resources

Dialog Boxes
Pane Customization Dialog Box
Task Pane Manager


Toolbars Dialog Box

Visual FoxPro 9.0
Toolbars Dialog Box
See Also

Allows you to create, edit, hide, and customize toolbars.

Toolbars

Lists available toolbars. Selected toolbars are tiled or displayed in the active output window.
New

Displays the NewToolbar dialog box, where you can enter a name for your new toolbar.
Reset

Returns the selected toolbar to its built-in version. This button changes to Delete if you select a custom toolbar. You cannot reset a custom toolbar.
Delete

Deletes the selected custom toolbar. This button changes to Reset if you select a built-in toolbar. You cannot delete a built-in toolbar.
Customize

Displays the Customize Toolbar Dialog Box so that you can add and delete toolbar buttons.

Display

Color Buttons

Displays colored buttons on both built-in and customized toolbars. Clear this check box if you are using a black-and-white monitor.
Large Buttons

Displays toolbar buttons that are larger than the standard size. If your monitor has a high resolution, you may want to display larger buttons.
Show ToolTips

Displays the name of the button when you place the pointer over any button on a toolbar.

See Also

Other Resources

Dialog Boxes
Tab Order Dialog Box
General Options Dialog Box
Menu Options Dialog Box
Define Window Layout Dialog Box
Creating Custom Toolbars


Customize Toolbar Dialog Box (Visual FoxPro)

Visual FoxPro 9.0
Customize Toolbar Dialog Box (Visual FoxPro)
See Also

Allows you to add and delete toolbar buttons. The available buttons are displayed by category. Click a button to see its description.

This dialog box appears when you choose Customize in the Toolbars Dialog Box.

Categories

Lists the button categories.
Button

Displays the buttons included in the category you select in the Categories box. To add the button, drag it to the desired toolbar or drop it onto the Visual FoxPro desktop to create a new toolbar.
Description

Describes the selected button.

For more information, see How to: Configure Visual FoxPro Toolbars.

See Also

Other Resources

Dialog Boxes
Tab Order Dialog Box
General Options Dialog Box
Menu Options Dialog Box
Define Window Layout Dialog Box
Creating Custom Toolbars


Undo Check Out of Files Dialog Box

Visual FoxPro 9.0
Undo Check Out of Files Dialog Box
See Also

Overwrites your changes to a file, and copies the latest checked in version to your development-environment working directory.

Files to Un-Check Out

Lists the currently checked out files. Click the files whose checkout you want to undo, or click Select All to select all the listed files.
Select All

Selects all files listed.

See Also

Other Resources

Dialog Boxes
Check Out Files Dialog Box
Add Files to Source Control Dialog Box
Compiling Source Code


Update Project List Dialog Box

Visual FoxPro 9.0
Update Project List Dialog Box
See Also

Displays the results when you choose Update Project List from the Source Control submenu on the Project menu.

Comments

Displays the results of the update.

See Also

Other Resources

Dialog Boxes
Remove Files from Source Control Dialog Box
Project Information Dialog Box
Compiling Source Code


View Parameters Dialog Box

Visual FoxPro 9.0
View Parameters Dialog Box
See Also

Sets up views that prompt for a value entry to complete the view.

Name

Specifies name of parameter.
Type

Specifies data type of parameter.
Insert

Inserts a blank row.
Delete

Deletes selected row.

See Also

Other Resources

Dialog Boxes
Advanced Options Dialog Box
Query and View Designers
Query Destination Dialog Box
How to: Create a Parameterized Query
PARAMETERS Command


Visual FoxPro Converter Dialog Box

Visual FoxPro 9.0
Visual FoxPro Converter Dialog Box
See Also

Converts FoxPro 2.6 and Visual FoxPro 3.0 files to the current Visual FoxPro format, which is necessary when you want to use these files with later versions of Visual FoxPro.

For information about converting these older files, see How to: Convert Earlier Visual FoxPro Files.

Convert both Macintosh and Windows form records

Available only when converting FoxPro 2.6 screens or projects that contain platform-specific controls or information such as references to screen fonts or paths. If you select this option, the converter creates a separate form for each platform. The Windows version of the form will have the original name, and the Macintosh version will have the original name with the suffix "_MAC" added. If the original screen was part of a project, the new project is updated to include both new forms.
Retain Visual FoxPro 3.0 default property values

Applies only when converting Visual FoxPro 3.0 projects. Visual FoxPro format default property settings for fonts and colors are compliant with Windows 98 and sometimes different from Visual FoxPro 3.0 settings. If you select this option, your converted forms will retain the Visual FoxPro 3.0 property settings.
File

Visible when using the Converter.app application as the converter tool. You can specify the file you want to convert. To browse for a file, click the ellipsis (...) button.
Backup files

Specify a directory for saving backup of files. To specify another directory, type the directory or click the ellipsis (...) button.
Create log file

Visible only when converting FoxPro 2.6 projects. You can save a list of the actions performed while converting your files to a log file.
Functional conversion

Visible only when converting FoxPro 2.6 screens or projects. This option creates form and control images and copies code to locations in object properties, events, and methods. Functional conversion provides immediate FoxPro 2.6 READ compatibility so you can use forms in Visual FoxPro without making extensive manual changes. To gain complete event model functionality, you must eliminate pages and page frames, change the form set WindowType Property, and manually relocate code in methods and events.
Visual conversion

Visible only when converting FoxPro 2.6 screens or projects. This option creates images of forms and all controls but copies all the code from the original FoxPro 2.6 project or screens to a noncompilable program (.prg) file. When you select this option, Visual FoxPro prompts you to create a .prg file. To move to full Visual FoxPro functionality without eliminating pages and page frames, changing the form set WindowType Property, and manually relocating code from object to object, choose Visual Conversion.
Continue

Completes the file conversion process. Pressing Continue displays the Visual FoxPro Transporter dialog box only when converting Macintosh or MS-DOS files that have never contained Windows records. For more information, see Visual FoxPro Transporter Dialog Box.
Directory

Visible when using the Converter.app application as the converter tool. You can convert all the files in a directory. When selected, this option enables you to specify or browse for the directory and select options that specify the types of files you want to convert. You can also specify whether to check subdirectories for convertible files.

See Also

Other Resources

Dialog Boxes
Command Window
MODIFY FORM Command
MODIFY LABEL Command


Visual FoxPro Transporter Dialog Box

Visual FoxPro 9.0
Visual FoxPro Transporter Dialog Box
See Also

Makes it possible for you to transport forms, labels, and reports across different FoxPro platforms and versions. This dialog box appears only when you are trying to convert Macintosh or MS-DOS files that have never contained Windows records.

According to the options set in the Visual FoxPro Transporter dialog box, Visual FoxPro creates Windows platform records from the Macintosh or MS-DOS records so that the Visual FoxPro Converter can convert the files to the current Visual FoxPro file format, which is necessary for using these files with later versions of Visual FoxPro.

For more information about converting files from other platforms, see How to: Convert Earlier Visual FoxPro Files.

Transport

Creates a Windows version of the Macintosh or MS-DOS records so that the Visual FoxPro Converter can recognize the file and convert it to the correct file format.
Don't Transport

Cancels the file transport and conversion process. You can still open the file in the older version of FoxPro.
Font

Opens the Font dialog box so you can choose the default font for your transported screen, report or label.
Transport Objects From

Makes it possible for you to choose the appropriate platform from the list.

See Also

Other Resources

Dialog Boxes
_TRANSPORT System Variable
Visual FoxPro Converter Dialog Box


Visual FoxPro XML Web Service Location Dialog Box

Visual FoxPro 9.0
Visual FoxPro XML Web Service Location Dialog Box
See Also

Specifies a local Uniform Resource Locator (URL) or virtual directory for publishing an XML Web service.

The Visual FoxPro XML Web Service Location dialog box appears the first time you select the Web Services Publisher wizard from the Wizards menu. You can open the dialog box by clicking Advanced in the Visual FoxPro XML Web Services Publisher dialog box. For more information, see Visual FoxPro XML Web Services Publisher Dialog Box.

Note:
All prior settings for previously published XML Web services are preserved, so you do not have to reset these values each time you want to republish a previously published XML Web service.

Existing

Select an existing location in the Select Location (Virtual Directory) box for publishing an XML Web service. This must be a URL location URL (virtual directory) available on an accessible IIS Web server.
New

Specifies a new virtual directory in the Select Location (Virtual Directory) box for publishing an XML Web service and to type a name for the virtual directory in the New Virtual Directory Namebox.
Select Location (Virtual Directory)

Specifies the local URL (virtual directory) to publish an XML Web service. The box lists all available virtual directories on your IIS default Web server. If New is selected, the specified URL is used as the root location for the new virtual directory appearing in the New Virtual Directory Name box.
File Output Path

Displays the physical path for the new virtual directory location and is available only when New is selected. Click Ellipsis (...) button to the right of the File Output Path box to select a physical directory for the new virtual directory.
New Virtual Directory Name

Specifies the name of the new virtual directory and is available only when New is selected.

See Also

Other Resources

Dialog Boxes
How to: Distribute XML Web Services
XML Web Services in Visual FoxPro


Visual FoxPro XML Web Services Publisher Dialog Box

Visual FoxPro 9.0
Visual FoxPro XML Web Services Publisher Dialog Box
See Also

Specifies information for publishing Visual FoxPro COM (.dll) servers as XML Web services that can be accessed on the Web. The Visual FoxPro XML Web Services Publisher dialog box appears when you click Publish an XML Web Service in the XML Web Services pane in the Task Pane Manager or when you click Web Services on the Wizards menu from the Tools menu.

Note:
The Visual FoxPro XML Web Services Publisher dialog box uses the Web Services Description Language (WSDL) generation engine from the SOAP Toolkit version 3.0. Therefore, certain complex types might not be supported. For more details about the WSDL or WSML files generated by the Visual FoxPro XML Web Services Publisher, see the SOAP Toolkit 3.0 documentation.

The Visual FoxPro XML Web Services Publisher dialog box uses the default URL location (virtual directory) for its settings. You can display and modify these default settings by clicking Advanced in the Publisher dialog box. Settings are preserved so that you can later republish your XML Web service with newly generated support files.

COM Server

Specifies the file name of the COM server to be published. Click the Ellipsis (...) button to select a COM server (.dll or .exe file). By default, a COM Server associated with an active project is displayed. The COM Server box lists all COM Servers associated with open projects and any previously published COM Servers.
Select Class

Specifies an individual class (OLEPUBLIC) of the COM Server to be published. The Select Class box lists all classes in the COM Server.
Advanced

Displays the Advanced dialog box so that you can modify the default settings for the XML Web service you want to publish and for the support files generated for the XML Web service. These settings are used when you click Generate. They are preserved so that you can republish the XML Web service later with newly generated support files. The following settings are available: Options tab
  • Service Name Specifies the name of the XML Web service to create. When generating the WSDL (and ASP) files, use this file name.

  • Listener URI Specifies the URL for the WSDL and ASP file.

    This box lists suggested locations based on the set of virtual directories on your default Web server. Clicking the Ellipsis (...) button displays the Visual FoxPro XML Web Service Location dialog box so you can choose an existing or new virtual directory. For more information, see Visual FoxPro XML Web Service Location Dialog Box.

  • File(s) Location Displays the physical location of the generated WSDL files. This location is determined by the location specified by clicking the Ellipsis (...) button on the right side of the Listener URI box.

  • Listener Type Specifies whether the XML Web service uses an ISAPI or ASP listener. The ISAPI listener is the default option and offers the fastest performance. If an ASP listener is specified, an ASP file is created along with the WSDL files when the Generate button is clicked.

  • ASP listener Application Displays the application name used in the ASP script of the listener file.

  • VBScript Specifies that the ASP listener file uses VBScript as the scripting language.

  • JScript Specifies that the ASP listener file uses JScript as the scripting language.

  • Automatically generate Creates a project hook with the COM Server project so that XML Web service support files are automatically generated when the COM Server is rebuilt.

  • Generate with UTF-16 Uses UTF-16 Unicode encoding when generating WSDL files. With UTF-16 encoding, every character uses two bytes. With UTF-8 encoding, most characters, for example, English characters, use one byte each. Other characters, such as Asian or Arabic, use up to three bytes each. Therefore, it is better to save files in UTF-16 format.

Methods tab
  • Methods Specifies a list of available methods in the selected COM Server class. Only selected methods are included as operations in the generated WSDL XML Web service file.

Namespaces tab Specifies different namespaces for URIs in your generated WSDL files. Each XML Web service needs a unique namespace for client applications to distinguish it from other services on the Web. It is recommend that you use a domain different from tempuri.org.
  • WSDL Namespace URI Specifies the namespace used for definitions in the WSDL document.

  • Schema Type Definition Namespace URI Specifies the namespace used for schema references in the WSDL document.

  • Message Namespace URI Specifies the namespace used for input or output messages, or method calls, in the WSDL document.

  • Base SOAP Action URI Specifies the URI used for operations in the WSDL document.

STK3 Wizard

Opens the SOAP Toolkit 3.0 WSDL Generator so that you can create a WSDL file from a COM object. You can use this wizard as an alternate method for publishing your COM Server as an XML Web service and contains many of the same options as the Visual FoxPro XML Web Services Publisher.
Generate

Generates all the XML Web service support files necessary to publish your COM server as an XML Web service including an ASP listener and WSDL files.

See Also

Other Resources

Dialog Boxes
How to: Distribute XML Web Services
XML Web Services in Visual FoxPro


Visual FoxPro XML Web Services Registration Dialog Box

Visual FoxPro 9.0
Visual FoxPro XML Web Services Registration Dialog Box
See Also

Specifies information for registering an XML Web service so you can use it in your applications.

The Visual FoxPro XML Web Services Registration dialog box appears when you click Register an XML Web Service in the XML Web Services pane in the Task Pane Manager. You can also open the dialog box from the XML Web Service Builder and Select dialog box when you type the characters, ws, in a code editing window.

WSDL URL Location

Specifies the location of the WSDL file and is usually a URL. However, the location can also be a local directory if stored locally. This value must be a valid WSDL location and file; otherwise, Visual FoxPro generates the appropriate message when you attempt to register the XML Web service. The box also includes the previously registered WSDL location reference. If you specify a WSDL file that contains multiple ports (classes), you are prompted to pick a specific port.
UDDI Search

Displays the UDDI Search dialog box so that you can search for an XML Web service registered in the Microsoft Universal Description, Discovery, and Integration (UDDI) database. The UDDI Search dialog box contains the following options:
  • Enter name to search for in UDDI database Specifies a name to search for and can be the name of a company, business, or a simple category, such as weather or stock.

  • Web Services Displays the results of the UDDI search.

    The Results area displays details about the specified XML Web service. However, there might be times when the search returns a result that is not an XML Web service but a reference to a URL containing a link to an XML Web service. If this situation occurs, the Select button is not available; however, the description contains a link you can click for more information.

  • View Service Description (WSDL) Contains a hyperlink to the WSDL for the XML Web Service.

  • Go to Microsoft UDDI Web Site Contains a hyperlink to the Microsoft UDDI Web site.

  • Search Performs the UDDI search for the specified expression.

    The time required for the search depends on the expression entered. If no matches are found, a message box displays to indicate this.

  • Select Enters the selected XML Web service in the WSDL URL Location box in the Visual FoxPro XML Web Services Registration dialog box.

    Note:
    If you need to perform a more complex search, visit the Microsoft UDDI Web site at .

See Also

Other Resources

Dialog Boxes
How to: Access XML Web Services
XML Web Services in Visual FoxPro


Wizard Selection Dialog Box

Visual FoxPro 9.0
Wizard Selection Dialog Box
See Also

Displays a list of wizards from which you can choose. This dialog box is displayed when you choose Wizards from the Tools menu and then choose Query, Form, Report, or All from the submenu.

Select the wizard you would like to use

Displays all Visual FoxPro wizards available for a particular item. For instance, Visual FoxPro has three different report wizards.
Description

Gives a brief description of the currently selected wizard.

See Also

Other Resources

Dialog Boxes
Wizards
Macros Dialog Box
Class Browser Window


Work Area Properties Dialog Box

Visual FoxPro 9.0
Work Area Properties Dialog Box
See Also

Lets you modify the structure of a table, select index files and fields, and define data filters. This dialog box appears when you choose Properties from the Table Menu.

Cursor

Displays the title of the currently opened table.
Enable data buffering

Sets buffering on.

Lock Records

When edited

Prevents access by other users while you edit records. This is also known as pessimistic buffering.
When written

Permits access by other users until the record is updated. This is also known as optimistic buffering.

Buffer

Current record

Enables buffering of the current record only. This is also known as record buffering.
All edited records

Enables buffering of all edited records. This is also known as table buffering.
Note:
When you select Buffer Current Record, SET MULTILOCKS Command are automatically set to ON (if they are currently off), but are not set to OFF if you clear Buffer Current Record or select Buffer All Edited Records. Set the defaults for new tables in the Data Tab, Options Dialog Box.

Data filter

Provides a text box for typing a data filter expression. Alternatively, the dialog button displays the Expression Builder Dialog Box, in which you can specify which records in the active table will be available for processing. Corresponds to the SET FILTER command.
Index order

Specifies the index order of the table. In the Database Designer, the table's primary index appears with a key symbol next to it in the list of indexes. Corresponds to the SET ORDER command.

Allow Access To

All fields in the work area

Specifies that the user have access to all fields in the work area. Corresponds to the SET FIELDS command.
Only fields specified by field filter

Specifies that only records which match the selections in the Field Picker Dialog Box be displayed or available for editing.
Field Filter

Displays the Field Picker dialog box, in which you control the number of active fields.
Modify

Displays the Table Designer, in which you can modify database and free tables, fields, and indexes.

See Also

Other Resources

Dialog Boxes
How to: Filter Records in Tables
Database Designer
Table Designer


XML Web Service - Client Detail Dialog Box

Visual FoxPro 9.0
XML Web Service - Client Detail Dialog Box
See Also

Makes it possible for you to specify the control, or client, to which you want to bind the results of the XML Web service operation. When calling an XML Web service operation, the results can be bound to a specific control on the form. You can then assign the return value, or the parameter as passed by reference, to a property of the control. Usually, you assign this return value to the Value or Caption property so that the user can see the results.

This dialog box appears when you click Add or Edit in the Clients group on the Operations tab of the XML Web Service Builder. For more information, see Operations Tab, XML Web Service Builder.

Select control

Displays and specifies controls or objects available on the current form to which you want to bind the results of the XML Web service operation. If your XML Web service returns a simple data type, you might want to select a text box or label. You can bind an operation that returns an ADO.NET DataSet, which is a complex type, to a grid. For DataEnvironment objects, you can select a CursorAdapter object and bind the operation results to its CursorFill method, which is typical for XML Web service operations that return ADO.NET DataSets.
Control property used to assign the Web service results

Displays and specifies the property of the selected control to which you want to bind the operation results. When the operation is called, the results are assigned to the property. For a TextBox control, you usually choose the Value property; however, if the operation returns an ADO.NET DataSet, you might want to use the ControlSource property. For a Label control, the Caption property is selected by default. For a Grid control, and if the operation returns an ADO.NET DataSet, you might want to use the RecordSource property.
Binding control to the Web service return value or parameter

Specifies the XML Web service parameter source to which the control property is bound. The ReturnValue setting is selected as the default. However, you can also specify an operation parameter as the source. This can be useful for operations that have parameters passed by reference. It is also sometimes useful to display the original input value, for example, by using the Label Caption property.
Client description

Specifies a name you want to use for the client. (Optional)
Name of binding property

Specifies the name of a custom property you want to use as the event source for triggering the XML Web service operation call and subsequent control binding. This option is set to BindMe by default. However, all custom properties and methods of the control are included in the list for you to select another if desired. If a CursorAdapter object is selected, the CursorFill method is selected by default so that the event causes a cursor to be created after calling the XML Web service. This is useful for operations that return an ADO.NET DataSet because the XML Web service enables the DataSet to be imported into CursorAdapter object, through an XMLAdapter object, which is used by the CursorAdapter CursorFill method. XML Web service operations are called using Visual FoxPro event binding capabilities. At run time, a property specified by the Name of binding property option is added to the control. The added property serves as the event source and is bound to the InvokeClient method of the XML Web service. When the value of the binding property is set to True (.T.), an event occurs and calls the InvokeClient method, which in turn, calls the XML Web service operation. After the operation is called, the return value is set to the control property specified. You can also specify a custom method instead of a custom property. Calling this custom method triggers an event that calls the InvokeClient delegate.
Invoke at startup

Specifies that the XML Web service is called and the control is bound when the form or class is first instantiated.
Always call Web service

Specifies that each control makes its own call to the XML Web service operation to which it is bound. The XML Web service control (wshandler) has the capability to detect when multiple client calls occur for the same operation. For performance, multiple clients reuse the results of an operation when those clients are called simultaneously, such as when the form or class is first instantiated. For example, suppose you have a TextBox control that binds an operation's results to its Value property and a Label control that binds the first parameter, an input value, of the same operation to its Caption property. When the form or class instantiates, and both clients are called, only a single call to the XML Web service operation usually occurs. However, by selecting Always call Web service, you can specify that all clients make their own calls to the same operation. This also occurs if a client manually calls the operation when the form or class instantiates.
Complex Types

Displays a dialog box that makes it possible for you to set additional options when binding to operations that return complex types, such as an ADO.NET DataSet or XMLDOMNodeList. For more informatin, see XML Web Service - Complex Types Dialog Box.

See Also

Other Resources

Dialog Boxes
Operations Tab, XML Web Service Builder


XML Web Service - Complex Types Dialog Box

Visual FoxPro 9.0
XML Web Service - Complex Types Dialog Box
See Also

Makes it possible for you to specify information for complex types such as table and field names for XML Web service operations that return ADO.NET DataSets or property names for a returned object, such as an XMLDOMNodeList, which SOAP Toolkit 3.0 returns for most complex types.

This dialog box appears when you click Complex Types in the XML Web Service - Client Detail Dialog Box.

Dataset

Specifies a table and field name of the returned DataSet. The XML Web service control imports the DataSet into an XMLAdapter object object that your application can use. When the client operation is called, the cursor is automatically created.
  • Dataset tables Specifies a table from the tables available in the DataSet.

  • Table fields Specifies a field from the fields available in the selected DataSet table. Selecting a field can be useful when binding to the TextBox ControlSource property.

  • Use existing cursor if already opened Specifies to use an existing cursor that has the same name; otherwise, create a new cursor.

Object

Most XML Web service operations that return complex types are objects, which are treated by SOAP Toolkit 3.0 as XMLDOMNodeLists, and have properties to which you might want to bind your control.
  • Values Displays properties associated with the object.

Query

Calls the XML Web service so that you can view the available values for the DataSet or object.
Reset

Resets all values to empty strings.
Attach Schema

Sets the CursorAdapterCursorSchema property to the schema of the selected table. Available when a CursorAdapter object is selected in the Client Detail dialog box.

See Also

Other Resources

Dialog Boxes
XML Web Service - Client Detail Dialog Box


XML Web Service - Operation Detail Dialog Box

Visual FoxPro 9.0
XML Web Service - Operation Detail Dialog Box
See Also

Makes it possible for you to choose specific operations, or methods, you want to call from your application. You can also specify parameter values for these operations.

This dialog box appears when you click Add or Edit in the Operations group of the Operations tab of the XML Web Service Builder. For more information, see Operations Tab, XML Web Service Builder.

Name

Specifies a name you want to use to refer to the operation.
Description

Specifies a description for the operation. (Optional)
Select an operation (method)

Specifies the operation you want to use. Details of the selected operation appear in the Syntax box, including any previously set parameters.
Set parameter(s)

Specifies how parameter values are set for the operation as follows:
  • Input values now Makes it possible for you to set parameter values in advance. To specify values or run-time parameter sources, click Set to open the XML Web Service - Parameter Values Dialog Box.

  • Programmatically set at run-time Set parameter values at run time using the operation's parameter collection.

  • Prompt at run-time Specifies that a dialog box appears for entering values when the operation is called at run time. The dialog box supports only simple data types.

Set

Displays a dialog box for you to set parameter values for the operation. This option is available only when Input values now is selected in the Set parameter(s) box.
Syntax

Displays the syntax for the operation.

Options

Allow Web service calls to be cached offline

Specifies that operation calls, including parameter values and results, are stored locally. If the operation is called offline using the same parameters, the original results are returned, making it possible for your application to run disconnected without interruption.

See Also

Other Resources

Dialog Boxes
Operations Tab, XML Web Service Builder


XML Web Service - Parameter Values Dialog Box

Visual FoxPro 9.0
XML Web Service - Parameter Values Dialog Box
See Also

Makes it possible for you to set parameter values or specify a control and its property as a parameter source for a selected XML Web service operation.

Note:
You can specify only simple data types in this dialog box. You can set complex data types, such as arrays or ADO.NET DataSets, programmatically using the operation's parameter collection.

This dialog box appears when you select Input values now in the Set parameter(s) box of the XML Web Service - Operation Detail Dialog Box.

Select parameter

Specifies the parameter you want to set.
Parameter type

Displays the data type for the parameter.
Specify parameter source

Specifies the source that supplies the value for the selected parameter.
  • Value Specifies a particular value for the parameter. The value provided is automatically converted to the correct data type required by the parameter.

    You can also include an expression, which is evaluated at run time, by prefacing it with an equal sign (=). For example, you can set the current date as follows:

    Copy Code
    =DATE()
  • Control/Property Displays available controls on the form and specifies that the property of the selected control or object supply the value for the parameter.

    When selecting a control, a list of properties available for that control appears so that you can select one to supply the value. If you want to have the user supply the value for the parameter, you might want to select the Value property.

See Also

Other Resources

Dialog Boxes
XML Web Service - Operation Detail Dialog Box


Zoom <property> Dialog Box

Visual FoxPro 9.0
Zoom <property> Dialog Box
See Also

Displays the text value of the selected property. This dialog box appears when choosing Zoom on the Properties window shortcut menu or the Zoom button.

The Zoom dialog box makes it possible for you to edit values of read/write properties except properties such as Visible or ColorSource. You cannot edit the value for a read-only property in the Zoom dialog box; however, you can select and copy the value.

Tip:
In Visual FoxPro 9.0, you can enter more than 255 characters (limited to 8k) as well as extended characters, such as CHR(13) (carriage return) and CHR(10) (linefeed), in the Zoom dialog box for custom user-defined properties and certain native ones. For more information on extended property values, see Properties Window (Visual FoxPro).

Caution:
Property values that exceed 255 characters or include extended characters such as CHR(13) (carriage return) or CHR(10) linefeed are stored in a special format inside the class library (.vcx) or form (.scx) file. The property value will contain special padding with CHR(1) characters. Be aware that classes in visual class libraries (.vcx) or forms (.scx) that contain properties with such values cannot be used in versions prior to Visual FoxPro 9.0. If you attempt to modify these in a prior version, an error occurs. You can still use other classes in the same visual class library (.vcx) files with previous versions of Visual FoxPro as long as they do not contain property values exceeding 255 characters or include carriage return or linefeed characters.

See Also

Other Resources

Dialog Boxes
Properties Window


Wizards (Visual FoxPro)

Visual FoxPro 9.0
Wizards (Visual FoxPro)

Visual FoxPro ships with several wizards. Wizards are interactive programs that help you quickly accomplish common tasks, such as creating forms, formatting reports, setting up queries, importing and upsizing data, graphing, creating mail merge output, generating pivot tables, creating cross-tab queries, and publishing in HTML format for the Web.

By answering questions or choosing options on the series of wizard screens, you are telling the wizard to build a file or perform a task based on your responses.

Most of the wizards have several output options in the last page. These output options are often to files that can be bound into your application. For example, the Web Publishing wizard has an output script option, which creates a program (.prg) file that dynamically generates an HTML page from FoxPro data. You can include this script file in your application and run it from a menu item or button on a form.

Note that additional wizards are available at the Visual FoxPro Web site at http://msdn.microsoft.com/vfoxpro/.

In This Section

Application Wizard

Allows you to create a project and a Visual FoxPro Enhanced Application Framework and then opens the Application builder, so you can add a database, tables, forms, or reports you have created already.
Cross-Tab Wizard

Allows you to create a cross-tab query to summarize data from existing tables.
Database Wizard

Makes it possible for you to use predefined templates to help you create a database containing appropriate tables.
Documenting Wizard

Enables you to format and produce text files from the code in your projects and program files.
Form Wizard

Makes it easy for you to use a single table to create a form for data entry.
Graph Wizard

Allows you to create a graph from a Visual FoxPro table using Microsoft Graph.
Import Wizard

Allows you to move data into Visual FoxPro table (.dbf) files from other file formats, such as plain text, Microsoft Excel, Microsoft Word, and other files.
Label Wizard

Allows you to create labels that you can affix to envelopes and packages or that you can use in your own custom situation.
Local View Wizard

Allows you to create views, which are customized displays of some or all information, using native Visual FoxPro data.
Mail Merge Wizard

Allows you to create either a data source, such as names or addresses, for a Microsoft Word merged document, such as a form letter, mailing labels, envelopes, or catalogs, or a text file, that can be used by any word processor.
One-To-Many Form Wizard

Allows you to create a data entry form that updates several tables from a single form.
One-To-Many Report Wizard

Allows you to create a report that groups records from a parent table with records from a child table.
PivotTable Wizard

Allows you to create interactive worksheet tables used to summarize and analyze data from existing tables.
Query Wizard

Allows you to create a query to select a group of records based on rules you specify.
Remote View Wizard

Allows you to create views, which are customized displays of some or all information, using remote data (ODBC).
Report Wizard

Allows you to create reports using one free table or one table or view in a database.
SQL Server Upsizing Wizard

Allows you to create a SQL Server database that duplicates, as much as possible, the functionality of a Visual FoxPro database.
Table Wizard

Allows you to create tables based on typical table structures and allows you to select a table to fit your needs from a list of sample tables.
Web Publishing Wizard

Displays data from a table or view in an HTML document.

Reference

Related Sections

User Interface Reference

Explains the options that appear on various dialog boxes, windows, and other user interfaces. These types of topics generally appear when you press F1 in a dialog box or window.
Creating Applications with the Application Framework

Explains how to create applications with the Application Framework using the Application Wizard and the Application Builder.
Builders

Describes how Builders aid in setting properties of controls on a form. Unlike wizards, builders are reentrant, so you can reopen a builder on a particular control repeatedly.
Windows

Explains the options that appear on various dialog boxes, windows, and other user interfaces.
Dialog Boxes

Explains the options that appear on various dialog boxes.
Designers

Describes how Designers make it possible for you to design the windows, dialog boxes, and components in your application visually.


Application Wizard

Visual FoxPro 9.0
Application Wizard
See Also

The Application Wizard creates a Project and a Visual FoxPro Enhanced Application Framework and then opens the Application Builder, so you can add a database, tables, forms, or reports you have created already. You also can create a new application in the Application Builder using database or table templates.

To access the Application Wizard from the Tools menu, choose Wizards, and click Application.

The wizard will display a dialog box in which you can specify the name and location of your new application.

Project name edit box

Makes it possible for you to specify the name of the project that is displayed in the Project title bar.
Project file edit box

Makes it possible for you to specify the file name and location of the new project.
Browse button

Makes it possible for you to locate an existing project file to use in the Application Builder.
Create project directory structure check box

Makes it possible for you to determine whether or not to have Visual FoxPro create the project directory structure for you automatically. The wizard creates a template that includes all possible application files, although you might not need them all. If you already have created your application files, leave this box cleared.

The Application Wizard will display a wait window that prompts you to wait as it generates the necessary Application framework file structure, the Visual FoxPro Application framework, for your application. When the process has completed, the wizard will display the new project window and the Application Builder so you can complete the details of your new application.

See Also

Other Resources

Application Builder
Application Framework Files
Visual FoxPro Framework Application Object
Wizards Overview
Application Wizard Object Members


Visual FoxPro Framework Application Object

Visual FoxPro 9.0
Visual FoxPro Framework Application Object
See Also

The enhanced framework _application class includes, aside from its properties and methods, five objects: cuserror, cusdatasession, cuswindowhandler, custablesort, and custablenav.

The application object contains code for standard methods and includes a set of new methods that provide most of the enhanced functionality of the enhanced Application Framework in this version of Visual FoxPro. You can access the details of _application and its contained objects in _framewk.vcx.

See Also

Other Resources

Application Builder
Wizards Overview
Application Wizard Object Members
Application Wizard


Application Wizard Object Members

Visual FoxPro 9.0
Application Wizard Object Members
See Also

When an Application Wizard creates a new project, it automatically generates two forms for the new application, a Quick Start form and an About form, subclassed respectively from the wzQuickStartForm and Wzaboutdialog forms in the Appwiz.vcx library.

The subclassed forms are containers for the following objects.

Wzaboutdialog Members

Object | Class | Description
cmdOK | CommandButton | Releases the form.

WzQuickStartForm Members

Object | Class | Description
CmdClose | CommandButton | Closes the QuickStart form.
CmdRun | CommandButton | Runs the form currently selected in the list box.
LblForms | Label | Text label.
LstForms | List Box | Contains a list of all forms defined in the application, generated automatically in the list box's Init method. When the user double-clicks the name of a form, the form is run.

See Also

Reference

Application Wizard Object Members

Other Resources

Wizards Overview
Visual FoxPro Framework Application Object


Cross-Tab Wizard

Visual FoxPro 9.0
Cross-Tab Wizard
See Also

This wizard creates a cross-tab query for summarizing table data in a spreadsheet format.

To access the Cross-Tab wizard

  1. From the Tools menu, choose Wizards, and click Query.

  2. In the Wizard Selection dialog box, choose Cross-Tab Wizard.

Step 1 - Select Fields

In this step, you can choose a free table or a table within a database as the source for your pivot table. You can select only fields from a single table or view. For more information, see Working with Views.

To select the fields for your cross-tab query

  1. Use the Databases and Tables controls to locate and select the table you want to use.

  2. In the Available fields window, select three or four fields you want to use from the selected table, and use the arrow buttons to move them to the Selected fields window.

You need to choose at least three fields; one each for row values, column values, and data.

Step 2 - Define Layout

In this step, you can specify which field values will be calculated for the data. For example, if you have an Orders table that contains, among others, a field for city, a field for region, and a field for order amount, you could create a pivot table that would display in the data area, sums for all the cities, by region. At the bottom, the table will display totals for each column. At the far right, the table will display totals for each row.

To define the cross-tab layout

  1. From the Available fields list, drag a field to the Rows box. The cross-tab query will contain a row for each unique value in the field that you drag to the Rows box

  2. From the Available fields list, drag a field to the Columns box. The cross-tab query will contain a column for each unique value in the field that you drag to the Columns box

  3. From the Available fields list, drag a field to the Data box. Because this field will be summarized, generally it is best to drag a numeric field here.

If you have a large table, you might want to first create a view that contains the desired fields and then create a cross-tab query from that view.

Step 3 - Add Summary Information

In this step, you can determine if you want to add a subtotal column and summary information in your data. To add summary information, select the appropriate radio button (Sum, Count, Average, Max, or Min) in the Summary section. To add a subtotal column, select the appropriate radio button (Sum of data, Number of cells containing data, or Percentage of the table total) in the Subtotals section. If you do not want to add a subtotal column, select the None radio button in the Subtotals section. The totals will appear in the rightmost column of your cross-tab query results.

Step 4 - Finish

This step makes it possible to save and specify the use of your cross-tab query.

Save cross-tab query

Saves the cross-tab query for use later.
Save and run cross-tab query

Saves the cross-tab query and runs it immediately.
Save cross-tab query and modify in the Query Designer

Saves the cross-tab query and opens it in the Query designer so you can modify it.

You can preview your cross-tab query by clicking the Preview button. To view null values, select the DisplayNull Values check box.

At any point after you save the cross-tab query, you can open and modify it as you would with any other query in the Query and View designers.

See Also

Other Resources

Wizards Overview
Query Wizard
Query and View Designers
How to: Create Queries


Database Wizard

Visual FoxPro 9.0
Database Wizard
See Also

The Database wizard uses predefined templates to help you create a database containing appropriate tables.

The following templates are included in Visual FoxPro.

Note:
You can use the Application wizard to create an application that uses these templates.

Template | Description
Address Book | Includes a table for a personal address book.
Asset Tracking | Includes tables useful in documenting assets and costs.
Books | Includes tables useful in documenting authors and books.
Contact | Includes tables useful in documenting and managing contacts.
Donation | Includes tables useful in managing donation campaigns.
Event Management | Includes tables useful in planning and managing events and personnel.
Expenses | Includes tables useful in documenting employee expenses and reporting.
Household Inventory | Includes tables useful in managing household furniture and equipment.
Inventory Control | Includes tables useful in tracking inventory.
Ledger | Includes tables useful in managing transactions.
Membership | Includes tables useful in managing club or other membership groups.
Music Collection | Includes tables useful in managing recordings collections.
Order Entry | Includes tables useful in managing order entry operations.
Picture Library | Includes tables useful in managing collections of film and photographs.
Recipes | Includes tables useful in managing household recipes.
Resource Scheduling | Includes tables useful in specifying, scheduling, and managing resources.
Service Call Management | Includes tables useful in managing service call jobs and personnel.
Students and Classes | Includes tables useful in managing students, teachers, facilities, and educational programs.
Time and Billing | Includes tables useful in managing client and employee accounts.
Video Collection | Includes tables useful in managing collections of videotapes.
Wine List | Includes tables useful in managing wine collections.
Workout | Includes tables useful in planning and managing a physical fitness program.
To access the Database wizard

  1. Open Visual FoxPro.

  2. From the Tools menu, choose Wizards, and click Database.

Step 1 – Select a Database

In this step, you can select a Visual FoxPro database template from the list in the Select database section. For more information about each of these templates, see the previous table. Alternatively, you can specify Visual FoxPro database or select an Access (.mdb) database template by clicking the Select button. This displays the Open dialog box from which you then locate the remote database to use as a template.

Step 2 – Select Tables and Views

In this step, you can choose the tables and views you want to include in your database. The template you specified in Step 1 provides a list of pre-selected tables and views. Select the check boxes for the tables or views you want to use in your database.

Step 3 – Index the Tables

In this step, you can determine how you want to index your tables. You can select which field you want to use as the primary index key.

To specify a field as primary index key

  1. In the Select table list box, highlight the table containing the field you want to use.

  2. In the Primary key list box, highlight the field you want to use.

You also can select check boxes beside the options offered in the Field Name section to create additional indexes.

Step 4 – Set up Relationships

In this step, you can establish or change the relationships between the tables in the database.

To specify a relationship between tables in your database

  1. In the Select table list box, highlight the table containing the field you want to use.

  2. In the My newXtable list box (with X being the name of the table), highlight the relationship statement you want to edit, and then click the Relationships... button.

  3. In the Relationships dialog box, click the radio button next to the description of the type of relationship you want to create. You can select the key field or create a new field by typing in the edit box.

  4. Click OK. This returns you to Step 4 where the new or edited relationship is listed in the My newXtable list box.

Step 5 – Finish

In this step, you select the final options for your database:

Save database for later use — Saves your database.

Save database and modify it in the Database Designer — Saves your database and opens it in the Database designer for further modification.

Populate tables with sample data — populates the new database with the sample data in the template.

After the wizard generates the database, you can add the database to a Project Manager window or to the Component Gallery, or you can open the Database designer to modify the database tables and relationships.

See Also

Other Resources

Wizards Overview
Project Manager Window
Using the Component Gallery
Database Designer


Documenting Wizard

Visual FoxPro 9.0
Documenting Wizard
See Also

The Documenting wizard formats and produces text files from your code in projects and program files. You can use these files to share the code or to more easily read large sections in projects and programs. For example, the wizard can produce files containing indented source code, capitalized reserved words and variables, and can also produce a report of the keywords in the program.

Note:
The wizard does not modify your code and only creates a text file to document the code.

You can customize the way the Documenting wizard works by adding certain directives to your code. For more information, see Customizing Documenting Wizard Output.

To access the Documenting wizard from the Tools menu, choose Wizards, and click Documenting.

Step 1 – Choose Source File

In this step, you can enter the name of a project file or a specific program file. If you choose a project file, the Documenting wizard documents all the programs in the project, including the event code for forms, class library code, and so on.

Step 2 – Set Capitalization

In this step, you choose how the Documenting wizard should capitalize keywords and symbols in the text file of your code. Keywords are all the reserved words in the Visual FoxPro programming language, such as MODIFY. Symbols are the variables and names that you define in your code. Capitalization makes it easier to read and identify elements in your code. The capitalization options are:

UPPERCASE

Keywords and symbols are displayed in all uppercase letters.
lowercase

Keywords and symbols are displayed in all lowercase letters.
MixedCase

Keywords are displayed with the first letter of each word in the keyword capitalized, for example, AddObject.
Match first occurrence

Symbols are displayed according to the capitalization of the first occurrence in the file. For instance, if you use initial capitals in the first occurrence in a file, all other occurrences of those keywords are displayed the same way, no matter how they might be typed in subsequent occurrences.
No change

Keywords and symbols are not modified.

Step 3 – Set Indentation

In this step, you specify how the Documenting wizard will indent lines in the text file of your code. The wizard can indent specific types of lines, and you can adjust how many spaces to use when indenting. Functionally, in code, there is no difference between spaces or tabs. Indenting makes it easier to read and understand your code.

Type of Indent

Choose whether the wizard should indent using tabs or spaces. To turn off indentation, choose No Change. If you choose Spaces, then you must select the number of spaces to be used. If you choose Tabs, then the Documenting wizard uses the current Visual FoxPro tab setting.
Text to indent

Specify the type of line that the wizard should indent. Your choices are Comments, Controls structures (such as loops, IF blocks, and DO CASE structures), and Lines continued by a semi-colon (statements that are split across multiple lines).

Step 4 – Add Headings

In this step, you specify where, if anywhere, you want the Documenting wizard to insert headings into the text file of your code. Headings are comments about the code that are relevant to the code that they precede. They can be placed at the beginning of files, procedures, class definitions, and methods to make your formatted code more understandable.

Step 5 – Select Reports

In this step, you specify the types of reports that the Documenting wizard creates. (The reports are actually text files.) The wizard can produce the types of reports listed in the following table.

Report Type | File Name | Remarks
Action Diagram | project.act | Shows the hierarchical relations within your code. If you are not working with ASCII code page 1250 and ANSI code page 1252, see the directive "*# document ACTIONCHARS" in Customizing Documenting Wizard Output.
Cross-Reference | Xref.lst | Lists all the user-defined symbols.
File Listing | Files.lst | Lists all the files in the project.
Source Code Listing | project.lst | Puts all formatted code in a single file.
Tree Diagram | Tree.lst | Shows the procedure calling tree.

The wizard also automatically creates the following files:

  • Files.dbf Table with a record for each file in the project.

  • Fdxref.dbf Table with a record for each instance of user symbols (as listed in the following table) in the code. This table makes it possible for you to see what type of Visual FoxPro element is represented by each symbol.

Note:
Fdxref.dbf contains a field named Flag for identifying the keywords. The identifiers are the following.

Flag | Description
B | Base class
C | Class name
D | Defined PROCEDURE or FUNCTION (not method)
F | Function call: myproc( ) or DO myproc
K | Keyword
M | Method definition
N | Name of file
O | Object
P | Property of an object
R | User symbol reference
V | User symbols (variable) definition (PARA, PRIV, PUBL, DIME)

Step 6 – Finish

In this step, you can determine the location and structure that contains your code document. You also can specify whether the current document overwrites any previous documents.

By default, the wizard does not overwrite your existing files. Specify Overwrite existing files to overwrite your existing code files with the new ones that the wizard saves.

You can choose to have a single directory in which the wizard will save all the files, by selecting the Place files in a single directory option. When you click Finish, the wizard will prompt you to choose a directory that it creates.

To choose a new directory that will contain the full project tree of your project, select the Place files in a new directory tree. When you click Finish, the wizard will prompt you to choose a directory where it will create a copy of the project's source tree and save the new, formatted program files in the appropriate directories of the new tree.

When you select Cross-reference keywords, the wizard creates or adds to Fdxref.dbf, the table of keywords mentioned earlier. After running the wizard, you can use the table to create reports of the keywords you are using in your application. The wizard adds one record to Fdxref.dbf for each instance a of Visual FoxPro keyword in your code.

In addition, when this option is selected, the wizard matches keywords in your code with the first field, named Token, in the Fdkeywrd.dbf file. This file can be found in the ..\Wizards folder of the Visual FoxPro root directory and contains all the Visual FoxPro reserved words. The second column, Code, in Fdkeywrd.dbf contains an identifier that tells the wizard how to treat the keyword when analyzing your code. The following table describes the identifier codes.

Code | Description
I | Indent
U | Un-indent (remove indent)
R | Reset indentation to 0 (or 1 if in DefineClass)
F | Procedure or function
D | While or Case: DO clause
O | Object (Spinner, CommandButton)
P | Property (Scalemode, DecimalPoints)
M | Method (Init, KeyPress)
C | ClauseUsed only as a Clause: can't start a statement
Note:
Depending on the size of your code, this option might enlarge Fdxref.dbf by a large number of records. Before running the wizard and choosing the option to create keyword cross-references, be sure you have enough disk space.

When you select Run analyzer, the wizard starts the Visual FoxPro Code Analyzer, which dynamically traces the structure and symbols in Visual FoxPro application files. Code Analyzer provides visual controls, a menu, and keyboard options to navigate through the text file of your application file code by using output from the Documenting wizard.

See Also

Other Resources

Customizing Documenting Wizard Output
Wizards Overview
Code Analyzer


Customizing Documenting Wizard Output

Visual FoxPro 9.0
Customizing Documenting Wizard Output
See Also

In addition to the options that you choose when running the Documenting wizard, you can employ additional options outside the wizard by changing the Fdkeywrd.dbf table, which contains all the Visual FoxPro reserved words, in the ...\Wizards folder or by adding Documenting wizard directives to your code.

Changing the Fdkeywrd.dbf

You can change the style of indent of the CASE structure by changing the code field value in Fdkeywrd.dbf. By default, the wizard looks for indentation in a CASE structure like this:

Copy Code
DO CASE
CASE case1=1
   case2=2
CASE case3=3
   case4=4
ENDCASE

Some developers prefer to indent the lines between DO CASE and ENDCASE an additional level like this:

Copy Code
DO CASE
   CASE case1=1
      case2=2
   CASE case3=3
      case4=4
ENDCASE

If you indent your CASE structures, as in the second example, specify this in Fdkeywrd.dbf.

To specify wholly nested indents in DO CASE statements

  1. Locate the Fdkeywrd.dbf file in the ...\Wizards folder of the Visual FoxPro root directory.

  2. Open the Fdkeywrd.dbf table.

  3. Locate the ENDCASE record.

  4. Change the value in the Code field to UU.

Adding Wizard Directives

You can place special directives in your code files that instruct the Documenting wizard to perform specific tasks when analyzing the code. The available wizard directives are as follows:

ACTIONCHARS

Specifies the characters used to create action or tree diagrams of your code. You might want to change the default settings if you use code pages other than ASCII 1250 or ANSI 1252 in FoxFont to get the characters you expect.
EXPANDKEYWORDS

Specifies whether keyword expansion is active or not in the Documenting wizard. The default value is OFF, which retains keywords as typed in code. If you have used four-character abbreviations throughout your code, you might want to make the code more reader friendly by setting keyword expansion ON.
XREFKEYWORDS

Specifies whether the wizard creates a file that shows all keywords and their locations in the code document. The file contains the keyword names, keyword type (according to the Fdxref.dbf table, as described in Step 5 of the Documenting wizard), the line it is located on, and the file containing it. The default is ON.
ARRAYBRACKETS

Specifies whether square brackets and parentheses are treated differently. The default, ON, treats square brackets as array delimiters and parentheses as function or method delimiters.
ACTIONINDENTLENGTH

Specifies the number of character spaces the wizard uses for indentation in tree or action diagrams. The minimum value is two characters. Functionally, in code, there is no difference between spaces or tabs. Indenting makes it easier to read and understand your code.

You can place wizard directives in the main program file of your project (to direct the wizard to analyze all code files in the project) or in individual code files (to instruct the wizard how to analyze specific files).

The syntax of the directives begins with an asterisk, so Visual FoxPro will treat them as comments and ignore them when compiling programs. The directives are not case sensitive. The syntax of the directives is:

Copy Code
*# document directive

For consistency throughout your code, it is a good idea to place the directives near the beginning of the main program file, so the Documenting wizard encounters the instruction when it begins analyzing.

The Documenting wizard directives are described below.

*# document ACTIONCHARS " abcdef"

By default, when the wizard creates an Action Diagram or a Tree Diagram, the wizard uses six characters that appear as lines and square corners when viewed under ASCII code page 1250 or under ANSI code page 1252 in FoxFont. Not all the characters map to line characters when viewed under other code pages. The six default characters and their corresponding FoxFont characters are listed below as a, b, c, d, e, and f.

abcdef Default Chr( ) Value As viewed in FoxFont

a

32

(space)

b

196
FoxProHorzLine screenshot

c

179
FoxProVerticalLine screenshot

d

218
FoxPro90DegreeTurnLine screenshot

e

192
FoxPro90DegreeTurnLine2 screenshot

f

195
FoxProTsectionLine screenshot
Tip:
When using other code pages, insert the following code in your main program file to ensure that the lines in your diagrams map to line-like characters (the first character of the string enclosed in quotes is a space):

Copy Code
*# document ACTIONCHARS " -|+++"
Note:
For a list of supported code pages, see Code Pages Supported by Visual FoxPro.

*# document XREF cMode

Enables cross-referencing of variables. The default is ON.

cMode Description

ON

Enables cross-referencing of variables

OFF

Disables cross-referencing of variables

SUSPEND

Disables cross-referencing of variables in the current file until the Documenting Wizard encounters the next instance of:

*# document XREF ON

*# document EXPANDKEYWORDS cMode

Enables the expansion of abbreviated keywords in your code. For example, "DEFI WIND" would be expanded to "DEFINE WINDOW." The default is OFF.
Caution:
Not all keywords in Visual FoxPro begin with a unique string of four characters. For example, "REPL" could be short for "REPLACE" or "REPLICATE." Be careful if you include this directive and choose to overwrite existing files.

cMode Description

ON

Enables keyword expansion

OFF

Disables keyword expansion

SUSPEND

Disables keyword expansion in the current file until the next instance of:

*# document EXPANDKEYWORDS ON

*# document XREFKEYWORDS cMode

This directive corresponds to the Cross-Reference Keywords option on "Step 6 – Finish" in the Documenting Wizard. The default is OFF.

cMode Description

ON

Enables cross-referencing of keywords

OFF

Disables cross-referencing of keywords

SUSPEND

Disables cross-referencing of keywords in the current file until the next instance of:

*# document XREFKEYWORDS ON

*# document ARRAYBRACKETS cMode

The default is OFF.

cMode Description

ON

The Documenting Wizard assumes that square brackets are used for arrays and that parentheses are used for functions and methods.

OFF

The Documenting Wizard treats both square brackets and parentheses as arrays.
*# document ACTIONINDENTLENGTH nSpace

nSpace is the number of character spaces that you want the Documenting Wizard to use for indentation. The minimum value allowed is 2.

See Also

Other Resources

Documenting Wizard
Wizards Overview
Code Pages Supported by Visual FoxPro


Form Wizard

Visual FoxPro 9.0
Form Wizard
See Also

This wizard makes it easy to use a single table to create a form for data entry. The wizard will populate the form automatically with all the fields from the table, so you can delete or rearrange them as you want. The size of the form is based on your Maximum design area setting on the Forms tab in the Options dialog box. Field mapping (what a form displays) is controlled by settings in the Field Mapping tab of the Tools menu, Options dialog box. This tab is not available while the Form wizard is open.

To access the Form wizard

  1. From the Tools menu, choose Wizards, and click Form.

  2. In the Wizard Selection dialog box, choose Form Wizard.

If you create a form within a database, the Form wizard can use input mask and format settings stored in the database. After you save the form, you can open and modify it later like any other form in the Form designer.

Step 1 - Select Fields

In this step, you can choose a free table or a table within a database as the source for your form. You only can select fields from a single table or view.

To select the fields for your form

  1. Use the Databases and Tables controls to locate and select the table you want to use.

  2. In the Available fields window, select one or more fields you want to use from the selected table and use the arrow buttons to move them to the Selected fields window.

Step 2 - Choose Form Style

In this step, you specify what the controls on your form will look like. When you click any of the styles listed in the Style text box, the wizard displays a picture in the magnifying glass as an example of the style.

The Button Type options refer to your form's navigation buttons.

Text Buttons

Places navigation text on the buttons of your form.
Picture buttons

Places navigation icons on the buttons of your form.
No buttons

Places no buttons on your form, so you can prevent navigation beyond the displayed or entered data.
Custom

Makes it possible for you to choose between two types of scrolling data windows.
  • Scrolling grid - Displays the fields you select from one record at a time.

  • Scrolling grid (justified) – Displays the fields you select from as many records, at one time, as will fit in the form.

The navigation buttons that the wizard creates on your form are as follows.

Button | Icon | Description
Top |  | Moves record pointer to first record.
Prev |  | Moves record pointer back one record.
Next |  | Moves record pointer forward one record.
Bottom |  | Moves record pointer to last record.
Find |  | Displays the Search dialog box.
Print |  | Prints a report.
Add |  | Adds a new record to the end of the table.
Edit |  | Makes it possible for a user to change values in current record.
Delete |  | Deletes current record.
Exit |  | Closes form.
Note:
After the wizard saves a form, you still can add fields to it using the same styles by selecting Quick Form on the Form menu to bring up the Form builder.

All controls created by the Form wizard and the Form builder are in the \Wizards directory in the file Wizstyle.vcx. If you want to modify the styles, modify the classes in this file using the Class designer.

Step 3 - Sort Records

Select the fields in the order that you would like to sort the records within each group. For example, if you are using two fields and have a first name field and a last name field, then you could choose to sort on first name+last name (such as PaulWilson) or on last name+first name (such as WilsonPaul). How you sort is determined by the order in which you selected those fields.

If your table already has one or more indexes, you can select the tag, which is listed below the fields in the Available fields window.

Step 4 - Finish

If you chose a large number of fields earlier and want to make sure they all fit on the form, you can select Add pages for fields that do not fit. Otherwise, if the number of fields exceeds the size of the form, Visual FoxPro provides a scrolling form.

You can use field mappings specified in the Options dialog box of the Tools menu or override those settings with information in the database. To preview the form before exiting the Form Wizard, click the Preview button.

After you save the form, you can open and modify it later like any other form in the Form designer.

See Also

Other Resources

Wizards Overview
Forms Tab, Options Dialog Box
Form Designer


Graph Wizard

Visual FoxPro 9.0
Graph Wizard
See Also

The Graph wizard creates a graph from a Visual FoxPro table using Microsoft Graph. You will want to use a graph of one kind or another to make it easier to visually display or evaluate data contained in large tables or reported in dense spreadsheets.

The larger your table is, the longer it will take the wizard to process your graph. You might consider limiting the scope of records in a large table by creating a view before you run the Graph wizard. For more information, see How to: Create Queries.

To access the Graph wizard

  1. From the Tools menu, choose Wizards, and click Query.

  2. In the Wizard Selection dialog box, choose Graph Wizard.

Step 1 – Select Fields

In this step, you can choose a free table or a table within a database as the source for your graph. This can normalize the input in data entry forms, and thereby, your data tables. You can select fields from only a single table or view. This selection must include at least one numeric field.

To select the fields for your graph

  1. Use the Databases and Tables controls to locate and select the table you want to use.

  2. In the Available fields window, select one or more fields you want to use from the selected table, and use the arrow buttons to move them to the Selected fields window.

    Note:
    If you choose a general or automation field in this step, the field will not be available in the next step for defining the graph layout.

Step 2 – Define Layout

In this step, you specify which numeric field is graphed and which field provides the divisions along which those values are graphed. Drag one or more of the available numeric fields from the Available fields window to the Data series window. Drag another field from the Available fields window to the Axis box beneath the graph picture. For example, in a table containing salary amounts as a numeric field, you might choose the salary field and a name or a region field to chart against.

Step 3 - Select Graph Style

In this step, you select a style of graph that effectively presents the information. Each graph style plots the data in a different manner. Look at the pictures on the buttons to choose a style that meets your needs. The following list summarizes the available chart types:

Area and 3D area

Indicates the relative importance of values over a period of time, and it emphasizes the amount of change rather than the rate of change.
Bar and 3D bar

Indicates values of discrete elements relative to each other. This is similar to a column chart but arrayed vertically.
Column and 3D column

Indicates variation over a period of time or draws comparisons between discrete items. The horizontal array of columns suggests time flow more than a bar chart.
Pie and 3D pie

Indicates the relationships or proportions of parts to a whole. This type of graph always contains just one data series.
Line and ribbon (3D line)

Indicates trends or changes in data over a period of time. This is similar to an area chart, but it emphasizes time flow and rate of change rather than amount of change.
Scatter (XY)

Indicates the relationship or degree of relationship between numeric values in different groups of data. This type of chart is useful for determining patterns or trends and for determining whether variables are dependent upon or affect one another.

Step 4 - Finish

In this step, you specify the way the graph is output and whether it will display the name of the selected numeric field and null values. You can save the graph to a form, you can use the graph on a report by saving it to a table, or you can create a query that generates the graph.

Saving to a Form

If you choose to save the graph to a form, the wizard creates a form containing the graph, and optionally, a legend of the charted value(s).

Saving to a Table

If you choose to save the graph to a table, the wizard creates a table with a single record containing a General field that stores an Automation object for your graph. You then can include this field on a report. After the wizard is finished, it leaves your new table open. To view the graph, browse the new table and double-click the Olegraph field.

Creating a Query

If you choose to create a query, the wizard saves a query that sends its results to the graph you have specified. After the wizard saves the query, you can open and modify it like any other query in the Query designer.

Show null values check box

Specifies that the graph represent any null values as well as all positive and negative values. For example, it might be important to your presentation to show that nothing happened on particular days or with particular clients.
Add a legend to the graph check box

Specifies that the graph include a legend naming the graphed value. This helps make your graph and its data more readable.
Preview button

Makes it possible for you to see the graph before saving it to a form, table, or query file.

See Also

Other Resources

How to: Run Queries
Cross-Tab Wizard
Local View Wizard
Query Wizard
Remote View Wizard
Wizards Overview
How to: Create Queries


Import Wizard

Visual FoxPro 9.0
Import Wizard
See Also

You can use the Import wizard to move data into Visual FoxPro table (.dbf) files from other file formats, such as plain text, Microsoft Excel, or Word, and other files. For example, you might have a list of names and addresses in a Word file that you would find easier to use and more effective if it were in a Visual FoxPro table.

To access the Import wizard

  1. From the Tools menu, choose Wizards, and click Import.

Step 1 – Identify Data

In this step, you identify the type and location of the data you want to import.

File Type drop-down list

Provides a list of known file types from which you can choose.
Source File edit box

Makes it possible for you to choose or to specify a file name and location. If you do not know either you can use the Locate button to find the file.
New table radio button

When you specify a destination file name and location, the wizard prompts you with a new table name in the same directory. The edit box makes it possible for you to specify a different name or location for the destination file. You can use the Locate button to specify another new file and location.
Existing table radio button

If you choose this button, the edit box makes it possible for you to specify the name and location of an existing file. If you do not know either you can use the Locate button to find the file.

Step 1a – Select a Database

In this step you can specify a database to which your table is added. You also can decide to import your data into a stand-alone table. If you choose a database, you can have enhancements like automatic and custom formatting options. For information on database enhancements, see Creating a Database

Step 2 – Determine Data Format

In this step, you can specify how the imported data was formatted — with or without delimiting characters between fields or columns and rows or as a single fixed-width column. You also can specify where within the file you want to begin importing data.

Delimited

Specifies that the fields in the file are separated by a character, such as a comma (,) or a semicolon (;).
Fixed Width

Specifies that the fields in the file are aligned in columns.
Field names in row

Makes it possible for you to specify the row of imported data that contains the field names. For instance, if the first line of your imported data contains the desired field names, set Field names in row to 1. If, however, field names are not part of the imported data, then in Step 3, you can specify field names for the new table. The Import wizard automatically replaces spaces with underscores and reduces field name size to fit the 10-character maximum.
Begin import at row

Makes it possible for you to specify the starting row of data in the imported file. This option makes it possible for you to avoid importing header data.

If you are importing a spreadsheet, this step offers a drop-down list of worksheets available in the selected spreadsheet.

Step 2a – Describe Data or Set Columns

Step 2a of the Import wizard only appears if you have chosen to import a text (.txt) file. Depending on what you chose as the Data format in step 2, you will get one of two options for step 2a: Describe Data or Set Columns.

Describe Data

This step appears as Describe Data, if you select Delimited as the Data format in step 2. Select what delimiter separates the text strings in the selected file. View the effect of the delimiter selected in the Field grid in the lower portion of this wizard dialog box.

Set Columns

This step appears as Set Columns, if you select Fixed Width as the Data format in step 2. You can use the Field grid in the lower portion of this wizard dialog box to specify more columns by clicking below the displayed data, so the imported information is divided into discrete fields.

Step 3 - Define Imported Fields

In this step, you specify the name of the columns in the table, the data type of the columns, and the width of the columns. Click below the existing heading of the column in the Field grid and edit the information listed in the Name, Type, Width, and Decimal drop-down lists.

If you do not want to import a specific column, click below the existing heading, and then press DELETE. The space for the column will still be visible (without a column heading name), but when you finish the wizard and import the data, that column will be ignored.

Worksheet

Specifies the name of the worksheet if you are importing an Excel spreadsheet.
Field Grid

For a text file, this grid displays, at the bottom of the wizard dialog box, the record number and data as it is found in the file. For other types of files, it displays the file data as it will appear when you have completed the Import wizard.

Step 3a – Specify International Options

In this step, you can specify alternative settings for internationalization of the data to be imported into the table. You can choose to change the code page, currency symbol, 1000 separator, decimal separator, and date format.

Code Page button

Changing the code page can affect the way your charts appear, because the characters that form lines and corners differ among code pages. This option makes it possible for you to select from code pages supported by Visual FoxPro.
Currency Symbol edit box

This setting makes it possible for you to override the default currency setting for the file created by this wizard.
1000 Separator edit box

This setting makes it possible for you to override the default 1000 separator for the file created by the Import wizard.
Decimal Separator

This setting makes it possible for you to override the default decimal separator for the file created by the Import wizard.
Date Format

This option makes it possible for you to select one of the date formats supported by Visual FoxPro. For more information, see Dateformat Property.

See Also

Other Resources

Wizards Overview
Graph Wizard
How to: Import Data with the Import Wizard
Importing and Exporting Data
Developing International Applications
Dateformat Property


Label Wizard

Visual FoxPro 9.0
Label Wizard
See Also

You can create labels that you can affix to envelopes and packages or for custom use by using the Label Wizard. In the wizard, labels are generated from the entries in a table. For information about starting the Label Wizard, see How to: Create Labels.

Step 1 – Select Tables

In this step, you select a table or view as the source for your labels. If you use a table, then you will get all the fields in the table to use on your label. Choosing a view can make it possible for you to pre-select certain records or certain fields in each record from a table.

Step 2 - Choose Label Type

In this step, you can choose a standard or custom label by name, size, and available columns.

The wizard lists the standard label types that are installed with Visual FoxPro. The wizard also lists any label types you create using the AddLabel application in the \Tools folder.

You also can launch the Add Label wizard by clicking the New Label button. For information, see How to: Add a Label Definition Using Addlabel.app.

Step 3 – Define Layout

In this step, you select the fields you want to use on the label and specify the layout, font, and any commentary text you want to appear on the label.

Add the fields in the order you want them to appear on the label. You can use the punctuation (comma, period, colon, and hyphen), new line, and Space buttons to format the label. Use the Text box to add text. You also can use the Font button to change the font used on labels.

As you add items to the label, the picture in the wizard window is updated to show approximately how your label will look. Check this picture to see if the fields you have chosen will fit on the label. The text lines will extend beyond the bottom edge of the label if there are too many lines.

Step 4 – Sort Records

In this step, you can specify the sort order of your labels. For example, if they are to be mailing labels, then you might sort by city, state, or zip code. However, if they are folder or party labels, then you might want to sort alphabetically by names.

Select the fields or index tag in the order that you would like to sort the records.

Step 5 - Finish

In this step, you choose how to save your labels. You can save them for later use; you can save them for modification in the Label designer, which makes it possible for you to use one of the default labels as a basis for a custom label of your own design; or you can print the labels immediately from Visual FoxPro.

You can choose Preview to verify your choices before finishing.

See Also

Other Resources

Wizards Overview
Working with Tables
Working with Reports


Local View Wizard

Visual FoxPro 9.0
Local View Wizard
See Also

With the Local View wizard, you can create views, which are customized displays of some or all information, using native Visual FoxPro data. You might want to use a view if the amount of source data is large, but you only need to display a particular portion of that data. If you do not have a database open, you are prompted to open a database or create one.

To access the Local View wizard

  1. From the Tools menu, choose Wizards, and click Query.

  2. In the Wizard Selection dialog box, choose Local View Wizard.

Step 1 – Select Fields

In this step, you specify which tables or views from a Visual FoxPro database you want to use as source for your local view. Using a view, you can gather information from one or more tables into a single display of information. A local view, unlike a Browse window, can make it possible for you to create very effective, perhaps simple, display from large or complex data sources.

You can select fields from several tables or views. First, select fields from one table or view and move them to the Selected fields box; then select fields from another table or view and move those.

Step 2 – Relate Tables

This step displays only if you select fields from more than one table or view. You can specify which fields in each table or view contain like information and can govern the relationship between the tables or view, thereby determining the included records.

Select the desired fields from the two drop-down list boxes, and then choose Add. If you use multiple tables in your view, then you must relate the tables by indicating which fields contain matching data in each table.

Step 2a – Include Records

This step displays only if you select fields from more than one table or view. You can specify which records from the selected tables will be made available to the Local View wizard.

If you are using more than one table, you can specify a join condition. For more information, see How to: Add Tables to Views. For example, if you specify only matching rows in Step 2a, you can further refine that choice in Step 3 by specifying a particular value for a field.

Limit the records to only matching rows

Returns only records from both tables that match the comparison condition set between the two fields in the join condition. This is called an inner join.
All rows from either table

Returns all the rows from the selected table. This makes it possible for you to create a left or right outer join.
All rows from both tables

Returns matching and non-matching records from both tables. This is called an outer join.

By default, only matching records are included.

Step 3 – Filter Records

This step appears immediately after Step 1 if you have chosen only one table or view as source for your local view. You can specify a filter condition, so only certain of the records you have chosen to make available are used in the local view.

To determine the filter condition

  1. Select a field from the Field drop-down list.

  2. Specify an operator, such as equals or contains, in the Operator drop-down box.

  3. Specify a value in the Value textbox.

    For example, if you wanted to filter on a specific city, such as Helena, you might choose city from the Field drop-down list, choose equals in the Operator drop-down list, and enter Helena in the Value textbox.

You can reduce the number of records by creating expressions that filter records from the selected tables or views. You can create two expressions and connect them with And, which returns only records meeting both specified criteria, or Or, which returns records meeting either criteria.

You can see the result by clicking the Preview button.

Step 4 – Sort Records

This step makes it possible for you to specify one or more fields by which to sort the records in your local view.

Choose up to three fields or an index tag that already exists in the database to determine the order in which your view results will be sorted. Select Ascending to sort the view in ascending order or Descending to sort the view in descending order.

Step 4a – Limit Records

This step appears only if you have specified one or more sort fields in Step 4. You can further limit the number of records in the view, based on either a percent of the records returned or an actual number of records.

To see a percentage of the available records, choose the Percent of records radio button, and then specify the percentage in the Portion value edit box. See all records by selecting Number of records and then selecting All records. As shown in the following procedures, you can choose a portion of records from the beginning or the end of the available records.

To see the first 10 items

  1. Choose the Number of records radio button.

  2. Enter 10 in the Portion value box.
To see the last 10 records

  1. In Step 4, change the sort order to Descending.
Note:
This changes the sort order to last record = first read.

  1. In Step 4a, select the Number of records radio button.

  2. Enter 10 in the Portion value box.

Step 5 - Finish

In this step, you can choose how to handle the newly defined local view.

Save local view

Saves the newly defined local view and exits the wizard.
Save local view and browse

Makes it possible for you to save the new local view and then open it in a Browse window, so you can review the displayed data.
Save local view and modify it in the View Designer

Makes it possible for you to save the new local view and then modify it when it opens in the View designer.

See Also

Other Resources

Query Wizard
Remote View Wizard
Wizards Overview


Mail Merge Wizard

Visual FoxPro 9.0
Mail Merge Wizard
See Also

The Mail Merge wizard creates either a data source, such as names or addresses, for a Microsoft Word merged document, such as a form letter, mailing labels, envelopes, or catalogs, or a text file that can be used by any word processor.

Visual FoxPro Setup can install ODBC functionality through the Visual FoxPro OLE DB Provider. For information about merged documents, see Microsoft Word Help. For more information, see OLE DB Provider for Visual FoxPro.

To access the Mail Merge wizard

  1. From the Tools menu, choose Wizards, and click Mail Merge.

Step 1 – Select Fields

This step makes it possible for you to specify the fields that contain the information you want to use with the merged document, which can be a Word document or a file from another word processor. You can select fields from a single table or view only.

Step 2 - Choose Word Processor

In this step, you specify whether you will create a file for use with Word or a generic, comma-delimited file for use with another word processor.

You must have a current version of Word installed on your computer if you select Microsoft Word. If you select Comma-delimited text file, the wizard will skip Steps 3 and 4 and go straight to the Finish screen.

Step 3 - Select Document Type

This step makes it possible for you to either create a new document, such as a mailing list, or to add to an existing document, such as a roster.

Step 4 - Choose Document Style

In this step, you choose a type of document to create.

Form Letter

Makes it possible for you to create or to use a letter template into which the data from the specified Visual FoxPro file will be merged.
Label

Makes it possible for you to create or to use a label template into which the data from the specified Visual FoxPro file will be merged.
Envelope

Makes it possible for you to create or to use an envelope template into which the data from the specified Visual FoxPro file will be merged.
Catalog

Makes it possible for you to create or to use a file that contains labels, such as Item or Color or Catalog number, into which the data from the specified Visual FoxPro file will be merged.

Step 5 - Finish

This step makes it possible for you to save the data as a text file or to continue into Word to specify how the Visual FoxPro data is merged into the existing or new merged document.

If you have chosen to create a Word document, the wizard will open the document in Word. If you have chosen to create a text file, the wizard will prompt you to save your comma-delimited file.

See Also

Other Resources

Importing and Exporting Data
Wizards Overview
Local View Wizard
Mail Merge Object


One-To-Many Form Wizard

Visual FoxPro 9.0
One-To-Many Form Wizard
See Also

You can use this wizard to create a data entry form that updates several tables from a single form. For example, you can create one form might update customer and order tables. The size of the form is based on your Maximum design area setting on the Forms tab in the Options dialog box.

To access the One-To-Many Form wizard

  1. From the Tools menu, choose Wizards, and then click Form.

  2. In the Wizard Selection dialog box, choose One-To-Many Form Wizard.

Step 1 – Select Parent Table Fields

In this step, you choose a free table or table or view from a database that will provide the controlling fields data presented in your form. This specifies which field of the parent or controlling table determines the records selected in the child or controlled table.

To select the fields for your form

  1. Use the Databases and Tables controls to locate and select the table you want to use.

  2. In the Available fields window, select one or more fields you want to use from the selected table, and use the arrow buttons to move them to the Selected fields window.

You can select fields from a single table or view only.

Step 2 - Select Child Table Fields

In this step, you choose the fields from the related table. This determines which fields from a child or controlled table are displayed on the form. For example, the parent table might hold only customer names, ID numbers, and addresses, and the child table might hold orders information, such as ID numbers, amount, date, discount, and so on. One customer might have many orders.

As with the parent table fields, you can select fields from a single child table or view only.

Step 3 – Relate Tables

In this step, you specify from the fields list how the parent and child tables are related. In the example from step 2, both tables contain the customer ID field, so that is one way to relate them. There might be other ways depending on the available fields and what you want to report.

Step 4 - Choose Form Style

In this step, you choose the basic format of your form from the styles built into the wizard. When you click any of the styles listed in the Style box, the wizard displays a picture in the magnifying glass as an example of the style.

The button type options refer to your form's navigation buttons. The navigation buttons that the wizard creates on your form are as follows.

Text Buttons

Places navigation text on the buttons of your form.
Picture buttons

Places navigation icons on the buttons of your form.
No buttons

Places no buttons on your form, so you can prevent navigation beyond the displayed or entered data.
Note:
The Custom button type is unavailable in the One-to-Many Form wizard.

Button | Icon | Description
Top |  | Moves record pointer to first record.
Prev |  | Moves record pointer back one record.
Next |  | Moves record pointer forward one record.
Bottom |  | Moves record pointer to last record.
Find |  | Displays the Search dialog box.
Print |  | Prints a report.
Add |  | Adds a new record to the end of the table.
Edit |  | Allows user to change values in current record.
Delete |  | Deletes current record.
Exit |  | Closes form.
Note:
After the wizard saves a form, you can add additional fields to it using the same styles by selecting Quick Form on the Form menu.

All controls created by the Form wizard and the Form builder are in Wizards\Wizstyle.vcx. If you want to modify the styles, modify the classes in this file.

Step 5 – Sort Records

In this step, you select in the parent table the fields in the order that you want to sort the records. For example, if you are using two fields and have a first name field and a last name field, then you could choose to sort on first name+last name (such as PaulWilson) or on last name+first name (such as WilsonPaul). How you sort is determined by the order in which you selected those fields.

If your table already has one or more indexes, you can select the index tag, which is listed below the fields, separated by a line, in the Available fields window.

Step 6 - Finish

In this step you can choose how and when to use the form.

Save form for later use

Makes it possible for you to save the form as a file, which you can open later.
Save and run form

Saves the form as a file and then opens it in Visual FoxPro for immediate use.
Save form and modify in the Form Designer

Saves the form as a file and then opens it in the Form designer, so you can modify it.

If you select the Use field mappings check box, then you can use field mappings specified in the Options dialog box of the Tools menu. For more information, see Field Mapping Tab, Options Dialog Box. If you use tables from a database, you can select Override with DBC field display classes so that your form uses information from the database, otherwise this option is unavailable.

To preview the form before exiting the One-To-Many Form wizard, click the Preview button.

See Also

Other Resources

Create One-To-Many Relationships Dialog Box
Form Designer
Wizards Overview
Forms Tab, Options Dialog Box


One-To-Many Report Wizard

Visual FoxPro 9.0
One-To-Many Report Wizard
See Also

You can create a report that groups records from a parent table with records from a child table, for example, names and address from a Customer table and amounts and discounts from an Orders table, using the One-To-Many Report Wizard. For information about starting the One-To-Many Report Wizard, see How to: Create Reports and Working with Reports.

Step 1 - Select Parent Table Fields

In this step, you choose a free table or table or view from a database that will provide the controlling fields data presented in your report. This specifies which field of the parent or controlling table determines the records selected in the child or controlled table. You can select fields from a single table or view only.

Step 2 - Select Child Table Fields

In this step, you choose the fields from the related table. This step determines which fields from a child or controlled table are displayed on the form. For example, the parent table might hold only customer names, ID numbers, and addresses, and the child table might hold orders information, such as ID numbers, amount, date, discount, and so on. One customer might have many orders.

You can select fields from a single child table or view only.

Step 3 – Relate Tables

In this step, you specify from the fields list how the parent and child tables are related. In the example from step 2, both tables contain the customer ID field, so that is one way to relate them. There might be other ways depending on the available fields and what you want to report.

Step 4 – Sort Records

In this step, you can select in the parent table the fields in the order that you would like to sort the records. For example, if you are using two fields and have a first name field and a last name field, then you could choose to sort on first name+last name (such as PaulWilson) or on last name+first name (such as WilsonPaul). How you sort is determined by the order in which you selected those fields.

If your table already has one or more indexes, you can select the index tag, which is listed below the fields, separated by a line, in the Available fields window.

Step 5 - Choose Report Style

In this step, you can choose the basic format of your form from the styles built into the wizard. When you click any of the styles, the wizard updates the graphic in the magnifying glass as an example of the style.

The Summary options button makes it possible for you to specify whether your report will include one or more calculations, such as sum or average, on available fields.

You also can choose whether your report will display or print in portrait or landscape orientation.

Step 6 - Finish

In this step, you can choose how and when to use the report.

Save report for later use

Makes it possible for you to save the report as a file, which you can open later.
Save report and modify in the Report Designer

Saves the report as a file and then opens it in the Report designer, so you can make modifications to it.
Save and print repor t

Saves the report as a file and then immediately prints it.

If you select Use display settings stored in the database, then your report uses information from the database.

If the number of fields you selected cannot fit on a single line within the width of your report, the fields will wrap to the following line. If you do not want the fields to wrap, clear the Wrap fields that do not fit check box. Click the Preview button to view the report without exiting the wizard.

After you save the report, you can open and modify it like any other report in the Report designer.

See Also

Other Resources

Report Wizard
Wizards Overview
Working with Tables


PivotTable Wizard

Visual FoxPro 9.0
PivotTable Wizard
See Also

With the PivotTable wizard, you can create pivot tables, which are interactive worksheet tables used to summarize and analyze data from existing, and perhaps large, tables. You can choose either to save a pivot table directly in Microsoft Excel or to add one as an object on a form.

You must have Microsoft Excel with Microsoft Query installed on your computer to create a pivot table. For more information, see Microsoft Excel Help.

To access the PivotTable wizard

  1. From Tools menu, choose Wizards, and then click PivotTable.

Step 1 – Select Fields

In this step, you can choose a free table or a table within a database as the source for your pivot table. You can select only fields from a single table or view. For information, see Working with Tables and Working with Views.

To select the fields for your pivot table

  1. Use the Databases and Tables controls to locate and select the table you want to use.

  2. In the Available fields window, select three or four fields you want to use from the selected table, and use the arrow buttons to move them to the Selected fields window.

The wizard will not permit you to proceed to the next step until you have chosen at least three fields; one each for row values, column values, and data.

Step 2 - Define Layout

In this step, you can specify which field values will be calculated for the data. For example, if you have an Orders table that contains, among others, a field for city, a field for region, and a field for order amount, you could create a pivot table that would display in the data area, sums for all the cities, by region. At the bottom, the table will display totals for each column. At the far right the table will display totals for each row.

To define the pivot table layout

  1. From the Available fields list, drag a field to the Rows box. The pivot table will contain a row for each unique value in the field that you drag to the Rows box

  2. From the Available fields list, drag a field to the Columns box. The pivot table will contain a column for each unique value in the field that you drag to the Columns box

  3. From the Available fields list, drag a field to the Data box. Because this field will be summarized, generally it is best to drag a numeric field here.

You also can drag a field to the Page box. If you drag a field to the Page box, the pivot table will contain a drop-down list from which you can select the different pages. There will be one page for each unique value that exists in the field you drag to the Page box.

If you have a large table, you might want to first create a view that contains the desired fields, then create a pivot table from that view. For information, see How to: Create Views.

Step 3 - Finish

If you select Create a Microsoft Excel pivot table, the wizard will display your finished pivot table in Excel. The default calculation for the pivot table wizard is sums. If you create an Excel pivot table, then you can change the calculation easily to another supported by Excel, such as average or count.

If you select Create a new form containing an embedded pivot table, the wizard will create a new form containing the embedded pivot table and open it in the Form designer. Double-click the embedded object to modify it in the Form designer.

See Also

Other Resources

How to: Create Views
Form Designer
Wizards Overview


Query Wizard

Visual FoxPro 9.0
Query Wizard
See Also

With the Query wizard, you can select a group of records based on some rules you specify, For example, if you have tables that contain large amounts of information in one or more tables, you can use a carefully designed query to collect or display just a few records that satisfy some numeric or logical value.

To access the Query wizard

  1. From Tools menu, choose Wizards, and then click Query.

  2. In the Wizard Selection dialog box, select Query Wizard.

Step 1 – Select Fields

In this step, you can choose free tables or tables within a database as the source for your query. You can select fields from one or more tables or views.

To select the fields for your query

  1. Use the Databases and Tables controls to locate and select the tables or views you want to use.

  2. In the Available fields window, select one or more fields you want to use from the selected table, and use the arrow buttons to move them to the Selected fields window.

Repeat this process to add fields from other tables or views.

Step 2 – Relate Tables

This step displays only if you select fields from more than one table or view. You can specify which fields in each table or view contain the same information and can therefore govern the relationship between the tables or views, thereby determining the included records.

Select the desired fields from the two drop-down list boxes, and then choose Add. If you use multiple tables in your view, then you must relate the tables by indicating which fields contain matching data in each table.

Step 2a – Include Records

This step displays only if you select fields from more than one table or view. You can specify which records from the selected tables will be made available to the Query wizard.

If you are using more than one table, you can specify a join condition. For more information, see How to: Create a Multitable View. For example, if you specify only matching rows in Step 2a, you can further refine that choice in Step 3 by specifying a particular value for a field.

Only matching rows

Returns only records from both tables that match the comparison condition set between the two fields in the join condition. This is called an inner join.
All rows from this table

Returns all the rows from one of the listed tables or views. This makes it possible for you to create a left or right outer join.
All rows from both tables

Returns matching and non-matching records from both tables. This is called an outer join.

By default, only matching records are included.

Step 3 – Filter Records

This step appears immediately after Step 1 if you have chosen only one table or view as source for your query. You can specify a filter condition, so only certain of the records you have chosen to make available are used in the query.

To determine the filter condition

  1. Select a field from the Field drop-down list.

  2. Specify an operator, such as equals or contains, in the Operator drop-down box.

  3. Specify a value in the Value textbox.

    For example, if you wanted to filter on a specific city, such as Helena, you might choose city from the Field drop-down list, choose equals in the Operator drop-down list, and enter Helena in the Value textbox.

You can reduce the number of records by creating expressions that filter records from the selected tables or views. You can create two expressions and connect them with And, which returns only records meeting both specified criteria, or Or, which returns records meeting either criteria.

You can see the result by clicking the Preview button.

Step 4 - Sort Records

In this step, you can specify the sort order of your query records. For example, if your query will be used to assess orders by region, then you might sort by state or zip code.

Choose up to three fields or an index tag that already exists in the database to determine the order in which your view results will be sorted. Select Ascending to sort the view in ascending order or Descending to sort the view in descending order.

Step 4a – Limit Records

This step appears only if you have specified one or more sort fields in Step 4. You can further limit the number of records in the view, based on either a percent of the records returned or an actual number of records.

To see a percentage of the available records, choose the Percent of records radio button, and then specify the percentage in the Portion value edit box. See all records by selecting Number of records and then selecting All records. As shown in the following procedures, you can choose a portion of records from the beginning or the end of the available records.

To see the first 10 items

  1. Choose the Number of records radio button

  2. Enter 10 in the Portion value box.
To see the last 10 records.

  1. In Step 4, change the sort order to Descending.

Note:
This changes the sort order to last record = first read.

  1. In Step 4a, select the Number of records radio button.

  2. Enter 10 in the Portion value box.

Step 5 - Finish

In this step, you can choose how to save your query.

Save query

Makes it possible for you to save the query for later use.
Save query and run it

Makes it possible for you to save the query and run it immediately
Save query and modify it in Query Designer

Makes it possible for you to save the query and then use the Query designer to enhance or modify it.

See Also

Other Resources

How to: Define Query Results
How to: Create Persistent Relationships Between Tables
Local View Wizard
Remote View Wizard
Wizards Overview
Query and View Designers


Remote View Wizard

Visual FoxPro 9.0
Remote View Wizard
See Also

With this wizard, you can create views using remote data (ODBC). You must have an existing database to store your view in, as well as an existing data source or named connection stored in a database. If you do not have a database open, you are prompted to select an existing database or create one.

Before you run the Remote View wizard, you can set options for remote view and connection defaults on the Remote Data tab in the Options dialog box. You can create connections in the Connection designer.

To access the Remote View wizard

  1. From Tools menu, choose Wizards, and then click Query.

  2. In the Wizard Selection dialog box, choose Remote View Wizard.

Step 1 - Choose Data Source

In this step, you can specify, from a list of available ODBC data sources or a list of named connections, which one contains the target data. If the box is empty, you must define your data sources and connections in Microsoft Windows before you run the wizard. You can define your data sources using the Data Sources control panel of the Administrative Tools control panel. If your remote data source requires a password, you will be prompted for it when you click Next.

You also can include System tables for ODBC drivers that support them.

After you select an ODBC data source, you might see the Configure Connection dialog box in which you specify whether to use a database or free table, and the location of the target table.

Step 2 – Select Fields

In this step, you specify which fields you want to use in your remote view.

To select the fields for your view

  1. Use the Tables controls to locate and select the table you want to use.

  2. In the Available fields box, select one or more fields you want to use from the selected table, and use the arrow buttons to move them to the Selected fields box.

    You can use fields from other tables by repeating this process. You can select as many fields as you need and move them into the Selected fields box.

Step 3 – Relate Tables

This step displays only if you select fields from more than one table. You can specify which fields in each table contain the same information and can govern the relationship between the tables, thereby determining the included records.

Select the desired fields from the two drop-down list boxes, and then choose Add. If you use multiple tables in your view, then you must relate the tables by indicating which fields contain matching data in each table.

If a relationship does not exist currently and the wizard could not suggest fields for a join, you must choose the fields. Typically, tables include fields for this purpose and often have the same name.

Step 4 - Include Records

This step displays only if you select fields from more than one table. You can specify which records from the selected tables will be made available to the Remote View wizard.

Only matching rows

Returns only records from both tables that match the comparison condition set between the two fields in the join condition. This is called an inner join.
All rows from this table

Returns all the rows from the selected table. This makes it possible for you to create a left or right outer join. For more information, see How to: Create a Multitable View.

Step 5 – Sort Records

This step makes it possible for you to specify one or more fields by which to sort the records in your remote view.

Select up to three fields or indexes to determine the order in which your view results will be sorted. If your table already has one or more indexes, you can select the index tag, which is listed below the fields, separated by a line, in the Available fields window. Select Ascending to sort the view in ascending order, or Descending to sort the view in descending order.

Step 6 - Filter Records

In this step, you can specify a filter condition, so only certain of the records you have chosen to make available are used in the remote view.

To determine the filter condition

  1. Select a field from the Field drop-down list.

  2. Specify an operator, such as equals or contains, in the Operator drop-down box.

  3. Specify a value in the Value textbox.

    For example, if you wanted to filter on a specific city, such as Helena, you might choose city from the Field drop-down list, choose equals in the Operator drop-down list, and enter Helena in the Value textbox.

You can reduce the number of records by creating expressions that filter records from the selected tables or views. You can create two expressions and connect them with And, which returns only records meeting both specified criteria, or Or, which returns records meeting either criteria.

You can see the result by clicking the Preview button.

Step 7 -Finish

In this step, you can choose how to handle the newly defined remote view.

Save remote view

Saves the newly defined remote view and exits the wizard.
Save remote view and browse

Saves the new remote view and then opens it in a Browse window, so you can review the displayed data.
Save remote view and modify it in the View Designer

Saves the new remote view and then modify it when it opens in the View designer.

See Also

Other Resources

Execution of ODBC Extensions to SQL
ODBC Registry
Cross-Tab Wizard
Graph Wizard
Local View Wizard
Query Wizard
Wizards Overview
Remote Data Tab, Options Dialog Box
Connection Designer
Query and View Designers


Report Wizard

Visual FoxPro 9.0
Report Wizard
See Also

With the Report Wizard, you can create reports using one free table or one table or view in a database. You can create reports quickly that you can run at any time and save them for future use. When you run the saved report, it displays or prints the then-current information from a table or view.

For information about starting the Report Wizard, see How to: Create Reports.

Step 1 – Select Fields

In this step, you can choose a free table or a table within a database as the source for your report. You can select fields from only a single table or view. To select fields, browse to and select the table or database you want to use by clicking the ellipsis (...) button. In the Available fields list, select one or more fields in the table and add them to the Selected fields list.

Step 2 – Group Records

In this step, you can use data grouping to categorize and sort your records, so they are easier to read. When you select a field in one of the Group by drop-down boxes, you can choose Grouping Options and Summary Options to refine your grouping selection. You can choose up to three fields for grouping.

Choosing Grouping Options opens the Grouping Intervals dialog box that makes it possible for you to select levels of filtering that are relevant to the type of data contained in the fields you selected for grouping.

Choosing Summary Options opens the Summary Options dialog box that makes it possible for you to specify from the following list the type of calculation to perform on specific numeric fields:

Summary Option | Return
Sum | Total of values in the specified numeric field.
Avg | Average of the values in the specified numeric field.
Count | A count of the number of records containing a non-nil value in the specified field.
Min | The minimum value in the specified numeric field.
Max | The maximum value in the specified numeric field.

You also can choose Detail and Summary, which provides group subtotals and totals, Summary only, which provides only totals, or No Totals for the report. Use the Calculate percent of total for sums to track the percentage of the total represented by each subtotal.

Fields that you select as groupings here are not available in Step 3 - Sort Records.

Step 3 - Choose Report Style

In this step, you can choose the basic format of your report from the styles built into the wizard. When you click any of the styles, the wizard updates the graphic in the magnifying glass as an example of the style.

Step 4 - Define Report Layout

In this step, you specify the number of rows or columns of the report and whether the report is to be portrait or landscape oriented.

When you specify a number of columns or select a layout option, the wizard updates the graphic in the magnifying glass as an example of the selection.

Note:
If you specified a grouping option in Step 2, the Columns and Field Layout selections in this step are not available.

Step 5 - Sort Records

This step makes it possible for you to specify one or more fields by which to sort the records in your report.

Choose up to three fields or an index tag that already exists in the database to determine the order in which your view results will be sorted. Select Ascending to sort the view in ascending order or Descending to sort the view in descending order.

Step 6 -Finish

In this step, you can choose how and when to use the report.

Save report for later use

Makes it possible for you to save the report as a file, which you can open later.
Save report and modify in the Report Designer

Saves the report as a file and then opens it in the Report designer, so you can make modifications to it.
Save and print report

Saves the report as a file and then immediately prints it.

If the number of fields you selected cannot fit on a single line within the width of your report, the fields will wrap to the following line. If you do not want the fields to wrap, clear the Wrap fields that do not fit check box. If you have used a table or view from a database, you can choose Use display settings stored in the database, otherwise this option is not available. Click the Preview button to view the report without exiting the wizard.

After you save the report, you can open and modify it like any other report in the Report designer.

See Also

Other Resources

One-To-Many Report Wizard
Wizards Overview
Working with Tables
CREATE REPORT Command
Report Designer


SQL Server Upsizing Wizard

Visual FoxPro 9.0
SQL Server Upsizing Wizard
See Also

The SQL Server Upsizing wizard creates a SQL Server database that duplicates, as much as possible, the functionality of Visual FoxPro database.

Note:
For SQL Server versions 6.5 and higher, the wizard sets the compatibility level to 6.5. You may need to reset this level and make additional changes after upsizing.

You can create a local working model of your application using Visual FoxPro tables, views, and databases to represent data that eventually will be accessed on a remote server. When you are ready to move this prototype to its working location, you will upsize it. You can use the SQL Server Upsizing wizard to:

  • Move local data to a remote server.

  • Transform local base tables and local views into remote base tables and remote views.

  • Migrate a local application to a client/server application.

Note:
Upsizing can take a long time, depending on the size of your data, the amount of network traffic, and the number of concurrent demands being handled by your server. Large tables may require several hours to upsize.

Before you run the SQL Server Upsizing wizard, you must prepare both the client and server sides. You must have certain CREATE and SELECT permissions on the server and named connections on the client. For more information, see SQL Server Upsizing Wizard Preparation.

To access the SQL Server Upsizing wizard from the Tools menu, choose Wizards, and then click Upsizing.

Step 1 - Select Local Database

In the first step, you choose which local database you want to upsize.

Database to upsize

Lists the currently open databases. Select the database you want to upsize. If you do not have a database open, choose the Open button to select and open a database.

Step 2 - Select Data Source

In this step, you specify options to select the ODBC SQL Server data source or named connection you want to use.

ODBC data sources

Choose this option button to display SQL Server ODBC data sources. When selected, the adjoining list is titled Available data sources.
Connections

Choose this option button to display connections stored in the open database that connect to SQL Server data sources. When selected, the adjoining list is titled Existing connections.
Available data sources

Lists the ODBC data sources that connect to the SQL Server. This list is displayed when the ODBC data sources option button is selected.
Existing connections

This list is displayed when the Connections option button is selected. It lists the connections stored in the open database that connect to SQL Server data sources.
All

Use this check box to display all data sources that are not identified explicitly with the "SQL Server" keywords in the title. The words "SQL Server" must appear in the data source name for Visual FoxPro to identify the data source as a SQL Server data source. If your data source uses a third-party driver to connect to SQL Server, it might not be identified as a SQL Server data source. The list displayed depends upon whether you have the ODBC data sources or the Connections option button selected.

When you click Next, the wizard connects you to SQL Server and displays the SQL Server Login dialog box. If you used a named connection with a saved password, the wizard logs you on to the SQL Server you've selected without prompting you for ODBC login information.

Using a Named Connection

If you use a named connection to access your data source, the SQL Server Upsizing wizard associates the named connection with any remote views it creates during upsizing. If the connection definition includes a password, the Save Password With View option (later in Step 8) is selected automatically for you and disabled; this prevents the password from being removed from the connection definition.

Using a Data Source

If you use a data source name rather than a connection name to log on to the data source, and you choose to have the wizard create remote views, the SQL Server Upsizing wizard creates a named connection called "Upsize" (or "Upsize2," "Upsize3," and so on, if a connection definition exists with the suggested name).

Step 3 – Choose Tables

In this step, you can select the Visual FoxPro tables you want to export to SQL Server.

Available tables

Lists all the tables stored in the database you have chosen to upsize.
Selected tables

Lists the tables you've chosen to upsize into the database on the server. You must select at least one table, and you can choose the >> button to export all tables.

When you choose Next, the SQL Server Upsizing wizard reads the list of tables you've selected to upsize and tries to open those tables for exclusive use in the database you choose to upsize. Any tables that can't be opened exclusively won't be available to upsize. The tables are opened exclusively to prevent other users from changing the data in the tables during the upsizing process, which helps to ensure the accuracy of exported data. If any tables are already open and shared, the wizard closes them and then reopens them exclusively; this might cause you to lose any temporary relations established with the SET RELATION or SET SKIP commands.

Choosing Tables to Export

It's very important to choose the tables you export carefully, as this choice has a significant impact on the performance of your application. Exporting all tables might result in excessive (and slow) server queries. A well-designed client/server database usually consists of a mix of local and remote tables.

In general, keep tables, which change rarely or infrequently, in your local database, such as a table of state names and abbreviations. Export tables that change frequently and are accessed by many users, such as a table of orders.

The SQL Server Upsizing wizard exports the table's field names, data types, and data. For more information, see Planning Client/Server Applications and Optimizing Client/Server Performance .

Step 4 - Map Field Data Types

In this step, Visual FoxPro displays the default data type mappings used to convert local data to remote data, as tables are upsized to the server. You can choose to change these default mappings.

You cannot change the default mapping for a key field to a data type that prevents the field from being indexed. You can change the default mapping of a field that is part of an index key if you choose a data type that is indexable; however, you might want to change the data types for the other fields in the key to match. Visual FoxPro warns you if you change the default data type mapping for a field that is not a key field but is used in a Visual FoxPro index. If you make a mistake, click Default to reset the data types.

Table

Select the table whose fields you want to map from the list of all the tables you've chosen to upsize.
Timestamp column

Select this check box to add a timestamp column to the server version of the table. If you want to apply this to all tables, you can save time by selecting the All Tables check box.
Identity column

Select this check box to add an identity column to the server version of the table. If you want to apply this to all tables, you can save time by checking the All Tables check box.
Default

Choose this button to reset all table field settings for all fields in the selected table back to their defaults. This button in effect undoes any changes you have entered for a specific table earlier in Step 4.
Field Name

Lists the fields contained in the table you selected in the Table list box.
FoxPro Type

Lists the Visual FoxPro data type for the field.
Server Type

Lists the server data type to which Visual FoxPro data in this field will be mapped when the table is copied to the server. Click this field to display a drop-down list from which you can select a different server data type.
Width

Specifies the width of the field.
Precision

Specifies the decimal precision of the field, when applicable.

Creating Timestamp Columns

A SQL Server timestamp column contains a unique value, generated by SQL Server that is updated whenever the server record is updated. Using a timestamp field on an updatable remote table can increase performance and reliability.

If you update fields using the Visual FoxPro SQL WhereType values DB_KEYANDMODIFIED or DB_KEYANDUPDATABLE, Visual FoxPro must check all modified or all updatable fields to determine whether they were changed by another user. Because text or image fields can be many megabytes in size, comparing these fields for changes can be network-intensive and time-consuming, thereby reducing performance. Reliability also can be affected, because converting the value of a floating-point field between client and server might cause the value to appear to have changed when it has not.

When you add a timestamp field to a remote table and update using the SQL WhereType value DB_KEYANDTIMESTAMP, Visual FoxPro uses only the value in the timestamp field to determine whether a record has been changed before updating it. Because Visual FoxPro can compare the value in the timestamp field more quickly than it can evaluate the contexts of large text or image fields, you can increase performance on remote data. However, if you use the SQL WhereType value DB_KEYANDTIMESTAMP, any change in the remote record is recognized as an update conflict, whether or not the changed remote field is in the list of fields you've set as modifiable in your remote view.

If you prefer to update fields using the Visual FoxPro SQL WhereType values DB_KEYANDMODIFIED, you might improve performance by setting the remote view's Compare Memo property to false (.F.). When CompareMemo is set to false, Memo fields are removed from the list of remote view fields compared against the data in the remote server row.

Step 5 - Select Target Database

In this step, you can select the database on the data source server to which you want to copy tables.

After you have connected to a server and have chosen a data source, the tables you want to upsize, and the field data type mapping, you can use an existing database or create a new database as the destination for your upsized local database. If you chose a named connection earlier in Step 2, you can use the database named in the connection or create a new database as the destination.

Available databases on ' database name '

This list is displayed when you select the Existing option button to add Visual FoxPro tables to an existing SQL Server database. Select the database into which you want to copy Visual FoxPro tables when you upsize.
New database name

This text box is displayed when the New option button is selected. Enter a name for the new database you want to create on the remote server to which you are upsizing. The name can be up to 30 characters in length and can include letters, digits, and the symbols #, $, and _. Spaces are not allowed.

If you upsize to an existing database, the wizard jumps to Step 8.

If you use a version of Microsoft SQL Server later than 6.x, the wizard jumps to Step 8 whether you use an existing database or create a new one.

Step 6 - Set Database Properties

If you chose to create a new SQL Server database earlier in Step 5, then the wizard displays this step to help you to select the database device and size for your database. You can choose to create your new SQL Server database on an existing device, or create a new device.

Selecting an Existing Device

Database device

Displays all the devices on the SQL Server you logged on to, including default devices. Select a device with sufficient free space for your database.
Size

Displays the size in megabytes of the database device selected in the adjoining Database Device list box.
Free Space

Displays the amount of free space remaining on the database device selected in the Database Device list box.
Database size

Enter the amount of space, in megabytes, you want to allocate for the new database. The size of a new database must be at least two megabytes, because that is the minimum allowed by SQL Server.

Default Devices

If one or more devices have been set as default devices on your SQL Server, the SQL Server Upsizing wizard includes a Default entry in the list of available devices. The Default entry can represent more than one device. Choosing the default device does not ensure you'll have enough room to upsize your database. The SQL Server Upsizing wizard checks the devices specified as default to make sure there's enough room for the database.

Tip:
To place your database on multiple devices, make those devices (and no others) default devices. When you run the SQL Server Upsizing wizard, select Default for your database.

For more information on setting the default status of devices, see your SQL Server documentation for a description of the sp_diskdefault system procedure.

Creating a New Device

If existing devices are too full, you might want to create a new device. You must be a system administrator to create new SQL Server devices.

To create a new SQL Server device

  1. Select Create new device from the list of devices.

    If you are a system administrator, a dialog box appears. Otherwise, an error message appears.

  2. Type a name for the new device.

    The device name must be 30 characters or less and consist of letters, digits, and the symbols #, $, or _. Spaces are not allowed.

  3. Click OK.

    The new device name is added to the devices list box.

  4. Type a device size.

    The device size must be at least two megabytes. The combined size of new devices cannot exceed available disk space.

If you are a system administrator, the SQLServerUpsizing wizard displays the amount of space on the server drive storing the Master SQL Server database.

Note:
The size of a device cannot be changed after it has been set. Make sure you create sufficiently large devices.

The selected new device is created after you choose the Finish button. The SQL Server Upsizing wizard creates the new device in the same directory as the Master database device. If you add a new device to the list but don't select the new device as the database device, then the new device is not created.

The SQL Server Upsizing wizard can generate a report that includes the logical name, physical name, and other information about new devices you create.

Device Number Limitations

Every SQL Server device is given a number when it is created. However, the available pool of device numbers is limited. The default value is 10, although the number might be different on your server. The SQL Server Upsizing wizard searches for an available device number. If all device numbers are taken, you won't be able to create a new device.

Note:
To increase the number of SQL Server device numbers available, see your SQL Server documentation for a description of the sp_configure system procedure.

Step 7 - Specify Log Properties

In this step, you can specify the size and device to store a transaction log. A transaction log is created for your database by SQL Server, and can be used to reconstruct the database in the event of a serious system problem.

Log Device

Displays a list of log devices on the remote server. Select the device you want to use for the transaction log. Ideally, a database and its corresponding log should be placed on devices that are on separate physical disks. These devices must be created before you start the SQL Server Upsizing wizard, as the wizard creates all new devices on the same physical disk — the disk where the master database device resides. If you have only one physical disk, you should place the database and its log on separate devices, so that you can use the SQL server DUMP TRANSACTION command.
Size

Displays the size in megabytes of the database device selected in the adjoining Log Device list box.
Free Space

Displays the amount of free space remaining on the log device selected in the Log Device list box.
Log Size

Enter the amount of space, in megabytes, you want to allocate for the transaction log. For more information on how to determine the log size you need, see Specifying Log Size later in this topic.
Database Size

Displays the amount of space allocated for the new database in Step 6.

Specifying Log Size

As a general guideline, you allocate 10 to 20 percent of the size of the new SQL Server database; this guideline is dependent upon a number of considerations that are discussed in your SQL Server documentation.

You can enter a value of 0 for the log size, which causes the wizard to place the log (a table called syslogs) on the same device as the database. When the log size is set to 0, the log consumes the minimum amount of space on the server but also fills up very quickly.

When you upsize to a new database, the SQL Server Upsizing wizard dumps the transaction log every time it fills up. The dump makes a backup copy of a database and its transaction log in a form that can be read in with LOAD DATABASE. For more information on the SQL Server DUMP TRANSACTION command and on estimating the amount of space to allocate for a transaction log, see your SQL Server documentation.

Note:
You can increase the size of a log or move it to a new device. For more information, see your SQL Server documentation for a description of the ALTER DATABASE command and the sp_logdevice system procedure.

Step 8 - Set Upsizing Options

In this step, you can control how the SQL Server Upsizing wizard exports your tables. You also can specify the changes you want the SQL Server Upsizing wizard to make to the local database. You can create upsizing reports, redirect views to use remote data, create new remote views on tables that are upsized, and save passwords with views.

Specifying Table Attributes to Upsize

By default, the SQL Server Upsizing wizard exports a table's structure and its data. Along with field names and data types, you can also export:

  • Indexes

  • Defaults

  • Relationships (referential integrity constraints)

  • Validation rules

The SQL Server Upsizing wizard can export additional table properties and create timestamp columns on certain SQL Server tables. The SQL Server Upsizing wizard also can modify your Visual FoxPro database so your queries, forms, and reports use the data in your new SQL Server tables, rather than the data in the local Visual FoxPro database.

Visual FoxPro indexes and defaults become SQL Server indexes and defaults. If you choose to export validation rules, the SQLServer Upsizing wizard attempts to export field- and row-level validation rules to SQL Server, where they become stored procedures called from SQL Server triggers. Exported table relationships also become part of the triggers.

Tip:
If you export table relationships, be sure to export indexes as well or you might experience mediocre performance.

Table Attributes to Upsize

Indexes

Select to upsize Visual FoxPro .cdx indexes.
Defaults

Select to upsize default values for table fields.
Relationships

Select to upsize relationships stored in the database you are upsizing.
Validation rules

Select to upsize field and table validation rules.
Structure only, no data

Select to upsize the empty table structure, without copying table data to the SQL Server data source.
Use declarative referential integrity

Enabled when upsizing to a SQL Server version 6.x database. Select to create SQL constraints to enforce referential integrity.
Null Mapping

Select the fields that can accept .NULL. This option helps to ensure that insert and update commands against remote data succeed. This option allows you to override the existing null setting fields in the Visual FoxPro tables being upsized. If you choose the General and Memo fields option, then all general and memo fields in your selected Visual FoxPro tables will be upsized with these fields set to allow nulls. There are differences in how Visual FoxPro SQL commands such as INSERT and UPDATE affect local and remote data depending on the null settings for fields. For example, if you have an INSERT command that does not include all the fields in a table, Visual FoxPro inserts blanks into the unspecified fields for local data. If the INSERT command is issued for a remote view (SQL Server data), then nulls are inserted into the fields not specified in the command. The command will fail if any one of these fields does not support nulls. It's fairly easy to write an INSERT command, which includes all the fields and values to be inserted. Note, however, that inserting content into a general field is a little more cumbersome.

Changes to Make Locally

Create upsizing report

Creates a series of reports documenting the results of the upsizing process.
Redirect views to remote data

Changes the definition of local views in the database you are upsizing to remote views that use the upsized server tables as base tables. Your queries, forms, and reports then use views on the data in the new SQL Server data source rather than the original Visual FoxPro data.
Create remote views on tables

When you upsize a local table, you need a remote view to access the upsized table on the remote server. The SQL Server Upsizing wizard can create new, remote views as you upsize. As the wizard creates new remote views, it renames all local versions of tables by adding the suffix "_local" to the table name.
Note:
Creating remote views on tables as you upsize is not recommended, because these unoptimized views select all the data in the table rather than selecting only the information your application needs. The preferred method is to create parameterized views. You can either create a local parameterized view, which you then upsize by choosing Redirect views to remote data, or create a new parameterized remote view on the table after you've completed the upsizing process. For more information, see How to: Create Parameterized Views.

Save password with views

By default, you must enter your password and login ID when opening a remote view in a new session with Visual FoxPro. Select this option to store your password locally with the remote view definition in your database.
Note:
This check box is checked automatically for you and disabled if you used a named connection earlier in Step 2 to access your data source and that named connection includes a password. This prevents the password from being removed from the connection definition.

Creating Upsizing Reports

When you select Create Upsizing Report, Visual FoxPro generates upsizing reports that document the tables, views, fields, indexes, and referential integrity constraints the SQL Server Upsizing wizard creates on SQL Server. The wizard places the reports in a new project, using the following report names:

  • RptErrors

  • RptField

  • RptIndex

  • RptRels

  • RptTable

  • RptViews

The upsizing reports include information about any devices and databases that are created, information about any errors encountered during the upsizing process, and a complete explanation of the way in which each Visual FoxPro object is mapped to a SQL Server object. You can view or print these reports after upsizing is complete.

Upsizing All Tables Used By a Local View

If you upsize all the tables used by a local view, the local view is renamed by adding the suffix "_local" to the existing local view name. The SQL Server Upsizing wizard creates a new view based on the SQL statement of the local view, substituting the remote table names for the local table names. The KeyField and other update properties of the view are preserved.

Upsizing Some of the Tables Used By a Local View

If you upsize only some of the tables used by a local view, the SQL Server Upsizing wizard does not rename the local views. Instead, it renames the Visual FoxPro tables you export with the suffix "_local." For example, if you export a table named "Employees," the table is renamed "Employees_local" in your database. The wizard then creates a remote view for each of the tables you exported. Each view selects all fields and all records from the remote table.

Note:
Visual FoxPro handles local and remote data in different ways. The data access design of an application using local data may become very inefficient when applied as is to remote data.

Advanced Dialog Box

Make Primary Key a Clustered Index

By default, tables that have a primary key automatically get a clustered index created on SQL Server by the Upsizing wizard. This is because it is a SQL Server default if the [CLUSTERED | NONCLUSTERED] clause is not specified in the ALTER TABLE statement, which the wizard uses. Being that primary keys are often already in sequential order, a clustered index may not be needed. This option allows you to control whether a clustered index is created.
Drop Local Tables

If you choose to create remote views for your tables, the wizard will create a new set of remote views using the names of their corresponding tables (and rename the original tables). It is possible that you no longer need to use the local tables. This option allows you to drop the local tables from the database.
Default Remote View Name

If you choose to create remote views, you may want to control the naming of these tables. By default, the name used is that of the original table (and the original table is renamed). The following options allow you to control the naming of remote views.
  • Prefix Specifies a character string to prepend to each of the newly created remote view names.

  • Suffix Specifies a character string to add to the end each of the newly created remote view names.

  • None (Same as local table name.) Defaults to using table name, and renames original table.

Step 9 -Finish

In this step, you can choose to:

  • Upsize without generating SQL code.

  • Only generate SQL code for upsizing.

  • Upsize and generate SQL code.

Upsize

Select to begin creating databases and tables, as applicable, on the remote server.
Save generated SQL

Select to have the upsizing wizard generate the SQL script necessary to upsize your database and then stop without beginning to create databases and tables on your remote server. You can use this option to provide a SQL upsizing script that you then customize to meet the needs of your application. Once you've modified and saved the SQL script, you then run the script to complete the upsizing process. This two-step process provides tremendous flexibility, allowing you to use Visual FoxPro to generate the large majority of the code you'll need, yet providing a method for fine-tuning the upsized installation.
Upsize and save generate SQL

Select to upsize your database and save the SQL script generated by the wizard.

The first and third upsizing options are available only if you have CREATE TABLE permission on the server. If you choose either of the options that save generated SQL code, all the SQL code generated by the SQL Server Upsizing wizard is stored on your hard disk.

Note:
Upsizing can take a long time, depending on the size of your data, the amount of network traffic, and the number of concurrent demands being handled by your server. Large tables can require several hours to export.

To upsize your database, select the upsizing option you want and choose Finish.

The SQL Server Upsizing wizard creates devices and databases if necessary, and begins exporting Visual FoxPro objects to SQL Server.

See Also

Other Resources

How to: Resolve SQL Server Upsizing Wizard Errors
Wizards Overview
Upsizing Visual FoxPro Databases
How the SQL Server Upsizing Wizard Works


How to: Resolve SQL Server Upsizing Wizard Errors

Visual FoxPro 9.0
How to: Resolve SQL Server Upsizing Wizard Errors
See Also

If any errors occur while the SQL Server Upsizing wizard is exporting data, you are asked whether you want to save error information. If you choose to save error information, an error report is generated.

Most upsizing errors occur because there isn't enough space on your server's database or log device, or because your remote database is not large enough to accept the data you're exporting to the server. Make sure that you select devices with ample free space and that you set your database size sufficiently high. Some errors occur because of inappropriate login permissions.

Database or Log Full

The SQL ServerUpsizing wizard runs out of space and stops if the SQL database you selected or created is too small. To resolve this problem, you can increase the space for the database or the log. This solution can involve dropping (removing) the database or the log from the upsizing process.

To increase the space for a new database or log

  1. Drop the database.

  2. If the SQL Server Upsizing wizard changed the names of any local tables, restore tables to their original names by:

    • Copying your backup version of your local database's .dbc file onto your system, overwriting the altered .dbc file.

      -or-

    • Renaming local tables to their original names.

  3. When you run the wizard again, specify a larger database or log size.

To increase the space for an existing database

  1. Increase the size of the database.

  2. If the SQL Server Upsizing wizard changed the names of any local tables, rename them to their original names.

    • Copying your backup version of your local database's .dbc file onto your system, overwriting the altered .dbc file.

      -or-

    • Renaming local tables to their original names.

  3. Run the wizard again.

To increase the space for an existing log

  1. Increase the size of the log.

    -or-

    Dump the transaction log.

  2. If the SQL Server Upsizing wizard changed the names of any local tables, rename them with their original names.

    • Copying your backup version of your local database's .dbc file onto your system, overwriting the altered .dbc file.

      -or-

    • Renaming local tables to their original names.

  3. Run the wizard again.

You should overwrite tables from the previous partial upsizing to make sure all table relationships are created.

For information on increasing the database or log size, see the ALTER DATABASE command in your SQL Server documentation. For information on dumping the transaction log, see the DUMP TRANSACTION command in your SQL Server documentation.

Device Full

The device on which a database or log is located can fill up. You can extend the database or log to another device using the ALTER DATABASE command or the SQL Server Administrator, or you can create a larger device.

To create a larger device

  1. Drop the device.

  2. Restart SQL Server.

  3. Create a larger device.

    Caution:
    Dropping a device deletes all databases and logs on the device, not just the database to which you are upsizing.

You can use the sp_dropdevice system procedure to drop a device. For more information, see your SQL Server documentation.

Improper Compatibility Level for Upsizing

To upsize a database, Visual FoxPro sets the compatibility level of the target SQL database to 6.5 by calling the SP_DBCMPTLEVEL stored procedure on SQL Server. Make sure the SQL login you are using has the appropriate rights to perform this action.

To make sure the SQL login has appropriate rights

  • Verify that the login you are using has the permissions as one of the following:

    • DBO

    • Member of the sysadmin fixed server role

    • DB_OWNER fixed database role

See Also

Other Resources

SQL Server Upsizing Wizard
Wizards Overview
Upsizing Visual FoxPro Databases
How the SQL Server Upsizing Wizard Works


Table Wizard

Visual FoxPro 9.0
Table Wizard
See Also

The Table Wizard creates tables based on typical table structures. It provides table templates, optional style settings, support for both Character and Memo binary data types, and access to databases and lets you select a table that fits your needs from the list of sample tables. You can customize the table's structure and fields as you step through the wizard, add your table to a database, and use database settings to determine the formats of fields you add to your table. You also can establish relationships between tables in the database.

If you have one or more databases open, the Table Wizard automatically adds the new table to the current database. If you add your table to a database, the Table Wizard provides automatic formatting of selected fields. If no databases are open, the wizard creates a free table. If you base your table on a database, you can use styles, field mappings, or a primary key, and establish or use relationships in the database tables.

You can start the Table Wizard from the File menu by clicking New, Table, then Wizard or from the Tools menu by pointing to Wizards and clicking Table.

Step 1 – Select Fields

In this step, you can choose one of the sample tables and select from the available fields to create your table.

To select fields for your table

  1. Use the Sample Tables list box to locate and select the table you want to use.

  2. In the Available fields list box, select one or more fields you want to use from the selected table, and use the arrow buttons to move them to the Selected fields box.

You can categorize your selection as Business or Personal, and you can select fields from more than one table. If you want to add one of your own tables to the Sample tables box, choose Add.

Step 1a - Select a Database

In this step you can choose to add your table to a database. Adding the table to a database gives you enhanced functionality, but your table can be completely functional without being part of a database. If you create your table in a database, the Table wizard will provide automatic and custom formatting options in the next step.

You can also specify a friendly or descriptive name for the new table.

Note:
If you create a stand-alone table, you won't be able to change field captions.

Step 2 - Modify Field Settings

In this step you can change any default field settings. For example, you can change the maximum width of a character field, or the number of decimal places allowed in a numeric field.

You can specify whether fields can contain null values and you can change the field caption or type.

If you are creating your table in a database, you can also select one of the predefined data input masks for each field type or create a custom input mask. The Format windows display the mask and format code you choose.

Step 3 - Index the Table

In this step you can specify a field that will be the primary index key for your table. You can also designate other fields as secondary index keys.

Step 4 - Set Up Relationships

In this step, if you are creating your table within a database, you can establish relationships between fields in your new table and existing tables in the database.

Highlight the field for which you want to establish a relationship, and then click the Relationships button.

To define a relationship

  1. Click the radio button that identifies the type of relationship you want to establish.

  2. Select the field that relates the tables within the database. If you select <newfield>, type in the field name.

  3. Click OK.

    The Relationships dialog box will close and return you to Step 3, where the list displays the new relationship.

Step 5 - Finish

In this step you can specify how your table is saved and used.

Save table for later use

Saves the table to disk for later use when you click Finish.
Save table and browse it

Saves the table to disk and opens it so you can immediately add records by choosing Append New Record from the Table menu after you click Finish.
Save table and modify it in the Table Designer

Saves the table to disk and then opens it in the Table Designer so you can immediately modify it after you click Finish.

See Also

Other Resources

Wizards Overview
Working with Tables
Working with Table Indexes


Web Publishing Wizard

Visual FoxPro 9.0
Web Publishing Wizard
See Also

This wizard uses data from a table or view to create an HTML document. You can use or share the file that the Web Publishing wizard creates in your browser or edit it in a text editor.

To access the Web Publishing wizard

  • From the Tools menu, choose Wizards, and click Web Publishing.

In the Web Publishing wizard, you can specify the layout for data as well as the layout and style of the head and body of the HTML page. You can use the default layouts and visual styles that come with the wizard or customize those layouts and styles. In addition, you can load an existing cascading style sheet (.css) file.

Step 1 – Select Fields

In this step, you can choose a free table or a table within a database as the source for your Web page. You can select fields from only a single table or view.

To select the fields for your Web page

  1. Use the Databases and Tables controls to locate and select the table you want to use.

  2. In the Available fields list box, select one or more fields you want to use from the selected table, and use the arrow buttons to move them to the Selected fields box.

Step 2 – Sort Records

This step makes it possible for you to specify one or more fields by which to sort the records in your Web page.

Choose up to three fields or an index tag that already exists in the database to determine the order in which your view results will be sorted. Select Ascending or Descending to determine the order of the sort.

Use Remove to eliminate a field from the sort list.

Step 3 – Choose Style

This step makes it possible for you to select a data layout and a visual style for your Web page.

You can modify the selected layout by using the Options button. You can override the default visual style settings and add your own HTML tags by using the Advanced button.

Options

Opens the Layout Options dialog box so that you can modify specific properties of the data layout you chose.
Advanced

Opens the Advanced dialog box so you can modify the appearance of your Web page by adding a cascading style sheet (.css), colors, text, and HTML tags.
Preview

Displays a sample of your Web page in the selected data layout and visual style. The preview is limited to 10 records per page.

Step 4 - Finish

In this step, you specify how to save and use your Web page.

Save Web page for later use

Saves the Web page to disk for later use.
Save Web page and modify it in a text editor

Saves the Web page to disk and opens it in your default text editor so you can modify it.
Save Web page and open it in a browser

Saves the Web page to disk and opens in your default Web browser.
Create script for generating Web page

Creates a program file that will dynamically create your Web page.

Save style

Use to specify and save the name of the style you apply to a Web page.

See Also

Other Resources

Wizards Overview


Advanced Dialog Box

Visual FoxPro 9.0
Advanced Dialog Box
See Also

This dialog box is part of the Web Publishing wizard and makes it possible for you to specify additional characteristics for your Web page. It is displayed from the Step 3, Advanced button. You can specify formatting and objects from cascading style sheets (.css) and add additional HTML items that can include headings, text, or other Web page items and characteristics.

To access the Advanced dialog box

  1. From Tools menu, choose Wizards, and then click Web Publishing.

  2. Navigate through the wizard until you reach Step 3.

  3. Click Advanced.
Cascading style sheet

This control makes it possible to specify or locate a cascading style sheet (.css) file to use for your Web page.
Body

Color This drop-down box makes it possible for you to specify a color from the list to use for the body background. This option overrides any color specified in the selected data layout or visual style. Image This textbox makes it possible for you to specify or locate an image file to display on your Web page.
Copy graphics to HTML output location

This check box makes it possible for you to specify that any graphic files used in your data layout or visual style are copied to the same location as your Web page file.
Save Settings

This button makes it possible for you to keep your visual style changes in a file to use later.
Load Settings

This button makes it possible for you to access a saved layout or to remove a saved layout you no longer want.
Additional HTML Items

This section makes it possible for you to add HTML tags for formatting, text, and references to your Web page.
Add

This button opens the HTML Item dialog box, so you can specify additional HTML items and formatting for your Web page. For more information, see HTML Item Dialog Box.
Edit

This button opens the HTML Item dialog box, so you can edit the selected HTML item for your Web page. For more information, see HTML Item Dialog Box.
Remove

This button makes it possible for you to delete the selected HTML item from your Web page.

See Also

Other Resources

Web Publishing Wizard
HTML Item Dialog Box
Layout Options Dialog Box
Wizards Overview


HTML Item Dialog Box

Visual FoxPro 9.0
HTML Item Dialog Box
See Also

The HTML Item dialog box is part of the Web Publishing wizard. This dialog box makes it possible for you to specify additional items and their attributes for the Web page you create.

To access the HTML Item dialog box

  1. From Tools menu, choose Wizards, and then click Web Publishing.

  2. Navigate through the wizard until you reach Step 3.

  3. Click Advanced.

  4. In the Advanced dialog box, click Add.
Type

This drop-down list provides a list of HTML tag items that you can add to your page.
Location

This drop-down list makes it possible for you to specify where on the Web page you want the selected HTML item to appear — in the header, before data, or after data.
Text Formatting

  • Text Specify the exact text you want to display in the location you selected in the Location drop-down list.

  • Heading Specify, from the drop-down list, the HTML heading tag you want to apply to the specified text.

  • Bold (Strong) Specify whether you want the specified text to be formatted bold.

  • Italic Specify whether you want the specified text to be formatted italic.

  • Font name Specify the font you want to use for the specified text. If you chose a Heading, then this option is disabled, and your Web page will use the heading value set in the viewing browser.

  • Size Specify the font size you want to use for the specified text. If you chose a Heading, then this option is disabled, and your Web page will use the heading value set in the viewing browser.

  • Alignment Specify the left-to-right page alignment of the specified HTML item.

  • Forecolor Specify the foreground (default text) color of the specified HTML item.

  • Backcolor Specify the color of the specified HTML item.

Attributes

  • File/HREF Specify or locate the file (or URL) you want to use if you chose Hyperlink or Image item in the Type drop-down list.

  • Style Class Specify a path reference to a class contained in a cascading style sheet (.css).

When you click OK, you are returned to the Advanced dialog box where you can specify another HTML item, save the current data layout and style information, or proceed to Step 4 of the Web Publishing wizard.

See Also

Other Resources

Web Publishing Wizard
Advanced Dialog Box
Layout Options Dialog Box
Wizards Overview


Layout Options Dialog Box

Visual FoxPro 9.0
Layout Options Dialog Box
See Also

The Layout Options dialog box is part of the Web Publishing wizard. This dialog box makes it possible for you to modify the default values of the selected data layout. You can save any changes you make as a new data layout and style specification by using the Save Settings button in the Advanced dialog box.

To access the Layout Options dialog box

  1. From Tools menu, choose Wizards, and then click Web Publishing.

  2. Navigate through the wizard until you reach Step 3.

  3. Click Options.
Border

This tab makes it possible for you to select the background and border colors and border width. You also can specify a .gif or .jpg file as a background image.
  • Border color Specify the border color.

  • Background color Specify the background color for graphics and text.

  • Background image Specify the name of a background .gif or .jpg image and, if necessary, its location.

  • Border width Specify the thickness of the border in points.

Font

This tab makes it possible for you to specify one or more HTML-defined fonts in case a user does not have a particular font. This can help provide good cross-platform browser behavior. You also can specify the font name and change the default font color.
  • Font names Specify the font name and, if necessary, its location.

  • Font size Specify the font size.

  • Forecolor Specify the color of the text.

Other

This tab makes it possible for you to specify the name of an HTML-defined class to use in your Web page. The Other tab also can provide access to properties settings that are specific to a particular layout choice.
  • Style class Specify the name and location of a .css file that contains a style class to use for your Web page.

  • First row color Specify from the drop-down list the color of the first rows of your Web page.

  • Next row color Specify from the drop-down list the color of rows following the number of offset rows on your Web page.

  • Row offset Specify the number of rows in each block of the displayed table. Each of the row colors you choose will be used in this number of alternating rows.

Reset Defaults

Use this button to restore your selections to the original wizard default values.

When you click OK, the dialog box closes and returns you to Step 3 of the Web Publishing wizard.

See Also

Other Resources

Web Publishing Wizard
Advanced Dialog Box
HTML Item Dialog Box
Wizards Overview


Windows (Visual FoxPro)

Visual FoxPro 9.0
Windows (Visual FoxPro)

Explains functions of and options that appear in various Visual FoxPro windows.

In This Section

Accessibility Browser Window

Makes it possible for you to explore various user interface elements of an application through their Iaccessible interface.
Automated Test Harness Window

Makes it possible to record and play back mouse and keyboard events in your applications.
Browse Window

Displays the records in the active table.
Call Stack Window

Makes it possible for you to display procedures, programs, and methods that are executing. While a program is running, it is listed in the Call Stack window.
Class Browser Window

Displays the classes in a class library or a form and the type library information in a .tlb, .olb, or .exe file.
Code References Window

Makes it possible to for you to select and replace code references or text after performing a search using the Look Up Reference dialog box.
Code Window

Use the Code window to write, display, and edit form, event, and method code.
Command Window

Displays Visual FoxPro language commands when you choose menu commands. The Command window is a Microsoft Visual FoxPro system window.
Component Gallery Window

Displays, as shortcut icons, components available to your Microsoft Visual FoxPro projects, applications, designers, wizards, and builders, which makes it possible for you to manage, in various ways, any file available to your system.
Coverage Profiler Window

Contains a group of Coverage Profiler Tool Buttons and options that make it possible for you to specify how you display the information returned by the Coverage Engine.
Data Session Window

Enables you to open and display tables or views, establish temporary relationships, and set work area properties.
Debug Output Window

Makes it possible to display output from active programs, procedures, or method code.
Debugger Window

Contains the Debugger menus, the Debugger toolbar, and several debugging windows.
Document View Window

Allows you to view and navigate to any procedure, function, or #DEFINE definition or preprocessor directive in your program.
Editing Window

Provides text and program file editing.
General Field Window

Makes it possible for you to create or insert OLE objects.
Go To Definition Window

Makes it possible for you to choose from multiple code definitions resulting from using View Definition to view definitions of code elements in your program.
Locals Window

Allows you to display all the variables, arrays, objects, and object members that are visible in a given program, procedure, or method.
Object Browser Window

Displays the classes, properties, methods, events, and constants available for COM object libraries.
Project Manager Window

Enables you to organize and manage your files in projects.
Properties Window

Contains the list of properties, events, and methods for a selected form, data environment, cursor, relation, or control.
Task List Manager Window

Describes important information about tasks through the use of visual cues, such as different colored text and icons.
Trace Window

Makes it possible to see your lines of code as they are being executed.
Visual FoxPro Intellisense Manager Window

Makes it possible for you to specify the appearance and behavior of the syntax statements and other tool tip information displayed in properties sheet, editor, and code windows.
Visual FoxPro System Windows

Provided by Visual FoxPro as part of the product interface.
Watch Window

Makes it possible for you to display expressions and their current values, and set breakpoints on an expression.

Related Sections

User Interface Reference

Explains the options that appear on various dialog boxes, windows, and other user interfaces. These types of topics generally appear when you press F1 in a dialog box or window.
Creating Applications with the Application Framework

Describes how the Application Framework is designed to include all required, and many optional, elements that make an application effective and pleasurable to use.
Builders

Describes tools that aid in setting properties of controls on a form. Unlike wizards, builders are reentrant, so you can reopen a builder on a particular control repeatedly.
Dialog Boxes

Explains the options that appear on various dialog boxes.
Developing Visual FoxPro Applications

Includes conceptual information about how to develop Visual FoxPro applications, instructions for creating databases and the user interface, and other tasks needed to create Visual FoxPro applications.
Programming in Visual FoxPro

Describes how understanding object-oriented programming techniques and the event-driven model can maximize your programming productivity and enable you to access the full power of Visual FoxPro.


Accessibility Browser Window

Visual FoxPro 9.0
Accessibility Browser Window
See Also

You can use the Accessibility Browser to help you explore various user interface elements of an application through their IAccessible interface and develop applications that are more accessible to people with disabilities. Source code for the browser is included so you can enhance the functionality of this tool.

For more information, see How to: Use the Accessibility Browser.

This VFP session

When clicked, the UI element list box is populated with the current instance of Visual FoxPro.
Separate VFP session

When clicked, the UI element list box is populated with a new instance of Visual FoxPro.
Refresh

Refreshes the UI element list box based on the Session options and Forms only check box settings.
Forms only

When selected, only Visual FoxPro forms (those from the _VFP.Forms collection) are displayed. Otherwise, all UI elements in the Visual FoxPro application are included.
+

Expands the UI element list box.
-

Collapses the UI element list box.
UI element list

Contains a hierarchical (based on parent containership) listing of all accessible user interface elements. The list is populated when the Refresh button is clicked. When you click an item in the list, IAccessible properties for that item are displayed in the Member detail section.

Member detail

This section lists IAccessible properties and their values for the item selected in the UI element list box. For more information about IAccessible properties and methods, visit the Microsoft Accessibility Web site at http://www.microsoft.com/enable/.

Go (accParent)

Selects parent of current item in UI elements list box.
Go (accChild)

Selects child of current item in UI elements list box. The child selected is one selected in the accChild drop-down list preceding the Go button.
Do It

Performs the default action of the selected item.
<- (accNavigate)

Navigates to prior UI element.
-> (accNavigate)

Navigates to next UI element.
Select

Selects the current UI element in the list box.
Focus

Puts focus on the current UI element in the list box.
Click

Clicks the current UI element in the list box.
Flash

Displays a yellow border around the actual user interface element selected in the UI elements list box.
Highlight

When selected, automatically shows a yellow border around the actual user interface element as you change item selected in the UI elements list box.

Platforms Supported

Windows 2000 and later includes all the core support for Accessibility. Earlier versions of Windows support Accessibility to various degrees.

Platform | Description of support
Windows 98 | Includes Active Accessibility version 1.1 in the initial release of Windows 98; however you can run msaardk.exe to upgrade to a later version of Active Accessibility. All language versions of Windows 98 are supported, and future Windows 98 Service Packs will contain updated, localized versions of Active Accessibility.
Windows 2000 | Includes the Active Accessibility core system files for all language versions of the operating system. Support for both Intel and Alpha processors is provided in Windows 2000.
Windows Me | Accessibility options are installed by default during Windows Me setup, making the Accessibility Wizard and accessibility utilities instantly available. The increased integration of Microsoft Active Accessibility in Windows Me helps make many accessibility aids run more smoothly and effectively with the operating system and other applications.

See Also

Other Resources

Windows
How to: Use the Accessibility Browser
Development Productivity Tools
Accessibility for People with Disabilities


Automated Test Harness Window

Visual FoxPro 9.0
Automated Test Harness Window
See Also

The Visual FoxPro Automated Test Harness Window makes it possible for you to record and play back Mouse and Keyboard events in your Visual FoxPro applications.

Scripts Tab

This tab makes it possible for you to view and work with existing scripts that were recorded earlier with the Test Harness. You can edit any script by highlighting it in the grid and then clicking the Edit the test script toolbar button or selecting the Edit Script menu item. One or more scripts can be played back at a time. Click checkboxes next to the scripts you want to play back and then click the Play the script toolbar button or select the Play menu item. The following options are available in this tab:
  • Scripts grid

    Displays all recorded scripts. Information for a script is displayed on a line including pre and postscripts that get executed before and after the main script. The main script uses the event log. Items checked in the first column are used when deleting or playing back scripts. The Edit script function only applies to the current row highlighted in the grid.

  • Delete button

    Deletes scripts selected (first column checked) in the grid.

Options Tab

This tab has optional settings you can select for both recording and playback. The following options are available in this tab:
  • Overwrite the existing script

    If checked, an existing script of the same name will automatically be overwritten without prompting for confirmation during recording.

  • Always launch new VFP Window

    If checked, recording will always start with a new instance of Visual FoxPro.

  • Validate startup window before playback

    If checked, the startup window is validated against the recorded window. If it doesn't match, it will prompt with an error. The test will fail if an unexpected window appears or an error occurs.

  • Check for presence of each object

    If checked, the object associated with every event will be verified before playback. For example, if the keypress event is recorded on a textbox, the presence of the same object name is verified before playing back the event. An error will be displayed if the object does not exist.

  • Check for program error

    This option is used to report an error in the testing application. If checked and there is an error during playback, the error will be logged in the test log. The test results can be viewed in the Test Log tab.

  • Run count

    Specifies the number of times each script selected in the Scripts tab is run during play back.

  • Delay between events

    Makes it possible for you to specify a specific delay (milliseconds) between events during playback.

  • On script failure

    Provides error handling options if a problem occurs during script playback. You can abort the entire script, skip only the event that failed or continue playing back the script after retrying the failed event.

Test Log

This tab has details on results from test runs (playbacks). The following options are available in this tab:
  • Test Log grid

    Displays useful information on recently played-back scripts. The memory usage is the difference in the memory before and after the test run.

  • Delete button

    Deletes the selected test log.

Coverage Log

You can set coverage logging by using the settings in the Coverage Log tab. During playback, it will turn on coverage logging and save the log in the file specified.
  • Turn on coverage logging during playback

    If checked, creates a coverage log during playback of a script.

  • Overwrite the log if file exists

    If checked, automatically overwrites the log if it already exists without confirmation.

  • View Log button

    Displays a coverage log for the test if one exists.

  • Coverage Profiler button

    Invokes the Coverage Profiler, which will load the coverage log if it exists; otherwise, it will prompt for a log.

See Also

Other Resources

Windows
How to: Use the Automated Test Harness
Testing and Debugging Applications
Debugging and Error-Handling Language
Accessibility Browser Window
Coverage Profiler Application


Browse Window

Visual FoxPro 9.0
Browse Window
See Also

Displays the records in the active table.

When you are browsing a table in the Browse window, you can view records in two different modes, Browse and Edit. You can switch modes by choosing Browse or Edit from the View menu.

Note:
When you open a table using Open from the File menu, you have to choose Browse <table> from the View menu in order to see the table.

To select fields, click a cell or press TAB, ENTER, or the arrow keys. Move a column to a new position by clicking on the field name, dragging the column where you want it, and releasing the mouse button.

To enter a null value in a field that accepts null values, press CTRL+0. As long as a field that contains a null value remains active, nothing is displayed in it. After you activate a different field, the one containing the null value will display the string defined by the SET NULLDISPLAY command (for example, ".NULL.")

If you choose Append from the View menu, the Browse window adds a new, blank record. When you fill in the new record, the Browse window automatically adds another new record.

Note:
In some cases, if you browse a table or cursor generated by a crosstab query, the field names start with a character and a dash, indicating the data type of the field. For example, a numeric field starts with N-.

See Also

Other Resources

How to: Configure Browse Windows or Grids
How to: View Records in Tables
Windows
BROWSE Command
SET BRSTATUS Command
SET REFRESH Command


Call Stack Window (Visual FoxPro)

Visual FoxPro 9.0
Call Stack Window (Visual FoxPro)
See Also

Makes it possible for you to display procedures, programs, and methods that are executing. While a program is running, it is listed in the Call Stack window. If you run a procedure or another program from within the first program, while the second program is running, both program names are displayed in the Call Stack window, and so on.

This window is activated when you choose Call Stack from the Window Menu, Debugger Window.

Output Pane

Displays currently executing procedures, programs, and methods.
Call Stack Indicator

Points to the currently running program, procedure, or method.

You can configure the Call Stack window in the Debug Tab, Options Dialog Box.

See Also

Other Resources

Windows
Debug Tab, Options Dialog Box
Debugger Window
Debugger Keyboard Shortcuts and Menus
Debug Output Window
Watch Window


Class Browser Window

Visual FoxPro 9.0
Class Browser Window
See Also

The Class Browser displays classes in class libraries or forms and type library information in a type library (.tlb), object library (.olb), or executable (.exe) file. You can use the Class Browser to view, use, and manage classes and their user-defined members. For more information, see Operating the Class Browser.

Note:
You can open the Class Browser shortcut menu by right-clicking the Class Browser window or by pressing ALT+F10.

In Visual FoxPro 9.0, you can also display class definitions in program (.prg.) files. Many of the Class Browser features that are available for class libraries are available for program files. You can double-click on a method or event to edit the method or event code, and you can double-click on a property to display its value. You can also double-click a program class to modify its structure. Classes in program files can be viewed in hierarchical or non- hierarchical views, and you can filter protected and hidden members.

Class icon

Displays an icon representing a selected class or class library. This icon appears next to the type box only when a class or class library is selected in the class list of the Class Browser. You can specify a different icon (.ico) or bitmap (.bmp) file for a class. For more information, see How to: Specify Design-Time Appearance for Classes.
Type box

Allows selection or entry of a class type or character string to filter the move. The drop-down list shows the base classes. The list also keeps a history of class types and filters you have selected or entered for the current instance of the Class Browser.

Class Browser buttons

Performs various Class Browser commands. The Class Browser shortcut menu provides additional functionality. For more information, see Class Browser Buttons.

Class List

Displays the classes and subclasses in an open class library (.vcx) file, a form (.scx), or program (.prg).
Note:
A chevron (<<) appearing next to a class indicates that the parent class is located in a file that is not displayed in the class list.

Member list

Displays members objects and any user-defined properties and methods of the class or form selected in the class list. You can filter this list by selecting one of the following options from the member list shortcut menu:
  • Protected filter If a protected icon (a key) is displayed beside the Protected filter shortcut menu item, protected members are displayed in the member list. Protected members are also indicated by an asterisk (*).

  • Hidden filter If a hidden icon (a lock) is displayed beside the Hidden filter shortcut menu item, hidden members are displayed in the member list. Hidden members are also indicated by a caret (^).

  • Empty filter If a check mark is displayed beside the Empty filter shortcut menu item, empty methods are displayed in the member list. Empty methods are indicated by a tilde (~).

Class description box

Displays a description for the selected class. This box is located at the bottom left of the Class Browser window. You can edit the description in this box.
Member description box

Displays information about the selected member of a class. This box is located at the bottom right of the Class Browser window.
Note:
For member objects, the box is read-only and displays class and base class information. For custom property or method members, the box displays a description you can edit. For instances of the class, the box displays a read-only description that includes the variable scope (public or hidden), member names, and property values.

See Also

Other Resources

Class Browser Methods
Class Browser Properties
Keyboard Shortcuts
Windows


Class Browser Buttons

Visual FoxPro 9.0
Class Browser Buttons
See Also

The following buttons are available in the Class Browser. For more information, see Class Browser Window and Operating the Class Browser.

Component Gallery

Switches between the Class Browser and the Component Gallery for managing foundation class items.
Open

Opens an existing class library (.vcx) file, creates new class library and type library files, or opens an existing form/form set (.scx) file.
View Additional File

Adds an existing class library (.vcx) file or a form or form set (.scx) file to the class list, or creates a new class library file. To list the most recently opened files in the Class Browser, right-click the View Additional File button.
View Class Code

Displays the class definition code in a program (.prg) file for the selected class. The class opens as read-only, and you cannot save any changes you make to the class. However, you can save the code to another file.
Find

Searches for specified text in class names, class descriptions, member names, and member descriptions.
New Class

Creates a subclass of the selected class or any existing class.
Rename

Changes the name of the selected class, property, or method.
Caution:
Renaming a class might invalidate forms or classes that are not currently displayed in Class Browser windows and that rely on the class. Changing the name of a property or method can cause code that references the property or method to fail.

Redefine

Changes the parent class of the selected class.
Clean Up Class Library

Runs the PACK command to remove records in the .vcx file marked for deletion. For more information, see PACK Command.

See Also

Other Resources

Using the Component Gallery


Code References Window

Visual FoxPro 9.0
Code References Window
See Also

Displays the results from a code reference search that meet the project/folder scope and file types specified in the Look Up Reference dialog box. For more information, see Look Up Reference Dialog Box.

The Code References window appears after you perform a search in the Look Up Reference dialog box or when you select Code References from the Tools menu when searching for a previously searched code reference in the same project or folder. The currently active project always takes precedence over Folder scope. If the Look Up Reference dialog box has been previously opened, you can also call the Code References window using the following code:

Copy Code
DO(_FOXREF)

You can set the Code References window to always appear in the foreground when other windows are active. In the Code References window, right-click in the area to the right of the toolbar and select Always On Top.

However, if you selected Always on Top for other Visual FoxPro windows, you will see no difference in behavior.

The following buttons are available in the Code References window. You can find some of these commands on shortcut menus available from different panes in the Code Reference window.

Open (folder icon)

Opens or brings forward the designer for the selected file. The Open command is available only when a file node is selected.
Arrow

Switches between project scope and folder scope.
Search

Displays the Look Up Reference dialog box for you to perform a new code reference search.
Refresh

Updates previous search results with current results.
Replace

Displays a Replace dialog box for you to specify a replacement expression for selected code references in the results pane. The following options are available in the Replace dialog box:
  • Replace with Specifies the replacement expression for the selected code reference or references.

  • Confirm replacements Opens a dialog box for you to confirm, decline, or cancel the replacement operation for each code reference.

  • Preserve case Performs replacement operations using the original casing of the code reference or text being replaced. Case preservation of text includes only uppercase, lowercase, and title (proper) case, in which the first letter of each word is capitalized. This option does not support mixed case such as in "FoxPro" because the lengths of the original and replacement values can differ.

  • Create backup of modified files Makes a backup copy of the selected files before performing a replacement operation. Backup copies are stored in the same locations as the original files. You can open the Options dialog box from the Code References window or Look Up Reference dialog box to control the naming of backup files.

Visual FoxPro creates an activity log containing the most recent results of individual code reference replacements. These activity logs are shown below the Replacement Logs node in the search pane. Each log contains the following items:
  • A line that shows the original and replacement value

  • Whether the replacement operation succeeded and whether a reference was skipped using the Confirm Replacements option

  • Details and code for you to make data structure changes if data files might be affected

    Note:
    Search and replace operations can include all Visual FoxPro files, including data files. As a result, performing replacement operations can change data structures.

    Note:
    When this possibility occurs, Visual FoxPro shows a dialog box prompting you to confirm or decline the replacement operation. If you confirm the replacement operation, Visual FoxPro performs only those replacements that do not affect data files and provides code in the search string node under the Replacement Logs node for you to manually perform the desired changes. If you decline replacement, no changes are made.

    Note:
    Additionally, the Code Reference tool does not support replacement of property or method names in a form (.scx) or visual class library (.vcx) because of possible changes to subclasses and outstanding references.

Print

Displays a Print dialog box for you to select a set of code reference search results for printing. The following options are available in the Print dialog box:
  • Search set Specifies all code reference search results or a set of results that you want to print.

  • All Specifies that all references in the selected set of code references should be printed.

  • Selected items only Specifies that only the selected items for a set of code references are printed.

  • Print Prints the specified set of code references.

  • Preview Opens a Print Preview dialog box and the Report Designer for you to preview the set of code references to be printed.

You can specify a different report if desired by modifying the following fields in the RefAddin.dbf file:
  • Type Specify Report.

  • Data Specify description of the report.

  • Filename Specify the name of the report, such as "report1.frx".

Export

Displays an Export dialog box for you to export all or a set of code reference search results to a variety of formats. The following options are available in the Export dialog box:
  • Type Specifies the target file type for your search results. To make XML Output Options available, select Extensible Markup Language (XML) in the Type drop-down list.

    When exporting your search results to HTML, Visual FoxPro generates the file using XML and XSLT. By default, Visual FoxPro searches for a FoxRef.xsl file in the Visual FoxPro home directory or HOME(0). If the file is not found, Visual FoxPro copies an internal .xsl file and places it in the Visual FoxPro User Application Data directory or HOME(7) unless you specify a different directory. You can supply an XSLT file for formatting the HTML file by renaming your XSLT file to FoxRef.xsl and replacing the original .xsl file with the new file.

  • To Specifies a file name for the exported file. To choose a location other than the current folder for the exported file, click the ellipsis (...) button.

  • Search set Specifies all code reference search results or a set of results that you want to export.

  • View after export Specifies that you view the generated results after the export operation finishes. This option becomes unavailable if you select Clipboard as the target file type.

  • XML Output Options Specifies the following additional options for exporting search results to XML output:

    Generate element-based XML Generates an XML file in which fields are stored as elements.

    Generate attribute-based XML Generates an XML file in which fields are stored as attributes.

    Include schema Adds XML Schema Definition (XSD) schema to XML output.

  • All Specifies that all references in the selected set of code references should be exported.

  • Selected items only Specifies that only the selected items for a set of code references are exported.

Options

Opens the Options dialog box to set additional options for your search. For more information, see Look Up Reference Dialog Box, Options Dialog Box.
Help

Opens the Visual FoxPro Help file.

Search Pane

The search pane, or upper-left window, contains a collapsible tree view of the results from a code reference search. The tree view displays an All Results node, each code reference, and the files that contain the reference. When you click a file name, the view in the results pane, or upper right window, is filtered to represent only the results from that particular file.

A Replacement Logs node appears in the search pane when logs containing the most recent results of individual code reference replacement operations are created.

The following commands are additionally available from a shortcut menu that appears when you right-click a navigation, code reference, or file node inside the search pane:

Copy

Copies all information in the results pane, including the file name, class, method or procedure, and line information, for the item selected to the clipboard so that you can paste the information elsewhere.
Expand All

Fully expands the search results tree.
Collapse All

Collapses the search results tree.
Sort by Most Recent First

Sorts the search results in the tree, placing the most recent results at the top of the tree.
Clear Result

Removes the selected result from the search pane. The Clear Result command is not available if the All Results node is selected. If a file is selected, only that file is removed from the search pane.
Clear All Results

Removes all search results from the search pane.
Refresh

Results Pane

The results pane, or upper-right window, displays results from a code reference search, including potential definitions, if they exist, which you can quickly jump to, and multiple references that might exist in a single line of code. If multiple references per line exist, the results pane displays an indicator (the number of references enclosed by a circle) on that line.

The results pane shows the following items:

  • Check boxes for you to select individual lines of code

  • # Number of code reference instances that occur in the result, if more than one

  • File Name File name and location of the code reference

  • Class.Method, Line Class, method, and line number

  • Code Line of code that contains the code reference

You can sort items in each column by clicking each of the column headers.

The following commands are additionally available from a shortcut menu that appears when you right-click a selected reference inside the results pane:

Copy

Copies all information for the selected line, including the file name, class, method or procedure, and line information, to the clipboard so that you can paste the information elsewhere.
Select All

Selects all the items in the results pane.
Clear Selections

Clears the check boxes in the results pane.
Sort by

Organizes the items in the following manner:
  • File Name Organizes items based on file name.

  • Class.Method Organizes items based on class name followed by method name.

  • Selected Groups items by whether they are selected.

  • File Type Organizes items based on file type (extension).

  • Location Organizes items by folder location.

Description Pane

The description pane, or bottom window, displays information about a code reference search such as the project or folder searched and the matches found. When a reference is selected, the description pane shows the location of the reference and the line of code in which the expression appears.

To hide or display the description pane

  1. In the Code References window, right-click in the area to the right of the toolbar.

  2. From the shortcut menu, select Display Descriptions.

See Also

Other Resources

Windows
Look Up Reference Dialog Box
Look Up Reference Dialog Box, Options Dialog Box
How to: View Code Definitions
HOME( ) Function


Code Window

Visual FoxPro 9.0
Code Window
See Also

Use the Code window to write, display, and edit form, event, and method code. You can open as many Code windows as you want, so you can easily view, copy, and paste the code from different forms.

The Code window appears when you double-click a form or form control in the Form Designer, double-click in the Data Environment Designer window, or double-click an event or method in the Properties Window. Doing this has the same effect as choosing the Code command on the View menu.

Any text added to a method or event in a Code window will cause that class to have Override behavior for the method or event. Therefore, code for the method or event in a parent class will not be executed by default (it must be explicitly executed). This includes non-executable comment lines that begin with "*".

Object

Lists the current form, form set, data environment, toolbar objects, cursor, relation, and all the controls on the current form.
Procedure

Lists all the events recognized by Microsoft Visual FoxPro for the form, form set, data environment, cursor, relation, or control displayed in the Object box. When you select an event or method from the Procedure box, the parameters passed to the event or method (if any) are displayed in the editing region of the Code window. Event names in boldface text contain code. Access and Assign methods created for a property are also displayed in the Procedure box.
Tip:
If you need help on syntax for functions, statements, properties, events, or methods while working in the Code window, type the keyword or the property, event, or method name, select it, and press F1 for online Help. You can also select an event or method in the Procedure box and press F1 for information about the selected event or method. Press PAGE DOWN to jump to the next event or method that has code in it.

See Also

Reference

* Command

Concepts

Overriding and Calling Parent Class Code

Other Resources

Windows
Access and Assign Methods
Form Designer
Properties Window
Data Environment Designer


Command Window (Visual FoxPro)

Visual FoxPro 9.0
Command Window (Visual FoxPro)
See Also

The Command window is a Visual FoxPro system window. When you choose menu commands, Visual FoxPro language commands are echoed in the Command window.

You can also type Visual FoxPro commands directly into the Command window. In the Command window, you can:

  • Delete text by pressing ESC if you haven't already pressed ENTER to execute the command.

  • Reissue a previous command by placing the cursor anywhere on the command line, and then pressing ENTER.

  • Re-issue a block of code by selecting it, and then pressing ENTER.

  • Split lengthy commands by typing a semicolon after a space in the command where you want it to break, and then pressing ENTER.

  • Move text within the Command window and to other editing windows. Select the desired text and drag it to the desired spot.

  • Copy text within the Command window and paste it into other editing windows without using Edit menu commands. Select the desired text, hold down CTRL, and then drag the text to the desired spot.

You can change font, line spacing and indentation by selecting the appropriate command from the Format Menu.

Right-click in the Command window to display a shortcut menu with these options:

  • Cut, Copy, Paste. Move or delete characters to and from the Command window.

  • Build Expression. Display the Expression Builder dialog box window, in which you can define an expression using commands, literals, fields, or other expressions. The expression you build is pasted into the Command window when you click OK.

  • Execute Selection. Execute the text selected in the Command window as a new command.

  • Clear. Remove the list of previously executed commands from the Command window.

  • Properties. Display the Edit Properties dialog box window in which you can change edit behavior, tab width, fonts, and syntax coloring options for the Command window.

Persistence of Contents

The contents of the Command window are saved to a file, _command.prg, automatically unless the noRecentDocHistory system policy is enabled or you are not using a FoxUser resource file. You can clear the window by selecting Clear from the Command Window shortcut menu. To enable its use by multiple instances of Visual FoxPro, the file is only read when starting Visual FoxPro, and written when exiting Visual FoxPro. The file is located in the same directory as the FoxUser resource file. You can determine or change the location of the resource file from the Options dialog box, File Locations tab, or via language using SET("RESOURCE") or SET RESOURCE respectively.

See Also

Other Resources

Windows
Edit Properties Dialog Box
Expression Builder Dialog Box
Editing Window
How to: Operate the Command Window
Visual FoxPro Configuration
File Locations Tab, Options Dialog Box,
SET RESOURCE Command


Component Gallery Window

Visual FoxPro 9.0
Component Gallery Window
See Also

The Component Gallery window displays, as shortcut icons, components available to your Visual FoxPro projects, applications, designers, wizards, and builders, enabling you to manage, in various ways, any file available to your system.

The Component Gallery window contains a Component Gallery Toolbar plus the following options:

Catalog (Left) Pane

Displays the Component Gallery hierarchy of catalogs and folders. Select a catalog or folder here to display the items of the container in the Object panel to the right.
Object (Right) Pane

Displays items contained in a catalog or folder. For information on using items in the Component Gallery, see Using the Component Gallery.
Description Box

Provides information on the selected item. The Visual FoxPro status bar reports Component Gallery process status.

See Also

Other Resources

Windows
Component Gallery Properties Dialog Boxes
Add Class to Project Dialog Box


Open Catalog Dialog Box

Visual FoxPro 9.0
Open Catalog Dialog Box
See Also

Enables you to select an existing catalog description or file name to open in the Component Gallery.

Open

Open the selected catalog or catalog description.
Browse

Opens the Windows system Open Dialog Box so you can locate a catalog to open.

See Also

Other Resources

Dialog Boxes
Using the Component Gallery
Open Dialog Box
Class Browser Window
Component Gallery Window
Component Gallery Options Dialog Box
Find Component Dialog Box


Component Gallery Options Dialog Box

Visual FoxPro 9.0
Component Gallery Options Dialog Box
See Also

Enables you to specify global settings for catalogs and views in the Component Gallery.

Tab Options

The options available in the Component Gallery Options dialog box are grouped on the following tabs.

Tab | To access these features
Standard Tab, Component Gallery Options Dialog Box | Enables you to specify global defaults. This tab is always available.
Catalogs Tab, Component Gallery Options Dialog Box | Enables you to add catalogs to the Component Gallery and to specify whether catalogs are global or default.
Dynamic Views Tab, Component Gallery Options Dialog Box | Enables you to add, edit, or remove views from your view list. This tab is always available.

See Also

Other Resources

Using the Component Gallery
Standard Tab, Component Gallery Options Dialog Box
Catalogs Tab, Component Gallery Options Dialog Box
Dynamic Views Tab, Component Gallery Options Dialog Box
Component Gallery Window


Standard Tab, Component Gallery Options Dialog Box

Visual FoxPro 9.0
Standard Tab, Component Gallery Options Dialog Box
See Also

Enables you to specify default behavior settings that are global for all catalogs and folders, or items. The following settings are available in this tab:

Global Defaults

Enable item renaming

Enables select-delay label editing within the Component Gallery panes. Renaming is always available from the shortcut menu.
FFC Builder Lock

Enables you to specify that a builder opens when you drop a class on a form.
Drag and drop to desktop

Enables gallery items to open as samples in the Visual FoxPro desktop window.
Advanced editing enabled

Enables the Type, Scripts, Views, and Comments advanced editing tabs of all Item Properties Dialog Box.

Catalog default behavior

Open file as new view

Changes default double-click behavior of gallery items from Modify to Run.
Add file to current view

Changes default double-click behavior of gallery items from Open to Add.

Item default behavior

Modify item file

Sets the default double-click behavior of gallery items to Modify.
Run item file

Sets the default double-click behavior of gallery items to Run.

See Also

Other Resources

Component Gallery Options Dialog Box
Component Gallery Window
Catalogs Tab, Component Gallery Options Dialog Box
Dynamic Views Tab, Component Gallery Options Dialog Box
Item Properties Dialog Box


Catalogs Tab, Component Gallery Options Dialog Box

Visual FoxPro 9.0
Catalogs Tab, Component Gallery Options Dialog Box
See Also

Displays the names of the views that are currently available in the Component Gallery. This is the list that displays in the View Type drop-down list.

Tab Options

Global

Sets a catalog to contain any type of folder. You can access global catalogs and their contents no matter what other catalogs are open.
Default

Enables a catalog to automatically open when the Component Gallery starts. All catalogs that are marked as default are available whenever you select the default view.
New

Displays the Open Catalog Dialog Box so you can add a catalog to the list.

See Also

Other Resources

Component Gallery Window
Dynamic Views Tab, Component Gallery Options Dialog Box
Standard Tab, Component Gallery Options Dialog Box
Component Gallery Options Dialog Box


Dynamic Views Tab, Component Gallery Options Dialog Box

Visual FoxPro 9.0
Dynamic Views Tab, Component Gallery Options Dialog Box
See Also

Displays the names of the Dynamic Views currently available in the Component Gallery. You can specify dynamic views in the Component Gallery Options dialog box.

Tab Options

New

Enables you to create a new Dynamic View in the Component Gallery.
Edit

Enables you to edit an existing Dynamic View by displaying the Edit View dialog box for the selected view.
Remove

Enables you to remove the selected Dynamic View from the Component Gallery.

See Also

Other Resources

Catalogs Tab, Component Gallery Options Dialog Box
Find Component Dialog Box
Component Gallery Options Dialog Box
Component Gallery Window
Standard Tab, Component Gallery Options Dialog Box


Find Component Dialog Box

Visual FoxPro 9.0
Find Component Dialog Box
See Also

Enables you to search catalogs or folders by any of several criteria. The search criteria is saved as a view that you can use again.

This dialog box appears when you click the Find button on the Component Gallery toolbar. Your search criteria are automatically saved as a view description before you close the Find Component dialog box. You can remove any gallery views you no longer need by using the Remove button of the Options dialog Dynamic views tab.

Dialog Box Options

Containing

Specifies a comma-separated list of expressions for which to search. You can use the same expressions used in How to: Filter the Class Browser Class List.
Look in

A selectable list of available catalogs and an "all catalogs" option. You can add a new scope for the search.
Keywords

Displays the Keywords Dialog Box for selecting within the Keywords field of the selected catalog.
Note:
All keywords are stored in the Keywords.dbf table in the HOME() folder.

Search fields

These check boxes select fields from the highlighted catalog:

Item Name

Searches for the Name as displayed in the General tab of the Item Properties dialog box.
Class Name

Searches for Class Name as displayed in the Class Item tab of the Item Properties dialog box.
Description

Searches for the Description as displayed in the General tab of the Item Properties dialog box.
Properties

Searches contents of Properties as displayed in the Scripts tab of the Items Properties dialog box.
File Name

Searches for the file name displayed as Class Library in the Class Items tab of the Item Properties dialog box.
Item Types

A list of the available default and user-defined item types to select as search targets.
Find

Starts the search once all criteria are set.
Cancel

Cancels a search.
New Search

Clears current criteria so you can start a new search specification.
Result View

Displays the name of the view you are creating or editing.

See Also

Other Resources

Component Gallery Properties Dialog Boxes
How to: Filter the Class Browser Class List
Component Gallery Options Dialog Box
Component Gallery Window


Component Gallery Properties Dialog Boxes

Visual FoxPro 9.0
Component Gallery Properties Dialog Boxes
See Also

In the Component Gallery you can use the Properties option on shortcut menus to view or change the properties of gallery catalogs, folders, or other items. The following topics provide details on each type of properties dialog:

  • Catalog Properties Dialog Box

  • Folder Properties Dialog Box

  • Item Properties Dialog Box

See Also

Other Resources

Component Gallery Options Dialog Box
Component Gallery Window
Add Class to Project Dialog Box


Catalog Properties Dialog Box

Visual FoxPro 9.0
Catalog Properties Dialog Box
See Also

Allows you to customize the behavior of a Component Gallery catalogs by accessing values in the related table.

This dialog appears when you click Properties on the shortcut menu of a selected catalog.

General Tab

Enables you to specify settings that are global for all catalogs. The following settings are available in this tab:

Name

Displays the value in the Text field as the component label in the Component Gallery.
Description

Optional information from the Desc field that displays in the description pane of the Component Gallery.
Picture

Value in the Folderpict field that specifies the path and file name of the graphic used to represent the item in the gallery.
Item picture

Value in the Picture field which specifies the path and file name of the graphic used to represent items in this catalog that have no specified picture.
Item Desc.

Value in the Typedesc field which contains a description that applies to all items contained in this catalog or folder.

Node Tab

A node is any selectable gallery item. Enables specifying settings that are global for all catalogs. The following settings are available in this tab:

ID

The name of the table plus the value in the ID field for the selected catalog.
Link ID

If the selected item is a link, specifies the name of the source item.
Class name

The value in the Classname field, which specifies the name of the class of the selected catalog or folder.
Class library

The value in the Classlib field, which specifies the name and path to the class library containing the gallery item.
Item class

The value in the Itemclass field that specifies the default class of items in the selected catalog that have no previously assigned class.
Dynamic Catalog

Value in the Filename field, which contains the target expression, filename, or URL that is launched when you select this dynamic catalog item.

Scripts Tab

This tab provides a place to specify events or properties that are global for all catalogs. The following areas are available in this tab:

Script

The value in the Script field that contains any event script related to this catalog and its items.
Properties

The value in the Properties field, which can contain value assignments to properties of the item.

Comments Tab

Enables specifying settings that are global for all catalogs. The following settings are available in this tab:

Comments

The value in the Comment field, which contains user comments about usage, characteristics, or anything.
User

The value in the User field, which contains user comments about usage, characteristics, or anything.

Item Types Tab

Enables specifying settings that are global for all catalogs. You can edit the setting of existing catalogs by selecting a catalog type from the list, or you can add a new type by clicking the Add button.

The tab provides a listbox that enables you to select an existing item type so you can view or modify its options. The following settings are also available in this tab:

Add button

Enables you to add new item types to the component gallery. You can then configure and specify the following properties:
Text

Specifies the label that displays in the Component Gallery.
Class

Specifies the class name of the selected item.
Class library

Specifies the name and path to the class library containing the gallery item.
File types

Specifies the file extension options the GETFILE( ) dialog box will provide for this item.
Item Type

Specifies whether the new item type is a folder or a gallery item.
Properties

Can contain value assignments to properties of the item.
Redirect

Specifies which extensions to use based on gallery item type.
Remove button

Enables you to remove an existing gallery item type.

See Also

Other Resources

Folder Properties Dialog Box
Item Properties Dialog Box
Component Gallery Window
Component Gallery Properties Dialog Boxes


Folder Properties Dialog Box

Visual FoxPro 9.0
Folder Properties Dialog Box
See Also

Allows you to customize the behavior of Component Gallery folders.

This dialog appears when you click Properties on the shortcut menu of a selected folder.

General Tab

Enables specifying settings that are global for all catalogs. The following settings are available in this tab:

Name

Displays the value in the Text field as the component label in the Component Gallery.
Description

Optional information from the Desc field that displays in the description pane of the Component Gallery.
Picture

Value in the Folderpict field that specifies the path and file name of the graphic used to represent the selected item in the gallery.
Item picture

Value in the Picture field which specifies the path and file name of the graphic used to represent items in this catalog that have no specified picture.
Item desc

Value in the Typedesc field which contains a description that applies to all items contained in this catalog or folder.

Node Tab

A node is any selectable gallery item. Enables specifying settings that are global for all catalogs. The following settings are available in this tab:

ID

The name of the table plus the value in the ID field for the selected folder.
Link ID

If the selected item is a link, specifies the name of the source item.
Class name

The value in the Classname field which specifies the name of the class of the selected folder.
Class library

The value in the Classlib field which specifies the name and path to the class library containing the gallery item.
Item class

The value in the Itemclass field which specifies the default class of items in the selected folder that have no previously assigned class.
Dynamic folder

Value in the Filename field which contains the target expression, filename, or URL that is launched when you select this dynamic folder item.

Scripts Tab

This tab provides a place to specify events or properties that are global for all folders. The following areas are available in this tab:

Script

The value in the Script field which contains any event script related to this catalog and its items.
Properties

The value in the Properties field which can contain value assignments to properties of the item.

Comments Tab

Enables specifying settings that are global for all catalogs. The following settings are available in this tab:

Comments

The value in the Comment field which contains user comments about usage, characteristics, or anything.
User

The value in the User field which contains user comments about usage, characteristics, or anything.

See Also

Other Resources

Catalog Properties Dialog Box
Item Properties Dialog Box
Component Gallery Properties Dialog Boxes
Component Gallery Window


Item Properties Dialog Box

Visual FoxPro 9.0
Item Properties Dialog Box
See Also

Allows you to customize the behavior of Component Gallery items.

This dialog appears when you click Properties on the shortcut menu of a selected item. When you select Advanced editing enabled in the Component Gallery Options Dialog Box, this dialog will also display the Type, Scripts, Views, and Comments tabs.

General Tab

Enables you to specify the following settings in this tab:

Name

Displays the value in the Text field as the component label in the Component Gallery.
Description

Optional information from the Desc field of this record in the selected table (specified in Node tab.ID). This item displays in the description pane of the Component Gallery.
Picture

Value in the Folderpict field which specifies the path and file name of the graphic used to represent the item in the gallery.

Views Tab

Enables you to specify characteristics that control display of this item in the Component Gallery.

Views

Specifies the name of the view and folder that contains the selected item in the following syntax:
Copy Code
<viewName>=<folderName>
Keywords

Displays the keywords by which the selected item can be found. You can add to this list by clicking the dialog button and selecting from the default list of gallery keywords.

Node Tab

A node is any selectable gallery item. Enables you to specify settings for the selected item. The following settings are available in this tab:

ID

The name of the table plus the value in the ID field of the record of the selected item in its parent catalog.
Link

If the selected item is a link, specifies the name of the source item.
Class Name

Specifies the gallery class of the selected item
Class Library

Specifies the path and file to the library containing the gallery class of the selected item.

Scripts Tab

Provides a place to specify events or properties that are global for all items. The following areas are available in this tab:

Script

The value in the Script field of the record of this item in its parent catalog. The field contains any event script related to this item.
Properties

The value in the Properties field which can contain value assignments to properties of the item.

Comments Tab

Enables specifying settings for the selected item. The following settings are available in this tab:

Comments

The value in the Comment field of this record in the parent catalog (specified in Node tab.ID) which contains user comments about usage, characteristics, or anything.
User

The value in the User field of this record in the parent catalog (specified in Node tab.ID) which contains user comments about usage, characteristics, or anything.

Item Tabs

Item tabs are generated by the Component Gallery and added to the Item Properties dialog box for most items you add to the gallery. Each Item tab provides a set of properties information that is specific to the particular item of that type. An Item Properties dialog box can include the Class Item tab, File Item tab, Form Item tab, Menu Item tab, Program Item tab, Project Item tab, and Report Item tab.

Class Item Tab

Enables you to specify the class and class library that contains the gallery item.

Class name

Specifies the Class name.
Class library

Specifies the name and path to the class library containing the gallery item.
Base class

Specifies the class from which this gallery item is subclassed.
Sample file

Specifies the name and path to a file containing an example of this gallery item.

File Item Tab

Enables you to specify the path and file name of the gallery item.

File name

Specifies the path and file name.

Form Item Tab

Enables you to specify the path and file name of the gallery item .scx file.

Form name

Specifies the path and form name.

Menu Item Tab

Enables you to specify the path and file name of the gallery item .mnx file.

Menu name

Specifies the path and form name.

Program Item Tab

Enables you to specify the path and file name of the gallery item file.

File name

Specifies the path and file name.

Project Item Tab

Enables you to specify the path and file name of the gallery item .pjx file.

File name

Specifies the path and file name of the source project.
Output name

Specifies the path and file name of the output file.
Build action

Specifies which build option (Rebuild Project, Build Application, Build Executable, or Build OLE DLL) is used when you build this project.
Rebuild all

Enables you to rebuild all files or only those that have changed since the last build.
Show Errors

Enables you to Build Option errors to an edit box after the compile is complete.
Run after build

Enables you to run the application after the build is complete.

Report Item Tab

Enables you to specify the class and class library that contains the gallery item.

Report Name

Specifies the path and file name of the source report.

See Also

Other Resources

Catalog Properties Dialog Box
Folder Properties Dialog Box
Build Options Dialog Box
Component Gallery Options Dialog Box


Add Class to Project Dialog Box

Visual FoxPro 9.0
Add Class to Project Dialog Box
See Also

Adds a class from the Component Gallery to a project.

Add class to project

Adds the class to the project.
Create new class from selected class

Creates a new class and then adds the new class to a project. The New Class dialog box is displayed, allowing you to specify a name for the new class and the class library in which the new class is stored.
Create new form from selected class

Adds a form to the project. This option is only available adding a form to the project.

See Also

Other Resources

Component Gallery Window
New Class Dialog Box
Component Gallery Properties Dialog Boxes


Coverage Profiler Window

Visual FoxPro 9.0
Coverage Profiler Window
See Also

Contains a group of Coverage Profiler Tool Buttons and options that let you specify how you display the information returned by the Coverage Engine.

Source List Pane

The upper Source List pane is divided into two columns. The left-hand column lists the classes within the selected file or All Classes, Objects, and Processes. The right-hand column displays the file containing the source code for this item. This file can be a .frx, .lbx, .scx or .vcx containing the class or object listed in the left pane, the .prg file for the ALL Classes selection or any other type of file that stores source code. For example, a .dbc could be listed if stored procedures were logged; an .frx could be listed if the Data Environment of a report form contained code.
Source Code Pane

The lower Source Code pane (in Preview mode) displays the code of the item you select in the upper Source List pane. The mode you select determines some of the content and the format of the code displayed.
Coverage Mode

In Coverage mode, the Source Code pane displays the code of the item highlighted in the upper section. The Coverage Profiler can mark the lines run and the lines not run. The default setting marks, with the symbol or symbols specified in the Coverage Profiler Options Dialog Box, each line that was not actually run. Use this mode when testing your application, to verify which lines of code actually run. By marking both the lines run and the lines not run (with different marks) you can more easily distinguish between lines that are never run, such as comments, from lines that were not run during this coverage analysis.
Profile Mode

In profile mode, the Source Code pane displays the code of the item highlighted in the upper Source List pane, the number of times a line was hit, and the duration of each line. Use this mode if you want to evaluate the performance of running code. Lines can report 0.000 duration (both 1st and Avg) even though column one shows 1 or more Hits for these lines. This happens when lines are executed so quickly that duration is less than .001 second.

See Also

Other Resources

Windows
Coverage Profiler Application
Coverage Profiler Options Dialog Box
Coverage Profiler Statistics Dialog Box
Coverage Profiler Tool buttons
Coverage Engine Object


Coverage Profiler Tool Buttons

Visual FoxPro 9.0
Coverage Profiler Tool Buttons
See Also

Contains the following Coverage Profiler Tool buttons.

 | Button | Description
FoxPro OpenFolderButton screenshot | Open Catalog Dialog Box | Displays the Open dialog box so you can open a coverage log.
FoxProSaveButton screenshot | Save As Dialog Box | Displays the Save As dialog box so you can save the Coverage Profiler application information as a table (.dbf).
FoxProStatsButton screenshot | Coverage Profiler Statistics Dialog Box | Displays the Coverage Profiler Statistics dialog box so you can view summaries of the Coverage Profiler details and review Coverage Profiler statistics relative to a specific Visual FoxPro project.
FoxProAddInsButton screenshot | Coverage Profiler Add-Ins Dialog Box | Displays the Coverage Profiler Add-Ins dialog box so you can specify Add-Ins to use with the Coverage Profiler.
FoxProCoverageButton button | Coverage Profiler Window | Displays coverage results in the lower pane of the Coverage Profiler window or in the Zoom window.
FoxProProfileButton screenshot | Coverage Profiler Window | Displays profiler results in the lower pane of the Coverage Profiler window or in the Zoom window.
FoxProPreviewButton screenshot | Coverage Profiler Window | Displays the Coverage Profiler window as a single dialog box of two panes.
FoxProZoomButton screenshot | Coverage Profiler Window | Displays the Coverage Profiler as two separate dialog boxes that you can arrange and resize.
 | Coverage Profiler Find dialog box | Displays the Coverage Profiler Find dialog so you can search for specific item in the coverage log.

See Also

Other Resources

Coverage Profiler Application
Coverage Profiler Options Dialog Box
Coverage Profiler Statistics Dialog Box
Coverage Profiler Window
Coverage Profiler Add-Ins Dialog Box


Coverage Profiler Options Dialog Box

Visual FoxPro 9.0
Coverage Profiler Options Dialog Box
See Also

Enables you to specify the path sensitivity, dialog format and environment, and the marks used for marking lines of code that run in your program or application, and the fonts for display and code.

Use Smart Pathing

Sets the Coverage Profiler to make certain assumptions about the location of files in your project or application according to how the files are listed in the coverage log. By default, Coverage Profiler prompts you to locate source files referenced in the coverage log. If you check this option, Coverage Profiler assumes that folders in which you have already located files contain additional source files you need. Uncheck this option for more complete control or if you have source files with the same name in different folders.
Register Add-Ins when run

Sets the Coverage Profiler to retain for future use the path and name information of Add-Ins as you run them so that you can locate them in the drop-down list of the Coverage Profiler Add-Ins Dialog Box.
Mark all code while log loads

Marks lines of code as the Coverage Profiler processes the coverage log (.log). This setting can slow load performance, especially in larger files.

Coverage Marks

Executed

Allows you to type a character or several characters, such as asterisks, to be used to mark each executed line of code.
Not Executed

Allows you to type a character or several characters to be used to mark each line of code that is not run. A vertical bar is the default character.
Note:
Some lines in code, such as comments, DEFINE CLASS and ELSE statements, and lines within TEXT... ENDTEXT do not appear in coverage logs because they are not executable. Also, lines broken by continuation symbols (semicolons) are considered as a single line of code and are marked only on the last line.

Start Mode

Coverage

Specifies that the Coverage Profiler application opens as a coverage analyzer, marking code that actually runs in selected projects or applications.
Profile

Specifies that the Coverage Profiler application opens as a profiler, determining the amount of time required to run lines of code in the selected project or application.

Environment

Coverage frame

Specifies that the Coverage Profiler application opens in the Windows desktop.
FoxPro frame

Specifies that the Coverage Profiler application opens within the main Visual FoxPro window.

Fonts

Display Font

Allows you to specify the font used in the Source List pane of Coverage Profiler window.
Code Font

Allows you to specify the font used in the Source Code pane of the Coverage Profiler window.
Set as default

Saves your selected options in the Windows registry. Startmode and Environment settings take effect when you restart Coverage Profiler.

See Also

Other Resources

Coverage Profiler Window
Coverage Profiler Tool Buttons
Coverage Profiler Add-Ins Dialog Box
Coverage Profiler Statistics Dialog Box


Coverage Profiler Add-Ins Dialog Box

Visual FoxPro 9.0
Coverage Profiler Add-Ins Dialog Box
See Also

Enables you to locate and run .app, .fxp, or .prg files to change or enhance the Coverage Profiler. You can use these Add-Ins to add controls, queries, dialog boxes, and other enhancements to the Coverage Profiler.

Add-Ins

Allows you to select an Add-In program to run.

Register this Add-In after running

Adds the current Add-In to a drop-down list so that you can access the Add-In in the future.
Note:
You can set the Coverage Profiler to register new Add-Ins by default by selecting the Register Add-Ins when run check box in the Coverage Profiler Options dialog box.

Run

Starts the Add-In program.

See Also

Other Resources

Coverage Profiler Window
Coverage Profiler Tool Buttons
Coverage Profiler Statistics Dialog Box
Coverage Profiler Options dialog box
Coverage Profiler Add-Ins


Coverage Profiler Statistics Dialog Box

Visual FoxPro 9.0
Coverage Profiler Statistics Dialog Box
See Also

Displays summary information from the current .log file and provides access to project, source text, and skipped files information.

Statistics

Displays summary information on the file selected in the Source List pane. The content of this area is dependent on the type of file selected. The dialog box displays only statistics on lines in the cases of database (.dbc) or program (.prg) files. In the case of file types such as .frx, .lbx, .scx, and .vcx, that contain classes, the dialog box displays information on lines and on classes. The details that comprise this information are displayed in the Source Code pane as either Coverage or Profile mode information.

View Details

Statistics by Project

Enables you to select a project file and generate a detail and summary report on the coverage of the project.
Source Text Log

Displays the current log file in the Visual FoxPro editor.
Source Files Skipped

Opens a Browse window on the SkippedFiles cursor. This cursor contains names of files for which the Coverage Profiler provides no information. These files can be files for which you have no uncompiled code, files Coverage Profiler was unable to locate, or Coverage Profiler source code.

See Also

Other Resources

Coverage Profiler Window
Coverage Profiler Tool Buttons
Coverage Profiler Add-Ins Dialog Box
Coverage Profiler Find dialog box


Coverage Profiler Find Dialog Box

Visual FoxPro 9.0
Coverage Profiler Find Dialog Box
See Also

Enables you to search the Coverage log for specific items.

Options

Match Case

Match the case of the search item
Wrap Around

Specifies that a search begun from within a file, continues past EOF through BOF to the current cursor position.

Search

Classes

Search through the classes in the coverage log.
Files

Search through the files in the coverage log.
Source code

Search through the source code in the current display.

See Also

Other Resources

Coverage Profiler Add-Ins Dialog Box
Coverage Profiler Options Dialog Box
Coverage Profiler Statistics Dialog Box
Coverage Profiler Window
Coverage Profiler Tool Buttons


Coverage Profiler Exit Dialog Box

Visual FoxPro 9.0
Coverage Profiler Exit Dialog Box
See Also

Stops the Coverage Profiler application and enables you to choose how to continue or end coverage logging. This dialog box displays if you have issued SET COVERAGE Command FileName before running the Coverage Profiler application.

The dialog provides the following options:

Button | Result
Yes | Enables you to continue logging data by appending more records to the current .log file for use in the Coverage Profiler application.
No | Enables you to continue logging data but overwrites the records in the current .log file.
Cancel | Leaves logging set off after closing the Coverage Profiler application.

See Also

Other Resources

Coverage Profiler Window
Coverage Profiler Tool Buttons
SET COVERAGE Command
Coverage Profiler Find dialog box
Coverage Profiler Statistics Dialog Box
Coverage Profiler Add-Ins


Data Session Window

Visual FoxPro 9.0
Data Session Window
See Also

You can use the Data Session window to open and display tables or views, establish temporary relationships, and set work area properties.

Current Session

Displays the name of the current data session.
Aliases

Displays the view name or table name without the file extension.
Relations

Indicates the temporary relationship established between the tables or views in the Aliases box.
Properties

Displays the Work Area Properties dialog box, in which you can modify the structure of a table, select index files and fields, and define data filters. If no tables or views are listed in the Aliases box, an Open dialog box appears to make it possible for you to open a table or view.
Browse

Displays the table or view selected in the Aliases box in a Browse window, where you can examine, edit, or append data.
Open

Displays an Open dialog box, similar to the Add Table or View dialog box, so you can select a table or view to open.
Close

Removes the selected table or view and any associated files from the Aliases box.
Relations

Defines the relations between tables or views, using the Expression Builder dialog box. The Set Index Order dialog box appears before the Expression Builder dialog box when no index order has been set between the two tables.
1-To-Many

Displays the Create One-To-Many Relationships dialog box, which makes it possible for you to establish a one-to-many temporary relationship between child tables and parent tables. This button is enabled when you establish relations between two or more tables by selecting them in the View dialog box and then clicking Relations.

See Also

Other Resources

Windows
Working with Tables
How to: Create Persistent Relationships Between Tables
Browse Window
Create One-To-Many Relationships Dialog Box
Expression Builder Dialog Box
Open Dialog Box
Work Area Properties Dialog Box


Debug Output Window

Visual FoxPro 9.0
Debug Output Window
See Also

Makes it possible for you to display output from active programs, procedures, or method code.

This window is activated when you choose Output from the Window Menu, Debugger Window.

Output Pane

Displays character strings specified by the DEBUGOUT command and, if event tracking is enabled, the names of system events as they occur.
To save the text in the window

  1. Choose Save Output As from the File menu in the Debugger window.

See Also

Other Resources

Windows
DEBUGOUT Command
Event Tracking Dialog Box
Debugger Window
Debugger Keyboard Shortcuts and Menus


Debugger Window

Visual FoxPro 9.0
Debugger Window
See Also

The Visual FoxPro Debugger window contains the Debugger menus, the Debugger toolbar, and several debugging windows.

This window is activated when you choose Debugger from the main Visual FoxPro Tools Menu, as long as the Environment option on the Debug menu (under Options on the Tools menu) is set to Debug Frame. If FoxPro Frame is selected, the Debugger window will not be accessible, and the individual debugger windows will be available from the FoxPro main menu.

Trace Window

Makes it possible for you to see your lines of code as they are being executed.
Locals Window

Displays the visible variables, arrays, objects, and object members from the current program, procedure, or method.
Watch Window

Displays expressions and their current values, and makes it possible for you to set breakpoints on an expression.
Call Stack Window

Displays procedures, programs, and methods that are executing.
Debug Output Window

Displays debug-specific output from your programs.

The debugging windows and toolbar can be docked and positioned.

To | Do
Resize adjacent docked windows | Drag the separator bar between them.
Float a window | Choose Undock from the shortcut menu.
View an open, hidden window | Click the toolbar button associated with the window twice: once to close the window and a second time to reopen the window.

See Also

Other Resources

Debugger Keyboard Shortcuts and Menus
Windows
Trace Window
Locals Window
Watch Window
Call Stack Window
Options Dialog Box


Debugger Keyboard Shortcuts and Menus

Visual FoxPro 9.0
Debugger Keyboard Shortcuts and Menus
See Also

The following keyboard shortcuts apply to the debugging tools in the Debugger window or in the FoxPro frame.

Action | Keyboard
Resume | F5
Cancel | ESC
Step Into | F8
Step Over | F6
Step Out | SHIFT+F7
Run To Cursor | F7
Trace Window | ALT+8
Watch Window | ALT+3
Locals Window | ALT+4
Call Stack Window | ALT+7
Debug Output Window | ALT+2
Toggle Breakpoint | F9
Clear Breakpoints | CTRL+SHIFT+F9
Breakpoints | CTRL+B
Open File | CTRL+O
Save Configuration | ALT+S
Exit Debugger | ALT+F4

File Menu, Debugger Window

This contains options that make it possible for you to open programs and debugging configurations. You also can save debug output to a file.

Menu Commands

Open

Displays the Open dialog box so you can specify a program to display in the Trace window. Opening a program does not run the program.
Load Configuration

Loads breakpoints, watches, and events to be tracked from a configuration file (.dbg file). Select the dialog button to display the Open dialog box, which makes it possible for you to specify a file.
Save Configuration

Saves the current breakpoints, watches, and events to be tracked into a configuration file (.dbg file) so they can be restored later. Select the dialog button to display the Open dialog box, which makes it possible for you to specify a file.
Save Output As

Writes the text displayed in the Debug Output window to a file specified in the Save As dialog box.
Exit

Closes the Debugger window and returns you to the main Visual FoxPro window.

Debug Menu, Debugger Window

This contains options for stepping through code. You also can set the speed at which commands are executed as you watch.

Menu Commands

Do

Begins executing the program open in the Trace window. If no program is open in the Trace window, this displays the Do dialog box, so you can specify a program or form to trace. The program or form you specify is executed with program execution suspended at the first line of executable code.
Resume

Is available if program execution is suspended. Continues execution of the program in the Trace window at the current line of code.
Cancel

Closes and stops executing the program or form in the Trace window.
Fix

Is available if program execution is suspended. If you are tracing through a program, Fix prompts you to cancel the program and then opens it in an editing window, at the same position that the cursor is in the Trace window. If you are tracing through code in a form, Fix prompts you to cancel execution and clear the form object from memory. Then an editing window in the Form Designer opens at the same position that the cursor is in the Trace window.
Step Out

Continues executing the code in a procedure without stepping through the code line by line. Program execution is suspended again on the line of code following the procedure call in the calling program.
Step Over

Executes the next line of code. If the next line of code calls a function, method, or procedure, then the function, method, or procedure is executed in the background.
Step Into

Executes the next line of code.
Run To Cursor

Executes code from the current line indicator to the line of code with the cursor. Click the line of code on which you want to suspend execution to place the cursor on that line.
Throttle

Opens the Execution Throttle dialog box so you can specify the delay in seconds between the execution of each line of code.
Set Next Statement

Places the current line marker on the line of code with the cursor. This line of code will then be executed when you step or resume execution.

Tools Menu, Debugger Window

This provides access to the Debugger dialog boxes.

Menu Commands

Breakpoints

Opens the Breakpoints dialog box so you can add, delete, enable, or disable breakpoints.
Event Tracking

Opens the Event Tracking dialog box so you can specify which events are written to the Debug Output window or a file when they occur.
Coverage Logging

Opens the Coverage dialog box so you can turn coverage logging on or off and specify a file for the coverage log.

See Also

Other Resources

Debugger Window
Debug Output Window
Keyboard Shortcuts


Document View Window

Visual FoxPro 9.0
Document View Window
See Also

Makes it possible for you to view and navigate to any procedure, function, or #DEFINE definition, class or preprocessor directive in your program.

You can activate this window from the Tools menu or when you choose Document View from the shortcut menu of a program in an editing window.

Note:
When the Document View window is open for a .prg file, you can use Ctrl-PgUp and Cltr-PgDn to navigate to the prior/next procedure.

Right-click in this window to access the following options.

Sort by Name

Specifies that list items are sorted by name.
Sort by Location

Specifies that list items are sorted by location in the program. When you select this option, you can use Ctrl+PageUp or Ctrl+PageDown to navigate through the listed items. Also, the Document View Window will automatically select the procedure that currently contains the insertion carat in the editor.
Sort by Type

Specifies that list items are sorted alphabetically by item type.
Display #define definitions

Toggles display of #DEFINE definitions in the list.
Display preprocessor directives

Toggles display of preprocessor directives. The display reports the following items: #INCLUDE #IF...#ELIF...#ELSE...#ENDIF #IFDEF...#ELSE...#ENDIF #IFNDEF...#ELSE...#ENDIF
Font

Opens the Font Dialog Box so you can change the font used in the Document View window

The Document View Window visually indicates each procedure or function, preprocessor definition, class, and preprocessor directive with the following symbols:

  • A red # (number sign) represents a preprocessor definition.

  • A yellow # (number sign) represents a preprocessor directive.

  • A blue box represents a function or procedure.

  • A set of multicolored boxes represents a class.

See Also

Other Resources

Windows
Insert Object Reference Dialog Box
#DEFINE ... #UNDEF Preprocessor Directive
#NAME Preprocessor Directive
APROCINFO( ) Function


Editing Window

Visual FoxPro 9.0
Editing Window
See Also

Provides text and program file editing. If you have selected Modify Selected File in the Projects tab, Options dialog box, the Editing window opens when you double-click a text or program file in the Project Manager.

In the Editing window, you can:

  • Move text within the Command window and to other editing windows. Select the desired text, and then drag it to the desired spot.

  • Copy text within the Command window and paste it into other editing windows without using Edit menu commands. Select the desired text, hold down CTRL, and then drag the text to the desired spot.

Change font, line spacing, and indentation by selecting the appropriate command from the Format menu.

See Also

Other Resources

Windows
How to: Display and Print Source Code in Color
Projects Tab, Options Dialog Box
Project Manager Window
Command Window


General Field Window

Visual FoxPro 9.0
General Field Window
See Also

This window is displayed when you double-click a General field's type designator in a browsed table, or press CTRL+PAGE UP or CTRL+PAGE DOWN to open the General Field window from the keyboard.

With this window displayed, you can create or insert OLE objects by using the Insert Object command on the Edit menu. You can edit the existing object by double-clicking it or by selecting Bitmap Image objectEdit or objectOpen from the Edit menu.

See Also

Other Resources

Windows
General Field Type
Table Designer
Insert Object Dialog Box
How to: Add General Fields to Reports


Go To Definition Window

Visual FoxPro 9.0
Go To Definition Window
See Also

Displays multiple code element definitions that you can choose from when searching for a code definition.

The Go To Definition window appears after the selection of the View Definition command results in multiple code element definitions. You can select the View Definition command from the shortcut menu that appears when you right-click inside a program's Editing window.

File

Lists the file name and location of the code definition.
Class.Method (Line)

Lists the class, method, and line number, if available, of the code definition.
Code

Lists the code that contains the code definition.
Go To

Moves to the location of the code definition selected.

See Also

Other Resources

Windows
How to: View Code Definitions
Editing Window


Locals Window (Visual FoxPro)

Visual FoxPro 9.0
Locals Window (Visual FoxPro)
See Also

Makes it possible for you to display all the variables, arrays, objects, and object members that are visible in a given program, procedure, or method.

This window is activated when you choose Locals from the Window Menu, Debugger Window.

In Visual FoxPro 9.0, the Find and Find Again menu items are available to search for items in the Name column of the Locals window.

Locals for

Indicates the procedure whose variables, arrays, and objects are displayed in the Locals window.
Name

Displays the names of the visible locals.
Value

Displays the current values of the visible locals.
Type

Displays characters that represents the data types of the visible locals.

Use the shortcut menu to control the category of variable displayed.

Category | Description
Public | Variables declared with the PUBLIC keyword.
Local | Variables declared with the LOCAL keyword.
Standard | All variables in the scope of the procedure displayed in the Locals for box.
Objects | Object variables.

To see the values of array elements or object properties, click the box to the left of the array or object name. The Locals window makes it possible for you to see properties of all objects in the container hierarchy.

See Also

Other Resources

Windows
LOCAL Command
PUBLIC Command
Debugger Window
Debugger Keyboard Shortcuts and Menus


MemberData Editor

Visual FoxPro 9.0
MemberData Editor
See Also

The MemberData Editor application allows developers to edit MemberData. The MemberData Editor presents an easy to use front-end so that you can view and edit MemberData associated with your classes.

To run the MemberData Editor, select the MemberData Editor menu item from the Form or Class menu when a Form or Class Designer is active. The member that is selected in the Properties window will be selected in the MemberData Editor. However, you can click on and edit MemberData for other members of the class selected in the designer.

The MemberData that you view and edit is stored with the _MemberData property which you can also edit directly from the Properties Window. Global MemberData is stored in your _FOXCODE table. MemberData is formatted as XML.

Using MemberData Editor

You can view and edit MemberData using the MemberData Editor. The following

Member List

Contains a list of all available members (properties, events and methods) for the selected class in the designer. Select a member to add or change its MemberData. A ">>" prefix character indicates that the member has MemberData associated with it. If the member is bold, it has MemberData for the selected Scope.
Scope

The Scope setting specifies where the MemberData is stored. The following settings are available:
  • Object – MemberData available at the object level. This option requires the selected object to have a _MemberData property, otherwise this option is disabled.

  • Container – MemberData available at the container level such as a form. If an object does not have its own MemberData, then it can inherit from its container. If multiple containers exist, each with their own _MemberData property, then the container dropdown is enabled.

  • Global – MemberData at the global level (your _FOXCODE table). This setting is not object specific. If an object does not inherit from the object or container MemberData, then it will use the Global setting if available.

You should understand the inheritance rules with MemberData since this impacts the Scope setting. The MemberData Editor, when invoked, is brought up for the currently selected object and property. For example, if a Textbox control on a form is selected, and the Textbox control does not contain a _MemberData property, then you cannot specify MemberData at the Textbox Object Level. You can only specify at the container (form) or global level.
Has MemberData

Select this option to add MemberData for the selected member. MemberData XML is only added for the Scope selected.
Description Pane

Lists the MemberData attributes that are set for the selected member and which Scope currently controls the setting.
Note:
The Hierarchy button displays MemberData detail for all scopes of the selected member.

Filter

You can filter the list of Members based on following criteria:
  • All members - all members of selected object are listed.

  • Custom members only - only custom properties or methods are listed.

  • Custom members added in this class - only custom properties or methods that were added to current instance of object are listed. Inherited custom members are not shown.

  • Native members only - displays only intrinsic Visual FoxPro members.

  • Favorites only - displays members that have a Favorites MemberData attribute assigned.

View XML

Displays MemberData XML detail for all members of the selected object at the selected scope.
Hierarchy

Displays MemberData attribute detail for all scopes of the selected member.
Options

Brings up the Options dialog.

Core MemberData Attributes

Visual FoxPro reserves certain MemberData attributes for the operational use of members in the Visual FoxPro IDE. The following attributes can be set using the MemberData Editor:

Favorites

Allows you to control whether a member is displayed in the Propertieswindow Favorites tab. If you check this option, you can specify True or False in the drop-down list box. The check box determines whether the favorites attribute is written out to the MemberData XML, and has implications on inheritance from above.
Override

Allows you to control whether MemberData attributes not found for that member are searched for up the hierarchy. If you check this option, you can specify True or False in the drop-down list box. The check box determines whether the override attribute is written out to the MemberData XML, and has implications on inheritance from above.
Display As

Controls how the member is displayed in the Visual FoxPro IDE such as with the Properties window and IntelliSense. This option is only available for custom (user-defined) members. This setting is represented by the display attribute.
Script

You can enter a script that is invoked when the user clicks the ellipsis (…) button next to the Property settings box in the Properties window. The Script box and button are only enabled for properties. Click the Script button to open the script in a larger edit window. This setting is represented by the script attribute.
Note:
Scripts are available for all custom properties and some native properties.

User-Defined MemberData Attributes

The MemberData is an XML formatted structure which allows for extensibility. Visual FoxPro provides certain core MemberData usage such as Favorites. You can also add custom attributes to the MemberData XML for use that you define. Visual FoxPro will store and retain these custom attributes with the core MemberData.

Custom Attributes List

Lists all MemberData custom attributes for the selected member.
Value

Sets a value for the custom attribute selected in the list.
Add

Adds a new custom attribute to the MemberData. As with all XML attributes, the ones you add are case-sensitive. You cannot add a name which is already reserved, such as favorites.
Remove

Removes a custom attribute from the MemberData.

Options Dialog Box

The Options dialog lets you control various settings of the MemberData Editor user interface as well as options for the generated MemberData.

Use Hungarian names

The default property capitalization for the Display as setting (display attribute) sets the first letter in lowercase and rest in proper case.
Method prefixes

Contains a comma-delimited list of prefixes to control how capitalization is done for MemberData when a custom method has a prefix that matches one in this list. When one is found, the MemberData Editor capitalizes the prefix based on what is in list, and capitalizes the rest of the name in proper case.
Line break after each XML element

Specifies whether a line break is inserted after each XML element in newly generated _MemberData.
Automatically add _MemberData property to objects

If this setting is turned on, a record is added to your IntelliSense (_FOXCODE) table that automatically creates a _MemberData property for a form opened in the Form Designer or the outer-most object in the Class Designer.
Script Font

Specifies font used in the Script edit box.

See Also

Reference

Task Pane Manager
_MemberData Property

Concepts

MemberData Extensibility
Report XML MemberData Extensions


Object Browser Window

Visual FoxPro 9.0
Object Browser Window
See Also

The Object Browser displays the classes, properties, methods, events, and constants available for COM object libraries. You can use it to find and use objects you create, as well as objects from other applications.

To launch the Object Browser from the Tools menu, choose Object Browser and open a COM library to view.

The Object Browser application is referenced by _OBJECTBROWSER system variable (which by default references objectbrowser.app). You can set this from the File Locations tab of the Options dialog box.

Classes & Members pane

Lists the classes, members, interfaces, enums, constants, and other information available from the class type library. To display members of each category, expand the category.
Members pane

Lists the member details of the selected item in the Classes & Members pane. If a class is selected, its events, methods, and properties are displayed.
Description pane

Displays the definition of the selected item, prototype syntax, and a hyperlink to the class, library, or type to which the item belongs. Some members have hyperlinks to their parent class. When an interface is selected, the description pane includes the Interface ID number. You can copy or drag text from the description pane to the editing window.
Open Type Library button

Displays the Open Type Library dialog box so you can select a particular COM Component or ActiveX Control. To display a list of recently opened libraries, click the down arrow.
Open Type Library dialog box

Appears when you click the Open Type Library button or right-click the Object Browser and then click Open.

Name Description

Recent History tab

Displays a list of recently opened libraries. To add a library to the Object Browser, select the check box next to the library. To clear all content in the Recent History list, click Clear History.

COM Libraries tab

Shows a list of all available COM class libraries on your system. The list includes libraries for COM components and ActiveX controls.

The first time you click this tab, the COM libraries are read from your system registry and cached to a local FoxRefs.dbf table. When you click the tab again, libraries are read from this table.

To reload all class libraries from your system, click the Refresh button. To select and load an individual library (.tlb, .ocx, .olb, .dll, .exe), click Browse to open a file picker dialog box.

Current Selection Tab

Displays a list of all open libraries.

To close individual libraries, clear the check box next to the library name. To close all libraries, click Close All.
Back button

Moves selection focus back to the last item that you viewed.
Forward button

Moves selection focus to the item you were viewing before clicking the Back button.
Refresh button

Refreshes the contents of the Object Browser by reloading the selected libraries. This is useful for frequently changing COM components under development. Additionally, cached libraries are refreshed.
Copy button

Makes it possible for you to copy the selected item in the current list. If there is no explicit selection in the Description pane, the entire text is copied.
Find button

Displays the Find view so you can enter a specific text string to search for within the libraries opened in the Object Browser.
Find view

Expands at the top of the Object Browser when you click the Find button. Use the Find view to search for a specific text phrase in the library.

Name Description

Look for: textbox

Enter text for which to search. The default search includes all opened libraries, all their members, and any item that contains the search text.

Go button

Click button to search for text entered in the text box. When you click this button a new node is added for each opened library to the Classes & Members pane with expression "(Search: <searchtext>)" appended to the end of the library. You can refine search using the Advanced view.

Switch to advanced find... link

Displays additional search options to perform a more refined search.

Libraries dropdown

Limits search to all opened libraries or just a single one. Advanced Find view only.

Scope dropdown

Limits search to members of all libraries or just a single one. The list of available options includes Classes, Constants, Enums, Interfaces, Methods, Events, and Properties. Advanced Find view only.

Options dropdown

Determines how text search is made. Options include Contained in, Starts with, and Exactly like. Advanced Find view only.
Options button

Displays the Options dialog box so that you can control various display options. You can also set custom add-ins for use with the Object Browser.
Display Options tab, Options dialog box

This tab in the Options dialog box makes it possible for you to control the visual aspects of the Object Browser.

Name Description

Highlight Potential Sources of Events check box

Specifies whether a potential source of events (interface or method) is highlighted.

Highlight Default Items check box

Specifies whether default items are highlighted using a bold font style.

Display Hidden Items check box

Specifies whether hidden items (such as interface, methods, and properties) are displayed.

Auto Expand Details check box

Specifies whether top-level items in the detail pain are expanded automatically.

Auto Drill Down Details check box

Specifies whether complex hierarchies in the Methods pane (such as methods and properties for each interface) are expanded automatically.

Display VTable Interfaces check box

Specifies whether VTable based interfaces and their members are displayed.

List all interfaces defining a method, event, or property in detail check box

Specifies whether all interfaces defining a method or property are listed in the Description pane.

Display properties that start with an underscore (_) check box

Properties that start with an underscore are usually placeholders for enums (a collections of constants). For this reason, they are not displayed by default.

Display members that are defined in IUnknown or IDispatch check box

All COM objects have methods that are defined in the IDispatch and IUnknown interfaces. These methods must be there to work in a COM environment; however, they usually are not useful directly to the Visual FoxPro developer.

List members parameters in detail check box

Method parameters can be listed directly in the Members pane. However, note that the parameters are listed in more detail in the Description pane.

List interfaces in class details check box

All creatable classes are based on one or more interfaces. Often interfaces listed in the Members pane simply show the same information as the entire class, but sometimes they provide more insight.

Show Interface Inheritance structure check box

Specifies whether inherited interfaces shall be displayed in the Members pane.

Font button

Specifies font for interface elements of the Object Browser.
Add Ins tab, Options dialog box

This tab in the Options dialog box makes it possible for you to add custom add-ins.

Name Description

Install Add-In button

Installs a new add-in.

Installed Add-Ins list

Displays all loaded add-ins.

Remove button

This button is displayed in the Add-Ins list next to an installed add-in. Click this button to remove an add-in. The add-in file is not actually deleted.
Help button

Displays documentation on the selected member. In addition, you can press F1.

See Also

Other Resources

Windows
How to: Use the Object Browser
Class Browser
_ObjectBrowser System Variable
DEFINE CLASS Command
EVENTHANDLER( ) Function
How to: View Type Library Information


Project Manager Window

Visual FoxPro 9.0
Project Manager Window
See Also

Use the Project Manager to organize and manage your files in projects. A project is a collection of files, data, documents, and Visual FoxPro objects that is saved as a file with a .pjx extension. When the Project Manager window is active, Visual FoxPro displays the Project menu on the menu bar.

The items in the Project Manager are organized in an outline-like view that you can expand or collapse. A plus sign appears next to a symbol if there are one or more items of that type in the project. Click the plus sign next to a symbol to see items in the list. Click the minus sign to collapse an expanded list.

Initially, the Project Manager appears as a separate window. You can move the container, resize it, or collapse it so that only the tabs show.

As with toolbars, you can dock the Project Manager by dragging it to the top of your screen or double-clicking the title bar. When the Project Manager is docked, it becomes part of the toolbar area of the window. You can't expand the Project Manager window when it's docked; instead, click on individual tabs to use them. You can also tear off tabs from a docked Project Manager.

When the Project Manager is docked, you can right-click on it to display a shortcut menu. In Visual FoxPro 9.0, the following options are available on the shortcut menu:

Undock

Restores the Project Manager to its former size and location.
Close

Closes the Project Manager.
Add Project to Source Control

If source control software is installed, adds the project to source control.
Project Info

Displays the Project Information Dialog Box, allowing you to view and edit information about the project and its files.
Errors

Opens an Error window that displays errors found when a project or application was built.
Build

Displays the Build Options Dialog Box. This dialog box lets you build a project or application, and you can also build an executable or Automation server.
Refresh

Refreshes the visual display of the Project Manager.
Clean Up Project

Cleans up a project by removing records marked for deletion and packing memo fields.
Builder

Displays the Wizard Selection Dialog Box, containing a list of wizards from which you can choose
Help

Opens the Help window.

You can customize your visual work area by changing your view of the Project Manager or by setting double-click to run files in the Project Manager. For more information, see Customizing the Visual FoxPro Environment.

Tabs

Display items by category. When the Project Manager is collapsed, you can tear off tabs by dragging them away from the Project Manager. To replace a tab, just drag it back to its original position, or click the Close box.

To tear off a tab, collapse the container, select a tab and drag it away from the Project Manager. When a tab is floating, you can access the options on the Project menu by right-clicking the mouse in the floating tab.

If you want the tab to always remain on top, click the pushpin icon at the top of the tab. The tab will remain on top of other Visual FoxPro windows. You can set more than one tab to be "always on top." To remove the "always on top" setting on a tab, click the pushpin icon again.

Expanding/Collapsing Button

Expands and collapses the Project Manager. When the Project Manager is collapsed you can "tear off" tabs by placing the mouse pointer over a tab and dragging it away from the Project Manager.

Items List

Lists the items contained in the project in an outline-like view. Icons appear to the left of the item to identify its type.

The symbol appears next to items that are excluded from the project.

When files are included in the project, they are compiled into a single .app file when the project is built. All included files are read-only at run time. In the Programs, Forms, Queries, or Menus group, the name of the main program file appears in bold.

Project Manager Buttons

New

Creates a new file or object. This button has the same effect as the New File command on the Project menu. The new file or object's type is the same as that of the currently selected item.
Note:
Files created from the File menu are not automatically included in a project. Files created from the New File command on the Project menu (or the New button in the Project Manager) are automatically included in a project.

Add

Adds an existing file to the project. This button has the same effect as the Add File command on the Project menu. After clicking Add, you can select multiple files by pressing the SHIFT or CTRL key in the Open dialog box while clicking files to add them.
Modify

Opens the selected item in the appropriate designer. This button has the same effect as the Modify File command on the Project menu.
Browse

Opens a table in a Browse window. This command has the same effect as the Browse File command on the Project menu, and is enabled only when a table is selected.
Close

Closes an open database. This command has the same effect as the Close File command on the Project menu, and is enabled only when a table is selected. If the selected database is already closed, this button changes to Open.
Open

Opens a database. This command has the same effect as the Open File command on the Project menu, and is enabled only when a table is selected. If the selected database is already open, this button changes to Close.
Remove

Removes the selected file or object from the project. Visual FoxPro asks you if you want to just remove the file from the project or if you want to remove it from the project and delete it from disk. This command has the same effect as the Remove File command on the Project menu.
Build

Builds a project or application and can also build an executable or Automation server. This command has the same effect as the Build command on the Project menu.
Preview

Displays the selected report or label in Print Preview mode. Enabled when you select a report or label in the Project Manager. This command has the same effect as the Preview File command on the Project menu.
Run

Runs the selected query, form, or program. Enabled when you select a query, form, menu, or program in the Project Manager. This command has the same effect as the Run File command on the Project menu.

See Also

Other Resources

Windows
Browse Window
Browse Window
Excluding Modifiable Files from Builds
User Interface Creation without Programming
Compiling an Application


Properties Window (Visual FoxPro)

Visual FoxPro 9.0
Properties Window (Visual FoxPro)
See Also

Displays properties, events, and methods and their settings when available for a selected object.

Note:
The names of properties that are read-only and cannot be edited appear in italic in the properties list.

For information about how to set values for object properties, events, and methods, see How to: Set Properties for Objects. For keyboard shortcut commands, see Keyboard Shortcuts.

Object list

Shows the currently selected object and displays a list of available objects when you click the arrow to the right of the list. This list includes the current form, form set, and all the controls on the form.

If the Data Environment Designer is open, the object list includes the data environment and all cursors and relationships in the data environment.

Tabs

Display properties, events, and methods by category:

  • All All properties, events, and methods.

  • Data Properties associated with what and how data is displayed or manipulated by the object.

  • Methods Methods and events.

  • Layout All layout properties.

  • Other Miscellaneous and user-defined properties.

  • Favorites Your favorite properties, events, and methods. To add a property, event, or method to the Favorites tab, right-click the property, event, or method and choose Add to Favorites. Properties, events, and methods can also be programmatically added to the Favorites tab. See MemberData Extensibility for more information.

Property settings box

Makes it possible for you to change the value of a read/write property when selected in the properties list.

Tip:
If the selected property has predefined settings, the property settings box contains a list of settings that you can choose from. To open the list, click the arrow to the right of the property settings box.

Tip:
You can browse settings by double-clicking the property name in the properties list. If the setting requires a file name or a color, click the ellipsis (...) button to display the appropriate dialog box or window for selecting a file or color.

Note:
The property settings box, Cancel, and Accept buttons are not available if the value for a property exceeds 255 characters or contains extended characters. To edit the property setting, use the Zoom dialog box or the Expression Builder.

The following buttons appear to the left of the property settings box:

  • Cancel (X) Cancels the changes you made to the setting and restores the original value.

  • Accept (check symbol) Confirms changes you made to a setting.

  • Function (Fx symbol) Opens the Expression Builder. The Function button is available when the property value is an expression. You can set literal values or values returned by functions or expressions. For more information, see Expression Builder Dialog Box.

  • Zoom (Z) Opens the Zoom dialog box so you can edit the value for a read/write property.

    For certain types of properties, Visual FoxPro 9.0 provides support for specifying values that exceed 255 characters (limited to 8K chars) directly in the Properties Window via the Zoom dialog. Additionally, these values can include carriage returns and linefeeds. This support is limited to custom user-defined properties as well as certain native properties. Common native properties that support extended values include Value, Text, DisplayValue, UserValue, PictureVal, CommandClauses, _MemberData, CursorSchema, DataSource as well as CursorAdapter and XMLAdapter class properties related to specifying a data source, field list or command.

    Tip:
    You can determine whether a property supports extended values by opening up the Zoom dialog for that property. If the dialog does not include an Apply button and you can type in a carriage return, then you have selected a property that supports extended values.

    Note:
    You can still specify extended values for properties that do not support them directly in the Zoom Dialog by setting their value in code, such as in the Init event of that object. Note that values typed into the Zoom dialog that exceed 255 characters for properties not supporting extended values will be truncated when the class is saved.

    Caution:
    Property values that exceed 255 characters or include extended characters such as CHR(13) (carriage return) or CHR(10) linefeed are stored in a special format inside the class library (.vcx) or form (.scx) file. The property value will contain special padding with CHR(1) characters. Be aware that classes in visual class libraries (.vcx) or forms (.scx) that contain properties with such values cannot be used in versions prior to Visual FoxPro 9.0. If you attempt to modify these in a prior version, an error occurs. You can still use other classes in the same visual class library (.vcx) files with previous versions of Visual FoxPro as long as they do not contain property values exceeding 255 characters or include carriage return or linefeed characters.

    The Zoom button might not be available for some properties. For more information, see Zoom <property> Dialog Box.

Properties list

This list shows all properties that can be changed at design time and their current settings. To get Help for a specific property, select the property and press F1.

The property settings in the properties list can appear as follows:

  • Property settings that are expressions are prefaced with an equal sign (=).

  • Settings for properties, events, and methods that are read-only appear in italics.

  • Methods and events display inheritance details as follows:

    Copy Code
    Default
    -or-

    Copy Code
    Inherited cClassname ClassLibrary
    For more information about viewing inherited code for a method or event, see How to: Display Inherited Code for Objects, Events, and Methods.

See Also

Other Resources

Windows
How to: Set Properties for Objects


Task List Manager Window

Visual FoxPro 9.0
Task List Manager Window
See Also

Makes it possible for you to keep track of tasks. To customize the Task List Manager, see Customizing the Task List Manager.

The Task List Manager appears when you click Task List on the Tools menu. You can also access the Task List Manager using the _TASKLIST system variable, which references Tasklist.app by default. You can modify this reference on the File Locations tab in the Options dialog box. For more information, see _TASKLIST System Variable or File Locations Tab, Options Dialog Box.

The task list is stored as a table in the FoxTask.dbf file. You can specify a different file using the _FOXTASK system variable. For more information, see _FOXTASK System Variable.

Task List Visual Cues

The Task List Manager indicates important information through visual cues:

Visual cue | Description
Red text | Indicates that the Due Date has passed already.
Black text | Indicates that the Due Date has not yet arrived yet.
Blue text | Indicates that today is the Due Date.
Bold text | Indicates that the task has not been Read yet.
Strikethrough text | Indicates that the task has been Completed.
Red up arrow | Indicates a high Priority task.
Blue down arrow | Indicates a low Priority task.
Icon with arrow | Indicates a Shortcut task.
Icon with person/task | Indicates a User-Defined or Other task.

Task Fields

The Task List Manager includes the following fields:

Field Name Description Initially Displayed Removable Shortcut Editable User- Defined Editable

Priority

Dropdown showing priority of task.

X

X

X

Task Completed

Checkbox indicating if task is complete.

X

X

X

Task Type

Visual representation of task type (icon). Internally, the types are represented by the following values in the Foxtask Type field:

Note:
S - Shortcut

Note:
U – User-Defined

Note:
O – Other

X

Contents

Description of the task.

X

X

File Name

Name of file containing the Shortcut or one associated with task.

X

X

X

Due Date

Date when task is scheduled to be completed.

X

X

X

X

Class

Name of class containing the Shortcut or task association.

X

X

Line

Line number of Shortcut or task association.

X

X

Method

Name of method containing the Shortcut or task association.

X

X

Timestamp

Numeric datetime stamp when task was first added.

X

Custom

You can add custom fields for tasks.

X

X

X
Tasklist Options dialog box

Displays options for adding, removing, and browsing custom fields in the Task List Manager. You can also edit the table structure and clean up the Task List table. The Tasklist Options dialog box appears when you right-click the Task List Manager and click Options.
  • New button Creates a new table and displays the Table Designer so you can add new custom fields and their data types. Do not modify the initial UniqueID field in the table definition.

    Note:
    The Fields tab in the Task Properties dialog box treats all custom fields as Character type and does not perform any type validation.

  • Edit Structure button Makes it possible for you to edit the structure of the user-defined columns table.

  • Clear button Removes the custom fields table association from the Task List. The table and its contents are left untouched so that they can be restored later if necessary.

  • Browse button Makes it possible for you to select an existing custom fields table so you can set up an association to the main FoxTask.dbf table.

    Note:
    When a custom fields table has been created, it cannot be altered directly from the Task List Manager. You must do this manually in Visual FoxPro using the Table Designer.

  • Clean Up FoxTask Cleans and packs the underlying Task List table.

See Also

Other Resources

Windows
How to: Use the Task List Manager
_TASKLIST System Variable
_FoxTask System Variable
How to: Create Bookmarks and Task List Shortcuts


Task Pane Manager

Visual FoxPro 9.0
Task Pane Manager
See Also

The Task Pane Manager displays links to useful information and dialog boxes for performing essential tasks. Individual panes can contain static or dynamic information, gather content from the Internet, expose wizards to accomplish routine tasks, display Help, and present samples. Users can create customized panes that can be shared with other users.

You can access the Task Pane Manager from the Tools menu in the main Visual FoxPro screen.

Start

Contains sections that display information on Visual FoxPro, list user-selected tools, and list recently opened projects and databases.
Community

Contains information on the Visual FoxPro community. This pane is created using dynamic Internet-based content.
Environment Manager

Specify Visual FoxPro environment settings, and associate them with individual projects. For more information, see Environment Manager Task Pane.
Solution Samples

Displays solution samples created in Visual FoxPro. Additional solution samples can be installed by using the Install Sample option.
XML Web Services

Aids users in using, publishing, and managing XML Web services. Also includes links to useful resources on XML Web services.
Filer

Specify search criteria to locate files.
Data Explorer

View and work with remote data sources such as SQL Server databases. For more information, see Data Explorer Task Pane.
Minesweeper

Take a quick break from work.
Refresh

Reloads the content for the pane that is currently displayed. If this content contains dynamic Internet-based information, the content is downloaded as specified in the Task Pane Options dialog box.
Options

Displays the Task Pane Options dialog box where you can set options for the Task Pane or for individual panes.

See Also

Other Resources

User Interface Reference
_TASKPANE System Variable
Pane Customization Dialog Box
Task Pane Options Dialog Box


Data Explorer Task Pane

Visual FoxPro 9.0
Data Explorer Task Pane
See Also

The Data Explorer Task Pane is used to open data connections and to log on to servers and explore their databases. You can right-click on nodes to perform various actions against the data elements represented by those nodes. You can drag nodes from Data Explorer and drop them onto Visual FoxPro designers and editors. This creates new data controls on forms or code that is preconfigured to reference the item dropped.

To access the Data Explorer Task Pane, select Task Pane on the Tools menu to bring up the Task Pane Manager. Choose the Data Explorer Task Pane from the Task Panes drop-down list box at the top.

The Data Explorer is also a stand-alone application and can be run outside of the Task Pane manager. To run the Data Explorer as a separate application, execute the following command from the Command window.

Copy Code
DO HOME() + DATAEXPLORER.APP
Note:
The Data Explorer stores your connections and settings in a table named DataExplorer.dbf, which is stored in your user data directory (see HOME(7)).

Using the Data Explorer

The Data Explorer is very easy to use. It has a simple interface that makes viewing and working with remote data easy. The basic operation of the Data Explorer is as follows:

  • You create a connection to your remote data such as a SQL Server database. This is done using the Add Connection button.

  • The connection appears as a node under the Connections root node and is persisted for future use.

  • You can expand nodes and view all the components of your data connection. When you select a node, detailed information about that node is shown in the description pane at the bottom.

  • You can right-click on individual nodes to perform actions such as browsing a table, examining a view definition or editing a stored procedure.

  • You can drag-and-drop nodes to Visual FoxPro editors and have code added for that specific node. You can also drag-and-drop to a form designer and have an appropriate control dropped to represent the node.

Use the Data Explorer to perform different actions with your remote data. The following is a list of some of the more common actions:

Add a new connection

Add a new connection to your remote data source by clicking Add Connection or by right-clicking the Connections root node and selecting the Add Connection… menu item. When the Add Connection dialog box appears, select a connection type. After choosing a connection type, you will be asked for more details about your data source. If you select a SQL or ADO Connection type, you will be prompted with a Connection Properties dialog box.
Access an existing SQL Server

The SQL Servers root node is a convenient way for you to explore and access SQL Servers available from your network. Simply click on the root node to expand and view all available servers.
Note:
It is often more convenient to create a separate connection for a specific SQL Server database than to access it from the SQL Servers root node. A separate connection will also provide quicker access.

Modify an existing connection

Once the connection is added to the Data Explorer, it is persisted so that it is available the next time you launch Visual FoxPro. You can make modifications to the connection by right-clicking the connection node and selecting the Properties menu item.
Work with Databases

If you select a SQL Server connection type, the nodes beneath the connection will be databases. With databases, you can expand the node to see various items including tables, views, stored procedures and functions. If using a SQL or ADO connection, you can drag and drop a database node to a program and code will be inserted that handles the connection and sets up a CursorAdapter object to retrieve data.
Work with Tables

You can expand the Tables node to see a list of all the tables in your data source. Information about that table, such as the owner or location, is displayed in the description pane. You can further expand a table node to view its fields. To view the data, you can right-click the desired table node and select the Browse menu. To run a more advanced query, select the Run Query menu. If you are working with a Fox table, you can right-click and select Design to open the Table Designer.
Note:
Through the extensibility architecture, you can add design support for remote data sources such as SQL Server.

When you drag and drop a table to a form or class designer, a Grid control for that table is added.
Note:
You will still need to add code or data environment objects to connect to the remote data source.

When you drag and drop a table to an edit window, code is inserted to view that table:
  • If you drag from a Fox table, a simple SELECT statement is inserted.

  • If you drag from a SQL or ADO connection, code is also inserted that handles the connection and sets up a CursorAdapter object to retrieve data.

Work with Views

You can expand the Views node to see a list of all views in your data source. Information about that view, such as the owner, is displayed in the description pane. You can further expand a view node to see its fields. To view the data, you can right-click the desired node and select the Browse menu. To run a more advanced query, select the Run Query menu. To see the definition of that view, select the View Definition menu.
Note:
Certain connection types, such as an ADO connection to SQL Server, may not display this option.

If you are working with a Fox view, you can right-click and select Design to open the View Designer.
Note:
Through the extensibility architecture, you can add design support for remote data sources such as SQL Server.

When you drag and drop a view to a form or class designer, a Grid control for that view is added.
Note:
You will still need to add code or data environment objects to connect to the remote data source.

When you drag and drop a view to an edit window, code is inserted to browse that view:
  • If you drag from a Fox view, a simple SELECT statement is inserted.

  • If you drag from a SQL or ADO connection, code is also inserted that handles the connection and sets up a CursorAdapter object to retrieve data.

Work with Fields

You can expand a Table or View node to see a list of its fields. Information about that field, such as the data type, is displayed in the description pane. If Column Info is checked for that connection, the data type is displayed in the field node.
Note:
Certain connection types may not support displaying field detail.

To run a query, select the Run Query menu. When you drag and drop a field to a form or class designer, a Textbox control for that field is added.
Note:
You will still need to add code or data environment objects to connect to the remote data source.

When you drag and drop a field to an edit window, code is inserted to browse that field:
  • If you drag from a Fox field, a simple SELECT statement is inserted.

  • If you drag from a SQL or ADO connection, code is also inserted that handles the connection and sets up a CursorAdapter object to retrieve data.

Working with Stored Procedures

You can expand the Stored Procedures node to see a list of all stored procedures in your data source. Information about the stored procedure, such as the owner, is displayed in the description pane. You can further expand an individual stored procedure node to see its parameters.
Note:
Certain connection types, may not support this option.

To execute the stored procedure, you can right-click that node and select the Run Stored Procedure menu. If the stored procedure requires parameters, a dialog box prompts you to enter parameters. The results are displayed in the Run Query window where you can modify and execute your procedure again. To execute your procedure with more control over the calling syntax, select the Run Query menu. To see the definition of the procedure, select the View Definition menu. To edit a procedure, select the Edit Procedure menu. To delete a procedure, select the Delete Procedure menu. To add a new procedure, select the New Procedure menu. You can drag and drop a SQL or ADO connection stored procedure to an edit window. When you do this, code is inserted that handles the connection and calls the procedure. For SQL connection procedures, code is also included to set up a CursorAdapter object to retrieve data from the stored procedure.
Work with Functions

You can expand the Functions node to see a list of all functions in your data source. Information about the function, such as the owner, is displayed in the description pane. You can further expand an individual function node to see its parameters.
Note:
Certain connection types, such as a Fox connection, may not support this option.

To call the function, you can right-click the desired node and select the Run Stored Procedure menu. If the stored procedure requires parameters, a dialog box prompts you to enter parameters. The results are displayed in the Run Query window where you can modify and execute your procedure again. To execute your function with more control over the calling syntax, select the Run Query menu. To see the definition of the function, select the View Definition menu. To edit a procedure, select the Edit Function menu. To delete a procedure, select the Delete Function menu. To add a new procedure, select the New Function menu. You can drag and drop a SQL or ADO connection function to an edit window. When you do this, code is inserted that handles the connection and calls the function.
Use the Run Query Window

When you select the Run Query menu item, the Run Query window displays and contains commands of relevance to the selected node. For example, if you open the Run Query window for a table, the edit box contains a SELECT statement for that table. If you choose a stored procedure, an EXEC statement (applicable to SQL) will be shown. With the Run Query window, you can type in a query, run it to see the results and perform additional add-in tasks such as copying the results to the clipboard. To run a query, enter in a query command such as SELECT or EXEC statement and click the Run button. The results will be displayed in the lower portion of the window.
Set a Filter

You can select the Filter menu to set a filter to display only child nodes that match or do not match the specified criteria. For example, you may want to filter for all tables that begin with "sys" to exclude system tables.
Refresh Data Nodes

If you right-click a node, you can select the Refresh menu to have all child nodes refreshed.

Add Connection Dialog Box

The Add Connection button brings up the Add Connection dialog box so that you can create a new persisted connection. You can choose from SQL Server, Visual FoxPro or ADO data sources. The following types are available in this dialog box:

Connection Type Description

SQL Server

A connection to a SQL Server. The connection node will display separate nodes for each database in that server.

SQL Database

A connection to a SQL Server database.

FoxPro Directory

A connection to a directory. The connection node displays separate nodes for each Visual FoxPro database (.dbc).

FoxPro Database

A connection to a Visual FoxPro database.

FoxPro Table

A connection to a Visual FoxPro table.

ADO Connection

A connection to an ADO data source.

Note:
If you are creating ADO Connections to SQL Server, it is recommended that you instead use one of the SQL Server connection types since there is more functionality available, such as additional shortcut menu items.

SQL Connection Properties Dialog Box

The SQL Connection Properties dialog box is used to specify connection information to a SQL Server database. This dialog box appears when you first create a SQL connection for either the SQL Server or SQL Database connection type. You can bring this dialog box up later and make changes once the connection is created by right-clicking the specific connection node and selecting the Properties menu item.

Server Name

You can type the SQL Server name in the combo box directly or select one from the drop-down list box. The drop-down list box contains the same list of servers that appear under the SQL Servers node.
Database

Once you have chosen a SQL Server, you can pick a database for your connection. This option is only available for a SQL Database connection.
Note:
You may be prompted to enter a Login/Password combination if the current Trusted Connection does not permit access to the list of databases for the selected server.

Use Trusted Connection

Select this to use your Windows login credentials to connect to the SQL Server.
Login

If you uncheck Use Trusted Connection, you can specify a SQL login name to use for the connection.
Password

If you uncheck Use Trusted Connection, you can specify a SQL login password to use for the connection.
Connection Timeout

Specifies the time to wait (seconds) before returning a connection time-out error. If you specify 0, the wait is indefinite and no time-out error is returned. The value can be from 0 to 600.
Note:
This is equivalent to using SQLSETPROP(0, “ConnectTimeOut”, nTimeout) before establishing the connection.

Query Timeout

Specifies the time to wait (seconds) before returning a general time-out error. If you specify 0, the wait is indefinite and no time-out error is returned. The value can be from 0 to 600.
Note:
This is equivalent to using SQLSETPROP(nHandle, “QueryTimeOut”, nTimeout) before executing the query.

Show Column Info

Displays the column type and length next to the column name on each column node.
Sort Objects

Sort objects beneath the connection by name.

ADO Connection Properties Dialog Box

The ADO Connection Properties dialog box is used to specify connection information to an ADO data source (OLE DB Provider). This dialog box appears when you first create an ADO connection. You can open this dialog box later and make changes once the connection is created by right-clicking the specific connection node and selecting the Properties menu item.

Use DSN

Specify a connection using an existing DSN. Enter the necessary OLE DB Provider information by select an available data source from the drop-down list box and optionally entering a User ID and Password.
Use Connection String

Enter a valid connection string. The Build button is available to assist in generating the connection string. This button opens the standard Data Link Properties dialog box where you can chose a registered OLE DB Provider.
Connection Timeout

Specifies the time to wait (seconds) before returning a connection time out error. If you specify 0, the wait is indefinite and no time out error is returned. The value can be from 0 to 600.
Note:
This is equivalent to using SQLSETPROP(0, “ConnectTimeOut”, nTimeout) before establishing the connection.

Query Timeout

Specifies the time to wait (seconds) before returning a general time out error. If you specify 0, the wait is indefinite and no time out error is returned. The value can be from 0 to 600.
Note:
This is equivalent to using SQLSETPROP(nHandle, “QueryTimeOut”, nTimeout) before executing the query.

Show Column Info

Displays the column type and length next to the column name on each column node.

Run Query Window

The Run Query window is a core part of the Data Explorer. It allows you to execute queries against the selected data node. You can also execute stored procedures and functions. To run a query, perform the following steps:

  • Right-click a data node whose data you want to query and select the Run Query menu.

  • If text is in the top edit box, you can click the Run button to execute the query. If no text is displayed, enter a query such as a SELECT statement and click Run.

  • The results of your query will appear in the bottom half of the Run Query window in a grid. If the query was unsuccessful, an error will appear in the lower results pane. You can edit your query to fix the problem and click Run to requery.

  • The Run Query window also allows you to execute stored procedures and functions. If these return result sets, such as from SQL Server, they will be displayed in a grid. Otherwise, the results are stored in the results pane.

  • The Run Query window supports add-in extensibility that allows for custom actions against the query or the data results. Add-ins which are managed using the Add-In Manager (Options dialog box), appear as buttons above the query edit box and results pane. You can also access add-ins by right-clicking the query edit box.

The following add-ins are included with Visual FoxPro and can be modified using the Add-In Manager:

Add-In Description

Save Query

You can save your current query text to a text file with a .SQL extension.

This is a query add-in.

Load Query

You can load a previously saved query from a text file.

This is a query add-in.

Format for VFP

This modifies the current query to add a continuation character (;) to the end of all lines, remove any blank lines, and convert any SQL "--" comments to "&&".

In addition, all brackets surrounding words are removed. This is useful if you have a SQL statement originally written for SQL Server and want to run it against Visual FoxPro data.

For example, the following query:

SELECT [au_lname]

FROM [pubs] -- retrieve all last names

is reformatted as:

SELECT au_lname ;

FROM pubs && retrieve all last names

This is a query add-in.

Format for SQL

This modifies the current query to remove any end-of-line continuation characters (;), convert any VFP comment lines that begin with "*" to SQL comment lines beginning with "--", change double quotes to single quotes, and change double equals (==) to single equals (=).

This is useful if you are modifying a query originally written to go against VFP data to run against SQL Server data.

This is a query add-in.

Clipboard to Variable

Copy query to clipboard formatted with variable assignment.

This is a query add-in.

Clipboard to TEXT/ENDT

Copy query to clipboard formatted with TEXT ... ENDTEXT Command.

This is a query add-in.

Copy Results to Clipboard.

The data displayed in the grid is copied to the clipboard.

This is a data result add-in.

Options Dialog Box

  • The Options dialog box allows you to customize the Data Explorer and connection behaviors.

Font

Sets the default font used by the Data Explorer.
Show Description Pane

Displays a description pane at the bottom of the Data Explorer.
Show Column Info

Shows column data type info in column nodes. This is the default setting for new connections. You can change this later in the Connection Properties dialog box.
Note:
If the description pane is visible, column data type info is displayed there for the selected column.

Manage Add-Ins

Opens the Add-Ins Manager.
Manage Menus

Opens the Menu Manager.
Manage DragDrop

Opens the DragDrop Manager.
Restore to Default

Restores the Data Explorer to its default settings. A backup of the original DataExplorer.dbf table is made with the name DataExplorerBackup_xx.dbf, where xx is a sequential number so that prior backups are not overwritten.

Add-In Manager

The Run Query window lets you add new and customize existing add-ins for working with your queries as well as the query data results. These add-ins appear in the Run Query window as buttons. Add-Ins are stored in your DataExplorer.dbf settings table.

Query Add-Ins

Add-Ins that appear at the top of the Run Query window and apply to the query.
Data Results Add-Ins

Add-Ins that appear toward the bottom of the Run Query window and apply to the results that appear after the query is run.
Add-In List

List of all registered Add-Ins. When you select an add-in, its details appear in the controls to the right.
New

Creates a new add-in.
Delete

Removes an add-in.
Move Up/Move Down

Use the arrows to move a selected add-in up or down in the list order. This controls the position the add-in appears in the Run Query window.
Add-In

Specifies the full descriptive name of the add-in.
Abbreviated Name

Specifies how the add-in is displayed in the menu bar.
Select Image

Select the image to be associated with the currently selected add-in.
Script Code Editbox

Specifies the code to execute when the add-in is selected. The script must accept one parameter, which is an object containing the query text, a reference to the data management object, and a reference to the DataExplorer engine.
Modify

Brings up editor window to modify script if you want a larger edit window.

Menu Manager

The Menu Manager lets you customize shortcut menus items available for specific nodes. Menus are stored in your DataExplorer.dbf settings table.

Menu List

List of all registered menus. When you select a menu, its details appear in the controls to the right.
New

Creates a new shortcut menu item.
Copy

Creates a new shortcut menu item using definition from selected item.
Delete

Deletes a shortcut menu item.
Move Up/Move Down

Use the arrows to move a selected menu up or down in the list order. This controls the position the menu item appears in a node's shortcut menu.
Caption

Specifies the name of the custom menu as it appears on the context menu of node. Use “\-“ to create a menu separator.
Additional Info

Allows you to easily categorize menu items. This is displayed as the second column in the list of menu items.
Template

Optional template of code that can be referenced in the menu's script code. Click the Modify button to open the code in an edit window.
Display Only

This page lets you control which nodes will display the menu. The Display only… text box lets you include a comma-separated list of node names (classes) that can display the menu. You can specify an asterisk at the end of any node name to specify any nodes that begin with the text.
Code to Determine…

Code that is executed for specified node classes included in the Display Only text box that can further be used to filter whether a menu is displayed or not. This is particularly useful if you want to limit a menu to only certain Providers with ADO Connections. The code must accept a single object parameter containing information about the node. Click the Modify button to open the code in an edit window.
Script To Run

Code to execute when the menu item is selected. The code must accept a single object parameter containing information about the node. Click the Modify button to bring up the code in an edit window.

DragDrop Manager

The DragDrop Manager lets you customize the drag-and-drop behavior for specified nodes. Drag-and-drop actions are stored in your DataExplorer.dbf settings table.

DragDrop Item List

List of all registered drag-and-drop actions. When you select an item, its details appear in the controls to the right.
New

Creates a new drag-and-drop item.
Copy

Creates a new drag-and-drop item using definition from selected item.
Delete

Deletes a drag-and-drop item.
Move Up/Move Down

Use the arrows to move a selected item up or down in the list order. This controls the order in which action's code is executed.
Caption

Specifies the name of the drag-and-drop item for future reference.
Template

Optional template of code that can be referenced in the script code. Click the Modify button to open the code in an edit window.
Execute Only

Specifies a comma-separated list of node names to apply the drag-and-drop action. If this is left blank then the node check is not performed. You can include an asterisk at the end of any node name to specify any nodes that begin with the text.
Script To Run

Code to execute when you drag and drop from a node to edit window. The code must accept a single object parameter containing information about the node. If you want to specify text to insert, you need to set the parameter object’s DropText property. Click the Modify button to open the code in an edit window.

Extending the Data Explorer

The Data Explorer that ships with Visual FoxPro includes support for many core remote data needs. With the extensibility architecture, you can add additional capabilities not currently available such as the ability to modify remote tables or views through a custom designer. Additionally, you can add support for new remote data sources as they become available in the future (such as new versions of SQL Server).

The Data Explorer can be extended by adding, removing, or swapping in node classes or connection manager classes. Each of these is defined in the DataExplorer table which is located in the user data directory (see HOME(7)). If the table is not found, then it is automatically created using the DataExplorerDefault.dbf table that is bound into the DataExplorer application.

Note:
If you want to make modifications or enhancements to the Data Explorer, you can find the source in XSource.zip contained in the Tools\XSource folder.

DataExplorer.dbf

Much of the Data Explorer extensibility is handled through this table so that you do not need to make modifications to the DataExplorer.app file. All of the customizations that are set by the various managers in the Options dialog box stored in this table. The following table contains details on extending the Data Explorer settings table:

Fieldname Type Description

UniqueID

C(25)

A unique ID for the record created. This should be in the format of: vendor.id

For example: microsoft.textscraps

DefType

C(1)

The record definition:

  • R = Root

  • S = Data Source

  • C = Connection

  • M = Menu

  • P = Picture

  • T = Template

  • Q = Query Add-in

  • Z = Data Add-in

  • E = Expanded Info

  • Y = Drop Action, Code Window

  • V = Drop Action, Design Surface

ConnType

C(25)

Connection type for a user created connection.

ConnName

C(100)

Name of the connection.

ConnInfo

M

Connection info.

ClassName

M

Name of class.

ClassLib

M

Name and location of class library.

ScriptCode

M

Script code to run.

DisplayOrd

I

Display order.

Options

M

Optional data for specific DefType record.

OptionData

M

Contains node settings that can be customized by the user. This applies to Connection and Root nodes. For connections, connection properties are stored in this field.

Template

M

Can be used by add-ins.

WhenNodes

M

Comma-delimited list of nodes that a menu add-in applies to.

WhenCode

M

Script code to execute when determining if a menu add-in should be displayed.

AddinImage

W

Image to display for add-in.

Inactive

L

If set to TRUE (.T.), then record is ignored.

User

M

User-defined.

Modified

T

Last modified.

The following table contains details about the different DefType field values in the Data Explorer table:

DefType Value Description

R

Root. Contains detail about root node. Data Connections and SQL Servers are the pre-defined root nodes.

S

Data Source. Specifies a valid connection type that can be made. The following columns are utilized:

  • ConnName - friendly name of the data source such as "SQL Server."

  • ClassName - name of class that is responsible for representing the node. This class should derive from IConnectionNode of TreeNodes.prg.

  • ClassLib - name and location of the class library where ClassName can be found.

C

Connection. Contains a user created connection.

M

Menu. Specifies a right-click menu option that is available for a node.

  • ConnName - name of the menu option as it appears on the right-click menu.

  • ScriptCode - code to run when this menu option is selected.

  • WhenNodes - comma-delimited list of nodes the menu add-in applies to.

  • WhenCode - code to execute to determine if menu should be displayed (only called if passes the WhenNodes test).

  • Template - additional information that can be used by the menu item.

  • DisplayOrd - relative order menu item should be displayed on the shortcut menu.

If the first word of ScriptCode is 'THIS.', then the DataExplorer assumes it is a method of the data management class and will run only if it finds the specified method name to be a member of that object.

If the DataExplorer finds a method called <MethodName>Okay(), then the DataExplorer calls this method first to determine if the menu option should be visible or not (and returns TRUE if it should be included).

If the first word of ScriptCode is not ‘THIS.’ then the run the code is executed normally.

P

Picture. Contains image used to represent a certain node.

ConnInfo - relative location of picture, such as "bitmaps\column.bmp."

T

Template (reserved for future).

Q

Query Add-In. This is a Run Query window query add-in that appears as a button towards top of window or from the shortcut menu. The following fields are used.

  • ConnName - name of the menu option as it appears on the right-click menu and in the add-in bar.

  • ConnInfo - descriptive name of the add-in as it appears in a tooltip.

  • ScriptCode - code to run when this menu option is selected.

  • DisplayOrd - relative order add-in should be displayed on the menu.

Z

Data Add-In. This is a Run Query window data add-in that appears as a button towards bottom of window. See Query Add-In above for more detail on fields used.

E

Expanded Info (reserved for future). Stores which nodes are expanded when the Data Explorer is closed so that these same nodes can be expanded when restarted. This information is stored in the OptionData column.

Y

DragDrop Action for Code Window.

  • ConnName - name of the DragDrop action as it appears in the DragDrop Manager.

  • ScriptCode - code to run for DragDrop action.

  • WhenNodes - comma-delimited list of nodes the DragDrop action applies to.

  • Template - additional information that can be used by the DragDrop action.

  • DisplayOrd - relative order the DragDrop action is executed.

V

DragDrop Action for Design Surface. See previous item for details.
Customizing ADO Connections

The Data Explorer contains support for generic ADO connection handling. However, you may want to customize for a specific connection type. In fact, the Data Explorer contains an example of this using Oracle. Here are steps you need to do to add this type of customization:
  • Create a new class based on the core ADO Data Management class. Here is an example of the Oracle one in Datamgmt_Oracle.prg:

    Copy Code
    DEFINE CLASS OracleDatabaseMgmt AS ADODatabaseMgmt OF DataMgmt_ADO.prg
    In this class, you can specify behaviors such as how to populate nodes or right-click menu functionality.

    You can rebuild the DataExplorer.app with your new class or just leave it external.

  • You need to reference this class in your DataExplorer.dbf so it can be used. To do this:

    • Open the DataExplorer.dbf table from your HOME(7) location and locate the ADO Connection record (Deftype="S").

    • Open the ScriptCode memo field

    • Add another CASE statement to existing code (below) for your specific provider along with the custom class information.

      Copy Code
      LPARAMETERS oParam, oConn
IF TYPE("oConn") == 'O' AND !ISNULL(oConn)
      DO CASE
      CASE ATC("ORACLE", oConn.DBMSName) > 0

      oParam.DataMgmtClass = "OracleDatabaseMgmt"

      oParam.DataMgmtClassLibrary = "DataMgmt_Oracle.prg"
            oParam.ProviderName = "ORACLE"

      CASE ATC("SQL Server", oConn.DBMSName) > 0
            oParam.ProviderName = "SQLSERVER"

      CASE ATC("FOXPRO", oConn.DBMSName) > 0
            oParam.ProviderName = "FOXPRO"

      ENDCASE
ENDIF
  • To add custom right-click menu and drag-and-drop functionality, use the specific managers available from the Options dialog box. For hints, take a look at the existing items in the various managers.

See Also

Reference

Task Pane Manager


Environment Manager Task Pane

Visual FoxPro 9.0
Environment Manager Task Pane
See Also

The Environment Manager is a tool you can use to manage and organize environment settings for reusable development needs such as at a specific client or project level. For example, you might have multiple projects for a specific client that all use the same form template (e.g., one with the client's logo) and environment settings (e.g., data paths). The Environment Manager lets you create environment sets which are packages of settings you can apply at any time. These settings include SET commands, Form and Formset templates, and Field class mappings.

To access the Environment Manager Task Pane, select Task Pane from the Tools menu to bring up the Task Pane Manager. Choose the Environment Manager Task Pane from the Task Panes drop-down list box at the top.

The Environment Manager Task Pane itself is simply a shell with a link that opens the actual Environment Manager tool. To open the tool, simply click on the Manage Environment link. This Task Pane also lists available Environment Sets and their associated projects. When you select a project, the Environment Set will be applied before the project opens.

The Environment Manager tool is also a stand-alone application and can be run outside of the Task Pane Manager. To run the Environment Manager as a separate application, execute the following command from the Command window.

Copy Code
DO HOME() + ENVMGR.APP
Note:
The Environment Manager stores its Environment Sets in a table named Envmgr.dbf, which is stored in your user data directory (see HOME(7)).

Working with Environment Sets

You can manage and apply your Environment Sets as follows:

Environment Set List

Lists all the Environment Sets available for use. When you launch the Environment Manager, your current settings are displayed in a reserved set named <current>. This is used when you click New to create a new set. The <default field mapping> set is another reserved set that is used to store your original Field Mapping settings stored in the Options dialog box. If you have applied an Environment Set with custom mappings, you can later reset to your defaults by selecting this reserved set and clicking the Set button.
New

Creates a new Environment Set. Once your new set appears in the list, you should rename it.
Copy

Creates a new Environment Set based on the one selected in the Environment Set List.
Remove

Deletes the selected Environment Set.
Set

Applies the settings defined in your Environment Set to current Visual FoxPro environment.
Name

Lets you specify a friendly name for your Environment Set.

Default Directory/Path

The Default Directory/Path page lets you specify settings for your Environment Set that relate to file locations.

Default Directory

Specifies the default directory to use when the Environment Set is applied. This is equivalent to using the CD | CHDIR Command.
Path

Specifies a list of search paths to use when the Environment Set is set. This is equivalent to using the SET PATH Command.
Directory

Lets you change the path selected in the Path list.
Add Path

Adds a new path to the Path list.
Copy

Adds a new path to the Path list based on the selected one.
Remove

Removes the selected path from the Path list.

Environment Settings

The Default Directory/Path page lets you specify settings for your Environment Set that relate to file locations.

Setting table

Lets you specify values for common SET commands you want applied when the Environment Set is set.
Tip:
You can add additional items that appear in this table by editing Envmgr.dbf, which is stored in your user data directory (see HOME(7)).

Resource file

Specifies the resource file to use when the Environment Set is set. This is equivalent to using the SET RESOURCE Command.
Run script before environment is set

A script of Visual FoxPro commands that is executed prior to the settings in Environment Set being applied.
Run script after environment is set and project is loaded

A script of Visual FoxPro commands that is executed after the Environment Set is applied.

Field Mapping

The Field Mapping page lets you specify settings for your Environment Set that relate to control classes used for mapping fields when you drag and drop a field from the Data Environment or Database Designer to a form or container. For more information, see Field Mapping Tab, Options Dialog Box and How to: Create Controls by Dragging and Dropping Fields or Tables. You can restore your original Field Mapping settings by selecting <default field mapping> and clicking the Set button.

Forms

The Forms page lets you specify settings for your Environment Set that relate to form and formset templates that are used when creating a new form or formset. For more information, see Forms Tab, Options Dialog Box.

Associated Projects

The Associated Projects page lets you specify projects in which the Environment Set is applied when the project is opened from the Environment Manager Task Pane. The Task Pane lists all of your custom Environment Sets along with their associated projects.

Projects table

Lists projects associated with the selected Environment Set.
Add

Adds a project to the set.
Remove

Removes a project from the set.

See Also

Reference

Task Pane Manager
SET Command Overview


Toolbox (Visual FoxPro)

Visual FoxPro 9.0
Toolbox (Visual FoxPro)
See Also

The Toolbox displays items used in the creation of applications, the items are displayed in toolsets (collections of tools) by category. The toolsets can be common resources such as native Visual FoxPro classes that can be placed onto a workspace. Additionally, the Toolbox supports items that are builders or wizards, ActiveX controls or classes, COM+ controls or classes, and text scraps. Furthermore, the Toolbox can hold file-based resources such as tables, images, reports, labels, and forms.

The individual tool sets can be fully customized. In addition, users can add new tool sets containing their own selection of items.

You can open the Toolbox by clicking Toolbox on the Tools menu or by clicking the Toolbox button on the Visual FoxPro standard toolbar. You can then drag and drop items from the Toolbox to your workspace or click them to perform other actions.

In Visual FoxPro 9.0, you can dock the Toolbox by double-clicking the Toolbox title bar. Right-click the title bar to display a shortcut menu that lets you turn docking on or off, or hide the Toolbox.

Favorites

A toolset for storing items that are used often. Items from other categories can be moved to this one for easy access.
Text Scraps

A toolset containing text scraps. New text scraps can be added by selecting text and dragging it onto this category.
VFP Base Classes

A toolset containing native Visual FoxPro classes.
VFP Foundation Classes

A toolset containing some of the most popular Visual FoxPro foundation classes.
My Base Classes

A toolset containing the FoxPro Foundation base classes from FFC\_BASE.VCX class library.
My XML Web Services

A tool set containing registered XML Web services.
My ActiveX Controls

A toolset containing registered ActiveX controls.

See Also

Other Resources

User Interface Reference
_TOOLBOX System Variable
How to: Customize the Toolbox
Customize Toolbox Dialog Box


Trace Window

Visual FoxPro 9.0
Trace Window
See Also

Makes it possible for you to see your lines of code as they are being executed.

This window is activated when you choose Trace from the Window Menu, Debugger Window.

Object

Available when running object code. The code in the Trace window is associated with the object displayed in the Object list. The Object list contains all objects contained in the highest-level parent container of the object whose code is currently executing.
Procedure

Available when running object code. The code in the Trace window is associated with the method or event displayed in the Procedure list. The Procedure list contains all methods of the object in the Object list that have code associated with them.

The left area of the Trace window can contain the following symbols.

Symbol | Description
FoxProBlueArrowRight screenshot | Currently executing line of code.
FoxProTraceFilled screenshot | Active breakpoint.
FoxProTraceEmpty screenshot | Inactive breakpoint.
FoxProTrace screenshot | Call stack position if you are examining code at a different level than the currently executing code.

See Also

Other Resources

Dialog Boxes
Debugger Window
Debugger Keyboard Shortcuts and Menus
Locals Window
Watch Window
Call Stack Window
Debug Output Window


Visual FoxPro IntelliSense Manager Window

Visual FoxPro 9.0
Visual FoxPro IntelliSense Manager Window
See Also

The IntelliSense Manager makes it possible for you to perform IntelliSense management tasks:

  • General Tab Set options that affect the appearance and functionality of IntelliSense, such as feature availability levels and letter casing for syntax completion.

  • Types Tab Manage items that appear in the AS clause list box for certain Visual FoxPro language elements when implementing strong typing.

  • Custom Tab Edit records in the IntelliSense table.

  • Advanced Tab Edit custom IntelliSense properties that affect its functionality. Perform maintenance for records in the IntelliSense table and other IntelliSense functionality.

The IntelliSense Manager application is specified by the _CODESENSE system variable. For more information, see _CODESENSE System Variable.

The IntelliSense table, which is stored in the FoxCode.dbf file, contains records that provide data for the IntelliSense Manager. For more information, see Customizing IntelliSense in Visual FoxPro and _FOXCODE System Variable.

General Tab

Controls availability levels and letter casing formatting options for IntelliSense functionality.

Enable IntelliSense

Activates or disables IntelliSense in Visual FoxPro. For more information, see How to: Activate or Disable IntelliSense.
List members

Specifies the level of availability for List Members functionality. The following levels are available:
  • Automatic Displays List Members list boxes automatically at the current cursor position when you press the appropriate activator key.

  • Manual Displays List Members list boxes when you select List Members from the Edit menu or press CTRL+J.

  • Disabled Does not display List Members list boxes.

For more information, see How to: Set IntelliSense Options and IntelliSense Syntax Completion.
Quick info tips

Specifies the level of availability for Quick Info functionality. The following levels are available:
  • Automatic Displays Quick Info list boxes automatically at the current cursor position when you press the appropriate activator key.

  • Manual Displays Quick Info list boxes when you select List Members from the Edit menu or press CTRL+I.

  • Disabled Does not display Quick Info list boxes.

For more information, see How to: Set IntelliSense Options and IntelliSense Syntax Completion.
Browse

Opens a browse window for the IntelliSense table. For more information, see Customizing IntelliSense in Visual FoxPro and _FOXCODE System Variable.
Tips

Opens a window that displays syntax information when you type enough characters to disambiguate a Visual FoxPro command. Use this for commands and functions that have many clauses or parameters. The Tips window displays only Visual FoxPro command and function information contained in the IntelliSense table. Class and object IntelliSense is not displayed.

Capitalization/Expansion

This section provides the capability to control how IntelliSense formats letter casing for native Visual FoxPro programming syntax when performing syntax completion or expansion. You can also disable expansion or use the letter casing set in the IntelliSense table.

Functions

Lists IntelliSense letter casing settings for Visual FoxPro functions. The default setting is UPPERCASE.
Commands

Lists IntelliSense letter casing settings for Visual FoxPro commands. The default setting is UPPERCASE.
FoxCode default

Lists letter casing settings for items in the IntelliSense table. This setting serves as a global default setting that items in the IntelliSense table can use if they do not have their own letter casing setting. This setting is stored in the first Version item record in the IntelliSense table. For more information, see IntelliSense Table Structure.
Apply changes to Visual FoxPro language only

Specifies whether to make changes to all or only Visual FoxPro native commands and functions. This setting is stored in the Source field for affected items in the IntelliSense table. For more information, see IntelliSense Table Structure.

Types Tab

Controls the display of available data type and other items when implementing strong typing, for example, when declaring LOCAL myVar AS using the LOCAL command. Types can be core intrinsic elements such as strings, numbers, and Visual FoxPro and COM classes. For more information, see How to: Implement Strong Typing for Class, Object, and Variable Code.

Types

Lists items and data types that can appear in the AS clause list box for certain Visual FoxPro commands. An asterisk in the third column indicates that the Data field for that item contains script code in the IntelliSense table. To hide an item from the list, clear the check box next to the item.
Tip:
To sort by column, click the column header.

Edit

Displays the selected item from the Types list in a browse window so you can edit its record in the IntelliSense table.
Type Libraries

Searches your Windows registry for available COM Server and ActiveX Control type libraries. You can select type libraries that appear in the Type Library References dialog box to add them to the list of items available for strong typing.
Classes

Opens the Open dialog box so you can select a Visual FoxPro class that you want to add to the list of items available for strong typing.
Web Services

Opens the Visual FoxPro XML Web Services Registration dialog box so you can add a Web service to the list of items available for strong typing. For details, see Visual FoxPro XML Web Services Registration Dialog Box.

Custom Tab

Makes it possible for you to add or modify records for user-defined IntelliSense items in the IntelliSense table. However, you can view all the other IntelliSense items by opening the table directly. For more information, see Customizing IntelliSense in Visual FoxPro.

Note:
An asterisk in the third column indicates that the Data field in the record for that IntelliSense item contains script code in the IntelliSense table.

Replace

Specifies the characters that activate syntax expansion using the characters in the With box.
With

Specifies the characters to insert when you type the characters in the Replace box.
Type

Lists types you can select for the IntelliSense item.
Script

Opens an edit window for adding or editing script code for the IntelliSense item. The script code appears in the Data field in the record for that item.
Edit

Displays the entire record for editing the IntelliSense item.
Add

Adds a new IntelliSense item with the specified Replace and With text to the IntelliSense table.
Note:
The Add button becomes available when you initially select a type other than Command. The Add button changes to Replace if you are modifying an existing IntelliSense item.

Delete

Deletes the selected item.

Advanced Tab

Makes it possible for you to edit custom IntelliSense properties that affect IntelliSense functionality and perform IntelliSense maintenance tasks.

Edit Properties

Displays custom IntelliSense properties in the Custom Properties dialog box so you can specify or edit values for advanced IntelliSense functionality. Closing the Custom Properties dialog box saves your changes.
  • Property Lists custom IntelliSense properties.

  • Description Displays a description of the custom IntelliSense property.

  • Value Displays the value for the custom IntelliSense property.

The following table describes custom IntelliSense properties.

Property Description Default value

lEnableFullSetDisplay

Controls whether to add the second word, for example, TO, automatically in certain SET commands.

T

lHideScriptErrors

Suppresses screen output of IntelliSense script errors.

F

lKeywordCapitalization

Enables capitalization and expansion of command keywords.

T

lPropertyValueEditors

Enables scripts that trigger value editors for certain properties.

T

lExpandCOperators

Enables auto expansion of C type operators, such as ++, --, +=, -+, *=, and /=.

T

lAllowCustomDefScripts

Enables scripts to be included into the default script handler.

T

lEnableMultiWordCmdExp

Controls whether to expand commands with multiple words.

T

lDebugScribts

Allows debugging for IntelliSense scripts.

F
Clean Up

Opens the Maintenance dialog box so you can perform IntelliSense maintenance tasks.
  • Restore Foxcode Restore the default IntelliSense table for native Visual FoxPro language elements. User-defined items remain unless you delete them manually on the Custom tab of the IntelliSense Manager.

  • Clean Up FoxCode Removes records marked for deletion in the IntelliSense table.

  • Clean Up Lists Remove files that no longer exist from most recently used (MRU) lists.

  • Zap Lists Remove all files from most recently used (MRU) lists.

See Also

Other Resources

Windows
IntelliSense Overview


Visual FoxPro System Windows

Visual FoxPro 9.0
Visual FoxPro System Windows
See Also

Visual FoxPro System windows are windows provided by Visual FoxPro as part of the product interface. The following table provides details that enable you to access and control these windows.

Window | Code access | Default Docking status
Command | ACTIVATE WINDOW Command | Dockable, undocked
Data Session | SET VIEW ON, ACTIVATE WINDOW VIEW | Dockable, undocked
Document View | ACTIVATE WINDOW Document | Dockable, undocked
Properties | ACTIVATE WINDOW Properties | Dockable, undocked
Debugger | DEBUG ACTIVATE WINDOW Debug[ger] | Undockable
Call Stack | (see note) | in Debugger, Dockable
Debug Output | (see note) | in Debugger, Dockable
Locals | (see note) | in Debugger, Dockable
Trace | (see note) | in Debugger, Dockable
Watch | (see note) | in Debugger, Dockable
Note:
Individual Debugger windows are dockable only when the Debugger is enabled in the FoxPro Frame. You cannot open the Debugger sub windows, alone, in code unless you first set the Debugger to use the Visual FoxPro Frame. For example, normally if you use ACTIVATE WINDOW "call stack" the entire Debugger opens with the Call Stack window highlighted. If you first set the Debugger to the Visual FoxPro Frame, ACTIVATE WINDOW "call stack" opens the Call Stack window.

See Also

Other Resources

Windows
Debug Tab, Options Dialog Box


Watch Window (Visual FoxPro)

Visual FoxPro 9.0
Watch Window (Visual FoxPro)
See Also

Makes it possible for you to display expressions and their current values, and set breakpoints on an expression. This window is activated when you choose Watch from the Window Menu, Debugger Window. Visual FoxPro enables IntelliSense in the Watch window but limits support to only List Members.

In Visual FoxPro 9.0, the Find and Find Again menu items are available to search for items in the Name column of the Watch window.

Watch

The value or expression you want to examine. Type expressions here to add them to the grid of active watch expressions below.
Name

Displays the names of the current watch expressions.
Value

Displays the values of the current watch expressions.
Type

Displays characters that represent the data types of the current watch expressions.

You can select expressions, delete them, or add breakpoints to them.

To create a new watch expression

  1. Select text in any Visual FoxPro window and drag it to the Watch window.
To edit a watch expression

  1. Double-click the watch expression.

See Also

Other Resources

Windows
Debugger Window
Debugger Keyboard Shortcuts and Menus
Call Stack Window


Error Messages

Visual FoxPro 9.0
Error Messages

This topic contains information about some of the more common error messages in Visual FoxPro.

In This Section

Error Messages A-Z

Contains a list of error message topics in alphabetical order.
Error Messages by Number

Contains a numeric list of error messages.

Related Sections

Reference

Includes topics on productivity tools, as well as the controls, objects, properties, methods, events, statements, functions, and constants available.
General Reference

Provides Visual FoxPro related technical information, including file types, file structures, and other reference information about Visual FoxPro elements.
Language Reference

Provides a list of language reference topics in alphabetical order.
User Interface Reference

Explains the options that appear on various dialog boxes, windows, and other user interfaces. These types of topics generally appear when you press F1 in a dialog box or window.


Error Messages Listed Alphabetically

Visual FoxPro 9.0
Error Messages Listed Alphabetically
See Also

Use the Expand and Collapse buttons to locate a specific error message.

<name value>

1815 | "cursor" must be created with SELECT ... INTO TABLE.
1832 | "field | variable" is not unique and must be qualified.
1130 | 'field' phrase is not found.
1165 | "field" is not related to the current work area.
1196 | "file" is not a Visual FoxPro .EXE file.
1309 | "file" is not an object file.
1298 | "name" band is too large to fit on page.
1929 | "name" can only be used within a method.
1932 | "name" cannot be closed while suspended.
1794 | "name" cannot be enumerated.
1462 | "name" internal consistency error.
1737 | "name" is a method, event, or object.
1740 | "name" is a read-only property.
226 | "name" is not a file variable.
1992 | "name" is not a function, procedure or program.
225 | "name" is not a variable.
1294 | "name" is not a valid resource file.
1745 | "name" is not a Visual FoxPro event.
232 | "name" is not an array.
1924 | "name" is not an object.
1983 | "name" objects cannot return a value.
1429 | "OLE error".
78 | ** or ^ domain error.
*** | *bad date*
*** | *Interrupted*
1550 | .DBC internal consistency error.
115 | .DIF file header is invalid.
117 | .DIF type indicator is invalid.
116 | .DIF vector is invalid - .DBF field mismatch.
120 | .SYLK file dimension bounds are invalid.
121 | .SYLK file format is invalid.
119 | .SYLK file header is invalid.

A

1727 | A .DBF-style Help file is required.
1771 | A member object with this name already exists.
2024 | A sharing violation occurred.
1538 | A stored procedure is executing.
1961 | A subdirectory or file "name" already exists.
1889 | A table in multiple relationships can only have one child order.
1640 | Access to system Registry denied
2081 | ADODB.Command is already opened.
2080 | ADODB.Recordset is already opened.
2143 | ADODB.Recordset is not opened.
13 | Alias is not found.
24 | Alias name is already in use.
103 | Allowed DO nesting level exceeded.
1870 | ALTER TABLE operation interrupted.
2032 | Ambiguous date/datetime constant.
1211 | An IF | ELSE | ENDIF statement is missing.
1781 | An object's control source cannot be set to its Value property.
2028 | API call caused an exception.
1098 | API function _UserError( ) was called.
1726 | API library is not found.
1711 | API library revision mismatch. Rebuild library.
1178 | Application file "file" is not closed.
1936 | Application object not initialized.
1972 | Array "name" is in use.
230 | Array dimensions are invalid.
1764 | Array is not a member of the parent object.
1974 | Arrays cannot be assigned to array elements.

B

1542 | Base table fields have been changed and no longer match view fields. View field properties cannot be set.
1590 | BEGIN TRANSACTION command failed. Nesting level is too deep.
38 | Beginning of file encountered.
2140 | Both Unicode and IsBinary properties can not be set to .T..
227 | Box dimensions are invalid.
1164 | Browse structure has changed.
1163 | Browse table is closed.

C

2147 | Calling OpenTables or CloseTables is not allowed while either of those methods are in the process of executing.
1651 | CANCEL or SUSPEND is not allowed.
62 | Cannot access characters beyond string.
1106 | Cannot access file "file"; transaction is in progress.
1152 | Cannot access the selected table.
1421 | Cannot activate the OLE server.
1741 | Cannot add "name". Class definition is cyclical.
1755 | Cannot add an object to this class.
1769 | Cannot add this object to a Column.
1768 | Cannot add this object to a Grid.
1537 | Cannot add this table: it belongs to database "name".
*** | Cannot allocate screen map
1672 | Cannot append from password protected file.
1795 | Cannot arrange an untransported form.
2070 | Cannot assign a class value to this member.
1952 | Cannot base a view on itself.
2002 | Cannot build a DLL without OLE public classes.
1689 | Cannot build without a main program.
2012 | Cannot call SetFocus from within a When, Valid, RangeHigh or RangeLow event.
2073 | Cannot change MemberClass because existing member objects have outstanding references.
1573 | Cannot change modality of a visible form.
1758 | Cannot change property "name" in SetAll method.
1770 | Cannot clear class "class" because it is in use.
176 | Cannot clear menu that is in use.
177 | Cannot clear popup that is in use.
1951 | Cannot clear the object "object" because it is in use.
2079 | Cannot close or detach extended cursor because it is currently in design mode.
1546 | Cannot close table during execution of a table-bound expression.
1535 | Cannot close this database because it is being used by a project.
1971 | Cannot compile until the current COMPILE command has completed.
102 | Cannot create file "file".
1102 | Cannot create file "file".
2019 | Cannot create offline view on a currently modified view.
*** | Cannot create program workspace.
169 | Cannot define menu item.
1572 | Cannot delete a database object while it is open in a designer.
2030 | Cannot delete file "name".
2201 | Cannot determine data type of the expression
1307 | Cannot divide by 0.
1871 | Cannot DROP all existing columns.
1754 | Cannot find entry point "name" in the DLL.
1562 | Cannot find object "name" in the database.
*** | Cannot find spell check program.
*** | Cannot find the beautify program.
1944 | Cannot find the builder program.
1798 | Cannot find the converter program.
1693 | Cannot find the menu-generation program.
1791 | Cannot find the text generation program.
*** | Cannot find the spell check program.
*** | Cannot find the wizard program.
1563 | Cannot find view "name" in the current database.
1846 | Cannot GROUP by aggregate field.
1671 | Cannot import from password-protected file.
1547 | Cannot insert an empty row from a view into its base table(s).
1566 | Cannot issue the PACK command on a database while its objects have open cursors.
1720 | Cannot issue the SET FORMAT command while a READ command is in progress on a format file.
1753 | Cannot load 32-bit DLL "name".
1527 | Cannot locate ODBC library, ODBC32.DLL.
1412 | Cannot locate the COMSPEC environment variable.
2006 | Cannot locate your Web browser.
1731 | Cannot modify a base class.
1948 | Cannot modify a class that is in use.
1844 | Cannot nest aggregate functions.
1926 | Cannot nest class definitions.
1254 | Cannot nest key labels.
1337 | Cannot nest the PRINTJOB command.
*** | Cannot open configuration file.
101 | Cannot open file "file".
2013 | Cannot open persistent table buffer directly.
1930 | Cannot redefine "name".
174 | Cannot redefine a menu that is in use.
175 | Cannot redefine popup that is in use.
2170 | Cannot refresh record from ADODB.Recordset because FOX cursor does not have an ADOBookmark column
2169 | Cannot refresh record from ADODB.Recordset because it does not support a Bookmark property
170 | Cannot release menu item.
2054 | Cannot release object.
1253 | Cannot rename the current directory.
1153 | Cannot rename the file to different device.
1970 | Cannot reopen project file "name".
1976 | Cannot resolve backlink.
2017 | Cannot reuse offline view in different mode.
1191 | Cannot save form: an object has an invalid name.
2045 | Cannot set DBCEventFile property when DBCEvents is off.
1706 | Cannot sort .IDX files in descending order.
2085 | Cannot update ADODB.Recordset because FOX cursor does not have an ADOBookmark column.
2084 | Cannot update ADODB.Recordset because it does not support a Bookmark property.
2083 | Cannot update ADODB.Recordset because it is read-only.
2082 | Cannot update ADODB.Recordset while cursor, created by CursorAdapter.CursorFill method, is not attached to a CursorAdapter object.
1909 | Cannot update project from project metafile.
111 | Cannot update the cursor "cursor", since it is read-only.
1157 | Cannot update the file "file".
292 | Cannot use 0 or negative as the argument for LOG10( ).
1979 | Cannot visually modify a class based on a nonvisual class.
1978 | Cannot visually modify a class of this type.
1502 | Cannot write to the record because it is in use.
1761 | Class "name" already exists.
1434 | Class "name" has not been registered.
1776 | Class "name" is in use.
1752 | Class "name" is in use by MODIFY CLASS.
1576 | Class "name" is not found in the class library.
1762 | Class "name" is not found.
1441 | Class cannot be instantiated because member "name" does not exist
1442 | Class cannot be instantiated because member "name" has wrong # of parameters
1313 | Class creation canceled.
1733 | Class definition "name" is not found.
1950 | Class definition "name" is recursive.
1747 | Class file "name" is invalid.
1746 | Class file name for "name" is not valid.
1751 | Class file version is greater than the current version.
1993 | Class library file "name" is not found.
2029 | Class "name" is not a Form class.
1949 | Class name is invalid.
2184 | Code page for the field "field name" doesn't match cursor's code page
1914 | Code page number is invalid.
1915 | Collating sequence "name" is not found.
1728 | Color scheme is reserved.
1642 | Color set resource is not found.
1695 | COLUMN | FORM | ALIAS | NOOVERWRITE | WIDTH are only allowed with the FROM clause.
1698 | COLUMN | ROW | ALIAS | NOOVERWRITE | SIZE | SCREEN are only allowed with the FROM clause.
223 | Column number must be between 0 and 255.
1657 | Column number must be between 0 and the right margin.
1579 | Command cannot be issued on a table with cursors in table buffering mode.
1593 | Command cannot be issued within a transaction.
1220 | Command contains invalid character.
36 | Command contains unrecognized phrase/keyword.
1297 | Command is allowed only in interactive mode.
1221 | Command is missing required clause.
1981 | Compile error in file "name".
1252 | Compiled code for this line is too long.
2176 | Connection "connection name" is in manual commit mode
1541 | Connection "name" is busy.
1466 | Connection handle is invalid.
1497 | Connection name is invalid.
1526 | Connectivity error: "name".
1522 | Connectivity internal consistency error.
1725 | Constant is already created with #DEFINE.
1509 | Conversion canceled. Adjust the memo BLOCKSIZE.
2136 | Conversion from Unicode has failed.
1799 | Conversion is canceled.
2135 | Conversion to Unicode has failed.
1168 | Could not add icon to executable file.
1181 | Could not add version resource to executable file.
2033 | CTOD and CTOT can produce incorrect results.
1988 | Currency value is out of range.
2173 | Cursor "cursor name" is in use and cannot be closed
2112 | Cursor "name" is attached to another CursorAdapter object.
2067 | Cursor "name" does not have a valid table or view reference.
2072 | Cursor cannot be modified because it contains an unsaved record.
2188 | Cursor doesn't support ADOBookmark property.
1166 | Cursor is corrupt or in wrong format.
2078 | CursorAdapter "name" cannot be loaded for design.
2125 | CursorAdapter and XMLTable objects do not belong to the same data session.
2092 | CursorAdapter cannot locate current record in the buffer. The record may have been reverted.
2090 | CursorAdapter does not have an associated cursor.
2175 | CursorAdapter internal error
2138 | CursorAdapter is unable to determine DataSourceType for the operation.
2075 | CursorSchema property is not specified.
44 | Cyclic relation.

D

1966 | Data environment is already loaded.
1967 | Data environment is already unloaded.
2068 | Data environment "name" does not contain a cursor object.
1549 | Data session #number cannot be released with open transaction(s).
1599 | Data session #number was forced to ROLLBACK all transactions to avoid deadlock.
1732 | Data type is invalid for this property.
9 | Data type mismatch.
1534 | Database "alias" is not open.
1569 | Database "name": File access denied.
1561 | Database is invalid. Please validate.
1570 | Database is read-only.
1709 | Database object is being used by someone else.
1773 | Database object type is invalid.
1544 | DataType property for field "name" is invalid.
2035 | Date/datetime contains illegal characters.
2034 | Date/datetime evaluated to an invalid value.
2027 | Declare DLL call caused an exception.
2086 | DEClass cannot be loaded.
1232 | DIMENSION contains variable declaration without required subscript arguments.
1963 | Directory is not found.
216 | Display mode is not available.
1907 | Drive specifier is invalid.
1156 | Duplicate field names.

E

4 | End of file encountered.
1591 | END TRANSACTION command cannot be issued without a corresponding BEGIN TRANSACTION command.
1214 | ENDTEXT does not have corresponding TEXT statement.
1473 | Environment-level property is invalid.
1957 | Error accessing printer spooler.
1779 | Error adding "name" to the object. Duplicate member/property name.
2199 | Error building key for index "name".
2186 | Error building sort key
1112 | Error closing the file.
1941 | Error code is not valid.
1424 | Error copying the OLE object to Clipboard.
1973 | Error creating table: "name".
1423 | Error creating the OLE object.
1735 | Error in the class definition. "Details"
1258 | Error in the PICTURE clause.
1574 | Error initializing application object.
1508 | Error initializing OLE.
1554 | Error instantiating cursor. Table "alias" cannot be opened. Object will be ignored.
1736 | Error instantiating the object "object".
1958 | Error loading printer driver.
1995 | Error loading the data environment. Table is in use.
1881 | Error loading file - record number n. "object" <or one of its members>. "Issue": "error".
2049 | Error loading HtmlHelp 2.0 collection.
1797 | Error occurred in conversion.
1584 | Error reading a property from the database. The property is ignored.
1104 | Error reading file "file".
1296 | Error reading the resource.
1422 | Error saving the OLE object.
2005 | Error with "name" - "property": "error".
1105 | Error writing to file "file".
1445 | EventHandler object "name" does not IMPLEMENT an interface
1977 | Exclusive open required to update this file. Please reopen.
1523 | Execution was canceled by the user.
46 | Expression evaluated to an illegal value.
67 | Expression evaluator failed.
1148 | Expression has been re-entered while the filter is executing.
1759 | Expression is invalid. Use a valid expression for "name" property.
1940 | Expression is not valid outside of WITH/ENDWITH.
1947 | Expression is too complex.
293 | Expression used with ACOS( ) is out of range.
291 | Expression used with ASIN( ) is out of range.

F

2039 | Failed to create recordset.
*** | Fatal error nExpr reporting error nExpr.
1001 | Feature is not available.
1580 | Feature is not supported for non-.DBC tables.
1953 | Feature is only available if the object is in design mode.
1530 | Fetching canceled; remote table is closed.
2174 | Field "field name" is not associated with a base table
1581 | Field "name" does not accept null values.
2172 | Field "field name" is not fetched
2088 | Field "name" is read-only.
1582 | Field "name" validation rule is violated.
1647 | Field expression contains an invalid data type.
2142 | Field for Unicode value should not use code page translation.
2040 | Field mismatch.
1913 | Field must be a General field.
350 | Field must be a Memo field.
1712 | Field name is a duplicate or invalid.
2141 | Field size for Unicode value can not be odd number.
1713 | Field width or number of decimal places is invalid.
2014 | Fields marked as update keys will be cleared.
1529 | File "name" already exists as part of a database.
1 | File "name" does not exist.
1553 | File "name" is a database.
1551 | File "name" is an invalid database.
1552 | File "name" is not a database.
1933 | File "name" is not closed.
1558 | File "name" is not part of a database.
1565 | File "name" is part of a database.
1718 | File "name" is read-only.
1190 | File "name" is too large.
1705 | File access is denied.
7 | File already exists.
1184 | File cannot be closed because outstanding references exist.
1503 | File cannot be locked.
108 | File is in use by another user.
3 | File is in use.
2191 | File is in use in another data session
1113 | File is not open.
1708 | File is open in another work area.
1338 | File is the wrong version.
1637 | File must be opened exclusively to convert the Memo file.
110 | File must be opened exclusively.
1918 | File name is too long.
1750 | File was created in a later version of Visual FoxPro than the current version.
91 | File was not placed in memory using the LOAD command.
1140 | FILTER expression exceeds allowed size.
2157 | Filter expression is not allowed for a Binary index
2190 | FontCharSet number is invalid
1749 | Form (.SCX) file must contain at least one Form.
1991 | Form file "name" is from a previous version of FoxPro. It must be converted to the current format before it can be executed.
1686 | Form file "name" is invalid.
2069 | Forms or Form classes that specify a DEClass and DEClassLibrary cannot be converted to or used with a FormSet.
2043 | Foxcode script "name" failure.
2042 | Foxcode table not found, is not correct version or is incompatible.
2046 | Foxtask table is corrupted or not the correct version.
11 | Function argument value, type, or count is invalid.
1999 | Function is not implemented.
1536 | Function is not supported on native tables.
1525 | Function is not supported on remote tables.
1300 | Function name is missing ).
1304 | Function name is missing (.
1504 | Function not supported for SQL pass-through cursors.
1586 | Function requires row or table buffering mode.

G - H

1986 | GDI memory is low, close one or more windows and try again.
1489 | General fields cannot be used in the WHERE condition of an update statement. Change the WhereType property of the view.
2053 | GroupBy clause is too long.
2050 | Help for this topic/context not implemented.

I

1167 | Icon is corrupt or in wrong format.
1587 | Illegal nested OLDVAL( ) or CURVAL( ).
2192 | Illegal operation for a table with pending changes
2193 | Illegal operation in rule evaluation
1910 | Illegal printer driver recursion.
1887 | Illegal recursion in rule evaluation.
1960 | Illegal redefinition of variable "name".
1594 | Illegal to attempt a file lock in a transaction after taking prior record locks.
1679 | Import only Worksheet A for Lotus 1-2-3 version 3.0 files.
1241 | Improper data type in the group expression.
1994 | Include file "name" is not found.
1471 | Incorrect column format.
1470 | Incorrect property name.
1886 | Index does not accept NULL.
114 | Index does not match the table. Delete the index file and re-create the index.
23 | Index expression exceeds maximum length.
19 | Index file does not match table.
2066 | Index file "file" is corrupted. Please rebuild it
2200 | Index "name" is in use and cannot be closed
1683 | Index tag is not found.
2198 | Index tag is not found for Cursor object "cursor name"
1684 | Index tag or file name must be specified.
2061 | Index or expression does not match an existing member of the collection.
1730 | Init event failed.
2177 | Inner and outer XMLTable objects are not associated with the same XMLAdapter object
1002 | Input/output operation failure.
1588 | INSERT cannot be issued when row or table buffering is enabled or when integrity constraints are in effect.
1308 | Insufficient stack space.
1443 | Interface "name" not found
1000 | Internal consistency error.
1243 | Internal error: Too many characters in the report.
231 | Invalid argument used with the SET function.
1477 | Invalid call issued while executing a SQLCOLUMNS( ) sequence.
1474 | Invalid call issued while executing a SQLEXEC( ) sequence.
1475 | Invalid call issued while executing a SQLMORERESULTS( ) sequence.
1476 | Invalid call issued while executing a SQLTABLES( ) sequence.
2047 | Invalid character entered.
1783 | Invalid class specified for @...Class command.
2153 | Invalid collate sequence
2048 | Invalid COMATTRIB value for "name"
*** | Invalid compact EXE file. Rebuild EXE.
1959 | Invalid coordinates.
2168 | Invalid data source type for RecordRefresh operation
1578 | Invalid database table name.
2098 | Invalid element in XMLTable.Fields collection.
1245 | Invalid expression in label definition file.
1111 | Invalid file descriptor.
1510 | Invalid file format. If this is a dBASE file, it must be converted first. To convert it, type MODIFY LABEL labelfilename.
2156 | Invalid index expression for a Binary index
2161 | Invalid Insert refresh column name "column name"
2162 | Invalid Insert refresh key column name "column name"
2146 | Invalid key column name "name".
112 | Invalid key length.
2026 | Invalid locale ID.
2011 | Invalid operation for offline view.
2008 | Invalid operation for offline view while being used online.
2007 | Invalid operation for offline view while offline.
1115 | Invalid operation for the cursor.
*** | Invalid or duplicate field name.
*** | Invalid or missing EXE file.
202 | Invalid path or file name.
2171 | Invalid refresh ignore column name "column name"
1103 | Invalid seek offset.
31 | Invalid subscript reference.
2160 | Invalid timestamp column name "column name"
1479 | Invalid update column name "name".
2163 | Invalid Update refresh column name "column name"
2164 | Invalid Update refresh key column name "column name"
1652 | Invalid use of a Visual FoxPro function as an array.
1223 | Invalid variable reference.

J - K

1124 | Key exceeds allowed size.
1117 | Key field length does not match.
1255 | Key label "label" is invalid.
1257 | Key string is too long.
356 | Keyboard macro file format is invalid.

L

54 | Label file is invalid.
1653 | Label nesting error.
221 | Left margin including indent must be less than the right margin.
21 | Length of variable strings exceeds amount of memory.
1691 | Library file "name" is invalid.
18 | Line is too long.
222 | Line number must be less than page length.
1194 | Link command failed.
1911 | Localized product is required for this environment.
58 | LOG( ): Zero or negative used as argument.
*** | Logical expression required
1662 | Lotus 1-2-3 version 1.0 file format is invalid.
297 | Lotus 1-2-3 version 2.0 file format is invalid.
1678 | Lotus 1-2-3 version 3.0 file format is invalid.

M

355 | Macro is not defined.
1609 | Maximum menu item length (50) is exceeded.
1607 | Maximum menu items allowed (128) is exceeded.
1608 | Maximum menus allowed (25) is exceeded.
1431 | Maximum number of OLE arguments is exceeded.
392 | Maximum record length exceeded in the import file.
1943 | Member "name" does not evaluate to an object.
1760 | Member "name" is a class member.
1975 | Member object "name" has not been instantiated.
1756 | Member object removed – cannot complete the Save operation.
41 | Memo file "name" is missing or is invalid.
55 | Memory file is invalid.
2000 | Memory is low, so streaming output updating has been disabled.
1687 | Menu file is invalid.
178 | Menu has not been activated with ACTIVATE MENU.
179 | Menu has not been activated with ACTIVATE POPUP.
168 | Menu has not been defined with DEFINE MENU.
165 | Menu has not been defined with DEFINE POPUP.
167 | Menu item position must be a positive number.
2051 | Menu item's conditional statement is too long.
1611 | Menu items and titles must be type Character.
287 | Menu size is too small.
181 | Menu specified in ACTIVATE MENU is already in use.
182 | Menu specified in ACTIVATE POPUP is already in use.
164 | Menu title has not been defined with DEFINE PAD.
279 | Menu was not pushed.
1765 | Method contains syntax errors. Method is not saved.
1661 | Microsoft Excel file format is invalid.
2038 | Microsoft Visual FoxPro doesn't support and cannot open this format of recordset.
1723 | Mismatched #IF/#ELSIF/#ELSE/#ENDIF.
1256 | Mismatched braces in key label.
1724 | Missing #ENDIF.
1193 | Missing .RTT section.
1306 | Missing comma (,).
152 | Missing expression.
1231 | Missing operand.
1670 | Multiplan version 4.0 file format is invalid.
1875 | Multiple warnings occurred performing the requested index modifications.
1710 | MULTISELECT or MOVER clause is not supported for PROMPT style menus.
1145 | Must be a character or numeric key field.
1226 | Must be a file variable.
1225 | Must be a variable or array.
94 | Must specify additional parameters.

N

96 | Nesting error.
2179 | Nested XML format is incompatible with 'Changes Only'
1488 | No connection associated with this cursor
1520 | No database is open or set as the current database.
1878 | No default value to DROP.
47 | No fields found to process.
138 | No fields were found to copy.
1492 | No key columns specified for the update table "name". Use the KeyFieldList property of the cursor.
1605 | No menu is defined.
1604 | No menu item is defined.
166 | No menu items have been defined for this menu.
1621 | No menu titles have been defined for this menu.
1964 | No PageFrame or Page is found in FormSet or Form with WindowType set to READ or READ MODAL.
1238 | No PARAMETER statement is found.
1649 | No previous PRINTJOB command to correspond to this command.
1879 | No primary key.
1796 | No records are found for the current platform.
1463 | No result set has been returned by the server.
1877 | No rule to DROP.
1774 | No sheet is found.
1612 | No such menu or menu item is defined.
52 | No table is open in the current work area.
1491 | No update tables are specified. Use the Tables property of the Cursor object.
45 | Not a character expression.
27 | Not a numeric expression.
1439 | Not a ProjectHook class.
15 | Not a table.
1682 | Not a user-defined window.
256 | Not a valid Framework II database/spreadsheet.
255 | Not a valid RapidFile database.
1149 | Not enough memory for buffer.
1150 | Not enough memory for file map.
1151 | Not enough memory for filename.
1600 | Not enough memory to open a table with the USE command.
1696 | NOWAIT/SAVE/NOENVIRONMENT/IN/WINDOW clauses are not allowed with the FROM clause.
2155 | Number of affected rows is not available
39 | Numeric overflow. Data was lost.

O

1766 | Object "name" is not found.
1923 | Object "name" is not found.
1985 | Object already has a data environment; cannot use another one with the SaveAs method.
1744 | Object class is invalid for this container.
1719 | Object file "name" is in use and cannot be removed from memory.
1195 | Object file "file" was compiled in a previous version of FoxPro.
2009 | Object is not an offline view.
1938 | Object is not contained in a "name".
1575 | Object name is invalid.
1942 | Objects cannot be assigned to arrays.
1987 | Objects cannot be programmatically added to the Form Designer's FormSet.
1919 | Objects cannot be programmatically deleted from the Class Designer.
1989 | Objects cannot be programmatically deleted from the Form Designer.
1528 | ODBC entry point missing, "name".
2015 | Offline view must be used online for this command
2010 | Offline views must be used exclusively when being used online.
2003 | OLE Changed Properties stream is the wrong version. Subclassed properties ignored.
1426 | OLE error code 0x"name".
1440 | OLE exception error "name". OLE object may be corrupt.
1427 | OLE IDispatch exception code "name".
1428 | OLE IDispatch exception code "number" from "name": "name".
1420 | OLE object is invalid or corrupted.
1965 | One of the members of this class is based on a nonvisual class. Cannot write .VCX file.
1968 | One of the members of this Form or FormSet is based on a nonvisual class. Cannot write .SCX file.
1436 | Only insertable objects are allowed in General fields.
2196 | Only single SQL SELECT statement can be enclosed in parenthesis
1885 | Only structural tags can be defined as candidate.
1912 | Operation is invalid for a General field.
34 | Operation is invalid for a Memo, Blob, General, or Picture field.
2076 | Operation is not allowed for CursorAdapter.
2077 | Operation is not allowed for CursorAdapter at this time.
2183 | Operation requires that SET MULTILOCKS is set to ON
107 | Operator/operand type mismatch.
2052 | OrderBy clause is too long.
2194 | Output page "page" is not available

P

1413 | Page frame cannot be sized that small.
1688 | Paradox file format is invalid.
1767 | Parent object will not allow this property setting for "name".
1217 | Picture error in GET statement.
1108 | Picture too big, corrupt, or in wrong format.
*** | Popup too big, first nExpr entries shown.
1722 | Preprocessor expression is invalid.
1681 | PREVIEW clause is not allowed with OFF/NOCONSOLE or TO PRINT/FILE.
1883 | Primary key already exists.
1567 | Primary key property is invalid; please validate database.
1956 | Printer access denied.
1643 | Printer driver is corrupted.
1644 | Printer driver is not found.
125 | Printer is not ready.
124 | Printer redirection is invalid.
1162 | Procedure "procedure" is not found.
1937 | Procedure file "name" is not found.
*** | Product has not been properly installed.
1202 | Program is too large.
1946 | Project file "name" is in the wrong version.
1685 | Project file is invalid.
1169 | Project file is read-only.
2197 | Property "property name" value is too long
1763 | Property "name" already exists.
2145 | Property "name" has invalid value.
1738 | Property "name" is not a method or event.
1734 | Property "name" is not found.
1757 | Property "name" is protected.
1743 | Property "name" is read-only.
1138 | Property does not have a default value.
1467 | Property is invalid for local cursors.
1468 | Property is invalid for table cursors.
1559 | Property is not found.
1739 | Property setting will not take effect until data environment reloaded.
1560 | Property value is invalid.
1469 | Property value is out of bounds.

Q

2055 | Query Parse Error - Try rebuilding in Query Wizard or by using View Designer Join Tab.
1716 | Queue "queue" is not found.

R

2018 | Reconnect of offline view failed.
109 | Record is in use by another user.
20 | Record is not in index.
130 | Record is not locked.
5 | Record is out of range.
1126 | Record is too long.
1583 | Record validation rule is violated.
2041 | Recordset does not exist.
1206 | Recursive macro definition.
2187 | Recursive XMLTable nesting is not allowed
1880 | Related table is not found in current database.
1882 | Related tag is not found or not primary or candidate.
1183 | Relation already exists.
1555 | Relational expression is not valid.
2016 | Removing a class member is not allowed.
1645 | Report contains a nesting error.
50 | Report file "name" is invalid.
2074 | Result is incompatible with cursor schema.
2060 | RETURN/RETRY statement not allowed in TRY/CATCH.
1592 | ROLLBACK command cannot be issued without a corresponding BEGIN TRANSACTION command.
30 | Row or column position is off the screen.
1598 | Rule and trigger code must balance transaction usage.
1405 | RUN|! Command failed. "Details"
1411 | RUN|! command string is too long.

S

1490 | Saving a converted form as a class is not supported.
1507 | Screen code is too large for available memory.
1917 | Script error: "name".
2139 | SelectCmd is empty.
1851 | Selects are not UNION compatible. "Details"
1715 | Server "server" is not found.
1540 | Session number is invalid.
*** | Source code not found.
*** | Source code out of date.
2167 | Source field for refresh is not found
1890 | SQL: Cannot determine data type of SQL column "column".
1802 | SQL: Cannot locate table
2151 | SQL: Cannot UPDATE or DELETE from subquery
2149 | SQL: Invalid SET expression in UPDATE, "table name" is not a target table
2150 | SQL: Table for UPDATE or DELETE cannot be outer joined
2148 | SQL: The ORDER BY clause is invalid in subqueries, unless TOP is also specified
2189 | SQL: Too many fields in final or intermediate result have the same name
1845 | SQL expression is too complex.
1499 | SQL parameter "name" is invalid.
1493 | SQL parameter is missing.
1465 | SQL pass-through internal consistency error.
1498 | SQL SELECT statement is invalid.
1472 | SQL statement parameter is required for non-prepared SqlExec() calls.
1811 | SQL: Aggregate on non-numeric expression.
1802 | SQL: Cannot locate table.
1806 | SQL: Column "field | variable" is not found.
1819 | SQL: DISTINCT is invalid.
1831 | SQL: Error building temporary index.
1801 | SQL: Error correlating fields.
1818 | SQL: FROM clause is required.
1807 | SQL: GROUP BY clause is invalid.
1803 | SQL: HAVING clause is invalid.
1828 | SQL: Illegal GROUP BY in subquery.
1830 | SQL: Index is not found.
1800 | SQL: Internal error.
1822 | SQL: Invalid aggregate field.
1865 | SQL: Invalid SET expression in UPDATE.
1866 | SQL: Invalid TOP specification.
1810 | SQL: Invalid use of subquery.
1839 | SQL: Operation was canceled.
1808 | SQL: ORDER BY clause is invalid.
1809 | SQL: Out of memory.
1814 | SQL: Queries of this type are not supported.
1820 | SQL: SELECT contains invalid *.
1826 | SQL: SELECT is invalid.
1804 | SQL: Statement is invalid.
1812 | SQL: Statement too long.
1825 | SQL: Subquery is invalid.
1842 | SQL: Subquery nesting is too deep.
1841 | SQL: Too many columns referenced.
1864 | SQL: Too many fields in UPDATE.
1805 | SQL: Too many subqueries.
1834 | SQL: Too many UNIONs.
1867 | SQL: TOP requires an ORDER BY.
1813 | SQL: Use of UNION in subquery is invalid.
1833 | SQL: WHERE clause is invalid.
61 | SQRT argument cannot be negative.
95 | Statement is not allowed in interactive mode.
1931 | Statement is not in a procedure.
1927 | Statement is not valid in a class definition.
1928 | Statement is only valid within a class definition.
1934 | Statement only valid within a method.
1903 | String is too long to fit.
1707 | Structural .CDX file is not found.
1235 | Structure is invalid.
1212 | Structure nesting is too deep.
1860 | Subquery returned more than one record.
1234 | Subscript is outside defined range.
1236 | Suspend program before using RESUME.
1673 | Symphony version 1.0 file format is invalid.
1674 | Symphony version 1.1 file format is invalid.
2093 | Syntax error: "name" is not allowed in the view script or is in the wrong place.
1242 | Syntax error in the field expression.
10 | Syntax error.

T

228 | Tab stops must be in ascending order.
1548 | Table "alias" has one or more non-structural indexes open. Please close them and retry the Begin Transaction.
1564 | Table "name" already exists in the database.
2065 | Table "name" has a file length / record number inconsistency.
2091 | Table "name" has become corrupted. The table will need to be repaired before using again.
1577 | Table "name" is referenced in a relation.
1545 | Table buffer for alias "name" contains uncommitted changes.
1596 | Table buffering is not enabled.
1556 | Table cannot be browsed because cursor object is no longer valid.
26 | Table has no index order set.
17 | Table number is invalid.
1690 | Table operation is invalid during indexing.
1589 | Table or row buffering requires that SET MULTILOCKS is set to ON.
1888 | Tag name is too long.
1147 | Target table is already engaged in a relation.
2131 | TEXT does not have corresponding ENDTEXT statement
1792 | Text generation is canceled.
2044 | Textmerge is recursive.
2089 | The "name" event has failed.
1954 | The builder program is already running.
1478 | The ChildOrder property of a relation object in the data environment is no longer valid. The relation is being removed.
2020 | The class file associated with this field cannot be found - class association cleared.
1969 | The clipboard contained one or more objects that could not be added to the container. Those objects were not pasted.
2036 | The current Help file is empty.
1935 | The current object does not inherit from class "name".
1945 | The current object has been released.
2195 | The cursor is already associated with a record set
2021 | The DataObject cannot be modified in the OLEDragOver or OLEDragDrop event.
1742 | The data source for this object must be a variable reference.
1557 | The database must be opened exclusively.
1997 | The default value for field "name" does not evaluate to the correct type for the field.
1962 | The directory is not empty.
2152 | The Dockable property cannot be enabled possibly due to conflicting properties
1984 | The fields in table "name" did not match the entries in the database.
1131 | The file specified in the FROM clause is empty.
1699 | The IN clause is not supported for this window.
1998 | The index expression for index "name" contains an invalid reference to a Memo, General, or Picture field.
42 | The LOCATE command must be issued before the CONTINUE command.
1571 | The name "name" is already used for another object. Please choose a different name.
2001 | The name of the object file for "file" is already used by another program in the project.
1793 | The network request is not supported.
1438 | The ActiveX control module failed to register correctly.
2166 | The refresh key defined for table "table name" is not found
2165 | The refresh key defined for table "table name" is not unique
*** | The Remote View Wizard was unable to obtain column information for this remote table. This may be the result of an ODBC error, or the remote table may not be owned by the current user.
1524 | The selected printer driver does not support direct access.
2057 | The specified class library does not exist or does not contain a valid member class.
2022 | The specified file or path was not found.
2062 | The specified Key already exists.
2056 | The specified member class does not exist or is of wrong type.
2025 | The SQL Statement is too complex for the View/Query Designer.
1531 | The table changes cannot be performed as the index or filter expression for index name would be invalid.
2004 | The table file "name" has moved. Please validate database "name" and try again.
1659 | The table has memo fields that cannot be converted while open read-only.
1778 | The table must be converted before appending.
1982 | The TO clause can only be used with modal Forms and FormSets.
1996 | The validation rule for field "name" does not evaluate to a logical or NULL type.
2105 | There is a duplicate field "name" in XML schema.
2104 | There is a duplicate table "name" in XML schema.
1213 | There is a missing keyword in the FOR ... ENDFOR or DO CASE ... ENDCASE command structure.
2023 | There is no application associated with the given filename extension.
2178 | There is no relation to the nested table "table name".
56 | There is not enough disk space for "name".
43 | There is not enough memory to complete this operation.
1780 | This array element has been defined as an object and cannot be redefined in the class definition.
1777 | This command is not supported for views.
2116 | This feature requires MSXML4 SP1 or later.
1748 | This file is incompatible with the current version of Visual FoxPro.
1784 | This object is derived from a base class and does not have a parent class.
1782 | This OLE property cannot be an expression.
1521 | This operation not supported for class member objects.
1533 | This property is read-only.
1916 | To use this feature, set CODEPAGE=AUTO in your CONFIG.FPW file and restart Visual FoxPro.
1229 | Too few arguments.
1230 | Too many arguments.
1310 | Too many characters are specified in the PICTURE clause.
1872 | Too many columns.
1694 | Too many extensions are specified.
6 | Too many files open.
1201 | Too many names used.
1250 | Too many PROCEDURE commands are in effect.
1249 | Too many READ commands are in effect.
22 | Too many variables.
1116 | Too many windows open.
1646 | Total field type must be Date or Numeric.
1246 | Total label width exceeds allowed size.
1539 | Trigger failed in "cursor".
2058 | TRY/CATCH/FINALLY/ENDTRY mismatch or error.
1532 | Type conversion is not supported.
1501 | Type conversion is not supported for output parameters.
1543 | Type conversion required by the DataType property for field '"name"' is invalid.
1444 | Type Library "name" not found

U

2101 | Unable to attach object with empty XMLName property.
2159 | Unable to cast NULL value to a NOT NULL data type
2103 | Unable to change XMLName property while XMLField object belongs to XMLTable object.
2122 | Unable to close offline view in ADMIN/ONLINE mode inside a transaction.
2102 | Unable to change XMLName property while XMLTable object belongs to XMLAdapter object.
1410 | Unable to create temporary work files.
2133 | Unable to emit XML, two or more cursors use different code pages.
2185 | Unable to infer cursor's code page from XML document
2120 | Unable to infer XML schema.
1717 | Unable to generate a printer driver.
*** | Unable to locate desired version of Visual FoxPro.
2158 | Unable to locate target record in ADODB.Recordset
2121 | Unable to open offline view in ADMIN/ONLINE mode inside a transaction.
*** | Unable to process error.
1437 | Unable to register the ActiveX control.
2123 | Unable to set external schema location when inline schema is used.
2059 | Unhandled Structured Exception
1884 | Uniqueness of index "name" is violated.
*** | Unknown error code nExpr.
104 | Unknown function key.
1925 | Unknown member "name".
2154 | Unknown member object "object name"
16 | Unrecognized command verb.
1141 | Unrecognized index file revision. Re-create the index.
1595 | Update conflict. Some of your changes in the current row batch were committed. Use TABLEUPDATE( ) with the lForce parameter to commit the update or the manual transaction to roll back the update.
1585 | Update conflict. Use TABLEUPDATE( ) with the lForce parameter to commit the update or TABLEREVERT( ) to roll back the update.
1097 | User-defined functions are not allowed.
2031 | User-interface operation not allowed at this time.
2071 | User Thrown Error

V

2100 | Value of XMLField.XMLName must be used as key value for collection.
2134 | Value of XMLName, XMLNamespace or XMLPrefix property should be a Unicode string.
2099 | Value of XMLTable.XMLName must be used as key value for collection.
12 | Variable "variable" is not found.
1134 | Variable must be in the selected table.
2137 | Vfp.VFPXMLProgId doesn't support cSchemaLocation parameter for XMLUpdateGram().
1494 | View definition has been changed.
1568 | View fields have been changed. The Update and Key field properties have been reset to the default values.
127 | View file is invalid.
1597 | Views require either DB_BUFOPTROW or DB_BUFOPTTABLE.
 | Visual FoxPro cannot start
1922 | Volume does not exist.

W

1485 | Warning: Invalid data conversion(s) starting at record "name".
1486 | Warning: Invalid memo field conversions starting at record "name".
1496 | Warning: No information is available to check remote update conflicts.
1483 | Warning: The connection packet size cannot be set.
1480 | Warning: The connection sync/async mode cannot be set.
1481 | Warning: The connection timeout cannot be set.
1487 | Warning: The connection transaction mode cannot be set.
1495 | Warning: The key defined by the KeyField property for table "alias" is not unique.
1484 | Warning: The next "cExpr" modified records have already been updated remote.
1482 | Warning: The query timeout cannot be set.
1908 | Width or decimal place argument is invalid.
1955 | WIN.INI/registry is corrupted.
1714 | Window "name" has not been defined.
2087 | Window "name" is not a dockable window. (Error 2087)
1632 | Window file format is invalid.
215 | Window has not been activated with ACTIVATE WINDOW.
214 | Window has not been defined with DEFINE WINDOW.
332 | Window specified in DEFINE WINDOW has invalid coordinates.
1939 | WITH/ENDWITH mismatch.
1775 | Worksheet "name" is not found.
1680 | Worksheet A for Lotus 1-2-3 version 3.0 file is hidden.

X - Z

2124 | XML document does not have a root element.
2126 | XML document is not a DiffGram.
2096 | XML document is not loaded.
2110 | XML Error: "error"
2128 | XML node does not belong to MSXML4.DOMDocument.
1435 | XML Parse Error
2094 | XML Schema is too complex.
2129 | XMLAdapter object doesn't have associated tables.
2180 | XMLAdapter XMLName property is an XPath expression
2107 | XMLAdapter.ToXML cannot be called while there is a loaded XML document.
2127 | XMLAdapter.XMLName is empty.
2118 | XMLAdapter: fractionDigits must not be greater than or equal to maxLength.
2144 | XMLField object is already associated with XMLTable object.
2182 | XMLName property contains illegal symbol(s)
2109 | XMLTable has child table.
2132 | XMLTable object already has parent or is associated with XMLAdapter object.
2097 | XMLTable object does not have associated fields.
2095 | XMLTable object does not have associated XMLAdapter object.
2130 | XMLTable object with XMLName "name" does not have associated fields.
2181 | XMLTable XMLName property is an XPath expression
2108 | XMLTable.Alias is empty.
1772 | You may not change the RecordSource of a BROWSE object.
1127 | You must use a logical expression with a FOR or WHILE clause.
37 | You must use a logical expression with FILTER.

See Also

Other Resources

Error Messages
Error Messages by Number
ERROR Command
ERROR( ) Function


Error Messages Listed Numerically

Visual FoxPro 9.0
Error Messages Listed Numerically
See Also

Locate the number for the error message to find a link to the topic for the message.

***

*** | *bad date*
*** | Cannot allocate screen map
*** | Cannot create program workspace.
*** | Cannot find spell check program.
*** | Cannot find the beautify program.
*** | Cannot find the spell check program.
*** | Cannot find the wizard program.
*** | Cannot open configuration file.
*** | Fatal error nExpr reporting error nExpr.
*** | *Interrupted*
*** | Invalid compact EXE file. Rebuild EXE.
*** | Invalid or duplicate field name.
*** | Invalid or missing EXE file.
*** | Logical expression required
*** | Popup too big, first nExpr entries shown.
*** | Product has not been properly installed.
*** | Source code not found.
*** | Source code out of date.
*** | The Remote View Wizard was unable to obtain column information for this remote table. This may be the result of an ODBC error, or the remote table may not be owned by the current user.
*** | Unable to locate desired version of Visual FoxPro.
*** | Unable to process error.
*** | Unknown error code nExpr.
*** | Visual FoxPro cannot start.

1

1 | File "name" does not exist.
3 | File is in use.
4 | End of file encountered.
5 | Record is out of range.
6 | Too many files open.
7 | File already exists.
9 | Data type mismatch.
10 | Syntax error.
11 | Function argument value, type, or count is invalid.
12 | Variable "variable" is not found.
13 | Alias is not found.
15 | Not a table.
16 | Unrecognized command verb.
17 | Table number is invalid.
18 | Line is too long.
19 | Index file does not match table.
20 | Record is not in index.
21 | Length of variable strings exceeds amount of memory.
22 | Too many variables.
23 | Index expression exceeds maximum length.
24 | Alias name is already in use.
26 | Table has no index order set.
27 | Not a numeric expression.
30 | Row or column position is off the screen.
31 | Invalid subscript reference.
34 | Operation is invalid for a Memo, Blob, General, or Picture field.
36 | Command contains unrecognized phrase/keyword.
37 | You must use a logical expression with FILTER.
38 | Beginning of file encountered.
39 | Numeric overflow. Data was lost.
41 | Memo file "name" is missing or is invalid.
42 | The LOCATE command must be issued before the CONTINUE command.
43 | There is not enough memory to complete this operation.
44 | Cyclic relation.
45 | Not a character expression.
46 | Expression evaluated to an illegal value.
47 | No fields found to process.
50 | Report file "name" is invalid.
52 | No table is open in the current work area.
54 | Label file is invalid.
55 | Memory file is invalid.
56 | There is not enough disk space for "name".
58 | LOG( ): Zero or negative used as argument.
61 | SQRT argument cannot be negative.
62 | Cannot access characters beyond string.
67 | Expression evaluator failed.
78 | ** or ^ domain error.
91 | File was not placed in memory using the LOAD command.
94 | Must specify additional parameters.
95 | Statement is not allowed in interactive mode.
96 | Nesting error.

100

101 | Cannot open file "file".
102 | Cannot create file "file".
103 | Allowed DO nesting level exceeded.
104 | Unknown function key.
107 | Operator/operand type mismatch.
108 | File is in use by another user.
109 | Record is in use by another user.
110 | File must be opened exclusively.
111 | Cannot update the cursor "cursor", since it is read-only.
112 | Invalid key length.
114 | Index does not match the table. Delete the index file and re-create the index.
115 | .DIF file header is invalid.
116 | .DIF vector is invalid - .DBF field mismatch.
117 | .DIF type indicator is invalid.
119 | .SYLK file header is invalid.
120 | .SYLK file dimension bounds are invalid.
121 | .SYLK file format is invalid.
124 | Printer redirection is invalid.
125 | Printer is not ready.
127 | View file is invalid.
130 | Record is not locked.
138 | No fields were found to copy.
152 | Missing expression.
164 | Menu title has not been defined with DEFINE PAD.
165 | Menu has not been defined with DEFINE POPUP.
166 | No menu items have been defined for this menu.
167 | Menu item position must be a positive number.
168 | Menu has not been defined with DEFINE MENU.
169 | Cannot define menu item.
170 | Cannot release menu item.
174 | Cannot redefine a menu that is in use.
175 | Cannot redefine popup that is in use.
176 | Cannot clear menu that is in use.
177 | Cannot clear popup that is in use.
178 | Menu has not been activated with ACTIVATE MENU.
179 | Menu has not been activated with ACTIVATE POPUP.
181 | Menu specified in ACTIVATE MENU is already in use.
182 | Menu specified in ACTIVATE POPUP is already in use.

200

202 | Invalid path or file name.
214 | Window has not been defined with DEFINE WINDOW.
215 | Window has not been activated with ACTIVATE WINDOW.
216 | Display mode is not available.
221 | Left margin including indent must be less than the right margin.
222 | Line number must be less than page length.
223 | Column number must be between 0 and 255.
225 | "name" is not a variable.
226 | "name" is not a file variable.
227 | Box dimensions are invalid.
228 | Tab stops must be in ascending order.
230 | Array dimensions are invalid.
231 | Invalid argument used with the SET function.
232 | "name" is not an array.
255 | Not a valid RapidFile database.
256 | Not a valid Framework II database/spreadsheet.
279 | Menu was not pushed.
287 | Menu size is too small.
291 | Expression used with ASIN( ) is out of range.
292 | Cannot use 0 or negative as the argument for LOG10( ).
293 | Expression used with ACOS( ) is out of range.
297 | Lotus 1-2-3 version 2.0 file format is invalid.

300

332 | Window specified in DEFINE WINDOW has invalid coordinates.
350 | Field must be a Memo field.
355 | Macro is not defined.
356 | Keyboard macro file format is invalid.
392 | Maximum record length exceeded in the import file.

1000

1000 | Internal consistency error.
1001 | Feature is not available.
1002 | Input/output operation failure.
1097 | User defined functions are not allowed.
1098 | API function _UserError( ) was called.

1100

1102 | Cannot create file "file".
1103 | Invalid seek offset.
1104 | Error reading file "file".
1105 | Error writing to file "file".
1106 | Cannot access file "file"; transaction is in progress.
1108 | Picture too big, corrupt, or in wrong format.
1111 | Invalid file descriptor.
1112 | Error closing the file.
1113 | File is not open.
1115 | Invalid operation for the cursor.
1116 | Too many windows open.
1117 | Key field length does not match.
1124 | Key exceeds allowed size.
1126 | Record is too long.
1127 | You must use a logical expression with a FOR or WHILE clause.
1130 | 'field' phrase is not found.
1131 | The file specified in the FROM clause is empty.
1134 | Variable must be in the selected table.
1138 | Property does not have a default value.
1140 | FILTER expression exceeds allowed size.
1141 | Unrecognized index file revision. Re-create the index.
1145 | Must be a character or numeric key field.
1147 | Target table is already engaged in a relation.
1148 | Expression has been re-entered while the filter is executing.
1149 | Not enough memory for buffer.
1150 | Not enough memory for file map.
1151 | Not enough memory for filename.
1152 | Cannot access the selected table.
1153 | Cannot rename the file to different device.
1156 | Duplicate field names.
1157 | Cannot update the file "file".
1162 | Procedure "procedure" is not found.
1163 | Browse table is closed.
1164 | Browse structure has changed.
1165 | "field" is not related to the current work area.
1166 | Cursor is corrupt or in wrong format.
1167 | Icon is corrupt or in wrong format.
1168 | Could not add icon to executable file.
1169 | Project file is read-only.
1178 | Application file "file" is not closed.
1181 | Could not add version resource to executable file.
1183 | Relation already exists.
1184 | File cannot be closed because outstanding references exist.
1190 | File "name" is too large.
1191 | Cannot save form: an object has an invalid name
1193 | Missing .RTT section.
1194 | Link command failed.
1195 | Object file "file" was compiled in a previous version of FoxPro.
1196 | "file" is not a Visual FoxPro .EXE file.

1200

1201 | Too many names used.
1202 | Program is too large.
1206 | Recursive macro definition.
1211 | An IF | ELSE | ENDIF statement is missing.
1212 | Structure nesting is too deep.
1213 | There is a missing keyword in the FOR ... ENDFOR or DO CASE ... ENDCASE command structure.
1214 | ENDTEXT does not have corresponding TEXT statement.
1217 | Picture error in GET statement.
1220 | Command contains invalid character.
1221 | Command is missing required clause.
1223 | Invalid variable reference.
1225 | Must be a variable or array.
1226 | Must be a file variable.
1229 | Too few arguments.
1230 | Too many arguments.
1231 | Missing operand.
1232 | DIMENSION contains variable declaration without required subscript arguments.
1234 | Subscript is outside defined range.
1235 | Structure is invalid.
1236 | Suspend program before using RESUME.
1238 | No PARAMETER statement is found.
1241 | Improper data type in the group expression.
1242 | Syntax error in the field expression.
1243 | Internal error: Too many characters in the report.
1245 | Invalid expression in label definition file.
1246 | Total label width exceeds allowed size.
1249 | Too many READ commands are in effect.
1250 | Too many PROCEDURE commands are in effect.
1252 | Compiled code for this line is too long.
1253 | Cannot rename the current directory.
1254 | Cannot nest key labels.
1255 | Key label "label" is invalid.
1256 | Mismatched braces in key label.
1257 | Key string is too long.
1258 | Error in the PICTURE clause.
1294 | "name" is not a valid resource file.
1296 | Error reading the resource.
1297 | Command is allowed only in interactive mode.
1298 | "name" band is too large to fit on page.

1300

1300 | Function name is missing ).
1304 | Function name is missing (.
1306 | Missing comma (,).
1307 | Cannot divide by 0.
1308 | Insufficient stack space.
1309 | "file" is not an object file.
1310 | Too many characters are specified in the PICTURE clause.
1313 | Class creation canceled.
1337 | Cannot nest the PRINTJOB command.
1338 | File is the wrong version.

1400

1405 | RUN|! Command failed. "Details".
1410 | Unable to create temporary work files.
1411 | RUN|! command string is too long.
1412 | Cannot locate the COMSPEC environment variable.
1413 | Page frame cannot be sized that small.
1420 | OLE object is invalid or corrupted.
1421 | Cannot activate the OLE server.
1422 | Error saving the OLE object.
1423 | Error creating the OLE object.
1424 | Error copying the OLE object to Clipboard.
1426 | OLE error code 0x"name".
1427 | OLE IDispatch exception code "name".
1428 | OLE IDispatch exception code "number" from "name": "name".
1429 | "OLE error".
1431 | Maximum number of OLE arguments is exceeded.
1434 | Class "name" has not been registered.
1435 | XML Parse Error
1436 | Only insertable objects are allowed in General fields.
1437 | Unable to register the ActiveX control.
1438 | The ActiveX control module failed to register correctly.
1439 | Not a ProjectHook class.
1440 | OLE exception error "name". OLE object may be corrupt.
1441 | Class cannot be instantiated because member "name" does not exist
1442 | Class cannot be instantiated because member "name" has wrong # of parameters
1443 | Interface "name" not found
1444 | Type Library "name" not found
1445 | EventHandler object "name" does not IMPLEMENT an interface
1462 | "name" internal consistency error.
1463 | No result set has been returned by the server.
1465 | SQL pass-through internal consistency error.
1466 | Connection handle is invalid.
1467 | Property is invalid for local cursors.
1468 | Property is invalid for table cursors.
1469 | Property value is out of bounds.
1470 | Incorrect property name.
1471 | Incorrect column format.
1472 | SQL statement parameter is required for non-prepared SqlExec( ) calls.
1473 | Environment-level property is invalid.
1474 | Invalid call issued while executing a SQLEXEC( ) sequence.
1475 | Invalid call issued while executing a SQLMORERESULTS( ) sequence.
1476 | Invalid call issued while executing a SQLTABLES( ) sequence.
1477 | Invalid call issued while executing a SQLCOLUMNS( ) sequence.
1478 | The ChildOrder property of a relation object in the data environment is no longer valid. The relation is being removed.
1479 | Invalid update column name \"name"\.
1480 | Warning: The connection sync/async mode cannot be set.
1481 | Warning: The connection timeout cannot be set.
1482 | Warning: The query timeout cannot be set.
1483 | Warning: The connection packet size cannot be set.
1484 | Warning: The next "cExpr" modified records have already been updated remote.
1485 | Warning: Invalid data conversion(s) starting at record "name".
1486 | Warning: Invalid memo field conversions starting at record "name".
1487 | Warning: The connection transaction mode cannot be set.
1488 | No connection associated with this cursor
1489 | General fields cannot be used in the WHERE condition of an update statement. Change the WhereType property of the view.
1490 | Saving a converted form as a class is not supported.
1491 | No update tables are specified. Use the Tables property of the Cursor object.
1492 | No key columns specified for the update table "name". Use the KeyFieldList property of the cursor.
1493 | SQL parameter is missing.
1494 | View definition has been changed.
1495 | Warning: The key defined by the KeyField property for table "alias" is not unique.
1496 | Warning: No information is available to check remote update conflicts.
1497 | Connection name is invalid.
1498 | SQL SELECT statement is invalid.
1499 | SQL parameter "name" is invalid.

1500

1501 | Type conversion is not supported for output parameters.
1502 | Cannot write to the record because it is in use.
1503 | File cannot be locked.
1504 | Function not supported for SQL pass-through cursors.
1507 | Screen code is too large for available memory.
1508 | Error initializing OLE.
1509 | Conversion canceled. Adjust the memo BLOCKSIZE.
1510 | Invalid file format. If this is a dBASE file, it must be converted first. To convert it, type MODIFY LABEL labelfilename.
1520 | No database is open or set as the current database.
1521 | This operation not supported for class member objects.
1522 | Connectivity internal consistency error.
1523 | Execution was canceled by the user.
1524 | The selected printer driver does not support direct access.
1525 | Function is not supported on remote tables.
1526 | Connectivity error: "name".
1527 | Cannot locate ODBC library, ODBC32.DLL.
1528 | ODBC entry point missing, "name".
1529 | File "name" already exists as part of a database.
1530 | Fetching canceled; remote table is closed.
1531 | The table changes cannot be performed as the index or filter expression for index name would be invalid.
1532 | Type conversion is not supported.
1533 | This property is read-only.
1534 | Database "alias" is not open.
1535 | Cannot close this database because it is being used by a project.
1536 | Function is not supported on native tables.
1537 | Cannot add this table: it belongs to database "name".
1538 | A stored procedure is executing.
1539 | Trigger failed in "cursor".
1540 | Session number is invalid.
1541 | Connection "name" is busy.
1542 | Base table fields have been changed and no longer match view fields. View field properties cannot be set.
1543 | Type conversion required by the DataType property for field '"name"' is invalid.
1544 | DataType property for field '"name"' is invalid.
1545 | Table buffer for alias "name" contains uncommitted changes.
1546 | Cannot close table during execution of a table-bound expression.
1547 | Cannot insert an empty row from a view into its base table(s).
1548 | Table "alias" has one or more non-structural indexes open. Please close them and retry the Begin Transaction.
1549 | Data session #number cannot be released with open transaction(s).
1550 | .DBC internal consistency error.
1551 | File "name" is an invalid database.
1552 | File "name" is not a database.
1553 | File "name" is a database.
1554 | Error instantiating cursor object. Table "alias" cannot be opened. Object will be ignored.
1555 | Relational expression is not valid.
1556 | Table cannot be browsed because cursor object is no longer valid.
1557 | The database must be opened exclusively.
1558 | File "name" is not part of a database.
1559 | Property is not found.
1560 | Property value is invalid.
1561 | Database is invalid. Please validate.
1562 | Cannot find object "name" in the database.
1563 | Cannot find view "name" in the current database.
1564 | Table "name" already exists in the database.
1565 | File "name" is part of a database.
1566 | Cannot issue the PACK command on a database while its objects have open cursors.
1567 | Primary key property is invalid; please validate database.
1568 | View fields have been changed. The Update and Key field properties have been reset to the default values.
1569 | Database "name": File access denied.
1570 | Database is read-only.
1571 | The name "name" is already used for another object. Please choose a different name.
1572 | Cannot delete a database object while it is open in a designer.
1573 | Cannot change modality of a visible form.
1574 | Error initializing application object.
1575 | Object name is invalid.
1576 | Class "name" is not found in the class library.
1577 | Table "name" is referenced in a relation.
1578 | Invalid database table name.
1579 | Command cannot be issued on a table with cursors in table buffering mode.
1580 | Feature is not supported for non-.DBC tables.
1581 | Field "name" does not accept null values.
1582 | Field "name" validation rule is violated.
1583 | Record validation rule is violated.
1584 | Error reading a property from the database. The property is ignored.
1585 | Update conflict. Use TABLEUPDATE( ) with the lForce parameter to commit the update or TABLEREVERT( ) to roll back the update.
1586 | Function requires row or table buffering mode.
1587 | Illegal nested OLDVAL( ) or CURVAL( ).
1588 | INSERT cannot be issued when row or table buffering is enabled or when integrity constraints are in effect.
1589 | Table or row buffering requires that SET MULTILOCKS is set to ON.
1590 | BEGIN TRANSACTION command failed. Nesting level is too deep.
1591 | END TRANSACTION command cannot be issued without a corresponding BEGIN TRANSACTION command.
1592 | ROLLBACK command cannot be issued without a corresponding BEGIN TRANSACTION command.
1593 | Command cannot be issued within a transaction.
1594 | Illegal to attempt a file lock in a transaction after taking prior record locks.
1595 | Update conflict. Some of your changes in the current row batch were committed. Use TABLEUPDATE( ) with the lForce parameter to commit the update or the manual transaction to roll back the update.
1596 | Table buffering is not enabled.
1597 | Views require either DB_BUFOPTROW or DB_BUFOPTTABLE.
1598 | Rule and trigger code must balance transaction usage.
1599 | Data session #number was forced to ROLLBACK all transactions to avoid deadlock.

1600

1600 | Not enough memory to open a table with the USE command.
1604 | No menu bar is defined.
1605 | No menu is defined.
1607 | Maximum menu items allowed (128) is exceeded.
1608 | Maximum menus allowed (25) is exceeded.
1609 | Maximum menu item length (50) is exceeded.
1611 | Menu items and titles must be type Character.
1612 | No such menu or menu item is defined.
1621 | No menu titles have been defined for this menu.
1632 | Window file format is invalid.
1637 | File must be opened exclusively to convert the Memo file.
1640 | Access to system Registry denied
1642 | Color set resource is not found.
1643 | Printer driver is corrupted.
1644 | Printer driver is not found.
1645 | Report contains a nesting error.
1646 | Total field type must be Date or Numeric.
1647 | Field expression contains an invalid data type.
1649 | No previous PRINTJOB command to correspond to this command.
1651 | CANCEL or SUSPEND is not allowed.
1652 | Invalid use of a Visual FoxPro function as an array.
1653 | Label nesting error.
1657 | Column number must be between 0 and the right margin.
1659 | The table has memo fields that cannot be converted while open read-only.
1661 | Microsoft Excel file format is invalid.
1662 | Lotus 1-2-3 version 1.0 file format is invalid.
1670 | Multiplan version 4.0 file format is invalid.
1671 | Cannot import from password-protected file.
1672 | Cannot append from password protected file.
1673 | Symphony version 1.0 file format is invalid.
1674 | Symphony version 1.1 file format is invalid.
1678 | Lotus 1-2-3 version 3.0 file format is invalid.
1679 | Import only Worksheet A for Lotus 1-2-3 version 3.0 files.
1680 | Worksheet A for Lotus 1-2-3 version 3.0 file is hidden.
1681 | PREVIEW clause is not allowed with OFF/NOCONSOLE or TO PRINT/FILE.
1682 | Not a user-defined window.
1683 | Index tag is not found.
1684 | Index tag or file name must be specified.
1685 | Project file is invalid.
1686 | Form file "name" is invalid.
1687 | Menu file is invalid.
1688 | Paradox file format is invalid.
1689 | Cannot build without a main program.
1690 | Table operation is invalid during indexing.
1691 | Library file "name" is invalid.
1693 | Cannot find the menu-generation program.
1694 | Too many extensions are specified.
1695 | COLUMN | FORM | ALIAS | NOOVERWRITE | WIDTH are only allowed with the FROM clause.
1696 | NOWAIT | SAVE | NOENVIRONMENT | IN | WINDOW clauses are not allowed with the FROM clause.
1698 | COLUMN | ROW | ALIAS | NOOVERWRITE | SIZE | SCREEN are only allowed with the FROM clause.
1699 | The IN clause is not supported for this window.

1700

1705 | File access is denied.
1706 | Cannot sort .IDX files in descending order.
1707 | Structural .CDX file is not found.
1708 | File is open in another work area.
1709 | Database object is being used by someone else.
1710 | MULTISELECT or MOVER clause is not supported for PROMPT style menus.
1711 | API library revision mismatch. Rebuild library.
1712 | Field name is a duplicate or invalid.
1713 | Field width or number of decimal places is invalid.
1714 | Window "name" has not been defined.
1715 | Server "server" is not found.
1716 | Queue "queue" is not found.
1717 | Unable to generate a printer driver.
1718 | File "name" is read-only.
1719 | Object file "name" is in use and cannot be removed from memory.
1720 | Cannot issue the SET FORMAT command while a READ command is in progress on a format file.
1722 | Preprocessor expression is invalid.
1723 | Mismatched #IF/#ELSIF/#ELSE/#ENDIF.
1724 | Missing #ENDIF.
1725 | Constant is already created with #DEFINE.
1726 | API library is not found.
1727 | A .DBF-style Help file is required.
1728 | Color scheme is reserved.
1730 | Init event failed.
1731 | Cannot modify a base class.
1732 | Data type is invalid for this property.
1733 | Class definition "name" is not found.
1734 | Property "name" is not found.
1735 | Error in the class definition. "Details"
1736 | Error instantiating the object "object".
1737 | "name" is a method, event, or object.
1738 | Property "name" is not a method or event.
1739 | Property setting will not take effect until data environment reloaded.
1740 | "name" is a read-only property.
1741 | Cannot add "name". Class definition is cyclical.
1742 | The data source for this object must be a variable reference.
1743 | Property "name" is read-only.
1744 | Object class is invalid for this container.
1745 | "name" is not a Visual FoxPro event.
1746 | Class file name for "name" is not valid.
1747 | Class file "name" is invalid.
1748 | This file is incompatible with the current version of Visual FoxPro.
1749 | Form (.SCX) file must contain at least one Form.
1750 | File was created in a later version of Visual FoxPro than the current version.
1751 | Class file version is greater than the current version.
1752 | Class "name" is in use by MODIFY CLASS.
1753 | Cannot load 32-bit DLL "name".
1754 | Cannot find entry point "name" in the DLL.
1755 | Cannot add an object to this class.
1756 | Member object removed – cannot complete the Save operation.
1757 | Property "name" is protected.
1758 | Cannot change property "name" in SetAll method.
1759 | Expression is invalid. Use a valid expression for "name" property.
1760 | Member "name" is a class member.
1761 | Class "name" already exists.
1762 | Class "name" is not found.
1763 | Property "name" already exists.
1764 | Array is not a member of the parent object.
1765 | Method contains syntax errors. Method is not saved.
1766 | Object "name" is not found.
1767 | Parent object will not allow this property setting for "name".
1768 | Cannot add this object to a Grid.
1769 | Cannot add this object to a Column.
1770 | Cannot clear class "class" because it is in use.
1771 | A member object with this name already exists.
1772 | You may not change the RecordSource of a BROWSE object.
1773 | Database object type is invalid.
1774 | No sheet is found.
1775 | Worksheet "name" is not found.
1776 | Class "name" is in use.
1777 | This command is not supported for views.
1778 | The table must be converted before appending.
1779 | Error adding "name" to the object. Duplicate member/property name.
1780 | This array element has been defined as an object and cannot be redefined in the class definition.
1781 | An object's control source cannot be set to its Value property.
1782 | This OLE property cannot be an expression.
1783 | Invalid class specified for @...Class command.
1784 | This object is derived from a base class and does not have a parent class.
1791 | Cannot find the text generation program.
1792 | Text generation is canceled.
1793 | The network request is not supported.
1794 | "name" cannot be enumerated.
1795 | Cannot arrange an untransported form.
1796 | No records are found for the current platform.
1797 | Error occurred in conversion.
1798 | Cannot find the converter program.
1799 | Conversion is canceled.

1800

1800 | SQL: Internal error.
1801 | SQL: Error correlating fields.
1802 | SQL: Cannot locate table.
1803 | SQL: HAVING clause is invalid.
1804 | SQL: Statement is invalid.
1805 | SQL: Too many subqueries.
1806 | SQL: Column "field | variable" is not found.
1807 | SQL: GROUP BY clause is invalid.
1808 | SQL: ORDER BY clause is invalid.
1809 | SQL: Out of memory.
1810 | SQL: Invalid use of subquery.
1811 | SQL: Aggregate on non-numeric expression.
1812 | SQL: Statement too long.
1813 | SQL: Use of UNION in subquery is invalid.
1814 | SQL: Queries of this type are not supported.
1815 | "cursor" must be created with SELECT ... INTO TABLE.
1818 | SQL: FROM clause is required.
1819 | SQL: DISTINCT is invalid.
1820 | SQL: SELECT contains invalid *.
1822 | SQL: Invalid aggregate field.
1825 | SQL: Subquery is invalid.
1826 | SQL: SELECT is invalid.
1828 | SQL: Illegal GROUP BY in subquery.
1830 | SQL: Index is not found.
1831 | SQL: Error building temporary index.
1832 | "field | variable" is not unique and must be qualified.
1833 | SQL: WHERE clause is invalid.
1834 | SQL: Too many UNIONs.
1839 | SQL: Operation was canceled.
1841 | SQL: Too many columns referenced.
1842 | SQL: Subquery nesting is too deep.
1844 | Cannot nest aggregate functions.
1845 | SQL expression is too complex.
1846 | Cannot GROUP by aggregate field.
1851 | SELECTs are not UNION compatible. "Details"
1860 | Subquery returned more than one record.
1864 | SQL: Too many fields in UPDATE.
1865 | SQL: Invalid SET expression in UPDATE.
1866 | SQL: Invalid TOP specification.
1867 | SQL: TOP requires an ORDER BY.
1870 | ALTER TABLE operation interrupted.
1871 | Cannot DROP all existing columns.
1872 | Too many columns.
1875 | Multiple warnings occurred performing the requested index modifications.
1877 | No rule to DROP.
1878 | No default value to DROP.
1879 | No primary key.
1880 | Related table is not found in current database.
1881 | Error loading file - record number n. "object" <or one of its members>. "Issue": "error".
1882 | Related tag is not found or not primary or candidate.
1883 | Primary key already exists.
1884 | Uniqueness of index "name" is violated.
1885 | Only structural tags can be defined as candidate.
1886 | Index does not accept NULL.
1887 | Illegal recursion in rule evaluation.
1888 | Tag name is too long.
1889 | A table in multiple relationships can only have one child order.
1890 | SQL: Cannot determine data type of SQL column "column".

1900

1903 | String is too long to fit.
1907 | Drive specifier is invalid.
1908 | Length or decimal place argument is invalid.
1909 | Cannot update project from project metafile.
1910 | Illegal printer driver recursion.
1911 | Localized product is required for this environment.
1912 | Operation is invalid for a General field.
1913 | Field must be a General field.
1914 | Code page number is invalid.
1915 | Collating sequence "name" is not found.
1916 | To use this feature, set CODEPAGE=AUTO in your CONFIG.FPW file and restart Visual FoxPro.
1917 | Script error: "name".
1918 | File name is too long.
1919 | Objects cannot be programmatically deleted from the Class Designer.
1922 | Volume does not exist.
1923 | Object "name" is not found.
1924 | "name" is not an object.
1925 | Unknown member "name".
1926 | Cannot nest class definitions.
1927 | Statement is not valid in a class definition.
1928 | Statement is only valid within a class definition.
1929 | "name" can only be used within a method.
1930 | Cannot redefine "name".
1931 | Statement is not in a procedure.
1932 | "name" cannot be closed while suspended.
1933 | File "name" is not closed.
1934 | Statement only valid within a method.
1935 | The current object does not inherit from class "name".
1936 | Application object not initialized.
1937 | Procedure file "name" is not found.
1938 | Object is not contained in a "name".
1939 | WITH/ENDWITH mismatch.
1940 | Expression is not valid outside of WITH/ENDWITH.
1941 | Error code is not valid.
1942 | Objects cannot be assigned to arrays.
1943 | Member "name" does not evaluate to an object.
1944 | Cannot find the builder program.
1945 | The current object has been released.
1946 | Project file "name" is in the wrong version.
1947 | Expression is too complex.
1948 | Cannot modify a class that is in use.
1949 | Class name is invalid.
1950 | Class definition "name" is recursive.
1951 | Cannot clear the object "object" because it is in use.
1952 | Cannot base a view on itself.
1953 | Feature is only available if the object is in design mode.
1954 | The builder program is already running.
1955 | WIN.INI/registry is corrupted.
1956 | Printer access denied.
1957 | Error accessing printer spooler.
1958 | Error loading printer driver.
1959 | Invalid coordinates.
1960 | Illegal redefinition of variable "name".
1961 | A subdirectory or file "name" already exists.
1962 | The directory is not empty.
1963 | Directory is not found.
1964 | No PageFrame or Page is found in FormSet or Form with WindowType set to READ or READ MODAL.
1965 | One of the members of this class is based on a nonvisual class. Cannot write .VCX file.
1966 | Data environment is already loaded.
1967 | Data environment is already unloaded.
1968 | One of the members of this Form or FormSet is based on a nonvisual class. Cannot write .SCX file.
1969 | The clipboard contained one or more objects that could not be added to the container. Those objects were not pasted.
1970 | Cannot reopen project file "name".
1971 | Cannot compile until the current COMPILE command has completed.
1972 | Array "name" is in use.
1973 | Error creating table: "name".
1974 | Arrays cannot be assigned to array elements.
1975 | Member object "name" has not been instantiated.
1976 | Cannot resolve backlink.
1977 | Exclusive open required to update this file. Please reopen.
1978 | Cannot visually modify a class of this type.
1979 | Cannot visually modify a class based on a nonvisual class.
1981 | Compile error in file "name".
1982 | The TO clause can only be used with modal Forms and FormSets.
1983 | "name" objects cannot return a value.
1984 | The fields in table '"name"' did not match the entries in the database.
1985 | Object already has a data environment; cannot use another one with the SaveAs method.
1986 | GDI memory is low, close one or more windows and try again.
1987 | Objects cannot be programmatically added to the Form Designer's FormSet.
1988 | Currency value is out of range.
1989 | Objects cannot be programmatically deleted from the Form Designer.
1991 | Form file "name" is from a previous version of FoxPro. It must be converted to the current format before it can be executed.
1992 | "name" is not a function, procedure or program.
1993 | Class library file "name" is not found.
1994 | Include file "name" is not found.
1995 | Error loading the data environment. Table is in use.
1996 | The validation rule for field "name" does not evaluate to a logical or NULL type.
1997 | The default value for field "name" does not evaluate to the correct type for the field.
1998 | The index expression for index "name" contains an invalid reference to a Memo, General, or Picture field.
1999 | Function is not implemented.

2000

2000 | Memory is low, so streaming output updating has been disabled.
2001 | The name of the object file for "file" is already used by another program in the project.
2002 | Cannot build a DLL without OLE public classes.
2003 | OLE Changed Properties stream is the wrong version. Subclassed properties ignored.
2004 | The table file "name" has moved. Please validate database "name" and try again.
2005 | Error with "name" - "property": "error".
2006 | Cannot locate your Web browser.
2007 | Invalid operation for offline view while offline.
2008 | Invalid operation for offline view while being used online.
2009 | Object is not an offline view.
2010 | Offline views must be used exclusively when being used online.
2011 | Invalid operation for offline view.
2012 | Cannot call SetFocus from within a When, Valid, RangeHigh or RangeLow event.
2013 | Cannot open persistent table buffer directly.
2014 | Fields marked as update keys will be cleared.
2015 | Offline view must be used online for this command
2016 | Removing a class member is not allowed.
2017 | Cannot reuse offline view in different mode.
2018 | Reconnect of offline view failed.
2019 | Cannot create offline view on a currently modified view.
2020 | The class file associated with this field cannot be found – class association cleared.
2021 | The DataObject cannot be modified in the OLEDragOver or OLEDragDrop event.
2022 | The specified file or path was not found.
2023 | There is no application associated with the given filename extension.
2024 | A sharing violation occurred.
2025 | The SQL Statement is too complex for the View/Query Designer.
2026 | Invalid locale ID.
2027 | Declare DLL call caused an exception.
2028 | API call caused an exception.
2029 | Class "name" is not a Form class.
2030 | Cannot delete file "name".
2031 | User-interface operation not allowed at this time.
2032 | Ambiguous date/datetime constant.
2033 | CTOD and CTOT can produce incorrect results.
2034 | Date/datetime evaluated to an invalid value.
2035 | Date/datetime contains illegal characters.
2036 | The current Help file is empty.
2038 | Microsoft Visual FoxPro doesn't support and cannot open this format of recordset.
2039 | Failed to create recordset.
2040 | Field mismatch.
2041 | Recordset does not exist.
2042 | Foxcode table not found, is not correct version or is incompatible.
2043 | Foxcode script "name" failure.
2044 | Textmerge is recursive.
2045 | Cannot set DBCEventFile property when DBCEvents is off.
2046 | Foxtask table is corrupted or not the correct version.
2047 | Invalid character entered.
2048 | Invalid COMATTRIB value for "name".
2049 | Error loading HtmlHelp 2.0 collection.
2050 | Help for this topic/context not implemented.
2051 | Menu item's conditional statement is too long.
2052 | OrderBy clause is too long.
2053 | GroupBy clause is too long.
2054 | Cannot release object.
2055 | Query Parse Error - Try rebuilding in Query Wizard or by using View Designer Join Tab.
2056 | The specified member class does not exist or is of wrong type.
2057 | The specified class library does not exist or does not contain a valid member class.
2058 | TRY/CATCH/FINALLY/ENDTRY mismatch or error.
2059 | Unhandled Structured Exception.
2060 | RETURN/RETRY statement not allowed in TRY/CATCH.
2061 | Index or expression does not match an existing member of the collection.
2062 | The specified Key already exists.
2063 | A Key must be specified when adding an item to this collection.
2064 | A Key cannot be specified when adding an item to this collection.
2065 | Table "name" has a file length / record number inconsistency.
2066 | Index file "file" is corrupted. Please rebuild it.
2067 | Cursor "name" does not have a valid table or view reference.
2068 | Data environment "name" does not contain a cursor object.
2069 | Forms or Form classes that specify a DEClass and DEClassLibrary cannot be converted to or used with a FormSet.
2070 | Cannot assign a class value to this member.
2071 | User Thrown Error.
2072 | Cursor cannot be modified because it contains an unsaved.
2073 | Cannot change MemberClass because existing member objects have outstanding references.
2074 | Result is incompatible with cursor schema.
2075 | CursorSchema property is not specified.
2076 | Operation is not allowed for CursorAdapter.
2077 | Operation is not allowed for CursorAdapter at this time.
2078 | CursorAdapter "name" cannot be loaded for design.
2079 | Cannot close or detach extended cursor because it is currently in design mode.
2080 | ADODB.Recordset is already opened.
2081 | ADODB.Command is already opened.
2082 | Cannot update ADODB.Recordset while cursor, created by CursorAdapter.CursorFill method, is not attached to a CursorAdapter object.
2083 | Cannot update ADODB.Recordset because it is read-only.
2084 | Cannot update ADODB.Recordset because it does not support a Bookmark property.
2085 | Cannot update ADODB.Recordset because FOX cursor does not have an ADOBookmark column.
2086 | DEClass cannot be loaded.
2087 | Window "name" is not a dockable window. (Error 2087)
2088 | Field "name" is read-only.
2089 | The "name" event has failed.
2090 | CursorAdapter does not have an associated cursor.
2091 | Table "name" has become corrupted. The table will need to be repaired before using again.
2092 | CursorAdapter cannot locate current record in the buffer. The record may have been reverted.
2093 | Syntax error: "name" is not allowed in the view script or is in the wrong place.
2094 | XML Schema is too complex.
2095 | XMLTable object does not have associated XMLAdapter object.
2096 | XML document is not loaded.
2097 | XMLTable object does not have associated fields.
2098 | Invalid element in XMLTable.Fields collection.
2099 | Value of XMLTable.XMLName must be used as key value for collection.

2100

2100 | Value of XMLField.XMLName must be used as key value for collection.
2101 | Unable to attach object with empty XMLName property.
2102 | Unable to change XMLName property while XMLTable object belongs to XMLAdapter object.
2103 | Unable to change XMLName property while XMLField object belongs to XMLTable object.
2104 | There is a duplicate table "name" in XML schema.
2105 | There is a duplicate field "name" in XML schema.
2107 | XMLAdapter.ToXML cannot be called while there is a loaded XML document.
2108 | XMLTable.Alias is empty.
2109 | XMLTable has child table.
2110 | XML Error: "error"
2112 | Cursor "name" is attached to another CursorAdapter object.
2116 | This feature requires MSXML4 SP1 or later.
2118 | XMLAdapter: fractionDigits must not be greater than or equal to maxLength.
2120 | Unable to infer XML schema.
2121 | Unable to open offline view in ADMIN/ONLINE mode inside a transaction.
2122 | Unable to close offline view in ADMIN/ONLINE mode inside a transaction.
2123 | Unable to set external schema location when inline schema is used.
2124 | XML document does not have a root element.
2125 | CursorAdapter and XMLTable objects do not belong to the same data session.
2126 | XML document is not a DiffGram.
2127 | XMLAdapter.XMLName is empty.
2128 | XML node does not belong to MSXML4.DOMDocument.
2129 | XMLAdapter object doesn't have associated tables.
2130 | XMLTable object with XMLName "name" does not have associated fields.
2131 | TEXT does not have corresponding ENDTEXT statement
2132 | XMLTable object already has parent or is associated with XMLAdapter object.
2133 | Unable to emit XML, two or more cursors use different code pages.
2134 | Value of XMLName, XMLNamespace or XMLPrefix property should be a Unicode string.
2135 | Conversion to Unicode has failed.
2136 | Conversion from Unicode has failed.
2137 | Vfp.VFPXMLProgId doesn't support cSchemaLocation parameter for XMLUpdateGram().
2138 | CursorAdapter is unable to determine DataSourceType for the operation.
2139 | SelectCmd is empty.
2140 | Both Unicode and IsBinary properties can not be set to .T..
2141 | Field size for Unicode value can not be odd number.
2142 | Field for Unicode value should not use code page translation.
2143 | ADODB.Recordset is not opened.
2144 | XMLField object is already associated with XMLTable object.
2145 | Property "name" has invalid value.
2146 | Invalid key column name "name".
2147 | Calling OpenTables or CloseTables is not allowed while either of those methods are in the process of executing.
2148 | SQL: The ORDER BY clause is invalid in subqueries, unless TOP is also specified
2149 | SQL: Invalid SET expression in UPDATE, "table name" is not a target table
2150 | SQL: Table for UPDATE or DELETE cannot be outer joined
2151 | SQL: Cannot UPDATE or DELETE from subquery
2152 | The Dockable property cannot be enabled possibly due to conflicting properties
2153 | Invalid collate sequence
2154 | Unknown member object "object name"
2155 | Number of affected rows is not available
2156 | Invalid index expression for a Binary index
2157 | Filter expression is not allowed for a Binary index
2158 | Unable to locate target record in ADODB.Recordset
2159 | Unable to cast NULL value to a NOT NULL data type
2160 | Invalid timestamp column name "column name"
2161 | Invalid Insert refresh column name "column name"
2162 | Invalid Insert refresh key column name "column name"
2163 | Invalid Update refresh column name "column name"
2164 | Invalid Update refresh key column name "column name"
2165 | The refresh key defined for table "table name" is not unique
2166 | The refresh key defined for table "table name" is not found
2167 | Source field for refresh is not found
2168 | Invalid data source type for RecordRefresh operation
2169 | Cannot refresh record from ADODB.Recordset because it does not support a Bookmark property
2170 | Cannot refresh record from ADODB.Recordset because FOX cursor does not have an ADOBookmark column
2171 | Invalid refresh ignore column name "column name"
2172 | Field "field name" is not fetched
2173 | Cursor "cursor name" is in use and cannot be closed
2174 | Field "field name" is not associated with a base table
2175 | CursorAdapter internal error
2176 | Connection "connection name" is in manual commit mode
2177 | Inner and outer XMLTable objects are not associated with the same XMLAdapter object
2178 | There is no relation to the nested table "table name".
2179 | Nested XML format is incompatible with 'Changes Only'
2180 | XMLAdapter XMLName property is an XPath expression
2181 | XMLTable XMLName property is an XPath expression
2182 | XMLName property contains illegal symbol(s)
2183 | Operation requires that SET MULTILOCKS is set to ON
2184 | Code page for the field "field name" doesn't match cursor's code page
2185 | Unable to infer cursor's code page from XML document
2186 | Error building sort key
2187 | Recursive XMLTable nesting is not allowed
2188 | Cursor doesn't support ADOBookmark property
2189 | SQL: Too many fields in final or intermediate result have the same name
2190 | FontCharSet number is invalid
2191 | File is in use in another data session
2192 | Illegal operation for a table with pending changes
2193 | Illegal operation in rule evaluation
2194 | Output page "page" is not available
2195 | The cursor is already associated with a record set
2196 | Only single SQL SELECT statement can be enclosed in parenthesis
2197 | Property "property name" value is too long
2198 | Index tag is not found for Cursor object "cursor name"
2199 | Error building key for index "name".

2200

2200 | Index "name" is in use and cannot be closed
2201 | Cannot determine data type of the expression

See Also

Other Resources

Error Messages
Error Messages A-Z
ERROR Command
ERROR( ) Function


Product Support (Visual FoxPro)

Visual FoxPro 9.0
Product Support (Visual FoxPro)

Learn more about Microsoft product support services options and copyright information.

In This Section

Microsoft Visual FoxPro Technical Support

Provides information about Microsoft product support services.
Copyright

Includes information about Microsoft copyright.

Related Sections

What's New in Visual FoxPro

Describes new features and enhancements made to this version of Visual FoxPro.
Installing Visual FoxPro

Describes requirements for installing this version of Visual FoxPro and explains how to install, customize, and start it.
Getting Started with Visual FoxPro

Describes how Visual FoxPro makes it possible for you to create state-of-the-art enterprise database solutions.
Upgrading from Earlier Versions

Describes how Visual FoxPro protects your investment in applications built in previous versions of FoxPro.
Optimizing Your System

Describes how to optimize your operating system, Visual FoxPro, or your application for maximum performance.
Microsoft Visual FoxPro Web Site

Describes additional information and resources for Visual FoxPro.


Microsoft Visual FoxPro Technical Support

Visual FoxPro 9.0
Microsoft Visual FoxPro Technical Support
See Also

Product Name

Microsoft Visual FoxPro

OEM distributed

If your product came installed with a new computer or device, the hardware manufacturer provides technical support and assistance for this software. Please contact your manufacturer directly for support.

Support Info Online

Microsoft Help and Support

TTY Users

Microsoft text telephone (TTY/TDD) services are available at (425) 635-4948 in Washington state or (800) 892-5234 in the U.S. Call (905) 568-9641 in Canada.

Worldwide

The support terms listed here are available in the United States and Canada only. Support elsewhere might vary. For regional contact information, please see the International Support list at http://support.microsoft.com/common/international.

If there is no Microsoft subsidiary office in your country or region, please contact the establishment from which you obtained your Microsoft product.

Conditions

Microsoft support services are subject to then-current prices, terms, and conditions, which can change without notice.

Professional Support Options

Advanced support for experts & businesses. Visit our http://support.microsoft.com/directory/customer.asp customized support sites for pay-per-incident assistance online http://support.microsoft.com/directory/directory/onlinesrpro.asp in the U.S. and phone http://support.microsoft.com/directory/directory/phonepro.asp in the U.S. by experts trained to assist business professionals. To advance-purchase support incidents, please call Professional Support Sales at (800) 936-3500. If you are calling from Canada, Professional support is available by calling (800) 805-4440 from 8:00 a.m. – 8:00 p.m. Monday – Friday Eastern Time.

Submit your incident online in the U.S.

  • http://support.microsoft.com/directory/directory/onlinesrpro.asp

Get additional information on our support offerings in the U.S.

  • Professional Support for Developers

  • Professional Support for IT Professionals

  • Professional Support for Value-Add Partners, Resellers, Consultants

  • Professional Support for Microsoft Certified Partners

  • Professional Support for OEMs

Submit your incident over the phone in the U.S.

  • Developers: (800) 936-5800

  • IT Professionals: (800) 936-4900

  • Partners (resellers/consultants): (888) 456-5570

  • Microsoft Certified Partners: (888) 677-9444

  • Original Equipment Manufacturers: (800) 936-2197

  • System Builders: (888) 456-5570

Advisory Services

Microsoft Advisory Services provides short-term advice and guidance for problems not covered by Problem Resolution Service as well as requests for consultative assistance for design, development, and deployment issues. Please see our Advisory Services support page for more information.

Premier Support

For larger organizations requiring managed support direct from Microsoft, contracts are also available through various Premier Support & Alliance Support offerings.

MSDN Support

Customers with MSDN subscriptions have the option to use any available MSDN incidents.

See Also

Other Resources

Product Support


Copyright

Visual FoxPro 9.0
Copyright
See Also

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2004 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows NT, Windows Server, Active Desktop, Active Directory, ActiveX, BackOffice, IntelliSense, JScript, Microsoft Office, Microsoft Press, Microsoft SQL Server, MSDN, MSN, OneNote, OpenType, Outlook, PivotTable, PowerPoint, Rushmore, Visual Basic, Visual C++, Visual C#, Visual FoxPro, Visual SourceSafe, Visual Studio, Windows Server System, Win32, and Win32s are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

See Also

Reference

Product Support (Visual FoxPro)


File is in use in another data session (Error 2191)

Visual FoxPro 9.0
File is in use in another data session (Error 2191)

This error is generated by the MAKETRANSACTABLE( ) function when a table for which you enable transactions has a cursor open in another data session.


Saving a converted form as a class is not supported (Error 1490)

Visual FoxPro 9.0
Saving a converted form as a class is not supported (Error 1490)

You have attempted to save a FoxPro 2.x converted screen as a class with the SaveAsClass method. This is not a valid operation.


Only structural tags can be defined as candidate (Error 1885)

Visual FoxPro 9.0
Only structural tags can be defined as candidate (Error 1885)

You have attempted to create a candidate key (as with INDEX ON ... CANDIDATE) that was either an IDX file or a tag in a CDX file other than the CDX file specified.

Create the candidate index in the structural CDX file.


SQL: Cannot determine data type of SQL column "column" (Error 1890)

Visual FoxPro 9.0
SQL: Cannot determine data type of SQL column "column" (Error 1890)

Visual FoxPro cannot determine the data type of the specified SQL column because the first record in the field contains a null value.


Cannot nest the PRINTJOB command (Error 1337)

Visual FoxPro 9.0
Cannot nest the PRINTJOB command (Error 1337)

After encountering a PRINTJOB command, an ENDPRINTJOB command was not found before another PRINTJOB command was encountered.


GDI memory is low, close one or more windows and try again (Error 1986)

Visual FoxPro 9.0
GDI memory is low, close one or more windows and try again (Error 1986)

Close all open applications and restart Windows on your computer.


File "name" is read-only (Error 1718)

Visual FoxPro 9.0
File "name" is read-only (Error 1718)

You have attempted to write to a read-only file.


Cannot access file "file"; transaction is in progress. (Error 1106)

Visual FoxPro 9.0
Cannot access file "file"; transaction is in progress. (Error 1106)

Visual FoxPro cannot access the table, index, or memo file because a transaction in progress is not yet complete.

FLOCK( ) and RLOCK( ) usually do not prevent other users from reading the locked information. This message, which scrolls from left to right to indicate that Visual FoxPro is still active, provides compatibility with the Novell transaction tracking system (TTS).


Too many arguments (Error 1230)

Visual FoxPro 9.0
Too many arguments (Error 1230)

A function call contains more than the permitted number of arguments.


NOWAIT/SAVE/NOENVIRONMENT/IN/WINDOW clauses are not allowed with the FROM clause (Error 1696)

Visual FoxPro 9.0
NOWAIT/SAVE/NOENVIRONMENT/IN/WINDOW clauses are not allowed with the FROM clause (Error 1696)

These clauses cannot be included when you create a quick report with the FROM clause.


No table is open in the current work area (Error 52)

Visual FoxPro 9.0
No table is open in the current work area (Error 52)

A table was not in use at the time Visual FoxPro attempted to execute a table command.

  • The current work area doesn't have an open table.

    Open a table or change work areas.


Number of affected rows is not available (Error 2155)

Visual FoxPro 9.0
Number of affected rows is not available (Error 2155)

This error is generated when a CursorAdapter Class cannot check for an update conflict because the data source doesn't return the number of affected rows.


Color set resource is not found (Error 1642)

Visual FoxPro 9.0
Color set resource is not found (Error 1642)

You have attempted to SET COLOR SET TO a color set not found in the current resource file. Verify the current resource file with SYS(2005).


Expression has been re-entered while the filter is executing (Error 1148)

Visual FoxPro 9.0
Expression has been re-entered while the filter is executing (Error 1148)

The expression in SET FILTER TO has been re-entered while the filter is executing. This can happen with complex setups involving SET RELATION or SET FILTER, or during the use of Visual FoxPro functions or user-defined functions which reference other work areas, such as LOOKUP( ) or SEEK( ).


GroupBy clause is too long. (Error 2053)

Visual FoxPro 9.0
GroupBy clause is too long. (Error 2053)

The GroupBy clause exceeds 256 characters. Try reducing the number of characters.


Connectivity internal consistency error (Error 1522)

Visual FoxPro 9.0
Connectivity internal consistency error (Error 1522)

Internal connectivity error.

If this error occurs, record your recent actions while using Visual FoxPro and then call Microsoft Support.


Too many READ commands are in effect (Error 1249)

Visual FoxPro 9.0
Too many READ commands are in effect (Error 1249)

The maximum nesting level for the READ command (5) in effect has been exceeded.


"name" cannot be closed while suspended (Error 1932)

Visual FoxPro 9.0
"name" cannot be closed while suspended (Error 1932)

Issue either RESUME or CANCEL for the stored procedure before re-attempting this operation.


Unhandled Structured Exception (Error 2059)

Visual FoxPro 9.0
Unhandled Structured Exception (Error 2059)

An unhandled exception can occur under the following conditions:

  • An error that occurred or exception that was thrown in a TRY, CATCH, or FINALLY block was not caught by a structured error handler such as TRY...CATCH...FINALLY.

  • A structured error handler did not catch a thrown exception that occured outside a TRY...CATCH...FINALLY structure.

You can catch an unhandled structured exception using the following unstructured exception handlers:

  • ON ERROR Command

  • Error Event

  • Visual FoxPro system handler

For each of these error handlers, the error number returned by the ERROR( ) function is 2059. Visual FoxPro provides details about the original error. You can also obtain additional information about the original error that caused the unhandled exception from the SYS(2018) - Error Message Parameter, MESSAGE( ), and AERROR( ) functions. The SYS(2018) function returns the same value as the third element in the array returned by the AERROR( ) function. The MESSAGE( ) function returns the same value as the second element in the array returned by AERROR( ).

If the unhandled exception was caused by a THROW statement, the value of SYS(2018) is 2071, or User Thrown Error.


Conversion canceled. Adjust the memo BLOCKSIZE (Error 1509)

Visual FoxPro 9.0
Conversion canceled. Adjust the memo BLOCKSIZE (Error 1509)

You are trying to convert a dBASE table with a memo blocksize less than 512K.

To successfully convert the file for Visual FoxPro, go back to dBASE and adjust the memo blocksize to greater than, or equal to, 512K.


"name" is not a valid resource file (Error 1294)

Visual FoxPro 9.0
"name" is not a valid resource file (Error 1294)

A resource file is corrupted. By default, your resource file is FoxUser (FoxUser.dbf and FoxUser.fpt).

  • FoxUser.dbf, FoxUser.fpt, or one of your default resource files is corrupted.

    Restore your resource files from backup, or exit Visual FoxPro, delete the resource files, and then restart Visual FoxPro.

    To check your default resource file, see the File Locations tab of the Options dialog box or use the SET RESOURCE command.


vfp.VFPXMLProgId doesn't support cSchemaLocation parameter for XMLUpdateGram(). (Error 2137)

Visual FoxPro 9.0
vfp.VFPXMLProgId doesn't support cSchemaLocation parameter for XMLUpdateGram(). (Error 2137)

Occurs when Visual FoxPro attempts to use the cSchemaLocation parameter in a custom implementation of XMLUpdateGram with the vfp.VFPXMLProgid. Visual FoxPro does not allow the use of the cSchemaLocation parameter in custom implementations.

  • If the cSchemaLocation parameter is required in your custom implementation of XMLUpdateGram, add the value to the schema via your own implementation.


Index does not accept NULL (Error 1886)

Visual FoxPro 9.0
Index does not accept NULL (Error 1886)

Your key index expression evaluated to NULL, which is an invalid value an index. This can often happen with a primary or candidate keys.

Change record values so the expression does not evaluate to NULL.


Command contains unrecognized phrase/keyword (Error 36)

Visual FoxPro 9.0
Command contains unrecognized phrase/keyword (Error 36)

A phrase beginning with an invalid keyword was used in a command line.


Internal consistency error (Error 1000)

Visual FoxPro 9.0
Internal consistency error (Error 1000)

Record your recent actions while using Visual FoxPro and then call Microsoft Support.


CANCEL or SUSPEND is not allowed (Error 1651)

Visual FoxPro 9.0
CANCEL or SUSPEND is not allowed (Error 1651)

The dBASE IV report or label file you are running calls a SUSPEND. This is not a valid operation in Visual FoxPro.


Database is read-only (Error 1570)

Visual FoxPro 9.0
Database is read-only (Error 1570)

Commands such as VALIDATE DATABASE and those involving creation or modification of database objects require writing to the database.

Close the database and re-open it with writable access.


Class cannot be instantiated because member "name" does not exist (Error 1441)

Visual FoxPro 9.0
Class cannot be instantiated because member "name" does not exist (Error 1441)

The IMPLEMENTS clause in the DEFINE CLASS command uses a member not included in the definition for the class. For more information, see DEFINE CLASS Command.


Cannot clear class "class" because it is in use. (Error 1770)

Visual FoxPro 9.0
Cannot clear class "class" because it is in use. (Error 1770)

The class specified cannot be deleted from a .vcx library file while the class definition is in use. This error can occur when using the REMOVE CLASS command, the OVERWRITE clause of the ADD CLASS command, or the RENAME CLASS command.

  • Issue CLEAR ALL to remove all references to the class and try again.


Missing #ENDIF (Error 1724)

Visual FoxPro 9.0
Missing #ENDIF (Error 1724)

You have issued an #IF command without a matching #ENDIF.


Syntax error in the field expression (Error 1242)

Visual FoxPro 9.0
Syntax error in the field expression (Error 1242)

There is an invalid expression involving a field.


Primary key already exists (Error 1883)

Visual FoxPro 9.0
Primary key already exists (Error 1883)

You have attempted to use the ADD PRIMARY KEY clause of the ALTER TABLE command on a table that already has a primary key.

Remove the existing primary key first.


Textmerge is recursive. (Error 2044)

Visual FoxPro 9.0
Textmerge is recursive. (Error 2044)

The textmerge statement evaluates to an expression that, itself, performs a textmerge.


Index or expression does not match an existing member of the collection. (Error 2061)

Visual FoxPro 9.0
Index or expression does not match an existing member of the collection. (Error 2061)

The index or expression provided does not match any of those that correspond to a member in the collection. Make sure you provide a valid index or expression for an existing member.


The current object does not inherit from class "name" (Error 1935)

Visual FoxPro 9.0
The current object does not inherit from class "name" (Error 1935)

You have specified a class name that is not in the inheritance hierarchy of the current object.


A subdirectory or file "name" already exists (Error 1961)

Visual FoxPro 9.0
A subdirectory or file "name" already exists (Error 1961)

You have chosen a name that already exists.


Fatal error nExpr reporting error nExpr.

Visual FoxPro 9.0
Fatal error nExpr reporting error nExpr.

No error number is returned. Visual FoxPro closes all open files and exits.

Record your recent actions while using Visual FoxPro and then call Microsoft Support.


SQL: Error building temporary index (Error 1831)

Visual FoxPro 9.0
SQL: Error building temporary index (Error 1831)

A temporary index could not be built, possibly due to insufficient disk space.


Invalid coordinates (Error 1959)

Visual FoxPro 9.0
Invalid coordinates (Error 1959)

Coordinate values must be greater than -32768 and less than 32767.


Text generation is canceled (Error 1792)

Visual FoxPro 9.0
Text generation is canceled (Error 1792)

The text generation program, SCCTEXT.PRG (or the program whose value is stored in the _SCCTEXT system variable), has been halted.

  • You pressed the ESC key.

    The program was creating text versions of project files to check into source control. Avoid pressing ESC while checking files in.


Report contains a nesting error (Error 1645)

Visual FoxPro 9.0
Report contains a nesting error (Error 1645)

A user-defined function in a report form has called REPORT FORM.


Cannot change MemberClass because existing member objects have outstanding references (Error 2073)

Visual FoxPro 9.0
Cannot change MemberClass because existing member objects have outstanding references (Error 2073)

An attempt was made to change the MemberClass of an existing container object when there were still outstanding references to some of the objects in the MemberClass object.


Width or decimal place argument is invalid (Error 1908)

Visual FoxPro 9.0
Width or decimal place argument is invalid (Error 1908)

Either the length or decimal argument was invalid in the STR( ) function.

The sum of the specified left margin and paragraph indent exceeds the right margin.


Error accessing printer spooler (Error 1957)

Visual FoxPro 9.0
Error accessing printer spooler (Error 1957)

An internal call to the GetPrinter( ) function has failed. Visual FoxPro calls this function through either PRTINFO( ) or SET PRINTER TO.


Array "name" is in use (Error 1972)

Visual FoxPro 9.0
Array "name" is in use (Error 1972)

An object attempted to resize the array that contains it.


Expression is too complex (Error 1947)

Visual FoxPro 9.0
Expression is too complex (Error 1947)

Your index expression is too long. The maximum number of characters allowed in an .IDX index key is 100. The maximum number of characters allowed in a .CDX index key is 240.


Length of variable strings exceeds amount of memory (Error 21)

Visual FoxPro 9.0
Length of variable strings exceeds amount of memory (Error 21)

The combined length of all variable strings has exceeded the amount of memory.


CTOD and CTOT can produce incorrect results. (Error 2033)

Visual FoxPro 9.0
CTOD and CTOT can produce incorrect results. (Error 2033)

This error occurs for the same reasons as error 2032, but CTOD( ) and CTOT( ) may be non-compliant or ambiguous.


The selected printer driver does not support direct access (Error 1524)

Visual FoxPro 9.0
The selected printer driver does not support direct access (Error 1524)

The printer you have selected and set through your operating system does not allow direct access. You can try the Generic/Text Only driver, or the equivalent, in Windows. Bear in mind that the "ASCII File" option in Visual FoxPro bypasses the printer driver and sends the contents of the selected file directly to the printer. You are responsible for making sure that any file sent in this manner contains valid printer commands, and/or that an appropriate driver is selected.


The table must be converted before appending (Error 1778)

Visual FoxPro 9.0
The table must be converted before appending (Error 1778)

You have attempted to use the APPEND FROM command on a table that was not created with Visual FoxPro.

Back up your original file and convert a copy of the table for use with Visual FoxPro.


No key columns specified for the update table "name". Use the KeyFieldList property of the cursor (Error 1492)

Visual FoxPro 9.0
No key columns specified for the update table "name". Use the KeyFieldList property of the cursor (Error 1492)

No key column(s) have been specified in the KeyFieldList property for a base table that is being updated.

Modify the KeyFieldList property to include key columns for each table that is being updated. The key fields also need to be included in the UpdateNameList property. For most views, you can use the View Designer to set the view update properties and then save the view back into the database. For more information, see CURSORGETPROP( ).


ADODB.Recordset is not opened. (Error 2143)

Visual FoxPro 9.0
ADODB.Recordset is not opened. (Error 2143)

Visual FoxPro requires that an ADO Recordset is opened when it is passed to the CursorFill methods Source parameter.

  • Make sure that the ADO Recordset has been properly opened and that the ADO Recordsets State is set to adStateOpen (1).


Operation requires that SET MULTILOCKS is set to ON (Error 2183)

Visual FoxPro 9.0
Operation requires that SET MULTILOCKS is set to ON (Error 2183)

This error is generated when Visual FoxPro attempts to generate a value for an autoincremented field. To autoincrement a field, the table or current record must be locked, or SET MULTILOCKS Command must be set to ON.


Cyclic relation (Error 44)

Visual FoxPro 9.0
Cyclic relation (Error 44)

A circular relationship was attempted by defining a sequence of relations that eventually points back to a table that is already related.


"file" is not an object file (Error 1309)

Visual FoxPro 9.0
"file" is not an object file (Error 1309)

An attempt was made to load a compiled Visual FoxPro program that doesn't have a proper header.

  • Verify the name of the file you are trying to run using DO Command.


No update tables are specified. Use the Tables property of the cursor (Error 1491)

Visual FoxPro 9.0
No update tables are specified. Use the Tables property of the cursor (Error 1491)

No base tables are specified in the Tables property of the view.

Set the Tables property to specify the base table or tables that should be updated from the view. For most views you can use the View Designer to set the view update properties and then save the view back into the database. For more information, see CURSORGETPROP( ) Function.


Printer access denied (Error 1956)

Visual FoxPro 9.0
Printer access denied (Error 1956)

An internal call to the OpenPrinter( ) function has failed. Visual FoxPro calls this function through either PRTINFO( ) or SET PRINTER TO.


File "name" is too large (Error 1190)

Visual FoxPro 9.0
File "name" is too large (Error 1190)

The file is too large to be modified.

  • The file is larger than 2 GB.

    Use another method to reduce the file size, and then try again.


Database is invalid. Please validate (Error 1561)

Visual FoxPro 9.0
Database is invalid. Please validate (Error 1561)

Visual FoxPro has detected a problem with the structure of the database.

Try running VALIDATE DATABASE to diagnose or repair the problem.


Unrecognized command verb (Error 16)

Visual FoxPro 9.0
Unrecognized command verb (Error 16)

A word used at the beginning of the command line was not a valid Visual FoxPro command. For more information, see Reserved Words.


Warning: The query timeout cannot be set (Error 1482)

Visual FoxPro 9.0
Warning: The query timeout cannot be set (Error 1482)

The connection query timeout cannot be set by the ODBC driver. The connection will use the default driver defined query timeout.


Cannot close or detach extended cursor because it is currently in design mode. (Error 2079)

Visual FoxPro 9.0
Cannot close or detach extended cursor because it is currently in design mode. (Error 2079)

This occurs if the cursor in the system data session is inadvertently closed.


SQL: Internal error (Error 1800)

Visual FoxPro 9.0
SQL: Internal error (Error 1800)

An internal error has occurred.

Record your recent actions while using Visual FoxPro and then call Microsoft Support.


XML Error: "error" (Error 2110)

Visual FoxPro 9.0
XML Error: "error" (Error 2110)

Occurs when an error is called from the MSXML object, while attempting to load or attach XML.


ENDTEXT does not have corresponding TEXT statement (Error 1214)

Visual FoxPro 9.0
ENDTEXT does not have corresponding TEXT statement (Error 1214)

An ENDTEXT statement is missing a corresponding TEXT statement.


An IF | ELSE | ENDIF statement is missing (Error 1211)

Visual FoxPro 9.0
An IF | ELSE | ENDIF statement is missing (Error 1211)
See Also

A portion of the statement is either missing or misplaced. Check for a mismatched use of IF … ENDIF within another control statement.

The following example fails because ENDIF is placed within the DO CASE....ENDCASE statement.

IF .T.

   DO CASE

      CASE .T.

ENDIF

   ENDCASE

For more information about executing commands conditionally, see the IF ... ENDIF Command.

See Also

Reference

IF ... ENDIF Command


Object already has a data environment; cannot use another one with the SaveAs method (Error 1985)

Visual FoxPro 9.0
Object already has a data environment; cannot use another one with the SaveAs method (Error 1985)

You cannot specify another data environment with the SaveAs method.


Objects cannot be programmatically deleted from the Form Designer (Error 1989)

Visual FoxPro 9.0
Objects cannot be programmatically deleted from the Form Designer (Error 1989)

You have attempted to programmatically delete forms from the Form Designer form set. This cannot be done.


Database "name": File access denied (Error 1569)

Visual FoxPro 9.0
Database "name": File access denied (Error 1569)

You have attempted to write to a write-protected database container (.dbc) file.


File already exists (Error 7)

Visual FoxPro 9.0
File already exists (Error 7)

The file name you have attempted to rename already exists. This error is usually generated by the RENAME command.


Window specified in DEFINE WINDOW has invalid coordinates (Error 332)

Visual FoxPro 9.0
Window specified in DEFINE WINDOW has invalid coordinates (Error 332)

An attempt was made to define a window's coordinates outside the allowable range.


Cannot change modality of a visible form (Error 1573)

Visual FoxPro 9.0
Cannot change modality of a visible form (Error 1573)

The nStyle parameter of the Show method cannot be changed while a form is visible.

  • You are calling a form's Show method with a parameter while the form is visible.

    Change the modality of the form while it is not visible by using code similar to the following:

    Copy Code
    Form1.Hide
Form1.Show(nStyle)


Cannot build without a main program (Error 1689)

Visual FoxPro 9.0
Cannot build without a main program (Error 1689)

The main program in the specified project cannot be found or has not been set.

  • Projects must have a main program.

    For more information, see Set Main on the Project menu.


Unable to process error.

Visual FoxPro 9.0
Unable to process error.

No error number is returned. Visual FoxPro closes all open files and exits.

Record your recent actions while using Visual FoxPro and then call Microsoft Support.


SQL: Illegal GROUP BY in subquery (Error 1828)

Visual FoxPro 9.0
SQL: Illegal GROUP BY in subquery (Error 1828)

When using one of the six operators +, -, *, /, < and >, there can be only one row of output. For more information, see SELECT - SQL Command.


You may not change the RecordSource of a BROWSE object (Error 1772)

Visual FoxPro 9.0
You may not change the RecordSource of a BROWSE object (Error 1772)

The browse object must remain aligned with its table.

  • You tried to change the RecordSource property programmatically.

    To browse a different table, close the current browse and browse the new table. For more information, see BROWSE Command or RecordSource Property.


There is a duplicate field "name" in XML schema. (Error 2105)

Visual FoxPro 9.0
There is a duplicate field "name" in XML schema. (Error 2105)

Visual FoxPro does not allow schemas to define more than one field with the same name.

  • Make sure the XML source returns the XML in a correct and expected format.

  • Correct the supplied schema and XML document.


Menu was not pushed (Error 279)

Visual FoxPro 9.0
Menu was not pushed (Error 279)

An attempt has been made to pop a menu or popup that was not pushed.


Offline views must be used exclusively when being used online (Error 2010)

Visual FoxPro 9.0
Offline views must be used exclusively when being used online (Error 2010)

Use the EXCLUSIVE clause together with the ONLINE clause to access the offline view. For more information, see USE Command.


Cannot create file "file" (Error 102)

Visual FoxPro 9.0
Cannot create file "file" (Error 102)

The operating system cannot create the specified file for the following possible reasons:

  • The disk or directory is full.

    Remove files and try again.

  • You do not have access to the target directory.

    Check your permission level.

  • You specified an invalid file name.

    Check for typing mistakes.


"name" can only be used within a method (Error 1929)

Visual FoxPro 9.0
"name" can only be used within a method (Error 1929)

One of the following commands was used outside of a method: THIS, THISFORM, or THISFORMSET.

  • You used the statement in a procedure, but it can only be used within a method.

    Move the THIS, THISFORM, or THISFORMSET command into the appropriate method.


ODBC entry point missing, "name" (Error 1528)

Visual FoxPro 9.0
ODBC entry point missing, "name" (Error 1528)

The entry point for the specified function is not found in the ODBC32 dynamic-link library. The file ODBC32.DLL is invalid.

Reinstall the ODBC component of Visual FoxPro.


Cannot close this database because it is being used by a project (Error 1535)

Visual FoxPro 9.0
Cannot close this database because it is being used by a project (Error 1535)

You have attempted to close a database container that a project is using to display data.

  • The database must remain open while the project is open.

    Leave the database open, or close the project.


Record validation rule is violated (Error 1583)

Visual FoxPro 9.0
Record validation rule is violated (Error 1583)

The operation you have attempted is in violation of a record validation rule.

Fix the record values or revert the record.


Menu specified in ACTIVATE MENU is already in use (Error 181)

Visual FoxPro 9.0
Menu specified in ACTIVATE MENU is already in use (Error 181)

You have attempted to activate a menu that is already active.


Class "name" is in use by MODIFY CLASS (Error 1752)

Visual FoxPro 9.0
Class "name" is in use by MODIFY CLASS (Error 1752)

You have attempted to use a class that is currently being edited in the Class Designer.


Empty Index Entry

Visual FoxPro 9.0
Empty Index Entry

The index entry you selected has no target topics associated with it.

For help on this entry, please choose one of this entry's child items.


Warning: The key defined by the KeyField property for table "alias" is not unique (Error 1495)

Visual FoxPro 9.0
Warning: The key defined by the KeyField property for table "alias" is not unique (Error 1495)

The key specified for this table changed more than one row in the base table for some of the remote view rows being updated.

Redefine the key using the KeyField view property.


Function requires row or table buffering mode (Error 1586)

Visual FoxPro 9.0
Function requires row or table buffering mode (Error 1586)

The function you have attempted call is only enabled for cursors with row or table buffering enabled. Set the Buffering property to 2, 3, 4, or 5 with CURSORSETPROP( ) to enable row or table buffering.


Tag name is too long (Error 1888)

Visual FoxPro 9.0
Tag name is too long (Error 1888)

Tag names cannot exceed 10 characters.


Cannot update ADODB.Recordset because it does not support a Bookmark property. (Error 2084)

Visual FoxPro 9.0
Cannot update ADODB.Recordset because it does not support a Bookmark property. (Error 2084)

Occurs when the supplied ADO Recordset does not support bookmarks. This is data source dependent.

  • Make sure the ADO Recordset is configured to support updates.


Tab stops must be in ascending order (Error 228)

Visual FoxPro 9.0
Tab stops must be in ascending order (Error 228)

The tab stops defined for the system variable _TABS must be in ascending order.


File name is too long (Error 1918)

Visual FoxPro 9.0
File name is too long (Error 1918)

The name of the file exceeds current system capacities.


Subquery returned more than one record (Error 1860)

Visual FoxPro 9.0
Subquery returned more than one record (Error 1860)

Subqueries linked with the six normal operators <>, =, <=, >=, < or >, excluding ALL or ANY, can produce only a one-row result.


There is no application associated with the given filename extension. (Error 2023)

Visual FoxPro 9.0
There is no application associated with the given filename extension. (Error 2023)

The file that you attempted to drop in an OLE drag-and-drop operation doesn't have an application associated with it.


Illegal recursion in rule evaluation (Error 1887)

Visual FoxPro 9.0
Illegal recursion in rule evaluation (Error 1887)

A rule or trigger code caused the original cursor, the cursor from which the rule or trigger was fired, to try to evaluate a rule or trigger recursively. This can occur under the following conditions:

  • Attempting to move the record pointer or change values in the original cursor.

  • Attempting to move the record pointer in the BeforeUpdate event for a CursorAdapter object.

Check your rule or trigger code.


No such menu or menu item is defined (Error 1612)

Visual FoxPro 9.0
No such menu or menu item is defined (Error 1612)

The values passed to a READ MENU TO or READ MENU BAR TO command do not correspond to a defined menu or menu item.


Icon is corrupt or in wrong format (Error 1167)

Visual FoxPro 9.0
Icon is corrupt or in wrong format (Error 1167)

An invalid icon (.ICO) file was encountered during BUILD EXE.


Reconnect of offline view failed (Error 2018)

Visual FoxPro 9.0
Reconnect of offline view failed (Error 2018)

The view cannot be reconnected as an online view: one of the components of the view is not available or missing. For example, a base table for the view might be locked exclusively or be missing, or the database container (.dbc) file might be missing.


Class definition "name" is not found (Error 1733)

Visual FoxPro 9.0
Class definition "name" is not found (Error 1733)

The class definition specified in a CREATEOBJECT( ) function cannot be located.


File access is denied (Error 1705)

Visual FoxPro 9.0
File access is denied (Error 1705)

You have attempted to write to a file that is write-protected or open exclusively by another.


Error reading the resource (Error 1296)

Visual FoxPro 9.0
Error reading the resource (Error 1296)

An internal Visual FoxPro error has occurred.

Record your recent actions while using Visual FoxPro and then call Microsoft Support.


"name" is a method, event, or object (Error 1737)

Visual FoxPro 9.0
"name" is a method, event, or object (Error 1737)

name cannot store a value because it is not a property

  • Only properties can store values.

    Verify the property names for the object you are working with (see its Help topic), and then use one of the existing properties or define your own in the New Property dialog box.


Recursive macro definition (Error 1206)

Visual FoxPro 9.0
Recursive macro definition (Error 1206)

The maximum number of macro substitutions (256 in any one statement) has been performed in the current line.

  • A macro references itself.


Warning: The connection packet size cannot be set (Error 1483)

Visual FoxPro 9.0
Warning: The connection packet size cannot be set (Error 1483)

The connection packet size cannot be set by the ODBC driver. The connection will use the default driver defined packet size. This might affect performance on this connection.

Check the driver and network documentation for alternative ways to set up the network packet size.


No rule to DROP (Error 1877)

Visual FoxPro 9.0
No rule to DROP (Error 1877)

You have attempted to use the DROP CHECK clause of the ALTER TABLE command on a column (or table) with no rule. This is not a valid operation.


Microsoft Excel file format is invalid (Error 1661)

Visual FoxPro 9.0
Microsoft Excel file format is invalid (Error 1661)

The Microsoft Excel file you have attempted to import is either not version 5.0 or has been corrupted.


Invalid call issued while executing a SQLTABLES( ) sequence (Error 1476)

Visual FoxPro 9.0
Invalid call issued while executing a SQLTABLES( ) sequence (Error 1476)

An invalid SQL pass-through (SPT) function call has been made while a SQLTABLES( ) call was expected to continue the SPT call sequence in progress.

Call SQLCANCEL( ) to cancel the SPT sequence or make valid SPT calls to finish the call sequence.


One of the members of this class is based on a nonvisual class. Cannot write .VCX file (Error 1965)

Visual FoxPro 9.0
One of the members of this class is based on a nonvisual class. Cannot write .VCX file (Error 1965)

You have included a non-visual class in your class definition.

Remove it and try again.


Queue "queue" is not found (Error 1716)

Visual FoxPro 9.0
Queue "queue" is not found (Error 1716)

The queue specified in the SET PRINTER TO command cannot be found.


Index tag is not found (Error 1683)

Visual FoxPro 9.0
Index tag is not found (Error 1683)

The tag you have specified could not be found in the index.

Verify the TAG clause of your command.


CursorAdapter and XMLTable objects do not belong to the same data session. (Error 2125)

Visual FoxPro 9.0
CursorAdapter and XMLTable objects do not belong to the same data session. (Error 2125)

Occurs when a CursorAdapter object and an XMLTable are created in different data sessions.

  • Make sure that the CursorAdapter object and the XMLTable are created in the same data session before they are used together.


Cannot issue the PACK command on a database while its objects have open cursors (Error 1566)

Visual FoxPro 9.0
Cannot issue the PACK command on a database while its objects have open cursors (Error 1566)

Close all database tables before issuing the PACK command.


SQL: Too many fields in final or intermediate result have the same name (Error 2189)

Visual FoxPro 9.0
SQL: Too many fields in final or intermediate result have the same name (Error 2189)

Final or intermediate result sets cannot have more than 26 fields with the same name.


CursorSchema property is not specified. (Error 2075)

Visual FoxPro 9.0
CursorSchema property is not specified. (Error 2075)

If the data environment contains a cursor adapter, but the cursor adapter does not contain valid data in CursorSchema property, the Data Environment Designer does not open.

  • Check that the cursor adapter's CursorSchema property contains valid data.


Error code is not valid (Error 1941)

Visual FoxPro 9.0
Error code is not valid (Error 1941)

The input to the ERROR command is not recognized.


Field must be a Memo field (Error 350)

Visual FoxPro 9.0
Field must be a Memo field (Error 350)

You have attempted to enter a field name that is not a Memo field type with the APPEND or COPY MEMO command.


Paradox file format is invalid (Error 1688)

Visual FoxPro 9.0
Paradox file format is invalid (Error 1688)

The Paradox file you have attempted to import is either not version 3.5 or has been corrupted.


Structure is invalid (Error 1235)

Visual FoxPro 9.0
Structure is invalid (Error 1235)

In CREATE FROM, a table was specified whose structure does not match the STRUCTURE EXTENDED format.


Must be a character or numeric key field (Error 1145)

Visual FoxPro 9.0
Must be a character or numeric key field (Error 1145)

The key field used to UPDATE ON must be of type Character, Date or Numeric.


Object name is invalid (Error 1575)

Visual FoxPro 9.0
Object name is invalid (Error 1575)

You have specified a name for a member object in the AddObject method that is invalid.

Check the name and try again.


Application object not initialized (Error 1936)

Visual FoxPro 9.0
Application object not initialized (Error 1936)

The Automation server or type library is not registered correctly.

  • Your registry file is corrupted.

    Remove the registry entry.


Insufficient stack space (Error 1308)

Visual FoxPro 9.0
Insufficient stack space (Error 1308)

One of the following has occurred:

  • Your program is too recursive.

  • Your program is too complex and is nested too deeply.

  • An error in Visual FoxPro.


This command is not supported for views (Error 1777)

Visual FoxPro 9.0
This command is not supported for views (Error 1777)

Views cannot be changed with this command. This error has the following causes and solutions:

  • Using one of the following commands to change view structure: ALTER TABLE, CREATE TRIGGER, DELETE TRIGGER, and MODIFY STRUCTURE.

    Use a command that operates on views, or use a table instead.

  • Modifying the structure of a view cursor with the Table Designer.

    Use the View Designer to permanently modify the structure of cursors produced with a view definition.


Maximum number of OLE arguments is exceeded (Error 1431)

Visual FoxPro 9.0
Maximum number of OLE arguments is exceeded (Error 1431)

You have specified more arguments for an Automation method than is allowed in Visual FoxPro.

Call the method with fewer than 64 arguments.


Data environment is already unloaded (Error 1967)

Visual FoxPro 9.0
Data environment is already unloaded (Error 1967)

The form is attempting to close tables as it shuts down.

  • AutoCloseTables is set to true (.T.).

    Don't programmatically close the data environment tables.

  • The CloseTables method is being called before the form is closed.

    Set AutoCloseTables to false (.F.).


Cannot update ADODB.Recordset because FOX cursor does not have an ADOBookmark column. (Error 2085)

Visual FoxPro 9.0
Cannot update ADODB.Recordset because FOX cursor does not have an ADOBookmark column. (Error 2085)

Visual FoxPro requires that a cursor is associated with an ADO Recordset, if it is to be used to update an ADO Recordset.

  • To verify a cursor is associated with an ADO Recordset check its SourceType property by using the CursorGetProp( ) function. Valid values for the SouceType property are 4, 104, and 204.


Table "alias" has one or more non-structural indexes open. Please close them and retry the Begin Transaction (Error 1548)

Visual FoxPro 9.0
Table "alias" has one or more non-structural indexes open. Please close them and retry the Begin Transaction (Error 1548)

Close all non-structural (non-.CDX) indexes and try the operation again.

If other indexes are open on the file, their writes will go directly to disk and will not be reflected in the table changes until you issue END TRANSACTION. Consequently, if a ROLLBACK is issued, the non-structural indexes will be incorrect.


"field" phrase is not found (Error 1130)

Visual FoxPro 9.0
"field" phrase is not found (Error 1130)

This error might occur under the following conditions:

  • The PROMPT field clause in a command references an unknown field or a field that is not found.

  • An invalid value is specified by the RowSource property of a ComboBox or ListBox control.


Key exceeds allowed size (Error 1124)

Visual FoxPro 9.0
Key exceeds allowed size (Error 1124)

The compiled version of the index expression has exceeded 150 bytes.


Error saving the OLE object (Error 1422)

Visual FoxPro 9.0
Error saving the OLE object (Error 1422)

There is not enough disk space or resources available to save the object.


Error loading file - record number n. "object" <or one of its members>. "Issue": "error" (Error 1881)

Visual FoxPro 9.0
Error loading file - record number n. "object" <or one of its members>. "Issue": "error" (Error 1881)

An error occurred while attempting to read in a form (.scx) or class (.vcx) file. Issue relates to either "Properties," "Methods," or "User Properties."

To resolve the error:

  1. To access the record referenced in the error, open the form or class as a table as follows:

    Copy Code
    USE myform.scx
  2. To move to that record, use the GO command.

You can often find the cause of the error in the Properties, Methods, Class, Classloc, Objname, or Parent fields.

Note:
You should make a backup copy of your form and class file before modifying the contained records and fields directly.


The name "name" is already used for another object. Please choose a different name (Error 1571)

Visual FoxPro 9.0
The name "name" is already used for another object. Please choose a different name (Error 1571)

No two top-level objects in the database can have the same database name.

Use DISPLAY DATABASE to see a list of all the objects in the database.


No menu items have been defined for this menu (Error 166)

Visual FoxPro 9.0
No menu items have been defined for this menu (Error 166)

You must define menu item bars for each menu.


The specified Key already exists. (Error 2062)

Visual FoxPro 9.0
The specified Key already exists. (Error 2062)

The specified key exists for a member in the collection. Try using a different key. Keys are case-sensitive, so you can use a key that has different casing.


Record is too long (Error 1126)

Visual FoxPro 9.0
Record is too long (Error 1126)

While attempting to create a table file, the maximum length for the data portion of a record (65,500 bytes) was exceeded. The length of the data portion of a record is equal to the sum of the lengths of the individual record fields.


Cannot clear the object "object" because it is in use. (Error 1951)

Visual FoxPro 9.0
Cannot clear the object "object" because it is in use. (Error 1951)

Method or event code is currently running for the object. This message can also occur when attempting to remove class definitions from memory with the CLEAR ALL command.

  • Interrupt the running code or wait until it completes before clearing memory.


CursorAdapter cannot locate current record in the buffer. The record may have been reverted. (Error 2092)

Visual FoxPro 9.0
CursorAdapter cannot locate current record in the buffer. The record may have been reverted. (Error 2092)

Occurs when Visual FoxPro cannot find an inserted, deleted or modified record in the buffer.

  • Make sure other operations are not changing the field state of modified records.


Help for this topic/context not implemented. (Error 2050)

Visual FoxPro 9.0
Help for this topic/context not implemented. (Error 2050)

No top-level information exists for the specified topic. Try using the search function.


File "name" is not closed (Error 1933)

Visual FoxPro 9.0
File "name" is not closed (Error 1933)

Internal consistency error. A form (.scx) or visual class library (.vcx) file was closed but the method and event code that is stored in it is still in use.


Environment-level property is invalid (Error 1473)

Visual FoxPro 9.0
Environment-level property is invalid (Error 1473)

You have specified a property that cannot be set in the environment to be inherited by new cursors. You must first create the cursor and then use CURSORSETPROP( ).


Syntax error (Error 10)

Visual FoxPro 9.0
Syntax error (Error 10)

You have issued a command that is syntactically incorrect.

  • You might have misspelled the command or variable name, or used a clause that is not valid in the current context.

    Press F1 to see context-sensitive help on the command.


The table changes cannot be performed as the index or filter expression for index name would be invalid (Error 1531)

Visual FoxPro 9.0
The table changes cannot be performed as the index or filter expression for index name would be invalid (Error 1531)

You have attempted to use the ALTER TABLE command where the result would render an existing index or filter expression invalid, even if it not explicitly modified by the ALTER TABLE command.


SQL: Cannot locate table (Error 1802)

Visual FoxPro 9.0
SQL: Cannot locate table (Error 1802)

The table you have specified could not be found.


Structural .CDX file is not found (Error 1707)

Visual FoxPro 9.0
Structural .CDX file is not found (Error 1707)

The structural index file associated with a table file could not be found.


The data source for this object must be a variable reference (Error 1742)

Visual FoxPro 9.0
The data source for this object must be a variable reference (Error 1742)

You have specified an invalid data source or control source for an object.

  • A data source or ControlSource property must contain a variable.

    Make sure you have not specified an expression.


OLE IDispatch exception code "name" (Error 1427)

Visual FoxPro 9.0
OLE IDispatch exception code "name" (Error 1427)

You have received an error code returned by an Automation object. It is specific to the OLE object. The object did not provide any other textual information about the error.

Refer to the object's documentation for more information.


No PageFrame or Page is found in FormSet or Form with WindowType set to READ or READ MODAL (Error 1964)

Visual FoxPro 9.0
No PageFrame or Page is found in FormSet or Form with WindowType set to READ or READ MODAL (Error 1964)

You attempted to manually make a form set of type READ or READMODAL and you don't have the right combination of pages and page frames. This operation should be performed only by the Converter.


One of the members of this Form or FormSet is based on a nonvisual class. Cannot write .SCX file (Error 1968)

Visual FoxPro 9.0
One of the members of this Form or FormSet is based on a nonvisual class. Cannot write .SCX file (Error 1968)

You have included a non-visual class in your form set.

Remove it and try again.


Cannot find the beautify program.

Visual FoxPro 9.0
Cannot find the beautify program.

Visual FoxPro cannot find the program called BEAUTIFY.APP because the program was either deleted, renamed, or moved out of the main Visual FoxPro directory. You can:

  • Run Visual FoxPro Setup to install BEAUTIFY.APP.


There is no relation to the nested table "table name" (Error 2178)

Visual FoxPro 9.0
There is no relation to the nested table "table name" (Error 2178)

This error is generated by the XMLAdapter Class ToXML Method if the RespectNesting Property is true (.T.) and there is no relation set from the "outer" cursor to the "nested" cursor.


Relational expression is not valid (Error 1555)

Visual FoxPro 9.0
Relational expression is not valid (Error 1555)

The RelationalExpr property is not valid.

Make sure the expression is not empty and can be evaluated.


Cannot use 0 or negative as the argument for LOG10( ) (Error 292)

Visual FoxPro 9.0
Cannot use 0 or negative as the argument for LOG10( ) (Error 292)

A zero or a negative number has been used as the argument for a base-10 logarithm. For more information, see LOG10( ).


*bad date*

Visual FoxPro 9.0
*bad date*

The date expression is invalid.


Unable to locate target record in ADODB.Recordset (Error 2158)

Visual FoxPro 9.0
Unable to locate target record in ADODB.Recordset (Error 2158)

The target record could not be found when attempting to update an ADODB Recordset using Auto-Refresh, Refresh, or Delayed Memo Fetch. This error message can be generated when the record has been deleted on the source, or with a Recordset.Delete operation.


Statement is not in a procedure (Error 1931)

Visual FoxPro 9.0
Statement is not in a procedure (Error 1931)

Statements are not allowed after the ENDPROC clause. For more information, see DEFINE CLASS Command.


Cannot change property "name" in SetAll method (Error 1758)

Visual FoxPro 9.0
Cannot change property "name" in SetAll method (Error 1758)

The Name and TabIndex properties must have unique values and cannot be set with the SetAll method.


Color scheme is reserved (Error 1728)

Visual FoxPro 9.0
Color scheme is reserved (Error 1728)

Color schemes are included for backward compatibility only. Color schemes 13 through 16 are reserved. User-defined color schemes are numbers 17 through 24.


Exclusive open required to update this file. Please reopen (Error 1977)

Visual FoxPro 9.0
Exclusive open required to update this file. Please reopen (Error 1977)

You do not have exclusive rights to this file.

Re-open the file with the EXCLUSIVE clause of the USE command.


Rule and trigger code must balance transaction usage (Error 1598)

Visual FoxPro 9.0
Rule and trigger code must balance transaction usage (Error 1598)

A rule or trigger expression, or code invoked from an expression, has either started a transaction that it did not finish or finished one that it did not start. The write attempt that fired the rule or trigger code has been aborted.


The current Help file is empty. (Error 2036)

Visual FoxPro 9.0
The current Help file is empty. (Error 2036)

The Help file you specified contains no information. Try specifying another file.


Illegal nested OLDVAL( ) or CURVAL( ) (Error 1587)

Visual FoxPro 9.0
Illegal nested OLDVAL( ) or CURVAL( ) (Error 1587)

The expression you are passing to OLDVAL( ) or CURVAL( ) references the OLDVAL( ) or CURVAL( ) function. This is not a supported operation.


SQL: Too many columns referenced (Error 1841)

Visual FoxPro 9.0
SQL: Too many columns referenced (Error 1841)

There must be no more than 256 columns total referenced in any SELECT command. For more information, see SELECT - SQL Command.


The specified class library does not exist or does not contain a valid member class. (Error 2057)

Visual FoxPro 9.0
The specified class library does not exist or does not contain a valid member class. (Error 2057)

Make sure the class library you specify exists and contains a valid member class.


SQL: Statement too long (Error 1812)

Visual FoxPro 9.0
SQL: Statement too long (Error 1812)

The object code is too long to be compiled. For more information, see SELECT - SQL Command.


Menu size is too small (Error 287)

Visual FoxPro 9.0
Menu size is too small (Error 287)

The menu is too small to display menu items.

Define a larger menu.


Cannot append from password protected file (Error 1672)

Visual FoxPro 9.0
Cannot append from password protected file (Error 1672)

The file you have attempted to append is encrypted.


Invalid operation for offline view while being used online (Error 2008)

Visual FoxPro 9.0
Invalid operation for offline view while being used online (Error 2008)

Some operations are not valid when an offline view is being used online.

  • You tried to change the buffer mode of the view.

    By definition, offline views used online are in table buffer mode. Do not call CURSORSETPROP( ) to change the buffer mode.

  • You tried to create an index.

    Do not use SET ORDER TO or INDEX on offline views while you are using it online.


Window file format is invalid (Error 1632)

Visual FoxPro 9.0
Window file format is invalid (Error 1632)

The window save file (.WIN) being restored does not contain valid data.


Error building sort key (Error 2186)

Visual FoxPro 9.0
Error building sort key (Error 2186)

This error is generated when sort key truncation is about to occur, typically during GROUP BY, ORDER BY or other sorting operations. This can happen with use of a sort key that contains an expression, such as a Memo field, whose length is not fixed.


Operation is not allowed for CursorAdapter at this time. (Error 2077)

Visual FoxPro 9.0
Operation is not allowed for CursorAdapter at this time. (Error 2077)

The CursorAdapter object is currently being used in another process or otherwise cannot be used at the time it was called.


TRY/CATCH/FINALLY/ENDTRY mismatch or error (Error 2058)

Visual FoxPro 9.0
TRY/CATCH/FINALLY/ENDTRY mismatch or error (Error 2058)

TRY...CATCH...FINALLY needs to end with an ENDTRY statement to compile.


General fields cannot be used in the WHERE condition of an update statement. Change the WhereType property of the view (Error 1489)

Visual FoxPro 9.0
General fields cannot be used in the WHERE condition of an update statement. Change the WhereType property of the view (Error 1489)

In the WHERE clause of a SQL update statement, expressions you use to enforce optimistic locking cannot include general fields. Use the WhereType view property (you can change it from the default KeyAndModified to Key) to remove general fields from the update WHERE clause.

For more information on the WhereType property, see CURSORGETPROP( ) or DBGETPROP( ).


View file is invalid (Error 127)

Visual FoxPro 9.0
View file is invalid (Error 127)

An attempt has been made to open a view file with invalid data.


Report file "name" is invalid (Error 50)

Visual FoxPro 9.0
Report file "name" is invalid (Error 50)
See Also

The report definition contains an error, such as:

  • The number of data groups or Detail bands in a report exceeds the specified limits.

  • The report file (frx) does not contain the required columns for an FRX table.

  • The report file (frx) does not include a record for a required band, such as a Page Header band.

See Also

Reference

Table File Structure (.dbc, .dbf, .frx, .lbx, .mnx, .pjx, .scx, .vcx)

Concepts

Understanding and Extending Report Structure

Other Resources

Visual FoxPro System Capacities


Localized product is required for this environment (Error 1911)

Visual FoxPro 9.0
Localized product is required for this environment (Error 1911)

There was an attempt to use a US version of Visual FoxPro with a non-US system.


Related table is not found in current database (Error 1880)

Visual FoxPro 9.0
Related table is not found in current database (Error 1880)

A database relation object is being created or referenced for which the related table could not be found.

  • You used the REFERENCES clause of the CREATE TABLE or ALTER TABLE command.

    Make sure both tables involved in the relation are in the database.


Cannot update ADODB.Recordset while cursor, created by CursorAdapter.CursorFill method, is not attached to a CursorAdapter object. (Error 2082)

Visual FoxPro 9.0
Cannot update ADODB.Recordset while cursor, created by CursorAdapter.CursorFill method, is not attached to a CursorAdapter object. (Error 2082)

Visual FoxPro requires a cursor, created from an ADO Recordset using the CursorFill method, to be attached to a CursorAdapter object, before it can be updated.

  • To update the cursor, reattach the cursor to the CursorAdapter object.


XML node does not belong to MSXML4.DOMDocument. (Error 2128)

Visual FoxPro 9.0
XML node does not belong to MSXML4.DOMDocument. (Error 2128)

Visual FoxPro requires that XML data cannot be accessed when there is not a parent document.


File must be opened exclusively (Error 110)

Visual FoxPro 9.0
File must be opened exclusively (Error 110)

You have attempted to perform an operation that requires exclusive use of the table.


The fields in table "name" did not match the entries in the database (Error 1984)

Visual FoxPro 9.0
The fields in table "name" did not match the entries in the database (Error 1984)

When opening a database-owned table, Visual FoxPro tries to confirm that each field of the table has a matching field object in the database.

  • The database or the table has been corrupted.

    Use VALIDATE DATABASE to identify the problem.

  • The table being opened is the wrong one.

    Remove and re-add the table to the database.


Invalid timestamp column name "column name" (Error 2160)

Visual FoxPro 9.0
Invalid timestamp column name "column name" (Error 2160)

The timestamp column name is invalid or can’t be found in the cursor.


The default value for field "name" does not evaluate to the correct type for the field (Error 1997)

Visual FoxPro 9.0
The default value for field "name" does not evaluate to the correct type for the field (Error 1997)

A default value expression must evaluate to the data type for the field.

Change the expression to evaluate to the correct data type.


Field "field name" is not associated with a base table (Error 2174)

Visual FoxPro 9.0
Field "field name" is not associated with a base table (Error 2174)

This error is generated by the CursorAdapter Class when it attempts delayed memo fetching. The base table is specified with the CursorAdapter Tables Property. The memo field should be associated with the base table with the CursorAdapter UpdateNameList Property.


Invalid call issued while executing a SQLMORERESULTS( ) sequence (Error 1475)

Visual FoxPro 9.0
Invalid call issued while executing a SQLMORERESULTS( ) sequence (Error 1475)

An invalid SQL pass-through (SPT) function call has been made while a SQLMORERESULTS( ) call was expected to continue the SPT call sequence in progress.

Call SQLCANCEL( ) to cancel the SPT sequence or make valid SPT calls to finish the call sequence.


Cannot compile until the current COMPILE command has completed (Error 1971)

Visual FoxPro 9.0
Cannot compile until the current COMPILE command has completed (Error 1971)

You have attempted to compile code while another compilation was in progress. The compiler can complete only one thing at a time.


Box dimensions are invalid (Error 227)

Visual FoxPro 9.0
Box dimensions are invalid (Error 227)

Row 2, column 2 must be larger than row 1, column 1 when using the @ ... BOX command.


Cannot rename the file to different device (Error 1153)

Visual FoxPro 9.0
Cannot rename the file to different device (Error 1153)

To move the file to another drive, use COPY FILE.


Keyboard macro file format is invalid (Error 356)

Visual FoxPro 9.0
Keyboard macro file format is invalid (Error 356)

An attempt has been made to use a macro file with invalid data.


SQL: Subquery nesting is too deep (Error 1842)

Visual FoxPro 9.0
SQL: Subquery nesting is too deep (Error 1842)

Visual FoxPro does not support nested subqueries. For more information, see SELECT - SQL Command.


Arrays cannot be assigned to array elements (Error 1974)

Visual FoxPro 9.0
Arrays cannot be assigned to array elements (Error 1974)

Check your assignment names.


"field | variable" is not unique and must be qualified (Error 1832)

Visual FoxPro 9.0
"field | variable" is not unique and must be qualified (Error 1832)

You have referenced a field that exists in more than one table.

For example, if you use the TESTDATA database and issue the following command, the same error occurs because the cust_id field exists in both the customer and orders tables:

Copy Code
SELECT cust_id FROM customer,orders
  • To work around the non-uniqueness of field names, issue the following command:

    Copy Code
    SELECT customer.cust_id FROM customer,orders
    For more information, see SELECT - SQL Command.


Illegal to attempt a file lock in a transaction after taking prior record locks (Error 1594)

Visual FoxPro 9.0
Illegal to attempt a file lock in a transaction after taking prior record locks (Error 1594)

You have either explicitly (with FLOCK( )) or implicitly (with REPLACE ALL, for example) attempted to take a file lock in a transaction. This is illegal if any record locks have already been taken either explicitly or implicitly at this transaction level or any lower transaction level. This is illegal even if those record locks have been freed inside the transaction.

You must roll back all record locks on this file before attempting this file lock. For more information, see ROLLBACK.


Session number is invalid (Error 1540)

Visual FoxPro 9.0
Session number is invalid (Error 1540)

Use a valid session number with SET DATASESSION TO..


Field width or number of decimal places is invalid (Error 1713)

Visual FoxPro 9.0
Field width or number of decimal places is invalid (Error 1713)

The field width or number of decimal places you have specified is not valid. For a list of the requirements, see System Capacities..


Missing expression (Error 152)

Visual FoxPro 9.0
Missing expression (Error 152)

A valid expression was expected, but not found.


Class "name" is not a Form class. (Error 2029)

Visual FoxPro 9.0
Class "name" is not a Form class. (Error 2029)

The class you specify in the AS clause of CREATE FORM must be based on a Form class.


File "name" is a database (Error 1553)

Visual FoxPro 9.0
File "name" is a database (Error 1553)

The operation you have attempted is not supported for database files.

Try again with a file of the correct type.


Cannot add "name". Class definition is cyclical (Error 1741)

Visual FoxPro 9.0
Cannot add "name". Class definition is cyclical (Error 1741)

You have attempted to specify a class in an ADD OBJECT statement whose class definition is the same as the class being defined. For more information, see DEFINE CLASS.


Cannot create file "file" (Error 1102)

Visual FoxPro 9.0
Cannot create file "file" (Error 1102)

The operating system cannot create the specified file for the following possible reasons:

  • The disk or directory is full.

    Remove files and try again.

  • You do not have access to the target directory.

    Check your permission level.

  • You specified an invalid file name.

    Check for typing mistakes.


Link command failed (Error 1194)

Visual FoxPro 9.0
Link command failed (Error 1194)

A compilation error occurred and an .EXE was not created on the disk.


Error loading HtmlHelp 2.0 collection. (Error 2049)

Visual FoxPro 9.0
Error loading HtmlHelp 2.0 collection. (Error 2049)

The HTML Help 2.0 collection specified did not load properly. Check the File Locations Tab, Options Dialog Box to make sure the file you specified is in the location specified.


Conversion from Unicode has failed. (Error 2136)

Visual FoxPro 9.0
Conversion from Unicode has failed. (Error 2136)

Occurs when a problem is encountered while Visual FoxPro attempts to convert an Unicode string to an ANSI character.

  • Examine your data, table, and field names to insure that they contain values that Visual FoxPro can convert properly to ANSI character.


Menu has not been defined with DEFINE MENU (Error 168)

Visual FoxPro 9.0
Menu has not been defined with DEFINE MENU (Error 168)

You have attempted to activate a menu that has not been defined. For more information, see DEFINE MENU Command.


Views require either DB_BUFOPTROW or DB_BUFOPTTABLE (Error 1597)

Visual FoxPro 9.0
Views require either DB_BUFOPTROW or DB_BUFOPTTABLE (Error 1597)

Local or remote view-based cursors support updating only by way of an optimistic buffering mode.


END TRANSACTION command cannot be issued without a corresponding BEGIN TRANSACTION command (Error 1591)

Visual FoxPro 9.0
END TRANSACTION command cannot be issued without a corresponding BEGIN TRANSACTION command (Error 1591)

Contain transaction code between matched BEGIN TRANSACTION and END TRANSACTION pairs.


Statement is not valid in a class definition (Error 1927)

Visual FoxPro 9.0
Statement is not valid in a class definition (Error 1927)

You have used a command that is not permitted within a DEFINE CLASS structure. Valid commands are: ADD OBJECT, ADD PROTECTED OBJECT, DIMENSION, FUNCTION, PROCEDURE, and PROTECTED. For more information, see DEFINE CLASS Command.


Type Library "name" not found (Error 1444)

Visual FoxPro 9.0
Type Library "name" not found (Error 1444)

A library that does not exist has been specified.

Try checking your statement, the location, and the library name to make sure the file exists where you specified it.


File "name" is not part of a database (Error 1558)

Visual FoxPro 9.0
File "name" is not part of a database (Error 1558)

The operation you have attempted is not supported for free tables.

Try again with a file of the correct type.


Form file "name" is from a previous version of FoxPro. It must be converted to the current format before it can be executed (Error 1991)

Visual FoxPro 9.0
Form file "name" is from a previous version of FoxPro. It must be converted to the current format before it can be executed (Error 1991)

You have attempted to compile a form file (.scx) from a previous version of FoxPro.

Convert to the current version and try again.


Function is not implemented (Error 1999)

Visual FoxPro 9.0
Function is not implemented (Error 1999)

You have attempted to call a function that is not supported in the current version of Visual FoxPro.


COLUMN | FORM | ALIAS | NOOVERWRITE | WIDTH are only allowed with the FROM clause (Error 1695)

Visual FoxPro 9.0
COLUMN | FORM | ALIAS | NOOVERWRITE | WIDTH are only allowed with the FROM clause (Error 1695)

These options are available only when you create a quick report with the FROM clause.


Operation is invalid for a Memo, Blob, General, or Picture field (Error 34)

Visual FoxPro 9.0
Operation is invalid for a Memo, Blob, General, or Picture field (Error 34)
  • An INDEX command cannot specify a Memo or Blob field as its key expression.

  • There was not enough memory for Visual FoxPro to complete an operation.

  • Unions between differing column types are not allowed when one of the columns is of Memo or General type unless UNION ALL is used.


Invalid operation for the cursor (Error 1115)

Visual FoxPro 9.0
Invalid operation for the cursor (Error 1115)

An attempt was made to use the PACK command on a cursor.


Unable to infer XML schema. (Error 2120)

Visual FoxPro 9.0
Unable to infer XML schema. (Error 2120)

Occurs when the XMLTOCURSOR( ) function is not able to successfully parse the supplied schema and create the cursor.


Window "name" has not been defined (Error 1714)

Visual FoxPro 9.0
Window "name" has not been defined (Error 1714)

You have referenced a window that does not exist.

  • The window has not been created, or it has already been destroyed.

    Create the window, or reference a different window.


An object's control source cannot be set to its Value property (Error 1781)

Visual FoxPro 9.0
An object's control source cannot be set to its Value property (Error 1781)

You have attempted to set a control source of an object to itself. Use a valid data source. For more information about setting up data sources, see "Setting up an ODBC Data Source" under the section Installing Visual FoxPro.


Cannot visually modify a class based on a nonvisual class (Error 1979)

Visual FoxPro 9.0
Cannot visually modify a class based on a nonvisual class (Error 1979)

You have attempted to modify a class that was defined in a program. You must use the Class Designer to modify classes based on base classes or classes defined in .vcx files.


Must be a variable or array (Error 1225)

Visual FoxPro 9.0
Must be a variable or array (Error 1225)

A file variable (field) was used where a variable or array was required.


Volume does not exist (Error 1922)

Visual FoxPro 9.0
Volume does not exist (Error 1922)

The volume specified in the SET VOLUME command does not exist.


Display mode is not available (Error 216)

Visual FoxPro 9.0
Display mode is not available (Error 216)

You have attempted to select an unavailable display mode.


XMLName property contains illegal symbol(s) (Error 2182)

Visual FoxPro 9.0
XMLName property contains illegal symbol(s) (Error 2182)

This error is generated when the XMLNameIsXPath Property is changed from true (.T.) to false (.F.) and the XMLName Property contains one or more illegal symbols.


Cannot GROUP by aggregate field (Error 1846)

Visual FoxPro 9.0
Cannot GROUP by aggregate field (Error 1846)

You have attempted to use an aggregate function (MIN( ), MAX( ), SUM( ), AVG( ), COUNT( ), NPV( ), STD( ) or VAR( )) in a GROUP clause.


There is not enough disk space for "name" (Error 56)

Visual FoxPro 9.0
There is not enough disk space for "name" (Error 56)

There is no room on the disk to complete this operation.

  • Your disk is full.

    Free up some disk space and retry the operation.

  • Under certain versions of Novell, you tried to extend a file that has no owner. This error is returned but is not correct.

    Work around the problem by assigning an owner to the file first.

  • You have a table file larger than 2 gigabytes in size.

    You have exceeded the maximum size for a Visual FoxPro DBF, FPT, or CDX file. Reduce the size of the specified file.


Feature is not available (Error 1001)

Visual FoxPro 9.0
Feature is not available (Error 1001)

The Visual FoxPro feature you have attempted to use is not supported in this version of Visual FoxPro.


Cannot find the menu-generation program (Error 1693)

Visual FoxPro 9.0
Cannot find the menu-generation program (Error 1693)

The program that create menus (GENMENU) cannot be located. See _GENMENU System Variable for more information about the GENMENU menu generation program.


Calling OpenTables or CloseTables is not allowed while either of those methods are in the process of executing. (Error 2147)

Visual FoxPro 9.0
Calling OpenTables or CloseTables is not allowed while either of those methods are in the process of executing. (Error 2147)

The OpenTables or CloseTables methods cannot be called, in either the BeforeOpenTables or AfterCloseTables events, as these events are not recursive.


File "name" is part of a database (Error 1565)

Visual FoxPro 9.0
File "name" is part of a database (Error 1565)

The operation you have attempted is supported only for free tables.

Try again with a file of the correct type.


No fields found to process (Error 47)

Visual FoxPro 9.0
No fields found to process (Error 47)

No fields can be found, usually because a SET FIELDS TO was in effect.


Currency value is out of range (Error 1988)

Visual FoxPro 9.0
Currency value is out of range (Error 1988)

The maximum size of a numeric or float field is 20 digits.


PREVIEW clause is not allowed with OFF/NOCONSOLE or TO PRINT/FILE (Error 1681)

Visual FoxPro 9.0
PREVIEW clause is not allowed with OFF/NOCONSOLE or TO PRINT/FILE (Error 1681)

Page preview is not allowed when the console is not on or when printing to the printer or a file.


Maximum menus allowed (Error 25) is exceeded (Error 1608)

Visual FoxPro 9.0
Maximum menus allowed (Error 25) is exceeded (Error 1608)

The maximum number of menus that may be defined (25) was exceeded.


Expression evaluated to an illegal value (Error 46)

Visual FoxPro 9.0
Expression evaluated to an illegal value (Error 46)

Occurs when an expression specified by SET MEMOWIDTH, BROWSE, or an @ ... TO command evaluates to an illegal value.

-or-

Occurs when the value specified for LockColumns or LockColumnsLeft properties is greater than the number of columns that are visible in a grid panel.


Label nesting error (Error 1653)

Visual FoxPro 9.0
Label nesting error (Error 1653)

A user-defined function in a label form has called LABEL with a FORM clause again.


Class cannot be instantiated because member "name" has wrong # of parameters (Error 1442)

Visual FoxPro 9.0
Class cannot be instantiated because member "name" has wrong # of parameters (Error 1442)

The IMPLEMENTS clause in the DEFINE CLASS command uses an incorrect number of parameters for this class. For more information, see DEFINE CLASS Command.


Invalid file format. If this is a dBASE file, it must be converted first. To convert it, type MODIFY LABEL file (Error 1510)

Visual FoxPro 9.0
Invalid file format. If this is a dBASE file, it must be converted first. To convert it, type MODIFY LABEL file (Error 1510)

Convert your dBASE file and try again.


Cannot open configuration file.

Visual FoxPro 9.0
Cannot open configuration file.

Visual FoxPro found a configuration file but did not have the proper rights to open it.


Object is not contained in a "name" (Error 1938)

Visual FoxPro 9.0
Object is not contained in a "name" (Error 1938)

This message is produced by the scope operator when the parent class you have specified is not in the inheritance hierarchy of the current (THIS) object. For example, this error will occur if you put FORMSET::Click in the Click event of a form that is not contained in a form set.


User-defined functions are not allowed (Error 1097)

Visual FoxPro 9.0
User-defined functions are not allowed (Error 1097)

User-defined functions are not supported in this area of Visual FoxPro.

Remove the user-defined function.


SQL: HAVING clause is invalid (Error 1803)

Visual FoxPro 9.0
SQL: HAVING clause is invalid (Error 1803)

There is an error in the HAVING clause.

For example, the clause might not contain a logical expression. For more information, see SELECT - SQL Command.


Warning: The connection timeout cannot be set (Error 1481)

Visual FoxPro 9.0
Warning: The connection timeout cannot be set (Error 1481)

The connection timeout interval cannot be set by the ODBC driver. The connection will use the default driver defined timeout interval. This will not allow SQL pass-through functions to return control while an ODBC call is in progress.


Class file version is greater than the current version (Error 1751)

Visual FoxPro 9.0
Class file version is greater than the current version (Error 1751)

You have attempted to use a visual class library (.vcx) file that was created by a later version of Visual FoxPro than the version you are currently using.


WIN.INI/registry is corrupted (Error 1955)

Visual FoxPro 9.0
WIN.INI/registry is corrupted (Error 1955)

You have attempted to get print information from the operating system by using PRTINFO( ) or SET PRINTER TO but no default printer is selected.

Use the Printer Control Panel to select set a default printer.


Missing .RTT section (Error 1193)

Visual FoxPro 9.0
Missing .RTT section (Error 1193)

The Microsoft Visual FoxPro distribution component is not properly installed.


FILTER expression exceeds allowed size (Error 1140)

Visual FoxPro 9.0
FILTER expression exceeds allowed size (Error 1140)

You have attempted to issue SET FILTER TO on an expression that is longer than the maximum allowable size of 160 characters.


SQL: Cannot UPDATE or DELETE from subquery (Error 2151)

Visual FoxPro 9.0
SQL: Cannot UPDATE or DELETE from subquery (Error 2151)

This error is generated when the target for a UPDATE - SQL Command or DELETE - SQL Command is a sub-query.


No fields were found to copy (Error 138)

Visual FoxPro 9.0
No fields were found to copy (Error 138)

During an attempt to copy to a file, no visible fields were found.


Window has not been activated with ACTIVATE WINDOW (Error 215)

Visual FoxPro 9.0
Window has not been activated with ACTIVATE WINDOW (Error 215)

An attempt was made to use a window, which has not been activated. For more information, see ACTIVATE WINDOW Command.


"name" band is too large to fit on page (Error 1298)

Visual FoxPro 9.0
"name" band is too large to fit on page (Error 1298)

You have attempted to use a report band that is too large to fit on a page.

  • Redesign your report form and try this operation again.

    For more information, see Report Designer.


Could not add version resource to executable file (Error 1181)

Visual FoxPro 9.0
Could not add version resource to executable file (Error 1181)

The resource could not be added to the executable file at build time.

  • The resource might be corrupt.

    Recreate the resource.

  • You might have used a letter in the VersionNumber property cBuildNumber setting.

    Use only numbers for the cBuildNumber setting.


Not a user-defined window (Error 1682)

Visual FoxPro 9.0
Not a user-defined window (Error 1682)

You have attempted to use a command containing a WINDOW clause on a window that is not user-defined, such as the Command window.


Cannot sort .IDX files in descending order (Error 1706)

Visual FoxPro 9.0
Cannot sort .IDX files in descending order (Error 1706)

.IDX index files do not support a DESCENDING clause.


Property is invalid for local cursors (Error 1467)

Visual FoxPro 9.0
Property is invalid for local cursors (Error 1467)

The property is not supported for cursors based on local tables or local views; it applies only to cursors based on remote views. Use the property only for remote view cursors.

When using the CURSORGETPROP( ) function, the ADORecordset property is not valid for cursors that are not based on ADO Recordsets.


No menu item is defined (Error 1604)

Visual FoxPro 9.0
No menu item is defined (Error 1604)

You attempted to read a menu bar that has not been defined.


Invalid key column name "name". (Error 2146)

Visual FoxPro 9.0
Invalid key column name "name". (Error 2146)

Occurs when the CursorAdapter objects, KeyFieldList property, contains an invalid value.

  • Make sure the value assigned to the KeyFieldList property is valid.


Cannot allocate screen map

Visual FoxPro 9.0
Cannot allocate screen map

There was not enough memory to run Visual FoxPro.


Cannot resolve backlink (Error 1976)

Visual FoxPro 9.0
Cannot resolve backlink (Error 1976)
See Also

Visual FoxPro was unable to match a table with its database. Use the VALIDATE DATABASE Command to verify the links in the database. Use the FREE TABLE Command to remove a table from the database that references it.

See Also

Reference

VALIDATE DATABASE Command
FREE TABLE Command


Cannot DROP all existing columns (Error 1871)

Visual FoxPro 9.0
Cannot DROP all existing columns (Error 1871)

An existing table must have at least one column.


Only a single SQL SELECT statement can be enclosed in parentheses (Error 2196)

Visual FoxPro 9.0
Only a single SQL SELECT statement can be enclosed in parentheses (Error 2196)

This error is caused by a SELECT - SQL Command with a SELECT - SQL Command - UNION Clause that includes more than one set of parentheses.


Numeric overflow. Data was lost (Error 39)

Visual FoxPro 9.0
Numeric overflow. Data was lost (Error 39)

A mathematical operation resulted in a number that was too large to be stored in the field or variable in which it was placed.


Invalid element in XMLTable.Fields collection. (Error 2098)

Visual FoxPro 9.0
Invalid element in XMLTable.Fields collection. (Error 2098)

Visual FoxPro has detected an invalid object in the XMLField collection.


SQL: Invalid TOP specification (Error 1866)

Visual FoxPro 9.0
SQL: Invalid TOP specification (Error 1866)

The TOP clause of the SELECT - SQL command requires a value greater than zero. If the PERCENT clause is present, the value must be greater than zero and less than 100. In both cases, the value must be numeric.


Incorrect property name (Error 1470)

Visual FoxPro 9.0
Incorrect property name (Error 1470)

You have attempted to use an incorrect property name.


Operation is not allowed for CursorAdapter. (Error 2076)

Visual FoxPro 9.0
Operation is not allowed for CursorAdapter. (Error 2076)

Occurs when attempting an operation that is not permitted such as when the TABLEUPDATE( ) function attempts to perform an insert, update, or delete operation, and the corresponding CursorAdapter AllowUpdate, AllowDelete, or AllowInsert properties are set to False (.F.).


Mismatched braces in key label (Error 1256)

Visual FoxPro 9.0
Mismatched braces in key label (Error 1256)

A left or right brace is missing from a key label.


The ActiveX control module failed to register correctly (Error 1438)

Visual FoxPro 9.0
The ActiveX control module failed to register correctly (Error 1438)

The file does not appear to be a valid ActiveX control.

  • The ActiveX control does not have a self-registration function.

    Contact the ActiveX control vendor for an updated control that contains a working DllRegisterServer function.


SQL: Error correlating fields (Error 1801)

Visual FoxPro 9.0
SQL: Error correlating fields (Error 1801)

An outer reference can be used only in syntax similar to the following:

X = Y

Syntax such as X = Y + 1 or X = 5 will produce this error.


"file" is not a Visual FoxPro .EXE file (Error 1196)

Visual FoxPro 9.0
"file" is not a Visual FoxPro .EXE file (Error 1196)

The .EXE file you specified was not created by Visual FoxPro.

  • Use RUN | ! Command to run external executable files.


XMLField object is already associated with XMLTable object. (Error 2144)

Visual FoxPro 9.0
XMLField object is already associated with XMLTable object. (Error 2144)

Visual FoxPro does not allow XMLField objects to be added to an XMLTable objects, XMLField collection, when they are already associated with another XMLTable object.

  • You can check to see if an XMLField object is already associated with an XMLTable object by checking its XMLTable property. If it is not associated, the value of the XMLTable property will be NULL. Otherwise, it will return an object reference to the owning XMLTable object.


Beginning of file encountered (Error 38)

Visual FoxPro 9.0
Beginning of file encountered (Error 38)

The record pointer is at the beginning of the file.

  • You have attempted to position the record pointer before the first record in the file.

    Use BOF( ) to test for the beginning of the file.


Window "name" is not a dockable window. (Error 2087)

Visual FoxPro 9.0
Window "name" is not a dockable window. (Error 2087)

The specified window could not be docked because it is not a dockable window.


Foxcode table not found, is not correct version or is incompatible. (Error 2042)

Visual FoxPro 9.0
Foxcode table not found, is not correct version or is incompatible. (Error 2042)

The table file specified by the _FOXCODE system variable does not exist or is incompatible with this version of Visual FoxPro. For more information, see _FOXCODE System Variable.

To determine the file specified by _FOXCODE, type the following line of code:

Copy Code
? _FOXCODE

Make sure the file is a properly structured table for this version of Visual FoxPro. For more information, see IntelliSense Table Structure.


Cannot update the cursor "cursor", since it is read-only. (Error 111)

Visual FoxPro 9.0
Cannot update the cursor "cursor", since it is read-only. (Error 111)

Visual FoxPro cannot update the specified cursor because it is read-only. This can occur when attempting to write to a file created or accessed for read-only purposes.


Invalid call issued while executing a SQLEXEC( ) sequence (Error 1474)

Visual FoxPro 9.0
Invalid call issued while executing a SQLEXEC( ) sequence (Error 1474)

An invalid SQL pass-through (SPT) function call has been made while a SQLEXEC( ) call was expected to continue the SPT call sequence in progress.

Call SQLCANCEL( ) to cancel the SPT sequence or make valid SPT calls to finish the call sequence.


DIMENSION contains variable declaration without required subscript arguments (Error 1232)

Visual FoxPro 9.0
DIMENSION contains variable declaration without required subscript arguments (Error 1232)

A DIMENSION statement contains a variable declaration without the required subscript arguments.


File must be opened exclusively to convert the Memo file (Error 1637)

Visual FoxPro 9.0
File must be opened exclusively to convert the Memo file (Error 1637)

The table file you are using must be opened exclusively to be able to convert the memo file.


SQL: Invalid SET expression in UPDATE (Error 1865)

Visual FoxPro 9.0
SQL: Invalid SET expression in UPDATE (Error 1865)

Check the expressions in your SET clauses. For more information, see the UPDATE command.


Printer driver is corrupted (Error 1643)

Visual FoxPro 9.0
Printer driver is corrupted (Error 1643)

An attempt has been made to load a printer driver that is corrupted.


Invalid index expression for a Binary index (Error 2156)

Visual FoxPro 9.0
Invalid index expression for a Binary index (Error 2156)

A binary index can only be created using a logical expression. See Visual FoxPro Index Types for more information on creating binary indexes.


Symphony version 1.0 file format is invalid (Error 1673)

Visual FoxPro 9.0
Symphony version 1.0 file format is invalid (Error 1673)

The Symphony file you have attempted to import is either not version 1.0 or has been corrupted.


No records are found for the current platform (Error 1796)

Visual FoxPro 9.0
No records are found for the current platform (Error 1796)

You have attempted to modify a file that has no records from the current platform.

Use the transport program to convert the file.


Invalid expression in label definition file (Error 1245)

Visual FoxPro 9.0
Invalid expression in label definition file (Error 1245)

An invalid expression was encountered in a label file (.LBX).


Invalid locale ID. (Error 2026)

Visual FoxPro 9.0
Invalid locale ID. (Error 2026)

The locale ID specified in STRCONV( ) isn't supported by the operating system.


Alias is not found (Error 13)

Visual FoxPro 9.0
Alias is not found (Error 13)

You have attempted to specify an alias that has not been defined. There is no such alias currently in use.


Cannot update project from project metafile (Error 1909)

Visual FoxPro 9.0
Cannot update project from project metafile (Error 1909)

There is a conflict in the project metafile (.PJM file).

  • You edited the .PJM file directly.

    Restore the file to a previous version and use the interface to make changes: undo the checkout of the .PJM file and update the project list.

  • There is a conflict in the project information section of the .PJM file.

    Resolve the conflict by removing complete lines only, if possible.

  • The formatting in the project metafile is incorrect.

    For example, some information has an unexpected data type, or commas are misplaced.


Logical expression required

Visual FoxPro 9.0
Logical expression required

The expression provided in the Expression Builder must be of Logical type. For more information, see Creating Logical Expressions.


Class creation canceled (Error 1313)

Visual FoxPro 9.0
Class creation canceled (Error 1313)

While attempting to create a class based on an ActiveX control, you canceled the dialog box.


Cannot access characters beyond string (Error 62)

Visual FoxPro 9.0
Cannot access characters beyond string (Error 62)

You have attempted to access characters beyond the last byte of a string variable or table field.


File cannot be locked (Error 1503)

Visual FoxPro 9.0
File cannot be locked (Error 1503)

Visual FoxPro cannot lock the requested file. It may already be locked by another user on the network.


The DataObject cannot be modified in the OLEDragOver or OLEDragDrop event. (Error 2021)

Visual FoxPro 9.0
The DataObject cannot be modified in the OLEDragOver or OLEDragDrop event. (Error 2021)

The DataObject methods are not supported in these events.


Topic Not Found

Visual FoxPro 9.0
Topic Not Found

The link you just clicked was not able to connect to the target page. Some possible reasons and remedies are as follows:

Reason | Remedy
Destination topic is not part of the area you specified in the Filtered by field. | Either select another filter or select (no filter).
The URL of the destination topic is incorrect or has changed. | Use the index or the search function instead.
Problems with the MSDN installation. | Uninstall the MSDN Library and then rerun Setup.

Additional help is available for filters, search, and the index.

Click Back to return to the page you were on.

The target parameters are:


The Remote View Wizard was unable to obtain column information for this remote table. This may be the result of an ODBC error, or the remote table may not be owned by the current user.

Visual FoxPro 9.0
The Remote View Wizard was unable to obtain column information for this remote table. This may be the result of an ODBC error, or the remote table may not be owned by the current user.

If the query you are using doesn't contain the owner name for the table you specified, the information from the remote table will be unavailable.

To correct this problem, use the View Designer to add the current user as the owner of the table to the SQL string.

If you still get an error, you must correct the problem in ODBC.


SQL: Column "field | variable" is not found (Error 1806)

Visual FoxPro 9.0
SQL: Column "field | variable" is not found (Error 1806)

The field or variable you specified cannot be found.


Picture error in GET statement (Error 1217)

Visual FoxPro 9.0
Picture error in GET statement (Error 1217)

The PICTURE clause within an @ ... SAY or @ ... GET statement contains a picture that cannot include the value to be formatted. This error might be occurring because the picture is corrupt or because the value to be formatted does not match the picture format.


Import only Worksheet A for Lotus 1-2-3 version 3.0 files (Error 1679)

Visual FoxPro 9.0
Import only Worksheet A for Lotus 1-2-3 version 3.0 files (Error 1679)

Worksheets B and C cannot be imported into Visual FoxPro because a table is two-dimensional.


SQL parameter "name" is invalid (Error 1499)

Visual FoxPro 9.0
SQL parameter "name" is invalid (Error 1499)

The SQL parameter definition in a SQLEXEC( ) call, or in a view definition, contains a syntax error.

  • It is missing the closing character for a string constant or a closing right parenthesis.

    Check the parameter definition following the "?" operator in the SQL string and correct the parameter syntax.


Cannot find the spell check program.

Visual FoxPro 9.0
Cannot find the spell check program.

Visual FoxPro cannot find the program called SPELLCHK.APP because the program was either deleted, renamed, or moved out of the main Visual FoxPro directory. You can:

  • Run Visual FoxPro Setup to install SPELLCHK.APP.


Member "name" does not evaluate to an object (Error 1943)

Visual FoxPro 9.0
Member "name" does not evaluate to an object (Error 1943)

Invalid syntax. The syntax indicates that the next element being evaluated should be an object but it isn't.

For example, if you had a form called myform with a text box called text1, the command myform.txt.value = "help" would generate this error. The command should be myform.text1.value = "help".


XML document does not have a root element. (Error 2124)

Visual FoxPro 9.0
XML document does not have a root element. (Error 2124)

Visual FoxPro does not allow empty DOM or DOM Nodes to be attached to the XMLAdapter object.


OLE Changed Properties stream is the wrong version. Subclassed properties ignored. (Error 2003)

Visual FoxPro 9.0
OLE Changed Properties stream is the wrong version. Subclassed properties ignored. (Error 2003)

The names and values of the OLE object properties could not be read from the form (.scx) or class (.vcx) file.

  • The information is missing from the file or the file is corrupt.

    Reapply your recent changes and save the file in the Form Designer or Class Designer. The correct information is written out.

  • The version number for the OLE object has changed.

    Contact the vendor of the OLE object.


Value of XMLTable.XMLName must be used as key value for collection. (Error 2099)

Visual FoxPro 9.0
Value of XMLTable.XMLName must be used as key value for collection. (Error 2099)

The XMLName property for an XMLTable must be used as the key, when adding the XMLTable to a Tables collection for an XMLAdapter.

  • Make sure that any XMLTable objects, that are going to be added to a collection have the XMLName property set to a valid value, and that this value is used as they key.


Invalid or duplicate field name.

Visual FoxPro 9.0
Invalid or duplicate field name.

The field name you specified already exists in the table.

  • Specify a unique field name for each field in the table.


Label file is invalid (Error 54)

Visual FoxPro 9.0
Label file is invalid (Error 54)

An attempt was made to modify or print labels using a label file that was not created with CREATE LABEL or MODIFY LABEL, or that had other label file definition errors.

Note Label files (lbx) in Visual FoxPro have the same table structure and requirements as Report forms (frx). For examples of report and layout file definition errors, see Report file "name" is invalid (Error 50).


Primary key property is invalid; please validate database (Error 1567)

Visual FoxPro 9.0
Primary key property is invalid; please validate database (Error 1567)

The primary key property for this table in the database is corrupted.

Use VALIDATE DATABASE to correct the problem.


Cannot release menu item (Error 170)

Visual FoxPro 9.0
Cannot release menu item (Error 170)

You have attempted to release a prompt that was defined with files or structure.


Cannot add this object to a Column (Error 1769)

Visual FoxPro 9.0
Cannot add this object to a Column (Error 1769)

The grid column does not support objects such as forms, form sets, toolbars, and columns.

  • You used the AddObject method on the grid column.

    Use AddObject only for objects that are reasonably represented in a column. If you would like the appearance of a form in the column, save the contents of the form to a container class and add it to the column.


Cannot issue the SET FORMAT command while a READ command is in progress on a format file (Error 1720)

Visual FoxPro 9.0
Cannot issue the SET FORMAT command while a READ command is in progress on a format file (Error 1720)

The format file you have specified calls upon a format file currently in use.


Missing operand (Error 1231)

Visual FoxPro 9.0
Missing operand (Error 1231)

You need to provide a second value for an operator you used. For example, the division operation requires two operands and one is missing in each of these examples.

? ( 13 + 4 ) /

? ( 3 / ) + 2

The multiplication operator requires two operands and one is missing in this example:

? 4 *.


Server "server" is not found (Error 1715)

Visual FoxPro 9.0
Server "server" is not found (Error 1715)

The server specified with the SET PRINTER TO command could not be found.


Window has not been defined with DEFINE WINDOW (Error 214)

Visual FoxPro 9.0
Window has not been defined with DEFINE WINDOW (Error 214)

An attempt has been made to activate a window that has not been defined.

Use the DEFINE WINDOW command before using the ACTIVATE WINDOW command.


Error occurred in conversion (Error 1797)

Visual FoxPro 9.0
Error occurred in conversion (Error 1797)

The converter has run and returned a non-error status, but the resulting report form (.FRX) file is not in Visual FoxPro format. If you have changed the value of _CONVERTER, the converter you are using doesn't generate proper Visual FoxPro .FRX files.


Objects cannot be programmatically added to the Form Designer's FormSet (Error 1987)

Visual FoxPro 9.0
Objects cannot be programmatically added to the Form Designer's FormSet (Error 1987)

You have attempted to programmatically add forms to the Form Designer form set. This cannot be done.


Class "name" is in use (Error 1776)

Visual FoxPro 9.0
Class "name" is in use (Error 1776)

The class specified with the SaveAsClass method already exists and is in use elsewhere.

Issue CLEAR ALL to free the class and allow it to be overwritten.


XMLAdapter object doesn't have associated tables. (Error 2129)

Visual FoxPro 9.0
XMLAdapter object doesn't have associated tables. (Error 2129)

Visual FoxPro requires that an XMLTable object or objects is associated with an XMLAdapter object, before attempting to call the ToXML method.

  • Execute the XMLAdapter objects, AddTableSchema method, to create the XMLTable and XMLField collections, or otherwise create these items.


Expression is invalid. Use a valid expression for "name" property (Error 1759)

Visual FoxPro 9.0
Expression is invalid. Use a valid expression for "name" property (Error 1759)

The expression you entered for a grid property is not valid. The expression is cleared from the property setting.

  • If you are setting the expression in the AfterRowColChange event of the grid, the error itself causes the event to fire again, leading to an recurring loop of error messages.

    Press Cancel in the dialog box to disable the expression. You will not be able to set or change the expression.

  • The expression contains syntax errors.

    Make sure your expression is valid and without syntax errors.

  • Variables in the expression are not scoped properly.

    Make sure that any variables you use in the expression are globally scoped, or scoped to the form. If your expression contains a variable that is local to the function that you are setting the expression in, the variable will go out of scope when the function returns. However, the expression will be evaluated in the future when the grid tries to paint, and this will cause an error.


Too many windows open (Error 1116)

Visual FoxPro 9.0
Too many windows open (Error 1116)

No more windows can be created.

  • You have too many application windows open.

    Close open applications.

  • There are not enough resources available.

    Restart Windows.


Command cannot be issued on a table with cursors in table buffering mode (Error 1579)

Visual FoxPro 9.0
Command cannot be issued on a table with cursors in table buffering mode (Error 1579)

Change the buffering mode to a non-table mode before executing this command.


There is not enough memory to complete this operation (Error 43)

Visual FoxPro 9.0
There is not enough memory to complete this operation (Error 43)

Free some memory currently in use and try this operation again.


Command is allowed only in interactive mode (Error 1297)

Visual FoxPro 9.0
Command is allowed only in interactive mode (Error 1297)

You are attempting to use a command that is only allowed in interactive mode. This command can be issued only through the Command window.


Cannot divide by 0 (Error 1307)

Visual FoxPro 9.0
Cannot divide by 0 (Error 1307)

You specified 0 (zero) as the second argument in the MOD( ) function.


Property is invalid for table cursors (Error 1468)

Visual FoxPro 9.0
Property is invalid for table cursors (Error 1468)

The property is not supported for cursors based on tables; it applies only to cursors based on views. Use the property only for view cursors.

For a cursor created by a CursorAdapter object, the SQL property for CURSORGETPROP( ) is not valid for table cursors when the DataSourceType property is specified as "XML".


Cannot redefine a menu that is in use (Error 174)

Visual FoxPro 9.0
Cannot redefine a menu that is in use (Error 174)

You have attempted to issue a DEFINE MENU command while the menu is active in memory.

Issue a DEACTIVATE MENU command first.


Result is incompatible with cursor schema. (Error 2074)

Visual FoxPro 9.0
Result is incompatible with cursor schema. (Error 2074)

Occurs if the CursorFill method is called with the lUserCursorSchema parameter set to True (.T.), and the field definitions do not match with the type or precision of the fields in the base table.

  • Make sure that the field types and precisions match the base table.

  • The lUserCursorSchema parameter should only be used if necessary, such as when converting XML that does not have a schema, and you need to control the field types.


.DIF file header is invalid (Error 115)

Visual FoxPro 9.0
.DIF file header is invalid (Error 115)

The .dif file header is incorrect.


Printer is not ready (Error 125)

Visual FoxPro 9.0
Printer is not ready (Error 125)

The printer device specified is currently not accessible or the printer is timing out.


SQL: Out of memory (Error 1809)

Visual FoxPro 9.0
SQL: Out of memory (Error 1809)

Visual FoxPro has run out of memory while trying to process your SELECT command. For more information, see SELECT - SQL Command.


Not a ProjectHook class. (Error 1439)

Visual FoxPro 9.0
Not a ProjectHook class. (Error 1439)

The default ProjectHook class you specify as a template for new projects must be based on a ProjectHook class.


Statement is only valid within a class definition (Error 1928)

Visual FoxPro 9.0
Statement is only valid within a class definition (Error 1928)

PROTECTED, ADD OBJECT, and ADD PROTECTED OBJECT commands are valid only within a class definition. For more information, see DEFINE CLASS Command.


Unable to emit XML, two or more cursors use different code pages. (Error 2133)

Visual FoxPro 9.0
Unable to emit XML, two or more cursors use different code pages. (Error 2133)

Occurs when attempting to call an XMLAdapter objects, ToXML method, when the XMLAdapter objects, AddTableSchema method, was used to add a schema from two or more cursors that have differing code pages.

  • Check to make sure that all of the cursors being converted to XML have the same code page.


File cannot be closed because outstanding references exist (Error 1184)

Visual FoxPro 9.0
File cannot be closed because outstanding references exist (Error 1184)

Outstanding references exist to an object in this form or form set.


.SYLK file format is invalid (Error 121)

Visual FoxPro 9.0
.SYLK file format is invalid (Error 121)

The file you have attempted to import is not in a valid SYLK file format.


The class file associated with this field cannot be found - class association cleared. (Error 2020)

Visual FoxPro 9.0
The class file associated with this field cannot be found - class association cleared. (Error 2020)

The class is not valid or cannot be found.

  • You modified a table that had a field/class association whose class file could not be read.

    Assign a valid class to the field.


Error creating table: "name" (Error 1973)

Visual FoxPro 9.0
Error creating table: "name" (Error 1973)

The table definition used in the FROM clause of the CREATE TABLE command contains an invalid field definition.


Unable to set external schema location when inline schema is used. (Error 2123)

Visual FoxPro 9.0
Unable to set external schema location when inline schema is used. (Error 2123)

The value of the XMLAdapter property, XMLSchemaLocation, cannot be set to Inline Schema (1), when the cSchemaLocation parameter has been populated.


Declare DLL call caused an exception. (Error 2027)

Visual FoxPro 9.0
Declare DLL call caused an exception. (Error 2027)

The parameters passed to a DLL caused an exception in the DLL.

Make sure that you pass all the necessary parameters to the DLL and that the parameters are of the proper type.


Not enough memory for file map (Error 1150)

Visual FoxPro 9.0
Not enough memory for file map (Error 1150)

There is not enough memory for Visual FoxPro to allocate memory for a Visual FoxPro internal resource.

  • Available memory is extremely limited.

    Add memory or remove memory-resident programs to give Visual FoxPro more working memory.


CursorAdapter does not have an associated cursor. (Error 2090)

Visual FoxPro 9.0
CursorAdapter does not have an associated cursor. (Error 2090)

Occurs when calling an operation that requires an attached cursor, but there is not an associated cursor for the CursorAdapter object.

  • Check to make sure that the CursorAdapter object has an associated cursor.


Warning: The connection sync/async mode cannot be set (Error 1480)

Visual FoxPro 9.0
Warning: The connection sync/async mode cannot be set (Error 1480)

The connection sync/async mode cannot be set by the ODBC driver. The connection will use the default driver defined sync/async mode. This will not allow SQL pass-through functions to return control while an ODBC call is in progress.


The network request is not supported (Error 1793)

Visual FoxPro 9.0
The network request is not supported (Error 1793)

Visual FoxPro was unable to obtain information about a file on the network.

  • There are no drive letters available.

    Free up a drive letter and try the request again.


Multiplan version 4.0 file format is invalid (Error 1670)

Visual FoxPro 9.0
Multiplan version 4.0 file format is invalid (Error 1670)

The Multiplan file you have attempted to import is either not version 4.0 or has been corrupted.


SQL pass-through internal consistency error (Error 1465)

Visual FoxPro 9.0
SQL pass-through internal consistency error (Error 1465)

Internal SQL pass-through error.

Record your recent actions while using Visual FoxPro and then call Microsoft Support.


Cannot delete file "name". (Error 2030)

Visual FoxPro 9.0
Cannot delete file "name". (Error 2030)

Visual FoxPro is unable to delete a file. For example, Visual FoxPro cannot delete a file if the file is marked as read-only.


Cannot find object "name" in the database (Error 1562)

Visual FoxPro 9.0
Cannot find object "name" in the database (Error 1562)

A reference has been made to a database object that cannot be found in the database. Use DISPLAY DATABASE or LIST DATABASE to confirm the names of the existing database objects.


Unable to attach object with empty XMLName property. (Error 2101)

Visual FoxPro 9.0
Unable to attach object with empty XMLName property. (Error 2101)

The XMLName field cannot be empty when adding an XMLTable object or an XMLField object to a collection.

  • Make sure that the XMLName property for the XMLField object or the XMLTable object is set to a valid value, and that this value is used as the key.


Removing a class member is not allowed (Error 2016)

Visual FoxPro 9.0
Removing a class member is not allowed (Error 2016)

An instance of a class cannot remove class members.

  • You tried to use RemoveObject.

    Use AddObject and then set the CurrentControl property.


Source field for refresh is not found (Error 2167)

Visual FoxPro 9.0
Source field for refresh is not found (Error 2167)

An attempt was made to refresh more fields than were returned by the REFRESH( ) Function.


Invalid file descriptor (Error 1111)

Visual FoxPro 9.0
Invalid file descriptor (Error 1111)

Visual FoxPro is unable to open a file.

Record your recent actions while using Visual FoxPro and then call Microsoft Support.


Recursive XMLTable nesting is not allowed (Error 2187)

Visual FoxPro 9.0
Recursive XMLTable nesting is not allowed (Error 2187)

An XMLTable Class cannot be nested into itself or into any descendant XMLTable.


Variable must be in the selected table (Error 1134)

Visual FoxPro 9.0
Variable must be in the selected table (Error 1134)

You can only use fields from the currently selected table in quick screens.


"OLE error" (Error 1429)

Visual FoxPro 9.0
"OLE error" (Error 1429)

The Automation server is transmitting an error to Visual FoxPro.

  • This error text was passed to Visual FoxPro from the Automation server.


Row or column position is off the screen (Error 30)

Visual FoxPro 9.0
Row or column position is off the screen (Error 30)

A row or column number specified in an @ command is larger than the number of rows or columns on the screen, window, or printer.


Too many names used (Error 1201)

Visual FoxPro 9.0
Too many names used (Error 1201)

As a program was being loaded or a table was being opened, the Visual FoxPro name table overflowed.

Divide the program into smaller modules.


ALTER TABLE operation interrupted (Error 1870)

Visual FoxPro 9.0
ALTER TABLE operation interrupted (Error 1870)

You have interrupted the ALTER TABLE command during the copying of records to the new record format. Some data might not have been copied. Verify the data.


SQL: WHERE clause is invalid (Error 1833)

Visual FoxPro 9.0
SQL: WHERE clause is invalid (Error 1833)

There is an error in the WHERE clause. For more information, see SELECT - SQL Command.


"name" is not a file variable (Error 226)

Visual FoxPro 9.0
"name" is not a file variable (Error 226)

A variable or an array was used where a file variable (table field) is required. For more information, see Fields, or Working with Fields and Records..


Cannot locate the COMSPEC environment variable (Error 1412)

Visual FoxPro 9.0
Cannot locate the COMSPEC environment variable (Error 1412)

Visual FoxPro can't find an environment variable it needs. This error usually occurs when you try to run Visual FoxPro from within another program and MS-DOS environment variables are passed improperly.


SQL: Statement is invalid (Error 1804)

Visual FoxPro 9.0
SQL: Statement is invalid (Error 1804)

There is an error in the projection list. For more information, see SELECT - SQL Command.


Command contains invalid character (Error 1220)

Visual FoxPro 9.0
Command contains invalid character (Error 1220)

The source line contains an invalid character. This is probably caused by control characters embedded in the source line by an external editor.


Error reading file "file" (Error 1104)

Visual FoxPro 9.0
Error reading file "file" (Error 1104)

The operating system returned an error while Visual FoxPro was attempting to read the specified file.


Cannot arrange an untransported form (Error 1795)

Visual FoxPro 9.0
Cannot arrange an untransported form (Error 1795)

When you move screens between different FoxPro 2.x platforms, you must transport the screens with the Transporter (TRANSPRT.PRG) before they can be arranged.


Invalid variable reference (Error 1223)

Visual FoxPro 9.0
Invalid variable reference (Error 1223)

A function was used where a variable was expected.

Replace the reference with a valid variable or array name.


SELECTs are not UNION compatible. "Details" (Error 1851)

Visual FoxPro 9.0
SELECTs are not UNION compatible. "Details" (Error 1851)

This occurred for one of the following possible reasons:

  • The number of fields do not match. Make sure the number of fields match.

  • The specified fields are not compatible. Make sure the specified fields are compatible.

  • Data types or sizes of fields being projected in each SELECT statement are not identical.


The IN clause is not supported for this window (Error 1699)

Visual FoxPro 9.0
The IN clause is not supported for this window (Error 1699)

This window cannot be placed inside another window.

  • You used the ACTIVATE WINDOW command to try and place one of the debugger windows inside another window.

    Use a different window, or change your debugging environment in the Debug tab of the Options dialog box.


RETURN/RETRY statement not allowed in TRY/CATCH. (Error 2060)

Visual FoxPro 9.0
RETURN/RETRY statement not allowed in TRY/CATCH. (Error 2060)

A RETURN statement cannot appear in a TRY...CATCH...FINALLY structure.


Index "name" is in use and cannot be closed (Error 2200)

Visual FoxPro 9.0
Index "name" is in use and cannot be closed (Error 2200)

This error is generated by SQL engine when an attempt is made to close an index tag while that tag is in use. The error can occur if you attempt to delete a tag while it is in use such as from a UDF() called by a SELECT - SQL Command.


Property value is invalid (Error 1560)

Visual FoxPro 9.0
Property value is invalid (Error 1560)

This error can occur under the following conditions.

  • The value set for the property of a cursor or database object is not in the range or type defined for that property.

  • When RowSourceType is set to 10 (Collection), RowSource must specify a Collection object.

Check for valid values and change the value to match the property type.


Array is not a member of the parent object (Error 1764)

Visual FoxPro 9.0
Array is not a member of the parent object (Error 1764)

Check your array references.


Class "name" already exists (Error 1761)

Visual FoxPro 9.0
Class "name" already exists (Error 1761)

The ADD CLASS or RENAME CLASS command was issued with a class name that already exists in the class library.


A table in multiple relationships can only have one child order (Error 1889)

Visual FoxPro 9.0
A table in multiple relationships can only have one child order (Error 1889)

You have specified more than one child order for a table in multiple relationships. This operation is not allowed.


Alias name is already in use (Error 24)

Visual FoxPro 9.0
Alias name is already in use (Error 24)

You have attempted to use a table with an alias that is associated with another table already in use.


Error in the PICTURE clause (Error 1258)

Visual FoxPro 9.0
Error in the PICTURE clause (Error 1258)

The compiler has detected an error when compiling a PICTURE clause. A picture must be a valid bitmap (.BMP) or icon (.ICO) file.


Syntax error: "name" is not allowed in the view script or is in the wrong place (Error 2093)

Visual FoxPro 9.0
Syntax error: "name" is not allowed in the view script or is in the wrong place (Error 2093)

Invalid syntax was used in the script of the View Designer. Make sure the code entered conforms to proper syntax for the SELECT - SQL Command.


Not enough memory to open a table with the USE command (Error 1600)

Visual FoxPro 9.0
Not enough memory to open a table with the USE command (Error 1600)

There was not enough memory to open an additional table.


Unable to change XMLName property while XMLTable object belongs to XMLAdapter object. (Error 2102)

Visual FoxPro 9.0
Unable to change XMLName property while XMLTable object belongs to XMLAdapter object. (Error 2102)

Visual FoxPro does not allow the XMLName property for an XMLTable object, to be changed, when the XMLTable object belongs to an XMLAdapter object.


The validation rule for field "name" does not evaluate to a logical or NULL type (Error 1996)

Visual FoxPro 9.0
The validation rule for field "name" does not evaluate to a logical or NULL type (Error 1996)

The field validation rule result must be either a Logical type or a NULL.


Index expression exceeds maximum length (Error 23)

Visual FoxPro 9.0
Index expression exceeds maximum length (Error 23)

The index expression for this index exceeds the maximum length of 220 bytes.


The specified file or path was not found. (Error 2022)

Visual FoxPro 9.0
The specified file or path was not found. (Error 2022)

The file that you attempted to drop in an OLE drag-and-drop operation could not be located.


Table "name" already exists in the database (Error 1564)

Visual FoxPro 9.0
Table "name" already exists in the database (Error 1564)

You have attempted to add a table to the database that was already in the database.


Parent object will not allow this property setting for "name" (Error 1767)

Visual FoxPro 9.0
Parent object will not allow this property setting for "name" (Error 1767)

You have attempted to set a property value on an object whose parent is controlling the setting of that property.

For example, when you try to set the ControlSource property of a contained control in a grid column, and the Bound property for the grid column has been set to true (.T.), you will get this error message because the ControlSource property for the control is taken from the grid column's ControlSource Property.


Function is not supported on remote tables (Error 1525)

Visual FoxPro 9.0
Function is not supported on remote tables (Error 1525)

The command or function you are using — for instance, PACK or ALTER TABLE — is not applicable to remote tables.


SQL: DISTINCT is invalid (Error 1819)

Visual FoxPro 9.0
SQL: DISTINCT is invalid (Error 1819)

You can use only one DISTINCT clause per level.


BEGIN TRANSACTION command failed. Nesting level is too deep (Error 1590)

Visual FoxPro 9.0
BEGIN TRANSACTION command failed. Nesting level is too deep (Error 1590)

Transactions may only be nested 5 levels deep.

  • You must end a transaction before another transaction can begin.

    Call END TRANSACTION or ROLLBACK first.


CursorAdapter "name" cannot be loaded for design. (Error 2078)

Visual FoxPro 9.0
CursorAdapter "name" cannot be loaded for design. (Error 2078)

Visual FoxPro cannot instantiate the cursor adapter.


Data session #number was forced to ROLLBACK all transactions to avoid deadlock (Error 1599)

Visual FoxPro 9.0
Data session #number was forced to ROLLBACK all transactions to avoid deadlock (Error 1599)

A deadlock was detected from another data session attempting to lock an index or memo file held by data session #number. A forced ROLLBACK was completed, leaving data session number in an error state.

Issue the appropriate number of ROLLBACK commands to clear the error state. These situations can be avoided by setting SYS(3052) on for index and memo files.


Invalid path or file name (Error 202)

Visual FoxPro 9.0
Invalid path or file name (Error 202)

You attempted to execute a Visual FoxPro command that contains an invalid path or file name.


Improper data type in the group expression (Error 1241)

Visual FoxPro 9.0
Improper data type in the group expression (Error 1241)

A picture data type was encountered by REPORT for the group expression.


Error building key for index "name". (Error 2199)

Visual FoxPro 9.0
Error building key for index "name". (Error 2199)
See Also

This error is generated when index key truncation is about to occur, typically during index creation or modification such as with the INDEX command. This can happen with use of a key that contains an expression involving a Memo field, whose length in not fixed, such as in the following example:

INDEX ON charfld1 + memofld1 TAG mytag

An index file with truncated index keys is a source for potentially incorrect data results. Visual FoxPro does not allow for key truncation during index creation or modification. When index key truncation is about to occur, this error is reported. If you desire key truncation, you should adjust the index expression to explicitly truncate the key.

Due to issues associated with key truncation, the SQL engine (such as during a SQL SELECT command or View creation) might fail to build a temporary index to optimize a join evaluation if it is unable to accurately determine the maximum size of the key. This might cause the join to be evaluated as a Cartesian product and as a result could impact performance. To allow you to diagnose this issue, a message is included in the SQL ShowPlan, which is controlled by the SYS(3054) function. When this function value is greater than or equal to 11, the message "Error building temporary index" is included in the ShowPlan to indicate the key truncation problem. You can fix this problem by adjusting join conditions to make the key size more explicit and to allow the temporary index to be built successfully.

Occasionally, the SQL engine will build a temporary composite index (this is a special index created internally by the product and is not supported through the INDEX command). In this case, some parts of the index may cause key truncation, while others might not. During the first attempt to build the index, those parts which cause problems are identified. The offensive parts are then removed from the key and the index is built again without them. The SQL ShowPlan will indicate this problem, but it is still possible that the join can still be optimized using valid parts only.

See Also

Reference

SYS(3054) - Rushmore Query Optimization Level
SELECT - SQL Command
INDEX Command

Concepts

Join Conditions for Tables, Queries, and Views


Menu specified in ACTIVATE POPUP is already in use (Error 182)

Visual FoxPro 9.0
Menu specified in ACTIVATE POPUP is already in use (Error 182)

You have attempted to activate a menu that is already activated.


Property "name" is read-only (Error 1743)

Visual FoxPro 9.0
Property "name" is read-only (Error 1743)

You cannot change the value of a read-only property.


Property does not have a default value. (Error 1138)

Visual FoxPro 9.0
Property does not have a default value. (Error 1138)

ResetToDefault can only be called for properties that have inheritable default values.

  • The property is read-only or is one of the following:

    Alias, ChildOrder , CursorSource., Database, Name, Order, ParentAlias, RelationalExpr.


Cannot base a view on itself (Error 1952)

Visual FoxPro 9.0
Cannot base a view on itself (Error 1952)

You have attempted to modify a view in the View Designer by selecting Add, and then selecting the view being modified as a base view from the dialog box. This is not a valid operation.


Feature is only available if the object is in design mode (Error 1953)

Visual FoxPro 9.0
Feature is only available if the object is in design mode (Error 1953)

The operation you have attempted is only valid in design mode.


Browse structure has changed (Error 1164)

Visual FoxPro 9.0
Browse structure has changed (Error 1164)

The structure of a Browse window was changed by a Browse validation routine.


Subscript is outside defined range (Error 1234)

Visual FoxPro 9.0
Subscript is outside defined range (Error 1234)

An attempt was made to reference an array element with a subscript outside of the range defined for the array using the DIMENSION command.

For example, copying a member array to an existing non-member array with certain dimensions using the ACOPY( ) function might generate this error. You can avoid this error changing the dimension of the destination array to a single element before calling ACOPY( ). For more information, see ACOPY( ) Function and DIMENSION Command.


Compiled code for this line is too long (Error 1252)

Visual FoxPro 9.0
Compiled code for this line is too long (Error 1252)

The object code produced for this statement exceeded the size of the Visual FoxPro internal code buffer.

  • This line contains too many long expressions.

    Subdivide the line into multiple statements.


Form (.SCX) file must contain at least one Form (Error 1749)

Visual FoxPro 9.0
Form (.SCX) file must contain at least one Form (Error 1749)

To add a form to an .scx file, use the Form Designer.


SQL: Index is not found (Error 1830)

Visual FoxPro 9.0
SQL: Index is not found (Error 1830)

Visual FoxPro could not find the existing index. For more information, see SELECT - SQL Command.


File is in use by another user (Error 108)

Visual FoxPro 9.0
File is in use by another user (Error 108)

You have attempted a USE, DELETE, or RENAME command on a file that is being used by another user on a network.


Cursor "name" does not have a valid table or view reference (Error 2067)

Visual FoxPro 9.0
Cursor "name" does not have a valid table or view reference (Error 2067)

The specified cursor class does not have a table or view name that can be resolved to the associated database.


A .DBF-style Help file is required (Error 1727)

Visual FoxPro 9.0
A .DBF-style Help file is required (Error 1727)

SET HELPFILTER works only with a .DBF-style help file.


"name" cannot be enumerated (Error 1794)

Visual FoxPro 9.0
"name" cannot be enumerated (Error 1794)

The FOR EACH ... ENDFOR Command can only be used to enumerate a Visual FoxPro array, an OLE array, a Visual FoxPro collection, or an OLE collection.


Cannot build a DLL without OLE public classes (Error 2002)

Visual FoxPro 9.0
Cannot build a DLL without OLE public classes (Error 2002)

The BUILD DLL command requires that OLE public classes be defined.

  • You chose the wrong option from the Build Options dialog box.

    Choose another action, such as Build Application.

  • No OLE public classes are defined.

    Define one or more OLE public classes. For more information, see the Class Info dialog box or the OLEPUBLIC clause of the DEFINE CLASS command.


Menu title has not been defined with DEFINE PAD (Error 164)

Visual FoxPro 9.0
Menu title has not been defined with DEFINE PAD (Error 164)

There is a reference to a menu title that doesn't exist. For more information, see DEFINE PAD Command.


Illegal printer driver recursion (Error 1910)

Visual FoxPro 9.0
Illegal printer driver recursion (Error 1910)

Your printer driver program calls upon the printer driver.


Invalid Insert refresh column name "column name" (Error 2161)

Visual FoxPro 9.0
Invalid Insert refresh column name "column name" (Error 2161)

The Insert refresh column name is invalid or can’t be found in the cursor.


Suspend program before using RESUME (Error 1236)

Visual FoxPro 9.0
Suspend program before using RESUME (Error 1236)

RESUME is applicable only when a program is suspended.


Filter expression is not allowed for a Binary index (Error 2157)

Visual FoxPro 9.0
Filter expression is not allowed for a Binary index (Error 2157)

A binary index can not contain a filtered expression. For example, the FOR clause in the INDEX command cannot be included when creating a binary index. See Visual FoxPro Index Types for more information on creating binary indexes.


No menu titles have been defined for this menu (Error 1621)

Visual FoxPro 9.0
No menu titles have been defined for this menu (Error 1621)

You attempted to activate a menu that has no titles.


Invalid Update refresh key column name "column name" (Error 2164)

Visual FoxPro 9.0
Invalid Update refresh key column name "column name" (Error 2164)

The Update refresh key column name is invalid or cannot be found in the cursor.


Offline view must be used online for this command (Error 2015)

Visual FoxPro 9.0
Offline view must be used online for this command (Error 2015)

When you are using a view in administrator mode, normal online use and table update operations are not valid. For more information, see the VIEW ADMIN clause of the USE command.


Include file "name" is not found (Error 1994)

Visual FoxPro 9.0
Include file "name" is not found (Error 1994)

The file specified in the form does not exist or #INCLUDE contains an invalid reference.


Product has not been properly installed.

Visual FoxPro 9.0
Product has not been properly installed.

Reinstall your copy of Visual FoxPro.


Field "name" does not accept null values (Error 1581)

Visual FoxPro 9.0
Field "name" does not accept null values (Error 1581)

You attempted to store a null value in a field that does not accept null values.

You can change this setting by checking the NULL checkbox when modifying a field in the Table Designer, or specifying the NULL keyword in a field definition.


Cannot modify a class that is in use (Error 1948)

Visual FoxPro 9.0
Cannot modify a class that is in use (Error 1948)

You have attempted to modify a class that is currently in use.

Use CLEAR CLASS to release the class definition from memory and try again.


Constant is already created with #DEFINE (Error 1725)

Visual FoxPro 9.0
Constant is already created with #DEFINE (Error 1725)

The constant has already been defined with #DEFINE.

Use #UNDEF to release it before redefining.


End of file encountered (Error 4)

Visual FoxPro 9.0
End of file encountered (Error 4)

The record pointer was positioned past the last record in the file.


Total field type must be Date or Numeric (Error 1646)

Visual FoxPro 9.0
Total field type must be Date or Numeric (Error 1646)

A report expression that includes a total specification is not numeric type.


Invalid Insert refresh key column name "column name" (Error 2162)

Visual FoxPro 9.0
Invalid Insert refresh key column name "column name" (Error 2162)

The Insert refresh key column name is invalid or can’t be found in the cursor.


Unable to close offline view in ADMIN/ONLINE mode inside a transaction. (Error 2122)

Visual FoxPro 9.0
Unable to close offline view in ADMIN/ONLINE mode inside a transaction. (Error 2122)

You cannot close an offline view in ADMIN or ONLINE mode from within a transaction.


Cannot delete a database object while it is open in a designer (Error 1572)

Visual FoxPro 9.0
Cannot delete a database object while it is open in a designer (Error 1572)

A view or connection is open in a designer.

  • You tried to delete the view or connection in the Command window or from the Database Designer.

    Close the View Designer or the Connection Designer first.


Maximum menu item length (50) is exceeded (Error 1609)

Visual FoxPro 9.0
Maximum menu item length (50) is exceeded (Error 1609)

Reduce the number of menu items.


Too many columns (Error 1872)

Visual FoxPro 9.0
Too many columns (Error 1872)

You can have a maximum of 255 fields per record.


OLE object is invalid or corrupted (Error 1420)

Visual FoxPro 9.0
OLE object is invalid or corrupted (Error 1420)

The data stored in a general field for an OLE object cannot be validated.


Cannot access the selected table (Error 1152)

Visual FoxPro 9.0
Cannot access the selected table (Error 1152)

You have attempted to select a table outside the 32K work area range or are attempting to reference a file variable in a table that is not open. This error can occur under the following conditions:

  • A table or cursor that is specified for the RowSource property of a ComboBox or ListBox control is closed.

    If you want to close a table or cursor that is specified for the RowSource property of a ComboBox or ListBox control, perform either of the following actions prior to closing the table or cursor:

    • Set the RowSource property to an empty value ("").

    -OR-

    • Release the form containing the ComboBox or ListBox control.

  • A SQL SELECT statement that recreates a table or cursor that is specified by the RowSource property is issued. When the SQL SELECT statement executes, Visual FoxPro closes then opens the table.

    To avoid this error, set the RowSource property to an empty value (""), issue the SQL SELECT statement, and reset the RowSource property to its previous value.


Line is too long (Error 18)

Visual FoxPro 9.0
Line is too long (Error 18)

The maximum length for a command line (8,192 bytes) has been exceeded.

  • Macro substitution might have caused the line to expand beyond the 8,192-byte limit.


The "name" event has failed (Error 2089)

Visual FoxPro 9.0
The "name" event has failed (Error 2089)

The specified CursorAdapter event failed for an unknown reason. Check to ensure that the event (such as BeforeCursorFill Event) and possible related method call (such as CursorFill Method) are valid and have no associated errors.


The clipboard contained one or more objects that could not be added to the container. Those objects were not pasted (Error 1969)

Visual FoxPro 9.0
The clipboard contained one or more objects that could not be added to the container. Those objects were not pasted (Error 1969)

You have attempted to paste something invalid ? for instance, a toolbar separator ? onto a form or control.


Cursor is corrupt or in wrong format (Error 1166)

Visual FoxPro 9.0
Cursor is corrupt or in wrong format (Error 1166)

You have attempted to set the DragIcon property to an invalid .CUR file. A valid .CUR file must include an uncorrupted black and white cursor.


SQL: Table for UPDATE or DELETE cannot be outer joined (Error 2150)

Visual FoxPro 9.0
SQL: Table for UPDATE or DELETE cannot be outer joined (Error 2150)

The table specified in an UPDATE - SQL Command or a DELETE - SQL Command cannot be used in an outer join. This error is generated when the target table in an UPDATE - SQL command or a DELETE - SQL command is a secondary table in an outer join.


Too many PROCEDURE commands are in effect (Error 1250)

Visual FoxPro 9.0
Too many PROCEDURE commands are in effect (Error 1250)

The number of procedures is limited to the amount of memory you have.


Error loading the data environment. Table is in use (Error 1995)

Visual FoxPro 9.0
Error loading the data environment. Table is in use (Error 1995)

Check to see if the table has been opened exclusively in another data session.


Cannot find view "name" in the current database (Error 1563)

Visual FoxPro 9.0
Cannot find view "name" in the current database (Error 1563)

The name you have specified is not the name of a view in the current database. Check that the name entered is correct and that the current database is the required database. Use DISPLAY VIEWS or LIST VIEWS to confirm the names of the existing database views.

If the view name is in the list, the .dbc index might be corrupted.

To rebuild the index

  1. Close the database.

  2. Delete the index file (database_name.DCX).

  3. Re-open the database.

  4. Re-create the index.


Relation already exists. (Error 1183)

Visual FoxPro 9.0
Relation already exists. (Error 1183)

The tables are already related.


Field for Unicode value should not use code page translation. (Error 2142)

Visual FoxPro 9.0
Field for Unicode value should not use code page translation. (Error 2142)

Occurs when Visual FoxPro attempts to convert Unicode data to or from XML, and the NoCpTrans property evaluates to False (.F.).

  • Check to make sure that your character and memo fields being used for Unicode data have the NoCpTrans property set to True (.T.).


Property setting will not take effect until data environment reloaded (Error 1739)

Visual FoxPro 9.0
Property setting will not take effect until data environment reloaded (Error 1739)

You attempted to set a property on a data environment object (Relation, Cursor) while the data environment is loaded. The property value will be stored with the object, but the property will not take effect until the data environment is unloaded and then reloaded.

To unload the data environment

  1. Issue CloseTables in the form:

    Copy Code
    [Formset.]Form.DataEnvironment.CloseTables

To reload the data environment

  1. Issue OpenTables in the form:

    Copy Code
    [Formset.]Form.DataEnvironment.OpenTables


The builder program is already running (Error 1954)

Visual FoxPro 9.0
The builder program is already running (Error 1954)

You have attempted to invoke a builder program while the builder is already running. This is not a valid operation.


The current object has been released (Error 1945)

Visual FoxPro 9.0
The current object has been released (Error 1945)

You have issued RELEASE THIS in the destroy event of the current object.


SQL: Too many fields in UPDATE (Error 1864)

Visual FoxPro 9.0
SQL: Too many fields in UPDATE (Error 1864)

You have attempted to issue UPDATE - SQL with more than 128 fields to update.


Cannot nest aggregate functions (Error 1844)

Visual FoxPro 9.0
Cannot nest aggregate functions (Error 1844)

Nesting of the aggregate functions MIN( ), MAX( ), and/or the CALCULATE command sub functions: AVG( ), CNT( ), MAX( ), MIN( ), NPV( ), STD( ), SUM( ), or VAR( ), is not permitted.


Too many extensions are specified (Error 1694)

Visual FoxPro 9.0
Too many extensions are specified (Error 1694)

Too many file extensions have been included in a GETFILE( ), LOCFILE( ), or PUTFILE( ) function.

Include no more than 30 file extensions.


Compile error in file "name" (Error 1981)

Visual FoxPro 9.0
Compile error in file "name" (Error 1981)

You have attempted to add stored procedures to a database with the FROM clause of the APPEND PROCEDURES command, from a file which cannot be successfully compiled. Check that the file contains valid code.


Cannot find the text generation program (Error 1791)

Visual FoxPro 9.0
Cannot find the text generation program (Error 1791)

The program that generates text versions of binary files for source control cannot be located.

  • The _SCCTEXT system variable does not contain a valid file name.

    Verify the value of _SCCTEXT.


Line number must be less than page length (Error 222)

Visual FoxPro 9.0
Line number must be less than page length (Error 222)

The line number used falls beyond the page length variable.


Class name is invalid (Error 1949)

Visual FoxPro 9.0
Class name is invalid (Error 1949)

The class name you have specified is not valid or does not exist.


XMLAdapter XMLName property is an XPath expression (Error 2180)

Visual FoxPro 9.0
XMLAdapter XMLName property is an XPath expression (Error 2180)
  • The XMLAdapter Class ToXML Method generates this error if the XMLNameIsXPath Property is set to true (.T.) and the XMLName Property is not empty.

  • The XMLAdapter Class ApplyDiffgram Method and the ChangesToCursor Method generate this error if the XMLNameIsXPath Property is set to true (.T.).

  • The XMLTable Class ToCursor Method generates this error if both the XMLAdapter Class XMLNameIsXPath Property and the IsDiffGram Property are set to true (.T.).


Property "name" has invalid value. (Error 2145)

Visual FoxPro 9.0
Property "name" has invalid value. (Error 2145)

Occurs when the CursorAdapter objects UpdateableFieldList and UpdateNameList properties are set to invalid values.

  • Make sure the values assigned to the above properties are valid. For more information see, Data Access Management Using CursorAdapters.


Not a valid Framework II database/spreadsheet (Error 256)

Visual FoxPro 9.0
Not a valid Framework II database/spreadsheet (Error 256)

The file you have attempted to import is not a valid Framework II file format.


Invalid subscript reference (Error 31)

Visual FoxPro 9.0
Invalid subscript reference (Error 31)

A subscript was used that is outside of the valid range of array subscripts defined in the DIMENSION statement. This might also be caused by using two subscripts with a one-dimensional array.


Error copying the OLE object to Clipboard (Error 1424)

Visual FoxPro 9.0
Error copying the OLE object to Clipboard (Error 1424)

There are not enough resources available.


A member object with this name already exists (Error 1771)

Visual FoxPro 9.0
A member object with this name already exists (Error 1771)

You tried to add a member object to a container that already has a member with the same name.

  • Member objects must have unique names within a given container.

    Review your member names.


Cannot create offline view on a currently modified view (Error 2019)

Visual FoxPro 9.0
Cannot create offline view on a currently modified view (Error 2019)

CREATEOFFLINE is not a valid operation.

  • You are modifying the view in the View Designer..

    Close the view and try CREATEOFFLINE again.


Page frame cannot be sized that small (Error 1413)

Visual FoxPro 9.0
Page frame cannot be sized that small (Error 1413)

Page frames must be tall enough to display one row of tabs, if the Tabs property is set; otherwise, they must be at least one pixel tall.

  • You tried to resize the page frame to less than the height of one row of tabs.

    Make the page frame taller.


Cannot visually modify a class of this type (Error 1978)

Visual FoxPro 9.0
Cannot visually modify a class of this type (Error 1978)

You have attempted to create a class based on one of the Cursor, DataEnvironment, Page, Column, Header, or Relation base classes. You cannot visually modify any of these base class types.


Unable to register the ActiveX control (Error 1437)

Visual FoxPro 9.0
Unable to register the ActiveX control (Error 1437)

The file does not appear to be a valid ActiveX control.

  • The ActiveX control does not have a self-registration function.

    Contact the ActiveX control vendor for an updated control that contains a working DllRegisterServer function.


To use this feature, set CODEPAGE=AUTO in your CONFIG.FPW file and restart Visual FoxPro (Error 1916)

Visual FoxPro 9.0
To use this feature, set CODEPAGE=AUTO in your CONFIG.FPW file and restart Visual FoxPro (Error 1916)

This error occurred due to an invalid designation with the SET COLLATE command.


Object "name" is not found (Error 1766)

Visual FoxPro 9.0
Object "name" is not found (Error 1766)

The object you have specified is protected and cannot be found.


Unable to create temporary work files (Error 1410)

Visual FoxPro 9.0
Unable to create temporary work files (Error 1410)

A SORT or INDEX command that requires temporary work files was not permitted by the operating system to create them.

  • Your directory is full.

    Remove some files.

  • Visual FoxPro does not have permission to access the temporary files directory.

    Verify your permissions.


Cannot define menu item (Error 169)

Visual FoxPro 9.0
Cannot define menu item (Error 169)

You have attempted to add a menu bar to a menu item that was defined with files or structure.


Invalid call issued while executing a SQLCOLUMNS( ) sequence (Error 1477)

Visual FoxPro 9.0
Invalid call issued while executing a SQLCOLUMNS( ) sequence (Error 1477)

An invalid SQL pass-through (SPT) function call has been made while a SQLCOLUMNS( ) call was expected to continue the SPT call sequence in progress.

Call SQLCANCEL( ) to cancel the SPT sequence or make valid SPT calls to finish the call sequence.


Visual FoxPro cannot start

Visual FoxPro 9.0
Visual FoxPro cannot start

Visual FoxPro cannot be initialized or configured for one of the following reasons:

  • Insufficient memory.

    Visual FoxPro could not allocate sufficient memory for internal structures. Free up memory and restart Visual FoxPro.

  • Insufficient disk space.

    Visual FoxPro could not allocate temporary files. Free up disk space and restart Visual FoxPro.

  • File name VFP<versionNumber>ENU.dll could not be loaded.

    Visual FoxPro cannot find the file because it is missing or has been renamed. Reinstall Visual FoxPro.

  • The resource file you specified with the -L startup switch could not be loaded.

    Visual FoxPro cannot find the file you specified. Check that the file you specified with the -L switch is available.

  • Visual FoxPro requires a supported Windows operating system.

    Install one of the supported Windows operating systems. For more information, see Installing Visual FoxPro.

  • Product in use by another.

    Make sure that you have the correct network access rights. See your Windows documentation.

  • Invalid or missing .EXE file.

    Reinstall Visual FoxPro.


The file specified in the FROM clause is empty (Error 1131)

Visual FoxPro 9.0
The file specified in the FROM clause is empty (Error 1131)

There are no records in this file.


A Key must be specified when adding an item to this collection. (Error 2063)

Visual FoxPro 9.0
A Key must be specified when adding an item to this collection. (Error 2063)

You must specify a key when adding a new item to a collection in which all items have keys. Either all items in a collection have keys or do not have keys. To determine if a collection requires keys, use GetKey(1) and the EMPTY( ) function as follows:

Copy Code
? EMPTY(Collection.GetKey(1))


The directory is not empty (Error 1962)

Visual FoxPro 9.0
The directory is not empty (Error 1962)

You cannot delete a directory that contains files or subdirectories.


File "name" already exists as part of a database (Error 1529)

Visual FoxPro 9.0
File "name" already exists as part of a database (Error 1529)

You have attempted to overwrite an existing file that is part of a database.

To avoid database corruption, first issue a REMOVE TABLE on the existing table from within its database.


Recordset does not exist (Error 2041)

Visual FoxPro 9.0
Recordset does not exist (Error 2041)

The specified ADO recordset could not be found.


Cursor "cursor name" is in use and cannot be closed (Error 2173)

Visual FoxPro 9.0
Cursor "cursor name" is in use and cannot be closed (Error 2173)

This error is generated when you attempt to close the cursor referenced by the RefreshAlias Property.


Key string is too long (Error 1257)

Visual FoxPro 9.0
Key string is too long (Error 1257)

The character expression included with KEYBOARD is too long. Reduce its length.


Cannot add this object to a Grid (Error 1768)

Visual FoxPro 9.0
Cannot add this object to a Grid (Error 1768)

You have attempted to execute the Grid.AddObject method to add an object other than a column to the grid.

  • You are trying to add an object to a column, rather than adding a column to the grid.

    To add an object to a column, use the Grid.Column syntax with the AddObject method.


Invalid argument used with the SET function (Error 231)

Visual FoxPro 9.0
Invalid argument used with the SET function (Error 231)

An invalid argument has been used with the SET( ) function.


Class "name" is not found in the class library (Error 1576)

Visual FoxPro 9.0
Class "name" is not found in the class library (Error 1576)

The class you have specified cannot be found.

Make sure you are using the correct class name.


Table "name" is referenced in a relation (Error 1577)

Visual FoxPro 9.0
Table "name" is referenced in a relation (Error 1577)

You cannot remove a table from a database if that table is involved in a relation.

Delete the relation first.


Cannot clear a menu that is in use (Error 176)

Visual FoxPro 9.0
Cannot clear a menu that is in use (Error 176)

You have attempted to clear an active menu.

  • The CLEAR MENU and RELEASE MENU commands cannot be applied to active menus.

    Use DEACTIVATE MENU before clearing or releasing the menu.


Unknown error code nExpr.

Visual FoxPro 9.0
Unknown error code nExpr.

No error number is returned. Visual FoxPro closes all open files and exits.

Record your recent actions while using Visual FoxPro and then call Microsoft Support.


Illegal operation for a table with pending changes (Error 2192)

Visual FoxPro 9.0
Illegal operation for a table with pending changes (Error 2192)

This error is generated by the MAKETRANSACTABLE( ) function if the table for which you want to enable transactions is pending changes.


"field" is not related to the current work area (Error 1165)

Visual FoxPro 9.0
"field" is not related to the current work area (Error 1165)

You have issued a command that requires a relation in order to exist.

For example, issuing SET SKIP TO prior to the relation being established would generate this error.

  • Issue SET RELATION Command prior to issuing the command that failed.


Warning: Invalid memo field conversion(s) starting at record "number" (Error 1486)

Visual FoxPro 9.0
Warning: Invalid memo field conversion(s) starting at record "number" (Error 1486)

A memo conversion error was reported while fetching large data in record number of the remote result set.

  • The ODBC driver cannot convert some large remote data values into the local view data type.

    Use a conversion function in the remote SQL statement to convert the data to a different data type before being fetched; use the DataType view field property to change the local data type. Use server-specific settings to limit the amount of data sent for each large data value.


Invalid data source type for RecordRefresh operation (Error 2168)

Visual FoxPro 9.0
Invalid data source type for RecordRefresh operation (Error 2168)

The data source type (XML, for example) specified with the DataSourceType property is invalid for the refresh operation.


Data environment "name" does not contain a cursor object. (Error 2068)

Visual FoxPro 9.0
Data environment "name" does not contain a cursor object. (Error 2068)

The Data Environment Designer does not open if the DataEnvironment class does not contain a CursorAdapter or Cursor object.


The refresh key defined for table "table name" is not unique (Error 2165)

Visual FoxPro 9.0
The refresh key defined for table "table name" is not unique (Error 2165)

The REFRESH( ) Function returned more than one row. Any changes are not reverted when Auto-refresh is used.


Not enough memory for filename (Error 1151)

Visual FoxPro 9.0
Not enough memory for filename (Error 1151)

There is not enough memory for Visual FoxPro to allocate memory for a Visual FoxPro internal resource.

  • Available memory is extremely limited.

    Add memory or remove memory-resident programs to give Visual FoxPro more working memory.


FontCharSet number is invalid (Error 2190)

Visual FoxPro 9.0
FontCharSet number is invalid (Error 2190)

This error is generated by the STRCONV( ) Function when an invalid character set or language script is specified with the nRegionalIDType parameter.


Illegal operation in rule evaluation (Error 2193)

Visual FoxPro 9.0
Illegal operation in rule evaluation (Error 2193)

This error is generated by the CLEAR Commands if it is executed when a rule is being evaluated.


Unknown member "name" (Error 1925)

Visual FoxPro 9.0
Unknown member "name" (Error 1925)

Visual FoxPro attempted to evaluate the following syntax:

Copy Code
        objvar.memberobj.property

No member named memberobj was found.

  • You were attempting to access the members of a control class from outside the class.

    Make sure references to controls, such as with .ActiveControl, are within scope.


LOG( ): Zero or negative used as argument (Error 58)

Visual FoxPro 9.0
LOG( ): Zero or negative used as argument (Error 58)

A zero or a negative number has been used as the argument of the natural log function.


Object class is invalid for this container (Error 1744)

Visual FoxPro 9.0
Object class is invalid for this container (Error 1744)

You have attempted to add a member object to a parent object with the AddObject method. It cannot be added because the member object's class cannot be a member of the parent's object class. For example, you cannot add a Grid object to a PageFrame object.


No primary key (Error 1879)

Visual FoxPro 9.0
No primary key (Error 1879)

You have attempted to use the DROP PRIMARY KEY clause of the ALTER TABLE command on a table with no primary key. This is not a valid operation.


The table file "name" has moved. Please validate database "name" and try again (Error 2004)

Visual FoxPro 9.0
The table file "name" has moved. Please validate database "name" and try again (Error 2004)

A cursor that is part of a data environment cannot find a table that is part of a database (.dbc file).


Unable to infer cursor's code page from XML document (Error 2185)

Visual FoxPro 9.0
Unable to infer cursor's code page from XML document (Error 2185)

This error is generated if a new XMLTOCURSOR( ) Function nFlag setting of 32768 is specified and the XMLTOCURSOR( ) function is unable to determine a code page for the new cursor.


Table number is invalid (Error 17)

Visual FoxPro 9.0
Table number is invalid (Error 17)

Select a table number between 1 and 225.


Code page number is invalid (Error 1914)

Visual FoxPro 9.0
Code page number is invalid (Error 1914)

The code page number you have specified (related to the country and language being used) is not valid for this version of Visual FoxPro. Verify that the code page number is correct. Localized versions can have support for additional code pages in the optional .INT file.


Field "name" validation rule is violated (Error 1582)

Visual FoxPro 9.0
Field "name" validation rule is violated (Error 1582)

Fix the field value or revert the record.


You must use a logical expression with FILTER (Error 37)

Visual FoxPro 9.0
You must use a logical expression with FILTER (Error 37)

You have attempted to issue SET FILTER TO on an expression that is not a logical expression. For more information, see Creating Logical Expressions.


Object file "name" is in use and cannot be removed from memory (Error 1719)

Visual FoxPro 9.0
Object file "name" is in use and cannot be removed from memory (Error 1719)

A program specified in the project is suspended.

Cancel execution of the program so that you can successfully build from the project.


No connection associated with this cursor (Error 1488)

Visual FoxPro 9.0
No connection associated with this cursor (Error 1488)

The connection was closed.

  • You closed the connection with SQLDISCONNECT( ). and then tried to update, requery, or refresh the view.

    Make sure you have an open connection before performing this command on a remote view.


Foxcode script "name" failure. (Error 2043)

Visual FoxPro 9.0
Foxcode script "name" failure. (Error 2043)

The script specified in the table file specified by the _FOXCODE system variable has failed. For more information, see _FOXCODE System Variable.

To determine the file specified by _FOXCODE, type the following line of code:

Copy Code
? _FOXCODE

To check the script syntax, open the table and find the corresponding script record.

For more information, see How to: Edit IntelliSense Records.


Project file is invalid (Error 1685)

Visual FoxPro 9.0
Project file is invalid (Error 1685)

The project file specified has become corrupted.


Fields marked as update keys will be cleared (Error 2014)

Visual FoxPro 9.0
Fields marked as update keys will be cleared (Error 2014)

Memo, General, and Picture fields cannot be key fields.

  • A key field was changed to Memo, General, or Picture.

    Visual FoxPro will clear the update key marker.


Error in the class definition. "Details" (Error 1735)

Visual FoxPro 9.0
Error in the class definition. "Details" (Error 1735)

An error occurred in the class definition for one of the following reasons:

  • The array does not exist.

  • Pages cannot be removed in the class definition.

  • Columns cannot be removed in the class definition.

  • Could not find the class name in the form.

  • CREATEOBJECT( ) was used in a class definition.

  • Grid columns were deleted in a class definition by setting the ColumnCount in the parent class to one value, and then setting the ColumnCount to a lower value in the child class.

  • Page frame-type pages were deleted in a class definition by setting the PageCount in the parent class to one value, and then setting the PageCount to a lower value in the child class.

  • The ADD OBJECT a[1] clause from the DEFINE CLASS command was used where a is not an array.


Ambiguous Date/DateTime constant (Error 2032)

Visual FoxPro 9.0
Ambiguous Date/DateTime constant (Error 2032)
See Also

A Date or DateTime value does not adhere to the strict format. For more information, see Date Data Type and DateTime Data Type.

See Also

Reference

SET STRICTDATE Command
StrictDateEntry Property


Application file "file" is not closed (Error 1178)

Visual FoxPro 9.0
Application file "file" is not closed (Error 1178)

Visual FoxPro was attempting to build an application while a file in the application was already open.

  • All files in the application must be closed before you can build it.

    Close the file and rebuild the application.


Foxtask table is corrupted or not the correct version. (Error 2046)

Visual FoxPro 9.0
Foxtask table is corrupted or not the correct version. (Error 2046)

The table specified as the value of the _FoxTask System Variable is invalid.


Statement is not allowed in interactive mode (Error 95)

Visual FoxPro 9.0
Statement is not allowed in interactive mode (Error 95)

The commands IF, ELSE, ENDIF, TEXT, ENDTEXT, EXIT, RETRY, RETURN, SUSPEND, DO WHILE, ENDDO, DO CASE, ENDCASE, SCAN, ENDSCAN, FOR, and ENDFOR are not allowed in the Command window; you must use these statements in a program.


Cannot find entry point "name" in the DLL (Error 1754)

Visual FoxPro 9.0
Cannot find entry point "name" in the DLL (Error 1754)
See Also

The dynamic-link library (DLL) entry point that you have declared is invalid. Check both the name of the entry point and the name of the DLL.

See Also

Other Resources

Accessing APIs


Error creating the OLE object (Error 1423)

Visual FoxPro 9.0
Error creating the OLE object (Error 1423)

There are not enough resources available, or Visual FoxPro can't find the server application.


COLUMN | ROW | ALIAS | NOOVERWRITE | SIZE | SCREEN are only allowed with the FROM clause (Error 1698)

Visual FoxPro 9.0
COLUMN | ROW | ALIAS | NOOVERWRITE | SIZE | SCREEN are only allowed with the FROM clause (Error 1698)

These options are available only when you create a quick screen with the FROM clause.


Menu file is invalid (Error 1687)

Visual FoxPro 9.0
Menu file is invalid (Error 1687)

The menu file you specified has become corrupted.


Property value is out of bounds (Error 1469)

Visual FoxPro 9.0
Property value is out of bounds (Error 1469)

The property value is outside the limits allowed for this property.

Change the value to be valid for this property.


Unable to open offline view in ADMIN/ONLINE mode inside a transaction. (Error 2121)

Visual FoxPro 9.0
Unable to open offline view in ADMIN/ONLINE mode inside a transaction. (Error 2121)

You cannot open an offline view in ADMIN or ONLINE mode from within a transaction.


Target table is already engaged in a relation (Error 1147)

Visual FoxPro 9.0
Target table is already engaged in a relation (Error 1147)

There is more than one relationship between the currently selected table file and one of its targets.


Invalid refresh ignore column name "column name" (Error 2171)

Visual FoxPro 9.0
Invalid refresh ignore column name "column name" (Error 2171)

The specified column name is invalid or cannot be found in the cursor.


Conversion to Unicode has failed. (Error 2135)

Visual FoxPro 9.0
Conversion to Unicode has failed. (Error 2135)

Occurs when a problem is encountered while Visual FoxPro attempts to convert a string to Unicode.

  • Examine your data, table, and field names to insure that they contain values that Visual FoxPro can convert property to Unicode.


Class definition "name" is recursive (Error 1950)

Visual FoxPro 9.0
Class definition "name" is recursive (Error 1950)

You have attempted to create an instance of one class that depends on another class that depends on the first class.


File is the wrong version (Error 1338)

Visual FoxPro 9.0
File is the wrong version (Error 1338)

You have attempted to open a screen or a report file that is not a Visual FoxPro file.


Interface "name" not found (Error 1443)

Visual FoxPro 9.0
Interface "name" not found (Error 1443)

The IMPLEMENTS clause in the DEFINE CLASS command specifies an interface for a COM object incorrectly. For more information, see DEFINE CLASS Command.


ADODB.Command is already opened. (Error 2081)

Visual FoxPro 9.0
ADODB.Command is already opened. (Error 2081)

Visual FoxPro requires that an ADO Command objects, State, is equal to adStateClosed, when attempting to pass an ADO Command object to the CursorFill methods Source parameter.


Error reading a property from the database. The property is ignored (Error 1584)

Visual FoxPro 9.0
Error reading a property from the database. The property is ignored (Error 1584)

An error occurred while loading rule or trigger code from the database container. The rule or trigger will be ignored.

Try running VALIDATE DATABASE before reopening this table.


Index tag or file name must be specified (Error 1684)

Visual FoxPro 9.0
Index tag or file name must be specified (Error 1684)

You have attempted to exit without specifying a tag name.


File was not placed in memory using the LOAD command (Error 91)

Visual FoxPro 9.0
File was not placed in memory using the LOAD command (Error 91)

An error occurred when attempting to CALL or RELEASE a module that was not loaded.


Column number must be between 0 and 255 (Error 223)

Visual FoxPro 9.0
Column number must be between 0 and 255 (Error 223)

The printer column number specified is out of range.


View fields have been changed. The Update and Key field properties have been reset to the default values (Error 1568)

Visual FoxPro 9.0
View fields have been changed. The Update and Key field properties have been reset to the default values (Error 1568)

You have attempted to modify a view whose table structure has changed. When you choose OK, the View Designer displays previous view conditions, but the Update Criteria tab resets to the default conditions. There has been no update.


Popup too big, first nExpr entries shown.

Visual FoxPro 9.0
Popup too big, first nExpr entries shown.

You specified too many items to be shown in the menu.


Program is too large (Error 1202)

Visual FoxPro 9.0
Program is too large (Error 1202)

The program that Visual FoxPro is attempting to load does not fit into memory. This message can also appear when the internal program cache runs out of space.

Note:
In versions prior to Visual FoxPro 9.0, the size of a program or single procedure that Visual FoxPro can load is limited to 65,000 bytes.

Visual FoxPro 9.0 allows you to configure the program cache size so you can prevent this error from occurring by specifying an adequate configuration file PROGCACHE setting (see Special Terms for Configuration Files). This setting is especially important for MTDLL scenarios.

For more information, see Visual FoxPro System Capacities.


Invalid seek offset (Error 1103)

Visual FoxPro 9.0
Invalid seek offset (Error 1103)

Record your recent actions while using Visual FoxPro and then call Microsoft Support.


Object is not an offline view (Error 2009)

Visual FoxPro 9.0
Object is not an offline view (Error 2009)

Some commands and clauses require an offline view.

  • You tried to use the ONLINE or ADMIN clauses.

    You must provide an offline view with these clauses. For more information, see USE Command.

  • You tried to drop a view.

    Use DROPOFFLINE( ) only with offline views.


Menu items and titles must be type Character (Error 1611)

Visual FoxPro 9.0
Menu items and titles must be type Character (Error 1611)

A menu item or menu title was encountered, which was defined with a data type other than Character.


Error initializing OLE (Error 1508)

Visual FoxPro 9.0
Error initializing OLE (Error 1508)

There is not enough memory or there has been an improper installation for this operation. Close any other running applications and try again.


Cannot find the wizard program.

Visual FoxPro 9.0
Cannot find the wizard program.

Visual FoxPro cannot find the program called WIZARD.APP because the program was either deleted, renamed, or moved out of the main Visual FoxPro directory. You can:

  • Run Visual FoxPro Setup to install WIZARD.APP.


XMLTable object does not have associated XMLAdapter object. (Error 2095)

Visual FoxPro 9.0
XMLTable object does not have associated XMLAdapter object. (Error 2095)

Visual FoxPro requires that XMLTable objects have a contained XMLAdapter object.

  • Check to make sure the XMLTable.XMLAdapter property is associated with an XMLAdapter object.


XML Schema is too complex. (Error 2094)

Visual FoxPro 9.0
XML Schema is too complex. (Error 2094)

The LoadXML method was unable to fully understand the supplied XML Schema

  • Check to make sure the supplied schema contains valid XSD data types or the schema and XML format is supported by Visual FoxPro.


Warning: The connection transaction mode cannot be set (Error 1487)

Visual FoxPro 9.0
Warning: The connection transaction mode cannot be set (Error 1487)

The connection transaction mode cannot be set by the ODBC driver. The connection will use the default driver defined transaction mode.


API library is not found (Error 1726)

Visual FoxPro 9.0
API library is not found (Error 1726)

You have attempted to issue SET LIBRARY TO or RELEASE LIBRARY, but the library you have specified cannot be found.


XMLTable object already has parent or is associated with XMLAdapter object. (Error 2132)

Visual FoxPro 9.0
XMLTable object already has parent or is associated with XMLAdapter object. (Error 2132)

The XMLTable object cannot be added as a child table reference to another XMLAdapter object, if it is already a child table or is associated with another XMLAdapter object.


Type conversion required by the DataType property for field "name" is invalid (Error 1543)

Visual FoxPro 9.0
Type conversion required by the DataType property for field "name" is invalid (Error 1543)

The type conversion between the remote data type and the Visual FoxPro data type, specified by the view field DataType property, is not supported for the field of the view that is being activated.

Change the view field DataType property to a valid type.


SQL: GROUP BY clause is invalid (Error 1807)

Visual FoxPro 9.0
SQL: GROUP BY clause is invalid (Error 1807)

There is an error in the GROUP BY clause. For more information, see SELECT - SQL Command or SET ENGINEBEHAVIOR Command.


XMLTable has child table. (Error 2109)

Visual FoxPro 9.0
XMLTable has child table. (Error 2109)

Visual FoxPro does not allow the use of the ChangesToCursor method on an XMLTable object that contains a child XMLTable object reference. You cannot create a cursor using the ChangesToCursor method when the XMLTable represents the results of a join on more or more tables.


Cannot add an object to this class (Error 1755)

Visual FoxPro 9.0
Cannot add an object to this class (Error 1755)

If a class is based on the Control base class, you can only add an object to it if its immediate parent is the CONTROLS class.


Memory file is invalid (Error 55)

Visual FoxPro 9.0
Memory file is invalid (Error 55)

An attempt was made to use RESTORE FROM on a file that is not a valid memory (.mem) file.


Cannot find the builder program (Error 1944)

Visual FoxPro 9.0
Cannot find the builder program (Error 1944)

The builder application cannot be found.

  • The _BUILDER system variable does not contain a valid file name.

    Verify the value of _BUILDER.


File was created in a later version of Visual FoxPro than the current version (Error 1750)

Visual FoxPro 9.0
File was created in a later version of Visual FoxPro than the current version (Error 1750)

There is a discrepancy in the comparison of the version number built into the form (.scx) or database container (.dbc) file and the version number stored in the product for these files.


Browse table is closed (Error 1163)

Visual FoxPro 9.0
Browse table is closed (Error 1163)

A Browse window was closed by a Browse validation routine.


Cannot redefine popup that is in use (Error 175)

Visual FoxPro 9.0
Cannot redefine popup that is in use (Error 175)

You have attempted to issue a DEFINE POPUP command while the menu is active in memory.

Issue a DEACTIVATE POPUP command first.


XMLTable.Alias is empty. (Error 2108)

Visual FoxPro 9.0
XMLTable.Alias is empty. (Error 2108)

The ToCursor Method and the ChangesToCursor Method cannot be called when the XMLTable's Alias Property is empty and the cAlias parameter was not used.


OLE exception error "name". OLE object may be corrupt. (Error 1440)

Visual FoxPro 9.0
OLE exception error "name". OLE object may be corrupt. (Error 1440)

A COM object or COM control caused a general protection fault, possibly because it was passed bad parameters. Release or reload the COM object or COM control.


Total label width exceeds allowed size (Error 1246)

Visual FoxPro 9.0
Total label width exceeds allowed size (Error 1246)

The LABEL command detected a condition where the sum of the individual label widths plus separating spaces is greater than the maximum width allowed.


Incorrect column format (Error 1471)

Visual FoxPro 9.0
Incorrect column format (Error 1471)

You have attempted to pass an incorrect column type descriptor to SQLCOLUMNS( ).


Statement only valid within a method (Error 1934)

Visual FoxPro 9.0
Statement only valid within a method (Error 1934)

You have attempted to use the :: (scope resolution) operator outside of a method. Since the scope operator is driven from the THIS object reference, it can only be used within a method.


"name" is not a Visual FoxPro event (Error 1745)

Visual FoxPro 9.0
"name" is not a Visual FoxPro event (Error 1745)

An event specified in the SET EVENTLIST command isn't a Visual FoxPro event.


Property "property name" value is too long (Error 2197)

Visual FoxPro 9.0
Property "property name" value is too long (Error 2197)

This error is generated when the XML character string specified in the _MemberData Property is too long. The XML character string size limit is 8K.


Could not add icon to executable file (Error 1168)

Visual FoxPro 9.0
Could not add icon to executable file (Error 1168)

You have specified an invalid icon file (.ICO) while creating your distributable, executable files.


Missing comma (,) (Error 1306)

Visual FoxPro 9.0
Missing comma (,) (Error 1306)

Visual FoxPro was expecting a comma and didn't find one.

  • You might not have included the proper number of arguments with a function.

    Check your syntax.


Memory is low, so streaming output updating has been disabled (Error 2000)

Visual FoxPro 9.0
Memory is low, so streaming output updating has been disabled (Error 2000)

The off-screen bitmap could not be created by a command such as ? Command, LIST , or DISPLAY.

  • Visual FoxPro memory is low.

    Free up some memory.


Invalid or missing EXE file.

Visual FoxPro 9.0
Invalid or missing EXE file.

The .EXE file you specified is either corrupted or missing.


Cannot add this table: it belongs to database "name" (Error 1537)

Visual FoxPro 9.0
Cannot add this table: it belongs to database "name" (Error 1537)

The operation you have attempted is supported only for free tables. Try again with a file of the correct type: a .dbf file that does not belong to a database.


This file is incompatible with the current version of Visual FoxPro (Error 1748)

Visual FoxPro 9.0
This file is incompatible with the current version of Visual FoxPro (Error 1748)

A file created in a pre-release version of Visual FoxPro 3.0 isn't compatible with the current version of Visual FoxPro. Run 30Update.prg, included with the pre-release version of Visual FoxPro 3.0 to convert the file to a current format.


The index expression for index "name" contains an invalid reference to a Memo, General, or Picture field (Error 1998)

Visual FoxPro 9.0
The index expression for index "name" contains an invalid reference to a Memo, General, or Picture field (Error 1998)

You cannot index on Memo, General, or Picture field types.


Invalid key length (Error 112)

Visual FoxPro 9.0
Invalid key length (Error 112)
  • If you created an index key that exceeds the following limits, create a shorter index key.

    The length of an index key for an index or compiled index (.idx) must be between 1 and 100 characters. The length for a compound index (.cdx) must between 1 and 240 characters.

    For certain collating sequences, or when using double-byte character sets (DBCS) characters, each character in the eExpression parameter in the INDEX command uses two characters in the index key. In these cases, the length of eExpression is limited to 120 characters.

  • If you created an index key with length of 0, make sure the first record of the fields you base the index on contains some data.

    When Visual FoxPro creates an index, it evaluates fields in the first record in the table.


"name" is not a variable (Error 225)

Visual FoxPro 9.0
"name" is not a variable (Error 225)

A file variable (table field) was used where a variable or array is required. For more information, see Variables, Arrays, or Working with Arrays..


Field "name" is read-only. (Error 2088)

Visual FoxPro 9.0
Field "name" is read-only. (Error 2088)

Occurs when attempting to insert, update, or replace a value in a field that uses autoincrementing, and the AutoIncError property is set to True (.T.) or ON via the SET AUTOINCERROR command.

Try setting the AutoIncError property to False (.F.) or OFF using the SET AUTOINCERROR command.


Error adding "name" to the object. Duplicate member/property name (Error 1779)

Visual FoxPro 9.0
Error adding "name" to the object. Duplicate member/property name (Error 1779)

The member or property name you are trying to add to the object already exists.


SQL: The ORDER BY clause is invalid in subqueries, unless TOP is also specified (Error 2148)

Visual FoxPro 9.0
SQL: The ORDER BY clause is invalid in subqueries, unless TOP is also specified (Error 2148)

The SELECT - SQL Command cannot contain an SELECT - SQL Command - ORDER BY Clause in a Subquery unless a TOP expression is also included.


Microsoft Visual FoxPro doesn't support and cannot open this format of recordset (Error 2038)

Visual FoxPro 9.0
Microsoft Visual FoxPro doesn't support and cannot open this format of recordset (Error 2038)

Visual FoxPro attempted to open an ADO Shaped (Hierarchical) recordset which is not directly supported by the product. You can use an ADO Shaped recordset in your application as long as it is handled by an Activex control which support these types of recordsets, such as the Microsoft Hierarchical FlexGrid Control.


SQL: Too many UNIONs (Error 1834)

Visual FoxPro 9.0
SQL: Too many UNIONs (Error 1834)

In Visual FoxPro 8.0, the maximum number of UNIONs (9) has been exceeded. In Visual FoxPro 9.0, the maximum number of UNIONs is limited by memory and disk space. For more information, see SELECT - SQL Command.


SQL: ORDER BY clause is invalid (Error 1808)

Visual FoxPro 9.0
SQL: ORDER BY clause is invalid (Error 1808)

One of the fields chosen for the ORDER BY clause is not in the SELECT list. This occurs only when using numeric indexing as in the following example where the number chosen exceeds the number of fields selected:

Copy Code
SELECT a,b,c FROM table ORDER BY 4

This error will also be generated if you include a Blob type field in the ORDER BY clause.

For more information, see SELECT - SQL Command.


Cannot refresh record from ADODB.Recordset because it does not support a Bookmark property (Error 2169)

Visual FoxPro 9.0
Cannot refresh record from ADODB.Recordset because it does not support a Bookmark property (Error 2169)

Occurs when the supplied ADO Recordset does not support bookmarks. This is data source dependant. Make sure the ADO Recordset is configured to support bookmarks.


No PARAMETER statement is found (Error 1238)

Visual FoxPro 9.0
No PARAMETER statement is found (Error 1238)

After doing a program with a parameter list, the called program must begin with a PARAMETER statement.


Class file name for "name" is not valid (Error 1746)

Visual FoxPro 9.0
Class file name for "name" is not valid (Error 1746)

A class stored in a visual class library (.vcx) file, based on a class that is also stored in a .vcx file, has been given a name that exceeds the maximum allowable file name length.


XML Parse Error (Error 1435)

Visual FoxPro 9.0
XML Parse Error (Error 1435)

This error is caused by an MSXML parser error reading an XML source when passed to the XMLTOCURSOR() function, which is usually due to improperly formatted XML. To see the specific parser error, view the XML file in a browser.


Menu has not been activated with ACTIVATE POPUP (Error 179)

Visual FoxPro 9.0
Menu has not been activated with ACTIVATE POPUP (Error 179)

You have attempted to select a menu title from a menu before the menu has been activated. For more information, see ACTIVATE POPUP Command.


User-interface operation not allowed at this time. (Error 2031)

Visual FoxPro 9.0
User-interface operation not allowed at this time. (Error 2031)

This error is generated when unattended server mode is enabled with SYS(2335). If possible, remove the code from your server that creates the modal state that generates this error.


Unable to change XMLName property while XMLField object belongs to XMLTable object. (Error 2103)

Visual FoxPro 9.0
Unable to change XMLName property while XMLField object belongs to XMLTable object. (Error 2103)

Visual FoxPro does not allow the XMLName property for an XMLField object, to be changed, when the XMLField object belongs to an XMLTable object.


Index file does not match table (Error 19)

Visual FoxPro 9.0
Index file does not match table (Error 19)

The index expression for the current index uses variables that are not contained within the current table.


Internal error: Too many characters in the report (Error 1243)

Visual FoxPro 9.0
Internal error: Too many characters in the report (Error 1243)

The total size of all the headings and expressions defined for the report in CREATE REPORT or MODIFY REPORT is too large to be contained in the standard report file.


Cannot rename the current directory (Error 1253)

Visual FoxPro 9.0
Cannot rename the current directory (Error 1253)

The directory you have flagged in the Filer could not be renamed.


Macro is not defined (Error 355)

Visual FoxPro 9.0
Macro is not defined (Error 355)

An attempt has been made to play a macro that does not exist.


Field size for Unicode value can not be odd number. (Error 2141)

Visual FoxPro 9.0
Field size for Unicode value can not be odd number. (Error 2141)

Occurs when attempting to convert Unicode data to or from XML, and the field size does not evaluate to an even number.

  • Make sure that Unicode strings are being used.

  • Check to make sure that field sizes are always even numbered.


Uniqueness of index "name" is violated (Error 1884)

Visual FoxPro 9.0
Uniqueness of index "name" is violated (Error 1884)

The uniqueness of primary or candidate key is violated.

Fix the record values or revert them.


Maximum menu items allowed (128) is exceeded (Error 1607)

Visual FoxPro 9.0
Maximum menu items allowed (128) is exceeded (Error 1607)

The maximum number of items that may be contained in a menu (128) was exceeded.


No Help Available

Visual FoxPro 9.0
No Help Available
See Also

Most user interface elements and error messages have an associated help topic. You have selected an element or generated an error, however, for which no Help exists.

  • Check Microsoft Product Support Services for help for late-breaking errors: Microsoft Product Support Knowledge Base Link.

    Help on these elements and late-breaking errors can be found in Knowledge Base articles.

See Also

Other Resources

Product Support
Getting Help from Microsoft Product Support Services


Cannot nest key labels (Error 1254)

Visual FoxPro 9.0
Cannot nest key labels (Error 1254)

You cannot nest key labels.


Maximum record length exceeded in the import file (Error 392)

Visual FoxPro 9.0
Maximum record length exceeded in the import file (Error 392)

The file you have attempted to import has a record length greater than 4,001 bytes.


The cursor is already associated with a record set (Error 2195)

Visual FoxPro 9.0
The cursor is already associated with a record set (Error 2195)

This error can be generated by VfpOleDB.dll, the OLE DB Provider for Visual FoxPro, when SETRESULTSET( ) Function returns a cursor already associated with a record set.


Not a numeric expression (Error 27)

Visual FoxPro 9.0
Not a numeric expression (Error 27)

You have attempted to use the SUM command on a non-numeric field.


Property is not found (Error 1559)

Visual FoxPro 9.0
Property is not found (Error 1559)

The property name you specified cannot be found or is not valid for the specified object.

Check the name of the property and try again. Make sure the object and property are compatible.


"name" is not a function, procedure or program (Error 1992)

Visual FoxPro 9.0
"name" is not a function, procedure or program (Error 1992)

An Access method must return an object reference.


Mismatched #IF/#ELSIF/#ELSE/#ENDIF (Error 1723)

Visual FoxPro 9.0
Mismatched #IF/#ELSIF/#ELSE/#ENDIF (Error 1723)

You have included an incomplete or incorrect #IF preprocessor command.


CursorAdapter is unable to determine DataSourceType for the operation. (Error 2138)

Visual FoxPro 9.0
CursorAdapter is unable to determine DataSourceType for the operation. (Error 2138)

The DataSourceType property must be specified.

  • Make sure the DataSourceType property has been specified for the CursorAdapter object.

  • Make sure the UseDeDataSource property is set to True (.T.).

  • Check to make sure the DataSourceType property for the associated DataEnvironment object is correctly set.


There is a duplicate table "name" in XML schema. (Error 2104)

Visual FoxPro 9.0
There is a duplicate table "name" in XML schema. (Error 2104)

Visual FoxPro does not allow schemas to define more than one table with the same name.

  • Make sure the XML source returns the XML in a correct and expected format.

  • Correct the supplied schema and XML document.


Type conversion is not supported for output parameters (Error 1501)

Visual FoxPro 9.0
Type conversion is not supported for output parameters (Error 1501)

SQL parameter conversion error. Internal connectivity error.

Record your recent actions while using Visual FoxPro and then call Microsoft Support.


Illegal redefinition of variable "name" (Error 1960)

Visual FoxPro 9.0
Illegal redefinition of variable "name" (Error 1960)

The PUBLIC or LOCAL command tried to change the state of a variable that already exists. For example, if you have a variable x that is not public and then issue PUBLIC x, you get this error.

Variables created in the Command window are public by definition. To create a variable that is not public, use a program (.PRG) file.


Unable to cast NULL value to a NOT NULL data type (Error 2159)

Visual FoxPro 9.0
Unable to cast NULL value to a NOT NULL data type (Error 2159)

You cannot cast a NULL value to a data type that does not accept NULL values.


Member object "name" has not been instantiated (Error 1975)

Visual FoxPro 9.0
Member object "name" has not been instantiated (Error 1975)

A reference was made to a member object in an Init event before that object was instantiated.


SQRT( ) argument cannot be negative (Error 61)

Visual FoxPro 9.0
SQRT( ) argument cannot be negative (Error 61)

SQRT( ) function arguments must not be negative.


Database object type is invalid (Error 1773)

Visual FoxPro 9.0
Database object type is invalid (Error 1773)

Valid types are: CONNECTION, VIEW, TABLE, RELATION, FIELD, INDEX. Some commands are appropriate only for a subset of these types.


Function name is missing (Error (Error 1304)

Visual FoxPro 9.0
Function name is missing (Error (Error 1304)

A function name is missing a left parenthesis.


Value of XMLField.XMLName must be used as key value for collection. (Error 2100)

Visual FoxPro 9.0
Value of XMLField.XMLName must be used as key value for collection. (Error 2100)

The XMLName property for an XMLField must be used as the key, when adding the XMLField to a Fields collection.

  • Make sure that any XMLField objects, that are going to be added to a collection have the XMLName property set to a valid value, and that this value is used as the key.


Cannot find the converter program (Error 1798)

Visual FoxPro 9.0
Cannot find the converter program (Error 1798)

The converter application cannot be found.

  • The _CONVERTER system variable does not contain a valid file name.

    Verify the value of _CONVERTER.


Cursor cannot be modified because it contains an unsaved record (Error 2072)

Visual FoxPro 9.0
Cursor cannot be modified because it contains an unsaved record (Error 2072)

This error typically occurs when a record in a cursor is modified in a grid or Browse window and is not saved before moving to another record.

Any code that modifies the cursor should ensure that all modifications are saved before moving the record pointer.


Function not supported for SQL pass-through cursors (Error 1504)

Visual FoxPro 9.0
Function not supported for SQL pass-through cursors (Error 1504)

This command applies to view cursors only.

  • SQL pass-through cursors do not necessarily return single result sets.

    Do not use REQUERY( ) on a SQL pass-through cursor.


Cannot determine data type of the expression (Error 2201)

Visual FoxPro 9.0
Cannot determine data type of the expression (Error 2201)

This error occurs when an attempt is made to create an index based on a null expression.


Table buffering is not enabled (Error 1596)

Visual FoxPro 9.0
Table buffering is not enabled (Error 1596)

You have attempted to use the GETNEXTMODIFIED( ) function, which requires table buffering to be enabled.

Enable table buffering or use a different function.


Key field length does not match (Error 1117)

Visual FoxPro 9.0
Key field length does not match (Error 1117)

The key field length does not match for an UPDATE or SET RELATION TO operation between two files.


Only insertable objects are allowed in General fields (Error 1436)

Visual FoxPro 9.0
Only insertable objects are allowed in General fields (Error 1436)

Insertable objects are objects such as a Microsoft Excel worksheet or Microsoft Word document. These are allowed in General fields. Non-insertable objects are objects such as ActiveX controls. ActiveX controls are not allowed in General fields.


Unable to locate desired version of Visual FoxPro.

Visual FoxPro 9.0
Unable to locate desired version of Visual FoxPro.

The version of Visual FoxPro requested is not on the designated path.


Cannot activate the OLE server (Error 1421)

Visual FoxPro 9.0
Cannot activate the OLE server (Error 1421)

The object cannot be activated.

  • The object is static.

    Link the object to a file.

  • The OLE server (also called Automation server) cannot be accessed.

    Make sure the server application is installed and accessible. Also, make sure there is enough memory to launch the application.


Drive specifier is invalid (Error 1907)

Visual FoxPro 9.0
Drive specifier is invalid (Error 1907)

You specified an invalid drive name in a DIR command.


Cannot insert an empty row from a view into its base table(s) (Error 1547)

Visual FoxPro 9.0
Cannot insert an empty row from a view into its base table(s) (Error 1547)

While a view is updating, a new empty record (with no modified fields) is being inserted into one of the base tables of the view.

Make sure each record inserted from a view into a base table has at least one field that has been modified in the view prior to the view update.


Cannot write to the record because it is in use (Error 1502)

Visual FoxPro 9.0
Cannot write to the record because it is in use (Error 1502)

Visual FoxPro could not write to the selected record because it is in use.


MULTISELECT or MOVER clause is not supported for PROMPT style menus (Error 1710)

Visual FoxPro 9.0
MULTISELECT or MOVER clause is not supported for PROMPT style menus (Error 1710)

Commands that have the clauses PROMPT FIELD, PROMPT FILE, or PROMPT STRUCTURE do not allow the clauses MULTISELECT or MOVER.


Connection handle is invalid (Error 1466)

Visual FoxPro 9.0
Connection handle is invalid (Error 1466)

The connection handle supplied is invalid.

Use SQLCONNECT( ) or SQLSTRINGCONNECT( ) to generate a valid connection handle.


XMLTable XMLName property is an XPath expression (Error 2181)

Visual FoxPro 9.0
XMLTable XMLName property is an XPath expression (Error 2181)
  • The XMLAdapter Class ToXML Method generates this error if the XMLTable Class XMLNameIsXPath Property is set to true (.T.).

  • The XMLTable Class ApplyDiffgram Method and the ChangesToCursor Method generate this error if the XMLNameIsXPath Property is set to true (.T.).


SQL: Queries of this type are not supported (Error 1814)

Visual FoxPro 9.0
SQL: Queries of this type are not supported (Error 1814)

You have attempted to run a query that is not supported by FoxPro versions 2.5 through the current version. For more information, see SELECT - SQL Command.


Record is out of range (Error 5)

Visual FoxPro 9.0
Record is out of range (Error 5)

The record number you attempted to access is beyond the actual number of records contained in the current table.

  • The current index does not match the table

    Issue REINDEX on the table to try and correct the problem.


Cannot load 32-bit DLL "name" (Error 1753)

Visual FoxPro 9.0
Cannot load 32-bit DLL "name" (Error 1753)

The dynamic link library (DLL) file is missing or invalid.


The Dockable property cannot be enabled possibly due to conflicting properties (Error 2152)

Visual FoxPro 9.0
The Dockable property cannot be enabled possibly due to conflicting properties (Error 2152)

This error message can be generated if a form's Dockable Property is set to true (.T.) and the form is part of a formset. Also, properties which can potentially conflict with docking behavior (ScrollBars Property, Desktop Property, ShowWindow Property) can generate this error.


Object file "file" was compiled in a previous version of FoxPro (Error 1195)

Visual FoxPro 9.0
Object file "file" was compiled in a previous version of FoxPro (Error 1195)

You have attempted to run an application compiled in a previous version of FoxPro.

Recompile the source code in the current version.


Error with "name" - "property": "error" (Error 2005)

Visual FoxPro 9.0
Error with "name" - "property": "error" (Error 2005)

You have attempted to set a property to an illegal value through the language.


No previous PRINTJOB command to correspond to this command (Error 1649)

Visual FoxPro 9.0
No previous PRINTJOB command to correspond to this command (Error 1649)

An ENDPRINTJOB command was encountered without a matching PRINTJOB command preceding it.


Index file "file" is corrupted. Please rebuild it (Error 2066)

Visual FoxPro 9.0
Index file "file" is corrupted. Please rebuild it (Error 2066)

The index file you are attempting to use is corrupted. Use the INDEX Command to rebuild it.


Data type is invalid for this property (Error 1732)

Visual FoxPro 9.0
Data type is invalid for this property (Error 1732)

Data type mismatch.

  • The value specified for the property is not the correct data type.

    For more information, see Data and Field Types.


SQL: Aggregate on non-numeric expression (Error 1811)

Visual FoxPro 9.0
SQL: Aggregate on non-numeric expression (Error 1811)

There was an attempt to perform an average, sum, standard deviation or variance on a non-numeric field.


Menu has not been defined with DEFINE POPUP (Error 165)

Visual FoxPro 9.0
Menu has not been defined with DEFINE POPUP (Error 165)

You have attempted to activate a menu before it has been defined. For more information, see DEFINE POPUP Command.


This operation not supported for class member objects (Error 1521)

Visual FoxPro 9.0
This operation not supported for class member objects (Error 1521)

You have attempted to clone or copy an object that is a member of a class.


Record is not in index (Error 20)

Visual FoxPro 9.0
Record is not in index (Error 20)

A key field of the table in use has been modified without the index having been active.

Apply the REINDEX command to the table file.


Nested XML format is incompatible with "Changes Only" mode (Error 2179)

Visual FoxPro 9.0
Nested XML format is incompatible with "Changes Only" mode (Error 2179)

This error is generated by the XMLAdapter Class ToXML Method if both the RespectNesting Property and the lChangesOnly parameter are set to true (.T.).


CursorAdapter internal error (Error 2175)

Visual FoxPro 9.0
CursorAdapter internal error (Error 2175)

An unknown error has occurred.


OrderBy clause is too long. (Error 2052)

Visual FoxPro 9.0
OrderBy clause is too long. (Error 2052)

The OrderBy clause exceeds 256 characters. Try reducing the number of characters.


SQL: Invalid aggregate field (Error 1822)

Visual FoxPro 9.0
SQL: Invalid aggregate field (Error 1822)

You have attempted to perform aggregation on a Memo field.


Field "field name" is not fetched (Error 2172)

Visual FoxPro 9.0
Field "field name" is not fetched (Error 2172)

This error may be generated when delayed memo fetch is not supported, when you attempt to send an update where the memo field is a key, and when the field cannot be fetched.


Date/DateTime contains illegal characters (Error 2035)

Visual FoxPro 9.0
Date/DateTime contains illegal characters (Error 2035)

The Date or DateTime constant contains characters that are not supported in Date and DateTime constants.


Cannot assign a class value to this member (Error 2070)

Visual FoxPro 9.0
Cannot assign a class value to this member (Error 2070)

An attempt was made to assign the Class property a value that was not an object reference.


SQL: FROM clause is required (Error 1818)

Visual FoxPro 9.0
SQL: FROM clause is required (Error 1818)

There must be a FROM clause in the SELECT command. For more information, see SELECT - SQL Command.


Connection "connection name" is in manual commit mode (Error 2176)

Visual FoxPro 9.0
Connection "connection name" is in manual commit mode (Error 2176)

This error is generated when the SQLIDLEDISCONNECT( ) Function is used to temporarily disconnect a SQL pass through connection and the connection is in manual commit mode. The AERROR( ) Function can be used to obtain additional error information.


Data type mismatch (Error 9)

Visual FoxPro 9.0
Data type mismatch (Error 9)

An expression is invalid because it is composed of data types that Visual FoxPro cannot evaluate together.

  • You have either specified an inappropriate data type, or the two fields specified in an operation between two tables (such as UPDATE, REPLACE, SET RELATION) did not have the same data type.


Member object removed – cannot complete Save operation (Error 1756)

Visual FoxPro 9.0
Member object removed – cannot complete Save operation (Error 1756)

The class could not be saved.

  • The .vcx file or memory is corrupted.


The database must be opened exclusively (Error 1557)

Visual FoxPro 9.0
The database must be opened exclusively (Error 1557)

Commands such as VALIDATE DATABASE RECOVER, PACK DATABASE, and those involving creation or modification of database objects require exclusive access to the database.

Close the database and reopen it using OPEN DATABASE FileName EXCLUSIVE.


SQL parameter is missing (Error 1493)

Visual FoxPro 9.0
SQL parameter is missing (Error 1493)

The parameter marker (?) in a SQL statement used in SQLEXEC( ) or in a view definition is not followed by the parameter expression.

Add the parameter expression after the parameter marker.


API library revision mismatch. Rebuild library (Error 1711)

Visual FoxPro 9.0
API library revision mismatch. Rebuild library (Error 1711)

The API library you are using does not match your version of Visual FoxPro.

  • You are using an older version of an .FLL file.

    Rebuild the .FLL file, or obtain an updated version.

  • The ActiveX control calling the Visual FoxPro API is out of date.

    Rebuild the ActiveX control or obtain an updated version.

For more information, see Accessing the Visual FoxPro API,.


Multiple warnings occurred performing the requested index modifications (Error 1875)

Visual FoxPro 9.0
Multiple warnings occurred performing the requested index modifications (Error 1875)

All structural and property changes to the table were completed successfully.

  • Since you registered an ON ERROR handler, warnings were processed there.

    Add code to verify the changes and handle the warnings you received.


Expression used with ASIN( ) is out of range (Error 291)

Visual FoxPro 9.0
Expression used with ASIN( ) is out of range (Error 291)

The expression you have used with the arc sine function has a value out of the range of – 1.0 to +1.0.


"cursor" must be created with SELECT ... INTO TABLE (Error 1815)

Visual FoxPro 9.0
"cursor" must be created with SELECT ... INTO TABLE (Error 1815)

You have tried to use a repackaged cursor as a source for another SELECT statement.

  • Some cursors cannot be used in successive queries.

    Use the INTO TABLE clause of the SELECT - SQL statement instead.


Record is not locked (Error 130)

Visual FoxPro 9.0
Record is not locked (Error 130)

An attempt was made to use a BROWSE, CHANGE, EDIT, DELETE, GATHER, MODIFY MEMO, READ, RECALL, or REPLACE command on a record that was not locked.


Error closing the file (Error 1112)

Visual FoxPro 9.0
Error closing the file (Error 1112)

An error was returned by the operating system while Visual FoxPro was attempting to close a file.


Execution was canceled by the user (Error 1523)

Visual FoxPro 9.0
Execution was canceled by the user (Error 1523)

You canceled a remote command by pressing the ESC key.


Field name is a duplicate or invalid (Error 1712)

Visual FoxPro 9.0
Field name is a duplicate or invalid (Error 1712)

This error can occur under the following conditions:

  • A field in the table already has that name.

  • The field name contains a space or one of the following characters: ., ", /, \, [, ], :, |, <, >, +, =, ;, *, or ?

  • The field name exceeds 10 characters.


Field mismatch (Error 2040)

Visual FoxPro 9.0
Field mismatch (Error 2040)

An attempt was made to copy to an ADO recordset, but failed because there was a mismatch between fields in the cursor and those in the ADO recordset.


User Thrown Error (Error 2071)

Visual FoxPro 9.0
User Thrown Error (Error 2071)

Occurs when you use the THROW command to throw an exception.


Expression used with ACOS( ) is out of range (Error 293)

Visual FoxPro 9.0
Expression used with ACOS( ) is out of range (Error 293)

The expression you have used with the arc cosine function has a value out of the range of – 1.0 to +1.0.


Nesting error (Error 96)

Visual FoxPro 9.0
Nesting error (Error 96)

One of these situations has been encountered:

  • A DO is present without a matching ENDDO or vice versa

  • A SCAN is present without a matching ENDSCAN or vice versa

  • A FOR is present without a matching ENDFOR or vice versa

  • A LOOP or EXIT clause is present outside the DO WHILE ... ENDDO, FOR ... ENDFOR, or SCAN ... ENDSCAN commands.


Forms or Form classes that specify a DEClass and DEClassLibrary cannot be converted to or used with a FormSet. (Error 2069)

Visual FoxPro 9.0
Forms or Form classes that specify a DEClass and DEClassLibrary cannot be converted to or used with a FormSet. (Error 2069)

Visual FoxPro does not support the DataEnvironment DEClass and DEClassLibrary properties for form sets. An error occurs under the following conditions at design time:

  • When attempting to convert a form to a form set after the DEClass and DEClassLibrary properties have been specified for the form.

  • When attempting to add a Form class that specifies the DEClass and DEClassLibrary properties to a FormSet class when the form set is open in the Form Designer.


Directory is not found (Error 1963)

Visual FoxPro 9.0
Directory is not found (Error 1963)

The directory you have specified does not exist.


XMLTable object does not have associated fields. (Error 2097)

Visual FoxPro 9.0
XMLTable object does not have associated fields. (Error 2097)

An XMLTable object must have associated XMLField objects to execute the ToCursor and ChangesToCursor methods.


.SYLK file dimension bounds are invalid (Error 120)

Visual FoxPro 9.0
.SYLK file dimension bounds are invalid (Error 120)

The file you have attempted to import is indicating invalid rows or columns.


Property "name" is not found (Error 1734)

Visual FoxPro 9.0
Property "name" is not found (Error 1734)

The property name you specified cannot be found.

Check the name of the property and try again.


SQL: Subquery is invalid (Error 1825)

Visual FoxPro 9.0
SQL: Subquery is invalid (Error 1825)

Something in the subquery is erroneous. For more information, see SELECT - SQL Command.


Code page for the field "field name" doesn't match cursor's code page (Error 2184)

Visual FoxPro 9.0
Code page for the field "field name" doesn't match cursor's code page (Error 2184)

The XMLAdapter Class ToXML Method generates this error if the RespectCursorCP Property is set to true (.T.), the UTF8Encoded Property is set to false (.F.), the UseCodePage Property is set to true (.T.), the XMLField Class CodePage Property is greater than zero and does not match cursor's code page.


Class "name" is not found (Error 1762)

Visual FoxPro 9.0
Class "name" is not found (Error 1762)

The REMOVE CLASS command specified a class name that does not exist in the class library.


Property "name" already exists (Error 1763)

Visual FoxPro 9.0
Property "name" already exists (Error 1763)

The object already has a property with this name.

Give the new property a unique name.


This object is derived from a base class and does not have a parent class. (Error 1784)

Visual FoxPro 9.0
This object is derived from a base class and does not have a parent class. (Error 1784)

The default class cannot be found. For more information, see DODEFAULT( ) Function.


Invalid class specified for @...Class command (Error 1783)

Visual FoxPro 9.0
Invalid class specified for @...Class command (Error 1783)

You cannot specify a form, form set, or toolbar class when using @ ... Class.


Field expression contains an invalid data type (Error 1647)

Visual FoxPro 9.0
Field expression contains an invalid data type (Error 1647)

A picture data type was encountered by REPORT for a field expression.


Query Parse Error - try rebuilding in Query Wizard or by using View Designer Join Tab (Error 2055)

Visual FoxPro 9.0
Query Parse Error - try rebuilding in Query Wizard or by using View Designer Join Tab (Error 2055)

This error may occur in certain circumstances when the View Designer or Query Designer is unable to parse the query.

  • Attempt to rebuild the query using the Query Wizard.

  • Make changes to the query in the View Designer Join Tab by removing, changing, or re-adding tables and relations to the query.


SQL: SELECT is invalid (Error 1826)

Visual FoxPro 9.0
SQL: SELECT is invalid (Error 1826)

You have attempted to select more than one field in a subquery. For more information, see SELECT - SQL Command.


Expression is not valid outside of WITH/ENDWITH (Error 1940)

Visual FoxPro 9.0
Expression is not valid outside of WITH/ENDWITH (Error 1940)

You can use an expression of the form .property=some_value only within a WITH ... ENDWITH construct.

  • This error might also occur if you are using .NULL. as an expression.

    Put quotes around the .NULL. to keep it from being identified as a property.

  • You might have forgotten an ending period with a value such as true (.T.), false (.F.) or a null value (.NULL.)

    Check for matching periods on either side of the constant.


There is a missing keyword in the FOR ... ENDFOR or DO CASE ... ENDCASE command structure (Error 1213)

Visual FoxPro 9.0
There is a missing keyword in the FOR ... ENDFOR or DO CASE ... ENDCASE command structure (Error 1213)

For more information, see the FOR ... ENDFOR and DO CASE ... ENDCASE topics.


Connection name is invalid (Error 1497)

Visual FoxPro 9.0
Connection name is invalid (Error 1497)

The name you have specified is not the name of a view in the current database.

Check that the name entered is correct and that the current database is the required database.


Input/output operation failure (Error 1002)

Visual FoxPro 9.0
Input/output operation failure (Error 1002)

The operating system is unable to perform a file or hardware operation.


The specified member class does not exist or is of wrong type. (Error 2056)

Visual FoxPro 9.0
The specified member class does not exist or is of wrong type. (Error 2056)

Make sure the member class you specify exists and is of the correct type.


Cannot clear a popup that is in use (Error 177)

Visual FoxPro 9.0
Cannot clear a popup that is in use (Error 177)

You have attempted to clear an active menu.

  • The CLEAR POPUP and RELEASE POPUP commands cannot be applied to active menus.

    Use DEACTIVATE POPUP before clearing or releasing the menu.


The SQL Statement is too complex for the View/Query Designer (Error 2025)

Visual FoxPro 9.0 Language Reference
The SQL Statement is too complex for the View/Query Designer (Error 2025)

The view/query could not be opened in the View/Query Designer because the SELECT - SQL Command was too complex for the designer's interface to support all the command clauses.


Property "name" is protected (Error 1757)

Visual FoxPro 9.0
Property "name" is protected (Error 1757)

You cannot change the value of a protected property.


.DIF type indicator is invalid (Error 117)

Visual FoxPro 9.0
.DIF type indicator is invalid (Error 117)

The .dif file has an invalid data type indicator.


Too many variables (Error 22)

Visual FoxPro 9.0
Too many variables (Error 22)

The maximum number of variables that can be created has been exceeded. For more information, see Visual FoxPro System Capacities.


SQL SELECT statement is invalid (Error 1498)

Visual FoxPro 9.0
SQL SELECT statement is invalid (Error 1498)

The SQL statement which defines a view is missing the SELECT or FROM clause. Correct the syntax of the SQL statement. For more information, see SELECT - SQL Command.


Data environment is already loaded (Error 1966)

Visual FoxPro 9.0
Data environment is already loaded (Error 1966)

You are invoking the OpenTables method of the data environment and the data environment is already loaded.


Too few arguments (Error 1229)

Visual FoxPro 9.0
Too few arguments (Error 1229)

A function call contains less than the required number of arguments.


Menu has not been activated with ACTIVATE MENU (Error 178)

Visual FoxPro 9.0
Menu has not been activated with ACTIVATE MENU (Error 178)

You have attempted to select from a menu before the menu has been activated. For more information, see ACTIVATE MENU Command.


Output page "page" is not available (Error 2194)

Visual FoxPro 9.0
Output page "page" is not available (Error 2194)

The Report Listener OutputPage method contains an invalid or out of range page parameter. Depending on the setting of the ReportListener Object ListenerType Property, a page parameter may be invalid regardless of the page range or the report's page total during report processing.

See the OutputPage Method for more information.


"name" is a read-only property (Error 1740)

Visual FoxPro 9.0
"name" is a read-only property (Error 1740)

Read-only properties cannot store values.

  • Only writable properties can store values.

    Verify the property names and attributes for the object you are working with (see its Help topic), and then use one of the existing writable properties or define your own in the New Property dialog box.


Unrecognized index file revision. Re-create the index (Error 1141)

Visual FoxPro 9.0
Unrecognized index file revision. Re-create the index (Error 1141)

The index file is in a format that is not compatible with this version of Visual FoxPro.

Recreate the index.


Menu item position must be a positive number (Error 167)

Visual FoxPro 9.0
Menu item position must be a positive number (Error 167)

You have attempted to position a menu or menu title using a negative number.


Cannot locate your Web browser (Error 2006)

Visual FoxPro 9.0
Cannot locate your Web browser (Error 2006)

Visual FoxPro could not run the Web START command for the Web location you chose.

  • There is no Web browser available on your machine.

    Install (or re-install) a Web browser.


This property is read-only (Error 1533)

Visual FoxPro 9.0
This property is read-only (Error 1533)

You cannot change the value of a read-only property.


Cannot modify a base class (Error 1731)

Visual FoxPro 9.0
Cannot modify a base class (Error 1731)

You have attempted to modify a Visual FoxPro base class.

To make modifications, you must first define your own subclass based on the Visual FoxPro base class.


RUN|! command string is too long (Error 1411)

Visual FoxPro 9.0
RUN|! command string is too long (Error 1411)

The command string included with the RUN command is too long. The maximum length allowed is approximately 240 characters.


.SYLK file header is invalid (Error 119)

Visual FoxPro 9.0
.SYLK file header is invalid (Error 119)

The file header of the file you have attempted to import has an incorrect SYLK file header.


SQL: Invalid use of subquery (Error 1810)

Visual FoxPro 9.0
SQL: Invalid use of subquery (Error 1810)

A subquery was used in a place where it wasn't expected. For more information, see SELECT - SQL Command.


Lotus 1-2-3 version 1.0 file format is invalid (Error 1662)

Visual FoxPro 9.0
Lotus 1-2-3 version 1.0 file format is invalid (Error 1662)

The Lotus 1-2-3 file you have attempted to import is either not version 1.0 or has been corrupted.


Worksheet A for Lotus 1-2-3 version 3.0 file is hidden (Error 1680)

Visual FoxPro 9.0
Worksheet A for Lotus 1-2-3 version 3.0 file is hidden (Error 1680)

Visual FoxPro cannot import a worksheet that has been hidden.


** or ^ domain error (Error 78)

Visual FoxPro 9.0
** or ^ domain error (Error 78)

Negative numbers can only be raised to integer values.

  • The exponentiation operator cannot accept fractional values for negative numbers.

    Use an integer exponent.


Lotus 1-2-3 version 2.0 file format is invalid (Error 297)

Visual FoxPro 9.0
Lotus 1-2-3 version 2.0 file format is invalid (Error 297)

The Lotus 1-2-3 file you have attempted to import is not version 2.0. Use the Lotus conversion utility to convert the file to version 2.0 before attempting to import it.


A Key cannot be specified when adding an item to this collection. (Error 2064)

Visual FoxPro 9.0
A Key cannot be specified when adding an item to this collection. (Error 2064)

You cannot specify a key when adding a new item to a collection in which all items do not have keys. Either all items in a collection have keys or do not have keys. To determine if a collection requires keys, use GetKey(1) and the EMPTY( ) function as follows:

Copy Code
? EMPTY(Collection.GetKey(1))


Value of XMLName, XMLNamespace or XMLPrefix property should be a Unicode string. (Error 2134)

Visual FoxPro 9.0
Value of XMLName, XMLNamespace or XMLPrefix property should be a Unicode string. (Error 2134)

Non-Unicode strings cannot be assigned as values to the XMLAdapter objects, XMLName, XMLNamespace, and XMLPrefix properties.

  • Use the STRCONV( ) function to convert a string to Unicode. The following code converts a string to Unicode.

    Copy Code
    oXMLTable = CREATEOBJECT("XMLTABLE")
oXMLTable.XMLName = STRCONV("MyTable",12)


Library file "name" is invalid (Error 1691)

Visual FoxPro 9.0
Library file "name" is invalid (Error 1691)

Visual FoxPro cannot use the library file you specified.

Rebuild the library.


Invalid use of a Visual FoxPro function as an array (Error 1652)

Visual FoxPro 9.0
Invalid use of a Visual FoxPro function as an array (Error 1652)

Visual FoxPro encountered a function when it was expecting an array name.

Replace the function with a valid array name.


Method contains syntax errors. Method is not saved (Error 1765)

Visual FoxPro 9.0
Method contains syntax errors. Method is not saved (Error 1765)

You have either included more than one procedure or have a class declaration in the code.

Fix the code and try again.


Error loading printer driver (Error 1958)

Visual FoxPro 9.0
Error loading printer driver (Error 1958)

An internal call to the LoadLibrary( ) function has failed. Visual FoxPro calls this function through either PRTINFO( ) or SET PRINTER TO.


DataType property for field "name" is invalid (Error 1544)

Visual FoxPro 9.0
DataType property for field "name" is invalid (Error 1544)

The value of the view field DataType property is not a valid Visual FoxPro data type.

Change the view field DataType property to a valid type.


Must specify additional parameters (Error 94)

Visual FoxPro 9.0
Must specify additional parameters (Error 94)

Occurs when:

The number of parameters specified in a DO ... WITH statement is greater than the number of parameters defined by the PARAMETERS statement in the called program.

-or-

The delegate method does not have the same number of parameters as the event specified in cEvent in the BINDEVENT( ) function.


Invalid collation sequence (Error 2153)

Visual FoxPro 9.0
Invalid collation sequence (Error 2153)

The collation sequence specified cannot be found or is not valid. This error can be generated when a collation sequence other than MACHINE is used when creating an index with a Varbinary Data Type expression.


No default value to DROP (Error 1878)

Visual FoxPro 9.0
No default value to DROP (Error 1878)

You have attempted to use the DROP DEFAULT clause of the ALTER TABLE command on a column with no default value. This is not a valid operation.


Cannot locate ODBC library, ODBC32.DLL (Error 1527)

Visual FoxPro 9.0
Cannot locate ODBC library, ODBC32.DLL (Error 1527)

The file ODBC32.DLL cannot be found.

  • This file must be in the current path to use connectivity features.

    If the file is not on your system, reinstall the ODBC component of Visual FoxPro. If present, copy the file to your default system directory.


INSERT cannot be issued when row or table buffering is enabled or when integrity constraints are in effect (Error 1588)

Visual FoxPro 9.0
INSERT cannot be issued when row or table buffering is enabled or when integrity constraints are in effect (Error 1588)

Either set row and table buffering off by setting the Buffering property to 1 with CURSORSETPROP( ), or use APPEND instead of INSERT.


Command is missing required clause (Error 1221)

Visual FoxPro 9.0
Command is missing required clause (Error 1221)

A command was used without a clause that was required by the Visual FoxPro syntax. Select the command and press F1 to get context-sensitive Help on the command.


Function name is missing ) (Error 1300)

Visual FoxPro 9.0
Function name is missing ) (Error 1300)

A function name is missing a right parenthesis.

  • The current line contains a left parenthesis which has not been matched.

  • The function contains too many arguments and thus the right parenthesis is undetected.


No database is open or set as the current database (Error 1520)

Visual FoxPro 9.0
No database is open or set as the current database (Error 1520)

You have attempted to perform an action which requires a database to be open and set as current.

Use the OPEN DATABASE or SET DATABASE TO commands, or select a database from the database drop-down list in the standard toolbar.


A sharing violation occurred. (Error 2024)

Visual FoxPro 9.0
A sharing violation occurred. (Error 2024)

Another application is using the file that you attempted to drop in an OLE drag-and-drop operation.


Function argument value, type, or count is invalid (Error 11)

Visual FoxPro 9.0
Function argument value, type, or count is invalid (Error 11)

A value passed to a function is not of the expected data type, or the value of the argument is out of range for this function, or you are passing too many arguments to a function.


Script error: "name" (Error 1917)

Visual FoxPro 9.0
Script error: "name" (Error 1917)

There was an unknown error is the specified script.


File is in use (Error 3)

Visual FoxPro 9.0
File is in use (Error 3)

You have attempted a USE, DELETE, or RENAME command on a file that is currently open.


Cannot close table during execution of a table-bound expression (Error 1546)

Visual FoxPro 9.0
Cannot close table during execution of a table-bound expression (Error 1546)

Do not attempt to close tables during this operation.


Property "name" is not a method or event (Error 1738)

Visual FoxPro 9.0
Property "name" is not a method or event (Error 1738)

You used a name that is not a method or event.


Source code out of date.

Visual FoxPro 9.0
Source code out of date.

The date source code you specified does not match the compiled (.FXP) file.


Init event failed (Error 1730)

Visual FoxPro 9.0
Init event failed (Error 1730)

The Init Event for the object failed and it is possible that the object could not be instantiated.


Cannot open file "file". (Error 101)

Visual FoxPro 9.0
Cannot open file "file". (Error 101)

Visual FoxPro cannot open the file specified. The file might be locked by another user on a network.


This array element has been defined as an object and cannot be redefined in the class definition (Error 1780)

Visual FoxPro 9.0
This array element has been defined as an object and cannot be redefined in the class definition (Error 1780)

Once you have defined an array element as an object member in a class definition, it cannot be redefined.

For example, the following code would cause this error:

Copy Code
DEFINE CLASS test AS form
   DIME a[1]
   ADD OBJECT a[1] AS commandbutton
   a[1] = 10
ENDDEFINE


Cannot set DBCEventFile property when DBCEvents is off. (Error 2045)

Visual FoxPro 9.0
Cannot set DBCEventFile property when DBCEvents is off. (Error 2045)

An attempt to call the DBSETPROP( ) function was made without turning DBCEvents on. For more information, see How to: Enable or Disable DBC Events.


Operation is invalid for a General field (Error 1912)

Visual FoxPro 9.0
Operation is invalid for a General field (Error 1912)

You have attempted to perform an invalid operation, such as a calculation or indexing, on a General field.


Objects cannot be programmatically deleted from the Class Designer (Error 1919)

Visual FoxPro 9.0
Objects cannot be programmatically deleted from the Class Designer (Error 1919)

You have attempted to delete an object contained within a class in the Class Designer. This cannot be done.


Date/DateTime evaluated to an invalid value (Error 2034)

Visual FoxPro 9.0
Date/DateTime evaluated to an invalid value (Error 2034)

A Date or DateTime is not in the valid Date or DateTime format, or is outside the valid Date or DateTime range.


A stored procedure is executing (Error 1538)

Visual FoxPro 9.0
A stored procedure is executing (Error 1538)

You have attempted to recompile or unload stored procedures (for example, MODIFY PROCEDURE or CLOSE DATABASES) while in the middle of executing a stored procedure. This is an invalid operation.


Cannot update ADODB.Recordset because it is read-only. (Error 2083)

Visual FoxPro 9.0
Cannot update ADODB.Recordset because it is read-only. (Error 2083)

Occurs when the supplied ADO Recordset is in a non-updatable configuration and is set as the data source.

  • Make sure the ADO Recordset is configured to support updates. The ADO Recordset must typically have its CursorType property be adOpenKeyset, adOpenDynamic, or adOpenStatic, and its CursorLocation property must typically be adUseClient.


"file" is not a table (Error 15)

Visual FoxPro 9.0
"file" is not a table (Error 15)

The file that Visual FoxPro is attempting to use as a table contains an improper header.


.DIF vector is invalid - .DBF field mismatch (Error 116)

Visual FoxPro 9.0
.DIF vector is invalid - .DBF field mismatch (Error 116)

The .dif file you have attempted to import has an internal conflict between its header and its data.


Class "name" has not been registered (Error 1434)

Visual FoxPro 9.0
Class "name" has not been registered (Error 1434)

You have attempted to use a form that contains an OLE object whose server has not been installed on the current machine.


No sheet is found (Error 1774)

Visual FoxPro 9.0
No sheet is found (Error 1774)

The .XLS file you are referencing contains no worksheet records. This can also occur for a file containing only charts or macros.


Cannot open persistent table buffer directly (Error 2013)

Visual FoxPro 9.0
Cannot open persistent table buffer directly (Error 2013)

The change buffer (.TBF) file for an offline view cannot be opened directly.

Only the .dbf file corresponding to the offline view can be opened.


File "name" is an invalid database (Error 1551)

Visual FoxPro 9.0
File "name" is an invalid database (Error 1551)

Problems were detected trying use the named database.

Try opening it and running VALIDATE DATABASE to diagnose or repair the problem.


Access to system Registry denied (Error 1640)

Visual FoxPro 9.0
Access to system Registry denied (Error 1640)

Access to the system Registry is required to perform operations such as creating COM servers. Make sure you are logged on and have the proper access rights.


ADODB.Recordset is already opened. (Error 2080)

Visual FoxPro 9.0
ADODB.Recordset is already opened. (Error 2080)

Visual FoxPro requires that an ADO Recordset is closed when it is being added to a CursorAdapter object. This is because, the CursorFill method attempts to open the ADO Recordset when it is being added. To use an ADO Recordset that is already open, pass it to the Source parameter of the CursorFill method.


Record is in use by another user (Error 109)

Visual FoxPro 9.0
Record is in use by another user (Error 109)

You have attempted to write to a record that is locked by another user.


File is open in another work area (Error 1708)

Visual FoxPro 9.0
File is open in another work area (Error 1708)

Commands that require exclusive use of a table (PACK, MODIFY STRUCTURE, ZAP, and so on) cannot be used on a table that has been opened in multiple work areas with the AGAIN clause of the USE command.


The LOCATE command must be issued before the CONTINUE command (Error 42)

Visual FoxPro 9.0
The LOCATE command must be issued before the CONTINUE command (Error 42)

You have attempted to execute a CONTINUE command without first executing a LOCATE command.


TEXT does not have corresponding ENDTEXT statement (Error 2131)

Visual FoxPro 9.0
TEXT does not have corresponding ENDTEXT statement (Error 2131)

A TEXT ... ENDTEXT Command is missing the required ENDTEXT terminator.


Invalid database table name (Error 1578)

Visual FoxPro 9.0
Invalid database table name (Error 1578)

Valid database table names contain only alphanumeric characters and spaces, and cannot start with a number. They may not be longer than 128 characters.


EventHandler object "name" does not IMPLEMENT an interface (Error 1445)

Visual FoxPro 9.0
EventHandler object "name" does not IMPLEMENT an interface (Error 1445)

The EVENTHANDLER( ) function specifies an interface that is not implemented by the specified EventHandler object. For more information, see EVENTHANDLER( ) Function.


Error instantiating the object "object". (Error 1736)

Visual FoxPro 9.0
Error instantiating the object "object". (Error 1736)

The server for the object is not registered properly, resources are low, or a required .dll file is not present. Other reasons are as specified.


Form file "name" is invalid (Error 1686)

Visual FoxPro 9.0
Form file "name" is invalid (Error 1686)

The screen file specified has become corrupted.


Array dimensions are invalid (Error 230)

Visual FoxPro 9.0
Array dimensions are invalid (Error 230)

Arrays must have at least one element, or the number of elements you've specified exceeds the amount of available memory.


Worksheet "name" is not found (Error 1775)

Visual FoxPro 9.0
Worksheet "name" is not found (Error 1775)

You are trying to specify a worksheet name that does not match a name in the specified .XLS file.

Verify the worksheet name and try the operation again.


Menu item's conditional statement is too long. (Error 2051)

Visual FoxPro 9.0
Menu item's conditional statement is too long. (Error 2051)

The condition exceeds 256 characters. Try reducing the number of characters.


Warning: Invalid data conversion(s) starting at record "number" (Error 1485)

Visual FoxPro 9.0
Warning: Invalid data conversion(s) starting at record "number" (Error 1485)

A data conversion error was reported while fetching data in record number of the remote result set.

  • The ODBC driver cannot convert some remote data values into the local view data type.

    Use a conversion function in the remote SQL statement to convert the data to a different data type before being fetched; use the DataType view field property to change the local data type.


Failed to create recordset (Error 2039)

Visual FoxPro 9.0
Failed to create recordset (Error 2039)

Error Message

Secondary English Title

Visual FoxPro attempted to created the ADO recordset, but could not do so for an unexpected reason.


Cannot nest class definitions (Error 1926)

Visual FoxPro 9.0
Cannot nest class definitions (Error 1926)

A class definition cannot contain another class definition.


Data session #number cannot be released with open transaction(s) (Error 1549)

Visual FoxPro 9.0
Data session #number cannot be released with open transaction(s) (Error 1549)

A data session-based object is being closed while there are open transactions. The data session will remain active.

Close the data session by issuing SET DATASESSION TO number followed by the appropriate number of END TRANSACTION or ROLLBACK commands.


Procedure "name" is not found (Error 1162)

Visual FoxPro 9.0
Procedure "name" is not found (Error 1162)

The procedure specified with the IN clause of the DO command could not be located.


Both Unicode and IsBinary properties can not be set to .T.. (Error 2140)

Visual FoxPro 9.0
Both Unicode and IsBinary properties can not be set to .T.. (Error 2140)

Visual FoxPro does not allow for both the Unicode property and the IsBinary property to be set to True (.T.) on the same XMLField object.


No menu is defined (Error 1605)

Visual FoxPro 9.0
No menu is defined (Error 1605)

You attempted to activate a menu before defining a menu bar.


Allowed DO nesting level exceeded (Error 103)

Visual FoxPro 9.0
Allowed DO nesting level exceeded (Error 103)

The number of nesting levels has been exceeded. For more information, see Visual FoxPro System Capacities.

To exceed the current limit of nesting levels, change the number of nesting levels by including the STACKSIZE setting and the new limit of nesting levels in a configuration file to use when Visual FoxPro starts up. For more information, see Special Terms for Configuration Files.


Symphony version 1.1 file format is invalid (Error 1674)

Visual FoxPro 9.0
Symphony version 1.1 file format is invalid (Error 1674)

The Symphony file you have attempted to import is either not version 1.1 or has been corrupted.


SQL expression is too complex (Error 1845)

Visual FoxPro 9.0
SQL expression is too complex (Error 1845)

Visual FoxPro ran out of memory when it tried to expand the SELECT statement in order to analyze it.


"name" objects cannot return a value (Error 1983)

Visual FoxPro 9.0
"name" objects cannot return a value (Error 1983)

The root object of the form stores the return value from its Unload event with the TO clause of the DO FORM command.

  • Only Form and FormSet objects can return values.

    Make sure the root object is a form or a form set.


Cannot reuse offline view in different mode (Error 2017)

Visual FoxPro 9.0
Cannot reuse offline view in different mode (Error 2017)

Offline views can only be opened in the mode they were originally created.

  • You opened an offline view online inside a transaction and then attempted to open it offline.


Project file is read-only (Error 1169)

Visual FoxPro 9.0
Project file is read-only (Error 1169)

Visual FoxPro does not allow you to open read-only projects.

Make the project writable and then try again.


Field must be a General field (Error 1913)

Visual FoxPro 9.0
Field must be a General field (Error 1913)

You have attempted to enter a non-general field name with APPEND GENERAL or MODIFY GENERAL., or you have attempted to enter a non-general field name into the Report Picture dialog box.


Operator/operand type mismatch (Error 107)

Visual FoxPro 9.0
Operator/operand type mismatch (Error 107)

An arithmetic, string, or logical operator or function is being used with an invalid data type. This error would occur, for example, if you were to attempt to add two logical values.


Class file "name" is invalid (Error 1747)

Visual FoxPro 9.0
Class file "name" is invalid (Error 1747)

The visual class library (.vcx) file is corrupt and must be restored from a backup file or recreated.


*Interrupted*

Visual FoxPro 9.0
*Interrupted*

Program execution has been halted temporarily.

  • You pressed the ESC key.

    Choose Cancel, Suspend, or Ignore from the error dialog box.


Table or row buffering requires that SET MULTILOCKS is set to ON (Error 1589)

Visual FoxPro 9.0
Table or row buffering requires that SET MULTILOCKS is set to ON (Error 1589)

All buffering modes require MULTILOCKS to be enabled. TO disable buffering, set buffering to 1 (DB_BUFOFF) using CURSORSETPROP( ).


WITH/ENDWITH mismatch (Error 1939)

Visual FoxPro 9.0
WITH/ENDWITH mismatch (Error 1939)

You must have a corresponding ENDWITH statement for every WITH statement.


SQL: TOP requires an ORDER BY (Error 1867)

Visual FoxPro 9.0
SQL: TOP requires an ORDER BY (Error 1867)

You must provide an ORDER BY clause if you use the TOP clause. For more information, see SELECT - SQL Command.


ROLLBACK command cannot be issued without a corresponding BEGIN TRANSACTION command (Error 1592)

Visual FoxPro 9.0
ROLLBACK command cannot be issued without a corresponding BEGIN TRANSACTION command (Error 1592)

A transaction must be ongoing to use the ROLLBACK command.


SQL: Invalid SET expression in UPDATE, "table name" is not a target table (Error 2149)

Visual FoxPro 9.0
SQL: Invalid SET expression in UPDATE, "table name" is not a target table (Error 2149)

The UPDATE statement in the SELECT - SQL Command contains an invalid table reference in the SET expression.


The refresh key defined for table "table name" is not found (Error 2166)

Visual FoxPro 9.0
The refresh key defined for table "table name" is not found (Error 2166)

The REFRESH( ) Function did not return any rows.


Cursor "name" is attached to another CursorAdapter object. (Error 2112)

Visual FoxPro 9.0
Cursor "name" is attached to another CursorAdapter object. (Error 2112)

Visual FoxPro does not allow a cursor to be attached to a CursorAdapter object if it is already associated with another CursorAdapter object.

  • To check if a cursor is already attached to a CursorAdapter, check its SourceType property by using the CursorGetProp( ) function.


Error initializing Application object (Error 1574)

Visual FoxPro 9.0
Error initializing Application object (Error 1574)

The Automation server or type library is not registered correctly.

  • Your registry file is corrupted.

    Remove the registry entry.


Cannot refresh record from ADODB.Recordset because FOX cursor does not have an ADOBookmark column (Error 2170)

Visual FoxPro 9.0
Cannot refresh record from ADODB.Recordset because FOX cursor does not have an ADOBookmark column (Error 2170)

The Visual FoxPro cursor does not have an ADOBookmark field.


Duplicate field names (Error 1156)

Visual FoxPro 9.0
Duplicate field names (Error 1156)

You have specified a duplicate name in the FIELDS clause for SORT or a COPY command. Correct your program or command and try again.


Class library file "name" is not found (Error 1993)

Visual FoxPro 9.0
Class library file "name" is not found (Error 1993)

The visual class library (.vcx) file specified in the RELEASE CLASSLIB or CLEAR CLASSLIB command is not in the SET CLASSLIB list.


Cannot save form: an object has an invalid name (Error 1191)

Visual FoxPro 9.0
Cannot save form: an object has an invalid name (Error 1191)

Objects must be named correctly before the form can be saved.

  • One or more object names are set to the empty string.

    Search for Name properties set to "".


This feature requires MSXML4 SP1 or later. (Error 2116)

Visual FoxPro 9.0
This feature requires MSXML4 SP1 or later. (Error 2116)

Visual FoxPro requires that MSXML 4 SP1 or later is installed to use the XMLAdapter object.


Cannot create program workspace.

Visual FoxPro 9.0
Cannot create program workspace.

Visual FoxPro was not able to create enough workspace at startup.

  • The disk or directory is full.

    Remove files and try again.

  • You do not have access to the target directory.

    Check your permission level.


Object "name" is not found (Error 1923)

Visual FoxPro 9.0
Object "name" is not found (Error 1923)

The object you have specified cannot be found.


SQL: Too many subqueries (Error 1805)

Visual FoxPro 9.0
SQL: Too many subqueries (Error 1805)

The number of subqueries allowed in Visual FoxPro 8.0 is nine per SELECT statement. In Visual FoxPro 9.0, the number of subqueries is limited by memory and disk space. For more information, see SELECT - SQL Command.


Database object is being used by someone else. (Error 1709)

Visual FoxPro 9.0
Database object is being used by someone else. (Error 1709)

Another user is accessing this database object.

  • Visual FoxPro is accessing records temporarily in response to another user's actions.

    Wait a few minutes and try again.

  • Another user is modifying a table or connection.

    Contact the user. If you are modifying a table or a connection, you are preventing others from having access while you are in the designer. For more information, see MODIFY STRUCTURE, MODIFY CONNECTION, and so on.

  • Another user is modifying a view.

    You can still use the view. If you want to modify it, contact the user. For more information, see MODIFY VIEW.


Conversion is canceled (Error 1799)

Visual FoxPro 9.0
Conversion is canceled (Error 1799)

The conversion has been canceled. The files involved might not be converted.


Table "name" has a file length / record number inconsistency (Error 2065)

Visual FoxPro 9.0
Table "name" has a file length / record number inconsistency (Error 2065)

The specified table appears to be corrupt due to an invalid file length or record number. The table will need to be repaired before transactions can be committed properly.


File is not open (Error 1113)

Visual FoxPro 9.0
File is not open (Error 1113)

You have attempted to read from, or write to, a file that is not currently open.


SQL statement parameter is required for non-prepared SqlExec( ) calls (Error 1472)

Visual FoxPro 9.0
SQL statement parameter is required for non-prepared SqlExec( ) calls (Error 1472)

You must either use SQLPREPARE( ) first or include a SQL statement in the call to SQLEXEC( ).

  • SQLPREPARE( ) has not been called.

    Include a SQL statement directly in SQLEXEC( ) or call SQLPREPARE( ) before calling SQLEXEC( ).

  • The prepared state has been cleared because SQLEXEC( ) was called with a cSQLCommand argument or because SQLPREPARE( ) was called.

    Call SQLPREPARE( ) again.


RUN|! Command failed. "Details" (Error 1405)

Visual FoxPro 9.0
RUN|! Command failed. "Details" (Error 1405)

The operating system message that accompanies this Visual FoxPro message indicates why it cannot create a process to execute a RUN command.

Most often, this error occurs because of the inability to find the shell program to be executed or does not have sufficient free memory to load the shell program into memory.


The table has memo fields that cannot be converted while open read-only (Error 1659)

Visual FoxPro 9.0
The table has memo fields that cannot be converted while open read-only (Error 1659)

You have attempted to perform a read-only operation on a dBASE IV style memo. Visual FoxPro cannot convert a memo in a read-only operation.


Table has no index order set (Error 26)

Visual FoxPro 9.0
Table has no index order set (Error 26)

The records in the table have no order.

  • An index for the table file was not selected when an UPDATE command using the RANDOM clause was encountered.

    Select an index for the table file.

  • A FIND or SEEK was attempted against a table with no index ordering.

    Use SET ORDER TO to specify an index order.

  • SET RELATION was issued with a non-numeric expression.

    Provide a numeric expression.


API call caused an exception. (Error 2028)

Visual FoxPro 9.0
API call caused an exception. (Error 2028)

The parameters passed to an API caused an exception in the API.

Make sure that you pass all the necessary parameters to the API and that the parameters are of the proper type.


OLE IDispatch exception code "number" from "name": "name" (Error 1428)

Visual FoxPro 9.0
OLE IDispatch exception code "number" from "name": "name" (Error 1428)

You have received an error code returned by an Automation object. It is specific to the OLE object.In this case, the object returns a textual description of the error, as well as the source (usually OLE object name) of the error.

Refer to the object's documentation for more detailed information.


Cursor doesn't support ADOBookmark property (Error 2188)

Visual FoxPro 9.0
Cursor doesn't support ADOBookmark property (Error 2188)

The CURSORGETPROP( ) Function was unable to determine the ADO bookmark for the current record in an ADO-based cursor.


Cannot call SetFocus from within a When, Valid, RangeHigh or RangeLow event (Error 2012)

Visual FoxPro 9.0
Cannot call SetFocus from within a When, Valid, RangeHigh or RangeLow event (Error 2012)

The SetFocus method conflicts with these events, which are testing to see if the object can get or lose focus.

  • You are calling SetFocus from a When event.

    Call SetFocus from the GotFocus event instead.

  • You are calling SetFocus from a Valid, RangeHigh, or RangeLow event.

    Call SetFocus from the LostFocus event instead.


Invalid operation for offline view (Error 2011)

Visual FoxPro 9.0
Invalid operation for offline view (Error 2011)

Some operations are not valid for offline views.

  • You tried to modify the view definition or table, compact the view, insert or delete records, or refresh the view.

    Do not use these commands on offline views.


Preprocessor expression is invalid (Error 1722)

Visual FoxPro 9.0
Preprocessor expression is invalid (Error 1722)

Only simple expressions (evaluation, concatenation, and math) are allowed in preprocessor commands (#IF and so on).


Left margin including indent must be less than the right margin (Error 221)

Visual FoxPro 9.0
Left margin including indent must be less than the right margin (Error 221)

The position of the right margin must be greater than the position of the left margin.

Adjust the margin settings and try this operation again.


Inner and outer XMLTable objects are not associated with the same XMLAdapter object (Error 2177)

Visual FoxPro 9.0
Inner and outer XMLTable objects are not associated with the same XMLAdapter object (Error 2177)

This error is generated by the XMLTable Class Nest Method when the XMLTable object and oXMLTable parameter do not belong to the same XMLAdapter object.


Not a character expression (Error 45)

Visual FoxPro 9.0
Not a character expression (Error 45)

You have attempted to call a module with an expression whose value is not of the type Character.


Unknown member object "object name" (Error 2154)

Visual FoxPro 9.0
Unknown member object "object name" (Error 2154)

You cannot subclass a property - only an object can be subclassed. See Subclasses in Visual FoxPro for more information about creating subclasses from objects.


SelectCmd is empty. (Error 2139)

Visual FoxPro 9.0
SelectCmd is empty. (Error 2139)

Occurs when the SelectCmd property is empty. Visual FoxPro requires that the SelectCmd property is set to a valid value, appropriate to the what the DataSourceType property specifies, when the CursorFill method is called.

  • Make sure that the SelectCmd property is set to a valid value.


Too many characters are specified in the PICTURE clause (Error 1310)

Visual FoxPro 9.0
Too many characters are specified in the PICTURE clause (Error 1310)

The amount of characters permitted in a PICTURE clause is limited by memory.


The name of the object file for "file" is already used by another program in the project (Error 2001)

Visual FoxPro 9.0
The name of the object file for "file" is already used by another program in the project (Error 2001)

Select a different file name.


Table buffer for alias "name" contains uncommitted changes (Error 1545)

Visual FoxPro 9.0
Table buffer for alias "name" contains uncommitted changes (Error 1545)

The named cursor has a modified table buffer, so changes must be explicitly committed using TABLEUPDATE( ) or discarded using TABLEREVERT( ) before either closing the cursor or changing the buffering mode.


Error writing to file "file" (Error 1105)

Visual FoxPro 9.0
Error writing to file "file" (Error 1105)

The operating system returned an error while Visual FoxPro was attempting to write to the specified file. Most often, this error occurs when attempting to write to a write-protected disk.


Trigger failed in "cursor". (Error 1539)

Visual FoxPro 9.0
Trigger failed in "cursor". (Error 1539)

Fix record values so the trigger does not fail, or revert the record.


String is too long to fit (Error 1903)

Visual FoxPro 9.0
String is too long to fit (Error 1903)

The allowable string length was exceeded. For more information, see Visual FoxPro System Capacities.


Type conversion is not supported (Error 1532)

Visual FoxPro 9.0
Type conversion is not supported (Error 1532)

SQL parameter conversion error. Internal connectivity error.

This error may also occur with an invalid use of the CAST function; for example, CAST(DATE( ) as Numeric).


Feature is not supported for non-.DBC tables (Error 1580)

Visual FoxPro 9.0
Feature is not supported for non-.DBC tables (Error 1580)

You have tried to implement a feature, such as a nullable field, a primary key, a persistent relation, a default value, a validation rule, or a trigger, on a free table. These features are available only for tables that are contained in a database (.dbc).

Use ADD TABLE to add a free table to a database.


SQL: Operation was canceled (Error 1839)

Visual FoxPro 9.0
SQL: Operation was canceled (Error 1839)

There was an attempt to run a SELECT statement on a table when SAFETY was ON and the user chose not to overwrite the table. For more information, see SELECT - SQL Command.


File "name" is not a database (Error 1552)

Visual FoxPro 9.0
File "name" is not a database (Error 1552)

The database operation you have attempted failed because the file was not a valid database.

Try again with a file of the correct type.


Cannot update the file "file" (Error 1157)

Visual FoxPro 9.0
Cannot update the file "file" (Error 1157)

Visual FoxPro cannot update the specified file. A critical error occurred while writing to the disk, such as lack of disk space or read/write failure.


Objects cannot be assigned to arrays (Error 1942)

Visual FoxPro 9.0
Objects cannot be assigned to arrays (Error 1942)

Array elements can only contain values.


Connection "name" is busy (Error 1541)

Visual FoxPro 9.0
Connection "name" is busy (Error 1541)

This remote connection is in use by another executing statement.

Wait until it completes or cancel it before retrying this operation.


Warning: The next "cExpr" modified records have already been updated remote (Error 1484)

Visual FoxPro 9.0
Warning: The next "cExpr" modified records have already been updated remote (Error 1484)

An error has occurred while trying to update a batch of modified rows of a remote view, in the view cursor, after the batch has been successfully updated in the remote base table.

Turn off the SendUpdates view property and commit the records by calling TABLEUPDATE( ).


Not a valid RapidFile database (Error 255)

Visual FoxPro 9.0
Not a valid RapidFile database (Error 255)

The file you have attempted to import is not a valid RapidFile file format.


"name" is not an object (Error 1924)

Visual FoxPro 9.0
"name" is not an object (Error 1924)

This name was previously defined as something other than an object.

  • You have another occurrence of name.

    Check your code for duplicate instances of name.


Expression evaluator failed (Error 67)

Visual FoxPro 9.0
Expression evaluator failed (Error 67)

An internal consistency check in the Visual FoxPro expression evaluator failed. This might be caused by a damaged Visual FoxPro object code file.

Recompile the program that caused the error.


Printer redirection is invalid (Error 124)

Visual FoxPro 9.0
Printer redirection is invalid (Error 124)

Either a path to a printer is not established or the print device cannot be shared.


Update conflict. Some of your changes in the current row batch were committed (Error 1595)

Visual FoxPro 9.0
Update conflict. Some of your changes in the current row batch were committed (Error 1595)

The full text of this error message is:

Update conflict. Some of your changes in the current row batch were committed. Use TABLEUPDATE( ) with the lForce parameter to commit the update or the manual transaction to roll back the update (Error 1595)

The multitable update was not included in a remote transaction and failed.

  • Some of the tables involved in the update may be committed in the base remote tables.

    Force the update for the current row or current row batch or rollback the remote manual transaction on the current connection. For more information, see TABLEUPDATE( ) Function.


OLE error code 0x"name" (Error 1426)

Visual FoxPro 9.0
OLE error code 0x"name" (Error 1426)
See Also

You have received a hexadecimal error code from OLE and a brief description of the error. The remedy depends on the error returned by OLE. Although the error is external to Visual FoxPro, you can use the AERROR( ) function to determine if a more specific error message was sent by the OLE provider.

See Also

Reference

AERROR( ) Function


Cannot import from password-protected file (Error 1671)

Visual FoxPro 9.0
Cannot import from password-protected file (Error 1671)

The file you have attempted to import is encrypted.


Unknown function key (Error 104)

Visual FoxPro 9.0
Unknown function key (Error 104)

An attempt was made to use SET FUNCTION with a function key that does not match the name or number of an existing function key.


Project file "name" is in the wrong version (Error 1946)

Visual FoxPro 9.0
Project file "name" is in the wrong version (Error 1946)

The project file specified does not match the version of Visual FoxPro.


API function _UserError( ) was called (Error 1098)

Visual FoxPro 9.0
API function _UserError( ) was called (Error 1098)

A user-supplied error string was displayed.


Index does not match the table. Delete the index file and re-create the index (Error 114)

Visual FoxPro 9.0
Index does not match the table. Delete the index file and re-create the index (Error 114)

A damaged structure within an index file has been detected.

Delete the index file (.CDX or .IDX) and recreate it.


XMLAdapter.XMLName is empty. (Error 2127)

Visual FoxPro 9.0
XMLAdapter.XMLName is empty. (Error 2127)

Visual FoxPro requires that the XMLName property, for an XMLTable is specified, before the ApplyDiffgram and the ChangesToCursor methods are called.


Memo file "name" is missing or is invalid (Error 41)

Visual FoxPro 9.0
Memo file "name" is missing or is invalid (Error 41)

An attempt was made to use a table file whose associated memo file (.dct or .fpt) has been deleted, removed, cannot be found or is invalid.


Related tag is not found or not primary or candidate (Error 1882)

Visual FoxPro 9.0
Related tag is not found or not primary or candidate (Error 1882)

A database relation object is being created or referenced in which some of the related information was missing, not primary or candidate, or invalid.

  • You used the REFERENCES and TAG clauses of the CREATE TABLE or ALTER TABLE command.

    Make sure both tables involved in the relation are in the database.


Invalid character entered (Error 2047)

Visual FoxPro 9.0
Invalid character entered (Error 2047)

An invalid character was entered for the expected value.


File "name" does not exist (Error 1)

Visual FoxPro 9.0
File "name" does not exist (Error 1)

The file specified does not exist.


Too many files open (Error 6)

Visual FoxPro 9.0
Too many files open (Error 6)

Visual FoxPro has attempted to open more than its internal limit of files.


View definition has been changed (Error 1494)

Visual FoxPro 9.0
View definition has been changed (Error 1494)

The view cannot be re-queried.

  • The view definition in the database has been changed.

    Close and reopen the view. To ensure that the view is not changed, open the database exclusively.


Cannot reopen project file "name" (Error 1970)

Visual FoxPro 9.0
Cannot reopen project file "name" (Error 1970)

Visual FoxPro attempted to open the project you left open in the previous session.

  • The project no longer exists. If the project exists but cannot be opened, it might be corrupted.

    Locate a valid project, or ignore the message.


No result set has been returned by the server (Error 1463)

Visual FoxPro 9.0
No result set has been returned by the server (Error 1463)

The remote query did not generate a result set.

Check your query and its parameters to make sure you are producing a result set on the server.


Cannot redefine "name" (Error 1930)

Visual FoxPro 9.0
Cannot redefine "name" (Error 1930)

You have tried to assign a value to THIS, THISFORM, THISFORMSET, or a reserved system variable. For more information, see Reserved Words.


Invalid update column name "name" (Error 1479)

Visual FoxPro 9.0
Invalid update column name "name" (Error 1479)

The column name is not found in the column list of the view.

Correct the column name.


"name" internal consistency error (Error 1462)

Visual FoxPro 9.0
"name" internal consistency error (Error 1462)

Internal product error. Visual FoxPro closes all open files and exits.

  • Visual FoxPro cannot reconcile two opposing internal states in the product.

    Record your recent actions while using Visual FoxPro and then call Microsoft Support.


Lotus 1-2-3 version 3.0 file format is invalid (Error 1678)

Visual FoxPro 9.0
Lotus 1-2-3 version 3.0 file format is invalid (Error 1678)

The Lotus 1-2-3 file you have attempted to import is either not version 3.0 or has been corrupted.


"name" is not an array (Error 232)

Visual FoxPro 9.0
"name" is not an array (Error 232)

A variable or file variable (table field) was used where an array is required. For more information, see Variables, Fields, or Working with Fields and Records..


Command cannot be issued within a transaction (Error 1593)

Visual FoxPro 9.0
Command cannot be issued within a transaction (Error 1593)

You must end all open transactions with END TRANSACTION or ROLLBACK before issuing this command. Visual FoxPro won't allow anything that modifies a database (.dbc) to be part of a transaction. The following commands are illegal within a transaction:

  • CLEAR ALL

  • CLOSE ALL

  • CLOSE DATABASE

  • CLOSE TABLES

  • COPY INDEXES

  • CREATE / DELETE / MODIFY DATABASE

  • CREATE / DELETE / MODIFY VIEW

  • CREATE / DELETE TRIGGER

  • CREATE / DELETE / MODIFY CONNECTION

  • APPEND / MODIFY / COPY PROCEDURES

The following commands are not legal for transaction-participating tables:

  • ALTER TABLE

  • CREATE TABLE (of a table in a database container)

  • DELETE TAG

  • INDEX ON

  • INSERT (non-SQL)

  • MODIFY STRUCTURE

  • PACK

  • TABLEREVERT( )

  • Turning off table buffering (by changing the Buffering property from 3 or 5 to 1, 2, or 4 with the CURSORETPROP( ) function).

  • Closing a table (by issuing the USE command in the work area of a transaction-participating table)

  • ZAP


Must be a file variable (Error 1226)

Visual FoxPro 9.0
Must be a file variable (Error 1226)

A variable or an array was used where a file variable (field) is required.


Invalid compact EXE file. Rebuild EXE.

Visual FoxPro 9.0
Invalid compact EXE file. Rebuild EXE.

Your compact executable (.EXE) file has become corrupt.

Rebuild the file.


XML document is not loaded. (Error 2096)

Visual FoxPro 9.0
XML document is not loaded. (Error 2096)

The ApplyDiffGram method, ChangesToCursor method, and ToCursor method and the associated XMLAdapter object must have an XML document loaded.

  • Check the XMLAdapter objects IsLoaded property to see if an XML document has been loaded.


SQL: SELECT contains invalid * (Error 1820)

Visual FoxPro 9.0
SQL: SELECT contains invalid * (Error 1820)

You have attempted to use * in one of the aggregate functions of MAX( ), MIN( ), AVG( ), or SUM( ).

For more information, see SELECT - SQL and the CALCULATE command.


XMLTable object with XMLName "name" does not have associated fields. (Error 2130)

Visual FoxPro 9.0
XMLTable object with XMLName "name" does not have associated fields. (Error 2130)

Visual FoxPro requires that the XMLTable object must contain an associated XMLField object or objects, before the XMLAdapter objects, ToXML method can be called.

  • Execute the XMLAdapter objects, AddTableSchema method, to create the XMLTable and XMLField collections, or otherwise create these items.


Warning: No information is available to check remote update conflicts (Error 1496)

Visual FoxPro 9.0
Warning: No information is available to check remote update conflicts (Error 1496)

The ODBC driver does not report the number of records affected by an UPDATE, DELETE, or INSERT statement. Optimistic locking conflicts on remote views using this connection will not be reported.

Be sure your update code handles this limitation.


Index tag is not found for Cursor object "cursor name" (Error 2198)

Visual FoxPro 9.0
Index tag is not found for Cursor object "cursor name" (Error 2198)

This error is generated when the order specified for a Cursor Object in a DataEnvironment Object cannot be found (an index tag is not available for the cursor).


Procedure file "name" is not found (Error 1937)

Visual FoxPro 9.0
Procedure file "name" is not found (Error 1937)

You have specified a name in a RELEASE PROCEDURE name command that is not in the SET PROCEDURE list.


Not enough memory for buffer (Error 1149)

Visual FoxPro 9.0
Not enough memory for buffer (Error 1149)

There is not enough memory for Visual FoxPro to allocate memory for a buffer.

  • Available memory is extremely limited.

    Add memory or remove memory-resident programs to give Visual FoxPro more working memory.


XMLAdapter: fractionDigits must not be greater than or equal to maxLength. (Error 2118)

Visual FoxPro 9.0
XMLAdapter: fractionDigits must not be greater than or equal to maxLength. (Error 2118)

The value of the FractionDigits property cannot be greater than the value of the MaxLength property.


Picture too big, corrupt, or in wrong format (Error 1108)

Visual FoxPro 9.0
Picture too big, corrupt, or in wrong format (Error 1108)

You attempted to use an invalid picture file.


Table operation is invalid during indexing (Error 1690)

Visual FoxPro 9.0
Table operation is invalid during indexing (Error 1690)

You have attempted to perform a table operation in a user-defined function referenced with an index expression.


SQL: Use of UNION in subquery is invalid (Error 1813)

Visual FoxPro 9.0
SQL: Use of UNION in subquery is invalid (Error 1813)

UNION is not supported in subqueries in Visual FoxPro. For more information, see SELECT - SQL Command.


Printer driver is not found (Error 1644)

Visual FoxPro 9.0
Printer driver is not found (Error 1644)

The specified printer driver could not be located.


Invalid Update refresh column name "column name" (Error 2163)

Visual FoxPro 9.0
Invalid Update refresh column name "column name" (Error 2163)

The Update refresh column name is invalid or cannot be found in the cursor.


Base table fields have been changed and no longer match view fields. View field properties cannot be set (Error 1542)

Visual FoxPro 9.0
Base table fields have been changed and no longer match view fields. View field properties cannot be set (Error 1542)

The name or number of columns in the base table or base view of a view definition have been changed and no longer match the view definition.

  • View properties cannot be loaded into the view cursor.

    Recreate or modify the view to reflect the structure changes in any base tables/views.

  • The lUseCursorSchema parameter for CursorFill method is True (.T.), and the number of fields defined in the CursorSchema property is fewer or greater than the number of fields in the base table.


The TO clause can only be used with modal Forms and FormSets (Error 1982)

Visual FoxPro 9.0
The TO clause can only be used with modal Forms and FormSets (Error 1982)

You have attempted to use the DO FORM command with the TO clause:

Copy Code
DO FORM x TO variable.

This operation is illegal on modeless forms and form sets.


You must use a logical expression with a FOR or WHILE clause (Error 1127)

Visual FoxPro 9.0
You must use a logical expression with a FOR or WHILE clause (Error 1127)

A FOR or WHILE clause within a command does not contain a logical expression. For more information, see Creating Logical Expressions.


Collating sequence "name" is not found (Error 1915)

Visual FoxPro 9.0
Collating sequence "name" is not found (Error 1915)

This error occurs when attempting to use a collating sequence that is not supported by the current code page. The collating sequence assigned with SET COLLATE command or the COLLATE clause in the CREATE TABLE - SQL, ALTER TABLE - SQL, or INDEX commands must be a valid Visual FoxPro collating sequence.

You must specify a compatible code page in your Visual FoxPro configuration file. For example, you might see the error, "Collating sequence "CZECH" is not found" when you issue the command:

Copy Code
SET COLLATE TO "CZECH"

To enable support for the CZECH collating sequence, add the following line of code to your Config.fpw file and restart Visual FoxPro:

Copy Code
CODEPAGE = 1250

For more information about collating sequences, see the SET COLLATE Command for valid collating sequences and Optimizing International Applications.


Cannot find spell check program.

Visual FoxPro 9.0
Cannot find spell check program.

The spelling check program cannot be found.

  • The _SPELLCHK system variable does not contain a valid file name.

    Verify the value of _SPELLCHK.


This OLE property cannot be an expression (Error 1782)

Visual FoxPro 9.0
This OLE property cannot be an expression (Error 1782)

You have attempted to set some of the OLE properties to be an expression in the property sheet. This is not a valid operation.


Unable to generate a printer driver (Error 1717)

Visual FoxPro 9.0
Unable to generate a printer driver (Error 1717)

The printer driver associated with the report or label you have chosen cannot be generated or loaded.


Screen code is too large for available memory (Error 1507)

Visual FoxPro 9.0
Screen code is too large for available memory (Error 1507)

The screen object you are trying to copy has code larger than 64 KB.


Key label "label" is invalid (Error 1255)

Visual FoxPro 9.0
Key label "label" is invalid (Error 1255)

The key label you have used is not supported. See ON KEY LABEL for a list of supported key labels.


XML document is not a DiffGram. (Error 2126)

Visual FoxPro 9.0
XML document is not a DiffGram. (Error 2126)

Visual FoxPro does not allow the ApplyDiffGram method and the ChangesToCursor method to be called when the IsDiffgram property of the XMLTable object is set to False (.F.).


Invalid COMATTRIB value for "name" (Error 2048)

Visual FoxPro 9.0
Invalid COMATTRIB value for "name" (Error 2048)

An incorrect value is specified for this property in the class definition.


Source code not found.

Visual FoxPro 9.0
Source code not found.

The file you specified cannot be located in the specified directory.


Column number must be between 0 and the right margin (Error 1657)

Visual FoxPro 9.0
Column number must be between 0 and the right margin (Error 1657)

There was an attempt to set the _PCOLNO system variable to an invalid number. This system variable is included for backward compatibility. For better results in the current version, use the Report Designer.


The ChildOrder property of a relation object in the data environment is no longer valid. The relation is being removed (Error 1478)

Visual FoxPro 9.0
The ChildOrder property of a relation object in the data environment is no longer valid. The relation is being removed (Error 1478)

Due to data environment changes, the relation of a ChildOrder property has been removed.


Connectivity error: "name" (Error 1526)

Visual FoxPro 9.0
Connectivity error: "name" (Error 1526)

An ODBC error has occurred. Visual FoxPro provides this message as a wrapper for the actual ODBC error. The ODBC error can be generated by the ODBC driver manager, by the ODBC driver, or by the back-end data server. AERROR( ) returns the ODBC errors. The format of an ODBC error 1526, as returned by AERROR( ), is as shown in the following table.

Element number | Description
1 | Numeric. Contains 1526.
2 | Character. The text of the error message.
3 | Character. The text of the ODBC error message.
4 | Character. The current ODBC SQL state.
5 | Numeric. The error number from the ODBC data source.
6 | Numeric. The ODBC connection handle.
7 | The null value.

The ODBC error message (element number 3) contains the source of the error as the last name in the list preceding the actual error text.

Use the ODBC state code (element number 4) to look up the error in the ODBC book (Programmer's Reference).

For a server error, the data source error is set (element number 5). Use it to look up the error in the server documentation.


Table cannot be browsed because cursor object is no longer valid. (Error 1556)

Visual FoxPro 9.0
Table cannot be browsed because cursor object is no longer valid. (Error 1556)

Close and reopen the Form Designer to resynchronize the table and the cursor.


XMLAdapter.ToXML cannot be called while there is a loaded XML document. (Error 2107)

Visual FoxPro 9.0
XMLAdapter.ToXML cannot be called while there is a loaded XML document. (Error 2107)

Visual FoxPro does not allow the ToXML method to execute when an XML document is already loaded.

  • Check the IsLoaded property to make sure that a XML document is not already loaded.

  • Use the ReleaseXML method to release the currently loaded XML document.


Variable "variable" is not found (Error 12)

Visual FoxPro 9.0
Variable "variable" is not found (Error 12)

The specified variable or field name could not be found.


.DBC internal consistency error (Error 1550)

Visual FoxPro 9.0
.DBC internal consistency error (Error 1550)

An internal database error has occurred.

  • The database is corrupt.

    Try VALIDATE DATABASE to diagnose or repair the problem.

  • The database container index (.dcx) is corrupt or not synchronized with the database container file (.dbc), usually as a result of an abnormal system shut-down.

    Rebuild the index by closing the database, deleting the index file dbc_name.DCX, and reopening the database.

    If the problem is not corrected, record your recent actions while using Visual FoxPro and then call Microsoft Support.


Member "name" is a class member (Error 1760)

Visual FoxPro 9.0
Member "name" is a class member (Error 1760)

You have attempted to remove a member from an object. The member cannot be removed because it is a member of the class the object is based on.

To remove the member, modify the class.


Cannot release object (Error 2054)

Visual FoxPro 9.0
Cannot release object (Error 2054)

The object could not be released. This error is usually caused by the object having an outstanding reference by another object.


Database "alias" is not open (Error 1534)

Visual FoxPro 9.0
Database "alias" is not open (Error 1534)

You have attempted to SET DATABASE TO a database that is not yet open.

Try OPEN DATABASE first.


Invalid operation for offline view while offline (Error 2007)

Visual FoxPro 9.0
Invalid operation for offline view while offline (Error 2007)

Some operations are not valid when an offline view is being used offline.

  • You tried to create an offline view from a view that is already offline.

    Use the original view directly, or use a different view as the basis for your new offline view.

For more information, see CREATEOFFLINE( ).


DEClass cannot be loaded. (Error 2086)

Visual FoxPro 9.0
DEClass cannot be loaded. (Error 2086)

An attempt was made to load the DEClass in a form or report unsuccessfully. As a result, the DEClass and DEClasslibrary properties were cleared. Make sure that the specified DEClass is a valid class and contained data sources are all valid.


Structure nesting is too deep (Error 1212)

Visual FoxPro 9.0
Structure nesting is too deep (Error 1212)

The maximum structured programming command nesting of 64 levels has been exceeded.


Error instantiating cursor. Table "alias" cannot be opened. Object will be ignored (Error 1554)

Visual FoxPro 9.0
Error instantiating cursor. Table "alias" cannot be opened. Object will be ignored (Error 1554)

An error occurred in design mode while attempting to load the data environment. The cursor was not created. If you save the form, the object will be lost.


Function is not supported on native tables (Error 1536)

Visual FoxPro 9.0
Function is not supported on native tables (Error 1536)

The command or function you are using — for instance, REQUERY( ) — is not applicable to native Visual FoxPro tables.


Table "name" has become corrupted. The table will need to be repaired before using again. (Error 2091)

Visual FoxPro 9.0
Table "name" has become corrupted. The table will need to be repaired before using again. (Error 2091)

Either the table record count does not match the actual records in the table, or the file size on the disk does not match the expected file size from the table header. Repair the table using an appropriate third-party repair utility for Visual FoxPro tables before opening the table again.


Update conflict (Error 1585)

Visual FoxPro 9.0
Update conflict (Error 1585)

An optimistic locking conflict has been detected while trying to update a view.

Make sure your update key is valid.

If you want to commit your changes to the base table(s), call TABLEUPDATE( ) with lForce. This will overwrite the changes made to the base table since the view was last fetched.

To discard the local changes made to the view, call TABLEREVERT( ).


Fetching canceled; remote table is closed (Error 1530)

Visual FoxPro 9.0
Fetching canceled; remote table is closed (Error 1530)

You interactively canceled a local function execution as part of remote data fetch by pressing the ESC key.